mod potential

module potential

C API for the potential handle lifecycle: create, calculate, free.

These three functions form the core public interface for potential energy calculations. The typical usage pattern from C/C++ is:

// 1. Create a handle from a callback
rgpot_potential_t *pot = rgpot_potential_new(my_callback, my_data, NULL);

// 2. Prepare input/output
rgpot_force_input_t  input  = rgpot_force_input_create(n, pos, types, box);
rgpot_force_out_t    output = rgpot_force_out_create();

// 3. Calculate
rgpot_status_t s = rgpot_potential_calculate(pot, &input, &output);
if (s != RGPOT_SUCCESS) { /* handle error */ }
// output.forces is now a DLPack tensor — use it, then free:
rgpot_tensor_free(output.forces);

// 4. Clean up
rgpot_force_input_free(&input);
rgpot_potential_free(pot);

Functions

unsafe extern C fn rgpot_potential_calculate(pot: *const rgpot_potential_t, input: *const rgpot_force_input_t, output: *mut rgpot_force_out_t) -> rgpot_status_t

Perform a force/energy calculation using the potential handle.

  • pot: a valid handle obtained from rgpot_potential_new.

  • input: pointer to the input configuration (DLPack tensors).

  • output: pointer to the output struct. The callback sets output->forces to a callee-allocated DLPack tensor.

Returns RGPOT_SUCCESS on success, or an error status code. On error, call rgpot_last_error() for details.

unsafe extern C fn rgpot_potential_free(pot: *mut rgpot_potential_t)

Free a potential handle previously obtained from rgpot_potential_new.

If pot is NULL, this function is a no-op. After this call, pot must not be used again.

unsafe extern C fn rgpot_potential_new(callback: PotentialCallback, user_data: *mut c_void, free_fn: Option<unsafe extern C fn (*mut c_void)>) -> *mut rgpot_potential_t

Create a new potential handle from a callback function pointer.

  • callback: the function that performs the force/energy calculation.

  • user_data: opaque pointer forwarded to every callback invocation (typically a pointer to the C++ potential object).

  • free_fn: optional destructor for user_data. Pass NULL if the caller manages the lifetime externally.

Returns a heap-allocated rgpot_potential_t*, or NULL on failure. The caller must eventually pass the returned pointer to rgpot_potential_free.