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 |
|---|---|---|---|---|---|---|---|
|
|
|
\(1\) |
Non-empty |
Curve name |
FEM/FDM CPU/GPU; planner and runtime capability checks remain authoritative |
|
|
|
|
\(1\) |
Boolean |
Include branch table |
FEM/FDM CPU/GPU; planner and runtime capability checks remain authoritative |
|
|
|
|
\(1\) |
One of the supported response observables |
Response output |
FEM/FDM CPU/GPU; planner and runtime capability checks remain authoritative |
|
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 |
|
Dispersion curve and branch-table output request |
|
Response output |
|
Driven frequency-response observable request |
|
Branch tracking |
|
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 ( |
|
|
Submit stage draft; output resources are revised after execution |
Dispersion curves, tracked branches, & \(S(k,f)\) heatmaps |
|
|
Readback from |
Driven FMR curves & resonance peak tables |
|
|
Readback from |
Saved multi-run dispersion / spectrum comparison |
|
|
Offline comparison across materialized |
Output formatting flags 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, 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. |
|
Dispersion output request validation and lowering. |
Source-map validator and focused API tests |
|
Response output request validation and lowering. |
|
Response output request validation and lowering. |
Source-map validator and focused API tests |
|
Branch tracking across k-paths. |
|
Mass-weighted Hungarian mode branch tracking. |
Rust runner source |