MD trajectory validation ======================== ``tcren.validation.md`` reads recorded, PBC-corrected GROMACS output. Coordinates use angstroms, timestamps use ps, whole-system potential uses kJ/mol, and forces use kJ/mol/nm. These measurements do not estimate affinity. Installed CLI ------------- Use a new output directory for each export. For an already PBC-corrected, continuous multi-model PDB, with explicit ``TITLE t=`` times in ps:: tcren md inspect --trajectory protein-continuous.pdb --reference first.pdb \ --potential potential.xvg --components components.json --mhc-class I \ --pbc-whole --docking -t 1 -o md-inspection ``components.json`` maps nonempty, disjoint component names to lists of chain IDs, for example ``{"TCR": ["A", "B"], "peptide": ["C"], "MHC": ["D"]}``. For class II, pass ``--mhc-class II`` and include **both** groove chains in MHC (for example ``["D", "E"]``). Class is declared by the caller and recorded; it is not inferred from the number of chains. Exports never pool classes. The name ``all`` is reserved for the whole-backbone fit. Each component fit measures every component without a second fit of the measured partner. The correspondence includes chain, sequence index, author residue number, insertion code, atom name and alternate-location label; repeated identities fail. Outputs are ``backbone_atoms.tsv`` (explicit atom/component correspondence), ``rmsd.tsv``, ``contact_counts.tsv``, ``contact_occupancy.tsv``, ``docking.tsv`` (header only when disabled), first/final/minimum-potential PDBs, saved-frame times and minimum-frame JSON, and ``provenance.json``. The latter records source/output hashes, units, class, component mapping, CPU ceiling, searched annotation indexes when docking is enabled, and initial-image check status. Failed inspection is marked ``failed`` rather than complete; existing directories are never overwritten. No predictor confidence is inherited by evolved coordinates. The ``--pbc-whole`` flag acknowledges input preparation; it does not perform or prove unwrapping. Prepare whole molecules, a compact first-frame anchor and continuous images with the GROMACS wrapper below. An absent unit cell is explicitly reported as ``unavailable_no_unit_cell``. No repair is guessed. The CPU ceiling accepts ``-t 1`` (serial), ``-t 0`` (all allocated) or an explicit count within the allocation. Frame inspection and numerical kernels are serial; only the optional single-reference annotation phase uses additional cores, in one TCR query batch and one MHC batch, never a search per frame. The public ``inspect_md_trajectory`` API enforces the same allocation and native-kernel limits. No environment exports are required. Atom-level proximity inspection uses the existing coordinate APIs:: tcren md quality -s predicted.pdb --mhc-class II --cutoff 2.0 -o atom-quality This writes ``coordinate_diagnostics.json`` and ``close_atom_pairs.tsv``, including author residue/atom identities, alternate locations and possible disulfides, with source/output hashes in ``provenance.json``. The strict cutoff is in angstroms. Same-residue/adjacent same-chain exclusions are heuristic; bond classification remains explicitly unknown. No clashscore is inferred. For same-coordinate numerical reruns, including PME-order 4 versus 8:: tcren md compare-forces --reference-energy order8-energy.xvg \ --reference-forces order8-forces.xvg --energy order4-energy.xvg \ --forces order4-forces.xvg --atoms 1000 --topology common.tpr \ --coordinates same-frame.gro --same-system --mhc-class I -o force-comparison Use the actual System-group atom count. XVGs contain one equal timestamp; energies have two columns and forces have time plus three columns per atom. ``comparison.json`` preserves the existing API's energy difference and force errors; provenance retains all four XVGs and declared common-input hashes. ``--same-system`` records a caller assertion, not proof of the XVGs' origin. Preserve both original rerun commands, MDP settings and input checks separately. These serial diagnostics do not run MD, establish PME convergence or estimate binding energy. They do not change an active Stratos simulation. Existing APIs and trajectory preparation ---------------------------------------- * ``component_relative_rmsd(reference, coordinates, components)`` fits each named component and measures every partner in that same frame. * ``inspect_md_trajectory(trajectory_pdb, reference_pdb, components, energy_path)`` streams multi-model PDB frames, verifies chain sequences and atom identities, and returns first, final and minimum-potential saved-frame coordinates. Optional ``contact_cutoff=5.0`` reports heavy-atom residue contacts, including zero-contact chain pairs and occupancy over saved frames. ``docking=True`` annotates the reference once and reports frame-specific docking geometry. * ``minimum_potential_frame`` requires matching saved-frame/energy timestamps; it neither interpolates coordinates nor selects an unsaved energy minimum. * ``compare_same_frame_energy_forces`` compares identical-coordinate reruns. The caller must establish matching topology, coordinates and atom order. * ``energy_drift`` reports NVE drift per ns and per atom without treating correlated frames as independent replicates. Use ``python scripts/inspect_gromacs_trajectory.py --help`` for the GROMACS export wrapper. It makes molecules whole, constructs a compact first-frame anchor, then applies continuous unwrapping before analysis. This preserves later relative motion. The wrapper requires an explicit GROMACS binary, TPR, trajectory, two-column potential XVG, component-to-chain JSON mapping, and a new output directory; command logs and source hashes accompany outputs. The library rejects consecutive C-alpha gaps above 8 angstroms, but this guard cannot detect every incorrect periodic image: input preparation remains required. ``tcren.validation.structures`` supplies sequence-verified component mapping, coordinate diagnostics and explicit nonlocal close-atom pairs. Proximity pairs are not a MolProbity clashscore. Original simulations and private campaign orchestration are outside this library change.