Finite-difference meshing

Last changes: Documentation changelog

Last changes: 12:31 24.08.2026

Fullmag FDM meshing is owned by the Study execution plan and produces a structured lattice plus canonical magnetic-support masks and region metadata.

Implementation status

FDM grid authoring, single-grid execution and multi-grid convolution are implemented with capability-dependent restrictions. Object-level FDM mesh panels are read-only by design.

Scope and purpose

Use the pages in this branch to configure and validate Cartesian cells, cut-cell boundary correction, multiple magnets and periodic grids. The detailed common formulation and parameter table are on the parent FDM Cartesian grids page.

Scientific and numerical model

Scientific invariants

An FDM grid stores the magnetization on a Cartesian lattice with cell dimensions \(\Delta x\), \(\Delta y\) and \(\Delta z\). Cell centers are

(1)\[\mathbf r_{ijk}=\mathbf r_0+ \left(i+\tfrac12,j+\tfrac12,k+\tfrac12\right) \odot(\Delta x,\Delta y,\Delta z).\]

The cell size simultaneously controls geometry voxelization, finite-difference exchange and the accuracy/cost of FFT demagnetization. It must therefore resolve the smallest magnetic length scale, the smallest geometric feature and the desired boundary accuracy. The exchange-length expression

(2)\[\ell_{\mathrm{ex}}=\sqrt{\frac{2A}{\mu_0M_s^2}}\]

is a useful initial guide, but final values require a grid-refinement study. A one-cell film thickness is a thickness-averaged discretization; it cannot represent a nonuniform mode across the thickness.

The FDM topology is implicit in (origin, spacing, shape) and the active-cell/region arrays. A valid result therefore requires all of these resources to share one grid fingerprint. An array with the correct length but a different origin or shape is not compatible.

Selection guide

Use case

Recommended choice

Reason

Basic single-body model

FDM Cartesian grids

Start with the common grid contract

Curved/cut geometry

Boundary correction

Control occupancy treatment at the staircase boundary

Several magnetic bodies

Multi-magnet grids

Resolve per-magnet and common convolution grids

Infinite/repeated lattice

Periodic grids

Configure mesh periodicity and demag images separately

Parameters

Python / IR key

Unit

Default

Validation

Numerical effect

default_cell / study.cell(dx,dy,dz)

m

required unless all magnets override it

three positive finite components

Cartesian cell dimensions used by geometry, exchange and demag

per_magnet

m

{}

mapping keyed by canonical magnet name

object-specific cell dimensions; must be compatible with the chosen demag strategy

demag.strategy

1

auto

auto, single_grid, multilayer_convolution

selects one shared FFT lattice or the multi-grid convolution plan

demag.mode

1

auto

auto, two_d_stack, three_d

constrains multi-grid convolution geometry

demag.common_cells

cells

unset

three positive integers; exclusive with common_cells_xy

forces the common 3-D convolution lattice shape

demag.common_cells_xy

cells

unset

two positive integers; exclusive with common_cells

forces the common in-plane lattice for a 2-D stack

demag.common_cell_size

m

unset

three positive finite components

overrides the common convolution cell size when supported

demag.explain

1

True

Boolean

requests a resolved plan/provenance explanation

boundary_correction

1

none

none, volume, full

selects cut-cell occupancy correction at geometry boundaries

boundary_phi_floor

1

backend default

strictly between 0 and 1

lower occupancy clamp used by corrected boundary operators

boundary_delta_min

m

0

non-negative

minimum distance/width regularization in boundary correction

Python API

Complete Python example

import fullmag as fm

nm = 1.0e-9
study = fm.study("fdm_grid_reference")
study.engine("fdm")
study.device("cpu", precision="double")
study.mode("strict")
study.universe(
    mode="manual",
    size=(160 * nm, 320 * nm, 10 * nm),
    center=(0.0, 0.0, 0.0),
    padding=(0.0, 0.0, 0.0),
)
# 32 x 64 x 2 cells in the universe; all dimensions are SI metres.
study.cell(5 * nm, 5 * nm, 5 * nm)

film = study.geometry(
    fm.Box(size=(100 * nm, 300 * nm, 10 * nm), name="film"),
    name="film",
)
film.Ms = 800.0e3
film.Aex = 13.0e-12
film.alpha = 0.02
film.m = fm.texture.uniform(1.0, 1.0e-4, 0.0)

study.exchange()
study.demag()
study.b_ext(0.0, 0.0, 1.0e-3)
study.solver(fix_dt=1.0e-13, g=2.115)
study.stages.add_relax(
    stage_id="equilibrium",
    algorithm="llg_overdamped",
    dt=1.0e-13,
    tolA=1.0e-4,
    max_steps=5_000,
).tableautosave(
    every_steps=25,
    quantities=["step", "t", "mx", "my", "mz", "e_ex", "e_demag", "e_total"],
)

Control Room workflow

  1. Select Study in Explorer and set Backend = FDM in the Study Inspector.

  2. Enter FDM default cell as dx, dy, dz in metres, or provide FDM per-magnet grids as a JSON object keyed by canonical magnet name.

  3. Select FDM demag: auto, single_grid, or multilayer_convolution. For more than one magnet, the current authoring model rejects single_grid and requires multilayer_convolution.

  4. Select FDM demag mode (auto, two_d_stack, three_d). Optional Common convolution cells (Nx, Ny, Nz) and Common convolution cells XY (Nx, Ny) are mutually exclusive.

  5. Keep Explain FDM demag plan enabled while developing a model. Review the resolved strategy, common lattice and any incompatibility before execution.

  6. Select an object’s mesh route to inspect the realized structured-grid origin, spacing, shape, active/inactive support cells, region metadata and grid fingerprint. This object view is read-only; FDM grid authoring is owned by the Study execution plan.

Verification, quality and provenance

After every build, inspect the realized resource rather than assuming that the authored request was applied. The production check is:

  • geometry and mesh revisions match the current model;

  • requested and realized discretization/topology/order are recorded;

  • node, element and boundary-facet counts are nonzero for every required region;

  • region and boundary markers cover the complete topology;

  • inverted and degenerate element counts are zero;

  • interface diagnostics report no orphan, coincident, nonmanifold or unmatched facets;

  • local size distributions are consistent with the intended edge/interface/core grading;

  • any fallback or degradation has an explicit reason and an actual method;

  • a mesh-refinement sequence demonstrates convergence of the scientific observable.

MeshQualityReport exposes signed inverse condition number (SICN), gamma/radius quality, volume statistics and optional per-element arrays. The source constants gamma_min=0.08 and SICN p05=0.1 are implementation gates for named report paths; they are not universal physical acceptance thresholds for every element family or study.

Mesh-convergence protocol

A production result should include at least three discretizations. Refine only the parameter under study while holding geometry, material parameters, solver tolerances, initial state and output sampling fixed. Let \(Q_h\) denote the observable for characteristic size \(h\). Report

(3)\[\varepsilon_h=\frac{|Q_h-Q_{h/\rho}|}{\max(|Q_{h/\rho}|,Q_{\mathrm{scale}})}, \qquad \rho>1,\]

with a documented scale for observables that can cross zero. For dynamics, compare resonance frequency, linewidth and mode profile; for relaxation, compare total energy and texture; for demag, compare field/energy and verify that moving the outer boundary does not change the result beyond the chosen tolerance.

Diagnostics and failure semantics

A structured grid descriptor is insufficient without the canonical binary support mask. Legacy or ambiguous masks must be reported as such; the UI must not invent active/inactive classification.

Where this is implemented

Responsibility

Repository source

Stable owner / symbol

Python FDM schemas

packages/fullmag-py/src/fullmag/model/discretization.py

FDM, FDMGrid, FDMDemag

FDM object inspector model

apps/control-room/src/modules/inspector/panels/fdmMeshInspectorModel.ts

resolveFdmObjectMeshInspectorModel

Study authoring model

apps/control-room/src/modules/inspector/panels/StudyGlobalAuthoringModel.ts

StudyFdmDraft

FDM runner

crates/fullmag-runner/src/fdm/mod.rs

FDM execution

Implementation map reviewed against commit 5db00ccf0113b9756fec2d46feb36ade762b12c2 on 2026-08-24.

References

  • C. Geuzaine and J.-F. Remacle, “Gmsh: a three-dimensional finite element mesh generator with built-in pre- and post-processing facilities,” International Journal for Numerical Methods in Engineering 79 (2009), 1309–1331, doi:10.1002/nme.2579.

  • C. Abert, “Micromagnetics and spintronics: models and numerical methods,” European Physical Journal B 92, 120 (2019), doi:10.1140/epjb/e2019-90599-6.

  • Gmsh reference manual, mesh algorithms, size fields, extrusion and physical groups: gmsh.info/doc/texinfo.

  • A. J. Newell, W. Williams and D. J. Dunlop, “A generalization of the demagnetizing tensor for nonuniform magnetization,” J. Geophys. Res. 98 (1993), 9551–9555, doi:10.1029/93JB00694.

  • A. Aharoni, “Demagnetizing factors for rectangular ferromagnetic prisms,” J. Appl. Phys. 83 (1998), 3432–3434, doi:10.1063/1.367113.

Documentation tree

Source-code index

This is a navigation page and introduces no standalone implementation symbol. The exact source-code index is maintained by the selected terminal page.