@tscircuit/capacity-autorouter 0.0.189 → 0.0.191

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import * as graphics_debug from 'graphics-debug';
 import { GraphicsObject, Rect, Circle, Line, Point as Point$3 } from 'graphics-debug';
 import { ConnectivityMap } from 'circuit-json-to-connectivity-map';
-import { RectDiffSolver } from '@tscircuit/rectdiff';
+import { RectDiffPipeline } from '@tscircuit/rectdiff';
 import { Polygon } from '@tscircuit/math-utils';
 
 type TraceId = string;
@@ -42,6 +42,7 @@ interface SimpleRouteJson {
     traces?: SimplifiedPcbTraces;
 }
 interface Obstacle {
+    obstacleId?: string;
     type: "rect";
     layers: string[];
     zLayers?: number[];
@@ -107,6 +108,8 @@ interface CapacityMeshNode {
     _isVirtualOffboard?: boolean;
     _offboardNetName?: string;
     _adjacentNodeIds?: CapacityMeshNodeId[];
+    _offBoardConnectionId?: string;
+    _offBoardConnectedCapacityMeshNodeIds?: CapacityMeshNodeId[];
     _parent?: CapacityMeshNode;
 }
 interface CapacityMeshEdge {
@@ -1094,10 +1097,15 @@ interface PortPointPathingHyperParameters {
     GREEDY_MULTIPLIER?: number;
     NODE_PF_FACTOR?: number;
     RANDOM_COST_MAGNITUDE?: number;
+    NODE_PF_MAX_PENALTY?: number;
     MEMORY_PF_FACTOR?: number;
     BASE_CANDIDATE_COST?: number;
-    REWARD_LOW_TRAVEL_PF_MAGNITUDE?: number;
+    MIN_ALLOWED_BOARD_SCORE?: number;
     MAX_ITERATIONS_PER_PATH?: number;
+    FORCE_CENTER_FIRST?: boolean;
+    RANDOM_WALK_DISTANCE?: number;
+    FORCE_OFF_BOARD_FREQUENCY?: number;
+    FORCE_OFF_BOARD_SEED?: number;
 }
 /**
  * An input port point without connectionName assigned yet.
@@ -1112,6 +1120,7 @@ interface InputPortPoint {
     connectionNodeIds: [CapacityMeshNodeId, CapacityMeshNodeId];
     /** XY distance to the centermost port on this Z level (centermost port has distance 0) */
     distToCentermostPortOnZ: number;
+    connectsToOffBoardNode?: boolean;
 }
 /**
  * A node with pre-computed port points (without connectionName assigned).
@@ -1132,6 +1141,8 @@ interface InputNodeWithPortPoints {
     _containsTarget?: boolean;
     /** If true, this node contains an obstacle */
     _containsObstacle?: boolean;
+    _offBoardConnectionId?: string;
+    _offBoardConnectedCapacityMeshNodeIds?: CapacityMeshNodeId[];
 }
 /**
  * A candidate in the A* search. Represents being at a port point,
@@ -1153,6 +1164,11 @@ interface PortPointCandidate {
     f: number;
     g: number;
     h: number;
+    /** Total distance traveled from start to this candidate */
+    distanceTraveled: number;
+    /** Whether this candidate has ever crossed through an off-board node */
+    hasTouchedOffBoardNode?: boolean;
+    lastMoveWasOffBoard?: boolean;
 }
 interface ConnectionPathResult {
     connection: SimpleRouteConnection;
@@ -1197,25 +1213,33 @@ declare class PortPointPathingSolver extends BaseSolver {
     nodeAssignedPortPoints: Map<CapacityMeshNodeId, PortPoint[]>;
     /** Factor applied to port point reuse penalty */
     PORT_POINT_REUSE_FACTOR: number;
+    /**
+     * Cost when a node doesn't go off board when it's supposed to w/ the
+     * FORCE_OFF_BOARD_FREQUENCY setting.
+     */
+    BASE_COST_FOR_NOT_GOING_OFF_BOARD: number;
     /** Multiplied by Pf delta cost (in -log(1-pf) space) */
     get NODE_PF_FACTOR(): number;
+    get RANDOM_WALK_DISTANCE(): number;
     /** Used only in heuristic (h) to "look ahead" into known-congested regions */
     get MEMORY_PF_FACTOR(): number;
     get CENTER_OFFSET_FOCUS_SHIFT(): number;
     /** Used as a *tie-breaker* in f (not part of g) */
     get RANDOM_COST_MAGNITUDE(): number;
-    /** Optional heuristic reward for stepping into low-memoryPf nodes */
-    get REWARD_LOW_TRAVEL_PF_MAGNITUDE(): number;
     /** Cost of adding a candidate to the path */
     get BASE_CANDIDATE_COST(): number;
-    /** Cost penalty for changing layers (used in heuristic) */
-    Z_DIST_COST: number;
+    get NODE_PF_MAX_PENALTY(): number;
+    get FORCE_CENTER_FIRST(): boolean;
+    get FORCE_OFF_BOARD_FREQUENCY(): number;
+    get FORCE_OFF_BOARD_SEED(): number;
+    get NODE_MAX_PF(): number;
     /** Penalty factor for port points that are far from the center of the segment */
     get CENTER_OFFSET_DIST_PENALTY_FACTOR(): number;
     colorMap: Record<string, string>;
     get GREEDY_MULTIPLIER(): number;
     MAX_CANDIDATES_IN_MEMORY: number;
     get MAX_ITERATIONS_PER_PATH(): number;
+    get MIN_ALLOWED_BOARD_SCORE(): number;
     nodeMemoryPfMap: Map<CapacityMeshNodeId, number>;
     currentConnectionIndex: number;
     currentPathIterations: number;
@@ -1226,10 +1250,12 @@ declare class PortPointPathingSolver extends BaseSolver {
     capacityMeshNodeMap: Map<CapacityMeshNodeId, CapacityMeshNode>;
     /** Heuristic scaling: an estimate of "node pitch" used to estimate remaining hops */
     avgNodePitch: number;
+    /** Whether the current connection should be forced to route off-board */
+    currentConnectionShouldRouteOffBoard: boolean;
+    /** Cached list of off-board nodes for computing distance to nearest off-board node */
+    offBoardNodes: InputNodeWithPortPoints[];
     /** Cache of base node cost (cost of node in current committed state) */
     private baseNodeCostCache;
-    /** Cache of delta cost for a specific node segment (entry->exit) for a specific connection */
-    private segmentDeltaCostCache;
     constructor({ simpleRouteJson, inputNodes, capacityMeshNodes, colorMap, nodeMemoryPfMap, hyperParameters, }: {
         simpleRouteJson: SimpleRouteJson;
         capacityMeshNodes: CapacityMeshNode[];
@@ -1242,10 +1268,9 @@ declare class PortPointPathingSolver extends BaseSolver {
     private clampPf;
     /** Convert Pf into an additive "failure cost" */
     private pfToFailureCost;
-    private round3;
-    private pointKey;
     /** Base node cost with the currently-committed port points (no candidate additions) */
     private getBaseNodeFailureCost;
+    computeBoardScore(): number;
     /**
      * Exact delta cost of routing this connection through `nodeId`
      * for the segment defined by entry->exit.
@@ -1288,6 +1313,13 @@ declare class PortPointPathingSolver extends BaseSolver {
      * This ensures the last node's segment is accounted for in g.
      */
     private computeGToEndTarget;
+    /**
+     * Compute distance to the nearest off-board node from a point.
+     */
+    computeDistanceToNearestOffBoardNode(point: {
+        x: number;
+        y: number;
+    }): number;
     /**
      * Heuristic: approximate remaining cost.
      *
@@ -1296,10 +1328,8 @@ declare class PortPointPathingSolver extends BaseSolver {
      *  - estimated remaining hops (distance / avgNodePitch)
      *  - memoryPfMap to bias away from historically high Pf regions
      */
-    computeH(point: {
-        x: number;
-        y: number;
-    }, currentNodeId: CapacityMeshNodeId, endGoalNodeId: CapacityMeshNodeId, currentZ: number): number;
+    computeH(point: InputPortPoint, currentNodeId: CapacityMeshNodeId, endGoalNodeId: CapacityMeshNodeId, currentZ: number, distanceTraveled: number, hasTouchedOffBoardNode?: boolean): number;
+    getAvailableExitPortPoints(nodeId: CapacityMeshNodeId): InputPortPoint[];
     /**
      * Get available port points to exit from a node, but *do not* return all.
      *
@@ -1309,7 +1339,10 @@ declare class PortPointPathingSolver extends BaseSolver {
      *   unassigned offsets as backups.
      */
     getAvailableExitPortPointsWithOmissions(nodeId: CapacityMeshNodeId, _endGoalNodeId: CapacityMeshNodeId): InputPortPoint[];
-    canTravelThroughObstacle(node: InputNodeWithPortPoints, connectionName: string): boolean;
+    getAvailableExitPortPointsForOffboardConnection(nodeId: CapacityMeshNodeId): (InputPortPoint & {
+        throughNodeId: CapacityMeshNodeId;
+    })[];
+    canTravelThroughObstacle(node: InputNodeWithPortPoints, connectionName: string, rootConnectionName: string): boolean;
     /**
      * Check if we've reached the end goal node
      */
@@ -1340,6 +1373,72 @@ declare class PortPointPathingSolver extends BaseSolver {
     visualize(): GraphicsObject;
 }
 
+interface HyperPortPointPathingSolverParams {
+    simpleRouteJson: SimpleRouteJson;
+    capacityMeshNodes: CapacityMeshNode[];
+    inputNodes: InputNodeWithPortPoints[];
+    colorMap?: Record<string, string>;
+    nodeMemoryPfMap?: Map<CapacityMeshNodeId, number>;
+    numShuffleSeeds?: number;
+    minAllowedBoardScore?: number;
+    hyperParameters?: Partial<PortPointPathingHyperParameters>;
+}
+declare class HyperPortPointPathingSolver extends HyperParameterSupervisorSolver<PortPointPathingSolver> {
+    private params;
+    constructor(params: HyperPortPointPathingSolverParams);
+    getHyperParameterDefs(): Array<HyperParameterDef>;
+    getCombinationDefs(): Array<string[]>;
+    generateSolver(hyperParameters: any): PortPointPathingSolver;
+    /**
+     * G measures the "cost" of this solver based on current score.
+     * We use the raw board score (more negative = worse quality = higher cost).
+     *
+     * The key insight is that early scores (at ~25% progress) are predictive
+     * of final quality. Solvers with better early scores tend to finish better.
+     */
+    computeG(solver: PortPointPathingSolver): number;
+    /**
+     * H estimates remaining "cost" based on current trajectory.
+     *
+     * Key insight from analysis: bad solvers have similar early scores but
+     * explode later (e.g., seed 760: -0.23 @ 25% → -15.05 final).
+     * Good solvers maintain low scores throughout (e.g., seed 829: -0.06 @ 25% → -2.42 final).
+     *
+     * We estimate remaining cost by extrapolating current score/connection rate.
+     */
+    computeH(solver: PortPointPathingSolver): number;
+    /**
+     * Get the nodes with port points from the winning solver
+     */
+    getNodesWithPortPoints(): NodeWithPortPoints[];
+    /**
+     * Get connection results from the winning solver
+     */
+    get connectionsWithResults(): ConnectionPathResult[];
+    /**
+     * Get input nodes from the winning solver
+     */
+    get inputNodes(): InputNodeWithPortPoints[];
+    /**
+     * Get node map from the winning solver
+     */
+    get nodeMap(): Map<CapacityMeshNodeId, InputNodeWithPortPoints>;
+    /**
+     * Get assigned port points from the winning solver
+     */
+    get assignedPortPoints(): Map<any, any>;
+    /**
+     * Get node assigned port points from the winning solver
+     */
+    get nodeAssignedPortPoints(): Map<any, any>;
+    /**
+     * Compute board score from the winning solver
+     */
+    computeBoardScore(): number;
+    onSolve(solver: SupervisedSolver<PortPointPathingSolver>): void;
+    visualize(): GraphicsObject;
+}
+
 interface PortPointSectionParams {
     centerOfSectionCapacityNodeId: CapacityMeshNodeId;
     expansionDegrees: number;
@@ -1514,7 +1613,12 @@ declare class MultiSectionPortPointOptimizer extends BaseSolver {
      * Marks nodes containing cut path endpoints as targets so the solver can route to/from them.
      */
     prepareSectionInputNodesForCutPaths(section: PortPointSection): InputNodeWithPortPoints[];
-    getHyperParametersForAttempt(attempt: number): PortPointPathingHyperParameters;
+    getHyperParametersForScheduleIndex(scheduleIndex: number, sectionAttempt: number): PortPointPathingHyperParameters;
+    /**
+     * Create a PortPointPathingSolver for the current section.
+     * This centralizes the solver creation logic that was previously duplicated in 3 places.
+     */
+    createSectionSolver(section: PortPointSection): PortPointPathingSolver;
     /**
      * Reattach the optimized section results back to the main state.
      * Handles both fully contained connections AND cut paths.
@@ -1542,7 +1646,7 @@ declare class AutoroutingPipelineSolver2_PortPointPathing extends BaseSolver {
     srj: SimpleRouteJson;
     opts: CapacityMeshSolverOptions$2;
     netToPointPairsSolver?: NetToPointPairsSolver;
-    nodeSolver?: RectDiffSolver;
+    nodeSolver?: RectDiffPipeline;
     nodeTargetMerger?: CapacityNodeTargetMerger;
     edgeSolver?: CapacityMeshEdgeSolver;
     colorMap: Record<string, string>;
@@ -1553,7 +1657,7 @@ declare class AutoroutingPipelineSolver2_PortPointPathing extends BaseSolver {
     deadEndSolver?: DeadEndSolver;
     traceSimplificationSolver?: TraceSimplificationSolver;
     availableSegmentPointSolver?: AvailableSegmentPointSolver;
-    portPointPathingSolver?: PortPointPathingSolver;
+    portPointPathingSolver?: HyperPortPointPathingSolver;
     multiSectionPortPointOptimizer?: MultiSectionPortPointOptimizer;
     viaDiameter: number;
     minTraceWidth: number;
@@ -1566,7 +1670,7 @@ declare class AutoroutingPipelineSolver2_PortPointPathing extends BaseSolver {
     capacityNodes: CapacityMeshNode[] | null;
     capacityEdges: CapacityMeshEdge[] | null;
     cacheProvider: CacheProvider | null;
-    pipelineDef: (PipelineStep$2<typeof NetToPointPairsSolver2_OffBoardConnection> | PipelineStep$2<typeof RectDiffSolver> | PipelineStep$2<typeof CapacityMeshEdgeSolver2_NodeTreeOptimization> | PipelineStep$2<typeof AvailableSegmentPointSolver> | PipelineStep$2<typeof PortPointPathingSolver> | PipelineStep$2<typeof MultiSectionPortPointOptimizer> | PipelineStep$2<typeof HighDensitySolver> | PipelineStep$2<typeof MultipleHighDensityRouteStitchSolver> | PipelineStep$2<typeof TraceSimplificationSolver>)[];
+    pipelineDef: (PipelineStep$2<typeof NetToPointPairsSolver2_OffBoardConnection> | PipelineStep$2<typeof RectDiffPipeline> | PipelineStep$2<typeof CapacityMeshEdgeSolver2_NodeTreeOptimization> | PipelineStep$2<typeof AvailableSegmentPointSolver> | PipelineStep$2<typeof HyperPortPointPathingSolver> | PipelineStep$2<typeof MultiSectionPortPointOptimizer> | PipelineStep$2<typeof HighDensitySolver> | PipelineStep$2<typeof MultipleHighDensityRouteStitchSolver> | PipelineStep$2<typeof TraceSimplificationSolver>)[];
     constructor(srj: SimpleRouteJson, opts?: CapacityMeshSolverOptions$2);
     currentPipelineStepIndex: number;
     _step(): void;
@@ -2398,7 +2502,7 @@ declare class AutoroutingPipeline1_OriginalUnravel extends BaseSolver {
     srj: SimpleRouteJson;
     opts: CapacityMeshSolverOptions$1;
     netToPointPairsSolver?: NetToPointPairsSolver;
-    nodeSolver?: RectDiffSolver;
+    nodeSolver?: RectDiffPipeline;
     nodeTargetMerger?: CapacityNodeTargetMerger;
     edgeSolver?: CapacityMeshEdgeSolver;
     initialPathingSolver?: CapacityPathingGreedySolver;
@@ -2425,7 +2529,7 @@ declare class AutoroutingPipeline1_OriginalUnravel extends BaseSolver {
     capacityNodes: CapacityMeshNode[] | null;
     capacityEdges: CapacityMeshEdge[] | null;
     cacheProvider: CacheProvider | null;
-    pipelineDef: (PipelineStep$1<typeof NetToPointPairsSolver2_OffBoardConnection> | PipelineStep$1<typeof RectDiffSolver> | PipelineStep$1<typeof StrawSolver> | PipelineStep$1<typeof CapacityMeshEdgeSolver2_NodeTreeOptimization> | PipelineStep$1<typeof DeadEndSolver> | PipelineStep$1<typeof CapacityPathingGreedySolver> | PipelineStep$1<typeof CapacityPathingMultiSectionSolver> | PipelineStep$1<typeof CapacityEdgeToPortSegmentSolver> | PipelineStep$1<typeof CapacitySegmentToPointSolver> | PipelineStep$1<typeof UnravelMultiSectionSolver> | PipelineStep$1<typeof HighDensitySolver> | PipelineStep$1<typeof MultipleHighDensityRouteStitchSolver> | PipelineStep$1<typeof TraceSimplificationSolver>)[];
+    pipelineDef: (PipelineStep$1<typeof NetToPointPairsSolver2_OffBoardConnection> | PipelineStep$1<typeof RectDiffPipeline> | PipelineStep$1<typeof StrawSolver> | PipelineStep$1<typeof CapacityMeshEdgeSolver2_NodeTreeOptimization> | PipelineStep$1<typeof DeadEndSolver> | PipelineStep$1<typeof CapacityPathingGreedySolver> | PipelineStep$1<typeof CapacityPathingMultiSectionSolver> | PipelineStep$1<typeof CapacityEdgeToPortSegmentSolver> | PipelineStep$1<typeof CapacitySegmentToPointSolver> | PipelineStep$1<typeof UnravelMultiSectionSolver> | PipelineStep$1<typeof HighDensitySolver> | PipelineStep$1<typeof MultipleHighDensityRouteStitchSolver> | PipelineStep$1<typeof TraceSimplificationSolver>)[];
     constructor(srj: SimpleRouteJson, opts?: CapacityMeshSolverOptions$1);
     currentPipelineStepIndex: number;
     _step(): void;
@@ -3207,10 +3311,10 @@ type AutoroutingPipelineSolverOptions = CapacityMeshSolverOptions;
 type PipelineStep<T extends new (...args: any[]) => BaseSolver> = {
     solverName: string;
     solverClass: T;
-    getConstructorParams: (instance: AssignableViaAutoroutingPipelineSolver) => ConstructorParameters<T>;
-    onSolved?: (instance: AssignableViaAutoroutingPipelineSolver) => void;
+    getConstructorParams: (instance: AssignableAutoroutingPipeline1Solver) => ConstructorParameters<T>;
+    onSolved?: (instance: AssignableAutoroutingPipeline1Solver) => void;
 };
-declare class AssignableViaAutoroutingPipelineSolver extends BaseSolver {
+declare class AssignableAutoroutingPipeline1Solver extends BaseSolver {
     srj: SimpleRouteJson;
     opts: CapacityMeshSolverOptions;
     netToPointPairsSolver?: NetToPointPairsSolver;
@@ -3278,4 +3382,4 @@ declare const convertSrjToGraphicsObject: (srj: SimpleRouteJson) => {
     points: Point$3[];
 };
 
-export { AssignableViaAutoroutingPipelineSolver, AutoroutingPipeline1_OriginalUnravel, AutoroutingPipelineSolver2_PortPointPathing as AutoroutingPipelineSolver, type AutoroutingPipelineSolverOptions, type CachableSolver, type CacheProvider, CapacityMeshSolver, InMemoryCache, LocalStorageCache, calculateOptimalCapacityDepth, convertSrjToGraphicsObject, getGlobalInMemoryCache, getGlobalLocalStorageCache, getTunedTotalCapacity1, setupGlobalCaches };
+export { AssignableAutoroutingPipeline1Solver, AutoroutingPipeline1_OriginalUnravel, AutoroutingPipelineSolver2_PortPointPathing as AutoroutingPipelineSolver, type AutoroutingPipelineSolverOptions, type CachableSolver, type CacheProvider, CapacityMeshSolver, InMemoryCache, LocalStorageCache, calculateOptimalCapacityDepth, convertSrjToGraphicsObject, getGlobalInMemoryCache, getGlobalLocalStorageCache, getTunedTotalCapacity1, setupGlobalCaches };