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);
 
    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.

Parameters:

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

Returns:

A new PotentialHandle wrapping impl.

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.