@tscircuit/hypergraph 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tscircuit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,224 @@
+# @tscircuit/hypergraph
+
+A generic A* pathfinding solver for routing connections through hypergraphs. Designed for circuit routing problems but extensible to any graph-based pathfinding scenario.
+
+## Installation
+
+```bash
+npm install @tscircuit/hypergraph
+```
+
+## Overview
+
+HyperGraphSolver implements an A* algorithm that routes connections through a hypergraph data structure where:
+
+- **Regions** are nodes representing spaces in your problem domain
+- **Ports** are edges connecting two regions (the boundary between them)
+- **Connections** define start and end regions that need to be linked
+
+The solver finds optimal paths through the graph while handling conflicts via "ripping" - the ability to reroute existing paths when they block new connections.
+
+## Core Types
+
+```typescript
+interface Region {
+  regionId: string
+  ports: RegionPort[]
+  d: any // Domain-specific data (e.g., bounds, coordinates)
+  assignments?: RegionPortAssignment[]
+}
+
+interface RegionPort {
+  portId: string
+  region1: Region
+  region2: Region
+  d: any // Domain-specific data (e.g., x, y position)
+  assignment?: PortAssignment
+  ripCount?: number
+}
+
+interface Connection {
+  connectionId: string
+  mutuallyConnectedNetworkId: string
+  startRegion: Region
+  endRegion: Region
+}
+
+interface HyperGraph {
+  regions: Region[]
+  ports: RegionPort[]
+}
+```
+
+## Basic Usage
+
+```typescript
+import { HyperGraphSolver } from "@tscircuit/hypergraph"
+
+const solver = new HyperGraphSolver({
+  inputGraph: {
+    regions: [...],
+    ports: [...],
+  },
+  inputConnections: [
+    { connectionId: "c1", mutuallyConnectedNetworkId: "net1", startRegion: regionA, endRegion: regionB },
+    { connectionId: "c2", mutuallyConnectedNetworkId: "net2", startRegion: regionC, endRegion: regionD },
+  ],
+})
+
+solver.solve()
+
+if (solver.solved) {
+  console.log(solver.solvedRoutes)
+}
+```
+
+## Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `inputGraph` | `HyperGraph \| SerializedHyperGraph` | required | The graph with regions and ports |
+| `inputConnections` | `Connection[]` | required | Connections to route |
+| `greedyMultiplier` | `number` | `1.0` | Weight for heuristic score (higher = greedier search) |
+| `rippingEnabled` | `boolean` | `false` | Allow rerouting existing paths to resolve conflicts |
+| `ripCost` | `number` | `0` | Additional cost penalty when ripping is required |
+
+## Creating a Custom Solver
+
+HyperGraphSolver is designed to be extended. Override these methods to customize behavior for your domain:
+
+```typescript
+import { HyperGraphSolver, Region, RegionPort, Candidate } from "@tscircuit/hypergraph"
+
+class MyCustomSolver extends HyperGraphSolver<MyRegion, MyPort> {
+  /**
+   * Estimate cost from a port to the destination region.
+   * Used for the A* heuristic.
+   */
+  estimateCostToEnd(port: MyPort): number {
+    // Return estimated distance/cost to currentEndRegion
+  }
+
+  /**
+   * Compute heuristic score for a candidate.
+   * Default uses estimateCostToEnd().
+   */
+  computeH(candidate: Candidate<MyRegion, MyPort>): number {
+    return this.estimateCostToEnd(candidate.port)
+  }
+
+  /**
+   * Return penalty for using a port (e.g., if previously ripped).
+   */
+  getPortUsagePenalty(port: MyPort): number {
+    return port.ripCount ?? 0
+  }
+
+  /**
+   * Cost increase when routing through a region using two specific ports.
+   * Useful for penalizing crossings or congestion.
+   */
+  computeIncreasedRegionCostIfPortsAreUsed(
+    region: MyRegion,
+    port1: MyPort,
+    port2: MyPort
+  ): number {
+    return 0
+  }
+
+  /**
+   * Detect assignments that conflict with using port1 and port2 together.
+   * Return assignments that must be ripped.
+   */
+  getRipsRequiredForPortUsage(
+    region: MyRegion,
+    port1: MyPort,
+    port2: MyPort
+  ): RegionPortAssignment[] {
+    return []
+  }
+
+  /**
+   * Filter candidates entering a region to reduce redundant exploration.
+   */
+  selectCandidatesForEnteringRegion(
+    candidates: Candidate<MyRegion, MyPort>[]
+  ): Candidate<MyRegion, MyPort>[] {
+    return candidates
+  }
+
+  /**
+   * Hook called after each route is solved.
+   */
+  routeSolvedHook(solvedRoute: SolvedRoute): void {
+    // Custom logic after route completion
+  }
+}
+```
+
+## Solver Output
+
+After calling `solve()`, access results via:
+
+```typescript
+solver.solved         // boolean - true if all connections routed
+solver.solvedRoutes   // SolvedRoute[] - array of solved paths
+solver.iterations     // number - iterations used
+solver.failed         // boolean - true if max iterations exceeded
+```
+
+Each `SolvedRoute` contains:
+
+```typescript
+interface SolvedRoute {
+  connection: Connection      // The connection that was routed
+  path: Candidate[]           // Sequence of candidates forming the path
+  requiredRip: boolean        // Whether ripping was needed
+}
+```
+
+## Serialized Input Format
+
+For JSON serialization, use ID references instead of object references:
+
+```typescript
+interface SerializedHyperGraph {
+  regions: Array<{
+    regionId: string
+    d: any
+  }>
+  ports: Array<{
+    portId: string
+    region1Id: string
+    region2Id: string
+    d: any
+  }>
+}
+
+interface SerializedConnection {
+  connectionId: string
+  mutuallyConnectedNetworkId: string
+  startRegionId: string
+  endRegionId: string
+}
+```
+
+The solver automatically converts serialized inputs to hydrated object references.
+
+## Algorithm
+
+HyperGraphSolver uses A* pathfinding:
+
+1. Initialize candidate queue with all ports of the start region
+2. Process candidates in priority order (lowest `f = g + h * greedyMultiplier`)
+3. When reaching the destination, trace back through parent pointers
+4. Handle conflicts by ripping (removing conflicting routes and re-queuing them)
+5. Continue until all connections are routed or max iterations exceeded
+
+## Example Implementation
+
+For a complete real-world implementation, see [JumperGraphSolver](./lib/JumperGraphSolver/JumperGraphSolver.ts) which extends HyperGraphSolver for PCB resistor network routing.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,360 @@
+import { GraphicsObject } from 'graphics-debug';
+import { BaseSolver } from '@tscircuit/solver-utils';
+import { Matrix } from 'transformation-matrix';
+
+type PortId = string;
+type RegionId = string;
+type ConnectionId = string;
+type NetworkId = string;
+type GScore = number;
+type RegionPort = {
+    portId: PortId;
+    region1: Region;
+    region2: Region;
+    d: any;
+    assignment?: PortAssignment;
+    /**
+     * The number of times this port has been ripped. Can be used to penalize
+     * ports that are likely to block off connections
+     */
+    ripCount?: number;
+};
+type Region = {
+    regionId: RegionId;
+    ports: RegionPort[];
+    d: any;
+    assignments?: RegionPortAssignment[];
+};
+type PortAssignment = {
+    solvedRoute: SolvedRoute;
+    connection: Connection;
+};
+type RegionPortAssignment = {
+    regionPort1: RegionPort;
+    regionPort2: RegionPort;
+    region: Region;
+    connection: Connection;
+    solvedRoute: SolvedRoute;
+};
+type SolvedRoute = {
+    path: Candidate[];
+    connection: Connection;
+    requiredRip: boolean;
+};
+type Candidate<RegionType extends Region = Region, RegionPortType extends RegionPort = RegionPort> = {
+    port: RegionPortType;
+    g: number;
+    h: number;
+    f: number;
+    hops: number;
+    parent?: Candidate;
+    lastPort?: RegionPortType;
+    lastRegion?: RegionType;
+    nextRegion?: RegionType;
+    ripRequired: boolean;
+};
+type HyperGraph = {
+    ports: RegionPort[];
+    regions: Region[];
+};
+type SerializedGraphPort = Omit<RegionPort, "edges"> & {
+    portId: PortId;
+    region1Id: RegionId;
+    region2Id: RegionId;
+};
+type SerializedGraphRegion = Omit<Region, "points" | "assignments"> & {
+    pointIds: PortId[];
+    assignments?: SerializedRegionPortAssignment[];
+};
+type SerializedRegionPortAssignment = {
+    regionPort1Id: PortId;
+    regionPort2Id: PortId;
+    connectionId: ConnectionId;
+};
+type SerializedHyperGraph = {
+    ports: SerializedGraphPort[];
+    regions: SerializedGraphRegion[];
+};
+type Connection = {
+    connectionId: ConnectionId;
+    mutuallyConnectedNetworkId: NetworkId;
+    startRegion: Region;
+    endRegion: Region;
+};
+type SerializedConnection = {
+    connectionId: ConnectionId;
+    startRegionId: RegionId;
+    endRegionId: RegionId;
+};
+
+type Bounds = {
+    minX: number;
+    minY: number;
+    maxX: number;
+    maxY: number;
+};
+
+interface JRegion extends Region {
+    d: {
+        bounds: Bounds;
+        center: {
+            x: number;
+            y: number;
+        };
+        isPad: boolean;
+        isThroughJumper?: boolean;
+        isConnectionRegion?: boolean;
+    };
+}
+interface JPort extends RegionPort {
+    d: {
+        x: number;
+        y: number;
+    };
+}
+type JumperGraph = {
+    regions: JRegion[];
+    ports: JPort[];
+};
+
+declare const generateJumperX4Grid: ({ cols, rows, marginX, marginY, innerColChannelPointCount, innerRowChannelPointCount, regionsBetweenPads, outerPaddingX, outerPaddingY, outerChannelXPointCount, outerChannelYPointCount, orientation, center, }: {
+    cols: number;
+    rows: number;
+    marginX: number;
+    marginY: number;
+    innerColChannelPointCount?: number;
+    innerRowChannelPointCount?: number;
+    regionsBetweenPads?: boolean;
+    outerPaddingX?: number;
+    outerPaddingY?: number;
+    outerChannelXPointCount?: number;
+    outerChannelYPointCount?: number;
+    orientation?: "vertical" | "horizontal";
+    center?: {
+        x: number;
+        y: number;
+    };
+}) => JumperGraph;
+
+declare const generateJumperGrid: ({ cols, rows, marginX, marginY, innerColChannelPointCount, innerRowChannelPointCount, outerPaddingX, outerPaddingY, outerChannelXPoints, outerChannelYPoints, }: {
+    cols: number;
+    rows: number;
+    marginX: number;
+    marginY: number;
+    innerColChannelPointCount?: number;
+    innerRowChannelPointCount?: number;
+    outerPaddingX?: number;
+    outerPaddingY?: number;
+    outerChannelXPoints?: number;
+    outerChannelYPoints?: number;
+}) => {
+    regions: JRegion[];
+    ports: JPort[];
+};
+
+type XYConnection = {
+    start: {
+        x: number;
+        y: number;
+    };
+    end: {
+        x: number;
+        y: number;
+    };
+    connectionId: string;
+};
+type JumperGraphWithConnections = JumperGraph & {
+    connections: Connection[];
+};
+/**
+ * Creates a new graph from a base graph with additional connection regions at
+ * specified positions on the boundary. Connection regions are 0.4x0.4 pseudo-regions
+ * that contain one port point connecting them to the grid boundary.
+ */
+declare const createGraphWithConnectionsFromBaseGraph: (baseGraph: JumperGraph, xyConnections: XYConnection[]) => JumperGraphWithConnections;
+
+type Node = {
+    f: number;
+    [key: string]: any;
+};
+declare class PriorityQueue<T extends Node = Node> {
+    private heap;
+    private maxSize;
+    /**
+     * Creates a new Priority Queue.
+     * @param nodes An optional initial array of nodes to populate the queue.
+     * @param maxSize The maximum number of elements the queue can hold. Defaults to 10,000.
+     */
+    constructor(nodes?: T[], maxSize?: number);
+    /**
+     * Returns the number of elements currently in the queue.
+     */
+    get size(): number;
+    /**
+     * Checks if the queue is empty.
+     */
+    isEmpty(): boolean;
+    /**
+     * Returns the node with the highest priority (smallest 'f') without removing it.
+     * Returns null if the queue is empty.
+     * @returns The highest priority node or null.
+     */
+    peek(): T | null;
+    /**
+     * Returns up to N nodes with the highest priority (smallest 'f') without removing them.
+     * Nodes are returned sorted by priority (smallest 'f' first).
+     * @param count Maximum number of nodes to return.
+     * @returns Array of nodes sorted by priority.
+     */
+    peekMany(count: number): T[];
+    /**
+     * Removes and returns the node with the highest priority (smallest 'f').
+     * Returns null if the queue is empty.
+     * Maintains the heap property.
+     * @returns The highest priority node or null.
+     */
+    dequeue(): T | null;
+    /**
+     * Adds a new node to the queue.
+     * Maintains the heap property.
+     * If the queue is full (at maxSize), the node is not added.
+     * @param node The node to add.
+     */
+    enqueue(node: T): void;
+    /**
+     * Moves the node at the given index up the heap to maintain the heap property.
+     * @param index The index of the node to sift up.
+     */
+    private _siftUp;
+    /**
+     * Moves the node at the given index down the heap to maintain the heap property.
+     * @param index The index of the node to sift down.
+     */
+    private _siftDown;
+    /**
+     * Swaps two elements in the heap array.
+     * @param i Index of the first element.
+     * @param j Index of the second element.
+     */
+    private _swap;
+    /** Calculates the parent index of a node. */
+    private _parentIndex;
+    /** Calculates the left child index of a node. */
+    private _leftChildIndex;
+    /** Calculates the right child index of a node. */
+    private _rightChildIndex;
+}
+
+declare class HyperGraphSolver<RegionType extends Region = Region, RegionPortType extends RegionPort = RegionPort, CandidateType extends Candidate<RegionType, RegionPortType> = Candidate<RegionType, RegionPortType>> extends BaseSolver {
+    input: {
+        inputGraph: HyperGraph | SerializedHyperGraph;
+        inputConnections: (Connection | SerializedConnection)[];
+        greedyMultiplier?: number;
+        rippingEnabled?: boolean;
+        ripCost?: number;
+    };
+    graph: HyperGraph;
+    connections: Connection[];
+    candidateQueue: PriorityQueue<Candidate>;
+    unprocessedConnections: Connection[];
+    solvedRoutes: SolvedRoute[];
+    currentConnection: Connection | null;
+    currentEndRegion: Region | null;
+    greedyMultiplier: number;
+    rippingEnabled: boolean;
+    ripCost: number;
+    lastCandidate: Candidate | null;
+    visitedPointsForCurrentConnection: Map<PortId, GScore>;
+    constructor(input: {
+        inputGraph: HyperGraph | SerializedHyperGraph;
+        inputConnections: (Connection | SerializedConnection)[];
+        greedyMultiplier?: number;
+        rippingEnabled?: boolean;
+        ripCost?: number;
+    });
+    computeH(candidate: CandidateType): number;
+    /**
+     * OVERRIDE THIS
+     *
+     * Return the estimated remaining cost to the end of the route. You must
+     * first understand the UNIT of your costs. If it's distance, then this could
+     * be something like distance(port, this.currentEndRegion.d.center)
+     */
+    estimateCostToEnd(port: RegionPortType): number;
+    /**
+     * OPTIONALLY OVERRIDE THIS
+     *
+     * This is a penalty for using a port that is not relative to a connection,
+     * e.g. maybe this port is in a special area of congestion. Use this to
+     * penalize ports that are e.g. likely to block off connections, you may want
+     * to use port.ripCount to help determine this penalty, or you can use port
+     * position, region volume etc.
+     */
+    getPortUsagePenalty(port: RegionPortType): number;
+    /**
+     * OVERRIDE THIS
+     *
+     * Return the cost of using two ports in the region, make sure to consider
+     * existing assignments. You may use this to penalize intersections
+     */
+    computeIncreasedRegionCostIfPortsAreUsed(region: RegionType, port1: RegionPortType, port2: RegionPortType): number;
+    /**
+     * OPTIONALLY OVERRIDE THIS
+     *
+     * Return the assignments that would need to be ripped if the given ports
+     * are used together in the region. This is used to determine if adopting
+     * a route would require ripping other routes due to problematic crossings.
+     */
+    getRipsRequiredForPortUsage(_region: RegionType, _port1: RegionPortType, _port2: RegionPortType): RegionPortAssignment[];
+    computeG(candidate: CandidateType): number;
+    /**
+     * Return a subset of the candidates for entering a region. These candidates
+     * are all possible ways to enter the region- you can e.g. return the middle
+     * port to make it so that you're not queueing candidates that are likely
+     * redundant.
+     */
+    selectCandidatesForEnteringRegion(candidates: Candidate[]): Candidate[];
+    getNextCandidates(currentCandidate: CandidateType): CandidateType[];
+    processSolvedRoute(finalCandidate: CandidateType): void;
+    /**
+     * OPTIONALLY OVERRIDE THIS
+     *
+     * You can override this to perform actions after a route is solved, e.g.
+     * you may want to detect if a solvedRoute.requiredRip is true, in which
+     * case you might want to execute a "random rip" to avoid loops or check
+     * if we've exceeded a maximum number of rips.
+     *
+     * You can also use this to shuffle unprocessed routes if a rip occurred, this
+     * can also help avoid loops
+     */
+    routeSolvedHook(solvedRoute: SolvedRoute): void;
+    ripSolvedRoute(solvedRoute: SolvedRoute): void;
+    beginNewConnection(): void;
+    _step(): void;
+}
+
+declare class JumperGraphSolver extends HyperGraphSolver<JRegion, JPort> {
+    UNIT_OF_COST: string;
+    constructor(input: {
+        inputGraph: HyperGraph | SerializedHyperGraph;
+        inputConnections: (Connection | SerializedConnection)[];
+    });
+    estimateCostToEnd(port: JPort): number;
+    getPortUsagePenalty(port: JPort): number;
+    computeIncreasedRegionCostIfPortsAreUsed(region: JRegion, port1: JPort, port2: JPort): number;
+    getRipsRequiredForPortUsage(region: JRegion, port1: JPort, port2: JPort): RegionPortAssignment[];
+    routeSolvedHook(solvedRoute: SolvedRoute): void;
+    visualize(): GraphicsObject;
+}
+
+/**
+ * Applies a transformation matrix to all points in a graph.
+ * Transforms region bounds, region centers, and port positions.
+ */
+declare const applyTransformToGraph: (graph: JumperGraph, matrix: Matrix) => JumperGraph;
+/**
+ * Rotates a graph 90 degrees clockwise around its center.
+ */
+declare const rotateGraph90Degrees: (graph: JumperGraph) => JumperGraph;
+
+export { HyperGraphSolver, JumperGraphSolver, type JumperGraphWithConnections, type XYConnection, applyTransformToGraph, createGraphWithConnectionsFromBaseGraph, generateJumperGrid, generateJumperX4Grid, rotateGraph90Degrees };