FDM Meshing API

Last changes: Documentation changelog

Problem statement

FDM(...) defines requested Cartesian-grid intent. The planner resolves integer dimensions, origins, masks, optional per-magnet grids, common convolution-grid policy, boundary correction, device, and precision.

Governing equations

This API introduces no independent physical equation. It selects the structured discrete space used by FDM interaction and time-integration operators.

Symbols and SI units

All cell and distance values are SI metres. Counts, masks, fractions, strategy names, and mode names are dimensionless.

Assumptions and validity

At least one default or per-magnet cell specification is required. Cell vectors have exactly three finite positive components. Conflicting aliases and common-grid specifications fail immediately. Boundary-correction support remains interaction/device capability-gated.

Python API

Python

Type

Default

SI unit

Validation

Meaning

Backend support

ProblemIR

FDM.cell

Sequence[float] | None

None

m

Three finite positive values; cannot be combined with default_cell.

Legacy alias for the default native cell size.

FDM CPU/GPU

backend_policy.discretization_hints.fdm.cell

FDM.default_cell

Sequence[float] | None

None

m

Three finite positive values.

Default native cell size inherited by magnets without an override.

FDM CPU/GPU

backend_policy.discretization_hints.fdm.default_cell

FDM.per_magnet

dict[str, FDMGrid] | None

None

1

Nonempty names and FDMGrid values.

Object-owned native grid overrides.

FDM CPU/GPU; multilayer capability-gated

backend_policy.discretization_hints.fdm.per_magnet

FDM.demag

FDMDemag | None

None

1

Typed, internally consistent demag policy.

Single-grid or multilayer common-grid request.

FDM demagnetization lanes

backend_policy.discretization_hints.fdm.demag

FDM.projection_policy

str | None

None

1

None or the supported unit_sphere policy.

Projected-RK state constraint policy; None selects the qualified default.

FDM CPU/GPU; planner checks combinations

backend_policy.discretization_hints.fdm.projection_policy

FDM.boundary_correction

str | None

None

1

none, volume, or full.

Requested embedded-boundary correction.

Interaction/device capability-gated

backend_policy.discretization_hints.fdm.boundary_correction

FDM.boundary_phi_floor

float | None

None

1

Strictly between zero and one.

Minimum stable partial-cell volume fraction.

Boundary-correction lanes

backend_policy.discretization_hints.fdm.boundary_phi_floor

FDM.boundary_delta_min

float | None

None

m

Finite and nonnegative.

Minimum geometric distance used by full correction.

Boundary-correction lanes

backend_policy.discretization_hints.fdm.boundary_delta_min

 
# %% Complete stage-first FDM mesh scenario
import fullmag as fm

nm = 1.0e-9
study = fm.study("fdm_meshing_api")
study.engine("fdm")
study.device("cpu", precision="double")
study.mode("strict")
study.objects.mesh.defaults(cell_size=(2 * nm, 2 * nm, 5 * nm))

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

study.exchange()
study.demag()
study.stages.add_run(stage_id="run", until=1.0e-12)

ProblemIR

The table gives canonical request destinations. Resolved execution adds integer shape, origin, spacing, masks/fractions, FFT padding, common-grid transfer, kernel digest, device, and precision.

Round-trip and failure semantics

Requested intent is preserved independently from resolved execution. Validation errors reject nonpositive cells, alias conflicts, invalid strategy/mode combinations, and invalid boundary parameters. Unsupported combinations fail capability checks without silent fallback.

Discrete realization

Solver

Device

Contract

FDM

CPU

host Cartesian state, masks, stencils, and FFT resources

FDM

GPU

identical semantic grid with device arrays and qualified CUDA kernels

FEM

CPU/GPU

not applicable; FEM uses conforming elements

Implementation mapping

The constructor and typed subpolicies lower in fullmag.model.discretization; runtime realization is documented in the backend FDM meshing branch.

Validation

Verify coordinate reconstruction, magnetic volume, constant/affine stencil behavior, mask/fraction convergence, common-grid transfer, kernel cache identity, and CPU/GPU parity on one serialized grid.

Limitations

Cartesian grids staircase arbitrary curved boundaries, one thickness cell is a thickness-averaged model, and public boundary-correction fields do not establish universal kernel support.

Scientific bibliography

  1. A. J. Newell, W. Williams, and D. J. Dunlop, “A generalization of the demagnetizing tensor for nonuniform magnetization,” J. Geophys. Res. 98, 9551–9555 (1993).

  2. C. Abert, “Micromagnetics and spintronics: models and numerical methods,” Eur. Phys. J. B 92, 120 (2019).

Control Room crosswalk

Status: Frontend support is not implemented unless a named source-backed panel is added.

Python/API surface

Control Room path

Status

Transaction

Parameters documented on this page

See the capability register; no page-specific route is established

not implemented

No supported frontend transaction

Parameters without a named UI field

See the capability register; no page-specific route is established

not implemented

Python-only until implemented

frontend support is not implemented for this API surface and its parameters. See Control Room capability register for the support matrix and not implemented policy. Frontend source owner: apps/control-room/src/modules/inspector/inspectorRouteCatalog.tsx (inspectorRouteCatalog).

Source-code index

Claim

Path

Stable symbol

Responsibility

Evidence

constructor and lowering

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

class FDM

default/per-magnet grid and boundary policy

signature and IR tests

per-magnet grid

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

class FDMGrid

positive cell triple

validation tests

demag grid policy

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

class FDMDemag

strategy, mode, and common-grid consistency

validation tests