External Library Conversions

The gmso.external module provides functions to convert Topology objects to and from in-memory representations used by other molecular simulation libraries. All public functions are importable from gmso.external.

mBuild 

mBuild is a hierarchical molecule builder. The conversions below allow a built mBuild.Compound to be typed and written to simulation files via GMSO, and vice-versa.

`gmso.external.from_mbuild`	Convert an mbuild.Compound to a gmso.Topology.
`gmso.external.from_mbuild_box`	Convert an `mbuild.Box` to a `Box`.
`gmso.external.to_mbuild`	Convert a `Topology` to an `mbuild.Compound`.

from_mbuild 

gmso.external.from_mbuild(compound, box=None, search_method=element_by_symbol, parse_label=True, custom_groups=None, infer_elements=False)[source]

Convert an mbuild.Compound to a gmso.Topology.

This conversion makes the following assumptions about the inputted Compound:

All positional and box dimension values in compound are in nanometers.

The hierarchical structure of the Compound will be flattened and translated to labels in GMSO Sites. The directly supported labels include Site.group, Site.molecule_name, and Site.residue_name.

group is determined as te second-highest level Compound and is automatically generated; * molecule is determined by traversing through hierarchy of the mb.Compound, starting from the particle level, until the lowest independent mb.Compound is reached (determined as an mb.Compound that does not have any bond outside its boundary);

residue is the mb.Compound level right above particle level.

molecule and residue take the format of (name, index), where the latter can be used to distinguish between molecule/residue of the same name. These two labels are only generated if parse_label=True.

Only Bonds are added for each bond in the Compound. If Angles and Dihedrals are desired in the resulting Topology, they must be added separately from this function.

Parameters:

compound (Compound) – mbuild.Compound instance that need to be converted
box (Box | None) – Box information to be loaded to a gmso.Topology
search_method (function, optional, default element_by_symbol) – Searching method used to assign element from periodic table to particle site. The information specified in the search_method argument is extracted from each Particle’s name attribute. Valid functions are element_by_symbol, element_by_name, element_by_atomic_number, and element_by_mass, which can be imported from gmso.core.element
parse_label (bool) – Option to parse hierarchy info of the compound into system of top label, including, group, molecule and residue labels.
custom_groups (list or str, optional, default None) – Allows user to identify the groups assigned to each site in the topology based on the compound.name attributes found traversing down the hierarchy. Be sure to supply names such that every particle will be pass through one matching name on the way down from compound.children. Only the first match while moving downwards will be assigned to the site. If parse_label=False, this argument does nothing.
infer_elements (bool) – Allows the reader to try to load element info from the mbuild Particle.name instead of only from the populated Particle.element

Returns:

top

Return type:

Topology

from_mbuild_box 

gmso.external.from_mbuild_box(mb_box)[source]

Convert an mbuild.Box to a Box.

Parameters:: mb_box (Box) – The mBuild box to convert. All lengths must be in nanometers.
Returns:: The converted box, or None when mb_box has zero lengths (i.e. no bounding box was set).
Return type:: Box | None

to_mbuild 

gmso.external.to_mbuild(topology, infer_hierarchy=True)[source]

Convert a Topology to an mbuild.Compound.

Parameters:

topology (Topology) – The topology to convert.
infer_hierarchy (bool) – When True, reconstruct the mBuild hierarchy from the molecule and residue labels on each site.

Returns:

A Compound whose particles correspond to the sites in topology.

Return type:

Compound

ParmEd 

ParmEd is a library for editing and converting molecular mechanics parameter files.

`gmso.external.from_parmed`	Convert a `parmed.Structure` to a `Topology`.
`gmso.external.to_parmed`	Convert a `Topology` to a `parmed.Structure`.

from_parmed 

gmso.external.from_parmed(structure, refer_type=True)[source]

Convert a parmed.Structure to a Topology.

Maps the Structure hierarchy to GMSO objects: Structure → Topology, Atom → Atom.

Parameters:

structure (Structure) – The ParmEd structure to convert. May be parametrized or un-parametrized.
refer_type (bool) – When True, transfer AtomType, BondType, AngleType, DihedralType, and ImproperType information from the ParmEd structure.

Returns:

Topology constructed from structure.

Return type:

Topology

to_parmed 

gmso.external.to_parmed(top, refer_type=True)[source]

Convert a Topology to a parmed.Structure.

Maps the GMSO hierarchy to ParmEd objects. The Molecule level in GMSO is skipped; the three-level mapping is: Topology → Structure, residue → Residue, Atom → Atom.

Parameters:

top (Topology) – The topology to convert.
refer_type (bool) – When True, transfer AtomType, BondType, AngleType, and DihedralType information to ParmEd parameter types.

Returns:

ParmEd structure built from top.

Return type:

Structure

OpenMM 

OpenMM is a GPU-accelerated molecular dynamics library. GMSO can export a typed topology as an OpenMM Topology object.

gmso.external.to_openmm

Convert a Topology to an untyped OpenMM topology or modeller.

to_openmm 

gmso.external.to_openmm(topology, openmm_object='topology')[source]

Convert a Topology to an untyped OpenMM topology or modeller.

Useful when atom-typing is performed within OpenMM rather than GMSO. See https://openmm.org for more information.

Parameters:

topology (gmso.Topology) – The un-typed GMSO topology to convert.
openmm_object (str) – Target OpenMM object type. Accepted values: 'topology' or 'modeller'.

Returns:

The converted OpenMM object.

Return type:

openmm.app.Topology or openmm.app.Modeller

HOOMD-blue 

HOOMD-blue is a particle simulation toolkit. GMSO can export directly to HOOMD-blue’s GSD snapshot and forcefield objects.

`gmso.external.to_hoomd_snapshot`	Create a hoomd.Snapshot objcet (HOOMD default data format).
`gmso.external.to_hoomd_forcefield`	Convert the potential portion of a typed GMSO to hoomd forces.
`gmso.external.to_gsd_snapshot`	Create a gsd.hoomd.Frame objcet (HOOMD default data format).

to_hoomd_snapshot 

gmso.external.to_hoomd_snapshot(top, base_units=None, shift_coords=True, parse_special_pairs=True, auto_scale=False)[source]

Create a hoomd.Snapshot objcet (HOOMD default data format).

The Hoomd snapshot defines the topology of HOOMD-blue simulations. 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.
base_units (dict, optinoal, default None) – The dictionary of base units to be converted to. Entries restricted to “energy”, “length”, and “mass”. There is also option to used predefined unit systems (“MD” or “AKMA” provided as string). If None is provided, this method will perform no units conversion.
shift_coords (bool, optional, default True) – Shift coordinates from (0, L) to (-L/2, L/2) if necessary.
parse_special_pairs (bool, optional, default True) – Writes out special pair information necessary to correctly use the OPLS fudged 1,4 interactions in HOOMD.
auto_scale (bool or dict, optional, default False) – Automatically scaling relevant length, energy and mass units. Referenced mass unit is obtained from sites’ masses. Referenced energy and distance are refered from sites’ atom types (when applicable). If the referenced scaling values cannot be determined (e.g., when the topology is not typed), all reference scaling values is set to 1. A dictionary specifying the referenced scaling values may also be provided for this argument.

Returns:

hoomd_snapshot (hoomd.Snapshot) – Converted HOOMD snapshot. Always returned.
base_units (dict) – Base units dictionary used during the conversion. Always returned.
rigid_info (hoomd.md.constrain.Rigid) – A HOOMD constraint object storing constituent particle information needed to run rigid body simulations in HOOMD-blue. Only returned when sites with site.molecule.isrigid = True are found in the topology.

Notes

Force field parameters are not written to the snapshot and must be generated separately using gmso.external.convert_hoomd.to_hoomd_forcefield().

When using mBuild and GMSO to initialise rigid body simulations with HOOMD-blue, set site.molecule.isrigid = True. If the topology contains a mix of rigid and flexible molecules, the rigid molecules must appear first in the GMSO topology hierarchy (and therefore first in the mBuild Compound hierarchy).

For more information about rigid body simulations in HOOMD-blue see https://hoomd-blue.readthedocs.io/en/latest/tutorial/06-Modelling-Rigid-Bodies/00-index.html

For information on the base_units dictionary see https://hoomd-blue.readthedocs.io/en/latest/units.html#base-units

Examples

Rigid benzene + flexible ethane system (benzene must be passed first so it sits at the top of the mBuild Compound hierarchy):

ethane = mb.lib.molecules.Ethane()
ethane.name = "ethane"
benzene = mb.load("c1ccccc1", smiles=True)
benzene.name = "benzene"
box = mb.fill_box([benzene, ethane], n_compounds=[1, 1], box=[2, 2, 2])
top = from_mbuild(box)
for site in top.sites:
    if site.molecule.name == "benzene":
        site.molecule.isrigid = True
snapshot, refs, rigid = to_hoomd_snapshot(top)

to_hoomd_forcefield 

gmso.external.to_hoomd_forcefield(top, r_cut, nlist=None, pppm_kwargs={'resolution': (8, 8, 8), 'order': 4}, base_units=None, auto_scale=False, kT=None)[source]

Convert the potential portion of a typed GMSO to hoomd forces.

Parameters:

top (gmso.Topology) – The typed topology to be converted
r_cut (float) – r_cut for the nonbonded forces.
nlist (hoomd.md.nlist.NeighborList or tuple or list or None, optional, default None) – Neighborlist object to use for nonbonded forcefield. Can also be a list or tuple of neighborlists where the first neighborlist is used for nonbonded pair forces, and the second with coulombic forces. If None, the default value used will be a hoomd.md.nlist.Cell(exclusions=exclusions, buffer=0.4).
pppm_kwargs (dict) – Keyword arguments to pass to hoomd.md.long_range.make_pppm_coulomb_forces().
base_units (dict or str, optional, default None) – The dictionary of base units to be converted to. Entries restricted to “energy”, “length”, and “mass”. There is also option to used predefined unit systems (“MD” or “AKMA” provided as string). If None is provided, this method will perform no units conversion.
auto_scale (bool or dict, optional, default False) – Automatically scaling relevant length, energy and mass units. Referenced mass unit is obtained from sites’ masses. Referenced energy and distance are refered from sites’ atom types (when applicable). If the referenced scaling values cannot be determined (e.g., when the topology is not typed), all reference scaling values is set to 1. A dictionary specifying the referenced scaling values may also be provided for this argument.
kT (float, optional, default None) – Set the kT parameter for running simulations with hoomd.md.pair.DPD forces. If none and these forces are present in top.pairpotential_types, will raise an error. Please convert to units of [energy] using base_units to ensure proper value is passed.

Returns:

forces (dict) – HOOMD forces converted from all available PotentialTypes of the provided GMSO Topology. Converted are grouped by their category (as key of the dictionary), namely, “nonbonded”, “bonds”, “angles”, “dihedrals”, and “impropers”.
base_units (dict) – Base units dictionary utilized during the conversion.

to_gsd_snapshot 

gmso.external.to_gsd_snapshot(top, base_units=None, shift_coords=True, parse_special_pairs=True, auto_scale=False)[source]

Create a gsd.hoomd.Frame objcet (HOOMD default data format).

The gsd snapshot defines the topology of HOOMD-blue simulations. 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.
base_units (dict, optinoal, default None) – The dictionary of base units to be converted to. Entries restricted to “energy”, “length”, and “mass”. There is also option to used predefined unit systems (“MD” or “AKMA” provided as string). If None is provided, this method will perform no units conversion.
shift_coords (bool, optional, default True) – Shift coordinates from (0, L) to (-L/2, L/2) if necessary.
parse_special_pairs (bool, optional, default True) – Writes out special pair information necessary to correctly use the OPLS fudged 1,4 interactions in HOOMD.
auto_scale (bool or dict, optional, default False) – Automatically scaling relevant length, energy and mass units. Referenced mass unit is obtained from sites’ masses. Referenced energy and distance are refered from sites’ atom types (when applicable). If the referenced scaling values cannot be determined (e.g., when the topology is not typed), all reference scaling values is set to 1. A dictionary specifying the referenced scaling values may also be provided for this argument.

Returns:

gsd_snapshot (gsd.hoomd.Frame) – Converted HOOMD snapshot. Always returned.
base_units (dict) – Base units dictionary used during the conversion. Always returned.
rigid_info (hoomd.md.constrain.Rigid) – A HOOMD constraint object storing constituent particle information needed to run rigid body simulations in HOOMD-blue. Only returned when sites with site.molecule.isrigid = True are found in the topology.

Notes

Force field parameters are not written to the GSD file and must be generated separately using gmso.external.convert_hoomd.to_hoomd_forcefield().

When using mBuild and GMSO to initialise rigid body simulations with HOOMD-blue, set site.molecule.isrigid = True. If the topology contains a mix of rigid and flexible molecules, the rigid molecules must appear first in the GMSO topology hierarchy (and therefore first in the mBuild Compound hierarchy).

For more information about rigid body simulations in HOOMD-blue see https://hoomd-blue.readthedocs.io/en/latest/tutorial/06-Modelling-Rigid-Bodies/00-index.html

For information on the base_units dictionary see https://hoomd-blue.readthedocs.io/en/latest/units.html#base-units

Examples

Rigid benzene + flexible ethane system (benzene must be passed first so it sits at the top of the mBuild Compound hierarchy):

ethane = mb.lib.molecules.Ethane()
ethane.name = "ethane"
benzene = mb.load("c1ccccc1", smiles=True)
benzene.name = "benzene"
box = mb.fill_box([benzene, ethane], n_compounds=[1, 1], box=[2, 2, 2])
top = from_mbuild(box)
for site in top.sites:
    if site.molecule.name == "benzene":
        site.molecule.isrigid = True
snapshot, refs, rigid = to_gsd_snapshot(top)

NetworkX 

GMSO topologies can be converted to and from NetworkX graphs for graph-based analysis.

`gmso.external.from_networkx`	Convert a `networkx.Graph` to a `Topology`.
`gmso.external.to_networkx`	Convert a `Topology` to a `networkx.Graph`.

from_networkx 

gmso.external.from_networkx(graph)[source]

Convert a networkx.Graph to a Topology.

Each graph node must be a Site and each edge becomes a Bond.

Parameters:: graph (Graph) – Graph whose nodes are Site instances. Edge data may optionally contain a 'connection' key holding a Connection object.
Returns:: Topology containing the sites and bonds from graph.
Return type:: Topology

Notes

Much information is lost when converting a topology to a graph (mixing rules, metadata, etc.). The edge 'connection' attribute stores the original Bond and is used to reconstruct it during the reverse conversion.

Angle and dihedral information stored as node attributes is detected but not converted; a warning is logged if such data is found.

Raises:: TypeError – If graph is not a networkx.Graph or if any node is not a Site.

to_networkx 

gmso.external.to_networkx(top, parse_angles=True, parse_dihedrals=True)[source]

Convert a Topology to a networkx.Graph.

Each site becomes a graph node and each bond becomes an edge.

Parameters:

top (Topology) – The topology to convert.
parse_angles (bool) – When True, populate an 'angles' attribute on every node with the list of angles that include that site.
parse_dihedrals (bool) – When True, populate a 'dihedrals' attribute on every node with the list of dihedrals that include that site.

Returns:

Graph where nodes are Atom objects and edges carry a 'connection' attribute holding the corresponding Bond.

Return type:

Graph

Notes

Converting to a graph loses metadata, mixing rules, and all potential type information. The graph is primarily useful for connectivity analysis.