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
• 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:

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:

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.