Skip to main content

​
Installation

warp-md is distributed as a Python package with pre-built binaries for common platforms. You can install it via pip or build from source for custom configurations. The simplest way to get started is to install the latest release from PyPI: 
pip install warp-md
Verify the installation: 
python -c "import warp_md; print(warp_md.System)"
You should see output like <class 'warp_md.traj_py.PySystem'> indicating the extension module loaded successfully.

​
Optional CLI Dependencies

If you plan to use YAML configuration files with the CLI tools, install the optional CLI dependencies: 
pip install "warp-md[cli]"
This adds PyYAML support for reading YAML-based analysis configurations.

​
Optional GIST Dependencies

For Grid Inhomogeneous Solvation Theory (GIST) calculations with OpenMM integration: 
pip install "warp-md[gist]"

​
CLI Tools

Once installed, you’ll have access to three command-line entry points: 
# Main analysis and configuration runner
warp-md --help
warp-md list-plans
warp-md rg --topology top.pdb --traj traj.xtc --selection "protein"
Run warp-md list-plans to see all available analysis plans and their command-line arguments.

​
Build from Source

Building from source gives you access to the latest development features and allows customization of build options like CUDA support.

​
Prerequisites

You’ll need:
  • Rust toolchain (1.70 or later)
  • Python (3.9 or later)
  • maturin (Python build tool for Rust extensions)
  • (Optional) CUDA toolkit for GPU acceleration

​
Build Steps

1

Clone the repository

git clone https://github.com/Haayhur/warp-md.git
cd warp-md
2

Install maturin

pip install maturin
3

Build and install in development mode

maturin develop
This compiles the Rust code and installs the Python package in editable mode.
4

Verify the build

python -c "import warp_md; print(warp_md.System)"

​
Build with CUDA Support

To enable GPU acceleration via CUDA: 
maturin develop --features cuda
CUDA support requires the NVIDIA CUDA toolkit installed and properly configured on your system. The CUDA feature is experimental and not all analysis plans support GPU acceleration.

​
Release Builds

For optimized performance, build in release mode: 
maturin develop --release
Release builds are significantly faster but take longer to compile.

​
Testing Your Installation

​
Python API Test

Test the Python bindings: 
python -m pytest python/warp_md/tests

​
Rust Tests

Run the Rust test suite: 
# All tests
cargo test

# Specific crates
cargo test -p warp-pack
cargo test -p warp-pep

# CUDA engine tests (requires CUDA runtime)
cargo test -p traj-engine --features cuda

​
System Requirements

​
Minimum Requirements

  • Python: 3.9 or later
  • NumPy: Installed automatically as a dependency
  • Pydantic: 2.0 or later (installed automatically)
  • OS: Linux (Ubuntu 20.04+, CentOS 7+) or macOS 11+
  • RAM: 8 GB minimum, 16 GB+ recommended for large trajectories
  • Storage: Fast SSD recommended for trajectory I/O

​
For CUDA Acceleration

  • GPU: NVIDIA GPU with compute capability 6.0+ (Pascal or newer)
  • CUDA: CUDA toolkit 11.0 or later
  • Driver: NVIDIA driver version 450.80.02 or later

​
Troubleshooting

​
Import Error: Extension Module Not Found

If you see an error like ImportError: cannot import name 'traj_py', the Rust extension didn’t build correctly. Solution: Rebuild with verbose output: 
maturin develop --release -v

​
CUDA Tests Fail

If CUDA tests fail, verify your CUDA installation: 
nvcc --version
nvidia-smi
Ensure the CUDA toolkit is in your PATH and LD_LIBRARY_PATH.

​
Missing CLI Commands

If warp-md commands aren’t found after installation: Solution: Ensure your Python scripts directory is in your PATH. For pip user installs: 
export PATH="$HOME/.local/bin:$PATH"
Add this to your shell configuration file (.bashrc, .zshrc, etc.) to make it permanent.

​
Next Steps

Quickstart

Run your first trajectory analysis in 5 lines of code

Build docs developers (and LLMs) love

Get started for freeTalk to us