class rgpot::PotentialHandle¶

Overview¶

Move-only RAII handle around an opaque rgpot_potential_t pointer. More…

#include <potential.hpp>
 
class PotentialHandle {
public:
    // construction
 
    PotentialHandle(rgpot_potential_t* handle);
    PotentialHandle(PotentialHandle&& other);
    PotentialHandle(const PotentialHandle&);
    ~PotentialHandle();
 
    // methods
 
    PotentialHandle& operator=(PotentialHandle&& other);
    PotentialHandle& operator=(const PotentialHandle&);
    CalcResult calculate(const InputSpec& input);
    rgpot_potential_t* raw() const;
 
    template <typename Impl>
    static PotentialHandle from_impl(Impl& impl);
 
    template <typename Impl>
    static PotentialHandle from_impl(Impl& impl, size_t n_atoms, const int32_t* atomic_numbers, const double* box_matrix, const double* bounds_low = nullptr, const double* bounds_high = nullptr);
 
    static PotentialHandle from_callback(rgpot_status_t(*)(void*, const rgpot_force_input_t*, rgpot_force_out_t*) callback, void* user_data, void(*)(void*) free_fn = nullptr);
};

Detailed Documentation¶

Move-only RAII handle around an opaque rgpot_potential_t pointer.

The handle is non-copyable. Move semantics transfer ownership of the underlying Rust allocation. On destruction the Rust core frees all resources associated with the potential via rgpot_potential_free().

Construction¶

PotentialHandle(rgpot_potential_t* handle)

Adopt an existing raw handle.

handle was obtained from rgpot_potential_new() and has not been freed.

Parameters:

handle

Raw pointer to the Rust-side potential object.

PotentialHandle(PotentialHandle&& other)

Move constructor — transfers ownership.

Parameters:

other

Handle to move from; left in a null state.

~PotentialHandle()

Destructor — releases the Rust-side allocation.

Safe to call on a moved-from handle (internal pointer is nullptr).

Methods¶

PotentialHandle& operator=(PotentialHandle&& other)

Move assignment — releases current handle, transfers ownership.

Parameters:

other

Handle to move from; left in a null state.

Returns:

Reference to *this.

CalcResult calculate(const InputSpec& input)

Perform a force/energy calculation.

Creates a CalcResult, delegates to rgpot_potential_calculate(), and checks the returned status code. The callback sets the forces tensor in the output struct.

Parameters:

input	The atomic configuration to evaluate.
rgpot::Error	when the underlying callback reports failure.

Returns:

A CalcResult containing energy, variance, and forces.

rgpot_potential_t* raw() const

Access the raw opaque handle for C interop.

Returns:

Pointer to the underlying rgpot_potential_t.

template <typename Impl>
static PotentialHandle from_impl(Impl& impl)

Create a handle from a legacy C++ potential implementation.

Registers a template trampoline that extracts raw CPU pointers from the DLPack tensors in rgpot_force_input_t, constructs legacy ForceInput / ForceOut types for Impl::forceImpl(), and wraps the resulting forces in an owning DLPack tensor.

The caller retains ownership of impl and must keep it alive for the lifetime of the returned handle.

The handle is one rgpot_potential_t and therefore one eindir_objective_t (first-member IS-A). Child terms stay inside impl; this factory does not build a list of objectives.

Parameters:

Impl	A type with `void` `forceImpl` (const `ForceInput&`, `ForceOut*`).
impl	Reference to the C++ potential object.

Returns:

A new PotentialHandle wrapping impl.

template <typename Impl>
static PotentialHandle from_impl(Impl& impl, size_t n_atoms, const int32_t* atomic_numbers, const double* box_matrix, const double* bounds_low = nullptr, const double* bounds_high = nullptr)

Wrap impl as one eindir objective with molecular context.

Same trampoline as from_impl(Impl&), but calls rgpot_potential_new_eindir with atom count, species, and cell so hosts that eval through eindir_objective_t* have bounds and species. rgpot_potential_calculate still uses the input tensors.

static PotentialHandle from_callback(rgpot_status_t(*)(void*, const rgpot_force_input_t*, rgpot_force_out_t*) callback, void* user_data, void(*)(void*) free_fn = nullptr)

Create a handle from an explicit C callback and user data.

This is the low-level factory; prefer from_impl() for C++ potentials.

Parameters:

callback	Function pointer matching the `rgpot_potential_t` callback signature.
user_data	Opaque pointer forwarded to every callback invocation.
free_fn	Optional destructor for user_data (may be `nullptr` if the caller manages the lifetime).

Returns:

A new PotentialHandle.