Tutorial
========

.. _tutorial-dhfr:

Molecular dynamics simulation of DHFR
-------------------------------------

DHFR (`dihydrofolate reductase <https://en.wikipedia.org/wiki/Dihydrofolate_reductase>`_) is a globular protein commonly used as a 
benchmark in MD simulations.

For the MD simulation with *ACEMD*, you need to:

- Prepare the simulation system and corresponding force field files
- Write an input file
- Run the simulation

All these tasks can be done easily with `HTMD <https://www.htmd.org/>`_: following the tutorial of the 
`molecular dynamics protocols <https://software.acellera.com/htmd/tutorials/md-protocols.html>`_.

In this tutorial, we show how to run the MD simulation with *ACEMD* directly.
The prepared DHFR files for the *CHARMM 36* force field can be found :download:`here <./acemd_benchmarks.zip>`.

Preparation
^^^^^^^^^^^

Extract the files to an empty directory and change into the ``dhfr_charmm`` directory

.. code-block:: bash

    unzip acemd_benchmarks.zip -d /tmp/
    cd /tmp/acemd_benchmarks/dhfr_charmm

The input file is for an NVT (298.15 K) simulation with 4 fs time step

.. code-block:: yaml

    parameters: dhfr.prm
    structure: dhfr.psf
    coordinates: dhfr.pdb
    boxsize: [62.23, 62.23, 62.23]
    thermostat: true
    run: 28ns

The other parameters are set to the default values (see the :ref:`input file options <input-options>` for details).

Starting the simulation
^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: bash

    acemd

By default, *ACEMD* runs on the first GPU (device 0).
This can be changed with ``--device`` argument (see the :ref:`command line arguments <arguments>` for details).

During the simulation, log messages are written to the standard output as well as to the ``output.csv`` file, 
and the simulation trajectory is saved to ``output.xtc``.
Also, the simulation state is periodically saved to ``restart.chk`` (see the :ref:`input options <input-options>` for details)

.. code-block:: bash

    $ ls -1
    dhfr.pdb
    dhfr.prm
    dhfr.psf
    input.yaml
    output.coor
    output.csv
    output.vel
    output.xsc
    output.xtc
    restart.chk

Python API
^^^^^^^^^^

ACEMD 4.0 introduces a basic Python API to run simulations. Instead of executing the ``acemd`` command from the command line, 
simulations can be run by importing the ``acemd`` package and calling the ``acemd()`` function. This allows for better
integration of ACEMD within python packages and scripts.

.. code-block:: python

    from acemd import acemd

    acemd(".") # Execute the current directory

This function can also accept any keyword arguments from the :ref:`input options <input-options>` in lower case
to override the values read from the input file in the given directory.

For example if we want to run the simulation in the directory ``/tmp/my_simulation`` for 2 ns,
we can do the following:

.. code-block:: python

    acemd("/tmp/my_simulation", run="2ns")

This will read the input file from ``/tmp/my_simulation/input.yaml`` and override the ``run`` parameter with the given value.

You can also pass as keyword arguments any of the :ref:`command line arguments <arguments>` for example to specify the device to run on:

.. code-block:: python

    acemd("/tmp/my_simulation", device=[0, 1], run="2ns")