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

Quick installation for the release
----------------------------------
Please download the lastest version of the ``DoMD.zip`` file at `Github Release <https://github.com/DoMD-toolkit/DoMD/releases>`_. Release includes the large database files ``opls.db``, which are required for the force field assignment. After downloading and unzipping the release zip file, you can set up the environment and test the installation with the following commands:


.. code-block:: bash

   # Download and unzip the release zip file
   $ cd <path-to-domd>
   $ conda env create -f environment.yml
   $ conda activate domd-toolkit
   $ python -c 'from domd_tools import *; print("Success install domd.")'

Step-by-step installation from repo
-----------------------------------
This is the installation process if you want to install from the git repository, which is recommended for developers or users who want to use the latest features. For users who just want to use the stable version, we recommend downloading the release version as described above.

We recommend using ``conda`` to manage your environment. Follow the steps below to set up DoMD:

**1. Create and Activate the Conda Environment**

.. code-block:: bash

   conda create -n domd-toolkit -c conda-forge python==3.12 nomkl numpy rdkit=2025.03.6 openbabel numba networkx pandas scipy jupyter scikit-learn matplotlib MDAnalysis
   conda activate domd-toolkit

**2. Install PyTorch and Additional Dependencies**

.. code-block:: bash

   pip3 install torch torchvision --index-url https://download.pytorch.org/whl/cpu
   pip3 install torch_geometric pdbreader

**3. Download the Toolkit**

You can obtain the DoMD toolkit via GitHub or by downloading our official release. **Please choose one of the following options:**

* **Option A: Clone from GitHub (Requires manual database download)**

  1. Clone the repository:

     .. code-block:: bash

        git clone https://github.com/DoMD-toolkit/DoMD.git

  2. **Important:** Download the required forcefield database ``opls.db`` (large file) from the `Google Drive Link <https://drive.google.com/file/d/18KM3CQI2Wrcs8jutCQxGTcVyc0St_Aj5/view>`_.

  3. Move ``opls.db`` into the following directory: ``DoMD/domd_forcefield/oplsaa/resources/opls.db``

* **Option B: Download the Release .zip (Recommended)**

  Download the latest ``.zip`` file from the `Releases page <https://github.com/DoMD-toolkit/DoMD/releases>`_. The ``opls.db`` file is already included in the compressed package, so no extra downloads are necessary. Unzip the file before proceeding.

**4. Install DoMD**

Navigate to the root directory of the project (where ``setup.py`` is located) and install it in editable mode:

.. code-block:: bash

   cd DoMD
   pip install -e .

Database Setup (Large Files)
----------------------------

**Important:** DoMD requires specific large database files for force field parameterization. These are not included in the git repository due to size limits.

**Download Link:** `Google Drive <https://drive.google.com/file/d/18KM3CQI2Wrcs8jutCQxGTcVyc0St_Aj5/view>`_

* ``domd_database/forcefield/oplsaa/data/ligpargen/AllData.pkl``: **This file is the OPLS-AA force field database, for training the force field model, this file is NOT NEEDED for the program.**
* ``domd_forcefield/oplsaa/resources/opls.db``: **This file is required for force field assignment.**

.. code-block:: text

   DoMD/
   └── domd_forcefield/
       └── oplsaa/
           └── resources/
               └──opls.db  <-- Required for parameterization


.. note::
    If you download the release version, the ``opls.db`` file is already included in the release package, so you don't need to download it separately.

The GitHub Release Assets
-------------------------

If you prefer to download our latest releases from the `GitHub Releases page <https://github.com/DoMD-toolkit/DoMD/releases>`_, here is a guide to the available files. *(Note: The release packages already include the ``opls.db`` file, so no Google Drive download is needed).*

* **``DoMD.zip`` (Recommended)**: The primary, standalone software package. It contains the complete source code, the environment configuration file (``environment.yml``), and the required ``opls.db`` database. **This is the only file you need to run the software.**
* **Example Archives**: We provide several advanced tutorial systems separately to keep the main software package lightweight. You can download and extract these into your ``examples/`` directory as needed:

  * ``aunps.zip``: Gold nanoparticle system.
  * ``core_shell_nps.zip``: Core-shell nanoparticle system.
  * ``custom_forcefield_gaff.zip``: Example demonstrating custom GAFF integration.
  * ``pi.zip``: Polyimide example.
  * ``spes_brush.zip``: Solid Polymer Electrolyte (SPE) brush system.
  * ``spes_network.zip``: Solid Polymer Electrolyte (SPE) cross-linked network system.