mod potential

module potential

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

rgpot_potential_t is the superset struct defined in crate::eindir: it embeds eindir_objective_t as its first member so every rgpot_potential_t* IS-A eindir_objective_t* at the C ABI.

The three lifecycle functions here use the direct callback path (pot.callback); the eindir evaluation path goes through eindir_objective_eval with the zero-cost cast.

// Direct rgpot path:
rgpot_potential_t *pot = rgpot_potential_new(my_callback, my_data, NULL);
rgpot_status_t s = rgpot_potential_calculate(pot, &input, &output);
rgpot_potential_free(pot);

// eindir path (IS-A cast, no conversion method):
eindir_objective_t *obj = (eindir_objective_t*)pot;
double val;
eindir_objective_eval(obj, x_tensor, &val);

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.

Routes through the direct rgpot callback (pot.callback), bypassing the eindir evaluation path.

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

Free a potential handle previously obtained from rgpot_potential_new or rgpot_potential_new_eindir.

Calls pot_free_fn(pot_user_data) if provided, frees all owned arrays, then frees the struct.

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.

Creates a rgpot_potential_t with no molecular context (n_atoms = 0) and no eindir bounds. The potential evaluates through callback directly. Use rgpot_potential_new_eindir when the IS-A eindir embedding is needed.

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