Skip to content

Bloch transforms and eigensolvers

Orbital Hamiltonians and overlaps may be stored as atom-pair blocks indexed by cell shift. A Bloch transform combines those blocks at a chosen k-point, producing the dense matrices needed for the generalized eigenproblem. Dense matrices can also be solved directly when no transform is needed.

The eigensolvers support spinless and Pauli-decomposed Hamiltonians. K-points use fractional coordinates, and the transform follows the ELFES phase convention stated in the function reference. See Periodic Systems for the underlying Bloch description.

Bloch transforms

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.

Generalized eigenproblems

The direct solver takes dense Hamiltonian and overlap matrices; the combined solver first transforms cell-shift-indexed matrices.

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.

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.