Skip to content

Numerical basis calculations

Numerical basis calculations use tabulated radial functions together with atom positions and boundary conditions. Grid calculators integrate sampled functions against a basis or expand basis coefficients on a uniform grid. Overlap calculators evaluate the ordinary inner products of basis functions.

The calculators retain preparation that can be reused: grid calculations are bound to one geometry/grid or an ordered batch, while overlap calculations share basis-dependent preparation across geometries. Both spline and uniform radial representations follow the atom-centered basis definitions.

Grid integration and expansion

Both calculator classes accept either (geometry, basis_set, grid) or (geometries, basis_set, grids). In batch mode, expand(coeffs_list) and integrate(volumetrics) return lists in the same order; a one-element sequence remains a batch. Prepared radial data is shared and per-structure traversal plans are reused. cpu_threads is the total budget per call: within a structure in single mode, across structures in batch mode. All native grid calculations use FP64 and have no Torch autograd path.

calculator = UniformNumericalBasisGridCalculator(
    geometries, basis_set, grids, cpu_threads=8,
)
densities = calculator.expand(coeffs_list)

Basis integrals from grid integration can be passed to the density projection solver.

SplineNumericalBasisGridCalculator

SplineNumericalBasisGridCalculator(
    geometry: Geometry | Sequence[Geometry],
    basis_set: SplineNumericalBasisSet,
    grid: UniformGrid | Sequence[UniformGrid],
    *,
    cpu_threads: int = 1,
)

Bases: _NumericalBasisGridCalculatorBase

Reusable spline-basis integration and expansion for one or many structures.

Parameters:

  • geometry (Geometry | Sequence[Geometry]) –

    One Geometry or a nonempty sequence of independent geometries.

  • basis_set (SplineNumericalBasisSet) –

    Shared spline numerical basis.

  • grid (UniformGrid | Sequence[UniformGrid]) –

    One UniformGrid or a matching sequence of grids.

  • cpu_threads (int, default: 1 ) –

    Total CPU thread budget per call. Single mode parallelizes within a structure; batch mode runs structures concurrently with one native worker each. Different structures share prepared radial data.

integrate

integrate(volumetric: UniformVolumetric) -> OrbVector
integrate(volumetric: Sequence[UniformVolumetric]) -> list[OrbVector]
integrate(volumetric)

Integrate grid values against the basis, preserving Pauli/extra axes.

Single mode takes and returns one physical object. Batch mode requires a sequence matching the bound geometries and returns a list in that order. The real-space volume element is included in each integral.

expand

expand(coeffs: OrbVector) -> UniformVolumetric
expand(coeffs: Sequence[OrbVector]) -> list[UniformVolumetric]
expand(coeffs)

Evaluate real coefficients on the bound grids in FP64.

Single mode takes an OrbVector and returns UniformVolumetric. Batch mode takes a sequence and returns a list, including a one-element batch. Different structures may have different grids and orbital counts. Calls reuse the prepared basis and geometric traversal plans, not basis-on-grid matrices. This NumPy/native calculation does not provide autograd.

UniformNumericalBasisGridCalculator

UniformNumericalBasisGridCalculator(
    geometry: Geometry | Sequence[Geometry],
    basis_set: UniformNumericalBasisSet,
    grid: UniformGrid | Sequence[UniformGrid],
    *,
    cpu_threads: int = 1,
)

Bases: _NumericalBasisGridCalculatorBase

Reusable uniform-radial-basis calculation on one or many spatial grids.

Radial values and local-Hermite tangents are prepared once and shared across the batch. Each geometry owns its periodic-image plan and scratch workspace.

Parameters:

  • geometry (Geometry | Sequence[Geometry]) –

    One Geometry or a nonempty sequence of independent geometries.

  • basis_set (UniformNumericalBasisSet) –

    Shared uniform numerical basis.

  • grid (UniformGrid | Sequence[UniformGrid]) –

    One UniformGrid or a matching sequence of grids.

  • cpu_threads (int, default: 1 ) –

    Total CPU thread budget per call. Batch mode parallelizes across structures; single mode parallelizes within one structure.

integrate

integrate(volumetric: UniformVolumetric) -> OrbVector
integrate(volumetric: Sequence[UniformVolumetric]) -> list[OrbVector]
integrate(volumetric)

Integrate grid values against the basis, preserving Pauli/extra axes.

Single mode takes and returns one physical object. Batch mode requires a sequence matching the bound geometries and returns a list in that order. The real-space volume element is included in each integral.

expand

expand(coeffs: OrbVector) -> UniformVolumetric
expand(coeffs: Sequence[OrbVector]) -> list[UniformVolumetric]
expand(coeffs)

Evaluate real coefficients on the bound grids in FP64.

Single mode takes an OrbVector and returns UniformVolumetric. Batch mode takes a sequence and returns a list, including a one-element batch. Different structures may have different grids and orbital counts. Calls reuse the prepared basis and geometric traversal plans, not basis-on-grid matrices. This NumPy/native calculation does not provide autograd.

Overlap integrals

SplineNumericalOverlapParameters dataclass

SplineNumericalOverlapParameters(
    *,
    k_cutoff: float = 120.0,
    k_spacing: float = 0.04,
    distance_spacing: float = 0.005,
    radial_quadrature_order: int = 8,
)

Resolution parameters for spline numerical overlap preparation.

Lengths use Å and reciprocal lengths use Å\(^{-1}\).

SplineNumericalOverlapCalculator

SplineNumericalOverlapCalculator(
    basis_set: SplineNumericalBasisSet,
    parameters: SplineNumericalOverlapParameters | None = None,
    *,
    cpu_threads: int = 1,
)

Bases: _NumericalOverlapCalculatorBase

Calculate ordinary overlaps for geometries sharing one spline numerical basis.

Construction copies the spline numerical atomic bases into the native kernel. Radial transforms and two-center distance tables are prepared lazily for species and species pairs encountered by later calculations, then reused by the calculator. cpu_threads controls native neighbor search and warm block evaluation within one call; it defaults to one.

calculate

calculate(geometry: Geometry) -> HermBlockSparseOrbMatrix

Return the overlap matrix for one geometry.

calculate_gamma

calculate_gamma(geometry: Geometry) -> HermOrbMatrix

Return the real dense Γ-folded overlap for one geometry.

UniformNumericalOverlapCalculator

UniformNumericalOverlapCalculator(
    basis_set: UniformNumericalBasisSet,
    *,
    cpu_threads: int = 1,
    distance_spacing: float | None = None,
    table_dtype: DTypeLike = float64,
    compute_dtype: DTypeLike = float64,
)

Bases: _NumericalOverlapCalculatorBase

Calculate overlaps from uniform radial samples without source splines.

cpu_threads controls native neighbor search and warm block evaluation within one call; it defaults to one. distance_spacing defaults to the source radial spacing; a coarser spacing must be an integer multiple and divide every shell-pair cutoff. table_dtype controls storage only. compute_dtype selects FP32/FP64 interpolation, contraction and accumulation for overlap values, independently of table and output dtype. Geometry, angular preparation, table construction and analytic gradients remain FP64. Cholesky factors the computed overlap using FP64 LAPACK.

calculate

calculate(geometry: Geometry) -> HermBlockSparseOrbMatrix

Return the overlap matrix for one geometry.

calculate_gamma

calculate_gamma(geometry: Geometry) -> HermOrbMatrix

Return the real dense Γ-folded overlap for one geometry.

prepare_tables

prepare_tables() -> UniformNumericalOverlapTables

Prepare all unordered species pairs and expose their arrays without copying.

from_tables classmethod

from_tables(
    tables: UniformNumericalOverlapTables,
    *,
    cpu_threads: int = 1,
    compute_dtype: DTypeLike = float64,
) -> UniformNumericalOverlapCalculator

Use tables without refitting; compute_dtype is independent of storage.

calculate_basis_connection

calculate_basis_connection(geometry: Geometry) -> BlockSparseOrbMatrix

Return the ket-side basis connection in Å\(^{-1}\).

For ket-cell displacement \(\boldsymbol d=\boldsymbol\tau_j+\boldsymbol R-\boldsymbol\tau_i\), the Cartesian components are \(\langle\phi_{i\boldsymbol0}|\partial_{\tau_{j\alpha}} \phi_{j\boldsymbol R}\rangle=\partial_{d_\alpha}S_{ij}(\boldsymbol d)\). Every directed partner block is stored explicitly.

Prepared overlap tables

Prepared tables can be saved and loaded through elfes.io.basis; they retain the distance grid, shell layout and FP32/FP64 arrays needed by UniformNumericalOverlapCalculator.from_tables().

UniformNumericalOverlapTables dataclass

UniformNumericalOverlapTables(
    basis_layout: BasisSet,
    cutoffs: NDArray[float64],
    distance_spacing: float,
    pairs: dict[tuple[int, int], tuple[ndarray, ndarray]],
)

Prepared distance tables, independent of geometry and source radial functions.

cutoffs contains one radius in Å per shell in basis_layout order. pairs[(Z1, Z2)] contains values and spline second derivatives, both contiguous FP32 or FP64 arrays of shape [channels, distance_points]. Only Z1 <= Z2 pairs are stored. Channels follow bra shell, ket shell, then L = abs(l1-l2), ..., l1+l2 in steps of two; for equal species, only bra shell <= ket shell is stored. Shorter-cutoff rows are zero padded. The grid starts at zero. Arrays remain owned by this object or their native builder; loading a calculator uses their storage directly.