Free tetrahedral ferromagnet mesh¶

Problem statement¶

The public object.mesh(...) route for general unstructured FEM volume meshing.

Governing equations¶

Symbols and SI units¶

Assumptions and validity¶

The geometry must define a meshable volume. Alias pairs must agree when both forms are supplied. The exported geometric connectivity is first order; order controls the FEM solution space. Positive volume is necessary but sliver quality and observable convergence still require checks.

Python API¶

The table is exhaustive for this public family entry point. Alias rows are alternatives, not extra simultaneous requirements.

# %% imports
import fullmag as fm

# %% stage-first study and complete free-tetrahedral request
study = fm.study("free_tetrahedral_reference")
study.engine("fem")
body = study.geometry(fm.Box(size=(80e-9, 40e-9, 20e-9)), name="body")
body.Ms = 800.0e3
body.Aex = 13.0e-12
body.m = fm.texture.uniform(1.0, 0.0, 0.0)
body.mesh(
    mesh_strategy="free_tetrahedral",
    maximum_element_size=8e-9,
    minimum_element_size=2e-9,
    algorithm_2d=6,
    algorithm_3d=1,
    optimize="Netgen",
    optimize_iterations=1,
    smoothing_steps=1,
    size_factor=1.0,
    size_from_curvature=0,
    curvature_factor=0.5,
    growth_rate=1.3,
    narrow_regions=0,
    interface_maximum_element_size=4e-9,
    interface_thickness=4e-9,
    transition_distance=16e-9,
    edge_maximum_element_size=3e-9,
    edge_thickness=4e-9,
    edge_transition_distance=12e-9,
    corner_maximum_element_size=2e-9,
    corner_extent=3e-9,
    corner_transition_distance=8e-9,
    order=1,
    compute_quality=True,
    per_element_quality=True,
)
study.stages.add_relax(stage_id="equilibrium", dt=5.0e-13, max_steps=1)

ProblemIR¶

GeometryMeshHandle.configure coalesces canonical names and aliases. _mesh_spec_to_metadata writes every body.mesh(...) value under the matching mesh_workflow.per_geometry[] entry. _collect_mesh_workflow_metadata derives top-level mesh_options from the default spec only; it is not the authoring destination for this per-object call. The build report separately records actual method and quality.

Round-trip and failure semantics¶

Requested intent is the complete object.mesh(...) configuration. Resolved execution records normalized aliases, selected effective algorithm, actual mesh method, element counts, and quality. Validation errors cover conflicting aliases, nonpositive sizes, minimum greater than maximum, a growth rate above 2.5, invalid counts, and FDM cell_size mixed with FEM controls. Interface transition_distance=0 is valid; edge and corner transition distances remain strictly positive when numeric. Unsupported combinations must be reported; the known MMG3D-with-background-fields case resolves to HXT with an explicit reason, not silently.

Discrete realization¶

_apply_mesh_options applies sizes, first-order geometric connectivity, algorithms, smoothing, optimization, and fields. generate_mesh dispatches supported geometries, while domain realization and _build_shared_domain_build_report record actual method, requested method, and fallbacks. FEM CPU consumes the resulting MeshIR; GPU consumption remains capability-gated.

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.

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¶

This page does not cover imported FEM(mesh=...), boundary layers, or thin-film/swept topology. mesh_strategy="free_tetrahedral" requests the family, but only the realized typed cells prove it.

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¶

Scope and purpose¶

This page defines the public contract for free tetrahedral FEM meshes. It is an authoring and implementation reference: the Python example, the serialized ProblemIR description, the implementation mapping, and the adjacent source map are the source-backed contract. A capability marked partial or not evaluated is not presented as a production guarantee.

Scientific and numerical model¶

The mesh or grid is a discrete approximation of the continuous domain. For a Cartesian partition, each spacing satisfies Delta_i = L_i / N_i; for a geometry-dependent FEM mesh, the requested local target is bounded by the active bulk, interface, boundary, and topology constraints. In compact form, h_target(x) = min(h_bulk(x), h_interface(x), h_boundary(x)). Length quantities use SI metres (m); counts, orders, and topology labels are dimensionless.

The equations and assumptions in the earlier physical-problem and governing-equations sections state the model-specific specialization. This section does not introduce a conversion from FEM to FDM, a hidden topology conversion, or a silent CPU fallback.

Parameters¶

The exact callable and argument names are the ones shown in the ## Python API section above. For this page the parameter family is maximum and minimum element size, order, algorithm, and optimizer. Use the documented defaults, validation rules, and ProblemIR lowering exactly as shown; do not replace a canonical argument with an unlisted alias. Numerical lengths must be supplied in metres, and invalid positive-length, count, order, periodicity, or topology constraints must fail closed rather than being silently repaired.

Control Room workflow¶

In Control Room, select the engine and mesh workflow, enter the same values as the Python authoring example, inspect the planned mesh or grid report, and only then submit the run. The UI is a projection of the public contract: a missing control is not evidence that the backend accepts the option, and a visible control is not evidence that a production lane is enabled. When the page or capability register marks a field partial or not evaluated, keep the workflow explicitly bounded to the implemented path.

Diagnostics and failure semantics¶

A valid request must preserve the declared geometry, units, element or cell topology, and backend lane. Reject non-finite or non-positive lengths, invalid counts and orders, incompatible periodic or shared-boundary data, and unsupported topology combinations at the owning validation layer. Reports should retain requested and resolved values, source identity, and any capability gate. No diagnostic may hide a failed mesh realization by substituting another discretization.

Where this is implemented¶

The existing implementation-mapping and source-code-index sections identify the exact public authoring, ProblemIR, planner, realization, and runtime owners for this topic. The adjacent .source-map.json file is the machine-readable source of truth for those paths, symbols, responsibilities, backend matrix, and reviewed revision. Claims in this page must be updated together with that map when an owner moves.