mag4.magnon
Multi-sublattice linear spin-wave theory (LSWT) and Tyablikov RPA.
Hamiltonian convention: H = +Σ_{i≠j} J_ij S_i·S_j (AFM: J > 0, FM: J < 0).
Inputs are JS² in meV·S² (multiply VASP eV values by 1000).
Public API
from mag4.magnon import (
get_sublattice_bonds, build_qmesh, auto_qmesh,
build_jq_matrices, compute_eigenvalues_all_q,
analyse_ordering, compute_tc, compute_tc_lswt,
get_kpath, compute_magnon_dispersion, plot_magnon_bands,
)
- mag4.magnon.get_inequivalent_sites(cif_path, element)[source]
Group magnetic sites into crystallographically inequivalent classes.
Uses
pymatgen.symmetry.analyzer.SpacegroupAnalyzerto derive Wyckoff orbits and returns one list of global site indices per class.
- mag4.magnon.get_sublattice_bonds(cif_path, element, cutoff, shells, j_values, tol=0.01)[source]
Build the bond table for the full
N_mag × N_magprimitive-cell exchange matrix.Every magnetic atom is treated as its own sublattice. The reciprocal-space exchange matrix is
\[J_{αβ}(q) = Σ_{\text{images}} J_n · \exp(i\,q · r_{αβ,\text{image}})\]
- mag4.magnon.build_qmesh(structure, na, nb, nc)[source]
Γ-centred uniform q-mesh over the full primitive BZ.
- mag4.magnon.auto_qmesh(structure, target_points=125000)[source]
Anisotropy-adapted q-mesh targeting ~``target_points`` q-points.
- mag4.magnon.build_jq_matrices(bond_data, q_points)[source]
Compute \(J_{αβ}(q) = Σ_{\text{bonds}(α,β)} JS²_n · e^{i\,q · r_{αβ}}\).
Returns a complex array of shape
(N_q, N_sub, N_sub).
- mag4.magnon.compute_eigenvalues_all_q(Jq)[source]
Diagonalise the Hermitian J(q) at every q.
Returns a real array
(N_q, N_sub)of eigenvalues sorted descending. Used for T_c and q₀ search; the magnon dispersion uses the LSWT dynamical matrix instead (seemag4.magnon.dispersion).
- mag4.magnon.analyse_ordering(Jq, evals, q_frac, q_cart, structure)[source]
Find
q₀ = argmin λ_min(q)and characterise the magnetic ordering.The output dict contains:
idx0, q0_cart, q0_frac, lam0, eigvec, ratios, character, sc_dims, commensurate.- Return type:
- mag4.magnon.get_spin_dirs_from_q0(bond_data, q0_frac)[source]
Assign collinear spin directions in the primitive cell from the ordering wavevector.
\[s_α = \mathrm{sign}\bigl(\cos(2π\,q₀ · r_α)\bigr)\]where
r_αis the fractional coordinate of site α. This is the TB2J strategy: the LSWT dynamical matrix is then built directly in the primitive cell, giving exactlyn_submagnon branches with a Goldstone mode atk = q₀. No supercell replication is required.
- mag4.magnon.compute_tc(evals, S, lam0)[source]
Mean-field and Luttinger–Tisza Tyablikov RPA critical temperature.
Both estimates use the Hermitian J(q) eigenvalue spectrum sampled on the BZ grid.
Returns a dict with keys
Tc_MF, Tc_RPA, note.- Return type:
- mag4.magnon.compute_tc_lswt(bond_data, S, ordering_lt, q_cart, evals_lt)[source]
Method-2 T_c, chosen based on q₀.
- Return type:
- Parameters:
- q₀ ≈ Γ (FM / type-I AFM)
LSWT is exact in the primitive cell. Build \(D^{ord}\) with \(s_α = \mathrm{sign}(v_α)\) and apply the Tyablikov RPA to the acoustic (lowest) magnon branch:
k_B T_c^{LSWT-RPA} = (S+1)/(3S) / ⟨1/ω_0(q)⟩_{ω_0 > 0}- q₀ ≠ Γ (commensurate or incommensurate ordering)
\(D^{ord}\) in the primitive cell has negative eigenvalues because \(s_α = \mathrm{sign}(\cos 2π q₀·r_α)\) is not the exact collinear ground state for q₀ ≠ Γ. Use the LT acoustic-branch RPA — Tyablikov RPA applied to
λ_min(q)directly:k_B T_c^{LT-ac-RPA} = (S+1)/(3S) / ⟨1/(λ_min(q₀) − λ_min(q))⟩_{q ≠ q₀}
- mag4.magnon.get_kpath(structure, n_points=100, custom_labels=None)[source]
Generate a high-symmetry k-path using pymatgen
HighSymmKpath.- Parameters:
- Returns:
Keys:
kpoints_cart, kpoints_frac, distances, tick_positions, tick_labels, break_indices, prim_rec_matrix, hs_frac.- Return type:
- mag4.magnon.compute_magnon_dispersion(bond_data, kpath, S, ordering)[source]
Compute the magnon dispersion in the primitive cell.
\[ω_k(q) = 2S × \bigl(λ_k(J(q)) − λ_{\min}(q_0)\bigr)\]where
λ_k(J(q))are the eigenvalues of the Hermitian exchange matrix at each k-point along the path, sorted ascending. This gives exactlyn_subbranches in the primitive BZ for any ordering wavevector q₀. The Goldstone mode (ω = 0) is atk = q₀by construction of the shift, so no supercell or spectral unfolding is needed.
- mag4.magnon.plot_magnon_bands(magnon_bands, kpath, S, n_sub, name)[source]
Plot the magnon band structure and save to
<name>_magnon_bands.png.Returns the output path, or
""if matplotlib is unavailable.
- mag4.magnon.print_report(shells, j_values, bond_data, evals, ordering_lt, tc_lt, tc_sw, S, qmesh, structure, output_file, j_values_note=None)[source]
Pretty-print the LSWT/RPA report and write it to
output_file.j_values_note(optional): provenance lines printed directly under the exchange-parameter table — e.g. the--jringring-renormalisation record, so effective couplings are never shown without their origin.
Modules
Magnon dispersion via the eigenvalues of J(q) in the primitive cell. |
|
Reciprocal-space exchange matrix J(q) and its eigenvalue spectrum. |
|
High-symmetry k-path generation (auto via pymatgen, or user-supplied label string). |
|
Ground-state ordering analysis: Luttinger-Tisza q₀ and spin direction assignment. |
|
Magnon band-structure plotting (matplotlib, optional). |
|
q-point grid generation for the BZ scan. |
|
Magnon / spin-wave report (textual summary written to disk). |
|
Inequivalent magnetic sites and bond table for the multi-sublattice exchange matrix. |
|
Critical temperature (mean-field and Tyablikov RPA) from J(q). |