DoMD (ChemFAST) Documentation

DoMD is a general-purpose platform designed for molecular dynamics simulations. ChemFAST (Chemical-Friendly Automated Simulation Toolkit) is a specialized toolkit within DoMD focused on high-throughput modeling and simulation.

ChemFAST functions as a “chemical compiler,” translating high-level chemical descriptions (SMILES/SMARTS) directly into simulation-ready all-atom models, enabling automated construction of complex polymer and biological systems.

Installation

Quick installation for the release

If you prefer the most straightforward setup without manually downloading databases, we highly recommend using our latest release.

First, download the latest version of the DoMD.zip file from our GitHub Releases page. Unzip the archive, navigate into the extracted directory, and run the following commands to set up the environment automatically:

# 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

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

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:
```
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.
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. 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:

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.

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

Download Link: Google Drive

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.

The GitHub Release Assets

If you prefer to download our latest releases from the GitHub Releases page, 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.

Usage Examples & Testing

Navigate to the polyimide example directory:

$ cd <path-to-the-examples>/pi

1. End-to-End Workflow

Run the main script to process a pre-equilibrated Coarse-Grained (CG) configuration:

$ python polyimides.py

Outputs:

chemfast.gro: The back-mapped All-Atom (AA) conformation.
chemfast.top: The GROMACS-compatible force field and topology file.
out_chemfast.xml: The PyGAMD xml input.

Purpose: These files are ready for immediate use in atomistic simulations using GROMACS.

2. Step-by-Step Module Testing

We also provide individual tests for specific S-CGFG functions to demonstrate the underlying workflow:

CG Topology Generation
```
$ python cg.py
```
Generates an initial CG configuration (e.g., linear chains) and force field parameters based on HSP (Hansen Solubility Parameters) predictions. This is typically used for pre-equilibration or reaction runs. (Note: This step is optional as a pre-equilibrated configuration is already provided).
- Output: out_chemfast_cg.xml file for PyGAMD, and cg_params.txt as CG forcefield parameters.
CG Parameterization
```
$ python cg_params.py
```
Generates CG simulation force field parameters only from specific monomers and reaction templates.
- Output: cg_parameters.txt
Back-mapping (CG to FG)
```
$ python fg.py
```
Tests the Coarse-Grained to Fine-Grained (AA) conversion.
- Outputs: AA conformations (stored in the aa_confs/ folder) and topology metadata (meta_aa_top.pkl).
Force Field Parameterization
```
$ python ff.py
```
Performs force field parameterization by reading meta_aa_top.pkl.
- Output: meta_ffs.pkl
Final Assembly
```
$ python output.py
```
Assembles the AA conformations and force field data into standard GROMACS input formats.
- Outputs: Final .gro, .top and .xml (for PyGAMD) files.

Documentation

Manual:

Tutorials: