quantcore_circuits.route.router

Route specs → KQC WaveguideComposite node lists.

Routing policy (deliberately simple and predictable, everything else is KQC):

  • A route leaves a port straight along the port’s outward direction for one turn radius (the KQC port_*_corner convention) and enters the destination port the same way.

  • Between the two stubs it follows the user nodes; without nodes it auto-routes Manhattan style (one elbow if possible, otherwise a Z through the midpoint), never doubling back on itself.

  • A route between ports that face an angle (a StarQubit pin at 72° steps, a ConcentricTransmon coupler at 60°) may run one oblique straight instead of a Manhattan stair: straight from stub to stub when the two ports face each other along one line (within a few degrees), else with one bend where the two ports’ axes meet (see _oblique()). Only where the bends fit; routes between axis-aligned ports are Manhattan as before.

  • type="meander" keeps the path and inserts a KQC Meander on one straight segment so that the total route length equals length. The correction uses KQC’s Node(length_increment=...) and is verified by building the waveguide (two-step correction like WaveguideComposite.produce_fixed_length_waveguide). A path that is already about the right length gets no meander, or its free corners’ radius trimmed, never a flattened zigzag (fix_length()).

  • airbridges="auto" puts n_bridges=-1 on every straight segment (KQC spaces them by ab_to_ab_spacing).

Attributes

Exceptions

RoutingError

Inappropriate argument value (of correct type).

Classes

RouteEnd

Resolved route end: position, direction pointing from the end into the route, termination.

RoutePlan

Functions

corner_violations(points, r[, tol, radii]) → list[tuple[int, float, float]]

Segments too short for their bends: (segment index, length, required).

fit_tapers(plan, measure) → RoutePlan

Tapers that end where the route can take them.

fix_length(plan, measure[, segment, meanders, tol, ...]) → RoutePlan

Make the built length equal plan.target_length.

kqc_nodes(nodes) → list[kqcircuits.util.node.Node]

The nodes KQC builds the route from: a node marked TAPER_END (by fit_tapers()) is moved back

max_meanders(span, r) → int

Most meander turns that stay on a straight of length span: KQC puts the first bend r after the straight's

meander_segment_index(nodes[, preferred, fixed]) → int

Index of the node ending the segment that hosts the meander (KQC puts length_* on that node).

meander_span(plan, segment) → float

Length (µm) of the straight KQC lays a meander on for the segment ending at node segment: the node-to-node

meander_turns(increment, span, r[, meanders]) → int

The turn count for a length-fixing meander of increment on a straight of span: meanders as given

meander_width(increment, r, meanders) → float

Total width (µm) of the KQC Meander that adds increment with meanders turns of radius r (the

merge_collinear(points[, angle_tol]) → list[kqcircuits.pya_resolver.pya.DPoint]

Drop interior points where the polyline goes straight on (no bend there): a straight leg split into pieces

plan_route(name, route, start, end, defaults) → RoutePlan

Build the node list for one route. defaults supplies a, b, r when neither route nor port does.

trim_corners(plan, increment, measure[, tol]) → RoutePlan | None

plan lengthened by increment without a meander: the free corners (_free_corners()) get a slightly

with_length_increment(plan, increment, segment[, ...]) → RoutePlan

plan with a meander of increment extra length on segment; direction (1 / −1) picks the side of

Module Contents

exception quantcore_circuits.route.router.RoutingError

Bases: ValueError

Inappropriate argument value (of correct type).

class quantcore_circuits.route.router.RouteEnd

Resolved route end: position, direction pointing from the end into the route, termination.

For a port this is the port’s outward direction (corner - port). A free end uses the same convention, so it behaves like a virtual port.

classmethod from_free(end: quantcore_circuits.design.schema.FreeEnd) → RouteEnd
classmethod from_port(port: quantcore_circuits.layouts.ports.Port) → RouteEnd
a: float | None = None
approach: list = []
b: float | None = None
dir: kqcircuits.pya_resolver.pya.DVector | None
pos: kqcircuits.pya_resolver.pya.DPoint
term: float | None = None
class quantcore_circuits.route.router.RoutePlan
node_strings() → list[str]

The KQC nodes the route cell is built from (kqc_nodes(): a taper that ends at its waypoint starts taper_length before it); polyline() keeps the waypoints where the design puts them.

polyline() → list[kqcircuits.pya_resolver.pya.DPoint]
fixed_segments: set
joins: list = []
length: float | None = None
name: str
nodes: list[kqcircuits.util.node.Node]
params: dict
target_length: float | None = None
quantcore_circuits.route.router.corner_violations(points: list[kqcircuits.pya_resolver.pya.DPoint], r: float, tol: float = 0.001, radii: dict | None = None) → list[tuple[int, float, float]]

Segments too short for their bends: (segment index, length, required).

A bend of angle θ with radius r uses r·tan(θ/2) of each adjacent straight segment (KQC WaveguideCoplanar corner model). radii maps corner positions ((x, y) rounded to 1e-6 µm) to their own radius (Waypoint.r); every other corner uses r. Call it on merge_collinear() points (the router does): indices refer to the list passed in.

quantcore_circuits.route.router.fit_tapers(plan: RoutePlan, measure) → RoutePlan

Tapers that end where the route can take them.

A waypoint with its own a/b becomes a KQC WaveguideCoplanarTaper that starts at the node and runs taper_length forward. Where the straight after the node is shorter than that (a widening taper 51 µm before the route’s end, say), KQC draws the taper past the next node and then runs the line back to it: the etch reaches beyond the route’s end and the built length counts the overshoot twice (forward in the taper, back in the line). Such a node is marked TAPER_END: the route cell is built with it taper_length further back along its incoming straight (kqc_nodes()), so the taper ends at the waypoint and the line after it keeps the new width up to the next node. The plan’s nodes, polyline and waypoint indices stay where the design puts them (the plugin’s route handles do not move).

measure(plan) -> float builds the route and returns its length: a mark is kept only where it removes the whole double count (the length drops by twice the overshoot), i.e. where the straight before the node has room for the taper after whatever element ends there. Other routes, and routes whose tapers fit, are returned as they are.

quantcore_circuits.route.router.fix_length(plan: RoutePlan, measure, segment: int | None = None, meanders: int = -1, tol: float = 0.01, direction: int | None = None) → RoutePlan

Make the built length equal plan.target_length.

measure(plan) -> float must build the waveguide and return its length (µm). By the leftover target - length of the path as drawn (2026-11-18: no slanted zigzags on a route that is already about the right length):

  • within tol: the path as drawn, no meander;

  • small enough: the free corners’ bend radius trimmed by up to TRIM_FRACTION (trim_corners());

  • else a KQC Meander on the longest free straight (or segment), with as many turns as fit unless they would flatten into a zigzag (meander_turns(): then fewer, wider turns).

quantcore_circuits.route.router.kqc_nodes(nodes: list[kqcircuits.util.node.Node]) → list[kqcircuits.util.node.Node]

The nodes KQC builds the route from: a node marked TAPER_END (by fit_tapers()) is moved back along its incoming straight by its taper’s length, so KQC’s taper, which starts at the node, ends at the waypoint. Other nodes are returned as they are.

quantcore_circuits.route.router.max_meanders(span: float, r: float) → int

Most meander turns that stay on a straight of length span: KQC puts the first bend r after the straight’s start and each turn takes 2·r along it, so int(span / 2r - 1) (the count KQC itself picks when automatic). A larger count runs the first and last bends past the straight’s ends (over whatever lies beyond the node).

quantcore_circuits.route.router.meander_segment_index(nodes: list[kqcircuits.util.node.Node], preferred: int | None = None, fixed: set | None = None) → int

Index of the node ending the segment that hosts the meander (KQC puts length_* on that node).

quantcore_circuits.route.router.meander_span(plan: RoutePlan, segment: int) → float

Length (µm) of the straight KQC lays a meander on for the segment ending at node segment: the node-to-node distance less the bend cut at each end (KQC Meander start / end points).

quantcore_circuits.route.router.meander_turns(increment: float, span: float, r: float, meanders: int = -1) → int

The turn count for a length-fixing meander of increment on a straight of span: meanders as given (-1: as many as fit, KQC’s choice) unless that meander would be narrower than r — KQC then draws its flattened bends along the whole straight, a slanted zigzag. Then the most turns that keep it r wide (at least one: a single bump in the middle of the straight).

quantcore_circuits.route.router.meander_width(increment: float, r: float, meanders: int) → float

Total width (µm) of the KQC Meander that adds increment with meanders turns of radius r (the same formulas as Meander.build). At 4·r and above every bend is 90°; below, KQC flattens the bends, and a width under r is a near-straight zigzag along the whole straight.

quantcore_circuits.route.router.merge_collinear(points: list[kqcircuits.pya_resolver.pya.DPoint], angle_tol: float = 1e-06) → list[kqcircuits.pya_resolver.pya.DPoint]

Drop interior points where the polyline goes straight on (no bend there): a straight leg split into pieces must not be checked piece by piece.

quantcore_circuits.route.router.plan_route(name: str, route: quantcore_circuits.design.schema.Route, start: RouteEnd, end: RouteEnd, defaults: dict) → RoutePlan

Build the node list for one route. defaults supplies a, b, r when neither route nor port does.

quantcore_circuits.route.router.trim_corners(plan: RoutePlan, increment: float, measure, tol: float = 0.01) → RoutePlan | None

plan lengthened by increment without a meander: the free corners (_free_corners()) get a slightly smaller bend radius (node corner_r, one value for all of them), so the path, its nodes and its fixed parts stay as drawn. None where the route has no free corner, a node sets its own r (KQC then changes the radius for the rest of the route), or the radius would shrink by more than TRIM_FRACTION.

quantcore_circuits.route.router.with_length_increment(plan: RoutePlan, increment: float, segment: int, meanders: int = -1, direction: int | None = None) → RoutePlan

plan with a meander of increment extra length on segment; direction (1 / −1) picks the side of the meander’s first turn (KQC Node.meander_direction). A requested number of turns that does not fit on the straight is reduced to what fits (the meander gets wider instead, the length is the same).

quantcore_circuits.route.router.TAPER_END = 'taper_end'
quantcore_circuits.route.router.TRIM_FRACTION = 0.05