FDM tensor convolution and FFT demagnetization¶

Scope and purpose¶

The canonical demagnetizing interaction is documented in FDM tensor convolution and FFT demagnetization. This page owns the FDM realization: a Cartesian cell grid, a cell-averaged demagnetization tensor, zero-padded open-boundary convolution, and a field/energy reduction with one shared physical convention. Python can author an FDM CPU or GPU request, but execution and qualification remain separate per device lane.

Scientific and numerical model¶

The cell-averaged field is the tensor convolution

The energy is reduced from the accepted field and magnetization:

The open-boundary FFT implementation embeds the finite convolution in a padded domain:

The tensor is constructed from Newell cell integrals; the FFT is an acceleration of the finite convolution, not an assumption of periodic physical boundaries.

Symbols and SI units¶

Assumptions and validity¶

• The mesh is Cartesian and each active cell has a defined volume and magnetization mask.

• Open boundaries require the documented padding and kernel embedding. A periodic FFT without the periodic demag policy is a different problem.

• The cell-averaged Newell tensor is exact for the chosen rectangular-cell discretization; it does not remove grid, geometry-mask, or finite-precision error.

• GPU FP32 and FP64 are separate precision lanes. Matching source code is not parity evidence, and authoring a GPU request does not prove that the GPU executed it.

• Multilayer convolution uses an explicit multilayer policy with an authored or planner-resolved common scratch layout. A failed common-grid resolution must not silently fall back to a single-grid approximation.

• Omitting both common_cells and common_cells_xy delegates scratch-grid selection to Fullmag’s planner-auto policy. This is not a reproduction of BORIS ncommonstatus=false: the authored ProblemIR simply has no common_cells* fields, while the resolved union-scratch layout is recorded separately in the plan/provenance.

• Fullmag mode="two_d_stack" is not BORIS 2dmulticonvolution=1 or =2. It requires one native Z cell per layer; use three_d for native through-thickness cells.

Python API¶

# %% Configure FDM demagnetization as a stage-first study
import fullmag as fm

nm = 1.0e-9
study = fm.study("fdm_demag_convolution")
study.engine("fdm")
study.device("cpu", precision="double")
study.mode("strict")
film = study.geometry(
    fm.Box(size=(100 * nm, 20 * nm, 5 * nm), name="film"),
    name="film",
)
film.mesh(cell_size=(2 * nm, 2 * nm, 5 * nm))
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.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-14,
    max_err=1.0e-7,
    tolT=1.0e-6,
    max_steps=50_000,
)

Parameters¶

The older study.fdm(...), FDMGrid, and FDMDemag forms are migration adapters, not the canonical authoring surface. For heterogeneous layers, common-XY versus full-3D behavior, and the complete 2 nm / 5 nm / 10 nm example, see FDM multilayer demagnetizing-field convolution.

ProblemIR and provenance¶

The physical request remains Demag; the FDM policy is nested under backend_policy.discretization_hints.fdm:

{
  "energy_terms": [{"kind": "demag"}],
  "backend_policy": {
    "discretization_hints": {
      "fdm": {
        "default_cell": [2e-9, 2e-9, 5e-9],
        "per_magnet": {
          "film": {"cell": [2e-9, 2e-9, 5e-9]}
        },
        "demag": {"strategy": "auto", "mode": "auto"}
      }
    }
  }
}

Normalization records requested strategy and mode. Planning resolves grid dimensions, FFT padding, mask, precision and memory budget; those resolved values belong to provenance and must not be inferred from auto after the run.

Diagnostics and failure semantics¶

Script export preserves the stage-first study and object-owned discretization policy. The round trip reports validation errors for invalid cell sizes and malformed common grids. The unsupported combinations are explicit: FEM requests, periodic axes without the periodic demag policy, and unavailable GPU precision lanes are rejected or reported by the planner; they do not silently become an open single-grid CPU run. A successful Python/ProblemIR GPU request is authoring evidence only; it becomes a GPU execution claim only with an executed-device receipt. Requested intent, resolved execution and provenance are separate.

Discrete realization by lane¶

CPU and GPU must share the tensor convention, sign and energy definition. They may differ in FFT library, storage layout, precision, reductions and residency.

Where this is implemented¶

Validation¶

Validation requires Newell self-term and tensor symmetry checks, analytical body factors, open-boundary padding convergence, field/energy consistency, CPU/GPU parity at the same precision, and an executed device identity for GPU claims. A Python capture or matching FFT output alone is not continuum or runtime qualification.

Limitations¶

The page does not claim arbitrary geometry exactness, universal FP32 accuracy, or periodic physics from ordinary zero-padded convolution. Partial-cell corrections and multilayer modes remain lane- and validation-dependent.

Scientific bibliography¶

• A. J. Newell, W. Williams and D. Dunlop, “A method for computing the demagnetizing factors for rectangular ferromagnetic prisms,” Journal of Geophysical Research 98 (1993), DOI: 10.1029/93JB00694.

• J. M. D. Coey, Magnetism and Magnetic Materials, Cambridge University Press, 2010.

• Canonical physics owner: FDM tensor convolution and FFT 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¶