Skip to content

Orbital quantities

Orbital quantities carry values indexed by atom-centered basis functions. A vector has one orbital axis and a matrix has two; each axis is partitioned by atom. Additional axes can carry other components, including Pauli components for spinful quantities.

Dense matrices store the complete orbital array. Block-sparse matrices store selected atom-pair blocks together with ket-cell shifts, making the same representation usable for finite and periodic systems. Hermitian forms encode the relation between a matrix element and its conjugate partner.

Orbital vectors

OrbVector dataclass 

OrbVector(array: ArrayLike, orb_counts: ArrayLike, pauli: str | None = None)

Dense array with one atom-partitioned orbital axis.

Arbitrary leading dimensions are preserved. The final dimension is the concatenation of the atom-centered basis functions described by orb_counts. When pauli is present, its component axis is immediately before the orbital axis.

Parameters:

  • array (ArrayLike) –

    Numeric array with shape (*extra_shape, n_orb).

  • orb_counts (ArrayLike) –

    Number of basis functions on every atom with shape (n_atoms,).

  • pauli (str | None, default: None ) –

    None for values without Pauli semantics, otherwise a non-empty ordered subset of "0xyz" naming the final leading component axis.

subvector 

subvector(atom_i: int) -> NDArray

Return the orbital subvector for one atom.

rotated 

rotated(
    spatial_rotation: ArrayLike,
    basis_set: BasisSet,
    atomic_numbers: ArrayLike,
    *,
    spin_rotation: bool | ArrayLike = False,
) -> OrbVector

Return values after actively rotating the spatial system.

The final orbital axis rotates by spatial_rotation. spin_rotation leaves Pauli components fixed when False, follows the spatial system as an axial vector when True, or applies an explicit proper spin rotation. Any earlier batch dimensions are preserved.

Dense matrices

The general, Hermitian, and upper-triangular forms express different matrix structures while sharing atom-partitioned orbital axes.

OrbMatrix dataclass 

OrbMatrix(array: ArrayLike, orb_counts: ArrayLike, pauli: str | None = None)

General dense array with two atom-partitioned orbital axes.

Arbitrary leading dimensions are preserved. When pauli is present, its component axis is immediately before the two orbital axes.

Parameters:

  • array (ArrayLike) –

    Numeric array with shape (*extra_shape, n_orb, n_orb).

  • orb_counts (ArrayLike) –

    Number of basis functions on every atom with shape (n_atoms,).

  • pauli (str | None, default: None ) –

    None for spinless values, otherwise a non-empty ordered subset of "0xyz" naming the final leading component axis.

submatrix 

submatrix(atom_i: int, atom_j: int) -> NDArray

Return the orbital submatrix for one atom pair.

HermOrbMatrix 

HermOrbMatrix(array: ArrayLike, orb_counts: ArrayLike, pauli: str | None = None)

Bases: OrbMatrix

Dense Hermitian matrix with two atom-partitioned orbital axes.

submatrix 

submatrix(atom_i: int, atom_j: int) -> NDArray

Return the orbital submatrix for one atom pair.

rotated 

rotated(
    spatial_rotation: ArrayLike,
    basis_set: BasisSet,
    atomic_numbers: ArrayLike,
    *,
    spin_rotation: bool | ArrayLike = False,
) -> HermOrbMatrix

Return the Hermitian matrix after actively rotating the spatial system.

Both orbital axes rotate by spatial_rotation. spin_rotation leaves Pauli components fixed when False, follows the spatial system as an axial vector when True, or applies an explicit proper spin rotation. Any earlier batch dimensions are preserved.

TriuOrbMatrix 

TriuOrbMatrix(array: ArrayLike, orb_counts: ArrayLike, pauli: str | None = None)

Bases: OrbMatrix

Dense upper-triangular matrix with atom-partitioned orbital axes.

submatrix 

submatrix(atom_i: int, atom_j: int) -> NDArray

Return the orbital submatrix for one atom pair.

Atom-pair blocks

General blocks are directed. The Hermitian form stores one member of each conjugate pair; absent blocks represent zero. Bloch transforms convert cell-shift-indexed matrices into dense matrices at chosen k-points.

BlockSparseOrbMatrix dataclass 

BlockSparseOrbMatrix(
    atom_pairs: ArrayLike,
    pair_shifts: ArrayLike,
    orb_counts: ArrayLike,
    values: ArrayLike,
    pauli: str | None = None,
)

Bases: _BlockSparseOrbMatrixBase

General cell-shift-indexed atom-pair orbital matrix.

atom_pairs[n] = (i, j) identifies the bra and ket basis centers of block n. pair_shifts[n] selects the cell image of the ket center. Stored block keys are sorted and unique; every stored block is an actual directed block, and a missing key represents zero. No relation between a key and its reverse-cell partner is implied.

Spatial matrix elements are flattened along the leading axis of values, whose shape is (n_values, *extra_shape). block(n) restores the shape (*extra_shape, n_orb_i, n_orb_j). When pauli is present, its component axis is the final axis of extra_shape.

from_blocks classmethod 

from_blocks(
    atom_pairs: ArrayLike,
    blocks: Iterable[ArrayLike],
    orb_counts: ArrayLike,
    *,
    pair_shifts: ArrayLike | None = None,
    pauli: str | None = None,
) -> Self

Pack blocks aligned with atom-pair and optional cell-shift rows.

Input rows may be unordered; they and their corresponding blocks are sorted lexicographically before storage. Every block has shape (*extra_shape, n_orb_i, n_orb_j), with one shared extra_shape.

block 

block(block_idx: int) -> NDArray

Return one stored block with shape (*extra_shape, n_i, n_j).

to_dense 

to_dense() -> OrbMatrix

Return an all-zero-shift matrix in global orbital order.

HermBlockSparseOrbMatrix 

HermBlockSparseOrbMatrix(
    atom_pairs: ArrayLike,
    pair_shifts: ArrayLike,
    orb_counts: ArrayLike,
    values: ArrayLike,
    pauli: str | None = None,
)

Bases: _BlockSparseOrbMatrixBase

Hermitian cell-shift-indexed atom-pair orbital matrix.

Only the lexicographically first key in each Hermitian-partner pair is stored; the other block is its conjugate transpose. Missing partner pairs contribute zero matrix elements. Onsite blocks are exactly Hermitian.

Spatial matrix elements are flattened along the leading axis of values, whose shape is (n_values, *extra_shape). block(n) restores the shape (*extra_shape, n_orb_i, n_orb_j). When pauli is present, its component axis is the final axis of extra_shape.

from_blocks classmethod 

from_blocks(
    atom_pairs: ArrayLike,
    blocks: Iterable[ArrayLike],
    orb_counts: ArrayLike,
    *,
    pair_shifts: ArrayLike | None = None,
    pauli: str | None = None,
) -> Self

Pack blocks aligned with atom-pair and optional cell-shift rows.

Input rows may be unordered; they and their corresponding blocks are sorted lexicographically before storage. Every block has shape (*extra_shape, n_orb_i, n_orb_j), with one shared extra_shape.

block 

block(block_idx: int) -> NDArray

Return one stored block with shape (*extra_shape, n_i, n_j).

rotated 

rotated(
    spatial_rotation: ArrayLike,
    basis_set: BasisSet,
    atomic_numbers: ArrayLike,
    *,
    spin_rotation: bool | ArrayLike = False,
) -> HermBlockSparseOrbMatrix

Return the matrix after actively rotating the spatial system.

Both orbital axes rotate by spatial_rotation. spin_rotation leaves Pauli components fixed when False, follows the spatial system as an axial vector when True, or applies an explicit proper spin rotation. Pair shifts, other leading dimensions, and block ordering are preserved.

to_dense 

to_dense() -> HermOrbMatrix

Return an all-zero-shift matrix in global orbital order.