C++ engine-backed potentials¶
These potentials call an external program or library: a quantum-chemistry
engine, a tight-binding library, a machine-learned model or a socket peer.
Every class derives from rgpot::Potential<Derived>, except the dlopen
frontends XTBDlopen and MetatomicDlopen, which have no base class and
declare forceImpl themselves.
The members they inherit (forceImpl, forceBatch, caps, the call operator)
are described with the base class; this page lists only the members each class
declares itself.
The in-process kernels are in C++ potentials.
Unless an entry says otherwise, a class takes positions and the cell in Angstrom
(cell vectors as rows) and returns the energy in eV and the forces in
eV/Angstrom. Engines that work in atomic units get positions converted with units::ANGSTROM_TO_BOHR, the energy with units::HARTREE_TO_EV and gradients with units::NEG_GRAD_TO_FORCE (minus Hartree/bohr
to eV/Angstrom), all from CppCore/rgpot/units.hpp.
How each class finds its engine¶
The dlopen frontends try a list of library names in order.
A bare name is resolved by the dynamic linker search path.
CP2KPot, CPMDPot, MOPACPot, NWChemPot, XTBDlopen and MetatomicDlopen
stop at the first library that opens and then check its symbols, so a library
with missing symbols ends the search.
LammpsPot, GromacsPot and OpenMMPot skip a library that lacks the symbols
and try the next name.
Class |
Library |
Search order |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
as |
|
engine plugin |
|
|
|
|
|
|
as |
|
|
|
|
|
|
After the .so names the CP2K, CPMD, MOPAC and NWChem lists also try the
.dylib names (bare and with ./), and CPMD, MOPAC and NWChem try cpmdc.dll,
mopacc.dll and nwchemc.dll.
LammpsPot uses .dylib names on macOS and .dll names on Windows instead of
.so.
XTBDlopen and MetatomicDlopen try the .dylib name before the .so name on
macOS, and on Windows try xtb_engine.dll and libxtb_engine.dll
(metatomic_engine.dll and libmetatomic_engine.dll) in place of the .so
name.
TBLitePot and XTBPot link libtblite and libxtb at build time.
MetatomicPot and UmaPot link libtorch.
XTBDlopen and MetatomicDlopen are in every librgpot and need neither;
their engine libraries carry the C ABIs in
Engine C ABI.
IPIPot opens a socket and waits for a driver.
None of the dlopen constructors throw when the library is missing.
They record the reason, available() returns false, and the first force throws
std::runtime_error with that reason.
The exceptions are LammpsPot, GromacsPot and OpenMMPot with an
engine_path: their constructors throw std::runtime_error when no library
opens.
XTBDlopen and MetatomicDlopen also throw from the constructor, so
available() is true for every object they construct.
CP2K¶
rgpot::CP2KPot¶
CP2KPot();
explicit CP2KPot(const ::CP2KParams::Reader ¶ms);
- Inputs
optional
CP2KParams(Cap’n Proto); the default constructor uses the schema defaults.- Units
positions and cell in Angstrom, energy in eV, forces in eV/Angstrom. The class converts positions and cell to bohr, and the shim’s Hartree energy and Hartree/bohr forces back. The shim returns forces, so there is no sign change.
- Outputs
a potential that runs CP2K Quickstep through the
libcp2kc_rgpotshim.- Errors
the constructors do not throw when the shim is missing; see
loadError. A force throwsrgpot::CP2KScfError(astd::runtime_error) when the SCF does not converge, on every rank of the calculator. Any other failure throwsstd::runtime_error: shim not loaded, a badinputTemplate,nAtomsof zero, a null buffer, a refused calculator binding, the shim refusing the deck or the orbital key, or a nonzero shim status.
The shim must report cp2kc_abi_version() equal to CP2KC_ABI_VERSION and
export the session functions, and cp2kc_available(), when exported, must be
nonzero.
The deck is rendered from the params (or from inputTemplate, which must
contain both @RGPOT_COORD@ and @RGPOT_CELL@) on the first force and again
whenever the sequence of atomic numbers changes.
A non-empty dataDir sets CP2K_DATA_DIR before the session starts.
The build option is -Dwith_cp2k=enabled and it needs -Dwith_rpc=true.
rgpot::CP2KPot::setParams¶
bool setParams(const ::CP2KParams::Reader ¶ms);
- Inputs
params, the nextCP2KParams.- Units
as the message fields (
cutoffRyin Rydberg); the call converts nothing.- Outputs
true when the shim is loaded and the params are usable. False when the shim cannot be loaded, or
inputTemplatelacks@RGPOT_COORD@or@RGPOT_CELL@. The params are stored either way.- Errors
no exception of its own; failures are reported by the return value and
loadError.
The live session is destroyed when the serialized params differ or enginePath
changes; otherwise it keeps its wavefunctions.
The shim is loaded again when it was not loaded or enginePath changed.
rgpot::CP2KPot::getParams¶
void getParams(::CP2KParams::Builder out) const;
- Inputs
out, a builder to fill.- Units
as the message fields.
- Outputs
outholds every field of the stored params, includingenginePath.- Errors
none.
rgpot::CP2KPot::available¶
bool available() const;
- Inputs
none.
- Units
none.
- Outputs
true when the shim is loaded and the params are usable.
- Errors
none.
rgpot::CP2KPot::loadError¶
std::string loadError() const;
- Inputs
none.
- Units
none.
- Outputs
why
available()is false: the shim load error when the shim is not loaded, else the template error; empty when available.- Errors
none.
rgpot::CP2KPot::runDirectory¶
std::string runDirectory() const;
- Inputs
none.
- Units
none.
- Outputs
the directory that holds the live session’s input and CP2K output; empty before the first force.
- Errors
none.
The directory is rgpot-cp2k-<pid>-g<group>-r<rank>-i<serial> under workDir,
else under TMPDIR, else under the system temporary directory.
It is removed when the session ends unless keepWorkDir is set.
CPMD¶
rgpot::CPMDPot¶
CPMDPot();
explicit CPMDPot(const ::CPMDParams::Reader ¶ms);
- Inputs
optional
CPMDParams(Cap’n Proto); the default constructor uses the schema defaults.- Units
positions in Angstrom, energy in eV, forces in eV/Angstrom, stress in eV/Angstrom3. With the session ABI, rgpot sends a
ForceInputtaggedangstromandeVand the engine returns those units. With the one-shot ABI, positions go in Angstrom and the class converts the Hartree energy and the Hartree/bohr gradient. It also converts a Hartree/bohr3stress when the engine exportscpmdc_last_stressand reports a valid tensor.- Outputs
a potential that runs CPMD through
libcpmdc.- Errors
the constructors do not throw when the engine is missing. A force throws
std::runtime_errorwhen the engine is not available,nAtomsis zero, a buffer is null, the calculator binding was refused, the orbital key is refused, the engine reports failure, or the returnedPotentialResultis malformed or has the wrong force count.
The engine must export the feature discovery functions (cpmdc_feature_count,
cpmdc_feature_table, cpmdc_feature_find) and either the session result ABI
or cpmdc_energy_gradient with cpmdc_set_params.
A non-empty cpmdRoot sets CPMD_ROOT.
The one-shot ABI does not receive the cell.
The class is built when -Dwith_rpc=true.
rgpot::CPMDPot::setParams¶
bool setParams(const ::CPMDParams::Reader ¶ms);
- Inputs
params, the nextCPMDParams.- Units
as the message fields (
cutOffRyin Rydberg); the call converts nothing.- Outputs
true when the engine is loaded and accepts the params (a session is created, or
cpmdc_set_paramsreturns 0).- Errors
no exception of its own; a false return covers a missing engine and a refusal.
The engine is loaded again when it was not loaded or enginePath changed.
A live session is kept when the engine path and the serialized params are
unchanged.
rgpot::CPMDPot::getParams¶
void getParams(::CPMDParams::Builder out) const;
- Inputs
out, a builder to fill.- Units
as the message fields.
- Outputs
outholds the stored params, includingenginePathandcpmdRoot.- Errors
none.
rgpot::CPMDPot::available¶
bool available() const;
- Inputs
none.
- Units
none.
- Outputs
true when the engine is loaded and, for the session ABI, a session exists; for the one-shot ABI, when both one-shot functions are present.
- Errors
none.
MOPAC¶
rgpot::MOPACPot¶
MOPACPot();
explicit MOPACPot(const Config &cfg);
- Inputs
Configwithcharge,spin,model(0 PM7, 1 PM6-D3H4, 2 PM6-ORG, 3 PM6, 4 AM1, 5 RM1; default 4),tolerance,max_timeandengine_path.- Units
positions in Angstrom, energy in eV, forces in eV/Angstrom.
libmopaccreturns Hartree and a Hartree/bohr gradient, which the class converts. The cell is not sent; the class reportsperiodic = false.- Outputs
a potential that runs OpenMOPAC through
libmopacc.- Errors
the constructors do not throw when the engine is missing. A force throws
std::runtime_errorwhen the engine is not loaded,nAtomsis zero, a buffer is null, or the engine reports failure.
The library must export mopacc_energy_gradient.
When it exports
mopacc_c_abi_version, the version must equal RGPOT_MOPACC_C_ABI_VERSION, and when it exports mopacc_available,
that must be nonzero.
The constructor passes the params once through mopacc_set_params when present
and ignores its status.
rgpot::MOPACPot::available¶
bool available() const;
- Inputs
none.
- Units
none.
- Outputs
true when
libmopaccis loaded and exportsmopacc_energy_gradient.- Errors
none.
NWChem¶
rgpot::NWChemPot¶
NWChemPot();
explicit NWChemPot(const ::NWChemParams::Reader ¶ms);
- Inputs
optional
NWChemParams(Cap’n Proto); the default constructor uses the schema defaults.- Units
positions in Angstrom, energy in eV, forces in eV/Angstrom.
libnwchemcreturns Hartree and a Hartree/bohr gradient, which the class converts. The cell is not sent; the class reportsperiodic = false.- Outputs
a potential that runs NWChem through
libnwchemc.- Errors
the constructors do not throw when the engine is missing. A force throws
std::runtime_errorwhen the engine is not loaded,nAtomsis zero, a buffer is null, ornwchemc_energy_gradientreports failure.
The library must export nwchemc_energy_gradient and nwchemc_set_params.
A loaded library stays mapped for the life of the process.
enginePath and nwchemRoot are cleared from the message the engine receives.
A non-empty nwchemRoot sets NWCHEM_TOP, and sets NWCHEM_BASIS_LIBRARY to
<nwchemRoot>/src/basis/libraries/ when that variable is unset or empty.
The class is built when -Dwith_rpc=true.
rgpot::NWChemPot::setParams¶
bool setParams(const ::NWChemParams::Reader ¶ms);
- Inputs
params, the nextNWChemParams.- Units
as the message fields; the call converts nothing.
- Outputs
true when the engine is loaded and
nwchemc_set_paramsreturns 0. The params are stored either way and are sent again with every force.- Errors
no exception of its own; a false return covers a missing engine and a refusal.
A library that is already loaded is kept, so a changed enginePath has no
effect after the first successful load.
rgpot::NWChemPot::getParams¶
void getParams(::NWChemParams::Builder out) const;
- Inputs
out, a builder to fill.- Units
as the message fields.
- Outputs
outholds the stored params, includingenginePathandnwchemRoot.- Errors
none.
rgpot::NWChemPot::available¶
bool available() const;
- Inputs
none.
- Units
none.
- Outputs
true when
libnwchemcis loaded with both required functions.- Errors
none.
This example compiles here; running it needs libnwchemc.
#include "rgpot/NWChemPot/NWChemPot.hpp"
#include <capnp/message.h>
#include <cstdio>
#include <string>
int main() {
::capnp::MallocMessageBuilder msg;
auto params = msg.initRoot<::NWChemParams>();
params.setTheory("scf");
params.setBasis("6-31g*");
params.setCharge(0);
params.setMultiplicity(1);
rgpot::NWChemPot pot(params.asReader());
std::string message;
::capnp::MallocMessageBuilder cfg_msg;
auto cfg = cfg_msg.initRoot<::PotentialConfig>();
cfg.setNwchem(params.asReader());
if (!pot.setPotentialConfig(cfg.asReader(), &message)) {
std::fprintf(stderr, "%s\n", message.c_str());
return 1;
}
return 0;
}
Skala¶
rgpot::SkalaConfig¶
- Inputs
xc(exchange-correlation keyword, defaultskala-1.1),basis(defaultdef2-tzvp),charge(default 0),multiplicity(2S+1, default 1),engine_path(default empty),nwchem_root(default empty).- Units
chargein elementary charges; the other fields have no unit.- Outputs
a plain struct read by
SkalaPot, which copies the fields into anNWChemParamsmessage.- Errors
SkalaPotthrowsstd::runtime_errorwhenbasisorxcis empty ormultiplicityis below 1. Other values reach NWChem unchecked; a rejection makesNWChemPot::setParamsreturn false, andSkalaPotignores that result.
rgpot::SkalaPot¶
SkalaPot();
explicit SkalaPot(const SkalaConfig &config);
- Inputs
config, anrgpot::SkalaConfig; the default constructor, where there is one, uses its defaults.- Units
as
rgpot::NWChemPot: Angstrom in, eV and eV/Angstrom out.- Outputs
a potential that runs NWChem Kohn-Sham DFT with the Skala functional through an owned
NWChemPot. The message it builds setstheorytodft,tasktogradientand one DFT stanza withxc.- Errors
std::runtime_errorfrom the constructor whenbasisorxcis empty ormultiplicityis below 1. A missing engine does not throw here; forces then throwstd::runtime_errorfromNWChemPot.
The owned NWChemPot is default-constructed first, so a library found by the
environment search is kept and engine_path is used only when that search
fails.
The build option is -Dwith_skala=true and it needs -Dwith_rpc=true.
rgpot::SkalaPot::config¶
[[nodiscard]] const SkalaConfig &config() const noexcept;
- Inputs
none.
- Units
none.
- Outputs
the stored
SkalaConfig, including charge and multiplicity set later.- Errors
none.
rgpot::SkalaPot::setChargeMultiplicity¶
void setChargeMultiplicity(int charge, int multiplicity);
- Inputs
chargein elementary charges andmultiplicityas 2S+1.- Units
none.
- Outputs
none; the new params are passed to the engine and
paramsKeyis recomputed.- Errors
std::runtime_errorwhenmultiplicityis below 1. The config already holds the new values when that throws.
rgpot::SkalaPot::available¶
[[nodiscard]] bool available() const;
- Inputs
none.
- Units
none.
- Outputs
NWChemPot::available()of the owned engine.- Errors
none.
rgpot::SkalaPot::getParams¶
void getParams(::NWChemParams::Builder out) const;
- Inputs
out, a builder to fill.- Units
as the message fields.
- Outputs
the
NWChemParamsthe class built and passed to the engine.- Errors
none.
tblite¶
rgpot::TBLiteConfig¶
- Inputs
method(TBLiteMethod::GFN1,GFN2orIPEA1; defaultGFN2),accuracy(default 1.0),electronic_temperature(default 300.0),max_iterations(default 250),charge(default 0.0),uhf(unpaired electrons, default 0).- Units
electronic_temperaturein K;chargein elementary charges; the other fields have no unit.- Outputs
a plain struct read by
TBLitePot.- Errors
TBLitePotdoes not check the values. tblite rejects them on the first force, andTBLitePotthrowsstd::runtime_errorwith the tblite message.
rgpot::TBLitePot¶
TBLitePot();
explicit TBLitePot(const TBLiteConfig &config);
- Inputs
config, anrgpot::TBLiteConfig; the default constructor, where there is one, uses its defaults.- Units
positions in Angstrom, energy in eV, forces in eV/Angstrom, stress in eV/Angstrom3. The class sends positions and cell in bohr and the electronic temperature in Hartree (times
KB_HARTREE), and converts the Hartree energy, the Hartree/bohr gradient and the Hartree virial divided by the cell volume. Stress is set only when the cell volume is positive.- Outputs
a potential that calls the linked tblite C API.
- Errors
std::runtime_errorfrom the constructor when the tblite context or result cannot be created. A force throwsstd::runtime_erroron a tblite structure, calculator, geometry update or SCF error.
The first force builds the structure and the calculator from that call’s atoms.
Later forces only update the geometry.
The build option is -Dwith_tblite=true.
xtb¶
rgpot::XTBConfig¶
- Inputs
method(GFNMethod::GFNFF,GFN0xTB,GFN1xTBorGFN2xTB; defaultGFN2xTB),accuracy(default 1.0),electronic_temperature(default 300.0),max_iterations(default 250),charge(default 0.0),uhf(unpaired electrons, default 0),warm_move(default 1.0),warm_min_gap(default 1.0).- Units
electronic_temperaturein K;chargein elementary charges;warm_movein Angstrom;warm_min_gapin eV; the other fields have no unit.- Outputs
a plain struct read by
XTBPotand, insideXTBDlopenConfig, byXTBDlopen.- Errors
neither class checks the values. A value xtb rejects fails the force with
std::runtime_error. Zero or a negativewarm_movedisables wavefunction reuse. Zero or a negativewarm_min_gapreuses the wavefunction at any gap.
rgpot::XTBDlopenConfig¶
- Inputs
xtb(anXTBConfig, default-constructed),engine_path(default empty).- Units
as
XTBConfig;engine_pathnone.- Outputs
a plain struct read by
XTBDlopen, the frontend that loadslibxtb_engineinstead of linking libxtb.- Errors
XTBDlopenthrowsstd::runtime_errorwhen a non-emptyengine_pathhas no directory separator, when no candidate library opens, or when the library lacks the C ABI or reports another ABI version.
A non-empty engine_path is the only candidate.
An empty one searches RGPOT_XTB_ENGINE,
XTB_ENGINE, the platform name (libxtb_engine.so on Linux), then
libxtb_engine.so in each directory of EON_POTENTIALS_PATH and RGPOT_ENGINE_PATH.
rgpot::XTBPot¶
XTBPot();
explicit XTBPot(const XTBConfig &config);
- Inputs
config, anrgpot::XTBConfig; the default constructor, where there is one, uses its defaults.- Units
positions in Angstrom, energy in eV, forces in eV/Angstrom, stress in eV/Angstrom3. The class sends positions and cell in bohr and converts the Hartree energy, the Hartree/bohr gradient and the Hartree virial divided by the cell volume. The molecule is created non-periodic in all three directions; stress is set when the cell volume is positive.
- Outputs
a potential that calls the linked libxtb C API.
- Errors
std::runtime_errorfrom the constructor when the xtb environment, calculator or results cannot be created. A force throwsstd::runtime_errorwhen the handles are missing,xtb_newMoleculefails, the single point fails, or the energy or gradient is not finite. After such a failure the handles are replaced.
A new composition rebuilds the molecule.
A force starts the SCC from the previous wavefunction when the composition is
unchanged, no atom moved further than warmMove(), and the HOMO-LUMO gap of
that wavefunction is at least warmMinGap().
A single point started that way that does not converge, or whose gap falls below
warmMinGap(), is run again from xtb’s own guess.
GFN-FF has no orbitals, so its gap never blocks reuse.
The first single point of a force runs at most 48 SCC iterations, or
max_iterations when that is smaller.
An SCC that does not converge is retried at 1000, 3000 and 5000 K (those above
the configured temperature) and then evaluated again at the configured
temperature.
The build option is -Dwith_xtb=true.
rgpot::XTBPot::reset¶
void reset();
- Inputs
none.
- Units
none.
- Outputs
none; the stored SCC wavefunction and the previous geometry are dropped, so the next force starts from xtb’s own guess.
- Errors
std::runtime_errorwhen a new xtb results object cannot be created.
rgpot::XTBPot::setWarmMove¶
void setWarmMove(double angstrom);
- Inputs
angstrom, the largest atom displacement that still reuses the previous wavefunction.- Units
Angstrom.
- Outputs
none. Zero or a negative value disables reuse.
- Errors
none.
rgpot::XTBPot::warmMove¶
[[nodiscard]] double warmMove() const noexcept;
- Inputs
none.
- Units
Angstrom.
- Outputs
the current displacement guard.
- Errors
none.
rgpot::XTBPot::setWarmMinGap¶
void setWarmMinGap(double ev);
- Inputs
ev, the smallest HOMO-LUMO gap at which the previous wavefunction is still the next guess.- Units
eV.
- Outputs
none. Zero or a negative value reuses the wavefunction at any gap.
- Errors
none.
rgpot::XTBPot::warmMinGap¶
[[nodiscard]] double warmMinGap() const noexcept;
- Inputs
none.
- Units
eV.
- Outputs
the current gap guard.
- Errors
none.
rgpot::XTBPot::reusedWavefunction¶
[[nodiscard]] bool reusedWavefunction() const noexcept;
- Inputs
none.
- Units
none.
- Outputs
true when the last successful force kept the previous wavefunction as its guess: same composition, a stored wavefunction, a positive displacement guard that no atom moved past, and a gap at or above
warmMinGap()before and after the single point. False when that force fell back to xtb’s own guess.- Errors
none.
rgpot::XTBDlopen¶
explicit XTBDlopen(const XTBDlopenConfig &config);
explicit XTBDlopen(const XTBConfig &xtb = XTBConfig{});
- Inputs
config, anrgpot::XTBDlopenConfig; the second form takes only theXTBConfigand searches for the engine with an emptyengine_path.- Units
as
XTBPot;libxtb_enginewraps anXTBPot.- Outputs
a frontend that loads
libxtb_engineand drives it through the XTB C ABI in Engine C ABI.warm_moveandwarm_min_gapare passed to the engine after it is created.- Errors
std::runtime_errorwhen a non-emptyengine_pathhas no directory separator, when no candidate library opens, when the library lacks anyrgpot_xtb_*symbol, whenrgpot_xtb_abi_versionis notRGPOT_XTB_ABI_VERSION, and with the engine’s message whenrgpot_xtb_createfails.
A library that opens but lacks a symbol ends the search; the next candidate is not tried. The destructor destroys the engine object and closes the library.
rgpot::XTBDlopen::available¶
[[nodiscard]] bool available() const noexcept;
- Inputs
none.
- Units
none.
- Outputs
true while the engine object exists, which is the whole life of a constructed
XTBDlopen.- Errors
none.
rgpot::XTBDlopen::forceImpl¶
void forceImpl(const ForceInput &in, ForceOut *out) const;
- Inputs
in, the positions, atomic numbers and cell;out, where the energy, forces and variance go.- Units
as
XTBPot.- Outputs
out->energy,out->Fandout->variancefromrgpot_xtb_force.out->has_stressandout->stressare not written.- Errors
std::runtime_errorwith the return code whenrgpot_xtb_forcereturns nonzero.
rgpot::XTBDlopen::reset¶
void reset();
- Inputs
none.
- Units
none.
- Outputs
none;
rgpot_xtb_resetdrops the engine’s stored wavefunction, asXTBPot::reset.- Errors
std::runtime_errorwhen the engine is not available.
rgpot::XTBDlopen::setWarmMove¶
void setWarmMove(double angstrom);
- Inputs
angstrom, the displacement guard, asXTBPot::setWarmMove.- Units
Angstrom.
- Outputs
none.
- Errors
std::runtime_errorwhen the engine is not available.
rgpot::XTBDlopen::warmMove¶
[[nodiscard]] double warmMove() const;
- Inputs
none.
- Units
Angstrom.
- Outputs
the engine’s displacement guard.
- Errors
std::runtime_errorwhen the engine is not available.
rgpot::XTBDlopen::setWarmMinGap¶
void setWarmMinGap(double ev);
- Inputs
ev, the gap guard, asXTBPot::setWarmMinGap.- Units
eV.
- Outputs
none.
- Errors
std::runtime_errorwhen the engine is not available.
rgpot::XTBDlopen::warmMinGap¶
[[nodiscard]] double warmMinGap() const;
- Inputs
none.
- Units
eV.
- Outputs
the engine’s gap guard.
- Errors
std::runtime_errorwhen the engine is not available.
rgpot::XTBDlopen::reusedWavefunction¶
[[nodiscard]] bool reusedWavefunction() const;
- Inputs
none.
- Units
none.
- Outputs
XTBPot::reusedWavefunctionof the engine’s potential.- Errors
std::runtime_errorwhen the engine is not available.
Metatomic¶
rgpot::MetatomicConfig¶
- Inputs
the fields and their defaults:
model_path(empty; the exported model file),device(empty; let metatomic pick from the model’s devices),length_unit(angstrom),extensions_directory(empty),check_consistency(false),uncertainty_threshold(-1.0; a positive value requests the model’s per-atomenergy_uncertaintyoutput),dtype_override(empty;float32orfloat64),random_rotation(false),n_symmetry_rotations(0; 12 or more averages over a rotation group, 12 elements below 24 and 24 from 24 up),so3_probe_scatter(false; with rotations, the unrotated pass gives the energy and forces and the rotated passes only the variance),torch_determinism(TorchDeterminismPolicy::Fast),engine_path(empty),task_name(empty),charge(0),spin(multiplicity, 1),attach_system_extras(false; true attaches the charge and spin names to every system).- Units
length_unitnames the unit of the positions given to the model;chargein elementary charges; the other fields have no unit.- Outputs
a plain struct read by
MetatomicPotand by the dlopen frontendMetatomicDlopen.- Errors
MetatomicPotthrows what metatomic raises for a model that does not load, andstd::runtime_errorfor a model without an energy output or with a dtype other thanfloat32orfloat64. Adtype_overrideother thanfloat32orfloat64is ignored, and a model that cannot move to the override keeps its own dtype. Anenergy_uncertaintyoutput that is missing or not per-atom turns the uncertainty request off.MetatomicDlopenthrowsstd::runtime_errorwhen no engine library opens or the engine refuses the config.
MetatomicPot compares uncertainty_threshold only with zero; the value itself
is not used as a threshold.
Each system carries charge as rgpot::charge and spin as
rgpot::spin_multiplicity and rgpot::spin, each name only when the model declares it in requested_inputs.
attach_system_extras attaches all three, for a model that reads them without
declaring them; it needs check_consistency off, because metatomic then rejects
data the model does not declare.
engine_path is read only by MetatomicDlopen, which tries it first, then RGPOT_METATOMIC_ENGINE, METATOMIC_ENGINE,
the platform name
(libmetatomic_engine.so on Linux) and the directories of EON_POTENTIALS_PATH and RGPOT_ENGINE_PATH.
MetatomicDlopen does not pass
task_name, charge, spin or attach_system_extras to the engine.
rgpot::MetatomicPot¶
explicit MetatomicPot(const MetatomicConfig &config);
- Inputs
config, anrgpot::MetatomicConfig; the default constructor, where there is one, uses its defaults.- Units
positions are passed unchanged and declared to the model in
length_unit; the energy is requested in eV. With the defaultlength_unitthat is Angstrom in, eV and eV/Angstrom out.varianceis the mean modelenergy_uncertaintyin eV when that output is used, else the RMS force spread over rotations in eV/Angstrom, else 0.- Outputs
a potential that evaluates the model in process with libtorch.
- Errors
the constructor throws what metatomic raises when the model cannot be loaded, and
std::runtime_errorfor a model dtype other thanfloat32orfloat64or a model without an energy output. Forces propagate torch and metatomic exceptions.
The device is chosen by metatomic_torch::pick_device from the model’s
supported devices and device.
TorchDeterminismPolicy::Strict changes process-global libtorch flags.
The build option is
-Dwith_metatomic=true; the class is not linked into librgpot when -Dwith_python=true.
rgpot::MetatomicPot::setChargeSpin¶
void setChargeSpin(int charge, int spin);
- Inputs
chargein elementary charges andspinas the multiplicity.- Units
none.
- Outputs
none; later forces attach these values under the names the model reads (see
readsChargeandreadsSpin).- Errors
none; a value the model does not read has no effect, and
libmetatomic_enginerefuses such a value without calling this.
rgpot::MetatomicPot::readsCharge¶
[[nodiscard]] bool readsCharge() const noexcept;
- Inputs
none.
- Units
none.
- Outputs
true when the model declares
rgpot::chargeinrequested_inputsorattach_system_extrasis true, so later forces attach the charge.- Errors
none.
rgpot::MetatomicPot::readsSpin¶
[[nodiscard]] bool readsSpin() const noexcept;
- Inputs
none.
- Units
none.
- Outputs
true when the model declares
rgpot::spin_multiplicityorrgpot::spininrequested_inputs, orattach_system_extrasis true, so later forces attach the multiplicity.- Errors
none.
rgpot::MetatomicDlopen¶
explicit MetatomicDlopen(const MetatomicConfig &config);
- Inputs
config, anrgpot::MetatomicConfig;engine_pathis read here, andtask_name,charge,spinandattach_system_extrasare not passed on.- Units
as
MetatomicPot;libmetatomic_enginewraps aMetatomicPot.- Outputs
a frontend that loads
libmetatomic_engineand drives it through the Metatomic C ABI in Engine C ABI. An emptydeviceruns oncpu.- Errors
std::runtime_errorwhen no candidate library opens, when the library lacksrgpot_mta_abi_version,rgpot_mta_create,rgpot_mta_destroyorrgpot_mta_force, when the version is notRGPOT_MTA_ABI_VERSION, and with the engine’s message whenrgpot_mta_createfails.
The library is opened with RTLD_GLOBAL.
The destructor destroys the engine object and leaves the library mapped, because
the static teardown of torch and metatomic after dlclose crashes at process
exit.
rgpot::MetatomicDlopen::available¶
[[nodiscard]] bool available() const noexcept;
- Inputs
none.
- Units
none.
- Outputs
true while the engine object exists, which is the whole life of a constructed
MetatomicDlopen.- Errors
none.
rgpot::MetatomicDlopen::forceImpl¶
void forceImpl(const ForceInput &in, ForceOut *out) const;
- Inputs
in, the positions, atomic numbers and cell;out, where the energy, forces and variance go.- Units
as
MetatomicPot.- Outputs
out->energy,out->Fandout->variancefromrgpot_mta_force.out->has_stressandout->stressare not written.- Errors
std::runtime_errorwith the return code whenrgpot_mta_forcereturns nonzero; the engine prints the reason on stderr.
UMA¶
rgpot::UmaConfig¶
- Inputs
model_path(default empty; an AOTInductor.pt2package fromscripts/export_uma_aoti.py),task_name(defaultomol),device(defaultcpu),charge(default 0),spin(multiplicity, default 1),cutoff(default 6.0),max_neighbors(default 300),cache_dir(default empty; the root of the persistent cache the package is unpacked into).- Units
cutoffin Angstrom;chargein elementary charges; the other fields have no unit.- Outputs
a plain struct read by
UmaPot.- Errors
UmaPotthrowsstd::runtime_errorwhenmodel_pathis empty or does not end in.pt2. The first force throwsstd::runtime_errorwhen the cache root cannot be created or the package cannot be unpacked into it. An emptycache_dirmeans$RGPOT_CACHE_DIR, then$XDG_CACHE_HOME/rgpot, then.rgpot-cachein the working directory; the UMA unpack cache in Engine C ABI gives the layout. Adevicethat is neithercpunor starts withcudaruns on the CPU. Acutoffthat is not positive and finite becomes 6.0, and amax_neighborsof zero or less keeps every neighbour. The package’scutoffandmax_neighborsmetadata replace the config values when present. Atask_name,chargeorspinthat disagrees with the package metadata makes each force throwrgpot::UmaContractError.
rgpot::UmaPot¶
explicit UmaPot(const UmaConfig &config);
- Inputs
config, anrgpot::UmaConfig; the default constructor, where there is one, uses its defaults.- Units
positions in Angstrom are passed to the package unchanged, and its energy and forces are copied unchanged; packages from that script return eV and eV/Angstrom. The package’s
cutoffmetadata replaces the config value when present.- Outputs
a potential that builds a neighbour list and runs the compiled graph.
- Errors
std::runtime_errorfrom the constructor whenmodel_pathis empty or does not end in.pt2. The package loads on the first force; loader errors andstd::runtime_errorfor bad dtype metadata surface there. A force throwsrgpot::UmaContractErrorwhen charge, spin, task or composition disagree with the package metadata,rgpot::UmaShapeErrorwhen the input does not fit the package shapes (both arestd::runtime_error), andstd::runtime_errorfor zero atoms, an empty edge list, mixed compositions in one batch, or output of the wrong shape.
The build option is
-Dwith_metatomic=true; the class is not linked into librgpot when -Dwith_python=true.
rgpot::UmaPot::config¶
[[nodiscard]] const UmaConfig &config() const noexcept;
- Inputs
none.
- Units
cutoffin Angstrom.- Outputs
the stored
UmaConfig, including charge and spin set later.- Errors
none.
rgpot::UmaPot::setChargeSpin¶
void setChargeSpin(int charge, int spin);
- Inputs
chargein elementary charges andspinas the multiplicity.- Units
none.
- Outputs
none; the config is updated and
paramsKeyis recomputed.- Errors
none here; the next force throws
rgpot::UmaContractErrorwhen the package was exported for other values.
rgpot::UmaPot::posDtypeName¶
[[nodiscard]] const char *posDtypeName() const;
- Inputs
none.
- Units
none.
- Outputs
float32,float64orunset: thepos_dtyperecorded in the package. The pointer stays valid while the potential lives.- Errors
loads the package first, so it throws what loading throws.
rgpot::UmaPot::modelDtypeName¶
[[nodiscard]] const char *modelDtypeName() const;
- Inputs
none.
- Units
none.
- Outputs
float32,float64orunset: themodel_dtyperecorded in the package.- Errors
as
posDtypeName.
rgpot::UmaPot::checkpointProvenance¶
[[nodiscard]] const UmaCheckpointProvenance &checkpointProvenance() const;
- Inputs
none.
- Units
none.
- Outputs
the checkpoint the package was exported from and the SHA-256 of its weights, read from the package metadata. Every field is unset for a package exported before the keys existed. The reference stays valid while the potential lives.
- Errors
loads the package first, so it throws what loading throws, including the
std::runtime_errorofUmaCheckpointProvenance::fromMetadatafor malformed keys.
rgpot::UmaCheckpointProvenance¶
- Inputs
none;
fromMetadatafills the sixstd::optional<std::string>fieldssource,path,hf_repo,hf_filename,hf_revisionandsha256from the package keyscheckpoint_source,checkpoint_path,checkpoint_hf_repo,checkpoint_hf_filename,checkpoint_hf_revisionandcheckpoint_sha256.- Units
none.
- Outputs
sourceiscli,envorhf;sha256is 64 andhf_revision40 lowercase hexadecimal digits.scripts/export_uma_aoti.pywritespathforcliandenvand the threehf_fields forhf.- Errors
none;
fromMetadatachecks the values.
CppCore/rgpot/UmaPot/UmaProvenance.hpp declares it, and the UMA checkpoint
provenance in Engine C ABI lists the keys.
sha256 is the digest of the checkpoint the exporter loaded, not of the .pt2;
rgpot_engine_model_digest hashes the package file.
rgpot::UmaCheckpointProvenance::present¶
[[nodiscard]] bool present() const noexcept;
- Inputs
none.
- Units
none.
- Outputs
true when any of the six fields is set.
- Errors
none.
rgpot::UmaCheckpointProvenance::fromMetadata¶
static UmaCheckpointProvenance
fromMetadata(const std::unordered_map<std::string, std::string> &meta);
- Inputs
meta, the package metadata as key and value strings.- Units
none.
- Outputs
the provenance; a key that is missing or empty leaves its field unset.
- Errors
std::runtime_errorwhencheckpoint_sourceis notcli,envorhf, whencheckpoint_sha256is not 64 lowercase hexadecimal digits, or whencheckpoint_hf_revisionis not 40.
i-PI socket¶
rgpot::IPIConfig¶
- Inputs
address(default empty),timeout_s(default 30.0).addressisunix:/absolute/path,unix:<name>(the i-PI default path with prefixipi_),tcp:<host>:<port>ortcp:<port>(host 127.0.0.1); port 0 lets the kernel choose.- Units
timeout_sin seconds; it covers one whole force call, including the wait for the driver to connect.- Outputs
a plain struct read by
IPIPot.- Errors
IPIPotthrowsstd::invalid_argumentfor an address without aunix:ortcp:prefix, an empty UNIX address, a UNIX name containing/, a UNIX path too long for the socket address, a missing or out-of-range port, or atimeout_sthat is negative or not finite. It throwsstd::runtime_errorwhen the host does not resolve or the socket cannot be bound or listened on.
rgpot::IPIPot¶
explicit IPIPot(const IPIConfig &config);
- Inputs
config, anrgpot::IPIConfig; the default constructor, where there is one, uses its defaults.- Units
positions and cell in Angstrom, energy in eV, forces in eV/Angstrom, stress in eV/Angstrom3. On the wire the class sends bohr (the cell with lattice vectors in columns, and its inverse) and converts the driver’s Hartree energy, Hartree/bohr forces and Hartree virial; the stress is -W/V.
timeout_sis in seconds and covers one whole force call, including the wait for the driver to connect.- Outputs
a potential that binds the socket at construction and evaluates through one i-PI driver.
- Errors
std::invalid_argumentfrom the constructor for a bad address, port or timeout or a UNIX path that is too long;std::runtime_errorwhen the socket cannot be bound or listened on. A force throwsstd::invalid_argumentfor missing buffers, zero atoms, more atoms than the protocol limit, non-finite positions or cell, or a singular cell, andstd::runtime_erroron a timeout, a disconnect, an unexpected header, a driver that does not become READY, or a mismatched atom count. After a failed exchange the connection is closed and the next force waits for a new driver.
Atomic numbers are not sent; the driver keeps its own species list.
The destructor sends EXIT.
The force call does not write ForceOut::stress; read it with copyStress.
The build option is -Dwith_ipi; its default, auto, builds the class
everywhere except Windows.
rgpot::IPIPot::config¶
[[nodiscard]] const IPIConfig &config() const noexcept;
- Inputs
none.
- Units
timeout_sin seconds.- Outputs
the
IPIConfiggiven to the constructor.- Errors
none.
rgpot::IPIPot::endpoint¶
[[nodiscard]] const std::string &endpoint() const noexcept;
- Inputs
none.
- Units
none.
- Outputs
the bound address,
unix:<path>ortcp:<host>:<port>with the port the kernel chose for port 0.- Errors
none.
rgpot::IPIPot::hasStress¶
[[nodiscard]] bool hasStress() const;
- Inputs
none.
- Units
none.
- Outputs
true after a force call whose cell had a positive volume. Each force call clears it first.
- Errors
none.
rgpot::IPIPot::copyStress¶
bool copyStress(double out[9]) const;
- Inputs
out, room for 9 doubles.- Units
eV/Angstrom3.
- Outputs
the last Cauchy stress, row-major, in
out; returns false (and writes nothing) when there is none oroutis null.- Errors
none.
This example compiles here; running it needs an i-PI driver that connects to the socket.
#include "rgpot/IPIPot/IPIPot.hpp"
#include <array>
#include <cstdio>
#include <vector>
int main() {
rgpot::IPIPot pot({.address = "tcp:127.0.0.1:0", .timeout_s = 60.0});
std::printf("driver should connect to %s\n", pot.endpoint().c_str());
rgpot::types::AtomMatrix positions(2, 3);
positions(0, 0) = 0.0;
positions(0, 1) = 0.0;
positions(0, 2) = 0.0;
positions(1, 0) = 0.74;
positions(1, 1) = 0.0;
positions(1, 2) = 0.0;
std::vector<int> numbers{1, 1};
std::array<std::array<double, 3>, 3> box{{{10, 0, 0}, {0, 10, 0}, {0, 0, 10}}};
auto [energy, forces, variance] = pot(positions, numbers, box);
double stress[9];
if (pot.copyStress(stress))
std::printf("E = %g eV, sigma_xx = %g eV/A^3\n", energy, stress[0]);
return 0;
}
LAMMPS, GROMACS and OpenMM¶
These three classes evaluate the shifted 12-6 Lennard-Jones potential described
by ExternalLjConfig.
The C entry points with the same names as the three factory functions are in
CppCore/rgpot/ExternalPot/external_potentials.h.
rgpot::ExternalLjConfig¶
- Inputs
u0(well depth, default 1.0),cutoff(truncation distance, default 8.0),psi(zero crossing, default 1.0),engine_path(default empty).- Units
u0in eV;cutoffandpsiin Angstrom;engine_pathnone.- Outputs
a plain struct read by the constructors of
LammpsPot,GromacsPotandOpenMMPot.- Errors
those constructors throw
std::invalid_argumentwhenu0,cutofforpsiis not positive and finite. Anengine_paththat does not open, or lacks the required symbols, makes them throwstd::runtime_error.
For LammpsPot an empty
engine_path searches RGPOT_LAMMPS_ENGINE, LAMMPS_ENGINE,
liblammps_engine and liblj_engine.
For GromacsPot and OpenMMPot an empty engine_path evaluates the potential
in process.
rgpot::rgpot_lammps_potential¶
std::unique_ptr<LammpsPot>
rgpot_lammps_potential(const ExternalLjConfig &config);
- Inputs
config, anExternalLjConfig.- Units
u0in eV,cutoffandpsiin Angstrom.- Outputs
a new
LammpsPotbuilt fromconfig, owned by the returnedstd::unique_ptr.- Errors
what the
LammpsPotconstructor throws:std::invalid_argumentfor a non-positive parameter,std::runtime_errorwhen no plugin loads orrgpot_engine_createfails.
rgpot::rgpot_gromacs_potential¶
std::unique_ptr<GromacsPot>
rgpot_gromacs_potential(const ExternalLjConfig &config);
- Inputs
config, anExternalLjConfig.- Units
u0in eV,cutoffandpsiin Angstrom; the potential stores them in kJ/mol and nm.- Outputs
a new
GromacsPotbuilt fromconfig, owned by the returnedstd::unique_ptr.- Errors
what the
GromacsPotconstructor throws:std::invalid_argumentfor a non-positive parameter,std::runtime_errorwhenengine_pathis set and the library does not load orrgpot_engine_createfails.
rgpot::rgpot_openmm_potential¶
std::unique_ptr<OpenMMPot>
rgpot_openmm_potential(const ExternalLjConfig &config);
- Inputs
config, anExternalLjConfig.- Units
as
rgpot::rgpot_gromacs_potential.- Outputs
a new
OpenMMPotbuilt fromconfig, owned by the returnedstd::unique_ptr.- Errors
as
rgpot::rgpot_gromacs_potential, for theOpenMMPotconstructor.
rgpot::LammpsPot¶
explicit LammpsPot(const ExternalLjConfig &config);
- Inputs
ExternalLjConfig.- Units
u0in eV,cutoffandpsiin Angstrom; positions in Angstrom, energy in eV, forces in eV/Angstrom. The plugin receives these values as three doubles and nothing is converted.- Outputs
a potential whose forces come from
rgpot_engine_forceof the loaded plugin; the plugin stays the backend.- Errors
std::invalid_argumentwhenu0,cutofforpsiis not positive and finite;std::runtime_errorwhen no library opens withrgpot_engine_create,rgpot_engine_destroyandrgpot_engine_force, orrgpot_engine_createfails. A force throwsstd::invalid_argumentfor missing buffers andstd::runtime_errorwhenrgpot_engine_forcereturns nonzero.
rgpot::GromacsPot¶
explicit GromacsPot(const ExternalLjConfig &config);
- Inputs
ExternalLjConfig.- Units
u0in eV,cutoffandpsiin Angstrom; positions in Angstrom, energy in eV, forces in eV/Angstrom. The constructor storesu0in kJ/mol and the lengths in nm. With anengine_path, positions and cell go torgpot_md_native_forcein nm, and the kJ/mol energy, the (kJ/mol)/nm forces and the variance (kJ/mol squared) come back converted. The factors are inCppCore/rgpot/ExternalPot/md_units.hpp.- Outputs
a potential that evaluates in process with
rgpot::LJPotwhenengine_pathis empty, or through the native library otherwise.caps().stressis true only for the in-process path.- Errors
std::invalid_argumentwhenu0,cutofforpsiis not positive and finite;std::runtime_errorwhen the library does not open, lacksrgpot_engine_create,rgpot_engine_destroyorrgpot_md_native_force, orrgpot_engine_createfails. A force throwsstd::invalid_argumentfor missing buffers andstd::runtime_errorwhenrgpot_md_native_forcereturns nonzero.
The three classes are built in every configuration except
-Dwith_rpc_client_only=true.
rgpot::OpenMMPot¶
explicit OpenMMPot(const ExternalLjConfig &config);
- Inputs
ExternalLjConfig.- Units
as
rgpot::GromacsPot.- Outputs
as
rgpot::GromacsPot; the two classes share one implementation.- Errors
as
rgpot::GromacsPot.
This example runs here because an empty engine_path evaluates in process.
#include "rgpot/ExternalPot/ExternalPot.hpp"
#include <array>
#include <cstdio>
#include <vector>
int main() {
rgpot::ExternalLjConfig cfg;
cfg.u0 = 1.0;
cfg.cutoff = 8.0;
cfg.psi = 1.0;
auto pot = rgpot::rgpot_gromacs_potential(cfg);
rgpot::types::AtomMatrix positions(2, 3);
for (int i = 0; i < 2; ++i)
for (int k = 0; k < 3; ++k)
positions(i, k) = 0.0;
positions(1, 0) = 1.5;
std::vector<int> numbers{1, 1};
std::array<std::array<double, 3>, 3> box{{{20, 0, 0}, {0, 20, 0}, {0, 0, 20}}};
auto [energy, forces, variance] = (*pot)(positions, numbers, box);
std::printf("u0 = %g kJ/mol, E = %.10f eV, Fx0 = %.10f eV/A\n",
pot->nativeU0(), energy, forces(0, 0));
return 0;
}
Members common to several classes¶
These members have the same declaration in each class that has them. A member whose description differs between classes has one entry per class.
rgpot::CP2KPot::paramsKey¶
[[nodiscard]] uint64_t paramsKey() const noexcept override;
- Inputs
none.
- Units
none.
- Outputs
a 64-bit FNV-1a hash of the serialized
CP2KParamsbytes andkKernelVersion. Instances that differ in these values get different result-cache keys.- Errors
none.
rgpot::CPMDPot::paramsKey¶
[[nodiscard]] uint64_t paramsKey() const noexcept override;
- Inputs
none.
- Units
none.
- Outputs
a 64-bit FNV-1a hash of the serialized
CPMDParamsbytes andkKernelVersion. Instances that differ in these values get different result-cache keys.- Errors
none.
rgpot::IPIPot::paramsKey¶
[[nodiscard]] uint64_t paramsKey() const noexcept override;
- Inputs
none.
- Units
none.
- Outputs
a 64-bit FNV-1a hash of
addressandtimeout_s. Instances that differ in these values get different result-cache keys.- Errors
none.
rgpot::SkalaPot::paramsKey¶
[[nodiscard]] uint64_t paramsKey() const noexcept override;
- Inputs
none.
- Units
none.
- Outputs
a 64-bit FNV-1a hash of
xc,basis,charge,multiplicity,engine_pathandnwchem_root. Instances that differ in these values get different result-cache keys.- Errors
none.
rgpot::UmaPot::paramsKey¶
[[nodiscard]] uint64_t paramsKey() const noexcept override;
- Inputs
none.
- Units
none.
- Outputs
a 64-bit FNV-1a hash of
model_path,task_name,device,chargeandspin. Instances that differ in these values get different result-cache keys.- Errors
none.
rgpot::CP2KPot::setPotentialConfig¶
bool setPotentialConfig(const ::PotentialConfig::Reader &cfg,
std::string *message_out = nullptr);
- Inputs
cfg, aPotentialConfigunion;message_out, an optional string that receives a one-line summary.- Units
as the message fields.
- Outputs
true for the
nonearm (nothing changes) and for thecp2karm whensetParamssucceeds. Any other arm returns false and names the arm inmessage_out.- Errors
no exception of its own; the
setParamsresult is returned.
rgpot::CPMDPot::setPotentialConfig¶
bool setPotentialConfig(const ::PotentialConfig::Reader &cfg,
std::string *message_out = nullptr);
- Inputs
cfg, aPotentialConfigunion;message_out, an optional string that receives a one-line summary.- Units
as the message fields.
- Outputs
true for the
nonearm (nothing changes) and for thecpmdarm whensetParamssucceeds. Any other arm returns false and names the arm inmessage_out.- Errors
no exception of its own; the
setParamsresult is returned.
rgpot::NWChemPot::setPotentialConfig¶
bool setPotentialConfig(const ::PotentialConfig::Reader &cfg,
std::string *message_out = nullptr);
- Inputs
cfg, aPotentialConfigunion;message_out, an optional string that receives a one-line summary.- Units
as the message fields.
- Outputs
true for the
nonearm (nothing changes) and for thenwchemarm whensetParamssucceeds. Any other arm returns false and names the arm inmessage_out.- Errors
no exception of its own; the
setParamsresult is returned.
rgpot::CP2KPot::probeAvailable¶
static bool probeAvailable();
- Inputs
none.
- Units
none.
- Outputs
true when the environment and default-name search, without an explicit path, finds a library that has the ABI version, the session functions and a nonzero
cp2kc_available, when exported. The first result is cached for the process.- Errors
none; a load failure gives false.
rgpot::CPMDPot::probeAvailable¶
static bool probeAvailable();
- Inputs
none.
- Units
none.
- Outputs
true when the environment and default-name search, without an explicit path, finds a library that has the feature discovery functions and the session or one-shot ABI. The first result is cached for the process.
- Errors
none; a load failure gives false.
rgpot::MOPACPot::probeAvailable¶
static bool probeAvailable();
- Inputs
none.
- Units
none.
- Outputs
true when the environment and default-name search, without an explicit path, finds a library that has
mopacc_energy_gradient, the ABI version and a nonzeromopacc_available, when exported. The first result is cached for the process.- Errors
none; a load failure gives false.
The probed library stays loaded for the process.
rgpot::NWChemPot::probeAvailable¶
static bool probeAvailable();
- Inputs
none.
- Units
none.
- Outputs
true when the environment and default-name search, without an explicit path, finds a library that has
nwchemc_energy_gradientandnwchemc_set_params. The first result is cached for the process.- Errors
none; a load failure gives false.
The probed library stays loaded for the process.
rgpot::CPMDPot::abiAvailable¶
static bool abiAvailable();
- Inputs
none.
- Units
none.
- Outputs
true when the probe search loads a library whose
cpmdc_availablereturns nonzero, which tells a real engine from the no-op stub. False when the library does not load or lacks that symbol. The first result is cached for the process.- Errors
none.
rgpot::MOPACPot::abiAvailable¶
static bool abiAvailable();
- Inputs
none.
- Units
none.
- Outputs
true when the probe search loads a library whose
mopacc_availablereturns nonzero, which tells a real engine from the no-op stub. False when the library does not load or lacks that symbol. The first result is cached for the process.- Errors
none.
rgpot::NWChemPot::abiAvailable¶
static bool abiAvailable();
- Inputs
none.
- Units
none.
- Outputs
true when the probe search loads a library whose
nwchemc_availablereturns nonzero, which tells a real engine from the no-op stub. False when the library does not load or lacks that symbol. The first result is cached for the process.- Errors
none.
rgpot::CP2KPot::selectOrbitals¶
void selectOrbitals(int64_t key);
- Inputs
key, an identifier of the calculation the following forces belong to (a band image, a ring-polymer bead).- Units
none.
- Outputs
none; every later force names this key to the engine first, so each key restarts from its own converged orbitals. Every rank of a calculator names the same key before the same force. An engine without
cp2kc_session_select_orbitalsignores the key.- Errors
none here; a force throws
std::runtime_errorwhen the engine refuses the key.
rgpot::CPMDPot::selectOrbitals¶
void selectOrbitals(int64_t key);
- Inputs
key, an identifier of the calculation the following forces belong to (a band image, a ring-polymer bead).- Units
none.
- Outputs
none; every later force names this key to the engine first, so each key restarts from its own converged orbitals. Every rank of a calculator names the same key before the same force. An engine without
cpmdc_session_select_orbitalsignores the key.- Errors
none here; a force throws
std::runtime_errorwhen the engine refuses the key.
rgpot::CP2KPot::keepsOrbitalsPerKey¶
[[nodiscard]] bool keepsOrbitalsPerKey() const;
- Inputs
none.
- Units
none.
- Outputs
true when the loaded engine exports
cp2kc_session_select_orbitals.- Errors
none.
rgpot::CPMDPot::keepsOrbitalsPerKey¶
[[nodiscard]] bool keepsOrbitalsPerKey() const;
- Inputs
none.
- Units
none.
- Outputs
true when the loaded engine exports
cpmdc_session_select_orbitalsand the session result ABI.- Errors
none.
rgpot::CP2KPot::bindCalculators¶
static int bindCalculators(int ranks_per_calc);
- Inputs
ranks_per_calc, the number of MPI ranks in one calculator.- Units
none.
- Outputs
this rank’s calculator index from
rgpot::bindCalculators, which splitsMPI_COMM_WORLDand hands the engine the calculator communicator. -1, before any split, when the default search finds no compatible library or the library lackscp2kc_adopt_calculator_comm; -1 also when the world cannot be divided.- Errors
std::runtime_errorwhen the library’s communicator callback changes between two loads; otherwise none.
Collective on MPI_COMM_WORLD: every rank calls it before the first force.
The adopting library stays loaded until the process exits.
rgpot::CPMDPot::bindCalculators¶
static int bindCalculators(int ranks_per_calc);
- Inputs
ranks_per_calc, the number of MPI ranks in one calculator.- Units
none.
- Outputs
this rank’s calculator index from
rgpot::bindCalculators, which splitsMPI_COMM_WORLDand hands the engine the calculator communicator. -1, before any split, when the default search finds no compatible library or the library lackscpmdc_adopt_calculator_comm; -1 also when the world cannot be divided.- Errors
std::runtime_errorwhen the library’s communicator callback changes between two loads; otherwise none.
Collective on MPI_COMM_WORLD: every rank calls it before the first force.
The adopting library stays loaded until the process exits.
.config¶
[[nodiscard]] const ExternalLjConfig &config() const noexcept;
- Applies to
rgpot::LammpsPot, rgpot::GromacsPot, rgpot::OpenMMPot
- Inputs
none.
- Units
u0in eV,cutoffandpsiin Angstrom.- Outputs
the
ExternalLjConfiggiven to the constructor.- Errors
none.
.nativeU0¶
[[nodiscard]] double nativeU0() const noexcept;
- Applies to
rgpot::GromacsPot, rgpot::OpenMMPot
- Inputs
none.
- Units
kJ/mol.
- Outputs
config().u0converted to kJ/mol once in the constructor.- Errors
none.
.nativeCutoff¶
[[nodiscard]] double nativeCutoff() const noexcept;
- Applies to
rgpot::GromacsPot, rgpot::OpenMMPot
- Inputs
none.
- Units
nm.
- Outputs
config().cutoffconverted to nm once in the constructor.- Errors
none.
.nativePsi¶
[[nodiscard]] double nativePsi() const noexcept;
- Applies to
rgpot::GromacsPot, rgpot::OpenMMPot
- Inputs
none.
- Units
nm.
- Outputs
config().psiconverted to nm once in the constructor.- Errors
none.