The command-line interface is where warp-md really shines for AI agents. Structured output, no parsing gymnastics, just run and get JSON.
The CLI was designed for agents first. Analysis and run commands emit JSON envelopes by default; discovery commands support --json/--format json.
Basic Usage
warp-md <analysis> --topology PATH --traj PATH [options]
What’s Available?
warp-md list-plans # Human-readable list
warp-md list-plans --json # Discover the full schema + all analysis names
warp-md list-plans --format json --details # Full parameter introspection
| Analysis | What It Computes |
|---|
rg | Radius of gyration |
rmsd | Root mean square deviation |
msd | Mean square displacement |
rdf | Radial distribution function |
rotacf | Rotational ACF |
conductivity | Ionic conductivity |
dielectric | Dielectric properties |
dipole-alignment | Dipole alignment |
ion-pair-correlation | Ion-pair correlations |
structure-factor | S(q) |
water-count | Water occupancy grid |
equipartition | Temperature from velocities |
hbond | Hydrogen bond counts |
end-to-end | Polymer end-to-end distance |
contour-length | Polymer contour length |
chain-rg | Per-chain Rg |
bond-length-distribution | Bond length histogram |
bond-angle-distribution | Bond angle histogram |
persistence-length | Polymer persistence length |
Examples (Copy-Paste Ready)
warp-md rg \
--topology protein.pdb \
--traj trajectory.xtc \
--selection "protein"
warp-md rdf \
--topology system.pdb \
--traj trajectory.xtc \
--sel-a "resname SOL and name OW" \
--sel-b "resname SOL and name OW" \
--bins 200 \
--r-max 10
warp-md msd \
--topology system.pdb \
--traj trajectory.xtc \
--selection "resname SOL" \
--group-by resid \
--axis 0,0,1
warp-md conductivity \
--topology il.pdb \
--traj il.xtc \
--selection "resname BMIM or resname BF4" \
--group-by resid \
--charges table:charges.csv \
--temperature 300.0
Output: Agent-Friendly by Default
Every command prints a JSON envelope with standardized fields:
# Default: writes output.npz, prints JSON envelope
warp-md rg --topology top.pdb --traj traj.xtc --selection "protein"
# Specify output file
warp-md rg --topology top.pdb --traj traj.xtc --selection "protein" --out rg.npy
# Include traceback on errors (for debugging)
warp-md rg --topology top.pdb --traj traj.xtc --selection "protein" --debug-errors
The envelope contract: Every output includes status, exit_code, and results. Even errors return valid JSON with status="error" and a stable error.code. Your agent always knows what happened.
Config Runner: Batch Workflows
For complex multi-analysis workflows, use a JSON config:
Generate Example Config
warp-md example > config.json
Customize It
{
"version": "warp-md.agent.v1",
"run_id": "my-workflow",
"system": {"path": "system.pdb"},
"trajectory": {"path": "production.xtc"},
"output_dir": "outputs",
"analyses": [
{"name": "rg", "selection": "protein"},
{"name": "rmsd", "selection": "backbone", "reference": "topology"},
{"name": "rdf", "sel_a": "resname SOL", "sel_b": "resname SOL", "bins": 200}
]
}
Run It
warp-md run config.json
# Streaming mode for real-time progress
warp-md run config.json --stream ndjson
Streaming events include completed, total, progress_pct, and eta_ms. Your agent can show progress bars or estimate completion time.
JSON Config Schema
Minimal Config
{
"version": "warp-md.agent.v1",
"system": {"path": "system.pdb"},
"trajectory": {"path": "traj.xtc"},
"analyses": [
{"name": "rg", "selection": "protein"}
]
}
Full Config
{
"version": "warp-md.agent.v1",
"run_id": "prod-run-001",
"system": {
"path": "system.pdb",
"format": "pdb"
},
"trajectory": {
"path": "traj.xtc",
"format": "xtc",
"length_scale": 10.0
},
"device": "auto",
"chunk_frames": 1000,
"stream": "none",
"output_dir": "outputs",
"analyses": [
{
"name": "rg",
"selection": "protein",
"mass_weighted": false,
"out": "outputs/rg.npz"
},
{
"name": "rmsd",
"selection": "backbone",
"reference": "topology",
"align": true,
"device": "cuda",
"chunk_frames": 500
},
{
"name": "rdf",
"sel_a": "resname SOL and name OW",
"sel_b": "resname SOL and name OW",
"bins": 200,
"r_max": 10.0,
"pbc": "orthorhombic"
}
]
}
Charges and Group Types
Some analyses need extra metadata:
Charges (for conductivity, dielectric, dipole)
# Inline array
warp-md conductivity --charges '[1.0,-1.0,1.0]' ...
# From CSV file
warp-md conductivity --charges table:charges.csv ...
# From selection rules
warp-md conductivity --charges 'selections:[{"selection":"resname NA","charge":1.0}]' ...
Group Types (for ion-pair, MSD by type)
# Inline array
warp-md msd --group-types '[0,1,1,0]' ...
# From selections
warp-md msd --group-types 'selections:resname NA,resname CL' ...
Discovery Commands
# Get full request schema
warp-md schema --format json
# Get result envelope schema
warp-md schema --kind result --format json
# Get stream event schema
warp-md schema --kind event --format json
# List all analyses with parameter metadata
warp-md list-plans --format json --details
# List bundled water templates
warp-md water-models --format json
Copy this when prompting AI agents to use warp-md:
TOOL warp-md
DESCRIPTION: Run molecular dynamics trajectory analysis. Writes output file and prints JSON envelope.
COMMAND: warp-md <analysis> --topology PATH --traj PATH [analysis flags]
ANALYSES: rg, rmsd, msd, rdf, rotacf, conductivity, dielectric, dipole-alignment,
ion-pair-correlation, structure-factor, water-count, equipartition, hbond,
end-to-end, contour-length, chain-rg, bond-length-distribution,
bond-angle-distribution, persistence-length
OUTPUT: .npz by default; --out for .npy/.csv/.json; envelope includes status/exit_code/results
DISCOVERY: warp-md list-plans --json (for full parameter schema)
Real Example: Python Subprocess Workflow
import subprocess
import json
# Run analysis
result = subprocess.run(
[
"warp-md", "rg",
"--topology", "protein.pdb",
"--traj", "trajectory.xtc",
"--selection", "protein",
"--out", "rg.npz"
],
capture_output=True,
text=True,
check=False
)
# Parse JSON envelope
envelope = json.loads(result.stdout)
if envelope["status"] == "ok":
print(f"Analysis complete: {envelope['results'][0]['out']}")
print(f"Elapsed: {envelope['elapsed_ms']}ms")
else:
print(f"Error: {envelope['error']['code']}")
print(f"Message: {envelope['error']['message']}")
See Also