Trajectory conversion (trjconv)

The trjconv command extracts a frame from an M-Chem MD trajectory and writes it as a structure file. It is a small analogue of gmx trjconv: give it a topology and a trajectory, and it produces coordinates in a common format.

The current version supports:

  • Topology input: SQLite .db (see M-Chem database (.db) format)

  • Trajectory input: M-Chem HDF5 (QArchive) .h5 / .hdf5

  • Output: single-frame PDB .pdb

The implementation (mchem.trjconv) is organized around three extensible abstractions – mchem.trjconv.TopologyProvider, mchem.trjconv.TrajectoryReader, and mchem.trjconv.TrajectoryWriter – so additional topology formats (e.g. PDB), trajectory formats, and output formats (e.g. XTC) and multi-frame output can be added without changing the mchem.trjconv.trjconv() orchestrator.

Command-line usage

mchem-tools trjconv -p system.db -i md_traj_1.h5 -o frame.pdb -f 10
trjconv options

Option

Meaning

-p / --topology

Topology file (currently .db). Provides atom names, elements, and residue information.

-i / --input

Input M-Chem HDF5 trajectory (.h5).

-o / --output

Output structure file (currently .pdb).

-f / --frame

Frame to extract. Uses the trajectory’s native 1-based index; -1 (the default) selects the last frame.

Note

Frames use the trajectory’s native 1-based numbering, matching the HDF5 time_step groups. Passing -1 (or omitting -f) selects the last frame.

Python API

from mchem.trjconv import trjconv

# Write the last frame (default)
frame = trjconv("system.db", "md_traj_1.h5", "last.pdb")
print(frame.index, frame.time, frame.box)

# Write a specific frame
trjconv("system.db", "md_traj_1.h5", "frame1.pdb", frame=1)

Lower-level building blocks can be used directly, for example to iterate frames:

from mchem.trjconv import DBTopologyProvider, HDF5TrajectoryReader

provider = DBTopologyProvider("system.db")
with HDF5TrajectoryReader("md_traj_1.h5") as reader:
    print(reader.n_frames, "frames")
    for frame in reader:
        coords = frame.coordinates      # (natoms, 3), Angstrom
        box = frame.box                 # (a, b, c), Angstrom

M-Chem HDF5 trajectory format

M-Chem writes trajectories as HDF5 files following the QArchive schema. The reader (mchem.trjconv.HDF5TrajectoryReader) expects the following layout:

/
|- .counters/                              (append/resume bookkeeping)
\- job/
   \- {job_id}/
      \- molecular_dynamics/
         |- natoms                         scalar, number of atoms
         \- time_step/
            |- 1/ ... N/                   one group per saved frame
            |  |- time                     scalar, float64   (ps)
            |  |- coordinates              [3, natoms], float64 (Angstrom)
            |  |- velocity                 [3, natoms], float64 (Angstrom/ps)
            |  |- acceleration             [3, natoms], float64 (Angstrom/ps^2)
            |  \- box                       [3], float64        (Angstrom)

Key conventions:

  • 1-based indexing. Both job and frame (time_step) groups start at 1.

  • Column-major coordinates. coordinates is stored as [3, natoms] (row = X/Y/Z component, column = atom). The reader transposes this to (natoms, 3).

  • Orthorhombic box. box holds cell lengths [Lx, Ly, Lz] in Angstroms; PDB output writes these as a CRYST1 record with 90 degree angles.

  • Units are defined by the schema rather than stored per dataset: coordinates and box in Angstroms, time in picoseconds.

Per-frame datasets (time_step/{frame}/)

Key

dtype

Shape

Notes

time

float64

scalar

Simulation time (ps)

coordinates

float64

[3, natoms]

X/Y/Z by atom (Angstrom)

velocity

float64

[3, natoms]

Angstrom/ps

acceleration

float64

[3, natoms]

Angstrom/ps^2

box

float64

[3]

Orthorhombic lengths (Angstrom)

See also