C API reference
The host C API exposes reusable plans and workspaces for evaluating molecular interactions on CUDA streams. Start with Getting started for installation and a complete example. The API is in early access and subject to change.
Runtime and data conventions
cupo_abi_version() must match CUPO_ABI_VERSION from cupo/version.h before
using the runtime. cupo_version_string() identifies the loaded library, and
cupo_runtime_capabilities() reports its supported interaction families and
force output. For versioned descriptors, zero-initialize the structure and set
struct_bytes and abi_version to its size and the corresponding header macro.
Status-returning functions report CUPO_SUCCESS or a cupo_status error from
cupo/status.h. APIs that use cupo_last_error() replace its thread-local
diagnostic on failure and clear it on success. Read or copy the message before
the next API call updates it. C++ exceptions do not cross the C API boundary.
For asynchronous calls, success means that work was enqueued. Check CUDA synchronization for device execution errors, and order dependent work on the same stream or with CUDA events. Keep input and output buffers alive until that work completes. Calls using the same direct-space or reciprocal-space workspace must not overlap.
Force outputs accumulate into the destination. Clear the force buffer before
starting a new evaluation, and interpret each stored 64-bit value as signed
before scaling by 2^-32. Output forces use the input particle order, even when
the cell list sorts particles internally.
Splitting plans
cupo/splitting_plan.h defines the Coulomb and attractive-dispersion
decompositions shared by direct and reciprocal space.
Workspaces copy immutable plans during creation. The plan can be destroyed afterward if no further queries are needed. The spreading-order query returns grid points per axis, rather than the spline’s approximation order.
Self and net-charge energy corrections are separate from the mesh output. Use
the same particle weights as the reciprocal calculation: charges for Coulomb,
and sqrt(C6) for dispersion. Recompute the net-charge correction when the box
volume changes.
Cell lists and direct space
cupo/pair.h describes either the built-in Coulomb and Lennard-Jones model or a
custom pair evaluator. The description defines the particle layout for
cupo/cell_list.h and the interaction evaluated by
cupo/dspace.h.
Call prepare with the energy and force flags that will be used by execute.
Complete cell-list construction and preparation before execution, then call
finish to write energy and accumulate forces. The cell list must remain alive
until its dependent workspaces, CUDA graphs, and queued work are finished.
Direct-space workspaces require a caller-owned, 256-byte-aligned device arena. Cell lists can also allocate internally when the arena pointer is null. Destroying a handle does not free caller-owned storage.
Exclusions cancel the selected direct interactions and, when configured, their
reciprocal contributions. Add physical replacement interactions with the tuples
API. Changes to application-level particle ordering require the topology and
weight remapping described in cupo/dspace.h.
Reciprocal space
cupo/kspace.h provides the spreading, convolution, and force-gathering pipeline.
The workspace borrows its cell list, a caller-owned 256-byte-aligned device arena, and any explicit particle-weight buffers. The arena-size query excludes memory owned by FFT plans and configured convolution backends.
Refresh the influence function before the first energy or force evaluation and after every box update. Build the cell list before spreading, and keep the box, cell list, and particle weights unchanged through force gathering. A shared cell list carrying Coulomb charges needs a separate explicit weight buffer for a dispersion calculation.
cupo_kspace_configure_convolution selects the FFT backend and retained Fourier
modes independently. The default is cuFFT with the full mesh spectrum. Configure
and tune the backend outside CUDA graph capture.
Compact convolutions
cupo/convolution.h
exposes standalone three-dimensional GPU convolution designed for compact
Fourier kernels. The retained spectral grid can be compressed relative to
the input real-space grid while preserving the input/output grid resolution.
Modes outside the selected Fourier support are treated as zero.
Applications choose the real-grid dimensions and Fourier support independently, manage their own spreading and gathering, and supply the Fourier influence function with transform normalization and physical factors. The API supports library-owned or caller-provided workspace storage.
For the rationale behind using a fine real-space grid with fewer reciprocal-space modes, see Andrew C. Simmonett and Bernard R. Brooks, A compression strategy for particle mesh Ewald theory, The Journal of Chemical Physics 154, 054112 (2021).
Custom pair expressions
cupo/expression.h compiles a symmetric radial energy expression into a pair
evaluator. Particle parameters use suffixes 1 and 2, globals use their
declared names, and r is the pair distance.
- Compile with
cupo_expression_compilefor the target CUDA architecture. - Create device resources with
cupo_expression_instantiate. - Use the returned
cupo_expression_bindingto create the cell list and direct-space workspace. - Call
cupo_expression_prepareto initialize or update parameters, then rebuild the cell list and evaluate direct space.
The instance owns the prepared records and device globals. Keep it alive through all consumers and their queued work. The program handle can be destroyed after instantiation because the instance retains its program data.
Optional lattice-direct terms subtract the selected long-range contribution from the expression. The application supplies the matching reciprocal calculation, self and background corrections, and exception interactions.
cupo/pair_device.cuh
defines the device-only callback for a custom pair evaluator supplied
by the application as LTO IR. It returns energy and the radial derivative
dU/dr and must satisfy the custom pair API’s symmetry and repeatability
requirements.
Bonded interactions and replacement pairs
cupo/tuples.h evaluates batches of harmonic bonds, harmonic angles, periodic
torsions, and unsplit Coulomb/Lennard-Jones pairs. Use cupo_tuples_create,
cupo_tuples_execute, and cupo_tuples_destroy for the lifecycle, and
cupo_tuples_update_parameters to change parameters while retaining topology.
Tuple coordinates are device float4 or double4 records, according to the
chosen precision. Periodic tuple interactions use a device FP64 six-value
box, unlike the FP32 box used by the nonbonded pipeline. Evaluation adds to both
the energy and fixed-point force buffers; it does not clear them. Unsplit pair
tuples apply no cutoff, switching, or lattice decomposition.
Scalar functions
The scalar functions in
cupo/math/splitting.h
and cupo/math/spreading.h
are callable from both host and device code. They are designed for
integration of cuPotential’s splitting, spreading, and interpolation math into
kernels developers have already built.
The distributed cupo_math.cu.o object contains both host implementations and
device LTO IR. Use a CUDA-aware compiler, and device-link the object when calling
these functions from CUDA kernels.
See samples/ltoir-usage/usage.cu,
included in the runtime archive, for a complete example using the scalar math
functions and standalone convolution.