Skip to navigation

C API reference

View as Markdown

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.

DataConvention
Standard particle parametersFP32 records {charge, sigma, epsilon}, with sigma in nm and epsilon in kJ/mol.
Nonbonded coordinatesFP32 device positions with a caller-specified stride of at least three floats per particle.
Periodic boxLower-triangular vectors packed as [ax, by, cz, bx, cx, cy]; host box arrays always contain six values. See cupo/box.h.
ForcesSigned fixed-point values with 32 fractional bits, in separate x, y, and z planes. Each plane has the caller’s padded particle stride.
EnergiesFP64 device scalars in physical energy units. Direct-space and reciprocal-space outputs overwrite their scalars; tuple evaluation adds to its scalar.

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.

OperationFunctions
Create a Coulomb plancupo_splitting_plan_create_prolate, cupo_splitting_plan_create_ewald
Create an attractive-dispersion plancupo_splitting_plan_create_prolate_dispersion, cupo_splitting_plan_create_ewald_dispersion
Compute energy correctionscupo_splitting_plan_get_self_energy, cupo_splitting_plan_get_net_charge_energy
Query the assignment stencil widthcupo_splitting_plan_get_spread_order
Release a plancupo_splitting_plan_destroy

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.

StageFunctions
Allocate and create a cell listcupo_cell_list_workspace_size, cupo_cell_list_create
Rebuild from current positions and parameterscupo_cell_list_execute
Update the boxcupo_cell_list_update_box
Allocate and create direct-space workcupo_dspace_workspace_size, cupo_dspace_create
Evaluate direct spacecupo_dspace_prepare, cupo_dspace_execute, cupo_dspace_finish
Release resourcescupo_dspace_destroy, cupo_cell_list_destroy

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.

StageFunctions
Choose mesh dimensionscupo_plan_grid
Allocate and create a workspacecupo_kspace_workspace_size, cupo_kspace_create
Prepare the influence functioncupo_kspace_refresh_influence
Evaluate the complete mesh calculationcupo_kspace_execute
Evaluate individual stagescupo_kspace_spread, cupo_kspace_convolve, cupo_kspace_interpolate
Release resourcescupo_kspace_destroy

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.

  1. Compile with cupo_expression_compile for the target CUDA architecture.
  2. Create device resources with cupo_expression_instantiate.
  3. Use the returned cupo_expression_binding to create the cell list and direct-space workspace.
  4. Call cupo_expression_prepare to 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.