@tscircuit/schematic-trace-solver 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,420 @@
+import * as graphics_debug from 'graphics-debug';
+import { GraphicsObject } from 'graphics-debug';
+import { Bounds, Point } from '@tscircuit/math-utils';
+import Flatbush from 'flatbush';
+import { ConnectivityMap } from 'connectivity-map';
+
+declare class BaseSolver {
+    MAX_ITERATIONS: number;
+    solved: boolean;
+    failed: boolean;
+    iterations: number;
+    progress: number;
+    error: string | null;
+    activeSubSolver?: BaseSolver | null;
+    failedSubSolvers?: BaseSolver[];
+    timeToSolve?: number;
+    stats: Record<string, any>;
+    /** DO NOT OVERRIDE! Override _step() instead */
+    step(): void;
+    _step(): void;
+    getConstructorParams(): void;
+    solve(): void;
+    visualize(): GraphicsObject;
+    /**
+     * Called when the solver is about to fail, but we want to see if we have an
+     * "acceptable" or "passable" solution. Mostly used for optimizers that
+     * have an aggressive early stopping criterion.
+     */
+    tryFinalAcceptance(): void;
+    /**
+     * A lightweight version of the visualize method that can be used to stream
+     * progress
+     */
+    preview(): GraphicsObject;
+}
+
+interface SpatiallyIndexedChip extends InputChip {
+    bounds: Bounds;
+    spatialIndexId: number;
+}
+declare class ChipObstacleSpatialIndex {
+    chips: Array<SpatiallyIndexedChip>;
+    spatialIndex: Flatbush;
+    spatialIndexIdToChip: Map<number, SpatiallyIndexedChip>;
+    constructor(chips: InputChip[]);
+    getChipsInBounds(bounds: Bounds): Array<InputChip & {
+        bounds: Bounds;
+    }>;
+    doesOrthogonalLineIntersectChip(line: [Point, Point], opts?: {
+        excludeChipIds?: string[];
+    }): boolean;
+}
+
+type FacingDirection = "x+" | "x-" | "y+" | "y-";
+
+type ChipId = string;
+type PinId = string;
+type NetId = string;
+interface InputPin {
+    pinId: PinId;
+    x: number;
+    y: number;
+    _facingDirection?: "x+" | "x-" | "y+" | "y-";
+}
+interface InputChip {
+    chipId: ChipId;
+    center: {
+        x: number;
+        y: number;
+    };
+    width: number;
+    height: number;
+    pins: Array<InputPin>;
+}
+interface InputDirectConnection {
+    pinIds: [PinId, PinId];
+    netId?: string;
+}
+interface InputNetConnection {
+    netId: string;
+    pinIds: Array<PinId>;
+}
+interface InputProblem {
+    chips: Array<InputChip>;
+    directConnections: Array<InputDirectConnection>;
+    netConnections: Array<InputNetConnection>;
+    availableNetLabelOrientations: Record<NetId, FacingDirection[]>;
+    _chipObstacleSpatialIndex?: ChipObstacleSpatialIndex;
+}
+
+type MspConnectionPairId = string;
+type MspConnectionPair = {
+    mspPairId: MspConnectionPairId;
+    dcConnNetId: string;
+    globalConnNetId: string;
+    userNetId?: string;
+    pins: [InputPin & {
+        chipId: string;
+    }, InputPin & {
+        chipId: string;
+    }];
+};
+declare class MspConnectionPairSolver extends BaseSolver {
+    inputProblem: InputProblem;
+    mspConnectionPairs: MspConnectionPair[];
+    dcConnMap: ConnectivityMap;
+    globalConnMap: ConnectivityMap;
+    queuedDcNetIds: string[];
+    chipMap: Record<string, InputChip>;
+    pinMap: Record<string, InputPin & {
+        chipId: string;
+    }>;
+    userNetIdByPinId: Record<string, string | undefined>;
+    constructor({ inputProblem }: {
+        inputProblem: InputProblem;
+    });
+    getConstructorParams(): ConstructorParameters<typeof MspConnectionPairSolver>[0];
+    _step(): void;
+    visualize(): GraphicsObject;
+}
+
+type Guideline = {
+    orientation: "horizontal";
+    y: number;
+    x: undefined;
+} | {
+    orientation: "vertical";
+    y: undefined;
+    x: number;
+};
+declare class GuidelinesSolver extends BaseSolver {
+    inputProblem: InputProblem;
+    guidelines: Guideline[];
+    chipPairsGenerator: Generator<readonly [InputChip, InputChip]>;
+    usedXGuidelines: Set<number>;
+    usedYGuidelines: Set<number>;
+    constructor(params: {
+        inputProblem: InputProblem;
+    });
+    getConstructorParams(): ConstructorParameters<typeof GuidelinesSolver>[0];
+    _step(): void;
+    visualize(): GraphicsObject;
+}
+
+interface MovableSegment {
+    start: Point;
+    end: Point;
+    freedom: "x+" | "x-" | "y+" | "y-";
+    dir: {
+        x: number;
+        y: number;
+    };
+}
+
+declare class SchematicTraceSingleLineSolver extends BaseSolver {
+    pins: MspConnectionPair["pins"];
+    inputProblem: InputProblem;
+    guidelines: Guideline[];
+    chipMap: Record<string, InputChip>;
+    movableSegments: Array<MovableSegment>;
+    baseElbow: Point[];
+    queuedCandidatePaths: Array<Point[]>;
+    chipObstacleSpatialIndex: ChipObstacleSpatialIndex;
+    solvedTracePath: {
+        x: number;
+        y: number;
+    }[] | null;
+    constructor(params: {
+        pins: MspConnectionPair["pins"];
+        guidelines: Guideline[];
+        inputProblem: InputProblem;
+        chipMap: Record<string, InputChip>;
+    });
+    getConstructorParams(): ConstructorParameters<typeof SchematicTraceSingleLineSolver>[0];
+    _step(): void;
+    visualize(): GraphicsObject;
+}
+
+interface SolvedTracePath extends MspConnectionPair {
+    tracePath: Point[];
+}
+declare class SchematicTraceLinesSolver extends BaseSolver {
+    inputProblem: InputProblem;
+    guidelines: Guideline[];
+    mspConnectionPairs: MspConnectionPair[];
+    dcConnMap: ConnectivityMap;
+    globalConnMap: ConnectivityMap;
+    queuedConnectionPairs: MspConnectionPair[];
+    chipMap: Record<string, InputChip>;
+    currentConnectionPair: MspConnectionPair | null;
+    solvedTracePaths: Array<SolvedTracePath>;
+    activeSubSolver: SchematicTraceSingleLineSolver | null;
+    constructor(params: {
+        mspConnectionPairs: MspConnectionPair[];
+        chipMap: Record<string, InputChip>;
+        dcConnMap: ConnectivityMap;
+        globalConnMap: ConnectivityMap;
+        inputProblem: InputProblem;
+        guidelines: Guideline[];
+    });
+    getConstructorParams(): ConstructorParameters<typeof SchematicTraceLinesSolver>[0];
+    _step(): void;
+    visualize(): GraphicsObject;
+}
+
+type ConnNetId$1 = string;
+interface OverlappingTraceSegmentLocator {
+    connNetId: string;
+    pathsWithOverlap: Array<{
+        solvedTracePathIndex: number;
+        traceSegmentIndex: number;
+    }>;
+}
+declare class TraceOverlapIssueSolver extends BaseSolver {
+    overlappingTraceSegments: OverlappingTraceSegmentLocator[];
+    traceNetIslands: Record<ConnNetId$1, Array<SolvedTracePath>>;
+    SHIFT_DISTANCE: number;
+    correctedTraceMap: Record<MspConnectionPairId, SolvedTracePath>;
+    constructor(params: {
+        overlappingTraceSegments: OverlappingTraceSegmentLocator[];
+        traceNetIslands: Record<ConnNetId$1, Array<SolvedTracePath>>;
+    });
+    _step(): void;
+    visualize(): GraphicsObject;
+}
+
+type ConnNetId = string;
+/**
+ * This solver finds traces that overlap (coincident and parallel) and aren't
+ * connected via the globalConnMap, then shifts them to avoid the overlap in
+ * such a way that minimizes the resulting intersections
+ *
+ * All traces are orthogonal, so for traces to be considered overlapping, they
+ * need to each have a segment where both are horizontal or both are vertical
+ * AND the segments must be within 1e-6 of each other in X (if vertical) or
+ * Y (if horizontal)
+ *
+ * Each iteration, we find overlapping traces that aren't part of the same net.
+ * This is the same as finding two "trace net islands" that have an overlap.
+ *
+ * We then consider all the possible ways to shift the overlapping traces to
+ * minimize the intersections. If there are multiple trace segments within the
+ * same net island they shift together.
+ */
+declare class TraceOverlapShiftSolver extends BaseSolver {
+    inputProblem: InputProblem;
+    inputTracePaths: Array<SolvedTracePath>;
+    globalConnMap: ConnectivityMap;
+    activeSubSolver: TraceOverlapIssueSolver | null;
+    /**
+     * A traceNetIsland is a set of traces that are connected via the globalConnMap
+     */
+    traceNetIslands: Record<ConnNetId, Array<SolvedTracePath>>;
+    correctedTraceMap: Record<MspConnectionPairId, SolvedTracePath>;
+    constructor(params: {
+        inputProblem: InputProblem;
+        inputTracePaths: Array<SolvedTracePath>;
+        globalConnMap: ConnectivityMap;
+    });
+    getConstructorParams(): ConstructorParameters<typeof TraceOverlapShiftSolver>[0];
+    computeTraceNetIslands(): Record<ConnNetId, Array<SolvedTracePath>>;
+    findNextOverlapIssue(): {
+        overlappingTraceSegments: Array<OverlappingTraceSegmentLocator>;
+    } | null;
+    _step(): void;
+    visualize(): graphics_debug.GraphicsObject;
+}
+
+/**
+ * Find a location in the overlappingSameNetTraceGroup where a net label should
+ * be placed. We do this by looking for the largest chip, and starting our
+ * search from the segment directly connected to the largest chip. We then
+ * travel along the segment, moving to any connected segment. Each step, we
+ * check a specific segment
+ *
+ * When checking a segment, we check the following locations with each
+ * orientation:
+ * - The start of the segment
+ * - The start of the segment, plus the width of the net label
+ * - The end of the segment
+ * - The end of the segment, minus the width of the net label
+ *
+ * When checking a location, we check for the following:
+ * 1. Would placing a net label at this location cause a collision with a chip?
+ * 2. Would placing a net label at this location cause a collision with ANY
+ *    trace? (Note: you must offset the anchor point slightly from the trace to
+ *    avoid counting the point where the net label contacts the trace)
+ *
+ * The first location that satisfies the above conditions, in our traversal
+ * order from the largest chip, is the location we return in netLabelPlacement
+ */
+declare class SingleNetLabelPlacementSolver extends BaseSolver {
+    inputProblem: InputProblem;
+    inputTraceMap: Record<MspConnectionPairId, SolvedTracePath>;
+    overlappingSameNetTraceGroup: OverlappingSameNetTraceGroup;
+    availableOrientations: Array<FacingDirection>;
+    chipObstacleSpatialIndex: ChipObstacleSpatialIndex;
+    netLabelPlacement: NetLabelPlacement | null;
+    testedCandidates: Array<{
+        center: {
+            x: number;
+            y: number;
+        };
+        width: number;
+        height: number;
+        bounds: {
+            minX: number;
+            minY: number;
+            maxX: number;
+            maxY: number;
+        };
+        anchor: {
+            x: number;
+            y: number;
+        };
+        orientation: FacingDirection;
+        status: "ok" | "chip-collision" | "trace-collision" | "parallel-to-segment";
+        hostSegIndex: number;
+    }>;
+    constructor(params: {
+        inputProblem: InputProblem;
+        inputTraceMap: Record<MspConnectionPairId, SolvedTracePath>;
+        overlappingSameNetTraceGroup: OverlappingSameNetTraceGroup;
+        availableOrientations: FacingDirection[];
+    });
+    private getDimsForOrientation;
+    private getCenterFromAnchor;
+    private getRectBounds;
+    private segmentIntersectsRect;
+    private rectIntersectsAnyTrace;
+    _step(): void;
+    visualize(): GraphicsObject;
+}
+
+/**
+ * A group of traces that have at least one overlapping segment and
+ * are part of the same global connectivity net
+ */
+type OverlappingSameNetTraceGroup = {
+    globalConnNetId: string;
+    netId?: string;
+    overlappingTraces: SolvedTracePath;
+};
+interface NetLabelPlacement {
+    globalConnNetId: string;
+    dcConnNetId?: string;
+    orientation: FacingDirection;
+    /**
+     * The anchor point is the point on the trace where the net label connects
+     */
+    anchorPoint: Point;
+    width: number;
+    height: number;
+    /**
+     * The center point is computed from the anchor point, the width and height
+     * and the orientation.
+     */
+    center: Point;
+}
+/**
+ * Places net labels in an available orientation along a trace in each group.
+ *
+ * Trace groups each receive either one net label or no net label if there
+ * isn't a netId.
+ *
+ * The specific placement of the net label is solved for using the
+ */
+declare class NetLabelPlacementSolver extends BaseSolver {
+    inputProblem: InputProblem;
+    inputTraceMap: Record<MspConnectionPairId, SolvedTracePath>;
+    overlappingSameNetTraceGroups: Array<OverlappingSameNetTraceGroup>;
+    queuedOverlappingSameNetTraceGroups: Array<OverlappingSameNetTraceGroup>;
+    activeSubSolver: SingleNetLabelPlacementSolver | null;
+    netLabelPlacements: Array<NetLabelPlacement>;
+    constructor(params: {
+        inputProblem: InputProblem;
+        inputTraceMap: Record<MspConnectionPairId, SolvedTracePath>;
+    });
+    computeOverlappingSameNetTraceGroups(): Array<OverlappingSameNetTraceGroup>;
+    _step(): void;
+    visualize(): GraphicsObject;
+}
+
+/**
+ * Pipeline solver that runs a series of solvers to find the best schematic layout.
+ * Coordinates the entire layout process from chip partitioning through final packing.
+ */
+
+type PipelineStep<T extends new (...args: any[]) => BaseSolver> = {
+    solverName: string;
+    solverClass: T;
+    getConstructorParams: (instance: SchematicTracePipelineSolver) => ConstructorParameters<T>;
+    onSolved?: (instance: SchematicTracePipelineSolver) => void;
+};
+declare class SchematicTracePipelineSolver extends BaseSolver {
+    mspConnectionPairSolver?: MspConnectionPairSolver;
+    guidelinesSolver?: GuidelinesSolver;
+    schematicTraceLinesSolver?: SchematicTraceLinesSolver;
+    traceOverlapShiftSolver?: TraceOverlapShiftSolver;
+    netLabelPlacementSolver?: NetLabelPlacementSolver;
+    startTimeOfPhase: Record<string, number>;
+    endTimeOfPhase: Record<string, number>;
+    timeSpentOnPhase: Record<string, number>;
+    firstIterationOfPhase: Record<string, number>;
+    inputProblem: InputProblem;
+    pipelineDef: (PipelineStep<typeof MspConnectionPairSolver> | PipelineStep<typeof GuidelinesSolver> | PipelineStep<typeof SchematicTraceLinesSolver> | PipelineStep<typeof TraceOverlapShiftSolver> | PipelineStep<typeof NetLabelPlacementSolver>)[];
+    constructor(inputProblem: InputProblem);
+    currentPipelineStepIndex: number;
+    _step(): void;
+    solveUntilPhase(phase: string): void;
+    getCurrentPhase(): string;
+    visualize(): GraphicsObject;
+    /**
+     * A lightweight version of the visualize method that can be used to stream
+     * progress
+     */
+    preview(): GraphicsObject;
+}
+
+export { type ChipId, type InputChip, type InputDirectConnection, type InputNetConnection, type InputPin, type InputProblem, type NetId, type PinId, SchematicTracePipelineSolver };