# Inire Configuration & API Documentation This document describes the user-tunable parameters for the `inire` auto-router. ## 1. AStarContext Parameters The `AStarContext` stores the configuration and persistent state for the A* search. It is initialized once and passed to `route_astar` or the `PathFinder`. | Parameter | Type | Default | Description | | :-------------------- | :------------ | :----------------- | :------------------------------------------------------------------------------------ | | `node_limit` | `int` | 1,000,000 | Maximum number of states to explore per net. Increase for very complex paths. | | `snap_size` | `float` | 5.0 | Grid size (µm) for expansion moves. Larger values speed up search. | | `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"`. | | `bend_clip_margin` | `float` | 10.0 | Extra space (µm) around the waveguide for clipped models. | ## 2. AStarMetrics The `AStarMetrics` object collects performance data during the search. | 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. | --- ## 3. CostEvaluator Parameters The `CostEvaluator` defines the "goodness" of a path. | 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. | --- ## 3. PathFinder Parameters The `PathFinder` orchestrates multi-net routing using the Negotiated Congestion algorithm. | 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.| --- ## 4. CollisionEngine Parameters | 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. | --- ## 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. --- ## 5. Best Practices & Tuning Advice ### 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. ### 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. Ensure `straight_lengths` includes larger values like `25.0` or `100.0`. 3. Decrease `greedy_h_weight` closer to `1.0`. ### 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. ### 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.