structural_units

Module in which all structural units are defined.

Atom is the fundamental structural unit in terms of which all others must be defined. All shared behaviour is included within the StructuralUnit base class.

class MDMC.MD.structural_units.Atom(element, position=(0.0, 0.0, 0.0), velocity=(0.0, 0.0, 0.0), charge=None, **settings)

A single atom

Parameters

• element (str) – The atomic element label.

• position (list, tuple, numpy.ndarray, optional) – A 3 element list, tuple or array with the position in units of Ang. The default is (0., 0., 0.).

• velocity (list, tuple, numpy.ndarray, optional) – A 3 element list, tuple or array with the velocity in units of Ang / fs. Note that if set, the velocity of atoms in the MD engine will be scaled when creating a Simulation in order to ensure the temperature is accurate. Otherwise, if the velocities of all Atom objects in a Simulation are 0, then the velocities of the atoms in the MD engine will be randomly chosen in order to provide an accurate temperature. The default is (0., 0., 0.).

• charge (float) – The charge of the Atom in units of elementary charge (e). The default is None, meaning that a Coulomb interaction is not applied to the Atom.

• **settings –

  mass (float)

  The atomic mass in amu. If not provided a lookup table will be used.

  atom_type (int)

  All atoms with the same atom_type will have the same non-bonded interactions applied to them. If not provided, MDMC will automatically infer/assign atom types. All atoms with the same element and interactions will have the same atom type.

  name (str)

  A name to uniquely identify the atom. Used by ForceFields (e.g. OPLSAA). Atoms should only have the same names if they are equivalent. Defaults to the element of the atom.

element

The atomic element label

Type

str

add_interaction(interaction, from_interaction=False)

Adds an interaction to the Atom

Parameters

• interaction (MDMC.MD.interactions.Interaction) – Any class dervied from Interaction, or any object with base class Interaction. If an Interaction class is passed then it must be a NonBondedInteraction i.e. only takes a single Atom as an argument. If an Interaction object is passed then this Atom must be in the interaction.atoms.

• from_interaction (bool, optional) – Specifies if this method has been called from an Interaction. Default is False.

property atom_type

Get or set the atom type of the Atom

Returns

The atom type

Return type

int

Raises

AttributeError – The atom_type cannot be changed once it has been set

property atoms

Get a list of the atoms, just consisting of the Atom

Returns

A list with a single item, the Atom

Return type

list

property bonded_interaction_pairs

Get bonded interactions acting on the Atom and the other atoms to which the Atom is bonded

Returns

(interaction, atoms) pairs acting on the Atom, where atoms is a tuple of all Atom objects for that specific bonded interaction.

Return type

list

Example

For an O Atom with two bonds, one to H1 and one to H2:

>>> print(O.bonded_interaction_pairs)
[(Bond, (H1, O)), (Bond, (H2, O))]

property charge

Get or set the charge in e if one has been applied to the Atom

If the Atom does not have a Coulombic interaction, setting a value of the charge will create one, and a default cutoff of 10. Ang will be applied

Returns

The charge in units of e, or None if no charge has been set

Return type

float

Raises

• ValueError – When the Atom has more than one Coulombic interaction

• ValueError – When the Atom has more than one parameter; i.e. should only have charge as a parameter

• ValueError – When setting charge to None when a Coulombic interaction already exists.

copy(position)

Copies the Atom and all attributes, except ID which is generated

Copying an Atom creates an exact duplicate at the specified position. The copied Atom will have identical bonded and nonbonded interactions as the original. For BondedInteractions this means that the copied atom will be bonded to all atoms to which the original atom is bonded. The ID of the copied atom will differ from the original, as they are sequentially generated.

Parameters

position (list, tuple, numpy.ndarray) – A 3 element list, tuple or array with the position of the new Atom

Returns

A copy of the Atom with the specified position

Return type

Atom

Examples

If the following Atom is copied:

H1 = Atom('H', position=(0., 0., 0.), charge=0.4238)
H2 = H1.copy(position=(1., 1., 1.))

then the new Atom (H2) will have no BondedInteractions, but will have a Coulombic interaction, with a charge of 0.4238 e

If H1 and H2 are then bonded together and a copy is made:

HHbond = Bond((H1, H2))
H3 = H1.copy(position=(2., 2., 2.))

then the newest Atom (H3) will have a Coulombic interaction (also with a charge of 0.4238 e), and it will also have a Bond interaction with H2 (as H1 had a Bond interaction with H2).

copy_interactions(atom, memo=None)

This replicates the interactions from self for Atom, but with self substituted by atom in the Interaction.atoms. These interactions are added to any that already exist for the Atom.

Passing the memo dict enables specific interactions to be excluded from being copied, duplicating the behaviour of __deepcopy__

Parameters

• atom (Atom) – The Atom for which self.interactions are being replicated

• memo (dict, optional) – The memoization dict

property mass

Get or set the atomic mass in amu

Returns

the atomic mass in amu

Return type

float

property nonbonded_interactions

Get a list of the nonbonded interactions acting on the Atom

Returns

NonBondedInteractions acting on the Atom

Return type

list

property universe

Get the Universe to which the Atomm belongs

Returns

The Universe to which the Atom belongs or None

Return type

Universe

class MDMC.MD.structural_units.BoundingBox(atoms: List)

A box with the minimum and maximum extents of the positions of a collection of atoms

Parameters

atoms (list) – Atom objects for which the minimum and maximum extents are determined

property max

Get or set the maximum extent of the positions of a collection of atoms

Returns

The maximum extent in Ang

Return type

numpy.ndarray

property min

Get or set the minimum extent of the positions of a collection of atoms

Returns

The minimum extent in Ang

Return type

numpy.ndarray

class MDMC.MD.structural_units.CompositeStructuralUnit(position, velocity, name)

Base class for structural units comprised of more than one Atom

abstract property bonded_interaction_pairs

Get bonded interactions acting on the StructuralUnit and the other atoms to which the atom is bonded

Returns

(interaction, atoms) pairs acting on the StructuralUnit, where atoms is a tuple of all Atom objects for that specific bonded interaction. At least one of these Atom objects belongs to the StructuralUnit

Return type

list

Example

For an O Atom with two bonds, one to H1 and one to H2:

>>> print(O.bonded_interaction_pairs)
[(Bond, (H1, O)), (Bond, (H2, O))]

copy(position, rotation=None)

Copies the CompositeStructuralUnit and all attributes, except ID which is generated

Copying a CompositeStructuralUnit (e.g. a Molecule) will copy all of the Atom objects within it. All of these atoms will have identical bonded and nonbonded interactions to the CompositeStructuralUnit from which they were copied i.e. the CompositeStructuralUnit will be exacltly duplicated. The only attributes of the CompositeStructuralUnit which will differ are the position (which is passed as a Parameter to copy), and the ID, which is generated automatically.

This will not currently work if the CompositeStructuralUnit has any bonded interactions with atoms external to it (e.g. it may cause issues for copying molecules with groups)

Interactions for Atom objects may be reordered with respect to initial atoms

Parameters

• position (list, tuple, numpy.ndarray) – 3 element list, tuple or array of float specifying the position of the new StructuralUnit

• rotation (list, tuple, numpy.ndarray, optional) – 3 element list, tuple or array of floats specifying the degrees of anticlockwise rotation around the x, y, and z axes respectively. The rotation is centered on the center of mass of the CompositeStructuralUnit. The default rotation is None, which applies no rotation to the copied CompositeStructuralUnit.

Returns

A CompositeStructuralUnit of the same type with all non-unique attributes copied and a new position

Return type

CompositeStructuralUnit

property formula

Get the chemical formula of the CompositeStructuralUnit

Returns

The chemical formula using the Hill system

Return type

str

abstract property nonbonded_interactions

Get a list of the nonbonded interactions acting on the StructuralUnit

Returns

NonBondedInteractions acting on the StructuralUnit

Return type

list

rotate(x=0.0, y=0.0, z=0.0)

Rotates the CompositeStructuralUnit around its center of mass

In all cases (e.g. x, y and z) the rotation is anticlockwise about the specific axis

Parameters

• x (float, optional) – The angle of rotation around the x-axis in deg. The default is 0.

• y (float, optional) – The angle of rotation around the y-axis in deg. The default is 0.

• z (float, optional) – The angle of rotation around the z-axis in deg. The default is 0.

property structure_list

Get or set the StructuralUnit objects that are subunits of this CompositeStructuralUnit

Returns

list of StructuralUnit that are subunits of this CompositeStructuralUnit

Return type

list

property universe

Get or set the Universe to which the CompositeStructuralUnit belongs

Returns

The Universe to which the CompositeStructuralUnit belongs or None

Return type

Universe

class MDMC.MD.structural_units.Molecule(position=None, velocity=(0, 0, 0), name=None, **settings)

Two or more bonded atoms

Must be declared with at least 2 Atom objects.

Parameters

• position (list, tuple, numpy.ndarray, optional) – A 3 element list, tuple or array with the position in units of Ang. The default is None, which sets the position of the Molecule to be equal to the center of mass of the atoms in the Molecule.

• velocity (list, tuple, numpy.ndarray, optional) – A 3 element list, tuple or array with the velocity in units of Ang / fs. The default is (0., 0., 0.).

• name (str, optional) – The name of the structure. The default is None.

• **settings –

  atoms (list)

  A list of Atom which will be included in the Molecule

  interactions (list)

  A list of Interaction acting on atoms within the Molecule. The interactions provides a convenience for declaring interactions on atoms when a Molecule is initialized. It is not required and is exactly equivalent to initializing the interactions prior to the Molecule.

property bonded_interaction_pairs

Get bonded interactions acting on the Molecule

Returns

(interaction, atoms) pairs acting on the Molecule, where atoms is a tuple of all atoms for that specific bonded interaction. At least one of these atoms belongs to the Molecule

Return type

list

Example

For an O Atom with two bonds, one to H1 and one to H2:

>>> print(O.bonded_interaction_pairs)
[(Bond, (H1, O)), (Bond, (H2, O))]

property nonbonded_interactions

Get a list of the nonbonded interactions acting on the Molecule

Returns

NonBondedInteraction objects acting on the Molecule

Return type

list

property position

Get or set the position of the center of mass of the Molecule in Ang

Also sets the positions of all subunits

Return type

numpy.ndarray

class MDMC.MD.structural_units.StructuralUnit(position, velocity, name)

Abstract base class for all structural units

Parameters

• position (list, tuple, numpy.ndarray) – A 3 element list, tuple or array with the position in units of Ang.

• velocity (list, tuple, numpy.ndarray) – A 3 element list, tuple or array with the velocity in units of Ang / fs.

• name (str) –

  The name of the structure.

  Attributes

• ---------- – ID : int A unique identifier for each StructuralUnit.

• universe (Universe) – The Universe to which the StructuralUnit belongs.

• name – The name of the structure.

• parent (StructuralUnit) – StructuralUnit to which this unit belongs, or self

property atoms

Get a list of all of the Atom objects in the structure by recursively calling atoms for all substructures

Returns

All atoms in the structure

Return type

list

abstract property bonded_interaction_pairs

Get bonded interactions acting on the StructuralUnit and the other atoms to which the atom is bonded

Returns

(interaction, atoms) pairs acting on the StructuralUnit, where atoms is a tuple of all Atom objects for that specific bonded interaction. At least one of these Atom objects belongs to the StructuralUnit

Return type

list

Example

For an O Atom with two bonds, one to H1 and one to H2:

>>> print(O.bonded_interaction_pairs)
[(Bond, (H1, O)), (Bond, (H2, O))]

property bonded_interactions

Get a list of the bonded interactions acting on the StructuralUnit

Returns

BondedInteractions acting on the StructuralUnit

Return type

list

property bounding_box

returns: Contains the lower and upper extents of the Molecule :rtype: BoundingBox

copy(position)

Copies the structural unit and sets the position

Parameters

position (list, tuple, numpy.ndarray) – 3 element list, tuple or array of float specifying the position of the new StructuralUnit

Returns

A StructuralUnit of the same type with all non-unique attributes copied and a new position

Return type

StructuralUnit

property interactions

Get a list of the interactions acting on the StructuralUnit

Returns

Interactions acting on the StructuralUnit

Return type

list

abstract property nonbonded_interactions

Get a list of the nonbonded interactions acting on the StructuralUnit

Returns

NonBondedInteractions acting on the StructuralUnit

Return type

list

property position

Get or set the position of the center of mass of the StructuralUnit in Ang

Return type

numpy.ndarray

property structure_type

Get the class of the StructuralUnit.

Returns

The name of the class

Return type

str

property top_level_structure

Get the top level structure (i.e. StructuralUnit which has no parent) of the StructuralUnit

Returns

Highest level StructuralUnit of which it is a member

Return type

StructuralUnit

translate(displacement)

Translate the structural unit by the specified displacement

Parameters

Displacement (tuple, numpy.ndarray) – A three element tuple or array of float

abstract property universe

Get the Universe to which the StructuralUnit belongs

Returns

The Universe to which the StructuralUnit belongs or None

Return type

Universe

valid_position(position=None)

Checks if the specified position is within the bounds of the StructuralUnit.universe, if it has one

Parameters

position (list, tuple, numpy.ndarray) – 3 element list, tuple or array with units of Ang or None. If None then the position of the StructuralUnit is used.

Returns

True if position is within Universe or there is no associated Universe. False if StructuralUnit has an associated Universe but the position is not within its bounds.

Return type

bool

Raises

ValueError – If position if undefined

property velocity

Get or set the velocity of the StructuralUnit in Ang/fs

Return type

numpy.ndarray

MDMC.MD.structural_units.filter_atoms(atoms, predicate)

Filters a list of Atoms with a given predicate

Parameters

• atoms (list) – A list of Atom

• predicate (function) – A function that returns a bool

Returns

Atom objects in atoms which meet the condition of predicate

Return type

list

MDMC.MD.structural_units.filter_atoms_element(atoms, element)

Filters a list of atoms based on the atomic element

Parameters

• atoms (list) – A list of Atom

• element (str) – The atomic element label

Returns

Atom objects of a specific element

Return type

list

MDMC.MD.structural_units.get_reduced_chemical_formula(symbols, factor=None, system='Hill')

Get the reduced chemical formula

Parameters

• symbols (list of str) – The chemical formula to be reduced. It is expressed as a list of elements, with a single element for each atom. Elements are grouped by type but not ordered e.g. all 'O' values, then all 'H' values etc.

• factor (int, optional) – The factor by which the total number of symbols will be reduced. If None, the greatest common divisor of the different symbols will be used. The default is None.

• system (str, optional) – Determines the order of the chemical formula. If 'Hill' the Hill system is used to determine the order. If None, the order is based on the order of `symbols. The default is 'Hill'.

Returns

The chemical formula corresponding to symbols, except with only n_atoms. If system is 'Hill', the formula will be ordered as per the Hill system, otherwise the formula will be ordered based on the order of symbols.

Return type

str

Example

Reducing the formula for four water molecules to a single water molecules:

>>> get_reduced_chemical_formula(['H'] * 8 + ['O'] * 4)
'H2O'

Reducing the formula for four water molecules to two water molecules:

>>> get_reduced_chemical_formula(['H'] * 8 + ['O'] * 4, factor=2)
'H4O2'