Quickstart

This tutorial builds rgpot from source, runs the local tests, and exercises the Cap’n Proto RPC server with the repository integration script. The same ForceInput / PotentialResult wire protocol is used by external clients.

What you will need

  • pixi (manages the full toolchain)

Clone and build

git clone https://github.com/OmniPotentRPC/rgpot.git
cd rgpot
pixi shell -e rpctest
meson setup bbdir -Dwith_tests=true -Dwith_rpc=true --buildtype=debug
meson compile -C bbdir

The RPC build produces the potserv executable:

bbdir/CppCore/potserv

Run the tests

meson test -C bbdir --print-errorlogs

Run the RPC smoke

The checked smoke starts potserv, connects through pycapnp, sends a ForceInput, and verifies the returned PotentialResult:

python tests/rpc_integ.py --server-bin ./bbdir/CppCore/potserv

Run configure smokes for the runtime-loaded quantum frontends:

python tests/rpc_integ.py \
  --server-bin ./bbdir/CppCore/potserv \
  --nwchem-smoke \
  --cpmd-smoke

What just happened

  1. potserv loaded a built-in potential and exposed it over Cap’n Proto RPC.

  2. The Python client sent atomic positions in ForceInput.

  3. The server returned energy and forces in PotentialResult.

  4. The same wire protocol works from any language with a Cap’n Proto

implementation.

Start a manual server

Launch a Lennard-Jones server on port 12345:

./bbdir/CppCore/potserv 12345 LJ

For runtime-loaded quantum engines, pass the matching selector and engine path:

RGPOT_CPMD_ENGINE="$PWD/bbdir/CppCore/libcpmdc_fake_engine.so" \
  ./bbdir/CppCore/potserv 12345 CPMD
NWCHEMC_LIBRARY=/path/to/libnwchemc.so ./bbdir/CppCore/potserv 12345 NWChem

Evaluate water with CPMD

The configure smoke does not calculate. This command reads the water geometry in tests/data/cpmd/water.xyz. The cell is a cube with side 20 angstrom. The stand-in engine comes from the tests build above.

export RGPOT_CPMD_ENGINE="$PWD/bbdir/CppCore/libcpmdc_fake_engine.so"
python tests/cpmd_water.py \
  --server-bin ./bbdir/CppCore/potserv \
  --expect 0.77

The command prints:

water geometry: water
water energy: 0.77

0.77 is the energy that stand-in engine returns for this geometry and cell. The same command with RGPOT_CPMD_ENGINE pointed at a CPMD-archive libcpmdc.so evaluates that file with CPMD.

Next steps