rework structure of everything
This commit is contained in:
parent
dcc4d6436c
commit
941d3e01df
64 changed files with 3819 additions and 3559 deletions
210
DOCS.md
210
DOCS.md
|
|
@ -1,107 +1,159 @@
|
|||
# Inire Configuration & API Documentation
|
||||
|
||||
This document describes the user-tunable parameters for the `inire` auto-router.
|
||||
This document describes the current public API for `inire`.
|
||||
|
||||
## 1. AStarContext Parameters
|
||||
## 1. Primary API
|
||||
|
||||
The `AStarContext` stores the configuration and persistent state for the A* search. It is initialized once and passed to `route_astar` or the `PathFinder`.
|
||||
### `RoutingProblem`
|
||||
|
||||
| Parameter | Type | Default | Description |
|
||||
| :-------------------- | :------------ | :----------------- | :------------------------------------------------------------------------------------ |
|
||||
| `node_limit` | `int` | 1,000,000 | Maximum number of states to explore per net. Increase for very complex paths. |
|
||||
| `max_straight_length` | `float` | 2000.0 | Maximum length (µm) of a single straight segment. |
|
||||
| `min_straight_length` | `float` | 5.0 | Minimum length (µm) of a single straight segment. |
|
||||
| `bend_radii` | `list[float]` | `[50.0, 100.0]` | Available radii for 90-degree turns (µm). |
|
||||
| `sbend_radii` | `list[float]` | `[5.0, 10.0, 50.0, 100.0]` | Available radii for S-bends (µm). |
|
||||
| `sbend_offsets` | `list[float] \| None` | `None` (Auto) | Lateral offsets for parametric S-bends. |
|
||||
| `bend_penalty` | `float` | 250.0 | Flat cost added for every 90-degree bend. |
|
||||
| `sbend_penalty` | `float` | 500.0 | Flat cost added for every S-bend. |
|
||||
| `bend_collision_type` | `str` | `"arc"` | Collision model for bends: `"arc"`, `"bbox"`, or `"clipped_bbox"` (an 8-point conservative arc proxy). |
|
||||
| `bend_clip_margin` | `float` | 10.0 | Extra space (µm) around the waveguide for clipped models. |
|
||||
| `visibility_guidance` | `str` | `"tangent_corner"` | Visibility-driven straight candidate mode: `"off"`, `"exact_corner"`, or `"tangent_corner"`. |
|
||||
`RoutingProblem` describes the physical routing problem:
|
||||
|
||||
## 2. AStarMetrics
|
||||
- `bounds`
|
||||
- `nets`
|
||||
- `static_obstacles`
|
||||
- `locked_routes`
|
||||
- `clearance`
|
||||
- `max_net_width`
|
||||
- `safety_zone_radius`
|
||||
|
||||
The `AStarMetrics` object collects performance data during the search.
|
||||
### `RoutingOptions`
|
||||
|
||||
| Property | Type | Description |
|
||||
| :--------------------- | :---- | :---------------------------------------------------- |
|
||||
| `nodes_expanded` | `int` | Number of nodes expanded in the last `route_astar` call. |
|
||||
| `total_nodes_expanded` | `int` | Cumulative nodes expanded across all calls. |
|
||||
| `max_depth_reached` | `int` | Deepest point in the search tree reached. |
|
||||
`RoutingOptions` groups all expert controls for the routing engine:
|
||||
|
||||
---
|
||||
- `search`
|
||||
- `objective`
|
||||
- `congestion`
|
||||
- `refinement`
|
||||
- `diagnostics`
|
||||
|
||||
## 3. CostEvaluator Parameters
|
||||
Route a problem with:
|
||||
|
||||
The `CostEvaluator` defines the "goodness" of a path.
|
||||
```python
|
||||
run = route(problem, options=options)
|
||||
```
|
||||
|
||||
| Parameter | Type | Default | Description |
|
||||
| :------------------- | :------ | :--------- | :--------------------------------------------------------------------------------------- |
|
||||
| `unit_length_cost` | `float` | 1.0 | Cost per µm of wire length. |
|
||||
| `greedy_h_weight` | `float` | 1.1 | Heuristic weight. `1.0` is optimal; higher values (e.g. `1.5`) speed up search. |
|
||||
| `congestion_penalty` | `float` | 10,000.0 | Multiplier for overlaps in the multi-net Negotiated Congestion loop. |
|
||||
If you omit `options`, `route(problem)` uses `RoutingOptions()` defaults.
|
||||
|
||||
---
|
||||
### Incremental routing with `LockedRoute`
|
||||
|
||||
## 3. PathFinder Parameters
|
||||
For incremental workflows, route one problem, convert a result into a `LockedRoute`, and feed it into the next problem:
|
||||
|
||||
The `PathFinder` orchestrates multi-net routing using the Negotiated Congestion algorithm.
|
||||
```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)
|
||||
```
|
||||
|
||||
| Parameter | Type | Default | Description |
|
||||
| :------------------------ | :------ | :------ | :-------------------------------------------------------------------------------------- |
|
||||
| `max_iterations` | `int` | 10 | Maximum number of rip-up and reroute iterations to resolve congestion. |
|
||||
| `base_congestion_penalty` | `float` | 100.0 | Starting penalty for overlaps. Multiplied by `1.5` each iteration if congestion remains.|
|
||||
| `refine_paths` | `bool` | `True` | Run the post-route path simplifier that removes unnecessary bend ladders when it finds a valid lower-cost replacement. |
|
||||
`LockedRoute` stores canonical physical geometry only. The next run applies its own clearance rules when treating it as a static obstacle.
|
||||
|
||||
---
|
||||
## 2. Search Options
|
||||
|
||||
## 4. CollisionEngine Parameters
|
||||
`RoutingOptions.search` is a `SearchOptions` object.
|
||||
|
||||
| Parameter | Type | Default | Description |
|
||||
| :------------------- | :------ | :--------- | :------------------------------------------------------------------------------------ |
|
||||
| `clearance` | `float` | (Required) | Minimum required distance between any two waveguides or obstacles (µm). |
|
||||
| `safety_zone_radius` | `float` | 0.0021 | Radius (µm) around ports where collisions are ignored for PDK boundary incidence. |
|
||||
| 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
|
||||
|
||||
## 4. Physical Units & Precision
|
||||
- **Coordinates**: Micrometers (µm).
|
||||
- **Grid Snapping**: The router internally operates on a **1nm** grid for final ports and a **1µm** lattice for expansion moves.
|
||||
- **Search Space**: Assumptions are optimized for design areas up to **20mm x 20mm**.
|
||||
- **Design Bounds**: The boundary limits defined in `DangerMap` strictly constrain the **physical edges** (dilated geometry) of the waveguide. Any move that would cause the waveguide or its required clearance to extend beyond these bounds is rejected with an infinite cost.
|
||||
`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. |
|
||||
|
||||
## 5. Best Practices & Tuning Advice
|
||||
## 4. Congestion Options
|
||||
|
||||
### Speed vs. Optimality
|
||||
The `greedy_h_weight` is your primary lever for search performance.
|
||||
- **`1.0`**: Dijkstra-like behavior. Guarantees the shortest path but is very slow.
|
||||
- **`1.1` to `1.2`**: Recommended range. Balances wire length with fast convergence.
|
||||
- **`> 1.5`**: Extremely fast "greedy" search. May produce zig-zags or suboptimal detours.
|
||||
`RoutingOptions.congestion` is a `CongestionOptions` object.
|
||||
|
||||
### Avoiding "Zig-Zags"
|
||||
If the router produces many small bends instead of a long straight line:
|
||||
1. Increase `bend_penalty` (e.g., set to `100.0` or higher).
|
||||
2. Increase available `bend_radii` if larger turns are physically acceptable.
|
||||
3. Decrease `greedy_h_weight` closer to `1.0`.
|
||||
| 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. |
|
||||
|
||||
### Visibility Guidance
|
||||
The router can bias straight stop points using static obstacle corners.
|
||||
- **`"tangent_corner"`**: Default. Proposes straight lengths that set up a clean tangent bend around nearby visible corners. This helps obstacle-dense layouts more than open space.
|
||||
- **`"exact_corner"`**: Only uses precomputed corner-to-corner visibility when the current search state already lands on an obstacle corner.
|
||||
- **`"off"`**: Disables visibility-derived straight candidates entirely.
|
||||
The arbitrary-point visibility scan remains available for diagnostics, but the router hot path intentionally uses the exact-corner / tangent-corner forms only.
|
||||
## 5. Refinement Options
|
||||
|
||||
### Handling Congestion
|
||||
In multi-net designs, if nets are overlapping:
|
||||
1. Increase `congestion_penalty` in `CostEvaluator`.
|
||||
2. Increase `max_iterations` in `PathFinder`.
|
||||
3. If a solution is still not found, check if the `clearance` is physically possible given the design's narrowest bottlenecks.
|
||||
`RoutingOptions.refinement` is a `RefinementOptions` object.
|
||||
|
||||
### S-Bend Usage
|
||||
Parametric S-bends bridge lateral gaps without changing the waveguide's orientation.
|
||||
- **Automatic Selection**: If `sbend_offsets` is set to `None` (the default), the router automatically chooses from a set of "natural" offsets (Fibonacci-aligned grid steps) and the offset needed to hit the target.
|
||||
- **Specific Offsets**: To use specific offsets (e.g., 5.86µm for a 45° switchover), provide them in the `sbend_offsets` list. The router will prioritize these but will still try to align with the target if possible.
|
||||
- **Constraints**: S-bends are only used for offsets $O < 2R$. For larger shifts, the router naturally combines two 90° bends and a straight segment.
|
||||
| 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`.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue