Quickstart

This tutorial walks through building rgpot from source, running a Lennard-Jones RPC server, and calling it from Python. By the end you will have a running potential server that any Cap’n Proto client can connect to.

What you will need

  • pixi (manages the full toolchain; nothing else to install)

  • About 5 minutes

Clone and build

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

Expected output (last few lines):

[105/105] Linking target CppCore/rgpot/rpc/potserv

Run the tests

meson test -C bbdir

All tests should pass:

Ok:                 7
Expected Fail:      0
Fail:               0

Start an RPC server

Open a second terminal (or use &) and launch a Lennard-Jones server on port 12345:

pixi shell   # if not already in the environment
./bbdir/CppCore/rgpot/rpc/potserv 12345 LJ

The server prints a line and then blocks, waiting for connections:

Listening on 0.0.0.0:12345 with potential: LJ

Call from Python

In the first terminal, install the Python Cap’n Proto bindings and run a calculation:

pixi shell -e rpctest

import capnp
capnp.remove_import_hook()
potentials_capnp = capnp.load("CppCore/rgpot/rpc/Potentials.capnp")

client = capnp.TwoPartyClient("localhost:12345")
pot = client.bootstrap().cast_as(potentials_capnp.Potential)

# Two hydrogen atoms separated by 2.5 Angstrom
request = pot.calculate_request()
fip = request.init("fip")
fip.pos = [0.0, 0.0, 0.0, 2.5, 0.0, 0.0]
fip.atmnrs = [1, 1]
fip.box = [20.0, 0.0, 0.0, 0.0, 20.0, 0.0, 0.0, 0.0, 20.0]

response = request.send().wait()
print(f"Energy: {response.result.energy}")
print(f"Forces: {list(response.result.forces)}")

Expected output:

Energy: -0.02734...
Forces: [0.02148..., 0.0, 0.0, -0.02148..., 0.0, 0.0]

The forces are equal and opposite, as expected for a two-body LJ pair.

What just happened

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

  2. The Python client connected, sent atomic positions, and received energy and forces back.

  3. The same wire protocol works from any language with a Cap’n Proto implementation (C++, Rust, Julia, Go, etc.).

Next steps