5.21. Gromacs portable run input TPR format parser

The TPRParser module allows reading of a Gromacs portable run input file (a TPR file). Because the file format of the TPR file is changing rapidly, not all versions are currently supported. The known working versions and the approximate Gromacs release numbers are listed in the table TPR format 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

119

27

2020[*]_

yes

122

28

2021

yes

127

28

2022

yes

129

28

2023

yes

133

28

2024.1

yes

134

28

2024.4

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.

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

  • bonds: regular bonds (type 1), G96 bonds (type 2), Morse (type 3), cubic bonds (type 4), connections (type 5), harmonic potentials (type 6), FENE bonds (type 7), restraint potentials (type 10), tabulated potential with exclusion/connection (type 8), tabulated potential without exclusion/connection (type 9), constraints with exclusion/connection (type 1), constraints without exclusion/connection (type 2), SETTLE constraints

  • angles: regular angles (type 1), G96 angles (type 2), cross bond-bond (type3), cross-bond-angle (type 4), Urey-Bradley (type 5), quartic angles (type 6), restricted bending potential (type 10), tabulated angles (type 8)

  • dihedrals: proper dihedrals (type 1 and type 9), Ryckaert-Bellemans dihedrals (type 3), Fourier dihedrals (type 5), restricted dihedrals (type 10), combined bending-torsion potentials (type 11), tabulated dihedral (type 8)

  • impropers: improper dihedrals (type 2), periodic improper dihedrals (type 4)

5.21.1. Classes

class MDAnalysis.topology.TPRParser.TPRParser(filename)[source]

Read topology information from a Gromacs TPR file.

close()

Close the trajectory file.

convert_forces_from_native(force, inplace=True)

Conversion of forces array force from native to base units

Parameters:

  • force (array_like) – Forces to transform

  • inplace (bool (optional)) – Whether to modify the array inplace, overwriting previous data

Note

By default, the input force is modified in place and also returned. In-place operations improve performance because allocating new arrays is avoided.

Added in version 0.7.7.

convert_forces_to_native(force, inplace=True)

Conversion of force array force from base to native units.

Parameters:

  • force (array_like) – Forces to transform

  • inplace (bool (optional)) – Whether to modify the array inplace, overwriting previous data

Note

By default, the input force is modified in place and also returned. In-place operations improve performance because allocating new arrays is avoided.

Added in version 0.7.7.

convert_pos_from_native(x, inplace=True)

Conversion of coordinate array x from native units to base units.

Parameters:

  • x (array_like) – Positions to transform

  • inplace (bool (optional)) – Whether to modify the array inplace, overwriting previous data

Note

By default, the input x is modified in place and also returned. In-place operations improve performance because allocating new arrays is avoided.

Changed in version 0.7.5: Keyword inplace can be set to False so that a modified copy is returned unless no conversion takes place, in which case the reference to the unmodified x is returned.

convert_pos_to_native(x, inplace=True)

Conversion of coordinate array x from base units to native units.

Parameters:

  • x (array_like) – Positions to transform

  • inplace (bool (optional)) – Whether to modify the array inplace, overwriting previous data

Note

By default, the input x is modified in place and also returned. In-place operations improve performance because allocating new arrays is avoided.

Changed in version 0.7.5: Keyword inplace can be set to False so that a modified copy is returned unless no conversion takes place, in which case the reference to the unmodified x is returned.

convert_time_from_native(t, inplace=True)

Convert time t from native units to base units.

Parameters:

  • t (array_like) – Time values to transform

  • inplace (bool (optional)) – Whether to modify the array inplace, overwriting previous data

Note

By default, the input t is modified in place and also returned (although note that scalar values t are passed by value in Python and hence an in-place modification has no effect on the caller.) In-place operations improve performance because allocating new arrays is avoided.

Changed in version 0.7.5: Keyword inplace can be set to False so that a modified copy is returned unless no conversion takes place, in which case the reference to the unmodified x is returned.

convert_time_to_native(t, inplace=True)

Convert time t from base units to native units.

Parameters:

  • t (array_like) – Time values to transform

  • inplace (bool, optional) – Whether to modify the array inplace, overwriting previous data

Note

By default, the input t is modified in place and also returned. (Also note that scalar values t are passed by value in Python and hence an in-place modification has no effect on the caller.)

Changed in version 0.7.5: Keyword inplace can be set to False so that a modified copy is returned unless no conversion takes place, in which case the reference to the unmodified x is returned.

convert_velocities_from_native(v, inplace=True)

Conversion of velocities array v from native to base units

Parameters:

  • v (array_like) – Velocities to transform

  • inplace (bool (optional)) – Whether to modify the array inplace, overwriting previous data

Note

By default, the input v is modified in place and also returned. In-place operations improve performance because allocating new arrays is avoided.

Added in version 0.7.5.

convert_velocities_to_native(v, inplace=True)

Conversion of coordinate array v from base to native units

Parameters:

  • v (array_like) – Velocities to transform

  • inplace (bool (optional)) – Whether to modify the array inplace, overwriting previous data

Note

By default, the input v is modified in place and also returned. In-place operations improve performance because allocating new arrays is avoided.

Added in version 0.7.5.

parse(tpr_resid_from_one=True, **kwargs)[source]

Parse a Gromacs TPR file into a MDAnalysis internal topology structure.

Parameters:

tpr_resid_from_one (bool (optional)) – Toggle whether to index resids from 1 or 0 from TPR files. TPR files index resids from 0 by default, even though GRO and ITP files index from 1.

Returns:

structure

Return type:

dict

Changed in version 1.1.0: Added the tpr_resid_from_one keyword to control if resids are indexed from 0 or 1. Default False.

Changed in version 2.0.0: Changed to tpr_resid_from_one=True by default.

units = {'length': None, 'time': None, 'velocity': None}

dict with units of of time and length (and velocity, force, … for formats that support it)

See also

MDAnalysis.topology.tpr

5.21.2. Development notes

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

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

  • Bonds

  • Angles

  • Dihedrals

  • Impropers

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.

Versions prior to Gromacs 4.0.x are not supported.

Changed in version 2.0.0: The elements topology attribute is now exposed if at least one atom has a valid element symbol. In that case, atoms for which the element is not recognized have their element attribute set to an empty string. If none of the elements are recognized, then the elements attribute is not set in the topology.

Changed in version 2.7.0: If the TPR molblock is named “Protein_chain_XXX” then we assume that XXX is describing the chain of a protein (in the sense of the PDB chainID) and set the topology attribute chainID to “XXX”. In all other cases, the chainID remains the full molblock name. The segID is never changed.