quantcore_circuits.route.router =============================== .. py:module:: quantcore_circuits.route.router .. autoapi-nested-parse:: 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 :func:`_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 (:func:`fix_length`). * ``airbridges="auto"`` puts ``n_bridges=-1`` on every straight segment (KQC spaces them by ``ab_to_ab_spacing``). Attributes ---------- .. autoapisummary:: quantcore_circuits.route.router.TAPER_END quantcore_circuits.route.router.TRIM_FRACTION Exceptions ---------- .. autoapisummary:: quantcore_circuits.route.router.RoutingError Classes ------- .. autoapisummary:: quantcore_circuits.route.router.RouteEnd quantcore_circuits.route.router.RoutePlan Functions --------- .. autoapisummary:: quantcore_circuits.route.router.corner_violations quantcore_circuits.route.router.fit_tapers quantcore_circuits.route.router.fix_length quantcore_circuits.route.router.kqc_nodes quantcore_circuits.route.router.max_meanders quantcore_circuits.route.router.meander_segment_index quantcore_circuits.route.router.meander_span quantcore_circuits.route.router.meander_turns quantcore_circuits.route.router.meander_width quantcore_circuits.route.router.merge_collinear quantcore_circuits.route.router.plan_route quantcore_circuits.route.router.trim_corners quantcore_circuits.route.router.with_length_increment Module Contents --------------- .. py:exception:: RoutingError Bases: :py:obj:`ValueError` Inappropriate argument value (of correct type). .. py:class:: 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. .. py:method:: from_free(end: quantcore_circuits.design.schema.FreeEnd) -> RouteEnd :classmethod: .. py:method:: from_port(port: quantcore_circuits.layouts.ports.Port) -> RouteEnd :classmethod: .. py:attribute:: a :type: float | None :value: None .. py:attribute:: approach :type: list :value: [] .. py:attribute:: b :type: float | None :value: None .. py:attribute:: dir :type: kqcircuits.pya_resolver.pya.DVector | None .. py:attribute:: pos :type: kqcircuits.pya_resolver.pya.DPoint .. py:attribute:: term :type: float | None :value: None .. py:class:: RoutePlan .. py:method:: node_strings() -> list[str] The KQC nodes the route cell is built from (:func:`kqc_nodes`: a taper that ends at its waypoint starts ``taper_length`` before it); :meth:`polyline` keeps the waypoints where the design puts them. .. py:method:: polyline() -> list[kqcircuits.pya_resolver.pya.DPoint] .. py:attribute:: fixed_segments :type: set .. py:attribute:: joins :type: list :value: [] .. py:attribute:: length :type: float | None :value: None .. py:attribute:: name :type: str .. py:attribute:: nodes :type: list[kqcircuits.util.node.Node] .. py:attribute:: params :type: dict .. py:attribute:: target_length :type: float | None :value: None .. py:function:: 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 :func:`merge_collinear` points (the router does): indices refer to the list passed in. .. py:function:: 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 :data:`TAPER_END`: the route cell is built with it ``taper_length`` further back along its incoming straight (:func:`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. .. py:function:: 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 :data:`TRIM_FRACTION` (:func:`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 (:func:`meander_turns`: then fewer, wider turns). .. py:function:: kqc_nodes(nodes: list[kqcircuits.util.node.Node]) -> list[kqcircuits.util.node.Node] The nodes KQC builds the route from: a node marked :data:`TAPER_END` (by :func:`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. .. py:function:: 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). .. py:function:: 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). .. py:function:: 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). .. py:function:: 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). .. py:function:: 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. .. py:function:: 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. .. py:function:: 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. .. py:function:: trim_corners(plan: RoutePlan, increment: float, measure, tol: float = 0.01) -> RoutePlan | None ``plan`` lengthened by ``increment`` without a meander: the free corners (:func:`_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 :data:`TRIM_FRACTION`. .. py:function:: 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). .. py:data:: TAPER_END :value: 'taper_end' .. py:data:: TRIM_FRACTION :value: 0.05