DynamicalVariable

class openxps.DynamicalVariable(name, unit, mass, bounds)

Dynamical variable for extended phase-space simulations with OpenMM.

Parameters:

• name (str) – The name of the context parameter to be turned into a dynamical variable. It must be an identifier, as in Python: a letter or an underscore followed by letters, digits or underscores, where letters may be non-ASCII (λ).

• unit (openmm.unit.unit.Unit) – The unit of measurement of this dynamical variable. If it does not have a unit, use openmm.unit.dimensionless. Couplings convert dynamical variables to MD units (see in_md_units()), so an extended phase-space context reports values in MD units and, as in OpenMM, reads numbers given without units in MD units too.

• mass (openmm.unit.quantity.Quantity) – The mass assigned to this dynamical variable, whose unit of measurement must be compatible with dalton*(nanometer/unit)**2, where unit is the dynamical variable’s own unit (see unit above).

• bounds (openxps.bounds.base.Bounds) – The boundary condition to be applied to this dynamical variable. It must be an instance of PeriodicBounds, ReflectiveBounds, or NoBounds (for unbounded variables, whose bounds are then typical values rather than actual limits). Its unit of measurement must be compatible with the dynamical variable’s own unit.

Example

>>> import openxps as xps
>>> import yaml
>>> from openmm import unit
>>> dv = xps.DynamicalVariable(
...     "psi",
...     unit.radian,
...     3 * unit.dalton*(unit.nanometer/unit.radian)**2,
...     xps.PeriodicBounds(-180, 180, unit.degree)
... )
>>> dv
DynamicalVariable(name='psi', unit=rad, mass=3 nm**2 Da/(rad**2), bounds=...)
>>> dv.bounds
PeriodicBounds(lower=-3.14159..., upper=3.14159..., unit=rad)
>>> assert yaml.safe_load(yaml.safe_dump(dv)) == dv

Methods

createCollectiveVariable(index, name=None)

Returns a cvpack.OpenMMForceWrapper object associating this extra degree of freedom with the x coordinate of a particle in an OpenMM system.

Parameters:

• index (int) – The index of the particle whose x coordinate will be associated with this dynamical variable.

• name (str | None) – The name of the context parameter to be used in the OpenMM system. If None, the name of the dynamical variable will be used.

Returns:

The collective variable object representing this dynamical variable.

Return type:

cvpack.OpenMMForceWrapper

Example

>>> import openxps as xps
>>> from openmm import unit
>>> dv = xps.DynamicalVariable(
...     "psi",
...     unit.radian,
...     3 * unit.dalton*(unit.nanometer/unit.radian)**2,
...     xps.PeriodicBounds(-180, 180, unit.degree)
... )
>>> cv = dv.createCollectiveVariable(0)

distanceTo(other)

Returns a Lepton expression representing the distance between this extra degree of freedom and another variable.

Parameters:

other (CollectiveVariable | Self) – The other variable to which the distance will be calculated.

Returns:

A string representing the distance between the two variables.

Return type:

str

Example

>>> import openxps as xps
>>> import pytest
>>> from openmm import unit
>>> dv = xps.DynamicalVariable(
...     "psi0",
...     unit.radian,
...     3 * unit.dalton*(unit.nanometer/unit.radian)**2,
...     xps.PeriodicBounds(-180, 180, unit.degree)
... )
>>> psi = cvpack.Torsion(6, 8, 14, 16, name="psi")
>>> dv.distanceTo(psi)
'(psi-psi0-6.28318...*floor(0.5+(psi-psi0)/6.28318...))'

in_md_units()

Return the dynamical variable in the MD unit system.

Return type:

DynamicalVariable

isPeriodic()

Returns whether this dynamical variable is periodic.

Returns:

True if this dynamical variable is periodic, False otherwise.

Return type:

bool

Example

>>> import openxps as xps
>>> from openmm import unit
>>> dv = xps.DynamicalVariable(
...     "psi",
...     unit.radian,
...     3 * unit.dalton*(unit.nanometer/unit.radian)**2,
...     xps.PeriodicBounds(-180, 180, unit.degree)
... )
>>> dv.isPeriodic()
True