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:

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:

from inire import route, RoutingOptions, RoutingProblem

Unstable example:

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:

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 model: "arc", "bbox", "clipped_bbox", or a custom 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.

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

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.