Embedding as a Subproject

This page covers how to embed rgpot into another C/C++ project using meson or cmake as a subproject dependency.

Meson

Add a subprojects/rgpot.wrap file or vendor the source directly into subprojects/rgpot/.

Full library build (server + potentials)

Use this when your project hosts an RPC server with rgpot’s built-in potentials:

rgpot_proj = subproject('rgpot',
    default_options: ['with_rpc=true', 'with_tests=false'])
rgpot_dep = rgpot_proj.get_variable('rgpot_dep')

RPC schema only (client mode)

Use this when your project only needs to call a remote potential server, or when you want to avoid namespace collisions with your own types (see integration guide):

rgpot_proj = subproject('rgpot',
    default_options: ['with_rpc_client_only=true', 'pure_lib=true'])
ptlrpc_dep = rgpot_proj.get_variable('ptlrpc_dep')

The ptlrpc_dep provides only the Cap’n Proto schema and generated code, without pulling in Potential.hpp or the existing C++ potentials. It is a static convenience archive: the same symbols are also inside librgpot, so a consumer that resolves rgpot through pkg-config instead of the wrap links them from the umbrella and has no separate libptlrpc to find at run time.

Feature-gated potentials (Meson)

Optional backends are off by default so the core library stays lightweight. Enable only what the host project needs:

Meson option	pixi env	Backend
-Dwith_xtb=true	xtbbld / tbbld	XTBPot (GFNFF, GFN0/1/2-xTB)
-Dwith_tblite=true	tblitebld / tbbld	TBLitePot (GFN1, GFN2, IPEA1)
-Dwith_metatomic=true	metatomicbld (linux-64)	MetatomicPot (TorchScript models)

NWChemPot is a pure consumer: the frontend is always compiled and dlopen=s =libnwchemc.so from nwchemc (stable nwchemc_* C symbols). rgpot builds no in-process NWChem embed of its own and has no -Dwith_nwchem option. No nwchem CLI/subprocess path. Build libnwchemc.so from the nwchemc project, then set NWCHEMC_LIBRARY or RGPOT_NWCHEMC_ENGINE. See CppCore/ rgpot/NWChemPot/README.md.

CPMDPot follows the same split-engine pattern: the frontend is always compiled and dlopen=s =libcpmdc.so from [[https://github.com/OmniPotentRPC/cpmdc] [cpmdc]]. rgpot builds no in-process OpenCPMD embed of its own and has no -Dwith_cpmd option. Build libcpmdc.so from the cpmdc project, then set CPMDC_LIBRARY, RGPOT_CPMDC_ENGINE, or RGPOT_CPMD_ENGINE. See CppCore/rgpot/CPMDPot/README.md.

Example – embed with metatomic support:

rgpot_proj = subproject('rgpot',
    default_options: [
      'with_rpc=true',
      'with_metatomic=true',
      'with_tests=false',
    ])
rgpot_dep = rgpot_proj.get_variable('rgpot_dep')

The metatomic path needs PyTorch (Torch CMake package), metatensor_torch, metatomic_torch, and vesin on the linker path. The Meson build supplements Torch CMake discovery with explicit -L / -rpath / -ltorch_cpu taken from python3 -c 'import torch; ...' so libtorch_cpu.so resolves under conda/pixi layouts.

For the pip wheel (nanobind abi3 + multi-ABI dlopen engines, torch 2.7+), see:

Python package (PyPI)

instead of embedding as a subproject.

CMake

rgpot also provides a CMake build. To use it as a subdirectory:

add_subdirectory(external/rgpot)
target_link_libraries(my_target PRIVATE rgpot::rgpot)

Build options

Option	Default	Description
RGPOT_BUILD_TESTS	OFF	Build the test suite
RGPOT_BUILD_EXAMPLES	OFF	Build example programs
RGPOT_RPC_CLIENT_ONLY	OFF	Build only the RPC client (schema library)

cmake -B build -DRGPOT_BUILD_TESTS=ON -DRGPOT_BUILD_EXAMPLES=ON
cmake --build build
ctest --test-dir build

Windows (MSVC)

rgpot builds on Windows with MSVC 2022. Install Cap’n Proto via conda-forge or vcpkg, then use the standard meson or cmake workflow. No special flags are required since v1.0.3.

For conda-forge builds, the following are handled automatically by the build system:

• capnp compile is used instead of capnpc (the Windows capnpc.EXE does not

support the -o flag)

• Generated .c++ files are renamed to .cpp (MSVC does not recognize the =.c+

+= extension)

• ws2_32 is linked for Cap’n Proto’s async networking layer