Skip to content

nagarh/AmberMDFlow

BranchesTags

Repository files navigation

AmberMDFlow Logo

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

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)

# 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:

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.

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.

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:

@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:

Acknowledgments

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

License

MIT License. See LICENSE for details.

Contact

About

AmberMDFlow — Automated AMBER Simulation Setup Web UI

Resources

Readme

License

MIT license
Activity

Stars

6 stars

Watchers

1 watching

Forks

3 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages