RPC and Serialization¶

Overview¶

gproptim supports two serialization/RPC mechanisms:

Cap’n Proto for zero-copy parameter loading
rgpot for potential energy evaluation via RPC

Both are optional and enabled at build time.

Cap’n Proto Parameters¶

Schema¶

The parameter schema is defined in schema/gprd_params.capnp. It provides a structured, versioned replacement for the legacy text-based input.dat format.

Key struct hierarchy:

Struct	Purpose
`InputParameters`	Top-level container for all dimer parameters
`GprModel`	GP hyperparameters (sigma2, magnSigma2, prior)
`ConvergenceCriteria`	Force thresholds and rotation angles
`IterationControl`	Outer/inner iteration limits
`HyperparameterOptimization`	SCG or ADAM optimizer settings (union)
`EarlyStopping`	Distance metric thresholds
`Pruning`	Observation pruning configuration
`Debug`	Output file paths and verbosity

Generating Binary Parameters¶

Use the Python generator to convert a TOML config to binary Cap’n Proto:

cd schema
uv run gen_capnp_params.py config.toml ../input/capnp_params.bin

Loading Parameters (C++)¶

The CapnProtoManager uses memory-mapped I/O for zero-copy deserialization:

#include "managers/io/CapnProtoManager.h"

gpr::InputParameters params;
gpr::io::loadParametersFromCapnp("input/capnp_params.bin", params);

This mmap-based approach avoids parsing overhead and is suitable for high-throughput parameter sweeps.

Build Configuration¶

meson setup builddir -Duse_capnp=true

Requires the capnproto package (available in pixi/conda-forge).

Potential Evaluation via rgpot¶

PotentialWrapper¶

PotentialWrapper is a type-erased interface for potential energy evaluation. It wraps any callable with the signature:

void(long N, const double* R, const int* atomicNrs,
     double* F, double* U, double* variance, const double* box)

Factory Methods¶

From rgpot potentials¶

#include "gpr/potentials/PotentialWrapper.h"
#include "rgpot/CuH2/CuH2Pot.hpp"

rgpot::CuH2Pot cuh2;
auto potential = pot::PotentialWrapper::from_rgpot(cuh2);

The factory handles array layout conversion between the legacy flat-array interface and rgpot’s AtomMatrix format.

From Python callables¶

from gpr_optim import PotentialWrapper

def my_potential(positions, atomic_numbers, forces, box):
    # positions: (N, 3), forces: (N, 3) writable, box: (3, 3)
    forces[:] = -0.1 * positions
    return float(0.05 * np.sum(positions**2))

pot = PotentialWrapper(my_potential)

From ASE calculators¶

from ase.calculators.emt import EMT
from ase.build import bulk
from gpr_optim import ase_potential

atoms = bulk("Cu", "fcc", a=3.6, cubic=True)
atoms.calc = EMT()
pot_fn = ase_potential(atoms)

RPC Client (Planned)¶

The from_rpc_client() factory method is reserved for future integration with rgpot’s Cap’n Proto RPC server, enabling remote potential evaluation for distributed computing workflows.

Comparison¶

Feature	Text input	Cap’n Proto	rgpot local	rgpot RPC
Parameters	Yes	Yes	N/A	N/A
Potentials	N/A	N/A	Yes	Planned
Zero-copy	No	Yes	N/A	N/A
Versioned schema	No	Yes	N/A	N/A
Python support	N/A	Via generator	Via nanobind	N/A