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/proxy model: `"arc"`, `"bbox"`, `"clipped_bbox"`, or, for backward compatibility, a custom polygon. A legacy custom polygon here is treated as both the physical bend and its proxy unless overridden by the split fields below. |
| `bend_proxy_geometry` | `None` | Optional explicit bend proxy geometry. Use this when you want a custom search/collision envelope that differs from the routed bend shape. Supplying only a custom polygon proxy warns and keeps the physical bend as the standard arc. |
| `bend_physical_geometry` | `None` | Optional explicit bend physical geometry. Use `"arc"` or a custom polygon. If you set a custom physical polygon and do not set a proxy, the proxy defaults to the same polygon. |
| `bend_clip_margin` | `None` | Optional legacy shrink margin for `"clipped_bbox"`. Leave `None` for the default 8-point proxy. |
| `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.

### Search Counters

- `nodes_expanded`: Total nodes expanded during the run.
- `moves_generated`: Total candidate moves generated during the run.
- `moves_added`: Total candidate moves admitted to the open set.
- `pruned_closed_set`: Total moves pruned because the state was already closed at lower cost.
- `pruned_hard_collision`: Total moves pruned by hard collision checks.
- `pruned_cost`: Total moves pruned by cost ceilings or invalid costs.
- `route_iterations`: Number of negotiated-congestion iterations entered.
- `nets_routed`: Number of net-routing attempts executed across all iterations.
- `nets_reached_target`: Number of those attempts that reached the requested target port.
- `warm_start_paths_built`: Number of warm-start seed paths built by the greedy bootstrap pass.
- `warm_start_paths_used`: Number of routing attempts satisfied directly from an initial or warm-start path.
- `refine_path_calls`: Number of completed paths passed through the post-route refiner.
- `timeout_events`: Number of timeout exits encountered during the run.

### Cache Counters

- `move_cache_abs_hits` / `move_cache_abs_misses`: Absolute move-geometry cache activity.
- `move_cache_rel_hits` / `move_cache_rel_misses`: Relative move-geometry cache activity.
- `static_safe_cache_hits`: Reuse count for the static-safe admission cache.
- `hard_collision_cache_hits`: Reuse count for the hard-collision cache.
- `congestion_cache_hits` / `congestion_cache_misses`: Per-search congestion-cache activity.

### Index And Collision Counters

- `dynamic_path_objects_added` / `dynamic_path_objects_removed`: Dynamic-path geometry objects inserted into or removed from the live routing index.
- `dynamic_tree_rebuilds`: Number of dynamic STRtree rebuilds.
- `dynamic_grid_rebuilds`: Number of dynamic congestion-grid rebuilds.
- `static_tree_rebuilds`: Number of static dilated-obstacle STRtree rebuilds.
- `static_raw_tree_rebuilds`: Number of raw static-obstacle STRtree rebuilds used for verification.
- `static_net_tree_rebuilds`: Number of net-width-specific static STRtree rebuilds.
- `visibility_builds`: Number of static visibility-graph rebuilds.
- `visibility_corner_pairs_checked`: Number of corner-pair visibility probes considered while building that graph.
- `visibility_corner_queries` / `visibility_corner_hits`: Precomputed-corner visibility query activity.
- `visibility_point_queries`, `visibility_point_cache_hits`, `visibility_point_cache_misses`: Arbitrary-point visibility query and cache activity.
- `ray_cast_calls`: Number of ray-cast queries issued against static obstacles.
- `ray_cast_candidate_bounds`: Total broad-phase candidate bounds considered by ray casts.
- `ray_cast_exact_geometry_checks`: Total exact non-rectangular geometry checks performed by ray casts.
- `congestion_check_calls`: Number of congestion broad-phase checks requested by search.
- `congestion_exact_pair_checks`: Number of exact geometry-pair checks performed while confirming congestion hits.

### Verification Counters

- `verify_path_report_calls`: Number of full path-verification passes.
- `verify_static_buffer_ops`: Number of static-verification `buffer()` operations.
- `verify_dynamic_exact_pair_checks`: Number of exact geometry-pair checks performed during dynamic-path verification.

## 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=...)`.

The current implementation structure is summarized in **[docs/architecture.md](docs/architecture.md)**. The committed example-corpus counter baseline is tracked in **[docs/performance.md](docs/performance.md)**.
Use `scripts/diff_performance_baseline.py` to compare a fresh local run against that baseline. The counter baseline is currently observational and is not enforced as a CI gate.

## 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.
- Use `search.bend_physical_geometry` and `search.bend_proxy_geometry` together when you need a real custom bend shape plus a different conservative proxy.

### 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`.