Global Namespace¶

Overview¶

// namespaces
 
namespace fortranpots;
namespace rgpot;
namespace rgpot;
    namespace rgpot::abi;
    namespace rgpot::cache;
    namespace rgpot::details;
    namespace rgpot::fortranpots;
    namespace rgpot::nlist;
    namespace rgpot::types;
        namespace rgpot::types::adapt;
            namespace rgpot::types::adapt::capnp;
            namespace rgpot::types::adapt::eigen;
            namespace rgpot::types::adapt::xtensor;
    namespace rgpot::units;
    namespace rgpot::vesin_compat;
namespace rgpot;
namespace rgpot;
namespace rgpot;
namespace rgpot;
namespace rgpot;
namespace rgpot_cuh2;
namespace rgpot_cuh2_capi;
namespace rgpot_eam_al;
namespace rgpot_eam_al_capi;
namespace rgpot_edip;
namespace rgpot_edip_capi;
namespace rgpot_fehe;
namespace rgpot_fehe_capi;
namespace rgpot_ferror;
namespace rgpot_kinds;
namespace rgpot_lenosky;
namespace rgpot_lenosky_capi;
namespace rgpot_neighbors;
namespace rgpot_sw;
namespace rgpot_sw_capi;
namespace rgpot_tersoff;
namespace rgpot_tersoff_capi;
namespace rgpot_water_h;
namespace rgpot_water_h_capi;
namespace std;
namespace string_literals;
namespace vesin;
    namespace vesin::cpu;
 
// typedefs
 
typedef struct CPMDCResult CPMDCResult;
typedef struct CPMDCSession CPMDCSession;
typedef enum CPMDCFeatureKind CPMDCFeatureKind;
typedef struct CPMDCFeatureEntry CPMDCFeatureEntry;
typedef struct RgpotMtaPot RgpotMtaPot;
typedef struct RgpotMtaConfig RgpotMtaConfig;
typedef struct NWChemCResult NWChemCResult;
typedef struct PotClient PotClient;
typedef struct RgpotXtbPot RgpotXtbPot;
typedef struct RgpotXtbConfig RgpotXtbConfig;
 
// enums
 
enum {
    RGPOT_XTB_METHOD_GFNFF = 0,
    RGPOT_XTB_METHOD_GFN0  = 1,
    RGPOT_XTB_METHOD_GFN1  = 2,
    RGPOT_XTB_METHOD_GFN2  = 3,
};
 
enum CPMDCFeatureKind;
 
// structs
 
struct CPMDCFeatureEntry;
struct CPMDCResult;
struct NWChemCResult;
struct RgpotMtaConfig;
struct RgpotMtaPot;
struct RgpotXtbConfig;
struct RgpotXtbPot;
 
// classes
 
class AtomMatrix;
class GenericPotImpl;
class PotClient;
 
// global variables
 
static const CPMDCFeatureEntry g_features[];
char* errbuf;
char size_t errlen;
long nAtoms;
long const double* positions;
long const double const int* atomicNrs;
long const double const int double* forces;
long const double const int double double* energy;
long const double const int double double double* variance;
long const double const int double double double const double* box;
static const char* STUB_VERSION = “nwchemc-stub/1.0.0”;
char* errbuf;
char size_t errlen;
long nAtoms;
long const double* positions;
long const double const int* atomicNrs;
long const double const int double* forces;
long const double const int double double* energy;
long const double const int double double double* variance;
long const double const int double double double const double* box;
 
// global functions
 
int cpmdc_set_params(const void* params_capnp, size_t params_capnp_size_bytes);
CPMDCResult cpmdc_energy_gradient(int n_atoms, const double* positions_ang, const int* atomic_numbers, const void* params_capnp, size_t params_capnp_size_bytes, double* grad_h_bohr);
CPMDCResult cpmdc_energy(int n_atoms, const double* positions_ang, const int* atomic_numbers, const void* params_capnp, size_t params_capnp_size_bytes);
CPMDCResult cpmdc_energy_forces(int n_atoms, const double* positions_ang, const int* atomic_numbers, const void* params_capnp, size_t params_capnp_size_bytes, double* forces_h_bohr);
CPMDCSession* cpmdc_session_create(const void* params_capnp, size_t params_capnp_size_bytes);
int cpmdc_session_set_params(CPMDCSession* session, const void* params_capnp, size_t params_capnp_size_bytes);
void cpmdc_session_destroy(CPMDCSession* session);
CPMDCResult cpmdc_session_energy_gradient(CPMDCSession* session, int n_atoms, const double* positions_ang, const int* atomic_numbers, double* grad_h_bohr);
CPMDCResult cpmdc_session_energy(CPMDCSession* session, int n_atoms, const double* positions_ang, const int* atomic_numbers);
CPMDCResult cpmdc_session_energy_forces(CPMDCSession* session, int n_atoms, const double* positions_ang, const int* atomic_numbers, double* forces_h_bohr);
CPMDCResult cpmdc_session_calculate_forces(CPMDCSession* session, const void* force_input_capnp, size_t force_input_capnp_size_bytes, double* forces_h_bohr, size_t forces_len);
CPMDCResult cpmdc_session_calculate_result(CPMDCSession* session, const void* force_input_capnp, size_t force_input_capnp_size_bytes, void* potential_result_capnp, size_t potential_result_capnp_capacity_bytes, size_t* potential_result_capnp_size_bytes);
CPMDCResult cpmdc_calculate_result(const void* params_capnp, size_t params_capnp_size_bytes, const void* force_input_capnp, size_t force_input_capnp_size_bytes, void* potential_result_capnp, size_t potential_result_capnp_capacity_bytes, size_t* potential_result_capnp_size_bytes);
size_t cpmdc_potential_result_size_for_force_input(const void* force_input_capnp, size_t force_input_capnp_size_bytes);
const char* cpmdc_version(void);
int cpmdc_available(void);
void cpmdc_finalize(void);
size_t cpmdc_feature_count(void);
const CPMDCFeatureEntry* cpmdc_feature_table(void);
const CPMDCFeatureEntry* cpmdc_feature_find(const char* feature_id);
static CPMDCResult stub_fail(void);
int cpmdc_set_params(const void* params_capnp, size_t params_capnp_size_bytes);
CPMDCResult cpmdc_energy_gradient(int n_atoms, const double* positions_ang, const int* atomic_numbers, const void* params_capnp, size_t params_capnp_size_bytes, double* grad_h_bohr);
CPMDCResult cpmdc_energy(int n_atoms, const double* positions_ang, const int* atomic_numbers, const void* params_capnp, size_t params_capnp_size_bytes);
CPMDCResult cpmdc_energy_forces(int n_atoms, const double* positions_ang, const int* atomic_numbers, const void* params_capnp, size_t params_capnp_size_bytes, double* forces_h_bohr);
const char* cpmdc_version(void);
int cpmdc_available(void);
void cpmdc_finalize(void);
CPMDCSession* cpmdc_session_create(const void* params_capnp, size_t params_capnp_size_bytes);
int cpmdc_session_set_params(CPMDCSession* session, const void* params_capnp, size_t params_capnp_size_bytes);
void cpmdc_session_destroy(CPMDCSession* session);
CPMDCResult cpmdc_session_energy(CPMDCSession* session, int n_atoms, const double* positions_ang, const int* atomic_numbers);
CPMDCResult cpmdc_session_energy_gradient(CPMDCSession* session, int n_atoms, const double* positions_ang, const int* atomic_numbers, double* grad_h_bohr);
CPMDCResult cpmdc_session_energy_forces(CPMDCSession* session, int n_atoms, const double* positions_ang, const int* atomic_numbers, double* forces_h_bohr);
CPMDCResult cpmdc_session_calculate_forces(CPMDCSession* session, const void* force_input_capnp, size_t force_input_capnp_size_bytes, double* forces_h_bohr, size_t forces_len);
CPMDCResult cpmdc_session_calculate_result(CPMDCSession* session, const void* force_input_capnp, size_t force_input_capnp_size_bytes, void* potential_result_capnp, size_t potential_result_capnp_capacity_bytes, size_t* potential_result_capnp_size_bytes);
CPMDCResult cpmdc_calculate_result(const void* params_capnp, size_t params_capnp_size_bytes, const void* force_input_capnp, size_t force_input_capnp_size_bytes, void* potential_result_capnp, size_t potential_result_capnp_capacity_bytes, size_t* potential_result_capnp_size_bytes);
size_t cpmdc_potential_result_size_for_force_input(const void* force_input_capnp, size_t force_input_capnp_size_bytes);
size_t cpmdc_feature_count(void);
const CPMDCFeatureEntry* cpmdc_feature_table(void);
const CPMDCFeatureEntry* cpmdc_feature_find(const char* feature_id);
program test_cuh2();
subroutine cu_slab_with_h2(integer, intent(in) cells, real(wp), intent(in) a, real(wp), intent(in) gap, real(wp), intent(in) height, real(wp), intent(in) bond, real(wp), dimension(:, :), intent(out), allocatable pos, integer(ip), dimension(:), intent(out), allocatable z, real(wp), dimension(3, 3), intent(out) box);
program test_eam_al();
subroutine fcc_lattice(integer, intent(in) cells, real(wp), intent(in) a, real(wp), dimension(:, :), intent(out), allocatable pos, real(wp), dimension(3, 3), intent(out) box);
program test_edip();
subroutine diamond_lattice(integer, intent(in) cells, real(wp), intent(in) a, real(wp), dimension(:, :), intent(out), allocatable pos, real(wp), dimension(3, 3), intent(out) box);
program test_fehe();
subroutine bcc_lattice(integer, intent(in) cells, real(wp), intent(in) a, real(wp), dimension(:, :), intent(out), allocatable pos, real(wp), dimension(3, 3), intent(out) box);
program test_lenosky();
subroutine diamond_lattice(integer, intent(in) cells, real(wp), intent(in) a, real(wp), dimension(:, :), intent(out), allocatable pos, real(wp), dimension(3, 3), intent(out) box);
program test_sw_gather();
subroutine diamond_lattice(integer, intent(in) cells, real(wp), intent(in) a, real(wp), dimension(:, :), intent(out), allocatable pos, real(wp), dimension(3, 3), intent(out) box);
program test_tersoff();
subroutine diamond_lattice(integer, intent(in) cells, real(wp), intent(in) a, real(wp), dimension(:, :), intent(out), allocatable pos, real(wp), dimension(3, 3), intent(out) box);
program test_water_h();
subroutine water_plus_h(real(wp), dimension(3, natoms), intent(out) pos, integer(ip), dimension(natoms), intent(out) atomic_numbers, real(wp), dimension(3, 3), intent(out) cellv);
__attribute__((visibility(“default”)));
static const char* nz(const char* s);
static void set_err(char* errbuf, size_t errlen, const char* msg);
int rgpot_mta_abi_version(void);
int rgpot_mta_available(void);
RgpotMtaPot* rgpot_mta_create(const RgpotMtaConfig* cfg, char* errbuf, size_t errlen);
void rgpot_mta_destroy(RgpotMtaPot* pot);
int rgpot_mta_force(RgpotMtaPot* pot, long nAtoms, const double* positions, const int* atomicNrs, double* forces, double* energy, double* variance, const double* box);
int nwchemc_set_params(const void* params_capnp, size_t params_capnp_size_bytes);
NWChemCResult nwchemc_energy_gradient(int n_atoms, const double* positions_ang, const int* atomic_numbers, const void* params_capnp, size_t params_capnp_size_bytes, double* grad_h_bohr);
const char* nwchemc_version(void);
int nwchemc_available(void);
int nwchemc_set_params(const void* params_capnp, size_t params_capnp_size_bytes);
NWChemCResult nwchemc_energy_gradient(int n_atoms, const double* positions_ang, const int* atomic_numbers, const void* params_capnp, size_t params_capnp_size_bytes, double* grad_h_bohr);
const char* nwchemc_version(void);
int nwchemc_available(void);
PotClient* pot_client_init(const char* host, int32_t port);
void pot_client_free(PotClient* client);
int32_t pot_calculate(PotClient* client, int32_t natoms, const double* pos, const int32_t* atmnrs, const double* box, double* out_energy, double* out_forces);
const char* pot_get_last_error(PotClient* client);
PotClient* pot_client_init(const char* host, int32_t port);
void pot_client_free(PotClient* client);
int32_t pot_calculate(PotClient* client, int32_t natoms, const double* pos, const int32_t* atmnrs, const double* box, double* out_energy, double* out_forces);
const char* pot_get_last_error(PotClient* client);
int main(int argc, char* argv[]);
__attribute__((visibility(“default”)));
static rgpot::GFNMethod method_from_c(int m);
int rgpot_xtb_abi_version(void);
int rgpot_xtb_available(void);
RgpotXtbPot* rgpot_xtb_create(const RgpotXtbConfig* cfg, char* errbuf, size_t errlen);
void rgpot_xtb_destroy(RgpotXtbPot* pot);
int rgpot_xtb_force(RgpotXtbPot* pot, long nAtoms, const double* positions, const int* atomicNrs, double* forces, double* energy, double* variance, const double* box);
 
// macros
 
#define CATCH_AND_REPORT(client, default_ret)
#define RGPOT_FORTRAN_POT_CLASS(ClassName, PotTypeValue)
#define RGPOT_FORTRAN_POT_IMPL(ClassName, Entry, Label)
#define RGPOT_FORTRAN_SPECIES_POT_IMPL(ClassName, Entry, Label)
#define RGPOT_MTA_ABI_VERSION
#define RGPOT_MTA_API
#define RGPOT_MTA_ENGINE_BUILD
#define RGPOT_XTB_ABI_VERSION
#define RGPOT_XTB_API

Detailed Documentation¶

Typedefs¶

typedef struct CPMDCResult CPMDCResult

Result returned by energy / gradient / forces entry points.

typedef struct CPMDCSession CPMDCSession

Opaque handle for repeated evaluations with one Cap’n Proto parameter set.

typedef struct RgpotMtaConfig RgpotMtaConfig

Flat config (subset of MetatomicConfig). NULL strings => empty/default.

typedef struct NWChemCResult NWChemCResult

Result of energy+gradient (atomic units).

typedef struct PotClient PotClient

C API for the RPC potential client bridge.

This header provides a C-compatible interface to the distributed potential calculation client, allowing integration with Fortran or other languages with a C interface, e.g. Julia.

Opaque handle to the client context.

Global Functions¶

int cpmdc_set_params(const void* params_capnp, size_t params_capnp_size_bytes)

Apply CPMD method parameters from a Cap’n Proto message.

Parameters:

params_capnp	Pointer to an unpacked flat `CPMDParams` message.
params_capnp_size_bytes	Size of `params_capnp` in bytes.

Returns:

0 on success, -1 on parse or configuration failure.

CPMDCResult cpmdc_energy_gradient(int n_atoms, const double* positions_ang, const int* atomic_numbers, const void* params_capnp, size_t params_capnp_size_bytes, double* grad_h_bohr)

Compute energy and nuclear gradient for an atomic configuration.

Positions are Angstrom; gradient is Hartree/Bohr (CPMD ionic forces are negated into a nuclear gradient for API symmetry with nwchemc).

CPMDCResult cpmdc_energy(int n_atoms, const double* positions_ang, const int* atomic_numbers, const void* params_capnp, size_t params_capnp_size_bytes)

Compute total energy only (no gradient allocation).

CPMDCResult cpmdc_energy_forces(int n_atoms, const double* positions_ang, const int* atomic_numbers, const void* params_capnp, size_t params_capnp_size_bytes, double* forces_h_bohr)

Compute energy and nuclear forces (negative gradient, Hartree/Bohr).

CPMDCSession* cpmdc_session_create(const void* params_capnp, size_t params_capnp_size_bytes)

Create a persistent evaluation session from a Cap’n Proto message.

The session owns a copy of the serialized message so callers may release the input buffer after this call returns.

int cpmdc_session_set_params(CPMDCSession* session, const void* params_capnp, size_t params_capnp_size_bytes)

Replace Cap’n Proto parameters before the session accepts topology.

void cpmdc_session_destroy(CPMDCSession* session)

Release a persistent evaluation session.

CPMDCResult cpmdc_session_calculate_forces(CPMDCSession* session, const void* force_input_capnp, size_t force_input_capnp_size_bytes, double* forces_h_bohr, size_t forces_len)

Compute energy and forces for one Cap’n Proto ForceInput step.

Session keeps persistent CPMDParams; each call supplies geometry. Returned energy/forces use CPMD native units: Hartree and Hartree/Bohr.

CPMDCResult cpmdc_session_calculate_result(CPMDCSession* session, const void* force_input_capnp, size_t force_input_capnp_size_bytes, void* potential_result_capnp, size_t potential_result_capnp_capacity_bytes, size_t* potential_result_capnp_size_bytes)

Compute forces for one ForceInput step and write PotentialResult.

Direct-call socket entry point: method state in the session, geometry in ForceInput, output energy/forces converted to ForceInput.energyUnit and energyUnit / lengthUnit.

When potential_result_capnp_capacity_bytes is too small, returns ok == 0, writes the required byte count to potential_result_capnp_size_bytes, and does not evaluate CPMD.

CPMDCResult cpmdc_calculate_result(const void* params_capnp, size_t params_capnp_size_bytes, const void* force_input_capnp, size_t force_input_capnp_size_bytes, void* potential_result_capnp, size_t potential_result_capnp_capacity_bytes, size_t* potential_result_capnp_size_bytes)

One-shot Cap’n Proto entry point (params + ForceInput -> PotentialResult).

Multi-step callers should create one session and call cpmdc_session_calculate_result() per step.

size_t cpmdc_potential_result_size_for_force_input(const void* force_input_capnp, size_t force_input_capnp_size_bytes)

Byte count needed for a PotentialResult for the given ForceInput.

Parses geometry only; does not initialize or evaluate CPMD. Returns 0 when the message is invalid or too large for the C ABI.

const char* cpmdc_version(void)

Compiled library version string.

int cpmdc_available(void)

1 when the embedded OpenCPMD runtime is available.

void cpmdc_finalize(void)

Finalize an owned embedded CPMD runtime.

int cpmdc_set_params(const void* params_capnp, size_t params_capnp_size_bytes)

Apply CPMD method parameters from a Cap’n Proto message.

Parameters:

params_capnp	Pointer to an unpacked flat `CPMDParams` message.
params_capnp_size_bytes	Size of `params_capnp` in bytes.

Returns:

0 on success, -1 on parse or configuration failure.

CPMDCResult cpmdc_energy_gradient(int n_atoms, const double* positions_ang, const int* atomic_numbers, const void* params_capnp, size_t params_capnp_size_bytes, double* grad_h_bohr)

Compute energy and nuclear gradient for an atomic configuration.

Positions are Angstrom; gradient is Hartree/Bohr (CPMD ionic forces are negated into a nuclear gradient for API symmetry with nwchemc).

CPMDCResult cpmdc_energy(int n_atoms, const double* positions_ang, const int* atomic_numbers, const void* params_capnp, size_t params_capnp_size_bytes)

Compute total energy only (no gradient allocation).

CPMDCResult cpmdc_energy_forces(int n_atoms, const double* positions_ang, const int* atomic_numbers, const void* params_capnp, size_t params_capnp_size_bytes, double* forces_h_bohr)

Compute energy and nuclear forces (negative gradient, Hartree/Bohr).

const char* cpmdc_version(void)

Compiled library version string.

int cpmdc_available(void)

1 when the embedded OpenCPMD runtime is available.

void cpmdc_finalize(void)

Finalize an owned embedded CPMD runtime.

CPMDCSession* cpmdc_session_create(const void* params_capnp, size_t params_capnp_size_bytes)

Create a persistent evaluation session from a Cap’n Proto message.

The session owns a copy of the serialized message so callers may release the input buffer after this call returns.

int cpmdc_session_set_params(CPMDCSession* session, const void* params_capnp, size_t params_capnp_size_bytes)

Replace Cap’n Proto parameters before the session accepts topology.

void cpmdc_session_destroy(CPMDCSession* session)

Release a persistent evaluation session.

CPMDCResult cpmdc_session_calculate_forces(CPMDCSession* session, const void* force_input_capnp, size_t force_input_capnp_size_bytes, double* forces_h_bohr, size_t forces_len)

Compute energy and forces for one Cap’n Proto ForceInput step.

Session keeps persistent CPMDParams; each call supplies geometry. Returned energy/forces use CPMD native units: Hartree and Hartree/Bohr.

CPMDCResult cpmdc_session_calculate_result(CPMDCSession* session, const void* force_input_capnp, size_t force_input_capnp_size_bytes, void* potential_result_capnp, size_t potential_result_capnp_capacity_bytes, size_t* potential_result_capnp_size_bytes)

Compute forces for one ForceInput step and write PotentialResult.

Direct-call socket entry point: method state in the session, geometry in ForceInput, output energy/forces converted to ForceInput.energyUnit and energyUnit / lengthUnit.

When potential_result_capnp_capacity_bytes is too small, returns ok == 0, writes the required byte count to potential_result_capnp_size_bytes, and does not evaluate CPMD.

CPMDCResult cpmdc_calculate_result(const void* params_capnp, size_t params_capnp_size_bytes, const void* force_input_capnp, size_t force_input_capnp_size_bytes, void* potential_result_capnp, size_t potential_result_capnp_capacity_bytes, size_t* potential_result_capnp_size_bytes)

One-shot Cap’n Proto entry point (params + ForceInput -> PotentialResult).

Multi-step callers should create one session and call cpmdc_session_calculate_result() per step.

size_t cpmdc_potential_result_size_for_force_input(const void* force_input_capnp, size_t force_input_capnp_size_bytes)

Byte count needed for a PotentialResult for the given ForceInput.

Parses geometry only; does not initialize or evaluate CPMD. Returns 0 when the message is invalid or too large for the C ABI.

program test_cuh2()

Physics checks for the CuH2 embedded-atom gather kernel, run from pure Fortran so a failure points at the kernel rather than the bindings.

Checked: translational invariance of the energy, vanishing net force, invariance under a relabelling of the atoms, and agreement between the analytic forces and a central difference of the energy.

The finite-difference check is the acceptance gate for the gather rearrangement. An embedding force attributed to the wrong end of a pair leaves the energy exactly right, keeps the net force at zero, and shows up only here.

The reordering check is the gate for the species dispatch: energies and forces are compared against a run with the atom list reversed, so H no longer occupies the trailing indices.

subroutine cu_slab_with_h2(integer, intent(in) cells, real(wp), intent(in) a, real(wp), intent(in) gap, real(wp), intent(in) height, real(wp), intent(in) bond, real(wp), dimension(:, :), intent(out), allocatable pos, integer(ip), dimension(:), intent(out), allocatable z, real(wp), dimension(3, 3), intent(out) box)

FCC Cu slab of cells conventional cells per direction, with a vacuum gap stacked on top and an H2 molecule inside it.

The gap exceeds the 6.1 Angstrom cutoff, so the slab does not see its own periodic image through the vacuum.

program test_eam_al()

Physics checks for the embedded-atom aluminium gather kernel, run from pure Fortran so a failure points at the kernel rather than the bindings.

Checked: the force vanishes on the ideal FCC lattice, the net force vanishes on a rattled periodic cell, the energy is translation invariant, and the analytic forces agree with a central difference of the energy. The finite-difference check is the gate on the gather rearrangement: dropping a neighbour’s embedding derivative from f_i leaves the energy exactly right and the force wrong by order one.

subroutine fcc_lattice(integer, intent(in) cells, real(wp), intent(in) a, real(wp), dimension(:, :), intent(out), allocatable pos, real(wp), dimension(3, 3), intent(out) box)

Face-centred cubic lattice, cells conventional cells per direction.

program test_edip()

Physics checks for the EDIP gather kernel, run from pure Fortran so a failure points at the kernel rather than the bindings.

Checked: translational invariance of the energy, vanishing net force, and agreement between the analytic forces and a central difference of the energy. The checks run on a rattled diamond lattice, not the perfect one: at equilibrium every force vanishes by symmetry and the difference check compares zero against zero, which passes whatever the force expression says. Off equilibrium it pins the gather rearrangement, since a mis-attributed coordination or end-atom term breaks the difference check even where the energy stays right.

subroutine diamond_lattice(integer, intent(in) cells, real(wp), intent(in) a, real(wp), dimension(:, :), intent(out), allocatable pos, real(wp), dimension(3, 3), intent(out) box)

Diamond-cubic lattice, n_side conventional cells per direction.

program test_fehe()

Physics checks for the Fe-He gather kernel, run from pure Fortran so a failure points at the kernel rather than the bindings.

Checked: translational invariance of the energy, vanishing net force, agreement between the analytic forces and a central difference of the energy, and rejection of an atomic number the potential does not cover. The finite-difference check is the gate: an embedded-atom force splits into a pair part and two embedding parts weighted by dF/drho at both ends of the pair, and dropping either end leaves the energy correct.

The cell is body-centred iron with two substitutional helium atoms on a nearest-neighbour <111>/2 bond, which puts force into all three pair channels and both density channels at once. Four cells a side keeps the largest cutoff (5.4 A, He-He) below half the box edge (5.71 A), so each pair enters the neighbour table exactly once per direction and the check measures the potential rather than vesin’s multiple-image path.

subroutine bcc_lattice(integer, intent(in) cells, real(wp), intent(in) a, real(wp), dimension(:, :), intent(out), allocatable pos, real(wp), dimension(3, 3), intent(out) box)

Body-centred cubic lattice, cells conventional cells per direction. Site 1 is the corner of the first cell and site 2 its body centre, so substituting the first two atoms puts helium on a nearest-neighbour bond.

program test_lenosky()

Physics checks for the Lenosky gather kernel, run from pure Fortran so a failure points at the kernel rather than the bindings.

Checked: translational invariance of the energy, vanishing net force, and agreement between the analytic forces and a central difference of the energy. The checks run on a rattled diamond lattice, not the perfect one: at equilibrium every force vanishes by symmetry and the difference check compares zero against zero, which passes whatever the force expression says. Off equilibrium it pins the gather rearrangement, since a mis-attributed embedding or end-atom term breaks the difference check even where the energy stays right.

subroutine diamond_lattice(integer, intent(in) cells, real(wp), intent(in) a, real(wp), dimension(:, :), intent(out), allocatable pos, real(wp), dimension(3, 3), intent(out) box)

Diamond-cubic lattice, n_side conventional cells per direction.

program test_sw_gather()

Physics checks for the Stillinger-Weber gather kernel, run from pure Fortran so a failure points at the kernel rather than the bindings.

Checked: translational invariance of the energy, vanishing net force, and agreement between the analytic forces and a central difference of the energy. Together these pin the gather rearrangement: a mismatched end-atom term would break the finite-difference check even where the energy stayed right.

subroutine diamond_lattice(integer, intent(in) cells, real(wp), intent(in) a, real(wp), dimension(:, :), intent(out), allocatable pos, real(wp), dimension(3, 3), intent(out) box)

Diamond-cubic lattice, n_side conventional cells per direction.

program test_tersoff()

Physics checks for the Tersoff gather kernel, run from pure Fortran so a failure points at the kernel rather than the bindings.

Checked: translational invariance of the energy, vanishing net force, and agreement between the analytic forces and a central difference of the energy. The finite-difference check is the acceptance gate. A bond-order term attributed to the wrong atom leaves the energy exactly right, keeps the net force zero whenever the misattribution is antisymmetric, and shows up only here.

Two configurations carry the checks. The diamond lattice at its experimental constant places every bond inside the inner taper radius, where the cutoff function is flat and its derivative drops out; the expanded lattice places bonds in the taper window so the cutoff derivative enters both the pair term and the coordination sum. Both carry a fixed jitter, because a force that vanishes by symmetry tests nothing.

subroutine diamond_lattice(integer, intent(in) cells, real(wp), intent(in) a, real(wp), dimension(:, :), intent(out), allocatable pos, real(wp), dimension(3, 3), intent(out) box)

Diamond-cubic lattice, n_side conventional cells per direction.

program test_water_h()

Physics checks for the H-in-water star gather, run from pure Fortran so a failure points at the kernel rather than the bindings.

Checked: translational invariance of the energy, vanishing net force, agreement between the analytic forces and a central difference of the energy, independence of the energy from the order the water sites arrive in, and rejection of atom lists that are not a water plus H system.

The finite-difference check is the one that can fail. Newton’s third law holds by construction here (the lone H is handed the negated sum of the legs), so a vanishing net force says nothing about whether the radial derivatives are right; the central difference does.

subroutine water_plus_h(real(wp), dimension(3, natoms), intent(out) pos, integer(ip), dimension(natoms), intent(out) atomic_numbers, real(wp), dimension(3, 3), intent(out) cellv)

Two water molecules and one extra H in a cubic cell, laid out in the order the entry point expects: the hydrogens of every molecule, then the oxygens, then the lone H.

__attribute__((visibility(“default”)))

Energy + forces. Returns 0 on success. variance may be NULL.

int nwchemc_set_params(const void* params_capnp, size_t params_capnp_size_bytes)

Apply sticky method options from an unpacked flat NWChemParams message.

Returns:

0 on success, non-zero if embed unavailable or params are invalid

NWChemCResult nwchemc_energy_gradient(int n_atoms, const double* positions_ang, const int* atomic_numbers, const void* params_capnp, size_t params_capnp_size_bytes, double* grad_h_bohr)

Energy + nuclear gradient.

Parameters:

n_atoms	atom count
positions_ang	n_atoms*3 Angstrom, row-major xyz
atomic_numbers	n_atoms Z values
params_capnp	unpacked flat `NWChemParams` message
params_capnp_size_bytes	size of params_capnp in bytes
grad_h_bohr	out n_atoms*3 Hartree/Bohr, row-major

const char* nwchemc_version(void)

Engine version string (static buffer).

int nwchemc_available(void)

1 if real embed (RGPOT_HAS_NWCHEM), 0 if stub.

int nwchemc_set_params(const void* params_capnp, size_t params_capnp_size_bytes)

Apply sticky method options from an unpacked flat NWChemParams message.

Returns:

0 on success, non-zero if embed unavailable or params are invalid

NWChemCResult nwchemc_energy_gradient(int n_atoms, const double* positions_ang, const int* atomic_numbers, const void* params_capnp, size_t params_capnp_size_bytes, double* grad_h_bohr)

Energy + nuclear gradient.

Parameters:

n_atoms	atom count
positions_ang	n_atoms*3 Angstrom, row-major xyz
atomic_numbers	n_atoms Z values
params_capnp	unpacked flat `NWChemParams` message
params_capnp_size_bytes	size of params_capnp in bytes
grad_h_bohr	out n_atoms*3 Hartree/Bohr, row-major

const char* nwchemc_version(void)

Engine version string (static buffer).

int nwchemc_available(void)

1 if real embed (RGPOT_HAS_NWCHEM), 0 if stub.

PotClient* pot_client_init(const char* host, int32_t port)

Initializes the RPC client connection.

Constructs a string-based address from the host and port, then initializes a new capnp::EzRpcClient. The main capability is cast to the Potential interface defined in the schema.

Note

Returns nullptr if the connection cannot be established or if the address is malformed.

void pot_client_free(PotClient* client)

Frees all resources associated with the client.

Performs a standard delete on the client pointer. This triggers the PotClient destructor, which cleans up the unique_ptr and associated RPC state.

int32_t pot_calculate(PotClient* client, int32_t natoms, const double* pos, const int32_t* atmnrs, const double* box, double* out_energy, double* out_forces)

Executes a remote potential calculation.

This function performs the following steps:

Resets the last_error buffer.
Initializes a calculation request.
Maps the input pointers to kj::arrayPtr views to avoid unnecessary copying before serialization.
Waits for the RPC promise to resolve.
Validates the size of the returned force array.
Copies the results into the provided output buffers.

Warning

The server must return a force array matching natoms * 3. If the sizes do not match, a non-zero error code is returned.

const char* pot_get_last_error(PotClient* client)

Retrieves the most recent error message.

Checks if a valid client handle is provided and if the last_error buffer contains data. If no error is recorded, an empty string is returned.

PotClient* pot_client_init(const char* host, int32_t port)

Initializes the RPC client connection.

Constructs a string-based address from the host and port, then initializes a new capnp::EzRpcClient. The main capability is cast to the Potential interface defined in the schema.

Note

Returns nullptr if the connection cannot be established or if the address is malformed.

Parameters:

host	Target server hostname or IP address.
port	Network port of the potential server.

Returns:

Pointer to the client context or NULL on failure.

Usage¶

````./potserv <port> <PotentialType>

Parameters:

argc	Argument count.
argv	Argument vector.

Returns:

0 on success, 1 on initialization failure.

__attribute__((visibility(“default”)))

Energy + forces. Returns 0 on success. variance may be NULL.

client	The opaque client handle.
natoms	Total number of atoms in the system.
pos	Array of flattened atomic coordinates.
atmnrs	Array of atomic numbers.
box	Simulation cell vectors in row-major order.
out_energy	Pointer to store the calculated energy.
out_forces	Buffer to store the calculated forces.