Mesh controls: Python, Control Room, and realized FEM mesh¶

Control hierarchy¶

FEM meshing is controlled at several nested scopes:

A lower scope overrides only the keys it owns. Empty/None values inherit; they do not write zero. The final shared-domain builder must satisfy all active scopes simultaneously.

Numerical interpretation¶

A size field defines a requested metric-like target, schematically

followed by growth, conformity, geometry, and mesher constraints. Therefore:

• the smallest overlapping field wins locally;

• requested hmax is not a guaranteed measured maximum;

• transition and grading controls can propagate refinement beyond the selected feature;

• a local object or region request can increase the airbox element count through conformity;

• the realized size distribution must be inspected in the build report and quality histogram.

Symbols and SI units¶

All Control Room length inputs are canonical SI metres. The interface does not silently convert a number entered as 5 into five nanometres.

Authoring state machine¶

geometry + authored policies
          |
          v
backend-effective policy  -- capability and inheritance resolution
          |
          v
mesh build command        -- Gmsh generation, extraction, validation
          |
          +--> failure: current/latest successful mesh remains unchanged
          |
          v
realized mesh + report + quality + digest

Calibration families¶

The public calibration vocabulary is:

• general_physics;

• micromagnetics_static;

• micromagnetics_relaxation;

• micromagnetics_frequency_domain;

• magnetostatics_dominated;

• imported_surface_cleanup.

A calibration name is normalized and preserved as provenance, but it does not currently select or change numerical defaults. size_preset and explicit numeric controls determine those defaults. Calibration provenance is not evidence that the resulting mesh is converged for a particular observable.

Size presets¶

When the corresponding numeric control is absent, the reviewed preset resolver supplies these fallbacks:

Explicit numeric values override preset fallbacks. size_factor then scales preset-derived targets where the active mesh workflow applies that factor.

MeshSizeControls¶

SharedMeshAssemblyPolicy¶

This low-level policy is currently inert: _resolve_per_object_mesh_options accepts it for API compatibility but does not read its fields. Use explicit interface, object, and airbox targets; the resolved target report records which effective value controlled each partition.

Stage-first commands¶

# %% Global, airbox, object, and exact thin-film mesh controls
import fullmag as fm

nm = 1.0e-9
study = fm.study("fem_mesh_controls")
study.engine("fem")
study.device("cpu", precision="double")
study.mode("strict")

study.universe(mode="manual", size=(1.0e-6, 500 * nm, 400 * nm))
study.universe.mesh(
    minimum_element_size=8 * nm,
    maximum_element_size=90 * nm,
    maximum_element_growth_rate=1.3,
    grading="geometric",
)

film = study.geometry(
    fm.Box(size=(400 * nm, 120 * nm, 4 * nm), name="film"),
    name="film",
)
film.mesh.thin_film(
    minimum_element_size=2 * nm,
    maximum_element_size=4 * nm,
    layers=2,
    topology="prismatic",
    exact_layers=True,
    transition="pyramid_to_tetrahedra",
    order=1,
)
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(model="airbox", variant="robin")
study.build_domain_mesh()
study.stages.add_relax(
    stage_id="equilibrium",
    algorithm="nonlinear_cg",
    tolT=1.0e-6,
    max_steps=50_000,
)

Control Room crosswalk¶

Explicit size fields¶

Ordered mesh operations¶

The operation schema is representable, but the current public build boundary rejects every authored operation with mesh operation executor unavailable before mesh generation, including entries with enabled=False. Therefore no operation is currently classified as applied, ignored, skipped, degraded, or failed in a build report. The table above describes intended families, not executable public capability.

ProblemIR and provenance¶

A reproducible mesh record contains:

• study, universe, object, and region authored policies with revisions;

• backend-effective values and inheritance source;

• geometry and material digests;

• requested and actual algorithms, topology, order, layers, and transitions;

• ordered size fields and operations with realization status;

• selector-to-native-tag resolution;

• build mode, fallback list, degradation flag, and exact failure reason;

• nodes/elements/facets by family, order, region, and boundary role;

• bounds, volumes, surfaces, connected components, and periodic pairs;

• Jacobian, SICN, gamma/radius, volume, edge-size, and histogram statistics;

• Gmsh/native versions, deterministic inputs, mesh/submesh digests;

• current versus latest-successful mesh identity.

Validation and failure semantics¶

Structured Python/UI controls reject invalid numeric values, unsupported vocabulary, inconsistent hmin/hmax, invalid layer tuples, and unresolved FEM/FDM lane selection before build. The mesh build then rejects or explicitly degrades:

• nonconformal or failed CAD assembly;

• empty magnetic or air partitions;

• inverted, collapsed, orphan, duplicate, or nonmanifold entities;

• missing material/boundary attributes;

• invalid periodic pairing;

• unresolved semantic selectors;

• unsupported family/order/device combinations;

• requested-versus-realized topology mismatch in strict mode.

A failed build must not overwrite the latest successful mesh. A green policy request without a green mesh build is not a usable solver discretization.

Discrete realization¶

FEM mesh generation is normally host/Gmsh work. CPU and GPU solvers must consume the same content-addressed extracted asset when parity is claimed. FDM uses a different structured-grid contract and exposes object/region mesh membership read-only in the Control Room.

Implementation mapping¶

Scientific mesh-convergence workflow¶

1. choose a target observable and physical parameter range;

2. make temporal, equilibrium, algebraic, and airbox errors smaller than the expected spatial change;

3. retain the exact authored/effective policy and realized mesh for at least three controlled levels where possible;

4. compare geometry volume and marker topology independently of field error;

5. compare fields on a common space and modes by complex overlap;

6. refine thickness layers, geometry order, airbox extent, and h/p independently;

7. inspect worst elements and lower quality percentiles, not only averages;

8. verify CPU/GPU on the identical mesh digest;

9. archive every build report and acceptance decision.

Limitations¶

• presets are convenience policies, not accuracy grades;

• advanced JSON can contain keys not consumed by the active backend;

• raw Gmsh tags are not stable geometry identifiers;

• region/object requests may be altered by conformity and shared-domain constraints;

• exact prism, boundary-layer, swept, and adaptive operations have bounded support scopes;

• this contract does not claim universal automatic adaptive remeshing.

Scientific bibliography¶

1. 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, 1309–1331 (2009), doi:10.1002/nme.2579.

2. P. G. Ciarlet, The Finite Element Method for Elliptic Problems, SIAM Classics, 2002, doi:10.1137/1.9780898719208.

3. R. Anderson et al., “MFEM: a modular finite element methods library,” Computers & Mathematics with Applications 81, 42–74 (2021), doi:10.1016/j.camwa.2020.06.009.

Python API¶

The complete runnable example is in the numbered example section below; the exact callable fields and arguments are in the numbered API section. These values are copied from the current Python contract, not inferred from the UI.

Source-code index¶