v0.4.0

MeanFieldTheories v0.4.0

Diff since v0.3.0

Breaking changes

New Features

Particle-hole excitation solver (solve_ph_excitations)

The major addition in this release. Computes collective excitation spectra on top of a converged Hartree-Fock ground state, with two methods:

• Tamm-Dancoff Approximation (TDA): Diagonalizes the Hermitian M×M effective Hamiltonian A(q) in the particle-hole pair space. Suitable when ground-state correlations are weak.
• Random Phase Approximation (RPA): Solves the full 2M×2M non-Hermitian Bosonic BdG eigenvalue problem (A, B; -B†, D), capturing ground-state quantum fluctuations. Uses the Cholesky-based method (Shindou et al. PRB 87, 174427, 2013) with automatic fallback to direct diagonalization. Guarantees gapless Goldstone modes for spontaneously broken continuous symmetries.

Key design choices:

• Unified API: solve_ph_excitations(...; solver=:TDA) or solver=:RPA
• Automatic BZ folding via _fold_to_BZ + _find_on_mesh (replaces the old _kindex_analytic); off-mesh k+q points are recomputed on the fly via energy_bands
• Occupation-based particle-hole pair detection (automatic per k-point)
• Optional band restriction via n_list keyword
• Multi-threaded over q-points (Threads.@threads)
• D(q) = -A(-q)* shortcut used when ±q occupation spaces match; otherwise D is computed directly with residual occupation factors

Charge order analysis

• local_charge(dofs, G): compute local charge density on each site
• charge_structure_factor(charges, lattice, qpoints): charge structure factor N(q)
• charge_ordering_wavevector(charges, lattice, qpoints): find the dominant charge ordering wavevector

Magnetic structure factor & ordering wavevector

• spin_structure_factor(mags, lattice, qpoints): magnetic structure factor S(q)
• magnetic_ordering_wavevector(mags, lattice, qpoints): find the dominant magnetic ordering wavevector

API Changes (Breaking)

• Renamed: local_magnetization → local_spin, print_magnetization → print_spin, plot_magnetization → plot_spin. The old names are removed.

Improvements

• Type signatures relaxed: green_k_to_tau, build_heff_k!, energy_bands, calculate_energies_k, _run_scf_k now accept AbstractVector{<:AbstractVector{Float64}} instead of Vector{Vector{Float64}}, improving interoperability with StaticArrays and views.
• SCF final-pass consistency: solve_hfk now performs a final recomputation of H_k, eigenvalues, eigenvectors, and mu from the converged G_k, ensuring all returned quantities are mutually consistent.

Documentation

• Restructured "Collective Excitations" section: replaced the old SMA-centric introduction (collective_excitations.md) with three focused pages:
  • BSE_TDA_RPA.md: Theoretical reference for Bethe-Salpeter Equation, TDA, and RPA frameworks
  • particle_hole.md: TDA derivation and implementation details
  • particle_hole2.md: Full RPA derivation (forward/backward amplitudes, Bosonic BdG, Goldstone theorem)
• New example tutorials:
  • AFM Magnon Dispersion (AFM_Magnon.md): Néel AFM on square lattice, magnon spectrum via RPA, Goldstone theorem validation
  • Tasaki Flat-Band Ferromagnet (Tasaki.md): Decorated chain, particle-hole excitations via TDA
• solve_ph_excitations added to API reference page
• README rewritten with AFM Magnon as the Quick Start showcase

Tests

• Replaced obsolete _kindex_analytic tests with comprehensive tests for _fold_to_BZ, _find_on_mesh, and _build_ph_pairs, covering multiple lattice types (1D, 2D square/rectangular/triangular/honeycomb), BZ translation invariance, k+q closure, pinv embedding for lower-dimensional systems, and occupation-dependent pair construction.

Examples

• New: examples/AFM_Magnon/ (run.jl, plot.jl, data files)
• New: examples/Tasaki/ (tasaki.jl)

v0.3.0

MeanFieldTheories v0.3.0

Diff since v0.2.2

Breaking changes

⚠️ All users of v0.2.x are strongly encouraged to upgrade. This release fixes a
critical bug that silently produces wrong self-consistent ground states whenever the
ordered phase involves spin-flip (off-diagonal) correlations, such as xy-plane SDW or
any non-collinear magnetic order.

---

Critical Bug Fix: Asymmetric Hubbard Interaction

What was wrong

In v0.2.x, the on-site Hubbard interaction was conventionally written as:

(qn1.spin, qn2.spin, qn3.spin, qn4.spin) == (1, 1, 2, 2) ? U : 0.0

This only defines the tensor element $V_{\uparrow\uparrow\downarrow\downarrow} = U$ and
leaves $V_{\downarrow\downarrow\uparrow\uparrow} = 0$, making the interaction tensor
non-Hermitian.

Why this matters

The Hartree-Fock self-energy is assembled from V through index permutations required
by Wick's theorem. Specifically, the Fock channel for Case A interactions uses the
relation

$$W^{adcb}(-\mathbf{r}) = \left[W^{bcda}(\mathbf{r})\right]^*$$

which is only valid when V (and hence W) is Hermitian. With the asymmetric definition
above, this identity breaks down. The resulting H_eff has a non-Hermitian component that
exactly zeroes out the spin-flip Fock matrix elements, making it impossible for the
SCF to develop any order with $\langle c^\dagger_\uparrow c_\downarrow \rangle \neq 0$.

In practice this means:

• xy-plane SDW / non-collinear magnetism: completely inaccessible — the SCF always
  converges to a collinear (z-axis) or paramagnetic state regardless of parameters.
• z-axis AFM (e.g. honeycomb Hubbard, cubic Hubbard): unaffected, because those
  states only require diagonal spin occupations.

The bug was compounded by eigen(Hermitian(H)) in the diagonalizer, which silently
discards any non-Hermitian residual instead of raising an error, so no warning was ever
emitted.

The fix

The correct symmetric form, which defines both $V_{\uparrow\uparrow\downarrow\downarrow}$
and $V_{\downarrow\downarrow\uparrow\uparrow}$ with equal weight, is:

(qn1.spin == qn2.spin) && (qn3.spin == qn4.spin) && (qn1.spin !== qn3.spin) ? U/2 : 0.0

The total Hubbard energy $U \sum_i n_{i\uparrow} n_{i\downarrow}$ is unchanged (both
terms contribute U/2 each, summing to U).

This fix has been applied to all Hubbard interaction definitions in the codebase:
examples/SM_AFM, examples/Cubic_AFM, examples/SDW_CDW, examples/KMH,
test/test_hartreefock_real.jl, and the docstring example in operators.jl.

New safeguard: H_eff Hermiticity check

solve_hfk now checks the Hermiticity of H_eff at the first SCF iteration and raises
an informative error immediately if the interaction definition is asymmetric:

ERROR: H_eff is not Hermitian at k-point 1: ||H - H†|| = 2.34, ||H|| = 3.12.
Check your interaction definition (e.g. asymmetric Hubbard U).

This ensures the bug cannot recur silently in user-defined Hamiltonians.

---

New Example: Kane-Mele-Hubbard Model

Added examples/KMH/ reproducing Figs. 5 and 6 of Rachel & Le Hur, Phys. Rev. B 82,
075106 (2010):

• Band structure (run.jl → bands.dat): non-interacting Kane-Mele bands for
  $\lambda/t \in {0.05, 0.2, 0.5, 1.0}$ along $K \to \Gamma \to K' \to K \to M \to \Gamma$.
• SDW order parameter (res.dat): xy-plane Néel order $m^\text{Néel}_{xy}$ vs $U$
  for $\lambda \in {0, 0.2, 0.4, 0.6, 0.8, 1.0}$, using a high-to-low $U$ warm-start scan.
• Phase boundary (plot.jl): $U_c$ vs $\lambda$, showing the topological insulator
  to SDW transition.

The example required the bug fix above — xy-plane SDW is completely invisible with the
asymmetric interaction definition.

---

Other Changes

• All examples split into run.jl / plot.jl: run.jl performs the HF computation
  and saves res.dat; plot.jl reads res.dat and generates figures independently.
  This avoids re-running expensive calculations just to adjust a figure.
• All figures moved to docs/src/fig/ for unified documentation asset management.
• Added examples/Cubic_AFM/: finite-temperature AFM transition on the simple cubic
  lattice, reproducing Néel temperature vs $U/t$.
• Documentation: added pages for Cubic_AFM and KMH examples.

---

Migration Guide for v0.2.x Users

If you have any code that defines an on-site Hubbard interaction, replace:

# OLD (v0.2.x) — WRONG for non-collinear order
(qn1.spin, qn2.spin, qn3.spin, qn4.spin) == (1, 1, 2, 2) ? U : 0.0

with:

# NEW (v0.3.0) — correct
(qn1.spin == qn2.spin) && (qn3.spin == qn4.spin) && (qn1.spin !== qn3.spin) ? U/2 : 0.0

Results for purely collinear (z-axis) ordered phases are numerically identical. Results
for paramagnetic phases are identical. Only calculations targeting xy-plane or
non-collinear order are affected.

v0.2.2

MeanFieldTheories v0.2.2

Diff since v0.2.1

What's New in v0.2.2

Makie Visualization Extension

A new weak-dependency extension ext/MakieExt.jl enables visualization through
any Makie backend. Load CairoMakie, GLMakie, or WGLMakie before calling
the plot functions — no mandatory Makie dependency is added to the package.

plot_magnetization(mags, positions; kwargs...)

Visualizes local magnetic moments from a converged Hartree-Fock calculation in a
single top-view panel encoding all three spin components simultaneously:

• Arrow — direction and length encode the in-plane component $(m_x, m_y)$
• ⊙ dot — $m_z > 0$ (spin out of page), size proportional to $|m_z|$
• ⊗ cross — $m_z < 0$ (spin into page), size proportional to $|m_z|$

Compatible with both solve_hfr (real-space) and solve_hfk (momentum-space) results.

plot_lattice(lattice; kwargs...)

Visualizes a tiled Lattice with full styling control:

• Multiple bond sets with independent colors, line widths, and line styles
• Site coloring grouped by any DOF label (e.g. site_groupby = :sub)
• Legend placed in a separate column, never overlapping the data

New Analysis Functions (src/groundstate/analysis.jl)

Function	Description
local_magnetization(dofs, G)	Extract per-site spin vectors $(m_x, m_y, m_z)$ from an HF density matrix; supports both HFr and HFk; optional label-based filtering via keyword arguments
print_magnetization(mags)	Tabular display of $n,, m_x,, m_y,, m_z,,

Examples

A new example script examples/Plot_magnetization/run.jl demonstrates three
representative magnetic orders:

1. Square-lattice Néel AFM — pure $z$ polarization; only ⊙/⊗ markers
2. Triangular-lattice 120° Néel — pure in-plane order; only arrows
3. Canted 120° Néel under uniform field — all three components present simultaneously

Other Changes

• examples/SDW_CDW/run.jl — phase-diagram plot migrated from Plots.jl to CairoMakie
• examples/Plot_Lattice/run.jl — rewritten to call plot_lattice()
• docs/src/plot_lattice.md renamed to docs/src/plot.md; extended with a
  plot_magnetization section and output figures for all three example cases

v0.2.1

Release Note

New Features

generate_onebody — Modernized API

• Symbol-based order argument: now uses (cdag, :i, c, :j) syntax (consistent with generate_twobody)
• Automatic operator reordering via _reorder_to_ca_alternating_with_two_positions
• Automatic h.c. suppression for on-site terms (same site for both labels → no double-counting of chemical potential)
• Proper h.c. construction by conjugating operator types

energy_bands — New function

Compute HF band energies along arbitrary k-path from a converged density matrix:

bands, H_q = energy_bands(dofs, onebody, twobody, kgrid, G_k, qpoints)

Returns (d × Nq) band matrix and the full Hamiltonian along the path.

Symmetry-breaking warmup restarts (solve_hfk / solve_hfr)

Two new keyword arguments to escape SCF saddle points:

• field_strength::Float64 — amplitude of a per-restart random Hermitian field injected into H_eff during early iterations
• n_warmup::Int (default 15) — number of iterations over which the field linearly decays to zero

Allows unbiased discovery of ordered phases (QAH, AFM, SDW, CDW, …) without hand-crafted initial conditions:

result = solve_hfk(dofs, onebody, twobody, kpoints, n_elec;
                   n_restarts=5, field_strength=1.0, n_warmup=15)

Improved initialize_green_k

Replaced old Hamiltonian-based initialization with random unitary + random fractional occupations scaled to target filling.

Documentation

• New page: HF Introduction — condensed-matter derivation, SCF dynamics geometry, basin-steering mechanism
• Updated hartreefock_momentum.md — added "⚠️ Critical Pitfall" section on SCF saddle-point trapping
• Rewritten SM_AFM.md and SDW_CDW.md — general field_strength workflow, no biased initialization

Examples

• SM_AFM/run.jl: single solve_hfk call, no hand-crafted initial states
• SDW_CDW/run.jl: phase determined from $S_q$ vs $N_q$ comparison

Full Changelog: v0.2.0...v0.2.1

v0.2.0

MeanFieldTheories v0.2.0

Diff since v0.1.0

Breaking changes

• Lattice API overhaul:
  • supercell_vectors renamed to vectors in Lattice.
  • Tiling constructor signature changed from Lattice(unitcell, vectors, box_size) to Lattice(unitcell, box_size).
  • unitcell.vectors must be set before tiling; code that passed vectors directly must be updated.
• Bond generation logic reworked (QuantumLattices-style):
  • Switched from min-image heuristics to explicit tiling + distance-shell selection.
  • Cross-cell bonds now use explicit periodic images and record icoordinates accordingly.
  • Neighbor-order bonds and distance-specified bonds now use a unified distance-shell definition.
• Momentum-space HF kernel updates:
  • Removed legacy 1/2 prefactors in self-energy accumulation (Cases A/B/C and Uk path).
  • Clarified real-space formulation vs FFT wording; numerical results may differ vs v0.1.0.
• Project layout changes:
  • benchmark/ migrated to examples/ (new entry points, paths, and outputs).
  • Docs/examples expanded accordingly; any scripts referencing old benchmark/ paths must be updated.

Other changes

• generate_onebody now supports 1-site bonds (onsite terms) in addition to 2-site bonds.
• Added example: examples/SM_AFM (AFM on honeycomb lattice with bands + order parameter).
• Added example: examples/SDW_CDW (extended Hubbard phase diagram; includes output data and figures).
• Added visualization helper: examples/Plot_Lattice/plot_lattice.jl (optional Plots.jl usage).
• Documentation updated:
  • New example pages: SDW_CDW.md, SM_AFM.md, plot_lattice.md.
  • Added figures under docs/src/fig/.
  • Updated home page and contents list to include the new examples.

Merged pull requests:

• Bump julia-actions/cache from 2 to 3 (#3) (@dependabot[bot])

Closed issues:

• Register package (#2)

v0.1.0

MeanFieldTheories v0.1.0

Merged pull requests:

• Bump actions/checkout from 4 to 6 (#1) (@dependabot[bot])