Trajectory converter

The trjconv tool reads an existing trajectory and converts, extracts, or rewrites it with options for:

  • frame selection (start / end / interval),

  • atom/molecule-based PBC treatment,

  • atom-group selection for output,

  • output format conversion (XTC ↔ PDB),

  • index-group based workflow.

It is the DROPPS/CGPS equivalent of GROMACS trjconv, using MDAnalysis as the transformation engine.

Implemented in trjconv.py.

Overview

dps trjconv performs:

  1. Load a complete simulation using: - a DROPPS TPR file (runtime information), - a trajectory file (XTC), - an index file (optional).

  2. Convert time → frame indices using the metadata stored in the TPR.

  3. Apply MDAnalysis coordinate transformations: - atom-level wrapping - molecule-level wrapping + unwrapping

  4. Interactively select atom groups for PBC treatment and for output.

  5. Write output to: - .xtc for compressed trajectory, - .pdb for coordinate snapshots.

Output frames follow the user-defined slicing in time.

Usage

Basic conversion:

dps trjconv -s run.tpr -f traj.xtc -o out.xtc -pbc none

Extract every 10 ns:

dps trjconv -s run.tpr -f traj.xtc -o slim.xtc \
    -b 0 -e 200 -dt 10 -pbc atom

Arguments

Required

-s, --run-input FILE

DROPPS .tpr runtime file (produced by dps grompp). Provides metadata: box, MD parameters, time-step, etc.

-f, --input FILE

Input trajectory (XTC).

-pbc {none, atom, mol}

Algorithm for treating periodic boundary conditions:

  • none — no correction

  • atom — wrap each atom independently

  • mol — wrap + unwrap a molecule as a whole

Optional

-n, --index FILE

Optional index file containing custom groups.

-o, --output FILE

Output trajectory file. Allowed extensions: - .xtc - .pdb

Any other extension triggers:

ERROR: Cannot write trajectory with extention ...
-b, --start-time INT

First frame to write, specified in nanoseconds.

-e, --end-time INT

Last frame to write, also in ns.

-dt, --delta-time INT

Interval between frames, in ns.

Interactive Selections

trjconv uses DROPPS’ interactive index-group system:

### 1. PBC selection (if pbc ≠ none)

Triggered by:

selection_wrap, _ = trajectory.getSelection_interactive()

Depending on --pbc:

  • atom → apply wrapping

  • mol → apply wrapping + unwrapping

The actual transformations:

transformations.wrap(selection)
transformations.unwrap(selection)

are then registered on the trajectory.

### 2. Output-group selection

Before writing output, the user selects the set of atoms to write:

selection_output, selection_output_name = \
    trajectory.getSelection_interactive("Group for output …")

Frame Selection

The time-to-frame mapping is handled by:

start_frame, end_frame, interval_frame = \
    trajectory.time2frame(b, e, dt)

Time is interpreted in ns, matching the MDP parameters.

Workflow

Complete workflow from the implementation

### 1. Load trajectory

trajectory = trajectory_class(args.run_input,
                              args.index,
                              args.input)

Failure produces:

## An exception occurred when trying to open trajectory file ...

### 2. Time slicing → frame slicing

start_frame, end_frame, interval = trajectory.time2frame()

### 3. Apply PBC transformations

For example, in molecule mode:

workflow = [wrap(selection), unwrap(selection)]
trajectory.Universe.trajectory.add_transformations(*workflow)

### 4. Determine output format

file_ext = splitext(args.output)[1].lower()

Allowed: .pdb or .xtc.

### 5. Select atoms for output

User chooses group interactively.

### 6. Write trajectory

with Writer(output_trajectory, n_atoms) as writer:
    for ts in Universe.trajectory[start:end:step]:
        writer.write(selection_output)

REPORT:

## Trajectory written to file out.xtc

Output Formats

### XTC Output

  • compressed, fast, portable

  • one frame per time slice

  • positions only

### PDB Output

  • writes one frame per snapshot

  • good for visualization or testing

  • may generate multiple MODEL records automatically (depends on MDAnalysis writer)

Error Messages

Unknown extension

ERROR: Cannot write trajectory to file.ext

Trajectory load failed

Usually indicates a missing or corrupted XTC file.

Interactive selection cancelled

User aborted interactive group selection (current behavior is to exit silently).

Summary

dps trjconv is a versatile, MDAnalysis-powered converter for DROPPS trajectories. It enables:

  • PBC wrapping/unwrap on atom or molecule groups

  • extraction of time windows

  • interpolation-free slicing (exact frame stepping)

  • interactive group-based selections

  • export of cleaned, wrapped, or trimmed trajectories

It plays the same role in DROPPS as trjconv does in GROMACS, and is widely used before analysis (density, gyration, ID/OD distributions, contact maps).