Simulation¶
The simulation finally connects a Topology
with an
EntityHandle
. While applying minimization or
md tasks, the current positions of the simulation object can be
mapped back to the attached structure at any time.

class
Simulation
(entity, settings)¶ First constructor that takes an
ost.mol.EntityHandle
as an input and automatically constructs an internalTopology
according to the provided settings. Be aware, that the entity will be altered depending on hydrogen/termini definitions in theForcefield
attached to the settingsParameters:  entity (
EntityHandle
) – Entity from which a defaultTopology
will be created according to the settings  settings (
Settings
) – Controls the parametrization of theSimulation
and the buildup of the internalTopology
Raises: RuntimeError
when construction ofTopology
fails entity (

class
Simulation
(topology, entity, settings) Second constructor that takes a
Topology
, a consistentost.mol.EntityHandle
and aSettings
as input.Parameters:  topology (
Topology
) – Topology to initialize theSimulation
 entity (
EntityHandle
) – Entity that is consistent with the provided topology  settings (
Settings
) – Controls the parametrization of theSimulation
Raises: RuntimeException
when number of atoms in entity is not equal the number of particles in topology
Save
(filename, settings)¶ Dumps current status of the simulation with its connected entity onto disk. All informations from the entity except plain chains, residues, atoms and bonds are lost.
Parameters: filename ( str
) – Filename

static
Load
(filename)¶ Loads a dumped simulation from disk. You have to make sure, that the provided settings are consistent with those from the saved simulation. Undefined behaviour must be expected otherwise.
Parameters:  filename (
str
) – Filename  settings (
Settings
) – Settings to reparametrize loaded simulation
 filename (

static
IsPlatformAvailable
(settings)¶ Returns: True, if platform defined in settings is available. Otherwise, construction of a simulation object will fail with these settings. Return type: bool
Parameters: settings ( Settings
) – Controls the parametrization of this class. OnlySettings.openmm_plugin_directory
,Settings.custom_plugin_directory
andSettings.platform
are relevant.

ApplyLBFGS
([tolerance=1.0, max_iterations=1000])¶ Run minimization using the Limitedmemory Broyden–Fletcher–Goldfarb–Shanno (LBFGS) method.
Parameters:  tolerance (
float
) – Tolerance describing abort criteria of minimization. The tolerance is interpreted as the root mean square value of all force components.  max_iterations (
int
) – Maximum number of minimization iterations
 tolerance (

ApplySD
([tolerance=100, max_iterations=1000])¶ Run minimization using the steepest descend method.
Parameters:  tolerance (
float
) – Tolerance describing abort criteria of minimization. The tolerance is interpreted as the norm of the maximum force acting onto the particles.  max_iterations (
int
) – Maximum number of minimization iterations
Returns: bool
whether tolerance has been reached tolerance (

Steps
(steps)¶ Runs the simulation for steps number of steps.
Parameters: steps ( int
) – Number of steps to perform

GetPositions
([enforce_periodic_box = false, in_angstrom = true])¶ Parameters:  enforce_periodic_box (
bool
) – True if periodic box has to be enforced  in_angstrom (
bool
) – True if positions should be in Angstrom, they’re in nm otherwise
Returns: A
ost.geom.Vec3List
of all the positions of the atoms in the Entity. enforce_periodic_box (

SetPositions
(positions[, in_angstrom = true])¶ Parameters:  positions (
ost.geom.Vec3List
) – Positions to be set  in_angstrom (
bool
) – True if positions are in Angstrom, they’re expected to be in nm otherwise
 positions (

UpdatePositions
([enforce_periodic_box=false])¶ Sets the positions of the atoms in the
EntityHandle
to the current positions of the simulation.Parameters: enforce_periodic_box ( bool
) – True if periodic box should be enforced

GetVelocities
()¶ Returns: A Vec3List
of all the velocities of the atoms in the Entity.

GetForces
()¶ Returns: A Vec3List
of all the resulting forces for each atom in the Entity.

SetVelocities
(velocities)¶ Parameters: velocities ( ost.geom.Vec3List
) – Velocities to be set

GetEntity
()¶ Returns: EntityHandle
attached to the simulation

GetEnergy
()¶ Returns: float
Potential + Kinetic energy in kJ/mol of current simulation state

GetPotentialEnergy
()¶ Returns: float
Potential energy in kJ/mol of current simulation state

GetKineticEnergy
()¶ Returns: float
Kinetic energy in kJ/mol of current simulation state

SetPeriodicBoxExtents
(vec)¶ Parameters: vec ( ost.geom.Vec3
) – Periodic box extents in A

Register
(observer)¶ Adds an observer to the simulation object. This can be used for example to write out the trajectory during the simulation.
Parameters: observer ( Observer
) – Observer to be attached

AddPositionConstraint
(index)¶ Fixes the position of the particle with index given in the argument. This requires to reinitialize the internal openmm Context (this is expensive!). Positions, velocities, forces, energies etc. are properly preserved but e.g. states of random number generators etc. might be lost.
Parameters: index ( int
) – Particle to be fixedRaises: RuntimeError
when index exceeds number of particles

AddPositionConstraints
(indices)¶ Fixes the position of the atoms with the indices given in in the argument. This requires to reinitialize the internal openmm Context (this is expensive!). Positions, velocities, forces, energies etc. are properly preserved but e.g. states of random number generators etc. might be lost.
Parameters: indices ( list
) – Particles to be fixedRaises: RuntimeError
when an index in indices exceeds number of particles

ResetPositionConstraints
()¶ Removes all position constraints. This requires to reinitialize the internal openmm Context (this is expensive!). Positions, velocities, forces, energies etc. are properly preserved but e.g. states of random number generators etc. might be lost.

ResetHarmonicBond
(index, bond_length, force_constant)¶ Update of the harmonic bond parameters in the simulation and in the attached
Topology
Parameters:  index (
int
) – Harmonic Bond to be reset  bond_length (
float
) – New bond length in nm  force_constant (
float
) – New force constant in kJ/mol/nm^2
Raises: RuntimeError
when index exceeds number of harmonic bonds index (

ResetHarmonicAngle
()¶ Update of the harmonic angle parameters in the simulation and in the attached
Topology
Parameters:  index (
int
) – Harmonic Angle to be reset  angle (
float
) – New Angle in radians  force_constant (
float
) – New force constant in kJ/mol/radian^2
Raises: RuntimeError
when index exceeds number of harmonic angles index (

ResetUreyBradleyAngle
(index, angle, angle_force_constant, bond_length, bond_force_constant)¶ Update of the UreyBradley angle parameters in the simulation and in the attached
Topology
Parameters:  index (
int
) – UreyBradley angle that has to be reset  angle (
float
) – New angle in radians  angle_force_constant (
float
) – New angle force constant kJ/mol/radian^2  bond_length (
float
) – New bond length in nm  bond_force_constant (
float
) – New bond force constant in kJ/mol/nm^2
Raises: RuntimeError
when index exceeds number of ureybradley angles index (

ResetPeriodicDihedral
(index, multiplicity, phase, force_constant)¶ Update of the periodic dihedral parameters in the simulation and in the attached
Topology
Parameters:  index (
int
) – Periodic dihedral to be reset  multiplicity (
int
) – New Multiplicity  phase (
float
) – New phase in radians  force_constant (
float
) – New force constant in kJ/mol/radian^2
Raises: RuntimeError
when index exceeds number of periodic dihedrals index (

ResetPeriodicImproper
(index, multiplicity, phase, force_constant)¶ Update of the periodic improper parameters in the simulation and in the attached
Topology
Parameters:  index (
int
) – Periodic improper to be reset  multiplicity (
int
) – New multiplicity  phase (
float
) – New phase in radians  force_constant (
float
) – New force constant kJ/mol/radian^2
Raises: RuntimeError
when index exceeds number of periodic impropers index (

ResetHarmonicImproper
(index, phase, force_constant)¶ Update of the harmonic improper parameters in the simulation and in the attached
Topology
Parameters:  index (
int
) – Harmonic improper to be reset  phase (
float
) – New phase in radians  force_constant (
float
) – New force constant kJ/mol/radian^2
Raises: RuntimeError
when index exceeds number of harmonic impropers index (

ResetLJPair
(index, sigma, epsilon)¶ Update of the LJ pair parameters in the simulation and in the attached
Topology
Parameters:  index (
int
) – LJ pair to be reset  sigma (
float
) – New sigma in nm  epsilon (
float
) – New epsilon in kJ/mol
Raises: RuntimeError
when index exceeds number of LJ pairs index (

ResetDistanceConstraint
(index, constraint_length)¶ Update of the distance constraint parameters in the simulation and in the attached
Topology
. This requires to reinitialize the internal openmm Context (this is expensive!). Positions, velocities, forces, energies etc. are properly preserved but e.g. states of random number generators etc. might be lost.Parameters:  index (
int
) – Distance constraint to be reset  constraint_length (
float
) – New constraint length in nm
Raises: RuntimeError
when index exceeds number of distance constraints index (

ResetHarmonicPositionRestraint
(index, ref_position, force_constant, x_scale, y_scale, z_scale)¶ Update of the harmonic position restraint parameters in the simulation and in the attached
Topology
Parameters:  index (
int
) – Harmonic position restraint to be reset  ref_position (
ost.geom.Vec3
) – New reference position in nm  force_constant (
float
) – New force constant in kJ/mol/nm^2  x_scale (
float
) – New xscale  y_scale (
float
) – New yscale  z_scale (
float
) – New zscale
Raises: RuntimeError
when index exceeds number of harmonic position restraints index (

ResetHarmonicDistanceRestraint
(index, length, force_constant)¶ Update of the harmonic distance restraint parameters in the simulation and in the attached
Topology
Parameters:  index (
int
) – Harmonic distance restraint to be reset  length (
float
) – New restraint length in nm  force_constant (
float
) – New force constant kJ/mol/nm^2
Raises: RuntimeError
when index exceeds number of harmonic distance restraints index (

ResetLJ
(index, sigma, epsilon)¶ Update of the lj parameters in the simulation and in the attached
Topology
Parameters:  index (
int
) – LJ to be reset  sigma (
float
) – New sigma in nm  epsilon (
float
) – New epsilon in kJ/mol
Raises: RuntimeError
when index exceeds number of particles index (

ResetGBSA
(index, radius, scaling)¶ Update of the GBSA parameters in the simulation and in the attached
Topology
Parameters:  index (
int
) – : GB to be reset  radius (
float
) – New radius in nm  scaling (
float
) – New OBC scaling
Raises: RuntimeError
when index exceeds number of particles index (

ResetCharge
(index, charge)¶ Update of the charge in the simulation and in the attached
Topology
Parameters:  index (
int
) – Charge to be reset  charge (
float
) – New Charge
Raises: RuntimeError
when index exceeds number of particles index (

ResetMass
(index, mass)¶ Update of the mass in the simulation and in the attached
Topology
This requires to reinitialize the internal openmm Context (this is expensive!). Positions, velocities, forces, energies etc. are properly preserved but e.g. states of random number generators etc. might be lost.Parameters:  index (
int
) – Mass to be reset  mass (
float
) – New mass
Raises: RuntimeError
when index exceeds number of particles index (
 topology (