Python API ---------- The extension module is ``rgpot._core``, and ``import rgpot`` re-exports its public names. Stubs live in ``rgpot/_core.pyi`` and the package ships ``py.typed``. A class or function whose build flag is off is ``None`` in ``rgpot``, for example ``rgpot.D3Pot`` when ``rgpot.has_dftd3`` is false. The ``rgpot.has_*`` entries below name the flag for each one. Calculators ~~~~~~~~~~~ .. table:: +----------------------------------+--------------------------------------------------------+ | Symbol | Role | +==================================+========================================================+ | ``rgpot.ase.RgpotCalculator`` | In-process ASE calculator | +----------------------------------+--------------------------------------------------------+ | ``rgpot.ase.RgpotRpcCalculator`` | Cap'n Proto ASE calculator | +----------------------------------+--------------------------------------------------------+ | ``rgpot.ase.AnnealRunner`` | Portfolio relaxation, not an ASE optimizer | +----------------------------------+--------------------------------------------------------+ | ``rgpot.ase.AnnealOptimizer`` | Deprecated alias of ``AnnealRunner`` | +----------------------------------+--------------------------------------------------------+ | ``rgpot.ase.available_kinds()`` | Kind strings ``RgpotCalculator`` accepts in this build | +----------------------------------+--------------------------------------------------------+ ``RgpotCalculator.calculate_many(frames)`` returns one dict per frame. ``threads`` selects the worker count; 0 uses the hardware concurrency. Results for energy and forces match one call per frame, bit for bit. The worker count is not part of the result. See the :doc:`ASE how-to <../howto/ase>` and the :doc:`thread-safety <../explanation/thread-safety>` page. Conventions ~~~~~~~~~~~ Every call that takes ``positions``, ``atom_types`` and ``box`` reads them the same way. - ``positions`` is a NumPy array of shape ``(N, 3)``, dtype float64, C-contiguous, in Angstrom. - ``box`` is a ``(3, 3)`` float64 C-contiguous array in Angstrom, row-major, one cell vector per row. - ``atom_types`` holds one atomic number per atom. It is a list or tuple of Python integers, or a one-dimensional C-contiguous int32 or int64 array. Values are copied into int32. - The energy is eV, forces are eV/Angstrom and equal minus the gradient, and stress is eV/Angstrom\ :sup:`3`\. - The variance is eV\ :sup:`2`\; kernels that do not estimate one return 0.0. - Returned arrays are new float64 (or int32) C-contiguous NumPy arrays owned by the caller. The checks run in this order and raise these exceptions: - ``positions`` or ``box`` that is not a float64 C-contiguous NumPy array (a list, float32, a strided view) raises ``TypeError`` from the argument conversion. - ``positions`` that is not two-dimensional with 3 columns raises ``ValueError``, for example ``positions: expected shape (N, 3), got (2, 2)``. - ``box`` that is not ``(3, 3)`` raises ``ValueError`` ``box: expected shape (3, 3), got ...``. - ``atom_types`` whose length is not ``N`` raises ``ValueError`` ``atom_types: expected shape (N,), got (M,)``. - ``atom_types`` that is not a sequence of integers (floats, booleans) or an int32/int64 array raises ``TypeError``. - An atomic number outside the int32 range raises ``ValueError``. - A kernel that rejects its input with ``std::invalid_argument`` raises ``ValueError``; a kernel that fails with ``std::runtime_error`` raises ``RuntimeError``. The message is the kernel's own text. - A non-finite energy raises ``rgpot.NumericalError``, except where an entry says otherwise. .. code:: python import numpy as np import rgpot pot = rgpot.LJPot() positions = np.array([[0.0, 0.0, 0.0], [1.1, 0.0, 0.0]]) box = np.eye(3) * 20.0 energy, forces, variance = pot(positions, [1, 1], box) print(f"{energy:.10f}", forces.shape, forces.dtype, variance) result = pot.evaluate(positions, [1, 1], box) print(sorted(result), result["stress"].shape) :: -0.9833720982 (2, 3) float64 0.0 ['energies', 'energy', 'forces', 'stress', 'variance'] (3, 3) .. code:: python import numpy as np import rgpot pot = rgpot.LJPot() box = np.eye(3) * 20.0 try: pot(np.zeros((2, 3), dtype=np.float32), [1, 1], box) except TypeError: print("TypeError") try: pot(np.zeros((2, 2)), [1, 1], box) except ValueError as err: print(err) try: pot(np.zeros((2, 3)), [1], box) except ValueError as err: print(err) try: pot(np.zeros((2, 3)), [1, 1], box) except rgpot.NumericalError as err: print(err) :: TypeError positions: expected shape (N, 3), got (2, 2) atom_types: expected shape (2,), got (1,) energy is not finite Module attributes ~~~~~~~~~~~~~~~~~ ``rgpot.__version__`` ^^^^^^^^^^^^^^^^^^^^^ Inputs none. Units none. Outputs the package version string. The extension sets it from ``RGPOT_PY_VERSION`` at build time, or ``"0.0.0"`` when the build did not define it. Errors none. ``rgpot.has_cache`` ^^^^^^^^^^^^^^^^^^^ Inputs none. Units none. Outputs ``True`` when the extension was compiled with ``RGPOT_HAS_CACHE``, so ``rgpot.PotentialCache`` is a class. Errors none. ``rgpot.has_dftd3`` ^^^^^^^^^^^^^^^^^^^ Inputs none. Units none. Outputs ``True`` when the extension was compiled with ``RGPOT_HAS_DFTD3``, so ``rgpot.D3Pot`` is a class and ``ExprPot`` accepts the ``"d3"`` kind. Errors none. ``rgpot.has_dftd4`` ^^^^^^^^^^^^^^^^^^^ Inputs none. Units none. Outputs ``True`` when the extension was compiled with ``RGPOT_HAS_DFTD4``, so ``rgpot.D4Pot`` is a class and ``ExprPot`` accepts the ``"d4"`` kind. Errors none. ``rgpot.has_expr`` ^^^^^^^^^^^^^^^^^^ Inputs none. Units none. Outputs ``True`` when the extension was compiled with ``RGPOT_HAS_EXPR``, so ``rgpot.ExprPot`` is a class. Errors none. ``rgpot.has_fortran_pots`` ^^^^^^^^^^^^^^^^^^^^^^^^^^ Inputs none. Units none. Outputs ``True`` when the extension was compiled with ``RGPOT_HAS_FORTRAN_POTS``. The Fortran kernel classes ``SWPot``, ``EDIPPot``, ``LenoskyPot``, ``TersoffPot``, ``EAMAlPot``, ``FeHePot``, ``CuH2Pot`` and ``WaterHPot`` exist only then. Errors none. ``rgpot.has_ipi`` ^^^^^^^^^^^^^^^^^ Inputs none. Units none. Outputs ``True`` when the extension was compiled with ``RGPOT_HAS_IPI``, so ``rgpot.IPIPot`` is a class. Errors none. ``rgpot.has_metatomic_dlopen`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Inputs none. Units none. Outputs ``True`` when the extension was compiled with ``RGPOT_HAS_METATOMIC``, so ``rgpot.evaluate_metatomic_dlopen`` is a function. Errors none. ``rgpot.has_xckernel`` ^^^^^^^^^^^^^^^^^^^^^^ Inputs none. Units none. Outputs ``True`` when the extension was compiled with ``RGPOT_HAS_XCKERNEL``, so ``rgpot.XcKernel`` is a class. Errors none. ``rgpot.PotentialCache`` ^^^^^^^^^^^^^^^^^^^^^^^^ Inputs none. Units none. Outputs the ``rgpot._core.PotentialCache`` class when ``rgpot.has_cache`` is true, otherwise ``None``. The class is not in the stub. Its constructor is ``PotentialCache(path, create_if_missing=True)`` and opens a RocksDB database at ``path``. ``counts()`` returns ``(computed, served)``, the results the kernel produced and the results the cache answered since construction or the last ``reset_counts()``. In a cache build ``LJPot`` also has ``set_cache(cache)``, which takes a ``PotentialCache`` or ``None``. Errors a database that cannot be opened does not raise. The constructor prints the RocksDB status to standard error and the object holds no database. ``rgpot.NumericalError`` ^^^^^^^^^^^^^^^^^^^^^^^^ Inputs the message string. Units none. Outputs an exception class, a subclass of ``ArithmeticError``. Potential calls raise it when the energy is not finite. ``hvp`` and ``hvp_centre`` also raise it when a force or a product is not finite. Errors none. Functions ~~~~~~~~~ ``rgpot.evaluate_lj`` ^^^^^^^^^^^^^^^^^^^^^ .. code:: python evaluate_lj(positions, atom_types, box) Inputs ``positions`` ``(N, 3)``, ``atom_types`` (``N`` integers, not used by the kernel), ``box`` ``(3, 3)``, as in the conventions. Units positions and box in Angstrom; energy eV; forces eV/Angstrom. Outputs a tuple ``(energy, forces, variance)``: a float, a ``(N, 3)`` float64 array and the float 0.0. Each call builds an ``LJPot`` with the default parameters, ``u0`` 1 eV, ``cutoff`` 15 Angstrom and ``psi`` 1 Angstrom. Errors the conventions list; a non-finite energy raises ``rgpot.NumericalError``. ``rgpot.neighbor_list`` ^^^^^^^^^^^^^^^^^^^^^^^ .. code:: python neighbor_list(positions, cell, cutoff, quantities='ijd', full=False, offsets=False) Inputs ``positions`` ``(natoms, 3)`` and ``cell`` ``(3, 3)``, float64 C-contiguous, the cell periodic in all three directions. ``cutoff`` is the pair cutoff. ``quantities`` is a string of the letters ``i``, ``j``, ``d``, ``D`` and ``S``, and sets which arrays come back and in which order. ``full=False`` lists each pair once; ``full=True`` lists both ``(i, j)`` and ``(j, i)``. ``offsets=True`` sorts the pairs by ``i``, then ``j``, and appends a row pointer. Units positions, cell, cutoff, ``d`` and ``D`` in Angstrom; ``i``, ``j``, ``S`` and the row pointer are counts. Outputs one array when a single array is requested, otherwise a tuple in the order of ``quantities``, with the row pointer last. ``i`` and ``j`` are int32 of shape ``(npairs,)``; ``d`` is the float64 distance, ``(npairs,)``; ``D`` is ``r_j - r_i``, float64 ``(npairs, 3)``; ``S`` is the int32 cell shift, ``(npairs, 3)``. The row pointer is int32 of length ``natoms + 1``. A cutoff longer than the cell lists periodic images, including an atom with its own image. Errors ``positions`` or ``cell`` that is not a float64 C-contiguous array raises ``TypeError``. A wrong shape, a letter outside ``ijdDS``, a negative or non-finite cutoff, or a cell with zero volume raises ``ValueError``. .. code:: python import numpy as np import rgpot positions = np.array([[0.0, 0.0, 0.0], [1.1, 0.0, 0.0], [0.0, 2.5, 0.0]]) cell = np.eye(3) * 10.0 i, j, d = rgpot.neighbor_list(positions, cell, 2.0) print(i, j, d) i, j, offsets = rgpot.neighbor_list(positions, cell, 2.0, "ij", full=True, offsets=True) print(i, j, offsets) :: [0] [1] [1.1] [0 1] [1 0] [0 1 2 2] ``rgpot.evaluate_metatomic`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code:: python evaluate_metatomic(positions, atom_types, box, *, model_path, engine_path=None, device='cpu') Inputs ``positions``, ``atom_types`` (atomic numbers) and ``box`` as in the conventions. ``model_path`` (keyword only) is the exported model file. ``engine_path`` ``None`` uses ``rgpot.default_metatomic_engine_path()``, or an empty string when that is ``None``. ``device`` is the torch device string. Units positions and box in Angstrom; energy eV; forces eV/Angstrom. Outputs the tuple ``(energy, forces, variance)`` of ``rgpot.evaluate_metatomic_dlopen``. The function imports ``torch`` first when it is installed, so the engine resolves the same ``libtorch``. Errors ``RuntimeError`` ``this build has no MetatomicDlopen frontend`` when ``rgpot.has_metatomic_dlopen`` is false. Otherwise the errors of ``rgpot.evaluate_metatomic_dlopen``. ``rgpot.evaluate_metatomic_dlopen`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code:: python evaluate_metatomic_dlopen(positions, atom_types, box, model_path, engine_path='', device='cpu') Inputs ``positions``, ``atom_types`` and ``box`` as in the conventions. ``model_path`` is the exported model. The frontend tries ``engine_path`` when it is not empty, then ``RGPOT_METATOMIC_ENGINE``, ``METATOMIC_ENGINE``, ``libmetatomic_engine.so`` on the loader path, and ``libmetatomic_engine.so`` in each directory of ``EON_POTENTIALS_PATH`` and ``RGPOT_ENGINE_PATH``. It does not search the engines bundled with the package; ``rgpot.evaluate_metatomic`` does. An empty ``device`` means ``"cpu"``. Units positions and box in Angstrom; energy eV; forces eV/Angstrom. Outputs a tuple ``(energy, forces, variance)``: a float, a ``(N, 3)`` float64 array and a float. Each call builds and drops its own frontend. ``None`` when ``rgpot.has_metatomic_dlopen`` is false. Errors an empty ``model_path`` raises ``ValueError``. No candidate library that opens raises ``RuntimeError`` ``MetatomicDlopen: libmetatomic_engine.so not found ...``. An ABI version mismatch, missing engine symbols, or a model the engine cannot create also raise ``RuntimeError`` with a ``MetatomicDlopen:`` message. A non-finite energy raises ``rgpot.NumericalError``; the conventions list the input errors. ``rgpot.default_metatomic_engine_path`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code:: python default_metatomic_engine_path() Inputs none. Units none. Outputs the path of the first engine library found, as a string, or ``None``. The search order is ``rgpot/lib/torch-X.Y/`` for the installed torch major, then every ``rgpot/lib/torch-*/`` directory, then the legacy single-engine locations, then the ``RGPOT_METATOMIC_ENGINE`` and ``METATOMIC_ENGINE`` environment variables. In each directory ``librgpot_metatomic_engine.so`` comes before ``libmetatomic_engine.so``. Errors none; a missing torch or missing files give ``None``. ``rgpot.available_metatomic_engine_abis`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code:: python available_metatomic_engine_abis() Inputs none. Units none. Outputs a list of torch ``X.Y`` strings, one per ``rgpot/lib/torch-X.Y/`` directory that holds an engine library, in sorted order. The list is empty when the package has no ``lib`` directory. Errors none. ``rgpot.rgpot_lammps_potential`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code:: python rgpot_lammps_potential(u0=1.0, cutoff=8.0, psi=1.0, engine_path='') Inputs the shifted 12-6 Lennard-Jones parameters ``u0`` (well depth), ``cutoff`` and ``psi`` (zero crossing), and ``engine_path``. An empty ``engine_path`` tries ``RGPOT_LAMMPS_ENGINE``, ``LAMMPS_ENGINE``, ``liblammps_engine.so`` and ``liblj_engine.so``, in that order. Units ``u0`` eV; ``cutoff`` and ``psi`` Angstrom. Outputs a ``rgpot.LammpsPot`` whose backend is the engine plugin the constructor opened. Errors ``u0``, ``cutoff`` or ``psi`` that is not positive and finite raises ``ValueError``. No engine library that opens and exports ``rgpot_engine_force`` raises ``RuntimeError`` ``engine library was not opened: ...``, listing each path tried. ``rgpot.rgpot_gromacs_potential`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code:: python rgpot_gromacs_potential(u0=1.0, cutoff=8.0, psi=1.0, engine_path='') Inputs the shifted 12-6 Lennard-Jones parameters ``u0``, ``cutoff`` and ``psi``, and ``engine_path``. An empty ``engine_path`` evaluates the potential in process. A path names a library whose ``rgpot_md_native_force`` works in nanometres and kJ/mol. Units ``u0`` eV; ``cutoff`` and ``psi`` Angstrom. The object stores them once in kJ/mol and nanometres; ``native_u0``, ``native_cutoff`` and ``native_psi`` read the stored values. Outputs a ``rgpot.GromacsPot``. Errors ``u0``, ``cutoff`` or ``psi`` that is not positive and finite raises ``ValueError``. A library that does not open or lacks ``rgpot_md_native_force`` raises ``RuntimeError``. ``rgpot.rgpot_openmm_potential`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code:: python rgpot_openmm_potential(u0=1.0, cutoff=8.0, psi=1.0, engine_path='') Inputs as ``rgpot.rgpot_gromacs_potential``; an example library is ``libopenmm_engine.so``. Units ``u0`` eV; ``cutoff`` and ``psi`` Angstrom, stored once in kJ/mol and nanometres. Outputs a ``rgpot.OpenMMPot``. Errors as ``rgpot.rgpot_gromacs_potential``. The in-process GROMACS and OpenMM objects give the same energy. The dimer at 1.5 Angstrom with ``u0`` 1, cutoff 8 and ``psi`` 1: .. code:: python import numpy as np import rgpot dimer = np.array([[0.0, 0.0, 0.0], [1.5, 0.0, 0.0]]) box = np.eye(3) * 20.0 for make in (rgpot.rgpot_gromacs_potential, rgpot.rgpot_openmm_potential): pot = make(u0=1.0, cutoff=8.0, psi=1.0) energy, forces, variance = pot(dimer, [1, 1], box) print(type(pot).__name__, f"{energy:.10f}", pot.native_u0(), pot.native_cutoff(), pot.native_psi()) :: GromacsPot -0.3203213355 96.48533212331002 0.8 0.1 OpenMMPot -0.3203213355 96.48533212331002 0.8 0.1 Potential classes ~~~~~~~~~~~~~~~~~ Each class entry gives the constructor. The methods are in the shared-method entries further down, and each lists the classes that have it. Only the fourteen classes ``LJPot``, ``LJClusterPot``, ``MorsePot``, ``SWPot``, ``EDIPPot``, ``LenoskyPot``, ``TersoffPot``, ``EAMAlPot``, ``FeHePot``, ``CuH2Pot``, ``WaterHPot``, ``D3Pot``, ``D4Pot`` and ``ExprPot`` have ``hvp`` and ``evaluate_batch``. ``StillingerWeberSi``, ``TersoffSiC``, ``IPIPot``, ``LammpsPot``, ``GromacsPot`` and ``OpenMMPot`` do not. The fourteen classes build their kernel in the constructor. A constructor argument the kernel rejects raises there, not at the first call. They keep one kernel instance per calling thread, except for kernels that share one instance. ``rgpot.LJPot`` ^^^^^^^^^^^^^^^ .. code:: python rgpot.LJPot(u0=1.0, cutoff=15.0, psi=1.0, switch_width=0.0) Inputs ``u0`` is the well depth, ``cutoff`` the pair cutoff and ``psi`` the zero crossing of the 12-6 term. ``switch_width`` 0 keeps the shifted truncation. A positive ``switch_width`` replaces the shift with the C\ :sup:`2`\ quintic switch over ``[cutoff - switch_width, cutoff]``. Atom types are read but the kernel does not use them; every atom is the same species. Units ``u0`` eV; ``cutoff``, ``psi`` and ``switch_width`` Angstrom. Outputs a periodic Lennard-Jones potential. ``evaluate`` returns the stress. Errors a nonzero ``switch_width`` outside ``0 < switch_width <`` cutoff= raises ``ValueError`` ``QuinticSwitch: switch width must satisfy 0 < width <`` cutoff=. ``rgpot.LJClusterPot`` ^^^^^^^^^^^^^^^^^^^^^^ .. code:: python rgpot.LJClusterPot(u0=1.0, cutoff=15.0, psi=1.0, switch_width=0.0) Inputs as ``rgpot.LJPot``. Units ``u0`` eV; ``cutoff``, ``psi`` and ``switch_width`` Angstrom. Outputs a free-boundary Lennard-Jones potential. The cell is read but does not fold pair vectors, so the energy does not depend on ``box``. ``caps()`` reports ``periodic`` false and ``stress`` false, and ``evaluate`` returns ``stress`` ``None``. Errors as ``rgpot.LJPot``. ``rgpot.MorsePot`` ^^^^^^^^^^^^^^^^^^ .. code:: python rgpot.MorsePot(De=0.7102, a=1.6047, re=2.897, cutoff=9.5, switch_width=0.0) Inputs ``De`` is the well depth, ``a`` the range parameter, ``re`` the equilibrium distance, ``cutoff`` the pair cutoff. The defaults are the platinum parameters. ``switch_width`` works as for ``rgpot.LJPot``. Atom types are not used by the kernel. Units ``De`` eV; ``a`` 1/Angstrom; ``re``, ``cutoff`` and ``switch_width`` Angstrom. Outputs a periodic shifted Morse pair potential. ``evaluate`` returns the stress. It is the only class here with an analytic Hessian-vector product: ``has_analytic_hvp()`` is true. Errors as ``rgpot.LJPot``. ``rgpot.SWPot`` ^^^^^^^^^^^^^^^ .. code:: python rgpot.SWPot() Inputs none. The kernel ignores ``atom_types`` and treats every atom as silicon. Units energy eV, lengths Angstrom. Epsilon is eOn's 2.3149945 eV, not the published 2.16723920 eV of ``rgpot.StillingerWeberSi``. Outputs the Fortran Stillinger-Weber silicon kernel. ``evaluate`` returns the stress; ``evaluate_batch`` does not. Errors a kernel failure raises ``RuntimeError`` ``SW potential failed (status K): ...`` with the kernel's message. A box that is not finite or has zero volume is such a failure. ``rgpot.EDIPPot`` ^^^^^^^^^^^^^^^^^ .. code:: python rgpot.EDIPPot() Inputs none. The kernel ignores ``atom_types`` and treats every atom as silicon. Units energy eV, lengths Angstrom. Outputs the Fortran environment-dependent interatomic potential for silicon. No stress. Errors ``RuntimeError`` ``EDIP potential failed (status K): ...``, for example when the cell is thinner than the interaction cutoff or the box has zero volume. ``rgpot.LenoskyPot`` ^^^^^^^^^^^^^^^^^^^^ .. code:: python rgpot.LenoskyPot() Inputs none. The kernel ignores ``atom_types`` and treats every atom as silicon. Units energy eV, lengths Angstrom. Outputs the Fortran Lenosky silicon kernel. No stress. Errors ``RuntimeError`` ``Lenosky potential failed (status K): ...``, for example for a zero-volume box. ``rgpot.TersoffPot`` ^^^^^^^^^^^^^^^^^^^^ .. code:: python rgpot.TersoffPot() Inputs none. When every atomic number is 14 the Fortran silicon kernel runs. Any other atomic number sends the call to the 1989 silicon-carbon kernel of ``rgpot.TersoffSiC``, which accepts 6 and 14. Units energy eV, lengths Angstrom. Outputs a Tersoff potential. No path writes a stress; ``evaluate`` returns ``stress`` ``None``. Errors an atomic number other than 6 or 14 raises ``ValueError`` ``TersoffSiC: atomic number Z is neither carbon (6) nor silicon (14)``. A failure of the silicon kernel raises ``RuntimeError`` ``Tersoff potential failed (status K): ...``. ``rgpot.EAMAlPot`` ^^^^^^^^^^^^^^^^^^ .. code:: python rgpot.EAMAlPot() Inputs none. The kernel ignores ``atom_types`` and treats every atom as aluminium. Units energy eV, lengths Angstrom, forces eV/Angstrom. Outputs the Fortran double-exponential embedded-atom aluminium kernel. No stress. Errors ``RuntimeError`` ``EAM-Al potential failed (status K): ...``, for example for a zero-volume box. ``rgpot.FeHePot`` ^^^^^^^^^^^^^^^^^ .. code:: python rgpot.FeHePot() Inputs none. Atomic numbers must be 26 (iron) or 2 (helium). Units energy eV, lengths Angstrom. Outputs the Fortran Fe-He embedded-atom kernel. No stress. Errors any other atomic number raises ``RuntimeError`` ``FeHe potential failed (status 2): rgpot_fehe: unsupported atomic number Z on atom K; ...``. Other kernel failures raise ``RuntimeError`` too. ``rgpot.CuH2Pot`` ^^^^^^^^^^^^^^^^^ .. code:: python rgpot.CuH2Pot() Inputs none. Atomic numbers must be 29 (copper) or 1 (hydrogen), in any order. Units energy eV, lengths Angstrom. Outputs the Fortran copper-hydrogen embedded-atom kernel. No stress. Errors any other atomic number raises ``RuntimeError`` ``CuH2 potential failed (status 2): rgpot_cuh2: atom K has atomic number Z; ...``. Two atoms at the same position also raise ``RuntimeError``. ``rgpot.WaterHPot`` ^^^^^^^^^^^^^^^^^^^ .. code:: python rgpot.WaterHPot() Inputs none. The atoms must be whole water molecules (atomic numbers 8 and 1) plus one extra hydrogen, and that hydrogen must be the last atom. A zero cell means an isolated cluster. Units energy eV, lengths Angstrom; the kernel holds its parameters in kJ/mol and converts the result. Outputs the Fortran potential of one H atom in the field of water molecules. No stress. Errors ``RuntimeError`` ``Water-H potential failed (status K): ...`` for fewer than 4 atoms, an element other than H and O, a composition that is not whole waters plus one H, or an atom on top of the lone H. ``rgpot.StillingerWeberSi`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code:: python rgpot.StillingerWeberSi() Inputs none. The kernel ignores ``atom_types`` and treats every atom as silicon; the list is still checked for length and dtype. Units energy eV, lengths Angstrom. Epsilon is the published 2.16723920 eV of Stillinger and Weber, Phys. Rev. B 31, 5262 (1985). Outputs the C++ Stillinger-Weber silicon kernel. It has ``__call__``, ``caps``, ``evaluate`` (with stress) and ``energy_gradient``, and no ``evaluate_batch`` or ``hvp``. See the :doc:`Stillinger-Weber reference `. Errors as the conventions list. A NaN coordinate returned energy 0.0 here without an error. ``rgpot.TersoffSiC`` ^^^^^^^^^^^^^^^^^^^^ .. code:: python rgpot.TersoffSiC() Inputs none. Atomic numbers must be 6 (carbon) or 14 (silicon). Units energy eV, lengths Angstrom. Outputs the 1989 Tersoff silicon-carbon kernel, Phys. Rev. B 39, 5566 (1989), with the 1990 erratum. It has only ``__call__`` and ``energy_gradient``: no ``caps``, ``evaluate``, ``evaluate_batch`` or ``hvp``. See the :doc:`Tersoff SiC reference `. Errors another atomic number raises ``ValueError`` ``TersoffSiC: atomic number Z is neither carbon (6) nor silicon (14)``. ``rgpot.D3Pot`` ^^^^^^^^^^^^^^^ .. code:: python rgpot.D3Pot(damping='bj', functional='pbe', atm=True) Inputs ``damping`` ``"bj"`` or ``"BJ"`` selects rational (Becke-Johnson) damping and ``"zero"`` or ``"Zero"`` selects zero damping. ``functional`` is the s-dftd3 method key. ``atm`` switches the Axilrod-Teller-Muto three-body term. ``atom_types`` are atomic numbers. Units positions in Angstrom, converted to bohr for s-dftd3; the Hartree energy is returned in eV and forces in eV/Angstrom. Outputs Grimme DFT-D3 dispersion. The structure is passed to s-dftd3 as non-periodic in all three directions, so the cell does not add periodic images. No stress. ``None`` when ``rgpot.has_dftd3`` is false. Errors an empty ``functional`` raises ``ValueError``; a key s-dftd3 rejects raises ``RuntimeError`` from the constructor. Any other ``damping`` string raises ``ValueError`` ``D3 damping must be 'bj' or 'zero', got 'NAME'``, also for a ``"d3"`` term of ``ExprPot``. s-dftd3 errors during a call raise ``RuntimeError``. ``rgpot.D4Pot`` ^^^^^^^^^^^^^^^ .. code:: python rgpot.D4Pot(functional='pbe', charge=0.0, atm=True) Inputs ``functional`` is the dftd4 method key for rational damping; ``charge`` is the total charge of the system; ``atm`` switches the many-body term. ``atom_types`` are atomic numbers. Units ``charge`` in elementary charges; positions in Angstrom, converted to bohr; energy eV; forces eV/Angstrom. Outputs Grimme DFT-D4 dispersion, non-periodic as for ``rgpot.D3Pot``. No stress. ``None`` when ``rgpot.has_dftd4`` is false. Errors an empty ``functional`` raises ``ValueError``; dftd4 errors raise ``RuntimeError``. ``rgpot.ExprPot`` ^^^^^^^^^^^^^^^^^ .. code:: python rgpot.ExprPot(expression, terms) Inputs ``expression`` is a Lepton expression over the term names, for example ``"a + 0.5*b"``. ``terms`` maps each name to a kind string, ``"lj"``, ``"morse"``, ``"d3"`` or ``"d4"``, or to a dict with a ``"kind"`` key (or ``"type"``) plus that kind's fields. The fields are ``u0``, ``cutoff``, ``psi``, ``switch_width`` for ``"lj"``; ``De``, ``a``, ``re``, ``cutoff``, ``switch_width`` for ``"morse"``; ``functional``, ``damping``, ``atm`` for ``"d3"``; ``functional``, ``charge``, ``atm`` for ``"d4"``. A missing field keeps the default of that kind's class. Units the fields have the units of ``LJPot``, ``MorsePot``, ``D3Pot`` and ``D4Pot``; the expression combines child energies in eV. Outputs the energy ``f(E_a, E_b, ...)`` with forces from the chain rule. ``"d3"`` and ``"d4"`` are available only when ``has_dftd3`` and ``has_dftd4`` are true. ``evaluate`` returns ``stress`` ``None``. Errors ``ValueError`` for an empty expression, no terms, a term that is not a string or a dict with ``"kind"``, an unknown kind, a parse failure, an identifier with no term, a term the expression does not use, or a duplicate name. .. code:: python import numpy as np import rgpot pot = rgpot.ExprPot("a + 0.5*b", {"a": "lj", "b": {"kind": "morse", "De": 1.0}}) positions = np.array([[0.0, 0.0, 0.0], [2.5, 0.0, 0.0]]) energy, forces, _ = pot(positions, [1, 1], np.eye(3) * 20.0) print(pot.expression, pot.d_energy_d_term("a"), pot.d_energy_d_term("b")) :: a + 0.5*b 1.0 0.5 ``rgpot.IPIPot`` ^^^^^^^^^^^^^^^^ .. code:: python rgpot.IPIPot(address, timeout_s=30.0) Inputs ``address`` is ``unix:/absolute/path``, ``unix:`` (the i-PI default socket prefix plus the name), ``tcp::`` or ``tcp:`` (host 127.0.0.1). Port 0 lets the system choose; ``endpoint`` reports the port. ``timeout_s`` covers waiting for the driver to connect plus one force exchange. ``atom_types`` are checked but not sent; the driver keeps its own species list. Units ``timeout_s`` seconds. Positions, box, energy and forces are Angstrom, eV and eV/Angstrom on the Python side; the wire carries bohr and hartree. Outputs an i-PI socket server that a driver (CP2K, Quantum ESPRESSO, FHI-aims, LAMMPS, i-pi-py\ :sub:`driver`\) connects to. The constructor binds the socket. It has ``__call__``, ``stress`` and ``endpoint``. ``None`` when ``rgpot.has_ipi`` is false. Errors an address without ``unix:`` or ``tcp:``, a bad port, or a negative or non-finite ``timeout_s`` raises ``ValueError``. A call with no atoms, non-finite positions or cell, or a singular cell raises ``ValueError``. A timeout, a disconnect or a protocol error raises ``RuntimeError`` ``IPIPot: ...``, for example ``IPIPot: timed out waiting for an i-PI driver``. ``rgpot.LammpsPot`` ^^^^^^^^^^^^^^^^^^^ Inputs none; the class has no Python constructor and ``rgpot.LammpsPot()`` raises ``TypeError``. ``rgpot.rgpot_lammps_potential`` returns instances. Units positions and box in Angstrom, energy eV, forces eV/Angstrom. Outputs a shifted 12-6 Lennard-Jones potential evaluated by the engine plugin. It has only ``__call__``. Errors ``TypeError`` on direct construction; calls raise as the conventions list, and an engine failure raises ``RuntimeError``. ``rgpot.GromacsPot`` ^^^^^^^^^^^^^^^^^^^^ Inputs none; the class has no Python constructor and ``rgpot.GromacsPot()`` raises ``TypeError``. ``rgpot.rgpot_gromacs_potential`` returns instances. Units positions and box in Angstrom, energy eV, forces eV/Angstrom; the stored parameters are kJ/mol and nanometres. Outputs a shifted 12-6 Lennard-Jones potential, in process or through a native-unit library. It has ``__call__``, ``native_u0``, ``native_cutoff`` and ``native_psi``. Errors ``TypeError`` on direct construction; a native library that returns a non-zero status raises ``RuntimeError`` ``rgpot_md_native_force failed``. ``rgpot.OpenMMPot`` ^^^^^^^^^^^^^^^^^^^ Inputs none; the class has no Python constructor and ``rgpot.OpenMMPot()`` raises ``TypeError``. ``rgpot.rgpot_openmm_potential`` returns instances. Units as ``rgpot.GromacsPot``. Outputs as ``rgpot.GromacsPot``, with ``__call__``, ``native_u0``, ``native_cutoff`` and ``native_psi``. Errors as ``rgpot.GromacsPot``. Shared methods ~~~~~~~~~~~~~~ ``.__call__`` ^^^^^^^^^^^^^ .. code:: python __call__(positions, atom_types, box) Applies to rgpot.LJPot, rgpot.LJClusterPot, rgpot.MorsePot, rgpot.SWPot, rgpot.EDIPPot, rgpot.LenoskyPot, rgpot.TersoffPot, rgpot.EAMAlPot, rgpot.FeHePot, rgpot.CuH2Pot, rgpot.WaterHPot, rgpot.D3Pot, rgpot.D4Pot, rgpot.ExprPot, rgpot.StillingerWeberSi, rgpot.TersoffSiC, rgpot.IPIPot, rgpot.LammpsPot, rgpot.GromacsPot, rgpot.OpenMMPot Inputs ``positions`` ``(N, 3)``, ``atom_types`` (``N`` integers) and ``box`` ``(3, 3)``, as in the conventions. Units positions and box in Angstrom; energy eV; forces eV/Angstrom; variance eV\ :sup:`2`\. Outputs a tuple ``(energy, forces, variance)``: a float, a new ``(N, 3)`` float64 array and a float. The kernel runs with the interpreter released. Errors the conventions list, plus each class's kernel errors. A non-finite energy raises ``rgpot.NumericalError``. ``.caps`` ^^^^^^^^^ .. code:: python caps() Applies to rgpot.LJPot, rgpot.LJClusterPot, rgpot.MorsePot, rgpot.SWPot, rgpot.EDIPPot, rgpot.LenoskyPot, rgpot.TersoffPot, rgpot.EAMAlPot, rgpot.FeHePot, rgpot.CuH2Pot, rgpot.WaterHPot, rgpot.D3Pot, rgpot.D4Pot, rgpot.ExprPot, rgpot.StillingerWeberSi Inputs none. Units none. Outputs a dict with the keys ``reentrancy`` (``"shared"``, ``"per_instance"`` or ``"process_serial"``), ``per_image``, ``batched``, ``periodic``, ``group_collective`` and ``stress`` (booleans). ``stress`` true means ``evaluate`` returns a stress tensor. Errors none. ``.config`` ^^^^^^^^^^^ .. code:: python config() Applies to rgpot.LJPot, rgpot.LJClusterPot, rgpot.MorsePot Inputs none. Units as the constructor: eV for ``u0`` and ``De``, 1/Angstrom for ``a``, Angstrom for the lengths. Outputs a dict of the constructor parameters. ``LJPot`` and ``LJClusterPot`` give ``u0``, ``cutoff``, ``psi``, ``switch_width``; ``MorsePot`` gives ``De``, ``a``, ``re``, ``cutoff``, ``switch_width``. Errors none. ``.evaluate`` ^^^^^^^^^^^^^ .. code:: python evaluate(positions, atom_types, box) Applies to rgpot.LJPot, rgpot.LJClusterPot, rgpot.MorsePot, rgpot.SWPot, rgpot.EDIPPot, rgpot.LenoskyPot, rgpot.TersoffPot, rgpot.EAMAlPot, rgpot.FeHePot, rgpot.CuH2Pot, rgpot.WaterHPot, rgpot.D3Pot, rgpot.D4Pot, rgpot.ExprPot, rgpot.StillingerWeberSi Inputs ``positions``, ``atom_types`` and ``box`` as in the conventions. Units energy eV; forces eV/Angstrom; variance eV\ :sup:`2`\; stress eV/Angstrom\ :sup:`3`\, the Cauchy stress (1/V) dE/dε. Outputs a dict with ``energy`` (float), ``forces`` (``(N, 3)`` float64), ``variance`` (float), ``stress`` and ``energies``. ``stress`` is a ``(3, 3)`` float64 array when the kernel wrote one and ``None`` otherwise; ``caps()["stress"]`` says which. ``energies`` is always ``None``. The kernel runs with the interpreter released. Errors the conventions list; a non-finite energy raises ``rgpot.NumericalError``. ``.evaluate_per_atom`` ^^^^^^^^^^^^^^^^^^^^^^ .. code:: python evaluate_per_atom(positions, atom_types, box) Applies to rgpot.LJPot, rgpot.LJClusterPot, rgpot.MorsePot Inputs ``positions``, ``atom_types`` and ``box`` as in the conventions. Units as ``evaluate``; ``energies`` and ``virials`` eV. Outputs the dict of ``evaluate``, with ``energies`` a ``(N,)`` float64 array, plus ``virials``, a ``(N, 6)`` float64 array in the Voigt order ``xx yy zz yz xz xy``. ``energies`` sums to ``energy``, up to rounding. The rows of ``virials`` sum to -dE/dε, which is ``-V`` times the stress, with ``V`` the cell volume, for a kernel that returns a stress. A pair term goes half to each atom. The kernel runs with the interpreter released. Errors as ``evaluate``. .. code:: python import numpy as np import rgpot pot = rgpot.LJPot(u0=0.0104, cutoff=8.5, psi=3.4) positions = np.array([[0.0, 0.0, 0.0], [3.8, 0.0, 0.0], [0.0, 3.8, 0.4]]) box = np.eye(3) * 20.0 out = pot.evaluate_per_atom(positions, [18, 18, 18], box) s = out["stress"] voigt = np.array([s[0, 0], s[1, 1], s[2, 2], s[1, 2], s[0, 2], s[0, 1]]) volume = np.linalg.det(box) print(out["energies"].shape, out["virials"].shape) print( np.isclose(out["energies"].sum(), out["energy"]), np.allclose(out["virials"].sum(axis=0), -volume * voigt), ) :: (3,) (3, 6) True True ``.evaluate_batch`` ^^^^^^^^^^^^^^^^^^^ .. code:: python evaluate_batch(positions, atom_types, box, n_threads=0) Applies to rgpot.LJPot, rgpot.LJClusterPot, rgpot.MorsePot, rgpot.SWPot, rgpot.EDIPPot, rgpot.LenoskyPot, rgpot.TersoffPot, rgpot.EAMAlPot, rgpot.FeHePot, rgpot.CuH2Pot, rgpot.WaterHPot, rgpot.D3Pot, rgpot.D4Pot, rgpot.ExprPot Inputs three lists of equal length: ``positions`` arrays, ``atom_types`` sequences and ``box`` arrays, one entry per configuration, each as in the conventions. ``n_threads`` is the worker count; 0 uses the hardware concurrency. The count is capped at the number of configurations, and each worker builds its own kernel instance. Units as ``evaluate``. Outputs a list with one dict per configuration, with keys ``energy``, ``forces`` and ``variance`` (no ``stress``). Entry ``i`` equals a serial call on configuration ``i``, bit for bit. Empty lists return an empty list. Errors lists of different lengths raise ``ValueError`` ``evaluate_batch: positions, atom_types, and box lengths differ``. A positions or box entry that is not a float64 C-contiguous array raises ``TypeError`` ``evaluate_batch: positions[I] must be a C-contiguous float64 array`` (``box[I]`` for a box). Shape and ``atom_types`` errors are those of the conventions; a non-finite energy raises ``rgpot.NumericalError``. .. code:: python import numpy as np import rgpot pot = rgpot.SWPot() si = np.array([[0.0, 0.0, 0.0], [2.35, 0.0, 0.0], [0.0, 2.35, 0.0]]) box = np.eye(3) * 20.0 frames = [si, si + 0.01] rows = pot.evaluate_batch(frames, [[14, 14, 14]] * 2, [box, box], n_threads=2) serial = [pot(p, [14, 14, 14], box)[0] for p in frames] print(sorted(rows[0]), [r["energy"] for r in rows] == serial) :: ['energy', 'forces', 'variance'] True ``.hvp`` ^^^^^^^^ .. code:: python hvp(positions, atom_types, box, direction, step=0.0, scheme='auto') Applies to rgpot.LJPot, rgpot.LJClusterPot, rgpot.MorsePot, rgpot.SWPot, rgpot.EDIPPot, rgpot.LenoskyPot, rgpot.TersoffPot, rgpot.EAMAlPot, rgpot.FeHePot, rgpot.CuH2Pot, rgpot.WaterHPot, rgpot.D3Pot, rgpot.D4Pot, rgpot.ExprPot Inputs ``positions``, ``atom_types`` and ``box`` as in the conventions; ``direction`` is a float64 C-contiguous ``(N, 3)`` array. ``step`` is the length of the displacement along the unit direction; 0 means 1e-3 Angstrom. ``scheme`` is ``"forward"``, ``"central"``, ``"analytic"`` or ``"auto"``. ``"forward"`` displaces once and reuses the forces of the centre, the last geometry this object evaluated through ``hvp`` or ``hvp_centre``; it is first order in ``step``. ``"central"`` displaces both ways, two force calls a product, second order in ``step``. ``"analytic"`` uses the kernel's own product, which only ``MorsePot`` has. ``"auto"`` is ``"analytic"`` when ``has_analytic_hvp()`` is true and ``"forward"`` otherwise. Units positions, box and ``step`` in Angstrom. The product is linear in ``direction``: H is eV/Angstrom\ :sup:`2`\, so a direction in Angstrom gives eV/Angstrom. Outputs ``H @ direction`` as a new float64 array of shape ``(N, 3)``. A zero direction returns zeros without a force call. The kernel runs with the interpreter released. Errors ``direction`` not of shape ``(N, 3)`` raises ``ValueError`` ``direction: expected shape (N, 3), got ...``. An unknown ``scheme``, ``"analytic"`` on a class without the analytic product, a negative or non-finite ``step``, or non-finite positions or direction raise ``ValueError``. A non-finite energy, force or product raises ``rgpot.NumericalError``. The conventions list the other input errors. The centre is keyed on the bits of the positions, atomic numbers and cell. Another geometry is a new centre, and ``invalidate_hvp()`` drops it. A Lanczos loop of ``k`` forward products at one geometry costs ``k + 1`` force calls. The products follow ``rgpot_potential_hvp``; see the :doc:`C ABI reference ` for the error terms of each scheme. .. code:: python import numpy as np import rgpot pot = rgpot.LJPot() positions = np.array([[0.0, 0.0, 0.0], [1.1, 0.0, 0.0], [0.0, 1.2, 0.0]]) types = [1, 1, 1] box = np.eye(3) * 20.0 rng = np.random.default_rng(0) energy, forces, _ = pot.hvp_centre(positions, types, box) for _ in range(3): v = rng.standard_normal(positions.shape) hv = pot.hvp(positions, types, box, v, scheme="forward") assert hv.shape == positions.shape print(pot.hvp_counts()) pot.reset_hvp_counts() pot.hvp(positions, types, box, v, scheme="central") print(pot.hvp_counts()) print(pot.has_analytic_hvp(), rgpot.MorsePot().has_analytic_hvp()) :: {'products': 3, 'force_calls': 4, 'centre_reused': 3, 'analytic': 0} {'products': 1, 'force_calls': 2, 'centre_reused': 0, 'analytic': 0} False True ``.hvp_centre`` ^^^^^^^^^^^^^^^ .. code:: python hvp_centre(positions, atom_types, box) Applies to rgpot.LJPot, rgpot.LJClusterPot, rgpot.MorsePot, rgpot.SWPot, rgpot.EDIPPot, rgpot.LenoskyPot, rgpot.TersoffPot, rgpot.EAMAlPot, rgpot.FeHePot, rgpot.CuH2Pot, rgpot.WaterHPot, rgpot.D3Pot, rgpot.D4Pot, rgpot.ExprPot Inputs ``positions``, ``atom_types`` and ``box`` as in the conventions. Units energy eV; forces eV/Angstrom; variance eV\ :sup:`2`\. Outputs a tuple ``(energy, forces, variance)`` at the geometry. The geometry becomes the centre that forward ``hvp`` products reuse; a geometry equal to the current centre is served without a force call. Errors non-finite positions raise ``ValueError``; a non-finite energy or force raises ``rgpot.NumericalError``; the conventions list the other input errors. ``.invalidate_hvp`` ^^^^^^^^^^^^^^^^^^^ .. code:: python invalidate_hvp() Applies to rgpot.LJPot, rgpot.LJClusterPot, rgpot.MorsePot, rgpot.SWPot, rgpot.EDIPPot, rgpot.LenoskyPot, rgpot.TersoffPot, rgpot.EAMAlPot, rgpot.FeHePot, rgpot.CuH2Pot, rgpot.WaterHPot, rgpot.D3Pot, rgpot.D4Pot, rgpot.ExprPot Inputs none. Units none. Outputs ``None``; the next ``hvp`` or ``hvp_centre`` call computes a new centre. The counters stay. Errors none. ``.hvp_counts`` ^^^^^^^^^^^^^^^ .. code:: python hvp_counts() Applies to rgpot.LJPot, rgpot.LJClusterPot, rgpot.MorsePot, rgpot.SWPot, rgpot.EDIPPot, rgpot.LenoskyPot, rgpot.TersoffPot, rgpot.EAMAlPot, rgpot.FeHePot, rgpot.CuH2Pot, rgpot.WaterHPot, rgpot.D3Pot, rgpot.D4Pot, rgpot.ExprPot Inputs none. Units none; the values are counts. Outputs a dict with ``products`` (products answered), ``force_calls`` (force evaluations made), ``centre_reused`` (requests served from the centre) and ``analytic`` (products from the kernel's own product), counted over ``hvp`` and ``hvp_centre``. Errors none. ``.reset_hvp_counts`` ^^^^^^^^^^^^^^^^^^^^^ .. code:: python reset_hvp_counts() Applies to rgpot.LJPot, rgpot.LJClusterPot, rgpot.MorsePot, rgpot.SWPot, rgpot.EDIPPot, rgpot.LenoskyPot, rgpot.TersoffPot, rgpot.EAMAlPot, rgpot.FeHePot, rgpot.CuH2Pot, rgpot.WaterHPot, rgpot.D3Pot, rgpot.D4Pot, rgpot.ExprPot Inputs none. Units none. Outputs ``None``; every ``hvp_counts()`` value becomes 0. The centre stays. Errors none. ``.has_analytic_hvp`` ^^^^^^^^^^^^^^^^^^^^^ .. code:: python has_analytic_hvp() Applies to rgpot.LJPot, rgpot.LJClusterPot, rgpot.MorsePot, rgpot.SWPot, rgpot.EDIPPot, rgpot.LenoskyPot, rgpot.TersoffPot, rgpot.EAMAlPot, rgpot.FeHePot, rgpot.CuH2Pot, rgpot.WaterHPot, rgpot.D3Pot, rgpot.D4Pot, rgpot.ExprPot Inputs none. Units none. Outputs ``True`` when the kernel has its own Hessian-vector product, so ``scheme``'auto'= uses it. Of these classes only ``MorsePot`` returns ``True``. Errors none. ``.energy_gradient`` ^^^^^^^^^^^^^^^^^^^^ .. code:: python energy_gradient(positions, atom_types, box) Applies to rgpot.StillingerWeberSi, rgpot.TersoffSiC Inputs ``positions`` of shape ``(n_atoms, 3)``, or ``(n_config, n_atoms, 3)`` for a batch, float64 C-contiguous. A batch shares ``atom_types`` (``n_atoms`` integers) and ``box`` ``(3, 3)``, and enters the library once. Units positions and box in Angstrom; energy eV; gradient eV/Angstrom. Outputs for one configuration, a tuple of the energy (float) and dE/dx, a ``(n_atoms, 3)`` float64 array. For a batch, a tuple of a ``(n_config,)`` energy array and a ``(n_config, n_atoms, 3)`` gradient array. The gradient is minus the forces of ``__call__``. The kernel runs with the interpreter released. Errors ``box`` not ``(3, 3)`` raises ``ValueError`` ``box must have shape (3, 3)``. ``positions`` of another rank, or whose last axis is not 3, raises ``ValueError``. A non-float64 or non-contiguous array raises ``TypeError``; ``atom_types`` errors are those of the conventions. ``TersoffSiC`` raises ``ValueError`` for an atomic number other than 6 or 14. The energy is not checked for non-finite values. .. code:: python import numpy as np import rgpot pot = rgpot.StillingerWeberSi() si = np.array([[0.0, 0.0, 0.0], [2.35, 0.0, 0.0], [0.0, 2.35, 0.0]]) box = np.eye(3) * 20.0 energy, gradient = pot.energy_gradient(si, [14, 14, 14], box) energies, gradients = pot.energy_gradient(np.stack([si, si]), [14, 14, 14], box) print(type(energy).__name__, gradient.shape, energies.shape, gradients.shape) _, forces, _ = pot(si, [14, 14, 14], box) print(np.array_equal(forces, -gradient)) :: float (3, 3) (2,) (2, 3, 3) True ``.native_u0`` ^^^^^^^^^^^^^^ .. code:: python native_u0() Applies to rgpot.GromacsPot, rgpot.OpenMMPot Inputs none. Units kJ/mol. Outputs the well depth stored for the engine, ``u0`` converted from eV. Errors none. ``.native_cutoff`` ^^^^^^^^^^^^^^^^^^ .. code:: python native_cutoff() Applies to rgpot.GromacsPot, rgpot.OpenMMPot Inputs none. Units nanometres. Outputs the cutoff stored for the engine, ``cutoff`` converted from Angstrom. Errors none. ``.native_psi`` ^^^^^^^^^^^^^^^ .. code:: python native_psi() Applies to rgpot.GromacsPot, rgpot.OpenMMPot Inputs none. Units nanometres. Outputs the zero crossing stored for the engine, ``psi`` converted from Angstrom. Errors none. Class-specific members ~~~~~~~~~~~~~~~~~~~~~~ ``rgpot.ExprPot.expression`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Inputs none; a read-only property. Units none. Outputs the expression string given to the constructor. Errors none. ``rgpot.ExprPot.d_energy_d_term`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code:: python d_energy_d_term(name) Inputs ``name``, a term name. Units none; the derivative of the expression with respect to one child energy is eV/eV. Outputs the float df/dE\ :sub:`name`\ from the derivative compiled at construction, evaluated at the child energies of this thread's last force call (all zero before the first call). A call through ``evaluate_batch`` does not update it. Errors a name that is not a term raises ``ValueError`` ``ExprPot name 'NAME' is not a term``. ``rgpot.IPIPot.stress`` ^^^^^^^^^^^^^^^^^^^^^^^ .. code:: python stress() Inputs none. Units eV/Angstrom\ :sup:`3`\. Outputs the Cauchy stress of the last call, a ``(3, 3)`` float64 array, from the driver's virial; ``None`` before a call that published one. Errors none. ``rgpot.IPIPot.endpoint`` ^^^^^^^^^^^^^^^^^^^^^^^^^ Inputs none; a read-only property. Units none. Outputs the bound address as a string, for example ``tcp:127.0.0.1:PORT`` with the port the system chose for ``tcp:0``. Errors none. ``rgpot.XcKernel`` ^^^^^^^^^^^^^^^^^^ .. code:: python rgpot.XcKernel(name) Inputs ``name``, a contraction kernel from ``XcKernel.catalog()``, for example ``"xck_lda_r_o1"``. Units none. Outputs an exchange-correlation contraction kernel. It is not a geometry potential: it takes basis-function values on a grid and Libxc derivative arrays that the host evaluates, and returns an AO matrix. ``None`` when ``rgpot.has_xckernel`` is false. Errors an unknown name raises ``ValueError`` ``unknown XcKernel: NAME``. ``rgpot.XcKernel.catalog`` ^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code:: python catalog() Inputs none; a static method. Units none. Outputs a list of the kernel names: LDA, GGA, meta-GGA with tau and meta-GGA with the Laplacian, at orders 1 and 2. Errors none. ``rgpot.XcKernel.name`` ^^^^^^^^^^^^^^^^^^^^^^^ Inputs none; a read-only property. Units none. Outputs the kernel name given to the constructor. Errors none. ``rgpot.XcKernel.scal_names`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code:: python scal_names() Inputs none. Units none. Outputs the list of keys ``contract`` reads from ``scal``, in the kernel's operand order. Errors none. ``rgpot.XcKernel.contract`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code:: python contract(chi, dchi=None, scal=None, lapl_chi=None, hess_chi=None) Inputs ``chi`` is the basis values, float64 C-contiguous ``(nbf, npts)``. ``dchi`` is the gradients ``(3, nbf, npts)``, or ``None``; only the LDA kernels accept ``None``. ``scal`` is required although the stub writes it as ``None``: a dict from each ``scal_names()`` key to a float64 array of shape ``(npts,)`` or ``(npts, 1)``. ``lapl_chi`` ``(nbf, npts)`` is required by the ``xck_mgga_lapl_`` kernels; ``hess_chi`` is ``(6, nbf, npts)`` or ``None``. ``k.contract(chi, None, scal)`` and ``k.contract(chi, scal=scal)`` both leave ``dchi`` unset. Units none are converted; the result has the units of the host's arrays (atomic units for Libxc output). Outputs a new float64 ``(nbf, nbf)`` array, the contraction accumulated into zeros. The kernel runs with the interpreter released. Errors ``scal`` omitted or ``None`` raises ``TypeError``. A wrong shape of ``dchi``, ``lapl_chi``, ``hess_chi`` or a ``scal`` array raises ``ValueError`` naming it. ``chi`` that is not two-dimensional raises ``ValueError``; ``chi`` of the wrong dtype or order raises ``TypeError``. A missing gradient or Laplacian, or a missing ``scal`` key, raises ``RuntimeError`` ``XcKernel.contract rc=K``. .. code:: python import numpy as np import rgpot name = "xck_lda_r_o1" assert name in rgpot.XcKernel.catalog() k = rgpot.XcKernel(name) nbf, npts = 2, 4 chi = np.ones((nbf, npts)) scal = {s: np.ones(npts) for s in k.scal_names()} out = k.contract(chi, scal=scal) assert out.shape == (nbf, nbf) assert np.array_equal(out, k.contract(chi, None, scal)) ``rgpot.XcKernel.fields_from_density`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code:: python fields_from_density(chi, dchi, density, lapl_chi=None, hess_chi=None) Inputs a static method. ``chi`` ``(nbf, npts)``, ``dchi`` ``(3, nbf, npts)`` or ``None``, ``lapl_chi`` and ``hess_chi`` as for ``contract``. ``density`` is the AO density matrix, float64 C-contiguous ``(nbf, nbf)``, symmetric or a transition density. Units none are converted; the fields have the units of the inputs. Outputs a dict with ``rho``, ``sigma``, ``tau`` and ``lapl``, each a float64 ``(npts, 1)`` array, and ``grad_rho``, a ``(3, npts)`` array. With ``dchi`` ``None`` every field is zero. ``lapl`` is zero without ``lapl_chi``. Errors ``density`` not ``(nbf, nbf)`` raises ``ValueError``; the shape errors of ``contract`` apply to the other arrays. ``chi`` or ``density`` of the wrong dtype or order raises ``TypeError``.