An AI-powered IDE for molecular dynamics (MD) trajectory analysis using cpptraj and large language models with Retrieval-Augmented Generation (RAG).

Type a prompt like "Calculate RMSD of the protein backbone" — CpptrajAI writes the cpptraj script, runs it, and reports the results.

🌐 Live demo: huggingface.co/spaces/hemantn/CpptrajAI

• Features
• Quick Start
• AI Backend Setup
• Uploading Files
• Using the AI Agent
• Script Editor
• Python Editor
• Results & Plots
• 3D Viewer
• Supported Analyses
• Supported File Formats
• Architecture
• Agent Execution
• Docker

git clone https://github.com/nagarh/CpptrajAI.git
cd CpptrajAI

pip install -r requirements.txt

cpptraj must be installed and available on your PATH.

Via conda (recommended):

conda install -c conda-forge ambertools

ambertools includes cpptraj. Requires Python 3.11.

From source:

git clone https://github.com/Amber-MD/cpptraj.git
cd cpptraj && ./configure gnu && make -j4 install

Custom path: If cpptraj is not on your PATH, set the environment variable:

export CPPTRAJ_PATH=/path/to/cpptraj

python server.py

Open your browser at http://localhost:8502

CpptrajAI supports cloud AI providers and local models via Ollama.

Run any model locally using Ollama:

# Install Ollama, then pull a model
ollama pull qwen3:14b

# Start Ollama server
ollama serve

In CpptrajAI Settings:

• Provider → Ollama
• Base URL → http://localhost:11434/v1
• Model → qwen3:14b (or any model you pulled)

Recommended local models: qwen3:14b, qwen3:32b, qwen3:30b-a3b (MoE). These have strong tool-calling support essential for the agentic workflow.

Recommendation: Use Claude Sonnet 4.6 for anything involving PCA, correlation matrices, or free energy. Use Qwen3 locally for quick exploratory analyses.

How to configure any provider:

1. Click ⚙ Settings (top-right of the IDE)
2. Select your provider
3. Paste your API key (not needed for Ollama)
4. Choose a model
5. Click Save

Privacy: API keys are never written to disk or logged. They are held in server memory only for the duration of your session and cleared automatically after 2 hours of inactivity. Use a key with a spending limit when running on shared infrastructure.

Before running any analysis, upload your MD files using the right panel:

1. Topology file — drag and drop or click to upload (.prmtop, .parm7, .psf, .gro, .mol2)
2. Trajectory file(s) — upload one or more trajectory files (.nc, .ncdf, .dcd, .xtc, .trr, .crd)

Once uploaded, the IDE displays:

• Topology filename
• Total atoms, residues
• Protein residues, ligand residues (auto-detected)
• Trajectory file(s) loaded

Test data: Click Load Test Data to load the built-in sample topology and trajectory to try the app without your own files.

• .prmtop, .parm7, .psf, .gro, .mol2 → always topology
• .nc, .ncdf, .dcd, .xtc, .trr, .crd, .mdcrd → always trajectory
• .pdb → auto-detected:
  • If a proper topology (.prmtop etc.) is already loaded → treated as trajectory
  • Otherwise → scanned for multi-MODEL records to determine if trajectory or single structure

The AI Chat tab is the primary interface. Type your analysis request in plain English.

Calculate RMSD of protein backbone over all frames

Plot radius of gyration of the ligand

Calculate the dynamic cross-correlation matrix of the Cα atoms and plot it as a heatmap

Strip water molecules and save a new trajectory

Calculate the radius of gyration of the protein and plot a 2D free energy landscape (PMF) as a function of RMSD vs Rg

1. Your prompt is enriched with file context (topology name, atom/residue counts, ligand info)
2. The AI calls search_cpptraj_docs when it needs exact command syntax from the manual
3. The AI writes a cpptraj script using verified commands and syntax
4. The script is executed automatically
5. Output files are read back and the AI summarizes key results
6. Plots are generated automatically for .dat output files

Click the Stop button (appears while the AI is thinking/running) to cancel mid-stream.

The AI maintains conversation history within your session, so you can ask follow-up questions:

Now do the same analysis but only for residues 50-150

Can you also calculate the dihedral angles for these residues?

The Script tab lets you write cpptraj scripts manually.

• Use the Command Reference (left panel) to look up syntax — click any command to insert it
• Scripts are pre-filled with parm and trajin lines pointing to your uploaded files
• Click Run Script to execute
• The go command is appended automatically if missing

parm protein.prmtop
trajin mdin_prod.nc
strip :WAT
autoimage
rmsd backbone :1-200@CA,C,N,O first out rmsd_backbone.dat
radgyr :203 out ligand_rg.dat mass
go

The Python tab provides an inline Python environment for post-processing output files.

• Output files from cpptraj are available in the working directory
• Use pandas, numpy, matplotlib, scipy, scikit-learn to process and plot results
• Results and plots appear in the output panel

import pandas as pd
import matplotlib.pyplot as plt

df = pd.read_csv("rmsd_backbone.dat", sep=r"\s+", comment="#",
                 names=["frame", "rmsd"])
print(df.describe())
print(f"Mean RMSD: {df['rmsd'].mean():.3f} Å")

After each analysis run, output files appear in the right panel:

• .dat files → automatically plotted as interactive Plotly line charts
• Multiple datasets in a single file → plotted as multi-line chart
• Click any file name to view its raw content
• Click Download to save a file locally

The right panel includes a 3D molecular viewer powered by 3Dmol.js:

• Automatically displays your uploaded topology (.prmtop, .pdb, etc.)
• If a trajectory was processed and a PDB output exists, it can be loaded for frame animation
• Supports standard visualization styles: cartoon, stick, sphere, surface

CpptrajAI supports all cpptraj analyses. Common categories:

CpptrajAI/
├── server.py               # Flask backend — REST API + SSE streaming
├── agent_ide.html          # Single-page frontend — HTML/CSS/JS
├── core/
│   ├── agent.py            # AI agent: tool calling, conversation history, RAG
│   ├── knowledge_base.py   # cpptraj manual RAG (TF-IDF) + command registry
│   ├── llm_backends.py     # Claude / OpenAI / Gemini / Ollama backends
│   └── runner.py           # cpptraj subprocess execution + file management
├── CpptrajManual.pdf       # Source PDF for RAG
├── cpptraj_manual_cache.json  # Pre-parsed PDF chunks (213 chunks)
├── test_data/              # Sample .prmtop and .nc for quick testing
├── Dockerfile              # For HuggingFace Spaces deployment
└── requirements.txt

This section explains exactly how CpptrajAI processes a user prompt from start to finish.

The AI agent has access to the following tools it can call autonomously:

Each run_cpptraj_script call is a fresh cpptraj process — in-memory datasets do not persist between calls. The agent handles this by:

1. Writing every intermediate result to disk with out filename
2. Reloading data in subsequent scripts using readdata filename name datasetname
3. Passing computed results (e.g. eigenvectors from PCA) to Python for post-processing

Example — PCA workflow:

Step 1 → run_cpptraj_script  : compute covariance matrix → write evecs.dat
Step 2 → run_cpptraj_script  : readdata evecs.dat → project trajectory → write pca.dat
Step 3 → run_python_script   : load pca.dat → plot PC1 vs PC2 free energy landscape

1. CpptrajManual.pdf is parsed into 213 chunks at startup (cached to JSON)
2. A TF-IDF index is built over all chunks
3. The AI agent has a search_cpptraj_docs tool it calls on demand when it needs exact command syntax
4. The top-2 most relevant manual chunks are returned to the model
5. Cloud models (Claude, GPT-4o, Gemini) call the tool only when uncertain — local models call it before every script for reliability
6. The AI writes scripts using exact command names from the retrieved documentation

Running an AI agent with tool calls can be expensive if not carefully managed. CpptrajAI applies several techniques to minimise token usage:

Each browser session gets a unique UUID cookie. All state (uploaded files, agent history, working directory, stop events) is stored per-session and automatically cleaned up after 2 hours of inactivity.

docker pull nagarh/cpptraj-ai:latest
docker run -p 8502:8502 nagarh/cpptraj-ai:latest

Open http://localhost:8502

MIT License. See LICENSE for details.

If you use CpptrajAI in your work, please cite:

@software{CpptrajAI,
  title  = {CpptrajAI: AI-Powered IDE for Molecular Dynamics Trajectory Analysis},
  author = {Nagar, Hemant},
  year   = {2025},
  url    = {https://github.com/nagarh/CpptrajAI}
}

Please also cite cpptraj:

Roe, D. R., & Cheatham III, T. E. (2013). PTRAJ and CPPTRAJ: software for processing and analysis of molecular dynamics trajectory data. Journal of Chemical Theory and Computation, 9(7), 3084–3095.

• Author: Hemant Nagar
• Email: hn533621@ohio.edu
• GitHub: github.com/nagarh