Mathematical Formulation¶

Last changes: 23:23 29.08.2026Documentation changelog

This page fixes the common magnetostatic equations used by every demagnetization realization.

Physical problem¶

The field is generated by the divergence and boundary trace of \(\mathbf M\), not by a local material coefficient. The exterior domain is part of the open-boundary problem even when a numerical method eliminates it analytically.

Governing equations¶

(1)¶\[\nabla\times\mathbf H_{\mathrm d}=\mathbf0, \qquad \nabla\cdot\mathbf B=0, \qquad \mathbf B=\mu_0(\mathbf H_{\mathrm d}+\mathbf M).\]

(2)¶\[\mathbf H_{\mathrm d}=-\nabla u, \qquad \Delta u=\nabla\cdot\mathbf M, \qquad u(\mathbf x)\to0\ \text{as}\ |\mathbf x|\to\infty.\]

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

Symbols and SI units¶

Symbol	Definition	SI unit
\(\mathbf M\)	magnetization	\(\mathrm{A\,m^{-1}}\)
\(\mathbf H_{\mathrm d}\)	demagnetizing field	\(\mathrm{A\,m^{-1}}\)
\(u\)	scalar potential	\(\mathrm{A}\)
\(\mathbf B\)	magnetic flux density	\(\mathrm{T}\)
\(\mu_0\)	vacuum permeability	\(\mathrm{N\,A^{-2}}\)
\(E_{\mathrm d}\)	demagnetization energy	\(\mathrm{J}\)
\(\Omega_m\)	magnetic domain	\(\mathrm{m^3}\)
\(N_{pq}^{ij}\)	discrete demagnetization tensor from source cell \(q\) to destination cell \(p\)	\(1\)
\(p,q\)	destination and source cell indices	\(1\)
\(i,j\)	Cartesian component indices	\(1\)
\(w_i\)	cell volume or FEM integration weight	\(\mathrm{m^3}\)

Assumptions and validity¶

The equations assume quasistatic, source-free magnetostatics and a continuum magnetization. The potential representation requires the selected domain topology to be handled by the solver. The open-boundary decay condition is exact at infinity; finite airbox and periodic realizations replace it with separately documented discrete conditions.

Python API¶

Python parameter	Type	Default	SI unit	Validation	Meaning	Backend support	ProblemIR
`Demag.model`	`optional str`	`None`	\(1\)	Canonical model name.	Selects the physical realization family.	Planner-dependent.	`energy[].realization`
`Demag.variant`	`optional str`	`None`	\(1\)	Valid only for `airbox`.	Selects Robin or Dirichlet airbox closure.	FEM airbox.	`energy[].realization`

Stage-first realization request¶

The common equations are selected through a solver-specific stage request. This example uses the public stage API and records a FEM Poisson Robin realization; it does not imply that the same finite-domain operator is used by FDM.

# %% FEM realization and physical state
import fullmag as fm

nm = 1e-9
study = fm.study("demag_formulation_reference")
study.engine("fem")
study.device("cpu", precision="double")
study.mode("strict")
study.demag(realization="poisson_robin")
study.fem_demag_solver(
    solver="CG",
    preconditioner="AMG",
    rtol=1e-12,
    max_iterations=600,
)
body = study.geometry(fm.Box(100 * nm, 20 * nm, 5 * nm), name="film")
body.Ms = 800e3
body.Aex = 13e-12
body.alpha = 0.02
body.m = fm.texture.uniform(1.0, 0.0, 0.0)
study.stages.add_relax(
    stage_id="relax",
    algorithm="llg_overdamped",
    solver="rk23",
    dt_initial=1e-15,
    dt_min=1e-17,
    dt_max=1e-14,
    max_err=1e-7,
    relax_alpha=1.0,
    tolT=1e-6,
    max_steps=50_000,
)

The selected realization is a requested intent. The resolved plan must additionally record the magnetic domain, air domain, outer marker, boundary variant, linear solver, preconditioner, tolerances, mesh identity, field recovery, and energy reduction.

Realization hierarchy¶

FDM CPU and GPU: discrete Green operator¶

FDM represents the magnetization by cell averages. The demagnetizing field is a discrete convolution with a translation-invariant tensor on a common grid:

(4)¶\[H_{d,p}^{i}=-sum_{q}sum_{j=1}^{3}N_{pq}^{ij}M_q^{j}.\]

The CPU reference constructs the tensor spectrum and applies the reduction in host memory. The CUDA lane uses device kernels and device reductions. The mathematical input is the same, but padding, FFT layout, precision, reduction order, and device residency are not. Neither lane solves a finite airbox Poisson equation.

FEM CPU and GPU: scalar potential¶

FEM introduces a scalar potential over the magnetic body and, for the airbox variant, an exterior air region. The magnetic source enters through the divergence of \(mathbf M\) and its boundary trace. The CPU path assembles and solves the operator using MFEM/Hypre components; the GPU path has a separate CSR/device-Hypre realization. The recovered field and energy must use the same sign convention as the common continuum equations.

Energy and observable ownership¶

The field-derived energy is not an arbitrary post-processing scalar. For a resolved field, the implementation must reduce

(5)¶\[E_{mathrm d}^{h}=- rac{mu_0}{2}sum_i w_i,mathbf M_icdotmathbf H_{mathrm d,i},\]

where \(w_i\) is the cell volume or FEM quadrature/lumped weight selected by the backend. The weight, field location, masking of non-magnetic air nodes, and reduction precision are part of provenance. A reported energy without these facts is not reproducible.

ProblemIR¶

The lowered interaction is {"kind": "demag", "realization": "poisson_robin"} for the example. The IR records semantic intent; it does not encode an unreported discretization approximation.

Round-trip and failure semantics¶

Export preserves requested intent and resolved execution separately. Invalid model/variant pairs are validation errors. Unsupported combinations are rejected as unsupported combinations rather than converted to an open-boundary default.

Discrete realization¶

FDM approximates the Green operator by a cell-averaged tensor. FEM approximates the scalar potential weak form. Both must reproduce the same sign convention and energy derivative.

Implementation mapping¶

Newell tensor construction is in compute_newell_kernels; FEM source assembly is in assemble_demag_poisson_rhs; energy reduction is in demag_poisson_energy_from_field.

Validation¶

Check Maxwell residuals, field sign, self-demagnetizing factors of uniformly magnetized bodies, and the identity between field-derived energy and the reported scalar energy.

Limitations¶

The scalar-potential page does not claim that every listed backend is qualified for every mesh, precision, periodicity, or airbox policy.

Scientific bibliography¶

Brown, W. F., Micromagnetics, Wiley, 1963.
Fredkin, D. R. and Koehler, T. R., IEEE Transactions on Magnetics 26, 1990.

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
`crates/fullmag-fdm-demag/src/newell.rs`	`compute_newell_kernels`	Cell-averaged FDM demag tensor.
`backends/fem/cpu/mfem/interactions/demag_poisson_rhs.cpp`	`assemble_demag_poisson_rhs`	FEM weak-form right-hand side.
`backends/fem/cpu/mfem/interactions/demag_poisson_energy.cpp`	`demag_poisson_energy_from_field`	FEM demag energy reduction.