CelerisLab/docs/validation/refined_dfg_timing.md

Refined DFG MRT timing harness (measurement only)

tests/validation/time_refined_dfg.py times the matched MRT refined/uniform DFG Re100 setup of run_refined_dfg.py (same configuration, geometry and initial state functions). No numerical, physics-gate or production change; no force or accuracy result is produced.

Variant	Loop	Force reads
A	refined step(1) + read_raw_exchange per base step	runner-like force-read workload (values discarded)
B	refined step(1) only, no host reads (observe_raw_exchange stays on)	timing-only
C	refined single step(N)	timing-only; ledger keeps the final base interval only
E	uniform sim.run(<=100) + read_force	runner-like force-read workload (values discarded)
E'	uniform single sim.run(2N)	timing-only; at most a whole-window average, different summation order

• No variant retains a valid force history; A/E omit the runner's interval aggregation and validation, and no variant includes macro/probe/CSV costs. Results are not full benchmark throughput.
• Status lines: CONSTRUCTED (construction/JIT complete) and WARM_READY (first warm-up and health check passed) per case.
• Equal simulated duration: N refined base steps vs 2N uniform D80 steps.
• Every repeat starts from the same fresh state (refined initialize, uniform snapshot/restore) and the same warm-up; construction/JIT, warm-up, downloads and parity checks are untimed.
• The actual stepping stream is synchronized explicitly before and after each timed loop; the wall timer (time.perf_counter) is the only source. No CUDA-event span is called kernel time.
• --max-wall-seconds is required for GPU runs (outer timeout, checked between variants and every 100 steps in per-step loops).
• Final populations and NaN masks must be bitwise identical to the first A repeat (A/B/C) or the first E repeat (E/E'); refined and uniform grids are never compared. Leaf/fluid populations must be finite. Physical health (finite leaf/fluid macros, rho in [0.5, 1.5], max Mach <= 0.2, the existing runner limits) is checked after warm-up and after each timed window. Matching NaN is accepted only as a storage mask; any infinity or level-count mismatch fails parity. All parity/health checks are untimed.
• Cases run sequentially (uniform, then refined) in one process with startup serialized; variants are interleaved within each repeat. A-B and B-C are measured comparative differences under GPU variability, not exact causal decompositions.

Usage (root selects one verified idle GPU):

PYTHONPATH=src python -m unittest tests/unit/test_time_refined_dfg.py
python tests/validation/time_refined_dfg.py --output <new> --plan
CUDA_VISIBLE_DEVICES=<gpu> python tests/validation/time_refined_dfg.py --output <new> --max-wall-seconds <s>

Defaults: 2000 base steps, 200 warm-up base steps, 3 repeats. Profiler capture and the observe_raw_exchange=False variant are deferred until these measurements exist.

A versus observation-window ledger (tests/validation/time_window_dfg.py)

Measurement-only comparison on the same shifted-MRT refined setup: A (per-base step(1) + read_raw_exchange, summed per 80-base-step interval), W (start_exchange_window, step(80), one window read) and W1 (window with 80 x step(1), isolating the read pattern from call batching). Same fresh state, warm-up and simulated duration; populations must be bitwise equal to the first A repeat and per-interval total impulses within the documented engineering tolerance, all outside timing. The candidate source is recorded (checkout revision, dirty flag, file hashes); frozen refined-DFG manifests/results are not used or changed.

PYTHONPATH=src python -m unittest tests/unit/test_time_window_dfg.py
python tests/validation/time_window_dfg.py --output <new> --plan
CUDA_VISIBLE_DEVICES=<gpu> python tests/validation/time_window_dfg.py --output <new> --max-wall-seconds <s>