@tscircuit/matchpack 0.0.1

package/README.md

@@ -0,0 +1,24 @@
+# matchpack
+
+The goal of this module is to find the best schematic layout for a set of `SchematicChip`s and `SchematicGroups` containing
+`SchematicPins` connected to each other with `SchematicTraces`
+
+To do this, we use a series of solvers that are run in a pipeline. Each solver is responsible for a specific piece of
+input preprocessing or calculation.
+
+This is roughly the hierarchy of solvers:
+
+```
+LayoutPipelineSolver: Runs pipeline
+↳ ChipPartitionsSolver: Creates partitions (small subset groups) surrounding complex chips
+  ↳ SingleChipPartitionSolver: Creates a single partition for a single chip
+↳ PinRangeMatchSolver: Finds pin ranges on each chip in the partition, constructs a subset group with just that pin range, then matches a laid out design from the corpus
+↳ PinRangeLayoutSolver: Applies the matched layout to the pin ranges, moving passives that are connected to each pin range
+↳ PinRangeOverlapSolver: Finds overlaps between laid out boxes from each pin range and fixes them
+↳ PartitionPackingSolver: Packs the laid out chip partitions into a single layout
+```
+
+## Implementation Notes
+
+- There is the concept of a "weak" and "strong" connection between pins. A "strong" connection is one where a pin is directly assigned to another pin. A "weak" connection is generally a pin assigned to a net like "GND" or "VCC". Strong connections are important for layout but weak connections often determine orientation of passives (e.g. a capacitor is "facing up" to VCC but "facing down" to GND)
+- Often there are pre-laid-out designs that are passed in. This is represented by a `SchematicGroup`. We don't lay out anything inside of these groups but the inner pins are still used to compute a good packing

package/dist/index.d.ts

@@ -0,0 +1,315 @@
+import { GraphicsObject } from 'graphics-debug';
+import { Point, Bounds } from '@tscircuit/math-utils';
+import { PhasedPackSolver } from 'calculate-packing';
+
+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;
+}
+
+type Side = "x-" | "x+" | "y-" | "y+";
+
+type PinId = string;
+type ChipId = string;
+type GroupId = string;
+type NetId = string;
+type ChipPin = {
+    pinId: PinId;
+    offset: Point;
+    side: Side;
+};
+type Chip = {
+    chipId: ChipId;
+    pins: PinId[];
+    size: Point;
+};
+type Group = {
+    groupId: GroupId;
+    pins: PinId[];
+    /** The shape of the group is defined by a set of bounding boxes */
+    shape: Bounds[];
+};
+type GroupPin = {
+    pinId: PinId;
+    offset: Point;
+};
+type Net = {
+    netId: NetId;
+};
+type InputProblem = {
+    chipMap: Record<ChipId, Chip>;
+    chipPinMap: Record<PinId, ChipPin>;
+    groupMap: Record<GroupId, Group>;
+    groupPinMap: Record<PinId, GroupPin>;
+    netMap: Record<NetId, Net>;
+    /** This is a two-way map */
+    pinStrongConnMap: Record<`${PinId}-${PinId}`, boolean>;
+    netConnMap: Record<`${PinId}-${NetId}`, boolean>;
+};
+
+/**
+ * Creates partitions (small subset groups) surrounding complex chips.
+ * Divides the layout problem into manageable sections for more efficient processing.
+ */
+
+declare class ChipPartitionsSolver extends BaseSolver {
+    inputProblem: InputProblem;
+    partitions: InputProblem[];
+    constructor(inputProblem: InputProblem);
+    _step(): void;
+    /**
+     * Creates partitions by finding connected components through strong pin connections
+     */
+    private createPartitions;
+    /**
+     * Finds the owner (chip or group) of a given pin
+     */
+    private findPinOwner;
+    /**
+     * Depth-first search to find connected components
+     */
+    private dfs;
+    /**
+     * Creates a new InputProblem containing only the components in the given partition
+     */
+    private createInputProblemFromPartition;
+    visualize(): GraphicsObject;
+}
+
+type Placement = Point & {
+    ccwRotationDegrees: number;
+};
+type OutputLayout = {
+    chipPlacements: Record<ChipId, Placement>;
+    groupPlacements: Record<GroupId, Placement>;
+};
+
+/**
+ * Packs the laid out chip partitions into a single layout.
+ * Combines all the individually processed partitions into the final schematic layout.
+ */
+
+type LaidOutPartition = InputProblem;
+interface PartitionPackingSolverInput {
+    resolvedLayout: OutputLayout;
+    laidOutPartitions: LaidOutPartition[];
+}
+declare class PartitionPackingSolver extends BaseSolver {
+    resolvedLayout: OutputLayout;
+    laidOutPartitions: LaidOutPartition[];
+    finalLayout: OutputLayout | null;
+    phasedPackSolver: PhasedPackSolver | null;
+    constructor(input: PartitionPackingSolverInput);
+    _step(): void;
+    private organizeComponentsByPartition;
+    private createPackInput;
+    private applyPackingResult;
+    visualize(): GraphicsObject;
+    getConstructorParams(): PartitionPackingSolverInput;
+}
+
+/**
+ * Sub-solver for processing pin ranges within a single partition
+ */
+
+type PinRange = {
+    pinIds: PinId[];
+    side: Side;
+    chipId?: ChipId;
+    groupId?: GroupId;
+    connectedPins?: PinId[];
+    connectedChips?: ChipId[];
+};
+declare class PartitionPinRangeMatchSolver extends BaseSolver {
+    inputProblem: InputProblem;
+    pinRanges: PinRange[];
+    constructor(inputProblem: InputProblem);
+    _step(): void;
+    private createPinRanges;
+    private createPinRangesForChip;
+    private createPinRangesForGroup;
+    private createPinRangesForSide;
+    private sortPinsBySide;
+    private calculateDistance;
+    private findConnectedPassives;
+    visualize(): GraphicsObject;
+    getConstructorParams(): {
+        inputProblem: InputProblem;
+    };
+}
+
+/**
+ * Solves the layout for a single pin range and its connected passive components.
+ * This solver takes a pin range and applies layout patterns to position the
+ * connected components optimally around the pin range.
+ */
+
+declare class SinglePinRangeLayoutSolver extends BaseSolver {
+    pinRange: PinRange;
+    inputProblem: InputProblem;
+    layoutApplied: boolean;
+    layout: OutputLayout | null;
+    debugPackInput: any;
+    constructor(pinRange: PinRange, inputProblem: InputProblem);
+    _step(): void;
+    /**
+     * Build a connectivity map that normalizes network IDs by finding connected components.
+     * All pins in the same connected component get the same network ID.
+     */
+    protected buildNetworkConnectivityMap(relevantPins: Set<string>): Map<string, string>;
+    protected createPinRangeLayout(): OutputLayout;
+    visualize(): GraphicsObject;
+    getConstructorParams(): {
+        pinRange: PinRange;
+        inputProblem: InputProblem;
+    };
+}
+
+/**
+ * Applies the matched layout to the pin ranges.
+ * Moves passives that are connected to each pin range according to the matched design.
+ */
+
+declare class PinRangeLayoutSolver extends BaseSolver {
+    pinRanges: PinRange[];
+    inputProblems: InputProblem[];
+    currentRangeIndex: number;
+    activeSolver: SinglePinRangeLayoutSolver | null;
+    completedSolvers: SinglePinRangeLayoutSolver[];
+    constructor(pinRanges: PinRange[], inputProblems: InputProblem[]);
+    _step(): void;
+    private findInputProblemForRange;
+    visualize(): GraphicsObject;
+    getConstructorParams(): {
+        pinRanges: PinRange[];
+        inputProblems: InputProblem[];
+    };
+}
+
+/**
+ * Finds pin ranges on each chip in the partition and matches layouts from the corpus.
+ * Creates subset groups with pin ranges and finds pre-laid-out designs that match.
+ */
+
+declare class PinRangeMatchSolver extends BaseSolver {
+    partitions: InputProblem[];
+    currentPartitionIndex: number;
+    activeSubSolver: PartitionPinRangeMatchSolver | null;
+    partitionResults: PinRange[][];
+    constructor(partitions: InputProblem[]);
+    _step(): void;
+    getAllPinRanges(): PinRange[];
+    visualize(): GraphicsObject;
+    getConstructorParams(): {
+        partitions: InputProblem[];
+    };
+}
+
+/**
+ * Finds overlaps between laid out boxes from each pin range and fixes them.
+ * Resolves spatial conflicts between different pin range layouts.
+ */
+
+declare class PinRangeOverlapSolver extends BaseSolver {
+    pinRangeLayoutSolver: PinRangeLayoutSolver | null;
+    inputProblems: InputProblem[];
+    resolvedLayout: OutputLayout | null;
+    constructor(pinRangeLayoutSolver: PinRangeLayoutSolver, inputProblems: InputProblem[]);
+    _step(): void;
+    private groupPlacementsByPartition;
+    private findPartitionIndexForSolver;
+    private resolvePartitionOverlaps;
+    private positionPartitionsHorizontally;
+    private findOverlaps;
+    private getComponentBounds;
+    private boundsOverlap;
+    private resolveOverlaps;
+    visualize(): GraphicsObject;
+    getConstructorParams(): {
+        pinRangeLayoutSolver: PinRangeLayoutSolver | null;
+        inputProblems: InputProblem[];
+    };
+}
+
+/**
+ * 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: LayoutPipelineSolver) => ConstructorParameters<T>;
+    onSolved?: (instance: LayoutPipelineSolver) => void;
+};
+declare class LayoutPipelineSolver extends BaseSolver {
+    chipPartitionsSolver?: ChipPartitionsSolver;
+    pinRangeMatchSolver?: PinRangeMatchSolver;
+    pinRangeLayoutSolver?: PinRangeLayoutSolver;
+    pinRangeOverlapSolver?: PinRangeOverlapSolver;
+    partitionPackingSolver?: PartitionPackingSolver;
+    startTimeOfPhase: Record<string, number>;
+    endTimeOfPhase: Record<string, number>;
+    timeSpentOnPhase: Record<string, number>;
+    firstIterationOfPhase: Record<string, number>;
+    inputProblem: InputProblem;
+    chipPartitions?: ChipPartitionsSolver["partitions"];
+    pinRanges?: ReturnType<PinRangeMatchSolver["getAllPinRanges"]>;
+    pipelineDef: (PipelineStep<typeof ChipPartitionsSolver> | PipelineStep<typeof PinRangeMatchSolver> | PipelineStep<typeof PinRangeLayoutSolver> | PipelineStep<typeof PinRangeOverlapSolver> | PipelineStep<typeof PartitionPackingSolver>)[];
+    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;
+    /**
+     * Checks if any chips are overlapping in the given layout, considering rotation.
+     * Returns an array of overlapping chip pairs.
+     */
+    checkForOverlaps(layout: OutputLayout): Array<{
+        chip1: string;
+        chip2: string;
+        overlapArea: number;
+    }>;
+    /**
+     * Calculate the axis-aligned bounding box for a rotated chip
+     */
+    private getRotatedBounds;
+    /**
+     * Calculate the overlap area between two axis-aligned bounding boxes
+     */
+    private calculateOverlapArea;
+    getOutputLayout(): OutputLayout;
+}
+
+export { type Chip, type ChipId, type ChipPin, type Group, type GroupId, type GroupPin, type InputProblem, LayoutPipelineSolver, type Net, type NetId, type OutputLayout, type PinId, type Placement };