Simulation preprocessor
=======================

This command should be named as dpspp (Dropps preprocessor). But the developer
is a huge fan of gromacs so he uses grompp (Gromacs preprocessor) instead.

**Bite Me.**

The ``grompp`` tool in DROPPS is a **system preprocessor** that combines:

- structural coordinates (PDB)  
- molecular topology files (ITP)  
- simulation parameters (MDP)  

into a single **TPR runtime file**, which is later consumed by ``mdrun`` to
perform the actual molecular dynamics simulation.

This is analogous to GROMACS ``grompp``, but generates a **pickled Python
runtime object** containing everything required by the DROPPS MD engine.

Implemented in ``grompp.py``.


Overview
--------

``dps grompp`` performs 4 major tasks:

1. Reads the initial **structure** from a PDB file  
2. Reads and aggregates **all molecular topologies (ITP)**  
3. Reads the **parameter (MDP)** file  
4. Calls the internal constructor:

   .. code-block:: python

      mdsystem, mdtopology, positions, ITP_list = build_system(...)

   to build a complete simulation state.

Finally, it packs everything into a dictionary and **pickles** the object to a
file with extension ``.tpr`` (DROPPS-TPR format).

The output file is later passed to:

.. code-block:: bash

   dps mdrun -s state.tpr

to perform time integration.


Usage
-----

Minimal example:

.. code-block:: bash

   dps grompp \
       -f conf.pdb \
       -p system.itp \
       -m run.mdp \
       -o state.tpr

If ``-o`` does not end with ``.tpr``, it will be appended automatically.


Arguments
---------

Required
--------

.. option:: -f, --structure FILE

   PDB structure file containing the initial configuration of your system.
   Internally processed by:

   .. code-block:: python

      read_pdb()
      phrase_pdb_atoms()

.. option:: -p, --topology FILE

   The main topology file (GROMACS-style ``.itp``), usually including other
   ITPs via ``#include`` directives.

.. option:: -m, --parameter FILE

   MDP-style parameter file.  
   Interpreted by:

   .. code-block:: python

      getparameter()

   and passed into ``build_system``.

.. option:: -o, --output FILE

   Output filename for the TPR runtime file.  
   ``.tpr`` extension is added if missing.


What `grompp` Generates
-----------------------

The output file is a Python pickle containing all runtime data required by
``mdrun``.

Structure of the pickled dictionary:

.. code-block:: python

   runtime_files = {
       "parameters": parameters,
       "mdsystem": mdsystem,
       "mdtopology": mdtopology,
       "positions": positions,
       "pdb_raw": PDB_raw,
       "ITP_list": ITP_Topology_list
   }

Where:

- **parameters** — parsed mdp dictionary  
- **mdsystem** — instantiated OpenMM system  
- **mdtopology** — DROPPS molecular-topology object  
- **positions** — initial coordinates (OpenMM array)  
- **pdb_raw** — raw PDB atom list + box vectors  
- **ITP_list** — list of all parsed ITP topologies  


Program Workflow
----------------

(1) **Prepare output name**

.. code-block:: python

   if not output.endswith(".tpr"):
       output_tpr = output + ".tpr"

(2) **Load parameters**

.. code-block:: python

   parameters = getparameter(args.parameter)

(3) **Build system**

Calls DROPPS system builder:

.. code-block:: python

   mdsystem, mdtopology, positions, ITP_list = \
       build_system(args.structure, args.topology, parameters)

This step:

- builds OpenMM forces  
- applies forcefield parameters  
- resolves #includes inside ITP files  
- builds bonded & non-bonded interactions  
- extracts initial coordinates  

(4) **Load raw PDB data**

.. code-block:: python

   atoms_pdb_raw, box_raw = read_pdb(args.structure)
   PDB_raw = phrase_pdb_atoms(atoms_pdb_raw, box_raw)

Stored for restart and trajectory writing later.

(5) **Package everything**

.. code-block:: python

   runtime_files = {...}

(6) **Pickle to `.tpr`**

.. code-block:: python

   with open(output_tpr, "wb") as f:
       pickle.dump(runtime_files, f)

Print:

::

   ## Write run time files to state.tpr.


Example
-------

Typical workflow:

.. code-block:: bash

   dps genmesh -oc init.pdb -op init.top  # build multi-chain system
   dps grompp  -f init.pdb -p init.top -m eq.mdp -o eq.tpr
   dps mdrun   -s eq.tpr                  # run MD


Error Messages
--------------

Because ``grompp`` relies heavily on file parsing, errors typically arise from:

**Invalid ITP file**

::

   ERROR: Cannot open topology file ...

**Invalid PDB file**

::

   ERROR: Cannot open structure file ...

**Parameter file missing fields**  
Errors thrown inside ``getparameter()``.

**Internal construction errors**  
From ``build_system`` if the topology and structure do not match.


Summary
-------

``dps grompp`` is the **preparation engine** of the DROPPS simulation pipeline.
It:

- loads structures, topologies, and parameters  
- builds a complete OpenMM system  
- collects all metadata  
- writes a unified DROPPS-TPR file (Python pickle)  

which is required by the ``dps mdrun`` integrator.

``grompp`` is therefore the first step in every DROPPS simulation workflow,
analogous to ``gmx grompp`` in the GROMACS ecosystem.