Package ffx.openmm

Class Context

java.lang.Object
ffx.openmm.Context
Direct Known Subclasses:
OpenMMContext
public class Context extends Object
A Context stores the complete state of a simulation. More specifically, it includes:
  • The current time
  • The position of each particle
  • The velocity of each particle
  • The values of configurable parameters defined by Force objects in the System

You can retrieve a snapshot of the current state at any time by calling getState(). This allows you to record the state of the simulation at various points, either for analysis or for checkpointing. getState() can also be used to retrieve the current forces on each particle and the current energy of the System.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    protected Integrator
    integrator
    The integrator used for this context.
    protected Platform
    platform
    The platform used for this context.

  • Constructor Summary

    Constructors
    Constructor
    Description
    Context()
    Constructor.
    Context(System system, Integrator integrator, Platform platform)
    Construct a new Context in which to run a simulation, explicitly specifying what Platform should be used to perform calculations.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    applyConstraints(double tol)
    Update the positions of particles so that all distance constraints are satisfied.
    void
    applyVelocityConstraints(double tol)
    Update the velocities of particles so the net velocity of each constrained distance is zero.
    void
    computeVirtualSites()
    Recompute the locations of all virtual sites.
    void
    destroy()
    Destroy the context.
    Integrator
    getIntegrator()
    Get Integrator being used by this context.
    double
    getParameter(com.sun.jna.Pointer name)
    Get the value of an adjustable parameter defined by a Force object in the System.
    double
    getParameter(String name)
    Get the value of an adjustable parameter defined by a Force object in the System.
    com.sun.jna.ptr.PointerByReference
    getParameters()
    Get all adjustable parameters that have been defined by Force objects in the System, along with their current values.
    Platform
    getPlatform()
    Get the Platform being used for calculations.
    com.sun.jna.ptr.PointerByReference
    getPointer()
    Get the pointer to the context.
    State
    getState(int types, int enforcePeriodicBox)
    Get a State object recording the current state information stored in this context.
    State
    getState(int types, int enforcePeriodicBox, int groups)
    Get a State object recording the current state information stored in this context.
    long
    getStepCount()
    Get the current step count.
    System
    getSystem()
    Get System being simulated in this context.
    double
    getTime()
    Get the current time of the simulation (in picoseconds).
    boolean
    hasContextPointer()
    Does the context have a pointer?
    void
    reinitialize(int preserveState)
    When a Context is created, it caches information about the System being simulated and the Force objects contained in it.
    void
    setParameter(com.sun.jna.Pointer name, double value)
    Set the value of an adjustable parameter defined by a Force object in the System.
    void
    setParameter(String name, double value)
    Set the value of an adjustable parameter defined by a Force object in the System.
    void
    setPeriodicBoxVectors(edu.uiowa.jopenmm.OpenMM_Vec3 a, edu.uiowa.jopenmm.OpenMM_Vec3 b, edu.uiowa.jopenmm.OpenMM_Vec3 c)
    Set the vectors defining the axes of the periodic box (measured in nm).
    void
    setPositions(double[] positions)
    Set the positions of all particles in the System (measured in nm).
    void
    setState(State state)
    Copy information from a State object into this Context.
    void
    setStepCount(long steps)
    Set the current step count.
    void
    setTime(double time)
    Set the current time of the simulation (in picoseconds).
    void
    setVelocities(double[] velocities)
    Set the velocities of all particles in the System (measured in nm/picosecond).
    void
    setVelocitiesToTemperature(double temperature, int randomSeed)
    Set the velocities of all particles in the System to random values chosen from a Boltzmann distribution at a given temperature.
    void
    updateContext(System system, Integrator integrator, Platform platform)
    Update the context.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • integrator

      protected Integrator integrator
      The integrator used for this context.

    • platform

      protected Platform platform
      The platform used for this context.

  • Constructor Details

    • Context

      public Context()
      Constructor.

    • Context

      public Context(System system, Integrator integrator, Platform platform)
      Construct a new Context in which to run a simulation, explicitly specifying what Platform should be used to perform calculations.
      Parameters:
      system - the System which will be simulated
      integrator - the Integrator which will be used to simulate the System
      platform - the Platform to use for calculations

  • Method Details

    • applyConstraints

      public void applyConstraints(double tol)
      Update the positions of particles so that all distance constraints are satisfied. This also recomputes the locations of all virtual sites.
      Parameters:
      tol - the distance tolerance within which constraints must be satisfied.

    • applyVelocityConstraints

      public void applyVelocityConstraints(double tol)
      Update the velocities of particles so the net velocity of each constrained distance is zero.
      Parameters:
      tol - the velocity tolerance within which constraints must be satisfied.

    • computeVirtualSites

      public void computeVirtualSites()
      Recompute the locations of all virtual sites. There is rarely a reason to call this, since virtual sites are also updated by applyConstraints(). This is only for the rare situations when you want to enforce virtual sites but not constraints.

    • destroy

      public void destroy()
      Destroy the context.

    • getParameter

      public double getParameter(String name)
      Get the value of an adjustable parameter defined by a Force object in the System.
      Parameters:
      name - the name of the parameter to get
      Returns:
      the value of the parameter

    • getParameter

      public double getParameter(com.sun.jna.Pointer name)
      Get the value of an adjustable parameter defined by a Force object in the System.
      Parameters:
      name - the name of the parameter to get
      Returns:
      the value of the parameter

    • getParameters

      public com.sun.jna.ptr.PointerByReference getParameters()
      Get all adjustable parameters that have been defined by Force objects in the System, along with their current values.
      Returns:
      a PointerByReference to a map containing the values of all parameters

    • getPlatform

      public Platform getPlatform()
      Get the Platform being used for calculations.
      Returns:
      the Platform being used for calculations

    • getIntegrator

      public Integrator getIntegrator()
      Get Integrator being used by this context.
      Returns:
      the Integrator being used by this context

    • getPointer

      public com.sun.jna.ptr.PointerByReference getPointer()
      Get the pointer to the context.
      Returns:
      The pointer to the context.

    • getState

      public State getState(int types, int enforcePeriodicBox)
      Get a State object recording the current state information stored in this context.
      Parameters:
      types - the set of data types which should be stored in the State object. This should be a union of DataType values, e.g. (State::Positions | State::Velocities).
      enforcePeriodicBox - if false, the position of each particle will be whatever position is stored in the Context, regardless of periodic boundary conditions. If true, particle positions will be translated so the center of every molecule lies in the same periodic box.
      Returns:
      a State object recording the current state information

    • getState

      public State getState(int types, int enforcePeriodicBox, int groups)
      Get a State object recording the current state information stored in this context.
      Parameters:
      types - the set of data types which should be stored in the State object. This should be a union of DataType values, e.g. (State::Positions | State::Velocities).
      enforcePeriodicBox - if false, the position of each particle will be whatever position is stored in the Context, regardless of periodic boundary conditions. If true, particle positions will be translated so the center of every molecule lies in the same periodic box.
      groups - a set of bit flags for which force groups to include when computing forces and energies. Group i will be included if (groups&(1<<i)) != 0. The default value includes all groups.
      Returns:
      a State object recording the current state information

    • getStepCount

      public long getStepCount()
      Get the current step count.
      Returns:
      the current step count

    • getSystem

      public System getSystem()
      Get System being simulated in this context.
      Returns:
      the System being simulated in this context

    • getTime

      public double getTime()
      Get the current time of the simulation (in picoseconds).
      Returns:
      the current time of the simulation (in picoseconds)

    • hasContextPointer

      public boolean hasContextPointer()
      Does the context have a pointer?
      Returns:
      True if the context pointer is not null.

    • reinitialize

      public void reinitialize(int preserveState)
      When a Context is created, it caches information about the System being simulated and the Force objects contained in it. This means that, if the System or Forces are then modified, the Context does not see the changes. Call reinitialize() to force the Context to rebuild its internal representation of the System and pick up any changes that have been made.

      This is an expensive operation, so you should try to avoid calling it too frequently. Most Force classes have an updateParametersInContext() method that provides a less expensive way of updating certain types of information. However, this method is the only way to make some types of changes, so it is sometimes necessary to call it.

      By default, reinitializing a Context causes all state information (positions, velocities, etc.) to be discarded. You can optionally tell it to try to preserve state information. It does this by internally creating a checkpoint, then reinitializing the Context, then loading the checkpoint. Be aware that if the System has changed in a way that prevents the checkpoint from being loaded (such as changing the number of particles), this will throw an exception and the state information will be lost.

      Parameters:
      preserveState - if true, try to preserve state information; if false, discard all state information

    • setParameter

      public void setParameter(String name, double value)
      Set the value of an adjustable parameter defined by a Force object in the System.
      Parameters:
      name - the name of the parameter to set
      value - the value of the parameter

    • setParameter

      public void setParameter(com.sun.jna.Pointer name, double value)
      Set the value of an adjustable parameter defined by a Force object in the System.
      Parameters:
      name - the name of the parameter to set
      value - the value of the parameter

    • setPeriodicBoxVectors

      public void setPeriodicBoxVectors(edu.uiowa.jopenmm.OpenMM_Vec3 a, edu.uiowa.jopenmm.OpenMM_Vec3 b, edu.uiowa.jopenmm.OpenMM_Vec3 c)
      Set the vectors defining the axes of the periodic box (measured in nm). They will affect any Force that uses periodic boundary conditions.

      Triclinic boxes are supported, but the vectors must satisfy certain requirements. In particular, a must point in the x direction, b must point "mostly" in the y direction, and c must point "mostly" in the z direction. See the documentation for details.

      Parameters:
      a - the vector defining the first edge of the periodic box
      b - the vector defining the second edge of the periodic box
      c - the vector defining the third edge of the periodic box

    • setPositions

      public void setPositions(double[] positions)
      Set the positions of all particles in the System (measured in nm). This method simply sets the positions without checking to see whether they satisfy distance constraints. If you want constraints to be enforced, call applyConstraints() after setting the positions.
      Parameters:
      positions - a vector whose length equals the number of particles in the System. The i'th element contains the position of the i'th particle.

    • setState

      public void setState(State state)
      Copy information from a State object into this Context. This restores the Context to approximately the same state it was in when the State was created. If the State does not include a piece of information (e.g. positions or velocities), that aspect of the Context is left unchanged.

      Even when all possible information is included in the State, the effect of calling this method is still less complete than loadCheckpoint(). For example, it does not restore the internal states of random number generators. On the other hand, it has the advantage of not being hardware specific.

      Parameters:
      state - the State object to copy information from

    • setStepCount

      public void setStepCount(long steps)
      Set the current step count.
      Parameters:
      steps - the current step count

    • setTime

      public void setTime(double time)
      Set the current time of the simulation (in picoseconds).
      Parameters:
      time - the current time of the simulation (in picoseconds)

    • setVelocities

      public void setVelocities(double[] velocities)
      Set the velocities of all particles in the System (measured in nm/picosecond).
      Parameters:
      velocities - a vector whose length equals the number of particles in the System. The i'th element contains the velocity of the i'th particle.

    • setVelocitiesToTemperature

      public void setVelocitiesToTemperature(double temperature, int randomSeed)
      Set the velocities of all particles in the System to random values chosen from a Boltzmann distribution at a given temperature.
      Parameters:
      temperature - the temperature for which to select the velocities (measured in Kelvin)
      randomSeed - the random number seed to use when selecting velocities

    • updateContext

      public void updateContext(System system, Integrator integrator, Platform platform)
      Update the context.
      Parameters:
      system - The system to simulate.
      integrator - The integrator to use for simulating the system.
      platform - The platform to use for performing computations.