Eigenmodes¶
Last changes: Documentation changelog
1. Contract and scope¶
fm.Eigenmodes and study.stages.add_eigenmodes(...) define the public Python authoring contract
for linearized spin-wave eigenmode studies around a verified micromagnetic equilibrium
\(\mathbf m_0(\mathbf x)\). Together with the companion schemas FemEigenSolverPolicy, KPoint,
KPath, BiasFieldSweep, and ModeTracking, this study type configures single-\(\mathbf k\)
resonances, Brillouin-zone magnonic dispersion relations \(f_n(\mathbf k)\), and static bias-field
ferromagnetic resonance sweeps \(f_n(\mathbf B_0)\).
Full mathematical derivations of the tangent-plane projection, coupled \((q,\phi)\) Poisson-airbox Schur complement, real-split SLEPc shift-and-invert, and consistent-\(P_1\) mass-weighted Hungarian branch tracking are given in Linearized LLG eigenvalue problem and Modal validation and dispersion qualification.
2. Governing equations¶
The modal study solves the tangent-projected generalized eigenvalue problem around \(\mathbf m_0\):
where operator="linearized_llg" selects the scalar projected \(N_m\times N_m\) operator along the
primary tangent axis \(\mathbf e_1\), and operator="full_2x2" selects the coupled \(2N_m\times 2N_m\)
Herring–Kittel tangent-plane block pencil in \((\mathbf e_1, \mathbf e_2)\) required for elliptical
precession, coupled Poisson-airbox magnetostatics (include_demag=True), and nonzero Bloch wave
vectors (\(\mathbf k \neq \mathbf 0\)).
3. Symbols and SI units¶
Symbol |
Meaning |
SI unit |
|---|---|---|
\(\mathsf K\) |
tangent rate-stiffness dynamic matrix (or \(\mathrm{J}\) in energy-Hessian form) |
\(\mathrm{s^{-1}}\) |
\(\mathsf G\) |
damping-modified tangent metric \(I - \alpha_{\mathrm{eff}}J\) (or \(\mathrm{J\,s}\) in energy-Hessian form) |
\(1\) |
\(\mathbf q\) |
discrete tangent eigenvector |
\(1\) |
\(\lambda\) |
complex eigenvalue |
\(\mathrm{s^{-1}}\) |
\(\sigma\) |
modal growth/decay real part |
\(\mathrm{s^{-1}}\) |
\(\omega\) |
angular frequency |
\(\mathrm{rad\,s^{-1}}\) |
\(f\) |
eigenfrequency |
\(\mathrm{Hz}\) |
4. Assumptions and validity¶
countmust be a positive integer (\(K \ge 1\)).target="nearest"requires a positivetarget_frequency(in \(\mathrm{Hz}\)).target="frequency_window"requires bothfrequency_minandfrequency_maxwith \(0 < f_{\min} < f_{\max}\).outputsmust include at least one modal output (SaveMode,SaveSpectrum,SaveDispersion, orSaveEigenDiagnostics); drivenSaveResponseoutputs are rejected onEigenmodes.
5. Python API and complete parameter reference¶
Complete stage-first example¶
# %% Stage-first FEM modal study with Schur-complement policy and branch tracking
import fullmag as fm
nm = 1.0e-9
study = fm.study("eigenmodes_api_example")
study.engine("fem")
study.device("cpu", precision="double")
study.mode("strict")
study.universe(mode="manual", size=(400 * nm, 150 * nm, 100 * nm))
film = study.geometry(fm.Box(size=(100 * nm, 20 * nm, 5 * nm), name="film"), name="film")
film.Ms = 800.0e3
film.Aex = 13.0e-12
film.alpha = 0.01
film.m = fm.init.UniformMagnetization((1.0, 0.0, 0.0))
study.exchange()
study.zeeman(field=(5.0e4, 0.0, 0.0))
study.demag(model="airbox", variant="robin")
study.stages.add_relax(stage_id="relax", algorithm="nonlinear_cg", max_steps=2000, tolT=1e-7)
# %% Add eigenmodes stage with k-path dispersion and mode tracking
study.stages.add_eigenmodes(
stage_id="eigen_dispersion",
count=8,
target="nearest",
target_frequency=8.0e9,
operator="full_2x2",
include_demag=True,
equilibrium_source="relax",
normalization="unit_l2",
damping_policy="ignore",
spatial_representation="full_3d",
k_sampling=fm.KPath(
nodes=[
("Gamma", (0.0, 0.0, 0.0)),
("X", (3.14159265e7, 0.0, 0.0)),
],
samples_per_segment=12,
),
mode_tracking=fm.ModeTracking(
method="overlap_hungarian",
min_overlap=0.6,
degeneracy_tolerance=1.0e6,
),
fem_solver_policy=fm.FemEigenSolverPolicy(
backend="slepc_shift_invert_schur",
subspace_dimension=24,
max_iterations=250,
tolerance=1.0e-8,
shift_Hz=8.0e9,
target_spectrum="target_magnitude",
),
)
Eigenmodes parameters¶
Python |
Type |
Default |
SI unit |
Validation |
Meaning |
Backend support |
ProblemIR |
|---|---|---|---|---|---|---|---|
|
|
|
\(1\) |
At least one; |
Mode/spectrum/dispersion/diagnostic outputs |
FDM/FEM CPU/GPU; planner checks materialization |
|
|
|
|
\(1\) |
Positive |
Number of eigenvectors requested |
FEM/FDM CPU/GPU |
|
|
|
|
\(1\) |
|
Eigenvalue selection policy |
FEM/FDM CPU/GPU |
|
|
|
|
\(\mathrm{Hz}\) |
Positive; required for |
Frequency target for nearest modes |
FEM/FDM CPU/GPU |
|
|
|
|
\(\mathrm{Hz}\) |
Positive lower bound; required with |
Lower frequency-window bound |
FEM/FDM CPU/GPU |
|
|
|
|
\(\mathrm{Hz}\) |
Positive upper bound; |
Upper frequency-window bound |
FEM/FDM CPU/GPU |
|
|
|
|
\(1\) |
|
Linearized operator |
FEM/FDM CPU/GPU |
|
|
|
|
\(1\) |
Boolean |
Include the dynamic demagnetization term |
FEM/FDM CPU/GPU |
|
|
|
|
\(1\) |
|
Equilibrium acquisition |
FEM/FDM CPU/GPU |
|
|
|
|
\(\mathrm{rad\,m^{-1}}\) |
Valid k sampling or k vector |
Wave-vector sampling |
FEM/FDM CPU/GPU |
|
|
|
|
\(\mathrm{A\,m^{-1}}\) |
Non-empty finite field list |
Static bias-field sweep |
FEM modal lane |
|
|
|
|
\(1\) |
Validated tracking policy |
Mass-weighted Hungarian mode tracking |
FEM modal runner |
|
|
|
|
\(1\) |
|
Mode normalization |
FEM/FDM CPU/GPU |
|
|
|
|
\(1\) |
|
Damping treatment |
FEM/FDM CPU/GPU |
|
|
|
|
\(1\) |
One of |
Spin-wave boundary condition |
FEM/FDM CPU/GPU |
|
|
|
|
\(1\) |
|
Spatial operator geometry |
FEM modal lane |
|
|
|
|
\(1\) |
Validated FEM eigensolver policy |
Native eigensolver configuration |
FEM modal lane |
|
Companion policy and sampling schemas¶
Class |
Field |
Type |
Default |
SI unit |
Meaning |
|---|---|---|---|---|---|
|
|
|
|
\(1\) |
|
|
|
|
|
\(1\) |
Krylov-Schur subspace dimension (\(\ge 2\) and \(\ge \mathrm{count}\)) |
|
|
|
|
\(1\) |
Maximum outer eigensolver restart cycles |
|
|
|
|
\(1\) |
Relative coupled residual convergence tolerance |
|
|
|
|
\(\mathrm{Hz}\) |
Spectral shift frequency \(\tau/(2\pi)\) for shift-and-invert |
|
|
|
|
\(1\) |
|
|
|
|
|
\(\mathrm{rad\,m^{-1}}\) |
Single Brillouin-zone wave vector \((k_x, k_y, k_z)\) |
|
|
|
|
\(\mathrm{rad\,m^{-1}}\) |
Ordered high-symmetry vertices along the dispersion path |
|
|
|
|
\(1\) |
Number of wave-vector samples per path segment |
|
|
|
|
\(\mathrm{A\,m^{-1}}\) |
Static external magnetic bias-field samples |
|
|
|
|
\(1\) |
Combinatorial branch assignment algorithm |
|
|
|
|
\(1\) |
Minimum consistent-\(P_1\) mass-weighted overlap threshold in \((0, 1]\) |
|
|
|
|
\(\mathrm{Hz}\) |
Frequency window for SVD Procrustes degenerate-subspace transport |
6. ProblemIR¶
Eigenmodes.to_ir() emits {"kind": "eigenmodes", ...} with operator, equilibrium, target,
count, k_sampling, bias_field_sweep, mode_tracking, normalization, damping_policy,
spin_wave_bc, spatial_representation, fem_solver_policy, and sampling.
7. Round-trip and failure semantics¶
Requested intent is the value authored by Python and preserved in ProblemIR; resolved execution is
the planner or realization result (FemEigenPlanIR). Validation errors identify the violated domain
rule, and unsupported combinations are rejected explicitly rather than silently substituted.
8. Discrete realization¶
Solver execution follows Linearized LLG eigenvalue problem: plan_fem_eigen
resolves FemEigenPlanIR, EigenKProcessPool isolates PETSc/SLEPc worker processes across
\(\mathbf k\)-points, solve_poisson_airbox_modal_eigen_cpu_schur solves the matrix-free Schur
complement, evaluate_poisson_airbox_modal_residuals certifies coupled \((q,\phi)\) residuals, and
track_branches / mass_weighted_subspace_transport track branches across \(\mathbf k\) or bias-field
sweeps.
9. Implementation mapping¶
Layer |
Owner |
Responsibility |
|---|---|---|
Python authoring |
|
Schema validation and |
Rust planner |
|
Capability check and |
Rust runner |
|
Multi-process \(\mathbf k\)-pool and consistent-\(P_1\) branch tracking |
Native C++ solver |
|
Shared-domain \((q,\phi)\) assembly, Schur shift-and-invert, and residual certification |
10. Validation¶
Constructor and round-trip tests verify Eigenmodes, FemEigenSolverPolicy, KPath,
BiasFieldSweep, and ModeTracking serialization, while scientific qualification follows
Modal validation and dispersion qualification.
11. Limitations¶
Authoring support is broader than any single backend’s resolved modal capability; the planner rejects
unsupported combinations (plan_fem_eigen) without silent fallback.
12. Scientific bibliography¶
C. Herring and C. Kittel, “On the theory of spin waves in ferromagnetic media,” Physical Review, 81, 869–880 (1951).
M. d’Aquino, C. Serpico, G. Miano, and C. Forestiere, “A novel formulation for the numerical computation of magnetization modes in complex micromagnetic systems,” Journal of Computational Physics, 228, 6130–6149 (2009).
13. Source-code index¶
Control Room crosswalk¶
Status: Eigenmode stage creation, dispersion inspection, and 3D spatial mode playback are partial; low-level FemEigenSolverPolicy matrix-free/Schur solver tuning and arbitrary \(k\)-path builders without matching fields remain not implemented in the stage draft form.
Python/API surface |
Control Room path |
Status |
Transaction |
|---|---|---|---|
Stage mode count, shift/target, & basic \(k\)-sampling |
|
|
Submit stage draft via |
Tracked \(\omega(k)\) dispersion plot & branch table |
|
|
Selecting a dispersion point or branch synchronizes explorer, inspector, and 3D target |
Spatial eigenmode profile, phase slider (\(0\text{–}2\pi\)), & complex projection |
|
|
UI visualization commands ( |
Advanced |
|
|
Python-only until implemented |
See Control Room capability register, Study Authoring, Stages & Interactive Re-Execution, and Planar Monitors, Dispersion & Frequency-Domain Inspectors.
Frontend source owners: EigenmodesStageInspector, EigenDispersionInspectorPanel, ModeVisualizationInspectorPanel, and StudyStageDraftEditor.
Source-code index¶
Repository path |
Stable symbol |
Responsibility |
|---|---|---|
Eigenmode study parameters and IR lowering. |
||
Native FEM eigensolver policy schema. |
||
Wave-vector sampling normalization. |
||
Stage-first modal request specification. |
||
Stage-first authoring entrypoint. |
||
Resolves FemEigenPlanIR and capability gates. |
||
Multi-process worker pool for k-path dispersion sweeps. |
||
Mass-weighted Hungarian branch tracking. |
||
SVD Procrustes degenerate-subspace transport. |
||
Consistent P1 finite-element mass inner product. |
||
Native modal eigensolver contract and diagnostics. |
||
|
Shared-domain (q, phi) magnetostatic block assembly. |
|
|
Matrix-free MATSHELL Schur shift-and-invert eigensolver. |
|
|
Reconstructs scalar potential and certifies coupled residuals. |