elfes.physics

Solve ordinary L2 projection equations for auxiliary coefficients.

Each leading dimension of basis_integrals.array is an independent right-hand side. The two inputs must use the same atom-partitioned auxiliary-basis order.

Parameters:

• aux_overlap

  (HermOrbMatrix) –

  Real dense auxiliary-basis overlap.

• basis_integrals

  (OrbVector) –

  Real <chi_lambda | f> values.

• solver

  (Literal['cholesky', 'pseudoinverse'], default: 'cholesky' ) –

  "cholesky" requires a full-rank positive-definite overlap. "pseudoinverse" accepts a rank-deficient Hermitian overlap and returns the minimum-norm solution after removing eigenvalues below rank_rtol relative to the largest absolute eigenvalue.

• rank_rtol

  (float, default: 1e-12 ) –

  Relative eigenvalue cutoff used by "pseudoinverse".

Returns:

• OrbVector –

  Auxiliary coefficients with the same shape and orbital partition as

• OrbVector –

  basis_integrals.

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

  (Tensor | ndarray) –

  Atomic Cartesian positions. For one structure, use an (n_atoms, 3) PyTorch tensor or NumPy array. For a batch, concatenate all positions into (n_total_atoms, 3). The dtype must be float32 or float64. Torch inputs may be on CPU or CUDA; NumPy inputs use the CPU backend. All values must be finite.

• cell

  (Tensor | ndarray) –

  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 and, for Torch, device 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

  (Tensor | ndarray) –

  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 and the array ecosystem/device must match positions.

• cutoff

  (float) –

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

• batch_ptr

  (Tensor | ndarray | 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 array ecosystem and, for Torch, device must match positions.

• 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 and leaves the option unspecified for CUDA. CPU workers are reused across calls. CUDA calls reject any explicit integer because CUDA execution does not use the CPU search pool.

• 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:

• tuple[Tensor, ...] | tuple[ndarray, ...] –

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

• tuple[Tensor, ...] | tuple[ndarray, ...] –

  the same order. All arrays use the same ecosystem as the inputs and,

• tuple[Tensor, ...] | tuple[ndarray, ...] –

  for Torch, the same device. If n_edges pairs are found:

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

  source and target.

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

  the target image.

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

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

• tuple[Tensor, ...] | tuple[ndarray, ...] –

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

• tuple[Tensor, ...] | 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; array arguments mix PyTorch and NumPy or use an unsupported container type; or a boolean option is not a Python bool.

• ValueError –

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

• RuntimeError –

  If the required native CPU or CUDA 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 torch
>>> from elfes.physics import neighbor_list
>>> positions = torch.tensor([[0.0, 0.0, 0.0], [0.8, 0.0, 0.0]])
>>> cell = torch.eye(3) * 4.0
>>> pbc = torch.tensor([False, False, False])
>>> pairs, shifts, distances = neighbor_list(
...     "PSd", positions, cell, pbc, cutoff=1.0
... )
>>> pairs.shape, shifts.shape, distances.tolist()
(torch.Size([2, 2]), torch.Size([2, 3]), [0.800000011920929, 0.800000011920929])

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

  (Tensor | NDArray[float64]) –

  Cartesian vectors with shape (..., 3). NumPy inputs must use dtype float64. Torch inputs may be on CPU or CUDA and must use dtype float32 or float64.

Returns:

• Tensor | NDArray[float64] –

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

• Tensor | NDArray[float64] –

  same array ecosystem, floating dtype and, for Torch, device as

• Tensor | NDArray[float64] –

  vectors. Torch results support reverse-mode differentiation through

• Tensor | NDArray[float64] –

  second derivatives.

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

  (Tensor | NDArray[float64]) –

  Nonzero Cartesian directions with shape (..., 3). NumPy inputs must use dtype float64. Torch inputs may be on CPU or CUDA and must use dtype float32 or float64.

Returns:

• Tensor | NDArray[float64] –

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

• Tensor | NDArray[float64] –

  array ecosystem, floating dtype and, for Torch, device as directions.

• Tensor | NDArray[float64] –

  Torch results support reverse-mode differentiation through second

• Tensor | NDArray[float64] –

  derivatives.

Return 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. For an improper transformation, inversion is separated from a proper rotation and contributes the natural parity (-1)**l.

Parameters:

• l_max

  (int) –

  Highest non-negative angular quantum number.

• rotation

  (ArrayLike) –

  Orthogonal Cartesian matrix with shape (3, 3) acting on column vectors.

Returns:

• NDArray[float64] –

  Tuple indexed by l containing matrices with shape

• ... –

  (2 * l + 1, 2 * l + 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.