Skip to content

Grids and volumetric quantities

Real-space densities need both sampled values and a description of where those values lie. A grid defines the points and their integration measure; a volumetric quantity attaches one or more real functions to that grid.

Uniform grids use an origin, three step vectors, and a shape. Quadrature grids store explicit Cartesian points and integration weights. Their corresponding volumetric types support integration-based norms, comparisons, and rotations, including spin rotations when the values carry Pauli components.

Grids

UniformGrid dataclass 

UniformGrid(
    origin: ArrayLike, step_vectors: ArrayLike, shape: ArrayLike, pbc: ArrayLike = False
)

Uniform three-dimensional affine grid.

Grid point (i, j, k) has Cartesian position origin + [i, j, k] @ step_vectors. Lengths are in Å.

Parameters:

  • origin (ArrayLike) –

    Cartesian position of grid point (0, 0, 0) with shape (3,).

  • step_vectors (ArrayLike) –

    Cartesian displacement for one index step along each grid axis, stored as the rows of a (3, 3) matrix.

  • shape (ArrayLike) –

    Number of grid points along the three axes.

  • pbc (ArrayLike, default: False ) –

    Boolean periodic-axis flags. A scalar applies to every grid axis; omission gives no periodic axes.

n_points property 

n_points: int

Number of sampled points.

grid_vectors property 

grid_vectors: NDArray[float64]

Full grid-period vectors as rows of a (3, 3) matrix.

volume_element property 

volume_element: float

Volume represented by one grid point in Å\(^{3}\).

coordinates 

coordinates(indices: ArrayLike) -> NDArray[float64]

Map grid-index triples with shape (..., 3) to Cartesian points.

integrate 

integrate(values: ArrayLike) -> NDArray

Integrate values whose final three axes match the grid.

rotated 

rotated(rotation: ArrayLike) -> UniformGrid

Return the grid after an active orthogonal transformation.

validate_geometry 

validate_geometry(geometry: Geometry) -> None

Check that this grid and a Geometry describe the same domain.

QuadratureGrid dataclass 

QuadratureGrid(coordinates: ArrayLike, weights: ArrayLike)

Cartesian quadrature points and their integration weights.

Parameters:

  • coordinates (ArrayLike) –

    Cartesian point coordinates in Å with shape (n_points, 3).

  • weights (ArrayLike) –

    Integration weights in Å\(^{3}\) with shape (n_points,).

shape property 

shape: tuple[int]

Shape of the sampled point axis.

n_points property 

n_points: int

Number of sampled points.

integrate 

integrate(values: ArrayLike) -> NDArray

Integrate values whose final axis is the point axis.

rotated 

rotated(rotation: ArrayLike) -> QuadratureGrid

Return the quadrature points after an active rotation.

build_pyscf_quadrature_grid 

build_pyscf_quadrature_grid(geometry: Geometry, *, level: int = 3) -> QuadratureGrid

Build a PySCF atom-centered quadrature grid.

Sampled functions

Volumetric is the union of the uniform and quadrature forms.

UniformVolumetric dataclass 

UniformVolumetric(grid: UniformGrid, values: ArrayLike, pauli: str | None = None)

One or more real functions sampled on a three-dimensional uniform grid.

extra_shape property 

extra_shape: tuple[int, ...]

Shape of the non-spatial value axes.

l1_norm 

l1_norm() -> float | NDArray[float64]

Return the grid-integrated L1 norm of each set of values.

l2_norm 

l2_norm() -> float | NDArray[float64]

Return the grid-integrated L2 norm of each set of values.

rotated 

rotated(
    spatial_rotation: ArrayLike, *, spin_rotation: bool | ArrayLike = False
) -> UniformVolumetric

Return the values and uniform grid after an active rotation.

spin_rotation leaves Pauli components fixed when False, follows the spatial system as an axial vector when True, or applies an explicit proper spin rotation.

QuadratureVolumetric dataclass 

QuadratureVolumetric(grid: QuadratureGrid, values: ArrayLike, pauli: str | None = None)

One or more real functions sampled at explicit quadrature points.

extra_shape property 

extra_shape: tuple[int, ...]

Shape of the non-spatial value axes.

l1_norm 

l1_norm() -> float | NDArray[float64]

Return the quadrature-integrated L1 norm of each set of values.

l2_norm 

l2_norm() -> float | NDArray[float64]

Return the quadrature-integrated L2 norm of each set of values.

rotated 

rotated(
    spatial_rotation: ArrayLike, *, spin_rotation: bool | ArrayLike = False
) -> QuadratureVolumetric

Return the values and quadrature points after an active rotation.

spin_rotation leaves Pauli components fixed when False, follows the spatial system as an axial vector when True, or applies an explicit proper spin rotation.

Volumetric 

Volumetric = UniformVolumetric | QuadratureVolumetric

Comparing sampled functions

These differences integrate over the grid measure. The compared quantities must use matching grids and component conventions.

volumetric_l1_diff 

volumetric_l1_diff(first: Volumetric, second: Volumetric) -> float | NDArray[float64]

Return the grid-integrated L1 difference between sampled values.

volumetric_l2_diff 

volumetric_l2_diff(first: Volumetric, second: Volumetric) -> float | NDArray[float64]

Return the grid-integrated L2 difference between sampled values.