inire/DOCS.md

Inire Configuration & API Documentation

This document describes the user-tunable parameters for the inire auto-router.

1. AStarRouter Parameters

The AStarRouter is the core pathfinding engine. It can be configured directly through its constructor.

Parameter	Type	Default	Description
node_limit	int	1,000,000	Maximum number of states to explore per net. Increase for very complex paths.
straight_lengths	list[float]	[1.0, 5.0, 25.0]	Discrete step sizes for straight waveguides (µm). Larger steps speed up search.
bend_radii	list[float]	[10.0]	Available radii for 90-degree turns (µm). Multiple values allow best-fit selection.
sbend_offsets	list[float] | None	None (Auto)	Lateral offsets for parametric S-bends. None uses automatic grid-aligned steps.
sbend_radii	list[float]	[10.0]	Available radii for S-bends (µm).
snap_to_target_dist	float	20.0	Distance (µm) at which the router attempts an exact bridge to the target port.
bend_penalty	float	50.0	Flat cost added for every 90-degree bend. Higher values favor straight lines.
sbend_penalty	float	100.0	Flat cost added for every S-bend. Usually higher than bend_penalty.
bend_collision_type	str	"arc"	Collision model for bends: "arc", "bbox", or "clipped_bbox".
bend_clip_margin	float	10.0	Extra space (µm) around the waveguide before the bounding box corners are clipped.

Bend Collision Models

• "arc": High-fidelity model following the exact curved waveguide geometry.
• "bbox": Conservative model using the axis-aligned bounding box of the bend. Fast but blocks more space.
• "clipped_bbox": A middle ground that starts with the bounding box but applies 45-degree linear cuts to the inner and outer corners. The bend_clip_margin defines the extra safety distance from the waveguide edge to the cut line.

---

2. CostEvaluator Parameters

The CostEvaluator defines the "goodness" of a path.

Parameter	Type	Default	Description
unit_length_cost	float	1.0	Cost per µm of wire length.
greedy_h_weight	float	1.1	Heuristic weight. 1.0 is optimal; higher values (e.g. 1.5) speed up search.
congestion_penalty	float	10,000.0	Multiplier for overlaps in the multi-net Negotiated Congestion loop.

---

3. PathFinder Parameters

The PathFinder orchestrates multi-net routing using the Negotiated Congestion algorithm.

Parameter	Type	Default	Description
max_iterations	int	10	Maximum number of rip-up and reroute iterations to resolve congestion.
base_congestion_penalty	float	100.0	Starting penalty for overlaps. Multiplied by 1.5 each iteration if congestion remains.

---

4. CollisionEngine Parameters

Parameter	Type	Default	Description
clearance	float	(Required)	Minimum required distance between any two waveguides or obstacles (µm).
safety_zone_radius	float	0.0021	Radius (µm) around ports where collisions are ignored for PDK boundary incidence.

---

4. Physical Units & Precision

• Coordinates: Micrometers (µm).
• Grid Snapping: The router internally operates on a 1nm grid for final ports and a 1µm lattice for expansion moves.
• Search Space: Assumptions are optimized for design areas up to 20mm x 20mm.
• Design Bounds: The boundary limits defined in DangerMap strictly constrain the physical edges (dilated geometry) of the waveguide. Any move that would cause the waveguide or its required clearance to extend beyond these bounds is rejected with an infinite cost.

---

5. Best Practices & Tuning Advice

Speed vs. Optimality

The greedy_h_weight is your primary lever for search performance.

• 1.0: Dijkstra-like behavior. Guarantees the shortest path but is very slow.
• 1.1 to 1.2: Recommended range. Balances wire length with fast convergence.
• > 1.5: Extremely fast "greedy" search. May produce zig-zags or suboptimal detours.

Avoiding "Zig-Zags"

If the router produces many small bends instead of a long straight line:

1. Increase bend_penalty (e.g., set to 100.0 or higher).
2. Ensure straight_lengths includes larger values like 25.0 or 100.0.
3. Decrease greedy_h_weight closer to 1.0.

Handling Congestion

In multi-net designs, if nets are overlapping:

1. Increase congestion_penalty in CostEvaluator.
2. Increase max_iterations in PathFinder.
3. If a solution is still not found, check if the clearance is physically possible given the design's narrowest bottlenecks.

S-Bend Usage

Parametric S-bends bridge lateral gaps without changing the waveguide's orientation.

• Automatic Selection: If sbend_offsets is set to None (the default), the router automatically chooses from a set of "natural" offsets (Fibonacci-aligned grid steps) and the offset needed to hit the target.
• Specific Offsets: To use specific offsets (e.g., 5.86µm for a 45° switchover), provide them in the sbend_offsets list. The router will prioritize these but will still try to align with the target if possible.
• Constraints: S-bends are only used for offsets O < 2R. For larger shifts, the router naturally combines two 90° bends and a straight segment.