Modes and Spectra

Last changes: Documentation changelog

Contract

This page records the eigenmode, spectrum, and eigen-diagnostics outputs attached to eigenmode studies.

Governing equations

Mode and spectrum mathematics belong to Linearized-LLG eigensolvers.

Symbols and SI units

Spectrum entries are eigenfrequencies in hertz; mode fields and diagnostics follow the eigenmode normalization.

Assumptions and validity

Mode index sets must be non-negative, unique, and non-empty (raw indices or branches).

Python API

Python

Type

Default

SI unit

Validation

Meaning

Backend support

ProblemIR

—

—

—

\(1\)

—

—

FEM/FDM CPU/GPU; planner and runtime capability checks remain authoritative

—

SaveMode.field

str

"mode"

\(1\)

Non-empty

Mode field name

FEM/FDM CPU/GPU; planner and runtime capability checks remain authoritative

eigen_mode.field

SaveMode.indices

Sequence[int]

()

\(1\)

Non-negative unique

Raw mode indices

FEM/FDM CPU/GPU; planner and runtime capability checks remain authoritative

eigen_mode.indices

SaveMode.branches

Sequence[int]

()

\(1\)

Non-negative unique

Tracked branch indices

FEM/FDM CPU/GPU; planner and runtime capability checks remain authoritative

eigen_mode.branches

SaveMode.sample_indices

Sequence[int] | None

None

\(1\)

Non-negative unique sample indices

Select samples by numeric index

FEM/FDM CPU/GPU; planner and runtime capability checks remain authoritative

eigen_mode.sample_indices

SaveMode.sample_labels

Sequence[str] | None

None

\(1\)

Non-empty sample labels

Select samples by label

FEM/FDM CPU/GPU; planner and runtime capability checks remain authoritative

eigen_mode.sample_labels

SaveSpectrum.quantity

str

"eigenfrequency"

\(1\)

Non-empty

Spectrum quantity

FEM/FDM CPU/GPU; planner and runtime capability checks remain authoritative

eigen_spectrum.quantity

SaveSpectrum.scope

str

"per_sample"

\(1\)

global or per_sample

Spectrum scope

FEM/FDM CPU/GPU; planner and runtime capability checks remain authoritative

eigen_spectrum.scope

SaveEigenDiagnostics.*

bool

True

\(1\)

Boolean

Diagnostic flags

FEM/FDM CPU/GPU; planner and runtime capability checks remain authoritative

eigen_diagnostics

Complete stage-first example

# %% Eigenmodes with spectrum and mode outputs
import fullmag as fm

nm = 1.0e-9

study = fm.study("modes_spectra_api_example")
study.engine("fdm")
study.device("cpu", precision="double")
study.mode("strict")

study.objects.mesh.defaults(cell_size=(2 * nm, 2 * nm, 5 * nm))
film = study.geometry(fm.Box(100 * nm, 20 * nm, 5 * nm), 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.stages.add_relax(stage_id="relax", algorithm="projected_gradient_bb", max_steps=1000, tolT=1e-8)
study.save("spectrum")
study.save("mode", indices=[0, 1, 2])
study.stages.add_eigenmodes(count=8, target="lowest", equilibrium_source="relax")

ProblemIR

SaveMode.to_ir(), SaveSpectrum.to_ir(), and SaveEigenDiagnostics.to_ir() emit eigen_mode, eigen_spectrum, and eigen_diagnostics records inside sampling.outputs.

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.

Discrete realization

Materialization follows the eigensolver; mode tracking and diagnostics are emitted when requested.

Implementation mapping

Anchor: packages/fullmag-py/src/fullmag/model/outputs.py (SaveMode, SaveSpectrum, SaveEigenDiagnostics).

Validation

Ownership tests compare this inventory with live signatures.

Limitations

Output availability depends on the eigensolver realization and equilibrium source.

Scientific bibliography

Mode and spectrum definitions belong to the eigensolver pages.

Control Room crosswalk

Status: Table/field autosave and result inspection are partial; unsupported output formats remain not implemented.

Python/API surface

Control Room path

Status

Transaction

Parameters documented on this page

Model Explorer -> Stages -> <stage> -> Autosave

partial

Submit autosave draft; output resources are revised after execution

Parameters without a named UI field

Model Explorer -> Stages -> <stage> -> Autosave

not implemented

Python-only until implemented

not implemented: frontend support for output parameters not rendered by the autosave/result inspectors. See Control Room capability register for the support matrix and not implemented policy. Frontend source owner: apps/control-room/src/modules/inspector/panels/stages/AutosaveStageInspector.tsx (AutosaveStageInspector).

Source-code index

Claim

Path

Stable symbol

Responsibility

Evidence

Eigen outputs

packages/fullmag-py/src/fullmag/model/outputs.py

SaveMode, SaveSpectrum, SaveEigenDiagnostics

Output lowering

Ownership test

Source-map coverage

Claim

Path

Stable symbol

Responsibility

Evidence

Mode-field output selection and lowering.

packages/fullmag-py/src/fullmag/model/outputs.py

class SaveMode

Mode-field output selection and lowering.

Source-map validator and focused API tests

Spectrum output selection and lowering.

packages/fullmag-py/src/fullmag/model/outputs.py

class SaveSpectrum

Spectrum output selection and lowering.

Source-map validator and focused API tests

Eigen-solver diagnostic output selection and lowering.

packages/fullmag-py/src/fullmag/model/outputs.py

class SaveEigenDiagnostics

Eigen-solver diagnostic output selection and lowering.

Source-map validator and focused API tests