openmmtools.testsystems.HarmonicOscillator

class openmmtools.testsystems.HarmonicOscillator(K=Quantity(value=100.0, unit=kilocalorie/(angstrom**2*mole)), mass=Quantity(value=39.948, unit=dalton), U0=Quantity(value=0.0, unit=kilojoule/mole), **kwargs)

Create a 3D harmonic oscillator, with a single particle confined in an isotropic harmonic well.

Parameters:

K : simtk.unit.Quantity, optional, default=100.0 * unit.kilocalories_per_mole/unit.angstrom**2

harmonic restraining potential

mass : simtk.unit.Quantity, optional, default=39.948 * unit.amu

particle mass

U0 : simtk.unit.Quantity, optional, default=0.0 * unit.kilocalories_per_mole

Potential offset for harmonic oscillator

The functional form is given by

U(x) = (K/2) * ( (x-x0)^2 + y^2 + z^2 ) + U0

Notes

The natural period of a harmonic oscillator is T = 2*pi*sqrt(m/K), so you will want to use an integration timestep smaller than ~ T/10.

The standard deviation in position in each dimension is sigma = (kT / K)^(1/2)

The expectation and standard deviation of the potential energy of a 3D harmonic oscillator is (3/2)kT.

Examples

Create a 3D harmonic oscillator with default parameters:

>>> ho = HarmonicOscillator()
>>> (system, positions) = ho.system, ho.positions

Create a harmonic oscillator with specified mass and spring constant:

>>> mass = 12.0 * unit.amu
>>> K = 1.0 * unit.kilocalories_per_mole / unit.angstroms**2
>>> ho = HarmonicOscillator(K=K, mass=mass)
>>> (system, positions) = ho.system, ho.positions

Get a list of the available analytically-computed properties.

>>> print(ho.analytical_properties)
['potential_expectation', 'potential_standard_deviation']

Compute the potential expectation and standard deviation

>>> import simtk.unit as u
>>> thermodynamic_state = ThermodynamicState(temperature=298.0*u.kelvin, system=system)
>>> potential_mean = ho.get_potential_expectation(thermodynamic_state)
>>> potential_stddev = ho.get_potential_standard_deviation(thermodynamic_state)

TODO: * Add getters and setters for K, x0, U0 that access current global parameter in system * Add method to compute free energy of the harmonic oscillator(s)

Attributes:

system : simtk.openmm.System

The simtk.openmm.System object corresponding to the test system.

positions : list

The simtk.unit.Quantity object containing the particle positions, with units compatible with simtk.unit.nanometers.

Methods

get_potential_expectation(state)	Return the expectation of the potential energy, computed analytically or numerically.
get_potential_standard_deviation(state)	Return the standard deviation of the potential energy, computed analytically or numerically.
reduced_potential_expectation(…)	Calculate the expected potential energy in state_sampled_from, divided by kB * T in state_evaluated_in.
serialize()	Return the System and positions in serialized XML form.

__init__(K=Quantity(value=100.0, unit=kilocalorie/(angstrom**2*mole)), mass=Quantity(value=39.948, unit=dalton), U0=Quantity(value=0.0, unit=kilojoule/mole), **kwargs)

Abstract base class for test system.

Methods

__init__([K, unit, mass, unit, U0, unit])	Abstract base class for test system.
get_potential_expectation(state)	Return the expectation of the potential energy, computed analytically or numerically.
get_potential_standard_deviation(state)	Return the standard deviation of the potential energy, computed analytically or numerically.
reduced_potential_expectation(…)	Calculate the expected potential energy in state_sampled_from, divided by kB * T in state_evaluated_in.
serialize()	Return the System and positions in serialized XML form.

Attributes

analytical_properties	A list of available analytical properties, accessible via ‘get_propertyname(thermodynamic_state)’ calls.
mdtraj_topology	The mdtraj.Topology object corresponding to the test system (read-only).
name	The name of the test system.
positions	The simtk.unit.Quantity object containing the particle positions, with units compatible with simtk.unit.nanometers.
system	The simtk.openmm.System object corresponding to the test system.
topology	The simtk.openmm.app.Topology object corresponding to the test system.

analytical_properties

A list of available analytical properties, accessible via ‘get_propertyname(thermodynamic_state)’ calls.

get_potential_expectation(state)

Return the expectation of the potential energy, computed analytically or numerically.

Returns:

potential_mean : simtk.unit.Quantity compatible with simtk.unit.kilojoules_per_mole

The expectation of the potential energy.

get_potential_standard_deviation(state)

Return the standard deviation of the potential energy, computed analytically or numerically.

Returns:

potential_stddev : simtk.unit.Quantity compatible with simtk.unit.kilojoules_per_mole

potential energy standard deviation if implemented, or else None

mdtraj_topology

The mdtraj.Topology object corresponding to the test system (read-only).

name

The name of the test system.

positions

The simtk.unit.Quantity object containing the particle positions, with units compatible with simtk.unit.nanometers.

reduced_potential_expectation(state_sampled_from, state_evaluated_in)

Calculate the expected potential energy in state_sampled_from, divided by kB * T in state_evaluated_in.

Notes

This is not called get_reduced_potential_expectation because this function requires two, not one, inputs.

serialize()

Return the System and positions in serialized XML form.

Returns:

system_xml : str

Serialized XML form of System object.

state_xml : str

Serialized XML form of State object containing particle positions.

system

The simtk.openmm.System object corresponding to the test system.

topology

The simtk.openmm.app.Topology object corresponding to the test system.