grid.ngrid module

Grid for N particle functions.

class MultiDomainGrid(grid_list=None, num_domains=None)

Bases: Grid

Grid class for integrating functions of multiple variables, each defined on a different grid.

This class facilitates the numerical integration of functions with \(N\) arguments over a corresponding \(N\)-dimensional domain using grid-based methods.

\[\int \cdots \int f(x_1, x_2, \ldots, x_N) \, dx_1 dx_2 \cdots dx_N\]

The function to integrate must accept arguments \(\{x_i\}\) that correspond to the dimensions (point-wise) of the respective grids. Specifically:

• Each argument \(x_i\) corresponds to a different grid.

• The dimensionality of each argument must match the dimensionality of a point of its associated grid.

For example:

• For a function of the form f([x1, y1, z1], [x2, y2]) -> float, the first argument corresponds to a 3-dimensional grid, and the second argument corresponds to a 2-dimensional grid.

The function to integrate must have all arguments \(\{x_i\}\) with the same dimension as the points of the corresponding grids (i.e. each of the arguments corresponds to a different grid). For example for a function of the form f((x1,y1,z1), (x2,y2)) -> float the first argument must be described by a 3D grid and the second argument by a 2D grid.

__init__(grid_list=None, num_domains=None)

Initialize the MultiDomainGrid grid.

Parameters

• grid_list (list of Grid) –

  A list of Grid objects, where each Grid corresponds to a separate argument (integration domain) of the function to be integrated.

  • At least one grid must be specified.

  • The number of elements in grid_list should match the number of arguments in the target function.

• num_domains (int, optional) –

  The number of integration domains.

  • This parameter is optional and can only be specified when grid_list contains exactly one grid.

  • It must be a positive integer greater than 1.

  • If specified, the function to integrate is considered to have num_domains arguments, all defined over the same grid (i.e., the same set of points is used for each argument).

Returns

A MultiDomainGrid object.

Return type

MultiDomainGrid

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(integrand_function, non_vectorized=False, integration_chunk_size=6000)

Integrate callable on the N particle grid.

Parameters

• integrand (callable) – Integrand function to integrate. It must take a list of arguments (one for each domain) with the same dimension as the grid points used for the corresponding domain and return a float (e.g. a function of the form f([x1,y1,z1], [x2,y2,z2]) -> float).

• integration_chunk_size (int, optional) – Number of points to integrate at once. This parameter can be used to control the memory usage of the integration. Default is 1000.

• non_vectorized (bool, optional) – Set to True if the integrand is not vectorized. Default is False. If True, the integrand will be called for each point of the grid separately without vectorization. This implies a slower integration. Use this option if the integrand is not vectorized.

• integration_chunk_size – Number of points to integrate at once. This parameter can be used to control the memory usage of the integration. Default is 6000. Values too large may cause memory issues and values too small may cause accuracy issues.

Returns

Integral of callable.

Return type

float

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\) 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 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 num_domains

The number of integration domains.

Type

int

property points

Combined points of the multi-dimensional grid.

Due to the combinatorial nature of the grid, the points are returned as a generator. Each point is a tuple of the points of the individual grids.

For a MultiDomainGrid formed from two grids, [(x11, y11), (x12, y12) … (x1n, y1n)] and [(x21, y21), (x22, y22) … (x2m, y2m)], the combined points are calculated as follows: For each combination of points (x1, y1) from the first grid and (x2, y2) from the second 2D grid, the combined point is a tuple of (x1i, y1i), (x2j, y2j) where (x1, y1) and (x2, y2) are the points from the individual grids respectively.

Type

Generator

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

Generator yielding the combined weights of the multi-dimensional grid.

Because the multi-dimensional grid is formed combinatorially from multiple lower-dimensional grids, the combined weights are returned as a generator for efficiency.

For a MultiDomainGrid formed from two grids, [(x11, y11), (x12, y12) … (x1n, y1n)] and [(x21, y21), (x22, y22) … (x2m, y2m)], the combined weights are calculated as follows: For each combination of points (x1, y1) from the first grid and (x2, y2) from the second 2D grid, the combined weight w is:

w = w1 * w2

where w1 and w2 are the weights from the individual grids corresponding to (x1, y1) and (x2, y2), respectively.

Yields

float – The product of the weights from each individual grid that make up a single point in the multi-dimensional grid.