====================
Crate ``rgpot_core``
====================


.. rust:crate:: rgpot_core
   :index: 0

   **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.

   .. rubric:: Modules
   .. toctree::
      :maxdepth: 1

      types
      tensor
      status
      potential
      c_api
      Potentials_capnp
      rpc


   .. rust:use:: rgpot_core
      :used_name: self


   .. rust:use:: rgpot_core
      :used_name: crate