AbstractQAtlas.jl

The model-independent layer of the QAtlas ecosystem — abstract quantity vocabulary + generic physics relations as first-class, tested objects.

In the spirit of AbstractFFTs: concrete atlases (QAtlas.jl) implement this package, never the reverse.

Division of responsibility

lives here (AbstractQAtlas)	lives in the implementing atlas
type vocabulary: `AbstractQAtlasModel`, `AbstractQuantity`, `BoundaryCondition`, the generic `fetch` verb	concrete models and registered `fetch` methods
generic relations: scaling laws, fluctuation–dissipation, Wick's theorem, topological invariants, FSS forms	reference values (critical temperatures, exact magnetizations, exponent tables)

A relation is an identity among observables or exponents — a statement true independently of any model. Expressing each one once, as a tested object, means downstream packages stop re-deriving them ad hoc in comments and per-model tests.

Declare once, derive everything

A relation is written exactly once, with @relation:

@relation :scaling Rushbrooke(α, β, γ) = α + 2β + γ - 2

One declaration yields the struct, the residual kernel, the variables/domain introspection traits, registry membership, and — with no hand-written rearrangements — solve for every variable the expression is affine in (a non-affine variable is refused, never silently mis-solved).

The uniform verbs:

residual(rel; vars...) — signed violation; 0 ⇔ satisfied,
check(rel; atol=0, vars...) — |residual| ≤ atol,
solve(rel, Val(:x); vars...) — the value of x implied by the rest,

with an exact-arithmetic contract: Rational in ⇒ Rational out, so exactly-known values satisfy their relations exactly, not merely to floating-point tolerance. Relations taking an inverse temperature accept β or T at every verb; normalization happens once, in the verb layer.

using AbstractQAtlas
using AbstractQAtlas: residual, check, solve

residual(Rushbrooke(); α=0//1, β=1//8, γ=7//4)   # 0//1 — exact
solve(Widom(), Val(:δ); β=1//8, γ=7//4)           # 15//1 — derived, not hand-coded
check(Fisher(); γ=7//4, ν=1//1, η=1//4)           # true

Equalities and bounds. Most relations are equalities (check ≡ abs(residual) ≤ atol); bound-type constraints are declared with @bound as AbstractInequality, whose residual is the ≥ 0 slack — check tests that direction, slack reports the margin, and solve returns the saturation (tight-bound) value. The quantum-information entropy bounds are the first users: EntropyNonNegativity, MaxEntropyBound (S ≤ ln d), Subadditivity, ArakiLieb, StrongSubadditivity (Lieb–Ruskai), RenyiMonotonicity.

check(StrongSubadditivity(); S_AB, S_BC, S_ABC, S_B)   # S_AB + S_BC ≥ S_ABC + S_B ?
solve(Subadditivity(), Val(:S_AB); S_A, S_B)           # the tight bound S_A + S_B

A bound is declared as the statement it makes, subject first, so the roles are readable off the declaration rather than inferred from the sign of a slack expression:

@bound :thermodynamic SpecificHeatPositivity(Cv::SpecificHeat >= 0)
@bound :quantum LiebRobinsonBound(v <= v_LR::LiebRobinsonVelocity)
@bound :entanglement Subadditivity(S_A, S_B, S_AB) = S_AB <= S_A + S_B

bounded_slot, bounding_slot, bounding_constant and bound_direction expose those roles, and bounds_on answers the reverse question — what bounds this quantity?

bounds_on(SpecificHeat)              # [SpecificHeatPositivity()]
bound_direction(LiebRobinsonBound()) # :upper — v is bounded from above
bounding_slot(LiebRobinsonBound())   # :v_LR

Family and group slots. A slot may be keyed on a parametric family (χT::Susceptibility), and relation_report then auto-discovers every concrete component in the bag — one row per component. That is safe because a family's components are one quantity at different indices, so a law written on the family is component-agnostic by construction.

An abstract group is different in kind — MassGap, ChargeGap and SpinGap are different quantities — so the quantifier is written explicitly:

@bound :test EveryGapPositive(g::EachOf{AbstractGap} >= 0)   # holds for every gap
@relation :test OneGapSetsXi(g::AnyOf{AbstractGap}, ξ) = g * ξ - 1   # about ONE gap

EachOf enumerates like a family. AnyOf does not: the engine cannot know which member a one-member law is about, so such a relation is checkable with an explicit subject but is not auto-discovered — and ambiguous_relations lists them, so the gap is visible instead of absent. A bare abstract slot is refused at declaration, because guessing the quantifier turns a one-member law into false violations on its siblings.

Adopting from another package: one call

A consumer never hand-lists relations — applicable_relations selects by variable names, relation_report evaluates and reports, check_all gates (an empty match is false, never a silent green):

check_all((α=0//1, β=1//8, γ=7//4, δ=15//1, ν=1//1, η=1//4, d=2))   # exponent table gate
relation_report((C=c, var_E=v, T=T, N=N); atol=tol)                  # thermodynamics sweep

Pass domain= when a data set mixes families (physics overloads names: the exponent β vs the inverse temperature β). Downstream packages declare their own relations with the same @relation macro.

What is covered (v0.1)

Scaling laws — Rushbrooke, Widom, Fisher, Josephson, gated by exponents_consistent.
Fundamental equations — FreeEnergyFromZ ($F = -β^{-1}\ln Z$), FreeEnergyLegendre ($F = U - TS$), EntropyResponse ($S = -∂F/∂T$), GibbsHelmholtz ($U = ∂(βF)/∂β$).
Distributions & statistics — MicroCanonical / Canonical / GrandCanonical / Squeezed with ensemble_weight; Fermionic/Bosonic occupation functions; the ThermalAverage marker ($⟨Q⟩_D$ at the type level).
Thermodynamic identities — SpecificHeatFDT, SusceptibilityFDT, LinearResponseFDT (conventions: $c_v = β^2\,\mathrm{Var}(E)/N$, $χ = β\,\mathrm{Var}(M)/N$).
Wick's theorem — wick_contraction, wick_density_correlation (number-conserving Gaussian fermion states; BdG/Pfaffian generalization tracked).
Topological invariants — winding_number (1D two-band), chern_number (Fukui–Hatsugai–Suzuki), TKNN.

Tensor structure — internal degrees of freedom

Quantities that are tensors carry their indices as type parameters and declare tensor_rank / index_spaces / indices, so they are not silently scalarized. Susceptibility(:x, :y) is the off-diagonal χ_xy; the design is order-extensible to nonlinear response — Susceptibility(:x, :y, :z) is χ⁽²⁾_{x;yz} = ∂²M_x/∂h_y∂h_z (response_order == 2, tensor_rank == 3) and the differentiation_chain extends recursively χ⁽ⁿ⁾ ⟵ χ⁽ⁿ⁻¹⁾ ⟵ … ⟵ M ⟵ F. Index spaces: SpinAxis, SpatialDirection (Conductivity, also nonlinear), OrbitalIndex (propagators). Dyson is written with inv, so the identity holds for scalar single-band and matrix orbital-space propagators alike.

frequency_arguments is a quantity's multi-time dimensionality — the count of independent frequency (⇔ time) variables. The static Susceptibility is the zero-frequency limit (0); the dynamical DynamicalSusceptibility(:x, :y, :z) is χ⁽²⁾(ω₁, ω₂) with frequency_arguments == 2 — an n-th order nonlinear response is intrinsically multi-time (2D coherent spectroscopy). Its microscopic origin is the Kubo formula (spectral_origin(DynamicalSusceptibility(:x,:y,:z)) == (DynamicalCorrelation{(:x,:y,:z)}, :kubo)): the retarded n-fold nested-commutator response function of the same-order correlation — an n-th order response is an n-time ((n+1)-point) correlation, so the Kubo edge preserves the frequency count on both sides. Response-theory and scaling/FDT references (Kubo 1957, Wan–Armitage 2019, Rushbrooke/Widom/Fisher/Josephson, Callen–Welton

live in docs/references.bib, DOI-verified in CI.

Nonlinear-tensor symmetry & accumulated relations

The nonlinear susceptibility is essentially a higher-order tensor, and carries intrinsic permutation symmetry — χ⁽ⁿ⁾'s field indices (with their frequencies) are interchangeable, so Susceptibility(:x, :y, :z) == Susceptibility(:x, :z, :y) under permutation_equivalent (canonical_component sorts the field indices; the response index is fixed).

Known inter-quantity relationships accumulate as first-class relations: ChernFromBerryCurvature (C = (1/2π)∫Ω) with TKNN (σ_xy = C) and BulkBoundary (n = |ν|) for the topological side; SpecificHeatFromEntropy (c = T ∂s/∂T) and HeatCapacityDifference (Mayer's c_p − c_v = T v α²/κ_T) for heat capacity; MicrocanonicalTemperature (β = ∂S/∂E, the microcanonical–canonical bridge) and CanonicalTPQ (Z = D·⟨ψ₀|e^{−βH}|ψ₀⟩, Sugiura–Shimizu) for statistical ensembles and thermal-pure-quantum estimators. The transport family (Conductivity with its AC DynamicalConductivity, ThermalConductivity, Thermopower, PeltierCoefficient, DrudeWeight, and the ElectricCurrent / HeatCurrent) carries WiedemannFranz (κ = L₀σT), the Mott MottFormula (S = −(π²/3)T d ln σ/dε), the Kelvin KelvinRelation (Π = TS), OnsagerReciprocity (L_{μν} = L_{νμ}), and the optical OpticalSumRule (∫Re σ dω = πD + W_reg). References are DOI-verified in docs/references.bib.

Scope note. The Berry curvature is the imaginary part of the quantum geometric tensor; the real part (the quantum metric) and the mixed-state / Uhlmann generalizations are deliberately out of scope — this package stays at the model-independent textbook level.

Structure — definitional correspondences

The structure/ layer holds the generic facts that are true by definition, from which the forms above are derived rather than restated:

Critical correspondence — critical_scaling maps each observable to the exponent governing its singularity (Susceptibility ↦ γ, SpontaneousMagnetization ↦ β, …). The singular and finite-size forms follow: singular_form, fss_size_exponent (so χ_max ∼ L^{γ/ν} is derived, not a hand-passed ratio), fss_peak, collapse_coordinates. Field-driven and distance-driven laws: critical_isotherm (δ), correlation_decay (η).
The exponents' RG origin — the four scaling laws (Rushbrooke, Widom, Fisher, Josephson) are not four independent axioms: they all follow from the homogeneity of the singular free energy f_s(t,h) = b^{-d} f_s(b^{y_t}t, b^{y_h}h), i.e. from just two RG eigenvalues plus d. ScalingDimensions(y_t, y_h, d) carries them and critical_exponents derives the whole set (α,β,γ,δ,ν,η) — for which every scaling relation has residual ≡ 0 by construction (exponents_consistent is true for any input). The inverse scaling_dimensions(; ν, η, d) recovers the eigenvalues, so δ, β, γ, α are all reconstructible from (ν, η, d) alone. Values are inputs; the map is the universal content:
```
critical_exponents(ScalingDimensions(1//1, 15//8, 2))
# (α=0//1, β=1//8, γ=7//4, δ=15//1, ν=1//1, η=1//4)  ← 2D Ising, exact
```
Transition classification — FirstOrder / ContinuousTransition / KosterlitzThouless, each carrying ehrenfest_order, has_order_parameter, has_latent_heat, has_critical_exponents.
Response genealogy — derivative_edge encodes the derivative tree rooted at a thermodynamic potential (M = −∂F/∂h, χ = ∂M/∂h, C = ∂U/∂T at the free-energy root; N = −∂Ω/∂μ at the grand-potential root). differentiation_chain traces any response back to its potential_root (FreeEnergy or GrandPotential); derivative_order counts field derivatives (χ = ∂²F/∂h² ⇒ order 2); is_response, conjugate_field. The exact formulas are the paired relations MagnetizationResponse, SusceptibilityResponse, GibbsHelmholtz — the definitional χ = ∂M/∂h and the statistical χ = β·Var(M) (SusceptibilityFDT) being the same response two ways.
Dynamical / spectral graph — spectral_origin / spectral_chain trace the frequency-resolved quantities back to their sources (DensityOfStates ⟵ SpectralFunction ⟵ RetardedGreensFunction ⟵ SelfEnergy), and origin_relation ties each single-(q,ω)-point edge to its exact identity: Dyson (G⁻¹ = G₀⁻¹ − Σ), SpectralFromGreens (A = −Im Gᴿ/π), with SpectralSumRule, DetailedBalance (S(q,−ω) = e^{−βω} S(q,ω)) and NMRExponent (θ_NMR = 2Δ_op − 1). Transform / BZ-sum / limit edges have no pointwise form — their evaluation is the functional sibling's job.
Keldysh RAK structure & fluctuation–dissipation — the real-time sibling of the Matsubara Dyson layer. The retarded/advanced/Keldysh components obey the state-independent identities G^K = G^> + G^< and G^R − G^A = G^> − G^< (KeldyshComponent, KeldyshCausality) plus the adjoint tie G^A = (G^R)† (AdvancedRetardedConjugate, which also puts G^A on the spectral graph via the :adjoint edge). In equilibrium the Keldysh component is not independent: the fluctuation–dissipation theorem KeldyshFDT locks it to the spectral part, G^K = h(ω)(G^R − G^A), with the distribution function keldysh_distribution h = coth(βω/2) (bosons) = tanh(βω/2) (fermions) = 1 ∓ 2n. That h is itself a consequence of the KMSGreaterLesser detailed-balance relation G^<(ω) = ζe^{−βω}G^>(ω) — FDT is derived, not assumed — and SpectralFromKeldysh A = i(G^R−G^A)/2π reduces to −Im G^R/π, bridging back to the normalized spectral function.

One queryable graph of physics

The genealogy, the spectral graph, the Fourier pairs and the relation ↔ quantity links are all the same shape — a typed edge between quantity kinds — so they fold into one queryable graph (quantity_graph), mirroring the vocabulary of QAtlas's model graph (relations(model)): the two atlases share one graph language, models ⊕ quantities.

related_quantities(q) — the neighborhood of a quantity: every edge it participates in, tagged by kind (:derivative, :spectral, :fourier, :law) as a QuantityEdge. For Susceptibility this surfaces both Magnetization (as ∂/∂h and via the FDT) and StaticStructureFactor (via the structure-factor sum rule) at once.
quantity_path(a, b) — the machine answer to "how are a and b related?": a shortest path of typed edges. SpecificHeat and Magnetization connect through their shared FreeEnergy root.
quantity_neighbors(fam) — incident edges in both directions (so a derivative root like FreeEnergy still surfaces the quantities that point at it), and quantity_graph_jsonl streams the whole network as stdlib-only JSONL for a graph view.

Nodes are quantity families (the index-erased Susceptibility, not Susceptibility{(:z,:z)}) so the structural graph is finite; the concrete index is still used to resolve an edge (χ⁽²⁾ ⟶ χ⁽¹⁾ ⟶ M) before the endpoints collapse to their families.

Under the hood this is one instance of a generic parent, the KnowledgeGraph{N} kernel — a bag of TypedEdges over nodes of type N, with the traversal/reachability/shortest-path/export (graph_reachable, graph_shortest_path, graph_jsonl) written once. quantity_graph() is a KnowledgeGraph{Type}; the derivation graph below is a KnowledgeGraph{Symbol} (derivation_graph); and QAtlas's model graph becomes a third instance once refactored onto this package — so a single graph-view renders models ⊕ quantities ⊕ derivations.

Deriving a quantity by route

Read each equality as a computation — solve turns a relation into "given all-but-one variable, produce the last" — and the whole registry becomes a directed derivation graph (derivation_steps): a node per variable, a directed edge for every variable a relation can be solved for. From a set of known quantities you can then ask what else is reachable and, lazily, get one route run for you:

derivable(; Z = 2.0, β = 1.0)                # Set([:Z, :β, :f, …])  reachable
derive(:f; Z = 2.0, β = 1.0)                 # -0.6931…   (F = −β⁻¹ ln Z)
derive(:δ; α = 0//1, β = 1//8)               # 15//1  — two exact hops, Rushbrooke→Widom

Two safety guarantees, because a chained result is weaker than a directly implemented one:

Equalities only. Inequalities are excluded — their solve returns a saturation bound, not an equational value, so a bound can never masquerade as a derived quantity.
Auditable provenance. derive(…; debug=true) returns a DerivationTrace — the value, the exact route (which relation produced each intermediate, from which inputs), and an indirect flag — so an indirectly derived number is inspected by its route, not trusted blindly. The route is discovered by calling the real solve, so a step whose relation is non-affine in its output is skipped, never faked; an unreachable target fails loudly.

derive(:δ; α = 0//1, β = 1//8, debug = true)
# DerivationTrace(:δ = 15//1  [indirect])
#   1. Rushbrooke: {α, β} → :γ
#   2. Widom: {β, γ} → :δ

The scope line: definitional vs functional

Where does a dynamical quantity's value come from — this package or the future ParaLA-based functional sibling? operation_scope draws the line (issue #14):

:definitional (here) — a pointwise identity relating quantity values at a single (q, ω), or a supplied scalar (an integral, a derivative): Dyson, SpectralFromGreens, the sum rules, KramersKronigReal/Imag, every @relation. This package holds these as stdlib-only tested identities.
:functional (sibling) — a transform / sum / limit that represents a quantity as a function and acts on it globally: the BZ average, the space-time Fourier transform, an ω → 0 limit, the Kubo response. Only the structural edge lives here; the numerical evaluation is deferred.

The grey zone (cf. #6) resolves by the supplied-value convention: a sum rule or Kramers–Kronig relation is :definitional — the relation checks a supplied number here, while computing that number from the function (the principal-value Hilbert transform, the spectral integral) is :functional, the sibling's job. So the boundary is exactly origin_relation's split: definitional ⟺ a pointwise @relation exists.

API reference

AbstractQAtlas.AbstractQAtlas — Module

AbstractQAtlas

The model-independent layer of the QAtlas ecosystem, in the spirit of AbstractFFTs: concrete atlases (QAtlas) implement this package, never the reverse.

Layers:

core/ — the abstract type vocabulary for physical quantities: AbstractQAtlasModel, BoundaryCondition (Infinite/OBC/PBC), AbstractQuantity and its hierarchy, the abstract fields, the generic fetch verb (+ its fetch_cached memoization), and the Universality machinery — so atlases and third packages share dispatch types without depending on a full atlas.
structure/ — the model-independent definitional correspondences between the core quantities: the transition classification, the quantity⇄exponent map behind the scaling forms, the response-function derivative genealogy (derivative_edge, rooted at FreeEnergy / GrandPotential), the spectral and Fourier graphs, and the Maxwell relations derived from the potentials.
relations/ — generic, model-independent physics relations as first-class tested objects with a uniform three-verb interface (residual / check / solve): scaling laws, fluctuation–dissipation identities, Wick's theorem, topological invariants, the spectral/Keldysh web, and finite-size scaling forms.
seams — generic verbs whose numerics/values live at the leaves: fetch (reference values, in QAtlas), report→Card (reported values), principal_value_hilbert/spectral_moment (functional numerics), and thermal_derivative/thermal_gradient (AD, in the ForwardDiff/Zygote extensions) — plus the KnowledgeGraph graph layer.

Values do not live here, and neither do model-specific laws. This package owns only what holds universally within a domain — independent of the system's symmetry, Hamiltonian, or any individual detail (Wick's theorem, the fluctuation–dissipation and Maxwell relations, the entropy inequalities, Kramers–Kronig, the scaling laws, …). Reference numbers (critical temperatures, exact magnetizations, exponent tables) AND model-specific relations (the Drude mobility μ=eτ/m, the ±J Nishimori- line energy, the SK de Almeida–Thouless line, single-band R_H=1/ne, …) belong to the implementing atlas (QAtlas), not here. The library is a universal yardstick: apply its relations to measured quantities to check whether a system obeys the laws that must hold regardless of its details.

region	spin	fermionic
`{1,2,3,4}`	0.628316	0.628316
`{1,2,5,6}`	1.112324	1.224109
`{1,3}`	1.166659	1.386294

process	`WaveMixing`	arguments	emits
`HarmonicGeneration(q)`	`((q,), (0,))`	`(ω, …, ω)`	`qω`
`OpticalRectification`	`((1,), (1,))`	`(ω, −ω)`	`0`
`SumFrequencyGeneration`	`((1,1), (0,0))`	`(ω₁, ω₂)`	`ω₁+ω₂`
`DifferenceFrequencyGeneration`	`((1,0), (0,1))`	`(ω₁, −ω₂)`	`ω₁−ω₂`
`FourWaveMixing`	`((2,0), (0,1))`	`(ω₁, ω₁, −ω₂)`	`2ω₁−ω₂`
`KerrEffect`	`((2,), (1,))`	`(ω, ω, −ω)`	`ω`
`CrossPhaseModulation`	`((1,1), (1,0))`	`(ω₁, −ω₁, ω₂)`	`ω₂`

`quantity`	`potential`	result
`Magnetization(α)`	`F(h)`	`M_α = −∂F/∂h`
`Susceptibility(α, β₁…βₙ)`	`F(h)`	`χ⁽ⁿ⁾ = −∂ⁿ⁺¹F/∂hⁿ⁺¹` (diagonal only — all indices equal)
`ThermalEntropy()`	`F(T)`	`S = −∂F/∂T`
`SpecificHeat()`	`U(T)`	`C = ∂U/∂T`
`Energy()`	`βF(β)`	`U = ∂(βF)/∂β` (Gibbs–Helmholtz)

Φ	dΦ
`U(S,V)`	`+T dS − p dV`
`F(T,V)`	`−S dT − p dV`
`H(S,p)`	`+T dS + V dp`
`G(T,p)`	`−S dT + V dp`

region	`ncuts`
one interval on a ring	2	`c/3`
block at an open end	1	`c/6`
block in the bulk of an open chain	2	`c/3`