Calculators

The interface

Calculator

Bases: ABC

Computes energies, forces and virials of systems.

Implementations set cutoff, elements and implemented and define compute. mdapy.calculators.testing.check_calculator tests any implementation.

Attributes:

Name	Type	Description
cutoff	float64	Interaction cutoff in Å; a neighbor list for compute must have at least this cutoff.
elements	tuple of str or None	Elements the calculator handles, or None for any.
implemented	frozenset of str	The properties compute can return, a subset of energy, atomic_energies, forces, virial and atomic_virials.

compute abstractmethod

compute(system, properties=('energy', 'forces'), *, neighbors=None)

Computes properties of a system.

Parameters:

Name	Type	Description	Default
system	System	The atoms, with the columns the calculator needs (usually element).	required
properties	iterable of str	The properties to compute; others may be computed too.	('energy', 'forces')
neighbors	NeighborList	A neighbor list of this system with at least cutoff; built when not given.	None

Returns:

Type	Description
CalculatorResult	At least the requested properties.

Raises:

Type	Description
InvalidParameter	If a property is not implemented, or the neighbor list does not fit the system.
MissingProperty	If the system lacks a column the calculator needs.

CalculatorResult dataclass

CalculatorResult(energy=None, atomic_energies=None, forces=None, virial=None, atomic_virials=None, volume=None)

Bases: Result

What a calculator computed for a system; unrequested values are None.

Attributes:

Name	Type	Description
energy	float64 or None	Total energy in eV.
atomic_energies	ndarray or None	(N,) float64 energies in eV; they sum to energy.
forces	ndarray or None	(N, 3) float64 forces in eV/Å.
virial	ndarray or None	(3, 3) float64 virial in eV, positive under compression.
atomic_virials	ndarray or None	(N, 3, 3) float64 virials in eV; they sum to virial.
volume	float64 or None	Volume of the box in ų, which gives stress.

stress property

stress

(3, 3) stress in GPa, positive under tension: -virial / volume.

columns

columns()

forces, atomic_energies and atomic_virials, where computed.

attach

attach(system)

The system with these values as columns and information.

forces, atomic_energies and atomic_virials become columns; energy and virial become entries of info.

check_calculator

check_calculator(calculator, system, *, displacement=0.0001, rtol=1e-06, atol=1e-06, atoms=3, seed=0)

Checks that a calculator is consistent with itself and with physics.

The checks are: atomic energies and atomic virials sum to the energy and the virial; forces and the virial agree with finite differences of the energy; translation, rotation and reordering of the atoms change nothing beyond rotating vectors; a doubled cell has twice the energy (for systems periodic along a); and a neighbor list given to the calculator gives the same result.

Parameters:

Name	Type	Description	Default
calculator	Calculator	The calculator.	required
system	System	A small system, a few dozen atoms, that the calculator handles.	required
displacement	float64	Step in Å (and strain step) of the finite differences.	0.0001
rtol	float64	Relative and absolute tolerances of the comparisons, in the units of each quantity.	1e-06
atol	float64	Relative and absolute tolerances of the comparisons, in the units of each quantity.	1e-06
atoms	int32	Number of atoms whose forces are checked by finite differences.	3
seed	int32	Seed of the random rotation, translation and atom choice.	0

Raises:

Type	Description
AssertionError	If a check fails; the message names it and the largest deviation.

Native

EAM

EAM(path)

Bases: Calculator

Embedded atom method potential, in the LAMMPS eam/alloy (setfl) form.

Parameters:

Name	Type	Description	Default
path	str or PathLike	The potential file.	required

Attributes:

Name	Type	Description
path	str or None	The file the potential was read from, None for a built one.
elements	tuple of str or None	The elements of the potential, in the order of the file; None for an average-atom potential, which handles atoms of any element.
masses	ndarray	(E,) float64, their masses in amu; the mass of the average atom for an average-atom potential.
cutoff	float64	Cutoff radius in Å.

zhou classmethod

zhou(elements, *, nr=2000, nrho=2000)

The potential of Zhou, Johnson and Wadley for elements, tabulated as the LAMMPS tool tools/eam_database does.

Parameters:

Name	Type	Description	Default
elements	sequence of str	Any of Cu, Ag, Au, Ni, Pd, Pt, Al, Pb, Fe, Mo, Ta, W, Mg, Co, Ti, Zr and Cr.	required
nr	int32	Number of points of the tables in distance and in density. Default 2000.	2000
nrho	int32	Number of points of the tables in distance and in density. Default 2000.	2000

Returns:

Type	Description
EAM	The potential, written to a file with write.

average

average(concentrations)

The average-atom potential of an alloy of the elements.

Parameters:

Name	Type	Description	Default
concentrations	mapping or sequence of float64	The fraction of each element, by element or in the order of elements; elements not given have none. They sum to 1.	required

Returns:

Type	Description
EAM	A potential in which every atom is the average atom, whatever its element. write writes it with the elements of this potential and the average atom, named A, last.

write

write(path)

Writes the potential as a LAMMPS eam/alloy (setfl) file.

Parameters:

Name	Type	Description	Default
path	str or PathLike	The file to write; it reads back to the same tables.	required

NEP

NEP(path)

Bases: Calculator

Neuroevolution potential of a GPUMD nep.txt file (nep4, nep4_zbl).

Parameters:

Name	Type	Description	Default
path	str or PathLike	The potential file.	required

Attributes:

Name	Type	Description
elements	tuple of str	The elements of the potential, in the order of the file.
cutoff	float64	The largest cutoff radius in Å.

descriptors

descriptors(system, *, neighbors=None, progress=None, cancel=None)

The descriptors of each atom, scaled as the network sees them.

Parameters:

Name	Type	Description	Default
system	System	The atoms, with an element column.	required
neighbors	NeighborList	A neighbor list of this system with at least cutoff.	None

Returns:

Type	Description
ndarray	(N, dim) float64 descriptors: the radial ones, then the angular ones by l and n, then the four-body and five-body ones by n.

Interfaces

LAMMPS

LAMMPS(pair, elements, *, commands='', cmdargs=(), cutoff=None)

Bases: Calculator

An interaction of LAMMPS, defined by its commands, as a calculator.

Parameters:

Name	Type	Description	Default
pair	str	The LAMMPS commands of the interaction, such as pair_style and pair_coeff. LAMMPS runs in metal units (Å, eV, ps, amu), the only units supported: the interaction must be defined for them.	required
elements	sequence of str	The element of each LAMMPS atom type, from type 1.	required
commands	str	LAMMPS commands run before pair, such as newton on.	''
cmdargs	sequence of str	Command-line arguments of LAMMPS, such as ["-k", "on", "t", "4", "-sf", "kk"] for Kokkos with four threads.	()
cutoff	float64	The largest cutoff of the interaction in Å; asked from LAMMPS when not given, which LAMMPS older than 30 Sep 2026 cannot tell.	None

Attributes:

Name	Type	Description
elements	tuple of str	The element of each atom type.
cutoff	float64	The largest cutoff of the interaction in Å.

Raises:

Type	Description
InvalidParameter	If LAMMPS rejects the commands, or cannot tell the cutoff when it is not given.
ImportError	If the LAMMPS Python module is not installed.

close

close()

Closes the LAMMPS instance; the next computation starts a new one.

compute

compute(system, properties=('energy', 'forces'), *, neighbors=None)

Computes properties of a system with LAMMPS.

Parameters:

Name	Type	Description	Default
system	System	The atoms, with an element column.	required
properties	iterable of str	The properties to compute; all are computed.	('energy', 'forces')
neighbors	NeighborList	Not used: LAMMPS searches its own neighbors.	None

Returns:

Type	Description
CalculatorResult	Every property.

VASP

VASP(incar=None, *, kpoints=None, potcars=None, setups=None, command=None, directory='vasp', restart=True)

Bases: Calculator

Energies, forces and virials from VASP: each call writes POSCAR, INCAR, KPOINTS and POTCAR, runs VASP with a command and reads its OUTCAR.

Parameters:

Name	Type	Description	Default
incar	mapping	INCAR tags, such as {"ENCUT": 520, "EDIFF": 1e-6, "ISMEAR": 1, "SIGMA": 0.1}. NSW, IBRION and ISIF are set for a single point with the stress and may not be given.	None
kpoints	sequence of int32	A Gamma-centered mesh of k-points, three numbers. Default none: VASP then takes KSPACING from the INCAR.	None
potcars	str or path - like	The folder of the POTCARs, one folder per element or setup, such as potpaw_PBE. Default the environment variable VASP_PP_PATH, or its potpaw_PBE folder.	None
setups	mapping	The POTCAR of an element when not its symbol, such as {"Ti": "Ti_sv"}.	None
command	str	The shell command that runs VASP in the directory, as in a job script, such as "mpirun -np 128 vasp_std" or "srun vasp_std". Default the environment variable MDAPY_VASP_COMMAND, else ASE_VASP_COMMAND, else vasp_std.	None
directory	str or path - like	Where VASP runs, made when missing. Default vasp.	'vasp'
restart	bool	Keep WAVECAR and CHGCAR between calls, so that VASP starts from the last wave functions, as in a minimization. Default True.	True

Attributes:

Name	Type	Description
cutoff	float64	0: VASP needs no neighbor list.

compute

compute(system, properties=('energy', 'forces'), *, neighbors=None)

Runs VASP on a system.

Parameters:

Name	Type	Description	Default
system	System	The atoms, with an element column.	required
properties	iterable of str	The properties to return: energy (the free energy TOTEN), forces and virial; VASP computes them all.	('energy', 'forces')
neighbors	NeighborList	Not used.	None

Returns:

Type	Description
CalculatorResult	The energy, forces and virial of the system, its atoms in their order.

Raises:

Type	Description
CalculationFailed	If VASP stops with an error or leaves no converged result.