rgpot
namespace rgpot¶
Overview¶
Capability handshake applied while loading a profile backend; the expectation, check and producer helpers live in Handshake.hpp. More…
namespace rgpot {
// namespaces
namespace rgpot::abi;
namespace rgpot::abi::detail;
namespace rgpot::aoti_execstack;
namespace rgpot::cache;
namespace rgpot::detail;
namespace rgpot::details;
namespace rgpot::engine;
namespace rgpot::fortranpots;
namespace rgpot::nlist;
namespace rgpot::plugin;
namespace rgpot::plugin::detail;
namespace rgpot::plugin::dynlib;
namespace rgpot::simd;
namespace rgpot::simd::detail;
namespace rgpot::tools;
namespace rgpot::types;
namespace rgpot::types::adapt;
namespace rgpot::types::adapt::capnp;
namespace rgpot::types::adapt::eigen;
namespace rgpot::types::adapt::xtensor;
namespace rgpot::uma;
namespace rgpot::units;
namespace rgpot::vesin_compat;
// typedefs
typedef std::function<std::unique_ptr<PotentialBase>()> PotentialFactory;
typedef int(*)(int ranks_per_calculator) CalculatorHook;
typedef int(*)(const void*, std::size_t, int) CalculatorCommAdopter;
// enums
enum D3Damping;
enum GFNMethod;
enum Reentrancy;
enum TBLiteMethod;
enum TorchDeterminismPolicy;
// structs
struct BatchInput;
struct BatchResult;
struct CalculatorGroup;
struct D3Config;
struct D4Config;
struct EAMCellConfig;
struct EMTConfig;
struct Fnv1a;
struct ForceBatch;
struct ForceInput;
struct ForceOut;
struct LJClusterConfig;
struct LJConfig;
struct MetatomicConfig;
struct MorseConfig;
struct PotCaps;
struct QuinticSwitch;
struct SkalaConfig;
struct TBLiteConfig;
struct UmaConfig;
struct WaterConfig;
struct XTBConfig;
struct XTBDlopenConfig;
struct XcFields;
struct XcGrid;
struct XcMo;
struct ZBLConfig;
struct ZblPairCoeffs;
struct ZblTables;
// classes
class BatchEvaluator;
class CPMDPot;
class CalcResult;
class D3Pot;
class D4Pot;
class DynLib;
class EAMPot;
class EMTPot;
class Error;
class ExprPot;
class InputSpec;
class LJClusterPot;
class LJPot;
class MOPACPot;
class MetatomicDlopen;
class MetatomicPot;
class MorsePot;
class NWChemPot;
class PotentialBase;
class PotentialHandle;
class RpcClient;
class SPCEPot;
class SkalaPot;
class TBLitePot;
class TIP4PPot;
class TIP4PPtPot;
class UmaPot;
class XTBDlopen;
class XTBPot;
class XcKernel;
class ZBLPot;
template <typename T>
class registry;
// global variables
std::atomic<size_t> registry< T >::count {0};
std::atomic<size_t> registry< T >::forceCalls {0};
T* registry< T >::head = nullptr;
double HARTREE_PER_BOHR3_TO_EV_PER_ANGSTROM3;
double KB_HARTREE;
double ANGSTROM_TO_BOHR;
double HARTREE_TO_EV;
double NEG_GRAD_TO_FORCE;
// global functions
int loadCalculatorMpi(const char* path);
std::string calculatorMpiLoadError();
int calculatorMpiLoaded();
void addCalculatorHook(CalculatorHook hook);
bool addCalculatorCommAdopter(CalculatorCommAdopter callback);
CalculatorGroup bindCalculators(int ranks_per_calculator);
const CalculatorGroup& thisCalculator();
int calculatorComm(void* comm_out, std::size_t comm_bytes);
int adoptCalculatorComm(CalculatorCommAdopter callback);
int calculatorsUseMpi();
int calculatorWorldSize();
int calculatorCount();
int shareFromCalculator(int owner, void* data, std::size_t bytes);
void finalizeMpiAtExit();
void abortMpiAtExit();
bool mpiAbortRequested();
int calculatorAgree(unsigned char* flags, std::size_t n);
void publishCalculatorError(const std::string& message);
void apply_torch_determinism_policy(TorchDeterminismPolicy policy);
EngineBundle& probe_engine_bundle();
void zeroForceOut(const size_t& nAtoms, ForceOut* efvd);
void checkParams(const ForceInput& params);
double cellVolume(const double* box);
void accumulatePairStrain(double acc[6], double fscale, double dx, double dy, double dz);
void publishCauchyStress(ForceOut* out, const double acc[6], double volume);
} // namespace rgpot
Detailed Documentation¶
Capability handshake applied while loading a profile backend; the expectation, check and producer helpers live in Handshake.hpp.
Header file for the screened nuclear repulsion (ZBL) potential.
Implementation of the ZBL potential methods.
Definition of the native AtomMatrix class.
Conversion utilities between xtensor and native types.
Conversion utilities between Eigen and native types.
Conversion utilities between Cap’n Proto and native types.
Utility templates and functions for potential management.
Implementation of utility functions for potential management.
Base classes and templates for chemical potentials.
Capability descriptors for potential implementations.
Field-by-field FNV-1a hashing for potential parameter sets.
C^2 quintic switch that takes a pair term smoothly to zero at its cutoff.
NWChem potential under rgpot PotentialConfig user parameters.
Portable dynamic library loader (dlopen / LoadLibrary family).
Header file for the Morse potential class.
Implementation of the Morse potential methods.
OpenMOPAC frontend. Pure consumer of libmopacc.so.
Header file for the Lennard-Jones potential class.
Header file for the free-boundary Lennard-Jones cluster potential.
Implementation of the free-boundary Lennard-Jones cluster potential.
C++ faces for the Fortran 2018 potential kernels.
POD structures for force and energy calculation interfaces.
Named-child PES algebra compiled with OpenMM Lepton.
CPMD potential under rgpot PotentialConfig user parameters.
Parallel evaluation of independent configurations.
Prefix-parameterized loader for the minimum potential ABI profile.
Capability handshake for backends loaded through the potential profile: decide from a Capabilities message whether this build can drive the backend before any work is dispatched, and fill the same message from the producing side.
Metadata a backend leaves unset (empty family, zero bridge major) is not a declaration and is not checked. The constants mirror the eindir-core objective ABI stamp that rgpot-core compares against.
Backends (nwchemc, cpmdc, future lammpsc/gromacsc) export the same C symbol set prefix-parameterized on <p> (see potentials-schema PROFILE.md). This loader resolves that whole set from one dlopen’d shared library, so rgpot drives every conforming backend through identical function pointers with no per-backend loader code. Everything stays native: flat binary Cap’n Proto messages both directions, plain C calls in-process.
A BatchEvaluator owns one potential instance per worker, created by a caller-supplied factory, and splits the configurations of one call into contiguous ranges, one range per worker. Instances share nothing, so no potential has to be re-entrant across threads; a potential that reports PotCaps::reentrancy as process-serial is safe here because each instance is touched by one thread at a time.
rgpot::BatchEvaluator eval(
[] { return std::make_unique<rgpot::LJPot>(); }, 4);
auto results = eval.evaluate(inputs); // results[i] answers inputs[i]
A worker that throws stops its range; evaluate() rethrows the exception of the lowest-numbered failing worker after every worker has joined.
One independent calculator is one group. A NEB image or a dimer end is that group, and ranks in a group share a subcommunicator. bindCalculators is collective on MPI_COMM_WORLD. Every rank calls it before the first force. shareFromCalculator broadcasts from the first rank of calculator owner onto MPI_COMM_WORLD. forceImpl fills ForceOut on the rank that calls it.
librgpot never links MPI. The MPI side lives in librgpot_mpi (meson dependency and pkg-config name rgpot-mpi), which bindCalculators and calculatorsUseMpi load with dlopen on first use through the C ABI in calculator_mpi_abi.h. A process that never calls them never maps libmpi; until the library is loaded every call below behaves as in a build without MPI.
ExprPot is a Potential. Terms are unique_ptr<PotentialBase> only.
Defines the core data exchange structures used between the high-level potential wrappers and the low-level physics engines.
Each kernel exposes one bind(c) entry taking flat buffers and returning a status. Those entries stay inside librgpot: forceImpl is defined out of line, and the archive holding the Fortran objects is linked with --exclude-libs, so no Fortran symbol reaches the dynamic table and consumers reach the kernels only through these classes.
Each instance owns a Fortran workspace (rgpot_workspace.f90): its own neighbour table, which vesin keeps between calls and rebuilds only when an atom leaves the Verlet skin, and its own error message. The kernels carry no other state, so instances evaluate on separate threads at once (Reentrancy::PerInstance), and multi-image callers keep one instance per image (perImageInstances) so each table follows one geometry instead of every image rebuilding a shared one.
Ported from eOn (https://github.com/TheochemUI/eOn, client/potentials/LJCluster), BSD-3-Clause licensed, copyright the eOn Development Team.
This file defines the LJClusterPot class, a 12-6 Lennard-Jones potential evaluated without periodic boundary conditions. The kernel is ported from eOn (https://github.com/TheochemUI/eOn, client/potentials/LJCluster), BSD-3-Clause licensed, copyright the eOn Development Team.
This file defines the LJPot class, which implements a standard 12-6 Lennard-Jones potential with a shifted cutoff for use in atomic simulations.
Packed MopacCParams. Default model is AM1.
Ported from eOn (https://github.com/TheochemUI/eOn, client/potentials/Morse), BSD-3-Clause licensed, copyright the eOn Development Team.
This file defines the MorsePot class, which implements the pairwise Morse potential with a shifted cutoff. The kernel is ported from eOn (https://github.com/TheochemUI/eOn, client/potentials/Morse), BSD-3-Clause licensed, copyright the eOn Development Team; the original attribution names A. Pedersen or G. Henkelman, revised by J.-C. C. Berthet (2010, University of Iceland).
Used by NWChemPot to resolve libnwchemc at runtime without a build-time link dependency on NWChem.
User path: Cap’n Proto PotentialConfig / NWChemParams only. The frontend serializes that message and passes it through C ABI symbols resolved by dlopen.
With \(t = (r - r_\mathrm{on}) / (r_c - r_\mathrm{on})\) clamped to \([0, 1]\),
The coefficients are the unique quintic with \(S(0) = 1\), \(S'(0) = S''(0) = 0\) and \(S(1) = S'(1) = S''(1) = 0\), so \(V(r) S(t(r))\) and its first two derivatives are continuous at \(r_\mathrm{on}\) and vanish at \(r_c\) for any smooth \(V\). scripts/validation/pair_kernels.py derives them and checks the C^2 conditions symbolically; scripts/validation/quintic_switch.sollya bounds the binary64 evaluation error of the Horner forms used here.
The clamp is a min/max pair, so evaluation carries no branch: below \(r_\mathrm{on}\) it returns \(S = 1\), \(dS/dr = 0\) exactly.
Potentials fingerprint their configuration into PotentialBase::paramsKey() so cached results never cross parameter sets. Hash field by field — never memcpy a struct (padding bytes).
Consumers that evaluate potentials from multiple threads (NEB images, dimer endpoints, batched searches) read these instead of maintaining per-potential blocklists.
Provides the abstract interface and CRTP template for all potential energy surfaces. Handles the high-level logic for caching, hashing, and force call registration.
Contains the implementations for global helper functions used to manage and validate the core force and energy data structures.
Defines a static registry for tracking potential instances and global force call counters. It also provides utility functions for structure initialization and validation.
Cauchy stress from a pair force.
sigma = (1/V) dE/dε for the right strain that sends a row of Cartesian coordinates r to r (I+ε). A pair whose force on atom i is fscale * d, with d = r_i - r_j, contributes -fscale * d ⊗ d to dE/dε.
This file contains inline adapter functions designed to facilitate the seamless transfer of data between the Cap’n Proto RPC layer and the internal Eigen based AtomMatrix and other STL types.
This file contains inline adapter functions for integrating the Eigen linear algebra library with the native AtomMatrix and std::vector types used in the rgpot library.
This file provides adapters for the xtensor library, enabling interoperability between multidimensional arrays and rgpot data structures.
This file defines a lightweight, row-major matrix class designed for storing atomic coordinates and forces.
Ported from eOn (https://github.com/TheochemUI/eOn, client/potentials/ZBL), BSD-3-Clause licensed, copyright the eOn Development Team, which adapts the GPL-licensed LAMMPS pair_zbl kernel. Constants follow LAMMPS metal units: eV, Angstrom.
This file defines the ZBLPot class, a universal screened Coulomb repulsion with the LAMMPS switching function. Based on J. F. Ziegler, J. P. Biersack and U. Littmark, “The Stopping and Range of Ions in
Matter”, Pergamon (1985). The kernel is ported from eOn (https://github.com/TheochemUI/eOn, client/potentials/ZBL), BSD-3-Clause licensed, copyright the eOn Development Team, which in turn adapts the GPL-licensed LAMMPS pair_zbl implementation.
Typedefs¶
typedef std::function<std::unique_ptr<PotentialBase>()> PotentialFactory
Creates one independent potential instance.
Global Functions¶
CalculatorGroup bindCalculators(int ranks_per_calculator)
Collective on MPI_COMM_WORLD when the process was started under MPI. ranks_per_calculator <= 0 means one group for the whole world. Returns index -1 when the world cannot be divided that way.
int shareFromCalculator(int owner, void* data, std::size_t bytes)
Broadcasts bytes from the first rank of calculator owner to every rank of MPI_COMM_WORLD, so all ranks hold that calculator’s result. Collective on MPI_COMM_WORLD. When more than one rank is bound, a rank that cannot enter the broadcast aborts the world after every rank prints the error. Returns 0 without MPI, before a split, or for a bad owner in a single process. Returns 1 once the bytes are in place.
void zeroForceOut(const size_t& nAtoms, ForceOut* efvd)
Zeroes the members of a ForceOut structure.
This function performs a manual reset of the ForceOut structure. It ensures the energy and variance are set to zero and iterates through the force array to clear components for each atom.
Parameters:
nAtoms |
The number of atoms. |
efvd |
The results structure to reset. |
Returns:
Void.
void checkParams(const ForceInput& params)
Validates the input parameters for a potential calculation.
Verifies that the input parameters represent a physically valid configuration. Currently, it strictly checks that the system contains at least one atom.
Warning
Throws a std::runtime_error if nAtoms is zero or less.
Parameters:
params |
The configuration structure to check. |
Returns:
Void.
double cellVolume(const double* box)
Absolute cell volume. The 3×3 box is row-major, index = 3 * row + column.
void accumulatePairStrain(double acc[6], double fscale, double dx, double dy, double dz)
Add one pair to the six Voigt components of dE/dε: xx, yy, zz, yz, xz, xy.
void publishCauchyStress(ForceOut* out, const double acc[6], double volume)
Write acc/volume into the row-major ForceOut stress. A nonpositive volume leaves has_stress clear.