rgpot-core 1.0.1

Core Rust library for rgpot: RPC-based potential energy surface calculations
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68

// MIT License
// Copyright 2023--present rgpot developers

// C-style names are intentional for cbindgen compatibility.
#![allow(non_camel_case_types)]

//! # rgpot-core
//!
//! Rust core library for rgpot: RPC-based distributed potential energy surface
//! calculations. This crate follows the
//! [metatensor](https://docs.metatensor.org/) architecture pattern: a Rust core
//! that defines fundamental types, exposed via a stable C ABI (auto-generated by
//! [cbindgen](https://github.com/mozilla/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.

pub mod types;
pub mod tensor;
pub mod status;
pub mod potential;
pub mod c_api;

#[cfg(feature = "rpc")]
#[allow(dead_code, non_snake_case, unused_parens, clippy::all)]
/// Auto-generated Cap'n Proto schema bindings for the RPC wire protocol.
///
/// This module is produced at build time from `Potentials.capnp` and is not
/// intended for direct use.  See the `rpc` module for the public RPC
/// client/server API.
pub mod Potentials_capnp {
    include!(concat!(env!("OUT_DIR"), "/Potentials_capnp.rs"));
}

#[cfg(feature = "rpc")]
pub mod rpc;