MLIP

Descriptors

SOAP

SOAP(species, r_cut=5.0, n_max=8, l_max=6, sigma=0.5, *, crossover=True)

The smooth overlap of atomic positions (SOAP) of each atom: the power spectrum of the Gaussian density of its neighbors, in Gaussian radial functions and spherical harmonics, the same as DScribe's SOAP with its default Gaussian radial functions.

Parameters:

Name	Type	Description	Default
species	sequence of str	The elements, each a part of the descriptor; every atom must be one of them, so that systems of other compositions share the same layout.	required
r_cut	float64	The cutoff of the radial functions in Å, above 1. Default 5.	5.0
n_max	int32	The number of radial functions. Default 8.	8
l_max	int32	The highest degree of the spherical harmonics, at most 20. Default 6.	6
sigma	float64	The width in Å of the Gaussian on each neighbor. Default 0.5.	0.5
crossover	bool	Keep the products of the densities of two different elements. Default True.	True

cutoff property

cutoff

The reach of the neighbors in Å: the cutoff and the distance over which the Gaussian of a neighbor decays to a thousandth.

dimension property

dimension

The number of values per atom.

descriptors

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

The SOAP of each atom.

Parameters:

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

Returns:

Type	Description
ndarray	(N, dimension) float64, the power spectrum of each atom: for each pair of species in the order of their atomic numbers, for each degree, for each pair of radial functions, the second from the first on within one species.

Raises:

Type	Description
MissingProperty	Without an element column.
InvalidParameter	For an atom of an element not among the species.

structure_descriptors

structure_descriptors(frames, calculator)

The descriptor of each frame: the mean of the descriptors of its atoms.

Parameters:

Name	Type	Description	Default
frames	sequence of System	The frames.	required
calculator	SOAP, NEP or any object with descriptors(system)	What gives the (N, D) descriptors of the atoms of a frame, such as mdapy.mlip.SOAP or mdapy.calculators.NEP.	required

Returns:

Type	Description
ndarray	(F, D) float64, one descriptor per frame.

principal_components

principal_components(points, n=2)

The principal components of points, such as descriptors.

Parameters:

Name	Type	Description	Default
points	array_like	(M, D) float64 points.	required
n	int32	Number of components kept, at most D. Default 2.	2

Returns:

Type	Description
PrincipalComponents	The projection of the points, the components and their variances; each component points so that its largest entry is positive.

PrincipalComponents dataclass

PrincipalComponents(projection, components, variance, ratio, mean)

Bases: Result

The principal components of points.

Attributes:

Name	Type	Description
projection	ndarray	(M, n) float64 coordinates of the points along the components.
components	ndarray	(n, D) float64, the components, unit vectors, by decreasing variance.
variance	ndarray	(n,) float64, the variance along each component.
ratio	ndarray	(n,) float64, the fraction of the total variance of each component.
mean	ndarray	(D,) float64, the mean of the points.

transform

transform(points)

(K, n) coordinates of other points along the components.

Choosing frames

farthest_point_sampling

farthest_point_sampling(points, count, *, start=0, selected=None)

Points chosen one by one, each the farthest from those chosen before, such as the frames of a training set that cover the space of descriptors.

Parameters:

Name	Type	Description	Default
points	array_like	(M, D) float64, the candidates.	required
count	int32	Number of points chosen.	required
start	int32 or None	The first point chosen; None to start from the farthest from selected. Default 0.	0
selected	array_like	(K, D) float64 points already chosen, such as the training set so far; the candidates are chosen far from them as well.	None

Returns:

Type	Description
ndarray	(count,) int64 indices of the points chosen, in order.

Errors and uncertainty

predict

predict(frames, calculator)

The predictions of a model against the labels of frames, such as those of a training set.

Parameters:

Name	Type	Description	Default
frames	sequence of System	The frames, their labels the info energy (eV) and virial (eV) and the column forces (eV/Å), as extended XYZ files of training sets hold them.	required
calculator	Calculator	The model: any MDAPY calculator, such as NEP, or an ASE calculator through mdapy.interop.from_ase_calculator.	required

Returns:

Type	Description
Predictions	The labels and the predictions, per atom.

read_gpumd

read_gpumd(folder, kind='train', *, xyz=None)

The predictions of a NEP model against its training or test set, from the files GPUMD or torchnep write: energy, force and virial.

Parameters:

Name	Type	Description	Default
folder	str or Path	The folder of energy_train.out, force_train.out and virial_train.out (or _test).	required
kind	str	"train" or "test". Default train.	'train'
xyz	str or Path	The extended XYZ file of the frames, whose frames give the number of atoms of each. Default train.xyz (or test.xyz) in the folder.	None

Returns:

Type	Description
Predictions	The labels and the predictions, the frames in the order of the training set; virials NaN where it has none.

Predictions dataclass

Predictions(atoms, energy, forces, virial)

Bases: Result

The energies, forces and virials of frames: the labels and the predictions of a model.

Attributes:

Name	Type	Description
atoms	ndarray	(F,) int64 the number of atoms of each frame.
energy	ndarray	(F, 2) float64, the label and the prediction of each frame, in eV per atom; NaN for a frame without a label.
forces	ndarray	(A, 2, 3) float64, the label and the prediction of the force on each atom of all frames one after the other, in eV/Å; NaN without labels.
virial	ndarray	(F, 2, 3, 3) float64, the label and the prediction of the virial of each frame, in eV per atom; NaN where either is missing.

frame_of_atom property

frame_of_atom

(A,) the frame of each atom of forces.

table

table()

The errors of each frame: of the energy per atom in eV, the root mean square and the largest error of the force components in eV/Å, and the root mean square error of the virial per atom in eV.

Returns:

Type	Description
DataFrame	One row per frame: frame, atoms, energy, energy_error, force_rmse, force_max_error, virial_rmse.

rmse

rmse()

The root mean square errors over all frames with labels.

Returns:

Type	Description
dict	energy in eV per atom, forces in eV/Å over the force components, virial in eV per atom over the components.

worst

worst(count, by='force_rmse')

The frames of the largest errors.

Parameters:

Name	Type	Description	Default
count	int32	How many.	required
by	str	A column of table: energy_error (by its size), force_rmse, force_max_error or virial_rmse. Default force_rmse.	'force_rmse'

Returns:

Type	Description
ndarray	int64 the frames, the largest error first.

committee

committee(frames, calculators)

The spread of the predictions of several models of frames: large where they disagree, as where none of them was trained.

Parameters:

Name	Type	Description	Default
frames	sequence of System	The frames.	required
calculators	sequence of Calculator	Two or more models, such as NEP models trained with other seeds, or models of other kinds.	required

Returns:

Type	Description
CommitteeResult	The spread of the energies and the forces.

CommitteeResult dataclass

CommitteeResult(atoms, energy, forces, max_force)

Bases: Result

How much the predictions of several models differ.

Attributes:

Name	Type	Description
atoms	ndarray	(F,) int64 the number of atoms of each frame.
energy	ndarray	(F,) float64, the standard deviation of the energy per atom of each frame in eV.
forces	ndarray	(A,) float64 of each atom of all frames one after the other, the root mean square over the models of the distance of its force from their mean force, in eV/Å.
max_force	ndarray	(F,) float64, the largest of forces in each frame.

novelty

novelty(points, reference=None)

How far each point lies from the nearest of others, such as the descriptors of candidate frames from those of a training set.

Parameters:

Name	Type	Description	Default
points	array_like	(M, D) float64, the points.	required
reference	array_like	(K, D) float64, the points to measure from. Default the other points of points, whose zero distances find repeated frames.	None

Returns:

Type	Description
ndarray	(M,) float64, the distance of each point from the nearest reference point.

Checking and perturbing frames

check_frames

check_frames(frames, *, close=0.5)

What may be wrong with each frame of a training set: atoms too close, a net force, missing labels.

Parameters:

Name	Type	Description	Default
frames	sequence of System	The frames, with an element column.	required
close	float64	Two atoms closer than this fraction of the sum of their covalent radii are too close. Default 0.5.	0.5

Returns:

Type	Description
DataFrame	One row per frame: frame, atoms; closest, the smallest distance of two atoms over the sum of their covalent radii where it is below the fraction, else inf; too_close; net_force, the length of the sum of the forces in eV/Å (NaN without forces); and has_energy, has_forces, has_virial.

perturb

perturb(system, count, *, displacement=0.05, strain=0.03, style='normal', seed=None)

Copies of a system with its atoms displaced and its box strained at random, such as for a first training set.

Parameters:

Name	Type	Description	Default
system	System	The system.	required
count	int32	Number of copies.	required
displacement	float64	Size of the displacement of each atom in Å. Default 0.05.	0.05
strain	float64	Largest component of the symmetric strain of the box, applied with the atoms. Default 0.03.	0.03
style	(normal, uniform, const)	Displacements with a root mean square of displacement; uniform in a ball of radius displacement; or exactly displacement long. Default normal.	"normal"
seed	int64 or Generator	Seed of the random numbers.	None

Returns:

Type	Description
list of System	The copies, without the energies and forces of the system.