Libdescriptor API

The core libdescriptor pybind11 module can be imported as

from libdescriptor import libdescriptor as c_lds

Usually you would not need it, as the libdescriptor module provides a more convenient interface to the library, but it is documented here for lower level access. Below is a list of the routines and classes that are available in the libdescriptor library python module.

class AvailableDescriptors

An enum class that represents the available descriptors.

SymmetryFunctions

The enum for symmetry functions descriptor, mapped to Descriptor::AvailableDescriptor::KindSymmetryFunctions in C++. In python Enum, this value is mapped to integer 0.

Bispectrum

The bispectrum descriptor, mapped to Descriptor::AvailableDescriptor::KindBispectrum in C++. In python Enum, this value is mapped to integer 1.

SOAP

The SOAP descriptor, mapped to Descriptor::AvailableDescriptor::KindSOAP in C++. In python Enum, this value is mapped to integer 2.

Xi

The Xi descriptor, mapped to Descriptor::AvailableDescriptor::KindXi in C++. In python Enum, this value is mapped to integer 3.

class DescriptorKind

A class that represents a descriptor. It is directly exposing the C++ DescriptorKind class.

Variables:

  • kind – The enum kind of the descriptor.

  • width – The width of the descriptor.

  • param_file – The parameter file of the descriptor, this file is used in initialization of the class in C++ and archiving.

compute(self, index: int, species: np.ndarray[int32], neighbors: np.ndarray[int32], coordinates: np.ndarray)

Compute the descriptor for the single atom with given atom index, species, neighbors and coordinates.

Parameters:

  • index – The index of the atom for which the descriptor is computed.

  • species – The species of the atoms.

  • neighbors – The neighbors index of the atoms.

  • coordinates – The coordinates of the atoms.

Returns:

The descriptor as a numpy array.

init_descriptor(kind: AvailableDescriptors) → DescriptorKind

Initialize the empty descriptor class with the given kind.

Parameters:

kind – The kind of the descriptor.

Returns:

The initialized descriptor.

init_descriptor(file_name: str, kind: AvailableDescriptors) → DescriptorKind

Initialize the descriptor class with the given kind and parameter file.

Parameters:

  • file_name – The parameter file name.

  • kind – The kind of the descriptor.

Returns:

The initialized descriptor.

init_descriptor(kind: AvailableDescriptor, species: List[str], cutoff_fun: str, cutoff_mat: np.ndarray, sym_fun_list: List[str], sym_fun_sizes: List[int], sym_fun_param: List[float]) → DescriptorKind

Initialize the descriptor class with the symmetry functions and parameters.

Parameters:

  • kind – The kind of the descriptor, should be Available.SymmetryFunctions kind.

  • species – The species of the atoms.

  • cutoff_fun – The cutoff function.

  • cutoff_mat – The cutoff matrix.

  • sym_fun_list – The symmetry functions g1 … g5.

  • sym_fun_sizes – The symmetry function sizes.

  • sym_fun_param – The symmetry function parameters.

Returns:

The initialized descriptor.

init_descriptor(kind: AvailableDescriptors, rfac0: float, twojmax: int, diagonalstyle: int, shared_array: int, rmin0: float, switch_flag: int, bzero_flag: int, cutoff_array: np.ndarray, species: List[str], weights: List[float]) → DescriptorKind

Initialize the descriptor class with the bispectrum parameters. They follow exact same meaning as their LAMMPS counterparts.

Parameters:

  • kind – The kind of the descriptor, should be Available.Bispectrum kind.

  • rfac0 – The rfac0 parameter.

  • twojmax – The twojmax parameter.

  • diagonalstyle – The diagonalstyle parameter.

  • shared_array – The shared_array parameter.

  • rmin0 – The rmin0 parameter.

  • switch_flag – The switch_flag parameter.

  • bzero_flag – The bzero_flag parameter.

  • cutoff_array – The cutoff_array parameter.

  • species – The species of the atoms.

  • weights – The weights of the atoms.

Returns:

The initialized descriptor.

init_descriptor(kind: AvailableDescriptors, n_max: int, l_max: int, cutoff: float, species: List[str], radial_basis: str, eta: float) → DescriptorKind

Initialize the descriptor class with the SOAP parameters. They follow exact same meaning as their LAMMPS counterparts.

Parameters:

  • kind – The kind of the descriptor, should be Available.SOAP kind.

  • n_max – Number of radial basis functions to use.

  • l_max – Maximum degree of spherical harmonics.

  • cutoff – The cutoff parameter.

  • species – List of species to consider.

  • radial_basis – Radial basis function to use. Currently supported are “polynomial”.

  • eta – The gaussian width parameter of the radial basis function.

Returns:

The initialized descriptor.

init_descriptor(kind: AvailableDescriptors, l_max: int, cutoff: float, species: List[str], radial_basis: str) → DescriptorKind

Initialize the descriptor class with the Xi parameters. They follow exact same meaning as their LAMMPS counterparts.

Parameters:

  • kind – The kind of the descriptor, should be Available.Xi kind.

  • l_max – Maximum degree of spherical harmonics.

  • cutoff – The cutoff parameter.

  • species – List of species to consider.

  • radial_basis – Radial basis function to use. Currently supported are “bessel”.

Returns:

The initialized descriptor.

compute_single_atom(descriptor_class: DescriptorKind, index: int, species: np.ndarray[int32], neighbor_idx: np.ndarray[int32], coordinates: np.ndarray) → np.ndarray

Compute the descriptor for the single atom with given atom index, species, neighbors and coordinates.

Parameters:

  • descriptor_class – The initialized descriptor class.

  • index – The index of the atom for which the descriptor is computed.

  • species – The array of species indexes of the atoms.

  • neighbor_idx – The array of neighbors indexes of the atoms.

  • coordinates – The array of coordinates of the atoms.

Returns:

The descriptor as a numpy array.

gradient_single_atom(descriptor_class: DescriptorKind, index: int, species: np.ndarray[int32], neighbor_idx: np.ndarray[int32], coordinates: np.ndarray, computed_desc: np.ndarray, dE_dzeta: np.ndarray) → np.ndarray

Compute the gradient of the descriptor for the single atom with given atom index, species, neighbors and coordinates. This method computes the vector-Jacobian product of the descriptor function with respect to incoming \(\frac{dE}{d\zeta}\) vector.

Parameters:

  • descriptor_class – The initialized descriptor class.

  • index – The index of the atom for which the descriptor is computed.

  • species – The array of species indexes of the atoms.

  • neighbor_idx – The array of neighbors indexes of the atoms.

  • coordinates – The array of coordinates of the atoms.

  • computed_desc – The computed descriptor of the environment.

  • dE_dzeta – The gradient of the energy with respect to the descriptor.

Returns:

The gradient of the descriptor as a numpy array.

compute(descriptor_class: DescriptorKind, n_atoms: int, species: np.ndarray[int32], neighbor_idx: np.ndarray[int32], num_neighbors: np.ndarray[int32], coordinates: np.ndarray) → np.ndarray

Compute the descriptor for the atoms with given species, neighbors and coordinates. This method is more efficient than calling compute_single_atom() for each atom.

Parameters:

  • descriptor_class – The initialized descriptor class.

  • n_atoms – The number of atoms.

  • species – The array of species indexes of the atoms.

  • neighbor_idx – The array of neighbors indexes of the atoms.

  • num_neighbors – The array of number of neighbors of the atoms.

  • coordinates – The array of coordinates of the atoms.

Returns:

The descriptor as a numpy array.

gradient(descriptor_class: DescriptorKind, n_atoms: int, species: np.ndarray[int32], neighbor_idx: np.ndarray[int32], num_neighbors: np.ndarray[int32], coordinates: np.ndarray, computed_desc: np.ndarray, dE_dzeta: np.ndarray) → np.ndarray

Compute the gradient of the descriptor for the atoms with given species, neighbors and coordinates. This method is more efficient than calling gradient_single_atom() for each atom.

Parameters:

  • descriptor_class – The initialized descriptor class.

  • n_atoms – The number of atoms.

  • species – The array of species indexes of the atoms.

  • neighbor_idx – The array of neighbors indexes of the atoms.

  • num_neighbors – The array of number of neighbors of the atoms.

  • coordinates – The array of coordinates of the atoms.

  • computed_desc – The computed descriptor of the environment.

  • dE_dzeta – The gradient of the energy with respect to the descriptor.

Returns:

The gradient of the descriptor as a numpy array.

compute_batch(descriptor_class: DescriptorKind, n_atoms: np.ndarray[int32], config_ptr: np.ndarray[int32], species: np.ndarray[int32], neighbor_idx: np.ndarray[int32], num_neighbors: np.ndarray[int32], coordinates: np.ndarray) → np.ndarray

Compute the descriptor for the atoms with given species, neighbors and coordinates. This method is more efficient than calling compute_single_atom() for each atom.

Parameters:

  • descriptor_class – The initialized descriptor class.

  • n_atoms – The number of atoms in each configuration.

  • config_ptr – The pointer to the start of each configuration coordinates. The length of this array should be same as n_atoms.

  • species – The array of species indexes of the atoms.

  • neighbor_idx – The array of neighbors indexes of the atoms.

  • num_neighbors – The array of number of neighbors of the atoms.

  • coordinates – The array of coordinates of the atoms.

Returns:

The descriptor as a numpy array.

gradient_batch(descriptor_class: DescriptorKind, n_atoms: np.ndarray[int32], config_ptr: np.ndarray[int32], species: np.ndarray[int32], neighbor_idx: np.ndarray[int32], num_neighbors: np.ndarray[int32], coordinates: np.ndarray, computed_desc: np.ndarray, dE_dzeta: np.ndarray) → np.ndarray

Compute the gradient of the descriptor for the atoms with given species, neighbors and coordinates. This method is more efficient than calling gradient_single_atom() for each atom.

Parameters:

  • descriptor_class – The initialized descriptor class.

  • n_atoms – The number of atoms in each configuration.

  • config_ptr – The pointer to the start of each configuration coordinates. The length of this array should be same as n_atoms.

  • species – The array of species indexes of the atoms.

  • neighbor_idx – The array of neighbors indexes of the atoms.

  • num_neighbors – The array of number of neighbors of the atoms.

  • coordinates – The array of coordinates of the atoms.

  • computed_desc – The computed descriptor of the environment.

  • dE_dzeta – The gradient of the energy with respect to the descriptor.

Returns:

The gradient of the descriptor as a numpy array.

jacobian(descriptor_class: DescriptorKind, n_atoms: int, species: np.ndarray[int32], neighbor_idx: np.ndarray[int32], num_neighbors: np.ndarray[int32], coordinates: np.ndarray) → np.ndarray

Compute the jacobian of the descriptor for the atoms with given species, neighbors and coordinates. Usually you should not calculate the jacobian of the descriptor, but rather use the gradient() method, which is more efficient. This is only useful if you want to calculate the jacobian of the descriptor for some other reason.

Parameters:

  • descriptor_class – The initialized descriptor class.

  • n_atoms – The number of atoms.

  • species – The array of species indexes of the atoms.

  • neighbor_idx – The array of neighbors indexes of the atoms.

  • num_neighbors – The array of number of neighbors of the atoms.

  • coordinates – The array of coordinates of the atoms.

Returns:

The jacobian of the descriptor as a numpy array.