Routing Functions

Start port(s) — gf.Port or list of Ports.

End port(s) — gf.Port or list of Ports.

Minimum bend radius (um). Derived from cross_section.radius_min when cross_section is given.

Keep-out zones. Any objects with xmin, ymin, xmax, ymax attributes (e.g. gdsfactory component references from c << gf.c.rectangle(...)).

Layer spec or list of layer specs to extract from context_component as keep-out zones. Extracted bboxes are appended to any explicit obstacles.

Alias for obstacle_layers for gdsfactory route_bundle() compatibility.

Clearance from obstacles (um). Derived from PDK separation when cross_section is given.

CrossSection object, string name (e.g. "strip"), or callable. When provided, routing parameters are derived from it.

Component to merge with when using build_gds(include_context=True).

FinetuneConfig(...) to run gradient-based optimization. None (default) for manhattan only.

If True, validate shared-backbone bundle initialization and retry with iterative bundle routing when it collides.

If True, use iterative bundle routing directly instead of shared-backbone bundle initialization.

If True, force raw shared-backbone bundle initialization with NO fallback ladder. For debugging/isolating the backbone method — it may produce crossing routes on non-offsettable bundles (the no-flag default escalates past such failures instead).

Center-to-center spacing used by the Manhattan bundle initializer when routing around prior routes.

Physical route width used by the Manhattan initializer when converting already-routed skeletons to temporary keepouts. Derived from cross_section.width when cross_section is given.

Complete routes to use instead of running the initializer — one (M_i, 2) array of corner coordinates per port pair, in the same order as the port lists. Hand-authored, or saved from a previous router.get_polylines(). Crossings are kept as given. With finetune=None the routes are drawn exactly as supplied, which is what makes GDS re-rendering reproducible; with a FinetuneConfig they are refined — axis-aligned polylines stay axis-aligned, while polylines that are not get the unconstrained finetune (with a warning, since that path moves each route's first and last interior point onto the port tangent lines). Cannot be combined with match_ports or sort_ports, which would re-pair the routes.

Supplied straights and L-routes are held fixed by finetune, since they own no tunable rail and playdough will not invent a detour you did not draw. If you handed in a sketch and want it reshaped, pass finetune=FinetuneConfig(..., ensure_min_dof=True).

This is only the input half of a cache: nothing is stored or invalidated for you. Stale geometry is caught at the ports — an endpoint that no longer reaches its port, or a terminal segment no longer leaving along the port axis, raises ValueError naming the route. Obstacles are not re-checked, so a saved route that now crosses a new keep-out is accepted silently; re-route when the surrounding layout moves.

Incomplete positional hints the manhattan initializer routes through — the middle of the family. polylines supply whole routes and skip the initializer; anchors are soft targets the finetune is merely pulled toward; waypoints are hard points the initializer must pass through while still solving everything else.

The nesting mirrors start_ports. A flat list of points hints the whole bundle; a list of lists gives one list per port pair, or per port group when the ports were passed grouped. None in a per-route list means "route that pair normally". A hint is (x, y), a kdb.DPoint, a kdb.DTrans, or ((x, y), degrees) — the last two pin the heading the route takes through the point, which is beyond what kfactory can express (it has one heading for a whole bundle). Note a pinned hint is always a pass-through on that heading, never a corner.

A hint costs no extra bend when the route can run straight through it: the initializer tries a pass-through first and only turns at the point when that does not work. So hinting somewhere a route already goes leaves it unchanged.

A hint shared by several routes belongs to the bundle: the representative route is routed through it and the others are derived as parallel offsets, so the group cannot cross itself. Use per-route hints when a specific route must hit a specific point.

Hints are honoured exactly by the initializer. finetune may then move a route off them, so they are also handed to it as anchor targets (waypoints_as_anchors, on by default). Anchoring is a soft pull that needs a non-zero anchor_proximity weight and competes with the other costs — on a length-matched bundle the two directly oppose each other, so choose the weight rather than expecting both. Unreachable hints are dropped with a warning rather than producing a broken route; the initializer never raises for them.

If True, reorder each port list using the same KFactory/gdsfactory bundle sorting convention used by gf.routing.route_bundle(..., sort_ports=True). This can change which start port connects to which end port — i.e. the netlist — because the two lists are sorted independently and then paired by index; use it only when the assignment is free (e.g. a fan-out into an interchangeable fiber array). A UserWarning reports how many connections were rewired, and router.port_permutation records the mapping back to the requested pairs. This is different from match_ports=True: sort_ports sorts both lists in a gdsfactory-compatible order and pairs by index, while match_ports computes pairings from route geometry to reduce crossings.

Forwarded to Router(). Common ones:

• target_radius (float): preferred bend radius (um).
• internal_pivots (int): corner count per route.
• route_width (float): physical width used for manhattan initialization keepouts.
• route_collision_width (float): route width used by the differentiable route-collision cost during finetuning.
• route_collision_margin (float): min clearance between routes.
• match_ports (bool): Playdough-specific geometry heuristic that changes which start port connects to which end port (the netlist) to minimize crossings. Only for free assignments.
• sort_ports (bool): gdsfactory-compatible port-list sorting before index-based pairing; also changes the netlist.
• maximize_radius (bool): prefer largest allowed radius.
• bend_type (str): "euler" (default) or "arc".

A Router with pivots set. Key methods:

• router.build_gds() → gdsfactory Component.

• router.get_polylines() → list of (N, 2) numpy arrays.

• router.finetune(config) → refine with optimization.

Start port(s) — gf.Port or list of Ports.

End port(s) — gf.Port or list of Ports.

If True, return dense smooth paths through euler/arc bends instead of raw corner-tip pivots. Only the smooth=False form can be fed back as polylines=.

Forwarded to route_bundle(). See its docstring for the full list (obstacles, cross_section, finetune, min_radius, target_radius, internal_pivots, polylines, etc.).

List of (N_i, 2) numpy arrays, one per route. Each array

contains the corner-point coordinates in um.

The gdsfactory Component to add routes to.

Start port(s) — gf.Port or list of Ports.

End port(s) — gf.Port or list of Ports.

Combine all routes into one sub-component.

Whether to include diagnostic polyline/smooth-path overlay layers in the inserted route geometry.

Deprecated for this in-place API. Use route_bundle(...).build_gds(include_context=True) when you want a separate combined copy of context plus routes.

Forwarded to route_bundle(). See its docstring for the full list.

The Router instance. Call router.finetune(config) to

refine, then router.build_gds() to update the inserted routes.