Add first-divergence diagnostics for particle-track comparisons

[JROChub]

Summary

Add a developer CLI that uses openmc.Tracks to identify the first exact difference between two recorded particle histories.

python tools/dev/compare_tracks.py reference/tracks.h5 candidate/tracks.h5

The JSON report distinguishes a match, a mismatch, and invalid input, with exit codes 0, 1, and 2. Histories are aligned by numeric (batch, generation, particle number) identifiers. Within each history, the comparison reports the first differing particle track, recorded state, and field, including binary64 bit patterns and finite-value ULP distances. Missing histories and particle/state count differences are reported separately.

The tool validates schemas, particle counts, and offsets before the existing reader slices the data. It supports both track format 3.0's legacy particle indices and format 3.1's PDG numbers. Comparison excludes HDF5 padding, byte order, and incidental metadata. Signed zeros and NaN payloads are compared exactly.

This is the diagnostic portion of the proposal on #3820. Transport, RNG consumption, the mathematical backend, and the default execution path are unchanged. The documentation explains explicit history selection, secondary-track ordinals, and the distinction between the first differing recorded state and its causative numerical operation.

Related to #3820.

Validation

• 112 focused tests passed. Coverage includes every state field, comparison order, signed zero, subnormals, extreme finite distances, infinities, signaling/quiet NaN payloads, endian/padding differences, both track formats, malformed files, external backing storage, unchanged inputs, and CLI exit statuses.
• The comparator has 96% combined statement/branch coverage in the parent test process. The remaining CLI entry lines are exercised separately by subprocess tests.
• Ruff error/pyflakes checks and git diff --check passed.
• Final focused run used the real native OpenMC library built from base 5260b9a0fc51f3f312024c425a5c1c227f8ba555 (GCC 15.2.0, strict FP enabled): 112 passed in 19.49s.
• Two serial fixed-source runs on that Linux build each recorded 128 primary histories and 2,553 states. Their typed state fields and track structure matched exactly. This smoke case adapts the existing two-group fixed-source regression with fission secondaries and weight windows disabled; it establishes same-build repeatability, not a Linux/macOS result.

Run the focused tests in an OpenMC development environment:

OMP_NUM_THREADS=1 OPENBLAS_NUM_THREADS=1 python -m pytest tests/unit_tests/test_compare_tracks.py -q

These tests create self-contained HDF5 records and do not require nuclear cross-section downloads. OpenMC's generic test-session warning about an unset OPENMC_CROSS_SECTIONS variable remains visible.

The benchmark that reproduces the Linux/macOS difference and the optional math-backend approach are being discussed separately on #3820. This contribution provides the comparison tool for that investigation; it does not introduce a cross-platform math correction.

Checklist

• Reviewed the change against the native track writer and Python reader
• Followed the Python style guidelines
• Added focused tests, including compatibility and malformed-input coverage
• Documented the interface and diagnostic workflow

[JROChub]

@jtramm, could you review this recorded-track comparison interface as a first diagnostic contribution for #3820? It reports exact state differences without changing transport or RNG consumption. I would particularly appreciate your feedback on the report format and which remaining fixed-source macOS failure would be most useful as the first reproducer. Thank you.