inire/DOCS.md

# Inire Configuration & API Documentation

This document describes the current public API for `inire`.

## 1. Primary API

### `RoutingProblem`

`RoutingProblem` describes the physical routing problem:

- `bounds`
- `nets`
- `static_obstacles`
- `initial_paths`
- `clearance`
- `safety_zone_radius`

### `RoutingOptions`

`RoutingOptions` groups all expert controls for the routing engine:

- `search`
- `objective`
- `congestion`
- `refinement`
- `diagnostics`

Route a problem with:

```python
run = route(problem, options=options)
```

If you omit `options`, `route(problem)` uses `RoutingOptions()` defaults.

The package root is the stable API surface. Deep imports under `inire.router.*` and `inire.geometry.*` remain accessible for advanced use, but they are unstable semi-private interfaces and may change without notice.

Stable example:

```python
from inire import route, RoutingOptions, RoutingProblem
```

Unstable example:

```python
from inire.router._router import PathFinder
```

### Incremental routing with locked geometry

For incremental workflows, route one problem, reuse the result's locked geometry, and feed it into the next problem:

```python
run_a = route(problem_a)
problem_b = RoutingProblem(
    bounds=problem_a.bounds,
    nets=(...),
    static_obstacles=run_a.results_by_net["netA"].locked_geometry,
)
run_b = route(problem_b)
```

`RoutingResult.locked_geometry` stores canonical physical geometry only. The next run applies its own clearance rules when treating it as a static obstacle.

### Initial paths with `PathSeed`

Use `RoutingProblem.initial_paths` to provide semantic per-net seeds. Seeds are materialized with the current width, clearance, and bend collision settings for the run, and partial seeds are retried by normal routing in later iterations.

## 2. Search Options

`RoutingOptions.search` is a `SearchOptions` object.

| Field | Default | Description |
| :-- | :-- | :-- |
| `node_limit` | `1_000_000` | Maximum number of states to explore per net. |
| `max_straight_length` | `2000.0` | Maximum length of a single straight segment. |
| `min_straight_length` | `5.0` | Minimum length of a single straight segment. |
| `greedy_h_weight` | `1.5` | Heuristic weight. `1.0` is optimal but slower. |
| `bend_radii` | `(50.0, 100.0)` | Available radii for 90-degree bends. |
| `sbend_radii` | `(10.0,)` | Available radii for S-bends. |
| `sbend_offsets` | `None` | Optional explicit lateral offsets for S-bends. |
| `bend_collision_type` | `"arc"` | Bend collision model: `"arc"`, `"bbox"`, `"clipped_bbox"`, or a custom polygon. |
| `visibility_guidance` | `"tangent_corner"` | Visibility-derived straight candidate strategy. |

## 3. Objective Weights

`RoutingOptions.objective` and `RoutingOptions.refinement.objective` use `ObjectiveWeights`.

| Field | Default | Description |
| :-- | :-- | :-- |
| `unit_length_cost` | `1.0` | Cost per unit length. |
| `bend_penalty` | `250.0` | Flat bend penalty before radius scaling. |
| `sbend_penalty` | `500.0` | Flat S-bend penalty. |
| `danger_weight` | `1.0` | Weight applied to danger-map proximity costs. |

## 4. Congestion Options

`RoutingOptions.congestion` is a `CongestionOptions` object.

| Field | Default | Description |
| :-- | :-- | :-- |
| `max_iterations` | `10` | Maximum rip-up and reroute iterations. |
| `base_penalty` | `100.0` | Starting overlap penalty for negotiated congestion. |
| `multiplier` | `1.5` | Multiplier applied after an iteration still needs retries. |
| `use_tiered_strategy` | `True` | Use cheaper collision proxies in the first pass when applicable. |
| `net_order` | `"user"` | Net ordering strategy for warm-start seeding and routed iterations. |
| `warm_start_enabled` | `True` | Run the greedy warm-start seeding pass before negotiated congestion iterations. |
| `shuffle_nets` | `False` | Shuffle routing order between iterations. |
| `seed` | `None` | RNG seed for shuffled routing order. |

## 5. Refinement Options

`RoutingOptions.refinement` is a `RefinementOptions` object.

| Field | Default | Description |
| :-- | :-- | :-- |
| `enabled` | `True` | Enable post-route refinement. |
| `objective` | `None` | Optional override objective for refinement. `None` reuses the search objective. |

## 6. Diagnostics Options

`RoutingOptions.diagnostics` is a `DiagnosticsOptions` object.

| Field | Default | Description |
| :-- | :-- | :-- |
| `capture_expanded` | `False` | Record expanded nodes for diagnostics and visualization. |

## 7. RouteMetrics

`RoutingRunResult.metrics` is an immutable per-run snapshot.

| Field | Type | Description |
| :-- | :-- | :-- |
| `nodes_expanded` | `int` | Total nodes expanded during the run. |
| `moves_generated` | `int` | Total candidate moves generated during the run. |
| `moves_added` | `int` | Total candidate moves admitted to the open set during the run. |
| `pruned_closed_set` | `int` | Total moves pruned because the state was already closed at lower cost. |
| `pruned_hard_collision` | `int` | Total moves pruned by hard collision checks. |
| `pruned_cost` | `int` | Total moves pruned by cost ceilings or invalid costs. |

## 8. Internal Modules

Lower-level search and collision modules are semi-private implementation details. They remain accessible through deep imports for advanced use, but they are unstable and may change without notice. The stable supported entrypoint is `route(problem, options=...)`.

## 9. Tuning Notes

### Speed vs. optimality

- Lower `search.greedy_h_weight` toward `1.0` for better optimality.
- Raise `search.greedy_h_weight` for faster, greedier routing.

### Congestion handling

- Increase `congestion.base_penalty` to separate nets more aggressively in the first iteration.
- Increase `congestion.max_iterations` if congestion needs more reroute passes.
- Increase `congestion.multiplier` if later iterations need to escalate more quickly.

### Bend-heavy routes

- Increase `objective.bend_penalty` to discourage ladders of small bends.
- Increase available `search.bend_radii` when larger turns are physically acceptable.

### Visibility guidance

- `"tangent_corner"` is the default and best general-purpose setting in obstacle-dense layouts.
- `"exact_corner"` is more conservative.
- `"off"` disables visibility-derived straight candidates.

### S-bends

- Leave `search.sbend_offsets=None` to let the router derive natural offsets automatically.
- Provide explicit `search.sbend_offsets` for known process-preferred offsets.
- S-bends are only used for offsets smaller than `2R`.