Installation

This guide covers installing PolyzyMD and its dependencies using pixi, a fast, reproducible package manager.

Prerequisites

• Linux x86-64 (the only platform with tested environments)

• pixi (installed below)

Note

PolyzyMD’s simulation stack (OpenMM, OpenFF Toolkit, etc.) is only available via conda-forge channels. Pixi handles this automatically — you do not need conda or mamba installed.

Install pixi

If you don’t already have pixi:

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

Then restart your shell or run source ~/.bashrc (or ~/.zshrc).

User Installation (local / no GPU)

Use the build environment for system building, validation, and PDB preparation on a local machine without a GPU.

# Clone the repository
git clone https://github.com/joelaforet/polyzymd.git
cd polyzymd

# Install the build environment
pixi install -e build

# Activate the environment
pixi shell -e build

# Verify installation
polyzymd --help
polyzymd info

Inside the pixi shell, the polyzymd CLI is on PATH and works directly.

What works in the build environment

Command	Works?	Notes
polyzymd build	Yes	System building (no GPU needed)
polyzymd validate	Yes	Config validation
polyzymd init	Yes	Project scaffolding
polyzymd info	Yes	Version/dependency info
polyzymd clean-pdb	Yes	PDB cleanup
polyzymd submit	No	Requires a CUDA environment
polyzymd run-segment	No	Requires a CUDA environment

HPC Installation

Warning

The SLURM presets in PolyzyMD are designed for CU Boulder Alpine/Blanca and PSC Bridges2. Other clusters will need custom presets — see HPC and SLURM Guide for details.

On HPC clusters with GPUs, use one of the CUDA environments. Pick the environment that matches your cluster’s CUDA driver version.

How to find your CUDA version

On a GPU node, run:

nvidia-smi | head -1

The driver version in the top-right maps to a maximum CUDA version:

Cluster	CUDA driver	Environment
PSC Bridges2	12.6	cuda-12-6
CU Boulder Blanca	12.4	cuda-12-4

Setup steps

# 1. Install pixi (if not already installed)
curl -fsSL https://pixi.sh/install.sh | sh
source ~/.bashrc

# 2. Clone the repo to your projects directory
cd /projects/$USER
git clone https://github.com/joelaforet/polyzymd.git
cd polyzymd

# 3. Install the environment matching your cluster
pixi install -e cuda-12-6    # Bridges2
# or
pixi install -e cuda-12-4    # CU Boulder Blanca

# 4. Verify installation (on a GPU node)
pixi shell -e cuda-12-6
polyzymd info

Tip

You only need to run pixi install once. After that, pixi shell -e <env> is all you need to activate the environment in each new session.

Submitting jobs

Inside the pixi shell, submission works as usual:

pixi shell -e cuda-12-6

polyzymd submit -c config.yaml \
    --replicates 1-3 \
    --preset aa100 \
    --dry-run

The generated SLURM scripts automatically activate the correct pixi environment via pixi shell-hook — no module load or conda activate needed in job scripts.

Developer Installation

For contributing to PolyzyMD or modifying the source code:

# Clone the repository
git clone https://github.com/joelaforet/polyzymd.git
cd polyzymd

# Install the build environment (editable mode is automatic via pixi.toml)
pixi install -e build

# Activate
pixi shell -e build

# Run tests
pytest tests/ -x -q --tb=short --ignore=tests/test_packmol.py

# Run linting
ruff check src/
ruff format --check src/

PolyzyMD is installed in editable mode by default (configured in pixi.toml via polyzymd = { path = ".", editable = true }). Any source changes are immediately reflected without reinstalling.

Optional Dependencies

AmberTools

AmberTools is included in all pixi environments by default (pinned to version 23.3 for compatibility with the OpenFF stack). No additional installation is needed.

To use AM1-BCC charges via AmberTools in your configuration:

substrate:
  charge_method: "am1bcc"

OpenEye Toolkit (commercial, faster AM1-BCC)

If you have an OpenEye license, install the toolkit in your pixi environment:

pixi shell -e build
pip install openeye-toolkits

Common Installation Issues

“pixi: command not found”

Make sure pixi is installed and on PATH:

curl -fsSL https://pixi.sh/install.sh | sh
source ~/.bashrc
which pixi

“polyzymd: command not found”

Make sure you’ve activated the pixi environment:

pixi shell -e build        # local use
pixi shell -e cuda-12-6    # HPC use
which polyzymd             # should show path inside .pixi/

pixi install fails on HPC login node

Some HPC systems restrict network access on login nodes. Try:

1. Use a compile/data-transfer node if available

2. Or pre-download on a machine with internet access and rsync the repository (including .pixi/) to the cluster

OpenMM can’t find CUDA

Make sure you’re using the correct CUDA environment for your cluster:

# Check your GPU's CUDA version
nvidia-smi | head -1

# Use the matching environment
pixi shell -e cuda-12-6    # NOT cuda-12-4 on a 12.6 system
python -c "import openmm; print(openmm.Platform.getPlatformByName('CUDA').getName())"

Adding support for a new cluster

If your cluster has a different CUDA driver version, you can add a new environment to pixi.toml following the pattern of the existing CUDA features. See the comments in pixi.toml for instructions, or file a PR.

Updating PolyzyMD

To update to the latest version:

cd /path/to/polyzymd
git pull
pixi install -e <your-environment>

Since PolyzyMD is installed in editable mode from the local clone, git pull picks up all code changes. Running pixi install again updates any changed conda dependencies.

Uninstalling

# Remove the pixi environments
cd /path/to/polyzymd
rm -rf .pixi

# Or remove the entire clone
rm -rf /path/to/polyzymd

Next Steps

Once installed, continue to the Quick Start Guide guide to run your first simulation.