# 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`
- `locked_routes`
- `clearance`
- `max_net_width`
- `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.

### Incremental routing with `LockedRoute`

For incremental workflows, route one problem, convert a result into a `LockedRoute`, and feed it into the next problem:

```python
run_a = route(problem_a)
problem_b = RoutingProblem(
    bounds=problem_a.bounds,
    nets=(...),
    locked_routes={"netA": run_a.results_by_net["netA"].as_locked_route()},
)
run_b = route(problem_b)
```

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

## 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. |
| `initial_paths` | `None` | Optional user-supplied initial paths for warm starts. |

## 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. |
| `congestion_penalty` | `0.0` | Congestion weight used when explicitly scoring complete paths. |

## 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. |
| `warm_start` | `"shortest"` | Optional greedy warm-start ordering. |
| `shuffle_nets` | `False` | Shuffle routing order between iterations. |
| `sort_nets` | `None` | Optional deterministic routing order. |
| `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 internal implementation details. The 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`.