rgpot_core/lib.rs
1// MIT License
2// Copyright 2023--present rgpot developers
3
4// C-style names are intentional for cbindgen compatibility.
5#![allow(non_camel_case_types)]
6
7//! # rgpot-core
8//!
9//! Rust core library for rgpot: RPC-based distributed potential energy surface
10//! calculations. This crate follows the
11//! [metatensor](https://docs.metatensor.org/) architecture pattern: a Rust core
12//! that defines fundamental types, exposed via a stable C ABI (auto-generated by
13//! [cbindgen](https://github.com/mozilla/cbindgen)), with hand-written C++ RAII
14//! wrappers on top.
15//!
16//! ## Module Overview
17//!
18//! | Module | Purpose |
19//! |--------|---------|
20//! | [`types`] | `#[repr(C)]` data structures for force/energy I/O |
21//! | [`tensor`] | DLPack tensor helpers: create, free, validate |
22//! | [`status`] | Status codes, thread-local error message, panic safety |
23//! | [`potential`] | Callback-based potential dispatch (opaque handle) |
24//! | [`c_api`] | `extern "C"` entry points collected by cbindgen |
25//! | [`rpc`] | Cap'n Proto RPC client and server (feature-gated) |
26//!
27//! ## Design Principles
28//!
29//! 1. **C ABI is the contract.** Every public type is `#[repr(C)]` and every
30//! public function is `extern "C"`. The generated `rgpot.h` header is the
31//! single source of truth for all language bindings.
32//!
33//! 2. **Panic safety at every boundary.** All `extern "C"` functions wrap their
34//! body in [`status::catch_unwind`], converting panics to
35//! [`status::rgpot_status_t::RGPOT_INTERNAL_ERROR`] and storing a
36//! human-readable message retrievable via [`status::rgpot_last_error`].
37//!
38//! 3. **Callback-based dispatch.** C++ potentials register themselves as
39//! function pointer callbacks. The Rust core never depends on concrete C++
40//! types — only on the callback signature.
41//!
42//! 4. **Feature-gated optional layers.** RPC (`rpc` feature) and caching
43//! (`cache` feature) are opt-in, keeping the core dependency-free.
44//!
45//! ## Quick Example (Rust-side)
46//!
47//! The core types use DLPack tensors for device-agnostic data exchange.
48//! See [`tensor`] for helpers to create DLPack tensors from raw pointers.
49
50pub mod types;
51pub mod tensor;
52pub mod status;
53pub mod potential;
54pub mod c_api;
55
56#[cfg(feature = "rpc")]
57#[allow(dead_code, non_snake_case, unused_parens, clippy::all)]
58/// Auto-generated Cap'n Proto schema bindings for the RPC wire protocol.
59///
60/// This module is produced at build time from `Potentials.capnp` and is not
61/// intended for direct use. See the `rpc` module for the public RPC
62/// client/server API.
63pub mod Potentials_capnp {
64 include!(concat!(env!("OUT_DIR"), "/Potentials_capnp.rs"));
65}
66
67#[cfg(feature = "rpc")]
68pub mod rpc;