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


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>)[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
  • If the Compound has 4 or more levels of hierarchy, these are compressed to 3 levels of hierarchy in the resulting Topology. The top level Compound becomes the Topology, the second level Compounds become SubTopologies, and each particle becomes a Site, which are added to their corresponding SubTopologies.
  • Furthermore, Sites that do not belong to a sub-Compound are added to a single-Site SubTopology.
  • The box dimension are extracted from compound.periodicity. If the compound.periodicity is None, the box lengths are the lengths of the bounding box + a 0.5 nm buffer.
  • 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.
  • 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’


Return type:



Convert a gmso.Topology to mbuild.Compound

Parameters:topology (gmso.Topology) – topology instance that need to be converted
Return type:mbuild.Compound


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. At this point, this method can only convert AtomType, BondType and AngleType. Conversion of DihedralType will be implement in the near future.

  • 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, and DihedralType information


Return type:



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.

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


Return type:

Untyped topology or modeller object