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.