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 parsing velocities from a gro file or 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, n_decimals=3, shift_coord=False)[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.

  • n_decimals (int, optional, default=3) – The number of sig fig to write out the position in.

  • shift_coord (bool, optional, default=False) – If True, shift the coordinates of all sites by the minimum position to ensure all sites have non-negative positions. This is not a requirement for GRO files, but can be useful for visualizing.

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, base_units=None, 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.

  • 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(top, filename, atom_style='full', unit_style='real', strict_potentials=False, strict_units=False, lj_cfactorsDict=None)[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.

  • unit_style (str, optional, default=’real’) – Can be any of “real”, “lj”, “metal”, “si”, “cgs”, “electron”, “micro”, “nano”. Otherwise an error will be thrown. These are defined in _unit_style_factory. See https://docs.lammps.org/units.html for LAMMPS documentation.

  • strict_potentials (bool, optional, default False) – Tells the writer how to treat conversions. If False, then check for conversions to usable potential styles found in default_parameterMaps. If True, then error if potentials are not compatible.

  • strict_units (bool, optional, default False) – Tells the writer how to treat unit conversions. If False, then check for conversions to unit styles defined in _unit_style_factory. If True, then error if parameter units do not match.

  • lj_cfactorsDict ((None, dict), optional, default None) – If using unit_style=”lj” only, can pass a dictionary with keys of (“mass”, “energy”, “length”, “charge”), or any combination of these, and they will be used to non- dimensionalize all values in the topology. If any key is not passed, default values will be pulled from the topology (see _default_lj_val). These are the largest: sigma, epsilon, atomtype.mass, and atomtype.charge from the topology.

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 a subset of everything LAMMPS supports is currently available. However, please raise issues as the current writer has been set up to eventually grow to support all LAMMPS styles.

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.