Formats

This submodule provides readers and writers for (on-disk) file formats.

GROMACS

The following methods are available for reading and writing GROMACS files.

gmso.formats.read_gro(filename)[source]

Create a topology from a provided gro file.

The Gromos87 (gro) format is a common plain text structure file used commonly with the GROMACS simulation engine. This file contains the simulation box parameters, number of atoms, the residue and atom number for each atom, as well as their positions and velocities (velocity is optional). This method will receive a filepath representation either as a string, or a file object and return a topology.

Parameters

filename (str or file object) – The path to the gro file either as a string, or a file object that points to the gro file.

Returns

A topology object containing site information

Return type

gmso.core.topology

Notes

Gro files do not specify connections between atoms, the returned topology will not have connections between sites either.

Currently this implementation does not support a gro file with more than 1 frame.

All residues and resid information from the gro file are currently lost when converting to topology.

gmso.formats.write_gro(top, filename)[source]

Write a topology to a gro file.

The Gromos87 (gro) format is a common plain text structure file used commonly with the GROMACS simulation engine. This file contains the simulation box parameters, number of atoms, the residue and atom number for each atom, as well as their positions and velocities (velocity is optional). This method takes a topology object and a filepath string or file object and saves a Gromos87 (gro) to disk.

Parameters
  • top (gmso.core.topology) – The topology to write out to the gro file.

  • filename (str or file object) – The location and name of file to save to disk.

Notes

Multiple residue assignment has not been added, each site will belong to the same resid of 1 currently.

Velocities are not written out.

GSD

The following methods are available for reading and writing GSD files.

gmso.formats.write_gsd(top, filename, ref_distance=unyt_quantity(1., 'nm'), ref_mass=unyt_quantity(1., 'g/mol'), ref_energy=unyt_quantity(1., 'kcal/mol'), rigid_bodies=None, shift_coords=True, write_special_pairs=True)[source]

Output a GSD file (HOOMD v3 default data format).

The GSD binary file format is the native format of HOOMD-Blue. This file can be used as a starting point for a HOOMD-Blue simulation, for analysis, and for visualization in various tools.

Parameters
  • top (gmso.Topology) – gmso.Topology object

  • filename (str) – Path of the output file.

  • ref_distance (float, optional, default=1.0) – Reference distance for conversion to reduced units

  • ref_mass (float, optional, default=1.0) – Reference mass for conversion to reduced units

  • ref_energy (float, optional, default=1.0) – Reference energy for conversion to reduced units

  • rigid_bodies (list of int, optional, default=None) – List of rigid body information. An integer value is required for each atom corresponding to the index of the rigid body the particle is to be associated with. A value of None indicates the atom is not part of a rigid body.

  • shift_coords (bool, optional, default=True) – Shift coordinates from (0, L) to (-L/2, L/2) if necessary.

  • write_special_pairs (bool, optional, default=True) – Writes out special pair information necessary to correctly use the OPLS fudged 1,4 interactions in HOOMD.

Notes

Force field parameters are not written to the GSD file and must be included manually in a HOOMD input script. Work on a HOOMD plugin is underway to read force field parameters from a Foyer XML file.

xyz

The following methods are available for reading and writing xyz files.

gmso.formats.read_xyz(filename)[source]

Reader for xyz file format.

Read in an xyz file at the given path and return a Topology object.

Parameters

filename (str) – Path to .xyz file that need to be read.

Returns

top – Topology object

Return type

topology.Topology

gmso.formats.write_xyz(top, filename)[source]

Writer for xyz file format.

Write a Topology object to an xyz file at the given path.

Parameters
  • top (topology.Topology) – Topology object that needs to be written out.

  • filename (str) – Path to file location.

LAMMPS DATA

The following methods are available for reading and writing LAMMPS data.

gmso.formats.write_lammpsdata(topology, filename, atom_style='full')[source]

Output a LAMMPS data file.

Outputs a LAMMPS data file in the ‘full’ atom style format. Assumes use of ‘real’ units. See http://lammps.sandia.gov/doc/atom_style.html for more information on atom styles.

Parameters
  • Topology (Topology) – A Topology Object

  • filename (str) – Path of the output file

  • atom_style (str, optional, default=’full’) – Defines the style of atoms to be saved in a LAMMPS data file. The following atom styles are currently supported: ‘full’, ‘atomic’, ‘charge’, ‘molecular’ see http://lammps.sandia.gov/doc/atom_style.html for more information on atom styles.

Notes

See http://lammps.sandia.gov/doc/2001/data_format.html for a full description of the LAMMPS data format. This is a work in progress, as only atoms, masses, and atom_type information can be written out.

Some of this function has been adopted from mdtraj’s support of the LAMMPSTRJ trajectory format. See https://github.com/mdtraj/mdtraj/blob/master/mdtraj/formats/lammpstrj.py for details.