[cekees]

C1.1. The archive of record was assembled at close: per-step grid metadata went into the HDF5 as it was produced, and the document describing it was built from that only when close() ran. A run that was killed, hit a scheduler timeout or died on one rank left an archive with the data in it and nothing describing the data — recoverable, but only by a separate pass, which is what scripts/gatherArchives.py exists for.

Depends on cekees/ymf#18, which must merge first — proteus CI installs ymf from @main, so CI here fails until it lands.

Each step is appended, not rewritten

The first version of this rewrote the whole document each step. On review that is the wrong shape: O(steps) per step, O(steps²) over a run, and many proteus runs have very large numbers of steps. The requirement that a document be rewritten to stay well formed is inherited from XML; YAML has no such rule.

steps	rewrite	append
10	0.6 ms	0.10 ms
100	6.8 ms	0.11 ms
500	35 ms	0.09 ms
5000	≈350 ms	0.11 ms
5000 cumulative	≈15 min (extrapolated)	0.49 s

Flat per step — the write no longer depends on what the archive already holds.

How it fits together

• master already holds this step's grids while allGatherIncremental runs, so a record costs no extra HDF5 read and no extra YAML parse;
• the header is written to <name>.ymf.writing and renamed; the records after it need no such care, because each ends with the document-end marker that tells a reader it is complete;
• records name their collection rather than indexing the header's list, because proteus creates collections lazily — one per archived FE space, of which there are 13 possible — so a model first archiving at step 40 adds one then;
• a failed append is logged and swallowed. The step is in the HDF5 regardless, and the authoritative document is still written at close;
• close() still writes the canonical single document, so a finished run leaves exactly what it leaves today. Only an interrupted run is in the live shape, and read_ymf takes both;
• writeIncrementalYmf = False restores writing only at close.

Tests (11 new; file goes 33 → 44)

• test_an_interrupted_run_still_leaves_a_readable_document — the point. Steps are synced, close() never happens, the document is complete and correct.
• test_what_it_looked_like_before — the control, same run with the feature off: asserts there is no .ymf at all, so the first is not a tautology.
• test_the_running_document_agrees_with_the_one_written_at_close — the appended stream is folded by the reader; the closing document is re-assembled from YAML in the HDF5. Different code, different sources, same result required. If they diverged, the archive of record would depend on whether the run finished, which is what this removes.
• test_the_running_document_is_appended_not_rewritten — pins the mechanism: one --- and one ... per step, mid-run.
• test_close_leaves_a_single_document — and the live shape does not leak into finished archives.
• plus both layouts, 2 and 3 ranks under mpiexec, and no .writing left behind.

The rank script gained SKIP_CLOSE and NO_INCREMENTAL so an interrupted run is simulated faithfully rather than approximated.

Testing

310 passed, 10 skipped, 1 failed across all six archive files plus test_adr_problem.py and test_pro_cli.py. The failure is test_an_l_shaped_region_converges_at_second_order, in the known pre-existing set verified on a clean tree.

Follow-on

This removes gatherArchives's reason to exist. The script is still shipped (setup.py:1136) and tested, so retiring it is a separate call — ERDC_ISSUE_TRIAGE.md has it as a Tier C close candidate.

🤖 Generated with Claude Code