grid.angular module

Angular grid module for constructing integration grids on the unit sphere.

The Lebedev grid points used were obtained from the theochem/HORTON package. Their calculations were based on F77 translation by Dr. Christoph van Wuellen and these are the comments from that translation.

This subroutine is part of a set of subroutines that generate Lebedev grids [1] [2] [3] [4] [5] [6] for integration on a sphere. The original C-code [1] was kindly provided by Dr. Dmitri N. Laikov and translated into Fortran by Dr. Christoph van Wuellen. This subroutine was translated from C to fortran77 by hand. Users of this code are asked to include reference [1] in their publications, and in the user- and programmers-manuals describing their codes. This code was distributed through CCL (http://www.ccl.net/).

The symmetric spherical t-design were obtained from reference [7].

References

The following references are for the Lebedev grid points.

[1] (1,2,3)

V.I. Lebedev, and D.N. Laikov “A quadrature formula for the sphere of the 131st algebraic order of accuracy” Doklady Mathematics, Vol. 59, No. 3, 1999, pp. 477-481.

[2]

V.I. Lebedev “A quadrature formula for the sphere of 59th algebraic order of accuracy” Russian Acad. Sci. Dokl. Math., Vol. 50, 1995, pp. 283-286.

[3]

V.I. Lebedev, and A.L. Skorokhodov “Quadrature formulas of orders 41, 47, and 53 for the sphere” Russian Acad. Sci. Dokl. Math., Vol. 45, 1992, pp. 587-592.

[4]

V.I. Lebedev “Spherical quadrature formulas exact to orders 25-29” Siberian Mathematical Journal, Vol. 18, 1977, pp. 99-107.

[5]

V.I. Lebedev “Quadratures on a sphere” Computational Mathematics and Mathematical Physics, Vol. 16, 1976, pp. 10-24.

[6]

V.I. Lebedev “Values of the nodes and weights of ninth to seventeenth order Gauss-Markov quadrature formulae invariant under the octahedron group with inversion” Computational Mathematics and Mathematical Physics, Vol. 15, 1975, pp. 44-51.

The following references are for the symmetric spherical t-design points:

[7]

R. S. Womersley, Efficient Spherical Designs with Good Geometric Properties. In: Dick J., Kuo F., Wozniakowski H. (eds) Contemporary Computational Mathematics - A Celebration of the 80th Birthday of Ian Sloan. Springer (2018) pp. 1243-1285 https://doi.org/10.1007/978-3-319-72456-0_57

class AngularGrid(degree=50, *, size=None, cache=True, method='lebedev')

Bases: Grid

Angular grid for integrating functions on the unit sphere.

This class numerically evaluates the surface integral of a function \(f: S^2 \rightarrow \mathbb{R}\) over the unit-sphere:

\[\int_{S^2} f d\Omega = \int_0^{2\pi} \int_0^\pi f(\theta, \phi) \sin(\phi) d\theta d\phi \approx \sum_{i}^{N} w_i f(\phi_i, \theta_i),\]

where \(S^2\) is the unit-sphere parameterized by the quadrature points \(\theta_i \in [0, 2\pi]\) and \(\phi_i \in [0, \pi)\), and \(w_{i}\) are the weights of the \(N\) quadrature points. The \(4\pi\) normalization factor present in the original quadrature scheme is included in the integration weights.

Two types of angular grids are supported: Lebedev-Laikov grid and symmetric spherical t-design. Specifically, for spherical t-design, the weights are constant value of \(4 \pi / N\), where \(N\) is the number of points in the grid. The weights are chosen so that the spherical harmonics are normalized.

__init__(degree=50, *, size=None, cache=True, method='lebedev')

Generate angular grid for a given degree or size.

Parameters:

• degree (int or None, optional) – Maximum angular degree \(l\) of spherical harmonics that the angular grid can integrate accurately. If the angular grid corresponding to the given angular degree is not supported, the next largest degree is used. If size is provided, degree is ignored.

• size (int or None, optional, keyword-only) – Number of angular grid points. If the angular grid corresponding to the given size is not supported, the next largest size is used. If both degree and size are given, size is used for constructing the angular grid.

• cache (bool, optional, keyword-only) – If True, then store the points and weights of the AngularGrid in cache to avoid duplicate grids that have the same degree.

• method (str, optional, keyword-only) – Method for constructing the angular grid. Options are “lebedev” (for Lebedev-Laikov) and “spherical” (for symmetric spherical t-design).

Returns:

An instance of angular grid with points and weights on a unit sphere.

Return type:

AngularGrid

Notes

• Sometimes the weights for Lebedev-Laikov grids can be negative. Choosing degrees that have positive weights can mitigate round-off errors. Degrees equal to 13, 25 or 27 have negative weights. See https://github.com/theochem/grid/issues/158.

static convert_angular_sizes_to_degrees(sizes, method)

Convert given Lebedev/Spherical design grid sizes to degrees.

Parameters:

• sizes (ndarray[int]) – Sequence of angular grid sizes (e.g., number of points for each atomic shell).

• method (str) – Method for constructing the angular grid. Options are “lebedev” (for Lebedev-Laikov) and “spherical” (for symmetric spherical t-design).

Returns:

Sequence of the corresponding angular degree of the angular grid corresponding to its size.

Return type:

ndarray[int]

property degree

The degree of spherical harmonics that this angular grid can integrate exactly.

Type:

int

get_localgrid(center, radius)

Create a grid containing points within the given radius of center.

Parameters:

• center (float or np.array(M,)) – Cartesian coordinates of the center of the local grid.

• radius (float) – Radius of sphere around the center. When equal to np.inf, the local grid coincides with the whole grid, which can be useful for debugging.

Returns:

Instance of LocalGrid.

Return type:

LocalGrid

integrate(*value_arrays)

Integrate over the whole grid for given multiple value arrays.

Product of all value_arrays will be computed element-wise then integrated on the grid with its weights:

\[\int w(x) \prod_i f_i(x) dx.\]

Parameters:

*value_arrays (np.ndarray(N, )) – One or multiple value array to integrate.

Returns:

The calculated integral over given integrand or function

Return type:

float

property method

Method used for constructing the angular grid.

Type:

str

moments(orders, centers, func_vals, type_mom='cartesian', return_orders=False)

Compute the multipole moment integral of a function over centers.

The Cartesian type moments are:

\[m_{n_x, n_y, n_z} = \int (x - X_c)^{n_x} (y - Y_c)^{n_y} (z - Z_c)^{n_z} f(r) dr,\]

where \(\textbf{R}_c = (X_c, Y_c, Z_c)\) is the center of the moment, \(f(r)\) is the function, and \((n_x, n_y, n_z)\) are the Cartesian orders.

The spherical/pure moments with \((l, m)\) parameter are:

\[m_{lm} = \int | \textbf{r} - \textbf{R}_c|^l S_l^m(\theta, \phi) f(\textbf{r}) d\textbf{r},\]

where \(S_l^m\) is a regular, real solid harmonic.

The radial moments with \(n\) parameter are:

\[m_n = \int | \textbf{r} - \textbf{R}_c|^{n} f(\textbf{r}) d\textbf{r}\]

The radial combined with spherical/pure moments \((n, l, m)\) are:

\[m_{nlm} = \int | \textbf{r} - \textbf{R}_c|^{n+1} S_l^m(\theta, \phi) f(\textbf{r}) d\textbf{r}\]

Parameters:

• orders (int) – Generates all orders with Horton order depending on the type of the multipole moment type_mom.

• centers (ndarray(M, 3)) – The centers \(\textbf{R}_c\) of the moments to compute from.

• func_vals (ndarray(N,)) – The function \(f\) is evaluated at all \(N\) points on the integration grid.

• type_mom (str) – The type of multipole moments: “cartesian”, “pure”, “radial” and “pure-radial”.

• return_orders (bool) – If true, it will also return a list of size \(L\) of the orders corresponding to each integral/row of the output.

Returns:

Computes the moment integral of the function at the mth center for all orders. If return_orders is true, then this also returns a list that describes what each row/order is, e.g. for Cartesian, [(0, 0, 0), (1, 0, 0) ,…].

Return type:

ndarray(L, M), or (ndarray(L, M), list)

property points

Positions of the grid points.

Type:

np.ndarray(N,) or np.ndarray(N, M)

save(filename)

Save the points and weights as a npz file.

Parameters:

filename (str) – The path/name of the .npz file.

property size

the total number of points on the grid.

Type:

int

property weights

the weights of each grid point.

Type:

np.ndarray(N,)