Crate rgpot_core

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