Mesh sizing, local refinement and convergence¶

Problem statement¶

Refinement composes object bulk, interface, transition, perimeter, manual-hotspot and region-owned fields into one realized Gmsh field stack.

Governing equations¶

Symbols and SI units¶

Assumptions and validity¶

The union denotes ordered composition in _build_field_stack, not a physical superposition rule. Region order other than one is explicitly rejected in the shown source path.

Python API¶

# %%
import fullmag as fm

# %%
study = fm.study("refinement_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,
    minimum_element_size=3.0e-9,
    maximum_element_growth_rate=1.2,
    interface_maximum_element_size=4.0e-9,
    interface_thickness=8.0e-9,
    transition_distance="airbox_boundary",
    edge_maximum_element_size=3.0e-9,
    edge_thickness=10.0e-9,
    corner_maximum_element_size=2.0e-9,
    corner_extent=6.0e-9,
)
film.mesh.size_field("Ball", VIn=2.0e-9, VOut=8.0e-9, Radius=15.0e-9)
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¶

Mesh-policy and size-field descriptors are normalized to per-geometry and region-owned records; the resulting field stack is resolved execution data, not a user-authored IR literal.

Round-trip and failure semantics¶

Requested intent is the policy descriptor. Resolved execution is the assembled field list. Validation errors include unsupported region order and malformed region data. Unsupported combinations are rejected or skipped with a progress warning; neither is silently represented as applied refinement.

Discrete realization¶

The cited owners build unstructured FEM fields. FDM CPU and GPU are not-applicable for this page contract; structured-grid refinement belongs to the linked FDM-grid page.

Implementation mapping¶

GeometryMeshHandle and surface_shell own public descriptors; _build_problem and Problem.to_ir preserve runtime_metadata.mesh_workflow.per_geometry; _build_field_stack composes realized Gmsh fields; the domain asset pipeline materializes the mesh; planner/runtime consume the artifact without proving convergence or GPU execution.

Validation¶

Inspect realized field records and local-size distributions, then establish observable convergence. No runtime/device evidence is added by this documentation change.

Limitations¶

The stack itself does not certify a requested physical resolution; convergence remains observable-specific.

Scientific bibliography¶

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

Contract source-code index¶

Last changes: 12:31 24.08.2026

Refinement should be driven by physical length scales and observable error. Fullmag combines calibrated presets, explicit min/max sizes, interface/edge/corner controls and structured size fields.

Scope and purpose¶

Use this page to choose element/cell sizes, construct local grading zones and design a convergence study. Refinement is not synonymous with globally decreasing hmax: it should target regions responsible for the dominant discretization error while preserving acceptable element quality and solver conditioning.

Scientific and numerical model¶

Selection guide¶

Detailed refinement field guidance¶

Complete refinement authoring example¶

Complete Python example

import fullmag as fm

nm = 1.0e-9
study = fm.study("fem_local_refinement_reference")
study.engine("fem")
study.device("cpu", precision="double")
study.mode("strict")
study.universe(
    mode="manual",
    size=(800 * 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=15 * nm,
    maximum_element_size=100 * nm,
    maximum_element_growth_rate=1.6,
    grading="geometric",
)

film = study.geometry(
    fm.Box(size=(600 * nm, 250 * nm, 10 * nm), name="film"),
    name="film",
)
film.mesh(
    mesh_strategy="free_tetrahedral",
    calibrate_for="general_physics",
    size_preset="fine",
    size_factor=1.0,
    minimum_element_size=3 * nm,
    maximum_element_size=10 * nm,
    maximum_element_growth_rate=1.35,
    order=1,
    compute_quality=True,
    per_element_quality=True,
)
film.mesh.size_field("Ball", VIn=3 * nm, VOut=10 * nm, Radius=30 * nm, XCenter=0.0, YCenter=0.0, ZCenter=0.0)
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.

Use Mesh Size Presets for the reproducible baseline. Use Element Size Parameters for explicit clamps and Gmsh controls. Configure Interface and Transition Refinement, Core Relaxation, Manual Size Field, or Edge and Corner Refinement only where the physics justifies them. The size histogram and scoped quality views should show the realized distribution; a filled form is not evidence that a field matched any entity.

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¶

• A semantic selector resolving zero entities is an error or explicit no-op, never silent success.

• Raw Gmsh tags are fragile across geometry rebuilds; prefer semantic selectors.

• An aggressive size jump can create poor quality or solver-conditioning problems despite a locally fine mesh.

• A preset name without effective numeric values is insufficient provenance.

• Refine geometry and field sampling together for imported/curved boundaries; very small hmin cannot repair a defective surface asset.

• A lower element count after adding refinement can indicate that another size field was replaced rather than combined; inspect the normalized field plan.

Where this is implemented¶

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

Related documentation¶

• FDM grids

• FEM ferromagnet meshes

• Airbox grading

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.