6.8. GRO file format — MDAnalysis.coordinates.GRO

Classes to read and write Gromacs GRO coordinate files; see the notes on the GRO format which includes a conversion routine for the box.

6.8.1. Writing GRO files

By default any written GRO files will renumber the atom ids to move sequentially from 1. This can be disabled, and instead the original atom ids kept, by using the reindex=False keyword argument. This is useful when writing a subsection of a larger Universe while wanting to preserve the original identities of atoms.

For example:

>>> u = mda.Universe()`

>>> u.atoms.write('out.gro', reindex=False)

# OR
>>> with mda.Writer('out.gro', reindex=False) as w:
...     w.write(u.atoms)

6.8.2. Classes

class MDAnalysis.coordinates.GRO.Timestep(n_atoms, **kwargs)[source]

Timestep data for one frame

Methods:

ts = Timestep(n_atoms)

create a timestep object with space for n_atoms

Changed in version 0.11.0: Added from_timestep() and from_coordinates() constructor methods. Timestep init now only accepts integer creation. n_atoms now a read only property. frame now 0-based instead of 1-based. Attributes status and step removed.

Changed in version 2.0.0: Timestep now can be (un)pickled. Weakref for Reader will be dropped. Timestep now stores in to numpy array memory in ‘C’ order rather than ‘F’ (Fortran).

Create a Timestep, representing a frame of a trajectory

Parameters:
  • n_atoms (int) – The total number of atoms this Timestep describes
  • positions (bool, optional) – Whether this Timestep has position information [True]
  • velocities (bool (optional)) – Whether this Timestep has velocity information [False]
  • forces (bool (optional)) – Whether this Timestep has force information [False]
  • reader (Reader (optional)) – A weak reference to the owning Reader. Used for when attributes require trajectory manipulation (e.g. dt)
  • dt (float (optional)) – The time difference between frames (ps). If time is set, then dt will be ignored.
  • time_offset (float (optional)) – The starting time from which to calculate time (in ps)

Changed in version 0.11.0: Added keywords for positions, velocities and forces. Can add and remove position/velocity/force information by using the has_* attribute.

copy()[source]

Make an independent (“deep”) copy of the whole Timestep.

copy_slice(sel)[source]

Make a new Timestep containing a subset of the original Timestep.

Parameters:sel (array_like or slice) – The underlying position, velocity, and force arrays are sliced using a list, slice, or any array-like.
Returns:A Timestep object of the same type containing all header information and all atom information relevant to the selection.
Return type:Timestep

Note

The selection must be a 0 based slice or array of the atom indices in this Timestep

Example

Using a Python slice object:

new_ts = ts.copy_slice(slice(start, stop, step))

Using a list of indices:

new_ts = ts.copy_slice([0, 2, 10, 20, 23])

New in version 0.8.

Changed in version 0.11.0: Reworked to follow new Timestep API. Now will strictly only copy official attributes of the Timestep.

dimensions

View of unitcell dimensions (A, B, C, alpha, beta, gamma)

lengths a, b, c are in the MDAnalysis length unit (Å), and angles are in degrees.

dt

The time difference in ps between timesteps

Note

This defaults to 1.0 ps in the absence of time data

New in version 0.11.0.

forces

A record of the forces of all atoms in this Timestep

Setting this attribute will add forces to the Timestep if they weren’t originally present.

Returns:forces – force data of shape (n_atoms, 3) for all atoms
Return type:numpy.ndarray with dtype numpy.float32
Raises:MDAnalysis.exceptions.NoDataError – if the Timestep has no force data

New in version 0.11.0.

classmethod from_coordinates(positions=None, velocities=None, forces=None, **kwargs)[source]

Create an instance of this Timestep, from coordinate data

Can pass position, velocity and force data to form a Timestep.

New in version 0.11.0.

classmethod from_timestep(other, **kwargs)[source]

Create a copy of another Timestep, in the format of this Timestep

New in version 0.11.0.

has_forces

A boolean of whether this Timestep has force data

This can be changed to True or False to allocate space for or remove the data.

New in version 0.11.0.

has_positions

A boolean of whether this Timestep has position data

This can be changed to True or False to allocate space for or remove the data.

New in version 0.11.0.

has_velocities

A boolean of whether this Timestep has velocity data

This can be changed to True or False to allocate space for or remove the data.

New in version 0.11.0.

n_atoms

A read only view of the number of atoms this Timestep has

Changed in version 0.11.0: Changed to read only property

positions

A record of the positions of all atoms in this Timestep

Setting this attribute will add positions to the Timestep if they weren’t originally present.

Returns:positions – position data of shape (n_atoms, 3) for all atoms
Return type:numpy.ndarray with dtype numpy.float32
Raises:MDAnalysis.exceptions.NoDataError – if the Timestep has no position data

Changed in version 0.11.0: Now can raise NoDataError when no position data present

time

The time in ps of this timestep

This is calculated as:

time = ts.data['time_offset'] + ts.time

Or, if the trajectory doesn’t provide time information:

time = ts.data['time_offset'] + ts.frame * ts.dt

New in version 0.11.0.

triclinic_dimensions

The unitcell dimensions represented as triclinic vectors

Returns:A (3, 3) numpy.ndarray of unit cell vectors
Return type:numpy.ndarray

Examples

The unitcell for a given system can be queried as either three vectors lengths followed by their respective angle, or as three triclinic vectors.

>>> ts.dimensions
array([ 13.,  14.,  15.,  90.,  90.,  90.], dtype=float32)
>>> ts.triclinic_dimensions
array([[ 13.,   0.,   0.],
       [  0.,  14.,   0.],
       [  0.,   0.,  15.]], dtype=float32)

Setting the attribute also works:

>>> ts.triclinic_dimensions = [[15, 0, 0], [5, 15, 0], [5, 5, 15]]
>>> ts.dimensions
array([ 15.        ,  15.81138802,  16.58312416,  67.58049774,
        72.45159912,  71.56504822], dtype=float32)

See also

MDAnalysis.lib.mdamath.triclinic_vectors()

New in version 0.11.0.

velocities

A record of the velocities of all atoms in this Timestep

Setting this attribute will add velocities to the Timestep if they weren’t originally present.

Returns:velocities – velocity data of shape (n_atoms, 3) for all atoms
Return type:numpy.ndarray with dtype numpy.float32
Raises:MDAnalysis.exceptions.NoDataError – if the Timestep has no velocity data

New in version 0.11.0.

volume

volume of the unitcell

class MDAnalysis.coordinates.GRO.GROReader(filename, convert_units=True, n_atoms=None, **kwargs)[source]

Reader for the Gromacs GRO structure format.

Note

This Reader will only read the first frame present in a file.

Note

GRO files with zeroed 3 entry unit cells (i.e. 0.0   0.0   0.0) are read as missing unit cell information. In these cases dimensions will be set to None.

Changed in version 0.11.0: Frames now 0-based instead of 1-based

Changed in version 2.0.0: Reader now only parses boxes defined with 3 or 9 fields. Reader now reads a 3 entry zero unit cell (i.e. [0, 0, 0]) as a being without dimension information (i.e. will the timestep dimension to None).

Writer(filename, n_atoms=None, **kwargs)[source]

Returns a CRDWriter for filename.

Parameters:filename (str) – filename of the output GRO file
Returns:
Return type:GROWriter
class MDAnalysis.coordinates.GRO.GROWriter(filename, convert_units=True, n_atoms=None, **kwargs)[source]

GRO Writer that conforms to the Trajectory API.

Will attempt to write the following information from the topology:
  • atom name (defaults to ‘X’)
  • resnames (defaults to ‘UNK’)
  • resids (defaults to ‘1’)

Note

The precision is hard coded to three decimal places.

Note

When dimensions are missing (i.e. set to None), a zero width unit cell box will be written (i.e. [0.0, 0.0, 0.0]).

Changed in version 0.11.0: Frames now 0-based instead of 1-based

Changed in version 0.13.0: Now strictly writes positions with 3dp precision. and velocities with 4dp. Removed the convert_dimensions_to_unitcell method, use Timestep.triclinic_dimensions instead. Now now writes velocities where possible.

Changed in version 0.18.0: Added reindex keyword argument to allow original atom ids to be kept.

Changed in version 2.0.0: Raises a warning when writing timestep with missing dimension information (i.e. set to None).

Set up a GROWriter with a precision of 3 decimal places.

Parameters:
  • filename (str) – output filename
  • n_atoms (int (optional)) – number of atoms
  • convert_units (bool (optional)) – units are converted to the MDAnalysis base format; [True]
  • reindex (bool (optional)) – By default, all the atoms were reindexed to have a atom id starting from 1. [True] However, this behaviour can be turned off by specifying reindex =False.

Note

To use the reindex keyword, user can follow the two examples given below.:

u = mda.Universe()

Usage 1:

u.atoms.write('out.gro', reindex=False)

Usage 2:

with mda.Writer('out.gro', reindex=False) as w:
    w.write(u.atoms)
fmt = {'box_orthorhombic': '{box[0]:10.5f} {box[1]:9.5f} {box[2]:9.5f}\n', 'box_triclinic': '{box[0]:10.5f} {box[4]:9.5f} {box[8]:9.5f} {box[1]:9.5f} {box[2]:9.5f} {box[3]:9.5f} {box[5]:9.5f} {box[6]:9.5f} {box[7]:9.5f}\n', 'n_atoms': '{0:5d}\n', 'xyz': '{resid:>5d}{resname:<5.5s}{name:>5.5s}{index:>5d}{pos[0]:8.3f}{pos[1]:8.3f}{pos[2]:8.3f}\n', 'xyz_v': '{resid:>5d}{resname:<5.5s}{name:>5.5s}{index:>5d}{pos[0]:8.3f}{pos[1]:8.3f}{pos[2]:8.3f}{vel[0]:8.4f}{vel[1]:8.4f}{vel[2]:8.4f}\n'}

format strings for the GRO file (all include newline); precision of 3 decimal places is hard-coded here.

write(obj)[source]

Write selection at current trajectory frame to file.

Parameters:obj (AtomGroup or Universe) –

Note

The GRO format only allows 5 digits for resid and atom number. If these numbers become larger than 99,999 then this routine will chop off the leading digits.

Changed in version 0.7.6: resName and atomName are truncated to a maximum of 5 characters

Changed in version 0.16.0: frame kwarg has been removed

Changed in version 2.0.0: Deprecated support for calling with Timestep has nwo been removed. Use AtomGroup or Universe as an input instead.

6.8.3. Developer notes: GROWriter format strings

The GROWriter class has a GROWriter.fmt attribute, which is a dictionary of different strings for writing lines in .gro files. These are as follows:

n_atoms

For the first line of the gro file, supply the number of atoms in the system. E.g.:

fmt['n_atoms'].format(42)
xyz

An atom line without velocities. Requires that the ‘resid’, ‘resname’, ‘name’, ‘index’ and ‘pos’ keys be supplied. E.g.:

fmt['xyz'].format(resid=1, resname='SOL', name='OW2', index=2, pos=(0.0, 1.0, 2.0))
xyz_v
As above, but with velocities. Needs an additional keyword ‘vel’.
box_orthorhombic

The final line of the gro file which gives box dimensions. Requires the box keyword to be given, which should be the three cartesian dimensions. E.g.:

fmt['box_orthorhombic'].format(box=(10.0, 10.0, 10.0))
box_triclinic
As above, but for a non orthorhombic box. Requires the box keyword, but this time as a length 9 vector. This is a flattened version of the (3,3) triclinic vector representation of the unit cell. The rearrangement into the odd gromacs order is done automatically.