jan/inire
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
inire/docs/architecture.md

3.1 KiB
Raw Blame History

Architecture Overview

inire is a single-package Python router with a small stable API at the package root and a larger semi-private implementation under inire.geometry and inire.router.

Stable Surface

  • The supported entrypoint is route(problem, options=...).
  • Stable public types live at the package root and include RoutingProblem, RoutingOptions, NetSpec, Port, RoutingResult, and RoutingRunResult.
  • Deep imports such as inire.router._router.PathFinder and inire.geometry.collision.RoutingWorld are intentionally accessible for advanced workflows, but they are unstable.

Current Module Layout

  • inire/model.py: Immutable request and option dataclasses.
  • inire/results.py: Immutable routing results plus the per-run RouteMetrics snapshot.
  • inire/seeds.py: Serializable path-seed primitives.
  • inire/geometry/primitives.py: Integer Manhattan ports and small transform helpers.
  • inire/geometry/components.py: Straight, Bend90, and SBend geometry generation.
  • inire/geometry/collision.py: Routing-world collision, congestion, ray-cast, and path-verification logic.
  • inire/geometry/static_obstacle_index.py and inire/geometry/dynamic_path_index.py: Spatial-index management for static obstacles and routed paths.
  • inire/router/_search.py, _astar_moves.py, _astar_admission.py, _astar_types.py: The state-lattice A* search loop and move admission pipeline.
  • inire/router/_router.py: The negotiated-congestion driver and refinement orchestration.
  • inire/router/refiner.py: Post-route path simplification for completed paths.
  • inire/router/cost.py and inire/router/danger_map.py: Search scoring and obstacle-proximity biasing.
  • inire/utils/visualization.py: Plotting and diagnostics helpers.

Routing Stack

route(problem, options=...) builds a routing stack composed of:

  1. RoutingWorld for collision state.
  2. DangerMap for static-obstacle proximity costs.
  3. CostEvaluator for move scoring and heuristic support.
  4. AStarContext for caches and search configuration.
  5. PathFinder for negotiated congestion, rip-up/reroute, and refinement.

The search state is a snapped Manhattan (x, y, r) port. From each state the router expands straight segments, 90-degree bends, and compact S-bends, then validates candidates against static geometry, dynamic congestion, and optional self-collision checks.

Notes On Current Behavior

  • Static obstacles and routed paths are treated as single-layer geometry; automatic crossings are not supported.
  • The danger-map implementation uses sampled obstacle-boundary points and a KD-tree, not a dense distance-transform grid.
  • use_tiered_strategy can swap in a cheaper bend proxy on the first congestion iteration.
  • Final RoutingResult validity is determined by explicit post-route verification, not only by search-time pruning.

Performance Visibility

RoutingRunResult.metrics includes both A* counters and index/cache/verification counters. The committed example-corpus baseline for those counters is tracked in docs/performance.md and docs/performance_baseline.json.