propagators

class atomsmm.propagators.Propagator

Bases: object

This is the base class for propagators, which are building blocks for constructing CustomIntegrator objects in OpenMM. Shortly, a propagator translates the effect of an exponential operator like \(e^{\delta t \, iL}\). This effect can be either the exact solution of a system of deterministic or stochastic differential equations or an approximate solution obtained by a splitting scheme such as, for instance, \(e^{\delta t \, (iL_A+iL_B)} \approx e^{\delta t \, iL_A} e^{\delta t \, iL_B}\).

integrator(stepSize)

This method generates an Integrator object which implements the effect of the propagator.

Parameters

stepSize (unit.Quantity) – The step size for integrating the equations of motion.

Returns

Integrator

class atomsmm.propagators.ChainedPropagator(propagators)

Bases: atomsmm.propagators.Propagator

This class combines a list of propagators \(A1 = e^{\delta t \, iL_{A1}}\) and \(B = e^{\delta t \, iL_B}\) by making \(C = A B\), that is,

\[e^{\delta t \, iL_C} = e^{\delta t \, iL_A} e^{\delta t \, iL_B}.\]

Warning

Propagators are applied to the system in the right-to-left direction. In general, the effect of the chained propagator is non-commutative. Thus, ChainedPropagator(A, B) results in a time-asymmetric propagator unless A and B commute.

Note

It is possible to create nested chained propagators. If, for instance, \(B\) is a chained propagator given by \(B = D E\), then an object instantiated by ChainedPropagator(A, B) will be a propagator corresponding to \(C = A D E\).

Parameters

• A (Propagator) – The secondly applied propagator in the chain.

• B (Propagator) – The firstly applied propagator in the chain.

class atomsmm.propagators.SplitPropagator(A, n)

Bases: atomsmm.propagators.Propagator

This class splits a propagators \(A = e^{\delta t \, iL_A}\) into a sequence of n propagators \(a = e^{\frac{\delta t}{n} \, iL_A}\), that is,

\[e^{\delta t \, iL_A} = \left( e^{\frac{\delta t}{n} \, iL_A} \right)^n.\]

Parameters

• A (Propagator) – The propagator to be split.

• n (int) – The number of parts.

class atomsmm.propagators.TrotterSuzukiPropagator(A, B)

Bases: atomsmm.propagators.Propagator

This class combines two propagators \(A = e^{\delta t \, iL_A}\) and \(B = e^{\delta t \, iL_B}\) by using the time-symmetric Trotter-Suzuki splitting scheme [5] \(C = B^{1/2} A B^{1/2}\), that is,

\[e^{\delta t \, iL_C} = e^{{1/2} \delta t \, iL_B} e^{\delta t \, iL_A} e^{{1/2} \delta t \, iL_B}.\]

Note

It is possible to create nested Trotter-Suzuki propagators. If, for instance, \(B\) is a Trotter-Suzuki propagator given by \(B = E^{1/2} D E^{1/2}\), then an object instantiated by TrotterSuzukiPropagator(A, B) will be a propagator corresponding to \(C = E^{1/4} D^{1/2} E^{1/4} A E^{1/4} D^{1/2} E^{1/4}\).

Parameters

• A (Propagator) – The middle propagator of a Trotter-Suzuki splitting scheme.

• B (Propagator) – The side propagator of a Trotter-Suzuki splitting scheme.

class atomsmm.propagators.SuzukiYoshidaPropagator(A, nsy=3)

Bases: atomsmm.propagators.Propagator

This class splits a propagator \(A = e^{\delta t \, iL_A}\) by using a high-order, time-symmetric Suzuki-Yoshida scheme [6][7][8] given by

\[e^{\delta t \, iL_A} = \prod_{i=1}^{n_{sy}} e^{w_i \delta t \, iL_A},\]

where \(n_{sy}\) is the number of employed Suzuki-Yoshida weights.

Parameters

• A (Propagator) – The propagator to be splitted by the high-order Suzuki-Yoshida scheme.

• nsy (int, optional, default=3) – The number of Suzuki-Yoshida weights to be employed. This must be 3, 7, or 15.

class atomsmm.propagators.TranslationPropagator(constrained=True)

Bases: atomsmm.propagators.Propagator

This class implements a coordinate translation propagator \(e^{\delta t \mathbf{p}^T \mathbf{M}^{-1} \nabla_\mathbf{r}}\).

Parameters

constrained (bool, optional, default=True) – If True, distance constraints are taken into account.

class atomsmm.propagators.VelocityBoostPropagator(constrained=True)

Bases: atomsmm.propagators.Propagator

This class implements a velocity boost propagator \(e^{\frac{1}{2} \delta t \mathbf{F}^T \nabla_\mathbf{p}}\).

Parameters

constrained (bool, optional, default=True) – If True, distance constraints are taken into account.

class atomsmm.propagators.MassiveIsokineticPropagator(temperature, timeScale, L, forceDependent)

Bases: atomsmm.propagators.Propagator

This class implements an unconstrained, massive isokinetic propagator. It provides, for every degree of freedom in the system, a solution for one of ODE systems below.

1. Force-dependent equations:

\[\begin{split}& \frac{dv}{dt} = \frac{F}{m} - \lambda_{F} v \\ & \frac{dv_1}{dt} = - \lambda_F v_1 \\ & \lambda_F = \frac{F v}{m v^2 + \frac{1}{2} Q_1 v_1^2}\end{split}\]

where \(F\) is a constant force. The exact solution for these equations is:

\[\begin{split}& v = H \hat{v} \\ & v_1 = H v_{1,0} \\ & \text{where:} \\ & \hat{v} = v_0 \cosh\left(\frac{F t}{\sqrt{m kT}}\right) + \sqrt{\frac{kT}{m}} \sinh\left(\frac{F t}{\sqrt{m kT}}\right) \\ & H = \sqrt{\frac{kT}{m \hat{v}^2 + \frac{1}{2} Q_1 v_{1,0}^2}} \\\end{split}\]

2. Force-indepependent equations:

\[\begin{split}& \frac{dv}{dt} = - \lambda_{N} v \\ & \frac{dv_1}{dt} = - (\lambda_N + v_2) v_1 \\ & \lambda_N = \frac{-\frac{1}{2} Q_1 v_2 v_1^2}{m v^2 + \frac{1}{2} Q_1 v_1^2}\end{split}\]

where \(v_2\) is a constant thermostat ‘velocity’. In this case, the exact solution is:

\[\begin{split}& v = H v_0 \\ & v_1 = H \hat{v}_1 \\ & \text{where:} \\ & \hat{v}_1 = v_{1,0} \exp(-v_2 t) \\ & H = \sqrt{\frac{kT}{m v_0^2 + \frac{1}{2} Q_1 \hat{v}_1^2}} \\\end{split}\]

Both ODE systems above satisfy the massive isokinetic constraint \(m v^2 + \frac{1}{2} Q_1 v_1^2 = kT\).

Parameters

• temperature (unit.Quantity) – The temperature to which the configurational sampling should correspond.

• timeScale (unit.Quantity) – A time scale \(\tau\) from which to compute the inertial parameter \(Q_1 = kT\tau^2\).

• forceDependent (bool) – If True, the propagator will solve System 1. If False, then System 2 will be solved.

class atomsmm.propagators.NewMethodPropagator(temperature, timeScale, L, forceDependent)

Bases: atomsmm.propagators.Propagator

Parameters

• temperature (unit.Quantity) – The temperature to which the configurational sampling should correspond.

• timeScale (unit.Quantity) – A time scale \(\tau\) from which to compute the inertial parameter \(Q_1 = kT\tau^2\).

• L (int) – The parameter L.

• forceDependent (bool) – If True, the propagator will solve System 1. If False, then System 2 will be solved.

class atomsmm.propagators.RestrainedLangevinPropagator(temperature, frictionConstant, L, kind)

Bases: atomsmm.propagators.Propagator

Parameters

• temperature (unit.Quantity) – The temperature to which the configurational sampling should correspond.

• timeScale (unit.Quantity) – A time scale \(\tau\) from which to compute the inertial parameter \(Q_1 = kT\tau^2\).

• L (int) – The parameter L.

• forceDependent (bool) – If True, the propagator will solve System 1. If False, then System 2 will be solved.

class atomsmm.propagators.LimitedSpeedLangevinPropagator(temperature, frictionConstant, L, kind)

Bases: atomsmm.propagators.Propagator

Parameters

• temperature (unit.Quantity) – The temperature to which the configurational sampling should correspond.

• timeScale (unit.Quantity) – A time scale \(\tau\) from which to compute the inertial parameter \(Q_1 = kT\tau^2\).

• L (int) – The parameter L.

• kind (str) – Options are move, boost, and bath.

class atomsmm.propagators.LimitedSpeedNHLPropagator(temperature, timeScale, frictionConstant, L, kind)

Bases: atomsmm.propagators.Propagator

Parameters

• temperature (unit.Quantity) – The temperature to which the configurational sampling should correspond.

• timeScale (unit.Quantity) – A time scale \(\tau\) from which to compute the inertial parameter \(Q_1 = kT\tau^2\).

• L (int) – The parameter L.

• kind (str) – Options are move, boost, and bath.

class atomsmm.propagators.LimitedSpeedStochasticPropagator(temperature, timeScale, frictionConstant, L, kind)

Bases: atomsmm.propagators.Propagator

Parameters

• temperature (unit.Quantity) – The temperature to which the configurational sampling should correspond.

• timeScale (unit.Quantity) – A time scale \(\tau\) from which to compute the inertial parameter \(Q_1 = kT\tau^2\).

• L (int) – The parameter L.

• kind (str) – Options are move, boost, and bath.

class atomsmm.propagators.LimitedSpeedStochasticVelocityPropagator(temperature, timeScale, frictionConstant, L, kind)

Bases: atomsmm.propagators.Propagator

Parameters

• temperature (unit.Quantity) – The temperature to which the configurational sampling should correspond.

• timeScale (unit.Quantity) – A time scale \(\tau\) from which to compute the inertial parameter \(Q_1 = kT\tau^2\).

• L (int) – The parameter L.

• kind (str) – Options are move, boost, and bath.

class atomsmm.propagators.OrnsteinUhlenbeckPropagator(temperature, frictionConstant, velocity='v', mass='m', force=None, overall=False, **globals)

Bases: atomsmm.propagators.Propagator

This class implements an unconstrained, Ornstein-Uhlenbeck (OU) propagator, which provides a solution for the following stochastic differential equation for every degree of freedom in the system:

\[dV = \frac{F}{M} dt - \gamma V dt + \sqrt{\frac{2 \gamma kT}{M}} dW.\]

In this equation, V, M, and F are generic forms of velocity, mass, and force. By default, the propagator acts on the atomic velocities (v) and masses (m), while the forces are considered as null.

Parameters

• temperature (unit.Quantity) – The temperature to which the configurational sampling should correspond.

• frictionConstant (unit.Quantity, optional, default=None) – The friction constant \(\gamma\) present in the stochastic equation.

• velocity (str, optional, default=’v’) – The name of a per-dof variable considered as the velocity of each degree of freedom.

• mass (str, optional, default=’m’) – The name of a per-dof or global variable considered as the mass associated to each degree of freedom.

• force (str, optional, default=None) – The name of a per-dof variable considered as the force acting on each degree of freedom. If it is None, then this force is considered as null.

class atomsmm.propagators.GenericBoostPropagator(velocity='v', mass='m', force='f', perDof=True, **globals)

Bases: atomsmm.propagators.Propagator

This class implements a linear boost by providing a solution for the following ODE for every degree of freedom in the system:

\[\frac{dV}{dt} = \frac{F}{M}.\]

Parameters

• velocity (str, optional, default=’v’) – The name of a per-dof variable considered as the velocity of each degree of freedom.

• mass (str, optional, default=’m’) – The name of a per-dof or global variable considered as the mass associated to each degree of freedom.

• force (str, optional, default=’f’) – The name of a per-dof variable considered as the force acting on each degree of freedom.

Keyword Arguments

perDof (bool, default=True) – This must be True if the propagated velocity is a per-dof variable or False if it is a global variable.

class atomsmm.propagators.GenericScalingPropagator(velocity, damping, perDof=True, **globals)

Bases: atomsmm.propagators.Propagator

This class implements scaling by providing a solution for the following ODE for every degree of freedom in the system:

\[\frac{dV}{dt} = -\lambda_\mathrm{damping}*V.\]

Parameters

• velocity (str) – The name of a per-dof variable considered as the velocity of each degree of freedom.

• damping (str) – The name of a per-dof or global variable considered as the damping parameter associated to each degree of freedom.

class atomsmm.propagators.RespaPropagator(loops, move=None, boost=None, core=None, shell=None, **kwargs)

Bases: atomsmm.propagators.Propagator

This class implements a multiple timescale (MTS) rRESPA propagator [9] with \(N\) force groups, where group \(0\) goes in the innermost loop (shortest time step) and group \(N-1\) goes in the outermost loop (largest time step). The complete Liouville-like operator corresponding to the equations of motion is split as

\[iL = iL_\mathrm{move} + \sum_{k=0}^{N-1} \left( iL_{\mathrm{boost}, k} \right) + iL_\mathrm{core} + \sum_{k=0}^{N-1} \left( iL_{\mathrm{shell}, k} \right)\]

In this scheme, \(iL_\mathrm{move}\) is the only component that entails changes in the atomic coordinates, while \(iL_{\mathrm{boost}, k}\) is the only component that depends on the forces of group \(k\). Therefore, operator \(iL_\mathrm{core}\) and each operator \(iL_{\mathrm{shell}, k}\) are reserved to changes in atomic velocities due to the action of thermostats, as well as to changes in the thermostat variables themselves.

The rRESPA split can be represented recursively as

\[e^{\Delta t iL} = e^{\Delta t iL_{N-1}}\]

where

\[\begin{split}e^{\delta t iL_k} = \begin{cases} \left(e^{\frac{\delta t}{2 n_k} iL_{\mathrm{shell}, k}} e^{\frac{\delta t}{2 n_k} iL_{\mathrm{boost}, k}} e^{\frac{\delta t}{n_k} iL_{k-1}} e^{\frac{\delta t}{2 n_k} iL_{\mathrm{boost}, k}} e^{\frac{\delta t}{2 n_k} iL_{\mathrm{shell}, k}} \right)^{n_k} & k \geq 0 \\ e^{\frac{\delta t}{2} iL_\mathrm{move}} e^{\delta t iL_\mathrm{core}} e^{\frac{\delta t}{2} iL_\mathrm{move}} & k = -1 \end{cases}\end{split}\]

Parameters

• loops (list(int)) – A list of N integers, where loops[k] determines how many iterations of force group k are internally executed for every iteration of force group k+1.

• move (Propagator, optional, default=None) – A propagator used to update the coordinate of every atom based on its current velocity. If it is None, then an unconstrained, linear translation is applied.

• boost (Propagator, optional, default=None) – A propagator used to update the velocity of every atom based on the resultant force acting on it. If it is None, then an unconstrained, linear boosting is applied.

• core (Propagator, optional, default=None) – An internal propagator to be used for controlling the configurational probability distribution sampled by the rRESPA scheme. This propagator will be integrated in the innermost loop (shortest time step). If it is None (default), then no core propagator will be applied.

• shell (dict(int : Propagator), optional, default=None) – A dictionary of propagators to be used for controlling the configurational probability distribution sampled by the rRESPA scheme. Propagator shell[k] will be excecuted in both extremities of the loop involving forces of group k. If it is None (default), then no shell propagators will be applied. Dictionary keys must be integers from 0 to N-1 and omitted keys mean that no shell propagators will be considered at those particular loop levels.

• has_memory (bool, optional, default=True) – If True, integration in the fastest time scale remembers the lattest forces computed in all other time scales. To compensate, each remembered force is substracted during the integration in its respective time scale. Warning: this integration scheme is not time-reversal symmetric.

class atomsmm.propagators.MultipleTimeScalePropagator(loops, move=None, boost=None, bath=None, **kwargs)

Bases: atomsmm.propagators.RespaPropagator

This class implements a Multiple Time-Scale (MTS) propagator using the RESPA method.

Parameters

• loops (list(int)) – A list of N integers. Assuming that force group 0 is composed of the fastest forces, while group N-1 is composed of the slowest ones, loops[k] determines how many steps involving forces of group k are internally executed for every step involving those of group k+1.

• move (Propagator, optional, default = None) – A move propagator.

• boost (Propagator, optional, default = None) – A boost propagator.

• bath (Propagator, optional, default = None) – A bath propagator.

Keyword Arguments

• scheme (str, optional, default = middle) – The splitting scheme used to solve the equations of motion. Available options are middle, xi-respa, xo-respa, side, and blitz. If it is middle (default), then the bath propagator will be inserted between half-step coordinate moves during the fastest-force loops. If it is xi-respa, xo-respa, or side, then the bath propagator will be integrated in both extremities of each loop concerning one of the N time scales, with xi-respa referring to the time scale of fastest forces (force group 0), xo-respa referring to the time scale of the slowest forces (force group N-1), and side requiring the user to select the time scale in which to locate the bath propagator via keyword argument location (see below). If it is blitz, then the force-related propagators will be fully integrated at the outset of each loop in all time scales and the bath propagator will be integrated between half-step coordinate moves during the fastest-force loops.

• location (int, optional, default = None) – The index of the force group (from 0 to N-1) that defines the time scale in which the bath propagator will be located. This is only meaningful if keyword scheme is set to side (see above).

• nsy (int, optional, default = 1) – The number of Suzuki-Yoshida terms to factorize the bath propagator. Valid options are 1, 3, 7, and 15.

• nres (int, optional, default = 1) – The number of RESPA-like subdivisions to factorize the bath propagator.

Warning

The xo-respa and xi-respa schemes implemented here are slightly different from the ones described in the paper by Leimkuhler, Margul, and Tuckerman [4].

class atomsmm.propagators.SIN_R_Propagator(loops, temperature, timeScale, frictionConstant, **kwargs)

Bases: atomsmm.propagators.MultipleTimeScalePropagator

This class is an implementation of the Stochastic-Iso-NH-RESPA or SIN(R) method of Leimkuhler, Margul, and Tuckerman [4]. The method consists in solving the following equations for each degree of freedom (DOF) in the system:

\[\begin{split}& \frac{dx}{dt} = v \\ & \frac{dv}{dt} = \frac{f}{m} - \lambda v \\ & \frac{dv_1}{dt} = - \lambda v_1 - v_2 v_1 \\ & dv_2 = \frac{Q_1 v_1^2 - kT}{Q_2}dt - \gamma v_2 dt + \sqrt{\frac{2 \gamma kT}{Q_2}} dW\end{split}\]

where:

\[\lambda = \frac{f v - \frac{1}{2} Q_1 v_2 v_1^2}{m v^2 + \frac{1}{2} Q_1 v_1^2}.\]

A consequence of these equations is that

\[m v^2 + \frac{1}{2} Q_1 v_1^2 = kT.\]

The equations are integrated by a reversible, multiple timescale numerical scheme.

Parameters

• loops (list(int)) – See description in MultipleTimeScaleIntegrator.

• temperature (unit.Quantity) – The temperature to which the configurational sampling should correspond.

• timeScale (unit.Quantity) – A time scale \(\tau\) from which the inertial parameters are computed as \(Q_1 = Q_2 = kT\tau^2\).

• frictionConstant (unit.Quantity) – The friction constant \(\gamma\) present in the stochastic equation of motion for per-DOF thermostat variable \(v_2\).

• **kwargs (keyword arguments) – The same keyword arguments of class MultipleTimeScalePropagator apply here.

class atomsmm.propagators.VelocityVerletPropagator

Bases: atomsmm.propagators.Propagator

This class implements a Velocity Verlet propagator with constraints.

\[e^{\delta t \, iL_\mathrm{NVE}} = e^{\frac{1}{2} \delta t \mathbf{F}^T \nabla_\mathbf{p}} e^{\delta t \mathbf{p}^T \mathbf{M}^{-1} \nabla_\mathbf{r}} e^{\frac{1}{2} \delta t \mathbf{F}^T \nabla_\mathbf{p}}\]

Note

In the original OpenMM VerletIntegrator class, the implemented propagator is a leap-frog version of the Verlet method.

class atomsmm.propagators.UnconstrainedVelocityVerletPropagator

Bases: atomsmm.propagators.Propagator

This class implements a Velocity Verlet propagator with constraints.

\[e^{\delta t \, iL_\mathrm{NVE}} = e^{\frac{1}{2} \delta t \mathbf{F}^T \nabla_\mathbf{p}} e^{\delta t \mathbf{p}^T \mathbf{M}^{-1} \nabla_\mathbf{r}} e^{\frac{1}{2} \delta t \mathbf{F}^T \nabla_\mathbf{p}}\]

Note

In the original OpenMM VerletIntegrator class, the implemented propagator is a leap-frog version of the Verlet method.

class atomsmm.propagators.VelocityRescalingPropagator(temperature, degreesOfFreedom, timeScale)

Bases: atomsmm.propagators.Propagator

This class implements the Stochastic Velocity Rescaling propagator of Bussi, Donadio, and Parrinello [10], which is a global version of the Langevin thermostat [11].

This propagator provides a solution for the following SDE [11]:

\[d\mathbf{p} = \frac{1}{2\tau}\left[\frac{(N_f-1)k_BT}{2K}-1\right]\mathbf{p}dt + \sqrt{\frac{k_BT}{2K\tau}}\mathbf{p}dW\]

The gamma-distributed random numbers required for the solution are generated by using the algorithm of Marsaglia and Tsang [12].

Warning

An integrator that uses this propagator will fail if no initial velocities are provided to the system particles.

Parameters

• temperature (unit.Quantity) – The temperature of the heat bath.

• degreesOfFreedom (int) – The number of degrees of freedom in the system, which can be retrieved via function countDegreesOfFreedom().

• timeScale (unit.Quantity) – The relaxation time of the thermostat.

class atomsmm.propagators.NoseHooverPropagator(temperature, degreesOfFreedom, timeScale, nloops=1)

Bases: atomsmm.propagators.Propagator

This class implements a Nose-Hoover propagator.

As usual, the inertial parameter \(Q\) is defined as \(Q = N_f k_B T \tau^2\), with \(\tau\) being a relaxation time [9].

Parameters

• temperature (unit.Quantity) – The temperature of the heat bath.

• degreesOfFreedom (int) – The number of degrees of freedom in the system, which can be retrieved via function countDegreesOfFreedom().

• timeScale (unit.Quantity (time)) – The relaxation time of the Nose-Hoover thermostat.

• nloops (int, optional, default=1) – Number of RESPA-like subdivisions.

class atomsmm.propagators.MassiveNoseHooverPropagator(temperature, timeScale, nloops=1)

Bases: atomsmm.propagators.Propagator

This class implements a massive Nose-Hoover propagator.

As usual, the inertial parameter \(Q\) is defined as \(Q = N_f k_B T \tau^2\), with \(\tau\) being a relaxation time [9].

Parameters

• temperature (unit.Quantity) – The temperature of the heat bath.

• timeScale (unit.Quantity (time)) – The relaxation time of the Nose-Hoover thermostat.

• nloops (int, optional, default=1) – Number of RESPA-like subdivisions.

class atomsmm.propagators.MassiveGeneralizedGaussianMomentPropagator(temperature, timeScale, nloops=1)

Bases: atomsmm.propagators.Propagator

This class implements a massive Generalized Gaussian Moment propagator.

As usual, the inertial parameter \(Q\) is defined as \(Q = N_f k_B T \tau^2\), with \(\tau\) being a relaxation time [9].

Parameters

• temperature (unit.Quantity) – The temperature of the heat bath.

• timeScale (unit.Quantity (time)) – The relaxation time of the Nose-Hoover thermostat.

• nloops (int, optional, default=1) – Number of RESPA-like subdivisions.

class atomsmm.propagators.NoseHooverChainPropagator(temperature, degreesOfFreedom, timeScale, frictionConstant=None)

Bases: atomsmm.propagators.Propagator

This class implements a Nose-Hoover chain [9] with two global thermostats.

This propagator provides a solution for the following ODE system:

\[\begin{split}& \frac{d\mathbf{p}}{dt} = -\frac{p_{\eta,1}}{Q_1} \mathbf{p} \\ & \frac{dp_{\eta,1}}{dt} = \mathbf{p}^T\mathbf{M}^{-1}\mathbf{p} - N_f k_B T - \frac{p_{\eta,2}}{Q_2} p_{\eta,1} \\ & \frac{dp_{\eta,2}}{dt} = \frac{p_{\eta,1}^2}{Q_1} - k_B T\end{split}\]

As usual, the inertial parameter \(Q\) is defined as \(Q = N_f k_B T \tau^2\), with \(\tau\) being a relaxation time [9]. An approximate solution is obtained by applying the Trotter-Suzuki splitting formula:

\[e^{(\delta t/2)\mathcal{L}_{B2}} e^{(\delta t/2)\mathcal{L}_{S1}} e^{(\delta t/2)\mathcal{L}_{B1}} e^{(\delta t)\mathcal{L}_{S}} e^{(\delta t/2)\mathcal{L}_{B1}} e^{(\delta t/2)\mathcal{L}_{S1}} e^{(\delta t/2)\mathcal{L}_{B2}}\]

Each exponential operator above is the solution of a differential equation.

Equation ‘B2’ is a boost of thermostat 2, whose solution is:

\[p_{\eta,2}(t) = p_{\eta,2}^0 +\left(\frac{p_{\eta,1}^2}{Q_1} - k_B T\right) t\]

Equation ‘S1’ is a scaling of thermostat 1, whose solution is:

\[p_{\eta,1}(t) = p_{\eta,1}^0 e^{-\frac{p_{\eta,2}}{Q_2} t}\]

Equation ‘B1’ is a boost of thermostat 1, whose solution is:

\[p_{\eta,1}(t) = p_{\eta,1}^0 + \left(\mathbf{p}^T\mathbf{M}^{-1}\mathbf{p} - N_f k_B T\right) t\]

Equation ‘S’ is a scaling of particle momenta, whose solution is:

\[\mathbf{p}(t) = \mathbf{p}_0 e^{-\frac{p_{\eta,1}}{Q_1} t}\]

Parameters

• temperature (unit.Quantity) – The temperature of the heat bath.

• degreesOfFreedom (int) – The number of degrees of freedom in the system, which can be retrieved via function countDegreesOfFreedom().

• timeScale (unit.Quantity (time)) – The relaxation time of the Nose-Hoover thermostat.

• frictionConstant (unit.Quantity (1/time)) – The friction coefficient of the Langevin thermostat.

class atomsmm.propagators.NoseHooverLangevinPropagator(temperature, degreesOfFreedom, timeScale, frictionConstant=None)

Bases: atomsmm.propagators.Propagator

This class implements a Nose-Hoover-Langevin propagator [13][14], which is similar to a Nose-Hoover chain [9] of two thermostats, but with the second one being a stochastic (Langevin-type) rather than a deterministic thermostat.

This propagator provides a solution for the following SDE system:

\[\begin{split}& d\mathbf{p} = -\frac{p_\eta}{Q} \mathbf{p} dt & \qquad\mathrm{(S)} \\ & dp_\eta = (\mathbf{p}^T\mathbf{M}^{-1}\mathbf{p} - N_f k_B T)dt - \gamma p_\eta dt + \sqrt{2\gamma Q k_B T}dW & \qquad\mathrm{(O)}\end{split}\]

As usual, the inertial parameter \(Q\) is defined as \(Q = N_f k_B T \tau^2\), with \(\tau\) being a relaxation time [9]. An approximate solution is obtained by applying the Trotter-Suzuki splitting formula:

\[e^{(\delta t/2)\mathcal{L}_B} e^{(\delta t/2)\mathcal{L}_S} e^{\delta t\mathcal{L}_O} e^{(\delta t/2)\mathcal{L}_S} e^{(\delta t/2)\mathcal{L}_B}\]

Each exponential operator above is the solution of a differential equation.

Equation ‘B’ is a boost, whose solution is:

\[p_\eta(t) = {p_\eta}_0 + (\mathbf{p}^T\mathbf{M}^{-1}\mathbf{p} - N_f k_B T) t\]

Equation ‘S’ is a scaling, whose solution is:

\[\mathbf{p}(t) = \mathbf{p}_0 e^{-\frac{p_\eta}{Q} t}\]

Equation ‘O’ is an Ornstein–Uhlenbeck process, whose solution is:

\[p_\eta(t) = {p_\eta}_0 e^{-\gamma t} + \sqrt{\frac{k_B T}{Q}(1-e^{-2\gamma t})} R_N\]

where \(R_N\) is a normally distributed random number.

Parameters

• temperature (unit.Quantity) – The temperature of the heat bath.

• degreesOfFreedom (int) – The number of degrees of freedom in the system, which can be retrieved via function countDegreesOfFreedom().

• timeScale (unit.Quantity (time)) – The relaxation time of the Nose-Hoover thermostat.

• frictionConstant (unit.Quantity (1/time)) – The friction coefficient of the Langevin thermostat.

class atomsmm.propagators.RegulatedTranslationPropagator(temperature, n, alpha_n=1)

Bases: atomsmm.propagators.Propagator

An unconstrained, regulated translation propagator which provides, for every degree of freedom in the system, a solution for the following ODE:

\[\frac{dr_i}{dt} = c_i \tanh\left(\frac{\alpha_n p_i}{m_i c_i}\right)\]

where \(c_i = \sqrt{\frac{\alpha_n n k_B T}{m_i}}\) is the speed limit for such degree of freedom and, by default, \(\alpha_n = \frac{n+1}{n}\). The exact solution for this equation is:

\[r_i(t) = r_i^0 + c_i \mathrm{tanh}\left(\frac{\alpha_n p}{m c_i}\right) t\]

where \(r_i^0\) is the initial coordinate.

Parameters

• temperature (unit.Quantity) – The temperature to which the configurational sampling should correspond.

• n (int or float) – The regulating parameter.

Keyword Arguments

alpha_n (int or float, default=1) – Another regulating parameter.

class atomsmm.propagators.RegulatedBoostPropagator

Bases: atomsmm.propagators.Propagator

An unconstrained, regulated boost propagator which provides, for every degree of freedom in the system, a solution for the following ODE:

\[\frac{dp_i}{dt} = F_i\]

where \(F_i\) is a constant force. The exact solution for this equation is:

\[p_i(t) = p_i^0 + F_i t\]

where \(p_i^0\) is the initial momentum.

class atomsmm.propagators.RegulatedMassiveNoseHooverLangevinPropagator(temperature, n, timeScale, frictionConstant, alpha_n=1, split=False, adiabatic=False)

Bases: atomsmm.propagators.Propagator

This class implements a regulated version of the massive Nose-Hoover-Langevin propagator [13][14]. It provides, for every degree of freedom in the system, a solution for the following SDE system:

\[\begin{split}& dp_i = -v_{\eta_i} p_i dt \\ & dv_{\eta_i} = \frac{p_i v_i - k_B T}{Q} dt - \gamma v_{\eta_i} dt + \sqrt{\frac{2\gamma k_B T}{Q}}dW_i,\end{split}\]

where:

\[v_i = c_i \tanh\left(\frac{\alpha_n p_i}{m_i c_i}\right).\]

Here, \(c_i = \sqrt{\frac{\alpha_n n k_B T}{m_i}}\) is the speed limit for such degree of freedom and, by default, \(\alpha_n = \frac{n+1}{n}\). As usual, the inertial parameter \(Q\) is defined as \(Q = k_B T \tau^2\), with \(\tau\) being a relaxation time [9]. An approximate solution is obtained by applying the Trotter-Suzuki splitting formula:

\[e^{\delta t\mathcal{L}} = e^{(\delta t/2)\mathcal{L}_B} e^{(\delta t/2)\mathcal{L}_S} e^{\delta t\mathcal{L}_O} e^{(\delta t/2)\mathcal{L}_S} e^{(\delta t/2)\mathcal{L}_B}\]

Each exponential operator above is the solution of a differential equation.

Equation ‘B’ is a boost, whose solution is:

\[v_{\eta_i}(t) = v_{\eta_i}^0 + \frac{p_i v_i - k_B T}{Q} t\]

Equation ‘S’ is a scaling, whose solution is:

\[p_i(t) = p_i^0 e^{-v_{\eta_i} t}\]

Equation ‘O’ is an Ornstein–Uhlenbeck process, whose solution is:

\[v_{\eta_i}(t) = v_{\eta_i}^0 e^{-\gamma t} + \sqrt{\frac{k_B T}{Q}(1-e^{-2\gamma t})} R_{N,i}\]

where \(R_{N,i}\) is a normally distributed random number.

Parameters

• temperature (unit.Quantity) – The temperature of the heat bath.

• n (int or float) – The regulating parameter.

• timeScale (unit.Quantity (time)) – The relaxation time of the Nose-Hoover thermostat.

• frictionConstant (unit.Quantity (1/time)) – The friction coefficient of the Langevin thermostat.

Keyword Arguments

alpha_n (int or float, default=1) – Another regulating parameter.

class atomsmm.propagators.TwiceRegulatedMassiveNoseHooverLangevinPropagator(temperature, n, timeScale, frictionConstant, alpha_n=1, split=False, adiabatic=False)

Bases: atomsmm.propagators.Propagator

This class implements a doubly-regulated version of the massive Nose-Hoover-Langevin propagator [13][14]. It provides, for every degree of freedom in the system, a solution for the following SDE system:

\[\begin{split}& dp_i = -v_{\eta_i} m_i v_i dt \\ & dv_{\eta_i} = \frac{1}{Q}\left(\frac{n+1}{n \alpha_n} m_i v_i^2 - k_B T\right) dt - \gamma v_{\eta_i} dt + \sqrt{\frac{2\gamma k_B T}{Q}} dW_i,\end{split}\]

where:

\[v_i = c_i \tanh\left(\frac{\alpha_n p_i}{m_i c_i}\right).\]

Here, \(c_i = \sqrt{\alpha_n n m_i k T}\) is speed limit for such degree of freedom and, by default, \(\alpha_n = \frac{n+1}{n}\). As usual, the inertial parameter \(Q\) is defined as \(Q = k_B T \tau^2\), with \(\tau\) being a relaxation time [9]. An approximate solution is obtained by applying the Trotter-Suzuki splitting formula:

\[e^{\delta t\mathcal{L}} = e^{(\delta t/2)\mathcal{L}_B} e^{(\delta t/2)\mathcal{L}_S} e^{\delta t\mathcal{L}_O} e^{(\delta t/2)\mathcal{L}_S} e^{(\delta t/2)\mathcal{L}_B}\]

Each exponential operator above is the solution of a differential equation.

Equation ‘B’ is a boost, whose solution is:

\[v_{\eta_i}(t) = v_{\eta_i}^0 + \frac{1}{Q}\left( \frac{n+1}{\alpha_n n} m_i v_i^2 - k_B T\right) t\]

Equation ‘S’ is a scaling, whose solution is:

\[p_i(t) = \frac{m_i c_i}{\alpha_n} \mathrm{arcsinh}\left[\sinh\left( \frac{\alpha_n p_i}{m_i c_i}\right) e^{-\alpha_n v_{\eta_i} t}\right]\]

Equation ‘O’ is an Ornstein–Uhlenbeck process, whose solution is:

\[v_{\eta_i}(t) = v_{\eta_i}^0 e^{-\gamma t} + \sqrt{\frac{k_B T}{Q}(1-e^{-2\gamma t})} R_N\]

where \(R_N\) is a normally distributed random number.

Parameters

• temperature (unit.Quantity) – The temperature of the heat bath.

• n (int or float) – The regulating parameter.

• timeScale (unit.Quantity (time)) – The relaxation time of the Nose-Hoover thermostat.

• frictionConstant (unit.Quantity (1/time)) – The friction coefficient of the Langevin thermostat.

Keyword Arguments

alpha_n (int or float, default=1) – Another regulating parameter.

class atomsmm.propagators.RegulatedAtomicNoseHooverLangevinPropagator(temperature, n, timeScale, frictionConstant, alpha_n=1, split=False)

Bases: atomsmm.propagators.Propagator

This class implements a regulated version of the massive Nose-Hoover-Langevin propagator [13][14]. It provides, for every degree of freedom in the system, a solution for the following SDE system:

\[\begin{split}& dp_i = -v_{\eta_i} p_i dt \\ & dv_{\eta_i} = \frac{p_i v_i - k_B T}{Q} dt - \gamma v_{\eta_i} dt + \sqrt{\frac{2\gamma k_B T}{Q}}dW_i,\end{split}\]

where:

\[v_i = c_i \tanh\left(\frac{\alpha_n p_i}{m_i c_i}\right).\]

Here, \(c_i = \sqrt{\frac{\alpha_n n k_B T}{m_i}}\) is the speed limit for such degree of freedom and, by default, \(\alpha_n = \frac{n+1}{n}\). As usual, the inertial parameter \(Q\) is defined as \(Q = k_B T \tau^2\), with \(\tau\) being a relaxation time [9]. An approximate solution is obtained by applying the Trotter-Suzuki splitting formula:

\[e^{\delta t\mathcal{L}} = e^{(\delta t/2)\mathcal{L}_B} e^{(\delta t/2)\mathcal{L}_S} e^{\delta t\mathcal{L}_O} e^{(\delta t/2)\mathcal{L}_S} e^{(\delta t/2)\mathcal{L}_B}\]

Each exponential operator above is the solution of a differential equation.

Equation ‘B’ is a boost, whose solution is:

\[v_{\eta_i}(t) = v_{\eta_i}^0 + \frac{p_i v_i - k_B T}{Q} t\]

Equation ‘S’ is a scaling, whose solution is:

\[p_i(t) = p_i^0 e^{-v_{\eta_i} t}\]

Equation ‘O’ is an Ornstein–Uhlenbeck process, whose solution is:

\[v_{\eta_i}(t) = v_{\eta_i}^0 e^{-\gamma t} + \sqrt{\frac{k_B T}{Q}(1-e^{-2\gamma t})} R_{N,i}\]

where \(R_{N,i}\) is a normally distributed random number.

Parameters

• temperature (unit.Quantity) – The temperature of the heat bath.

• n (int or float) – The regulating parameter.

• timeScale (unit.Quantity (time)) – The relaxation time of the Nose-Hoover thermostat.

• frictionConstant (unit.Quantity (1/time)) – The friction coefficient of the Langevin thermostat.

Keyword Arguments

alpha_n (int or float, default=1) – Another regulating parameter.

class atomsmm.propagators.TwiceRegulatedAtomicNoseHooverLangevinPropagator(temperature, n, timeScale, frictionConstant, alpha_n=1, split=False)

Bases: atomsmm.propagators.Propagator

This class implements a doubly-regulated version of the atomic Nose-Hoover-Langevin propagator [13][14]. It provides, for every atom in the system, a solution for the following SDE system:

\[\begin{split}& dv_i = -v_{\eta,\mathrm{atom}_i} v_i \left[ 1 - \left(\frac{v_i}{c_i}\right)^2\right] dt \\ & dv_{\eta,j} = \frac{1}{Q}\left( \frac{n+1}{\alpha_n n} m_j \mathbf{v}_j^T \mathbf{v}_j - 3 k_B T\right) dt - \gamma v_{\eta,j} dt + \sqrt{\frac{2\gamma k_B T}{Q}} dW_j,\end{split}\]

where \(c_i = \sqrt{\alpha_n n m_i k T}\) is speed limit for such degree of freedom and, by default, \(\alpha_n = \frac{n+1}{n}\). As usual, the inertial parameter \(Q\) is defined as \(Q = 3 k_B T \tau^2\), with \(\tau\) being a relaxation time [9]. An approximate solution is obtained by applying the Trotter-Suzuki splitting formula:

\[e^{\delta t\mathcal{L}} = e^{(\delta t/2)\mathcal{L}_B} e^{(\delta t/2)\mathcal{L}_S} e^{\delta t\mathcal{L}_O} e^{(\delta t/2)\mathcal{L}_S} e^{(\delta t/2)\mathcal{L}_B}\]

Each exponential operator above is the solution of a differential equation.

Equation ‘B’ is a boost, whose solution is:

\[v_{\eta,j}(t) = v_{\eta,j}^0 + \frac{1}{Q}\left( \frac{n+1}{\alpha_n n} m_j \mathbf{v}_j^T \mathbf{v}_j - 3 k_B T\right) t\]

Equation ‘S’ is a scaling, whose solution is:

\[\begin{split}& v_{s,i}(t) = v_i^0 e^{-\alpha_n v_{\eta_i} t} \\ & v_i(t) = \frac{v_{s,i}(t)}{\sqrt{1 - \left(\frac{v_i^0}{c_i}\right)^2 + \left(\frac{v_{s,i}(t)}{c_i}\right)^2}}\end{split}\]

Equation ‘O’ is an Ornstein–Uhlenbeck process, whose solution is:

\[v_{\eta_i}(t) = v_{\eta_i}^0 e^{-\gamma t} + \sqrt{\frac{k_B T}{Q}(1-e^{-2\gamma t})} R_N\]

where \(R_N\) is a normally distributed random number.

Parameters

• temperature (unit.Quantity) – The temperature of the heat bath.

• n (int or float) – The regulating parameter.

• timeScale (unit.Quantity (time)) – The relaxation time of the Nose-Hoover thermostat.

• frictionConstant (unit.Quantity (1/time)) – The friction coefficient of the Langevin thermostat.

Keyword Arguments

alpha_n (int or float, default=1) – Another regulating parameter.

class atomsmm.propagators.TwiceRegulatedGlobalNoseHooverLangevinPropagator(degreesOfFreedom, temperature, n, timeScale, frictionConstant, alpha_n=1, split=False)

Bases: atomsmm.propagators.Propagator

This class implements a doubly-regulated version of the global Nose-Hoover-Langevin propagator [13][14]. It provides, for every degree of freedom in the system, a solution for the following SDE system:

\[\begin{split}& dv_i = -\alpha_n v_\eta v_i \left[1 - \left(\frac{v_i}{c_i}\right)^2\right] dt \\ & dv_\eta = \frac{1}{Q}\left(\frac{n+1}{n \alpha_n} \mathbf{v}^T \mathbf{M} \mathbf{v} - N_f k_B T\right) dt - \gamma v_\eta dt + \sqrt{\frac{2\gamma k_B T}{Q}} dW,\end{split}\]

where \(c_i = \sqrt{\alpha_n n m_i k T}\) is speed limit for such degree of freedom and, by default, \(\alpha_n = \frac{n+1}{n}\). As usual, the inertial parameter \(Q\) is defined as \(Q = N_f k_B T \tau^2\), with \(\tau\) being a relaxation time [9]. An approximate solution is obtained by applying the Trotter-Suzuki splitting formula:

\[e^{\delta t\mathcal{L}} = e^{(\delta t/2)\mathcal{L}_B} e^{(\delta t/2)\mathcal{L}_S} e^{\delta t\mathcal{L}_O} e^{(\delta t/2)\mathcal{L}_S} e^{(\delta t/2)\mathcal{L}_B}\]

Each exponential operator above is the solution of a differential equation.

Equation ‘B’ is a boost, whose solution is:

\[v_\eta(t) = v_\eta^0 + \frac{1}{Q}\left( \frac{n+1}{n \alpha_n} \mathbf{v}^T \mathbf{M} \mathbf{v}- N_f k_B T\right) t\]

Equation ‘S’ is a scaling, whose solution is:

\[\begin{split}& v_{s,i}(t) = v_i^0 e^{-\alpha_n v_\eta t} \\ & v_i(t) = \frac{v_{s,i}(t)}{\sqrt{1 - \left(\frac{v_i^0}{c_i}\right)^2 + \left(\frac{v_{s,i}(t)}{c_i}\right)^2}}\end{split}\]

Equation ‘O’ is an Ornstein–Uhlenbeck process, whose solution is:

\[v_\eta(t) = v_\eta^0 e^{-\gamma t} + \sqrt{\frac{k_B T}{Q}(1-e^{-2\gamma t})} R_N\]

where \(R_N\) is a normally distributed random number.

Parameters

• degreesOfFreedom (int) – The number of degrees of freedom in the system

• temperature (unit.Quantity) – The temperature of the heat bath.

• n (int or float) – The regulating parameter.

• timeScale (unit.Quantity (time)) – The relaxation time of the Nose-Hoover thermostat.

• frictionConstant (unit.Quantity (1/time)) – The friction coefficient of the Langevin thermostat.

Keyword Arguments

alpha_n (int or float, default=1) – Another regulating parameter.

class atomsmm.propagators.ExtendedSystemPropagator(parameter, mass, period, propagator, group=None)

Bases: atomsmm.propagators.Propagator