File Format Readers and Writers

The gmso.formats module provides readers and writers for common molecular simulation file formats. All public functions are importable from gmso.formats.

GROMACS 

GROMACS coordinate files (.gro) and topology/parameter files (.top, .itp) are supported for both reading and writing.

`gmso.formats.read_gro`	Read a Gromos87 (GRO) file and return a `Topology`.
`gmso.formats.write_gro`	Write a `Topology` to a Gromos87 (GRO) file.
`gmso.formats.write_top`	Write a `Topology` to a GROMACS topology (`.top`) file.

read_gro 

gmso.formats.read_gro(filename)[source]

Read a Gromos87 (GRO) file and return a Topology.

The GRO format is a plain-text structure file used by the GROMACS simulation engine. It encodes simulation-box parameters, atom count, residue/atom names, positions, and (optionally) velocities.

Parameters:: filename (Union[str, Path]) – Path to the .gro file to read.
Returns:: Topology containing the sites and box parsed from filename.
Return type:: Topology

Notes

GRO files do not specify bonds; the returned topology will have no connections.
Velocities are detected but not parsed.
Only single-frame GRO files are supported.
Residue/resid information is mapped to site.molecule and site.residue but the original resid integers are rebased to 0-indexed integers.

write_gro 

gmso.formats.write_gro(top, filename, n_decimals=3, shift_coord=False)[source]

Write a Topology to a Gromos87 (GRO) file.

Parameters:

top (Topology) – Topology to write.
filename (Union[str, Path]) – Destination file path.
n_decimals (int) – Number of decimal places to use for coordinate values.
shift_coord (bool) – When True, shift all coordinates so that the minimum position in each dimension is zero. Useful for visualisation; not required by the GRO format.

Return type:

None

Notes

Velocities are not written.
Residue/resid indices cycle back at 99 999 to comply with the fixed-width GRO column format.

write_top 

gmso.formats.write_top(top, filename, top_vars=None, settles_tag=None)[source]

Write a Topology to a GROMACS topology (.top) file.

Parameters:

top (Topology) – Fully typed topology to write.
filename (Union[str, Path]) – Destination file path.
top_vars (Optional[dict]) – Override the default GROMACS [ defaults ] section values. Keys are GROMACS parameter names (e.g. 'nbfunc', 'comb-rule', 'gen-pairs', 'fudgeLJ', 'fudgeQQ'). Any key not supplied falls back to the value inferred from the topology.
settles_tag (Optional[str]) – When provided, write a [ settles ] section for rigid 3-site water models using the given tag string.

Returns:

Writes the GROMACS topology file to filename in place.

Return type:

None

Notes

This writer is a work in progress and does not yet support the full GROMACS topology spec. See the GROMACS manual at https://manual.gromacs.org/current/reference-manual/topologies/topology-file-formats.html for the complete format description.

GSD 

GSD (General Simulation Data) is the native trajectory format for HOOMD-blue.

gmso.formats.write_gsd

Output a GSD file (HOOMD default data format).

write_gsd 

gmso.formats.write_gsd(top, filename, base_units=None, shift_coords=True, write_special_pairs=True)[source]

Output a GSD file (HOOMD default data format).

The GSD binary file format is the native format of HOOMD-blue. It can be used as a starting point for a HOOMD-blue simulation, for trajectory analysis, and for visualisation in various tools.

To write a HOOMD snapshot, see gmso.external.convert_hoomd.to_hoomd_snapshot() and gmso.external.convert_hoomd.to_gsd_snapshot()

Parameters:

top (Topology) – Typed topology to write.
filename (Union[str, Path]) – Path of the output file.
base_units (Optional[dict]) – Dictionary of base units to use when writing the GSD snapshot. If None, HOOMD-blue default units are used.
shift_coords (bool) – Shift coordinates from (0, L) to (-L/2, L/2) if necessary.
write_special_pairs (bool) – Write special pair information needed to correctly apply the OPLS fudged 1-4 interactions in HOOMD-blue.

Returns:

Writes the GSD snapshot to filename in place.

Return type:

None

Notes

Force field parameters are not stored in the GSD file. You can use GMSO to create the HOOMD force objects. See gmso.external.convert_hoomd.to_hoomd_forcefield()

XYZ 

The plain-text XYZ format stores atomic symbols and Cartesian coordinates.

`gmso.formats.read_xyz`	Read an XYZ file and return a `Topology`.
`gmso.formats.write_xyz`	Write a `Topology` to an XYZ file.

read_xyz 

gmso.formats.read_xyz(filename)[source]

Read an XYZ file and return a Topology.

Parameters:: filename (Union[str, Path]) – Path to the .xyz file to read.
Returns:: Topology containing the sites parsed from filename. No bonds or box information are set; call update_topology() afterwards if needed.
Return type:: Topology
Raises:: ValueError – If the number of coordinate lines does not match the atom count in the first line of the file.

write_xyz 

gmso.formats.write_xyz(top, filename, decimals=3)[source]

Write a Topology to an XYZ file.

Parameters:

top (Topology) – Topology to write.
filename (Union[str, Path]) – Destination file path.
decimals (int) – Number of decimal places written for each coordinate value.

Return type:

None

LAMMPS DATA 

LAMMPS data files encode particle positions, topology, and forcefield coefficients.

`gmso.formats.write_lammpsdata`	Write a LAMMPS data file from a `Topology`.
`gmso.formats.read_lammpsdata`	Read a LAMMPS data file and return a `Topology`.

write_lammpsdata 

gmso.formats.write_lammpsdata(top, filename, atom_style='full', unit_style='real', strict_potentials=False, strict_units=False, lj_cfactorsDict=None)[source]

Write a LAMMPS data file from a Topology.

Parameters:

top (Topology) – Typed topology to write.
filename (Union[str, Path]) – Path of the output file.
atom_style (str) – LAMMPS atom style. Supported values: 'full', 'atomic', 'charge', 'molecular'.
unit_style (str) – LAMMPS unit system. Supported values: 'real', 'lj', 'metal', 'si', 'cgs', 'electron', 'micro', 'nano'.
strict_potentials (bool) – When True, raise an error if any potential style is not directly supported instead of attempting an automatic conversion.
strict_units (bool) – When True, raise an error if parameter units do not match the target unit style instead of converting automatically.
lj_cfactorsDict (Optional[dict]) – Used only when unit_style='lj'. A dict with any subset of keys 'mass', 'energy', 'length', 'charge' that override the default non-dimensionalisation factors (which are derived from the largest values found in the topology).

Returns:

Writes the LAMMPS data file to filename in place.

Return type:

None

Notes

See https://docs.lammps.org/read_data.html for a full description of the LAMMPS data format. Only a subset of atom styles, potential styles, and unit styles are currently supported.

read_lammpsdata 

gmso.formats.read_lammpsdata(filename, atom_style='full', unit_style='real')[source]

Read a LAMMPS data file and return a Topology.

Parameters:

filename (Union[str, Path]) – Path to the LAMMPS data file.
atom_style (str) – LAMMPS atom style used in the data file. Currently only 'full' is supported; supply the correct value or parsing will fail.
unit_style (str) – LAMMPS unit style used when the data file was written. Supported values: 'real', 'lj', 'metal', 'si', 'cgs', 'electron', 'micro', 'nano'.

Returns:

Typed topology parsed from filename.

Return type:

Topology

Notes

This reader is a work in progress. Currently supported styles:

Atom styles: 'full'
Pair potential styles: 'lj'
Bond styles: 'harmonic', 'fene'
Angle styles: 'harmonic'
Dihedral styles: 'opls'
Improper styles: 'harmonic'

MOL2 

Tripos MOL2 is a common format for small-molecule structures.

`gmso.formats.read_mol2`	Read a TRIPOS MOL2 file and return a `Topology`.
`gmso.formats.write_mol2`	Write a `Topology` to a TRIPOS MOL2 file.

read_mol2 

gmso.formats.read_mol2(filename, site_type='atom', verbose=False)[source]

Read a TRIPOS MOL2 file and return a Topology.

Parses sites, bonds, and box information from a MOL2 file. Forcefield parameters present in the file are not converted.

Parameters:

filename (Union[str, Path]) – Path to the .mol2 file.
site_type (str) – Controls element identification. Use 'atom' to read element symbols from the file; use 'lj' to skip element lookup and store the raw site name instead (useful for coarse-grained systems).
verbose (bool) – When True, emit warnings for any assumptions made during parsing.

Returns:

Topology containing the sites, bonds, and box from filename.

Return type:

Topology

Notes

Atom positions in MOL2 files are assumed to be in Angstroms.

write_mol2 

gmso.formats.write_mol2(top, filename, n_decimals=4)[source]

Write a Topology to a TRIPOS MOL2 file.

Parameters:

top (Topology) – Topology to write.
filename (Union[str, Path]) – Destination file path.
n_decimals (int) – Number of decimal places written for each coordinate value.

Returns:

Writes the MOL2 file to filename in place.

Return type:

None

MCF 

Monte Carlo forcefield (MCF) files are used by Cassandra Monte Carlo.

gmso.formats.write_mcf

Write a Cassandra Monte Carlo MCF file from a Topology.

write_mcf 

gmso.formats.write_mcf(top, filename)[source]

Write a Cassandra Monte Carlo MCF file from a Topology.

The MCF file encodes the topology of a single molecular species for the Cassandra Monte Carlo engine. The supplied topology should contain a single fully parameterised molecule. One MCF file is required for each unique species in the simulation.

Parameters:

top (Topology) – Fully parameterised single-molecule topology.
filename (Union[str, Path]) – Destination file path. When the topology contains more than one subtopology and a plain string is given, an integer suffix is appended automatically for each subtopology.

Returns:

Writes the MCF file(s) to filename in place.

Return type:

None

Notes

Atom indexing in the MCF format begins at 1. See the Cassandra documentation at https://cassandra.nd.edu/index.php/documentation for a complete format description.

JSON 

GMSO topologies can be serialized to and from JSON for storage and interoperability.

`gmso.formats.write_json`	Write a `Topology` to a JSON file.
`gmso.formats.load_json`	Load a `Topology` from a JSON file.

write_json 

gmso.formats.write_json(top, filename, types=True, update=False, **kwargs)[source]

Write a Topology to a JSON file.

Parameters:

top (Topology) – Topology to serialise.
filename (Union[str, Path]) – Destination file path; must end with .json.
types (bool) – When True, include potential type information (atom types, bond types, etc.) in the output.
update (bool) – When True, call update_topology() before serialisation.
**kwargs – Additional keyword arguments forwarded to json.dump().

Returns:

Writes the JSON file to filename in place.

Return type:

None

load_json 

gmso.formats.load_json(filename)[source]

Load a Topology from a JSON file.

Parameters:: filename (Union[str, Path]) – Path to the .json file to read.
Returns:: Topology deserialised from filename.
Return type:: Topology

Format Registry 

The format registry provides the decorator-based mechanism for registering new file format readers and writers.

gmso.formats.formats_registry.LoadersRegistry: alias of <gmso.formats.formats_registry.Registry object>

gmso.formats.formats_registry.SaversRegistry: alias of <gmso.formats.formats_registry.Registry object>