GSD file to xtc converter

The gsd2xtc tool converts HOOMD GSD trajectory files into GROMACS XTC files. This is essential when moving from HOOMD-blue simulations to analysis pipelines based on MDAnalysis, GROMACS tools, or the DROPPS ecosystem.

The converter performs:

  • coordinate unit conversion (Å → nm or your internal units)

  • box vector scaling

  • insertion of artificial time stamps

  • frame-by-frame writing using the MDAnalysis XTC writer

Implemented in gsd2xtc.py.

Overview

GSD trajectories often lack:

  • physical box dimensions

  • physical time information

  • consistent length units

gsd2xtc resolves these inconsistencies by:

  1. Loading the GSD file into an MDAnalysis Universe

  2. Scaling coordinates and box lengths by a factor of 10.0 (i.e., converting internal units → nm)

  3. Assigning a time stamp to each frame based on the user-provided --time-step

  4. Writing the modified frames into a compressed and portable XTC trajectory

The output trajectory is immediately usable for DROPPS analysis scripts such as gyrate, density, contact_map, idist, odist, and more.

Usage

Basic conversion:

dps gsd2xtc -f traj.gsd -o traj.xtc

Specify time-step (ns per frame):

dps gsd2xtc -f traj.gsd -o out.xtc -ts 0.25

Arguments

Required

-f, --input FILE

Input GSD trajectory file.

Optional

-o, --output FILE

Output XTC filename. If omitted, extension will be corrected to .xtc by:

output_filename = validate_extension(args.output, "xtc")
-ts, --time-step FLOAT

Time (in ns) assigned to each frame. Default = 0.1 ns.

Internal conversion:

time_step = args.time_step * 1000   # stored in ps for MDAnalysis

Each frame is time-stamped as:

ts.time = time_step + i * time_step

Program Workflow

  1. Load GSD trajectory

u = mda.Universe(args.input)

If box vectors are all zeros:

Warning: No PBC detected. Setting default PBC dimensions.

A cubic box is automatically inserted.

  1. Determine output filename

output_filename = validate_extension(args.output, "xtc")

  1. Coordinate scaling

The script multiplies all coordinates by:

factor = 10.0
ts.positions *= factor

  1. Box scaling

Similarly:

ts.dimensions = [Lx*10, Ly*10, Lz*10, alpha, beta, gamma]

Angles remain unchanged.

  1. Assign time stamps

Using provided --time-step:

ts.time = time_step + i * time_step

  1. Write XTC file

with XTC.XTCWriter(output_filename, n_atoms) as xtc_writer:
    xtc_writer.write(u)

Progress is shown using tqdm.

Example

Convert with default 0.1 ns per frame:

dps gsd2xtc -f polymer.gsd -o polymer.xtc

Convert 100k-frame HOOMD trajectory with 0.02 ns spacing:

dps gsd2xtc -f sim.gsd -o sim.xtc -ts 0.02

Output Details

The resulting XTC contains:

  • properly scaled coordinates (nanometers)

  • properly scaled box vectors

  • sequential timestamps

  • compressed XTC format compatible with:

    • MDAnalysis

    • GROMACS tools

    • DROPPS analysis modules

Error Messages

Common issues include:

GSD file cannot be opened

IOError loading Universe

Invalid output filename

Handled by validate_extension.

Zero box dimensions

A warning appears and a default cubic box is applied.

MDAnalysis XTC writer errors

Occur if input positions become invalid; typically due to corrupted GSD input.

Summary

dps gsd2xtc is a lightweight but powerful converter that transforms HOOMD GSD trajectories into standard GROMACS XTC files. Its main features include:

  • automatic unit scaling

  • box reconstruction

  • time stamping

  • frame-by-frame conversion

  • compatibility with the full DROPPS analysis ecosystem

This tool is essential for workflows where HOOMD-blue simulations must be analyzed alongside other MD engines or integrated into larger pipelines.