> 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.

# C API getting started

> Use cuPotential from C or C++ to compute molecular interaction energies and forces on NVIDIA GPUs.

The C API provides direct access to cuPotential from C and C++ applications.
It includes bonded interactions, direct-space pair interactions, reciprocal-space
calculations, and custom radial expressions. Your application supplies particle
data in CUDA device memory and manages CUDA streams and synchronization.

> **Note**
>
> cuPotential is in early-access mode. Its C API is experimental: expect breaking changes, including to its structure, in upcoming releases.

## Runtime and headers

Download the runtime archive, `cupo-0.3.5+<build>.tar.gz`, from the
[release](https://github.com/NVIDIA/cuPotential/releases/tag/v0.3.5).
It contains the public headers in `include/cupo/` and the shared library in
`build/libcupo.so`. Use the headers and library from the same release.

```bash
tar -xzf cupo-0.3.5+*.tar.gz
cd cupo-0.3.5+*/
```

Building an application requires Linux x86-64, a C or C++ compiler, and the
CUDA Toolkit version recorded in the archive’s `.cuda-version` file. The
[GPU and driver requirements](/cuda/cupotential/install#requirements) are the
same as for the OpenMM plugin. The standalone C API does not require OpenMM
or Python.

## Example: harmonic bond energy and forces

This example evaluates one harmonic bond, with
`E = k (r - r0)^2 / 2`, between two atoms. The atoms are 0.2 nm apart; the
bond has an equilibrium length of 0.1 nm and a force constant of
1000 kJ/(mol nm²). It uses double-precision coordinates and no periodic
boundary conditions.

Save the following source as `bond.c` in the root of the unpacked archive.

Download bond.c

```c
#include <cupo/tuples.h>
#include <cupo/version.h>
#include <cuda_runtime_api.h>
#include <stdint.h>
#include <stdio.h>

#define CUDA_CHECK(call) do { \
    cudaError_t status = (call); \
    if (status != cudaSuccess) { \
        fprintf(stderr, "%s\n", cudaGetErrorString(status)); \
        goto cleanup; \
    } \
} while (0)

#define CUPO_CHECK(call) do { \
    if ((call) != CUPO_SUCCESS) { \
        fprintf(stderr, "%s\n", cupo_last_error()); \
        goto cleanup; \
    } \
} while (0)

int main(void)
{
    int result = 1;
    cupo_tuples_handle handle = NULL;
    void *device_positions = NULL;
    int64_t *device_forces = NULL;
    double *device_energy = NULL;

    /* Two atoms separated by 0.2 nm; the fourth component is unused. */
    const double positions[2][4] = {{0, 0, 0, 0}, {0.2, 0, 0, 0}};
    int64_t forces[6];
    double energy;
    const cupo_tuples_bond bond = {
        .atoms = {0, 1},
        .parameters = {.length = 0.1, .k = 1000.0},
        .use_pbc = 0,
        .group = 0
    };
    const cupo_tuples_term_batch batch = {
        .kind = CUPO_TUPLES_HARMONIC_BOND, .count = 1, .terms = &bond
    };

    if (cupo_abi_version() != CUPO_ABI_VERSION) {
        fprintf(stderr, "cuPotential headers and library have different ABIs\n");
        return 1;
    }
    CUDA_CHECK(cudaSetDevice(0));
    CUPO_CHECK(cupo_tuples_create(2, 1, &batch, CUPO_TUPLES_FLOAT64, &handle));
    CUDA_CHECK(cudaMalloc(&device_positions, sizeof(positions)));
    CUDA_CHECK(cudaMalloc((void **)&device_forces, sizeof(forces)));
    CUDA_CHECK(cudaMalloc((void **)&device_energy, sizeof(energy)));
    CUDA_CHECK(cudaMemcpy(device_positions, positions, sizeof(positions),
                          cudaMemcpyHostToDevice));

    /* Execution adds to the outputs, so clear them before this calculation. */
    CUDA_CHECK(cudaMemset(device_forces, 0, sizeof(forces)));
    CUDA_CHECK(cudaMemset(device_energy, 0, sizeof(energy)));
    CUPO_CHECK(cupo_tuples_execute(handle, device_positions, NULL,
        device_forces, 2, device_energy, 1u, NULL));
    CUDA_CHECK(cudaDeviceSynchronize());
    CUDA_CHECK(cudaMemcpy(&energy, device_energy, sizeof(energy),
                          cudaMemcpyDeviceToHost));
    CUDA_CHECK(cudaMemcpy(forces, device_forces, sizeof(forces),
                          cudaMemcpyDeviceToHost));

    /* x, y, and z are separate force planes, each with stride 2. */
    printf("Energy: %.6f kJ/mol\n", energy);
    printf("Forces along x: %.6f, %.6f kJ/(mol*nm)\n",
           (double)forces[0] / 4294967296.0,
           (double)forces[1] / 4294967296.0);
    result = 0;

cleanup:
    cudaDeviceSynchronize();
    cupo_tuples_destroy(handle);
    cudaFree(device_energy);
    cudaFree(device_forces);
    cudaFree(device_positions);
    return result;
}
```

Build and run from the archive root. Set `CUPO_CUDA_ROOT` to the CUDA Toolkit
installation that matches the archive’s `.cuda-version`:

```bash
CUPO_CUDA_ROOT=/usr/local/cuda
export LD_LIBRARY_PATH="$CUPO_CUDA_ROOT/lib64${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}"
gcc -O2 -std=c11 bond.c -o build/bond \
    -Iinclude -I"$CUPO_CUDA_ROOT/include" \
    -Lbuild -lcupo -L"$CUPO_CUDA_ROOT/lib64" -lcudart \
    -Wl,-rpath,'$ORIGIN'
./build/bond
```

Expected output:

```text
Energy: 5.000000 kJ/mol
Forces along x: 100.000000, -100.000000 kJ/(mol*nm)
```

The handle copies the host interaction records when it is created. Positions,
forces, and the energy accumulator remain in caller-owned CUDA device memory.
The position records contain four doubles per atom; the fourth component is
ignored. Force output uses three planes of signed 64-bit fixed-point values,
with a scale factor of `2^32`. For this two-atom example, the x components occupy
entries 0 and 1, y occupies 2 and 3, and z occupies 4 and 5.

`cupo_tuples_execute` adds to the output buffers asynchronously. Clear them
before a fresh calculation, and wait for CUDA work to finish before reading
results or destroying the handle. The final two arguments select force group
0 and the default CUDA stream. The box pointer is `NULL` because this bond does
not use periodic boundaries.

For nonbonded calculations, the [API reference](/cuda/cupotential/c-api/reference)
describes splitting plans, cell lists, direct and reciprocal space, and custom
expressions. It also links to the public headers, which specify each function's
arguments and ownership requirements.