inire/docs/performance.md

Performance Baseline

Generated on 2026-04-02 by scripts/record_performance_baseline.py.

The full machine-readable snapshot lives in docs/performance_baseline.json. Use scripts/diff_performance_baseline.py to compare a fresh run against that snapshot.

The default baseline table below covers the standard example corpus only. The heavier example_07_large_scale_routing_no_warm_start canary remains performance-only and is tracked through targeted diffs plus the conflict/frontier trace artifacts.

Use scripts/characterize_pair_local_search.py when you want a small parameter sweep over example_07-style no-warm runs instead of a single canary reading. The current tracked sweep output lives in docs/pair_local_characterization.json and docs/pair_local_characterization.md. Use scripts/record_iteration_trace.py when you want a seed-42 vs seed-43 negotiated-congestion attribution run; the current tracked output lives in docs/iteration_trace.json and docs/iteration_trace.md.

Scenario	Duration (s)	Total	Valid	Reached	Iter	Nets Routed	Nodes	Ray Casts	Moves Gen	Moves Added	Dyn Tree	Visibility Builds	Congestion Checks	Verify Calls
example_01_simple_route	0.0040	1	1	1	1	1	2	10	11	7	0	0	0	4
example_02_congestion_resolution	0.3378	3	3	3	1	3	366	1164	1413	668	0	0	0	38
example_03_locked_paths	0.1929	2	2	2	2	2	191	657	904	307	0	0	0	16
example_04_sbends_and_radii	0.0279	2	2	2	1	2	15	70	123	65	0	0	0	8
example_05_orientation_stress	0.2367	3	3	3	2	6	299	1284	1691	696	0	0	149	18
example_06_bend_collision_models	0.1998	3	3	3	3	3	240	682	1026	629	0	0	0	12
example_07_large_scale_routing	0.2005	10	10	10	1	10	78	383	372	227	0	0	0	40
example_08_custom_bend_geometry	0.0176	2	2	2	2	2	18	56	78	56	0	0	0	8
example_09_unroutable_best_effort	0.0058	1	0	0	1	1	3	13	16	10	0	0	0	1

Full Counter Set

Each scenario entry in docs/performance_baseline.json records the full RouteMetrics snapshot, including cache, index, congestion, and verification counters. These counters are currently observational only and are not enforced as CI regression gates.

For the current accepted branch, the most important performance-only canary is example_07_large_scale_routing_no_warm_start, which now finishes 10/10/10 after a bounded post-loop pair-local scratch reroute. The relevant counters for that phase are:

• pair_local_search_pairs_considered
• pair_local_search_attempts
• pair_local_search_accepts
• pair_local_search_nodes_expanded

The latest tracked characterization sweep confirms there is no smaller stable pair-local smoke case under the <=1.0s rule, so the 10-net no-warm-start canary remains the primary regression target for this behavior.

The tracked iteration trace adds one more diagnosis target: example_07_large_scale_routing_no_warm_start_seed43. That seed now remains performance-only, and its blowup is concentrated in late iterations rather than the initial basin. In the current trace, seed 43 matches seed 42 through iteration 5, then spends three extra iterations with 4 completed nets while net_03 and net_06 dominate both nodes_expanded and congestion_check_calls.

Tracked metric keys:

nodes_expanded, moves_generated, moves_added, pruned_closed_set, pruned_hard_collision, pruned_cost, route_iterations, nets_routed, nets_reached_target, warm_start_paths_built, warm_start_paths_used, refine_path_calls, timeout_events, iteration_reverify_calls, iteration_reverified_nets, iteration_conflicting_nets, iteration_conflict_edges, nets_carried_forward, score_component_calls, score_component_total_ns, path_cost_calls, danger_map_lookup_calls, danger_map_cache_hits, danger_map_cache_misses, danger_map_query_calls, danger_map_total_ns, move_cache_abs_hits, move_cache_abs_misses, move_cache_rel_hits, move_cache_rel_misses, guidance_match_moves, guidance_match_moves_straight, guidance_match_moves_bend90, guidance_match_moves_sbend, guidance_bonus_applied, guidance_bonus_applied_straight, guidance_bonus_applied_bend90, guidance_bonus_applied_sbend, static_safe_cache_hits, hard_collision_cache_hits, congestion_cache_hits, congestion_cache_misses, congestion_presence_cache_hits, congestion_presence_cache_misses, congestion_presence_skips, congestion_candidate_precheck_hits, congestion_candidate_precheck_misses, congestion_candidate_precheck_skips, congestion_grid_net_cache_hits, congestion_grid_net_cache_misses, congestion_grid_span_cache_hits, congestion_grid_span_cache_misses, congestion_candidate_nets, congestion_net_envelope_cache_hits, congestion_net_envelope_cache_misses, dynamic_path_objects_added, dynamic_path_objects_removed, dynamic_tree_rebuilds, dynamic_grid_rebuilds, static_tree_rebuilds, static_raw_tree_rebuilds, static_net_tree_rebuilds, visibility_corner_index_builds, visibility_builds, visibility_corner_pairs_checked, visibility_corner_queries_exact, visibility_corner_hits_exact, visibility_point_queries, visibility_point_cache_hits, visibility_point_cache_misses, visibility_tangent_candidate_scans, visibility_tangent_candidate_corner_checks, visibility_tangent_candidate_ray_tests, ray_cast_calls, ray_cast_calls_straight_static, ray_cast_calls_expand_snap, ray_cast_calls_expand_forward, ray_cast_calls_visibility_build, ray_cast_calls_visibility_query, ray_cast_calls_visibility_tangent, ray_cast_calls_other, ray_cast_candidate_bounds, ray_cast_exact_geometry_checks, congestion_check_calls, congestion_lazy_resolutions, congestion_lazy_requeues, congestion_candidate_ids, congestion_exact_pair_checks, verify_path_report_calls, verify_static_buffer_ops, verify_dynamic_candidate_nets, verify_dynamic_exact_pair_checks, refinement_windows_considered, refinement_static_bounds_checked, refinement_dynamic_bounds_checked, refinement_candidate_side_extents, refinement_candidates_built, refinement_candidates_verified, refinement_candidates_accepted, pair_local_search_pairs_considered, pair_local_search_attempts, pair_local_search_accepts, pair_local_search_nodes_expanded