Reading in Files

Below are the three main classes for reading in and accessing information from Gromacs simulation files. Each class contains its own header file in the gmxcpp directory which should be included in your own program. See the previous section on some example usages.

Index

class Index

Class containing index file info.

Contains all information from an index file. When constructed the index file is read in. The names of each group are stored in headers. The locations for each group are stored in the locations vector.

Public Functions

Index()

Blank constructor for Index class.

Index(string ndxfile)

Constructor which specifies index file.

When constructed the index file is read into the corresponding data elements of the object and can be retrieved with getter functions below.

Parameters
  • ndxfile: Name of index file to be read in.

int GetGroupSize(string groupName) const

Gets the size of an index group.

Return
Size of the group.
Parameters
  • groupName: Name of group for which size is desired.

int GetLocation(string groupName, int atomNumber) const

Gets the index location of the atom in the group specified.

This returns in the index location of an atom relative to the entire system. That is, if you know a specific atom’s location relative to an index group, i.e., it is the second atom in a group, then this gives the index number for it for the entire system, i.e., the second atom in a group might be the 300th atom in the system. Look at how an index file is formatted to understand more thoroughly.

Parameters
  • groupName: Name of group where at is located.
  • atomNumber: The location of the atom in the group.

string GetFilename() const

Gets the filename associated with this object.

Topology

class Topology

The main class in reading Gromacs .tpr files.

Class which stores information from a Gromacs topology (tpr) file. Currently just stores the atomic charges and masses in vectors which can be retrieved by getters.

Public Functions

Topology(string tprfile)

Constructor which reads in a GROMACS tpr file.

Constructor which reads in the tpr file. Currently only reads charges and masses of each atom into memory.

Parameters
  • tprfile: Name of the Gromacs tpr file to be read in.

Topology(string tprfile, Index index)

Constructor which reads in a GROMACS tpr file and associates an index file with it.

Constructor which reads in the tpr file and associates an index file with it. Currently only reads charges and masses of each atom into memory.

Parameters
  • index: Index object to associate with this topology.
  • tprfile: Name of the Gromacs tpr file to be read in.

double GetCharge(int atom) const

Gets the electric charge of the specified atom.

Return
The charge (units specified in Gromacs manual)
Parameters
  • atom: The atom

double GetCharge(int atom, string group) const

Gets the electric charge of the specified atom in an index group.

Return
The charge (units specified in Gromacs manual)
Parameters
  • atom: The atom
  • group: Index group

vector<double> GetCharge() const

Gets the electric charge of all atoms in the system.

Return
The charge of all atoms in the system (units specified in Gromacs manual)

vector<double> GetCharge(string group) const

Gets the electric charge of the specified index group.

Return
The charge of all atoms in the index group (units specified in Gromacs manual)
Parameters

double GetMass(int atom) const

Gets the mass of the specified atom.

Return
The mass (units specified in Gromacs manual)
Parameters
  • atom: The atom

double GetMass(int atom, string group) const

Gets the mass of the specified atom in an index group.

Return
The mass (units specified in Gromacs manual)
Parameters

vector<double> GetMass() const

Gets the mass of all atoms in the system.

Return
The mass of all atoms in the system (units specified in Gromacs manual)

vector<double> GetMass(string group) const

Gets the mass of the specified index group.

Return
The mass of all atoms in the inde group (units specified in Gromacs manual)
Parameters

string GetElem(int atom)

Gets the element name of an atom.

Return
Name of the element
Parameters
  • atom: The atom number

string GetElem(int atom, string group)

Gets the element name of an atom in a specified group.

Return
Name of the element
Parameters
  • atom: The atom number
  • group: Index group of which the atom belongs

string GetAtomName(int atom)

Gets the atom name of an atom.

Return
Name of the atom
Parameters
  • atom: The atom number

string GetAtomName(int atom, string group)

Gets the element name of an atom in a specified group.

Return
Name of the element
Parameters
  • atom: The atom number
  • group: Index group of which the atom belongs

string GetResName(int atom)

Gets the residue name of an atom.

Return
Name of the residue
Parameters
  • atom: The atom number

string GetResName(int atom, string group)

Gets the residue name of an atom in a specified group.

Return
Name of the residue
Parameters
  • atom: The atom number
  • group: Index group of which the atom belongs

Trajectory

class Trajectory

The main class in reading Gromacs files.

A Trajectory object contains a vector of Frame objects, plus other info on the simulation (number of atoms). It also contains the special xd pointer that libxdrfile needs to open the xtc file, as well as the number of atoms in the system, the number of frames read in, and an Index object.

Public Functions

Trajectory(string xtcfile)

Constructor where only XTC file is read.

Constructor of Trajectory object, with no index file specified

Parameters
  • xtcfile: Name of the Gromacs XTC file to be read in. file.

Trajectory(string xtcfile, Index index)

Constructor which sets both the XTC file and incorporates a previously read in Index object.

When this constructor is used, both the Gromacs XTC file is saved in the vector of Frame objects, and the group names and index numbers from an Index object are copied into the Trajectory object.

Parameters
  • xtcfile: Name of the Gromacs XTC file to be read in.
  • index: The Index object which has already had its index file read in.

Trajectory(string xtcfile, string ndxfile)

Constructor that sets both the XTC file and a GROMACS index file.

When this constructor is used, both the Gromacs XTC file is saved in the vector of Frame objects, and the group names and index numbers for the index file are saved in an Index object.

Parameters
  • xtcfile: Name of the Gromacs XTC file to be read in.
  • ndxfile: Name of the Gromacs index file to be read in.

int read(int b = 0, int s = 1, int e = -1)

Reads in simulation frames into memory and then closes the file.

Return
Number of frames read in.
Parameters
  • b: First frame to be read in. By default, starts at the first frame (frame 0).
  • s: Read in every sth frame.
  • e: Stop reading at this frame. -1 means read until the end of the

int read_next(int n = 1)

Reads in n simulations frames into memory and keeps the file open.

Frames are saved into the frameArray object, overwriting previously saved frames

Return
Number of frames actually read in.
Parameters
  • n: Number of frames to read into memory.

int skip_next(int n = 1)

Skip n frames.

Return
Number of frames actually skipped
Parameters
  • n: Number of frames to skip

int GetNAtoms() const

Gets the number of atoms in a system.

Return
Number of atoms.

int GetNAtoms(string groupName) const

Gets the number of atoms in an index group.

Return
number of atoms in the group specified.
Parameters
  • groupName: Name of group for which number of atoms is returned.

int GetNFrames() const

Gets the number of frames that were saved.

Return
Number of frames.

float GetTime(int frame) const

Gets the time at frame specified.

Return
Time in picoseconds.
Parameters
  • frame: Number corresponding with the frame for which time should be returned.

int GetStep(int frame) const

Gets the step at frame specified.

Return
Step number.
Parameters
  • frame: Number corresponding with the frame for which step should be returned.

coordinates GetXYZ(int frame, int atom) const

Gets the coordinates of a specific atom in the entire system.

Gets the cartesian coordinates for the atom specified at the frame specified and returns it as a vector

Return
Vector with X, Y, and Z coordinates of the atom specified.
Parameters
  • atom: The number corresponding with the atom in the entire system.
  • frame: Number of the frame desired.

coordinates GetXYZ(int frame, string groupName, int atom) const

Gets the coordinates for a specific atom in a group.

Gets the cartesian coordinates for the atom specified in the specific index group for this frame.

Return
Vector with X, Y, and Z coordinates of the atom specified.
Parameters
  • frame: Number of the frame desired.
  • groupName: Name of index group in which atom is located.
  • atom: The number corresponding with the atom in the index group. Note that this is not the same number corresponding with the system. That is, the atom may be the 5th atom in the system, but it may be the 2nd atom in the group. This is where it is located in the group.

vector<coordinates> GetXYZ(int frame) const

Gets all of the coordinates for the system for a specific frame.

Return
A two dimensional vector with all cartesian coordinates for the system at this frame. The first dimension is the atom number. The second dimension contains the X, Y, and Z positions.
Parameters
  • frame: Number of the frame desired.

vector<coordinates> GetXYZ(int frame, string groupName) const

Gets all of the coordinates for an index group for a specific frame.

Return
A two dimensional vector with all cartesian coordinates for the system at this frame. The first dimension is the atom number in the group. The second dimension contains the X, Y, and Z positions.
Parameters
  • frame: Number of the frame desired.
  • groupName: Name of index group in which atom is located.

triclinicbox GetBox(int frame) const

Gets the triclinic box dimensions for a frame.

Return
Two-dimensional array with three elements in each dimension, corresponding to a triclinic box.
Parameters
  • frame: Number of the frame desired.

double GetBoxVolume(int frame) const

Gets the volume of the box at a specific frame.

Return
Box volume.
Parameters
  • frame: Number of the frame desired.