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 Limited-memory Broyden–Fletcher–Goldfarb–Shanno (L-BFGS) 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 Urey-Bradley angle parameters in the simulation and in the attached
Topology
Parameters: - index (
int
) – Urey-Bradley 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 urey-bradley 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 x-scale - y_scale (
float
) – New y-scale - z_scale (
float
) – New z-scale
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 (