Skip to main content

​
Quickstart

This guide walks you through your first trajectory analysis with warp-md. You’ll learn both the Python API and CLI approaches.
Make sure you’ve installed warp-md before starting this tutorial.

​
Python API: Radius of Gyration

Let’s calculate the radius of gyration for a protein trajectory. This is one of the most common analyses in molecular dynamics.

​
The Complete Example

from warp_md import System, Trajectory, RgPlan

system = System.from_pdb("topology.pdb")
selection = system.select("protein")
traj = Trajectory.open_xtc("trajectory.xtc", system)
rg = RgPlan(selection).run(traj, system, device="auto")
print(rg[:5])

​
Breaking It Down

1

Load the topology

from warp_md import System

system = System.from_pdb("topology.pdb")
The System object contains atomic coordinates, topology information, and provides selection capabilities.
2

Create a selection

selection = system.select("protein")
Selections use a flexible syntax similar to VMD or MDAnalysis. Common examples:
  • "protein" - all protein atoms
  • "resname SOL" - water molecules
  • "name CA" - alpha carbons
  • "resid 1-10 and name CA" - CA atoms in residues 1-10
3

Open the trajectory

from warp_md import Trajectory

traj = Trajectory.open_xtc("trajectory.xtc", system)
The Trajectory object provides lazy iteration over frames. warp-md supports XTC, PDB, and other formats.
4

Run the analysis

from warp_md import RgPlan

rg = RgPlan(selection).run(traj, system, device="auto")
Analysis plans are configured once and executed with .run(). The device="auto" parameter enables GPU acceleration if available.
5

Inspect results

print(rg[:5])  # First 5 frames
Results are returned as NumPy arrays for easy analysis and visualization.

​
GPU Acceleration

To explicitly use GPU acceleration (if compiled with CUDA support): 
rg = RgPlan(selection).run(traj, system, device="cuda")
To force CPU execution: 
rg = RgPlan(selection).run(traj, system, device="cpu")

​
CLI: Radial Distribution Function

The command-line interface is perfect for quick analyses and scripting. Let’s calculate the oxygen-oxygen radial distribution function for water.

​
Basic Command

warp-md rdf \
  --topology top.pdb \
  --traj traj.xtc \
  --sel-a "resname SOL and name OW" \
  --sel-b "resname SOL and name OW" \
  --bins 200 \
  --r-max 10
This computes g(r) between water oxygen atoms out to 10 Å using 200 bins.

​
Available Plans

List all 98+ available analysis plans: 
warp-md list-plans
Get detailed help for a specific analysis: 
warp-md rg --help
warp-md rmsd --help
warp-md pca --help

​
Configuration Files

For complex workflows or reproducible analyses, use JSON or YAML configuration files.

​
Generate Example Config

warp-md example > config.json
This creates a template configuration with common analysis plans.

​
Edit and Run

Edit config.json to match your system and trajectory: 
{
  "topology": "topology.pdb",
  "trajectory": "trajectory.xtc",
  "plans": [
    {
      "name": "rg",
      "selection": "protein",
      "output": "rg.dat"
    },
    {
      "name": "rmsd",
      "selection": "backbone",
      "reference": "reference.pdb",
      "output": "rmsd.dat"
    }
  ]
}
Run the configuration: 
warp-md run config.json

​
Molecular Packing Example

Create a water box with 200 TIP3P molecules: 
from warp_md.pack import Box, Structure, PackConfig, water_pdb
from warp_md.pack.runner import run
from warp_md.pack.export import export

cfg = PackConfig(
    structures=[Structure(water_pdb("tip3p"), count=200)],
    box=Box((40.0, 40.0, 40.0)),
    min_distance=2.0,
)
result = run(cfg)
export(result, "pdb", "packed.pdb")

​
Available Water Models

warp-md includes pre-defined water models:
  • tip3p - TIP3P water model
  • tip4p - TIP4P water model
  • spce - SPC/E water model
  • And more…
List all available models: 
from warp_md.pack import available_water_models

print(available_water_models())

​
Complex Packing

Pack multiple structure types with constraints: 
from warp_md.pack import Box, Structure, PackConfig, Constraint
from warp_md.pack.runner import run
from warp_md.pack.export import export

cfg = PackConfig(
    structures=[
        Structure("protein.pdb", count=1, fixed=True),
        Structure("ligand.pdb", count=5),
        Structure(water_pdb("tip3p"), count=1000),
    ],
    box=Box((60.0, 60.0, 60.0)),
    min_distance=2.0,
    constraints=[
        Constraint(
            selection1="protein",
            selection2="ligand",
            min_distance=5.0,
        )
    ],
)
result = run(cfg)
export(result, "pdb", "solvated_system.pdb")

​
Common Analysis Patterns

​
RMSD with Alignment

from warp_md import System, Trajectory, RmsdPlan

system = System.from_pdb("topology.pdb")
selection = system.select("backbone")
reference = System.from_pdb("reference.pdb")
traj = Trajectory.open_xtc("trajectory.xtc", system)

rmsd = RmsdPlan(
    selection=selection,
    reference=reference,
    align=True
).run(traj, system, device="auto")

print(f"Mean RMSD: {rmsd.mean():.2f} Å")
print(f"Max RMSD: {rmsd.max():.2f} Å")

​
Hydrogen Bonds

warp-md hbond \
  --topology top.pdb \
  --traj traj.xtc \
  --donor "protein" \
  --acceptor "resname SOL" \
  --distance 3.5 \
  --angle 120

​
PCA for Conformational Analysis

from warp_md import System, Trajectory, PcaPlan

system = System.from_pdb("topology.pdb")
selection = system.select("name CA")
traj = Trajectory.open_xtc("trajectory.xtc", system)

pca = PcaPlan(selection, n_components=3).run(traj, system)

print(f"Explained variance: {pca.explained_variance_ratio_}")

​
Next Steps

API Reference

Explore all 98+ analysis plans and their parameters

CLI Reference

Complete command-line interface documentation

Packing Guide

Advanced molecular packing workflows

Peptide Builder

Build and manipulate peptide structures
Join the community and report issues at github.com/Haayhur/warp-md

Build docs developers (and LLMs) love

Get started for freeTalk to us