Shared-domain build modes and fallback semantics

Last changes: Documentation changelog

Problem statement

The asset pipeline resolves one FEM object preview/source mesh. It is distinct from shared-domain topology realization and should not be used to infer an effective fallback policy.

Governing equations

(1)\[h_{max}=h_{recipe}\succ h_{per\_geometry}\succ h_{default}\succ h_{FEM}.\]

Symbols and SI units

Token

Meaning

SI unit

\(h_{max}\)

effective preview element-size target

\(\mathrm{m}\)

\(h_{recipe}\)

per-object recipe target

\(\mathrm{m}\)

\(h_{FEM}\)

FEM hint target

\(\mathrm{m}\)

Assumptions and validity

The precedence relation is stated in the function docstring. It applies to the preview target of this function, not a proof of shared-domain fallback behavior.

Python API

Complete public signature and IR matrix

The following rows are the exhaustive public-signature contract for this page; each row mirrors one public_api.parameters entry in the source map.

Python

Type

Default

SI unit

Validation

Meaning

Backend support

ProblemIR

study.build_domain_mesh()

zero-argument method

n/a

\(1\)

accepts no public arguments; capture marks the request without invoking Gmsh, ordinary execution reaches SDK-backed realization

shared-domain materialization request

FEM CPU/GPU capability-gated

runtime_metadata.mesh_workflow.default_mesh.build_requested

realize_fem_mesh_asset(...) is internal. Public scripts request shared-domain materialization with zero-argument StudyBuilder.build_domain_mesh(), which sets build_requested before the SDK-backed realization boundary.

Python

Type

Default

SI unit

Validation

Meaning

Backend support

ProblemIR

StudyBuilder.build_domain_mesh()

no public arguments

n/a

\(1\)

sets build_requested; capture stops before Gmsh and ordinary execution may require the Gmsh Python SDK

shared-domain build request

FEM CPU/GPU capability-gated

runtime_metadata.mesh_workflow.default_mesh.build_requested

 
# %%
import fullmag as fm

# %%
nm = 1.0e-9
study = fm.study("build_mode_contract")
study.engine("fem")
study.device("cpu", precision="double")
study.mode("strict")
study.universe(mode="manual", size=(240 * nm, 140 * nm, 100 * nm), center=(0.0, 0.0, 0.0), padding=(0.0, 0.0, 0.0))
study.universe.mesh(maximum_element_size=30 * nm, minimum_element_size=5 * nm)
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")
try:
    study.build_domain_mesh()
except RuntimeError as exc:
    if "Gmsh Python SDK is required for FEM meshing" not in str(exc):
        raise
    print(f"Mesh realization unavailable in this environment: {exc}")
study.stages.add_relax(stage_id="equilibrium", dt=5.0e-13, max_steps=1)

ProblemIR

Authoring lowers workflow metadata and policy; target.hmax, source choice and mesh data are resolved execution values. A loaded mesh or generated mesh is provenance that must be retained separately.

Round-trip and failure semantics

Requested intent is geometry plus hints/workflow. Resolved execution is the selected target and generated or loaded mesh. Validation errors include unsupported surface-only imported geometry and zero tetrahedral elements. Unsupported combinations reject with ValueError; this function does not silently create a solver-eligible mesh from a surface preview.

Discrete realization

FEM CPU/GPU can consume a valid volume artifact subject to solver capability. FDM CPU/GPU are not applicable to this FEM asset pipeline.

Implementation mapping

StudyBuilder.build_domain_mesh owns the public request; _build_problem and Problem.to_ir lower requested workflow and assets; realize_fem_mesh_asset is object-preview realization, while realize_fem_domain_mesh_asset_from_components_with_report owns shared-domain build modes and _build_shared_domain_build_report owns requested/effective/fallback provenance. Planner/runtime are downstream and do not retroactively change authored intent.

Validation

Require nonzero tetrahedral elements and inspect target.source; validate any reported fallback in its responsible shared-domain route. No GPU runtime execution is claimed.

Limitations

This function is not the universal build-mode planner and does not qualify a surface preview for solver use.

Scientific bibliography

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

Contract source-code index

ID

Path

Symbol

Responsibility

Evidence

fem_asset

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

realize_fem_mesh_asset

FEM asset realization and volume checks

source-inspected

public_study

packages/fullmag-py/src/fullmag/world.py

study

public study entry point

source-inspected

build_request

packages/fullmag-py/src/fullmag/world.py

class StudyBuilder

public StudyBuilder.build_domain_mesh request

source-inspected

problem_lowering

packages/fullmag-py/src/fullmag/world.py

_build_problem

builder-state lowering

source-inspected

problem_ir

packages/fullmag-py/src/fullmag/model/problem.py

class Problem

ProblemIR and geometry-asset serialization

source-inspected

domain_realization

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

realize_fem_domain_mesh_asset_from_components_with_report

shared-domain build-mode realization

source-inspected

build_report

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

_build_shared_domain_build_report

requested/effective/fallback provenance

source-inspected

planner

crates/fullmag-plan/src/lib.rs

plan

ProblemIR planning and compatibility

source-inspected, runtime-unverified

runtime

crates/fullmag-runner/src/lib.rs

run_planned_problem

planned runtime dispatch

source-inspected, device-unverified

Last changes: 12:31 24.08.2026

Build mode is part of numerical provenance. A production report distinguishes requested strategy, normalized plan, actual generator, fallback/degradation reason and realized topology.

Implementation status

Ordinary tetrahedral paths and explicit fallback reporting are implemented. Exact mixed mode single_geometry_geo_mixed is narrow: a qualified single sweepable geometry can use it, while generic multi-object/airbox swept requests are not universally executable.

Scope and purpose

Use this page to interpret why a build used a particular generator and whether that outcome satisfies the authored scientific intent. Fullmag intentionally treats an exact topology request differently from a preference: strict mode rejects unmet exact intent; a permissive mode may allow a named fallback only when the policy says so.

Scientific and numerical model

The canonical provenance state is

requested_method
normalized_method
actual_method
status = applied | ignored | degraded | fallback | rejected
reason_code + human explanation
realized_cell_families

single_geometry_geo_mixed is the source-visible exact mixed route for an eligible single geometry such as a box with strict prism intent. A specialized ArchWaveguide route can realize thickness-aware/layered tetrahedra. Ordinary shared OCC/component or imported-surface paths can realize tetrahedra and must report that actual method. No path may label a tetrahedral result as an exact prism success.

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

(2)\[\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.

Selection guide

Use case

Recommended choice

Reason

Exact topology is part of the model

study.mode("strict")

Rejects unsupported or mismatched realization

Topology is only a preference

explicit fallback-enabled policy

Allows a named fallback with provenance

General multi-object airbox

ordinary conforming tetrahedral build

Most broadly supported shared route

Single box exact prism and capabilities pass

single_geometry_geo_mixed

Narrow qualified mixed route

Parameters

Python / IR key

Unit

Default

Validation

Numerical effect

execution mode

1

strict recommended

supported mode

controls whether unsupported/degraded requests can proceed

mesh_strategy

1

auto

valid object strategy

requested topology/generator intent

build_mode

1

planner-selected

advertised mode

actual assembly/generation route

fallback policy

1

reject for exact paths

explicit policy

defines legal alternative methods

actual_method

1

report output

non-empty for every build

generator that produced the realized mesh

reason code

1

report output

required for ignored/degraded/fallback/rejected

machine- and human-readable explanation

Python API

Complete Python example

import fullmag as fm

nm = 1.0e-9
study = fm.study("strict_mixed_build_mode")
study.engine("fem")
study.device("cpu", precision="double")
study.mode("strict")
study.universe(
    mode="manual",
    size=(800 * nm, 400 * nm, 200 * nm),
    center=(0.0, 0.0, 0.0),
    padding=(0.0, 0.0, 0.0),
)
study.universe.mesh(
    minimum_element_size=15 * nm,
    maximum_element_size=100 * nm,
    maximum_element_growth_rate=1.5,
    grading="geometric",
)

film = study.geometry(
    fm.Box(size=(600 * nm, 200 * nm, 6 * nm), name="film"),
    name="film",
)
film.mesh(
    mesh_strategy="swept_prism",
    topology="prismatic",
    through_thickness_elements=2,
    through_thickness_distribution="fixed",
    sweep_face_meshing="triangular",
    sweep_direction="auto",
    element_family="prism",
    transition_policy="pyramid_to_tetrahedra",
    exact_layer_count=True,
    minimum_element_size=4 * nm,
    maximum_element_size=8 * nm,
    order=1,
)
film.Ms = 800.0e3
film.Aex = 13.0e-12
film.m = fm.texture.uniform(1.0, 0.0, 0.0)

study.exchange()
study.demag(realization="poisson_robin")
study.build_domain_mesh()
study.stages.add_relax(stage_id="equilibrium", dt=5.0e-13, max_steps=10_000, tolT=1.0e-6)
# In strict mode, an unsupported exact request must fail instead of returning
# an unreported tetrahedral substitute.

Control Room workflow

Select Strict execution for topology-sensitive work. Before building, read the capability banner. After building, open History and compare requested/effective/actual strategy, build mode, fallback state and cell-family counts. A yellow/red capability or fallback badge is part of the result and must be exported with the simulation—not dismissed after visual inspection.

Fallback verification

Test every supported request and at least one deliberately unsupported request. Strict mode must reject the latter before solver execution. A permitted fallback must preserve geometry/regions, record the reason and pass its own quality/convergence checks. Regression tests should assert exact actual_method and family counts, not only that a file was produced.

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.

Diagnostics and failure semantics

  • Missing actual_method is a provenance failure.

  • Exact prism request plus all-tet result is fallback/failure, never success.

  • A retry between Gmsh algorithms is distinct from a topology fallback; both attempts/reasons should be recorded.

  • auto is not reproducible unless the resolved method and capabilities are stored.

  • A source-visible code path is not a production qualification; capability evidence controls UI.

Where this is implemented

Responsibility

Repository source

Stable owner / symbol

Build-mode dispatch

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

shared-domain build-mode selection

Fallback/report schema

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

requested/actual/fallback fields

Generator retries

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

_stl_meshing_retry_algorithm, sanitizers

Fallback tests

packages/fullmag-py/tests/test_meshing_fallbacks.py

explicit fallback assertions

Mixed mode tests

packages/fullmag-py/tests/test_mixed_element_meshing.py

single_geometry_geo_mixed

Control Room capability model

apps/control-room/src/modules/inspector/panels/ObjectMeshPolicyPanelModel.ts

mesh strategy capability states

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.

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.