Loading Data

Data is input into mBuild in a few different ways or from different file types.


Load a file or an existing topology into an mbuild Compound.

Files are read using the predefined backend, unless otherwise specified by the user (through the backend flag). Supported backends include “pybel”, “mdtraj”, “parmed”, “rdkit”, and “internal”. Please refer to http://mdtraj.org/1.8.0/load_functions.html for formats supported by MDTraj and https://parmed.github.io/ParmEd/html/readwrite.html for formats supported by ParmEd.


filename_or_objectstr, mdtraj.Trajectory, parmed.Structure,

mbuild.Compound, pybel.Molecule, Name of the file or topology from which to load atom and bond information.

relative_to_modulestr, optional, default=None

Instead of looking in the current working directory, look for the file where this module is defined. This is typically used in Compound classes that will be instantiated from a different directory (such as the Compounds located in mbuild.lib).

compoundmb.Compound, optional, default=None

Existing compound to load atom and bond information into. New structure will be added to the existing compound as a sub compound.

coords_onlybool, optional, default=False

Only load the coordinates into an existing compound.

rigidbool, optional, default=False

Treat the compound as a rigid body

backendstr, optional, default=None

Backend used to load structure from file or string. If not specified, a default backend (extension specific) will be used.

smiles: bool, optional, default=False

Use RDKit or OpenBabel to parse filename as a SMILES string or file containing a SMILES string. If this is set to True, rdkit is the default backend.

infer_hierarchybool, optional, default=True

If True, infer hierarchy from chains and residues

ignore_box_warnbool, optional, default=False

If True, ignore warning if no box is present. Defaults to True when loading from SMILES

**kwargskeyword arguments

Key word arguments passed to mdTraj, RDKit, or pybel for loading.


compound : mb.Compound


If smiles is True, either rdkit (default) or pybel can be used, but RDkit is the only option of these that allows the user to specify a random number seed to reproducibly generate the same starting structure. This is NOT possible with openbabel, use rdkit if you need control over starting structure’s position (recommended).

Load CIF

Load a CifFile object into an mbuild.Lattice.


wrap_coordsbool, False

Wrap the lattice points back into the 0-1 acceptable coordinates.