Overview
========

DROPPS (*Distributed Rapid Operation Platform for Phase-separation Simulations*)
is a unified, GROMACS-style workflow platform for performing large-scale
coarse-grained (CG) simulations of biomolecular liquid–liquid phase separation
(LLPS). The system was designed to solve long-standing issues in the LLPS
simulation community, including workflow fragmentation, force-field
inconsistencies, and a lack of standardized tooling for multichain CG modeling.

DROPPS integrates **OpenMM**, **MDAnalysis**, custom high-efficiency IO layers,
a modular force-field engine, and a GROMACS-inspired command-line interface
(“``dps``”). Its goal is to make CG LLPS simulations as easy and reproducible as
running a typical GROMACS simulation — but with significantly greater flexibility
and model extensibility.


Why DROPPS Exists
-----------------

Traditional CG simulations for LLPS often involve:

- many force fields scattered across many folders  
- per-project ad-hoc scripts  
- duplicated coarse-graining procedures  
- incompatible file formats  
- fragile user-built analysis pipelines  
- impossible reproducibility across research groups

DROPPS solves these issues by:

- providing **one** unified CLI  
- integrating **all** CG workflows into a single platform  
- offering a stable I/O and FF engine  
- providing an extendable command registry  
- offering a Python API for analysis, system building, and FF manipulation


Design Philosophy
-----------------

DROPPS is built around five core principles (pages 6–8):

- **统一 (Unification)** — all workflows follow the same logical structure.  
- **通用 (General-purpose)** — supports any CG model, not only HPS.  
- **兼容 (GROMACS-like interface)** — familiar commands for experienced users.  
- **易用 (Usability)** — reduces the complexity of setting up LLPS simulations.  
- **可扩展 (Extensibility)** — new FFs, new commands, and new analysis modules can be added with minimal effort.

The framework is intentionally non-monolithic. While GROMACS includes its own
MD engine, DROPPS *outsources* the expensive parts of the computation to:

- **OpenMM** → MD engine  
- **MDAnalysis** → trajectory handling  
- **MDTraj / custom readers** → optional readers  


Architecture
------------

DROPPS consists of four major layers:

1. **Command Layer (CMD)**  
   All user-facing commands such as ``pdb2dps``, ``genmesh``, ``grompp``,
   ``mdrun``, ``contact``, ``density``, etc.  
   Registered in ``all_commands``.

2. **pydps Layer**  
   The core Python package implementing structure generation, FF processing,
   topology handling, mesh operations, MD input conversion, and analysis
   routines.

3. **IO & Utilities Layer (fileio / misc)**  
   - Topology reader/writer  
   - PDB/ITP/TOP parsers  
   - MDP parser  
   - Random generators  
   - Logging and text formatting (rich)  
   - High-performance table utilities

4. **Trajectory Layer (OpenMM + MDAnalysis + custom wrappers)**  
   A unified trajectory object exposing:
   - OpenMM topology  
   - MDAnalysis Universe  
   - consistent IDs / chain indices / residue labels  
   - helper methods for fast selection and iteration  

These layers produce a modular yet coherent system.


GROMACS-Style Simulation Workflow
---------------------------------

DROPPS intentionally mirrors the familiar GROMACS workflow (page 34):

===================  ===================
GROMACS              DROPPS
===================  ===================
pdb2gmx              pdb2dps
editconf             editconf
insert-molecules     genmesh
grompp               grompp
mdrun                mdrun
make_ndx             make_ndx
analysis tools       density / contact / cmap / idist / odist / gyrate
===================  ===================

This ensures that experienced GROMACS users can adopt DROPPS with near-zero
learning cost.


Key Features
------------

DROPPS provides the following capabilities:

**Unified workflow**  
A full simulation pipeline that covers:

- PDB/sequence coarse-graining  
- topology assembly  
- system construction (multi-chain mesh packing)  
- MD input generation  
- MD execution  
- trajectory analysis  
- visualization utilities  

**Flexible force-field system**  
Full programmatic access to:

- masses, charges, λ parameters  
- σ and interaction tables  
- bonded / nonbonded terms  
- custom FF loading

**High-performance trajectory handling**  
The custom trajectory wrapper integrates:

- OpenMM topology  
- MDAnalysis coordinates  
- chain/residue indexing  
- per-chain, per-group iteration  

**Extensible command registry**  
Adding a command requires only:

1. argument parser  
2. processing function  
3. registering via ``single_command``  

**Professional data analysis suite**  
Provided analysis commands:

- ``density``  
- ``gyrate``  
- ``cmap``  
- ``idist`` / ``odist``  
- ``contact``  
- ``angle``  
- ``check`` (topology/trajectory validator)

**User mode vs developer mode**  
DROPPS exposes two “modes” of operation:

- **User mode** — simplified commands, preconfigured workflows  
- **Developer mode** — direct access to topology objects, FF tables, trajectory API, etc.


Command Dispatcher System
-------------------------

One of the novel design elements of DROPPS is the command-dispatcher architecture:

.. code-block:: python

   all_commands = {
       "pdb2dps": pdb2dps_cmd,
       "grompp": grompp_cmd,
       "mdrun": mdrun_cmd,
       ...
   }

Users may extend or replace built-in commands by editing ``all_commands`` or by
plugging in custom modules.


File Formats
------------

DROPPS uses file formats analogous to the GROMACS ecosystem:

- **.pdb** — CG coordinate files  
- **.itp** — single-chain topologies  
- **.top** — combined topology after system construction  
- **.mdp** — MD parameter files  
- **.tpr** — DROPPS-specific MD input (not compatible with GROMACS)  
- **.xtc** — compressed trajectory files  
- **.ndx** — selection groups

Important note:  
DROPPS `.tpr` and GROMACS `.tpr` are structurally incompatible. 
They cannot be interconverted.


Target Users
------------

DROPPS is designed for:

- LLPS researchers  
- protein-condensate modelers  
- large-system CG simulation users  
- method developers who need to integrate custom FFs  
- students who need a standardized simulation platform  
- PIs who want reproducible workflows across group members

The platform’s goal is to replace the per-student, per-project “script zoo” with
a unified and professional tool.


Summary
-------

DROPPS provides:

- a unified, GROMACS-inspired interface  
- robust force-field and topology processing  
- an extensible MD pipeline using OpenMM  
- high-performance trajectory tools  
- a rich and extendable analysis suite  

The entire ecosystem is structured to make CG LLPS simulations **repeatable,
maintainable, and shareable**, with minimal user-side scripting and maximal
developer flexibility.