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 in open space.
bend_radii	list[float]	[10.0]	Available radii for 90-degree turns (µm). Multiple values allow the router to pick the best fit.
sbend_offsets	list[float]	[-5, -2, 2, 5]	Lateral offsets for parametric S-bends (µm).
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	Margin (µm) for the "clipped_bbox" collision model.

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 uses the bounding box but clips corners that are far from the waveguide.

---

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) are faster but may produce longer paths.
congestion_penalty	float	10,000.0	Multiplier for overlaps in the multi-net Negotiated Congestion loop.

---

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

---

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 are triggered by the sbend_offsets list. If you need a specific lateral shift (e.g., 5.86µm for a 45° switchover), add it to sbend_offsets. The router will only use an S-bend if it can reach a state that is exactly on the lattice or the target.