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

> Runtime interfaces for splitting plans, cell lists, nonbonded interactions, expressions, and bonded interactions.

The host C API exposes reusable plans and workspaces for evaluating molecular
interactions on CUDA streams. Start with [Getting started](/cuda/cupotential/c-api/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`](https://github.com/NVIDIA/cuPotential/blob/v0.3.5/include/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`](https://github.com/NVIDIA/cuPotential/blob/v0.3.5/include/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.

| Data                         | Convention                                                                                                                                                                                          |
| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Standard particle parameters | FP32 records `{charge, sigma, epsilon}`, with sigma in nm and epsilon in kJ/mol.                                                                                                                    |
| Nonbonded coordinates        | FP32 device positions with a caller-specified stride of at least three floats per particle.                                                                                                         |
| Periodic box                 | Lower-triangular vectors packed as `[ax, by, cz, bx, cx, cy]`; host box arrays always contain six values. See [`cupo/box.h`](https://github.com/NVIDIA/cuPotential/blob/v0.3.5/include/cupo/box.h). |
| Forces                       | Signed fixed-point values with 32 fractional bits, in separate x, y, and z planes. Each plane has the caller's padded particle stride.                                                              |
| Energies                     | FP64 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`](https://github.com/NVIDIA/cuPotential/blob/v0.3.5/include/cupo/splitting_plan.h) defines the Coulomb and attractive-dispersion
decompositions shared by direct and reciprocal space.

| Operation                            | Functions                                                                                      |
| ------------------------------------ | ---------------------------------------------------------------------------------------------- |
| Create a Coulomb plan                | `cupo_splitting_plan_create_prolate`, `cupo_splitting_plan_create_ewald`                       |
| Create an attractive-dispersion plan | `cupo_splitting_plan_create_prolate_dispersion`, `cupo_splitting_plan_create_ewald_dispersion` |
| Compute energy corrections           | `cupo_splitting_plan_get_self_energy`, `cupo_splitting_plan_get_net_charge_energy`             |
| Query the assignment stencil width   | `cupo_splitting_plan_get_spread_order`                                                         |
| Release a plan                       | `cupo_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`](https://github.com/NVIDIA/cuPotential/blob/v0.3.5/include/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`](https://github.com/NVIDIA/cuPotential/blob/v0.3.5/include/cupo/cell_list.h) and the interaction evaluated by
[`cupo/dspace.h`](https://github.com/NVIDIA/cuPotential/blob/v0.3.5/include/cupo/dspace.h).

| Stage                                         | Functions                                                          |
| --------------------------------------------- | ------------------------------------------------------------------ |
| Allocate and create a cell list               | `cupo_cell_list_workspace_size`, `cupo_cell_list_create`           |
| Rebuild from current positions and parameters | `cupo_cell_list_execute`                                           |
| Update the box                                | `cupo_cell_list_update_box`                                        |
| Allocate and create direct-space work         | `cupo_dspace_workspace_size`, `cupo_dspace_create`                 |
| Evaluate direct space                         | `cupo_dspace_prepare`, `cupo_dspace_execute`, `cupo_dspace_finish` |
| Release resources                             | `cupo_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`](https://github.com/NVIDIA/cuPotential/blob/v0.3.5/include/cupo/kspace.h) provides the spreading, convolution, and force-gathering pipeline.

| Stage                                  | Functions                                                               |
| -------------------------------------- | ----------------------------------------------------------------------- |
| Choose mesh dimensions                 | `cupo_plan_grid`                                                        |
| Allocate and create a workspace        | `cupo_kspace_workspace_size`, `cupo_kspace_create`                      |
| Prepare the influence function         | `cupo_kspace_refresh_influence`                                         |
| Evaluate the complete mesh calculation | `cupo_kspace_execute`                                                   |
| Evaluate individual stages             | `cupo_kspace_spread`, `cupo_kspace_convolve`, `cupo_kspace_interpolate` |
| Release resources                      | `cupo_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`](https://github.com/NVIDIA/cuPotential/blob/v0.3.5/include/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*](https://pubmed.ncbi.nlm.nih.gov/33557541/),
*The Journal of Chemical Physics* **154**, 054112 (2021).

## Custom pair expressions

[`cupo/expression.h`](https://github.com/NVIDIA/cuPotential/blob/v0.3.5/include/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`](https://github.com/NVIDIA/cuPotential/blob/v0.3.5/include/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`](https://github.com/NVIDIA/cuPotential/blob/v0.3.5/include/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`](https://github.com/NVIDIA/cuPotential/blob/v0.3.5/include/cupo/math/splitting.h)
and [`cupo/math/spreading.h`](https://github.com/NVIDIA/cuPotential/blob/v0.3.5/include/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`](https://github.com/NVIDIA/cuPotential/blob/v0.3.5/samples/ltoir-usage/usage.cu),
included in the runtime archive, for a complete example using the scalar math
functions and standalone convolution.