Frequency Response¶

Contract¶

This page records the public Python authoring contract and canonical lowering for the linear-response study type. Solver mathematics and response qualification are owned by Frequency-domain response.

Governing equations¶

Frequency response solves the linearized magnetization response to a small transverse excitation field at prescribed frequencies. Equations, susceptibility definitions, and solver methods belong to the frequency-domain numerical pages.

Symbols and SI units¶

Frequency is authored in hertz; the excitation field is in \(\mathrm{A\,m^{-1}}\); phase is in radians. \(1\) denotes dimensionless data.

Assumptions and validity¶

Constructor checks run immediately. Lowering and planning additionally check excitation finite-ness, frequency positivity, equilibrium-source validity, solver-policy fallbacks, mesh cardinality, capability, and backend legality.

Python API¶

# %% Linear-response frequency sweep
import fullmag as fm

nm = 1.0e-9

# %% Study and execution lane
study = fm.study("frequency_response_api_example")
study.engine("fdm")
study.device("cpu", precision="double")
study.mode("strict")

# %% Geometry, material, initial state, and interactions
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()

# %% Relax to equilibrium and solve a frequency sweep
study.stages.add_relax(stage_id="relax", algorithm="projected_gradient_bb", max_steps=1000, tolT=1e-8)
study.stages.add_frequency_response(
    frequencies_hz=[1.0e9, 2.0e9, 3.0e9],
    excitation_field_au_per_m=(0.0, 1.0, 0.0),
    observable="susceptibility_tensor",
    equilibrium_source="relax",
    magnetostatic_bc="open",
)

ProblemIR¶

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.

Round-trip and failure semantics¶

Requested intent is preserved in Python and IR; resolved execution and solver method are selected by the planner. Validation errors reject empty sweeps, non-positive frequencies, malformed excitation vectors, invalid operator/boundary-condition values, and inconsistent solver policy. Unsupported combinations fail capability checks without silent fallback.

Discrete realization¶

This page owns authoring and lowering only. Solver realizations are documented under Frequency-domain response.

Implementation mapping¶

The adjacent map anchors claims to packages/fullmag-py/src/fullmag/model/study.py (class FrequencyResponse, FrequencyResponseSolverPolicy) and packages/fullmag-py/src/fullmag/world.py (StudyStagesBuilder.add_frequency_response).

Validation¶

Ownership tests compare this inventory with live signatures and validate the adjacent source map.

Limitations¶

Several solver methods and the GPU Krylov lanes are planned rather than production-qualified; planner resolution is authoritative and must be reported as provenance.

Scientific bibliography¶

Solver and response-validation references belong to the frequency-domain numerical pages.

Control Room crosswalk¶

Status: Stage authoring and inspection are partial; the stage editor exposes only its advertised fields.

not implemented: frontend support for study parameters not rendered by the stage editor. See Control Room capability register for the support matrix and not implemented policy. Frontend source owner: apps/control-room/src/modules/inspector/panels/StudyStageDraftEditor.tsx (StudyStageDraftEditor).

Source-code index¶