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/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. The committed example-corpus counter baseline is tracked in docs/performance.md.

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.