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¶
Symbol |
Role |
|---|---|
|
In-process ASE calculator |
|
Cap’n Proto ASE calculator |
|
Portfolio relaxation, not an ASE optimizer |
|
Deprecated alias of |
|
Kind strings |
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 ASE how-to and the thread-safety page.
Conventions¶
Every call that takes positions, atom_types and box reads them the same
way.
positionsis a NumPy array of shape(N, 3), dtype float64, C-contiguous, in Angstrom.boxis a(3, 3)float64 C-contiguous array in Angstrom, row-major, one cell vector per row.atom_typesholds 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/Angstrom3.
The variance is eV2; 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:
positionsorboxthat is not a float64 C-contiguous NumPy array (a list, float32, a strided view) raisesTypeErrorfrom the argument conversion.positionsthat is not two-dimensional with 3 columns raisesValueError, for examplepositions: expected shape (N, 3), got (2, 2).boxthat is not(3, 3)raisesValueErrorbox: expected shape (3, 3), got ....atom_typeswhose length is notNraisesValueErroratom_types: expected shape (N,), got (M,).atom_typesthat is not a sequence of integers (floats, booleans) or an int32/int64 array raisesTypeError.An atomic number outside the int32 range raises
ValueError.A kernel that rejects its input with
std::invalid_argumentraisesValueError; a kernel that fails withstd::runtime_errorraisesRuntimeError. The message is the kernel’s own text.A non-finite energy raises
rgpot.NumericalError, except where an entry says otherwise.
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)
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_VERSIONat build time, or"0.0.0"when the build did not define it.- Errors
none.
rgpot.has_cache¶
- Inputs
none.
- Units
none.
- Outputs
Truewhen the extension was compiled withRGPOT_HAS_CACHE, sorgpot.PotentialCacheis a class.- Errors
none.
rgpot.has_dftd3¶
- Inputs
none.
- Units
none.
- Outputs
Truewhen the extension was compiled withRGPOT_HAS_DFTD3, sorgpot.D3Potis a class andExprPotaccepts the"d3"kind.- Errors
none.
rgpot.has_dftd4¶
- Inputs
none.
- Units
none.
- Outputs
Truewhen the extension was compiled withRGPOT_HAS_DFTD4, sorgpot.D4Potis a class andExprPotaccepts the"d4"kind.- Errors
none.
rgpot.has_expr¶
- Inputs
none.
- Units
none.
- Outputs
Truewhen the extension was compiled withRGPOT_HAS_EXPR, sorgpot.ExprPotis a class.- Errors
none.
rgpot.has_fortran_pots¶
- Inputs
none.
- Units
none.
- Outputs
Truewhen the extension was compiled withRGPOT_HAS_FORTRAN_POTS. The Fortran kernel classesSWPot,EDIPPot,LenoskyPot,TersoffPot,EAMAlPot,FeHePot,CuH2PotandWaterHPotexist only then.- Errors
none.
rgpot.has_ipi¶
- Inputs
none.
- Units
none.
- Outputs
Truewhen the extension was compiled withRGPOT_HAS_IPI, sorgpot.IPIPotis a class.- Errors
none.
rgpot.has_metatomic_dlopen¶
- Inputs
none.
- Units
none.
- Outputs
Truewhen the extension was compiled withRGPOT_HAS_METATOMIC, sorgpot.evaluate_metatomic_dlopenis a function.- Errors
none.
rgpot.has_xckernel¶
- Inputs
none.
- Units
none.
- Outputs
Truewhen the extension was compiled withRGPOT_HAS_XCKERNEL, sorgpot.XcKernelis a class.- Errors
none.
rgpot.PotentialCache¶
- Inputs
none.
- Units
none.
- Outputs
the
rgpot._core.PotentialCacheclass whenrgpot.has_cacheis true, otherwiseNone. The class is not in the stub. Its constructor isPotentialCache(path, create_if_missing=True)and opens a RocksDB database atpath.counts()returns(computed, served), the results the kernel produced and the results the cache answered since construction or the lastreset_counts(). In a cache buildLJPotalso hasset_cache(cache), which takes aPotentialCacheorNone.- 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.hvpandhvp_centrealso raise it when a force or a product is not finite.- Errors
none.
Functions¶
rgpot.evaluate_lj¶
evaluate_lj(positions, atom_types, box)
- Inputs
positions(N, 3),atom_types(Nintegers, 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 anLJPotwith the default parameters,u01 eV,cutoff15 Angstrom andpsi1 Angstrom.- Errors
the conventions list; a non-finite energy raises
rgpot.NumericalError.
rgpot.neighbor_list¶
neighbor_list(positions, cell, cutoff, quantities='ijd', full=False, offsets=False)
- Inputs
positions(natoms, 3)andcell(3, 3), float64 C-contiguous, the cell periodic in all three directions.cutoffis the pair cutoff.quantitiesis a string of the lettersi,j,d,DandS, and sets which arrays come back and in which order.full=Falselists each pair once;full=Truelists both(i, j)and(j, i).offsets=Truesorts the pairs byi, thenj, and appends a row pointer.- Units
positions, cell, cutoff,
dandDin Angstrom;i,j,Sand 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.iandjare int32 of shape(npairs,);dis the float64 distance,(npairs,);Disr_j - r_i, float64(npairs, 3);Sis the int32 cell shift,(npairs, 3). The row pointer is int32 of lengthnatoms + 1. A cutoff longer than the cell lists periodic images, including an atom with its own image.- Errors
positionsorcellthat is not a float64 C-contiguous array raisesTypeError. A wrong shape, a letter outsideijdDS, a negative or non-finite cutoff, or a cell with zero volume raisesValueError.
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¶
evaluate_metatomic(positions, atom_types, box, *, model_path, engine_path=None, device='cpu')
- Inputs
positions,atom_types(atomic numbers) andboxas in the conventions.model_path(keyword only) is the exported model file.engine_pathNoneusesrgpot.default_metatomic_engine_path(), or an empty string when that isNone.deviceis the torch device string.- Units
positions and box in Angstrom; energy eV; forces eV/Angstrom.
- Outputs
the tuple
(energy, forces, variance)ofrgpot.evaluate_metatomic_dlopen. The function importstorchfirst when it is installed, so the engine resolves the samelibtorch.- Errors
RuntimeErrorthis build has no MetatomicDlopen frontendwhenrgpot.has_metatomic_dlopenis false. Otherwise the errors ofrgpot.evaluate_metatomic_dlopen.
rgpot.evaluate_metatomic_dlopen¶
evaluate_metatomic_dlopen(positions, atom_types, box, model_path, engine_path='', device='cpu')
- Inputs
positions,atom_typesandboxas in the conventions.model_pathis the exported model. The frontend triesengine_pathwhen it is not empty, thenRGPOT_METATOMIC_ENGINE,METATOMIC_ENGINE,libmetatomic_engine.soon the loader path, andlibmetatomic_engine.soin each directory ofEON_POTENTIALS_PATHandRGPOT_ENGINE_PATH. It does not search the engines bundled with the package;rgpot.evaluate_metatomicdoes. An emptydevicemeans"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.Nonewhenrgpot.has_metatomic_dlopenis false.- Errors
an empty
model_pathraisesValueError. No candidate library that opens raisesRuntimeErrorMetatomicDlopen: libmetatomic_engine.so not found .... An ABI version mismatch, missing engine symbols, or a model the engine cannot create also raiseRuntimeErrorwith aMetatomicDlopen:message. A non-finite energy raisesrgpot.NumericalError; the conventions list the input errors.
rgpot.default_metatomic_engine_path¶
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 isrgpot/lib/torch-X.Y/for the installed torch major, then everyrgpot/lib/torch-*/directory, then the legacy single-engine locations, then theRGPOT_METATOMIC_ENGINEandMETATOMIC_ENGINEenvironment variables. In each directorylibrgpot_metatomic_engine.socomes beforelibmetatomic_engine.so.- Errors
none; a missing torch or missing files give
None.
rgpot.available_metatomic_engine_abis¶
available_metatomic_engine_abis()
- Inputs
none.
- Units
none.
- Outputs
a list of torch
X.Ystrings, one perrgpot/lib/torch-X.Y/directory that holds an engine library, in sorted order. The list is empty when the package has nolibdirectory.- Errors
none.
rgpot.rgpot_lammps_potential¶
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),cutoffandpsi(zero crossing), andengine_path. An emptyengine_pathtriesRGPOT_LAMMPS_ENGINE,LAMMPS_ENGINE,liblammps_engine.soandliblj_engine.so, in that order.- Units
u0eV;cutoffandpsiAngstrom.- Outputs
a
rgpot.LammpsPotwhose backend is the engine plugin the constructor opened.- Errors
u0,cutofforpsithat is not positive and finite raisesValueError. No engine library that opens and exportsrgpot_engine_forceraisesRuntimeErrorengine library was not opened: ..., listing each path tried.
rgpot.rgpot_gromacs_potential¶
rgpot_gromacs_potential(u0=1.0, cutoff=8.0, psi=1.0, engine_path='')
- Inputs
the shifted 12-6 Lennard-Jones parameters
u0,cutoffandpsi, andengine_path. An emptyengine_pathevaluates the potential in process. A path names a library whosergpot_md_native_forceworks in nanometres and kJ/mol.- Units
u0eV;cutoffandpsiAngstrom. The object stores them once in kJ/mol and nanometres;native_u0,native_cutoffandnative_psiread the stored values.- Outputs
a
rgpot.GromacsPot.- Errors
u0,cutofforpsithat is not positive and finite raisesValueError. A library that does not open or lacksrgpot_md_native_forceraisesRuntimeError.
rgpot.rgpot_openmm_potential¶
rgpot_openmm_potential(u0=1.0, cutoff=8.0, psi=1.0, engine_path='')
- Inputs
as
rgpot.rgpot_gromacs_potential; an example library islibopenmm_engine.so.- Units
u0eV;cutoffandpsiAngstrom, 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:
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¶
rgpot.LJPot(u0=1.0, cutoff=15.0, psi=1.0, switch_width=0.0)
- Inputs
u0is the well depth,cutoffthe pair cutoff andpsithe zero crossing of the 12-6 term.switch_width0 keeps the shifted truncation. A positiveswitch_widthreplaces the shift with the C2quintic switch over[cutoff - switch_width, cutoff]. Atom types are read but the kernel does not use them; every atom is the same species.- Units
u0eV;cutoff,psiandswitch_widthAngstrom.- Outputs
a periodic Lennard-Jones potential.
evaluatereturns the stress.- Errors
a nonzero
switch_widthoutside0 < switch_width <cutoff= raisesValueErrorQuinticSwitch: switch width must satisfy 0 < width <cutoff=.
rgpot.LJClusterPot¶
rgpot.LJClusterPot(u0=1.0, cutoff=15.0, psi=1.0, switch_width=0.0)
- Inputs
as
rgpot.LJPot.- Units
u0eV;cutoff,psiandswitch_widthAngstrom.- 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()reportsperiodicfalse andstressfalse, andevaluatereturnsstressNone.- Errors
as
rgpot.LJPot.
rgpot.MorsePot¶
rgpot.MorsePot(De=0.7102, a=1.6047, re=2.897, cutoff=9.5, switch_width=0.0)
- Inputs
Deis the well depth,athe range parameter,rethe equilibrium distance,cutoffthe pair cutoff. The defaults are the platinum parameters.switch_widthworks as forrgpot.LJPot. Atom types are not used by the kernel.- Units
DeeV;a1/Angstrom;re,cutoffandswitch_widthAngstrom.- Outputs
a periodic shifted Morse pair potential.
evaluatereturns 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¶
rgpot.SWPot()
- Inputs
none. The kernel ignores
atom_typesand 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.
evaluatereturns the stress;evaluate_batchdoes not.- Errors
a kernel failure raises
RuntimeErrorSW 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¶
rgpot.EDIPPot()
- Inputs
none. The kernel ignores
atom_typesand treats every atom as silicon.- Units
energy eV, lengths Angstrom.
- Outputs
the Fortran environment-dependent interatomic potential for silicon. No stress.
- Errors
RuntimeErrorEDIP potential failed (status K): ..., for example when the cell is thinner than the interaction cutoff or the box has zero volume.
rgpot.LenoskyPot¶
rgpot.LenoskyPot()
- Inputs
none. The kernel ignores
atom_typesand treats every atom as silicon.- Units
energy eV, lengths Angstrom.
- Outputs
the Fortran Lenosky silicon kernel. No stress.
- Errors
RuntimeErrorLenosky potential failed (status K): ..., for example for a zero-volume box.
rgpot.TersoffPot¶
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;
evaluatereturnsstressNone.- Errors
an atomic number other than 6 or 14 raises
ValueErrorTersoffSiC: atomic number Z is neither carbon (6) nor silicon (14). A failure of the silicon kernel raisesRuntimeErrorTersoff potential failed (status K): ....
rgpot.EAMAlPot¶
rgpot.EAMAlPot()
- Inputs
none. The kernel ignores
atom_typesand 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
RuntimeErrorEAM-Al potential failed (status K): ..., for example for a zero-volume box.
rgpot.FeHePot¶
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
RuntimeErrorFeHe potential failed (status 2): rgpot_fehe: unsupported atomic number Z on atom K; .... Other kernel failures raiseRuntimeErrortoo.
rgpot.CuH2Pot¶
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
RuntimeErrorCuH2 potential failed (status 2): rgpot_cuh2: atom K has atomic number Z; .... Two atoms at the same position also raiseRuntimeError.
rgpot.WaterHPot¶
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
RuntimeErrorWater-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¶
rgpot.StillingerWeberSi()
- Inputs
none. The kernel ignores
atom_typesand 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) andenergy_gradient, and noevaluate_batchorhvp. See the Stillinger-Weber reference.- Errors
as the conventions list. A NaN coordinate returned energy 0.0 here without an error.
rgpot.TersoffSiC¶
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__andenergy_gradient: nocaps,evaluate,evaluate_batchorhvp. See the Tersoff SiC reference.- Errors
another atomic number raises
ValueErrorTersoffSiC: atomic number Z is neither carbon (6) nor silicon (14).
rgpot.D3Pot¶
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.functionalis the s-dftd3 method key.atmswitches the Axilrod-Teller-Muto three-body term.atom_typesare 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.
Nonewhenrgpot.has_dftd3is false.- Errors
an empty
functionalraisesValueError; a key s-dftd3 rejects raisesRuntimeErrorfrom the constructor. Any otherdampingstring raisesValueErrorD3 damping must be 'bj' or 'zero', got 'NAME', also for a"d3"term ofExprPot. s-dftd3 errors during a call raiseRuntimeError.
rgpot.D4Pot¶
rgpot.D4Pot(functional='pbe', charge=0.0, atm=True)
- Inputs
functionalis the dftd4 method key for rational damping;chargeis the total charge of the system;atmswitches the many-body term.atom_typesare atomic numbers.- Units
chargein 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.Nonewhenrgpot.has_dftd4is false.- Errors
an empty
functionalraisesValueError; dftd4 errors raiseRuntimeError.
rgpot.ExprPot¶
rgpot.ExprPot(expression, terms)
- Inputs
expressionis a Lepton expression over the term names, for example"a + 0.5*b".termsmaps 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 areu0,cutoff,psi,switch_widthfor"lj";De,a,re,cutoff,switch_widthfor"morse";functional,damping,atmfor"d3";functional,charge,atmfor"d4". A missing field keeps the default of that kind’s class.- Units
the fields have the units of
LJPot,MorsePot,D3PotandD4Pot; 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 whenhas_dftd3andhas_dftd4are true.evaluatereturnsstressNone.- Errors
ValueErrorfor 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.
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¶
rgpot.IPIPot(address, timeout_s=30.0)
- Inputs
addressisunix:/absolute/path,unix:<name>(the i-PI default socket prefix plus the name),tcp:<host>:<port>ortcp:<port>(host 127.0.0.1). Port 0 lets the system choose;endpointreports the port.timeout_scovers waiting for the driver to connect plus one force exchange.atom_typesare checked but not sent; the driver keeps its own species list.- Units
timeout_sseconds. 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-pydriver) connects to. The constructor binds the socket. It has
__call__,stressandendpoint.Nonewhenrgpot.has_ipiis false.- Errors
an address without
unix:ortcp:, a bad port, or a negative or non-finitetimeout_sraisesValueError. A call with no atoms, non-finite positions or cell, or a singular cell raisesValueError. A timeout, a disconnect or a protocol error raisesRuntimeErrorIPIPot: ..., for exampleIPIPot: timed out waiting for an i-PI driver.
rgpot.LammpsPot¶
- Inputs
none; the class has no Python constructor and
rgpot.LammpsPot()raisesTypeError.rgpot.rgpot_lammps_potentialreturns 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
TypeErroron direct construction; calls raise as the conventions list, and an engine failure raisesRuntimeError.
rgpot.GromacsPot¶
- Inputs
none; the class has no Python constructor and
rgpot.GromacsPot()raisesTypeError.rgpot.rgpot_gromacs_potentialreturns 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_cutoffandnative_psi.- Errors
TypeErroron direct construction; a native library that returns a non-zero status raisesRuntimeErrorrgpot_md_native_force failed.
rgpot.OpenMMPot¶
- Inputs
none; the class has no Python constructor and
rgpot.OpenMMPot()raisesTypeError.rgpot.rgpot_openmm_potentialreturns instances.- Units
as
rgpot.GromacsPot.- Outputs
as
rgpot.GromacsPot, with__call__,native_u0,native_cutoffandnative_psi.- Errors
as
rgpot.GromacsPot.
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¶
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/dEnamefrom 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_batchdoes not update it.- Errors
a name that is not a term raises
ValueErrorExprPot name 'NAME' is not a term.
rgpot.IPIPot.stress¶
stress()
- Inputs
none.
- Units
eV/Angstrom3.
- Outputs
the Cauchy stress of the last call, a
(3, 3)float64 array, from the driver’s virial;Nonebefore 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:PORTwith the port the system chose fortcp:0.- Errors
none.
rgpot.XcKernel¶
rgpot.XcKernel(name)
- Inputs
name, a contraction kernel fromXcKernel.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.
Nonewhenrgpot.has_xckernelis false.- Errors
an unknown name raises
ValueErrorunknown XcKernel: NAME.
rgpot.XcKernel.catalog¶
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¶
scal_names()
- Inputs
none.
- Units
none.
- Outputs
the list of keys
contractreads fromscal, in the kernel’s operand order.- Errors
none.
rgpot.XcKernel.contract¶
contract(chi, dchi=None, scal=None, lapl_chi=None, hess_chi=None)
- Inputs
chiis the basis values, float64 C-contiguous(nbf, npts).dchiis the gradients(3, nbf, npts), orNone; only the LDA kernels acceptNone.scalis required although the stub writes it asNone: a dict from eachscal_names()key to a float64 array of shape(npts,)or(npts, 1).lapl_chi(nbf, npts)is required by thexck_mgga_lapl_kernels;hess_chiis(6, nbf, npts)orNone.k.contract(chi, None, scal)andk.contract(chi, scal=scal)both leavedchiunset.- 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
scalomitted orNoneraisesTypeError. A wrong shape ofdchi,lapl_chi,hess_chior ascalarray raisesValueErrornaming it.chithat is not two-dimensional raisesValueError;chiof the wrong dtype or order raisesTypeError. A missing gradient or Laplacian, or a missingscalkey, raisesRuntimeErrorXcKernel.contract rc=K.
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¶
fields_from_density(chi, dchi, density, lapl_chi=None, hess_chi=None)
- Inputs
a static method.
chi(nbf, npts),dchi(3, nbf, npts)orNone,lapl_chiandhess_chias forcontract.densityis 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,tauandlapl, each a float64(npts, 1)array, andgrad_rho, a(3, npts)array. WithdchiNoneevery field is zero.laplis zero withoutlapl_chi.- Errors
densitynot(nbf, nbf)raisesValueError; the shape errors ofcontractapply to the other arrays.chiordensityof the wrong dtype or order raisesTypeError.