> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/cuda/cupotential/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/cuda/cupotential/_mcp/server.

# Samples

> Run solvated-system and alchemical simulations with the OpenMM plugin.

The OpenMM samples in `plugins/openmm/samples/` demonstrate solvated-system and
alchemical simulations. Both check the plugin's results against reference
calculations.

Run the commands below from the repository root. `./run_docker` provides a
Docker environment with OpenMM, the CUDA toolkit, and access to your GPUs.
See [Installation](/cuda/cupotential/install) for system requirements.

## Get the source

Clone the release, or use the source archive from the
[installation guide](/cuda/cupotential/install):

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

## Build the plugin

```bash
./run_docker plugins/openmm/run_build
```

The first run also builds the image defined by the repository's `Dockerfile`.
When building from a clone, the build downloads cuPotential's prebuilt libraries
for the matching release and verifies them against `SHA256SUMS`. The source
archive already includes these libraries.

## Run a sample

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

Both samples print `PASS` on success and return a nonzero exit code if a check
fails.

### Solvated systems

`solvated_systems` runs apoa1 (about 92,000 atoms), bace (about 70,000), and dhfr
(about 24,000). Each system runs in NVT, then in NPT with the plugin's barostat.
The sample checks energies against high-accuracy references and compares
throughput with stock OpenMM over 3,000 steps. It takes no arguments and runs in
about a minute on a recent GPU.

The bace input is included. For apoa1 and dhfr, the sample uses OpenMM's benchmark
files from your OpenMM installation, downloading them once from OpenMM's GitHub
repository if they are missing.

### Alchemical simulation

`alchemical` uses an included TYK2 relative binding free energy system. It
combines the stock `NonbondedForce` and `CustomNonbondedForce` into one plugin
force, preserving global parameters and parameter offsets.

The sample checks energies and forces against stock OpenMM after changing charge
and softcore parameters, then runs 200 NVT steps.

## Use an installed plugin

If you installed the plugin with pip or conda, run the sample's `run` script
from the repository root in the same `./run_docker bash` session used for
installation. For conda, prefix the command with `micromamba run -n cupotential`
to use the environment where the plugin is installed.

See [Tests](/cuda/cupotential/tests) for correctness checks, including tests of an
installed plugin. For performance measurements, see
[Benchmarks](/cuda/cupotential#benchmarks).