Input Files
===========

DROPPS uses a structured set of input files that work together to define a
complete coarse-grained simulation system.  
This page explains the four most important file types used in DROPPS:

1. PDB files  (coordinates)
2. MDP files  (MD parameters)
3. ITP files  (single-chain topology)
4. TOP files  (system-level topology)

These files are ultimately combined using ``dps grompp`` to produce a DROPPS
``.tpr`` file.

Each section below describes the purpose, format, and role of each file.


PDB File (Structure)
--------------------

PDB files store **coordinates and chain information** for coarse-grained
simulations. They are used at multiple points in the workflow:

- Generated by ``dps pdb2dps`` for single-chain CG structures.  
- Used by ``dps genmesh`` to assemble multichain systems.  
- Passed to ``dps grompp`` as the final coordinate input.

A typical DROPPS CG PDB structure contains:

- Atom names representing **coarse-grained beads**  
- Residue names matching HPS (or other CG) residue labels  
- Chain IDs for multi-chain systems  
- ONE bead per residue (for HPS-type FFs)

Example (CG PDB snippet):

.. code-block:: text

   ATOM      1   ALA A   1      12.541  15.223  10.991
   ATOM      2   PRO A   2      13.114  16.102  11.887
   ATOM      3   LYS A   3      14.001  16.445  12.901

Important notes:

- Coordinates may be scaled or centered using ``dps editconf``.  
- Multi-chain PDBs generated by ``genmesh`` contain possibly hundreds of chains
  arranged on a regular lattice.


MDP File (Simulation Parameters)
--------------------------------

MDP files define the **simulation control parameters**, analogous to GROMACS
``.mdp`` files, but interpreted by DROPPS to generate an OpenMM integrator
configuration .

An MDP file contains:

- simulation time settings  
- integrator type  
- timestep  
- thermostat parameters  
- cutoffs and neighbor lists  
- trajectories and energy output frequency  

Example MDP snippet:

.. code-block:: text

   integrator      = langevin
   dt              = 0.01
   nsteps          = 5000000
   tau_t           = 1.0
   temperature     = 310
   cutoff-scheme   = hps
   output-frequency = 10000

Notes:

- DROPPS parses the MDP using its internal ``mdp_reader`` module.  
- Not all GROMACS keywords are supported; DROPPS supports LLPS-relevant
  parameters specifically.  
- The MDP file is combined with PDB + ITP + TOP during ``grompp`` to form the
  ``.tpr``.

**Please refer to Reference Manual for detailed mdp setups.**


ITP File (Single-Chain Topology)
--------------------------------

ITP files define the **topology of a single coarse-grained chain**.  
These files are created by ``dps pdb2dps`` and contain:

- atom (bead) types  
- masses  
- charges  
- sigma / epsilon  
- bonded terms (bonds, angles, optionally dihedrals)  
- residue labels  
- mapping from residue → bead name → FF parameters  

A typical DROPPS ITP file may contain:

.. code-block:: text

   [ atoms ]
   ; id  type   resnr  resid  charge  mass
     1   ALA      1     ALA     0.0    100
     2   PRO      2     PRO     0.0    100
     3   LYS      3     LYS     1.0    110

   [ bonds ]
   1  2  1
   2  3  1

   [ angles ]
   1  2  3  1

Key characteristics:

- **Residue parameters come directly from the CG force field**, such as HPS,
  M`HPS`, or your custom FF.  
- Angle terms may be optional depending on FF definition.  
- Users can modify FF parameters programmatically using pydps (page 17).


TOP File (System Topology)
--------------------------

The TOP file describes the **entire multichain system**, including:

- which ITP files are included  
- number of chains  
- system-wide definitions  
- nonbonded parameter includes  
- global simulation topology hierarchy  

A typical TOP file looks like:

.. code-block:: text

   #include "asyn.itp"

   [ system ]
   Alpha-synuclein LLPS system

   [ molecules ]
   asyn   125

This file is generated automatically by ``dps genmesh`` and updated during
``dps grompp``.

Important notes:

- The TOP file acts as the **master topology**.  
- DROPPS topologies resemble GROMACS `.top` files but contain CG-specific
  force-field and system metadata.  
- The final system topology is validated by ``dps check``.


How These Files Work Together
-----------------------------

The four primary input files flow through the simulation pipeline as follows:

1. **pdb2dps**  
   → produces ``*.pdb`` + ``*.itp`` (single-chain)

2. **genmesh**  
   → builds multi-chain ``*.pdb``  
   → generates ``system.top``

3. **grompp**  
   → combines:

      - system.pdb  
      - system.top  
      - md.mdp  
      - all included .itp files  

   → produces ``run.tpr``

4. **mdrun**  
   → runs simulation and generates:

      - ``run.xtc``  
      - ``run.log``  
      - ``run.ndx`` (optional)  

This mirrors the GROMACS workflow but is specialized for LLPS simulations
using CG force fields.


Summary
-------

DROPPS input files form a coherent ecosystem:

- **PDB** — coordinates for single-chain and multi-chain systems  
- **MDP** — simulation parameters  
- **ITP** — single-chain topology describing beads and bonded terms  
- **TOP** — system-level topology linking all chains and FF files  

These files are merged by ``dps grompp`` into a DROPPS-native ``.tpr`` file,
which serves as the input for ``dps mdrun``.