.. _examples-openmm:

Running a |pyretis| simulation with OpenMM
==========================================

In this example, we show the interface between ``OpenMM`` and |pyretis|.

**Verification status:** engine -- see :ref:`example-tutorial-map`.

Tutorial quick start
--------------------

* **Best starting point:** the OpenMM fixture under
  :file:`examples/tests/test-openmm/` and the files included below.
* **Requirements:** ``openmm`` importable in Python and an OpenMM
  ``Simulation`` object defined in a Python module.
* **Edit first:** the ``openmm_module`` and ``openmm_simulation``
  settings in the ``Engine`` section.
* **Run:** ``pyretisrun -i openmm_retis.rst -p``.
* **Expected output:** standard RETIS output folders, with propagation
  delegated to OpenMM.
* **Related check:** :file:`examples/tests/test-openmm/`; see
  :ref:`example-test-status`.

First, we need to generate a file with an OpenMM ``Simulation`` object. We
use the online tool `OpenMM Script Builder <http://builder.openmm.org/>`_ to
generate the example with this
:download:`PDB file </_static/engine-examples/input.pdb>` containing two
water molecules.

.. literalinclude:: /_static/engine-examples/openmm_sim.py


With this ``simulation`` object, we can now construct the required ``.rst``
options in the engine section:

.. literalinclude:: /_static/engine-examples/openmm_retis.rst    
   :language: rst
   :lines: 14-20

Here we say that:

  * The engine ``type`` is ``openmm``, which tells |pyretis| that it has a
    special system representation.

  * The engine ``class`` is also ``openmm`` to tell |pyretis| we want to use the
    ``OpenMM`` engine.

  * The ``openmm_module`` is the module from which we want to load the
    simulation. Here it is ``openmm_sim.py``.

  * The ``openmm_simulation`` is the name of the object in that file. In this
    case it is ``simulation``.

Finally, we give the number of ``subcycles``, which indicates how many MD
steps ``OpenMM`` performs before |pyretis| requests another frame. This value
should be relatively high when using GPUs, as it determines how often |pyretis|
communicates with the GPU. However, keep in mind that this also lowers the
time resolution of your |pyretis| simulation.

After this, the setup can be run as a regular |pyretis| simulation using
``pyretisrun``:

.. code-block:: pyretis

   pyretisrun -i openmm_retis.rst -p

Tested by
---------

OpenMM coverage is tracked through :file:`examples/tests/test-openmm/`.
This check is optional because it depends on the local OpenMM
installation. See :ref:`example-test-status` for the current run status
before treating this example as verified on a given platform.