Mesh¶

Introduction¶

μfem reads the computational mesh from a file and uses it for the lifetime of the simulation. The mesh is loaded either through the Simulation.New factory or, later, through the domain:

sim = mufem.Simulation.New("My Example", "data/geometry.mesh")

# Equivalent two-step form:
sim = mufem.Simulation.New("My Example")
sim.get_domain().load_mesh("data/geometry.mesh")

The same load_mesh call accepts optional matching and merging interface conditions used during partitioning, and a non-conforming option for adaptively refined meshes.

Supported Formats¶

The mesh file is parsed by the underlying MFEM library. The two formats exercised across the μfem test suite are:

Extension	Format	Notes
`.mesh`	MFEM native	Recommended for in-house workflows; preserves curvature directly.
`.msh`	Gmsh	Write the MSH 2.2 format (see note below). Both integer attributes and `PhysicalNames` are read.

Write Gmsh meshes in the MSH 2.2 format

μfem reads the Gmsh 2.2 format reliably. The current Gmsh default (MSH 4.x) can fail on import with Gmsh file : vertices indices are not unique, especially for meshes that carry several physical groups. Select the 2.2 format explicitly: in the Gmsh Python API set gmsh.option.setNumber("Mesh.MshFileVersion", 2.2) before gmsh.write(...), or on the command line pass -format msh22.

NURBS meshes are converted to a piecewise-polynomial curved mesh on import.

Entities and Attributes¶

μfem exposes two kinds of mesh entities:

Entity	Marker keyword	Used for
Volume	`Vol`	Material assignment, model regions, volumetric reports.
Boundary	`Bnd`	Boundary conditions, interfaces, surface reports.

Edges and points are not addressable from the Python interface.

Each entity carries a mesh attribute — either an integer (e.g. Gmsh physical tag 11) or a string name (e.g. the PhysicalNames entry "Bnd1"). Both forms can be used interchangeably when constructing a Marker:

inlet = 11      @ Bnd
inlet = "Bnd1"  @ Bnd

Named tags are recommended: they survive renumbering by the mesher and make case scripts self-documenting. See Markers for the full syntax, including list and union markers.

Mesh Coefficients¶

A set of mesh-derived coefficients (Position, Cell Attribute, Cell Volume, Cell Aspect Ratio, Element Type, Element Order, Global Cell Index, Local Cell Index) is registered automatically and listed in Built-in Coefficients. They can be exported with the Field Exporter to inspect mesh quality and topology.

Quality Check on Import¶

When a mesh is loaded, μfem automatically scans every element and reports any geometry that would compromise the solution. The check runs once per import, costs a single Jacobian evaluation per element node, and is negligible compared to partitioning.

Two conditions are reported:

Condition	Meaning
Inverted element	The Jacobian determinant \(\det(J)\) is non-positive at one or more nodal points of the element. The element has folded onto itself and will cause solver instability or wrong results. Most commonly produced by midpoint snapping on curved boundaries in second-order meshes.
Sliver element	\(\det(J)\) is positive but below \(10^{-14}\). The element is nearly degenerate; the solution stays valid but iterative solvers may converge slowly.

An inverted-element report looks like:

============================================================
!!  INVERTED MESH ELEMENTS DETECTED  !!
============================================================
  Inverted element count : 3
  min det(J)             : -1.842e-04
  max det(J)             : 7.531e-02
  worst local cell       : 18427
  Such elements will cause solver instability or incorrect results.
  Fix the mesh before trusting the solution -- typically by refining
  near curved surfaces.
============================================================

When inverted elements are reported, the mesh should be regenerated — typically with finer resolution along curved surfaces — before the solution is used for engineering decisions. Sliver warnings are advisory; they do not invalidate results.