@tscircuit/fanout-solver 0.0.17 → 0.0.19

package/lib/route-bus.ts

@@ -11,6 +11,10 @@ import {
   segmentsAreClear,
 } from "./geometry"
 import { getLayerSpan } from "./layer-names"
+import {
+  connectionsShareElectricalNet,
+  obstacleSharesElectricalNet,
+} from "./net-identity"
 import type {
   Bounds,
   FanoutDirection,
@@ -21,7 +25,9 @@ import type {
   RoutedSegment,
 } from "./types"
 
-interface RouteBusParams {
+export type RouteBusStaticClearanceCache = Map<string, boolean>
+
+export interface RouteBusParams {
   srj: SimpleRouteJson
   bus: PreparedBus
   targetLayer: string
@@ -32,6 +38,9 @@ interface RouteBusParams {
   viaHoleDiameter: number
   clearance: number
   compactBusTracks: boolean
+  allowSameNetMerges?: boolean
+  staticClearanceCache?: RouteBusStaticClearanceCache
+  blockingBusCounts?: Map<string, number>
 }
 
 interface TrackCandidate {
@@ -658,13 +667,29 @@ function segmentIsClearOfObstacles(params: {
   segment: RoutedSegment
   plan: FanoutRoutePlan
   segmentIndex: number
+  srj: SimpleRouteJson
+  allowSameNetMerges: boolean
   obstacles: Obstacle[]
   clearance: number
 }): boolean {
-  const { segment, plan, segmentIndex, obstacles, clearance } = params
+  const {
+    segment,
+    plan,
+    segmentIndex,
+    srj,
+    allowSameNetMerges,
+    obstacles,
+    clearance,
+  } = params
   for (const obstacle of obstacles) {
     if (!obstacle.layers.includes(segment.layer)) continue
     if (obstacle.connectedTo.includes(plan.connectionName)) continue
+    if (
+      allowSameNetMerges &&
+      obstacleSharesElectricalNet(srj, obstacle, plan.connectionName)
+    ) {
+      continue
+    }
     if (
       segmentIndex === 0 &&
       obstacle === plan.sourceObstacle &&
@@ -682,14 +707,14 @@ function segmentIsClearOfObstacles(params: {
   return true
 }
 
-function planIsClear(params: {
+function planIsStaticallyClear(params: {
   plan: FanoutRoutePlan
-  otherPlans: FanoutRoutePlan[]
   srj: SimpleRouteJson
   sharedBoundary: Bounds
   clearance: number
+  allowSameNetMerges: boolean
 }): boolean {
-  const { plan, otherPlans, srj, sharedBoundary, clearance } = params
+  const { plan, srj, sharedBoundary, clearance, allowSameNetMerges } = params
   const routableBounds = getRoutableBounds(srj.bounds, sharedBoundary)
   if (
     !pointIsInsideBounds(plan.exitPoint, routableBounds) ||
@@ -707,6 +732,8 @@ function planIsClear(params: {
         segment: plan.segments[index]!,
         plan,
         segmentIndex: index,
+        srj,
+        allowSameNetMerges,
         obstacles: srj.obstacles,
         clearance,
       })
@@ -721,6 +748,12 @@ function planIsClear(params: {
       ) {
         continue
       }
+      if (
+        allowSameNetMerges &&
+        obstacleSharesElectricalNet(srj, obstacle, plan.connectionName)
+      ) {
+        continue
+      }
       if (
         distancePointToObstacle(plan.via.center, obstacle) <
         plan.via.diameter / 2 + clearance - 1e-9
@@ -730,10 +763,55 @@ function planIsClear(params: {
     }
   }
 
+  return true
+}
+
+function planIsClearOfPlans(params: {
+  plan: FanoutRoutePlan
+  otherPlans: FanoutRoutePlan[]
+  srj: SimpleRouteJson
+  allowSameNetMerges: boolean
+  clearance: number
+  blockingBusCounts?: Map<string, number>
+}): boolean {
+  const {
+    plan,
+    otherPlans,
+    srj,
+    allowSameNetMerges,
+    clearance,
+    blockingBusCounts,
+  } = params
   for (const otherPlan of otherPlans) {
+    if (
+      allowSameNetMerges &&
+      connectionsShareElectricalNet(
+        srj,
+        plan.connectionName,
+        otherPlan.connectionName,
+      )
+    ) {
+      continue
+    }
+    const plansShareSourcePort =
+      (plan.sourcePoint.pcb_port_id &&
+        plan.sourcePoint.pcb_port_id === otherPlan.sourcePoint.pcb_port_id) ||
+      (plan.sourcePoint.pointId &&
+        plan.sourcePoint.pointId === otherPlan.sourcePoint.pointId)
+    if (plansShareSourcePort) continue
+    const recordBlocker = (): void => {
+      if (otherPlan.busId === plan.busId) return
+      blockingBusCounts?.set(
+        otherPlan.busId,
+        (blockingBusCounts.get(otherPlan.busId) ?? 0) + 1,
+      )
+    }
     for (const segment of plan.segments) {
       for (const otherSegment of otherPlan.segments) {
-        if (!segmentsAreClear(segment, otherSegment, clearance)) return false
+        if (!segmentsAreClear(segment, otherSegment, clearance)) {
+          recordBlocker()
+          return false
+        }
       }
       if (
         otherPlan.via?.spanLayers.includes(segment.layer) &&
@@ -744,6 +822,7 @@ function planIsClear(params: {
         ) <
           otherPlan.via.diameter / 2 + segment.width / 2 + clearance - 1e-9
       ) {
+        recordBlocker()
         return false
       }
     }
@@ -758,6 +837,7 @@ function planIsClear(params: {
           ) <
             plan.via.diameter / 2 + otherSegment.width / 2 + clearance - 1e-9
         ) {
+          recordBlocker()
           return false
         }
       }
@@ -769,6 +849,7 @@ function planIsClear(params: {
         distance(plan.via.center, otherPlan.via.center) <
           (plan.via.diameter + otherPlan.via.diameter) / 2 + clearance - 1e-9
       ) {
+        recordBlocker()
         return false
       }
     }
@@ -776,6 +857,99 @@ function planIsClear(params: {
   return true
 }
 
+function planIsClear(params: {
+  plan: FanoutRoutePlan
+  otherPlans: FanoutRoutePlan[]
+  staticClearanceCache?: RouteBusStaticClearanceCache
+  blockingBusCounts?: Map<string, number>
+  cacheKey: string
+  srj: SimpleRouteJson
+  sharedBoundary: Bounds
+  clearance: number
+  allowSameNetMerges: boolean
+}): boolean {
+  const {
+    plan,
+    otherPlans,
+    staticClearanceCache,
+    blockingBusCounts,
+    cacheKey,
+    srj,
+    sharedBoundary,
+    clearance,
+    allowSameNetMerges,
+  } = params
+  let staticallyClear = staticClearanceCache?.get(cacheKey)
+  if (staticallyClear === undefined) {
+    staticallyClear = planIsStaticallyClear({
+      plan,
+      srj,
+      sharedBoundary,
+      clearance,
+      allowSameNetMerges,
+    })
+    staticClearanceCache?.set(cacheKey, staticallyClear)
+  }
+  return (
+    staticallyClear &&
+    planIsClearOfPlans({
+      plan,
+      otherPlans,
+      srj,
+      allowSameNetMerges,
+      clearance,
+      blockingBusCounts,
+    })
+  )
+}
+
+/**
+ * Validate a complete set of fanout plans against the source SRJ and against
+ * one another. This is intentionally separate from route search so every
+ * route-producing strategy can share the same final safety invariant.
+ */
+export function fanoutPlansAreClear(params: {
+  plans: readonly FanoutRoutePlan[]
+  srj: SimpleRouteJson
+  sharedBoundary: Bounds
+  clearance: number
+  allowSameNetMerges?: boolean
+}): boolean {
+  const {
+    plans,
+    srj,
+    sharedBoundary,
+    clearance,
+    allowSameNetMerges = false,
+  } = params
+  for (let index = 0; index < plans.length; index++) {
+    const plan = plans[index]!
+    if (
+      !planIsStaticallyClear({
+        plan,
+        srj,
+        sharedBoundary,
+        clearance,
+        allowSameNetMerges,
+      })
+    ) {
+      return false
+    }
+    if (
+      !planIsClearOfPlans({
+        plan,
+        otherPlans: plans.filter((_, otherIndex) => otherIndex !== index),
+        srj,
+        allowSameNetMerges,
+        clearance,
+      })
+    ) {
+      return false
+    }
+  }
+  return true
+}
+
 function routePlaneTerminatedBus(
   params: RouteBusParams,
 ): FanoutRoutePlan[] | null {
@@ -789,6 +963,9 @@ function routePlaneTerminatedBus(
     viaDiameter,
     viaHoleDiameter,
     clearance,
+    staticClearanceCache,
+    blockingBusCounts,
+    allowSameNetMerges = false,
   } = params
   const sourceObstacle = bus.connections[0]?.sourceObstacle
   if (!sourceObstacle || bus.termination.type !== "plane") return null
@@ -833,9 +1010,13 @@ function routePlaneTerminatedBus(
           !planIsClear({
             plan,
             otherPlans: [...acceptedPlans, ...candidatePlans],
+            staticClearanceCache,
+            blockingBusCounts,
+            cacheKey: `plane:${bus.busId}:${targetLayer}:${preparedConnection.connectionIndex}:${viaHandedness}`,
             srj,
             sharedBoundary: bus.sharedBoundary,
             clearance,
+            allowSameNetMerges,
           })
         ) {
           orderIsClear = false
@@ -850,7 +1031,10 @@ function routePlaneTerminatedBus(
   return null
 }
 
-export function routeBus(params: RouteBusParams): FanoutRoutePlan[] | null {
+export function routeBusAlternatives(
+  params: RouteBusParams,
+  maxAlternatives = 1,
+): FanoutRoutePlan[][] {
   const {
     srj,
     bus,
@@ -862,13 +1046,22 @@ export function routeBus(params: RouteBusParams): FanoutRoutePlan[] | null {
     viaHoleDiameter,
     clearance,
     compactBusTracks,
+    staticClearanceCache,
+    blockingBusCounts,
+    allowSameNetMerges = false,
   } = params
+  if (!Number.isInteger(maxAlternatives) || maxAlternatives < 1) {
+    throw new Error(
+      `FanoutSolver: maxAlternatives must be a positive integer, received ${maxAlternatives}`,
+    )
+  }
   if (bus.termination.type === "plane") {
-    return routePlaneTerminatedBus(params)
+    const plan = routePlaneTerminatedBus(params)
+    return plan ? [plan] : []
   }
   const exitAxis = getExitAxis(bus)
   const sourceObstacle = bus.connections[0]?.sourceObstacle
-  if (!sourceObstacle) return []
+  if (!sourceObstacle) return [[]]
   const directionalPadSize = isHorizontal(bus.direction)
     ? sourceObstacle.width
     : sourceObstacle.height
@@ -886,71 +1079,112 @@ export function routeBus(params: RouteBusParams): FanoutRoutePlan[] | null {
       : [1, -1]
     : [0]
 
-  for (const viaHandedness of viaHandednesses) {
-    for (const connectionOrder of getConnectionOrders(bus)) {
-      const candidatePlans: FanoutRoutePlan[] = []
-      let orderIsClear = true
-      for (const preparedConnection of connectionOrder) {
-        let acceptedPlan: FanoutRoutePlan | null = null
-        for (const track of getTrackCandidates({
-          bus,
-          connection: preparedConnection,
-          preferredTrack: getPreferredTrack({
-            bus,
-            connection: preparedConnection,
-            targetUsesVia,
-            interstitialEscape,
-            compactBusTracks,
-            traceWidth,
-            viaDiameter,
-            clearance,
-          }),
-          traceWidth,
+  const alternatives: FanoutRoutePlan[][] = []
+  const seenAlternativeKeys = new Set<string>()
+
+  const addAlternative = (plans: FanoutRoutePlan[]): void => {
+    const key = plans
+      .map(
+        (plan) =>
+          `${plan.connectionIndex}:${plan.targetLayer}:${plan.exitPoint.x}:${plan.exitPoint.y}:${plan.segments.map((segment) => `${segment.start.x},${segment.start.y},${segment.end.x},${segment.end.y},${segment.layer}`).join(";")}`,
+      )
+      .join("|")
+    if (seenAlternativeKeys.has(key)) return
+    seenAlternativeKeys.add(key)
+    alternatives.push(plans)
+  }
+
+  const searchConnectionOrder = (
+    connectionOrder: PreparedConnection[],
+    viaHandedness: ViaHandedness,
+    connectionIndex: number,
+    candidatePlans: FanoutRoutePlan[],
+  ): void => {
+    if (alternatives.length >= maxAlternatives) return
+    if (connectionIndex >= connectionOrder.length) {
+      addAlternative(candidatePlans)
+      return
+    }
+
+    const preparedConnection = connectionOrder[connectionIndex]!
+    const connectionRank = getConnectionRank(bus, preparedConnection)
+    const trackCandidates = getTrackCandidates({
+      bus,
+      connection: preparedConnection,
+      preferredTrack: getPreferredTrack({
+        bus,
+        connection: preparedConnection,
+        targetUsesVia,
+        interstitialEscape,
+        compactBusTracks,
+        traceWidth,
+        viaDiameter,
+        clearance,
+      }),
+      traceWidth,
+      clearance,
+    })
+    for (
+      let trackIndex = 0;
+      trackIndex < trackCandidates.length;
+      trackIndex++
+    ) {
+      const track = trackCandidates[trackIndex]!
+      const plan = buildPlan({
+        preparedConnection,
+        bus,
+        targetLayer,
+        track: track.value,
+        exitAxis,
+        layerNames,
+        traceWidth,
+        viaDiameter,
+        viaHoleDiameter,
+        viaHandedness,
+        interstitialEscape,
+        spreadLaneIndex: Math.min(
+          connectionRank,
+          bus.connections.length - connectionRank - 1,
+        ),
+        clearance,
+        terminateAtVia: false,
+      })
+      if (
+        !planIsClear({
+          plan,
+          otherPlans: [...acceptedPlans, ...candidatePlans],
+          staticClearanceCache,
+          blockingBusCounts,
+          cacheKey: `boundary:${bus.busId}:${targetLayer}:${preparedConnection.connectionIndex}:${viaHandedness}:${trackIndex}`,
+          srj,
+          sharedBoundary: bus.sharedBoundary,
           clearance,
-        })) {
-          const plan = buildPlan({
-            preparedConnection,
-            bus,
-            targetLayer,
-            track: track.value,
-            exitAxis,
-            layerNames,
-            traceWidth,
-            viaDiameter,
-            viaHoleDiameter,
-            viaHandedness,
-            interstitialEscape,
-            spreadLaneIndex: Math.min(
-              getConnectionRank(bus, preparedConnection),
-              bus.connections.length -
-                getConnectionRank(bus, preparedConnection) -
-                1,
-            ),
-            clearance,
-            terminateAtVia: false,
-          })
-          if (
-            planIsClear({
-              plan,
-              otherPlans: [...acceptedPlans, ...candidatePlans],
-              srj,
-              sharedBoundary: bus.sharedBoundary,
-              clearance,
-            })
-          ) {
-            acceptedPlan = plan
-            break
-          }
-        }
-        if (!acceptedPlan) {
-          orderIsClear = false
-          break
-        }
-        candidatePlans.push(acceptedPlan)
+          allowSameNetMerges,
+        })
+      ) {
+        continue
       }
-      if (orderIsClear) return candidatePlans
+      searchConnectionOrder(
+        connectionOrder,
+        viaHandedness,
+        connectionIndex + 1,
+        [...candidatePlans, plan],
+      )
+      if (alternatives.length >= maxAlternatives) return
+      if (maxAlternatives === 1) return
     }
   }
 
-  return null
+  for (const viaHandedness of viaHandednesses) {
+    for (const connectionOrder of getConnectionOrders(bus)) {
+      searchConnectionOrder(connectionOrder, viaHandedness, 0, [])
+      if (alternatives.length >= maxAlternatives) return alternatives
+    }
+  }
+
+  return alternatives
+}
+
+export function routeBus(params: RouteBusParams): FanoutRoutePlan[] | null {
+  return routeBusAlternatives(params, 1)[0] ?? null
 }

package/lib/types.ts

@@ -98,6 +98,8 @@ export interface FanoutSolverOptions {
   viaHoleDiameter?: number
   clearance?: number
   compactBusTracks?: boolean
+  /** Allow branches belonging to the same electrical net to share copper. */
+  allowSameNetMerges?: boolean
   singleLayerPushAndShove?: boolean
   /**
    * When preferred single-layer exits cannot coexist, allow a global
@@ -115,6 +117,7 @@ export interface FanoutAttemptSummary {
   routedConnectionCount: number
   failedBusIds: string[]
   score: number
+  validationIssues?: FanoutValidationIssue[]
 }
 
 export interface FanoutSolverOutput {
@@ -124,6 +127,42 @@ export interface FanoutSolverOutput {
   busLayerAssignments: Readonly<Record<string, string>>
   busDirections: Readonly<Record<string, FanoutDirection>>
   attempts: FanoutAttemptSummary[]
+  validation: FanoutValidationReport
+}
+
+export interface FanoutValidationIssue {
+  code:
+    | "missing-plan"
+    | "duplicate-plan"
+    | "unknown-plan"
+    | "connection-mismatch"
+    | "source-mismatch"
+    | "termination-mismatch"
+    | "not-broken-out"
+    | "outside-routing-bounds"
+    | "disconnected-trace"
+    | "unsupported-route-point"
+    | "trace-plan-mismatch"
+    | "output-connection-missing"
+    | "output-exit-mismatch"
+    | "downstream-endpoint-lost"
+    | "plane-connection-retained"
+    | "obstacle-clearance"
+    | "via-obstacle-clearance"
+    | "different-net-trace-clearance"
+    | "different-net-trace-via-clearance"
+    | "different-net-via-clearance"
+  message: string
+  connectionName?: string
+  otherConnectionName?: string
+  busId?: string
+}
+
+export interface FanoutValidationReport {
+  valid: boolean
+  checkedConnectionCount: number
+  brokenOutConnectionCount: number
+  issues: FanoutValidationIssue[]
 }
 
 export interface Point2D {