First Simulation
================

This tutorial provides a complete, step-by-step guide to performing your first
molecular dynamics simulation using **DROPPS**.  

DROPPS is intentionally designed to mimic the user interface of GROMACS, meaning
that each step corresponds to a familiar GROMACS command:

===================  ===================
GROMACS              DROPPS
===================  ===================
gmx pdb2gmx          dps pdb2dps
gmx editconf         dps editconf
gmx grompp           dps grompp
gmx mdrun            dps mdrun
gmx make_ndx         dps make_ndx
gmx contact          dps contact
===================  ===================

This tutorial walks you through the complete pipeline.

Overview of the Workflow
------------------------

A DROPPS simulation consists of the following steps:

1. Generate single-chain structure & topology (`pdb2dps`)
2. Build a multi-chain system (`genmesh`)
3. Prepare simulation input (`grompp`)
4. Run MD simulation (`mdrun`)
5. (Optional) Build index groups (`make_ndx`)
6. (Optional) Perform trajectory analysis (`contact`, `density`, `gyrate`, etc.)

Each step directly corresponds to a command in the ``dps`` command-line suite.


1. Generate Structure and Topology (pdb2dps)
--------------------------------------------

To create the initial single-chain structure and topology from a sequence or
PDB file, use ``dps pdb2dps``:

.. code-block:: bash

   dps pdb2dps -f asyn.pdb -op asyn -on asyn -oc asyn

This command performs:

- sequence parsing  
- generation of HPS bead representation  
- force-field assignment  
- writing the following files:
  
  - ``asyn.pdb``  — coarse-grained coordinates  
  - ``asyn.itp``  — single-chain topology  
  - ``asyn-angle.itp`` (optional, if angles are included)

2. Build a Multi-Chain System (genmesh)
---------------------------------------

To construct a system with many copies of the protein, use ``dps genmesh``:

.. code-block:: bash

   dps genmesh -f asyn.pdb -mesh 5 5 5 -n 125 -p asyn.top -o system.pdb

This command:

- arranges 125 chains on a 5×5×5 spatial mesh  
- generates a multi-chain coordinate file (``system.pdb``)  
- generates or updates a system topology file (``system.top``)

``insert-molecules`` in GROMACS is replaced by ``dps genmesh``


3. Prepare MD Input (grompp)
----------------------------

Once the structure and topology are ready, create the simulation input file
(``.tpr``) using:

.. code-block:: bash

   dps grompp -m md.mdp -f system.pdb -p system.top -o asyn.tpr

This step:

- reads ``md.mdp`` (simulation parameters)
- reads ``system.pdb`` (coordinates)
- reads ``system.top`` (topology)
- generates ``asyn.tpr`` containing all integrated information


4. Run the Simulation (mdrun)
-----------------------------

To run the MD simulation:

.. code-block:: bash

   dps mdrun -s asyn.tpr -o asyn

The simulation will output:

- ``asyn.xtc`` — coarse-grained trajectory
- ``asyn.edr`` — energy file
- ``asyn.log`` — simulation log
- periodic screen output with step/energy summaries

This mirrors ``gmx mdrun`` but optimized for HPS simulations.


5. Generate Index Groups (Optional)
-----------------------------------

Some analyses require custom index groups.

Use:

.. code-block:: bash

   dps make_ndx -f asyn.tpr -o asyn.ndx

The interactive interface supports:

- `splitch` — automatically split groups by chain (specialized for large multichain HPS systems)
- `res`, `abbr`, `chain`, `index`, etc.


6. Perform Data Analysis (Optional)
-----------------------------------

DROPPS provides a suite of built-in analysis tools (page 36):

- ``dps density``  
- ``dps cmap``  
- ``dps idist`` / ``dps odist``  
- ``dps gyrate``  
- ``dps contact``  

Example: calculate a contact number map between protein chains:

.. code-block:: bash

   dps contact -s asyn.tpr -f asyn.xtc -n asyn.ndx -o contact.xvg

Example: compute density profile along the z-axis:

.. code-block:: bash

   dps density -s asyn.tpr -f asyn.xtc -n asyn.ndx --axis z -o rho.xvg


Complete Example Workflow
-------------------------

Putting everything together:

.. code-block:: bash

   # 1. Single chain
   dps pdb2dps -f asyn.pdb -op asyn -on asyn -oc asyn

   # 2. Multi-chain system
   dps genmesh -f asyn.pdb -mesh 5 5 5 -n 125 -p asyn.top -o system.pdb

   # 3. Generate tpr
   dps grompp -m md.mdp -f system.pdb -p system.top -o asyn.tpr

   # 4. Run MD
   dps mdrun -s asyn.tpr -o asyn

   # 5. Analysis
   dps contact -s asyn.tpr -f asyn.xtc -n asyn.ndx -o contact.xvg


Troubleshooting
---------------

Common issues (summarized from user guidance on pp. 31–33):

- **Command not found**  
  Ensure ``dps`` is added to your ``$PATH``.

- **Missing topology files**  
  Check that ``.itp`` and ``.top`` files are correctly generated in earlier steps.

- **MDAnalysis cannot load trajectory**  
  Use ``dps check`` to diagnose ``tpr`` / ``xtc`` issues.

- **Incorrect box size after genmesh**  
  Use ``dps editconf`` to adjust simulation boundaries.


Summary
-------

You have now completed your first full DROPPS simulation, following the exact
pipeline recommended by the official documentation slides.  
The design philosophy, commands, and workflow mirror GROMACS but are optimized
for multi-chain HPS coarse-grained simulations.

Next steps:

- Learn advanced ``mdp`` parameters
- Enable elastic restraints (``dps genelastic``)
- Add angle potentials (``dps addangle``)
- Write custom analysis scripts using the trajectory API