Crate rgpot_core 

rgpot-core

Rust core library for rgpot: RPC-based distributed potential energy surface calculations. This crate follows the metatensor architecture pattern: a Rust core that defines fundamental types, exposed via a stable C ABI (auto-generated by cbindgen), with hand-written C++ RAII wrappers on top.

Module Overview

Module	Purpose
types	#[repr(C)] data structures for force/energy I/O
tensor	DLPack tensor helpers: create, free, validate
status	Status codes, thread-local error message, panic safety
potential	Callback-based potential dispatch (opaque handle)
c_api	extern "C" entry points collected by cbindgen
[rpc]	Cap’n Proto RPC client and server (feature-gated)

Design Principles

1. C ABI is the contract. Every public type is #[repr(C)] and every public function is extern "C". The generated rgpot.h header is the single source of truth for all language bindings.

2. Panic safety at every boundary. All extern "C" functions wrap their body in [status::catch_unwind], converting panics to status::rgpot_status_t::RGPOT_INTERNAL_ERROR and storing a human-readable message retrievable via status::rgpot_last_error.

3. Callback-based dispatch. C++ potentials register themselves as function pointer callbacks. The Rust core never depends on concrete C++ types — only on the callback signature.

4. Feature-gated optional layers. RPC (rpc feature) and caching (cache feature) are opt-in, keeping the core dependency-free.

Quick Example (Rust-side)

The core types use DLPack tensors for device-agnostic data exchange. See tensor for helpers to create DLPack tensors from raw pointers.

Modules

c_api

Public C API entry points.

potential

Callback-based potential dispatch.

status

Error handling following the metatensor pattern.

tensor

DLPack tensor helpers for creating, freeing, and validating tensors.

types

C-compatible core data types for force/energy calculations.