C API getting started
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.
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.
Build and run from the archive root. Set CUPO_CUDA_ROOT to the CUDA Toolkit
installation that matches the archive’s .cuda-version:
Expected output:
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.