Components

AbstractSource

Abstract supertype for format sources. Concrete subtypes (e.g. CanonicalSource, DeepHSource, FHIaimsSource) carry format-specific configuration such as the default SH convention and data layout. Used to dispatch format-specific methods throughout the pipeline.

namedtuple(source::AbstractSource)

Convert a source's fields to a NamedTuple. Useful for forwarding source properties as keyword arguments.

OperatorKind{K}

Identifies an operator by its kind symbol K (e.g. :Hamiltonian, :Overlap) and a set of tags stored in an unordered dictionary. Tags are key-value pairs of Symbols that distinguish variants — for example source=:ref or spin=:up. Tag order does not affect equality.

Convenience aliases: Hamiltonian = OperatorKind{:Hamiltonian}, Overlap = OperatorKind{:Overlap}.

Examples

kind = Hamiltonian(; source=:ref)          # reference Hamiltonian
kind = Hamiltonian(; source=:pred, spin=:soc)  # predicted SOC Hamiltonian

allows_symmetry(operatorkinds)
allows_symmetry(operatorkind::OperatorKind)

Check whether k-point symmetry reduction is valid. Returns false if any operator has a non-trivial spin tag (:up, :down, :soc), since spin-polarised operators generally break the spatial symmetry used for k-point reduction.

get_operator_groups(op_list; op_filter=op->true, excluded_keys=nothing)

Group a list of OperatorKinds by tag equality. Returns a vector of vectors, where each inner vector contains kinds that share identical tags (after filtering). Use op_filter to restrict which kinds are considered and excluded_keys to ignore specific tags during grouping.

get_tags(kind; excluded_keys=nothing)

Return the tag dictionary of an OperatorKind. If excluded_keys is provided, those keys are filtered out from the result.

statictuple(kind::OperatorKind)

Convert an OperatorKind into a tuple of Val-wrapped symbols, sorted by tag key. Used for type-stable dispatch on operator kind in format-specific methods (e.g. file name lookup).

SHConvention{lmax,T}

Spherical harmonics ordering/phase convention, expressed as a transformation from the wiki (reference) ordering to a target format. For each angular momentum l, stores:

• orders — permutation vector mapping wiki index → format index.
• shifts — precomputed index shifts for applying the permutation to a full basis.
• phases — sign factors (±1) applied after reordering.

Two conventions can be composed with ∘ and inverted with inv. Use isidentity to check if a convention is a no-op.

shconv2 ∘ shconv1 -> SHConvention

Compose two SH conventions. The result applies shconv1 first, then shconv2. If the two conventions have different lmax, the lower value is used.

inv(shconv::SHConvention) -> SHConvention

Return the inverse convention (format → wiki), such that inv(c) ∘ c is the identity.

convert_speciesdict_shconv(dict, basis, shconv)

Return a deep copy of dict with per-species vectors permuted according to the SH convention. The in-place variant convert_speciesdict_shconv! modifies dict directly.

isidentity(shconv::SHConvention) -> Bool

Return true if the convention is a no-op (identity ordering with all-positive phases).

precompute_orders(basis, shconv) -> ImmutableDict

Precompute per-species permutation vectors for the full basis set under the given SH convention. Unlike get_order (which operates within a single angular-momentum subblock), these are global indices into the species' basis.

precompute_shifts(basis, shconv) -> ImmutableDict

Precompute per-species index shift vectors for applying the SH convention to a full basis set.

precompute_shphases(basis, shconv, Val(D)=Val(1), T=Float64)

Precompute per-species sign phase vectors (±1) for the SH convention. When D=1, returns a per-species dictionary of vectors. When D=2, returns a per-species-pair dictionary of outer-product phase matrices (used for matrix-valued data).

precompute_signed_perm_matrices(basis, shconv, T=Float64)

Compute per-species signed permutation matrices for the SH convention. An SH conversion of a matrix M_{z₁z₂} can be performed as P_{z₁} * M_{z₁z₂} * P_{z₂}ᵀ.

BasisMetadata{E}

Metadata for a single basis function: chemical species z, principal quantum number n, angular momentum l, magnetic quantum number m (always in wiki SH convention), and optional extras (e.g. degeneracy labels). Two BasisMetadata are equal if all fields match; they share_subblock if everything except m matches.

BasisSetMetadata{B,A}

A basis set. Contains a basis dictionary mapping each ChemicalSpecies to its vector of BasisMetadata entries, and an atom2species vector mapping atom indices to species.

convert_basisset_shconv(basisset, shconv) -> BasisSetMetadata

Reorder basis functions according to the spherical harmonics convention shconv. The input basis is assumed to be in the wiki (standard) convention.

get_angular_momenta(basis) -> Vector{Int}

Return the angular momentum l of each subblock's representative basis function.

get_atom2basis(basisset) -> Vector{UnitRange{Int}}

Return the global basis function index range for each atom.

get_atom2nbasis(basisset) -> Vector{Int}

Return the number of basis functions per atom.

get_atom2offset(basisset) -> Vector{Int}

Return the cumulative basis function offset for each atom (number of basis functions belonging to atoms with lower index).

get_basis2atom(basisset) -> Vector{Int}

Return the atom index for each global basis function index.

get_dense_subbasis_mask(basisset, subbasis; inverted=false) -> BitVector
get_dense_subbasis_mask(basisset, subbasis_masks) -> BitVector

Flatten per-species subbasis masks into a single BitVector over all atoms (following atom2species ordering), suitable for indexing into dense matrices.

get_indices_in_subblock(basisset::BasisSetMetadata)
get_indices_in_subblock(basis_z::AbstractVector{<:BasisMetadata})

Return the 1-based position of each basis function within its subblock. Unlike m, this reflects the actual ordering after SH convention reordering.

get_species2nbasis(basisset) -> ImmutableDict{ChemicalSpecies, Int}

Return the number of basis functions per chemical species.

get_subbasis_masks(basisset, subbasis; inverted=false) -> Dictionary{ChemicalSpecies, BitVector}

Compute per-species boolean masks indicating which basis functions belong to subbasis. If inverted=true, the masks select the complement (i.e. everything not in subbasis).

get_subblock_ranges(basisset::BasisSetMetadata)
get_subblock_ranges(basis_z::AbstractVector{<:BasisMetadata})

Return contiguous index ranges for each angular momentum subblock. The BasisSetMetadata form returns a Dictionary{ChemicalSpecies, Vector{UnitRange{Int}}}. It is assumed that all basis functions belonging to a sublock are next to each other.

is_arbitrary_degeneracy(basisset) -> Bool
is_arbitrary_degeneracy(basis_z) -> Bool

Check whether any species has multiple subblocks sharing the same (n, l) quantum numbers.

lift_arbitrary_degeneracy(basis)
lift_arbitrary_degeneracy(basis_z)

When multiple subblocks share the same (z, n, l) (arbitrary degeneracy), add a :dgen label to the extras field of each basis function to distinguish them.

reduce_basisset(basisset, subbasis; inverted=false) -> BasisSetMetadata
reduce_basisset(basisset, subbasis_masks) -> BasisSetMetadata

Return a new BasisSetMetadata containing only the basis functions selected by subbasis (a vector of BasisMetadata to keep). If inverted=true, keep the complement instead. The second form accepts precomputed per-species BitVector masks.

share_subblock(b1::BasisMetadata, b2::BasisMetadata) -> Bool

Return true if b1 and b2 belong to the same angular momentum subblock (same species, n, l, and extras — only m may differ).

Spin

Enum with values ⬆ (+1) and ⬇ (−1) representing spin-up and spin-down channels.

SpinsMetadata{S}

Per-species spin assignment for each basis function.

Fields:

• spins::S — species-keyed dictionary mapping each species to a vector of Spin values (one per basis function). For SOC, each species' vector is doubled.
• soc::Bool — true if this represents spin-orbit coupling (basis doubled per species).

SpinsMetadata(source, kind, basisset)

Construct SpinsMetadata from an operator kind's :spin tag. Dispatches on the spin tag value (:up, :down, :soc) to build the appropriate per-species spin vectors.

convert_spins_shconv(spins, basisset, shconv)

Reorder spin vectors to match a new SH convention, preserving the spin-basis correspondence.

convert_spins_source(in_spins, out_basisset, in_source, out_source)

Make final changes due to the source change (e.g. reorder up and down spins if the two sources don't agree). This often might leave the spins unchanged.

reduce_spins(spins, basisset, subbasis; inverted=false)

Restrict spin metadata to a sub-basis, keeping only the spin entries corresponding to the retained basis functions.

AbstractSparsity

Abstract supertype for all sparsity patterns. All concrete subtypes store a hermitian flag (accessible via op_hermicity) and, for real-space types, an images vector of lattice translation vectors.

build_sparsity(::Type{S}, atoms, radii; hermitian=false)

Build a sparsity pattern of type S from an atomic system and per-species interaction radii. Constructs a neighbour list and retains pairs within the sum of their radii.

convert_sparsity(::Type{Sₒᵤₜ}, in_sparsity, basisset; hermitian=false)

Convert a sparsity pattern to type Sₒᵤₜ, optionally changing hermicity. When input and output types match, only the hermicity is adjusted. Cross-type conversions (e.g. CSCRealSparsity → BlockRealSparsity, BlockRealSparsity → DenseRecipSparsity) are also supported.

get_iglobal2ilocal(sparsity::BlockRealSparsity)

Return per-pair index maps from global image indices to local image indices in ij2images.

KGrid{T,W}

Container for an irreducible k-point grid with integration weights.

Fields:

• kpoints::T — collection of irreducible k-point coordinate vectors (fractional).
• weights::W — integration weights summing to 1.
• time_reversal::Bool — whether time-reversal symmetry was used to reduce the grid.
• crystal_symmetry::Bool — whether crystal point-group symmetry was used to reduce the grid.

construct_kgrid(atoms; density, mesh, shift, time_reversal, crystal_symmetry, symprec)

Build an irreducible k-point grid for the given atomic system using Spglib.

Returns a KGrid with irreducible k-points and integration weights. The grid is reduced using the requested symmetries and validated by checking that all reducible k-points can be regenerated. Falls back to no symmetries if validation fails.

The function works only for periodic, or fully non-periodic systems (in which case a gamma point is returned).

The implementation is inspired by DFTK.jl.

Keyword arguments

• density=nothing — reciprocal-space density (points per Å⁻¹ per axis). Ignored if mesh is given.
• mesh=nothing — explicit Monkhorst–Pack grid dimensions [n₁, n₂, n₃]. Takes priority over density.
• shift=falses(3) — half-grid shift per axis (true shifts by half a grid spacing).
• time_reversal=false — exploit time-reversal symmetry (k ↔ −k) to further reduce the grid.
• crystal_symmetry=false — exploit crystal point-group symmetry to reduce the grid.
• symprec=1e-5 — symmetry detection tolerance (Å) passed to Spglib.

normalize_kpoint_coordinate(k)

Wrap fractional k-point coordinates into the range [-0.5, 0.5). Accepts a scalar or vector.

precompute_phases(kpoints, images) -> Matrix{ComplexF64}

Compute Bloch phase factors $e^{2πi \mathbf{T} \cdot \mathbf{k}}$ for all image–k-point pairs. Returns a (nimages, nkpoints) matrix.