FDM multilayer convolution: Python, ProblemIR, and UI¶

What this guide configures¶

This page is the authoring guide for Fullmag’s FDM multilayer demagnetization path. It shows how to give every named magnet its own Cartesian native grid, request a shared convolution layout, preserve that request in ProblemIR, and inspect the planner/runtime result in the Control Room. The magnetostatic equations and their derivation are owned by FDM multilayer demagnetizing-field convolution; this page owns the Python, ProblemIR, UI, and failure contracts.

Three layouts must not be confused:

1. a native layer grid carries the layer’s physical magnetization and field samples;

2. the common convolution grid is FFT scratch used for transfers and pair convolutions, not a physical mesh and not a visualization fallback;

3. an optional target-only Airbox grid carries only the published H_demag observation outside the magnetic support.

The public authoring vocabulary mirrors FEM: body.mesh(...) configures an object’s native mesh, while study.universe.mesh(...) configures the shared computational domain. For FDM both calls use cell_size=(dx, dy, dz). The common domain is FFT scratch, not an extra magnetic body. Layer separation still comes only from geometry transforms and the resulting native-grid origins.

Authoring-to-grid relations¶

For layer \(\ell\), Fullmag realizes the cell-center coordinates from the native origin and authored cell size as

With an explicit two-dimensional stack request, the authored in-plane common-grid size fixes the resolved transform-grid cell count to

For \(L\) layers the planner records \(L^2\) ordered source-to-destination interactions. Kernel reuse is not determined by a physical separation alone. The reusable implementation key quantizes the signed \(z\) displacement in units of the resolved convolution-cell thickness and also contains the source and destination cell sizes and the common convolution-grid shape:

These relations define the numerical layout only. They do not replace the demagnetizing-field and energy equations on the physics page.

Symbols and SI units¶

Assumptions and validity¶

The planner forms a computational common-scratch envelope from the union of every native XY rectangle. Therefore multilayer bodies may have different XY extents and centers; their native origins, masks, and physical meshes remain separate, and a non-coincident layer is marked push_pull. An explicit common_cells or common_cells_xy must contain that union with a compatible pitch. A runtime lane that cannot consume the resulting insertion/crop or transfer descriptor fails closed. This transfer path is not a claim that Appendix-A irregular Newell supports arbitrary different XY cells: the irregular kernel itself requires common XY cell sizes. Bodies may be separated along \(z\), but they may not overlap there. two_d_stack requires one native Z cell per layer. A multi-cell-Z request fails closed: no public moment-preserving Z reduction exists, so the planner never copies one arbitrary native slice. Select three_d for through-thickness cells. Open boundaries are executable; periodic multilayer axes fail closed. Per-object regions, thermal noise, spin torque, Oersted terms, regional field drives, spatial material fields, and bulk DMI are currently rejected for this path. CPU execution accepts FP64 only. CUDA FP32/FP64 has separate runtime and qualification requirements; representability in Python or ProblemIR is not proof that a requested GPU lane executed.

Python API¶

# %% Imports and study execution intent
import fullmag as fm

nm = 1.0e-9
study = fm.study("fdm_multilayer_python_guide")
study.engine("fdm")
study.device("cpu", precision="double")
study.mode("strict")
study.interactive(False)

# %% Native cell size
native_cell = (4.0 * nm, 4.0 * nm, 3.0 * nm)

# %% Universe and three non-overlapping, XY-aligned layers
study.universe(
    mode="manual",
    size=(40.0 * nm, 20.0 * nm, 30.0 * nm),
    center=(0.0, 0.0, 9.0 * nm),
    padding=(0.0, 0.0, 0.0),
)

layer_size = (32.0 * nm, 16.0 * nm, 3.0 * nm)
bottom = study.geometry(fm.Box(size=layer_size), name="layer_bottom")
middle = study.geometry(
    fm.Box(size=layer_size).translate((0.0, 0.0, 9.0 * nm)),
    name="layer_middle",
)
top = study.geometry(
    fm.Box(size=layer_size).translate((0.0, 0.0, 18.0 * nm)),
    name="layer_top",
)
for layer in (bottom, middle, top):
    layer.mesh(cell_size=native_cell)
study.universe.mesh(cell_size=native_cell)

# %% Material state and interactions
for layer in (bottom, middle, top):
    layer.Ms = 800.0e3
    layer.Aex = 13.0e-12
    layer.alpha = 0.02
    layer.m = fm.init.UniformMagnetization((1.0, 0.0, 0.0))

study.exchange(enabled=True)
study.demag(enabled=True)
study.b_ext(-24.6e-3, 4.3e-3, 0.0)

# %% Output and stage
study.save("H_demag", every=1.0e-13)
study.solver(integrator="rk4", fix_dt=1.0e-14, gamma=2.211e5)
study.tableautosave(
    1.0e-13,
    quantities=["step", "t", "mx", "my", "mz", "e_demag", "e_total"],
)
study.stages.add_run(until=1.0e-13, stage_id="multilayer_run")

# %% Complete study with a target-only Airbox observation
import fullmag as fm

nm = 1.0e-9
study = fm.study("fdm_multilayer_airbox_guide")
study.engine("fdm")
study.device("cpu", precision="double")
study.mode("strict")
study.universe(mode="manual", size=(40.0 * nm, 20.0 * nm, 30.0 * nm), center=(0.0, 0.0, 4.5 * nm))
bottom = study.geometry(fm.Box(size=(32.0 * nm, 16.0 * nm, 3.0 * nm)), name="bottom")
top = study.geometry(
    fm.Box(size=(32.0 * nm, 16.0 * nm, 3.0 * nm)).translate((0.0, 0.0, 9.0 * nm)),
    name="top",
)
for layer in (bottom, top):
    layer.mesh(cell_size=(4.0 * nm, 4.0 * nm, 3.0 * nm))
study.universe.mesh(cell_size=(4.0 * nm, 4.0 * nm, 3.0 * nm))
for layer in (bottom, top):
    layer.Ms = 800.0e3
    layer.Aex = 13.0e-12
    layer.alpha = 0.02
    layer.m = fm.init.UniformMagnetization((1.0, 0.0, 0.0))
study.exchange(enabled=True)
study.demag(enabled=True)
study.save("H_demag", every=1.0e-13)
study.runtime_metadata(
    "airbox_observation",
    {
        "cells": (10, 6, 12),
        "spacing_m": (4.0 * nm, 4.0 * nm, 3.0 * nm),
        "origin_m": (-20.0 * nm, -12.0 * nm, -15.0 * nm),
        "padding_cells_above_below": (4, 6),
        "target_only": True,
        "scope_kind": "airbox",
        "published_quantities": ("H_demag",),
        "unavailable_quantities": {
            "H_eff": "fdm_multilayer_airbox_h_eff_unavailable.v1",
        },
    },
)
study.solver(integrator="rk4", fix_dt=1.0e-14, gamma=2.211e5)
study.stages.add_run(until=1.0e-13, stage_id="airbox_run")

Canonical ProblemIR¶

The public mesh-authoring calls produce backend_policy.discretization_hints.fdm. The following JSON is the canonical ProblemIR wrapper produced by the first example’s FDM objects; explain is absent by design because it is an authoring/display preference. The surrounding backend_policy path is part of the canonical contract, not an illustrative shorthand:

{
  "backend_policy": {
    "requested_backend": "fdm",
    "execution_precision": "double",
    "discretization_hints": {
      "fdm": {
        "cell": [4e-09, 4e-09, 3e-09],
        "default_cell": [4e-09, 4e-09, 3e-09],
        "per_magnet": {
          "layer_bottom": {"cell": [4e-09, 4e-09, 3e-09]},
          "layer_middle": {"cell": [4e-09, 4e-09, 3e-09]},
          "layer_top": {"cell": [4e-09, 4e-09, 3e-09]}
        },
        "demag": {
          "strategy": "multilayer_convolution",
          "mode": "two_d_stack",
          "common_cells_xy": [8, 4]
        }
      }
    }
  }
}

The physical interaction remains a separate global Demag energy term. study.demag(enabled=True) controls whether that term is enabled; the mesh calls are a distinct FDM discretization policy which selects how that enabled term is realized. They are not normalized by one shared Python resolver. The planner lowers the authored FDM subtree to BackendPlanIR::FdmMultilayer, whose resolved payload contains:

• mode, common_cells, and a topology-bound grid_certificate;

• one FdmLayerPlanIR per named magnet with layer_id, object_id, native grid, native origin, active mask, convolution layout, and transfer_kind (identity or push_pull);

• planner_summary.requested_strategy, selected_strategy, requested_mode, resolved_mode, eligibility, pair/unique-kernel counts, memory estimate, and warnings;

• resolved precision, integrator, fixed timestep, enabled interactions, periodicity, and output plan.

This resolved plan is runtime input and provenance. It is not written back over the authored Python request.

Round-trip, requested intent, and failure semantics¶

Requested intent is the Python/UI strategy, mode, native cell sizes, optional common-grid counts, precision, device, and execution mode. auto remains auto in authored ProblemIR. Resolved execution is recorded separately in the execution plan and artifacts: actual mode, common-grid shape, native origins and masks, transfer kinds, grid fingerprints, pair-kernel counts, selected runtime engine, precision, FFT backend, and runtime/device identity.

Python constructor validation errors reject malformed vectors, non-positive sizes, Boolean cell counts, incompatible common-grid fields, invalid modes/strategies, empty magnet names, wrong grid objects, and the removed fallback switch. Rust deserialization repeats the demag-policy checks for non-Python producers. Planner validation errors reject geometry and capability violations before allocation. Unsupported combinations fail without silently changing multilayer to single-grid, CUDA to CPU, or three_d to two_d_stack.

The Control Room’s global Demag toggle is exported as study.demag(...); the FDM policy is exported independently through the public mesh-authoring calls. A saved explain checkbox may round-trip through authoring state and generated Python even though it does not enter physical ProblemIR.

Backend support and qualification¶

Control Room workflow¶

Validation checklist¶

Before treating a configuration as executable, verify:

• every per_magnet name matches an authored magnet;

• the planner’s common scratch envelope contains every native XY rectangle; layers do not overlap along Z;

• two_d_stack layers each have one native Z cell;

• the common-grid field matches the mode and is within the planner memory budget;

• Demag is enabled and requested/resolved strategies are visible in provenance;

• every native layer has the expected fingerprint, mask, transfer kind, and sample coverage;

• any Airbox carrier reports CPU FP64 runtime origin, target_only=true, H_demag only, and matching field/layout fingerprints;

• GPU claims include a fresh managed device execution receipt; UI claims include a fresh WebGL receipt as described above.

Limitations¶

The public constructors describe more combinations than are production-qualified. The common grid is not a mesh authoring surface. The target-only Airbox is currently CPU FP64 post-processing, not a hot-loop field carrier, and publishes no H_eff. Its runtime-metadata request is deliberately strict and is not a general arbitrary-observation-grid API. Periodic multilayer execution and the capability-gated physics listed under assumptions remain unavailable. Fresh browser/WebGL evidence for every Airbox display mode and fresh managed CUDA parity are separate release gates.

Scientific bibliography¶

The physical derivation and primary literature are collected on FDM multilayer demagnetizing-field convolution. This guide uses the repository implementation and tests as the source of truth for public API, ProblemIR, planner, runtime-resource, and UI behavior.

Source-code index¶