elfes.physics

Evaluate a basis set placed on a finite geometry at Cartesian points.

Parameters:

• geometry

  (Geometry) –

  Atomic centers; periodic geometries are unsupported.

• basis_set

  (SplineNumericalBasisSet | UniformNumericalBasisSet | GaussianBasisSet) –

  Basis functions selected by each atom's atomic number.

• coordinates

  (ArrayLike) –

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

Returns:

• NDArray[float64] –

  Values with shape (n_points, n_orb) in atom-major basis ordering.

Merge compatible element subsets of one concrete basis-set type.

Shared atomic numbers must have equal complete atomic bases. The returned atomic bases are ordered by atomic number independently of input order.

Contract a Gaussian AO density matrix with three-center overlaps.

Three-center integrals are evaluated one target-basis shell at a time and immediately contracted with every leading density-matrix component. The full (n_ao, n_ao, n_basis) tensor is never materialized.

Calculate the ordinary overlap matrix of a finite Gaussian basis.

Evaluate physical components of a Gaussian AO density matrix at quadrature points.

Build an atomistic neighbor list within a strict distance cutoff.

Parameters:

• quantities

  (str) –

  String selecting the returned quantities and their order. The supported characters are "i" for source indices, "j" for target indices, "P" for paired indices, "S" for integer cell shifts, "d" for distances, and "D" for displacement vectors. Characters may be repeated. An empty string returns an empty tuple.

• positions

  (NDArray[float32] | NDArray[float64]) –

  Atomic Cartesian positions. For one structure, use an (n_atoms, 3) NumPy array. For a batch, concatenate all positions into (n_total_atoms, 3). The dtype must be float32 or float64. All values must be finite.

• cell

  (NDArray[float32] | NDArray[float64]) –

  Cartesian cell vectors stored as rows. Use shape (3, 3) when batch_ptr is None and (n_structures, 3, 3) for a batch. Its floating dtype must match positions. All values must be finite. For every nonempty structure, the rows enabled by pbc must be linearly independent; inactive rows and the full cell may be rank deficient.

• pbc

  (NDArray[bool_]) –

  Periodic boundary flags for the three cell rows. Use shape (3,) for one structure and (n_structures, 3) for a batch. The dtype must be bool.

• cutoff

  (float) –

  Strict, finite, positive distance cutoff. positions, cell, and cutoff must use the same length unit.

• batch_ptr

  (NDArray[int64] | None, default: None ) –

  Optional int64 structure boundaries in the concatenated positions, with shape (n_structures + 1,). It must start at zero, be nondecreasing, and end at n_total_atoms. None denotes one structure and is equivalent to [0, n_atoms]. Its dtype must be int64.

• algorithm

  (Literal['auto', 'brute_force', 'cell_list'], default: 'auto' ) –

  Search method. "auto" (default) selects a backend- appropriate method. "brute_force" exhaustively checks every relevant atom pair. "cell_list" partitions space so that atoms only inspect nearby regions.

• cpu_threads

  (int | None, default: None ) –

  Number of CPU threads used by this call, including the calling thread. A positive integer explicitly selects the thread count. None uses the conservative CPU default of one thread. CPU workers are reused across calls.

• sorted

  (bool, default: False ) –

  If True, sort pairs by source index. The order of target indices and cell shifts within each source is unspecified. The default is False.

• half_list

  (bool, default: False ) –

  If False (default), return the full directed list. If True, retain the lexicographically smaller of (source, target, Sx, Sy, Sz) and (target, source, -Sx, -Sy, -Sz).

• include_self

  (bool, default: False ) –

  Whether to include exactly one zero-shift self pair (i, i, [0, 0, 0]) for every atom. The default is False.

Returns:

• ndarray –

  A tuple containing one array for each character in quantities, in

• ... –

  the same order. If n_edges pairs are found:

• tuple[ndarray, ...] –
  • i and j have dtype int64 and shape (n_edges,).
• tuple[ndarray, ...] –
  • P has dtype int64 and shape (n_edges, 2); its columns are
• tuple[ndarray, ...] –

  source and target.

• tuple[ndarray, ...] –
  • S has dtype int32 and shape (n_edges, 3) and translates
• tuple[ndarray, ...] –

  the target image.

• tuple[ndarray, ...] –
  • d has the input floating dtype and shape (n_edges,).
• tuple[ndarray, ...] –
  • D has the input floating dtype and shape (n_edges, 3).
• tuple[ndarray, ...] –

  For pair k in structure b, D[k] is

• tuple[ndarray, ...] –

  positions[target[k]] - positions[source[k]] + S[k] @ cell[b].

• tuple[ndarray, ...] –

  For a single structure, use cell directly.

Raises:

• TypeError –

  If quantities or algorithm is not a string; cpu_threads is neither None nor a Python int; or a boolean option is not a Python bool.

• ValueError –

  If quantities contains an unsupported character; algorithm is unsupported; or frontend shapes, dtypes, batch_ptr, cutoff, cpu_threads, periodic cells, or host-validated index/resource bounds are invalid.

• RuntimeError –

  If the required native CPU extension is missing; if native search discovers nonfinite positions or a representative wrap/output shift outside its integer range; if an explicitly requested cell list cannot safely process the input; or if backend execution otherwise fails.

>>> import numpy as np
>>> from elfes.physics import neighbor_list
>>> positions = np.array([[0.0, 0.0, 0.0], [0.8, 0.0, 0.0]])
>>> cell = np.eye(3) * 4.0
>>> pbc = np.zeros(3, dtype=np.bool_)
>>> pairs, shifts, distances = neighbor_list(
...     "PSd", positions, cell, pbc, cutoff=1.0
... )
>>> pairs.shape, shifts.shape, distances.tolist()
((2, 2), (2, 3), [0.8, 0.8])

Build a PySCF atom-centered quadrature grid.

Return a new basis whose radial shells have unit radial norm.

Integrate r^2 |R(r)|^2 for every radial shell.

Spline numerical bases use five-point Gauss–Legendre quadrature on each spline interval. Uniform numerical bases use composite Simpson quadrature on their stored samples.

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.

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).

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).

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).

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))).

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

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 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.

Return the grid-integrated L1 difference between sampled values.

Return the grid-integrated L2 difference between sampled values.