Skip to content

Symmetry operations

Spatial rotations and spin transformations act on different parts of an electronic quantity. Spherical harmonics and Wigner matrices describe the spatial basis, while Pauli decomposition makes the spin components explicit. These operations provide the conventions used by the physical objects and their rotation methods.

The mathematical background is developed in Spherical Harmonics and Spatial and Spin Symmetries. The functions below operate on NumPy arrays; Torch counterparts for spherical harmonics and Wigner matrices are available in elfes.modules.

Spherical functions and rotations

Spherical harmonics use the normalized real convention. Solid harmonics include the radial factor, Gaunt coefficients integrate products of three harmonics, and rotation matrices act on spherical components or complete atomic bases.

spherical_harmonics 

spherical_harmonics(l_max: int, directions: NDArray[float64]) -> NDArray[float64]

Evaluate normalized real spherical harmonics through l_max.

The harmonics follow the Wikipedia real spherical harmonic convention and are ordered in consecutive degree blocks, with m = -l, ..., l within each block.

Parameters:

  • l_max (int) –

    Highest angular degree to calculate. Results include every degree from zero through l_max.

  • directions (NDArray[float64]) –

    Nonzero Cartesian directions with shape (..., 3) and dtype float64.

Returns:

  • NDArray[float64] –

    Harmonic values with shape (..., (l_max + 1) ** 2).

solid_harmonics 

solid_harmonics(l_max: int, vectors: NDArray[float64]) -> NDArray[float64]

Evaluate real solid harmonics through l_max.

Each degree-l block contains r**l * Y_lm(r_hat) in the Wikipedia real spherical harmonic convention, ordered by m = -l, ..., l. At the origin the degree-zero component is Y_00 and all higher-degree components are zero.

Parameters:

  • l_max (int) –

    Highest angular degree to calculate. Results include every degree from zero through l_max.

  • vectors (NDArray[float64]) –

    Cartesian vectors with shape (..., 3) and dtype float64.

Returns:

  • NDArray[float64] –

    Solid-harmonic values with shape (..., (l_max + 1) ** 2).

gaunt_coefficients 

gaunt_coefficients(l1: int, l2: int, l3: int) -> NDArray[float64]

Return triple products of normalized real spherical harmonics.

The harmonics follow the Wikipedia real spherical harmonic convention. Each output axis is ordered by m = -l, ..., l. Combinations that violate the angular-momentum selection rules return an exact-zero array.

Parameters:

  • l1 (int) –

    Angular degree of the first harmonic.

  • l2 (int) –

    Angular degree of the second harmonic.

  • l3 (int) –

    Angular degree of the third harmonic.

Returns:

  • NDArray[float64] –

    Coefficients with shape (2*l1 + 1, 2*l2 + 1, 2*l3 + 1).

wigner_D 

wigner_D(l_max: int, rotation: ArrayLike) -> NDArray[float64]

Return flattened real Wigner D matrices through l_max.

The matrices use the Wikipedia real spherical harmonic basis, with each block ordered by m = -l, ..., l and the l = 1 block ordered as (y, z, x). They describe an active orthogonal transformation acting on Cartesian column vectors: Y_l(rotation.T @ x) = Y_l(x) @ D_l(rotation) when the harmonics form a row.

Parameters:

  • l_max (int) –

    Highest non-negative angular quantum number.

  • rotation (ArrayLike) –

    Proper Cartesian rotation matrices with shape (..., 3, 3) acting on column vectors.

Returns:

  • NDArray[float64] –

    Consecutive row-major flattened blocks D_0, ..., D_l_max, with shape

  • NDArray[float64] –

    (..., sum((2 * l + 1) ** 2 for l in range(l_max + 1))).

Notes

This is the Ivanic–Ruedenberg direct recursion, including the 1998 correction and the independently verified m < 0 V term used by google/spherical-harmonics (Apache-2.0) and spaudiopy (MIT).

References

Ivanic and Ruedenberg, J. Phys. Chem. 100, 6342–6347 (1996), doi:10.1021/jp953350u; correction, J. Phys. Chem. A 102, 9099–9100 (1998), doi:10.1021/jp9833350.

basis_rotations 

basis_rotations(
    basis_set: BasisSet, atomic_numbers: NDArray[int32], rotation: ArrayLike
) -> dict[int, NDArray[float64]]

Construct active function rotations for the requested elements.

The recursion is evaluated once through the largest requested angular momentum, then each requested block is shared by every matching shell and element.

Parameters:

  • basis_set (BasisSet) –

    Atomic bases keyed by atomic number.

  • atomic_numbers (NDArray[int32]) –

    Atomic numbers with shape (n_atoms,).

  • rotation (ArrayLike) –

    Orthogonal Cartesian matrix with shape (3, 3).

Returns:

  • dict[int, NDArray[float64]] –

    Block-diagonal orbital rotation keyed by each distinct atomic number.

Pauli components

The conversion functions relate explicit spin matrices to Pauli coefficients. Quantity-specific normalization, such as the relation between density-matrix coefficients and charge or magnetization density, is determined by the physical quantity.

decompose_pauli 

decompose_pauli(spin_blocks: ArrayLike) -> NDArray

Decompose explicit spin blocks into Pauli coefficients.

The first two axes are spin row and column in (up, down) order. Remaining axes contain the corresponding spatial values. Coefficients satisfy H = sum_A H[A] * sigma_A.

Parameters:

  • spin_blocks (ArrayLike) –

    Array with shape (2, 2, *spatial_shape).

Returns:

  • NDArray –

    Complex Pauli coefficients with shape (4, *spatial_shape) and

  • NDArray –

    component order (0, x, y, z).

reconstruct_pauli 

reconstruct_pauli(
    components: ArrayLike, pauli: str, *, fill_missing: complex | None = None
) -> NDArray[complex128]

Reconstruct explicit spin blocks from Pauli coefficients.

Parameters:

  • components (ArrayLike) –

    Coefficients with shape (len(pauli), *spatial_shape).

  • pauli (str) –

    Stored Pauli components in their axis order.

  • fill_missing (complex | None, default: None ) –

    Value assigned to components absent from pauli. Required unless all four components are present.

Returns:

  • NDArray[complex128] –

    Complex array with shape (2, 2, *spatial_shape). The first two axes

  • NDArray[complex128] –

    are spin row and column in (up, down) order.

collinear_pauli 

collinear_pauli(up: ArrayLike, down: ArrayLike) -> NDArray

Convert equal-shaped spin-up/down values to (0, z) components.