C++ API¶
The C++ API in include/rgpot/ wraps the C ABI of rgpot-core in move-only
handles.
rgpot/rgpot.hpp includes errors.hpp, potential.hpp and types.hpp, and
rpc_client.hpp only when RGPOT_HAS_RPC is defined.
It does not include CppCore/rgpot/Potential.hpp; each potential header (for
example rgpot/LennardJones/LJPot.hpp) brings in rgpot::PotentialBase and
rgpot::Potential.
Most wrapper methods pass the C status code to an internal check that throws
rgpot::Error for any status other than RGPOT_SUCCESS.
The exceptions are stated in each entry: invalidate_hvp and reset_hvp_counts
call C functions that return nothing, and the factories and the InputSpec and
CalcResult constructors check nothing.
The wrappers call the C functions of rgpot-core, which a Meson build links
only with -Dwith_rust_core=true.
Meson defines RGPOT_HAS_RPC only when with_rust_core is on together with
with_rpc or with_rpc_client_only.
The handles do not convert units.
Positions, cell, energy and forces are in the units of the wrapped potential.
The built-in potentials use Angstrom, eV and
eV/Angstrom (CppCore/rgpot/units.hpp).
include/rgpot/errors.hpp¶
rgpot::Error¶
explicit Error(const std::string &msg);
- Inputs
msg, the text thatwhat()returns.- Units
none.
- Outputs
an exception derived from
std::runtime_error.- Errors
none; the constructor has no failure path.
The wrappers build msg from a category prefix and the rgpot_last_error()
text, or “unknown error” when that pointer is NULL.
The prefixes are “invalid parameter: “ for RGPOT_INVALID_PARAMETER, “RPC
error: “ for RGPOT_RPC_ERROR, “buffer size error: “ for
RGPOT_BUFFER_SIZE_ERROR, and “internal error: “ for RGPOT_INTERNAL_ERROR and
any other code.
Every category throws the same type, rgpot::Error.
include/rgpot/types.hpp¶
rgpot::InputSpec¶
InputSpec(size_t n_atoms, double *pos, int *atmnrs, double *box);
InputSpec(std::vector<double> &positions, std::vector<int> &atmnrs, double *box);
- Inputs
n_atoms;posorpositions, 3*n doubles, row-major xyz per atom;atmnrs, n atomic numbers;box, 9 doubles, the cell vectors as rows. The vector overload takes n aspositions.size() / 3.- Units
positions and cell in the length unit of the potential (Angstrom for the built-in potentials); atomic numbers and counts have none.
- Outputs
a move-only object holding an
rgpot_force_input_twith non-owning DLPack tensors over the caller’s arrays. The arrays are borrowed, not copied, and must outlive the object. The destructor frees the tensor metadata, not the arrays.- Errors
none; nothing is checked. The vector overload does not compare
atmnrs.size()with n. NULL pointers are stored as given and surface as errors from the call that reads them.
rgpot::InputSpec::c_struct¶
const rgpot_force_input_t &c_struct() const;
- Inputs
none.
- Units
none.
- Outputs
a const reference to the wrapped
rgpot_force_input_t, valid while theInputSpeclives.- Errors
none.
rgpot::InputSpec::n_atoms¶
size_t n_atoms() const;
- Inputs
none.
- Units
none.
- Outputs
the atom count given at construction.
- Errors
none.
rgpot::CalcResult¶
CalcResult();
- Inputs
none.
- Units
none.
- Outputs
a move-only result buffer from
rgpot_force_out_create(): NULL forces, energy and variance 0.0. The destructor frees the forces tensor withrgpot_tensor_freewhen one was set.- Errors
none.
rgpot::CalcResult::c_struct¶
rgpot_force_out_t &c_struct();
- Inputs
none.
- Units
none.
- Outputs
a mutable reference to the wrapped
rgpot_force_out_t. TheCalcResultkeeps ownership of any forces tensor stored in it.- Errors
none.
rgpot::CalcResult::energy¶
double energy() const;
- Inputs
none.
- Units
the energy unit of the potential (eV for the built-in potentials).
- Outputs
the potential energy; 0.0 before a calculation.
- Errors
none.
rgpot::CalcResult::variance¶
double variance() const;
- Inputs
none.
- Units
as the potential reports it; most potentials leave it at 0.0.
- Outputs
the variance or uncertainty estimate; 0.0 when unused.
- Errors
none.
rgpot::CalcResult::forces_data¶
const double *forces_data(size_t &n_elements) const;
- Inputs
n_elements, an out-parameter.- Units
forces in the energy-per-length unit of the potential (eV/Angstrom for the built-in potentials).
- Outputs
a pointer to the forces tensor data, 3*n doubles in row-major
[n, 3]order, valid while theCalcResultlives;n_elementsis set to the product of the tensor shape. With no forces tensor it returnsnullptrand setsn_elementsto 0.- Errors
none. The pointer is read as CPU memory; the device of the tensor is not checked.
rgpot::CalcResult::forces_vec¶
std::vector<double> forces_vec() const;
- Inputs
none.
- Units
as
forces_data.- Outputs
a copy of the forces, 3*n doubles row-major; empty when there is no forces tensor.
- Errors
none.
rgpot::CalcResult::has_forces¶
bool has_forces() const;
- Inputs
none.
- Units
none.
- Outputs
truewhen a forces tensor is set.- Errors
none.
include/rgpot/potential.hpp¶
rgpot::PotentialHandle¶
explicit PotentialHandle(rgpot_potential_t *handle);
- Inputs
handle, a pointer fromrgpot_potential_neworrgpot_potential_new_eindir, or NULL.- Units
none.
- Outputs
a move-only handle that owns
handleand passes it torgpot_potential_freeon destruction. A moved-from handle holds NULL.- Errors
none; a NULL
handleis stored as given.
rgpot::PotentialHandle::from_impl¶
template <typename Impl> static PotentialHandle from_impl(Impl &impl);
template <typename Impl>
static PotentialHandle from_impl(Impl &impl, size_t n_atoms,
const int32_t *atomic_numbers,
const double *box_matrix,
const double *bounds_low = nullptr,
const double *bounds_high = nullptr);
- Inputs
impl, an object withforceImpl(const rgpot::ForceInput &, rgpot::ForceOut *); the caller keeps ownership and must keep it alive while the handle lives. The second overload also takesn_atoms,atomic_numbers(n values),box_matrix(9 doubles) and optional bounds (3*n doubles each, default -50 and 50 per coordinate when NULL);rgpot_potential_new_eindircopies them.- Units
positions, cell and bounds in the length unit of
impl.- Outputs
a handle whose callback calls
impl.forceImpland returns the forces as a new owning[n, 3]tensor. WhenImplhashessianVectorImpl, it is registered as the analytic Hessian-vector product.- Errors
none thrown by the factory. When
n_atoms * 3overflows, the second overload returns a handle holding NULL, and later calls on it throwrgpot::Error(“invalid parameter”). At calculation time an exception fromimpl.forceImplbecomesRGPOT_INTERNAL_ERROR, and missing positions becomeRGPOT_INVALID_PARAMETER; the calling method throwsrgpot::Error. The exception’s own message is dropped.
The trampoline copies energy, variance and forces from ForceOut; it does not
pass stress through.
rgpot::PotentialHandle::from_callback¶
static PotentialHandle from_callback(rgpot_status_t (*callback)(void *, const rgpot_force_input_t *, rgpot_force_out_t *),
void *user_data, void (*free_fn)(void *) = nullptr);
- Inputs
callback, a C potential callback;user_data, passed to every call;free_fn, called withuser_datawhen the handle is freed, ornullptr.- Units
those of
callback.- Outputs
a handle from
rgpot_potential_new.- Errors
none; the result of
rgpot_potential_newis not checked for NULL. A non-success status fromcallbackis thrown asrgpot::Errorby the method that called it.
rgpot::PotentialHandle::calculate¶
CalcResult calculate(const InputSpec &input);
- Inputs
input, the configuration.- Units
those of the wrapped potential.
- Outputs
a
CalcResultwith energy, variance and the[n, 3]forces tensor set by the callback.- Errors
throws
rgpot::Errorwhenrgpot_potential_calculatereturns a non-success status: a NULL handle gives “invalid parameter”, and a failing callback gives the category of its status.
rgpot::PotentialHandle::hvp¶
void hvp(const InputSpec &input, const double *direction, double *hv_out,
double step = 0.0, rgpot_hvp_scheme_t scheme = RGPOT_HVP_AUTO) const;
std::vector<double> hvp(const InputSpec &input,
const std::vector<double> &direction,
double step = 0.0,
rgpot_hvp_scheme_t scheme = RGPOT_HVP_AUTO) const;
- Inputs
input, the geometry;direction, 3*n doubles laid out like the positions;hv_out, room for 3*n doubles that must not overlapdirection;step, the displacement length, where 0 selectsRGPOT_HVP_DEFAULT_STEP;scheme, one ofRGPOT_HVP_AUTO,RGPOT_HVP_FORWARD,RGPOT_HVP_CENTRAL,RGPOT_HVP_ANALYTIC.- Units
stepin the length unit of the positions; the product is the Hessian (energy per length squared, eV/Angstrom2for the built-in potentials) timesdirection.- Outputs
the Hessian-vector product, 3*n doubles: written to
hv_out, or returned as a new vector by the second overload.- Errors
throws
rgpot::Errorwhenrgpot_potential_hvpreturns a non-success status: NULL pointers, an unknown scheme, a negative or non-finite step, a non-finite direction value, overlapping buffers, orRGPOT_HVP_ANALYTICwith no analytic callback give “invalid parameter”; a failing force callback gives the category of its status. The vector overload throwsrgpot::Error(“invalid parameter: direction must hold 3 * natomsvalues”) whendirection.size()is not 3*n.
With RGPOT_HVP_FORWARD, k products at one geometry make k+1 force calls.
rgpot::PotentialHandle::hvp_centre¶
CalcResult hvp_centre(const InputSpec &input) const;
- Inputs
input, the geometry.- Units
those of the wrapped potential.
- Outputs
a
CalcResultwith energy and an owning[n, 3]forces tensor, taken from the cached centre when the geometry matches, otherwise from one force call that becomes the cached centre.- Errors
throws
rgpot::Errorwhenrgpot_potential_hvp_centrereturns a non-success status (NULL handle, failing callback).
rgpot::PotentialHandle::set_hvp_callback¶
void set_hvp_callback(HessianVectorCallback callback) const;
- Inputs
callback, an analytic Hessian-vector product called with the handle’suser_data, ornullptrto clear it.- Units
those of the wrapped potential.
- Outputs
none.
- Errors
throws
rgpot::Error(“invalid parameter”) when the handle is NULL.
rgpot::PotentialHandle::invalidate_hvp¶
void invalidate_hvp() const;
- Inputs
none.
- Units
none.
- Outputs
none; drops the cached centre.
- Errors
none; a NULL handle is a no-op.
Call it after changing the state behind the potential at a fixed geometry, because the centre is keyed on positions, atomic numbers and cell only.
rgpot::PotentialHandle::hvp_counts¶
rgpot_hvp_counts_t hvp_counts() const;
- Inputs
none.
- Units
none.
- Outputs
an
rgpot_hvp_counts_twithproducts,force_calls,centre_reusedandanalyticsince creation or the last reset.- Errors
throws
rgpot::Error(“invalid parameter”) when the handle is NULL.
rgpot::PotentialHandle::reset_hvp_counts¶
void reset_hvp_counts() const;
- Inputs
none.
- Units
none.
- Outputs
none; zeroes the counters and keeps the cached centre.
- Errors
none; a NULL handle is a no-op.
rgpot::PotentialHandle::raw¶
rgpot_potential_t *raw() const;
- Inputs
none.
- Units
none.
- Outputs
the owned
rgpot_potential_tpointer, NULL after a move; the handle keeps ownership.- Errors
none.
include/rgpot/rpcclient.hpp¶
The class is declared only when RGPOT_HAS_RPC is defined.
rgpot::RpcClient¶
RpcClient(const std::string &host, uint16_t port);
- Inputs
host, a host name or IP address;port, the TCP port of an rgpot server.- Units
none.
- Outputs
a move-only client connected by
rgpot_rpc_client_new; the destructor callsrgpot_rpc_client_free.- Errors
throws
rgpot::Errorwhenrgpot_rpc_client_newreturns NULL; the message is thergpot_last_error()text without a category prefix, or “failed to create RPC client” when that pointer is NULL.
rgpot::RpcClient::calculate¶
CalcResult calculate(const InputSpec &input);
- Inputs
input, the configuration sent to the server.- Units
those of the potential on the server.
- Outputs
a
CalcResultwith energy, variance and forces from the server.- Errors
throws
rgpot::Errorwhenrgpot_rpc_calculatereturns a non-success status, for example “RPC error” on a transport or server failure.
CppCore/rgpot/Potential.hpp: rgpot::PotentialBase¶
rgpot::PotentialBase¶
explicit PotentialBase(PotType inp_type);
- Inputs
inp_type, thePotTypeof the potential.- Units
none.
- Outputs
the abstract base of every potential. Its pure virtual
operator()takes positions (n x 3AtomMatrix), atomic numbers and a 3 x 3 cell, and returns energy, forces (n x 3) and variance.- Errors
none.
rgpot::PotentialBase::caps¶
[[nodiscard]] virtual PotCaps caps() const noexcept;
- Inputs
none.
- Units
none.
- Outputs
a
PotCapswith the reentrancy, per-image, batched, periodic, group-collective and stress flags; the default is a value-initialisedPotCaps(SharedInstance, periodic, nothing else set).- Errors
none; the method is
noexcept.
rgpot::PotentialBase::forceBatch¶
virtual void forceBatch(const ForceBatch & /*batch*/);
- Inputs
a
ForceBatchof independent systems.- Units
none in the base.
- Outputs
none in the base;
rgpot::Potential::forceBatchoverrides it.- Errors
the base implementation throws
std::runtime_error(“PotentialBase::forceBatch called directly”).
rgpot::PotentialBase::paramsKey¶
[[nodiscard]] virtual uint64_t paramsKey() const noexcept;
- Inputs
none.
- Units
none.
- Outputs
a 64-bit fingerprint of the parameter set, mixed into the result-cache key; the default is 0.
- Errors
none; the method is
noexcept.
rgpot::PotentialBase::setCache¶
virtual void setCache(rgpot::cache::PotentialCache * /*c*/);
- Inputs
a
rgpot::cache::PotentialCachepointer.- Units
none.
- Outputs
none in the base;
rgpot::Potential::setCacheoverrides it.- Errors
the base implementation throws
std::runtime_error(“PotentialBase::setCache called directly”).
Declared only when RGPOT_HAS_CACHE is defined.
rgpot::PotentialBase::getType¶
[[nodiscard]] PotType getType() const;
- Inputs
none.
- Units
none.
- Outputs
the
PotTypegiven at construction.- Errors
none.
CppCore/rgpot/Potential.hpp: rgpot::Potential¶
rgpot::Potential¶
- Inputs
the template argument
Derived, the concrete potential; the constructor is inherited fromPotentialBaseand takes aPotType.- Units
those of
Derived; the built-in potentials use Angstrom, eV and eV/Angstrom.- Outputs
a CRTP base whose
operator()flattens the positions and cell, callsforceImplwith zeroed outputs, counts the force call, and returns energy, forces (n x 3) and variance. WithRGPOT_HAS_CACHEand a cache set,operator()returns a cached result when the key matches.- Errors
operator()propagates any exception fromforceImpl.
rgpot::Potential::forceImpl¶
virtual void forceImpl(const ForceInput &in, ForceOut *out) const = 0;
- Inputs
in.nAtoms;in.pos, 3*n doubles row-major;in.atmnrs, n atomic numbers;in.box, 9 doubles, cell vectors as rows.- Units
those of
Derived; built-in potentials take Angstrom and write eV, eV/Angstrom and, for stress, eV/Angstrom3.- Outputs
out->F, 3*n force doubles row-major;out->energy;out->variance;out->stress, 9 doubles row-major xx..zz;out->has_stress, 0 when no stress was computed.operator()andforceBatchpassoutzeroed.- Errors
defined by each potential; an override may throw with
outpartly written.
rgpot::Potential::forceBatchImpl¶
virtual void forceBatchImpl(const ForceBatch &batch) const;
- Inputs
batch,batch.nSystemssystems with parallel arraysbatch.inandbatch.out.- Units
as
forceImpl.- Outputs
fills
batch.out[i]frombatch.in[i]for every i; the default callsforceImplonce per system.- Errors
the default propagates any exception from
forceImpl.
An override must treat the systems as independent and set caps().batched.
rgpot::Potential::forceBatch¶
void forceBatch(const ForceBatch &batch) override;
- Inputs
batch; eachbatch.out[i].Fmust have room for 3 *batch.in[i].nAtomsdoubles.- Units
as
forceImpl.- Outputs
batch.out[i]for every system. Every slot is zeroed first. WithRGPOT_HAS_CACHEand a cache set, hits are served from the cache and only the misses reachforceBatchImpl.- Errors
propagates any exception from
forceBatchImpl; the slots stay zeroed or partly written.
rgpot::Potential::setCache¶
void setCache(rgpot::cache::PotentialCache *c) override;
- Inputs
c, argpot::cache::PotentialCachepointer, ornullptrto stop caching.- Units
none.
- Outputs
none; stores
cforoperator()andforceBatch. The caller keeps ownership.- Errors
none.
Declared only when RGPOT_HAS_CACHE is defined.
CppCore/rgpot/ForceStructs.hpp¶
rgpot::ForceInput¶
- Inputs
four fields, all
const, so the struct is filled by aggregate initialisation:nAtoms(size_t), the atom count n;pos(const double *), 3*n positions, row-major xyz per atom;atmnrs(const int *), n atomic numbers;box(const double *), 9 doubles, the three cell vectors as rows (ax ay az bx by bz cx cy cz).- Units
posandboxin the length unit of the potential (Angstrom for the built-in potentials);nAtomsandatmnrshave none.- Outputs
none; the struct borrows the caller’s arrays and owns nothing.
- Errors
none; the struct is plain data and nothing is checked.
rgpot::ForceOut¶
- Inputs
F(double *), a caller-owned buffer with room for 3*n doubles.- Units
Fin the force unit of the potential (eV/Angstrom for the built-in potentials);energyin its energy unit (eV);stressin energy per length cubed (eV/Angstrom3);varianceas the potential reports it.- Outputs
F, 3*n forces row-major like the positions;energy(double);variance(double), 0 when unused;stress(double[9]), the Cauchy stress row-major xx xy xz yx yy yz zx zy zz;has_stress(int), 0 when the potential did not compute stress.- Errors
none; the struct is plain data.
Potentials that write stress set caps().stress.
rgpot::ForceBatch¶
- Inputs
nSystems(size_t), the number of systems;in(const ForceInput *),nSystemsinputs;out(ForceOut *),nSystemsresult slots, whereout[i]belongs toin[i]andout[i].Fhas room for 3 *in[i].nAtomsdoubles.- Units
as
ForceInputandForceOut.- Outputs
none; the caller owns both arrays and every buffer they point at.
- Errors
none; the struct is plain data.
The systems are independent: each has its own atom count, cell and species.
CppCore/rgpot/potcaps.hpp¶
rgpot::Reentrancy¶
- Inputs
none; an
enum classwithuint8_tstorage.- Units
none.
- Outputs
one of three values:
SharedInstance, one instance may be called from many threads at once;PerInstance, concurrent evaluation needs one instance per thread;ProcessSerial, all evaluations in the process must be serialised, whatever the instance count.- Errors
none.
rgpot::PotCaps¶
- Inputs
none; a struct of fields with default member initialisers.
- Units
none.
- Outputs
reentrancy(Reentrancy, defaultSharedInstance);perImageInstances(bool, default false), callers should clone one instance per NEB image;batched(bool, default false), the potential overridesforceBatchImpl;periodic(bool, default true), the kernel supports periodic boundaries;groupCollective(bool, default false), every rank of a calculator group enters each force call together, so the result cache decides hit or miss jointly over the group;stress(bool, default false),forceImplwrites the Cauchy stress for a positive cell volume.- Errors
none.
rgpot::PotentialBase::caps returns this struct.
CppCore/rgpot/pottypes.hpp¶
rgpot::PotType¶
- Inputs
none; an
enum classwith one enumerator per potential kind.- Units
none.
- Outputs
UNKNOWN(0),CuH2,LJ,XTB,TBLite,Metatomic,NWChem,CPMD,Morse,LJCluster,ZBL,SWSi,EDIP,LenoskySi,TersoffSi,EAMAl,FeHe,WaterH,D3,D4,Expr,Uma,Skala,MOPAC,EMT,EAMCell,TIP4P,SPCE,TIP4PPt,IPI,SuttonChen,SWSi1985,EAMTable,Lammps,Gromacs,OpenMM,CP2K,LrCoulomb,LrDispersion,LrNlh,LrSum, numbered in that order.- Errors
none.
Every enumerator is declared in every build; whether the potential behind it is
compiled depends on the Meson options.
The value is part of the result-cache key, and rgpot::PotentialBase::getType
returns it.
CppCore/rgpot/CalculatorGroup.hpp¶
A calculator is one independent evaluation, such as a NEB image or a dimer end;
the ranks of one calculator share a subcommunicator.
librgpot never links MPI.
The MPI side is
librgpot_mpi, which bindCalculators and calculatorsUseMpi load with dlopen on first use (Meson option -Dwith_mpi=enabled).
Until that library is loaded, every function below behaves as a process of one
calculator with one rank.
Running under MPI is described in MPI.
rgpot::CalculatorGroup¶
- Inputs
none; a struct of four
intfields.- Units
none.
- Outputs
index(default 0), the calculator this rank belongs to, or -1 when the bind was refused;ranks(default 1), ranks per calculator;rank_in_group(default 0), this rank within its calculator;world_size(default 1), the size ofMPI_COMM_WORLD.- Errors
none.
rgpot::addCalculatorHook¶
void addCalculatorHook(CalculatorHook hook);
- Inputs
hook, a functionint (*)(int ranks_per_calculator)that returns the group index or -1 to refuse the bind.- Units
none.
- Outputs
none;
hookis called on every rank from each laterbindCalculatorsthat performs a bind. A hook already registered is not added twice.- Errors
none; a null
hookis ignored.
rgpot::bindCalculators¶
CalculatorGroup bindCalculators(int ranks_per_calculator);
- Inputs
ranks_per_calculator; 0 or less means one calculator for the whole world.- Units
none.
- Outputs
the
CalculatorGroupof this rank, also kept forthisCalculator. Withlibrgpot_mpiloaded it is collective onMPI_COMM_WORLD, callsMPI_Initwhen MPI is not up yet, and splits the world. Without it, 1 or 0 or less gives index 0 with one rank, and any other value gives index -1. Registered hooks and communicator adopters are then called; a negative result from any of them sets index to -1.- Errors
no exception; failure is reported as index -1. Index is -1 when the world size is not a multiple of
ranks_per_calculatoror is smaller than it, and when a hook or adopter refuses. After a bind, a call whose argument equals the stored ranks per calculator returns the stored group. Any other argument returns a group with index -1 and leaves the stored group unchanged. An argument of 0 or less is compared as its resolved value (the world size, or 1 without MPI), so repeatingbindCalculators(0)returns the stored group.
rgpot::thisCalculator¶
const CalculatorGroup &thisCalculator();
- Inputs
none.
- Units
none.
- Outputs
the group stored by the last bind; a default
CalculatorGroup(index 0, one rank, world size 1) before any bind.- Errors
none.
rgpot::calculatorComm¶
int calculatorComm(void *comm_out, std::size_t comm_bytes);
- Inputs
comm_out, storage for anMPI_Comm;comm_bytes,sizeof(MPI_Comm)on the caller.- Units
none.
- Outputs
1 after copying the calculator’s communicator into
\*comm_out; 0 otherwise.- Errors
none; returns 0 without
librgpot_mpi, without a split, for a nullcomm_out, or whencomm_bytesdiffers from the library’ssizeof(MPI_Comm).
rgpot::adoptCalculatorComm¶
int adoptCalculatorComm(CalculatorCommAdopter callback);
- Inputs
callback, a functionint (*)(const void *, std::size_t, int)that receives the address and byte size of the calculator’sMPI_Comm, then the ranks per calculator; it must borrow the handle and not free it.- Units
none.
- Outputs
the result of
callback.- Errors
none; returns -1 without
librgpot_mpi, for a nullcallback, before a bind, after a refused bind, or without a communicator.
rgpot::addCalculatorCommAdopter¶
bool addCalculatorCommAdopter(CalculatorCommAdopter callback);
- Inputs
callback, as foradoptCalculatorComm; its code must stay loaded for the life of the process.- Units
none.
- Outputs
truewhen registered. Before a bind the callback is queued forbindCalculators; after a bind it is called at once with the existing communicator. A callback already registered is not added twice.- Errors
no exception; returns
falsefor a nullcallbackor after a refused bind. When the immediate call after a bind returns a value other than the group index, the stored index becomes -1 and the result isfalse.
Every rank must register the same callbacks in the same order. Registration does not load MPI.
rgpot::calculatorsUseMpi¶
int calculatorsUseMpi();
- Inputs
none.
- Units
none.
- Outputs
1 when
librgpot_mpiis loaded (it loads it if needed) andMPI_Initializedreports MPI up; else 0.- Errors
none; a failed load returns 0, with the reason in
calculatorMpiLoadError.
rgpot::loadCalculatorMpi¶
int loadCalculatorMpi(const char *path = nullptr);
- Inputs
path, the library file to open, ornullptr(or an empty string) to try in order: theRGPOT_MPI_LIBRARYenvironment variable,librgpot_mpi.so.3(librgpot_mpi.3.dylibon macOS) in the directory oflibrgpot, then that name through the dynamic linker’s search path.- Units
none.
- Outputs
1 when the MPI side is available, also when it was loaded already; else 0. The library stays loaded for the life of the process.
- Errors
none thrown; returns 0 when no candidate opens, lacks the
rgpot_mpi_api_v1symbol, or has an incompatible ABI version, and on Windows. The reason is kept forcalculatorMpiLoadError.
rgpot::calculatorMpiLoaded¶
int calculatorMpiLoaded();
- Inputs
none.
- Units
none.
- Outputs
1 once
librgpot_mpiis loaded in this process, else 0.- Errors
none.
rgpot::calculatorMpiLoadError¶
std::string calculatorMpiLoadError();
- Inputs
none.
- Units
none.
- Outputs
the reason the last
loadCalculatorMpifailed; empty after a success or before any attempt.- Errors
none.
rgpot::calculatorWorldSize¶
int calculatorWorldSize();
- Inputs
none.
- Units
none.
- Outputs
the
MPI_COMM_WORLDsize recorded bybindCalculators, also after a refused split; 1 before a bind.- Errors
none.
rgpot::calculatorCount¶
int calculatorCount();
- Inputs
none.
- Units
none.
- Outputs
the number of calculators, world size divided by ranks per calculator; 1 before a bind and after a refused one.
- Errors
none.
rgpot::finalizeMpiAtExit¶
void finalizeMpiAtExit();
- Inputs
none.
- Units
none.
- Outputs
none; registers, once per process, an exit handler. The handler calls
MPI_Abort(MPI_COMM_WORLD, 1)whenabortMpiAtExitwas called, otherwiseMPI_FinalizewhenbindCalculatorscalledMPI_Initand MPI is not yet finalized.- Errors
none; a no-op without
librgpot_mpi.
rgpot::abortMpiAtExit¶
void abortMpiAtExit();
- Inputs
none.
- Units
none.
- Outputs
none; sets a process-wide flag that the
finalizeMpiAtExithandler reads.- Errors
none; harmless without MPI.
A backend calls it before throwing out of a failed engine call, so the other ranks are not left waiting in a collective.
rgpot::mpiAbortRequested¶
bool mpiAbortRequested();
- Inputs
none.
- Units
none.
- Outputs
trueonceabortMpiAtExitwas called in this process.- Errors
none.
rgpot::calculatorAgree¶
int calculatorAgree(unsigned char *flags, std::size_t n);
- Inputs
flags,nbytes, each read as a boolean; every rank of the calculator must pass the samen.- Units
none.
- Outputs
1 after replacing
flagsin place with their logical AND over the ranks of this calculator; 0 withflagsuntouched. It is collective on the calculator’s communicator; other calculators take no part.- Errors
none; returns 0 without
librgpot_mpi, when MPI is not initialized or already finalized, before a split, after a refused bind, or for a calculator of one rank.
rgpot::publishCalculatorError¶
void publishCalculatorError(const std::string &message);
- Inputs
message, empty for success; every rank of the calculator calls it at the end of agroupCollectiveforce call.- Units
none.
- Outputs
none when no rank has a message.
- Errors
when any rank has a message, every message (at most 512 bytes each) is printed to stderr on every rank of the calculator and
MPI_Abort(MPI_COMM_WORLD, 1)runs. Without a split, or for a calculator of one rank, a non-empty message prints and aborts. A rank with a message that waits more than 10 seconds for the exchange aborts on its own. Withoutlibrgpot_mpi, or when MPI is not initialized, it returns and the caller’s exception carries the message.
Example¶
The build in this tree is configured with with_rust_core off, so the
rgpot-core symbols that the handles call are not linked; the example is only
compiled.
#include <cstdio>
#include "rgpot/LennardJones/LJPot.hpp"
#include "rgpot/rgpot.hpp"
int main() {
rgpot::LJPot lj;
auto pot = rgpot::PotentialHandle::from_impl(lj);
double pos[] = {0, 0, 0, 1.1, 0, 0};
int atm[] = {1, 1};
double box[] = {10, 0, 0, 0, 10, 0, 0, 0, 10};
rgpot::InputSpec input(2, pos, atm, box);
try {
rgpot::CalcResult result = pot.calculate(input);
std::vector<double> forces = result.forces_vec();
std::printf("E = %.6f, Fx0 = %.6f\n", result.energy(), forces[0]);
} catch (const rgpot::Error &e) {
std::printf("%s\n", e.what());
return 1;
}
return 0;
}