FDM multi-magnet grids

Last changes: Documentation changelog

Physical problem

FDMGrid provides body-local Cartesian cells; FDMDemag requests a common demagnetization strategy. A request is not an implicit resampling permission.

Governing equations

(1)\[\mathbf H_a=\sum_b\mathcal N_{ab}*\mathbf M_b .\]

Symbols and SI units

Symbol

Meaning

SI unit

\(\mathbf H_a\)

field on layer \(a\)

A m^-1

\(\mathcal N_{ab}\)

cross-kernel

1

\(\mathbf M_b\)

magnetization on layer \(b\)

A m^-1

Assumptions and validity

Names are non-empty and values are FDMGrid. With multiple magnets, strategy="single_grid" is rejected; the executable strategy is multilayer_convolution. Explicit fftw and mkl requests are unavailable in this build, rustfft is the CPU realization, and cufft is the CUDA realization. Any explicit FFT backend requires an active demag interaction.

common_cell_size is incompatible with explicit mode="two_d_stack". For a 3-D plan, every component must divide the corresponding common convolution extent into an integer cell count within the planner tolerance; strict mode rejects a nonintegral ratio and does not round it. Runner preflight additionally requires a compatible certificate, common grid, transfers, masks, and memory accounting. This is not a convergence proof.

Python API

# %%
import fullmag as fm
nm = 1e-9
study = fm.study("two-magnet-grid")
study.engine("fdm")
study.fdm(
    default_cell=(2 * nm, 2 * nm, nm),
    per_magnet={
        "free": fm.FDMGrid(cell=(2 * nm, 2 * nm, nm)),
        "reference": fm.FDMGrid(cell=(4 * nm, 4 * nm, nm)),
    },
    demag=fm.FDMDemag(
        strategy="multilayer_convolution",
        mode="two_d_stack",
        common_cells_xy=(256, 128),
        fft_backend="rustfft",
    ),
)
free = study.geometry(
    fm.Box(60 * nm, 40 * nm, nm).translate((-40 * nm, 0.0, 0.0)),
    name="free",
)
free.Ms = 800.0e3
free.Aex = 13.0e-12
free.m = fm.texture.uniform(1.0, 0.0, 0.0)
reference = study.geometry(
    fm.Box(60 * nm, 40 * nm, nm).translate((40 * nm, 0.0, 0.0)),
    name="reference",
)
reference.Ms = 800.0e3
reference.Aex = 13.0e-12
reference.m = fm.texture.uniform(1.0, 0.0, 0.0)
study.demag()
study.stages.add_relax(stage_id="equilibrium", dt=5.0e-13, max_steps=1)

Python

Type

Default

SI unit

Validation

Meaning

Backend support

ProblemIR

FDMGrid.cell

Sequence[float]

required

m

exactly three positive finite values

native cell dimensions

FDM CPU source-backed; GPU capability-gated; FEM not applicable

per_magnet.<name>.cell

FDM.cell

Sequence[float] | None

None

m

exclusive with default_cell; three positive finite values

compatibility alias for default grid

FDM CPU source-backed; GPU capability-gated; FEM not applicable

cell and default_cell

FDM.default_cell

Sequence[float] | None

None

m

three positive finite values

default grid

FDM CPU source-backed; GPU capability-gated; FEM not applicable

default_cell

FDM.per_magnet

dict[str, FDMGrid] | None

None

m

non-empty names and FDMGrid values

named grid overrides

FDM CPU source-backed; GPU capability-gated; FEM not applicable

per_magnet

FDM.demag

FDMDemag | None

None

1

FDMDemag annotation; no constructor type guard; .to_ir() is called when present

nested demag policy

FDM CPU source-backed; GPU capability-gated; FEM not applicable

demag

FDMDemag.strategy

str

auto

1

auto, single_grid, or multilayer_convolution; single_grid rejects multiple magnets

demag strategy

FDM CPU source-backed; GPU capability-gated; FEM not applicable

demag.strategy

FDMDemag.mode

str

auto

1

auto, two_d_stack, three_d

grid topology mode

FDM CPU source-backed; GPU capability-gated; FEM not applicable

demag.mode

FDMDemag.common_cells

tuple[int, int, int] | None

None

cells

three positive integers; exclusive with common_cells_xy and common_cell_size; incompatible with two_d_stack

common 3-D cell counts

FDM CPU source-backed; GPU capability-gated; FEM not applicable

demag.common_cells

FDMDemag.common_cells_xy

tuple[int, int] | None

None

cells

positive values; only auto or two_d_stack

common in-plane cells

FDM CPU source-backed; GPU capability-gated; FEM not applicable

demag.common_cells_xy

FDMDemag.common_cell_size

tuple[float, float, float] | None

None

m

positive finite; exclusive with count fields; forbidden with explicit two_d_stack; must divide every common extent without rounding

common convolution cell size

FDM CPU source-backed; GPU capability-gated; FEM not applicable

demag.common_cell_size

FDMDemag.fft_backend

str

auto

1

explicit choice requires active demag; fftw and mkl unavailable; rustfft CPU; cufft CUDA

requested FFT backend

auto resolves by lane; rustfft CPU; cufft CUDA; fftw/mkl unsupported

demag.fft_backend

FDMDemag.explain

bool

True

1

no runtime type guard

authoring-only explanation flag

authoring only; not a backend capability

not lowered

FDMDemag.allow_single_grid_fallback

bool | None

None

1

any non-None value raises ValueError

removed compatibility input

unsupported on all lanes

no field; construction fails

ProblemIR

StudyBuilder.fdm(...) applies the complete FDM policy to the current study. FDM(cell=...) is the compatibility form: it emits both cell and default_cell, and cannot be combined with default_cell. FDM.demag nests FDMDemag.to_ir() as demag. That payload always contains strategy, mode, and fft_backend, and conditionally contains common_cells, common_cells_xy, or common_cell_size. explain is accepted by the Python object but deliberately not lowered.

Round-trip and failure semantics

Requested intent preserves native grids and the nested demag policy, including requested FFT realization. Resolved execution requires a certified common grid and a lane-compatible FFT backend. Validation errors cover malformed grids, conflicting common-grid controls, nondivisible common extents, unknown enum values, unavailable/lane-incompatible FFT requests, explicit FFT without active demag, multi-body single_grid, and every non-None request for the removed fallback input. Unsupported combinations, transfers, certificates, or budgets reject before allocation without fallback.

Discrete realization

validate_multilayer_grid_budget checks topology-bound certificates, layer grid equality, masks, and kernel accounting. The CPU operator owner is MultilayerDemagRuntime::compute_demag_fields_checked: it pushes each source to the convolution grid, performs FFTs, accumulates every destination/source tensor pair, then inverse-transforms and pulls fields to native grids. CUDA owns the analogous FP64/FP32 paths in launch_multilayer_demag_field_fp64 and launch_multilayer_demag_field_fp32.

Implementation mapping

Python owns schema/lowering and StudyBuilder.fdm(...) applies it to the active study. FdmDemagHintsIR::validate owns the explicit two_d_stack/common_cell_size rejection; plan_fdm_multilayer owns multi-body strategy and exact common-grid resolution; plan_fdm_fft owns FFT lane selection. Runner owns preflight. The engine and native CUDA functions listed below own convolution execution.

Validation

Check IR names and grids, require a resolved certificate, then test invalid common-grid/certificate inputs. Sweep native and common cells for physical convergence.

Limitations

This contract does not prove two_d_stack equals three_d or GPU parity. explain has no runtime type guard and is not represented in ProblemIR. FDM.demag likewise relies on its annotation and calls .to_ir() when present. The example applies its per-magnet grids and FFT policy directly through StudyBuilder.fdm(...).

Scientific bibliography

Source-code index