mod potential

module potential

Callback-based potential dispatch.

This module defines PotentialImpl, an opaque handle that wraps a C function pointer callback together with a void* user_data and an optional destructor. This is the core abstraction that lets existing C++ potentials (LJ, CuH2, or any future implementation) plug into the Rust infrastructure without the Rust side knowing the concrete type.

How it Works

  1. The C++ side creates a potential object (e.g., LJPot).

  2. A trampoline function with the PotentialCallback signature is registered, casting user_data back to the concrete type and calling forceImpl.

  3. The Rust core dispatches through the function pointer, receiving results via the rgpot_force_out_t output struct.

Lifetime Contract

  • The user_data pointer is borrowed by PotentialImpl. The caller must keep the underlying object alive for the lifetime of the handle.

  • If a free_fn is provided, it is called on drop when user_data is non-null, transferring ownership to PotentialImpl.

  • The handle is exposed to C as rgpot_potential_t — an opaque pointer managed via rgpot_potential_new / rgpot_potential_free.

Types

type FreeFn

Destructor for the user_data pointer.

type PotentialCallback

Function pointer type for a potential energy calculation.

The callback receives: - user_data: opaque pointer to the C++ object (e.g. LJPot*) - input: the atomic configuration (DLPack tensors) - output: the buffer for results (callback sets forces tensor)

Returns RGPOT_SUCCESS on success, or an error status code.

type rgpot_potential_t

Opaque handle exposed to C as rgpot_potential_t.

This is a type alias used by cbindgen to generate a forward declaration.

Structs and Unions

struct PotentialImpl

Opaque potential handle wrapping a callback + user data.

Implementations

impl PotentialImpl

Functions

unsafe fn calculate(&self, input: *const rgpot_force_input_t, output: *mut rgpot_force_out_t) -> rgpot_status_t

Invoke the underlying callback.

Safety The caller must ensure input and output point to valid, properly sized structures.

fn new(callback: PotentialCallback, user_data: *mut c_void, free_fn: Option<FreeFn>) -> Self

Create a new potential from a callback, user data, and optional destructor.

Traits implemented

unsafe impl Send for PotentialImpl
impl Drop for PotentialImpl