Core

AbstractMetadata{O,X,S,B,Y,A}

Abstract supertype for all operator metadata. Type parameters encode the operator kind (O), source format (X), sparsity pattern (S), basis set (B), SH convention (Y), and atomic structure (A).

Concrete subtypes, such as RealMetadata, RecipMetadata, SpinRealMetadata, SpinRecipMetadata, differ in which extra fields they carry (k-point, spin information, or both). Traits, e.g. SpaceTrait and SpinTrait, encode these differences for dispatch.

AbstractOperator{O,M,D}

Abstract supertype for all operators. Type parameters encode the operator kind (O), metadata type (M), and data container type (D).

Base type for all Holy Traits used in dispatch throughout Quoll.

BasicMetadataContainer{O,X,S,B,Y,A}

Holds the core metadata fields shared by all metadata types: operator kind, source format, sparsity pattern, basis set, spherical harmonics convention, and atomic structure.

Every concrete AbstractMetadata subtype wraps a BasicMetadataContainer in its common field, accessed via op_basic_metadata.

DataContainer{T,N,B,X,S}

Type-tagged wrapper around operator data arrays. The type parameters encode the element type (T), dimensionality (N), concrete body type (B), source format (X), and sparsity pattern (S). This enables dispatch on data format without inspecting the body directly.

Use unwrap_data to access the underlying array/dictionary and wrap_data to construct a DataContainer from a raw body.

Singleton indicating an operator carries keyed data (e.g. per-atom-pair blocks).

Singleton indicating spin-polarised metadata (carries a SpinsMetadata).

KeyedOperator{O,M,D,KD}

An operator with keyed data. Holds metadata, a data container, and an additional keydata container (e.g. per-atom-pair block matrices indexed by (i, j) pairs).

trait(KeyedTrait, KeyedOperator) → HasKeydata().

See also Operator, build_operator.

Trait distinguishing operators that carry keydata from those that do not.

Singleton indicating an operator has no keyed data.

Singleton indicating no spin polarisation.

Operator{O,M,D}

An operator that holds metadata and a single data container.

trait(KeyedTrait, Operator) → NoKeydata().

See also KeyedOperator, build_operator.

RealMetadata{O,X,S,B,Y,A}

Real-space, non-spin-polarised metadata. Wraps only a BasicMetadataContainer.

Singleton indicating real-space metadata (no k-point).

RecipMetadata{O,X,S,B,Y,A,K}

Reciprocal-space, non-spin-polarised metadata. Extends BasicMetadataContainer with a k-point vector.

Singleton indicating reciprocal-space metadata (has a k-point).

Trait distinguishing real-space and reciprocal-space metadata.

SpinRealMetadata{O,X,S,B,Y,A,P}

Real-space, spin-polarised metadata. Extends BasicMetadataContainer with spin information.

SpinRecipMetadata{O,X,S,B,Y,A,P,K}

Reciprocal-space, spin-polarised metadata. Extends BasicMetadataContainer with both spin information and a k-point vector.

Trait distinguishing spin-polarised and non-spin-polarised metadata.

synchronise_data!(operator, comm::MPI.Comm)

All-reduce the operator's data across MPI communicator comm, summing contributions from different ranks (e.g. after distributing k-points across processes).

unwrap_data(data::DataContainer) -> body

Return the underlying array or dictionary stored in the DataContainer.

wrap_data(::Type{M}, body) where {M<:AbstractMetadata}
wrap_data(::Type{X}, ::Type{S}, body)

Wrap a raw array or dictionary into a DataContainer, tagging it with the source and sparsity types inferred from metadata type M (or provided directly as X and S).

similar(operator::AbstractOperator)

Return a new operator of the same type and metadata, with allocated but uninitialised data.

zero(operator::AbstractOperator)

Return a new operator of the same type and metadata, with all data elements set to zero.

build_data(metadata; value=0.0, type=Nothing, initialised=true)

Allocate a DataContainer matching the format described by metadata. Dispatches to format-specific build_data methods based on op_data_type(M).

build_operator(::Type{OP}, metadata; kwargs...) -> OP
build_operator(::Type{OP}, metadata, data; extra_kwargs=NamedTuple()) -> OP

Construct an operator of type OP (Operator or KeyedOperator) from metadata.

The first form allocates and initialises data according to the metadata's format. The second form uses pre-existing data directly.

For KeyedOperator, keydata is automatically built from the data via build_keydata.

Keyword arguments

• value=0.0: fill value for data arrays (determines element type if type is not given).
• type=Nothing: explicit element type override (e.g. Float32, ComplexF64).
• initialised=true: if false, allocate data without initialising (requires type).
• subbasis=nothing: if provided, reduce the basis set to this subbasis before building.
• inverted=false: if true, keep the complement of subbasis instead.
• extra_kwargs=NamedTuple(): passed through to build_operator_extra.

build_operator_extra(::Type{OP}, metadata, data; extra_kwargs) -> extras

Build extra operator fields (e.g. keydata) required by operator type OP, determined by its extrafield_traittypes. Returns a skipmissing iterator over the built extras.

find_operatorkinds(::Type{M}, dir) -> Vector{OperatorKind}

Scan directory dir for available operator data files matching metadata format M. Returns the list of OperatorKinds whose files are found on disk.

load_operator(::Type{OP}, ::Type{M}, dir, kind) -> OP

Load a single operator of type OP from directory dir. Loads metadata and data for the given OperatorKind, then assembles via build_operator. Format-specific loading is dispatched through load_metadata_basic, load_metadata, and load_data methods defined per format.

load_operators(::Type{OP}, ::Type{M}, dir, kinds) -> Vector{OP}

Load multiple operators from disk. Calls load_operator for each OperatorKind in kinds.

write_operators(::Type{M}, dir, operators)

Write a collection of operators to disk in the format determined by metadata type M. Creates the directory if it doesn't exist.

cast_basisset(out_metadata::AbstractMetadata, in_basisset) -> new_metadata
cast_basisset(out_operator::AbstractOperator, in_basisset) -> new_operator

Metadata- and operator-level wrappers around cast_basisset(out_basisset, in_basisset): transfer the principal quantum numbers n and the extras of in_basisset onto the basis set of out_metadata / out_operator. Everything else — sparsity, spherical harmonics convention, atoms, k-point, spins — is carried over unchanged, so the result keeps its concrete type.

convert_data!(out_operator, in_operator)

Transfer and transform data from in_operator into out_operator (mutating out_operator in place). Currently dispatches on the KeyedTrait of both operators to select the correct data types for conversion:

• (NoKeydata, NoKeydata) → route on (Dₒᵤₜ, Dᵢₙ)
• (HasKeydata, NoKeydata) → route on (KDₒᵤₜ, Dₒᵤₜ, Dᵢₙ)
• (NoKeydata, HasKeydata) → route on (Dₒᵤₜ, KDᵢₙ, Dᵢₙ)
• (HasKeydata, HasKeydata) → route on (KDₒᵤₜ, Dₒᵤₜ, KDᵢₙ, Dᵢₙ)

Concrete conversion methods are defined per format pair in src/conversions/.

convert_metadata(::Type{Mₒᵤₜ}, in_metadata; kwargs...) -> AbstractMetadata

Convert metadata from one format to another. This is a three-stage pipeline:

1. convert_metadata_basic — convert source, SH convention, sparsity, basis.
2. convert_metadata_extra — convert extra fields (k-point, spins) via trait dispatch.
3. convert_metadata_final — assemble the concrete output metadata type.

Mₒᵤₜ may be a union type (e.g. CanonicalBlockRealMetadata); the concrete subtype is chosen automatically based on which extra fields are present.

Keyword arguments

• radii=nothing: build sparsity from neighbour list instead of converting. Per-species radii, or per-subblock radii (a cutoff vector per species).
• hermitian=nothing: override hermicity (defaults to input's).
• out_shconv=nothing: explicit output SH convention.
• subbasis=nothing: reduce basis to this subset of orbitals.
• inverted=false: if true, keep the complement of subbasis.
• source_kwargs=NamedTuple(): extra arguments for constructing the output source.
• extra_kwargs=NamedTuple(): extra arguments for trait-based conversion (e.g. kpoint).

convert_metadata_basic(::Type{Mₒᵤₜ}, in_metadata; kwargs...) -> BasicMetadataContainer

Convert the core metadata fields: derives the output source, computes the SH convention delta, converts sparsity (optionally from radii), reorders the basis set to the output SH convention, and optionally reduces it with a subbasis.

convert_metadata_extra(::Type{Mₒᵤₜ}, in_metadata, out_basic_metadata; kwargs...)

Convert extra metadata fields (k-point, spins) based on extrafield_traittypes(Mₒᵤₜ). Traits are sorted alphabetically and each dispatches to a trait-specific handler.

convert_metadata_final(::Type{Mₒᵤₜ}, out_basic_metadata, extra_args...)

Assemble the final concrete metadata type from the basic metadata container and any extra fields (k-point, spins). When Mₒᵤₜ is a union type, the concrete subtype is chosen based on which extra arguments are present. For example:

• No extras → RealMetadata
• Spins only → SpinRealMetadata
• K-point only → RecipMetadata
• Both → SpinRecipMetadata

convert_operator(::Type{OPₒᵤₜ}, ::Type{Mₒᵤₜ}, in_operator; kwargs...) -> OPₒᵤₜ

Convert an operator to a different format in a single call. This is the main entry point for format conversion, composing three stages:

1. convert_metadata — convert source, SH convention, sparsity, basis set.
2. build_operator — allocate the output operator with zero-initialised data.
3. convert_data! — transfer and transform the actual matrix data.

Arguments

• OPₒᵤₜ: output operator type (<:KeyedOperator).
• Mₒᵤₜ: output metadata type (e.g. CanonicalBlockRealMetadata, DeepHBlockRealMetadata). May be a union type; the concrete subtype is chosen based on available extra fields.
• in_operator: the input operator to convert.

Keyword arguments

• radii=nothing: if given, build output sparsity from a neighbour list with these radii instead of converting the input sparsity. Per-species radii (one scalar per ChemicalSpecies) build an atom-pair resolved sparsity; per-subblock radii (one cutoff vector per species, or a BasisSetMetadata carrying :radius extras) build a subblock resolved one — see build_sparsity.
• hermitian=nothing: override hermicity of the output (defaults to input's hermicity).
• float=nothing: override the floating-point element type (defaults to input's).
• out_shconv=nothing: explicit output SH convention (defaults to the output source's default).
• source_kwargs=NamedTuple(): extra keyword arguments for constructing the output source struct.
• operator_extra_kwargs=NamedTuple(): passed to build_operator_extra.
• metadata_extra_kwargs=NamedTuple(): passed to convert_metadata_extra (e.g. kpoint).

convert_sparsity(::Type{Sₒᵤₜ}, in_metadata; radii=nothing, hermitian=nothing)

Metadata-level sparsity conversion wrapper. If radii is provided, builds a new sparsity pattern from a neighbour list; otherwise converts the input metadata's existing sparsity to type Sₒᵤₜ, optionally changing hermicity.

radii is passed straight to build_sparsity, which dispatches on it: per-species radii build an atom-pair resolved sparsity such as BlockRealSparsity, whereas per-subblock radii (a cutoff vector per species) build a SubBlockRealSparsity. Sₒᵤₜ must agree with the form of radii given.

zero_out_data!(out_operator, in_metadata)

Zero out the data entries of out_operator whose sparsity is not contained in the sparsity of in_metadata, mutating out_operator in place. Entries of out_operator that fall under in_metadata's sparsity keep their current values; every other entry is set to zero.

Unlike convert_operator / convert_data!, which build a new operator with a new (and therefore differently-typed) metadata, this routine changes only the data values and leaves the metadata — and hence the operator's type — untouched. This is useful for restricting an operator to a sparser support (e.g. a shorter-range neighbour pattern) without changing its type, so that all methods defined for that type remain applicable.

Dispatches on the KeyedTrait of out_operator, then on the concrete output data type and the input sparsity type. Concrete methods are defined per format in src/conversions/.

Arguments

• out_operator: the operator whose data is zeroed in place. Its metadata is not modified.
• in_metadata: metadata whose sparsity determines which entries of out_operator are retained.

fourier_transform(::Type{OPₒᵤₜ}, ::Type{Mₒᵤₜ}, in_operator, kpoints; kwargs...)

Fourier-transform a real-space operator to reciprocal space at one or more k-points. Returns a vector of reciprocal-space operators (one per k-point).

Internally: precomputes phases from the input sparsity's image vectors, converts metadata (injecting the k-point), allocates a complex output operator, and calls fourier_transform_data! for each k-point.

Arguments

• OPₒᵤₜ: output operator type (<:AbstractOperator).
• Mₒᵤₜ: output metadata type (e.g. CanonicalDenseRecipMetadata).
• in_operator: real-space input operator.
• kpoints: a single k-point vector or a collection of k-point vectors.

Keyword arguments

• out_shconv=nothing: explicit SH convention for the output (defaults to the source's).
• source_kwargs=NamedTuple(): extra keyword arguments for constructing the output source.

fourier_transform_data!(out_operator, in_operator, phases_k)

Perform the forward Fourier transform of data from in_operator into out_operator (mutating in place) using precomputed phase factors phases_k. Currently dispatches on KeyedTrait of both operators, mirroring the 4-way dispatch pattern of convert_data!.

Concrete implementations are in src/conversions/.

inv_fourier_transform_data!(out_operator, in_operator, phases_k, weight, symmetry)

Perform the inverse Fourier transform, accumulating the contribution of in_operator (at a single k-point) into the real-space out_operator, weighted by weight. Designed to be called in a loop over k-points, summing weighted contributions.

symmetry::KGridSymmetry encodes which symmetries were used to reduce the k-point grid and selects how the real-space matrix is reconstructed (e.g. a time-reversal-folded grid reconstructs the −k partner via real, whereas a full grid keeps the complex contribution).

Dispatches on KeyedTrait of both operators, same pattern as fourier_transform_data!.