MDSimulationAgent — mdagent

A multi-agent pipeline that drives a GROMACS MD workflow end-to-end from a single natural-language instruction. Ships as:

• mdagent — installable Python CLI + library.
• Three Claude skills (md-run-workflow, md-prep-structure, md-visualize) packaged inside the wheel so they're discoverable from any project after one install.

Install (one-time per machine)

brew install uv                        # macOS — or: curl -LsSf https://astral.sh/uv/install.sh | sh
uv tool install --force git+https://github.com/FidhaNazreen/MDSimulationAgent@v0.1.0
brew install gromacs                   # for any step past prep
mdagent install-skills --user          # → ~/.claude/skills/ (or use --project DIR)

Verify:

mdagent --version           # → mdagent 0.1.0
mdagent doctor --gmx-required
mdagent self-test resources

Use

From any directory:

mdagent run-workflow --runs-root ./runs --pdb-id 1AKI --run-id demo
mdagent inspect      --run-root ./runs/demo

Or just open a Claude Code session and ask:

"Set up lysozyme in water and minimize it."

Claude's md-run-workflow skill routes the request to the right CLI.

Pipeline overview

StructureIngest → SystemClassifier → StructurePrep → Topology → Solvation
  → ShortEM → NVT → NPT → Production → Analysis → Visualization → Report

Each phase produces immutable artifacts (gro/top/itp/tpr/log/xtc/json) + a per-step fingerprint that drives resume-after-crash and config-drift invalidation.

Shipping-ready packed bundle (mdagent pack-bundle)

For a teammate who just wants to run MD simulations — not learn the architecture — produce a self-contained folder with everything wired up:

mdagent pack-bundle ./mdagent-bundle --with-vendor --with-propka --archive
# → ./mdagent-bundle/                                          (drop-in folder)
# → ./mdagent-bundle-macos-arm64-py311.tar.gz                  (drop-in archive)

The bundle contains a one-screen README.md, executable setup.sh

• run_simulation.sh, pre-templated .claude/skills/, example run_configs/, a bundled CC0 1AKI structure for offline smoke, a MANIFEST.json with per-file sha256 + platform + Python version, and (optionally) a vendor/wheels/ wheelhouse so setup.sh can install mdagent fully offline.

On a teammate's machine:

tar -xzf mdagent-bundle-macos-arm64-py311.tar.gz
cd mdagent-bundle
./setup.sh --check-only        # detect-only (no install)
./setup.sh                     # install mdagent
./run_simulation.sh            # run a ~2-min MD on the bundled lysozyme

Verified end-to-end: runs/<run-id>/REPORT.md headline readiness: **ready**; Rg ≈ 1.42 nm; NPT density ≈ 1000 kg/m³.

Tutorials

Eight tutorials ship inside the wheel under src/mdagent/_resources/tutorials/. Markdown is canonical; notebooks and PDFs are generated from the same source:

# Drop the whole tutorial bundle into any directory (markdown + notebooks):
mdagent tutorials extract ./my-tutorials

# Also build PDFs (requires the `tutorials` extra):
mdagent tutorials extract ./my-tutorials --with-pdf

#	Topic	Requires
1	Getting started	mdagent only
2	Claude Code workflow	mdagent only
3	Configs and modes	mdagent + GROMACS
4	Reading outputs	mdagent only
5	PROPKA-driven protonation	mdagent + GROMACS + PROPKA
6	Visualization	mdagent + GROMACS + (VMD or PyMOL)
7	Resume + fingerprint invalidation	mdagent + GROMACS
8	Failure triage	mdagent only

Layout

src/mdagent/
  _resources/              # bundled schemas + skills + starter_kit + tutorials (shipped in the wheel)
    schemas/v0.1.0/        # JSON Schemas for run_config / step_report / index / etc.
    skills/                # SKILL.md files for the three Claude skills
    starter_kit/           # `mdagent init-project DIR` materializes this
    tutorials/             # 8 markdown tutorials + build pipeline (md → ipynb → PDF)
  cli.py                   # `mdagent` console script
  doctor.py                # config-aware preflight
  orchestrator.py          # the 13-step DAG runner with resume + fingerprints
  steps/                   # one module per phase
  dialogue/                # PTY-driven driver for interactive gmx tools
.claude/skills/            # generated by `mdagent install-skills --project .`
critiques/                 # adversarial gpt-critique sessions that hardened the design

Status (slices 1–12, 148 fast tests + 11 slow/wheel tests, all green)

• ✅ Soluble protein-only systems on OPLS-AA / AMBER / CHARMM with matching water.
• ✅ Tutorial mode (auto-resolution) and general_md_prep mode (-inter per-residue).
• ✅ PROPKA-driven protonation: per-residue pKa vs. configured pH (slice 11).
• ✅ Disulfide auto-acceptance from structural distance.
• ✅ Short EM as validation gate + NVT + NPT + production MD.
• ✅ Analysis: RMSD / Rg / RMSF / H-bonds / NVT temperature / NPT pressure & density.
• ✅ mmCIF canonical ingest with coordinate_id_map injectivity check.
• ✅ Resume + fingerprint dependency invalidation.
• ✅ Visualization with VMD/PyMOL/NGLview probing + scripts-always.
• ✅ Wheel-installable; doctor preflight; install-skills helper.
• ✅ Standalone starter kit via mdagent init-project DIR (slice 10).
• ✅ Tutorial bundle (8 .md + 8 .ipynb + .pdf) via mdagent tutorials extract DIR (slice 12).
• 🚧 Remote executor (HPC / cloud GPU) — not yet wired.
• 🚧 PROPKA-driven protonation — currently fixed pH-7 defaults.
• 🚧 Free-energy / enhanced sampling — past scope.

Development

git clone https://github.com/FidhaNazreen/MDSimulationAgent
cd MDSimulationAgent
uv sync
uv run pytest                  # fast suite (~9 s)
uv run pytest --run-slow       # + full GROMACS pipeline tests (~5 min)
uv run pytest --run-wheel      # + wheel build + clean-venv install smoke test