FEM discretization and mesh authoring¶

Contract and ownership hierarchy¶

Fullmag FEM meshing has four policy levels:

1. FEM(...) supplies the study-level finite-element order, default maximum element size, optional imported mesh reference, and optional demagnetization linear-solver policy.

2. study.universe.mesh(...) controls the nonmagnetic exterior/airbox size field and the global meshing envelope.

3. object.mesh(...), object.mesh.thin_film(...), or PerObjectMeshRecipe(...) override the policy for one magnetic object.

4. the mesh builder resolves all geometry, region, interface, edge, corner, boundary-layer, swept, periodic, and airbox constraints into one conforming solver mesh.

The precedence for an object maximum-size target is, from highest to lowest:

1. explicit PerObjectMeshRecipe.maximum_element_size or hmax;

2. per-geometry mesh-workflow target;

3. mesh-workflow object default;

4. study-level FEM.maximum_element_size or hmax.

The realized mesh report derives provenance from the field that supplied the effective maximum-size target, not merely from the presence of an object recipe. It reports recipe_override, local_override, workflow_default, or study_default for the four levels above. An inherited value in the UI is therefore not equivalent to a numeric zero or to deleting the mesh policy.

Numerical meaning¶

This API page introduces no new physical interaction. It selects the finite-element trial/test space used by all enabled operators. For a scalar P1 basis phi_a, each component of reduced magnetization is represented by nodal coefficients. The public schema can represent higher order values, but every current production native FEM planner accepts only order=1; higher orders are planned capability and are rejected before execution. Geometry order, field order, quadrature, material attributes, and airbox closure remain separate numerical choices.

Changing the mesh changes the discrete exchange, DMI, anisotropy, demagnetization, mass, tangent, and response operators. Results from two meshes are not the same discrete problem even when their CAD geometry and nominal hmax match.

Symbols and SI units¶

All public lengths are SI metres. Control Room displays the same canonical values; it does not apply an implicit nanometre conversion when writing the backend resource.

Assumptions and validity¶

• FEM.order is an integer greater than or equal to one.

• current production FEM CPU/GPU execution is P1-only (FEM.order == 1); higher integer values are representable authoring intent but fail planner capability validation.

• FEM.maximum_element_size is required and strictly positive; hmax is a compatibility spelling for the same value.

• when both maximum_element_size and hmax are supplied, their floating-point values must be equal.

• FEM.mesh, when present, is a nonempty imported/prebuilt mesh reference. Import does not bypass region, boundary, unit, order, orientation, and compatibility validation.

• a valid FEM mesh is conforming across shared material and magnetic/air interfaces unless an explicitly different formulation owns a discontinuous trace.

• a mesh accepted on CPU is usable on GPU only when every realized element family, polynomial order, interaction, and auxiliary operator has a qualified GPU implementation.

Complete FEM mode matrix¶

mesh_strategy describes requested topology. build_mode and operation_statuses describe what actually ran. They must not be collapsed into one field.

Python API¶

from fullmag.model import MeshOperation, MeshSizeControls, PerObjectMeshRecipe, SharedMeshAssemblyPolicy

# %% Shared-domain FEM with an exact layered film and graded airbox
import fullmag as fm

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

study.universe(mode="manual", size=(1.2e-6, 600 * nm, 550 * nm))
study.universe.mesh(
    minimum_element_size=8 * nm,
    maximum_element_size=100 * nm,
    maximum_element_growth_rate=1.3,
    grading="geometric",
)

film = study.geometry(
    fm.Box(size=(500 * nm, 125 * nm, 3 * nm), name="film"),
    name="film",
)
film.mesh.thin_film(
    minimum_element_size=3 * nm,
    maximum_element_size=5 * 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.fem_demag_solver(
    solver="CG",
    preconditioner="AMG",
    rtol=1.0e-10,
    max_iterations=500,
)
study.build_domain_mesh()
study.stages.add_relax(
    stage_id="equilibrium",
    algorithm="nonlinear_cg",
    tolT=1.0e-6,
    max_steps=50_000,
)

Control Room mapping¶

The active FEM mesh controls are split by semantic owner:

Control Room preserves authored and backend-effective values separately. The advanced JSON editor is part of the round-trip contract, not permission to bypass validation. Unknown keys may be retained as authored JSON, but only source-backed keys are guaranteed to affect meshing.

ProblemIR and resolved execution¶

The canonical request contains study-level discretization hints plus derived mesh-workflow metadata. The object and universe resources preserve their own revision numbers. Resolved execution adds:

• effective object and airbox targets and the source of each value;

• requested and actual meshing algorithms;

• shared-domain build mode and ordered fallback history;

• region, boundary, periodic-pair, selector, and magnetic-submesh identities;

• element and facet counts by family, order, region, and role;

• requested and realized layer count, node planes, sweep direction, and transition topology;

• applied/ignored/degraded size fields and mesh operations;

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

• Gmsh/native extraction versions, deterministic inputs, and mesh digest.

Only the resolved report can establish whether a requested mode executed without degradation.

Round-trip and failure semantics¶

Requested intent is the canonical Python or Control Room policy stored before meshing. Resolved execution is the backend-effective policy and the concrete Gmsh/native result. Public validation errors reject malformed requests before build, while unsupported combinations fail capability validation rather than being replaced silently by a different topology or device.

The public boundary rejects malformed values before build. The mesh builder additionally fails or marks degradation for nonconformal assembly, empty regions, inverted/collapsed elements, unresolved selectors, unsupported topology combinations, marker loss, invalid periodic pairs, and requested/ resolved topology mismatch.

Strict mode forbids hidden substitution. In particular:

• exact layered prism does not silently become free tetrahedral;

• a spherical airbox does not silently become a box without a degradation record;

• a requested optimizer/size field does not silently disappear;

• a GPU request does not silently rebuild a different CPU mesh;

• an imported mesh does not bypass unit or semantic-marker validation.

Device and solver realization¶

Meshing itself is generally a host/Gmsh operation. A final FEM GPU simulation does not imply that CAD construction, Gmsh generation, selector resolution, or quality analysis ran on the GPU.

Implementation mapping¶

Verification and scientific qualification¶

A production mesh study should include:

1. geometry bounds, volume, region connectivity, and marker validation;

2. positive Jacobians and acceptable lower-tail quality for every element family;

3. constant/affine interpolation and operator null-case tests;

4. at least three controlled h-refinement levels for the target observable where feasible;

5. independent layer-count convergence for thin-film modes;

6. independent airbox-extent, closure, grading, and Poisson-tolerance studies;

7. branch/mode correspondence for equilibria, eigenmodes, and response peaks;

8. CPU/GPU comparison using the exact same mesh digest;

9. archived authored policy, resolved report, and generated mesh asset.

Limitations¶

• hmax is a mesher target, not a guaranteed realized maximum.

• high field order does not repair low-order geometry automatically.

• exact layered prism support is intentionally narrow and capability-gated.

• swept hex is represented in schemas but disabled in the reviewed Control Room production gate.

• general multi-object and general airbox-plus-swept workflows remain scenario-dependent.

• boundary layers and semantic selectors can degrade when CAD/component identities are lost.

• the current contract does not claim universal automatic a posteriori adaptivity.

Scientific bibliography¶

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

2. S. C. Brenner and L. R. Scott, The Mathematical Theory of Finite Element Methods, 3rd ed., Springer, 2008, doi:10.1007/978-0-387-75934-0.

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

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

5. 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¶