README.md

---
title: AmberMDFlow
emoji: 🧬
colorFrom: blue
colorTo: indigo
sdk: docker
app_port: 7860
short_description: Web-based MD pipeline to setup simulation for AMBER
---

# AmberMDFlow

**AmberMDFlow** is a web-based pipeline for preparing structures, setting up molecular dynamics (MD) simulations with the AMBER force field. It integrates structure completion (ESMFold), preparation, force field parameterization, simulation file generation, and PLUMED-based biased MD in a single interface. This is the beta version.

---

## Note
- If you plan to dock ligands and have filled missing residues in the protein chain using ESMFold, you should also energy-minimize the structure.
- The **Fill Missing Residues** option works only for PDB files retrieved from the RCSB database, as it relies on the REMARK 465 records to identify missing residues.
- The public ESMFold API is used to predict protein structures from input sequences, and it supports sequences of up to 400 amino acids.

---

## Features

| Section | Description |
|--------|-------------|
| **Protein Loading** | Upload PDB files or fetch from RCSB PDB; 3D visualization with NGL |
| **Fill Missing Residues** | Detect missing residues (RCSB annotations), complete with ESMFold, optional trimming and energy minimization of predicted structure|
| **Structure Preparation** | Remove water/ions/H; add ACE/NME capping; chain and ligand selection; GAFF/GAFF2 parameterization |
| **Ligand Docking** | AutoDock Vina + Meeko; configurable search box; pose selection and use selected ligand pose to setup MD simulations |
| **Simulation Parameters** | Force fields (ff14SB, ff19SB), water models (TIP3P, SPCE), box size, temperature, pressure |
| **Simulation Steps** | Restrained minimization, minimization, NVT, NPT, production — each with configurable parameters |
| **Generate Files** | AMBER `.in` files, `prmtop`/`inpcrd`, PBS submission scripts |
| **PLUMED** | Collective variables (PLUMED v2.9), `plumed.dat` editor, and simulation file generation with PLUMED |

---

## Requirements for Custom PDB Files

For **custom PDB files** (uploaded or fetched), ensure:

| Requirement | Description |
|-------------|-------------|
| **Chain IDs** | Chain IDs (A,B,C..) must be clearly marked in the PDB file. |
| **Ligands as HETATM** | All ligands must be in **HETATM** records with name and IDs marked (LIG and A). |
| **Standard amino acids** | AmberMDFlow supports **standard amino acids** only. Non-standard residues and residues with PTMs are currently not supported in the pipeline. |

For RCSB structures, the pipeline parses the header and HETATM as provided; for your own PDBs, apply the above conventions.

---

## Quick Start

Try AmberMDFlow instantly on Hugging Face Spaces (no installation required):

**[https://huggingface.co/spaces/hemantn/AmberMDFlow](https://huggingface.co/spaces/hemantn/AmberMDFlow)**

---

## Installation

### Prerequisites

AmberMDFlow requires scientific packages that are only available via **conda** (not PyPI). You must install these first:

| Package | Purpose |
|---------|---------|
| `ambertools` | AMBER MD tools (tleap, antechamber, sander) |
| `pymol-open-source` | Structure visualization and editing |
| `autodock-vina` | AutoDock Vina 1.1.2 molecular docking (from bioconda) |
| `openbabel` | Molecule format conversion |
| `rdkit` | Cheminformatics toolkit |
| `gemmi` | Structure file parsing (required by Meeko) |

---

### Option 1: pip install (recommended)

```bash
# Step 1: Create conda environment with required tools
conda create -n ambermdflow python=3.11 -y
conda activate ambermdflow

# Step 2: Install conda-only dependencies
conda install -c conda-forge -c bioconda ambertools pymol-open-source autodock-vina openbabel rdkit gemmi -y

# Step 3: Install AmberMDFlow from Test PyPI
pip install --extra-index-url https://test.pypi.org/simple/ ambermdflow

# Step 4: Run the web app
ambermdflow
```

Open your browser at **http://localhost:7860**

---

### Option 2: Docker (no conda/pip needed)
**build from source:**
```bash
git clone https://github.com/nagarh/AmberMDFlow.git
cd AmberMDFlow
docker build -t ambermdflow .
docker run -p 7860:7860 ambermdflow
```

Open your browser at **http://localhost:7860**

---

### Troubleshooting

| Issue | Solution |
|-------|----------|
| `ModuleNotFoundError: No module named 'gemmi'` | Run: `conda install -c conda-forge gemmi` |
| `vina: command not found` | Run: `conda install -c conda-forge vina` |
| Port 7860 already in use | Kill the process or edit `start_web_server.py` to use a different port |


---

## Usage

### 1. Protein Loading

- **Upload**: Drag-and-drop or choose a `.pdb` file.
- **Fetch**: Enter a 4-character PDB ID (e.g. `1HPV`) to download from RCSB.

After loading, the **Protein Preview** shows: structure ID, atom count, chains, residues, water, ions, ligands, and HETATM count. Use the 3D viewer to inspect the structure.

---

### 2. Fill Missing Residues

- Click **Analyze Missing Residues** to detect gaps from RCSB metadata.
- **Select chains** to complete with ESMFold.
- **Trim residues** (optional): remove residues from N- or C-terminal edges; internal loops are always filled by ESMFold.
- **Energy minimization** (optional): if you enable ESMFold completion, you can minimize selected chains to resolve clashes before docking. Recommended if receptor preparation (Meeko) fails later.
- **Build Completed Structure** to run ESMFold and (if requested) minimization. Use **Preview Completed Structure** and **View Superimposed Structures** to compare original and completed chains.

> If you use ESMFold in this workflow, please cite [ESM Atlas](https://esmatlas.com/about).

---

### 3. Structure Preparation

- **Remove**: Water, ions, and hydrogens (options are pre-configured).
- **Add capping**: ACE (N-terminal) and NME (C-terminal).
- **Chains**: Select which protein chains to keep for force field generation.
- **Ligands**:
  - **Preserve ligands** to keep them in the structure.
  - **Select ligands to preserve** (e.g. `GOL-A-1`, `LIZ-A`). Unselected ligands are dropped.
  - **Create separate ligand file** to export selected ligand(s) to a PDB.
  - **Protonate** ligand using Open Babel.

Click **Prepare Structure**. The status panel reports original vs prepared atom counts, removed components, added capping, and preserved ligands. Use **View Prepared Structure** and **Download Prepared PDB** as needed.

**Ligand Docking** (nested in this tab):

- Select ligands to dock.
- Set the **search space** (center and size in X, Y, Z) with live 3D visualization.
- **Run Docking** (AutoDock Vina + Meeko). Progress and logs are shown in the docking panel.
- **Select poses** per ligand and **Use selected pose** to write the chosen pose into the structure for AMBER. You can switch modes (e.g. 1–9) and jump by clicking the mode labels.

---

### 4. Simulation Parameters

- **Force field**: ff14SB or ff19SB.
- **Water model**: TIP3P or SPCE.
- **Box size** (Å): padding for solvation.
- **Add ions**: to neutralize (and optionally reach a salt concentration).
- **Temperature** and **Pressure** (e.g. 300 K, 1 bar).
- **Time step** and **Cutoff** for non-bonded interactions.

If ligands were preserved, **Ligand force field** (GAFF/GAFF2) is configured here; net charge is computed before `antechamber` runs.

---

### 5. Simulation Steps

Enable/disable and set parameters for:

- **Restrained minimization** (steps, force constant)
- **Minimization** (steps, cutoff)
- **NVT heating** (steps, temperature)
- **NPT equilibration** (steps, temperature, pressure)
- **Production** (steps, temperature, pressure)

---

### 6. Generate Files

- **Generate All Files** to create AMBER inputs (`min_restrained.in`, `min.in`, `HeatNPT.in`, `mdin_equi.in`, `mdin_prod.in`), `tleap` scripts, `submit_job.pbs`, and (after `tleap`) `prmtop`/`inpcrd`.
- **Preview Files** to open and **edit** each file (e.g. `min.in`, `submit_job.pbs`) and **Save**; changes are written to the output directory.
- **Preview Solvated Protein** / **Download Solvated Protein** to inspect and download the solvated system.

For **PLUMED-based runs**, go to the **PLUMED** tab to configure CVs and `plumed.dat`, then use **Generate simulation files** there to produce inputs that include PLUMED.

---

### 7. PLUMED

- **Collective Variables**: search and select CVs from the PLUMED v2.9 set; view docs and add/edit lines in `plumed.dat`.
- **Custom PLUMED**: edit `plumed.dat` directly.
- **Generate simulation files**: create AMBER + PLUMED input files. Generated files can be **previewed, edited, and saved** as in the main **Generate Files** tab.

> PLUMED citation: [plumed.org/cite](https://www.plumed.org/cite).

---

## Pipeline Overview

```
Protein Loading (upload/fetch)
        ↓
Fill Missing Residues (detect → ESMFold → optional trim & minimize)
        ↓
Structure Preparation (clean, cap, chains, ligands) → optional Docking (Vina, select pose)
        ↓
Simulation Parameters (FF, water, box, T, P, etc.)
        ↓
Simulation Steps (min, NVT, NPT, prod)
        ↓
Generate Files (AMBER .in, tleap, prmtop/inpcrd, PBS)
        ↓
[Optional] PLUMED (CVs, plumed.dat, generate PLUMED-enabled files)
```

---

## Output Layout

Generated files are written under `output/` (or the path set in the app), for example:

- `0_original_input.pdb` — raw input
- `1_protein_no_hydrogens.pdb` — cleaned, capped, chain/ligand selection applied
- `2_protein_with_caps.pdb`, `tleap_ready.pdb` — intermediates
- `4_ligands_corrected_*.pdb` — prepared ligands
- `protein.prmtop`, `protein.inpcrd` — after `tleap`
- `min_restrained.in`, `min.in`, `HeatNPT.in`, `mdin_equi.in`, `mdin_prod.in`, `submit_job.pbs`
- `output/docking/` — receptor, ligands, Vina configs, poses, logs
- `plumed.dat` — when using PLUMED

---

## Multi-user deployment (e.g. Hugging Face Spaces)

When multiple users use the app at the same time (e.g. on Hugging Face Spaces), each user gets an **isolated output folder** so one user’s files are not overwritten by another’s. The app assigns a session ID when the page loads; all API requests send this ID and generated files are stored under `output/<session_id>/`. No configuration is required—this works automatically in multi-user and single-user setups.

---

## Dependencies

| Category | Tools / libraries |
|----------|-------------------|
| **Python** | Flask, Flask-CORS, BioPython, NumPy, Pandas, Matplotlib, Seaborn, MDAnalysis, Requests, RDKit, SciPy |
| **AMBER** | AMBER Tools (tleap, antechamber, sander, ambpdb, etc.) |
| **Docking** | Meeko (`mk_prepare_ligand`, `mk_prepare_receptor`), AutoDock Vina, Open Babel |
| **Visualization** | PyMOL (scripted for H removal, structure editing), NGL (in-browser 3D) |
| **Structure completion** | ESMFold (via API or local, depending on deployment) |

---

## Project Structure

```
AmberMDFlow/
├── start_web_server.py      # Entry point
├── html/
│   ├── index.html           # Main UI
│   └── plumed.html          # PLUMED-focused view (if used)
├── css/
│   ├── styles.css
│   └── plumed.css
├── js/
│   ├── script.js            # Main frontend logic
│   ├── plumed.js            # PLUMED + docking UI
│   └── plumed_cv_docs.js    # CV documentation
├── python/
│   ├── app.py               # Flask backend, API, file generation
│   ├── structure_preparation.py
│   ├── add_caps.py          # ACE/NME capping
│   ├── Fill_missing_residues.py  # ESMFold, trimming, minimization
│   ├── docking.py           # Docking helpers
│   └── docking_utils.py
├── output/                  # Generated files (gitignored in dev)
├── Dockerfile
└── README.md
```

---

## Citation

If you use AmberMDFlow in your work, please cite:

```bibtex
@software{AmberMDFlow,
  title = {AmberMDFlow: Molecular Dynamics and Docking Pipeline},
  author = {Nagar, Hemant},
  year = {2025},
  url = {https://github.com/nagarh/AmberMDFlow}
```

**Related software to cite when used:**

- **AMBER**: [ambermd.org](https://ambermd.org)
- **PLUMED**: [plumed.org/cite](https://www.plumed.org/cite)
- **ESMFold / ESM Atlas**: [esmatlas.com/about](https://esmatlas.com/about)
- **AutoDock Vina**: [autodock-vina/cite](https://autodock-vina.readthedocs.io/en/latest/citations.html)
- **Meeko**: [github.com/forlilab/Meeko](https://github.com/forlilab/Meeko)
- **MDAnalysis**: [mdanalysis/cite](https://www.mdanalysis.org/pages/citations/)
- **NGL Viewer**: [nglviewer/cite](https://doi.org/10.1093/bioinformatics/bty419)
- **PyMOL**: [pymol/cite](https://www.pymol.org/support.html) 

---

## Acknowledgments

- **Mohd Ibrahim** (Technical University of Munich) for the protein capping logic (`add_caps.py`).

---

## License

MIT License. See `LICENSE` for details.

---

## Contact

- **Author**: Hemant Nagar  
- **Email**: hn533621@ohio.edu