Modal validation and qualification¶

Scope and purpose¶

Modal validation compares computed eigenfrequencies and mode branches with an independent physical reference. It is not a plot-only step: the equilibrium, field units, \(\mathbf k\) sampling, branch identity, analytical model, tolerance and demagnetization policy define the validation case. Fullmag supports thin-film Damon–Eshbach/backward-volume dispersion checks and zero-wave-number Kittel field sweeps as explicit validation intent attached to the study.

Scientific and numerical model¶

For each matched mode sample \(j\), the relative frequency error is

For a Kittel field sweep, each selected bias field \(\mathbf H_j\) is compared with the declared macrospin or thin-film analytical frequency \(f_{\mathrm{Kittel}}(\mathbf H_j)\):

The reference does not prescribe a branch-matching algorithm beyond the declared branch ID and sample indices. A validation result without a reproducible matching rule is not a qualification.

Symbols and SI units¶

Assumptions and validity¶

• Thin-film dispersion validation requires both Damon–Eshbach and backward-volume scenarios, a nonzero equilibrium magnetization and a declared film normal.

• Frequency windows and wave-vector bounds are validation-domain limits, not solver convergence tolerances. They must be reported separately.

• Kittel validation requires at least three unique nonzero bias-field samples. The thin_film_in_plane model requires a positive effective magnetization.

• relative_tolerance is a comparison threshold. It does not replace mesh, equilibrium, eigenvalue residual or branch-tracking evidence.

• Synthetic demagnetization factors, periodic-airbox \(k=0\), and no-demag Kittel cases are separate physical assumptions and cannot be mixed without an explicit case ID.

Python API¶

# %% Attach reproducible modal validation intent to a stage-first study
import fullmag as fm

nm = 1.0e-9
study = fm.study("modal_validation")
study.engine("fem")
study.device("cpu", precision="double")
study.mode("strict")
study.universe(mode="manual", size=(700 * nm, 250 * nm, 250 * nm))
film = study.geometry(fm.Box(size=(500 * nm, 125 * nm, 3 * nm), name="film"), name="film")
film.Ms = 8.0e5
film.Aex = 1.3e-11
film.m = fm.init.UniformMagnetization((1.0, 0.0, 0.0))
study.dispersion_validation(
    fm.ThinFilmDEBVDispersionValidation(
        film_thickness_m=3 * nm,
        equilibrium_magnetization=(1.0, 0.0, 0.0),
        scenarios=[
            {"geometry": "damon_eshbach", "branch_id": "branch_0", "sample_indices": (0, 1, 2)},
            {"geometry": "backward_volume", "branch_id": "branch_0", "sample_indices": (3, 4, 5)},
        ],
    )
)
study.k0_kittel_validation(
    fm.K0KittelFieldSweepValidation(
        samples=[
            {"sample_index": 0, "bias_field": (8.0e3, 0.0, 0.0)},
            {"sample_index": 1, "bias_field": (1.0e4, 0.0, 0.0)},
            {"sample_index": 2, "bias_field": (1.2e4, 0.0, 0.0)},
        ],
        model="macrospin_larmor",
        relative_tolerance=0.05,
        case_id="k0-macrospin",
    )
)
study.stages.add_eigenmodes(count=8, target="lowest", equilibrium_source="provided")

Parameters¶

ProblemIR and provenance¶

Validation intent is serialized under runtime metadata and remains distinct from the modal study request. Provenance records the validation schema, canonicalized units, case ID, source mode branch, sample mapping, analytical model, tolerance, solver diagnostics and the exact resolved execution.

Diagnostics and failure semantics¶

Script export preserves validation objects and stage ordering. Requested intent and resolved execution are stored separately. Validation errors include missing geometries, too few samples, duplicate sample indices, invalid model names, invalid field/frequency windows and tolerance violations. Unsupported combinations combinations are rejected explicitly; validation metadata cannot make an unsupported solver lane qualified.

Discrete realization by lane¶

Where this is implemented¶

Validation¶

The validation itself must report every sample, branch assignment, reference frequency, computed frequency, signed difference, relative error and acceptance threshold. In addition, report equilibrium torque, eigen residuals, mesh/cell resolution, precision, demag policy and runtime identity. A passing relative-error threshold without these provenance fields is incomplete.

Limitations¶

Analytical agreement is a qualification gate for the declared domain, not proof of correctness for all geometries, modes, wave vectors or devices. The current analytical model set is intentionally bounded by the Python validators and does not represent arbitrary multilayer dispersion.

Scientific bibliography¶

• E. H. Lock, “The Kittel formula for ferromagnetic resonance,” standard macrospin reference.

• I. A. Kalinikos and A. N. Slavin, “Theory of dipole-exchange spin wave spectrum for ferromagnetic films with mixed exchange boundary conditions,” Journal of Physics C 19 (1986).

• Canonical modal owner: Linearized LLG eigensolver.

Control Room workflow¶

Use Model Explorer -> Stages -> Add stage -> <stage kind> for stage-level controls when the terminal page identifies a matching field. The current editor is partial: only fields surfaced by the stage draft are authorable. Numerical parameters without a matching control are not implemented in the frontend. Do not infer frontend support from Python or backend availability. See {doc}/frontend/capability-register for the current register and exact source owner.

Source-code index¶