Installation
Each GitHub release includes a pip wheel, a conda package and channel, and a source archive.
We recommend installing and running the plugin in the provided Docker
environment. It includes OpenMM 8.4 with CUDA support, the CUDA libraries, and
Python 3.12. Use ./run_docker <command> to run a command or ./run_docker bash
to open a shell. The Docker workflow below starts with a clone or source
archive, which contains run_docker and its Dockerfile.
Requirements
- An NVIDIA GPU of SM 75, 80, 86, 89, 90, 100, 103 or 120 (Turing through Blackwell, including B200).
- The NVIDIA driver R615 or newer, for CUDA 13.4. NVIDIA data center GPUs, and
the professional RTX GPUs that CUDA forward compatibility supports, also work
with an older driver of the R535, R570, R580, R590, R595 or R610 branch, through
CUDA 13.4’s forward compatibility package. The Docker environment has the
package, and the NVIDIA Container Toolkit uses it on an older driver. Outside
Docker, install
cuda-compat-13-4from NVIDIA’s CUDA repository (aptordnf) and put/usr/local/cuda-13.4/compatonLD_LIBRARY_PATH; take it off again once the driver is R615 or newer. GeForce GPUs need R615 or newer. See CUDA Forward Compatibility. - Docker with the NVIDIA Container Toolkit, so that
docker run --gpus=allworks, for the recommended Docker environment. - Linux x86-64.
- Python 3.12, for the wheel and the conda package.
- OpenMM 8.4 with its CUDA platform, which the Docker environment brings.
From PyPI
Install nv-openmm-plugin from PyPI
into an environment meeting the Python, OpenMM, CUDA, and GPU requirements above:
Installing the PyPI package does not require a repository checkout.
From GitHub
The steps below use the GitHub release and the repository’s Docker environment.
1. Get the source
Clone the repository at the release tag:
Alternatively, download cupo-nv-openmm-plugin-src-0.3.5+<build>.tar.gz
from the release
and unpack it:
Run the commands below from the root of the clone or unpacked archive.
2. Install the plugin
Each ./run_docker invocation starts a new container and removes it when the
command finishes. For pip and conda installations, install and run the plugin
in the same ./run_docker bash session. The lines after ./run_docker bash
below run inside that shell.
With pip
Install the release’s wheel with pip. It requires openmm[cuda13]>=8.4,<8.5;
the Docker environment already provides a compatible OpenMM installation.
With conda
The first command runs on the host and downloads the release’s conda channel. Inside Docker, micromamba creates an environment with the plugin from that channel and its dependencies from conda-forge, then runs a sample.
From source
The source archive includes cuPotential’s prebuilt libraries in build/.
When building from a clone, run_build downloads those libraries from the
matching release and verifies them against SHA256SUMS. For a private
repository, set GITHUB_TOKEN to a token with read access.
Build the plugin
From the root of the tree:
run_docker runs the build in a container with OpenMM, the CUDA toolkit, and
other build dependencies. The first run also builds the image from the
repository’s Dockerfile. By default, the plugin is built for every supported
GPU architecture. To shorten the build, select one architecture with
CUDA_ARCHITECTURES=89 ./run_docker plugins/openmm/run_build (SM 89 in this example).
Run the samples
With the plugin you built, from the root of the tree:
The build leaves the plugin’s Python package, nv_openmm_plugin, in
plugins/openmm/python/, and the samples import it from there.
See Samples for example simulations and
Tests for correctness checks. Benchmark results and
instructions are in the Overview.
Outside Docker
You can also install the wheel or conda package outside Docker. Your environment
must provide OpenMM 8.4 with its CUDA platform, the matching CUDA libraries, and
Python 3.12. The repository’s Dockerfile lists the commands used to install
these dependencies.
The GPUs the container gets
./run_docker gives the container every GPU in the machine by default. Use
NV_GPU=0 ./run_docker bash to select the first host GPU. GPU indices start at 0.
NV_GPU also accepts GPU UUIDs and comma-separated lists, such as NV_GPU=0,1,
using the same selection as docker run --gpus device=.
If the GPU disappears in the middle of a run, with “Failed to initialize NVML:
Unknown Error” from nvidia-smi or “No compatible CUDA device is available” from
OpenMM, the host probably ran systemctl daemon-reload. On a host whose Docker
uses the systemd cgroup driver, that removes the GPUs from every running container
that got them with --gpus only. Set CUPO_DOCKER_ADD_DEVICE_NODES=1 to have
run_docker also pass the GPUs’ device nodes, /dev/nvidia*, with --device,
which keeps them: CUPO_DOCKER_ADD_DEVICE_NODES=1 ./run_docker bash. run_docker
finds each GPU’s node with nvidia-smi on the host, and prints a warning when it
cannot. NVIDIA’s
troubleshooting page
describes the issue.