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.

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.
• 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.
• 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.

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)

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.

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