Skip to navigation

Installation

View as Markdown

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-4 from NVIDIA’s CUDA repository (apt or dnf) and put /usr/local/cuda-13.4/compat on LD_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=all works, 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:

pip install nv-openmm-plugin

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:

git clone --branch v0.3.5 https://github.com/NVIDIA/cuPotential
cd cuPotential

Alternatively, download cupo-nv-openmm-plugin-src-0.3.5+<build>.tar.gz from the release and unpack it:

tar -xzf cupo-nv-openmm-plugin-src-0.3.5+*.tar.gz
cd cupo-nv-openmm-plugin-src-0.3.5+*/

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.

./run_docker bash
pip install https://github.com/NVIDIA/cuPotential/releases/download/v0.3.5/nv_openmm_plugin-0.3.5-cp312-cp312-manylinux_2_38_x86_64.whl
./plugins/openmm/samples/solvated_systems/run

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.

curl -fL https://github.com/NVIDIA/cuPotential/releases/download/v0.3.5/nv-openmm-plugin-conda-channel-0.3.5.tar.gz | tar -xz
./run_docker bash
micromamba create -y -n cupotential -c ./nv-openmm-plugin-conda-channel-0.3.5 -c conda-forge nv-openmm-plugin
micromamba run -n cupotential ./plugins/openmm/samples/solvated_systems/run

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 plugins/openmm/run_build

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:

./run_docker # solvated_systems, the default
./run_docker plugins/openmm/samples/alchemical/run

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.