inire/examples/README.md

# Inire Routing Examples

This directory contains examples demonstrating the features and architectural capabilities of the `inire` router.

## Architectural Visualization
In all plots generated by `inire`, we distinguish between the search-time geometry and the final "actual" geometry:
*   **Dashed Lines & Translucent Fill**: The **Collision Proxy** used during the A* search (e.g., `clipped_bbox` or `bbox`). This represents the conservative envelope the router used to guarantee clearance.
*   **Solid Lines**: The **Actual Geometry** (high-fidelity arcs). This is the exact shape that will be used for PDK generation and fabrication.

---

## Example Index

| Example | Script | Output PNG | Summary |
| :-- | :-- | :-- | :-- |
| 01 | `01_simple_route.py` | `01_simple_route.png` | Single-net baseline route with one bend radius. |
| 02 | `02_congestion_resolution.py` | `02_congestion_resolution.png` | Small multi-net negotiated-congestion example. |
| 03 | `03_locked_paths.py` | `03_locked_paths.png` | Incremental routing with previously routed geometry treated as locked obstacles. |
| 04 | `04_sbends_and_radii.py` | `04_sbends_and_radii.png` | S-bend and bend-radius behavior on compact routes. |
| 05 | `05_orientation_stress.py` | `05_orientation_stress.png` | Orientation-heavy routing with flips, loops, and U-turn-like cases. |
| 06 | `06_bend_collision_models.py` | `06_bend_collision_models.png` | Comparison of bend collision/proxy geometry models. |
| 07 | `07_large_scale_routing.py` | `07_large_scale_routing.png` | Large fan-out through a bottleneck with negotiated congestion and expansion overlay. |
| 08 | `08_custom_bend_geometry.py` | `08_custom_bend_geometry.png` | Custom physical bend geometry and separate custom proxy geometry. |
| 09 | `09_unroutable_best_effort.py` | `09_unroutable_best_effort.png` | Best-effort partial routing for a blocked or unroutable net. |

## 01. Simple Route
A minimal single-net example that routes one connection across an empty board and saves the result to `01_simple_route.png`.

![Simple Route](01_simple_route.png)

## 02. Congestion Resolution
Demonstrates negotiated congestion on a small multi-net problem where overlapping routes must be separated over successive iterations.

![Congestion Resolution](02_congestion_resolution.png)

## 03. Locked Paths
Shows how to treat previously routed geometry as fixed static obstacles in a later run.

![Locked Paths](03_locked_paths.png)

## 04. S-Bends And Radii
Highlights compact routing behavior with S-bends and the configured bend radii.

![S-Bends And Radii](04_sbends_and_radii.png)

## 05. Orientation Stress Test
Demonstrates the router's ability to handle complex orientation requirements, including U-turns, 90-degree flips, and loops.

![Orientation Stress Test](05_orientation_stress.png)

## 06. Bend Geometry Models
`inire` supports multiple collision models for bends, allowing a trade-off between search speed and geometric accuracy:
*   **Arc**: High-fidelity geometry (Highest accuracy).
*   **BBox**: Simple axis-aligned bounding box (Fastest search).
*   **Custom Manhattan Geometry**: A custom 90-degree bend polygon with the same width as the normal waveguide.

Example 06 uses the Manhattan polygon as both the true routed bend geometry and the collision proxy.

![Bend Collision Models](06_bend_collision_models.png)

## 07. Fan-Out (Negotiated Congestion)
Demonstrates the Negotiated Congestion algorithm handling multiple intersecting nets. The router iteratively increases penalties for overlaps until a collision-free solution is found. This example shows a bundle of nets fanning out through a narrow bottleneck.

![Fan-Out Routing](07_large_scale_routing.png)

## 08. Custom Bend Geometry
Compares the standard arc against a run that uses a custom physical bend plus a separate custom proxy polygon, with each net routed in its own session.

![Custom Bend Geometry](08_custom_bend_geometry.png)

## 09. Unroutable Nets & Best-Effort Display
When a net is physically blocked or exceeds the node limit, the router returns the "best-effort" partial path—the path that reached the point closest to the target according to the heuristic. This is critical for debugging design constraints.

![Best Effort Display](09_unroutable_best_effort.png)

## Notes
- Example 07 overlays expanded search nodes on the saved routing figure.
- The current implementation can use a cheaper bend proxy on the first negotiated-congestion pass before later passes fall back to the configured bend model. This is controlled by `RoutingOptions.congestion.use_tiered_strategy` together with the bend collision settings described in `DOCS.md`.