.. _examples-mc:

.. _examples-mc-umbrella-sampling:

Umbrella Sampling
=================

This example will simply calculate the free energy profile in a given,
known, potential using umbrella sampling. The results we will obtain are
shown in the figure below: the potential energy :math:`V(x)`
and the probability density.

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

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

* **Best starting point:** :file:`examples/tutorials/umbrella_sampling/`.
* **Edit first:** :file:`umbrella_sampling_mc.py` for umbrella windows,
  force-field parameters, and the number of Monte Carlo cycles.
* **Run:** ``python umbrella_sampling_mc.py``.
* **Expected output:** terminal progress for each umbrella window and a
  plot of the reconstructed probability/free-energy profile.
* **Short check:** :file:`examples/run-tutorials.sh`
  starts this script with a timeout.
* **Related checks:** no dedicated heavy-test fixture yet; see
  :ref:`example-test-status`.

.. figure:: /_static/img/umbrella_sampling.png
   :class: img-responsive center-block
   :alt: Result from the umbrella sampling
   :align: center

   Sample results for the potential energy and the probability density.

We begin by importing the |pyretis| library and 
`numpy <http://www.numpy.org/>`_
and `matplotlib <http://matplotlib.org/>`_
which we will use for some additional numerical methods and for plotting.

.. literalinclude:: /_static/examples/examples_mc.py
   :lines: 4-10


First, we set up the system by defining the units we will
use and adding a particle (labeled as 'X') at a specified position.

.. literalinclude::  /_static/examples/examples_mc.py
   :lines: 13-15


Next we define the force field in terms of potential functions.
Here, we create the unbiased potential - a
:ref:`double well potential <user-section-potential-doublewell>` -
and a biased version of the potential where a
:ref:`rectangular well <user-section-potential-rectangularwell>` is used.
Finally, the biased force field is attached to the system.

.. literalinclude::  /_static/examples/examples_mc.py
   :lines: 17-22

In order to run the actual simulation, we need to specify some additional
settings, like where the umbrella windows should be placed and how many
cycles we need to perform:

.. literalinclude::  /_static/examples/examples_mc.py
   :lines: 24-28

and we create a random number generator for use in the umbrella simulation:

.. literalinclude::  /_static/examples/examples_mc.py
   :lines: 30-31

We are now ready to run the simulation. We will do this by looping over
the umbrella windows we defined,

.. literalinclude::  /_static/examples/examples_mc.py
   :lines: 33-65

The simulation is now done, and we can do the analysis and plot the results.
For the analysis we match the histograms:

.. literalinclude::  /_static/examples/examples_mc.py
   :lines: 67-76

And we finally plot the results:

.. literalinclude::  /_static/examples/examples_mc.py
   :lines: 78-112

Tested by
---------

This tutorial is covered by the tutorial smoke runner, which verifies
that the script starts and performs Monte Carlo cycles with the current
|pyretis| installation. Add a shortened fixture under
:file:`examples/tests/` before treating umbrella sampling as part of the
heavy regression suite.