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 internal Topology according to the provided settings. Be aware, that the entity will be altered depending on hydrogen/termini definitions in the Forcefield attached to the settings

Parameters:

  • entity (EntityHandle) – Entity from which a default Topology will be created according to the settings

  • settings (Settings) – Controls the parametrization of the Simulation and the buildup of the internal Topology

Raises:

RuntimeError when construction of Topology fails

class Simulation(topology, entity, settings)

Second constructor that takes a Topology, a consistent ost.mol.EntityHandle and a Settings as input.

Parameters:

  • topology (Topology) – Topology to initialize the Simulation

  • entity (EntityHandle) – Entity that is consistent with the provided topology

  • settings (Settings) – Controls the parametrization of the Simulation

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

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. Only Settings.openmm_plugin_directory, Settings.custom_plugin_directory and Settings.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 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.

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

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

GetTopology()
Returns:

Topology attached to the simulation

GetPeriodicBoxExtents()
Returns:

Vec3 Extents of the periodic box

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 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

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

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

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

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

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

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

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

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

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

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

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

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

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