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-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)
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')[source]
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^{ang}_i\) are the weights of the \(N\) quadrature points. Just to clarify, the \(4\pi\) 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')[source]
Generate angular grid for a given degree or size.
- Parameters
degree (int, 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
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)[source]
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)[source]
Create a grid contain 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
- integrate(*value_arrays)[source]
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 an angular grid.
- Type
str
- moments(orders, centers, func_vals, type_mom='cartesian', return_orders=False)[source]
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 density, 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\) values evaluated on 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 on the m`th 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)[source]
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,)