85 lines
5.5 KiB
Markdown
85 lines
5.5 KiB
Markdown
# Opt-in observation-window ledger in the DFG runner
|
||
|
||
This test-only integration adds `--exchange-window` to `run_refined_dfg.py`. It uses the
|
||
existing production ledger; no collision, boundary, transfer, physical setup, reference,
|
||
periodicity gate or acceptance threshold changes. Default remains the historical
|
||
per-base-step observation path. Uniform stepping/force accumulation is unchanged.
|
||
|
||
For the refined case, each existing observation interval opens a new ledger at completed
|
||
base step `begin`, advances exactly the same `n` base intervals, and reads the integrated
|
||
root-lattice impulse for `[begin, begin+n]`. The contract requires root units, `window`
|
||
kind, `2*n` fine samples, matching endpoints, and fine dt=.5. The existing coefficient
|
||
calculation still divides this impulse by `n` and `.5*U_lattice**2*D_root`; force timestamps
|
||
remain `(begin+n/2)*U_lattice/D_root`. It does not divide an already averaged force again.
|
||
Pressure/macro/physical-leaf mass measurements and safety checks remain at the original
|
||
interval end. Pilot interval is 80 root steps; early full-run intervals remain 2000, and
|
||
any final shortened interval uses its actual `n`.
|
||
|
||
The opt-in uses one `step(n)` call and one window read per observation, rather than `n`
|
||
Python calls/readbacks. Internal subcycling and per-base synchronization remain owned by
|
||
the same backend. Cooperative deadline checks surround that complete interval; unlike
|
||
the default path they cannot interrupt between base steps inside `step(n)`. The existing
|
||
external hard watchdog is still required. The full-run cadence/cap is documented here,
|
||
but this preparation does not admit a full run or a GPU operation.
|
||
|
||
## Provenance and receipt separation
|
||
|
||
`source_manifest_window.json` pins the reviewed a233c9032487a6006e950d1e327079b00466c410
|
||
snapshot (production ledger origin d930) plus existing helper/reference files. Both SRT
|
||
and MRT are supported by this explicit opt-in source pin; collision selection remains
|
||
independent and shared by the two cases. Existing SRT and MRT manifests are untouched.
|
||
Default mode continues to reject the changed candidate under those historical pins;
|
||
use a matching historical `--source` checkout to run its default path. There is no
|
||
silent repinning, source fallback, or reuse of historical outputs as candidate evidence.
|
||
|
||
Plan, READY, summaries, timeout/comparison receipts now record `observation_mode` as
|
||
`last_base_step` or `window`, alongside collision and actual checkout provenance. On a
|
||
uniform receipt this labels its **paired campaign's refined observation mode**, not a
|
||
change to uniform observation. Full-mode pilot validation rejects missing or mismatched
|
||
mode labels in the plan, either case summary, and either READY receipt. Source/runner
|
||
hash, collision, completeness and health checks remain. Cross-mode pilot reuse is denied.
|
||
|
||
The earlier short A/W/W1 timing/capability evidence is not a full-run speedup or accuracy
|
||
claim. Mathematical impulse integration/units are unchanged; floating-point reduction
|
||
order can differ, so bitwise equality of force sums is not promised. Physics acceptance
|
||
continues to use the existing frozen gates. Historical failures/results are untouched.
|
||
|
||
CPU preparation commands, from the repository root:
|
||
|
||
```sh
|
||
python tests/unit/test_refined_dfg.py
|
||
PYTHONPATH=src python -m unittest tests.unit.test_raw_exchange_window tests.unit.test_time_window_dfg -v
|
||
python tests/validation/run_refined_dfg.py --collision MRT --exchange-window --mode plan --output /tmp/new-window-dfg-plan
|
||
```
|
||
|
||
Root must independently review and admit any execution. An admitted paired pilot uses
|
||
the existing watchdog, device selection, `--gpu-gates-approved`, positive
|
||
`--max-wall-seconds` and a new output directory, adding only `--exchange-window` to the
|
||
selected collision's pilot command. No GPU or remote action was performed for this patch.
|
||
|
||
## Public Jet diagnostic option
|
||
|
||
`--collision MRT --exchange-window --jet-scenario zero|fixed|reverse` selects
|
||
unshifted FP32, no LES, constant transfer on both existing public backends. Default
|
||
`none` and the historical manifests remain unchanged. `zero` registers both Jets at
|
||
zero amplitude and retains every existing DFG verdict, including pressure. `fixed`
|
||
uses outward radial parabolic sectors at pi/2 and 3pi/2, half-width pi/12, peaks
|
||
(+.001,-.001). Both use the existing D40/D80 geometry and U=.01. Sector origins are
|
||
(80.5,81) in root edge coordinates and (160,160.5) in uniform node coordinates;
|
||
radial extent is [0,1.005R]. `reverse` keeps those peaks through t*=300, updates both
|
||
public setters at that completed boundary, and continues to 305 with opposite signs.
|
||
|
||
Fixed diagnostic windows are 250–260, 260–270, 270–280, 280–290 and 290–300; reversal
|
||
adds 300–305. Histories retain exact interval endpoints and root/uniform lattice
|
||
impulses. The refined window uses total exchange; uniform uses public `read_force`
|
||
batch averages. Driven windows report mean/min/max/RMS Cd/Cl without applying DFG
|
||
reference or periodicity gates. Exit zero means healthy execution, not qualification;
|
||
`matched_case_pass` remains false. No independent CV or stress-load claim is made.
|
||
|
||
This opt-in records current source/helper hashes with the existing manifest format,
|
||
checkout revision/dirty state and runner hash. Pilot/full must match that snapshot
|
||
and the exact scenario. It does not relabel current source as historical evidence.
|
||
Use the existing bounded plan/pilot/full commands with the three option flags above;
|
||
full requires the matching completed t*=5 paired pilot. `step_seconds` includes force
|
||
readback; observation/overhead and total wall time are separate, not kernel throughput.
|