@tscircuit/schematic-trace-solver 0.0.1

package/lib/solvers/TraceOverlapShiftSolver/TraceOverlapIssueSolver/TraceOverlapIssueSolver.ts

@@ -0,0 +1,180 @@
+import type { GraphicsObject } from "graphics-debug"
+import { BaseSolver } from "lib/solvers/BaseSolver/BaseSolver"
+import type { MspConnectionPairId } from "lib/solvers/MspConnectionPairSolver/MspConnectionPairSolver"
+import type { SolvedTracePath } from "lib/solvers/SchematicTraceLinesSolver/SchematicTraceLinesSolver"
+
+type ConnNetId = string
+
+export interface OverlappingTraceSegmentLocator {
+  connNetId: string
+  pathsWithOverlap: Array<{
+    solvedTracePathIndex: number
+    traceSegmentIndex: number
+  }>
+}
+
+export class TraceOverlapIssueSolver extends BaseSolver {
+  overlappingTraceSegments: OverlappingTraceSegmentLocator[]
+  traceNetIslands: Record<ConnNetId, Array<SolvedTracePath>>
+
+  SHIFT_DISTANCE = 0.1
+
+  correctedTraceMap: Record<MspConnectionPairId, SolvedTracePath> = {}
+
+  constructor(params: {
+    overlappingTraceSegments: OverlappingTraceSegmentLocator[]
+    traceNetIslands: Record<ConnNetId, Array<SolvedTracePath>>
+  }) {
+    super()
+    this.overlappingTraceSegments = params.overlappingTraceSegments
+    this.traceNetIslands = params.traceNetIslands
+
+    // Only add the relevant traces to the correctedTraceMap
+    for (const { connNetId, pathsWithOverlap } of this
+      .overlappingTraceSegments) {
+      for (const {
+        solvedTracePathIndex,
+        traceSegmentIndex,
+      } of pathsWithOverlap) {
+        const mspPairId =
+          this.traceNetIslands[connNetId][solvedTracePathIndex].mspPairId
+        this.correctedTraceMap[mspPairId] =
+          this.traceNetIslands[connNetId][solvedTracePathIndex]
+      }
+    }
+  }
+
+  override _step() {
+    // Shift only the overlapping segments, and move the shared endpoints
+    // (the last point of the previous segment and the first point of the next
+    // segment) so the polyline remains orthogonal without self-overlap.
+    const EPS = 1e-6
+
+    // Compute offsets for each island involved: alternate directions
+    const offsets = this.overlappingTraceSegments.map((_, idx) => {
+      const n = Math.floor(idx / 2) + 1
+      const signed = idx % 2 === 0 ? -n : n
+      return signed * this.SHIFT_DISTANCE
+    })
+
+    const eq = (a: number, b: number) => Math.abs(a - b) < EPS
+    const samePoint = (
+      p: { x: number; y: number } | undefined,
+      q: { x: number; y: number } | undefined,
+    ) => !!p && !!q && eq(p.x, q.x) && eq(p.y, q.y)
+
+    // For each net island group, shift only its overlapping segments and adjust adjacent joints
+    this.overlappingTraceSegments.forEach((group, gidx) => {
+      const offset = offsets[gidx]!
+
+      // Gather unique segment indices per path
+      const byPath: Map<number, Set<number>> = new Map()
+      for (const loc of group.pathsWithOverlap) {
+        if (!byPath.has(loc.solvedTracePathIndex)) {
+          byPath.set(loc.solvedTracePathIndex, new Set())
+        }
+        byPath.get(loc.solvedTracePathIndex)!.add(loc.traceSegmentIndex)
+      }
+
+      for (const [pathIdx, segIdxSet] of byPath) {
+        const original = this.traceNetIslands[group.connNetId][pathIdx]!
+        const current = this.correctedTraceMap[original.mspPairId] ?? original
+        const pts = current.tracePath.map((p) => ({ ...p }))
+
+        const segIdxs = Array.from(segIdxSet).sort((a, b) => a - b)
+
+        // Track per-point adjustments to avoid double-shifting shared joints
+        const appliedX = new Set<number>()
+        const appliedY = new Set<number>()
+
+        for (const si of segIdxs) {
+          if (si < 0 || si >= pts.length - 1) continue
+          const start = pts[si]!
+          const end = pts[si + 1]!
+          const isVertical = Math.abs(start.x - end.x) < EPS
+          const isHorizontal = Math.abs(start.y - end.y) < EPS
+
+          if (!isVertical && !isHorizontal) continue
+
+          if (isVertical) {
+            if (!appliedX.has(si)) {
+              start.x += offset
+              appliedX.add(si)
+            }
+            if (!appliedX.has(si + 1)) {
+              end.x += offset
+              appliedX.add(si + 1)
+            }
+          } else if (isHorizontal) {
+            if (!appliedY.has(si)) {
+              start.y += offset
+              appliedY.add(si)
+            }
+            if (!appliedY.has(si + 1)) {
+              end.y += offset
+              appliedY.add(si + 1)
+            }
+          }
+        }
+
+        // Remove consecutive duplicate points that might appear after shifts
+        const cleaned: typeof pts = []
+        for (const p of pts) {
+          if (
+            cleaned.length === 0 ||
+            !samePoint(cleaned[cleaned.length - 1], p)
+          ) {
+            cleaned.push(p)
+          }
+        }
+
+        this.correctedTraceMap[original.mspPairId] = {
+          ...current,
+          tracePath: cleaned,
+        }
+      }
+    })
+
+    this.solved = true
+  }
+
+  override visualize(): GraphicsObject {
+    // Visualize overlapped segments and proposed corrections
+    const graphics: GraphicsObject = {
+      lines: [],
+      points: [],
+      rects: [],
+      circles: [],
+    }
+
+    // Draw overlapped segments in red
+    for (const group of this.overlappingTraceSegments) {
+      for (const {
+        solvedTracePathIndex,
+        traceSegmentIndex,
+      } of group.pathsWithOverlap) {
+        const path =
+          this.traceNetIslands[group.connNetId][solvedTracePathIndex]!
+        const segStart = path.tracePath[traceSegmentIndex]!
+        const segEnd = path.tracePath[traceSegmentIndex + 1]!
+        graphics.lines!.push({
+          points: [segStart, segEnd],
+          strokeColor: "red",
+          strokeWidth: 0.006,
+        })
+      }
+    }
+
+    // Draw corrected traces (post-shift) in blue dashed
+    for (const trace of Object.values(this.correctedTraceMap)) {
+      graphics.lines!.push({
+        points: trace.tracePath,
+        strokeColor: "blue",
+        strokeDash: "4 2",
+        strokeWidth: 0.004,
+      })
+    }
+
+    return graphics
+  }
+}

package/lib/solvers/TraceOverlapShiftSolver/TraceOverlapShiftSolver.ts

@@ -0,0 +1,264 @@
+import { BaseSolver } from "lib/solvers/BaseSolver/BaseSolver"
+import { visualizeInputProblem } from "../SchematicTracePipelineSolver/visualizeInputProblem"
+import type { InputProblem } from "lib/types/InputProblem"
+import type { SolvedTracePath } from "../SchematicTraceLinesSolver/SchematicTraceLinesSolver"
+import type { ConnectivityMap } from "connectivity-map"
+import {
+  TraceOverlapIssueSolver,
+  type OverlappingTraceSegmentLocator,
+} from "./TraceOverlapIssueSolver/TraceOverlapIssueSolver"
+import type { MspConnectionPairId } from "../MspConnectionPairSolver/MspConnectionPairSolver"
+
+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.
+ */
+export class TraceOverlapShiftSolver extends BaseSolver {
+  inputProblem: InputProblem
+  inputTracePaths: Array<SolvedTracePath>
+  globalConnMap: ConnectivityMap
+
+  declare 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
+  }) {
+    super()
+    this.inputProblem = params.inputProblem
+    this.inputTracePaths = params.inputTracePaths
+    this.globalConnMap = params.globalConnMap
+
+    for (const tracePath of this.inputTracePaths) {
+      const { mspPairId } = tracePath
+      this.correctedTraceMap[mspPairId] = tracePath
+    }
+
+    this.traceNetIslands = this.computeTraceNetIslands()
+  }
+
+  override getConstructorParams(): ConstructorParameters<
+    typeof TraceOverlapShiftSolver
+  >[0] {
+    return {
+      inputProblem: this.inputProblem,
+      inputTracePaths: this.inputTracePaths,
+      globalConnMap: this.globalConnMap,
+    }
+  }
+
+  computeTraceNetIslands(): Record<ConnNetId, Array<SolvedTracePath>> {
+    // Build islands keyed by global connection net id.
+    // Preserve stable order by iterating original inputTracePaths array.
+    const islands: Record<ConnNetId, Array<SolvedTracePath>> = {}
+
+    for (const original of this.inputTracePaths) {
+      const path = this.correctedTraceMap[original.mspPairId] ?? original
+      const key: ConnNetId = path.globalConnNetId
+      if (!islands[key]) islands[key] = []
+      islands[key].push(path)
+    }
+
+    return islands
+  }
+
+  findNextOverlapIssue(): {
+    overlappingTraceSegments: Array<OverlappingTraceSegmentLocator>
+  } | null {
+    // Detect the next set of overlapping segments between two different net islands.
+    const EPS = 1e-6
+
+    const netIds = Object.keys(this.traceNetIslands)
+    // Compare each pair of different nets
+    for (let i = 0; i < netIds.length; i++) {
+      for (let j = i + 1; j < netIds.length; j++) {
+        const netA = netIds[i]!
+        const netB = netIds[j]!
+        const pathsA = this.traceNetIslands[netA] || []
+        const pathsB = this.traceNetIslands[netB] || []
+
+        // Collect overlaps for this pair
+        const overlapsA: Array<{
+          solvedTracePathIndex: number
+          traceSegmentIndex: number
+        }> = []
+        const overlapsB: Array<{
+          solvedTracePathIndex: number
+          traceSegmentIndex: number
+        }> = []
+
+        // Track to avoid duplicates
+        const seenA = new Set<string>()
+        const seenB = new Set<string>()
+
+        const overlaps1D = (
+          a1: number,
+          a2: number,
+          b1: number,
+          b2: number,
+        ): boolean => {
+          const minA = Math.min(a1, a2)
+          const maxA = Math.max(a1, a2)
+          const minB = Math.min(b1, b2)
+          const maxB = Math.max(b1, b2)
+          const overlap = Math.min(maxA, maxB) - Math.max(minA, minB)
+          return overlap > EPS
+        }
+
+        for (let pa = 0; pa < pathsA.length; pa++) {
+          const pathA = pathsA[pa]!
+          const ptsA = pathA.tracePath
+          for (let sa = 0; sa < ptsA.length - 1; sa++) {
+            const a1 = ptsA[sa]!
+            const a2 = ptsA[sa + 1]!
+            const aVert = Math.abs(a1.x - a2.x) < EPS
+            const aHorz = Math.abs(a1.y - a2.y) < EPS
+            if (!aVert && !aHorz) continue
+
+            for (let pb = 0; pb < pathsB.length; pb++) {
+              const pathB = pathsB[pb]!
+              const ptsB = pathB.tracePath
+              for (let sb = 0; sb < ptsB.length - 1; sb++) {
+                const b1 = ptsB[sb]!
+                const b2 = ptsB[sb + 1]!
+                const bVert = Math.abs(b1.x - b2.x) < EPS
+                const bHorz = Math.abs(b1.y - b2.y) < EPS
+                if (!bVert && !bHorz) continue
+
+                // Only consider colinear, parallel orientation overlaps
+                if (aVert && bVert) {
+                  if (Math.abs(a1.x - b1.x) < EPS) {
+                    if (overlaps1D(a1.y, a2.y, b1.y, b2.y)) {
+                      const keyA = `${pa}:${sa}`
+                      const keyB = `${pb}:${sb}`
+                      if (!seenA.has(keyA)) {
+                        overlapsA.push({
+                          solvedTracePathIndex: pa,
+                          traceSegmentIndex: sa,
+                        })
+                        seenA.add(keyA)
+                      }
+                      if (!seenB.has(keyB)) {
+                        overlapsB.push({
+                          solvedTracePathIndex: pb,
+                          traceSegmentIndex: sb,
+                        })
+                        seenB.add(keyB)
+                      }
+                    }
+                  }
+                } else if (aHorz && bHorz) {
+                  if (Math.abs(a1.y - b1.y) < EPS) {
+                    if (overlaps1D(a1.x, a2.x, b1.x, b2.x)) {
+                      const keyA = `${pa}:${sa}`
+                      const keyB = `${pb}:${sb}`
+                      if (!seenA.has(keyA)) {
+                        overlapsA.push({
+                          solvedTracePathIndex: pa,
+                          traceSegmentIndex: sa,
+                        })
+                        seenA.add(keyA)
+                      }
+                      if (!seenB.has(keyB)) {
+                        overlapsB.push({
+                          solvedTracePathIndex: pb,
+                          traceSegmentIndex: sb,
+                        })
+                        seenB.add(keyB)
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+
+        if (overlapsA.length > 0 && overlapsB.length > 0) {
+          return {
+            overlappingTraceSegments: [
+              { connNetId: netA, pathsWithOverlap: overlapsA },
+              { connNetId: netB, pathsWithOverlap: overlapsB },
+            ],
+          }
+        }
+      }
+    }
+
+    return null
+  }
+
+  override _step() {
+    if (this.activeSubSolver?.solved) {
+      for (const [mspPairId, newTrace] of Object.entries(
+        this.activeSubSolver.correctedTraceMap,
+      )) {
+        this.correctedTraceMap[mspPairId] = newTrace
+      }
+      this.activeSubSolver = null
+      this.traceNetIslands = this.computeTraceNetIslands()
+    }
+
+    if (this.activeSubSolver) {
+      this.activeSubSolver.step()
+      return
+    }
+
+    // Find the next overlapping trace segment
+    const overlapIssue = this.findNextOverlapIssue()
+
+    if (overlapIssue === null) {
+      this.solved = true
+      return
+    }
+
+    const { overlappingTraceSegments } = overlapIssue
+
+    this.activeSubSolver = new TraceOverlapIssueSolver({
+      overlappingTraceSegments,
+      traceNetIslands: this.traceNetIslands,
+    })
+  }
+
+  override visualize() {
+    if (this.activeSubSolver) {
+      return this.activeSubSolver.visualize()
+    }
+
+    const graphics = visualizeInputProblem(this.inputProblem)
+
+    // Draw current corrected traces
+    for (const trace of Object.values(this.correctedTraceMap)) {
+      graphics.lines!.push({
+        points: trace.tracePath,
+        strokeColor: "purple",
+        strokeWidth: 0.005,
+      })
+    }
+
+    return graphics
+  }
+}

package/lib/types/InputProblem.ts

@@ -0,0 +1,40 @@
+import type { ChipObstacleSpatialIndex } from "lib/data-structures/ChipObstacleSpatialIndex"
+import type { FacingDirection } from "lib/utils/dir"
+
+export type ChipId = string
+export type PinId = string
+export type NetId = string
+
+export interface InputPin {
+  pinId: PinId
+  x: number
+  y: number
+
+  _facingDirection?: "x+" | "x-" | "y+" | "y-"
+}
+export interface InputChip {
+  chipId: ChipId
+  center: { x: number; y: number }
+  width: number
+  height: number
+  pins: Array<InputPin>
+}
+export interface InputDirectConnection {
+  pinIds: [PinId, PinId]
+  netId?: string
+}
+
+export interface InputNetConnection {
+  netId: string
+  pinIds: Array<PinId>
+}
+
+export interface InputProblem {
+  chips: Array<InputChip>
+  directConnections: Array<InputDirectConnection>
+  netConnections: Array<InputNetConnection>
+
+  availableNetLabelOrientations: Record<NetId, FacingDirection[]>
+
+  _chipObstacleSpatialIndex?: ChipObstacleSpatialIndex
+}

package/lib/utils/dir.ts

@@ -0,0 +1,16 @@
+export type FacingDirection = "x+" | "x-" | "y+" | "y-"
+export const dir = (
+  facingDirection: FacingDirection,
+): { x: number; y: number } => {
+  switch (facingDirection) {
+    case "x+":
+      return { x: 1, y: 0 }
+    case "x-":
+      return { x: -1, y: 0 }
+    case "y+":
+      return { x: 0, y: 1 }
+    case "y-":
+      return { x: 0, y: -1 }
+  }
+  throw new Error(`Invalid facing direction: ${facingDirection}`)
+}

package/lib/utils/getAllPossibleOrderingsGenerator.ts

@@ -0,0 +1,47 @@
+/**
+ * Lazily generates **all permutations** (orderings) of the given array.
+ *
+ * This is a generator: it yields one permutation at a time without allocating
+ * the full result set up front, which is helpful because there are `n!`
+ * permutations for `n` items.
+ *
+ * - The input array is **not mutated**.
+ * - If `items` contains duplicates, duplicate permutations will be yielded.
+ * - For an empty array, it yields a single empty permutation `[]`.
+ *
+ * @typeParam T - Element type.
+ * @param items - The array whose permutations to generate.
+ * @yields A new array representing one permutation of `items`.
+ *
+ * @example
+ * for (const perm of getAllPossibleOrderingsGenerator([1, 2, 3])) {
+ *   console.log(perm);
+ *   // -> [1, 2, 3]
+ *   // -> [1, 3, 2]
+ *   // -> [2, 1, 3]
+ *   // -> [2, 3, 1]
+ *   // -> [3, 1, 2]
+ *   // -> [3, 2, 1]
+ * }
+ *
+ * @remarks
+ * Complexity:
+ * - Time: Θ(n!) permutations, each of length n.
+ * - Additional space: O(n) for recursion + the arrays yielded.
+ */
+export function* getAllPossibleOrderingsGenerator<T>(
+  items: T[],
+): Generator<T[], void, void> {
+  if (items.length === 0) {
+    yield []
+    return
+  }
+
+  for (let i = 0; i < items.length; i++) {
+    const head = items[i]
+    const rest = items.slice(0, i).concat(items.slice(i + 1))
+    for (const tail of getAllPossibleOrderingsGenerator(rest)) {
+      yield [head, ...tail]
+    }
+  }
+}

package/lib/utils/getColorFromString.ts

@@ -0,0 +1,7 @@
+export const getColorFromString = (string: string, alpha = 1) => {
+  // pseudo random number from string
+  const hash = string.split("").reduce((acc, char) => {
+    return acc * 31 + char.charCodeAt(0)
+  }, 0)
+  return `hsl(${hash % 360}, 100%, 50%, ${alpha})`
+}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@tscircuit/schematic-trace-solver",
+  "main": "dist/index.js",
+  "version": "0.0.1",
+  "type": "module",
+  "scripts": {
+    "start": "cosmos",
+    "build": "tsup lib/index.ts --format esm --dts",
+    "format": "biome format --write ."
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.2.2",
+    "@tscircuit/math-utils": "^0.0.19",
+    "@types/bun": "latest",
+    "calculate-elbow": "^0.0.10",
+    "connectivity-map": "^1.0.0",
+    "flatbush": "^4.5.0",
+    "graphics-debug": "^0.0.62",
+    "react-cosmos": "^7.0.0",
+    "react-cosmos-plugin-vite": "^7.0.0",
+    "tsup": "^8.5.0",
+    "vite": "^7.1.3",
+    "@react-hook/resize-observer": "^2.0.2"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "dependencies": {}
+}

package/site/components/PipelineDebugger.tsx

@@ -0,0 +1,29 @@
+import { SchematicTracePipelineSolver } from "lib/solvers/SchematicTracePipelineSolver/SchematicTracePipelineSolver"
+import type { InputProblem } from "lib/types/InputProblem"
+import { useMemo, useReducer } from "react"
+import { InteractiveGraphics } from "graphics-debug/react"
+import { SolverToolbar } from "./SolverToolbar"
+import { PipelineStageTable } from "./PipelineStageTable"
+
+export const PipelineDebugger = ({
+  inputProblem,
+}: {
+  inputProblem: InputProblem
+}) => {
+  const [, incRenderCount] = useReducer((x) => x + 1, 0)
+  const solver = useMemo(
+    () => new SchematicTracePipelineSolver(inputProblem),
+    [],
+  )
+
+  return (
+    <div>
+      <SolverToolbar triggerRender={() => incRenderCount()} solver={solver} />
+      <InteractiveGraphics graphics={solver.visualize()} />
+      <PipelineStageTable
+        triggerRender={() => incRenderCount()}
+        pipelineSolver={solver}
+      />
+    </div>
+  )
+}