C++ potentials¶
Every potential derives from rgpot::Potential<Derived>, which derives from
rgpot::PotentialBase.
Energies are eV, lengths are Angstrom and forces are eV/Angstrom unless an entry
says otherwise.
This page lists the constructors, their configuration structs and the members
each class adds.
The members every potential inherits (forceImpl, forceBatch, caps,
setCache, …) are on C++ API.
How the classes fit together is on Architecture.
A force call takes a rgpot::ForceInput: nAtoms, pos (3 * nAtoms doubles, x
y z per atom, Angstrom), atmnrs (one atomic number per atom) and box (nine
doubles, one cell vector per row, Angstrom).
It writes a rgpot::ForceOut: F (3 * nAtoms doubles, same layout as pos,
eV/Angstrom), energy (eV), variance, and stress with has_stress. stress is the Cauchy stress in eV/Angstrom3,
nine entries row-major. A potential that writes it sets has_stress to 1, and
to 0 when the cell volume is not positive.
The program below evaluates a Lennard-Jones dimer with the default parameters.
It links against librgpot.
#include <cstdio>
#include "rgpot/LennardJones/LJPot.hpp"
int main() {
rgpot::LJPot pot({.u0 = 1.0, .cutoff = 15.0, .psi = 1.0});
const double pos[6] = {0.0, 0.0, 0.0, 1.5, 0.0, 0.0};
const int z[2] = {18, 18};
const double box[9] = {40.0, 0.0, 0.0, 0.0, 40.0, 0.0, 0.0, 0.0, 40.0};
double forces[6] = {};
rgpot::ForceInput in{2, pos, z, box};
rgpot::ForceOut out{};
out.F = forces;
pot.forceImpl(in, &out);
std::printf("energy %.6f eV\n", out.energy);
std::printf("force on atom 1, x: %.6f eV/Angstrom\n", forces[3]);
return 0;
}
Configuration structs¶
Each struct is a plain aggregate with inline defaults. Construct it with designated initializers and pass it to the constructor of its class.
rgpot::LJConfig¶
- Inputs
u0(well depth, default 1.0),cutoff(truncation distance, default 15.0),psi(zero-crossing distance, default 1.0),switch_width(width of the quintic switch that ends atcutoff, default 0.0, which keeps the shifted truncation).- Units
u0in eV;cutoff,psiandswitch_widthin Angstrom.- Outputs
the parameters of
rgpot::LJPot.- Errors
the constructor throws
std::invalid_argumentwhenswitch_widthis non-zero and not in (0, cutoff]. No other field is checked.
rgpot::LJClusterConfig¶
- Inputs
the fields of
rgpot::LJConfigwith the same defaults:u01.0,cutoff15.0,psi1.0,switch_width0.0.- Units
u0in eV;cutoff,psiandswitch_widthin Angstrom.- Outputs
the parameters of
rgpot::LJClusterPot.- Errors
the constructor throws
std::invalid_argumentwhenswitch_widthis non-zero and not in (0, cutoff]. Acutoffof 0 or less is accepted and keeps every pair.
rgpot::MorseConfig¶
- Inputs
De(well depth, default 0.7102),a(range, default 1.6047),re(equilibrium distance, default 2.8970),cutoff(default 9.5),switch_width(default 0.0). The defaults are the platinum set of the header.- Units
Dein eV,ain 1/Angstrom,re,cutoffandswitch_widthin Angstrom.- Outputs
the parameters of
rgpot::MorsePot.- Errors
the constructor throws
std::invalid_argumentwhenswitch_widthis non-zero and not in (0, cutoff]. No other field is checked.
rgpot::ZBLConfig¶
- Inputs
cut_inner(where the switch starts, default 2.0),cut_global(truncation distance, default 2.5).- Units
Angstrom.
- Outputs
the parameters of
rgpot::ZBLPot.- Errors
the constructor throws
std::invalid_argumentunless 0 <cut_inner<cut_global.
rgpot::SuttonChenConfig¶
- Inputs
epsilon(default 1.0),c(default 34.408),a(default 1.0),n(repulsive exponent, default 10),m(density exponent, default 8),cutoff(default 40.0; 0 or less keeps every pair),periodic(minimum image, default false),stress(write the stress, default false). The defaults are the reduced platinum and gold 10-8 potential.- Units
epsilonsets the energy unit andathe length unit;cutoffis in the coordinate unit;c,nandmare dimensionless.- Outputs
the parameters of
rgpot::SuttonChenPot.- Errors
the constructor throws
std::invalid_argumentwhennormis below 1, whenais not positive, whenepsilon,corcutoffis not finite, and whenperiodicis set with acutoffthat is not positive.
rgpot::EAMCellConfig¶
- Inputs
none; the struct has no fields.
- Units
none.
- Outputs
the argument of
rgpot::EAMPot, whose element table is built into the kernel.- Errors
none.
rgpot::EAMTableConfig¶
- Inputs
path(the table file, no default),format(EAMTableFormat::Funcfl,SetflorFinnisSinclair, defaultSetfl),periodic(minimum image, default true),stress(write the stress, default false),skin(Verlet skin of the potential’s own pair list, default 1.0).- Units
none; the table carries its own units, eV and Angstrom for the LAMMPS metal files.
skinis in the length unit of the table.- Outputs
the parameters of
rgpot::EAMTablePot.- Errors
the constructor throws
std::invalid_argumentwhenpathcannot be opened, when the file does not parse asformat, and whenskinis negative or not finite.
rgpot::EMTConfig¶
- Inputs
rasmussen(default false): true selects the Rasmussen parameter provider of Asap, false the Asap default provider.- Units
none.
- Outputs
the parameters of
rgpot::EMTPot.- Errors
none.
rgpot::WaterConfig¶
- Inputs
cutoff(default 8.5),switching_width(default 1.0). The defaults are the values the eOn wrappers pass.- Units
Angstrom.
- Outputs
the parameters of
rgpot::TIP4PPot,rgpot::SPCEPotandrgpot::TIP4PPtPot.- Errors
none; the constructors do not check the fields.
rgpot::D3Config¶
- Inputs
damping(D3Damping::BJ, the rational damping, orD3Damping::Zero; defaultBJ),functional(the s-dftd3 method key, default"pbe"),atm(the Axilrod-Teller-Muto three-body term, default true).- Units
none.
- Outputs
the parameters of
rgpot::D3Pot.- Errors
the constructor throws
std::invalid_argumentfor an emptyfunctional, andstd::runtime_errorwhen s-dftd3 cannot load damping parameters for it.
rgpot::D4Config¶
- Inputs
functional(the dftd4 method key, default"pbe"),charge(total charge, default 0.0),atm(the many-body term, default true).- Units
chargein elementary charges.- Outputs
the parameters of
rgpot::D4Pot.- Errors
the constructor throws
std::invalid_argumentfor an emptyfunctional, andstd::runtime_errorwhen dftd4 cannot load damping parameters for it.chargeis not checked.
rgpot::lr::CoulombConfig¶
- Inputs
method(CoulombMethod::Ewald,SPMEorDSF, defaultEwald),cutoff(real-space or DSF cutoff, default 9.0),alpha(splitting parameter, default 0.30),kmax(Ewald reciprocal shell, default 8),grid(SPME mesh, default 32 32 32),spline_order(SPME B-spline order, default 6),short_cutoff(short list, default 4.0),skin(default 1.0),periodic(default true),stress(default true).- Units
cutoff,short_cutoffandskinin Angstrom;alphain 1/Angstrom; the others are counts or flags.- Outputs
the parameters of
rgpot::lr::CoulombPot.stressfalse skips the strain and lets the SPME mesh run in single precision.- Errors
the constructor checks no field. The force call throws
std::invalid_argumentwhencutofforalphais not positive, whenkmaxis below 1 withEwald, and whenspline_orderis outside 3 to 16 withSPME. SPME raises agridentry below 4 to 4.
rgpot::lr::DispersionConfig¶
- Inputs
kind(DispersionKind::D3BJ,D4,MBDorQDO, defaultQDO),functional(D3 and D4 method key, default"pbe"),atm(three-body term, default true),charge(D4 total charge, default 0.0),mbd_beta(default 0.83),mbd_a(default 6.0),mbd_k(Monkhorst-Pack mesh for periodic MBD, default 4 4 4),mbd_gamma(one k-point at Gamma instead of the shifted mesh, default false),qdo_scale(default 1.0),qdo_legacy(legacy QDO tables, default false),qdo_damped(default true),cutoff(pair list cutoff, default 15.0),lib_disp2,lib_disp3andlib_cn(library real-space cutoffs, default 0.0, which keeps the library default),switch_width(default 0.0, a hard cutoff),short_cutoff(default 4.0),skin(default 1.0),periodic(default false).- Units
cutoff,switch_width,short_cutoffandskinin Angstrom;lib_disp2,lib_disp3andlib_cnin bohr;chargein elementary charges; the others are dimensionless, counts or flags.- Outputs
the parameters of
rgpot::lr::DispersionPot.- Errors
the constructor checks no field. Invalid values surface as the errors of the force call listed under
rgpot::lr::DispersionPot.
rgpot::lr::NlhConfig¶
- Inputs
cutoff(default 2.0),skin(default 0.5),switch_off(distance by which the repulsion is switched off, default 1.5).- Units
Angstrom.
- Outputs
the parameters of
rgpot::lr::NlhPot.- Errors
the constructor throws
std::invalid_argumentunlesscutoff>switch_off> 0.skinis not checked.
Pair potentials¶
Each class here has a config() member that returns its configuration struct;
the return type differs, so each has its own entry.
rgpot::LJPot¶
LJPot();
explicit LJPot(const LJConfig &c);
- Inputs
a
rgpot::LJConfig; the default constructor usesLJConfig{}.- Units
energy in eV, forces in eV/Angstrom, stress in eV/Angstrom3.
- Outputs
a shifted 12-6 Lennard-Jones potential. With
switch_width0 each pair energy is shifted to zero atcutoffand the force jumps there. A non-zeroswitch_widthdrops the shift and multiplies each pair term by a C2quintic switch over [cutoff - switchwidth, cutoff]. Pairs use the minimum image in every direction, so the call needs a cell. Atomic numbers are not read. A cutoff of 0 or less gives zero energy and forces. The force call writes the stress.- Errors
the errors of
rgpot::LJConfig. The force call does not check its pointers.
rgpot::LJPot::config¶
[[nodiscard]] const LJConfig &config() const noexcept;
- Inputs
none.
- Units
as in
rgpot::LJConfig.- Outputs
the
rgpot::LJConfigthe instance was built with.- Errors
none.
rgpot::LJPot::densityStage¶
void densityStage(const HalfList &, double *) const;
- Inputs
a
rgpot::HalfListand a density array, as for.densityStage.- Units
none.
- Outputs
none. A pair potential has no densities:
locality().densitiesis 0, and the call writes nothing.- Errors
none.
rgpot::LJClusterPot¶
LJClusterPot();
explicit LJClusterPot(const LJClusterConfig &c);
- Inputs
a
rgpot::LJClusterConfig.- Units
energy in eV, forces in eV/Angstrom.
- Outputs
the pair kernel of
rgpot::LJPotwith free boundaries. The cell is never used to fold pair vectors, andcaps().periodicis false. A cutoff of 0 or less keeps every pair. Atomic numbers are not read. The force call does not write a stress.- Errors
the errors of
rgpot::LJClusterConfig. The direct all-pairs kernel throwsstd::bad_allocwhen its scratch allocation fails.
rgpot::LJClusterPot::config¶
[[nodiscard]] const LJClusterConfig &config() const noexcept;
- Inputs
none.
- Units
as in
rgpot::LJClusterConfig.- Outputs
the
rgpot::LJClusterConfigthe instance was built with.- Errors
none.
rgpot::MorsePot¶
MorsePot();
explicit MorsePot(const MorseConfig &c);
- Inputs
a
rgpot::MorseConfig.- Units
energy in eV, forces in eV/Angstrom, stress in eV/Angstrom3.
- Outputs
the pair energy De [1 - exp(-a (r - re))]2- De, shifted to zero at
cutoff. A non-zeroswitch_widthreplaces the shift by the quintic switch, as inrgpot::LJPot. Pairs use the minimum image in every direction. Atomic numbers are not read. The force call writes the stress.- Errors
the errors of
rgpot::MorseConfig. The force call does not check its pointers.
rgpot::MorsePot::config¶
[[nodiscard]] const MorseConfig &config() const noexcept;
- Inputs
none.
- Units
as in
rgpot::MorseConfig.- Outputs
the
rgpot::MorseConfigthe instance was built with.- Errors
none.
rgpot::MorsePot::energyShift¶
[[nodiscard]] double energyShift() const noexcept;
- Inputs
none.
- Units
eV.
- Outputs
the unshifted pair energy at the cutoff, which is subtracted from every pair term. It is 0 when
switch_widthis non-zero.- Errors
none.
rgpot::MorsePot::densityStage¶
void densityStage(const HalfList &, double *) const;
- Inputs
a
rgpot::HalfListand a density array, as for.densityStage.- Units
none.
- Outputs
none. A pair potential has no densities:
locality().densitiesis 0, and the call writes nothing.- Errors
none.
rgpot::ZBLPot¶
ZBLPot();
explicit ZBLPot(const ZBLConfig &c);
- Inputs
a
rgpot::ZBLConfig.- Units
energy in eV, forces in eV/Angstrom, stress in eV/Angstrom3.
- Outputs
the universal screened nuclear repulsion. A polynomial between
cut_innerandcut_globaltakes energy and force to zero atcut_global. Coefficients come from the atomic numbers of the call, so any atomic number is accepted. Boundaries are free:caps().periodicis false and the cell is not used to fold pairs. The force call writes the stress when the cell volume is positive.- Errors
the errors of
rgpot::ZBLConfig.
rgpot::ZBLPot::config¶
[[nodiscard]] const ZBLConfig &config() const noexcept;
- Inputs
none.
- Units
Angstrom.
- Outputs
the
rgpot::ZBLConfigthe instance was built with.- Errors
none.
Embedded-atom and many-body metals¶
rgpot::EAMPot¶
EAMPot();
explicit EAMPot(const EAMCellConfig &);
- Inputs
an empty
rgpot::EAMCellConfig, or nothing.- Units
energy in eV, forces in eV/Angstrom.
- Outputs
the cell-list EAM kernel from eOn for aluminium (13), palladium (46) and gold (79). The element cutoffs are 5.555, 5.412 and 5.5155 Angstrom. The cell is periodic in every direction and only its diagonal (
box[0],box[4],box[8]) is used. A stored list adds a skin of one fifth of the widest cutoff. The force call does not write a stress.- Errors
the force call throws
std::invalid_argumentwhen a diagonal entry of the box is not positive. An atomic number outside the table throwsstd::invalid_argument.
rgpot::EAMPot::listBuilds¶
[[nodiscard]] std::uint64_t listBuilds() const noexcept;
- Inputs
none.
- Units
none.
- Outputs
the number of neighbour-list builds so far. A call on a geometry inside the Verlet skin does not increment it.
- Errors
none.
rgpot::EAMPot::neighborSlots¶
[[nodiscard]] std::size_t neighborSlots() const noexcept;
- Inputs
none.
- Units
none.
- Outputs
the number of stored neighbour indices after the last build.
- Errors
none.
rgpot::EAMPot::streamPartners¶
[[nodiscard]] std::size_t streamPartners() const noexcept;
- Inputs
none.
- Units
none.
- Outputs
the partner indices kept between the passes of a streaming call. The density-only stream keeps none.
- Errors
none.
rgpot::EAMPot::threadsUsed¶
[[nodiscard]] int threadsUsed() const noexcept;
- Inputs
none.
- Units
none.
- Outputs
the number of threads the last force call used.
- Errors
none.
rgpot::EAMTablePot¶
explicit EAMTablePot(const EAMTableConfig &c);
EAMTablePot(const EAMTable &table, bool periodic, bool stress,
double skin = 1.0);
- Inputs
a
rgpot::EAMTableConfig, or a parsedEAMTablewith theperiodicandstressflags and theskinof the pair list.- Units
the units of the table; eV and Angstrom for the LAMMPS metal files. Stress in energy per length cubed of the table.
- Outputs
the tabulated EAM or Finnis-Sinclair energy and forces. Each atom picks its element by its atomic number, matched against the first field of each element line. A pair counts when r is below the cutoff on the grid line of the table. With
stressset the force call writes the stress. The force calls keep a list of the pairs within the cutoff plusskinwhile every atom stays within half of it, socaps().reentrancyisReentrancy::PerInstance. See Tabulated EAM and Finnis-Sinclair potentials.- Errors
std::invalid_argumentwith a message startingEAM table:. The constructors throw it in the cases ofrgpot::EAMTableConfig, when an array count or length does not match, whenskinis negative or not finite, and for a negative atomic number in an element line. The force call throws it for an atomic number in no element line, for a periodic call without a cell, and when the cutoff exceeds half a face spacing of the cell.
This class is built with -Dwith_eam_table=true.
rgpot::EAMTablePot::listBuilds¶
[[nodiscard]] std::uint64_t listBuilds() const noexcept;
- Inputs
none.
- Units
none.
- Outputs
the number of pair lists
forceImplandforcePerAtomhave built so far. A call that keeps the list does not count, and the two stages, which run on the host’s list, build none.- Errors
none.
rgpot::SuttonChenPot¶
SuttonChenPot();
explicit SuttonChenPot(const SuttonChenConfig &c);
- Inputs
a
rgpot::SuttonChenConfig.- Units
energy in the unit of
epsilon, lengths in the unit ofa. Withepsilonin eV andain Angstrom, forces are eV/Angstrom.- Outputs
the Sutton-Chen energy and analytic forces, with no energy shift at the cutoff. Atomic numbers are not read. With
periodicfalse the cell is not used to fold pairs. Withstressset the force call writes the stress. See Sutton-Chen.- Errors
the errors of
rgpot::SuttonChenConfig. The force call throwsstd::invalid_argumentwhenperiodicis set and the cell is null or has a diagonal entry that is not positive.
rgpot::SuttonChenPot::config¶
[[nodiscard]] const SuttonChenConfig &config() const noexcept;
- Inputs
none.
- Units
as in
rgpot::SuttonChenConfig.- Outputs
the
rgpot::SuttonChenConfigthe instance was built with.- Errors
none.
rgpot::SuttonChenPot::setPairTermLimit¶
void setPairTermLimit(std::size_t pairs) noexcept;
- Inputs
pairs, the most pairs, summed over the threads of a call, whose density-pass terms the force pass reads back.- Units
none.
- Outputs
none. A force call keeps
epsilon n (a/r)^n,m (a/r)^mand1/r^2for each pair the density pass accepts, 24 bytes a pair, and the force pass computes the terms of the pairs past the limit again, with the same bits. The room for a call follows the pairs the previous call saw, so a walk whose pair count is not known in advance keeps its terms from the second call on. The default keeps 32 MiB of terms, and 0 keeps none.- Errors
none.
rgpot::EMTPot¶
EMTPot();
explicit EMTPot(const EMTConfig &config);
- Inputs
a
rgpot::EMTConfig.- Units
energy in eV, forces in eV/Angstrom.
- Outputs
the effective-medium theory energy and forces of the vendored Asap kernel. The default provider covers H (1), Mg (12), Al (13), Ni (28), Cu (29), Pd (46), Ag (47), Pt (78) and Au (79). The Rasmussen provider covers Al (13), Cu (29), Ag (47) and Au (79). The cell is periodic in every direction. The kernel is rebuilt when the atom count or any atomic number changes. The force call does not write a stress.
- Errors
an element the provider does not cover throws the Asap
Exceptionclass, which does not derive fromstd::exception.
rgpot::EMTPot::config¶
[[nodiscard]] const EMTConfig &config() const noexcept;
- Inputs
none.
- Units
none.
- Outputs
the
rgpot::EMTConfigthe instance was built with.- Errors
none.
Covalent potentials¶
rgpot::StillingerWeberSi¶
StillingerWeberSi();
- Inputs
none; the parameters are the static members
kEpsilon,kSigma,kA,kB,kP,kCut,kLambdaandkGamma.- Units
kEpsilonin eV (2.16723920),kSigmain Angstrom (2.0951); the others are dimensionless. Energy in eV, forces in eV/Angstrom, stress in eV/Angstrom3.- Outputs
Stillinger-Weber silicon with the 1985 published parameters. The cutoff is
kCut * kSigma. Atomic numbers are not read. The cell is periodic in every direction. The force call writes the stress. This is not the kernel behindPotType::SWSi; seergpot::fortranpots::SWPotand Stillinger-Weber silicon (1985).- Errors
the force call throws
std::invalid_argumentfor a nullForceOut, for a null position, cell or force buffer whennAtoms> 0, and for a non-finite position.
rgpot::TersoffSiC¶
TersoffSiC();
- Inputs
none; the parameters are the 1989 silicon and carbon sets with the 1990 erratum.
- Units
energy in eV, forces in eV/Angstrom, stress in eV/Angstrom3.
- Outputs
the Tersoff energy for silicon (14), carbon (6) and silicon carbide. The taper runs from 2.7 to 3.0 Angstrom for silicon and from 1.8 to 2.1 Angstrom for carbon; a mixed pair takes the geometric mean of each. The cell is periodic in every direction. The force call writes the stress. See Tersoff Si-C.
- Errors
the force call throws
std::invalid_argumentfor a nullForceOut, for a null position, atomic number, cell or force buffer whennAtoms> 0, and for an atomic number other than 14 or 6.
rgpot::TersoffSiC::heldList¶
[[nodiscard]] const nlist::NeighborList &heldList() const noexcept;
- Inputs
none.
- Units
the list’s cutoff and skin are in Angstrom.
- Outputs
the Verlet list
forceImplkeeps aftersetHeldSkinwith a positive skin. It is not built until such a call.- Errors
none.
Water¶
The three water classes take a rgpot::WaterConfig.
The cell is periodic and only its diagonal is used.
Energy is eV and forces are eV/Angstrom; no class writes a stress.
rgpot::TIP4PPot¶
TIP4PPot();
explicit TIP4PPot(const WaterConfig &config);
- Inputs
a
rgpot::WaterConfig.- Units
energy in eV, forces in eV/Angstrom.
- Outputs
flexible TIP4P water. For N molecules the first 2N atoms are the hydrogens, two per molecule in molecule order, and the last N atoms are the oxygens. Atomic numbers are not read. Zero atoms give zero energy.
- Errors
the force call throws
std::invalid_argumentwhen the atom count is not a multiple of 3.
rgpot::SPCEPot¶
SPCEPot();
explicit SPCEPot(const WaterConfig &config);
- Inputs
a
rgpot::WaterConfig.- Units
energy in eV, forces in eV/Angstrom.
- Outputs
flexible SPC/E water with the CCL intramolecular term, in the atom order of
rgpot::TIP4PPot. Atomic numbers are not read.- Errors
the force call throws
std::invalid_argumentwhen the atom count is not a multiple of 3.
rgpot::TIP4PPtPot¶
TIP4PPtPot();
explicit TIP4PPtPot(const WaterConfig &config);
- Inputs
a
rgpot::WaterConfig.- Units
energy in eV, forces in eV/Angstrom.
- Outputs
TIP4P water on platinum (Zhu-Philpott). The hydrogens come first in pairs, then one oxygen per pair, then the platinum atoms. The leading run of atomic number 1, read two atoms at a time, sets the number of molecules.
- Errors
the force call throws
std::invalid_argumentfor null atomic numbers, when the hydrogen pairs run past the last atom, and when the atom count is smaller than the water atoms.
Dispersion libraries¶
rgpot::D3Pot needs
-Dwith_dftd3=true and rgpot::D4Pot needs -Dwith_dftd4=true.
Both convert positions to bohr for the library and convert the result back to eV
and eV/Angstrom.
Both evaluate the molecule without periodicity, need a non-null cell, and write
no stress.
The structure is built on the first call and rebuilt when the atom count or any
atomic number changes; other calls only update the positions and the cell.
rgpot::D3Pot¶
D3Pot();
explicit D3Pot(const D3Config &config);
- Inputs
a
rgpot::D3Config.- Units
energy in eV, forces in eV/Angstrom.
- Outputs
Grimme DFT-D3 dispersion through the s-dftd3 C API.
- Errors
the errors of
rgpot::D3Config. The force call throwsstd::runtime_errorwith the s-dftd3 message when building the structure or model, updating it, or computing the dispersion fails.
rgpot::D3Pot::config¶
[[nodiscard]] const D3Config &config() const noexcept;
- Inputs
none.
- Units
none.
- Outputs
the
rgpot::D3Configthe instance was built with.- Errors
none.
rgpot::D4Pot¶
D4Pot();
explicit D4Pot(const D4Config &config);
- Inputs
a
rgpot::D4Config; the damping is always rational.- Units
energy in eV, forces in eV/Angstrom.
- Outputs
Grimme DFT-D4 dispersion through the dftd4 C API.
- Errors
the errors of
rgpot::D4Config. The force call throwsstd::runtime_errorwith the dftd4 message when building the structure or model, updating it, or computing the dispersion fails.
rgpot::D4Pot::config¶
[[nodiscard]] const D4Config &config() const noexcept;
- Inputs
none.
- Units
chargein elementary charges.- Outputs
the
rgpot::D4Configthe instance was built with.- Errors
none.
Expression of potentials¶
rgpot::ExprPot¶
ExprPot(std::string expression, std::vector<Term> terms);
- Inputs
expression, a Lepton expression over the term names;terms, pairs of a name and astd::unique_ptr<PotentialBase>child.- Units
each name stands for its child’s energy in eV. The energy is the value of the expression, and the forces are the sum of each child’s forces times the derivative of the expression with respect to that child’s energy.
- Outputs
a potential whose energy is f(E0, E1, …) over the children. The expression and each derivative are compiled once in the constructor. The variance is the sum of each child’s variance times its derivative, or 0 when any child variance is not finite.
caps()is the least reentrant of the children, periodic only when every child is. The force call does not write a stress.- Errors
the constructor throws
std::invalid_argumentfor an empty expression, zero terms, a name that is not a Lepton identifier, a duplicate name, a null child, a parse, compile or differentiation failure, a term name the expression does not use, and an identifier in the expression that is not a term name.
This class is built with -Dwith_expr=true.
rgpot::ExprPot::expression¶
[[nodiscard]] const std::string &expression() const noexcept;
- Inputs
none.
- Units
none.
- Outputs
the expression string given to the constructor.
- Errors
none.
rgpot::ExprPot::dEnergyDTerm¶
[[nodiscard]] double dEnergyDTerm(const std::string &name) const;
- Inputs
name, a term name.- Units
none; the derivative of eV by eV.
- Outputs
the derivative of the expression with respect to that term, evaluated at the child energies of the last force call. Before any force call the child energies are 0.
- Errors
throws
std::invalid_argumentwhennameis not a term.
Term names and constructor failures¶
How to compose terms is in Compose potentials with ExprPot.
A term name must be a Lepton identifier: an ASCII letter or underscore first,
then ASCII letters, digits, or underscores.
lj, morse, and d3 are valid.
1lj, lj-x, and lj.x are not.
The constructor throws std::invalid_argument before any force call when:
the expression is empty or blank
there are zero terms
a name is not a Lepton identifier
a name is duplicated
a child pointer is null
Lepton cannot parse or compile the expression
a supplied name is missing from the expression
an identifier in the expression has no child
ParsedExpression::differentiate(name)fails
Python raises ValueError with the same message.
Long-range summands¶
These classes are in namespace rgpot::lr and are built with
-Dwith_long_range=true.
Each one owns a DualList, a pair list with a short and a long cutoff, until
setNeighbours replaces it.
rgpot::lr::CoulombPot¶
CoulombPot(CoulombConfig cfg, std::shared_ptr<ChargeSource> charges,
std::shared_ptr<ChargeResponse> response = nullptr);
- Inputs
a
rgpot::lr::CoulombConfig;chargesgives the per-atom charges and the net charge each call;response, when not null, adds the chain rule for charges that depend on positions.- Units
charges in elementary charges; energy in eV, forces in eV/Angstrom, stress in eV/Angstrom3.
- Outputs
electrostatics: Ewald with a conducting boundary, smooth particle-mesh Ewald, or the damped shifted force in the gas phase.
DSFalways runs without a cell and writes no stress. WithEwaldorSPMEthe force call writes the stress when the cell volume is positive.- Errors
the constructor throws
std::invalid_argumentfor a nullcharges. The force call throwsstd::invalid_argumentin the cases ofrgpot::lr::CoulombConfig, when a charge, the net charge or a position is not finite, and when the charges do not sum to the net charge within 1e-6 (1 +|net charge|).FixedChargesthrowsstd::invalid_argumentwhen its length does not match the atom count.
rgpot::lr::CoulombPot::neighbours¶
[[nodiscard]] const DualList &neighbours() const;
- Inputs
none.
- Units
none.
- Outputs
the pair list the instance uses.
- Errors
none; after
setNeighbours(nullptr)the call dereferences a null pointer.
rgpot::lr::DispersionPot¶
explicit DispersionPot(DispersionConfig cfg, std::shared_ptr<RatioSource> ratios = nullptr,
std::shared_ptr<RatioResponse> response = nullptr);
- Inputs
a
rgpot::lr::DispersionConfig;ratiosgives the Hirshfeld volume ratio and the C6 ratio per atom, and null uses ratio 1 for every atom;response, when not null, adds the chain rule for ratios that depend on positions, by central differences of the energy.- Units
energy in eV, forces in eV/Angstrom, stress in eV/Angstrom3.
- Outputs
one dispersion model as an additive potential.
D3BJandD4need s-dftd3 and dftd4 linked into the build.MBDaccepts atomic numbers 1 to 102.QDOaccepts 1 to 86, or 1 to 102 withqdo_legacy. The force call writes the stress when the model reports one and the cell volume is positive.- Errors
the force call throws
std::invalid_argumentfor null atomic numbers, for an atomic number outside the model’s table, and for MBD parameters that are not positive. It throwsstd::runtime_errorwhen the D3 or D4 library was not linked, when the library reports an error, when the MBD screening matrix is singular and when an MBD eigenvalue is negative.FixedRatiosthrowsstd::invalid_argumentwhen a ratio vector does not match the atom count.
rgpot::lr::NlhPot¶
explicit NlhPot(NlhConfig cfg = {});
- Inputs
a
rgpot::lr::NlhConfig.- Units
energy in eV, forces in eV/Angstrom, stress in eV/Angstrom3.
- Outputs
the short-range repulsion of SO3LR, a sum of exponentials times a screened Coulomb term, switched off by
switch_off. It accepts atomic numbers 1 (H) to 92 (U). The list is always built without periodicity. Fewer than two atoms give zero energy.- Errors
the errors of
rgpot::lr::NlhConfig. The force call throwsstd::invalid_argumentfor null atomic numbers and for an atomic number outside 1 to 92.
rgpot::lr::SumPot¶
SumPot();
- Inputs
none; terms are added with
add.- Units
the sum keeps the units of its terms: eV, eV/Angstrom and eV/Angstrom3.
- Outputs
the sum of the energies, forces and variances of every term. The stress is the sum over the terms that report one, and
has_stressis 1 when any term reports one. An empty sum gives zero energy and forces.- Errors
the force call passes on the exceptions of its terms.
rgpot::lr::SumPot::add¶
void add(std::unique_ptr<PotentialBase> term);
- Inputs
term, a potential the sum takes ownership of.- Units
none.
- Outputs
appends
term.- Errors
throws
std::invalid_argumentfor a nullterm.
rgpot::lr::SumPot::size¶
[[nodiscard]] std::size_t size() const noexcept;
- Inputs
none.
- Units
none.
- Outputs
the number of terms.
- Errors
none.
Fortran kernels¶
These classes are in namespace rgpot::fortranpots and are built with
-Dwith_fortran_pots=enabled.
Each has only a default constructor.
Each instance owns a Fortran workspace with its own neighbour table, kept
between calls.
A kernel failure throws std::runtime_error with the label of the kernel, the
status and the kernel’s message.
A workspace that cannot be allocated throws std::bad_alloc from the
constructor.
Zero atoms give zero energy and forces.
Energy is eV and forces are eV/Angstrom.
The porting rules are on
Fortran potentials: porting rules.
rgpot::fortranpots::CuH2Pot¶
- Inputs
none.
- Units
energy in eV, forces in eV/Angstrom.
- Outputs
the EAM potential for copper (29) and hydrogen (1) from eOn, with a cutoff of 6.1 Angstrom. The force call does not write a stress.
- Errors
std::runtime_errorfor an atomic number other than 29 or 1, and when two atoms occupy the same position.
rgpot::fortranpots::EAMAlPot¶
- Inputs
none.
- Units
energy in eV, forces in eV/Angstrom.
- Outputs
the double-exponential EAM for aluminium from eOn, with a cutoff of 7.1 Angstrom stored as a single-precision literal. Atomic numbers are not read. The force call does not write a stress.
- Errors
std::runtime_errorwhen the kernel or the neighbour table reports a failure.
rgpot::fortranpots::EDIPPot¶
- Inputs
none.
- Units
energy in eV, forces in eV/Angstrom.
- Outputs
the environment-dependent interatomic potential for silicon, with a cutoff of 3.1213820 Angstrom. Atomic numbers are not read. The force call does not write a stress.
- Errors
std::runtime_errorwhen the cell is thinner than the cutoff, and when the neighbour table reports a failure.
rgpot::fortranpots::FeHePot¶
- Inputs
none.
- Units
energy in eV, forces in eV/Angstrom.
- Outputs
the iron (26) and helium (2) potential from eOn, with Fe-Fe, Fe-He and He-He pair terms. The neighbour table uses the largest of its cutoffs, 5.4 Angstrom for the He-He pair. The force call does not write a stress.
- Errors
std::runtime_errorfor an atomic number other than 26 or 2.
rgpot::fortranpots::LenoskyPot¶
- Inputs
none.
- Units
energy in eV, forces in eV/Angstrom.
- Outputs
the Lenosky silicon potential from eOn, with a cutoff of 4.5 Angstrom. Atomic numbers are not read. The force call does not write a stress.
- Errors
std::runtime_errorwhen the neighbour table reports a failure.
rgpot::fortranpots::SWPot¶
- Inputs
none.
- Units
energy in eV, forces in eV/Angstrom, stress in eV/Angstrom3.
- Outputs
Stillinger-Weber silicon with eOn’s epsilon, 2.16826 * 1.06767385 eV, and sigma 2.0951 Angstrom; the cutoff is 1.8 sigma. This is
PotType::SWSi;rgpot::StillingerWeberSicarries the published epsilon. Atomic numbers are not read.forceImplwrites the stress; the batch call does not.- Errors
std::runtime_errorwhen the kernel or the neighbour table reports a failure.
rgpot::fortranpots::TersoffPot¶
- Inputs
none.
- Units
energy in eV, forces in eV/Angstrom.
- Outputs
Tersoff silicon (
PotType::TersoffSi). A call where every atomic number is 14, or the atomic numbers are null, uses the Fortran gather with a cutoff of 3.0 Angstrom. Any other atomic number sends the call torgpot::TersoffSiC. No call writes a stress:has_stressis 0 and the tensor is zero.- Errors
std::runtime_errorwhen the Fortran kernel reports a failure, and thestd::invalid_argumentcases ofrgpot::TersoffSiCon the other path.
rgpot::fortranpots::WaterHPot¶
- Inputs
none.
- Units
energy in eV, forces in eV/Angstrom.
- Outputs
one hydrogen atom in the field of water molecules, Andersson’s potH-H2O surface. Atoms are hydrogen (1) and oxygen (8): whole water molecules followed by the lone H as the last atom. Every site interacts with the lone H at its nearest periodic image; there is no cutoff. The force call does not write a stress.
- Errors
std::runtime_errorfor fewer than 4 atoms, for an atomic number other than 1 or 8, when the last atom is not hydrogen, for no oxygen, when the hydrogens are not two per oxygen plus one, and when an atom coincides with the lone H.