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 settings- Parameters:
entity (
EntityHandle
) – Entity from which a defaultTopology
will be created according to the settingssettings (
Settings
) – Controls the parametrization of theSimulation
and the buildup of the internalTopology
- Raises:
RuntimeError
when construction ofTopology
fails
- 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 topologysettings (
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
) – Filenamesettings (
Settings
) – Settings to reparametrize loaded simulation
- 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
- 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
- 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 enforcedin_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.
- SetPositions(positions[, in_angstrom = true])¶
- Parameters:
positions (
ost.geom.Vec3List
) – Positions to be setin_angstrom (
bool
) – True if positions are in Angstrom, they’re expected to be in nm otherwise
- 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 fixed- Raises:
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 fixed- Raises:
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 resetbond_length (
float
) – New bond length in nmforce_constant (
float
) – New force constant in kJ/mol/nm^2
- Raises:
RuntimeError
when index exceeds number of harmonic bonds
- ResetHarmonicAngle()¶
Update of the harmonic angle parameters in the simulation and in the attached
Topology
- Parameters:
index (
int
) – Harmonic Angle to be resetangle (
float
) – New Angle in radiansforce_constant (
float
) – New force constant in kJ/mol/radian^2
- Raises:
RuntimeError
when index exceeds number of harmonic angles
- 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 resetangle (
float
) – New angle in radiansangle_force_constant (
float
) – New angle force constant kJ/mol/radian^2bond_length (
float
) – New bond length in nmbond_force_constant (
float
) – New bond force constant in kJ/mol/nm^2
- Raises:
RuntimeError
when index exceeds number of urey-bradley angles
- 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 resetmultiplicity (
int
) – New Multiplicityphase (
float
) – New phase in radiansforce_constant (
float
) – New force constant in kJ/mol/radian^2
- Raises:
RuntimeError
when index exceeds number of periodic dihedrals
- 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 resetmultiplicity (
int
) – New multiplicityphase (
float
) – New phase in radiansforce_constant (
float
) – New force constant kJ/mol/radian^2
- Raises:
RuntimeError
when index exceeds number of periodic impropers
- 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 resetphase (
float
) – New phase in radiansforce_constant (
float
) – New force constant kJ/mol/radian^2
- Raises:
RuntimeError
when index exceeds number of harmonic impropers
- 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 resetsigma (
float
) – New sigma in nmepsilon (
float
) – New epsilon in kJ/mol
- Raises:
RuntimeError
when index exceeds number of LJ pairs
- 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 resetconstraint_length (
float
) – New constraint length in nm
- Raises:
RuntimeError
when index exceeds number of distance constraints
- 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 resetref_position (
ost.geom.Vec3
) – New reference position in nmforce_constant (
float
) – New force constant in kJ/mol/nm^2x_scale (
float
) – New x-scaley_scale (
float
) – New y-scalez_scale (
float
) – New z-scale
- Raises:
RuntimeError
when index exceeds number of harmonic position restraints
- 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 resetlength (
float
) – New restraint length in nmforce_constant (
float
) – New force constant kJ/mol/nm^2
- Raises:
RuntimeError
when index exceeds number of harmonic distance restraints
- ResetLJ(index, sigma, epsilon)¶
Update of the lj parameters in the simulation and in the attached
Topology
- Parameters:
index (
int
) – LJ to be resetsigma (
float
) – New sigma in nmepsilon (
float
) – New epsilon in kJ/mol
- Raises:
RuntimeError
when index exceeds number of particles
- ResetGBSA(index, radius, scaling)¶
Update of the GBSA parameters in the simulation and in the attached
Topology
- Parameters:
index (
int
) – : GB to be resetradius (
float
) – New radius in nmscaling (
float
) – New OBC scaling
- Raises:
RuntimeError
when index exceeds number of particles
- ResetCharge(index, charge)¶
Update of the charge in the simulation and in the attached
Topology
- Parameters:
index (
int
) – Charge to be resetcharge (
float
) – New Charge
- Raises:
RuntimeError
when index exceeds number of particles
- 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 resetmass (
float
) – New mass
- Raises:
RuntimeError
when index exceeds number of particles