TPR (GROMACS run topology files)

Topology parser

MDAnalysis.topology.TPRParser.TPRParser

A GROMACS TPR file is a portable binary run input file. It contains both topology and coordinate information. However, MDAnalysis currently only reads topology information about atoms, bonds, dihedrals, and impropers; it does not read the coordinate information.

Important

Atom ids, residue resids, and molnums

GROMACS indexes atom numbers and residue numbers from 1 in user-readable files. However, the MDAnalysis TPRParser creates atom ids and residue resids from 0. This means that if your atom is numbered 3 in your GRO, ITP, or TOP file, it will have an Atom.id of 2 in MDAnalysis. Likewise, if your residue ALA has a residue number of 4 in your GRO file, it will have a Residue.resid number of 3 in MDAnalysis. Finally, molecules are also numbered from 0, in the attribute molnums.

This will change in version 2.0.0. The TPRParser will number resids, ids, etc. from 1 to be consistent with other formats.

Atom indices and residue resindices are MDAnalysis derived and always index from 0, no matter the file type.

Supported versions

TPR format versions and generations read by MDAnalysis.topology.TPRParser.parse().

TPX format

TPX generation

Gromacs release

read

??

??

3.3, 3.3.1

no

58

17

4.0, 4.0.2, 4.0.3, 4.0.4, 4.0.5, 4.0.6, 4.0.7

yes

73

23

4.5.0, 4.5.1, 4.5.2, 4.5.3, 4.5.4, 4.5.5

yes

83

24

4.6, 4.6.1

yes

100

26

5.0, 5.0.1, 5.0.2, 5.0.3,5.0.4, 5.0.5

yes

103

26

5.1

yes

110

26

2016

yes

112

26

2018

yes

116

26

2019

yes

For further discussion and notes see Issue 2. Please open a new issue in the Issue Tracker when a new or different TPR file format version should be supported.

TPR specification

The TPR reader is a pure-python implementation of a basic TPR parser. Currently the following topology attributes are parsed:

  • Atoms: number, name, type, resname, resid, segid, chainID, mass, charge, [residue, segment, radius, bfactor, resnum, moltype]

  • Bonds

  • Angles

  • Dihedrals

  • Impropers

segid and chainID

MDAnalysis gets the segment and chainID attributes from the TPR molblock field. Since TPR files are built from GROMACS topology files, molblock fields get their names from the compounds listed under the [ molecules ] header. For example:

[ molecules ]
; Compound        #mols
Protein_chain_A     1
Protein_chain_B     1
SOL             40210

So, the TPR will get 3 molblock s: Protein_chain_A, Protein_chain_B and SOL, while MDAnalysis will set the segid s to seg_{segment_index}_{molblock}, thus: seg_0_Protein_chain_A, seg_1_Protein_chain_B and seg_2_SOL. On the other hand, chainID will be identical to molblock unless molblock is named “Protein_chain_XXX”, in which case chainID will be set to XXX. Thus in this case the chainID s will be: A, B and SOL.

Bonds

Bonded interactions available in Gromacs are described in the Gromacs manual. The following ones are used to build the topology (see Issue 463):

GROMACS entries used to create bonds.

Directive

Type

Description

bonds

1

regular bond

bonds

2

G96 bond

bonds

3

Morse bond

bonds

4

cubic bond

bonds

5

connections

bonds

6

harmonic potentials

bonds

7

FENE bonds

bonds

8

tabulated potential with exclusion/connection

bonds

9

tabulated potential without exclusion/connection

bonds

10

restraint potentials

constraints

1

constraints with exclusion/connection

constraints

2

constraints without exclusion/connection

settles

1

SETTLE constraints

GROMACS entries used to create angles.

Directive

Type

Description

angles

1

regular angle

angles

2

G96 angle

angles

3

Bond-bond cross term

angles

4

Bond-angle cross term

angles

5

Urey-Bradley

angles

6

Quartic angles

angles

8

Tabulated angles

angles

10

restricted bending potential

GROMACS entries used to create dihedrals.

Directive

Type

Description

dihedrals

1

proper dihedral

dihedrals

3

Ryckaert-Bellemans dihedral

dihedrals

5

Fourier dihedral

dihedrals

8

Tabulated dihedral

dihedrals

9

Periodic proper dihedral

dihedrals

10

Restricted dihedral

dihedrals

11

Combined bending-torsion potential

GROMACS entries used to create improper dihedrals.

Directive

Type

Description

dihedrals

2

improper dihedral

dihedrals

4

periodic improper dihedral

Developer notes

This tpr parser is written according to the following files

  • gromacs_dir/src/kernel/gmxdump.c

  • gromacs_dir/src/gmxlib/tpxio.c (the most important one)

  • gromacs_dir/src/gmxlib/gmxfio_rw.c

  • gromacs_dir/src/gmxlib/gmxfio_xdr.c

  • gromacs_dir/include/gmxfiofio.h

or their equivalent in more recent versions of Gromacs.

The function read_tpxheader() is based on the TPRReaderDevelopment notes. Functions with names starting with read_ or do_ are trying to be similar to those in gmxdump.c or tpxio.c, those with extract_ are new.

Wherever fver_err(fver) is used, it means the tpx version problem has not been solved. Versions prior to Gromacs 4.0.x are not supported.