Frequency Response¶
Last changes: Documentation changelog
1. Physical problem and solver family¶
fm.FrequencyResponse and study.stages.add_frequency_response(...) define the public Python authoring contract for first-order harmonic steady-state response studies around an accepted equilibrium \(\mathbf{m}_0(\mathbf{r})\) at prescribed drive frequencies \(\{f_j\}\).
Solver mathematics, Schur-complement elimination, and algebraic residual qualification are documented in Frequency-domain solvers and Driven frequency-response solver.
2. Governing equations¶
For a small harmonic excitation field \(\delta\mathbf{h}_{\mathrm{ext}}(\mathbf{r}, t) = \Re\{\widehat{\mathbf{h}}_{\mathrm{ext}}(\mathbf{r})\,\mathrm{e}^{\mathrm{i}\omega t}\}\) at angular frequency \(\omega = 2\pi f\), the linearized tangent-plane response \(\widehat{\mathbf{q}}(\omega)\) satisfies the forced linear system:
3. Symbols and SI units¶
Symbol |
Meaning |
SI unit |
|---|---|---|
\(f\) |
prescribed harmonic drive frequency ( |
\(\mathrm{Hz}\) |
\(\omega\) |
angular drive frequency \(2\pi f\) |
\(\mathrm{rad\,s^{-1}}\) |
\(\widehat{\mathbf{h}}_{\mathrm{ext}}\) |
transverse excitation field amplitude ( |
\(\mathrm{A\,m^{-1}}\) |
\(\phi_{\mathrm{drive}}\) |
global harmonic drive phase ( |
\(\mathrm{rad}\) |
\(\mathsf{A}(\omega)\) |
shifted complex tangent response operator |
\(\mathrm{rad\,s^{-1}}\) |
\(\mathsf{K}\) |
linearized effective-field stiffness operator |
\(\mathrm{rad\,s^{-1}}\) |
\(\mathsf{G}\) |
gyrotropic and Gilbert damping operator |
\(\mathrm{1}\) |
\(\mathsf{C}\) |
tangent-plane drive projection operator |
\(\mathrm{m\,A^{-1}\,s^{-1}}\) |
\(\widehat{\mathbf{q}}(\omega)\) |
complex tangent-coordinate response vector |
\(\mathrm{1}\) |
\(\widehat{\mathbf{b}}(\omega)\) |
assembled harmonic right-hand side vector |
\(\mathrm{rad\,s^{-1}}\) |
4. Assumptions, boundary meaning, and validity limits¶
Choice |
Mathematical meaning |
What it does not mean |
|---|---|---|
|
Solves the independent linear system \(\mathsf{A}(2\pi f_j)\widehat{\mathbf{q}} = \widehat{\mathbf{b}}\) at each positive frequency \(f_j > 0\). |
Does not run a time-domain transient simulation or nonlinear harmonic-balance expansion. |
|
Relaxes the initial state to an accepted equilibrium \(\mathbf{m}_0\) before linearizing the operator. |
Does not linearize around an unrelaxed transient state unless |
|
Supplies requested solver method, preconditioner, relative tolerance, and Krylov iteration limits. |
Does not bypass planner capability checks or true-residual verification. |
5. Python API and complete parameter reference¶
Stage-first example: FEM driven susceptibility sweep¶
# %%
import fullmag as fm
nm = 1.0e-9
study = fm.study("frequency_response_api_example")
study.engine("fem")
study.device("cpu", precision="double")
study.mode("strict")
study.universe(mode="manual", size=(300 * nm, 120 * nm, 100 * nm))
study.objects.mesh.defaults(maximum_element_size=5 * nm)
# %%
film = study.geometry(fm.Box(size=(100 * nm, 20 * nm, 5 * nm)), name="film")
film.Ms = 800.0e3
film.Aex = 13.0e-12
film.alpha = 0.02
film.m = fm.texture.uniform(1.0, 0.0, 0.0)
study.exchange()
study.demag(model="airbox", variant="robin")
# %%
study.stages.add_relax(stage_id="relax_eq", dt=5.0e-13, max_steps=100)
study.stages.add_frequency_response(
frequencies_hz=[5.0e9, 7.5e9, 10.0e9],
excitation_field_au_per_m=(0.0, 100.0, 0.0),
excitation_phase_rad=0.0,
observable="susceptibility_tensor",
include_demag=True,
equilibrium_source="relax",
damping_policy="include",
magnetostatic_bc="open",
solver_method="auto",
solver_preconditioner="block_jacobi",
solver_rtol=1.0e-8,
solver_max_iterations=500,
solver_restart_iterations=50,
)
Parameter reference (FrequencyResponse and FrequencyResponseSolverPolicy)¶
Python |
Type |
Default |
SI unit |
Validation |
Meaning |
Backend support |
ProblemIR |
|---|---|---|---|---|---|---|---|
|
|
|
\(1\) |
At least one |
Response observables |
FEM/FDM CPU/GPU; planner checks materialization |
|
|
|
|
\(\mathrm{Hz}\) |
Non-empty, finite, positive |
Sweep frequencies |
FEM/FDM CPU/GPU |
|
|
|
|
\(\mathrm{A\,m^{-1}}\) |
Length-3 finite vector |
Small transverse excitation field |
FEM/FDM CPU/GPU |
|
|
|
|
\(\mathrm{rad}\) |
Finite |
Excitation phase |
FEM/FDM CPU/GPU |
|
|
|
|
\(1\) |
|
Linearized operator |
FEM/FDM CPU/GPU |
|
|
|
|
\(1\) |
Boolean |
Include dynamic demagnetization |
FEM/FDM CPU/GPU |
|
|
|
|
\(1\) |
|
Equilibrium acquisition |
FEM/FDM CPU/GPU |
|
|
|
|
\(1\) |
|
Magnetostatic boundary condition |
FEM/FDM CPU/GPU |
|
|
|
|
mixed |
Valid method/preconditioner/tolerance/iteration values |
Solver method and preconditioner overrides |
FEM/FDM CPU/GPU; several methods are planned |
|
|
|
|
\(1\) |
Supported solver method name ( |
Requested linear solver lane |
FEM CPU/GPU |
|
|
|
|
\(1\) |
One of |
Requested Krylov preconditioner |
FEM CPU/GPU |
|
|
|
|
\(1\) |
Finite and positive |
Relative algebraic residual tolerance |
FEM CPU/GPU |
|
|
|
|
\(1\) |
Positive integer |
Maximum Krylov iterations per frequency |
FEM CPU/GPU |
|
|
|
|
\(1\) |
Positive integer \(\le\) |
GMRES/FGMRES restart subspace dimension |
FEM CPU/GPU |
|
6. ProblemIR, normalization, and provenance¶
FrequencyResponse.to_ir() emits {"kind": "frequency_response", ...} with dynamics, operator, equilibrium, k_sampling, normalization, damping_policy, spin_wave_bc, magnetostatic_bc, excitation, frequencies_hz, sampling, and optional solver_policy:
{
"kind": "frequency_response",
"operator": {
"kind": "linearized_llg",
"include_demag": true
},
"equilibrium": {
"kind": "relaxed_initial_state"
},
"damping_policy": "include",
"spin_wave_bc": "free",
"magnetostatic_bc": "open",
"excitation": {
"field_au_per_m": [0.0, 100.0, 0.0],
"phase_rad": 0.0
},
"frequencies_hz": {
"kind": "explicit",
"values_hz": [5000000000.0, 7500000000.0, 10000000000.0]
},
"solver_policy": {
"method": "auto",
"preconditioner": "block_jacobi",
"rtol": 1e-8,
"max_iterations": 500,
"restart_iterations": 50
}
}
7. Round-trip and failure semantics¶
Requested intent is preserved in Python and ProblemIR; resolved execution and solver method are selected by the planner and recorded separately in runtime provenance. Validation errors reject empty sweeps, non-positive frequencies, malformed excitation vectors, invalid operator or boundary-condition values, and inconsistent solver policy (restart_iterations > max_iterations). Unsupported combinations fail capability checks without silent fallback.
8. Discrete realization and execution sequence¶
8.1 Planner resolution¶
plan_fem_frequency_response validates the equilibrium source, boundary constraints, magnetostatic closure, and solver policy before lowering into FemFrequencyResponsePlanIR.
8.2 FEM CPU¶
FEM CPU executes solve_driven_frequency_response using the planner-selected lane (production_cpu_host_gmres, schur_reduced, or dense_reference) and verifies true unpreconditioned algebraic residuals at every frequency sample.
8.3 FEM GPU¶
FEM GPU supports the gpu_operator_host_krylov lane when device capability and operator gates pass; FDM CPU and FDM GPU frequency-response studies are explicitly rejected by the planner.
9. Implementation mapping¶
Stage builder and spec:
packages/fullmag-py/src/fullmag/world.py(class FrequencyResponseStageSpec,frequency_response_stage,add_frequency_response).Study and solver policy models:
packages/fullmag-py/src/fullmag/model/study.py(class FrequencyResponse,class FrequencyResponseSolverPolicy).Rust planner:
crates/fullmag-plan/src/fem.rs(plan_fem_frequency_response).Native FEM solver:
backends/fem/src/frequency_domain/driven_response_solver.cpp(solve_driven_frequency_response).
10. Validation and qualification¶
Validation layer |
Required check |
Evidence required |
|---|---|---|
Python \(\to\) IR serialization |
|
Verifies frequency list, excitation vector/phase, and solver policy round-trip. |
Algebraic residual gate |
True residual verification |
Recomputes \(|\widehat{\mathbf{b}} - \mathsf{A}(\omega)\widehat{\mathbf{q}}|_2\) per frequency sample. |
11. Limitations and failure modes¶
Native FDM frequency-response execution is unsupported and rejected at the planner boundary.
Several target solver-tree methods (
cpu_sparse_direct,full_coupled_field_split,modal_reduced,gpu_device_krylov) remain gated byfrequency_response_solver_method_rejection_reasonin the current runtime.
12. Scientific bibliography¶
C. Kittel, On the theory of ferromagnetic resonance absorption, Phys. Rev. 73, 155–161 (1948), DOI: 10.1103/PhysRev.73.155.
Y. Saad and M. H. Schultz, GMRES: A generalized minimal residual algorithm for solving nonsymmetric linear systems, SIAM J. Sci. Stat. Comput. 7, 856–869 (1986), DOI: 10.1137/0907058.
13. Source-code index¶
Control Room crosswalk¶
Status: Frequency-response stage authoring, FMR susceptibility sweeps, peak extraction, and 3D driven response playback are partial; specialized FrequencyResponseSolverPolicy linear-system tuning fields without UI controls remain not implemented in the stage editor.
Python/API surface |
Control Room path |
Status |
Transaction |
|---|---|---|---|
Driven frequency bounds, step schedule, & excitation binding |
|
|
Submit stage draft via |
Swept FMR curve, resonance peaks, & complex susceptibility detail |
|
|
Readback from |
Driven spatial response field & harmonic phase playback in 3D |
|
|
|
Solver policy parameters without a named UI field |
|
|
Python-only until implemented |
See Control Room capability register, Planar Monitors, Dispersion & Frequency-Domain Inspectors, and Study Authoring, Stages & Interactive Re-Execution.
Frontend source owners: FrequencyResponseStageInspector, FmrResponseSweepInspectorPanel, FmrPeakInspector, ModeVisualizationInspectorPanel, and StudyStageDraftEditor.
Source-map coverage¶
Claim |
Path |
Stable symbol |
Responsibility |
Evidence |
|---|---|---|---|---|
Frequency-response study parameters and IR lowering |
|
Frequency-response study parameters and IR lowering |
Source-map validator and focused API tests |
|
Frequency-response solver policy validation and lowering |
|
Frequency-response solver policy validation and lowering |
Source-map validator and focused API tests |
|
Stage specification and builder |
|
Stage-first frequency-response specification |
Source-map validator and focused API tests |
|
Stage authoring entrypoint |
|
Stage-first authoring entrypoint on |
Source-map validator and focused API tests |
|
Planner frequency-response lowering |
|
Lowers |
Planner contract tests |
|
Native FEM driven response solver |
|
|
Executes FEM harmonic response sweep and residual verification |
Native frequency-domain tests |