PolyzyMD

Molecular dynamics simulation toolkit for enzyme-polymer systems.

Documentation • Installation • Quick Start

Overview

PolyzyMD provides a streamlined workflow for setting up and running MD simulations of enzymes with co-polymer chains. It handles:

• System Building: Combine enzyme structures, docked substrates, and random co-polymers
• Solvation: Add water, ions, and optional co-solvents with PACKMOL
• Simulation: Run equilibration and production with OpenMM
• HPC Integration: Self-resubmitting job submission for SLURM clusters
• Configuration: YAML-based configuration with validation

Analysis Status

• Stable comparison and plotting workflows: RMSF, contacts, distances, catalytic triad, and secondary structure
• Experimental but still available: contacts binding preference, exposure dynamics, binding free energy, and polymer affinity score
• Experimental analyses remain callable from the CLI, but PolyzyMD labels their text output and generated figures as experimental because definitions and interpretation may change in a later release
• Analysis currently supports OpenMM-produced trajectories (DCD format) only; GROMACS XTC trajectory support is planned for v1.2.1 (#47)

Installation

PolyzyMD uses pixi for environment management. Pixi handles all dependencies (OpenMM, OpenFF stack, CUDA, etc.) from conda-forge with reproducible lockfiles.

1. Install pixi

curl -fsSL https://pixi.sh/install.sh | sh

2. Clone and install

git clone https://github.com/joelaforet/polyzymd.git
cd polyzymd

For local use (building systems, validation, no GPU):

pixi install -e build
pixi shell -e build

For HPC clusters (GPU simulations):

Pick the environment that matches your cluster's CUDA version:

# Example for Blanca:
pixi install -e cuda-12-4
pixi shell -e cuda-12-4

# Example for Bridges2:
pixi install -e cuda-12-6
pixi shell -e cuda-12-6

After pixi shell, the polyzymd command is on PATH and works normally.

How to find your CUDA version

Run on a GPU node:

nvidia-smi | head -1

The driver version in the top-right maps to a maximum supported CUDA version. Use the environment whose CUDA version does not exceed your driver.

Quick Start

1. Initialize a Project

polyzymd init --name my_simulation
cd my_simulation

This creates a project directory with a template config.yaml and placeholder files.

2. Add Your Structure Files

cp /path/to/enzyme.pdb structures/
cp /path/to/substrate.sdf structures/  # optional

3. Edit Configuration & Run

# Edit config.yaml with your settings, then:
polyzymd validate -c config.yaml
polyzymd submit -c config.yaml --replicates 1-5 --preset blanca-shirts

The --preset flag selects SLURM configuration and automatically picks the correct pixi environment (cuda-12-4 for Blanca, cuda-12-6 for Bridges2). You can override with --pixi-env:

polyzymd submit -c config.yaml --replicates 1-5 --preset bridges2 --pixi-env cuda-12-6

See the Quick Start Guide for a complete walkthrough.

CLI Commands

Pixi Environments

PolyzyMD uses pixi instead of conda/mamba. Key differences:

• No conda activate — use pixi shell -e <env> instead
• No environment YAML — pixi.toml + pixi.lock are the single source of truth
• Reproducible — the lockfile pins every package to exact versions
• CUDA-aware — each environment pins the correct CUDA and OpenMM versions

Adding support for a new cluster

1. Determine the CUDA version (nvidia-smi on a GPU node)
2. Add a new [feature.cuda-X-Y] block in pixi.toml following the existing pattern
3. Add the corresponding environment in [environments]
4. Add the preset mapping in PRESET_DEFAULT_PIXI_ENV in slurm.py
5. File a PR

Documentation

Full documentation is available at polyzymd.readthedocs.io.

• Installation Guide
• Configuration Reference
• HPC & SLURM Guide
• API Reference

License

MIT License - see LICENSE file for details.

Citation

If you use PolyzyMD in your research, please cite:

@software{polyzymd,
  author = {Laforet Jr., Joseph R.},
  title = {PolyzyMD: Polymer-Enzyme Interactions Studied with Molecular Dynamics},
  year = {2026},
  url = {https://github.com/joelaforet/polyzymd}
}