Dispersion and Response

Last changes: Documentation changelog

1. Contract and scope

This page records the dispersion-curve (SaveDispersion) and frequency-response (SaveResponse) output descriptors attached to Eigenmodes and FrequencyResponse studies.

2. Governing equations

Response and dispersion definitions belong to Frequency-domain solvers and Eigensolvers. SaveDispersion publishes \(\omega_b(\mathbf k_s)\) and tracked branch tables (eigen/branches.v2.json and eigen/dispersion.csv), while SaveResponse publishes steady-state dynamic susceptibility and complex response fields \(\delta\mathbf m(\omega)\).

3. Symbols and SI units

Eigenfrequency values are in hertz (\(\mathrm{Hz}\)), wave vectors in \(\mathrm{rad\,m^{-1}}\), and response observables carry the SI units of their physical definition.

4. Assumptions and validity

Response observable identifiers and dispersion names are validated immediately upon construction and checked for stage compatibility during planning (validate_eigen_outputs).

5. Python API

Python

Type

Default

SI unit

Validation

Meaning

Backend support

ProblemIR

SaveDispersion.name

str

"dispersion"

\(1\)

Non-empty

Curve name

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

dispersion_curve.name

SaveDispersion.include_branch_table

bool

True

\(1\)

Boolean

Include branch table

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

dispersion_curve.include_branch_table

SaveResponse.observable

str

required

\(1\)

One of the supported response observables

Response output

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

frequency_response_output.observable

Supported response observables include susceptibility_tensor, m_complex, u_complex, strain_complex, stress_complex, absorbed_power_density, response_amplitude, response_phase, and mode_hybridization_index.

Complete stage-first example

# %% Frequency response with a susceptibility observable
import fullmag as fm

nm = 1.0e-9

study = fm.study("dispersion_response_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_response("susceptibility_tensor")
study.stages.add_frequency_response(
    frequencies_hz=[1.0e9, 2.0e9],
    excitation_field_au_per_m=(0.0, 1.0, 0.0),
    equilibrium_source="relax",
)

6. ProblemIR

SaveDispersion.to_ir() emits dispersion_curve; SaveResponse.to_ir() emits frequency_response_output. Both are carried in the study’s 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. Unknown response observables fail immediately; dispersion names are preserved without interpretation.

8. Discrete realization

Response materialization follows the frequency-domain solvers; dispersion follows the modal eigensolver and track_branches (crates/fullmag-runner/src/eigen/tracking.rs).

9. Implementation mapping

Class

Repository path

Stable symbol

Responsibility

Dispersion output

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

class SaveDispersion

Dispersion curve and branch-table output request

Response output

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

class SaveResponse

Driven frequency-response observable request

Branch tracking

crates/fullmag-runner/src/eigen/tracking.rs

track_branches

Mass-weighted Hungarian dispersion branch tracking

10. Validation

Ownership tests compare this inventory with live signatures.

11. Limitations

Requesting an output does not guarantee the solver materializes it; planner and solver capability resolution are authoritative.

12. Scientific bibliography

Definitions belong to Frequency-domain solvers and Eigensolvers.

Control Room crosswalk

Status: Spectral dispersion and driven response inspection are implemented as inspection-only result views, while stage output selectors (Outputs) are partial and unsupported raw output serialization formats remain not implemented in the form editor.

Python/API surface

Control Room path

Status

Transaction

Dispersion & response output specs (SaveDispersion, SaveResponse)

Model Explorer -> Stages -> <stage> -> Outputs (StudyStageDraftEditor)

partial

Submit stage draft; output resources are revised after execution

Dispersion curves, tracked branches, & \(S(k,f)\) heatmaps

Analysis Plots (EigenDispersionInspectorPanel, DynamicStructureFactorView, SpinWaveGammaView)

inspection-only

Readback from /v2/sessions/current/analysis/spin-wave/* and SolutionSet (decimated heatmaps disclose bounding explicitly)

Driven FMR curves & resonance peak tables

Analysis Plots (FmrResponseSweepInspectorPanel, FmrPeakInspector, FrequencyResponseChart)

inspection-only

Readback from /v2/sessions/current/analysis/frequency-response/* and interactive peak selection

Saved multi-run dispersion / spectrum comparison

Results Navigator (SavedResultsBrowser)

inspection-only

Offline comparison across materialized SolutionSet revisions

Output formatting flags without a named UI field

Model Explorer -> Stages -> <stage> -> Outputs

not implemented

Python-only until implemented

Spin-wave dispersion, Dynamic Structure Factor S(k,f) heatmap, and FMR spectrum inside Control Room Analysis Plots Saved Results Navigator comparing historical SolutionSet runs and spectral overlays

not implemented: frontend support for output parameters not rendered by the autosave/result inspectors. See Control Room capability register, Planar Monitors & Frequency-Domain Inspectors, and Charts & Playback. Frontend source owners: apps/control-room/src/shared/domain/analysis/frequencyDomainChartModels.ts (buildEigenDispersionChartModel, buildFrequencyResponseChartModel), EigenDispersionInspectorPanel, DynamicStructureFactorView, and SavedResultsBrowser.

13. Source-code index

Claim

Path

Stable symbol

Responsibility

Evidence

Dispersion output request validation and lowering.

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

class SaveDispersion

Dispersion output request validation and lowering.

Source-map validator and focused API tests

Response output request validation and lowering.

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

class SaveResponse

Response output request validation and lowering.

Source-map validator and focused API tests

Branch tracking across k-paths.

crates/fullmag-runner/src/eigen/tracking.rs

track_branches

Mass-weighted Hungarian mode branch tracking.

Rust runner source