FDM Cartesian grids¶

Physical problem¶

Let a magnetic region occupy a bounded subset of a rectangular Cartesian universe. Fullmag stores one magnetization vector per active FDM cell. The rectangular allocation also contains inactive cells outside the magnetic support. Geometry voxelization determines the active/material mask and, when boundary correction is requested and supported, a magnetic volume fraction.

The cell spacing controls geometry occupancy, local finite-difference operators, FFT demagnetization kernels, allocation size, and the shortest represented wavelength. It must resolve the smallest relevant geometric and magnetic length scales. A one-cell film thickness is a thickness-averaged model and cannot resolve a nonuniform thickness mode.

Governing grid equations¶

For cell-boundary origin \(\mathbf x_0\), native spacings \((h_x,h_y,h_z)\), and zero-based indices,

The rectangular allocation has cell volume and count

With a binary active/material mask, the following is the documentary volume identity derived from the resolved mask and spacing:

If a supported boundary-correction route supplies cell fractions, the corresponding documentary volume identity is

The native grid of magnetic body \(r\) is the implementation tuple

For multilayer convolution, source and target identities must remain distinct. For every source layer \(s\), the CPU runtime pushes magnetization to that layer’s common transform layout and performs one forward FFT. For every ordered pair \((r,s)\), a destination/source binding selects the pair tensor from the kernel catalog and accumulates into target \(r\). Finally, each target is negated, inverse transformed, cropped, and pulled to its native grid:

Local interaction pages own exact field stencils and boundary equations. On an interior uniform axis,

Here \(\widehat{\mathbf N}_{rs}\) is selected by the ordered binding with dst_layer = r and src_layer = s. Catalog deduplication may let several ordered bindings reuse one stored tensor, but it does not merge source magnetizations or target accumulators. For \(L\) layers, one refresh performs \(L\) forward FFTs, \(L^2\) ordered-pair accumulations, and \(L\) inverse FFTs when all pairs are present.

The first-derivative formula is realized for interior active neighbours by multilayer_dmi_field_kernel; missing/inactive neighbours are clamped to the centre and DMI boundary corrections are applied separately. The second-derivative formula is the uniform-material fast path of exchange_field_fp64_kernel; its general path uses per-neighbour exchange coefficients, active masks, and periodic wrap or clamped Neumann neighbours. The displayed formulas therefore do not define cut-cell, interface, or boundary treatment.

Symbols and SI units¶

Assumptions and validity¶

• Spacings are finite, strictly positive SI lengths; grids are axis-aligned and Cartesian.

• Cell counts are positive integers resolved from geometry, spacing, and planner policy.

• Geometry smaller than a cell can disappear or change occupancy under a sub-cell translation.

• A demag kernel is tied to grid shape, spacing, boundary policy, and precision.

• common_cells, common_cells_xy, and common_cell_size are alternative common-grid requests, not native-grid cell sizes.

• Grid refinement establishes adequacy for the reported observable.

• The centre and volume equations are grid definitions. resolved_fdm_cell_centers implements the centre coordinates; FdmPlanIR carries the resolved shape, spacing, masks, and origin from which the volume identities are derived. FDMGrid itself validates spacing only.

• compute_boundary_geometry realizes \(\phi_{ijk}\) by fixed \(4^3\) SDF sub-sampling per cell for the boundary-correction geometry route; the volume sum is a documented derived quantity, not a claim that every backend computes a standalone V_mh scalar.

Python API¶

# %% Imports and study
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.objects.mesh.defaults(cell_size=(2 * nm, 2 * nm, 2 * nm))
study.universe.mesh(cell_size=(1 * nm, 1 * nm, 1 * nm))

# %% Magnetic bodies and native grids
bottom = study.geometry(
    fm.Box(size=(80 * nm, 40 * nm, 2 * nm)).translate((0.0, 0.0, -2 * nm)),
    name="bottom",
)
top = study.geometry(
    fm.Box(size=(80 * nm, 40 * nm, 2 * nm)).translate((0.0, 0.0, 2 * nm)),
    name="top",
)
top.mesh(cell_size=(4 * nm, 4 * nm, 2 * nm))

# %% Materials and initial state
for body in (bottom, top):
    body.Ms = 800.0e3
    body.Aex = 13.0e-12
    body.alpha = 0.02
    body.m = fm.texture.uniform(1.0, 0.0, 0.0)

# %% Physics and stage
study.exchange()
study.demag()
study.stages.add_relax(
    stage_id="equilibrium",
    algorithm="llg_overdamped",
    dt=1.0e-13,
    tolA=1.0e-4,
    max_steps=5_000,
)

ProblemIR contract¶

Authored intent is stored at backend_policy.discretization_hints.fdm:

{
  "cell": [2e-9, 2e-9, 2e-9],
  "default_cell": [2e-9, 2e-9, 2e-9],
  "per_magnet": {"top": {"cell": [4e-9, 4e-9, 2e-9]}},
  "demag": {
    "strategy": "auto",
    "mode": "auto",
    "fft_backend": "auto",
    "common_cell_size": [1e-9, 1e-9, 1e-9]
  }
}

cell is a compatibility mirror of default_cell; Python emits both when a default exists. Optional fields are omitted when unset. projection_policy is emitted when requested. FDMDemag.explain is deliberately absent, while allow_single_grid_fallback cannot reach lowering because every non-None value is rejected. Canonical body.mesh lowers by canonical magnet name to per_magnet.<name>.cell; study.objects.mesh.defaults lowers to both default/compatibility cell fields; study.universe.mesh creates a demag object with strategy="auto", mode="auto", fft_backend="auto", and the authored common_cell_size.

ProblemIR records requested intent, not execution. Single-grid planning resolves FdmPlanIR. Multilayer planning resolves FdmMultilayerPlanIR with common counts, per-layer native grid, spacing, origin, masks, convolution descriptors, transfer kind, grid certificate, and planner_summary. The summary preserves requested_strategy/requested_mode separately from selected_strategy/resolved_mode.

Round-trip and failure semantics¶

Discrete realization¶

Each body grid owns origin, shape, spacing, active mask, region mask, and material data. Allocation size is \(N_xN_yN_z\) even when only a subset is magnetic. Supported boundary correction can replace binary occupancy by fractional volume and corrected local operators.

compute_newell_kernels constructs a cell-geometry-dependent Newell tensor and FftWorkspace owns single-grid spectra/cache state. CPU multilayer execution is owned by MultilayerDemagRuntime::compute_demag_fields_checked. Its persistent workspace stores separate m_fft[s] and h_fft[r] arrays. build_kernel_catalog_incrementally consumes KernelCatalogSpec::pair_bindings, materializes each unique tensor at most once, and retains every ordered src_layer/dst_layer binding. Runtime performs a forward transform per source, calls accumulate_tensor_convolution for every binding into the selected target accumulator, then negates, inverse-transforms, crops, and pulls each target field. VolumeWeightedTransfer or identity transfer realizes \(\mathcal P_s\) and \(\mathcal R_r\); these symbols do not promise arbitrary interpolation.

Implementation mapping¶

Validation and convergence¶

Source tests cover canonical lowering, common-grid conflicts, FFT request preservation, Python/Scene/script/ProblemIR round-trip, and fail-closed IR validation. CPU runtime tests additionally check three forward FFTs, nine ordered-pair accumulations, and three inverse FFTs for three layers, plus equality of the catalog result with a sum of separate pair runs. These tests do not prove a study is grid converged. Use at least three grid levels with geometry, materials, solver tolerances, initial state, and output sampling fixed. Report cell sizes, resolved shapes, active-cell counts, backend/device/precision, grid fingerprint, and convergence of the scientific observable.

Limitations¶

• Cartesian voxelization is stair-stepped without supported boundary correction.

• A common grid can increase memory; explicit counts remain subject to budget checks.

• Canonical authoring exposes spacing, not explicit native counts or origins.

• The centred-difference equations do not specify interface, cut-cell, or periodic stencils.

• Source-backed capability does not replace a runtime receipt for the selected lane.

Scientific bibliography¶

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

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

• A. Aharoni, “Demagnetizing factors for rectangular ferromagnetic prisms,” Journal of Applied Physics 83 (1998), 3432–3434, doi:10.1063/1.367113.

• W. F. Brown Jr., Micromagnetics, Interscience Publishers, New York (1963).

Related documentation¶

• FDM overview

• Boundary correction

• Multi-magnet grids

• Periodic grids

• Physics interactions

Runtime ownership and validation boundaries¶

Source-code index¶

Scope and purpose¶

This page defines the public contract for Cartesian FDM grid construction. It is an authoring and implementation reference: the Python example, the serialized ProblemIR description, the implementation mapping, and the adjacent source map are the source-backed contract. A capability marked partial or not evaluated is not presented as a production guarantee.

Scientific and numerical model¶

The mesh or grid is a discrete approximation of the continuous domain. For a Cartesian partition, each spacing satisfies Delta_i = L_i / N_i; for a geometry-dependent FEM mesh, the requested local target is bounded by the active bulk, interface, boundary, and topology constraints. In compact form, h_target(x) = min(h_bulk(x), h_interface(x), h_boundary(x)). Length quantities use SI metres (m); counts, orders, and topology labels are dimensionless.

The equations and assumptions in the earlier physical-problem and governing-equations sections state the model-specific specialization. This section does not introduce a conversion from FEM to FDM, a hidden topology conversion, or a silent CPU fallback.

Parameters¶

The exact callable and argument names are the ones shown in the ## Python API section above. For this page the parameter family is cell_size, grid dimensions, origin, and periodicity. Use the documented defaults, validation rules, and ProblemIR lowering exactly as shown; do not replace a canonical argument with an unlisted alias. Numerical lengths must be supplied in metres, and invalid positive-length, count, order, periodicity, or topology constraints must fail closed rather than being silently repaired.

Control Room workflow¶

In Control Room, select the engine and mesh workflow, enter the same values as the Python authoring example, inspect the planned mesh or grid report, and only then submit the run. The UI is a projection of the public contract: a missing control is not evidence that the backend accepts the option, and a visible control is not evidence that a production lane is enabled. When the page or capability register marks a field partial or not evaluated, keep the workflow explicitly bounded to the implemented path.

Diagnostics and failure semantics¶

A valid request must preserve the declared geometry, units, element or cell topology, and backend lane. Reject non-finite or non-positive lengths, invalid counts and orders, incompatible periodic or shared-boundary data, and unsupported topology combinations at the owning validation layer. Reports should retain requested and resolved values, source identity, and any capability gate. No diagnostic may hide a failed mesh realization by substituting another discretization.

Where this is implemented¶

The existing implementation-mapping and source-code-index sections identify the exact public authoring, ProblemIR, planner, realization, and runtime owners for this topic. The adjacent .source-map.json file is the machine-readable source of truth for those paths, symbols, responsibilities, backend matrix, and reviewed revision. Claims in this page must be updated together with that map when an owner moves.