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.