2. Molecule API¶

Bases: moldesign.molecules.atomcollections.AtomContainer, moldesign.molecules.molecule.MolConstraintMixin, moldesign.molecules.molecule.MolPropertyMixin, moldesign.molecules.molecule.MolDrawingMixin, moldesign.molecules.molecule.MolReprMixin, moldesign.molecules.molecule.MolTopologyMixin, moldesign.molecules.molecule.MolSimulationMixin

Molecule objects store a molecular system, including atoms, 3D coordinates, molecular properties, biomolecular entities, and other model-specific information. Interfaces with simulation models take place through the molecule object.

Molecule objects will generally be created by reading files or parsing other input; see, for example: moldesign.read(), moldesign.from_smiles(), moldesign.from_pdb(), etc.

This constructor is useful, however for copying other molecular structures (see examples below).

Examples

Use the Molecule class to create copies of other molecules and substructures thereof: >>> benzene = mdt.from_name(‘benzene’) >>> benzene_copy = mdt.Molecule(benzene, name=’benzene copy’)

>>> protein = mdt.from_pdb('3AID')
>>> carbon_copies = mdt.Molecule([atom for atom in protein.atoms if atom.atnum==6])
>>> first_residue_copy = mdt.Molecule(protein.residues[0])

Molecule instance attributes:

atoms¶

AtomList – List of all atoms in this molecule.

bond_graph¶

dict – symmetric dictionary specifying bonds between the atoms:

bond_graph = {atom1:{atom2:bond_order, atom3:bond_order}, atom2:...}

bond_graph[atom1][atom2] == bond_graph[atom2][atom1]

residues¶

List[moldesign.Residue] – flat list of all biomolecular residues in this molecule

chains¶

Dict[moldesign.Chain] – Biomolecular chains - individual chains can be accessed as mol.chains[list_index] or mol.chains[chain_name]

name¶

str – A descriptive name for molecule

charge¶

units.Scalar[charge] – molecule’s formal charge

constraints¶

List[moldesign.geom.GeometryConstraint] – list of constraints

ndims¶

int – length of the positions, momenta, and forces arrays (usually 3*self.num_atoms)

num_atoms¶

int – number of atoms (synonym: natoms)

num_bonds¶

int – number of bonds (synonym: nbonds)

positions¶

units.Array[length] – Nx3 array of atomic positions

momenta¶

units.Array[momentum] – Nx3 array of atomic momenta

masses¶

units.Vector[mass] – vector of atomic masses

dim_masses¶

units.Array[mass] – Nx3 array of atomic masses (for numerical convenience - allows you to calculate velocity, for instance, as velocity = mol.momenta/mol.dim_masses

time¶

units.Scalar[time] – current time in dynamics

energy_model¶

moldesign.models.base.EnergyModelBase – Object that calculates molecular properties - driven by mol.calculate()

integrator¶

moldesign.integrators.base.IntegratorBase – Object that drives movement of 3D coordinates in time, driven by mol.run()

is_biomolecule¶

bool – True if this molecule contains at least 2 biochemical residues

Molecule methods and properties

See also methods offered by the mixin superclasses:

• moldesign.molecules.AtomContainer
• moldesign.molecules.MolPropertyMixin
• moldesign.molecules.MolDrawingMixin
• moldesign.molecules.MolSimulationMixin
• moldesign.molecules.MolTopologyMixin
• moldesign.molecules.MolConstraintMixin
• moldesign.molecules.MolReprMixin

addatom(newatom)[source]¶

Add a new atom to the molecule

Parameters:	newatom (moldesign.Atom) – The atom to add (it will be copied if it already belongs to a molecule)

addatoms(newatoms)[source]¶

Add new atoms to this molecule. For now, we really just rebuild the entire molecule in place.

Parameters:	newatoms (List[moldesign.Atom]) –

bonds¶

Iterator over all bonds in the molecule

Yields:	moldesign.atoms.Bond – bond object

deletebond(bond)[source]¶

Remove this bond from the molecule’s topology

Parameters:	Bond – bond to remove

is_small_molecule¶

bool – True if molecule’s mass is less than 500 Daltons (not mutually exclusive with self.is_biomolecule)

nbonds¶

int – number of chemical bonds in this molecule

newbond(a1, a2, order)[source]¶

Create a new bond

Parameters:	a1 (moldesign.Atom) – First atom in the bond a2 (moldesign.Atom) – Second atom in the bond order (int) – order of the bond
Returns:	moldesign.Bond

num_bonds¶

int – number of chemical bonds in this molecule

velocities¶

u.Vector[length/time] – Nx3 array of atomic velocities

write(filename=None, **kwargs)[source]¶

Write this molecule to a string or file.

This is a convenience method for moldesign.converters.write

Parameters:	filename (str) – filename to write (if not passed, write to string) format (str) – file format (if filename is not passed, format must be specified) Guessed from file extension if not passed

Bases: moldesign.molecules.atoms.AtomDrawingMixin, moldesign.molecules.atoms.AtomGeometryMixin, moldesign.molecules.atoms.AtomPropertyMixin, moldesign.molecules.atoms.AtomReprMixin

A data structure representing an atom.

Atom objects store information about individual atoms within a larger molecular system, providing access to atom-specific geometric, biomolecular, topological and property information. Each Molecule is composed of a list of atoms.

Atoms can be instantiated directly, but they will generally be created automatically as part of molecules.

Atom instance attributes:

name¶

str – A descriptive name for this atom

element¶

str – IUPAC elemental symbol (‘C’, ‘H’, ‘Cl’, etc.)

index¶

int – the atom’s current index in the molecule (self is self.parent.atoms[ self.index])

atnum¶

int – atomic number (synonyms: atomic_num)

mass¶

u.Scalar[mass] – the atom’s mass

position¶

units.Vector[length] – atomic position vector. Once an atom is part of a molecule, this quantity will refer to self.molecule.positions[self.index].

momentum¶

units.Vector[momentum] – atomic momentum vector. Once an atom is part of a molecule, this quantity will refer to self.molecule.momenta[self.index].

x,y,z

u.Scalar[length] – x, y, and z components of atom.position

vx, vy, vz

u.Scalar[length/time] – x, y, of atom.velocity

px, py, pz

u.Scalar[momentum] – x, y, and z of atom.momentum

fx, fy, fz

u.Scalar[force] – x, y, and z atom.force

residue¶

moldesign.Residue – biomolecular residue that this atom belongs to

chain¶

moldesign.Chain – biomolecular chain that this atom belongs to

parent¶

moldesign.Molecule – molecule that this atom belongs to

index

int – index in the parent molecule: atom is atom.parent.atoms[index]

Atom methods and properties

See also methods offered by the mixin superclasses:

• AtomDrawingMixin
• AtomGeometryMixin
• AtomPropertyMixin
• AtomReprMixin

bond_graph¶

Mapping[Atom, int] – dictionary of this atoms bonded neighbors, of the form {bonded_atom1, bond_order1, ...}

bond_to(other, order)[source]¶

Create or modify a bond with another atom

Parameters:	other (Atom) – atom to bond to order (int) – bond order
Returns:	bond object
Return type:	moldesign.molecules.bonds.Bond

bonds¶

List[Bond] – list of all bonds this atom is involved in

copy(self)¶

Copy a group of atoms which may already have bonds, residues, and a parent molecule assigned. Do so by copying only the relevant entities, and creating a “mask” with deepcopy’s memo function to stop anything else from being copied.

Returns:	list of copied atoms
Return type:	AtomList

elem¶

str – elemental symbol

element¶

str – elemental symbol

force¶

(units.Vector[force]) – atomic force vector. This quantity must be calculated - it is equivalent to self.molecule.forces[self.index]

Raises:	moldesign.NotCalculatedError – if molecular forces have not been calculated

heavy_bonds¶

List[Bond] – list of all heavy atom bonds (where BOTH atoms are not hydrogen)

Note

this returns an empty list if called on a hydrogen atom

nbonds¶

int – the number of other atoms this atom is bonded to

num_bonds¶

int – the number of other atoms this atom is bonded to

symbol¶

str – elemental symbol

to_json(parent=None)[source]¶

Designed to be called by the MdtJsonEncoder

valence¶

int – the sum of this atom’s bond orders

velocity¶

u.Vector[length/time, 3] – velocity of this atom; equivalent to self.momentum/self.mass