Installation Guide
==================

This page provides detailed instructions for installing **DROPPS**
(Distributed Rapid Operation Platform for Phase-separation Simulations).
DROPPS is implemented in Python and uses **OpenMM**, **numpy**, **gsd**,
and **MDAnalysis** as its computational backend.

Installation consists of the following steps:

1. Preparing a Python environment
2. Installing required dependencies
3. Installing DROPPS from source
4. Verifying the installation

DROPPS requires **Python 3.10+**, **CUDA (optional)**, and a working
compiler toolchain if OpenMM/GSD are compiled from source.

Quick start
-------------

**DROPPS** is distributed using python wheals package. It is recommended
to install DROPPS using a conda virtual environment by the following
very simple commands.

On Linux (preferably CentOS Stream 7/8/9) or MacOS (preferably M1/M2/M3/M4 Mac)
without GPU support or with OpenCL Support

.. code-block:: bash

    conda create -n DROPPS python=3.12.11
    conda activate DROPPS
    pip install dropps-0.2.0-py3-none-any.whl

On high-performance Computing Cluster with GPU Support

.. code-block:: bash
   
    conda create -n DROPPS python=3.12
    conda install -c conda-forge openmm cudatoolkit
    pip install dropps-0.2.0-py3-none-any.whl

Manual installation
-------------------

Prerequisites
-------------

Before installing DROPPS, ensure you have the following dependencies:

- Python 3.10 or newer
- pip ≥ 22.0
- openMM ≥ 8.1
- OpenCL toolkit (optional, for GPU acceleration on AMD cards or Apple silicons)
- NVIDIA CUDA toolkit (optional, for GPU acceleration)

On Linux (Debian/Ubuntu):

.. code-block:: bash

   sudo apt update
   sudo apt install -y build-essential cmake git python3-dev python3-venv


Creating a Python Environment
-----------------------------

It is recommended to install DROPPS inside a dedicated conda environment:

.. code-block:: bash

   conda create -n dropps python=3.12 -y
   conda activate dropps

Or using ``venv``:

.. code-block:: bash

   python3 -m venv dropps-env
   source dropps-env/bin/activate


Installing Dependencies
-----------------------

DROPPS uses the following libraries:

- OpenMM (MD engine)
- GSD (If gsd file support is enabled)
- MDAnalysis (trajectory manipulation)
- numpy, scipy, h5py, tqdm

Install OpenMM:

.. code-block:: bash

   conda install -c conda-forge openmm

Install GSD:

.. code-block:: bash

   conda install -c conda-forge gsd

Install MDAnalysis:

.. code-block:: bash

   pip install MDAnalysis

Install Python utilities:

.. code-block:: bash

   pip install numpy scipy h5py tqdm


Installing DROPPS
-----------------

DROPPS is currently under development and distributed via GitHub.

Clone the repository:

.. code-block:: bash

   git clone https://github.com/tymworld/DROPPS.git
   cd DROPPS

Install using ``pip``:

.. code-block:: bash

   pip install dist/dropps-0.2.0-py3-none-any.whl

Or install in editable (developer) mode:

.. code-block:: bash

   pip install -e dist/dropps-0.2.0-py3-none-any.whl


Configuring GPU Support
-----------------------

DROPPS can run on:

- NVIDIA GPUs (CUDA)
- AMD GPUs / Apple silicons (OpenCL)
- CPU only (OpenMM Reference platform)

To check that OpenMM sees your GPU:

.. code-block:: bash

   python -m openmm.testInstallation

To verify HOOMD GPU backend:

.. code-block:: bash

   python - << EOF
   import hoomd
   print(hoomd.device.GPU())
   EOF


Environment Variables
---------------------

Optional environment variables for performance tuning:

.. code-block:: bash

   export OPENMM_CPU_THREADS=8
   export OMP_NUM_THREADS=8
   export HOOMD_DISABLE_JIT=1


Verifying the Installation
--------------------------

Run the built-in test script:

.. code-block:: bash

   dps -h

Run a simple LLPS simulation example:

.. code-block:: bash

   dps pdb2dps -s FF -r 1 -oc FF -op OC -on OC
   dps genmesh -f FF.pdb -p FF.itp -n 1 -mesh 1 1 1 -oc box -op box
   cp /PATH_TO_DPS/share/template/md.mdp ./
   dps grompp -f box.pdb -p box.top -m md.mdp -o FF.tpr
   dps mdrun -s FF.tpr -o FF 

If the simulation starts successfully, the installation is complete.

Troubleshooting
---------------

**OpenMM CUDA not detected**

- Check CUDA installation
- Ensure correct conda channel priority
- Ensure your GPU is supported by OpenMM

**HOOMD “No GPU detected”**

- Update NVIDIA drivers
- Try installing HOOMD from conda-forge only

**MDAnalysis trajectory loading errors**

- Ensure packages are up-to-date:
  
  .. code-block:: bash

     pip install --upgrade MDAnalysis h5py

If problems persist, please open an issue on the DROPPS GitHub page.


.. note::

   DROPPS is actively developed. Installation instructions may change
   frequently as new modules and plugins are added.