Oliver Beckstein edited this page Mar 23, 2018 · 5 revisions

Notes on file formats.



(From PR #1155)

The DCD file format is not well defined. It originated with CHARMM but there is no official description of the format on the CHARMM website. NAMD also uses the format, and they have recently been defining their version of DCD in NAMD file formats. LAMMPS can work with DCD files as well (the LAMMPS DCD code was written by @nmichaud).

The table summarizes our current understanding of the DCD variants (please comment!). h1, h2, h3 are the box vectors.

code version unitcell time length first frame
CHARMM <22 ? A,B,C,cos(α),cos(β),cos(γ) AKMA Å 1
≥22 ? h1, h2, h3 (symmetric) AKMA Å 1
NAMD ≤ 2.5 A,B,C,α,β,γ (in degrees) ps(??) Å 1 (?)
> 2.5 A,B,C,cos(α),cos(β),cos(γ) AKMA Å 1 (?)
LAMMPS ?A,B,C,cos(α),cos(β),cos(γ) ps Å ?
? user-def user-def ?

Unit cell

The comments in the dcd.c source say for "A,B,C,α,β,γ" "This file was generated by Charmm, or by NAMD > 2.5, with the angle cosines of the periodic cell angles written to the DCD file. " Thus we list the old box information for NAMD ≤ 2.5.


Updated table from #187, taking @peastman's mdtraj/mdtraj#1163 into account that NAMD 2.9 (at least) stores time in DCD files in AKMA units (see NAMD file formats; in NAMD 2.5 this was not well defined)

NAMD 2.9 DCD format:

The timestep is stored in the DCD file in NAMD internal units and must be multiplied by TIMEFACTOR=48.88821 to convert to fs. Positions in DCD files are stored in Å.

The time is listed in ps for NAMD <2.5 because the first time it is explicitly defined as AKMA is in the NAMD 2.8 DCD docs and @orbeckst thinks we did some trial-and-error on earlier NAMD files that only made sense when interpreted as ps. Or the original catdcd code did the conversion somewhere in the C layer and @orbeckst got confused. — this should be changed as soon as better data comes along.

Also note

Velocities in DCD files are stored in NAMD internal units and must be multiplied by PDBVELFACTOR=20.45482706 to convert to Å/ps. Forces in DCD files are stored in kcal/mol/Å.

(Only relevant if we ever want to read DCD files as containing velocities or forces.)

First frame

The first frame in CHARMM DCD is istart/nsavc where nsavc is the integrator time steps per saved time step and istart the number of integrator timesteps before the first saved frame. The CHARMM docs (Example under TRAJECTORY command) imply that the DYNAmics command does indeed start saving after the coordinates with the initial conditions:

Example. Assume that the three files traj1.trj, traj2.trj and traj3.trj were created using the following dyanmics commands:

dyna start nstep 1000 nsavc 100 ! saves 10 frames (100, 200, ...1000) 

From the comments it is clear that the first frame starts at integrator time step 100 and thus should be labeled as "frame 1". Other simulation packages such as Gromacs also write the initial frame to the trajectory and hence a Gromacs XTC or TRR file starts at frame 0.

More discussion see PR #1832 and PR #1767.

Project Information

GNU GPL v2 code license
Labels: python, molecular dynamics, analysis, DCD, CHARMM, LAMMPS, NAMD, Gromacs, computer simulation, atoms, coordinates, trajectory, XTC, Library, object-oriented
Core Developers


Release Notes
Guide for Developers
Google Summer of Code

Code of Conduct


@mdanalysis on Twitter
Downloads (PyPi)
Mailing Lists:
User discussion group
Developer mailing list

Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.