Reference

AX = (; H=1, h=1, K=2, k=2, L=3, ℓ=3, l=3, E = 4, ω=4, w=4)

Maps axis symbols to index for collapse function.

Result container for Linear Spin Wave Theory calculations obtained from Sunny.

Stores broadened intensity data along multiple q-space paths, compatible with Sunny.jl output format.

Fields

• intensities::Vector{Sunny.Intensities{T, Sunny.QPath, 2}}: Broadened intensity objects
• qpaths::Vector{Sunny.QPath}: Q-space paths
• energies::E: Energy grid (typically StepRangeLen or similar)
• meta::Dict{String,Any}: Metadata (temperature, parameters, etc.)

Constructors

# From LSWT() output:
LSWTResults(nt::NamedTuple, meta=Dict())

# Full construction:
LSWTResults(intensities, qpaths, energies, meta)

LSWT(cryst, sys, paths; energies, kern, kT)

Computes LSWT for intensities I(q,ω) along several q-space paths (uses Sunny.jl). Calculates broadened 2D intensity for multiple 1D paths in parallel. The default kernel is Gaussian with fwhm=35, if not provided.

Input: cryst::Sunny.Crystal, sys::Sunny.System, paths::Vector{Sunny.QPath} Output: (intensities, qpaths, energies)::NamedTuple

Constructs a tetragonal La₂CuO₄-like crystal and Sunny spin system. Applies J, J′, J″, Jc exchanges, randomizes spins, and minimizes energy.

Space Group: 139 ~ Single Cu Ion @ [0,0,0] | (s=1/2, g=2) Supercell: (6×6×3)

Returns (cryst::Sunny.Crystal, sys::Sunny.System).

MAD(t) = 1.48*median.(abs.(t .- median(vec(t))))

Median Absolute Deviation (MAD) Applies elementwise relative to the median of t. Suitable for thresholding outliers in intensity arrays. Returns an array of MAD values with the same shape as t.

Constructs low-temperature monoclinic (CH₃)₄[NMnCl₃] crystal via Sunny. Applies exchange coupling J and anisotropic exchange Δ (along z-axis).

This crystal is commonly referred to as TMMC. It is a 1D high-spin Heisenberg chain.

Space group: 14 (P2₁/b) ~ Single Mn Ion @ [1/5, 1/4, 1/5] | (s=5/2, g=2) Supercell: (1×4×150)

Returns (cryst::Sunny.Crystal, sys::Sunny.System)

autosplitbands(Iqω, ωs; pers_ratio_min=2.0)

Automatically perform persistence-homology–based band segmentation along both energy and momentum axes.

You MUST use (q,ω) index ordering or the keys are not physically accurate.

This function applies splitbands twice: (1) directly to I(q,ω), yielding bands resolved along ω (energy-first), (2) to the transposed matrix I(ω,q), yielding bands resolved along q (momentum-first).

The results are returned as two named tuples:

• splitE : band structure obtained by splitting along ω
• splitQ : band structure obtained by splitting along q

Each tuple has the form: (bandIq = ..., bandIω = ...)

where bandIq denotes energy-integrated intensities as a function of q, and bandIω denotes momentum-integrated intensities as a function of ω, with index conventions adjusted to maintain physical meaning after transposition.

This is intended as a minimal, orientation-agnostic wrapper that enables automatic comparison between phonon-like (ω-gapped) and magnon-like (q-persistent) spectral structures.

The parameter pers_ratio_min controls the persistence-lifetime ratio threshold used to infer the number of bands in each slice.

betti_curvature(pd, τ; dims = 0:1, scheme = :forward)

Compute βp(τ) and κp(τ) = dβ_p/dτ on a grid τ.

• scheme = :forward (default) uses forward differences and sets κ[end]=κ[end-1]. Use :central for central differences on interior points.

Returns (β::Dict{Int,Vector{Int}}, κ::Dict{Int,Vector{Float64}}).

betti_curve(PDs, τ; dims = 0:1)

Compute per-dimension Betti curves βp(τj) on a user-provided grid τ.

• PDs :: Vector of Ripserer PD (grouped by degree).
• τ :: Sorted vector of life-time thresholds (monotone increasing).

Returns Dict{Int,Vector{Int}} mapping p ↦ β_p(τ).

collapse(A::AbstractArray; over::Union{Symbol, Tuple{Symbol}}, op::Function)

Collapse (reduce) a 4D array over one or more axes with specified operation (default operation is :sum). Axes may be symbols (:h,:k,:ℓ,:ω) [Julia Syntax] or integer indices [Python Syntax]. Reduces highest axes first to keep indices stable. Returns collapsed (reduced) array.

Note, the indexing convention in Julia is such that (JuliaArr[1] ~ PythonArr[0]).

convert4D(result2D, Qs, Es)

Reshape Sunny intensities from (ω, q) or (q, ω) into a 4D cube (h,k,ℓ,ω). Validates sizes given Q-grid shape, then reshapes/permutedims accordingly. Returns a 4D Array with axis order (h,k,ℓ,ω).

h5tree(fname; keypath=nothing, maxdepth=Inf)

Display HDF5 file structure in tree format.

Arguments

• fname::String: HDF5 filename (without .h5 extension)
• keypath::Union{String,Nothing}: Start from specific path (default: root)
• maxdepth::Int: Maximum depth to display (default: Inf = all levels)

Examples

#Show entire file
h5tree("crystal-data")

#Show specific subtree
h5tree("crystal-data"; keypath="crystals/La2CuO4")

#Limit depth
h5tree("crystal-data"; keypath="crystals/La2CuO4/LSWT", maxdepth=1)

loadHDF5(fname; keypath=nothing) -> data

Load data from an HDF5 file.

Arguments

• fname::String: Filename without .h5 extension
• keypath::Union{String,Nothing}: HDF5 internal path to specific dataset or group. If nothing (default), loads entire file structure as nested Dict.

Returns

• Dict{String,Any}: Nested dictionary mirroring HDF5 hierarchy, or the specific dataset/group if keypath is provided

Examples

# Load entire file structure
data = loadHDF5("crystal-data")
data["crystals"]["La2CuO4"]["LSWT"]["Temp"]["0K"]["H"]["intensities"]  # Access nested data

#Load specific group
LCO_data = loadHDF5("crystal-data"; keypath="crystals/La2CuO4/LSWT")
LCO_data["Temp"]["0K"]["H"]["intensities"]  # Only La2CuO4 LSWT data loaded

#Load specific direction
H_data = loadHDF5("crystal-data"; keypath="crystals/La2CuO4/LSWT/Temp/0K/H")
H_data["intensities"]  # Only H-direction data

#Load specific dataset (array)
intensities = loadHDF5("crystal-data"; keypath="crystals/La2CuO4/LSWT/Temp/0K/H/intensities")
#intensities is now a Matrix{Float64}

#Load q-points
qpoints = loadHDF5("crystal-data"; keypath="crystals/La2CuO4/LSWT/Temp/0K/H/qpoints")

Notes

• HDF5 hierarchy uses "/" as path separator (like filesystem paths)
• Use keypath to load only what you need (faster for large files)
• Returned structure depends on what's stored at keypath:
  • Group → Dict with nested structure
  • Dataset → Array or scalar value

merge_energy_bands!(peaks_sorted::Vector{Int}, ωs; merge_tol = 1.0)

Given a sorted list of peak indices for one q-slice, merge peaks whose ω-values differ by less than merge_tol (meV).

Returns a new vector of representative peak indices.

pd_array_intensities(A; maxdim=1, threshold=0, superlevel=true, normalize=false)

Compute persistance diagrams of an intensity array using cubical complex.

Input:

• A :: N₁×N₂ Intensity Array
• maxdim :: Sets Maximum Homology Degree p
• threshold :: Sets Lower/Upper Bound for Superlevel/Sublevel Filtration
• superlevel :: Chooses Filtration Scheme
• normalize :: Sets Normalization

Returns:

• PDs :: Persistence Diagrams {Dₚ} for p ∈ [0, maxdim]

Each persistence diagram Dₚ ∈ PDs contains birth-death pairs of topological features, grouped by homology degree up to maxdim. Optional sublevel/superlevel filtration and normalization.

Threshold values should be given as a percent of the maximum intensity value. For superlevel filtration, features with intensity vales above threshold * maximum(A) survive. For sublevel filtration, features with intensity values below threshold * maximum(A) survive. If threshold is set to nothing (default), the full range of intensity is evaluated.

Used to analyze the topology of I(Q,ω) = |S(Q,ω)|².

pd_sunny_intensities(I; maxdim, threshold, superlevel, normalize)

Wrapper: Sunny.Intensities -> dense Array -> pdarrayintensity

Converts I.data to a dense array and calls pd_array_intensity. Respects maxdim, threshold, and superlevel. Returns PDs.

Convenient for topology on Sunny LSWT intensity objects.

persistence_entropy(PDs; dims = 0:1, tol = 0.0)

Compute per-dimension persistence entropy Sₚ and total persistence Eₚ.

• PDs :: A vector of persistence diagrams, grouped by homology degree p.
• dims:: Homology degrees (default 0:1).
• tol :: Discards lifetimes ≤ tol (guards numerical noise).

Returns (S::Dict{Int,Float64}, E::Dict{Int,Float64}) keyed by p.

persistence_entropy_curve(PDs, τs; dims = 0:1, tol = 0.0)

Filtration-dependent persistence entropy Sₚ(τⱼ) and total truncated persistence Eₚ(τⱼ).

• PDs :: Vector of Ripserer persistence diagrams grouped by homology degree.
• τs :: sorted vector of filtration parameters (monotone increasing).
• dims :: homology degrees to use (default 0:1).
• tol :: discard contributions with truncated lifetime ≤ tol.

For each p and τⱼ, lifetimes are truncated as ℓᵢ(τⱼ) = max(0, min(dᵢ, τⱼ) - bᵢ) and only ℓᵢ(τⱼ) > tol and finite dᵢ are used.

Returns (S::Dict{Int,Vector{Float64}}, E::Dict{Int,Vector{Float64}}) keyed by p, where S[p][j] = Sₚ(τⱼ), E[p][j] = Eₚ(τⱼ).

saveHDF5(crystal, sweepParam, sweepValue, qnames, results::LSWTResults; fname, root)

Save LSWT results to HDF5 using the canonical hierarchy:

root/crystal/LSWT/sweepParam/sweepValue/direction/{qpoints, energies, intensities}

This enforces a structured scientific database layout where:

• crystal identifies the material,
• LSWT identifies the computational method (determined by dispatch),
• sweepParam defines the swept physical parameter (e.g. "Temp"),
• sweepValue defines the specific parameter value (e.g. "0K"),
• direction corresponds to q-space paths provided by qnames.

Arguments

• crystal::String Crystal or material identifier (e.g., "La2CuO4").

• sweepParam::String Name of the swept parameter (e.g., "Temp", "Field", "Pressure").

• sweepValue::String Label for the specific parameter value (e.g., "0K", "10K", "B=5T").

• qnames::Vector{String} Direction labels corresponding to q-space paths (typically from the @name macro).

• results::LSWTResults LSWT computation results container.

Keyword Arguments

• fname::String="crystal-data" Output filename (without .h5 extension).

• root::String="crystals" Top-level group name in the HDF5 hierarchy.

Notes

• Data is appended to the file ("a" mode), allowing multiple sweeps and methods to coexist.

• Metadata stored in results.meta is written to:

  root/crystal/LSWT/sweepParam/sweepValue/meta/

• Physical state variables (e.g., temperature, field, doping) should be encoded via sweepParam and sweepValue, not stored as metadata.

splitbands(Iqω, ωs; pers_ratio_min=2.0)

Use 0D PH on each q-slice to estimate the number of significant bands, then partition ω into that many bands via peak locations.

Returns bandIq::Matrix{Float64} with size (Nbands, nq) and bandIω::Matrix{Float64} with size (Nbands, nω).

@name [var1, var2, ...]

Output variable names and values into a named tuple. Returns (paths=[var1,var2,...], names=["var1","var2",...]).

Note: Variables must be provided as a literal array expression at the call site. This macro cannot work with pre-existing arrays.

Example

# Correct
H = Sunny.q_space_path(cryst, [[h,0,0] for h in -1:1], 500)
K = Sunny.q_space_path(cryst, [[0,k,0] for k in -1:1], 500)
L = Sunny.q_space_path(cryst, [[0,0,ℓ] for ℓ in -1:1], 500)

qpaths = @name [H,K,L]

#qpaths.paths = [H,K,L]
#qpaths.names = ["H","K","L"]

# Incorrect
arr = [H,K]
qpaths = @name arr #Throws error here