Eigensolvers

Last changes: Documentation changelog

This section documents the numerical eigensolver pipeline used by FullMag to compute small-amplitude spin-wave normal modes, eigenfrequencies \(f_n = \omega_n/(2\pi)\), modal damping rates \(\sigma_n\), spatial mode profiles \(\delta\mathbf m_n(\mathbf x)\), and magnonic dispersion relations \(f_n(\mathbf k)\) around a verified static micromagnetic equilibrium \(\mathbf m_0(\mathbf x)\).

End-to-end modal architecture

The modal solver spans four strictly separated layers with immutable provenance handoffs:

Architectural layer

Primary responsibility

Key source files

Python DSL & ProblemIR

Declares EigenmodesStageSpec, FemEigenSolverPolicy, KPath, BiasFieldSweep, ModeTracking, and validation schemas; lowers to StudyIR::Eigenmodes.

packages/fullmag-py/src/fullmag/model/study.py, packages/fullmag-py/src/fullmag/model/eigen.py, crates/fullmag-ir/src/study.rs

Planner & R4 Handoff Gate

Resolves FemEigenPlanIR, classifies \(\Gamma\)-point vs nonzero-\(\mathbf k\) Bloch/waveguide execution, and enforces converged equilibrium handoff (accepted_relax_handoff_for_eigen_stage).

crates/fullmag-plan/src/fem.rs, crates/fullmag-cli/src/orchestrator.rs

Runner, V6 Certificate & Tracking

Materializes \(\mathbf m_0\), binds the cryptographic V6 certificate, dispatches multi-\(\mathbf k\) worker processes (EigenKProcessPool), and performs consistent-\(P_1\) mass-weighted Hungarian + SVD Procrustes branch tracking.

crates/fullmag-runner/src/fem/eigen_equilibrium.rs, crates/fullmag-runner/src/fem/eigen_certificate.rs, crates/fullmag-runner/src/eigen/k_process_pool.rs, crates/fullmag-runner/src/eigen/tracking.rs

Native C++ MFEM / PETSc / SLEPc

Builds the nodal tangent frame \((\mathbf e_1, \mathbf e_2, \mathbf m_0)\), assembles the coupled \((q,\phi)\) shared-domain blocks, evaluates the matrix-free MATSHELL Schur complement \(S(\tau)\), gates inner shifted KSP residuals, and certifies full coupled eigenpair residuals.

backends/fem/src/frequency_domain/modal_eigen_solver.cpp, backends/fem/cpu/frequency_domain/operators/poisson_airbox_shared_domain.hpp, backends/fem/cpu/frequency_domain/poisson_airbox_schur_matshell.hpp

Chapters in this section

  • Linearized LLG eigenvalue problem — tangent-plane projection, rate-form and energy-Hessian operator pencils, shared-domain \((q,\phi)\) magnetostatic Schur complement, real-split SLEPc shift-and-invert, 3D Floquet vs 2.5D waveguide dispersion operators, and consistent-\(P_1\) branch tracking.

  • Modal validation and dispersion qualification — analytical Kittel ferromagnetic resonance sweep models, Kalinikos–Slavin dipole-exchange thin-film dispersion (\(n=0\)), and coupled \((q,\phi)\) residual qualification gates.