C++ potentials -------------- Every potential derives from ``rgpot::Potential``, 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 :doc:`C++ API `. How the classes fit together is on :doc:`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/Angstrom\ :sup:`3`\, 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``. .. code:: cpp #include #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 at ``cutoff``, default 0.0, which keeps the shifted truncation). Units ``u0`` in eV; ``cutoff``, ``psi`` and ``switch_width`` in Angstrom. Outputs the parameters of ``rgpot::LJPot``. Errors the constructor throws ``std::invalid_argument`` when ``switch_width`` is non-zero and not in (0, cutoff]. No other field is checked. ``rgpot::LJClusterConfig`` ^^^^^^^^^^^^^^^^^^^^^^^^^^ Inputs the fields of ``rgpot::LJConfig`` with the same defaults: ``u0`` 1.0, ``cutoff`` 15.0, ``psi`` 1.0, ``switch_width`` 0.0. Units ``u0`` in eV; ``cutoff``, ``psi`` and ``switch_width`` in Angstrom. Outputs the parameters of ``rgpot::LJClusterPot``. Errors the constructor throws ``std::invalid_argument`` when ``switch_width`` is non-zero and not in (0, cutoff]. A ``cutoff`` of 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 ``De`` in eV, ``a`` in 1/Angstrom, ``re``, ``cutoff`` and ``switch_width`` in Angstrom. Outputs the parameters of ``rgpot::MorsePot``. Errors the constructor throws ``std::invalid_argument`` when ``switch_width`` is 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_argument`` unless 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 ``epsilon`` sets the energy unit and ``a`` the length unit; ``cutoff`` is in the coordinate unit; ``c``, ``n`` and ``m`` are dimensionless. Outputs the parameters of ``rgpot::SuttonChenPot``. Errors the constructor throws ``std::invalid_argument`` when ``n`` or ``m`` is below 1, when ``a`` is not positive, when ``epsilon``, ``c`` or ``cutoff`` is not finite, and when ``periodic`` is set with a ``cutoff`` that 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``, ``Setfl`` or ``FinnisSinclair``, default ``Setfl``), ``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. ``skin`` is in the length unit of the table. Outputs the parameters of ``rgpot::EAMTablePot``. Errors the constructor throws ``std::invalid_argument`` when ``path`` cannot be opened, when the file does not parse as ``format``, and when ``skin`` is 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::SPCEPot`` and ``rgpot::TIP4PPtPot``. Errors none; the constructors do not check the fields. ``rgpot::D3Config`` ^^^^^^^^^^^^^^^^^^^ Inputs ``damping`` (``D3Damping::BJ``, the rational damping, or ``D3Damping::Zero``; default ``BJ``), ``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_argument`` for an empty ``functional``, and ``std::runtime_error`` when 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 ``charge`` in elementary charges. Outputs the parameters of ``rgpot::D4Pot``. Errors the constructor throws ``std::invalid_argument`` for an empty ``functional``, and ``std::runtime_error`` when dftd4 cannot load damping parameters for it. ``charge`` is not checked. ``rgpot::lr::CoulombConfig`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Inputs ``method`` (``CoulombMethod::Ewald``, ``SPME`` or ``DSF``, default ``Ewald``), ``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_cutoff`` and ``skin`` in Angstrom; ``alpha`` in 1/Angstrom; the others are counts or flags. Outputs the parameters of ``rgpot::lr::CoulombPot``. ``stress`` false skips the strain and lets the SPME mesh run in single precision. Errors the constructor checks no field. The force call throws ``std::invalid_argument`` when ``cutoff`` or ``alpha`` is not positive, when ``kmax`` is below 1 with ``Ewald``, and when ``spline_order`` is outside 3 to 16 with ``SPME``. SPME raises a ``grid`` entry below 4 to 4. ``rgpot::lr::DispersionConfig`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Inputs ``kind`` (``DispersionKind::D3BJ``, ``D4``, ``MBD`` or ``QDO``, default ``QDO``), ``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_disp3`` and ``lib_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_cutoff`` and ``skin`` in Angstrom; ``lib_disp2``, ``lib_disp3`` and ``lib_cn`` in bohr; ``charge`` in 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_argument`` unless ``cutoff`` > ``switch_off`` > 0. ``skin`` is not checked. Shared members ~~~~~~~~~~~~~~ These members have the same declaration and behaviour on every class listed. A sentence after the fields names a class whose behaviour differs in detail. ``.paramsKey`` ^^^^^^^^^^^^^^ .. code:: cpp [[nodiscard]] uint64_t paramsKey() const noexcept override; Applies to rgpot\:\:EAMPot, rgpot\:\:EAMTablePot, rgpot\:\:EMTPot, rgpot\:\:ExprPot, rgpot\:\:LJClusterPot, rgpot\:\:LJPot, rgpot\:\:MorsePot, rgpot\:\:SPCEPot, rgpot\:\:StillingerWeberSi, rgpot\:\:SuttonChenPot, rgpot\:\:TIP4PPot, rgpot\:\:TIP4PPtPot, rgpot\:\:TersoffSiC, rgpot\:\:ZBLPot, rgpot\:\:lr\:\:CoulombPot, rgpot\:\:lr\:\:DispersionPot, rgpot\:\:lr\:\:NlhPot Inputs none. Units none. Outputs a 64-bit FNV-1a hash of the parameters and a kernel version, computed in the constructor. The result cache mixes it into its key. Errors none. ``rgpot::ExprPot`` hashes the expression, each term name and each child's ``paramsKey``. ``rgpot::lr::CoulombPot`` does not hash ``stress`` or ``short_cutoff``. ``rgpot::lr::DispersionPot`` does not hash ``functional``, ``periodic``, ``switch_width``, ``lib_disp2``, ``lib_disp3``, ``lib_cn``, ``mbd_gamma``, ``qdo_damped``, ``short_cutoff`` or ``skin``. ``.setNeighbourMode`` ^^^^^^^^^^^^^^^^^^^^^ .. code:: cpp void setNeighbourMode(nlist::Mode mode) noexcept; Applies to rgpot\:\:EAMPot, rgpot\:\:EAMTablePot, rgpot\:\:LJClusterPot, rgpot\:\:LJPot, rgpot\:\:MorsePot, rgpot\:\:StillingerWeberSi, rgpot\:\:SuttonChenPot, rgpot\:\:TersoffSiC, rgpot\:\:ZBLPot Inputs ``mode``: ``nlist::Mode::Stored`` keeps a Verlet list of candidate pairs, ``nlist::Mode::Stream`` walks the cells and stores no pairs, ``nlist::Mode::Auto`` (the default) stores when the index fits in the memory the OS reports. Units none. Outputs sets the mode used by later force calls. Errors none. In ``Auto``, ``rgpot::MorsePot`` stores from 20000 atoms up and ``rgpot::ZBLPot`` stores below two million atoms. ``.forcePerAtom`` ^^^^^^^^^^^^^^^^^ .. code:: cpp void forcePerAtom(const ForceInput &in, ForceOut *out, const PerAtomOut &atoms) const; Applies to rgpot\:\:EAMTablePot, rgpot\:\:LJClusterPot, rgpot\:\:LJPot, rgpot\:\:MorsePot, rgpot\:\:SuttonChenPot, rgpot\:\:ZBLPot Inputs ``in`` and ``out`` as for ``forceImpl``; ``atoms.energy`` (nAtoms doubles or null) and ``atoms.virial`` (6 \* nAtoms doubles or null). Units per-atom energy and per-atom virial in eV. Outputs fills ``out`` as ``forceImpl`` does, then writes the per-atom arrays. Each pair term goes half to each atom, and an embedding term goes to its own atom. Per-atom energies sum to ``out->energy``. The virial order per atom is xx, yy, zz, yz, xz, xy. A null array is skipped. Errors the exceptions of the class's ``forceImpl``. ``rgpot::LJClusterPot`` always walks the cells here, so its energy can differ from ``forceImpl`` in the last bits. ``.locality`` ^^^^^^^^^^^^^ .. code:: cpp [[nodiscard]] Locality locality() const noexcept; Applies to rgpot\:\:EAMTablePot, rgpot\:\:LJPot, rgpot\:\:MorsePot, rgpot\:\:SuttonChenPot Inputs none. Units ``cutoff`` in the length unit of the potential: Angstrom for ``rgpot::LJPot`` and ``rgpot::MorsePot``, the unit of ``a`` for ``rgpot::SuttonChenPot`` and the unit of the table for ``rgpot::EAMTablePot``. Outputs a ``rgpot::Locality`` from ``CppCore/rgpot/Locality.hpp``. ``cutoff`` is the range of each site energy, ``pairwise`` is true when every energy term is a function of one pair distance, and ``densities`` is the number of values per atom that ``densityStage`` sums and ``forceStage`` reads. ``forceRange()`` is ``cutoff`` for a pairwise potential and twice ``cutoff`` otherwise; the atoms within it of an atom set the force on that atom. A host that evaluates its own atoms with every atom within ``forceRange()`` of them, free of periodic images, gets the forces, site energies and per-atom virials those atoms have in the whole system. With ``densityStage`` and ``forceStage`` it needs only the atoms within ``cutoff``, and exchanges ``densities`` values per atom between the two stages. A ``cutoff`` of 0 declares no finite range. Errors none. ``rgpot::LJPot`` and ``rgpot::MorsePot`` return their cutoff with ``pairwise`` set, and 0 when the cutoff is 0 or less. ``rgpot::SuttonChenPot`` and ``rgpot::EAMTablePot`` return their cutoff as a many-body range with ``densities`` 1. ``rgpot::SuttonChenPot`` returns 0 when its cutoff is 0 or less, since it then keeps every pair. ``.densityStage`` ^^^^^^^^^^^^^^^^^ .. code:: cpp void densityStage(const HalfList &list, double *densities) const; Applies to rgpot\:\:EAMTablePot, rgpot\:\:SuttonChenPot Inputs ``list``, a ``rgpot::HalfList`` from ``CppCore/rgpot/Staged.hpp``. It holds the positions and atomic numbers of the host's ``nOwned`` atoms followed by their copies, ``nAtoms`` in all, and a half neighbour list over the owned atoms in the layout of a LAMMPS ``NeighList``. ``densities`` holds ``locality().densities`` values per atom for all ``nAtoms`` atoms, zeroed by the caller. Units positions in the length unit of the potential. The densities are those of the table for ``rgpot::EAMTablePot`` and sums of :math:`(a/r)^m` for ``rgpot::SuttonChenPot``. Outputs adds the density of each listed pair to its row atom, and to the other atom when that one is owned or ``list.newton`` is set. Pairs beyond the cutoff are skipped, so a list built with a skin works. The host completes the sums before ``forceStage``: with ``newton`` it adds the values of each copy into its owner, and it copies the values of each owner to its copies. Errors ``rgpot::EAMTablePot`` throws ``std::invalid_argument`` when a pair within the cutoff has an atomic number in no element line. ``rgpot::SuttonChenPot`` throws nothing. ``rgpot::LJPot`` and ``rgpot::MorsePot`` have no densities; their ``densityStage`` is listed with each class. ``.forceStage`` ^^^^^^^^^^^^^^^ .. code:: cpp void forceStage(const HalfList &list, const double *densities, double *forces, StageTally *tally) const; Applies to rgpot\:\:EAMTablePot, rgpot\:\:LJPot, rgpot\:\:MorsePot, rgpot\:\:SuttonChenPot Inputs ``list`` as for ``.densityStage``, and ``densities`` after the host completed them; the pair potentials do not read ``densities``. ``forces`` holds 3 \* nAtoms doubles, and ``tally`` is a ``rgpot::StageTally`` or null. Units the units of ``forceImpl``. Outputs adds the force of each listed pair to its row atom, and the opposite force to the other atom when that one is owned or ``list.newton`` is set. The many-body potentials take the embedding derivative of both atoms of a pair from their densities, so a copy needs the densities of its owner. With a tally it adds the host's share of the energy and of the virial W = -V sigma, in the order xx, yy, zz, yz, xz, xy. That share is all of a pair that only this host lists, half of a pair that both hosts list, and the embedding energy of each owned atom. ``tally->atoms`` takes the per-atom split of ``.forcePerAtom``; the entries of a copy are written only with ``newton``, for the host to add to its owner. Errors ``rgpot::EAMTablePot`` throws ``std::invalid_argument`` when a pair within the cutoff, or with a tally an owned atom, has an atomic number in no element line. The other classes throw nothing. ``rgpot::LJPot`` sets ``tally->energy`` to NaN when two listed atoms coincide. ``.listReused`` ^^^^^^^^^^^^^^^ .. code:: cpp [[nodiscard]] bool listReused() const noexcept; Applies to rgpot\:\:EAMPot, rgpot\:\:EAMTablePot, rgpot\:\:LJClusterPot, rgpot\:\:LJPot, rgpot\:\:MorsePot, rgpot\:\:ZBLPot Inputs none. Units none. Outputs true when the last force call kept the Verlet list, because no atom had moved by more than half the skin. Errors none. ``.retainedPairs`` ^^^^^^^^^^^^^^^^^^ .. code:: cpp [[nodiscard]] std::size_t retainedPairs() const noexcept; Applies to rgpot\:\:LJClusterPot, rgpot\:\:LJPot, rgpot\:\:MorsePot, rgpot\:\:ZBLPot Inputs none. Units none. Outputs the number of pair indices the last force call kept. It is 0 after a streaming call. Errors none. ``rgpot::LJClusterPot`` also reports 0 after a call that took the direct all-pairs kernel. ``.neighbourSkin`` ^^^^^^^^^^^^^^^^^^ .. code:: cpp [[nodiscard]] static double neighbourSkin(double cutoff) noexcept; Applies to rgpot\:\:MorsePot, rgpot\:\:ZBLPot Inputs ``cutoff``. Units ``cutoff`` and the result in Angstrom. Outputs the skin added to the cutoff for a stored list, ``cutoff / 5``. A streaming call uses no skin. Errors none. ``.setHeldSkin`` ^^^^^^^^^^^^^^^^ .. code:: cpp void setHeldSkin(double skin); Applies to rgpot\:\:TersoffSiC, rgpot\:\:fortranpots\:\:TersoffPot Inputs ``skin``, the extra search distance of a Verlet list kept across force calls. Units Angstrom. Outputs a positive skin keeps one list until an atom has moved by more than skin/2, or the cell or the atom count changes. 0, the default, rebuilds the pairs on every call. Each call drops the list held before. Errors throws ``std::invalid_argument`` when ``skin`` is negative or not finite. ``rgpot::fortranpots::TersoffPot`` passes the skin to its ``rgpot::TersoffSiC``, so it applies only to calls that reach the 1989 kernel. ``.setNeighbours`` ^^^^^^^^^^^^^^^^^^ .. code:: cpp void setNeighbours(std::shared_ptr lists); Applies to rgpot\:\:lr\:\:CoulombPot, rgpot\:\:lr\:\:DispersionPot, rgpot\:\:lr\:\:NlhPot Inputs ``lists``, a pair list with a short and a long cutoff. Units none. Outputs replaces the list the instance built in its constructor. Later force calls update and read ``lists``, so several summands can share one list. The cutoffs of ``lists`` then decide which pairs the summand sees. Errors none; a null pointer is stored and the next force call dereferences it. ``rgpot::lr::NlhPot`` reads the short pairs and updates the list without periodicity. ``.energyAndGradient`` ^^^^^^^^^^^^^^^^^^^^^^ .. code:: cpp void energyAndGradient(const double *positions, const int *atomic_numbers, const double *box, std::size_t n_atoms, double *energy, double *gradient, nlist::NeighborList *neighbors = nullptr) const; Applies to rgpot\:\:StillingerWeberSi, rgpot\:\:TersoffSiC Inputs ``positions`` (3 \* n\ :sub:`atoms`\ doubles, row-major), ``atomic_numbers`` (n\ :sub:`atoms`\ entries), ``box`` (nine doubles, periodic in every direction), ``n_atoms``, and an optional Verlet list ``neighbors``. Units positions and box in Angstrom; energy in eV; gradient in eV/Angstrom. Outputs ``\*energy`` and ``gradient`` (3 \* n\ :sub:`atoms`\ doubles), the derivative dE/dx. The force is the negative of the gradient. A null ``neighbors`` rebuilds the pairs on every call; a list is reused while each atom has moved by at most half its skin and the cell is unchanged. Errors throws ``std::invalid_argument`` for a null ``energy``, or for a null ``positions``, ``box`` or ``gradient`` when ``n_atoms`` > 0. ``rgpot::StillingerWeberSi`` does not read ``atomic_numbers`` and also throws ``std::invalid_argument`` for a non-finite position. ``rgpot::TersoffSiC`` also throws ``std::invalid_argument`` for a null ``atomic_numbers`` and for an atomic number other than 14 or 6. ``.energyAndGradientBatch`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code:: cpp void energyAndGradientBatch(std::size_t n_config, const double *positions, const int *atomic_numbers, const double *box, std::size_t n_atoms, double *energies, double *gradients) const; Applies to rgpot\:\:StillingerWeberSi, rgpot\:\:TersoffSiC Inputs ``n_config`` configurations of ``n_atoms`` atoms each, ``positions`` as ``n_config`` blocks of 3 \* n\ :sub:`atoms`\ doubles, one ``atomic_numbers`` array and one ``box`` shared by every configuration. Units positions and box in Angstrom; energies in eV; gradients in eV/Angstrom. Outputs ``energies`` (n\ :sub:`config`\ doubles) and ``gradients`` (n\ :sub:`config`\ \* n\ :sub:`atoms`\ \* 3 doubles, dE/dx per configuration). ``n_config`` of 0 returns without writing. Errors throws ``std::invalid_argument`` for a null ``energies``, or for a null ``positions``, ``box`` or ``gradients`` when ``n_atoms`` > 0, and the errors of ``energyAndGradient`` for each configuration. ``.config`` ^^^^^^^^^^^ .. code:: cpp [[nodiscard]] const WaterConfig &config() const noexcept; Applies to rgpot\:\:TIP4PPot, rgpot\:\:SPCEPot, rgpot\:\:TIP4PPtPot Inputs none. Units Angstrom, as in ``rgpot::WaterConfig``. Outputs the ``rgpot::WaterConfig`` the instance was built with. Errors none. 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`` ^^^^^^^^^^^^^^^^ .. code:: cpp LJPot(); explicit LJPot(const LJConfig &c); Inputs a ``rgpot::LJConfig``; the default constructor uses ``LJConfig{}``. Units energy in eV, forces in eV/Angstrom, stress in eV/Angstrom\ :sup:`3`\. Outputs a shifted 12-6 Lennard-Jones potential. With ``switch_width`` 0 each pair energy is shifted to zero at ``cutoff`` and the force jumps there. A non-zero ``switch_width`` drops the shift and multiplies each pair term by a C\ :sup:`2`\ quintic switch over [cutoff - switch\ :sub:`width`\, 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`` ^^^^^^^^^^^^^^^^^^^^^^^^ .. code:: cpp [[nodiscard]] const LJConfig &config() const noexcept; Inputs none. Units as in ``rgpot::LJConfig``. Outputs the ``rgpot::LJConfig`` the instance was built with. Errors none. ``rgpot::LJPot::densityStage`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code:: cpp void densityStage(const HalfList &, double *) const; Inputs a ``rgpot::HalfList`` and a density array, as for ``.densityStage``. Units none. Outputs none. A pair potential has no densities: ``locality().densities`` is 0, and the call writes nothing. Errors none. ``rgpot::LJClusterPot`` ^^^^^^^^^^^^^^^^^^^^^^^ .. code:: cpp LJClusterPot(); explicit LJClusterPot(const LJClusterConfig &c); Inputs a ``rgpot::LJClusterConfig``. Units energy in eV, forces in eV/Angstrom. Outputs the pair kernel of ``rgpot::LJPot`` with free boundaries. The cell is never used to fold pair vectors, and ``caps().periodic`` is 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 throws ``std::bad_alloc`` when its scratch allocation fails. ``rgpot::LJClusterPot::config`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code:: cpp [[nodiscard]] const LJClusterConfig &config() const noexcept; Inputs none. Units as in ``rgpot::LJClusterConfig``. Outputs the ``rgpot::LJClusterConfig`` the instance was built with. Errors none. ``rgpot::MorsePot`` ^^^^^^^^^^^^^^^^^^^ .. code:: cpp MorsePot(); explicit MorsePot(const MorseConfig &c); Inputs a ``rgpot::MorseConfig``. Units energy in eV, forces in eV/Angstrom, stress in eV/Angstrom\ :sup:`3`\. Outputs the pair energy De [1 - exp(-a (r - re))]\ :sup:`2`\ - De, shifted to zero at ``cutoff``. A non-zero ``switch_width`` replaces the shift by the quintic switch, as in ``rgpot::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`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code:: cpp [[nodiscard]] const MorseConfig &config() const noexcept; Inputs none. Units as in ``rgpot::MorseConfig``. Outputs the ``rgpot::MorseConfig`` the instance was built with. Errors none. ``rgpot::MorsePot::energyShift`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code:: cpp [[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_width`` is non-zero. Errors none. ``rgpot::MorsePot::densityStage`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code:: cpp void densityStage(const HalfList &, double *) const; Inputs a ``rgpot::HalfList`` and a density array, as for ``.densityStage``. Units none. Outputs none. A pair potential has no densities: ``locality().densities`` is 0, and the call writes nothing. Errors none. ``rgpot::ZBLPot`` ^^^^^^^^^^^^^^^^^ .. code:: cpp ZBLPot(); explicit ZBLPot(const ZBLConfig &c); Inputs a ``rgpot::ZBLConfig``. Units energy in eV, forces in eV/Angstrom, stress in eV/Angstrom\ :sup:`3`\. Outputs the universal screened nuclear repulsion. A polynomial between ``cut_inner`` and ``cut_global`` takes energy and force to zero at ``cut_global``. Coefficients come from the atomic numbers of the call, so any atomic number is accepted. Boundaries are free: ``caps().periodic`` is 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`` ^^^^^^^^^^^^^^^^^^^^^^^^^ .. code:: cpp [[nodiscard]] const ZBLConfig &config() const noexcept; Inputs none. Units Angstrom. Outputs the ``rgpot::ZBLConfig`` the instance was built with. Errors none. Embedded-atom and many-body metals ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ``rgpot::EAMPot`` ^^^^^^^^^^^^^^^^^ .. code:: cpp 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_argument`` when a diagonal entry of the box is not positive. An atomic number outside the table throws ``std::invalid_argument``. ``rgpot::EAMPot::listBuilds`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code:: cpp [[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`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code:: cpp [[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`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code:: cpp [[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`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code:: cpp [[nodiscard]] int threadsUsed() const noexcept; Inputs none. Units none. Outputs the number of threads the last force call used. Errors none. ``rgpot::EAMTablePot`` ^^^^^^^^^^^^^^^^^^^^^^ .. code:: cpp explicit EAMTablePot(const EAMTableConfig &c); EAMTablePot(const EAMTable &table, bool periodic, bool stress, double skin = 1.0); Inputs a ``rgpot::EAMTableConfig``, or a parsed ``EAMTable`` with the ``periodic`` and ``stress`` flags and the ``skin`` of 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 ``stress`` set the force call writes the stress. The force calls keep a list of the pairs within the cutoff plus ``skin`` while every atom stays within half of it, so ``caps().reentrancy`` is ``Reentrancy::PerInstance``. See :doc:`Tabulated EAM and Finnis-Sinclair potentials `. Errors ``std::invalid_argument`` with a message starting ``EAM table:``. The constructors throw it in the cases of ``rgpot::EAMTableConfig``, when an array count or length does not match, when ``skin`` is 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`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code:: cpp [[nodiscard]] std::uint64_t listBuilds() const noexcept; Inputs none. Units none. Outputs the number of pair lists ``forceImpl`` and ``forcePerAtom`` have 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`` ^^^^^^^^^^^^^^^^^^^^^^^^ .. code:: cpp SuttonChenPot(); explicit SuttonChenPot(const SuttonChenConfig &c); Inputs a ``rgpot::SuttonChenConfig``. Units energy in the unit of ``epsilon``, lengths in the unit of ``a``. With ``epsilon`` in eV and ``a`` in 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 ``periodic`` false the cell is not used to fold pairs. With ``stress`` set the force call writes the stress. See :doc:`Sutton-Chen `. Errors the errors of ``rgpot::SuttonChenConfig``. The force call throws ``std::invalid_argument`` when ``periodic`` is set and the cell is null or has a diagonal entry that is not positive. ``rgpot::SuttonChenPot::config`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code:: cpp [[nodiscard]] const SuttonChenConfig &config() const noexcept; Inputs none. Units as in ``rgpot::SuttonChenConfig``. Outputs the ``rgpot::SuttonChenConfig`` the instance was built with. Errors none. ``rgpot::SuttonChenPot::setPairTermLimit`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code:: cpp 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)^m`` and ``1/r^2`` for 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`` ^^^^^^^^^^^^^^^^^ .. code:: cpp 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 ``Exception`` class, which does not derive from ``std::exception``. ``rgpot::EMTPot::config`` ^^^^^^^^^^^^^^^^^^^^^^^^^ .. code:: cpp [[nodiscard]] const EMTConfig &config() const noexcept; Inputs none. Units none. Outputs the ``rgpot::EMTConfig`` the instance was built with. Errors none. Covalent potentials ~~~~~~~~~~~~~~~~~~~ ``rgpot::StillingerWeberSi`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code:: cpp StillingerWeberSi(); Inputs none; the parameters are the static members ``kEpsilon``, ``kSigma``, ``kA``, ``kB``, ``kP``, ``kCut``, ``kLambda`` and ``kGamma``. Units ``kEpsilon`` in eV (2.16723920), ``kSigma`` in Angstrom (2.0951); the others are dimensionless. Energy in eV, forces in eV/Angstrom, stress in eV/Angstrom\ :sup:`3`\. 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 behind ``PotType::SWSi``; see ``rgpot::fortranpots::SWPot`` and :doc:`Stillinger-Weber silicon (1985) `. Errors the force call throws ``std::invalid_argument`` for a null ``ForceOut``, for a null position, cell or force buffer when ``nAtoms`` > 0, and for a non-finite position. ``rgpot::TersoffSiC`` ^^^^^^^^^^^^^^^^^^^^^ .. code:: cpp 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/Angstrom\ :sup:`3`\. 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 :doc:`Tersoff Si-C `. Errors the force call throws ``std::invalid_argument`` for a null ``ForceOut``, for a null position, atomic number, cell or force buffer when ``nAtoms`` > 0, and for an atomic number other than 14 or 6. ``rgpot::TersoffSiC::heldList`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code:: cpp [[nodiscard]] const nlist::NeighborList &heldList() const noexcept; Inputs none. Units the list's cutoff and skin are in Angstrom. Outputs the Verlet list ``forceImpl`` keeps after ``setHeldSkin`` with 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`` ^^^^^^^^^^^^^^^^^^^ .. code:: cpp 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_argument`` when the atom count is not a multiple of 3. ``rgpot::SPCEPot`` ^^^^^^^^^^^^^^^^^^ .. code:: cpp 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_argument`` when the atom count is not a multiple of 3. ``rgpot::TIP4PPtPot`` ^^^^^^^^^^^^^^^^^^^^^ .. code:: cpp 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_argument`` for 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`` ^^^^^^^^^^^^^^^^ .. code:: cpp 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 throws ``std::runtime_error`` with the s-dftd3 message when building the structure or model, updating it, or computing the dispersion fails. ``rgpot::D3Pot::config`` ^^^^^^^^^^^^^^^^^^^^^^^^ .. code:: cpp [[nodiscard]] const D3Config &config() const noexcept; Inputs none. Units none. Outputs the ``rgpot::D3Config`` the instance was built with. Errors none. ``rgpot::D4Pot`` ^^^^^^^^^^^^^^^^ .. code:: cpp 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 throws ``std::runtime_error`` with the dftd4 message when building the structure or model, updating it, or computing the dispersion fails. ``rgpot::D4Pot::config`` ^^^^^^^^^^^^^^^^^^^^^^^^ .. code:: cpp [[nodiscard]] const D4Config &config() const noexcept; Inputs none. Units ``charge`` in elementary charges. Outputs the ``rgpot::D4Config`` the instance was built with. Errors none. Expression of potentials ~~~~~~~~~~~~~~~~~~~~~~~~ ``rgpot::ExprPot`` ^^^^^^^^^^^^^^^^^^ .. code:: cpp ExprPot(std::string expression, std::vector terms); Inputs ``expression``, a Lepton expression over the term names; ``terms``, pairs of a name and a ``std::unique_ptr`` 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(E\ :sub:`0`\, E\ :sub:`1`\, ...) 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_argument`` for 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`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code:: cpp [[nodiscard]] const std::string &expression() const noexcept; Inputs none. Units none. Outputs the expression string given to the constructor. Errors none. ``rgpot::ExprPot::dEnergyDTerm`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code:: cpp [[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_argument`` when ``name`` is not a term. Term names and constructor failures ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ How to compose terms is in :doc:`Compose potentials with ExprPot <../howto/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`` ^^^^^^^^^^^^^^^^^^^^^^^^^ .. code:: cpp CoulombPot(CoulombConfig cfg, std::shared_ptr charges, std::shared_ptr response = nullptr); Inputs a ``rgpot::lr::CoulombConfig``; ``charges`` gives 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/Angstrom\ :sup:`3`\. Outputs electrostatics: Ewald with a conducting boundary, smooth particle-mesh Ewald, or the damped shifted force in the gas phase. ``DSF`` always runs without a cell and writes no stress. With ``Ewald`` or ``SPME`` the force call writes the stress when the cell volume is positive. Errors the constructor throws ``std::invalid_argument`` for a null ``charges``. The force call throws ``std::invalid_argument`` in the cases of ``rgpot::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|``). ``FixedCharges`` throws ``std::invalid_argument`` when its length does not match the atom count. ``rgpot::lr::CoulombPot::neighbours`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code:: cpp [[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`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code:: cpp explicit DispersionPot(DispersionConfig cfg, std::shared_ptr ratios = nullptr, std::shared_ptr response = nullptr); Inputs a ``rgpot::lr::DispersionConfig``; ``ratios`` gives 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/Angstrom\ :sup:`3`\. Outputs one dispersion model as an additive potential. ``D3BJ`` and ``D4`` need s-dftd3 and dftd4 linked into the build. ``MBD`` accepts atomic numbers 1 to 102. ``QDO`` accepts 1 to 86, or 1 to 102 with ``qdo_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_argument`` for null atomic numbers, for an atomic number outside the model's table, and for MBD parameters that are not positive. It throws ``std::runtime_error`` when 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. ``FixedRatios`` throws ``std::invalid_argument`` when a ratio vector does not match the atom count. ``rgpot::lr::NlhPot`` ^^^^^^^^^^^^^^^^^^^^^ .. code:: cpp explicit NlhPot(NlhConfig cfg = {}); Inputs a ``rgpot::lr::NlhConfig``. Units energy in eV, forces in eV/Angstrom, stress in eV/Angstrom\ :sup:`3`\. 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 throws ``std::invalid_argument`` for null atomic numbers and for an atomic number outside 1 to 92. ``rgpot::lr::SumPot`` ^^^^^^^^^^^^^^^^^^^^^ .. code:: cpp SumPot(); Inputs none; terms are added with ``add``. Units the sum keeps the units of its terms: eV, eV/Angstrom and eV/Angstrom\ :sup:`3`\. 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_stress`` is 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`` ^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code:: cpp void add(std::unique_ptr term); Inputs ``term``, a potential the sum takes ownership of. Units none. Outputs appends ``term``. Errors throws ``std::invalid_argument`` for a null ``term``. ``rgpot::lr::SumPot::shareNeighbours`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code:: cpp void shareNeighbours(std::shared_ptr lists); Inputs ``lists``, one pair list. Units none. Outputs calls ``setNeighbours(lists)`` on every term added so far that is a ``rgpot::lr::CoulombPot``, ``rgpot::lr::DispersionPot`` or ``rgpot::lr::NlhPot``. Other terms and terms added later keep their own lists. Errors none. ``rgpot::lr::SumPot::size`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code:: cpp [[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 :doc:`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_error`` for 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_error`` when 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_error`` when 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_error`` for 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_error`` when the neighbour table reports a failure. ``rgpot::fortranpots::SWPot`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Inputs none. Units energy in eV, forces in eV/Angstrom, stress in eV/Angstrom\ :sup:`3`\. 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::StillingerWeberSi`` carries the published epsilon. Atomic numbers are not read. ``forceImpl`` writes the stress; the batch call does not. Errors ``std::runtime_error`` when 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 to ``rgpot::TersoffSiC``. No call writes a stress: ``has_stress`` is 0 and the tensor is zero. Errors ``std::runtime_error`` when the Fortran kernel reports a failure, and the ``std::invalid_argument`` cases of ``rgpot::TersoffSiC`` on 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_error`` for 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.