grids

Provides helper functions for setting up grids for numerical calculations.

compute_density_density_basis(mol_with_density_basis: Mole, grid: Grids, coeffs: ndarray | Tensor, max_memory: float = 4000.0)

Compute the density on the grid using the density basis.

compute_density_orbital_basis(mol_with_orbital_basis: Mole, grid: Grids, gamma: ndarray | Tensor, max_memory: float = 4000.0)

Compute the density on the grid using the orbital basis.

compute_l1_norm_orbital_vs_density_basis(mol_with_orbital_basis: Mole, mol_with_density_basis: Mole, grid: Grids, gamma: ndarray, coeffs: ndarray, max_memory: float = 4000.0)

Compute the L1 norm (sum of absolute differences) between the densities computed in the orbital and density basis.

This function computes the density over the same grid using two different approaches (orbital and density bases) and then returns the L1 norm of the difference.

Parameters:

• mol_with_orbital_basis – Molecule object using the orbital basis.

• mol_with_density_basis – Molecule object using the density basis.

• grid – Grid on which the densities are evaluated.

• gamma – Density matrix used in the orbital basis evaluation.

• coeffs – Coefficients used in the density basis evaluation.

• max_memory – Maximum memory (in MB) allowed for processing grid blocks.

Returns:

L1 norm (a torch scalar) of the density difference.

compute_max_block_size(max_memory: float, num_aos: int, heuristic_multiplier: int = 8) → int

Compute the maximum number of grid points per block.

The estimated memory usage per grid point is assumed to be:

memory_usage_per_point = dtype_bytes * heuristic_multiplier * num_aos

where:

• dtype_bytes: the number of bytes per tensor entry (e.g., 8 for float64)

• heuristic_multiplier: an empirical factor that estimates the additional memory overhead per grid point when computing the XC functional.

The total memory allowed is given in MB, so we first convert it to bytes, then compute:

max_block_size = floor((max_memory_in_bytes) / memory_usage_per_point)

Parameters:

• max_memory – Maximum memory (in MB) allowed. when computing the XC functional.

• num_aos – Number of atomic orbitals (or related dimension).

• heuristic_multiplier – A heuristic factor estimating the actual memory usage per grid point entry

Returns:

Maximum number of grid points in one block.

get_grid_blocks(grid_size: int, block_size: int) → list[tuple[int, int]]

Split the grid into blocks defined by start and end indices.

Parameters:

• grid_size – Total number of grid points.

• block_size – Maximum number of grid points per block.

Returns:

List of tuples (block_start, block_end) for each block.

get_lebedev_grid(n_points: int) → tuple[ndarray, ndarray]

Get Lebedev grid with a given number of points.

Parameters:

n_points – Number of grid points. Allowed values are: 1, 6, 14, 26, 38, 50, 74, 86, 110, 146, 170, 194, 230, 266, 302, 350, 434, 590, 770, 974, 1202, 1454, 1730, 2030, 2354, 2702, 3074, 3470, 3890, 4334, 4802, 5294, 5810.

Returns:

Coordinates and weights of the grid points. The weights sum up to \(4 \pi\).

get_radial_densities(mol: Mole, center: ndarray, coeffs: ndarray, radii: ndarray, n_spherical_points: int) → ndarray

Get radial density for a given number of points and radii.

Parameters:

• mol – The molecule with density basis.

• center – Center of the radial density.

• coeffs – Coefficients of the basis functions. If the dimension is one, they are interpreted as a single set of coefficients. If the dimension is two, they are interpreted as a list of coefficients with shape (n_densities, n_basis_functions). The coefficients are assumed to be untransformed.

• radii – Radii of the spheres in Bohr.

• n_spherical_points – Number of grid points on the sphere. Possible values are listed in get_lebedev_grid().

Returns:

Radial densities at given radii.

grid_setup(mol: Mole, grid_level: int = 3, prune: str | Callable | None = 'nwchem_prune') → Grids

Sets up a grid for numerical calculations of the exchange correlation potential.

Parameters:

• mol – the Molecule object in some basis

• grid_level – controls the density of the grid-points

• prune – the pruning scheme

Returns:

a grid object

Return type:

grid

Raises:

NotImplementedError – if the specified pruning method is not known.