Orbital data preparation
Orbital models may need an explicit set of matrix blocks to predict, or an overlap matrix for a physical loss. These operations prepare such data for an existing batch. Output atom pairs are selected from geometry and basis cutoffs independently of the model's connectivity.
Output atom pairs and label alignment
add_basis_atom_pairs(batch, basis_set) independently generates output requests from geometry and complete numerical-basis cutoffs. It attaches top-level atom_pair_index and pair_shifts, retaining onsite and Hermitian-half pairs within the sum of the two atomic radii. It never reads labels or connectivity. reindex_herm_block_sparse() aligns Hermitian matrix labels to those keys, conjugate-transposes reverse partners, fills absent partner pairs with zeros, and recomputes packed counts. The basis-radius rule is an output truncation choice rather than an exact sparsity theorem for every operator.
The top-level batch.atom_pair_index and batch.pair_shifts describe requested outputs. A reference matrix keeps its own block keys inside batch.physical_data[name] until it is explicitly aligned to those requests.
add_basis_atom_pairs
add_basis_atom_pairs(batch: Batch, basis_set: BasisSet) -> Batch
Attach Hermitian-half atom pairs within the sum of numerical-basis radii.
Each atomic radius is the largest shell cutoff in Å. Include all onsite
blocks and pairs satisfying distance < radius_i + radius_j, retaining
the lexicographically first (i, j, S) of each Hermitian partner pair.
This is an explicit output truncation rule, not a claim that every
Hamiltonian vanishes outside these distances.
Only geometry (pos, cell, pbc, atomic_numbers, ptr) is read.
Attach atom_pair_index: [2, P] and pair_shifts: [P, 3], grouped by
sample, on the input device. Labels and model connectivity are untouched.
A layout-only or Gaussian basis cannot supply finite numerical cutoffs.
reindex_herm_block_sparse
reindex_herm_block_sparse(
data: BlockSparseOrbData,
atom_pair_index: Tensor,
pair_shifts: Tensor,
orb_counts: Tensor,
ptr: Tensor,
) -> BlockSparseOrbData
Gather requested blocks, conjugate-transposing partners and filling zeros.
data stores unique lexicographically first Hermitian partner keys, as
returned for an ELFES Hermitian block-sparse matrix. Missing partner pairs
denote zeros. Requested keys may use either direction, in arbitrary order
within each sample; samples must remain grouped in batch order. All atom
indices are batch-global. orb_counts: [N] gives the spatial block shapes
and ptr: [B+1] partitions the atoms. Real/imaginary extra axes are retained.
Returns values in exactly the requested order with recomputed block/value counts. Supports CPU/CUDA and gradients with respect to stored values.
Numerical-basis overlaps
add_nao_overlap() may similarly calculate numerical-basis overlap for an already collated CPU Batch. It passes the batch's packed atom arrays through a Spline or Uniform calculator's internal batch execution and attaches the result as BlockSparseOrbData. When a consumer only needs Γ, add_nao_gamma_overlap() attaches its OrbData(values_real, num_values) representation; add_nao_cholesky() directly attaches the packed upper factor. Temporary NumPy batch arrays remain an internal bridge rather than a parallel public matrix hierarchy, and the physics and native modules do not depend on PyG.
These helpers attach entries to batch.physical_data under the requested name and require a CPU batch. The reusable calculators and their basis requirements are documented under Numerical basis calculations. The Γ overlap and Cholesky forms connect to the quadratic orbital-vector losses.
add_nao_overlap
add_nao_overlap(
batch: Batch,
calculator: SplineNumericalOverlapCalculator | UniformNumericalOverlapCalculator,
*,
name: str = "overlap",
) -> Batch
Calculate and attach numerical-basis overlap to a CPU PyG batch.
add_nao_gamma_overlap
add_nao_gamma_overlap(
batch: Batch,
calculator: SplineNumericalOverlapCalculator | UniformNumericalOverlapCalculator,
*,
name: str = "overlap",
) -> Batch
Calculate and attach packed real Γ overlap to a CPU PyG batch.
add_nao_cholesky
add_nao_cholesky(
batch: Batch,
calculator: SplineNumericalOverlapCalculator | UniformNumericalOverlapCalculator,
*,
name: str = "cholesky",
) -> Batch
Calculate and attach packed upper Cholesky factors to a CPU PyG batch.
Numerical-basis grid expansion
NumericalBasisGridExpansion binds a CPU batch and uniform-grid metadata, then expands packed coefficient predictions repeatedly. It preserves structure order and extra/Pauli axes while translating between packed Torch data and physics objects. Use geometry_dtype=torch.float64 when loading geometry and grid coordinates for periodic native calculations; coefficient and reference values remain FP32. Detach predictions and transfer them to CPU explicitly before calling expand().
expansion = NumericalBasisGridExpansion(
cpu_batch, basis_set, cpu_batch["physical_data"]["density"], cpu_threads=8,
)
predicted_density = expansion.expand(cpu_coeffs, pauli="0")
Returned values_real is FP64. The adapter keeps prepared calculation plans and grid metadata, but not reference density values. Baseline composition and the lifetime of cached expansion objects belong to the caller. The underlying calculators are described under Numerical basis calculations.
NumericalBasisGridExpansion
NumericalBasisGridExpansion(
batch: Batch,
basis_set: SplineNumericalBasisSet | UniformNumericalBasisSet,
grid: UniformVolumetricData,
*,
cpu_threads: int = 1,
)
Bind a CPU PyG batch and its grids for repeated coefficient expansion.
The batch supplies atomic_numbers, pos, cell, pbc and ptr.
Load geometry/grid coordinates in float64 for periodic native calculations
(HDF5Dataset(..., geometry_dtype=torch.float64)). Physical coefficients may
remain float32. This object keeps grid metadata, not reference grid values.
Parameters:
-
batch(Batch) –CPU batch, in the same structure order as
gridand coefficients. -
basis_set(SplineNumericalBasisSet | UniformNumericalBasisSet) –Shared numerical basis determining the orbital order.
-
grid(UniformVolumetricData) –Packed uniform-grid metadata; reference values are not consumed.
-
cpu_threads(int, default:1) –Total thread budget for the batch.
expand
expand(coeffs: OrbData, *, pauli: str | None = None) -> UniformVolumetricData
Expand detached real CPU coefficients, returning packed FP64 values.
Coefficient layout is [sum(n_orb), *extra_shape]; returned values use
[sum(n_grid_points), *extra_shape]. Pauli, when supplied, is the last
extra axis. There is no autograd path through the native computation.