GR-raytracing/benchmarks/adaptive_step_bounds_2026-10-05/README.md

adaptive_step_bounds_2026-10-05

Long-term benchmark for calibrating the DP54 adaptive-integrator step bounds (min_step / max_step) of the past-directed null-geodesic tracer, and the public record of the one authorised 4K Schwarzschild max_step 2-vs-8 pair.

The benchmark runs the public endpoint geodesic_trace_past(), the production DP core, and bounded adaptive-mesh renders against the analytic Minkowski / Schwarzschild / Alcubierre backends. It does not modify production sources.

Build (required before renderer scripts)

The Python mesh/4K drivers start from an existing renderer binary. The shell endpoint/core drivers compile their own small harnesses against production code.

make -j4 BUILD_TYPE=Release SPACETIME=schwarzschild backend
# binary: build/Release/schwarzschild_sky

Files

file	role
a_public_endpoints.c	Experiment A: step-bound scans through the public endpoint, tol=1e-12 reference, RK4 h-halving on near-critical rays.
b_actual_h.c	Experiment B: textually includes src/geodesic.c, drives the production dp_advance_one on finite trusted intervals to measure observed accepted h.
critical_ref_check.c	Critical-classification probe (r30/r100 inward, r2.1 outward; theta_crit and theta_crit±1e-7; tol/max_step ladder).
mesh_maps.py	Pure GRLENS v3 load/compare; no renderer, no untracked import.
run_mesh.py	8 bounded 320x180 candidates (R100 and R2.1, max_step .5/2/8/32).
run_mesh_reference.py	2 tight-tolerance references and comparisons against the 8 maps.
summarize_4k.py	Postprocess existing maps only; never invokes a renderer.
run_4k_pair.py	One-task, at-most-two-attempt 4K pair; refuses to run without --authorize-two-4k.
record_environment.py	Provenance (git/hashes/compiler/cpu/build/run commands); no render.
failure_floor.c	Failure-path floor diagnostic; includes ../../tests/test_geodesic_adaptive.c.
run_failure_floor.sh	Builds/runs failure_floor.c with -DGEODESIC_EVENT_TESTING.
run_limited.sh	Builds/runs Experiment A + B; all output under OUT_DIR.
run_critical_ref.sh	Builds/runs critical_ref_check.c; all output under OUT_DIR.
summarize.py	OUT_DIR CLI arg (default local/adaptive_step_bounds_2026-10-05); writes OUT_DIR/logs/summary.txt.
results/	Tracked long-term evidence (see below).

Reproduction

AB_OUT="$PWD/local/adaptive_step_bounds_2026-10-05"
OUT="$PWD/local/adaptive_bounds_mesh"

bash  benchmarks/adaptive_step_bounds_2026-10-05/run_limited.sh "$AB_OUT"
bash  benchmarks/adaptive_step_bounds_2026-10-05/run_critical_ref.sh "$AB_OUT"
python3 benchmarks/adaptive_step_bounds_2026-10-05/summarize.py "$AB_OUT"

python3 benchmarks/adaptive_step_bounds_2026-10-05/run_mesh.py "$OUT"
python3 benchmarks/adaptive_step_bounds_2026-10-05/run_mesh_reference.py "$OUT"
bash  benchmarks/adaptive_step_bounds_2026-10-05/run_failure_floor.sh "$OUT"

# 4K only after explicit fresh user authorization for that task:
python3 benchmarks/adaptive_step_bounds_2026-10-05/run_4k_pair.py \
        --authorize-two-4k --out local/adaptive_bounds_4k

Defaults: A/B OUT_DIR is local/adaptive_step_bounds_2026-10-05; mesh OUT_DIR is local/adaptive_bounds_mesh; 4K --out default is local/adaptive_bounds_4k. All logs/CSV go to OUT_DIR; the tracked benchmark directory holds only sources and results/. Scratch binaries go to /tmp/opencode/step_bounds/.

The run_4k_pair.py driver refuses to run without --authorize-two-4k, keeps an attempt ledger, and has no automatic retry. Authorisation does not extend to later tasks or routine tests.

All catalog inputs are generated inline by the scripts (column header longitude_deg,latitude_deg,temperature_K,amplitude, one 1e-30 star); no external survey CSV is read.

Results

1. Public-endpoint step-bound scan (Experiment A/B)

Environment and full table inputs: results/source_environment.txt, results/summary_tables.txt; full stdout: results/expA.log, results/expB.log. Per-ray raw CSV (not tracked) is reproduced by run_limited.sh.

backend	worst near-critical sky error vs tol=1e-12 ref	notes
Schwarzschild r30	2.82e-4 rad (max_step≥1); 8.67e-5 rad at 0.25	r100 8.0e-5 / 2.6e-5; r2.1 2.87e-4
Minkowski	Δn = 0, Δg/g = 0 (analytic)	crossing x/t ≤ 7.7e-11 at max_step≤256
Alcubierre	≤1.8e-10 rad, no class change	8x vs 1x initial RHS cost 4.3x–5.7x

• Dark terminal L−L0 margin agrees with the reference to ≤2.1e-13 in every config; near-critical dark stop times differ up to ~41 time units between tol=1e-9 and tol=1e-12 (orbit-count sensitivity, reported not hidden).
• Schwarzschild floor plateau: min_step 1e-14 … 1e-2 give bit-identical results and RHS; only 0.1 breaks one r1.5 ray (INCOMPLETE/INTEGRATION_ERROR). No evidence to raise the default floor, and no evidence that 1e-12 is uniquely optimal (it is never active).
• Observed accepted h (Experiment B, finite window T=min(20, ref span)): Schwarzschild only — r1.5 radial 0.0921, all other sampled Schwarzschild rays ≥0.1; Alcubierre minimum = its initial step (0.05 / 0.005 / 0.0005); Minkowski 1.0. This is a finite-window diagnostic, not a full-trajectory minimum.
• RK4 h-halving worst (r2.1, theta_crit−1e-7): 1.04e-5 rad.

2. Bounded 320x180 adaptive mesh

Numeric inputs: results/mesh_summary.json, results/mesh_reference_summary.json. Scene: R100/FOV45/jacobian0.2 and R2.1/outward/FOV90; DP54, hmin 1e-12, initial 0.1, tol 1e-9 (tight reference 1e-12), 8 threads, one-point dim catalog.

scene	max_step	persistent vertices	RHS	wall (s)
R100	0.5	3158	16813349	2.071
R100	2	3158	6030185	0.979
R100	8	3158	4230835	0.823
R100	32	3158	4081609	0.830
R2.1	0.5	5496	20136508	1.974
R2.1	2	5496	9548434	1.178
R2.1	8	5496	7389760	0.970
R2.1	32	5496	7197806	0.972

• 2→8 RHS reduction 29.84% (R100) / 22.61% (R2.1); 8→32 only 3.53% / 2.60%.
• Identical terminal classifications and mesh/sample counts for all four caps.
• Error vs tight reference: R100 max sky 9.216e-8 (hmax2) / 8.744e-8 (hmax8), mutual 2-vs-8 difference 7.063e-9 rad; R2.1 max sky 1.4772e-5 rad at both, mutual difference 8.370e-11 rad. The larger R2.1 reference error is tolerance/conditioning sensitive and is not cured by a smaller max_step.
• Max log-frequency differences ≤8.51e-10 (R100) / ≤2.10e-9 (R2.1).
• Short single-run wall times include setup/cache/output; not a timing study.

3. One authorised 4K pair (R100, 3840x2160, FOV45)

Raw terminal output (byte-for-byte): results/4k_hmax2.log, results/4k_hmax8.log; provenance: results/4k_metadata.json, results/4k_attempts.json; postprocessed: results/4k_final_summary.json, results/4k_raw_summary.log.

metric	max_step=2	max_step=8
persistent vertices / triangles	66045 / 131338	66045 / 131338
outcomes	62419 ESC, 3626 DARK	62419 ESC, 3626 DARK
unresolved / error	0	0
persistent accepted	15,768,677	10,183,020
persistent rejected	97,176	194,781
persistent RHS	130,409,139	91,991,144
trace+refine time (s)	10.774	7.805
process wall (s)	11.3893	8.38925

• Triangle payload is bit-identical; shared film identities 66045, terminal mismatches 0; max mutual endpoint sky difference 7.9544e-7 rad, max logg difference 3.4711e-11.
• Persistent-vertex RHS reduction −29.46%; accepted −35.42%; wall −26.34%.
• Cost scope: the v3 map stores final persistent vertices only. The requested-sample count including discarded refinement probes is 116308 (> 66045), so discarded probes contribute no stored cost and these sums must not be read as full-render executed RHS totals.
• Timing: one sequential pair only; no statistical timing confidence.
• PSF splat cached/direct = 0 and --psf-min-y discarded 1965 (hmax2) / 1954 (hmax8) events; this does not measure image error. The PNGs are dark diagnostic backgrounds; no 2MASS catalog was used.

4. Critical-classification reference check

Full output: results/critical_ref.log, results/critical_ref.csv (36 endpoint traces). The exact theta_crit direction is a classification separatrix; it is reported, never asserted.

• r2.1 theta_crit: ref tol1e-12/h0.25 vs tol1e-13/h0.125 sky difference 2.33638 rad — the exactly-critical escape direction is not independently converged. EXACT_CRITICAL_REFERENCE_NOT_CONVERGED.
• r30 theta_crit (DARK) stop-time difference 13.056; r100 theta_crit (DARK) 12.700. At tol1e-11, h2-vs-h8 at r2.1 theta_crit is 5.09e-5 rad.
• Neighbours ±1e-7: both reference tiers agree (same outcome/reason/end, clean, positive steps) at every neighbour. Escaped-neighbour sky differences between the layers are ~1e-7 rad (9.47e-8 r30, 2.74e-8 r100, 1.42e-7 r2.1), consistent with the loose 1e-4 magnitude trend; DARK neighbours report stop-time differences 1.5e-7 … 7.5e-7.
• CRITICAL_REFERENCE_CHECK status=0 (no neighbour reference disagreement or error endpoint).

Decision summary

• Schwarzschild max_step = 8: supported by the far-field cost plateau (2→8 saves ~23–30% persistent RHS; 8→32 only ~3%) together with the tight reference and 4K 2-vs-8 comparisons. This is not claimed as globally optimal and gives no guarantee for arbitrary near-critical/shadow directions.
• min_step = 1e-12: retained as a non-binding numerical guard; not a measured optimum.
• Minkowski max_step = 16 and Alcubierre max_step = 8 × initial: retained as conservative caps. Their bounded accuracy checks support keeping these values, not claiming cost optimality; larger Alcubierre caps still reduce RHS, but have larger frequency errors in some cases.
• The R2.1 exactly-critical difference is tolerance-sensitive; critical_ref_check.c confirms the exact direction is not independently converged and the report does not treat it as certified.

Caveats

• Analytic backends only; no time-dependent numerical-relativity metric was exercised. Bounds and the unit = 1 calibration are not transferable to NR.
• Experiment B samples T = min(20, reference span); no full-trajectory minimum-step claim is made.
• The 4K numbers are one sequential pair; no timing-stability confidence and no image-error bound (inverse-lens-map Jacobian amplification is separate).
• Sky-angle differences divided by pixel angle are not inverse-lens-map image error bounds.
• failure_floor.c reuses the regression invalid-metric temporal-domain fixture; it is not a physical shadow or floor calibration.

Verification of the selected defaults and reproduction tools

make -B -j4 BUILD_TYPE=Debug test passed after selecting the Schwarzschild cap of 8 and adding CLI provenance assertions for the default bounds. Full terminal output is retained locally at local/step_bounds_mesh/final_debug_tests.log (STEP_BOUNDS_FULL_DEBUG_EXIT=0). The explicit-RK4 HDR reference tests remain bit-identical. The Release Schwarzschild binary was rebuilt with the selected default.

The self-contained limited driver was also executed with the relative output path local/step_bounds_reproduction: 1500 endpoint traces and 2427 observed finite-window steps completed, including summary generation. Small angular differences use atan2(|cross|,dot) rather than rounded acos(dot). Running the 4K driver without fresh explicit authorization refuses with exit code 2; this check launches no renderer. No further 4K attempt was made.