inire/DOCS.md

Inire Configuration & API Documentation

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

1. AStarContext Parameters

The AStarContext stores the configuration and persistent state for the A* search. It is initialized once and passed to route_astar or the PathFinder.

Parameter	Type	Default	Description
node_limit	int	1,000,000	Maximum number of states to explore per net. Increase for very complex paths.
snap_size	float	5.0	Grid size (µm) for expansion moves. Larger values speed up search.
max_straight_length	float	2000.0	Maximum length (µm) of a single straight segment.
min_straight_length	float	5.0	Minimum length (µm) of a single straight segment.
bend_radii	list[float]	[50.0, 100.0]	Available radii for 90-degree turns (µm).
sbend_radii	list[float]	[5.0, 10.0, 50.0, 100.0]	Available radii for S-bends (µm).
sbend_offsets	list[float] | None	None (Auto)	Lateral offsets for parametric S-bends.
bend_penalty	float	250.0	Flat cost added for every 90-degree bend.
sbend_penalty	float	500.0	Flat cost added for every S-bend.
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 for clipped models.

2. AStarMetrics

The AStarMetrics object collects performance data during the search.

Property	Type	Description
nodes_expanded	int	Number of nodes expanded in the last route_astar call.
total_nodes_expanded	int	Cumulative nodes expanded across all calls.
max_depth_reached	int	Deepest point in the search tree reached.

---

3. 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.