Free-Tetrahedral API¶

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.

Symbols and SI units¶

All geometric lengths use \(\mathrm{m}\); dimensionless selectors use \(1\).

Assumptions and validity¶

Authoring validation does not prove mesh generation or solver qualification; the realized report is authoritative.

1. What it is and when to use it¶

object.mesh(...) is the default object meshing strategy: an unstructured tetrahedral mesh generated by Gmsh inside the object geometry, with no forced through-thickness topology.

When to use it:

• any magnetic object without special layering requirements,

• complex-shaped geometries (imported STL/STEP, nanoflowers),

• the first choice before reaching for specialized modes.

When to pick something else: thin films with through-thickness control → Thin-Film Tetrahedral API; exact prism layers → Swept-Prism API; an external prebuilt mesh → Imported-Mesh API.

Impact on the simulation: maximum_element_size controls the accuracy/cost trade-off; refinement should respect the exchange length \(l_{\mathrm{ex}}\) (section 2).

2. Physical and mathematical explanation¶

This page introduces no equation of its own; it selects the discrete space for micromagnetic operators. The practical sizing rule follows from the exchange length:

where \(A\) — exchange stiffness (\(\mathrm{J\,m^{-1}}\)), \(M_s\) — saturation magnetization (\(\mathrm{A\,m^{-1}}\)), \(\mu_0\) — vacuum permeability (\(\mathrm{H\,m^{-1}}\)). For a correct domain-wall description, elements should not be significantly larger than \(l_{\mathrm{ex}}\).

3. Example — complete Python script¶

# %% Free-tetrahedral object mesh
import fullmag as fm

nm = 1.0e-9

study = fm.study("free_tetrahedral_example")
study.engine("fem")
study.device("cpu", precision="double")
study.mode("strict")

study.universe(mode="manual", size=(800 * nm, 400 * nm, 300 * nm))
study.universe.mesh(
    minimum_element_size=8 * nm,
    maximum_element_size=80 * nm,
    maximum_element_growth_rate=1.5,
    grading="geometric",
)

film = study.geometry(fm.Box(300 * nm, 100 * nm, 5 * nm), name="film")
film.Ms = 800.0e3          # A/m
film.Aex = 13.0e-12        # J/m
film.alpha = 0.02
film.m = fm.texture.uniform(1.0, 0.0, 0.0)
film.mesh(
    minimum_element_size=2.5 * nm,
    maximum_element_size=5 * nm,
    order=1,
    compute_quality=True,
)

study.exchange()
study.demag(model="airbox", variant="robin")
study.build_domain_mesh()
study.stages.add_relax(stage_id="equilibrium", tolT=1.0e-6)

4. Exact API¶

Signature: object.mesh(**kwargs) — GeometryMeshHandle.__call__ (packages/fullmag-py/src/fullmag/world.py). The most common arguments:

Advanced recipes (PerObjectMeshRecipe) additionally expose mesh_strategy="free_tetrahedral", Gmsh algorithms, size fields (size_field), ordered operations, and boundary layers — see Boundary-Layer API and the source index below.

Failure behavior: non-positive sizes, order < 1, and contradictory aliases raise ValueError immediately, before any mesh is built.

ProblemIR mapping: fields land in the canonical object recipe (PerObjectMeshRecipe) and then in the mesh workflow metadata.

ProblemIR¶

The request lowers to the mesh-workflow or discretization subtree; requested intent remains distinct from the resolved mesh asset and provenance report.

Round-trip and failure semantics¶

Requested intent is the Python policy; resolved execution is the realized mesh report. Validation errors identify the violated domain rule, and unsupported combinations fail explicitly without silent fallback.

Discrete realization¶

The backend consumes the realized Cartesian or finite-element asset, including topology, markers, quality, and provenance where available.

5. How to set it in Control Room¶

Model Explorer
└── Objects
    └── <object>
        └── Mesh            → selection kind: object.mesh

The Object Mesh Policy inspector (ObjectMeshPolicyPanel.tsx): the Element Size Parameters, Mesh Size Presets, and Backend Mesh Parameters groups (Gmsh algorithms, optimizer, quality). Apply Object Policy writes the recipe; Build Mesh materializes it. Full description: FEM Object Mesh Panel.

6. Backend support¶

Validation¶

Focused constructor, lowering, and mesh-report tests are the evidence boundary for this page.

7. Limitations and known pitfalls¶

• Tetrahedra do not guarantee through-thickness layers — for films with strong resolution anisotropy prefer Swept-Prism API.

• maximum_element_size is a target, not a local guarantee; realized extrema are in the build report.

8. Scientific bibliography¶

1. C. Geuzaine and J.-F. Remacle, “Gmsh,” Int. J. Numer. Methods Eng. 79, 1309–1331 (2009).

2. A. Hubert and R. Schäfer, Magnetic Domains, Springer, 1998.

9. Source-code index¶

Source-code index¶

• Python contract source: packages/fullmag-py/src/fullmag/model/discretization.py and packages/fullmag-py/src/fullmag/world.py, where applicable. Backend realization is in the relevant backends/fdm or backends/fem lane named by the page.