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.