interaction_functions

A module for storing atomic interaction functions

Contains class InteractionFunction from which all interaction function classes must derive. All functions describing atomic interactions must be added to this module in order to be called by a universe. If needed, the interaction function classes can be extended to contain actual function definitions.

Contains class Parameter, which defines the name and value of each parameter which belongs to an InteractionFunction, and whether the parameter is fixed, has constraints or is tied.

Contains filters for filtering list of parameters based on a predicate.

class MDMC.MD.interaction_functions.Buckingham(A: float, B: float, C: float)[source]

The Buckingham potential (in units of kJ mol^-1) for the interaction of 2 atoms at distance r (in Ang) has the form:

\[{\Phi _{12}(r)=A\exp \left(-Br\right)-{\frac {C}{r^{6}}}}\]

The first and second terms represent a repulsion and attraction respectively, and so all parameters \(A\), \(B\) and \(C\) should be positive in order to be physically valid.

Parameters:

A (float) – The Buckingham parameter A in units of kJ mol^-1
B (float) – The Buckingham parameter B in units of Ang^-1
C (float) – The Buckingham parameter C in units of Ang^6 kJ mol^-1

Examples

The following creates a Dispersion interaction with a Buckingham functional form:

buck = Buckingham(3.65e-18, 6.71, 6.94e-22)
O_disp = Dispersion(universe, (O.atom_type, O.atom_type), function=buck)

class MDMC.MD.interaction_functions.Coulomb(charge: float)[source]

Coulomb interaction for charged particles:

\[E = \frac{Cq_{i}q_{j}}{r}\]

Parameters:: charge (float) – The charge in units of e

Examples

The following creates a Coulombic interaction with a Coulomb functional form:

O = Atom('O')
coul = Coulomb(-0.8476)
O_coulombic = Coulombic(atoms=O, cutoff=10., function=coul)

As Coulomb is the default functional form of Coulombic interactions when an Atom is created, this is equivalent to setting the charge on an Atom:

O = Atom('O', charge=-0.8476)

class MDMC.MD.interaction_functions.HarmonicPotential(equilibrium_state: float, potential_strength: float, **settings: dict)[source]

Harmonic potential for bond stretching, and angular and improper dihedral vibration, with the form:

\[E = K(r-r_0)^2\]

As HarmonicPotential can be used with several different Interaction types, the Interaction type must be specified, so that the correct units can be assigned to the equilibrium_state and potential_strength parameters.

Parameters:

equilibrium_state (float) – The equilibrium state of the object in either Ang or degrees, depending on the interaction_type passed.
potential_strength (float) – The potential strength in units of kJ mol^-1 Ang^-2 (linear) or kJ mol^-1 rad^-2 (angular/improper), depending on the interaction_type passed.
**settings –

interaction_typestr
A str specifying either 'bond', 'angle' or 'improper'. This assigns the correct units to equilibrium_state and potential_strength. This keyword must be passed.

Raises:

ValueError – The interaction_type must be 'bond', 'angle', or 'improper'
TypeError – An interaction_type of 'bond', 'angle', or 'improper' must be passed

Examples

The following creates a HarmonicPotential for a Bond interaction:

hp = HarmonicPotential(1., 4637., interaction_type='bond')

The following creates a HarmonicPotential for a BondAngle interaction:

hp = HarmonicPotential(109.47, 383., interaction_type='angle')

The following creates a HarmonicPotential for a DihedralAngle interaction with improper==True (i.e. an improper dihedral):

hp = HarmonicPotential(180., 20.92, interaction_type='improper')

class MDMC.MD.interaction_functions.InteractionFunction(val_dict: dict)[source]

Base class for interaction functions, which can be user supplied

Parameters:: val_dict (dict) – name:value pairs. Currently this must be ordered alphabetically. value must either be an object with a value and a unit (e.g. a UnitFloat object), or a (float, str) tuple, where float is the value and str is the unit.

property name: str

Get the name of the class of the InteractionFunction

Returns:: The class name
Return type:: str

property parameters: Parameters

Get or set the interaction function’s parameters

Returns:: A Parameters object containing each Parameter
Return type:: Parameters

property parameters_values: ndarray

Get the values for all Parameters objects

Returns:: A NumPy array of values for all Parameter
Return type:: numpy.ndarray

set_parameters_interactions(interaction: Interaction) → None[source]

Sets the parent Interaction for all Parameters objects

Parameters:: interaction (Interaction) – An Interaction to set as the parent of all the Parameters

class MDMC.MD.interaction_functions.LennardJones(epsilon: float, sigma: float, **settings: dict)[source]

Dispersive Lennard-Jones interaction with the form:

\[E = 4{\epsilon}[(\frac{\sigma}{r})^{12} - (\frac{\sigma}{r})^6)] \qquad r < r_c\]

Parameters:

epsilon (float) – The LJ epsilon value in units of kJ mol^-1
sigma (float) – The LJ sigma value in units of Ang
**settings –

cutofffloat
The distance in Ang at which the potential is cutoff

long_range_solverstr
The long range solver, either 'PPPM', 'PME', or 'E' for Particle-Particle Particle-Mesh, Particle Mesh Ewald, or Ewald solvers

Examples

The following creates a Dispersion interaction with a LennardJones functional form:

lj = LennardJones(0.6502, 3.166)
O_disp = Disperion(universe, (O.atom_type, O.atom_type), function=lj)

class MDMC.MD.interaction_functions.Periodic(K1: float, n1: float, d1: float, *parameters: float)[source]

Periodic potential for proper and improper dihedral interactions, with the form:

\[E = \sum_{i=1,m}K_i[1.0+\cos(n_i\phi-d_i)]\]

where phi is angle between the ijk and jkl planes (where i, j, k, and l are the four atoms of the dihedral).

Parameters:

K1 (float) – The K parameter (energy) of the first order term, in units of kJ mol^-1
n1 (int) – The n parameter of the first order term, which is unitless. This must be a non-negative int.
d1 (float) – The d parameter (angle) of the first order term, in units of deg
*parameters – K, n, and d parameters for higher order terms. These must be ordered K2, n2, d2, K3, n3, d3, K4, n4, d4 etc. The types and units of these parameters are the same as the corresponding first order parameters listed above.

Examples

The following creates a first order Periodic for a DihedralAngle interaction with improper==True (i.e. an improper dihedral):

periodic = Periodic(87.864, 2, 180.)
improper = DihedralAngle(atoms=[C, H1, H2, O], improper=True,
                         function=periodic)

The following creates a third order Periodic for a DihedralAngle interaction with improper==False (i.e. a proper dihedral), with K1=3.53548, K2=-4.02501 and K3=2.98319:

periodic = Periodic(3.53548, 1, 0., -4.02501, 2, 180., 2.98319, 3, 0.)
proper = DihedralAngle(atoms=[N, C1, C2, C3], improper=False,
                       function=periodic)

MDMC.MD.interaction_functions.inter_func_decorator(*parameter_units) → Callable[source]

Decorates a method to add units to all positional and any relevant keyword arguments

Designed for adding units to parameters of __init__ method for subclasses of InteractionFunction.

Parameters:: *parameter_units (tuple) – One or more tuple where the first element is a str giving the keyword name of an expected parameter. The second element is a str or Unit, where each str (or Unit) is a unit which is applied to the corresponding value passed to the decorated method. If one of the values is unitless, pass None at the corresponding index in parameter_units.

Examples

The following adds units of 'Ang' to parameter alpha, units of 's' to the parameter beta, and units of 'atm' to the parameter gamma:

@inter_func_decorator(('alpha', 'Ang'), ('beta', 's'), ('gamma', 'Pa'))
def __init__(self, alpha, beta, gamma):
    ...

If one of the parameters is unitless, this can be set with None (in which case the returned type will be the same as the original value i.e. a UnitFloat or UnitNDArray will not be created). So to set epsilon as unitless:

@inter_func_decorator(('delta', 'arb'), ('epsilon', None), ('gamma', 'deg'))
def __init__(self, delta, epsilon, gamma):
    ...