Validation¶

Last changes: 23:23 29.08.2026Documentation changelog

Demagnetization validation must establish physical correctness, numerical convergence, and backend qualification separately. A source-level contract test is evidence of an implementation contract, not proof of an executed GPU result.

Physical problem¶

The observable pair is the demagnetizing field and self-energy. A valid test therefore checks field direction and magnitude, energy sign and magnitude, and the relation between them. The test record must also identify whether the field is cell-centred, nodal, element-recovered, or sampled after interpolation. Comparing fields at different locations can otherwise produce an apparently small error for the wrong reason.

Governing equations¶

(1)¶\[E_{\mathrm d}=-\frac{\mu_0}{2}\int_{\Omega_m}\mathbf M\cdot\mathbf H_{\mathrm d}\,\mathrm dV.\]

(2)¶\[r=\nabla\cdot(\mathbf H_{\mathrm d}+\mathbf M), \qquad \nabla\times\mathbf H_{\mathrm d}=\mathbf0.\]

Symbols and SI units¶

Symbol	Definition	SI unit
$E_{\mathrm d}$	demagnetization energy	$\mathrm{J}$
$\mathbf M$	magnetization	$\mathrm{A\,m^{-1}}$
$\mathbf H_{\mathrm d}$	demagnetizing field	$\mathrm{A\,m^{-1}}$
$r$	magnetic divergence residual	$\mathrm{A\,m^{-2}}$
$\mu_0$	vacuum permeability	$\mathrm{N\,A^{-2}}$

Assumptions and validity¶

Every comparison must state geometry, material, grid/mesh, boundary policy, precision, solver tolerance, and whether the device actually executed the kernel. Relative errors without absolute scales are insufficient for near-zero fields.

Python API¶

This stage-first FDM scenario fixes the geometry, grid, precision, boundary policy, initial state, and output cadence needed by a demagnetization validation artifact. A refinement study should rerun the same script with successively smaller cells while preserving every other requested setting.

# %% Imports and units
import fullmag as fm

nm = 1.0e-9

# %% Study and reference execution lane
study = fm.study("demag_rectangular_prism_validation")
study.engine("fdm")
study.device("cpu", precision="double")
study.mode("strict")
study.objects.mesh.defaults(cell_size=(2 * nm, 2 * nm, 4 * nm))

# %% Geometry, material, state, and isolated demagnetization term
prism = study.geometry(
    fm.Box(size=(80 * nm, 40 * nm, 4 * nm), name="prism"),
    name="prism",
)
prism.Ms = 8.0e5
prism.Aex = 1.3e-11
prism.alpha = 0.02
prism.m = fm.init.UniformMagnetization((1.0, 0.0, 0.0))
study.exchange(enabled=False)
study.demag()
study.solver(integrator="rk4", fix_dt=5.0e-15)

# %% Ordered measurement stage
study.stages.add_run(stage_id="measure_demag", until=1.0e-12).autosave(
    fm.StageAutosave(
        table=fm.TableAutosave(
            t_sampl=1.0e-13,
            quantities=[
                "t",
                "mx",
                "my",
                "mz",
                "e_demag",
                "e_total",
                "max_h_demag",
            ],
        ),
        fields=[fm.FieldAutosave("H_demag", every=2.0e-13)],
    )
)

Python parameter	Type	Default	SI unit	Validation	Meaning	Backend support	ProblemIR
`Demag.model`	`optional str`	`None`	$1$	Canonical model validation.	Selects realization under test.	Planner-dependent.	`energy[].realization`
`SaveField("H_demag")`	`str`	required	$\mathrm{A\,m^{-1}}$	Quantity must be materializable.	Requests vector field.	Executable lane-dependent.	`outputs[].quantity`
`SaveScalar("E_demag")`	`str`	required	$\mathrm{J}$	Quantity must be materializable.	Requests global energy.	Executable lane-dependent.	`outputs[].quantity`

ProblemIR¶

The interaction and output requests are lowered separately. Planner validation must verify that the selected realization can materialize H_demag and E_demag before execution.

Round-trip and failure semantics¶

The report records requested intent, resolved execution, validation errors, and unsupported combinations. A missing quantity is a fail-closed planner error rather than a zero-filled result.

The validation artifact separates requested intent from resolved execution. Requested intent contains the chosen model, mesh/grid, output quantities, tolerance, precision, and device request. Resolved execution contains the selected backend realization, actual mesh identity, solver policy, iteration count, convergence flag, field recovery, energy reduction, and runtime/device identity. An artifact that omits any of these fields is not sufficient for a CPU/GPU qualification claim.

Discrete realization¶

FDM compares cell fields and volume-weighted energy. FEM compares recovered nodal/element fields, integrated energy, and residuals. CPU/GPU parity requires the same precision and tolerance.

For FDM, the reference comparison must fix cell dimensions, padding, kernel convention, FFT normalization, self-term, and periodic-image policy. For FEM, it must fix the magnetic/air domain, boundary marker, Robin or Dirichlet closure, mesh order, quadrature/recovery rule, linear solver, preconditioner, relative tolerance, absolute tolerance when present, and maximum iterations.

Error metrics and acceptance¶

Use more than one metric:

Quantity	Definition	Why it is required
Field absolute error	$	\mathbf H-\mathbf H_{\mathrm{ref}}\|_2$
Field relative error	$	\mathbf H-\mathbf H_{\mathrm{ref}}\|2/(\|\mathbf H{\mathrm{ref}}\|2+H*)$
Energy error	$	E-E_{\mathrm{ref}}
Maxwell residual	Norm of $r$ and curl residual	Detects a plausible energy with an invalid field.
Refinement slope	Observed error versus grid/mesh scale	Distinguishes convergence from accidental agreement.

The report must state $H_*$ and $E_*$ whenever relative metrics are used. No universal numerical threshold is implied by this page; the threshold belongs to the qualified test or standard problem.

Lane-specific qualification¶

Lane	Minimum evidence before status can be implemented	Typical failure that must remain visible
FDM CPU	independent kernel/tensor checks, analytic geometry, refinement	wrong self-term, padding, or FFT normalization
FDM GPU	matched CPU reference, executed CUDA device identity, precision record	skipped device test or silent CPU fallback
FEM CPU	weak-form residual, airbox/boundary convergence, energy derivative	residual/energy mismatch or unconverged Hypre solve
FEM GPU	executed device operator, matched tolerance/precision, phase telemetry	host-only assembly reported as GPU parity

Implementation mapping¶

Contract tests include batched_demag_fft_contract.cpp, cuda_demag_robin_energy_contract.cpp, and cuda_periodic_demag_contract.cpp; production qualification additionally needs managed runtime and executed-device evidence.

Validation matrix¶

Test family	Required evidence
Analytical rectangle	Demag factors and energy against an independent reference.
FDM tensor/FFT	Kernel symmetry, self term, padding, CPU/CUDA parity.
FEM airbox	Mesh and airbox convergence, Robin energy accounting, residual.
FEM/BEM	Surface orientation, solid-angle terms, open-boundary comparison.
Periodic	Image-count or periodic-class convergence and zero-mode behavior.
Qualification	Same tolerance, same precision, runtime identity, executed device.

Limitations¶

Historical reports and source tests may document a no-go or partial gate. They must not be rewritten as a production qualification claim without current evidence.

Scientific bibliography¶

Newell, A. J., Williams, W. and Dunlop, D. J., Geophysical Research Letters 21, 1994.
FullMag validation sources: backends/fdm/tests/ and backends/fem/tests/ demagnetization contracts.

Control Room crosswalk¶

Use Model Explorer -> Objects -> <object> -> Physics when PhysicsInteractionPanel exposes the interaction. Status: partial. frontend support is not implemented applies to physical parameters without a matching control. See {doc}/frontend/capability-register; do not infer UI support from backend or Python availability.

Python/API crosswalk¶

The linked Python API page is authoritative for exact functions, arguments, units, and failure semantics. If this page is a foundation or category overview, runnable Python is ot applicable here and must be taken from the terminal API page.

Bibliography and source scope¶

Use the scientific bibliography and source-code index on the linked terminal page. This block adds no new equation or unverified implementation claim.

Source-code index¶

Repository path	Stable symbol	Responsibility
`packages/fullmag-py/src/fullmag/model/energy.py`	`class Demag`	Validation target selection.
`backends/fem/cpu/mfem/interactions/demag.cpp`	`compute_demag_field_for_magnetization`	FEM production field path used by validation.

Symbol	Definition	SI unit
\(E_{\mathrm d}\)	demagnetization energy	\(\mathrm{J}\)
\(\mathbf M\)	magnetization	\(\mathrm{A\,m^{-1}}\)
\(\mathbf H_{\mathrm d}\)	demagnetizing field	\(\mathrm{A\,m^{-1}}\)
\(r\)	magnetic divergence residual	\(\mathrm{A\,m^{-2}}\)
\(\mu_0\)	vacuum permeability	\(\mathrm{N\,A^{-2}}\)