Simulation Workflow
===================

This page provides a complete overview of the DROPPS simulation workflow.  
The workflow is intentionally designed to follow a GROMACS-like structure
, but optimized for large multichain coarse-grained (CG) LLPS simulations.

A typical workflow consists of five major stages:

1. Generate a CG structure and single-chain topology (``pdb2dps``)
2. Build a multichain simulation box (``genmesh``)
3. Prepare the simulation input (``grompp``)
4. Run the MD simulation (``mdrun``)
5. Analyze the trajectory and compute observables (``density``, ``contact``, etc.)


Overview Diagram
----------------

DROPPS workflow consists of:

::

      SEQUENCE / PDB
            ↓
        pdb2dps
            ↓
        genmesh
            ↓
        grompp
            ↓
         mdrun
            ↓
        analysis


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

``pdb2dps`` converts an input sequence or PDB structure into a coarse-grained
representation compatible with the selected force field (HPS, MHPS, custom FF).

Purpose:

- build CG bead coordinates  
- assign FF parameters  
- generate per-chain topology files (`.itp`)  
- detect available FFs
- optional angle/dihedral generation  

Example:

.. code-block:: bash

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

Outputs:

- ``asyn.pdb`` – CG coordinates  
- ``asyn.itp`` – single-chain topology  
- ``asyn-angle.itp`` – angle terms (if present in FF)  


2. Construct a Multichain System (genmesh)
------------------------------------------

Large LLPS systems typically require tens to thousands of chains. DROPPS provides
a mesh-based packing system to efficiently generate these configurations.

Example:

.. code-block:: bash

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

This command:

- replicates the chain on a 5×5×5 cubic mesh  
- generates a `system.pdb` with 125 chains  
- writes `system.top` containing the system-level topology  

This step eliminates the need for GROMACS’s ``insert-molecules`` and ensures that
multichain packing is reproducible across systems.


3. Prepare the Simulation Input (grompp)
----------------------------------------

The ``grompp`` command merges all required input data (PDB, ITP, TOP, MDP) into
DROPPS’s MD input file (``.tpr``).

Inputs:

- ``system.pdb`` – multichain coordinates  
- ``system.top`` – topology including all molecules  
- ``md.mdp`` – MD parameters  
- ``*.itp`` – chain-level topologies

Example:

.. code-block:: bash

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

Outputs:

- ``run.tpr`` – complete simulation input  
- internal validation and warnings (box size, FF consistency, etc.)

**Important:**  
DROPPS `.tpr` is not compatible with GROMACS `.tpr`.  

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

This is the execution stage where the MD engine (OpenMM) performs the actual
numerical integration.

Example:

.. code-block:: bash

   dps mdrun -s run.tpr -o run

Produces:

- ``run.xtc`` – trajectory  
- ``run.log`` – simulation log  
- ``run.edr`` – energy-like output  
- periodic progress output via rich console logging  


5. Indexing and Selection (make_ndx)
------------------------------------

Many analyses require custom index groups.  
DROPPS includes a GROMACS-like interactive index builder with LLPS-optimized
extensions such as ``splitch``.

Example:

.. code-block:: bash

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

Useful commands:

- ``splitch`` – automatically create per-chain groups (critical for LLPS)  
- ``abbr`` – select residues by abbreviation (A, R, G, etc.)  
- ``chain A`` – select chain by ID  
- ``res 10`` – select residue by number  
- ``q`` – save and exit  


6. Trajectory Analysis
----------------------

DROPPS includes a suite of high-performance analysis tools for multichain CG
trajectories.

Available commands (updating):

- ``dps density`` – density profile along an axis  
- ``dps gyrate`` – radius of gyration  
- ``dps contact`` – contact number / contact map  
- ``dps cmap`` – correlation matrix  
- ``dps idist`` – intra-chain distance  
- ``dps odist`` – inter-chain distance  
- ``dps angle`` – angle distributions  
- ``dps check`` – validate tpr/top/xtc/ndx integrity  

Example:

.. code-block:: bash

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

This example computes residue-level or chain-level contact patterns, a common
metric for LLPS studies.


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

Below is a minimal working example using asyn.pdb:

.. code-block:: bash

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

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

   # 3. Build the simulation input
   dps grompp -m md.mdp -f system.pdb -p system.top -o run.tpr

   # 4. Run molecular dynamics
   dps mdrun -s run.tpr -o run

   # 5. Generate index file (optional)
   dps make_ndx -f run.tpr -o run.ndx

   # 6. Perform analysis
   dps contact -s run.tpr -f run.xtc -n run.ndx -o contact.xvg


Workflow Philosophy
-------------------

DROPPS is designed around:

- **unification** — one system for all steps  
- **generalization** — compatible with multiple CG FFs  
- **GROMACS interface** — easy transition for experienced MD users  
- **usability** — minimal scripting required  
- **extensibility** — easily add new FFs, commands, and analysis modules  

This enables reproducible, scalable LLPS simulations without the “per-student  
script zoo” problem.


Summary
-------

The DROPPS workflow consists of:

1. ``pdb2dps`` — create structure + topology  
2. ``genmesh`` — build multichain box  
3. ``grompp`` — assemble simulation input  
4. ``mdrun`` — perform MD integration with OpenMM  
5. ``make_ndx`` — build index groups  
6. analysis tools — compute LLPS observables  

This workflow provides a robust, reproducible, and efficient pipeline for
large-scale coarse-grained biomolecular phase-separation simulations.