FileFormats

Notes on file formats.

Coordinates

DCD

(From PR #1155)

Updated table from https://github.com/MDAnalysis/mdanalysis/issues/187#issuecomment-89474316, taking @peastman's https://github.com/mdtraj/mdtraj/pull/1163#issuecomment-237360771 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 table summarizes our current understanding of the DCD variants (please comment!). h1, h2, h3 are the box vectors.

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

I kept time 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 I think 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 I got confused. — I am more than happy to change this 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.)

• The comments in the dcd.c source say that "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 I changed the NAMD < 2.5 to NAMD ≤ 2.5.