Periodic demagnetization solvers¶

Last changes: 06:12 31.08.2026Documentation changelog

Scope and purpose¶

The canonical interaction is owned by Periodic Demagnetization. Periodic demagnetization is a different Green-function problem from open-boundary demagnetization: an axis marked periodic identifies translated cells or representative mesh degrees of freedom, and the zero-wave-number or null-potential policy becomes part of the numerical problem. Fullmag has two documented realization families: finite translated-image summation for FDM and a reduced periodic Poisson system for FEM. Neither is silently substituted for the other or for the open kernel.

Scientific and numerical model¶

For FEM, let \(P\) lift one value per periodic representative to all equivalent mesh degrees of freedom. The reduced stiffness system is

(1)¶\[A_p=P^{T}A_{\mathrm{open}}P, \qquad b_p=P^{T}b, \qquad A_pu_p=b_p.\]

The physical potential is lifted before taking its gradient, and the field-based energy is reduced over the magnetic volume:

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

For FDM, the open Newell tensor is replaced by a periodic finite-image tensor. With translation vectors \(\mathbf t_{\boldsymbol\ell}\) and image set \(\mathcal I\), the discrete convolution is

(3)¶\[\mathbf H_{\mathrm d}(\mathbf r_i)= \sum_{\boldsymbol\ell\in\mathcal I} \mathbf N(\mathbf r_i-\mathbf r_j-\mathbf t_{\boldsymbol\ell})\mathbf M(\mathbf r_j), \qquad \mathcal I=\{-n_x,\ldots,n_x\}\times\{-n_y,\ldots,n_y\}\times\{-n_z,\ldots,n_z\}.\]

The image counts therefore change the operator itself. They are not a gauge parameter and are not interchangeable with the FEM null-space treatment.

Symbols and SI units¶

Symbol	Meaning	SI unit
\(A_p\)	reduced periodic FEM stiffness operator	\(\mathrm{m}\)
\(A_{\mathrm{open}}\)	unreduced FEM stiffness operator	\(\mathrm{m}\)
\(P\)	periodic representative prolongation	\(1\)
\(b_p\)	reduced Poisson right-hand side	\(\mathrm{A\,m}\)
\(b\)	unreduced Poisson right-hand side	\(\mathrm{A\,m}\)
\(u_p\)	reduced scalar potential	\(\mathrm{A}\)
\(\mathbf H_{\mathrm d}\)	demagnetizing field	\(\mathrm{A\,m^{-1}}\)
\(E_{\mathrm d}\)	demagnetization energy	\(\mathrm{J}\)
\(\mu_0\)	vacuum permeability	\(\mathrm{N\,A^{-2}}\)
\(\Omega_m\)	magnetic volume	\(\mathrm{m^3}\)
\(\mathbf r_i\)	FDM cell-center position	\(\mathrm{m}\)
\(\mathbf t_{\boldsymbol\ell}\)	periodic translation vector	\(\mathrm{m}\)
\(\mathcal I\)	finite image-index set	\(1\)
\(n_x,n_y,n_z\)	image counts along each axis	\(1\)
\(\mathbf N\)	demagnetizing tensor kernel	\(1\)
\(\mathbf M\)	magnetization field	\(\mathrm{A\,m^{-1}}\)

Assumptions and validity¶

FdmPbc.axes contains exactly three Boolean axis flags. demag="truncated_images" is a finite approximation to an infinite image sum; increasing image counts is required for a convergence study.
FEM periodic reduction requires a valid periodic mesh certificate and a separately recorded null-space/zero-mode policy. An apparently finite energy does not prove that the null mode was handled correctly.
A periodic request must preserve axis order, image semantics, precision and field normalization between CPU and GPU before parity is evaluated.
periodic_airbox_k0 is FEM-only. It is a planner error for FDM and must not silently fall back to open or truncated_images.
The periodic page describes current source-visible paths. A source-visible GPU function is not by itself a production qualification claim.

Python API¶

The public authoring surface is stage-first. Periodicity is attached to the study before stages are created; it is not expressed through a legacy fm.Problem(...) aggregate.

# %% Periodic FDM demagnetization with explicit image truncation
import fullmag as fm

nm = 1.0e-9
study = fm.study("periodic_fdm_demag")
study.engine("fdm")
study.device("cpu", precision="double")
study.mode("strict")
study.objects.mesh.defaults(cell_size=(2 * nm, 2 * nm, 5 * nm))
study.pbc(x=True, y=True, z=False, demag="truncated_images", images=(4, 4, 0))
film = study.geometry(
    fm.Box(size=(100 * nm, 20 * nm, 5 * nm), name="film"),
    name="film",
)
film.Ms = 8.0e5
film.Aex = 1.3e-11
film.alpha = 0.02
film.m = fm.init.UniformMagnetization((1.0, 0.0, 0.0))
study.demag()
study.solver(
    integrator="rk45",
    dt_initial=1.0e-15,
    dt_min=1.0e-17,
    dt_max=1.0e-12,
    max_err=1.0e-7,
)
study.stages.add_relax(
    stage_id="relax",
    algorithm="llg_overdamped",
    solver="rk45",
    dt_initial=1.0e-15,
    dt_min=1.0e-17,
    dt_max=1.0e-12,
    max_err=1.0e-7,
    max_steps=100,
    tolT=1.0e-6,
)

study.pbc(...) is the stage-first facade. The equivalent serialized object is fm.FdmPbc; the constructor is useful when inspecting or testing the Python contract, while the documented script should keep study construction and stage ordering visible.

Parameters¶

Python parameter	Type	Default	SI unit	Validation	Meaning	Backend support	ProblemIR
`FdmPbc.axes`	`tuple[bool,bool,bool]`	required	\(1\)	exactly three Boolean values	periodic status of x, y, z	FDM planner; FEM mesh planner consumes the same intent	`pbc.axes`
`FdmPbc.demag`	`str`	`open`	\(1\)	`open`, `truncated_images`, or `periodic_airbox_k0`	demagnetization boundary policy	FDM supports `open`/`truncated_images`; FEM supports the periodic airbox policy subject to qualification	`pbc.demag`
`FdmPbc.image_counts`	`tuple[int,int,int]	None`	`None`	\(1\)	exactly three non-negative integers; only with `truncated_images`	finite image counts \(n_x,n_y,n_z\)	FDM CPU/GPU image policies as qualified
`study.pbc(..., x/y/z=...)`	`bool` flags	all `False`	\(1\)	at least one axis for non-open policy	stage-first authoring facade for `FdmPbc.axes`	Python authoring; planner resolves backend legality	`pbc.axes`

ProblemIR and provenance¶

The periodic policy is lowered independently from the interaction term:

{
  "energy_terms": [{"kind": "demag"}],
  "backend_policy": {
    "engine": "fdm",
    "pbc": {
      "axes": ["periodic", "periodic", "open"],
      "demag": "truncated_images",
      "image_counts": [4, 4, 0]
    }
  }
}

The IR records requested periodic axes and the selected policy. Resolved execution must additionally record the chosen FDM/FEM lane, precision, actual image counts or representative-map certificate, zero-mode treatment, solver residuals, field recovery and energy reduction. Requested intent and resolved execution are not interchangeable provenance fields.

Diagnostics and failure semantics¶

Script export preserves the stage-first study, periodic axes and demagnetization policy. Validation errors include a wrong axis tuple length, invalid image counts, image counts without truncated_images, periodic_airbox_k0 requested for FDM, missing periodic mesh pairing and an unresolved FEM null mode. Unsupported combinations are rejected explicitly; no fallback to the open kernel is permitted. Requested intent remains visible even when resolved execution reports an unsupported lane, and the planner must report validation errors before runtime submission.

Discrete realization by lane¶

Solver	Device	Status	Realization
FDM	CPU	partial/source-backed	periodic Newell spectra with finite translated-image truncation
FDM	GPU	partial/qualification-dependent	separate CUDA realization only when the selected policy is qualified
FEM	CPU	partial/source-backed	periodic representative reduction of the Poisson system
FEM	GPU	partial/qualification-dependent	separate device realization; CPU source presence does not establish parity

For FDM, changing image_counts changes the convolution kernel and therefore the computed field. For FEM, changing the periodic node equivalence classes changes the matrix topology and right-hand side. CPU/GPU results are comparable only after the same policy, mesh/cell topology, precision, zero-mode handling and tolerances are recorded.

Where this is implemented¶

Claim	Repository path	Stable symbol	Responsibility	Lane
Python policy	`packages/fullmag-py/src/fullmag/model/problem.py`	`class FdmPbc`	validates axes, policy and image counts; lowers periodic intent	Python/IR
FDM periodic kernel	`crates/fullmag-engine/src/fdm/cpu/fft.rs`	`compute_periodic_newell_kernel_spectra`	computes periodic kernel spectra for the FDM convolution	FDM CPU
FEM periodic reduction	`backends/fem/cpu/mfem/interactions/demag_poisson_periodic.cpp`	`solve_demag_periodic_poisson_reduced`	reduces and solves the periodic Poisson system	FEM CPU

Validation¶

FDM validation must sweep image counts, compare field and energy observables against a larger-image reference, and test CPU/GPU parity at identical precision and axis order. FEM validation must check periodic mesh certificates, representative-map completeness, open-axis solvability, reduced-system residuals, zero-mode handling, field continuity across seams and the field-energy identity. A finite energy alone is insufficient evidence for either realization.

Limitations¶

Finite image summation is not an exact Ewald or infinite periodic Green function. Periodic FEM qualification is independent of the FDM image study and independent of open-airbox convergence. This reference does not claim a universal fully periodic 3-D FEM solution or GPU qualification for every periodic policy.

Scientific bibliography¶

A. J. Newell, W. Williams, and D. J. Dunlop, “A method for computing the magnetostatic demagnetizing tensor for rectangular prisms,” Geophysical Journal International 124 (1993), 938–946, DOI: 10.1111/j.1365-246X.1993.tb04780.x.
Fullmag internal periodic FEM design: docs/physics/0800-fem-static-pbc-demag.md.
Canonical physics owner: Periodic Demagnetization.

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¶

Claim	Repository path	Stable symbol	Responsibility	Evidence
Python periodic contract	`packages/fullmag-py/src/fullmag/model/problem.py`	`class FdmPbc`	validation and IR lowering	Python contract tests
FDM periodic spectra	`crates/fullmag-engine/src/fdm/cpu/fft.rs`	`compute_periodic_newell_kernel_spectra`	finite-image kernel spectrum	FDM source contract
FEM reduced solve	`backends/fem/cpu/mfem/interactions/demag_poisson_periodic.cpp`	`solve_demag_periodic_poisson_reduced`	periodic Poisson reduction	FEM source contract