Basis functions¶

class featomic.basis.TensorProduct(*, max_angular: int, radial: RadialBasis, spline_accuracy: float | None = 1e-08)¶

Bases: ExpansionBasis

Basis function set combining spherical harmonics with a radial basis functions set, taking all possible combinations of radial and angular basis function.

Using N radial basis functions and L angular basis functions, this will create N x L basis functions (\(B_{nlm}\)) for the overall expansion:

\[B_{nlm}(\boldsymbol{r}) = R_{nl}(r)Y_{lm}(\hat{r}) \,\]

Parameters:

max_angular – Largest angular channel to include in the basis
radial – radial basis to use for all angular channels
spline_accuracy – requested accuracy of the splined radial integrals, defaults to 1e-8

class featomic.basis.Explicit(*, by_angular: Dict[int, RadialBasis], spline_accuracy: float | None = 1e-08)¶

Bases: ExpansionBasis

An expansion basis where combinations of radial and angular functions is picked explicitly.

The angular basis functions are still spherical harmonics, but only the degrees included as keys in by_angular will be part of the output. Each of these angular basis function can then be associated with a set of different radial basis function, potentially of different sizes.

Parameters:

by_angular – definition of the radial basis for each angular channel to include.
spline_accuracy – requested accuracy of the splined radial integrals, defaults to 1e-8

class featomic.basis.LaplacianEigenstate(*, radius: float, max_radial: int, max_angular: int | None = None, spline_accuracy: float | None = 1e-08)¶

Bases: ExpansionBasis

The Laplacian eigenstate basis, introduced in https://doi.org/10.1063/5.0124363, is a set of basis functions for spherical expansion which is both smooth (in the same sense as the smoothness of a low-pass-truncated Fourier expansion) and ragged, using a different number of radial function for each angular channel. This is intended to obtain a more balanced smoothness level in the radial and angular direction for a given total number of basis functions.

This expansion basis is not directly implemented in the native calculators, but is intended to be used with the featomic.splines.SoapSpliner to create splines of the radial integrals.

Parameters:

radius – radius of the basis functions
max_radial – number of radial basis function for the L=0 angular channel. All other angular channels will have fewer radial basis functions.
max_angular – Truncate the set of radial functions at this angular channel. If None, this will be set to a high enough value to include all basis functions with an Laplacian eigenvalue below the one for l=0, n=max_radial.
spline_accuracy – requested accuracy of the splined radial integrals, defaults to 1e-8

class featomic.basis.ExpansionBasis¶

Base class representing a set of basis functions used by spherical expansions.

A full basis typically uses both a set of radial basis functions, and angular basis functions; combined in various ways. The angular basis functions are almost always spherical harmonics, while the radial basis function can be freely picked.

You can inherit from this class to define new sets of basis functions, implementing get_hypers() to create the right hyper parameters for the underlying native calculator, as well as angular_channels() and radial_basis() to define the set of basis functions to use.

get_hypers()¶: Return the native hyper parameters corresponding to this set of basis functions

abstract angular_channels() → List[int]¶: Get the list of angular channels that are included in the expansion basis.

abstract radial_basis(angular: int) → RadialBasis¶: Get the radial basis used for a given angular channel

Radial basis functions¶

class featomic.basis.Gto(*, max_radial: int, radius: float | None = None)¶

Bases: RadialBasis

Gaussian Type Orbital (GTO) radial basis.

It is defined as

\[R_n(r) = r^n e^{-\frac{r^2}{2\sigma_n^2}},\]

where \(\sigma_n = \sqrt{n} r_0 / N\) with \(r_0\) being the basis radius and \(N\) the number of radial basis functions.

Parameters:

max_radial – maximal radial basis index to include (there will be N = max_radial + 1 basis functions overall)
radius – radius of the GTO basis functions. This is only required for LODE spherical expansion or splining the radial integral.

class featomic.basis.Monomials(*, angular_channel: int, max_radial: int, radius: float)¶

Bases: RadialBasis

Monomial radial basis, consisting of functions:

\[R_{nl}(r) = r^{l+2n}\]

These capture precisely the radial dependence if we compute the Taylor expansion of a generic function defined in 3D space.

Parameters:

angular_channel – index of the angular channel associated with this radial basis, i.e. \(l\) in the equation above.
max_radial – maximal radial basis index to include (there will be N = max_radial + 1 basis functions overall)
radius – radius of the radial basis. For local spherical expansions, this is typically the same as the spherical cutoff radius.

class featomic.basis.SphericalBessel(*, angular_channel: int, max_radial: int, radius: float)¶

Bases: RadialBasis

Spherical Bessel functions as a radial basis.

This is used among others in the Laplacian eigenstate basis. The basis functions have the following form:

\[R_{ln}(r) = j_l \left( \frac{r}{r_0} \text{zero}(J_l, n) \right)\]

where \(j_l\) is the spherical bessel function of the first kind of order \(l\), \(r_0\) is the basis function radius, and \(\text{zero}(J_l, n)\) is the \(n\)-th zero of (non-spherical) bessel function of first kind and order \(l\).

Parameters:

angular_channel – index of the angular channel associated with this radial basis, i.e. \(l\) in the equation above.
max_radial – maximal radial basis index to include (there will be N = max_radial + 1 basis functions overall)
radius – radius of the radial basis. For local spherical expansions, this is typically the same as the spherical cutoff radius.

class featomic.basis.RadialBasis(*, max_radial: int, radius: float)¶

Base class representing a set of radial basis functions, indexed by a radial index n.

You can inherit from this class to define new custom radial basis function, by implementing the compute_primitive() method. If needed, finite_differences_derivative() can be used to compute the derivatives of a radial basis.

Overriding integration_radius can be useful to control the integration radius when evaluating the radial integral numerically. See this explanation for more information.

If the new radial basis function has corresponding hyper parameters in the native calculators, you should also implement get_hypers().

Parameters:

max_radial – maximal radial basis index to include (there will be N = max_radial + 1 basis functions overall)
radius – radius of the radial basis. For local spherical expansions, this is typically the same as the spherical cutoff radius.

get_hypers()¶: Return the native hyper parameters corresponding to this set of basis functions

property size: int¶: Get the size of the basis set (i.e. the total number of basis functions)

property integration_radius: float¶

Get the radius to use for numerical evaluation of radial integrals.

This default to the radius given as a class parameter, but can be overridden by child classes as needed.

abstract compute_primitive(positions: ndarray, n: int, *, derivative: bool) → ndarray¶

Evaluate the primitive (not normalized not orthogonalized) radial basis for index n on grid points at the given positions.

Parameters:

n – index of the radial basis to evaluate
positions – positions of the grid points where the basis should be evaluated
derivative – should this function return the values of the radial basis or its derivatives.

Returns:

the values (or derivative) of radial basis on the grid points

compute(positions: ndarray, *, derivative: bool) → ndarray¶

Evaluate the orthogonalized and normalized radial basis on grid points at the given positions. The returned array contains all the radial basis, from n=0 to n = max_radial.

Parameters:

positions – positions of the grid points where the basis should be evaluated
derivative – should this function return the values of the radial basis or its derivatives.

Returns:

the values (or derivative) of radial basis on the grid points

finite_differences_derivative(positions: ndarray, n: int, *, displacement=1e-06) → ndarray¶: Helper function to compute derivate of the radial function using finite differences. This can be used by child classes to implement the derivative=True branch of compute() function.