Python API¶

class sphericart.SphericalHarmonics(l_max: int)¶

Spherical harmonics calculator, which computes the real spherical harmonics \(Y^m_l\) up to degree l_max. The calculated spherical harmonics are consistent with the definition of real spherical harmonics from Wikipedia.

The SphericalHarmonics object computes prefactors and initializes buffers upon creation

>>> import numpy as np
>>> import sphericart as sc
>>> sh = sc.SphericalHarmonics(l_max=8)

Then, the compute() method can be called on an array of 3D Cartesian points to compute the spherical harmonics

>>> xyz = np.random.normal(size=(10, 3))
>>> sh_values = sh.compute(xyz)
>>> sh_values.shape
(10, 81)

In order to also compute derivatives, you can use

>>> sh_values, sh_grads = sh.compute_with_gradients(xyz)
>>> sh_grads.shape
(10, 3, 81)

which returns the gradient as a tensor with size (n_samples, 3, (l_max+1)**2).

Parameters:: l_max – the maximum degree of the spherical harmonics to be calculated
Returns:: a calculator, in the form of a SphericalHarmonics object

compute(xyz: ndarray) → ndarray¶

Calculates the spherical harmonics for a set of 3D points, whose coordinates are given by the xyz array.

>>> import numpy as np
>>> import sphericart as sc
>>> sh = sc.SphericalHarmonics(l_max=8)
>>> xyz = np.random.normal(size=(10, 3))
>>> sh_values = sh.compute(xyz)
>>> sh_values.shape
(10, 81)

Parameters:: xyz – The Cartesian coordinates of the 3D points, as an array with shape (n_samples, 3)
Returns:: An array of shape (n_samples, (l_max+1)**2) containing all the spherical harmonics up to degree l_max in lexicographic order. For example, if l_max = 2, The last axis will correspond to spherical harmonics with (l, m) = (0, 0), (1, -1), (1, 0), (1, 1), (2, -2), (2, -1), (2, 0), (2, 1), (2, 2), in this order.

compute_with_gradients(xyz: ndarray) → Tuple[ndarray, ndarray]¶

Calculates the spherical harmonics for a set of 3D points, whose coordinates are in the xyz array, together with their Cartesian derivatives.

>>> import numpy as np
>>> import sphericart as sc
>>> sh = sc.SphericalHarmonics(l_max=8)
>>> xyz = np.random.normal(size=(10, 3))
>>> sh_values, sh_grads = sh.compute_with_gradients(xyz)
>>> sh_grads.shape
(10, 3, 81)

Parameters:

xyz – The Cartesian coordinates of the 3D points, as an array with shape (n_samples, 3).

Returns:

A tuple containing:

an array of shape (n_samples, (l_max+1)**2) containing all the spherical harmonics up to degree l_max in lexicographic order. For example, if l_max = 2, The last axis will correspond to spherical harmonics with (l, m) = (0, 0), (1, -1), (1, 0), (1, 1), (2, -2), (2, -1), (2, 0), (2, 1), (2, 2), in this order.
an array of shape (n_samples, 3, (l_max+1)**2) containing all the spherical harmonics’ derivatives up to degree l_max. The last axis is organized in the same way as in the spherical harmonics return array, while the second-to-last axis refers to derivatives in the x, y, and z directions, respectively.

compute_with_hessians(xyz: ndarray) → Tuple[ndarray, ndarray, ndarray]¶

Calculates the spherical harmonics for a set of 3D points, whose coordinates are in the xyz array, together with their Cartesian derivatives and second derivatives.

>>> import numpy as np
>>> import sphericart as sc
>>> sh = sc.SphericalHarmonics(l_max=8, normalized=False)
>>> xyz = np.random.normal(size=(10, 3))
>>> sh_values, sh_grads, sh_hessians = sh.compute_with_hessians(xyz)
>>> sh_values.shape
(10, 81)
>>> sh_grads.shape
(10, 3, 81)
>>> sh_hessians.shape
(10, 3, 3, 81)

Parameters:

xyz – The Cartesian coordinates of the 3D points, as an array with shape (n_samples, 3).

Returns:

A tuple containing:

an array of shape (n_samples, (l_max+1)**2) containing all the spherical harmonics up to degree l_max in lexicographic order. For example, if l_max = 2, The last axis will correspond to spherical harmonics with (l, m) = (0, 0), (1, -1), (1, 0), (1, 1), (2, -2), (2, -1), (2, 0), (2, 1), (2, 2), in this order.
an array of shape (n_samples, 3, (l_max+1)**2) containing all the spherical harmonics’ derivatives up to degree l_max. The last axis is organized in the same way as in the spherical harmonics return array, while the second-to-last axis refers to derivatives in the the x, y, and z directions, respectively.
an array of shape (n_samples, 3, 3, (l_max+1)**2) containing all the spherical harmonics’ second derivatives up to degree l_max. The last axis is organized in the same way as in the spherical harmonics return array, while the two intermediate axes represent the Hessian dimensions.

class sphericart.SolidHarmonics(l_max: int)¶

Solid harmonics calculator, up to degree l_max.

This class computes the solid harmonics, a non-normalized form of the real spherical harmonics, i.e. \(r^l Y^m_l\). These scaled spherical harmonics are polynomials in the Cartesian coordinates of the input points, and they are therefore faster to compute.

Parameters:: l_max – the maximum degree of the solid harmonics to be calculated
Returns:: a calculator, in the form of a SolidHarmonics object

compute(xyz: ndarray) → ndarray¶: Same as SphericalHarmonics.compute, but for the solid harmonics.

compute_with_gradients(xyz: ndarray) → Tuple[ndarray, ndarray]¶: Same as SphericalHarmonics.compute_with_gradients, but for the solid harmonics.

compute_with_hessians(xyz: ndarray) → Tuple[ndarray, ndarray, ndarray]¶: Same as SphericalHarmonics.compute_with_hessians, but for the solid harmonics.