Skip to content

elfes.physics.calc

Sample-level CPU/NumPy physical calculations.

SplineNumericalBasisGridCalculator 

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

Bases: _NumericalBasisGridCalculatorBase

Reusable spline numerical basis calculator bound to one geometry and grid.

Construction prepares the complete cutoff-local traversal plan and one spherical-harmonic workspace per CPU thread. Reuse the calculator when both integration and expansion use the same geometry, basis, and grid. Calls on one calculator are serialized because its compiled workspaces own reusable scratch memory.

Parameters:

  • geometry

    (Geometry) –

    Atom positions and periodic cell used by the basis functions.

  • basis_set

    (SplineNumericalBasisSet) –

    Spline numerical basis evaluated on the grid.

  • grid

    (UniformGrid) –

    Uniform grid on which values are integrated or expanded.

  • cpu_threads

    (int, default: 1 ) –

    Threads used inside the fused grid calculation.

integrate 

integrate(volumetric: UniformVolumetric) -> OrbVector

Integrate values on the bound grid against the numerical basis.

expand 

expand(coeffs: OrbVector) -> UniformVolumetric

Evaluate auxiliary coefficients on the bound grid.

UniformNumericalBasisGridCalculator 

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

Bases: _NumericalBasisGridCalculatorBase

Numerical-basis grid calculator using uniform radial samples directly.

The native kernel derives the radial interval by integer indexing and uses precomputed local-Hermite tangents. It does not copy radial-grid arrays or global spline coefficients.

integrate 

integrate(volumetric: UniformVolumetric) -> OrbVector

Integrate values on the bound grid against the numerical basis.

expand 

expand(coeffs: OrbVector) -> UniformVolumetric

Evaluate auxiliary coefficients on the bound grid.

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.

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

UniformNumericalOverlapCalculator 

UniformNumericalOverlapCalculator(
    basis_set: UniformNumericalBasisSet, *, cpu_threads: int = 1
)

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.

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.

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.

UniformNumericalSpinOrbitCalculator 

UniformNumericalSpinOrbitCalculator(
    basis_set: UniformNumericalBasisSet,
    potential_set: UniformNumericalSpinOrbitPotentialSet,
    *,
    cpu_threads: int = 1,
)

Calculate the fixed spin-orbit Hamiltonian for one numerical basis.

Species-level radial transforms and two-center AO--projector tables are prepared lazily and reused. Each geometry is evaluated as finite-cutoff AO--projector overlaps followed by projector-centered sparse contractions. cpu_threads controls native neighbor search, overlap evaluation, and contraction; it defaults to one.

calculate 

calculate(geometry: Geometry) -> HermBlockSparseOrbMatrix

Return fixed Pauli \(x,y,z\) SOC blocks in eV.

UniformNumericalSpinOrbitPotential dataclass 

UniformNumericalSpinOrbitPotential(
    projectors: UniformNumericalAtomicBasis, d_so: HermOrbMatrix
)

Separable spin-orbit potential for one species.

projectors is the ordered KB-projector family. d_so stores its spin-traceless nonlocal coefficient matrix in eV, expanded as Pauli \(x,y,z\) components over the projector axes. In the real-projector convention used here, every component of d_so is purely imaginary and Hermitian.

Parameters:

  • projectors

    (UniformNumericalAtomicBasis) –

    Uniform numerical KB projectors for one species.

  • d_so

    (HermOrbMatrix) –

    Projector-space \(D^{\mathrm{SO}}\) in eV, with one atomic orbital partition and pauli="xyz".

UniformNumericalSpinOrbitPotentialSet dataclass 

UniformNumericalSpinOrbitPotentialSet(
    atomic_potentials: tuple[UniformNumericalSpinOrbitPotential, ...]
    | list[UniformNumericalSpinOrbitPotential],
)

Uniform numerical spin-orbit potentials keyed by atomic number.

projectors is the role-neutral basis set assembled from each atomic potential's projector family.

atomic_potential 

atomic_potential(atomic_number: int) -> UniformNumericalSpinOrbitPotential

Return the potential for one atomic number.

calculate_aux_coeffs 

calculate_aux_coeffs(
    aux_overlap: HermOrbMatrix,
    basis_integrals: OrbVector,
    *,
    solver: Literal["cholesky", "pseudoinverse"] = "cholesky",
    rank_rtol: float = 1e-12,
) -> OrbVector

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.

bloch_transform 

bloch_transform(
    matrix_r: HermBlockSparseOrbMatrix, kpoints: ArrayLike, *, cpu_threads: int = 1
) -> HermOrbMatrix

bloch_transform(
    matrix_r: BlockSparseOrbMatrix, kpoints: ArrayLike, *, cpu_threads: int = 1
) -> OrbMatrix

bloch_transform(
    matrix_r: BlockSparseOrbMatrix | HermBlockSparseOrbMatrix,
    kpoints: ArrayLike,
    *,
    cpu_threads: int = 1,
) -> OrbMatrix | HermOrbMatrix

Transform \(X(R)\) to Bloch matrices at fractional k-points.

The integer ket-cell shifts use the ELFES forward phase exp(+2πi k·R). A single (3,) k-point returns one matrix. An (n_kpoints, 3) batch returns matrices with n_kpoints as the first axis. cpu_threads controls native OpenMP parallelism; internal BLAS calls remain single-threaded to avoid nested parallelism.

bloch_transform_gamma 

bloch_transform_gamma(matrix_r: HermBlockSparseOrbMatrix) -> HermOrbMatrix

bloch_transform_gamma(matrix_r: BlockSparseOrbMatrix) -> OrbMatrix

bloch_transform_gamma(
    matrix_r: BlockSparseOrbMatrix | HermBlockSparseOrbMatrix,
) -> OrbMatrix | HermOrbMatrix

Transform X(R) at Γ without allocating complex phases.

solve_bloch_eigen 

solve_bloch_eigen(
    hamiltonian_r: HermBlockSparseOrbMatrix,
    overlap_r: HermBlockSparseOrbMatrix,
    kpoints: ArrayLike,
    *,
    eigvals_only: Literal[True],
    cpu_threads: int = 1,
) -> NDArray

solve_bloch_eigen(
    hamiltonian_r: HermBlockSparseOrbMatrix,
    overlap_r: HermBlockSparseOrbMatrix,
    kpoints: ArrayLike,
    *,
    eigvals_only: Literal[False] = False,
    cpu_threads: int = 1,
) -> tuple[NDArray, NDArray]

solve_bloch_eigen(
    hamiltonian_r: HermBlockSparseOrbMatrix,
    overlap_r: HermBlockSparseOrbMatrix,
    kpoints: ArrayLike,
    *,
    eigvals_only: bool = False,
    cpu_threads: int = 1,
) -> NDArray | tuple[NDArray, NDArray]

Bloch-transform \(H(R)\) and \(S(R)\), then solve their eigenproblem.

A single (3,) fractional k-point returns one eigensystem. An (n_kpoints, 3) batch preserves n_kpoints as the first output axis. cpu_threads controls native Bloch-transform parallelism and the subsequent BLAS/LAPACK solve within the same sequential CPU budget.

Parameters:

  • hamiltonian_r

    (HermBlockSparseOrbMatrix) –

    Cell-shift-indexed Hermitian Hamiltonian.

  • overlap_r

    (HermBlockSparseOrbMatrix) –

    Cell-shift-indexed spinless Hermitian overlap matrix.

  • kpoints

    (ArrayLike) –

    One fractional k-point or a batch with shape (n_kpoints, 3).

  • eigvals_only

    (bool, default: False ) –

    Return only eigenvalues when True; otherwise return (eigenvalues, eigenvectors).

  • cpu_threads

    (int, default: 1 ) –

    CPU threads used during each transform and solve stage.

solve_eigen 

solve_eigen(
    hamiltonian_k: HermOrbMatrix,
    overlap_k: HermOrbMatrix,
    *,
    eigvals_only: Literal[True],
    cpu_threads: int = 1,
) -> NDArray

solve_eigen(
    hamiltonian_k: HermOrbMatrix,
    overlap_k: HermOrbMatrix,
    *,
    eigvals_only: Literal[False] = False,
    cpu_threads: int = 1,
) -> tuple[NDArray, NDArray]

solve_eigen(
    hamiltonian_k: HermOrbMatrix,
    overlap_k: HermOrbMatrix,
    *,
    eigvals_only: bool = False,
    cpu_threads: int = 1,
) -> NDArray | tuple[NDArray, NDArray]

Solve \(\mathbf H\mathbf C=\mathbf S\mathbf C\mathbf E\).

The inputs are dense matrices already Bloch-transformed at the requested k-points. Their leading batch dimensions are preserved. Eigenvalues are ascending along the final axis and use the Hamiltonian's energy unit. Eigenvectors are columns of the returned final two axes and satisfy \(\mathbf C^\dagger\mathbf S\mathbf C=\mathbf I\).

A spinless Hamiltonian returns n_orb states. A Hamiltonian carrying Pauli components returns 2 * n_orb states in an explicit basis ordered as (orb_0 up, orb_0 down, orb_1 up, orb_1 down, ...). Scalar and collinear Pauli Hamiltonians are solved as one or two spatial problems instead of forming a doubled dense spin matrix.

Parameters:

  • hamiltonian_k

    (HermOrbMatrix) –

    Dense spinless or Pauli-component Hamiltonian at the requested k-points.

  • overlap_k

    (HermOrbMatrix) –

    Dense spinless positive-definite overlap matrix at the requested k-points.

  • eigvals_only

    (bool, default: False ) –

    Return only eigenvalues when True; otherwise return (eigenvalues, eigenvectors).

  • cpu_threads

    (int, default: 1 ) –

    BLAS/LAPACK threads used during this call.