Modes and Spectra¶
Last changes: Documentation changelog
1. Contract and scope¶
This page records the eigenmode (SaveMode), eigenvalue spectrum (SaveSpectrum), and
eigensolver diagnostic (SaveEigenDiagnostics) output descriptors attached to Eigenmodes
studies.
2. Governing equations¶
Mode and spectrum mathematics belong to Eigensolvers and Linearized LLG eigenvalue problem. Each returned eigenmode \((\lambda_n, \mathbf q_n)\) is reconstructed into 3D magnetization coordinates \(\delta\mathbf m_n = T\mathbf q_n\) and paired with its complex eigenvalue \(\lambda_n = \sigma_n + \mathrm i\omega_n\) (\(f_n = |\omega_n|/(2\pi)\)).
3. Symbols and SI units¶
Spectrum entries are eigenfrequencies in hertz (\(\mathrm{Hz}\)) and decay rates in \(\mathrm{s^{-1}}\); spatial mode fields \(\delta\mathbf m_n\) are dimensionless normalized shape functions (\(1\)), and optional reconstructed magnetostatic potential fields \(\delta\phi_n\) carry units of amperes (\(\mathrm{A}\)).
4. Assumptions and validity¶
Mode index sets (indices or branches) must be non-negative, unique, and non-empty when
selecting explicit subsets; sample selectors (sample_indices or sample_labels) filter which
\(\mathbf k\)-path or bias-field sweep samples persist 3D spatial mode arrays.
5. Python API¶
Python |
Type |
Default |
SI unit |
Validation |
Meaning |
Backend support |
ProblemIR |
|---|---|---|---|---|---|---|---|
|
|
|
\(1\) |
Non-empty |
Mode field name |
FEM/FDM CPU/GPU; planner and runtime capability checks remain authoritative |
|
|
|
|
\(1\) |
Non-negative unique |
Raw mode indices |
FEM/FDM CPU/GPU; planner and runtime capability checks remain authoritative |
|
|
|
|
\(1\) |
Non-negative unique |
Tracked branch indices |
FEM/FDM CPU/GPU; planner and runtime capability checks remain authoritative |
|
|
|
|
\(1\) |
Non-negative unique sample indices |
Select samples by numeric index |
FEM/FDM CPU/GPU; planner and runtime capability checks remain authoritative |
|
|
|
|
\(1\) |
Non-empty sample labels |
Select samples by label |
FEM/FDM CPU/GPU; planner and runtime capability checks remain authoritative |
|
|
|
|
\(1\) |
Non-empty |
Spectrum quantity |
FEM/FDM CPU/GPU; planner and runtime capability checks remain authoritative |
|
|
|
|
\(1\) |
|
Spectrum scope |
FEM/FDM CPU/GPU; planner and runtime capability checks remain authoritative |
|
|
|
|
\(1\) |
Boolean |
Diagnostic flags |
FEM/FDM CPU/GPU; planner and runtime capability checks remain authoritative |
|
Complete stage-first example¶
# %% Eigenmodes with spectrum, mode, and diagnostic outputs
import fullmag as fm
nm = 1.0e-9
study = fm.study("modes_spectra_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.02
film.m = fm.init.UniformMagnetization((1.0, 0.0, 0.0))
study.exchange()
study.demag(model="airbox", variant="robin")
study.stages.add_relax(stage_id="relax", algorithm="nonlinear_cg", max_steps=1000, tolT=1e-6)
study.save("spectrum")
study.save("mode", indices=[0, 1, 2])
study.stages.add_eigenmodes(count=8, target="lowest", equilibrium_source="relax")
6. ProblemIR¶
SaveMode.to_ir(), SaveSpectrum.to_ir(), and SaveEigenDiagnostics.to_ir() emit
eigen_mode, eigen_spectrum, and eigen_diagnostics records inside sampling.outputs.
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. Validation errors identify the violated domain rule, and
unsupported combinations are rejected explicitly rather than silently substituted. Duplicate or
negative mode/branch indices, an empty selection, and invalid scopes fail immediately.
8. Discrete realization¶
Materialization follows the native FEM modal eigensolver (eigen/spectrum.v2.json,
frequency_domain/manifest.v1.json, and binary mode/potential payloads).
9. Implementation mapping¶
Class |
Repository path |
Stable symbol |
Responsibility |
|---|---|---|---|
Mode output |
|
Spatial eigenmode selection and IR lowering |
|
Spectrum output |
|
Eigenfrequency spectrum selection and IR lowering |
|
Diagnostics output |
|
Modal solver residual and KSP diagnostic flags |
10. Validation¶
Ownership tests compare this inventory with live signatures and validate_eigen_outputs in
crates/fullmag-plan/src/validate.rs.
11. Limitations¶
Output availability depends on the eigensolver realization and equilibrium source.
12. Scientific bibliography¶
Mode and spectrum definitions belong to Linearized LLG eigenvalue problem.
Control Room crosswalk¶
Status: Mode-field and spectrum inspection are partial; 3D modal overlays and planar monitor frequency projections are implemented (inspection-only), while stage output toggles not rendered in the inspector remain not implemented.
Python/API surface |
Control Room path |
Status |
Transaction |
|---|---|---|---|
|
|
|
Submit stage draft; output resources are revised after execution |
Planar monitor definitions & frequency-domain spatial cuts |
|
|
Commit monitor geometry to |
3D eigenmode / driven response phasor & spatial profile |
|
|
|
Parameters without a named UI field |
|
|
Python-only until implemented |
not implemented: frontend support for output parameters not rendered by the autosave/result inspectors.
See Control Room capability register and Planar Monitors & Frequency-Domain Inspectors.
Frontend source owners: apps/control-room/src/modules/inspector/panels/StudyStageInspectorRouter.tsx (EigenmodesOutputsStageInspectorPanel), PlanarMonitorInspectorPanel, and ModeVisualizationInspectorPanel.
13. Source-code index¶
Claim |
Path |
Stable symbol |
Responsibility |
Evidence |
|---|---|---|---|---|
Mode-field output selection and lowering. |
|
Mode-field output selection and lowering. |
Source-map validator and focused API tests |
|
Spectrum output selection and lowering. |
|
Spectrum output selection and lowering. |
Source-map validator and focused API tests |
|
Eigen-solver diagnostic output selection and lowering. |
|
Eigen-solver diagnostic output selection and lowering. |
Source-map validator and focused API tests |
|
Planner modal output validation. |
|
Validates modal output requests against study configuration. |
Rust planner source |