FileFormats

Notes on file formats.

Coordinates

DCD

(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.

Units

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) dyna restart nstep 10000 nsavc 100 ! saves 100 frames (1100, 1200, ...10100) dyna restart nstep 10000 nsavc 100 ! saves 100 frames (10200, 10300, ...20100)

More discussion see PR #1832 and PR #1767.