FEM shared-domain assembly

Last changes: Documentation changelog

Last changes: 12:31 24.08.2026

Shared-domain assembly turns object and universe authoring into one revisioned solver mesh. Its manifest must prove conformity, semantic ownership, actual build mode, topology and fallback status.

Implementation status

Ordinary conforming tetrahedral assembly is implemented. Specialized mixed/swept modes and periodic pairing are separately qualified and must be checked in the manifest.

Scope and purpose

Read the child pages when a simulation contains several bodies, an exterior airbox, interfaces, mixed cell families or semantic mesh operations. The shared mesh is the final solver-facing discretization; object previews are inputs and diagnostics only.

Scientific and numerical model

Scientific invariants

A finite-element mesh is not only a visualization asset. It defines the trial/test spaces used by exchange, anisotropy, DMI, magnetostatic and dynamic operators. The following conditions are therefore part of the numerical contract:

  1. Every magnetic volume has an unambiguous region marker and every exterior-air volume has the canonical air role.

  2. Interfaces used by coupled operators are conforming, or an explicitly supported nonconforming coupling operator is selected. Fullmag’s ordinary shared-domain path expects conformity.

  3. Cell orientation is valid: the element mapping has a positive Jacobian at all required evaluation points. Inverted or collapsed cells are build failures, not warnings to ignore.

  4. Requested topology, polynomial order, layer count and mesh-size controls are compared with the realized mesh. A topology change is legal only when the build mode permits fallback and the report names the actual method and reason.

  5. Mesh convergence is assessed on physical observables—energy, average magnetization, switching field, eigenfrequency, linewidth or field error—not only on element count.

For exchange-dominated variation, a useful starting scale is the magnetostatic exchange length

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

Using an element size below roughly one half of the smallest relevant magnetic length scale is a common initial choice, not a proof of convergence. Curved boundaries, surface charges, DMI, defects, interfaces and through-thickness modes can demand a smaller local size.

Shared assembly is a deterministic lowering

geometry revisions + object policies + universe policy + capabilities
    -> normalized build plan
    -> realized topology + semantic manifest + quality + provenance

Every arrow must be inspectable. The manifest should distinguish requested, normalized, applied, ignored, degraded and fallback fields.

Selection guide

Use case

Recommended choice

Reason

Understand interface requirements

Assembly and conformity

Shared nodes/facets and region partition

Interpret actual generation path

Build modes and fallbacks

Request vs actual method and strict behavior

Target fields/boundaries robustly

Selectors and attributes

Semantic ownership instead of fragile tags

Parameters

Python / IR key

Unit

Default

Validation

Numerical effect

scene/model revision

1

current

must match authoring resources

inputs to the build fingerprint

object policy revisions

1

per object

current or inherited

local topology/size intent

universe policy revision

1

current

required for exterior solve

airbox intent

capability snapshot

1

active lane

current backend/device/physics

gates build mode and cell families

build fingerprint

hash

generated

content-addressed inputs

identifies one immutable realization

Python API

Complete Python example

import fullmag as fm

nm = 1.0e-9
study = fm.study("shared_domain_reference")
study.engine("fem")
study.device("cpu", precision="double")
study.mode("strict")
study.universe(
    mode="manual",
    size=(700 * nm, 500 * nm, 260 * nm),
    center=(0.0, 0.0, 0.0),
    padding=(0.0, 0.0, 0.0),
)
study.universe.mesh(
    minimum_element_size=12 * nm,
    maximum_element_size=90 * nm,
    maximum_element_growth_rate=1.5,
    grading="geometric",
)

left = study.geometry(
    fm.Box(size=(180 * nm, 80 * nm, 10 * nm), name="left_geom").translate(
        (-120 * nm, 0.0, 0.0)
    ),
    name="left",
)
right = study.geometry(
    fm.Box(size=(180 * nm, 80 * nm, 10 * nm), name="right_geom").translate(
        (120 * nm, 0.0, 0.0)
    ),
    name="right",
)
for body, direction in ((left, (1.0, 0.0, 0.0)), (right, (0.0, 1.0, 0.0))):
    body.mesh(
        mesh_strategy="free_tetrahedral",
        minimum_element_size=4 * nm,
        maximum_element_size=8 * nm,
        interface_maximum_element_size=6 * nm,
        interface_thickness=15 * nm,
        transition_distance="airbox_boundary",
        transition_growth=1.4,
        order=1,
        compute_quality=True,
    )
    body.Ms = 800.0e3
    body.Aex = 13.0e-12
    body.alpha = 0.02
    body.m = fm.texture.uniform(*direction)

study.exchange()
study.demag(realization="poisson_robin")
study.build_domain_mesh()
study.stages.add_relax(
    stage_id="equilibrium",
    algorithm="llg_overdamped",
    tolA=1.0e-4,
    max_steps=20_000,
)

Control Room workflow

Magnetic-object workflow

  1. In Explorer, select the magnetic object’s Mesh child (the object mesh-policy route).

  2. In Inspector → Object Mesh Policy, enable Use object policy when an object-specific override is required.

  3. Configure the relevant groups: Mesh Size Presets, Element Size Parameters, Thin-Film Sweep Strategy, Interface and Transition Refinement, Backend Mesh Parameters, Core Relaxation, Manual Size Field, and Edge and Corner Refinement.

  4. Select Apply Object Policy. This stores authoring intent and invalidates mesh resources whose revision no longer matches the model.

  5. Select Build Mesh. If the draft is dirty, the panel applies it first and dispatches the canonical mesh.build-selected command.

  6. Open the Quality and History tabs. Compare requested and realized values, then inspect the scoped size/quality distributions and the raw build report before running a solver.

The read-only effective values come from backend resources. They must not be reconstructed from the current form fields because presets, capability gates and backend normalization can change the resolved configuration.

Universe / airbox workflow

  1. In Explorer, select Universe / Airbox Mesh.

  2. Choose Domain mode and enter either explicit Size X/Y/Z and Center X/Y/Z, or automatic Padding X/Y/Z.

  3. For FEM, set Maximum element size, Minimum element size, Maximum element growth rate, Element grading, Curvature factor and Narrow-region resolution as needed.

  4. Select Apply Airbox Policy to store the universe-owned exterior-domain intent. This makes any older shared-domain realization stale.

  5. Select Apply & Build Shared-Domain Mesh to dispatch mesh.build-shared-domain.

  6. Inspect the effective configuration, shared-domain manifest, outer-boundary marker, interface conformity and mesh-quality scopes. The effective configuration returned by the backend is the source of truth.

For FDM, the panel filters FEM-only air-mesh controls and exposes structured-domain geometry only.

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

(2)\[\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 manifest that omits actual method, realized cell families, marker map or fallback reason is insufficient for production provenance.

Where this is implemented

Responsibility

Repository source

Stable owner / symbol

Shared asset pipeline

packages/fullmag-py/src/fullmag/meshing/asset_pipeline.py

shared-domain materialization

Build report

packages/fullmag-py/src/fullmag/meshing/mesh_build_report.py

shared-domain report

API schema

crates/fullmag-api/src/schemas/mesh.rs

shared-domain resource schema

Control Room lifecycle resources

apps/control-room/src/kernel/resources/geometryLifecycleResources.ts

mesh build/summary/manifest hooks

Mesh details UI

apps/control-room/src/modules/inspector/panels/MeshDetailsPanel.tsx

MeshDetailsPanel

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.

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.