FEM shared-domain meshing¶

Problem statement¶

A shared FEM domain is one conformal mesh carrying magnetic objects, interfaces and air. SharedMeshAssemblyPolicy is retained for compatibility; its fields are validated and serialized but are not consumed by the current builder.

Governing equations¶

Symbols and SI units¶

Assumptions and validity¶

The equation denotes a record, not an effective meshing law. Current effective sizing must be authored through explicit object, interface and airbox targets.

Python API¶

# %%
import fullmag as fm
from fullmag.model import SharedMeshAssemblyPolicy

# %%
nm = 1.0e-9
compatibility_policy = SharedMeshAssemblyPolicy(
    interface_hmax_factor=0.5,
    enforce_conforming=True,
    airbox_hmax_factor=3.0,
)
compatibility_policy_ir = compatibility_policy.to_ir()
study = fm.study("shared_domain_contract")
study.engine("fem")
study.device("cpu", precision="double")
study.mode("strict")
study.universe(
    mode="manual",
    size=(300 * nm, 180 * nm, 120 * nm),
    center=(0.0, 0.0, 0.0),
    padding=(0.0, 0.0, 0.0),
)
study.universe.mesh(
    maximum_element_size=40 * nm,
    minimum_element_size=5 * nm,
    maximum_element_growth_rate=1.4,
)
film = study.geometry(fm.Box(size=(100 * nm, 50 * nm, 5 * nm), name="film"), name="film")
film.mesh(maximum_element_size=8 * nm, minimum_element_size=4 * nm)
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(realization="poisson_robin")
study.stages.add_relax(stage_id="equilibrium", dt=5.0e-13, max_steps=1)

ProblemIR¶

SharedMeshAssemblyPolicy.to_ir() emits exactly the three fields shown above. This serialization preserves authored intent; it is not proof that the planner or runtime applied those values.

Round-trip and failure semantics¶

Requested intent is the serialized compatibility record plus explicit targets. Resolved execution is the builder’s actual mesh configuration and topology. Validation errors are the field-domain exceptions in __post_init__. Unsupported combinations remain rejected or capability-gated; compatibility serialization does not create an implementation.

Discrete realization¶

FEM CPU/GPU use the shared mesh subject to runtime capability. FDM CPU/GPU are not applicable: no unstructured shared-domain mesh is lowered into the FDM mesh route.

Implementation mapping¶

SharedMeshAssemblyPolicy owns compatibility validation and to_ir only. StudyUniverseHandle authors the public universe; _build_problem and Problem.to_ir preserve requested metadata; the asset pipeline and OCC own mesh realization; fullmag_plan::plan and run_planned_problem own planning/runtime boundaries without implying GPU qualification.

Validation¶

Validate policy construction and inspect the realized shared mesh separately. A source map pass does not demonstrate planner consumption or GPU execution.

Limitations¶

Do not treat enforce_conforming=True as an effective current build-mode switch; the source explicitly states that the builder does not consume this policy.

Scientific bibliography¶

Geuzaine and Remacle, IJNME 79 (2009), doi:10.1002/nme.2579.

Contract source-code index¶

Last changes: 12:31 24.08.2026

A shared-domain mesh is one immutable topology containing all magnetic and air regions required by coupled FEM operators, with conforming interfaces and semantic markers.

Scope and purpose¶

Use a shared-domain build whenever an operator spans more than one geometry or requires an exterior region. Fullmag assembles geometry, object policies, airbox policy and semantic selections before generating one mesh. Per-object preview meshes are not substitutes for the final shared domain because boolean fragmentation can change nodes, facets and markers.

Scientific and numerical model¶

Selection guide¶

Parameters¶

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",
    dt=5.0e-13,
    tolA=1.0e-4,
    max_steps=20_000,
)

Control Room workflow¶

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

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¶

• Overlapping magnetic volumes without an explicit material/region rule are invalid.

• Coincident but duplicate interface facets are not conforming; inspect adjacency and orphan diagnostics rather than surface coordinates alone.

• Region-marker count must match semantic objects after boolean fragmentation.

• A strict mixed request must fail if it realizes only tetrahedra or loses exact layer planes.

• Fallback is acceptable only when the build mode permits it and the report records request, reason, actual method and realized families.

• A solver must reject cell families it does not support even if the mesher produced valid cells.

Where this is implemented¶

Implementation map reviewed against commit 5db00ccf0113b9756fec2d46feb36ade762b12c2 on 2026-08-24.

Related documentation¶

• Shared-domain branch

• Airbox

• Mixed elements

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.

Source-code index¶

• Python contract source: packages/fullmag-py/src/fullmag/model/discretization.py and packages/fullmag-py/src/fullmag/world.py, where applicable. Runtime realization is owned by the relevant backends/fdm or backends/fem implementation; the page must not claim a symbol not named in its implementation mapping.