Assemble2D

https://github.com/tab58/assemble2d
Admin
Assemble2D is a 2D geometric constraint solver that uses energy-based optimization to satisfy...
Tokens:11,250
Snippets:70
Trust Score:7.6
License:MIT
Update:5 months ago
Show doc for...
Tokens:
Raw
### Solve Coincident Points with ConstraintSystem (Example)

Source: https://context7.com/tab58/assemble2d/llms.txt

A practical example of using CoincidentConstraint within a ConstraintSystem. After solving, it verifies that the two points have converged to the same location within a small tolerance.

```typescript
import { ConstraintSystem } from './src/solver/assembly';
import { SolverPoint } from './src/solver/entities';
import { CoincidentConstraint } from './src/solver/constraints/coincident';

const p0 = new SolverPoint(0, 0);
const p1 = new SolverPoint(10, 10);

const system = new ConstraintSystem();
system.addConstraint(new CoincidentConstraint(p0, p1));

await system.solve();
// p0 and p1 now share the same location
console.log(Math.abs(p0.x - p1.x) < 1e-6); // true
console.log(Math.abs(p0.y - p1.y) < 1e-6); // true
```

--------------------------------

### Horizontal and Vertical Line Energy Functions

Source: https://context7.com/tab58/assemble2d/llms.txt

Forces line endpoints to share the same y-coordinate (horizontal) or x-coordinate (vertical). Examples show satisfied and unsatisfied cases.

```typescript
import { horizontalLineEnergyFunc } from './src/solver/constraints/energy/horizontalLine';
import { verticalLineEnergyFunc }   from './src/solver/constraints/energy/verticalLine';

// Horizontal: (0,0)→(5,0) — y0 == y1, satisfied
console.log(horizontalLineEnergyFunc(0, 0, 5, 0)); // 0
// Not satisfied: (0,0)→(5,3)
console.log(horizontalLineEnergyFunc(0, 0, 5, 3)); // 9  ((0-3)²)

// Vertical: (2,0)→(2,5) — x0 == x1, satisfied
console.log(verticalLineEnergyFunc(2, 0, 2, 5)); // 0
// Not satisfied: (1,0)→(2,5)
console.log(verticalLineEnergyFunc(1, 0, 2, 5)); // 1
```

--------------------------------

### Create and Configure SolverCircle

Source: https://context7.com/tab58/assemble2d/llms.txt

Demonstrates initializing a SolverCircle with center coordinates and a radius. The center point and radius are individually indexed for constraint system use.

```typescript
import { SolverCircle } from './src/solver/entities';

const circle = new SolverCircle();
circle.setCenterX(5);
circle.setCenterY(5);
circle.setRadius(3);

console.log(circle.centerX, circle.centerY); // 5, 5
console.log(circle.radius);                  // 3
console.log(circle.radiusIndex);             // UUID for radius parameter
```

--------------------------------

### Building a Constrained Triangle with ConstraintSystem

Source: https://context7.com/tab58/assemble2d/llms.txt

Shows how to create a ConstraintSystem and add CoincidentConstraint objects to define relationships between solver entities like lines. The system is then solved asynchronously. Ensure all necessary constraint classes are imported.

```typescript
import { ConstraintSystem } from './src/solver/assembly';
import { SolverPoint, SolverLine, SolverCircle } from './src/solver/entities';
import { CoincidentConstraint } from './src/solver/constraints/coincident';
// (Import other constraint classes as needed — see energy/ directory for all types)

// Build a constrained triangle: three lines sharing endpoints
const l1 = new SolverLine();
const l2 = new SolverLine();
const l3 = new SolverLine();

// Set initial approximate positions
l1.setP0x(0);  l1.setP0y(0);  l1.setP1x(4);  l1.setP1y(0);
l2.setP0x(4);  l2.setP0y(0.1); l2.setP1x(2);  l2.setP1y(3.5);
l3.setP0x(2);  l3.setP0y(3.4); l3.setP1x(0.1); l3.setP1y(0.1);

// Connect endpoints so line vertices are coincident
const system = new ConstraintSystem();
system.addConstraint(new CoincidentConstraint(l1.p1, l2.p0)); // l1 end = l2 start
system.addConstraint(new CoincidentConstraint(l2.p1, l3.p0)); // l2 end = l3 start
system.addConstraint(new CoincidentConstraint(l3.p1, l1.p0)); // l3 end = l1 start

const ok = await system.solve();
if (!ok) {
  console.error('System is overconstrained or did not converge');
} else {
  console.log('Triangle vertices:', l1.p0x, l1.p0y, '/', l1.p1x, l1.p1y, '/', l2.p1x, l2.p1y);
}
```

--------------------------------

### Initialize and Manipulate SolverPoint

Source: https://context7.com/tab58/assemble2d/llms.txt

Shows how to create a SolverPoint with initial coordinates and how to update its position using setter methods or the set() method. Each coordinate is tracked by a unique UUID index.

```typescript
import { SolverPoint } from './src/solver/entities';

const pt = new SolverPoint(3.0, 4.0);

console.log(pt.x);      // 3.0
console.log(pt.y);      // 4.0
console.log(pt.xIndex); // UUID string – used internally by constraints
console.log(pt.yIndex); // UUID string

// Update values (also done automatically by the solver after solving)
pt.setX(10.0);
pt.setY(20.0);
pt.set(1.0, 2.0); // set both at once
```

--------------------------------

### Create and Solve Coincident Points with ConstraintSystem

Source: https://context7.com/tab58/assemble2d/llms.txt

Demonstrates creating two points, defining a coincident constraint between them, adding it to a ConstraintSystem, and solving the system. The points will converge to the same location.

```typescript
import { ConstraintSystem } from './src/solver/assembly';
import { SolverPoint } from './src/solver/entities';
import { CoincidentConstraint } from './src/solver/constraints/coincident';

// Create two points that are initially far apart
const p0 = new SolverPoint(0, 0);
const p1 = new SolverPoint(5, 5);

// Declare that they must be coincident (same location)
const constraint = new CoincidentConstraint(p0, p1);

const system = new ConstraintSystem();
system.addConstraint(constraint);

const success = await system.solve();
// success === true when constraints are satisfied

console.log(p0.x, p0.y); // ~2.5, ~2.5
console.log(p1.x, p1.y); // ~2.5, ~2.5  (both converge to same point)
```

--------------------------------

### ConstraintSystem

Source: https://context7.com/tab58/assemble2d/llms.txt

The central orchestrator class that holds constraints, constructs the parameter vector, and drives the L-BFGS optimizer.

```APIDOC
## ConstraintSystem

### Description
The central orchestrator class. Holds a list of `SolverConstraint` objects, constructs the global parameter vector from their indexes, and drives the L-BFGS optimizer to satisfy all constraints.

### Usage Example
```typescript
import { ConstraintSystem } from './src/solver/assembly';
import { SolverPoint } from './src/solver/entities';
import { CoincidentConstraint } from './src/solver/constraints/coincident';

// Create two points that are initially far apart
const p0 = new SolverPoint(0, 0);
const p1 = new SolverPoint(5, 5);

// Declare that they must be coincident (same location)
const constraint = new CoincidentConstraint(p0, p1);

const system = new ConstraintSystem();
system.addConstraint(constraint);

const success = await system.solve();
// success === true when constraints are satisfied

console.log(p0.x, p0.y); // ~2.5, ~2.5
console.log(p1.x, p1.y); // ~2.5, ~2.5  (both converge to same point)
```
```

--------------------------------

### Line2D Geometry Operations

Source: https://context7.com/tab58/assemble2d/llms.txt

Demonstrates constructing Line2D objects from points and directions, and performing operations like intersection, point membership testing, closest point projection, and parallel/perpendicular checks. Requires importing Line2D, Point2D, and Vector2D.

```typescript
import { Line2D }  from './src/geometry/line2';
import { Point2D } from './src/math/point2';
import { Vector2D } from './src/math/vector2';

// Construct from point and direction
const p   = new Point2D(0, 0);
const dir = new Vector2D(1, 0); // horizontal
const line1 = await Line2D.create(p, dir);

// Construct from two points
const p0 = new Point2D(0, 0);
const p1 = new Point2D(4, 3);
const line2 = await Line2D.newFrom2Points(p0, p1);

// Intersection
const vLine = await Line2D.create(new Point2D(2, 0), new Vector2D(0, 1));
const intersect = line1.intersectsLine(vLine);
console.log(intersect.x, intersect.y); // 2, 0

// Point membership
const onLine = await line1.isPointOn(new Point2D(3, 0), 1e-10);
console.log(onLine); // true

// Closest point projection
const closest = await line1.getClosestPointTo(new Point2D(3, 7), 1e-10);
console.log(closest.x, closest.y); // 3, 0

// Parallel / perpendicular tests
const horiz2 = await Line2D.create(new Point2D(0, 5), new Vector2D(1, 0));
console.log(await line1.isParallelTo(horiz2, 1e-10)); // true
```

--------------------------------

### Define and Access SolverLine Endpoints

Source: https://context7.com/tab58/assemble2d/llms.txt

Illustrates creating a SolverLine by setting its two endpoint coordinates. Accessors are provided for each coordinate, and each has a unique index for use in constraints.

```typescript
import { SolverLine } from './src/solver/entities';

const line = new SolverLine();
line.setP0x(0); line.setP0y(0);
line.setP1x(4); line.setP1y(3);

console.log(line.p0x, line.p0y); // 0, 0
console.log(line.p1x, line.p1y); // 4, 3

// Each coordinate has an index for use in constraints:
console.log(line.p0xIndex); // UUID
console.log(line.p1yIndex); // UUID
```

--------------------------------

### L-BFGS Solver for Minimizing Functions

Source: https://context7.com/tab58/assemble2d/llms.txt

Minimizes a differentiable scalar function using the L-BFGS algorithm with backtracking Armijo line search. Suitable for problems with multiple dimensions and requires the function and its gradient.

```typescript
import { SolverLBFGS } from './src/solver/optim/lbfgs';

// Minimize f(x,y) = x² + y²  (minimum at origin)
const f  = (v: number[]) => v[0] * v[0] + v[1] * v[1];
const df = (v: number[]) => [2 * v[0], 2 * v[1]];

const solver = new SolverLBFGS(2 /* dimensions */, 4 /* memory steps */);
const values = [5.0, -3.0]; // starting point

const result = await solver.solve(values, f, df, {
  maxIterations: 500,
  tolerance: 1e-10,
});

console.log(result.success);          // true
console.log(result.iterations);       // number of iterations taken
console.log(result.objectiveValue);   // ~0 (converged to minimum)
console.log(values);                  // [~0, ~0]

// With custom tolerance
const result2 = await solver.solve([10, 10], f, df, { tolerance: 1e-6 });
console.log(result2.relativeDifference < 1e-6); // true
```

--------------------------------

### Point-on-Line Energy Function and Gradient

Source: https://context7.com/tab58/assemble2d/llms.txt

Calculates the energy and gradient for constraining a point to a line. The energy is based on the squared cross-product. Ensure the line is defined by two distinct points.

```typescript
import { pointOnLineEnergyFunc, pointOnLineEnergyGrad } from './src/solver/constraints/energy/pointOnLine';

// Line from (0,0) to (4,0) (x-axis); point (2,0) is on it
console.log(pointOnLineEnergyFunc(0, 0, 4, 0,  2, 0)); // 0

// Point (2,3) is NOT on the x-axis
console.log(pointOnLineEnergyFunc(0, 0, 4, 0,  2, 3)); // 144

const grad = new Array(6).fill(0);
pointOnLineEnergyGrad(0, 0, 4, 0,  2, 3, grad);
```

--------------------------------

### SolverLine

Source: https://context7.com/tab58/assemble2d/llms.txt

Represents a line entity defined by two SolverPoint endpoints.

```APIDOC
## SolverLine

### Description
A line entity defined by two `SolverPoint` endpoints (`p0` and `p1`). Exposes indexed accessors for each coordinate so constraints can reference individual parameters.

### Usage Example
```typescript
import { SolverLine } from './src/solver/entities';

const line = new SolverLine();
line.setP0x(0); line.setP0y(0);
line.setP1x(4); line.setP1y(3);

console.log(line.p0x, line.p0y); // 0, 0
console.log(line.p1x, line.p1y); // 4, 3

// Each coordinate has an index for use in constraints:
console.log(line.p0xIndex); // UUID
console.log(line.p1yIndex); // UUID
```
```

--------------------------------

### SolverPoint

Source: https://context7.com/tab58/assemble2d/llms.txt

Represents a mutable 2D point with indexed x and y coordinates for use in the solver.

```APIDOC
## SolverPoint

### Description
A mutable 2D point whose x and y coordinates are individually tracked `SolverScalar` objects, each with a unique UUID index used to identify parameters in the global optimization vector.

### Usage Example
```typescript
import { SolverPoint } from './src/solver/entities';

const pt = new SolverPoint(3.0, 4.0);

console.log(pt.x);      // 3.0
console.log(pt.y);      // 4.0
console.log(pt.xIndex); // UUID string – used internally by constraints
console.log(pt.yIndex); // UUID string

// Update values (also done automatically by the solver after solving)
pt.setX(10.0);
pt.setY(20.0);
pt.set(1.0, 2.0); // set both at once
```
```

--------------------------------

### Point-on-Circle Energy Function and Gradient

Source: https://context7.com/tab58/assemble2d/llms.txt

Computes the energy and gradient for constraining a point to a circle's circumference. The energy is the squared difference between the squared distance from the center and the squared radius. Requires circle center, radius, and the point coordinates.

```typescript
import { pointOnCircleEnergyFunc, pointOnCircleEnergyGrad } from './src/solver/constraints/energy/pointOnCircle';

// Circle center (0,0) radius 5; point (3,4) lies on it (3²+4²=25=5²)
console.log(pointOnCircleEnergyFunc(3, 4,  0, 0, 5)); // 0

// Point (1,1) does NOT lie on circle of radius 5 centered at origin
console.log(pointOnCircleEnergyFunc(1, 1,  0, 0, 5)); // 529  // (2-25)²

const grad = new Array(5).fill(0);
pointOnCircleEnergyGrad(1, 1,  0, 0, 5, grad);
```

--------------------------------

### Coincident Energy Function and Gradient

Source: https://context7.com/tab58/assemble2d/llms.txt

Evaluates the energy and gradient for coincident points. Energy is zero only when points are identical. The gradient output layout is [gpx, gqx, gpy, gqy].

```typescript
import { coincidentEnergyFunc, coincidentEnergyGrad } from './src/solver/constraints/energy/coincident';

// Energy is zero only when points are identical
console.log(coincidentEnergyFunc(1, 2, 1, 2)); // 0
console.log(coincidentEnergyFunc(0, 0, 3, 4)); // 25  (3² + 4²)

// Gradient: [d/dx0, d/dy0, d/dx1, d/dy1]  (note: output layout is [gpx, gqx, gpy, gqy])
const grad = [0, 0, 0, 0];
coincidentEnergyGrad(0, 0, 3, 4, grad);
console.log(grad); // [-6, 6, -8, 8]
```

--------------------------------

### Fixed Point Energy Function and Gradient

Source: https://context7.com/tab58/assemble2d/llms.txt

Pins a SolverPoint to a specific absolute coordinate (a, b). Energy is calculated as the squared distance from the point to the target coordinate.

```typescript
import { fixedPointEnergyFunc, fixedPointEnergyGrad } from './src/solver/constraints/energy/fixedPoint';

// Point at (3, 4) fixed to (3, 4) — satisfied
console.log(fixedPointEnergyFunc(3, 4, 3, 4)); // 0

// Point at (0, 0) fixed to (3, 4) — not satisfied
console.log(fixedPointEnergyFunc(0, 0, 3, 4)); // 25

const grad = [0, 0];
fixedPointEnergyGrad(0, 0, 3, 4, grad);
console.log(grad); // [-6, -8]
```

--------------------------------

### VectorN Utility for Array Operations

Source: https://context7.com/tab58/assemble2d/llms.txt

Provides essential numerical operations for plain `number[]` arrays, including allocation, copying, scaling, AXPY (scale and add), and dot product. Used internally by SolverLBFGS.

```typescript
import { VectorN } from './src/solver/optim/nvector';

const a = VectorN.new(3);          // [0, 0, 0]
const b = [1, 2, 3];
const c = VectorN.new(3);

VectorN.copy(a, b);                // a = [1, 2, 3]
console.log(VectorN.dot(a, b));    // 14  (1+4+9)

VectorN.scale(2, b, c);            // c = [2, 4, 6]
VectorN.scaleAndAdd(c, 3, b, c);   // c = c + 3*b = [5, 10, 15]  (AXPY)

console.log(VectorN.size(c));      // 3
```

--------------------------------

### Coincident Energy Functions

Source: https://context7.com/tab58/assemble2d/llms.txt

Calculates the energy and its gradient when two points are coincident. Energy is zero only when points are identical.

```APIDOC
## Coincident Energy Functions

Low-level pure functions used internally by `CoincidentConstraint`. Can be used directly to evaluate or test the coincident energy and its gradient without building a full constraint system.

```typescript
import { coincidentEnergyFunc, coincidentEnergyGrad } from './src/solver/constraints/energy/coincident';

// Energy is zero only when points are identical
console.log(coincidentEnergyFunc(1, 2, 1, 2)); // 0
console.log(coincidentEnergyFunc(0, 0, 3, 4)); // 25  (3² + 4²)

// Gradient: [d/dx0, d/dy0, d/dx1, d/dy1]  (note: output layout is [gpx, gqx, gpy, gqy])
const grad = [0, 0, 0, 0];
coincidentEnergyGrad(0, 0, 3, 4, grad);
console.log(grad); // [-6, 6, -8, 8]
```
```

--------------------------------

### CoincidentConstraint

Source: https://context7.com/tab58/assemble2d/llms.txt

Forces two SolverPoint objects to occupy the same (x, y) location.

```APIDOC
## CoincidentConstraint

### Description
Forces two `SolverPoint` objects to occupy the same (x, y) location. Uses energy function `f = (x1-x0)² + (y1-y0)²`.

### Usage Example
```typescript
import { ConstraintSystem } from './src/solver/assembly';
import { SolverPoint } from './src/solver/entities';
import { CoincidentConstraint } from './src/solver/constraints/coincident';

const p0 = new SolverPoint(0, 0);
const p1 = new SolverPoint(10, 10);

const system = new ConstraintSystem();
system.addConstraint(new CoincidentConstraint(p0, p1));

await system.solve();
// p0 and p1 now share the same location
console.log(Math.abs(p0.x - p1.x) < 1e-6); // true
console.log(Math.abs(p0.y - p1.y) < 1e-6); // true
```
```

--------------------------------

### Parallel Energy Function and Gradient

Source: https://context7.com/tab58/assemble2d/llms.txt

Enforces that two lines are parallel using a cross-product formulation. The gradient array holds partial derivatives for all 8 coordinates.

```typescript
import { parallelEnergyFunc, parallelEnergyGrad } from './src/solver/constraints/energy/parallel';

// Line1: (0,0)→(1,0), Line2: (0,1)→(1,1) — already parallel
console.log(parallelEnergyFunc(0, 0, 1, 0,  0, 1, 1, 1)); // 0

// Line1: (0,0)→(1,0), Line2: (0,0)→(0,1) — perpendicular, not parallel
console.log(parallelEnergyFunc(0, 0, 1, 0,  0, 0, 0, 1)); // 1

const grad = new Array(8).fill(0);
parallelEnergyGrad(0, 0, 1, 0,  0, 0, 0, 1, grad);
// grad[0..7] holds d/dx0, d/dy0, d/dx1, d/dy1, d/dx2, d/dy2, d/dx3, d/dy3
```

--------------------------------

### Parallel Energy Functions

Source: https://context7.com/tab58/assemble2d/llms.txt

Enforces that two lines, defined by their endpoint pairs, are parallel. Uses Eberly's cross-product formulation.

```APIDOC
## Parallel Energy Functions

Enforces that two lines (defined by endpoint pairs) are parallel. Based on Eberly's cross-product formulation: `f = (dx10·dy32 - dx32·dy10)²`.

```typescript
import { parallelEnergyFunc, parallelEnergyGrad } from './src/solver/constraints/energy/parallel';

// Line1: (0,0)→(1,0), Line2: (0,1)→(1,1) — already parallel
console.log(parallelEnergyFunc(0, 0, 1, 0,  0, 1, 1, 1)); // 0

// Line1: (0,0)→(1,0), Line2: (0,0)→(0,1) — perpendicular, not parallel
console.log(parallelEnergyFunc(0, 0, 1, 0,  0, 0, 0, 1)); // 1

const grad = new Array(8).fill(0);
parallelEnergyGrad(0, 0, 1, 0,  0, 0, 0, 1, grad);
// grad[0..7] holds d/dx0, d/dy0, d/dx1, d/dy1, d/dx2, d/dy2, d/dx3, d/dy3
```
```

--------------------------------

### Perpendicular Energy Function and Gradient

Source: https://context7.com/tab58/assemble2d/llms.txt

Enforces that two lines are perpendicular by minimizing the square of their dot product. The gradient array holds partial derivatives for all 8 coordinates.

```typescript
import { perpendicularEnergyFunc, perpendicularEnergyGrad } from './src/solver/constraints/energy/perpendicular';

// Line1: (0,0)→(1,0), Line2: (0,0)→(0,1) — already perpendicular
console.log(perpendicularEnergyFunc(0, 0, 1, 0,  0, 0, 0, 1)); // 0

// Line1: (0,0)→(1,0), Line2: (0,0)→(1,1) — not perpendicular
console.log(perpendicularEnergyFunc(0, 0, 1, 0,  0, 0, 1, 1)); // 1

const grad = new Array(8).fill(0);
perpendicularEnergyGrad(0, 0, 1, 0,  0, 0, 1, 1, grad);
```

--------------------------------

### Circle2D Geometry Class

Source: https://context7.com/tab58/assemble2d/llms.txt

A high-level 2D circle class for geometric computations. Supports creation from various inputs (center+radius, center+point, 3 points) and testing point membership on the circumference within a given tolerance.

```typescript
import { Circle2D } from './src/geometry/circle2';
import { Point2D }  from './src/math/point2';

// Create from center + radius
const center = new Point2D(0, 0);
const circle = await Circle2D.create(center, 5);
console.log(circle.getRadius());  // 5

// Create from center + point on circle
const onCircle = new Point2D(3, 4);
const c2 = await Circle2D.newFromCenterAndPoint(center, onCircle);
console.log(c2.getRadius());      // 5

// Create from 3 points (circumscribed circle)
const p1 = new Point2D(1, 0);
const p2 = new Point2D(0, 1);
const p3 = new Point2D(-1, 0);
const c3 = await Circle2D.newFrom3Points(p1, p2, p3, 1e-10);

// Test if a point lies on the circle within tolerance
const pt = new Point2D(5 + 1e-15, 0);
const isOn = await circle.isPointOn(pt, 1e-10);
console.log(isOn); // true
```

--------------------------------

### Perpendicular Energy Functions

Source: https://context7.com/tab58/assemble2d/llms.txt

Enforces that two lines are perpendicular by minimizing the square of their dot product.

```APIDOC
## Perpendicular Energy Functions

Enforces that two lines are perpendicular by minimizing the square of their dot product: `f = (u·v)²`.

```typescript
import { perpendicularEnergyFunc, perpendicularEnergyGrad } from './src/solver/constraints/energy/perpendicular';

// Line1: (0,0)→(1,0), Line2: (0,0)→(0,1) — already perpendicular
console.log(perpendicularEnergyFunc(0, 0, 1, 0,  0, 0, 0, 1)); // 0

// Line1: (0,0)→(1,0), Line2: (0,0)→(1,1) — not perpendicular
console.log(perpendicularEnergyFunc(0, 0, 1, 0,  0, 0, 1, 1)); // 1

const grad = new Array(8).fill(0);
perpendicularEnergyGrad(0, 0, 1, 0,  0, 0, 1, 1, grad);
```
```

--------------------------------

### SolverCircle

Source: https://context7.com/tab58/assemble2d/llms.txt

Represents a circle entity defined by a center SolverPoint and a radius SolverScalar.

```APIDOC
## SolverCircle

### Description
A circle entity defined by a center `SolverPoint` and a `SolverScalar` radius. All three parameters (cx, cy, r) are individually indexed.

### Usage Example
```typescript
import { SolverCircle } from './src/solver/entities';

const circle = new SolverCircle();
circle.setCenterX(5);
circle.setCenterY(5);
circle.setRadius(3);

console.log(circle.centerX, circle.centerY); // 5, 5
console.log(circle.radius);                  // 3
console.log(circle.radiusIndex);             // UUID for radius parameter
```
```

--------------------------------

### Horizontal / Vertical Line Energy Functions

Source: https://context7.com/tab58/assemble2d/llms.txt

Functions to enforce horizontal (y-coordinates are equal) or vertical (x-coordinates are equal) alignment for line segments.

```APIDOC
## Horizontal / Vertical Line Energy Functions

`horizontalLineEnergyFunc` forces the two endpoints of a line to share the same y-coordinate. `verticalLineEnergyFunc` forces them to share the same x-coordinate.

```typescript
import { horizontalLineEnergyFunc } from './src/solver/constraints/energy/horizontalLine';
import { verticalLineEnergyFunc }   from './src/solver/constraints/energy/verticalLine';

// Horizontal: (0,0)→(5,0) — y0 == y1, satisfied
console.log(horizontalLineEnergyFunc(0, 0, 5, 0)); // 0
// Not satisfied: (0,0)→(5,3)
console.log(horizontalLineEnergyFunc(0, 0, 5, 3)); // 9  ((0-3)²)

// Vertical: (2,0)→(2,5) — x0 == x1, satisfied
console.log(verticalLineEnergyFunc(2, 0, 2, 5)); // 0
// Not satisfied: (1,0)→(2,5)
console.log(verticalLineEnergyFunc(1, 0, 2, 5)); // 1
```
```

--------------------------------

### Equal Length Energy Function and Gradient

Source: https://context7.com/tab58/assemble2d/llms.txt

Ensures two line segments have the same Euclidean length. The gradient array holds partial derivatives for all 8 coordinates.

```typescript
import { equalLengthEnergyFunc, equalLengthEnergyGrad } from './src/solver/constraints/energy/equalLength';

// Segment1: (0,0)→(3,4) → length 5; Segment2: (0,0)→(0,5) → length 5
console.log(equalLengthEnergyFunc(0, 0, 3, 4,  0, 0, 0, 5)); // 0

// Segment1 length 5, Segment2 length 3 → not equal
console.log(equalLengthEnergyFunc(0, 0, 3, 4,  0, 0, 0, 3)); // 256

const grad = new Array(8).fill(0);
equalLengthEnergyGrad(0, 0, 3, 4,  0, 0, 0, 3, grad);
```

--------------------------------

### Equal Length Energy Functions

Source: https://context7.com/tab58/assemble2d/llms.txt

Ensures two line segments have the same Euclidean length. Energy is calculated as (|L1|² - |L2|²)².

```APIDOC
## Equal Length Energy Functions

Ensures two line segments (each given by endpoint pairs) have the same Euclidean length. Energy: `f = (|L1|² - |L2|²)²`.

```typescript
import { equalLengthEnergyFunc, equalLengthEnergyGrad } from './src/solver/constraints/energy/equalLength';

// Segment1: (0,0)→(3,4) → length 5; Segment2: (0,0)→(0,5) → length 5
console.log(equalLengthEnergyFunc(0, 0, 3, 4,  0, 0, 0, 5)); // 0

// Segment1 length 5, Segment2 length 3 → not equal
console.log(equalLengthEnergyFunc(0, 0, 3, 4,  0, 0, 0, 3)); // 256

const grad = new Array(8).fill(0);
equalLengthEnergyGrad(0, 0, 3, 4,  0, 0, 0, 3, grad);
```
```

--------------------------------

### Radius Energy Function and Gradient

Source: https://context7.com/tab58/assemble2d/llms.txt

Constrains the radius of a circle to a specific value 'r'. Energy is the squared difference between the circle's radius and the target radius.

```typescript
import { radiusEnergyFunc, radiusEnergyGrad } from './src/solver/constraints/energy/radiusLength';

// Circle radius 5, constrained to 5 — satisfied
console.log(radiusEnergyFunc(0, 0, 5, 5)); // 0

// Circle radius 3, constrained to 5
console.log(radiusEnergyFunc(0, 0, 3, 5)); // 4

const grad = [0, 0, 0];
radiusEnergyGrad(0, 0, 3, 5, grad);
console.log(grad); // [0, 0, -4]  (only r0 component is non-zero)
```

--------------------------------

### Line-Circle Tangent Energy Function and Gradient

Source: https://context7.com/tab58/assemble2d/llms.txt

Forces a line segment to be tangent to a circle. Energy is based on the squared point-to-line distance from the circle's center to the line, compared against the radius.

```typescript
import { lineCircleTangentEnergyFunc, lineCircleTangentEnergyGrad } from './src/solver/constraints/energy/lineCircleTangent';

// Line from (0,0) to (10,0) (x-axis); circle center (5,3) radius 3
// Distance from center to line = 3 = radius → tangent
console.log(lineCircleTangentEnergyFunc(0, 0, 10, 0,  5, 3, 3)); // 0

// Same line, circle center (5,5) radius 3 — not tangent (dist=5 ≠ 3)
console.log(lineCircleTangentEnergyFunc(0, 0, 10, 0,  5, 5, 3)); // > 0

const grad = new Array(7).fill(0);
lineCircleTangentEnergyGrad(0, 0, 10, 0,  5, 3, 3, grad);
```

--------------------------------

### Distance Energy Function and Gradient

Source: https://context7.com/tab58/assemble2d/llms.txt

Encodes the constraint that two points are separated by a fixed Euclidean distance 'd'. The gradient returns partial derivatives with respect to x0, y0, x1, y1.

```typescript
import { distanceEnergyFunc, distanceEnergyGrad } from './src/solver/constraints/energy/distance';

// Points (0,0) and (3,4) → distance = 5
console.log(distanceEnergyFunc(0, 0, 3, 4, 5)); // 0  (satisfied)
console.log(distanceEnergyFunc(0, 0, 3, 4, 6)); // 121  (not satisfied)

const grad = [0, 0, 0, 0];
distanceEnergyGrad(0, 0, 3, 4, 5, grad);
// Returns partial derivatives w.r.t. x0, y0, x1, y1
console.log(grad); // [0, 0, 0, 0]  (at minimum, gradient is zero)
```

--------------------------------

### Circle-Circle Tangent Energy Function and Gradient

Source: https://context7.com/tab58/assemble2d/llms.txt

Forces two circles to be externally tangent. Energy is the squared difference between the distance between their centers and the sum of their radii.

```typescript
import { circleCircleTangentEnergyFunc, circleCircleTangentEnergyGrad } from './src/solver/constraints/energy/circleCircleTangent';

// Circle1: center (0,0) r=3; Circle2: center (5,0) r=2 → dist=5, r0+r1=5
console.log(circleCircleTangentEnergyFunc(0, 0, 3,  5, 0, 2)); // 0

// Not tangent: center (0,0) r=1, center (5,0) r=1 → dist=5, r0+r1=2
console.log(circleCircleTangentEnergyFunc(0, 0, 1,  5, 0, 1)); // 441

const grad = new Array(6).fill(0);
circleCircleTangentEnergyGrad(0, 0, 3,  5, 0, 2, grad);
```

--------------------------------

### Concentric Energy Function and Gradient

Source: https://context7.com/tab58/assemble2d/llms.txt

Forces two circles to share the same center point. It uses the squared distance between centers as energy. The radii do not affect the energy calculation.

```typescript
import { concentricEnergyFunc, concentricEnergyGrad } from './src/solver/constraints/energy/concentric';

// Two circles both centered at (2, 3) — satisfied
console.log(concentricEnergyFunc(2, 3, 1,  2, 3, 4)); // 0

// Centers (0,0) and (3,4)
console.log(concentricEnergyFunc(0, 0, 1,  3, 4, 2)); // 25

const grad = new Array(6).fill(0);
concentricEnergyGrad(0, 0, 1,  3, 4, 2, grad);
// grad[2] and grad[5] are always 0 (radii not involved)
```

--------------------------------

### Angle Energy Function and Gradient

Source: https://context7.com/tab58/assemble2d/llms.txt

Constrains the angle between two lines to a specified value using an atan2 formulation for stability. The gradient array holds partial derivatives for all 8 coordinates.

```typescript
import { angleEnergyFunc, angleEnergyGrad } from './src/solver/constraints/energy/angle';

const theta = Math.PI / 2; // 90 degrees

// Line1: (0,0)→(1,0), Line2: (0,0)→(0,1) — exactly 90°
console.log(angleEnergyFunc(0, 0, 1, 0,  0, 0, 0, 1,  theta)); // ~0

// Line1: (0,0)→(1,0), Line2: (0,0)→(1,0) — 0° angle, not 90°
console.log(angleEnergyFunc(0, 0, 1, 0,  0, 0, 1, 0,  theta)); // > 0

const grad = new Array(8).fill(0);
angleEnergyGrad(0, 0, 1, 0,  0, 0, 0, 1,  theta, grad);
```

--------------------------------

### Midpoint Energy Function and Gradient

Source: https://context7.com/tab58/assemble2d/llms.txt

Constrains a point (x, y) to lie at the midpoint of a segment defined by two other points. Energy is the squared difference between the point's position and the calculated midpoint.

```typescript
import { midpointEnergyFunc, midpointEnergyGrad } from './src/solver/constraints/energy/midpoint';

// Midpoint of (0,0)→(4,4) is (2,2)
console.log(midpointEnergyFunc(0, 0, 4, 4, 2, 2)); // 0

// (3,3) is NOT the midpoint of (0,0)→(4,4)
console.log(midpointEnergyFunc(0, 0, 4, 4, 3, 3)); // 64

const grad = new Array(6).fill(0);
midpointEnergyGrad(0, 0, 4, 4, 3, 3, grad);
```

--------------------------------

### Horizontal and Vertical Distance Energy Functions

Source: https://context7.com/tab58/assemble2d/llms.txt

Enforces a fixed horizontal or vertical separation 'l' between two points. Energy is the squared difference between the actual and target separation.

```typescript
import { horizontalDistanceEnergyFunc } from './src/solver/constraints/energy/horizontalDistance';
import { verticalDistanceEnergyFunc }   from './src/solver/constraints/energy/verticalDistance';

// Horizontal distance between (0,0) and (4,99) should be 4
console.log(horizontalDistanceEnergyFunc(0, 0, 4, 99, 4)); // 0
console.log(horizontalDistanceEnergyFunc(0, 0, 3, 99, 4)); // 49  // (9-16)²

// Vertical distance between (99,0) and (99,6) should be 6
console.log(verticalDistanceEnergyFunc(99, 99, 0, 6, 6)); // 0
console.log(verticalDistanceEnergyFunc(99, 99, 0, 4, 6)); // 256  // (16-36)²
```

--------------------------------

### Distance Energy Functions

Source: https://context7.com/tab58/assemble2d/llms.txt

Encodes the constraint that two points are separated by a fixed Euclidean distance 'd'. Energy is calculated as ((x1-x0)² + (y1-y0)² - d²)².

```APIDOC
## Distance Energy Functions

Encodes the constraint that two points are separated by a fixed Euclidean distance `d`. Energy: `f = ((x1-x0)² + (y1-y0)² - d²)²`.

```typescript
import { distanceEnergyFunc, distanceEnergyGrad } from './src/solver/constraints/energy/distance';

// Points (0,0) and (3,4) → distance = 5
console.log(distanceEnergyFunc(0, 0, 3, 4, 5)); // 0  (satisfied)
console.log(distanceEnergyFunc(0, 0, 3, 4, 6)); // 121  (not satisfied)

const grad = [0, 0, 0, 0];
distanceEnergyGrad(0, 0, 3, 4, 5, grad);
// Returns partial derivatives w.r.t. x0, y0, x1, y1
console.log(grad); // [0, 0, 0, 0]  (at minimum, gradient is zero)
```
```

--------------------------------

### Angle Energy Functions

Source: https://context7.com/tab58/assemble2d/llms.txt

Constrains the angle between two lines to a specified value 'theta' in radians using an atan2 formulation for stability.

```APIDOC
## Angle Energy Functions

Constrains the angle between two lines (each given by two endpoints) to a specified value `theta` (in radians). Uses `atan2` formulation for numerical stability.

```typescript
import { angleEnergyFunc, angleEnergyGrad } from './src/solver/constraints/energy/angle';

const theta = Math.PI / 2; // 90 degrees

// Line1: (0,0)→(1,0), Line2: (0,0)→(0,1) — exactly 90°
console.log(angleEnergyFunc(0, 0, 1, 0,  0, 0, 0, 1,  theta)); // ~0

// Line1: (0,0)→(1,0), Line2: (0,0)→(1,0) — 0° angle, not 90°
console.log(angleEnergyFunc(0, 0, 1, 0,  0, 0, 1, 0,  theta)); // > 0

const grad = new Array(8).fill(0);
angleEnergyGrad(0, 0, 1, 0,  0, 0, 0, 1,  theta, grad);
```
```
Tokens:
Raw