simulation

Module for setting up and running the simulation

Classes for the simulation box, minimizer and integrator.

class MDMC.MD.simulation.ConstraintAlgorithm(accuracy, max_iterations)[source]

Class describing the algorithm and parameters which are applied to constrain BondedInteraction objects

Parameters
  • accuracy (float) – The accuracy (tolerance) of the applied constraints

  • max_iterations (int) – The maximum number of iterations that can be used when calculating the additional force that is required to constrain the atoms to satisfy the constraints on the bonded interactions

accuracy

The accuracy (tolerance) of the applied constraints

Type

float

property max_iterations

Get or set the maximum number of iterations that can be used when calculating the additional force that is required to constrain the atoms to satisfy the constraints on the bonded interactions

Returns

The maximum number of iterations

Return type

int

property name

Get the name of the class

Returns

The name of the class

Return type

str

class MDMC.MD.simulation.Ewald(**settings)[source]

Holds the parameters that are required for the Ewald solver to be applied to both/either the electrostatic and/or dispersion interactions

Parameters

**settings

accuracy (float)

The relative RMS error in per-atom forces

class MDMC.MD.simulation.KSpaceSolver(**settings)[source]

Class describing the k-space solver that is applied to electrostatic and/or dispersion interactions

Different MDEngine require different parameters to be specified for a k-space solver to be used. These parameters are specified in settings.

Parameters

**settings

accuracy (float)

The relative RMS error in per-atom forces

accuracy

The relative RMS error in per-atom forces

Type

float

property name

Get the name of the class

Returns

The name of the class

Return type

str

class MDMC.MD.simulation.PPPM(**settings)[source]

Holds the parameters that are required for the PPPM solver to be applied to both/either the electrostatic and/or dispersion interactions

Parameters

**settings

accuracy (float)

The relative RMS error in per-atom forces

class MDMC.MD.simulation.Rattle(accuracy, max_iterations)[source]

Holds the parameters which are required for the RATTLE algorithm to be applied to the constrained interactions

Parameters
  • accuracy (float) – The accuracy (tolerance) of the applied constraints

  • max_iterations (int) – The maximum number of iterations that can be used when calculating the additional force that is required to constrain the atoms to satisfy the constraints on the bonded interactions

class MDMC.MD.simulation.Shake(accuracy, max_iterations)[source]

Holds the parameters which are required for the SHAKE algorithm to be applied to the constrained interactions

Parameters
  • accuracy (float) – The accuracy (tolerance) of the applied constraints

  • max_iterations (int) – The maximum number of iterations that can be used when calculating the additional force that is required to constrain the atoms to satisfy the constraints on the bonded interactions

class MDMC.MD.simulation.Simulation(universe: MDMC.MD.simulation.Universe, traj_step: int, time_step: float = 1.0, engine: str = 'lammps', **settings)[source]

Sets up the molecular dynamics engine and parameters for how it should run

An ensemble is defined by whether a thermostat or barostat are present

Parameters
  • universe (Universe) – The Universe on which the simulation is performed.

  • traj_step (int) – How many steps the simulation should take between dumping each Trajectory frame. Along with time_step determines the time separation of calculated variables such as energy.

  • time_step (float, optional) – Simulation timestep in fs. Default is 1.

  • engine (str, optional) – The MDEngine used for the simulation. Default is 'lammps'.

  • **settings

    temperature (float)

    Simulation temperature in K. Note that velocities of atoms in the MD engine are set based on the temperature. If all atoms in the universe have 0 velocity, then velocities for the MD engine will be randomly chosen from a uniform distribution and then scaled to give the correct temperature. If one or more velocities are set, then these will be scaled to give the correct temperature. In either case, only the velocities on the engine, not the universe, are affected.

    integrator (str)

    Simulation time integrator.

    lj_options (dict)

    option:value pairs for Lennard-Jones interactions.

    es_options (dict)

    option:value pairs for electrostatic interactions.

    thermostat (str)

    The name of the thermostat e.g. Nose-Hoover.

    barostat (str)

    The name of the barostat e.g. Nose-Hoover.

    pressure (float)

    Simulation pressure in Pa. This is required if a barostat is passed.

universe

The Universe on which the simulation is performed.

Type

Universe

traj_step

How many steps the simulation should take between dumping each Trajectory frame. Along with time_step determines the time separation of calculated variables such as energy.

Type

int

engine

A subclass of MDEngine which provides the interface to the MD library. Default is 'lammps'.

Type

MDEngine, optional

settings

The settings passed to the Simulation. See the Parameters section for details.

Type

dict

minimize(n_steps: int, verbose: bool = False, output_log: Optional[str] = None, work_dir: Optional[str] = None, **settings)[source]

Minimizes the total potential energy of the simulated system by modifying the positions of the constituent atoms until one of the stopping criteria is met.

Parameters
  • n_steps (int) – Maximum number of steps to run the minimization

  • verbose (bool, optional) – Whether to print statements when the minimization has been started and completed (including the number of minimization steps and time taken). Default is False.

  • output_log (str, optional) – Log file for the MD engine to write to. Default is None.

  • work_dir (str, optional) – Working directory for the MD engine to write to. Default is None.

  • **settings

    etol (float)

    If the energy change between iterations is less than etol, minimization is stopped. Default depends on engine used.

    ftol (float)

    If the magnitude of the global force is less than ftol, minimization is stopped. Default depends on engine used.

    maxeval (int)

    Maximum number of force evaluations to perform. Default depends on engine used.

    nfreq (int)

    Frequency at which minimisation is performed. Default depends on engine used.

run(n_steps: int, equilibration: bool = False, verbose: bool = False, output_log: Optional[str] = None, work_dir: Optional[str] = None, **settings)[source]

Runs the MD simulation for the specified number of steps. Trajectories for the simulation are only saved when equilibration is False. Additionally running equilibration for an NVE system (neither barostat nor thermostat set) will temporarily apply a Berendsen thermostat (it is removed from the simulation after the run is completed).

Parameters
  • n_steps (int) – Number of simulation steps to run

  • equilibration (bool, optional) – If the run is for equilibration (True) or production (False). Default is False.

  • verbose (bool, optional) – Whether to print statements upon starting and completing the run. Default is False.

  • output_log (str, optional) – Log file for the MD engine to write to. Default is None.

  • work_dir (str, optional) – Working directory for the MD engine to write to. Default is None.

property time_step

Get or set the simulation time step in fs

Returns

Simulation time step in fs

Return type

float

property traj_step

Get or set the number of simulation steps between saving the Trajectory

Returns

Number of simulation steps that elapse between the Trajectory being stored

Return type

int

property trajectory

The Trajectory produced by the most recent production run of the Simulation.

Returns

Most recent production run Trajectory, or None if no production run has been performed

Return type

Trajectory

class MDMC.MD.simulation.Universe(dimensions, force_field=None, structures=None, **settings)[source]

Class where the configuration and topology are defined

Parameters
  • dimensions (numpy.ndarray, list, float) – Dimensions of the Universe, in units of Ang. A float can be used for a cubic universe.

  • force_field (ForceField, optional) – A force field to apply to the Universe. The force fields available are: TIP3PFB, SPC, OPLSAA, TIP3P, SPCE. Default is None.

  • structures (list, optional) – Structure objects contained in the Universe. Default is None.

  • **settings

    kspace_solver (KSpaceSolver)

    The k-space solver to be used for both electrostatic and dispersive interactions. If this is passed then no electrostatic_solver or dispersive_solver may be passed.

    electrostatic_solver (KSpaceSolver)

    The k-space solver to be used for electrostatic interactions.

    dispersive_solver (KSpaceSolver)

    The k-space solver to be used for dispersive interactions.

    constraint_algorithm (ConstraintAlgorithm)

    The constraint algorithm which will be applied to constrained BondedInteractions.

dimensions

Dimensions of the Universe in units of Ang.

Type

numpy.ndarray, list, float

configuration

Stores the content, i.e. configuration of atoms etc within the universe

Type

Configuration

force_field

Force field to apply to the Universe

Type

ForceField or None

kspace_solver

The k-space solver to be used for both electrostatic and dispersive interactions.

Type

KSpaceSolver

electrostatic_solver

The k-space solver to be used for electrostatic interactions.

Type

KSpaceSolver

dispersive_solver

The k-space solver to be used for dispersive interactions.

Type

KSpaceSolver

constraint_algorithm

The constraint algorithm which will be applied to constrained BondedInteractions.

Type

ConstraintAlgorithm

add_bonded_interaction_pairs(*bonded_interaction_pairs)[source]

Adds one or more interaction pairs to the Universe

Parameters

*bonded_interaction_pairs – one or more (interaction, atoms) pairs, where atoms is a tuple of all atoms for that specific bonded interaction

add_force_field(force_field, *interactions, **settings)[source]

Adds a force field to the specified interactions. If no interactions are passed, the force field is applied to all interactions in the Universe.

Parameters
  • force_field (str) – The ForceField to parameterize interactions (if provided), or all the interactions in the Universe. The available ForceField are: TIP3PFB, SPC, OPLSAA, TIP3P, SPCE

  • *interactionsInteraction objects to parameterize with the ForceField

  • **settings

    add_dispersions (bool or list of Atoms)

    If True, a Dispersion interaction will be added to all atoms in the Universe. If a list of Atom objects is provided, the Dispersion will be added to these instead. Any added Dispersion interactions (and any previously defined) will then be parametrized by the ForceField. The Dispersion interactions added will only be like-like. By default, no Dispersion interactions are added.

add_nonbonded_interaction(*nonbonded_interactions)[source]

Adds one or more nonbonded interactions to the Universe

Parameters

*nonbonded_interactions

Nonbonded interactions to be added to the Universe. Can take any number of non-bonded interactions:

Dispersion():

either Lennard-Jones or Buckingham dispersion

Coulombic():

normal or modified Coulomb interaction

with appropriate parameters for the interaction. See http://mdmcproject.org/tutorials/building-a-universe.html?highlight=interaction#Create-non-bonded-interactions for more details on non-bonded interactions.

add_structure(structure, force_field=None, center=False)[source]

Adds a single Structure to the Universe, with optional ForceField applying only to that Structure

Parameters
  • structure (Structure or int) – The Structure (or its ID as an int) to be added to the Universe

  • force_field (str, optional) – The force field to be applied to the structure. The available ForceField are: TIP3PFB, SPC, OPLSAA, TIP3P, SPCE

  • center (bool, optional) – Whether to center structure within the Universe as it is added

property atom_type_interactions

Get the atom types and the interactions for each atom type

Returns

atom_type:interactions pairs where atom_type is a int specifying the atom type and interactions is a list of Interaction objects acting on that atom_type

Return type

dict

property atom_types

Get the atom types of atoms in the Universe

Returns

The atom types in the Universe

Return type

list

property atoms

Get a list of the atoms in the Universe

Returns

The atoms in the Universe

Return type

list

property bonded_interaction_pairs

Get the bonded interactions and the atoms they apply to

Returns

The (interaction, atoms) pairs in the Universe, where atoms is a tuple of all Atom objects for that specific 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 bonded_interactions

Get the bonded interactions in the Universe

Returns

The bonded interactions in the Universe

Return type

list

property element_dict

Get the elements in the Universe and example Atom objects for each element

This is required for MD engines which assign the same potential parameters for all identical element types.

Returns

element:atom pairs, where atom is a single Atom of the specified element.

Return type

dict

property element_list

The elements of the atoms in the Universe

Returns

The elements in the Universe

Return type

list

property element_lookup

Get the elements by ID in the Universe

This is required for MD engines which assign the same potential parameters for all identical element names.

Returns

element:atom pairs, where atom is a single Atom of the specified element.

Return type

dict

property equivalent_top_level_structures_dict: Dict[MDMC.MD.structures.Structure, int]

Get a dict of equivalent top level Structure objects that exist in the Universe as keys, and the number of Structure that are equivalent to the key as a value. This does not include any Structure that are a subunit of another structure belonging to the Universe.

Returns

The top level Structure objects in the Universe as keys, and the number of each as a value

Return type

dict

fill(structures: MDMC.MD.structures.Structure, force_field: str = None, num_density: float = None, num_struc_units: int = None)[source]

A liquid-like filling of the Universe independent of existing atoms

Adds copies of structures to existing configuration until Universe is full. As exclusion region is defined by the size of a bounding sphere, this method is most suitable for atoms or molecules with approximately equal dimensions.

Note

CURRENT APPROACH RESULTS IN NUMBER DENSITY DIFFERENT TO WHAT IS SPECIFIED DEPENDING ON HOW CLOSE CUBE ROOT OF N_MOLECULES IS TO AN int.

Note

CURRENT IMPLEMENTATION SHOULD NOT BE USED WITH NON-CUBIC UNIVERSES AS THE DENSITY MAY OR MAY NOT BE ISOTROPIC DEPENDING ON THE DIMENSIONS AND NUMBER OF UNITS.

Parameters
  • structures (Structure or int) – The Structure with which to fill the Universe

  • force_field (str) – Applies a ForceField to the Universe. The available ForceField are: TIP3PFB, SPC, OPLSAA, TIP3P, SPCE

  • num_density (float) – Non-negative float specifying the number density of the Structure, in units of Structure / Ang ^ -3

  • num_struc_units (int) – Non-negative int specifying the number of passed Structure objects that the universe should be filled with, regardless of Universe.dimensions.

Raises
  • ValueError – If both num_density and num_struc_units are passed

  • ValueError – If neither num_density or num_struc_units are passed

property force_fields

Get or set the ForceField acting on the Universe

The available force fields are: TIP3PFB, SPC, OPLSAA, TIP3P, SPCE

Returns

ForceField that applies to the Universe

Return type

list

property interactions

Get the interactions in the Universe

Returns

The interactions in the Universe

Return type

list

property molecule_list

Get a list of the Molecule objects in the Universe

Returns

The Molecule objects in the Universe

Return type

list

property n_atoms: int

Get the number of atoms in the Universe

Returns

The number of atoms in the Universe

Return type

int

property n_bonded: int

Get the number of bonded interactions in the Universe

Returns

The number of bonded interactions in the Universe

Return type

int

property n_interactions: int

Get the number of interactions in the Universe

Returns

The number of interactions in the Universe

Return type

int

property n_molecules: int

Get the number of molecules in the Universe

Returns

The number of molecules in the Universe

Return type

int

property n_nonbonded: int

Get the number of nonbonded interactions in the Universe

Returns

The number of nonbonded interactions in the Universe

Return type

int

property nbis_by_atom_type_pairs

Generates a dict of all nonbonded interactions possessed by all combinations of atom_type pairs in the Universe.

Returns

A dict of {pair: interactions} pairs, where:
  • pair is a tuple for a pair of atom_types in the Universe

  • interactions is a list of nonbonded interactions that exist for this pair of atom_types

Any Dispersions in interactions are ones that exist explicity for this pair, whereas any Coulombics in interactions are ones that exist for either of the atom_types in pair.

Return type

dict

property nonbonded_interactions

Get the nonbonded interactions in the Universe

Returns

The nonbonded interactions in the Universe

Return type

list

property parameters

Get the parameters of the interactions that exist within the Universe

Returns

The Parameters objects defined within Universe

Return type

Parameters

solvate(density, tolerance=1.0, solvent='SPCE', **settings)[source]

Fills the Universe with solvent molecules according to pre-defined coordinates.

Parameters
  • density (float) – The desired density of the Solvent that solvates the Universe, in units of amu Ang ^ -3

  • tolerance (float, optional) – The +/- percentage tolerance of the density to be achieved. The default is 1 %. Tolerances of less than 1 % are at risk of not converging.

  • solvent (str, optional) – A str specifying an inbuilt Solvent from the following: SPC, TIP3PFB, SPCE, TIP3P. The default is ‘SPCE’.

  • **settings

    constraint_algorithm (ConstraintAlgorithm)

    A ConstraintAlgorithm which is applied to the Universe. If an inbuilt Solvent is selected (e.g. ‘SPCE’) and constraint_algorithm is not passed, the ConstraintAlgorithm will default to Shake(1e-4, 100).

Raises

ValueError – If the Universe has already been solvated with a different density.

property structure_list

Get a list of all Structure objects that exist in the Universe. This includes all Structure that are a subunit of another structure belonging to the Universe.

Returns

The Structure objects in the Universe

Return type

list

property top_level_structure_list: List[MDMC.MD.structures.Structure]

Get a list of the top level Structure objects that exist in the Universe. This does not include any Structure that are a subunit of another structure belonging to the Universe.

Returns

The top level Structure objects in the Universe

Return type

list