FEM boundary-layer mesh controls¶
Last changes: Documentation changelog
Problem statement¶
Targeted Gmsh boundary-layer controls for a ferromagnetic FEM mesh.
Governing equations¶
Symbols and SI units¶
Symbol |
Meaning |
SI unit |
|---|---|---|
\(d_0\) |
first requested layer thickness |
m |
\(q\) |
requested layer stretching ratio |
1 |
\(N\) |
requested layer count |
1 |
Assumptions and validity¶
At least one explicit surface or curve target is required for realization. Tags are Gmsh entity identifiers and can change after geometry edits; selector mappings are resolved against current geometry. Boundary layers can create high-aspect-ratio cells and require observable-level convergence.
Python API¶
The table is exhaustive for this public family entry point. Alias rows are alternatives, not extra simultaneous requirements.
Python |
Type |
Default |
SI unit |
Validation |
Meaning |
Backend support |
ProblemIR |
|---|---|---|---|---|---|---|---|
|
|
|
1 |
coerced with int(…), then result must be >= 1; non-integral numeric values truncate toward zero |
requested layer count |
FEM CPU source-backed; FEM GPU capability-gated |
|
|
|
|
m |
finite and > 0 when supplied |
first-wall spacing passed as hwall_n and thickness |
FEM CPU source-backed; FEM GPU capability-gated |
|
|
|
|
1 |
finite and > 0 when supplied |
successive-layer growth ratio |
FEM CPU source-backed; FEM GPU capability-gated |
|
|
|
|
1 |
positive integer entity tags |
explicit target surfaces; their boundary curves are derived |
FEM CPU source-backed; FEM GPU capability-gated |
|
|
|
|
1 |
positive integer entity tags |
explicit target curves |
FEM CPU source-backed; FEM GPU capability-gated |
|
|
|
|
1 |
each item must be a selector mapping |
semantic surface targets resolved at build time |
FEM CPU source-backed; FEM GPU capability-gated |
|
|
|
|
1 |
each item must be a selector mapping |
semantic curve targets resolved at build time |
FEM CPU source-backed; FEM GPU capability-gated |
|
# %% imports
import fullmag as fm
# %% stage-first study and a target-bearing mesh recipe
study = fm.study("boundary_layer_reference")
study.engine("fem")
film = study.geometry(
fm.Box(size=(80e-9, 40e-9, 8e-9), name="film"),
name="film",
)
film.Ms = 800.0e3
film.Aex = 13.0e-12
film.m = fm.texture.uniform(1.0, 0.0, 0.0)
film.mesh(
maximum_element_size=6e-9,
boundary_layer_count=3,
boundary_layer_thickness=1e-9,
boundary_layer_stretching=1.25,
boundary_layer_target_surface_tags=[1],
compute_quality=True,
)
study.stages.add_relax(stage_id="equilibrium", dt=5.0e-13, max_steps=1)
ProblemIR¶
GeometryMeshHandle.configure normalizes the four target forms and _mesh_spec_to_metadata writes them under the matching mesh_workflow.per_geometry[] entry. _collect_mesh_workflow_metadata uses mesh_workflow.mesh_options only for the default mesh spec, not for this film.mesh(...) request. Tags and selectors are requested intent; selector-resolution records and BoundaryLayerResult are resolved evidence.
Round-trip and failure semantics¶
Requested intent contains count, first spacing, ratio, and at least one target form. Resolved execution contains selector matches and a boundary-layer status: applied, degraded, or ignored, with a reason where applicable. Validation errors include a boundary-layer count whose int(...) conversion fails or whose converted value is below one, nonpositive thickness, invalid tags, and non-mapping selectors. Because conversion precedes range validation, for example 3.9 resolves to 3 and 0.9 resolves to 0 and is rejected. Unsupported combinations do not acquire a hidden fallback: no targets yields ignored; surface-to-curve failure yields ignored; unavailable setAsBoundaryLayer yields degraded.
Discrete realization¶
_add_boundary_layer_field converts selected surfaces to boundary curves, sets CurvesList, hwall_n, thickness, ratio, and NbLayers, then calls setAsBoundaryLayer. This is a Gmsh field request; the extracted cell topology and build report remain authoritative.
Implementation mapping¶
The source index maps public authoring, lowering, realization, reporting, and backend consumption. Source-backed FEM CPU support does not imply that every requested topology is supported; FEM GPU remains capability-gated by the realized mesh and active runtime.
FEM CPU/GPU plan and runtime consumption¶
plan_fem resolves the domain or per-object mesh asset, validates typed MeshIR and region ownership, and places that mesh in FemPlanIR; this is the planning consumer after Python realization. The production runner enters execute_fem_with_context_in_mode, normalizes the FEM plan, resolves CPU/GPU behavior, and calls the configuration-selected execute_native_fem implementation for native execution. apply_native_fem_runtime_contract is not a gate: after runtime observations exist, it returns () and only populates ExecutionProvenance fields such as execution mode, qualification status, data residency, CUDA-kernel use, GPU Poisson use, and hot-loop synchronization counts. A source-backed Python mesh build is therefore not itself CPU or GPU runtime proof; actual execution and its populated provenance provide that evidence.
Validation¶
Confirm source identity, requested and actual methods, typed cell families, complete region/boundary markers, zero inverted or degenerate cells, and the relevant quality distributions. Then refine the controlling size or layer count while holding geometry, materials, solver tolerances, and outputs fixed, and require convergence of a physical observable.
Limitations¶
A configured layer without targets is deliberately ignored. The implementation sets both hwall_n and thickness from boundary_layer_thickness; it does not document that value as total geometric-series thickness. Tag-based targeting is not stable across geometry revisions.
Scientific bibliography¶
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.
Source-code index¶
Repository path |
Stable symbol |
Responsibility |
|---|---|---|
Public object.mesh arguments and validation. |
||
Per-object ProblemIR metadata lowering. |
||
Requested mesh_options lowering. |
||
Selector resolution and field-plan application. |
||
Gmsh boundary-layer status and realization. |
||
|
Requested/resolved operation statuses. |
|
FEM domain mesh realization and report. |
||
Validated MeshIR consumption and FEM plan construction. |
||
Production plan normalization and CPU/GPU native execution routing. |
||
|
|
Configuration-selected native CPU/GPU execution implementation. |
Populates runtime provenance fields after observations exist; returns |