Swept and layered FEM meshes¶

Problem statement¶

Swept meshing realizes layered cells only for source-supported geometry and strategy combinations; the dispatcher never substitutes a different topology without an explicit higher-level report.

Governing equations¶

Symbols and SI units¶

Assumptions and validity¶

This equality is only a requested input relation; resolved counts belong in the realization report. The body-only prism path accepts only axis-aligned Box; cylinders require the canonical Z axis, and explicit swept_hex raises ValueError.

Python API¶

# %%
import fullmag as fm

# %%
study = fm.study("swept_contract")
study.engine("fem")
study.device("cpu", precision="double")
study.mode("strict")
study.universe(
    mode="manual",
    size=(220.0e-9, 170.0e-9, 80.0e-9),
    center=(0.0, 0.0, 0.0),
    padding=(20.0e-9, 20.0e-9, 20.0e-9),
)
study.universe.mesh(
    maximum_element_size=12.0e-9,
    minimum_element_size=6.0e-9,
    maximum_element_growth_rate=1.3,
    grading="geometric",
)
film = study.geometry(fm.Box(size=(100e-9, 50e-9, 5e-9), name="film"), name="film")
film.Ms = 800.0e3
film.Aex = 13.0e-12
film.alpha = 0.02
film.m = fm.texture.uniform(1.0, 0.0, 0.0)
film.mesh(
    maximum_element_size=8.0e-9,
    mesh_strategy="swept_prism",
    topology="prismatic",
    through_thickness_elements=2,
    through_thickness_distribution="fixed",
    through_thickness_symmetric=False,
    sweep_face_meshing="triangular",
    sweep_direction="auto",
    element_family="prism",
    transition_policy="pyramid_to_tetrahedra",
    exact_layer_count=True,
    order=1,
)
study.exchange()
study.demag(realization="poisson_robin")
study.build_domain_mesh()
study.stages.add_relax(stage_id="equilibrium", dt=5.0e-13, max_steps=1)

Parameters¶

The complete parameter matrix in the Python API section is the public mesh-authoring contract. Defaults, validation, ProblemIR lowering and capability-gated lanes are listed there and mirrored by the adjacent source map.

ProblemIR¶

The public mesh-policy fields lower to a requested strategy, layer count, distribution, axis and order. MeshRealizationReport records the resolved counterparts and fallback markers.

Round-trip and failure semantics¶

Requested intent is the policy tuple. Resolved execution is the dispatch result and realization report. Validation errors include explicit hex, non-box prism input and non-Z cylinder input. Unsupported combinations fail with these errors rather than becoming a free-tetrahedral mesh in this dispatcher.

Discrete realization¶

This is FEM CPU/GPU meshing, with GPU solver support capability-gated after artifact realization. FDM CPU/GPU are not applicable because they use structured cells rather than swept FEM elements.

Implementation mapping¶

GeometryMeshHandle owns requested swept policy; _build_problem and Problem.to_ir lower it under runtime_metadata.mesh_workflow.per_geometry; generate_swept_mesh owns geometry dispatch; MeshRealizationReport separates requested/resolved topology; the asset pipeline, planner and runtime retain their distinct artifact/compatibility/execution responsibilities.

Validation¶

Compare requested and resolved topology, layers, axis and order; require named fallback markers whenever they differ. This change has no new live GPU receipt.

Limitations¶

The source does not support arbitrary swept geometries or an explicit body-only hexahedral realization.

Scientific bibliography¶

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

Contract source-code index¶

Last changes: 12:31 24.08.2026

Swept meshing extrudes a source surface through a thickness or along a sweep direction. In Fullmag, requested layers and topology are strict scientific intent only when the capability matrix and post-build certificate confirm them.

Scope and purpose¶

Use a swept mesh when the geometry is sweepable and the through-thickness topology is part of the physical model—for example thin films, waveguides and layered structures. The page distinguishes three outcomes: exact layered prism, layered-surface tetrahedral realization, and unsupported or fallback topology. These outcomes are not interchangeable.

Scientific and numerical model¶

Selection guide¶

Detailed swept-policy guidance¶

Complete swept authoring example¶

Complete Python example

import fullmag as fm

nm = 1.0e-9
study = fm.study("swept_prism_reference")
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.6,
    grading="geometric",
)

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

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¶

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.

In Thin-Film Sweep Strategy, select Swept prism only when the capability banner enables it. The UI canonicalizes triangular source faces, P1 order, prism family, exact layer count and the pyramid-to-tetrahedra transition. The supported layer-count selector is populated from mesh.exact_layer_count; the reviewed Control Room gate requires exactly [1, 2, 3]. Swept hex remains disabled until its topology/operator gate is qualified.

Required realization certificate¶

For an exact prism request, require: requested and actual method; exact layer count; \(N+1\) node planes; plane coordinates and tolerance; prism/pyramid/tet counts by region; positive reference and physical Jacobians; complete interface and outer markers; mixed-topology conformity; quality metric name; and fallback status. A report containing only total element count is insufficient.

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¶

• Non-sweepable geometry must be rejected in strict mode or reported with an explicit fallback.

• Exact layer count with a nonuniform distribution is rejected by the strict Python schema.

• Prism requests require P1, triangular source faces, swept_prism, exact layer count and pyramid_to_tetrahedra in the current mixed route.

• Hex requests require swept_hex and quadrilateral source faces and cannot use the pyramid transition in the current schema.

• Gmsh surface algorithm 8 is sanitized to algorithm 6 in thin-film 3-D volume workflows because the source-visible generator records it as unstable for that context.

• A successful Gmsh call that realizes only tetrahedra does not satisfy an exact prism request.

Where this is implemented¶

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

Related documentation¶

• Swept prism

• Swept hex

• 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.

Extended source notes¶

• 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.