@tscircuit/fastforce

Fast force-directed graph solving with support for segment-applied forces.

View online

Installation

npm install @tscircuit/fastforce

Usage

import { ForceRelaxationSolver } from "@tscircuit/fastforce"
import type { ForceRelaxationProblem } from "@tscircuit/fastforce"

const problem: ForceRelaxationProblem = {
  bounds: { minX: 0, minY: 0, maxX: 100, maxY: 100 },
  boundaryPadding: 10,
  layerIds: ["0", "1"],

  entities: {
    points: [
      {
        pointId: "p1",
        position: { x: 0, y: 20 },
        movable: false,
        radius: 0,
        layerIds: ["0"],
      },
      {
        pointId: "p2",
        position: { x: 50, y: 20 },
        movable: true,
        radius: 0,
        layerIds: ["0", "1"],
      },
    ],
    segments: [
      {
        segmentId: "s1",
        startPointId: "p1",
        endPointId: "p2",
        width: 2,
        layerId: "0",
        fixedLength: false,
        fixedOrientation: false,
      },
    ],
  },

  interactions: {
    segSegRepel: {
      strength: 1,
      exponentialDecay: 0.5,
      overlapMultiplier: 5,
      minSeparation: 10,
    },
    pointSegRepel: {
      strength: 1,
      exponentialDecay: 0.5,
      overlapMultiplier: 5,
      minSeparation: 10,
    },
    boundsKeepIn: {
      strength: 2,
      exponentialDecay: 1,
      overlapMultiplier: 10,
    },
    fixedLengthCorrection: {
      strength: 1,
      exponentialDecay: 0,
    },
    fixedOrientationCorrection: {
      strength: 5,
      exponentialDecay: 0,
    },
  },

  solve: {
    maxSteps: 300,
    stepSize: 0.1,
    epsilonMove: 0.01,
    maxMovePerStep: 2,
    friction: 0.1,
    relaxationSteps: 100,
  },
}

const solver = new ForceRelaxationSolver(problem)

// Run until solved or max iterations reached
solver.solve()

// Access updated point positions
for (const point of problem.entities.points) {
  console.log(`${point.pointId}: (${point.position.x}, ${point.position.y})`)
}

API

ForceRelaxationSolver

The main solver class. Extends BaseSolver from @tscircuit/solver-utils.

• constructor(problem: ForceRelaxationProblem) - Create a new solver
• solve() - Run the solver until convergence or max iterations
• step() - Run a single iteration
• visualize() - Returns a GraphicsObject for visualization

ForceRelaxationProblem

Configuration object with the following properties:

| Property | Description | | ------------------- | ------------------------------------------------------ | | bounds | Axis-aligned bounding box { minX, minY, maxX, maxY } | | boundaryPadding | Inset from bounds for keep-in constraints | | layerIds | Array of layer identifiers | | entities.points | Array of point entities | | entities.segments | Array of segment entities | | interactions | Force interaction parameters | | solve | Solver parameters |

Solver Parameters

| Parameter | Description | Default | | ----------------- | ------------------------------------- | ------- | | maxSteps | Maximum iterations | - | | stepSize | Integration step size | - | | epsilonMove | Convergence threshold | - | | maxMovePerStep | Maximum movement per step | - | | friction | Velocity damping (0-1, 1=no momentum) | 1.0 | | relaxationSteps | Steps to linearly reduce forces | 0 |