EquilibriumGate

Modern structural engineering relies heavily on complex Computer-Aided Engineering (CAE) systems to verify safety. However, a significant gap exists between continuous physical space (the actual structural assembly) and discrete computational space (the data schemas stored in CAD and PLM databases). This gap introduces micro-rounding discrepancies, topology anomalies, and untraceable aliasing bugs that compromise physical safety audits.

This paper documents the design and implementation of EquilibriumGate, a zero-dependency, deterministic physical engine and interactive web-based workbench designed to bridge this divide. Built from first principles, EquilibriumGate acts as an absolute mechanical auditor. It parses 2D planar structural inputs, enforces strict spatial and physical boundaries, evaluates topological validity using graph theory, and computes global static equilibrium convergence using a highly reproducible, deterministic mathematical kernel. We detail the mechanics of the Python calculation engine and the architecture of the real-time React interactive presentation layer, showing how continuous human gestures are normalized into verifiable physical data.

GitHub Repository: github.com/algorithmicalabs/equilibriumgate-core

1. Introduction: The Cognitive Overhead of Physical Verification

In structural design, verifying static equilibrium is the ultimate gatekeeper of safety. In classical planar mechanics, a system is in static equilibrium if and only if the vector sum of all external forces and moments acting upon it equals zero:

$$\sum F_x = 0, \quad \sum F_y = 0, \quad \sum M_z = 0$$

Despite the simplicity of these governing equations, modern engineering pipelines suffer from considerable administrative and cognitive overhead when translating physical designs into verified schemas. CAD coordinates exported from layout software often contain floating-point noise; structural joints are modeled with minute offsets that escape human review but break standard structural solvers; and kinematic stability is often evaluated only after expensive finite-element simulations are run.

The engineering goal of EquilibriumGate is to resolve these issues at the absolute perimeter of execution. By building a strict, fail-fast, deterministic boundary guard, we prevent corrupt, unfeasible, or kinematically unstable structural drawings from ever entering downstream calculation pipelines.

To achieve this, the system is split into two tightly coupled layers:

• The Deterministic Physical Kernel (Python): A pure, dependency-free mathematical engine that acts as the absolute mechanical auditor.
• The Cognitive Bridge (React/SVG): An interactive visual interface that maps continuous human click-and-drag inputs into snapped, clean, discrete physical data packets.

2. Core Architectural Ideals

To ensure high-integrity computational execution, the EquilibriumGate physical kernel is governed by three architectural pillars:

2.1 Absolute Determinism

Stochastic solvers, random pivot selections, or environment-dependent floating-point optimizations are strictly forbidden. Given an identical structural graph and external load configuration, the system's pivot selection, structural analysis, and residual convergence must be 100% reproducible across any machine, operating system, or execution environment.

2.2 Strict Immutable Domain State

To eliminate pointer-aliasing, side-effect mutations, and downstream state corruption, all domain entities are modeled as frozen objects. Once a joint location or force vector is validated and constructed, its internal state cannot be modified. Structural updates are handled via explicit, pure state-transition operations that return new instances of the structural domain.

2.3 Fail-Fast Boundary Guarding

Mathematical sanity checks are executed at the absolute perimeter of the execution loop. The engine draws an unyielding line between topological validity (physical sanity, geometric uniqueness, kinematic stability) and equilibrium compliance (numerical summation of forces and moments). If a structure is topologically corrupt (e.g., has overlapping joints, floating nodes, or insufficient supports), calculations are halted immediately, raising highly specific, typed exceptions before the solver is ever invoked.

3. The Pure Domain Schema (schemas.py)

The engine enforces a type-safe representation of physical components through frozen, immutable data structures. These entities are directly mapped to native JSON structures for end-to-end integration.

3.1 Boundary Constraints

Planar structural boundary conditions are governed by three explicit, physical states:

• Constraint.PINNED: Re-constrains translation in both planar directions. It supplies two independent, unknown external reaction forces: $$R_x, \quad R_y$$
• Constraint.ROLLER: Re-constrains translation normal to the support plane. In our planar coordinate system, rollers are assumed to act vertically, supplying one independent, unknown external reaction force: $$R_y$$
• Constraint.FREE: Provides no translational constraints to the joint. It supplies zero external reaction forces.

3.2 Domain Entities

Using these constraints, the structural geometry is assembled from three foundational entities:

• Node: Represents a discrete physical joint in 2D Cartesian space: $$\text{Node} = \{ \text{node\_id} \in \text{String}, \, x \in \mathbb{R}, \, y \in \mathbb{R}, \, c \in \text{Constraint} \}$$
• Member: Represents an axial structural element connecting two discrete joints, establishing the physical load-bearing topology: $$\text{Member} = \{ \text{member\_id} \in \text{String}, \, \text{node\_start} \in \text{Node.node\_id}, \, \text{node\_end} \in \text{Node.node\_id} \}$$
• Force: Represents a vector of point-load force acting directly at a designated joint. This represents both external loads applied by the environment and reaction forces supplied by boundary supports: $$\text{Force} = \{ \text{node\_id} \in \text{Node.node\_id}, \, F_x \in \mathbb{R}, \, F_y \in \mathbb{R} \}$$

4. Coordinate Geometry Primitives (geometry.py)

All physical computations operate in a continuous 2D Cartesian coordinate system using Base SI units: Meters ($m$) for length, Newtons ($N$) for force, and Newton-meters ($N \cdot m$) for moment.

4.1 Euclidean Spans

The physical distance $d$ between any two joints, $N_1 = (x_1, y_1)$ and $N_2 = (x_2, y_2)$, is computed using the standard Euclidean metric:

$$d(N_1, N_2) = \sqrt{(x_2 - x_1)^2 + (y_2 - y_1)^2}$$

4.2 Decoupled Tolerance Framework

A primary failure mode of structural engines is computational precision conflicts. Rounding errors inherent to floating-point arithmetic can cause coordinate matching to fail or prevent perfect static equilibrium calculations from registering. To solve this, EquilibriumGate strictly decouples spatial evaluations from physical balance calculations using two distinct epsilons:

• Spatial Epsilon ($\epsilon_{\text{spatial}} = 10^{-4} \text{ m}$): The minimum physical distance separating two discrete joints. If the computed Euclidean distance $d(N_1, N_2) < \epsilon_{\text{spatial}}$, the joints are classified as co-located. This protects the engine from duplicating nodes due to rounding errors introduced during CAD dxf/dwg exports.
• Physics Epsilon ($\epsilon_{\text{physics}} = 10^{-3} \text{ N or N}\cdot\text{m}$): The threshold used to verify static convergence. Because floating-point operations accumulate small rounding errors, a physical sum will rarely equal exactly 0.00000000. Static equilibrium is declared verified if the absolute value of the horizontal, vertical, and rotational residuals falls below this threshold.

4.3 Planar Position and Cross-Product Moment Formulation

To calculate moments, the engine determines the position vector $\vec{r}$ pointing from a designated moment pivot joint $P = (x_p, y_p)$ to the target joint where the force vector is applied, $F_{\text{node}} = (x_f, y_f)$:

$$\vec{r} = \begin{bmatrix} r_x \\ r_y \end{bmatrix} = \begin{bmatrix} x_f - x_p \\ y_f - y_p \end{bmatrix}$$

The moment $M_z$ generated by a planar force vector $\vec{F} = [F_x, F_y]^T$ acting at a distance $\vec{r}$ from a rotation center is computed using the scalar component of the 3D cross-product $\vec{r} \times \vec{F}$ perpendicular to the $xy$-plane:

$$M_z = r_x F_y - r_y F_x$$

The engine strictly enforces the standard counter-clockwise positive (CCW+) mechanics sign convention:

• A positive result ($M_z > 0$) indicates a counter-clockwise rotational tendency.
• A negative result ($M_z < 0$) indicates a clockwise rotational tendency.

5. Pre-Flight Boundary Guarding (preflight.py)

Before allowing input data to reach the mathematical solvers, the engine runs three independent topological checks to ensure physical and structural sanity.

5.1 Coordinate Uniqueness Check

To ensure coordinate drawing integrity, the engine runs an optimized $O(n^2)$ triangular loop to evaluate node spacing. For every unique node pair $(N_i, N_j)$ where $i < j$, the engine asserts:

$$d(N_i, N_j) \ge \epsilon_{\text{spatial}}$$

If any node pair is closer than $\epsilon_{\text{spatial}}$, execution is halted immediately and a DuplicateNodeError is raised.

5.2 Structural Graph Integrity

To prevent mathematical "floating nodes" or isolated elements from corrupting the stiffness and equilibrium calculations, the structural assembly is modeled as an undirected graph $G = (V, E)$, where $V$ is the set of Nodes and $E$ is the set of Members:

• Orphan Checking: For every member $M \in E$, the engine verifies that its defined endpoints node_start and node_end exist inside the defined node set $V$. Any missing reference triggers an OrphanedNodeError.
• Connectivity Checking: The engine computes the degree of every node $\text{deg}(N)$, representing the number of physical members connected to that joint. It enforces that every node must be structurally unified with at least one member: $$\forall N \in V, \quad \text{deg}(N) \ge 1$$ Any isolated node with $\text{deg}(N) = 0$ is flagged, raising an IsolatedNodeError.

5.3 Kinematic Stability Audit

To prevent the assembly from acting as a mechanical mechanism (unconstrained rigid-body motion), the structure must possess sufficient external boundary reactions. The engine computes the sum of translational constraints, $R$:

$$R = \sum_{N \in V} \text{constraint\_value}(N.c)$$

Where the physical resistance degrees-of-freedom are defined as:

$$\text{constraint\_value}(c) = \begin{cases} 2 & \text{if } c = \text{Constraint.PINNED} \\ 1 & \text{if } c = \text{Constraint.ROLLER} \\ 0 & \text{if } c = \text{Constraint.FREE} \end{cases}$$

The engine audits this sum against the fundamental degrees of freedom in planar space (translation in $x$, translation in $y$, and rotation in $z$):

$$R \ge 3$$

If $R < 3$, the system is kinematically unstable, and execution is halted by raising a KinematicInstabilityError.

6. The Static Equilibrium Solver (equilibrium.py)

If all pre-flight guards pass, the validated coordinate state is handed over to the equilibrium solver. This module is responsible for choosing a pivot, accumulating horizontal and vertical force vectors, and evaluating rotational moments.

6.1 Alpha-Priority Pivot Selection

Static equilibrium is physically independent of the chosen pivot point. However, to execute numerical calculations, the machine requires a concrete coordinate anchor $P = (x_p, y_p)$ to calculate position vectors. To ensure 100% predictable, test-reproducible runs across platforms, the engine selects the global pivot point using a deterministic search hierarchy:

1. Filter the node set down to only support joints: $$S = \{ N \in V \mid N.c \in \{\text{PINNED}, \text{ROLLER}\} \}$$
2. Sort the set $S$ alphabetically by its `node_id`.
3. Search the sorted list $S$ for the first joint where $N.c = \text{Constraint.PINNED}$. If found, return this node as the global calculation pivot.
4. If no PINNED joint exists in the assembly (for example, a simple beam resting on two rollers), return the first node in the sorted support array, $S[0]$.

6.2 Global Force and Moment Summation

The engine treats all elements inside the input force list uniformly as force vectors acting on coordinate nodes, regardless of whether they are external active loads or computed support reaction values.

It accumulates the horizontal and vertical vectors independently:

$$R_x = \sum_{F \in \text{Forces}} F.F_x, \quad R_y = \sum_{F \in \text{Forces}} F.F_y$$

The solver then loops through the forces list, fetches the physical coordinates of each target node, calculates the corresponding lever arm vector relative to the selected pivot $P$, and accumulates the global moments:

$$M_z = \sum_{F \in \text{Forces}} (r_x F.F_y - r_y F.F_x)$$

6.3 Convergence Evaluation (The Equilibrium Gate)

The structural assembly is declared safe and verified in static equilibrium if and only if all three residuals converge within our tight physical epsilon boundaries:

$$\text{is\_equilibrium} = \left( |R_x| < \epsilon_{\text{physics}} \right) \land \left( |R_y| < \epsilon_{\text{physics}} \right) \land \left( |M_z| < \epsilon_{\text{physics}} \right)$$

7. The Cognitive Bridge: Designing the Interactive Frontend

The primary design challenge of the EquilibriumGate interactive frontend is to map continuous, physical mouse and touch gestures on a digital screen into discrete, normalized data payloads that can be audited by our backend solver.

7.1 Coordinate Mapping (Pixels to Meters)

Let $P_{\text{canvas}} = (u, v)$ represent the raw pixel coordinate inside the SVG DOM viewport, and $W_{\text{real}} = (x, y)$ represent the real-world physical coordinate in meters. The coordinate mapping is governed by a global zoom/scaling factor $s_{\text{scale}}$ (expressed in pixels/meter) and canvas offset translations $(O_u, O_v)$:

$$x = \frac{u - O_u}{s_{\text{scale}}}, \quad y = -\frac{v - O_v}{s_{\text{scale}}}$$

Note: The negative sign in the $y$-translation is required to flip the screen coordinate axis (where the origin is top-left and $v$ increases downward) to a standard Cartesian coordinate system (where $y$ increases upward).

7.2 Snap-to-Grid Formulation

To enforce clean spatial entry and bypass micro-rounding noise at the browser level, the mapped coordinates $(x, y)$ are locked into a grid interval spacing $\Delta_{\text{grid}} = 0.25 \text{ m}$ before updating local state:

$$x_{\text{snapped}} = \text{round}\left( \frac{x}{\Delta_{\text{grid}}} \right) \times \Delta_{\text{grid}}$$ $$y_{\text{snapped}} = \text{round}\left( \frac{y}{\Delta_{\text{grid}}} \right) \times \Delta_{\text{grid}}$$

By executing this calculation on every mouse-move event before state updates, we guarantee that the backend never receives floating-point coordinate chaos, while preserving the user's ability to construct precise, standard trusses.

7.3 Real-Time Vector Interaction Models

• Node Instantiation: A single click on an empty grid coordinate adds a new, unconstrained node to local state: $$\text{Node} = \{ \text{node\_id}: \text{UUID}, \, x: x_{\text{snapped}}, \, y: y_{\text{snapped}}, \, \text{constraint}: \text{Constraint.FREE} \}$$
• Support Configuration: Left-clicking an existing node highlights it and opens a minimalist toolbar to toggle the constraint property.
  Constraint.PINNED renders a sharp, solid equilateral triangle pointing upward, anchored to the node coordinate: $$\text{Triangle Vertices} = \left\{ (x, y), \, (x - \delta_w, y - \delta_h), \, (x + \delta_w, y - \delta_h) \right\}$$ Constraint.ROLLER renders a clean circle with underlying horizontal sliding lines, indicating a vertical-only constraint restriction: $$\text{Circle Center} = (x, y - R)$$
• Dynamic Force Vector Dragging: To apply loads, the user clicks an active node and drags outward. The displacement vector $\vec{D} = [D_u, D_v]^T$ in screen pixels is translated into physical force components $(F_x, F_y)$ in Newtons via a calibration factor $k_{\text{force}}$ (expressed in Newtons/pixel): $$F_x = D_u \times k_{\text{force}}, \quad F_y = -D_v \times k_{\text{force}}$$ The frontend renders a bold vector arrow pointing in the direction of the drag, accompanied by a real-time monospaced inline text tag displaying the exact components: $$\vec{F} = \begin{bmatrix} F_x \\ F_y \end{bmatrix} \text{ N}$$

8. The Event Loop: Asynchronous Debounced Auditing

To maintain a highly fluid, 60fps rendering experience in the browser while protecting server resources from API floods, the synchronization between the React canvas and the Python solver is managed via a non-blocking debounced communication pipeline.

When a user drags a node or stretches a force arrow, the frontend updates the local React state and redraws the local SVG vectors immediately, ensuring lag-free visual feedback. Simultaneously, the application resets a global timer. When the timer successfully reaches $250\text{ ms}$ of continuous user inactivity, the app compiles the entire structure into a unified JSON payload and dispatches an asynchronous HTTP POST request to /api/audit.

This architecture isolates computational network latency from the user interface. The user experiences buttery-smooth drawing physics, while the validation engine is spared from auditing incomplete intermediate states.

9. Status-Driven Color Tokens & UI State Mapping

The workspace is designed on the minimalist, raw data ethos of Algorithmica Labs. The interface uses status-driven color tokens to represent physical state changes in real time, shifting the frame border based on the API response:

9.1 The Green State: Static Convergence (HTTP 200)

• Condition: Backend reports is_equilibrium: true.
• UI Mutation: The workbench frame border transitions to an emerald-green accent.
• Render elements: A success block reads: [AUDIT SUCCESS] Global Static Equilibrium Verified.
• Engineering Values: Monospaced panels display the absolute residuals converging to zero: $$|R_x| < \epsilon_{\text{physics}}, \quad |R_y| < \epsilon_{\text{physics}}, \quad |M_z| < \epsilon_{\text{physics}}$$

9.2 The Red State: Static Imbalance (HTTP 200)

• Condition: Backend reports is_equilibrium: false.
• UI Mutation: The workbench frame border transitions to a warning-red accent.
• Render elements: A warning block reads: [AUDIT FAILURE] Collapse Risk: System is not in static equilibrium.
• Engineering Values: Live tickers display the active unbalanced residuals ($R_x, R_y, M_z$). If $M_z \neq 0$, a curved rotational moment arrow is rendered around the selected calculation pivot, visually representing whether the assembly is twisting clockwise or counter-clockwise.

10. End-to-End API Integration Contract

The interface contract strictly enforces aligned structural schemas. The JSON payloads directly serialize the immutable Python dataclasses.

10.1 Unified JSON Payload Structure (POST /api/audit)

{
  "nodes": [
    { "node_id": "Node_A", "x": 0.0, "y": 0.0, "constraint": "PINNED" },
    { "node_id": "Node_B", "x": 4.0, "y": 0.0, "constraint": "ROLLER" },
    { "node_id": "Node_C", "x": 2.0, "y": 0.0, "constraint": "FREE" }
  ],
  "members": [
    { "member_id": "Mem_AC", "node_start": "Node_A", "node_end": "Node_C" },
    { "member_id": "Mem_CB", "node_start": "Node_C", "node_end": "Node_B" }
  ],
  "forces": [
    { "node_id": "Node_C", "fx": 0.0, "fy": -1000.0 },
    { "node_id": "Node_A", "fx": 0.0, "fy": 500.0 },
    { "node_id": "Node_B", "fx": 0.0, "fy": 500.0 }
  ]
}

10.2 Successful Audit Response JSON (HTTP 200)

{
  "is_equilibrium": true,
  "rx_residual": 0.0,
  "ry_residual": 0.0,
  "moment_residual": 0.0,
  "pivot_node_id": "Node_A",
  "tolerance_used": 0.001
}

10.3 Topological Validation Failure JSON (HTTP 400)

{
  "error_type": "KinematicInstabilityError",
  "message": "Kinematically unstable assembly: total support reaction restriction (R=2) is less than planar degrees of freedom (3)."
}

11. Retrospective & Epistemological Grounding

Building EquilibriumGate is a critical milestone in Phase I of the Algorithmica Labs roadmap. As an exercise in structural auditing, it unifies academic mechanical engineering fundamentals with rigorous software architecture.

Throughout the development of this engine, a core insight emerged: computational safety audits of physical systems are only as reliable as the boundary conditions at the perimeter of the software. By enforcing strict immutability, decoupling coordinate matching from physical evaluations, and executing fail-fast pre-flight validations, we eliminate the primary pathways for silent data corruption.

Furthermore, this project demonstrates how we can systematically reduce administrative cognitive overhead in structural engineering workflows. By providing a real-time, status-driven, debounced interactive loop, we bridge the gap between human physical intuition and structured machine intelligence. The engineer can instantly feel the rotational twist of a structural imbalance or see the topological error of a misplaced joint, while the software preserves absolute, mathematical authority.

This core methodology—translating continuous physical properties into deterministic, structured schemas and verifying them through unyielding mathematical gates—serves as the foundational substrate for all future industrial document intelligence and manufacturing workflow tools built at Algorithmica Labs.