Imported-Mesh 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¶

Importing a prebuilt FEM mesh instead of generating it with Gmsh. At study level: FEM(..., mesh="path-or-asset"); at object level: the recipe source field.

When to use it:

• the mesh was produced in an external tool (COMSOL, Salome, a custom mesher),

• you want to repeat exactly the same mesh across runs,

• the geometry requires specialized meshing unavailable in Gmsh.

Impact on the simulation: import does not bypass validation — units, element family/order, orientation, attributes, and backend compatibility are checked at extraction; a defective mesh fails loudly instead of being silently used.

2. Physical and mathematical explanation¶

This page introduces no equation of its own; it supplies a ready discrete space. Import validation checks, among others, metric consistency of element Jacobians:

where \(\mathbf{x}\) — physical node coordinates (\(\mathrm{m}\)), \(\boldsymbol{\xi}\) — reference coordinates (\(1\)). A negative or degenerate \(J_K\) disqualifies the element.

3. Example — complete Python script¶

# %% Imported FEM mesh at study level
import fullmag as fm
from pathlib import Path

nm = 1.0e-9

study = fm.study("imported_mesh_example")
study.engine("fem")
study.device("cpu", precision="double")
study.mode("strict")
study.objects.mesh.defaults(order=1, maximum_element_size=5 * nm)

film = study.geometry(fm.Box(300 * nm, 100 * nm, 5 * nm), 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)

# Import only an existing, validated Gmsh/COMSOL domain mesh. The fallback keeps
# this public example executable when the optional artifact is not present.
mesh_path = Path("run_output/prebuilt_domain_mesh.msh")
if mesh_path.is_file():
    study.mesh.import_(mesh_path)
else:
    study.universe(mode="manual", size=(800 * nm, 400 * nm, 300 * nm))
    study.universe.mesh(maximum_element_size=100 * nm)

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

# %% Object-level imported source (advanced recipe)
# film.mesh(source="assets/film_mesh.msh2")

4. Exact API¶

Extraction-time validation covers: units, element family and order, orientation, region attributes, boundaries, periodic metadata, and target-backend compatibility.

Failure behavior: a missing/unreadable asset → extraction error; any failed check → validation error describing the mismatch. Import never shortcuts validation.

ProblemIR mapping: backend_policy.discretization_hints.fem.mesh (study level) / the object-recipe source field.

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: the Element Size Parameters group holds the source field (path/asset reference). An imported mesh is read-only with respect to generation parameters; quality and history inspection remain available (Quality / History tabs). Full panel 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¶

• Import does not waive shared-domain rules: the mesh must cover the universe and objects according to the build policy.

• Changing geometry after importing invalidates the match; the authoring fingerprint detects the drift.

8. Scientific bibliography¶

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

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.