inire/README.md

# inire: Auto-Routing for Photonic and RF Integrated Circuits

`inire` is a high-performance auto-router designed specifically for the physical constraints of photonic and RF integrated circuits. It uses a Hybrid State-Lattice A* search combined with negotiated congestion to route multiple nets while maintaining strict geometric fidelity and clearance.

## Key Features

*   **Hybrid State-Lattice Search**: Routes using discrete 90° bends and parametric S-bends, ensuring manufacturing-stable paths.
*   **Negotiated Congestion**: Iteratively resolves multi-net bottlenecks by inflating costs in high-traffic regions.
*   **Analytic Correctness**: Every move is verified against an R-Tree spatial index of obstacles and other paths.
*   **1nm Precision**: All coordinates and ports are snapped to a 1nm manufacturing grid.
*   **Safety & Proximity**: Uses a sampled obstacle-boundary proximity model to bias routes away from nearby geometry.
*   **Locked Routes**: Supports treating prior routed nets as fixed obstacles in later runs.

## Installation

`inire` requires Python 3.11+. You can install the dependencies using `uv` (recommended) or `pip`:

```bash
# Using uv
uv sync

# Using pip
pip install numpy scipy shapely rtree matplotlib
```

## Quick Start

```python
from inire import NetSpec, ObjectiveWeights, Port, RoutingOptions, RoutingProblem, SearchOptions, route

problem = RoutingProblem(
    bounds=(0, 0, 1000, 1000),
    nets=(
        NetSpec("net1", Port(0, 0, 0), Port(100, 50, 0), width=2.0),
    ),
)
options = RoutingOptions(
    search=SearchOptions(
        bend_radii=(50.0, 100.0),
        greedy_h_weight=1.2,
    ),
    objective=ObjectiveWeights(
        bend_penalty=10.0,
    ),
)

run = route(problem, options=options)

if run.results_by_net["net1"].is_valid:
    print("Successfully routed net1!")
```

For incremental workflows, feed prior routed results back into a new `RoutingProblem` via `static_obstacles` using `RoutingResult.locked_geometry`.

## Usage Examples

For detailed visual demonstrations and architectural deep-dives, see the **[Examples README](examples/README.md)**.

Check the `examples/` directory for ready-to-run scripts. To run an example:
```bash
python3 examples/01_simple_route.py
```

## Testing

Run the default correctness suite with:

```bash
python3 -m pytest
```

Runtime regression checks for the example scenarios are opt-in and require:

```bash
INIRE_RUN_PERFORMANCE=1 python3 -m pytest -q inire/tests/test_example_performance.py
```

## Documentation

Current documentation lives in:

*   **[DOCS.md](DOCS.md)** for the public API and option reference.
*   **[docs/architecture.md](docs/architecture.md)** for the current implementation structure.
*   **[docs/performance.md](docs/performance.md)** for the committed performance-counter baseline.

## API Stability

The stable API lives at the package root and is centered on `route(problem, options=...)`.

Deep-module interfaces such as `inire.router._router.PathFinder`, `inire.router._search.route_astar`, and `inire.geometry.collision.RoutingWorld` remain accessible for advanced use, but they are unstable semi-private interfaces and may change without notice.

## Architecture

`inire` operates on a **State-Lattice** defined by $(x, y, \theta)$. From any state, the router expands via three primary "Move" types:
1.  **Straights**: Variable-length segments.
2.  **90° Bends**: Fixed-radius PDK cells.
3.  **Parametric S-Bends**: Procedural arcs for bridging small lateral offsets ($O < 2R$).

For multi-net problems, the negotiated-congestion loop handles rip-up and reroute logic and seeks a collision-free configuration without crossings.

## Configuration

`inire` is highly tunable. The stable API is `RoutingProblem` plus `RoutingOptions`, routed via `route(problem, options=...)`. Deep modules remain accessible for advanced workflows, but they are unstable and may change without notice. See `DOCS.md` for a full parameter reference.

## License

This project is licensed under the GNU Affero General Public License v3. See `LICENSE.md` for details.