Skip to navigation

C API getting started

View as Markdown

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.

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

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 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
#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:

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:

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