FAQ
===

This page collects commonly asked questions about installing, running, and
developing with **DROPPS**.  
DROPPS is under active development, and behaviors may evolve as new modules,
APIs, and analysis tools are added.

General Questions
-----------------

**What is DROPPS?**

DROPPS stands for *Distributed Rapid Operation Platform for Phase-separation
Simulations*.  
It provides a unified command-line interface (``dps``) that wraps system
building, simulation, topology preparation, and trajectory analysis.  
It mirrors the workflow of GROMACS, but is optimized for HPS
coarse-grained simulations.


**Does DROPPS perform molecular dynamics simulations directly?**

No.  

- Molecular dynamics is executed by **OpenMM**  
- Data analysis relies on **MDAnalysis**  
- Trajectory handling can additionally use **MDTraj**

DROPPS organizes and automates these processes through a GROMACS-like command
framework.


Installation
------------

**How do I install DROPPS?**

The program is distributed as a Python wheel. Install with:

.. code-block:: bash

   pip install dropps-0.1.0-py3-none-any.whl

Then place the ``dps`` launcher script in your ``$PATH``:

.. code-block:: bash

   dps help commands


**Do I need a conda environment?**

Strongly recommended.  
DROPPS depends on OpenMM and MDAnalysis packages that are easier to
manage inside isolated environments.

**The command `dps` is not found. What should I do?**

Ensure that the directory containing the ``dps`` script is included in your
``$PATH``.  
Alternatively run it locally:

.. code-block:: bash

   ./dps help

(Although this is not recommended in production setups.)


Simulation Workflow
-------------------

**How do I build the initial topology for a sequence?**

Use ``dps pdb2dps``.  
It generates structure (``.pdb``), single-chain topology (``.itp``), and angle
terms if needed.  


**How do I create a large multi-chain system?**

Use ``dps genmesh``.

Example:

.. code-block:: bash

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

This is DROPPS’s replacement for ``gmx insert-molecules``.


**How do I generate the final input file (`.tpr`)?**

Use:

.. code-block:: bash

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

This step merges coordinates, topology, and MD parameters into a single file.


**How do I run the simulation?**

.. code-block:: bash

   dps mdrun -s run.tpr -o run

This produces ``run.xtc``, ``run.log``, and energy-like output.


Indexing and Selection
----------------------

**How do I create index groups?**

Use:

.. code-block:: bash

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

The indexing interface fully mimics GROMACS but adds optimized
commands such as ``splitch`` for efficiently separating thousands of chains.


**Does DROPPS support GROMACS `.ndx` syntax?**

Yes.  
The syntax and file format follow GROMACS exactly.


Trajectory and File Handling
----------------------------

**What is the difference between DROPPS `.tpr` and GROMACS `.tpr`?**

They are *completely different formats*. They cannot be converted or read interchangeably.


**`dps check` reports errors for `.xtc` or `.tpr`. What does it mean?**

The file may be:

- incomplete,  
- corrupted,  
- produced with mismatched topology, or  
- incompatible due to version changes.

``dps check`` verifies the integrity of ``tpr``, ``xtc``, and ``ndx`` and ensures
they can be loaded by MDAnalysis.


**How do I load a trajectory in Python?**

Use the DROPPS trajectory wrapper:

.. code-block:: python

   from dropps.share.trajectory import trajectory_class
   trj = trajectory_class("run.tpr", "run.ndx", "run.xtc")

This wrapper exposes:

- OpenMM topology  
- MDAnalysis Universe  
- ID/chain/residue lookup  
- Frame iteration tools


Force Fields
------------

**How do I use a different HPS force field?**

Place your custom ``.ff`` file in the working directory.  
``dps pdb2dps`` will automatically detect and list all available force fields.


**Can I modify mass, charge, lambda, or sigma?**

Yes.  
DROPPS exposes full programmatic control:

.. code-block:: python

   ff = dps.share.getff("HPS.ff")
   ff.abbr2charge["H"] = 0.5
   dps.fileio.itp_reader.write_itp(ff)


Analysis Tools
--------------

**How do I compute contact numbers?**

.. code-block:: bash

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

This program supports intra-chain, inter-chain, group-wise contact matrices.


**How do I compute density profiles?**

.. code-block:: bash

   dps density -s run.tpr -f run.xtc --axis z -o rho.xvg


**Which analyses are available?**

DROPPS supports, to date,:

- ``density``  
- ``gyrate``  
- ``cmap``  
- ``idist`` / ``odist``  
- ``contact``  
- ``angle``  
- ``check``  


Developer Questions
-------------------

**How do I write a new analysis program?**

Only two functions are required (page 37–38):

1. a function defining command-line arguments  
2. a function executing the calculation

Register your command using:

.. code-block:: python

   from dropps.share.command_class import single_command
   mycmd = single_command("hello", getargs_hello, hello, "description")

Then add it to ``all_commands`` (page 39).


**Can I bundle my analysis program into the official DROPPS package?**

Yes, DROPPS allows extending the command registry.  
Just include the module when constructing ``all_commands``.


Contact Us
----------

In case of technical questions, error reports, or feature requests:

- Provide **your full command line**,  
- **all input files** (``pdb/itp/top/mdp``),  
- **the error message**,  
- and **a short description** of the expected behavior.

Submit your issue through email or your internal project repository.

DROPPS is a non-commercial academic project, so no official customer
service is available — but contributions, suggestions, and bug reports are
welcome.