Unwrapping Periodic Xyz Trajectories

Common Pitfalls

• Using MIC alone and assuming it always fixes bonds.
  Evidence: multiple runs initially produced remaining 4–5 Å bonded distances after MIC-only traversal.
• Reformatting frame 1 coordinates.
  Evidence: one run failed its own exact check because writing 10.500000 changed original text 10.5.
• Validating only structure, not chemistry.
  File shape can be correct while bonded pairs still violate threshold.
• Assuming chain topology without using provided bonds.
  Works on simple examples but reduces generality; use bond file as source of truth.

Verification Strategy

Run verification immediately after writing output:

1. Schema checks

   • Output file exists and is non-empty.
   • Frame count and atom counts per frame match input.
   • Atom symbols and box comment lines preserved.

2. Reference-frame immutability

   • Compare frame 1 block against input.
   • If requirement says “exactly unchanged,” use raw line equality (not float-tolerance).

3. Bond-distance checks

   • For every frame and every bond, compute Euclidean distance.
   • Fail if any distance exceeds threshold (e.g., 2.0 Å + tiny epsilon).
   • Print worst offending frame/bond for fast debugging.

4. Final harness check

   • Execute provided tests (pytest /tests/test_outputs.py) to confirm all contract checks pass.

References to Load On Demand

• MIC formula per axis: d' = d - L * round(d/L)
• Graph unwrapping pattern: BFS parent placement from anchor
• Temporal fallback pattern: substitute previous-frame bond vector when current-frame wrapped data is ambiguous or corrupted