External

This submodule includes functions that convert core data structures between external libraries and their internal representation.

mBuild

The following methods are available for converting mBuild objects to and from GMSO.

gmso.external.from_mbuild(compound, box=None, search_method=<function 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 (mbuild.Compound) – mbuild.Compound instance that need to be converted

  • box (mbuild.Box, optional, default=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, optional, default=True) – 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, default=False) – 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:

gmso.Topology

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

Convert a gmso.Topology to mbuild.Compound.

Parameters:

  • topology (gmso.Topology) – topology instance that need to be converted

  • infer_hierarchy (bool, optional, default=True) – Option to infer the hierarchy from Topology’s labels

Returns:

compound

Return type:

mbuild.Compound

Parmed

Conversion methods for Parmed objects to and from GMSO.

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

Convert a parmed.Structure to a gmso.Topology.

Convert a parametrized or un-parametrized parmed.Structure object to a topology.Topology. Specifically, this method maps Structure to Topology and Atom to Site. This method can only convert AtomType, BondType AngleType, DihedralType, and ImproperType.

Parameters:

  • structure (parmed.Structure) – parmed.Structure instance that need to be converted.

  • refer_type (bool, optional, default=True) – Whether or not to transfer AtomType, BondType, AngleType, DihedralType, and ImproperType information

Returns:

top

Return type:

gmso.Topology

OpenMM

Conversion methods for OpenMM objects to and from GMSO.

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

Convert an untyped topology object to an untyped OpenMM modeller or topology.

This is useful if it’s preferred to atom-type a system within OpenMM. See http://openmm.org for more information.

Parameters:

  • topology (Topology object) – An untyped topology object

  • open_mm_object (‘topology’ or ‘modeller’ OpenMM object, default=’topology’) – Untyped OpenMM object to convert to

Returns:

open_mm_object

Return type:

Untyped topology or modeller object