MMG behavior and guarantees
Tested behavior of Rodin's MMG wrappers, required entities, and level-set cuts.
Overview
Rodin's MMG module wraps the Mmg Platform for local mesh processing. It provides three distinct workflows:
| Workflow | Rodin entry point | Expected behavior |
|---|---|---|
| Mesh-quality optimization | MMG:: | Improves element quality while staying close to the existing local size distribution |
| Metric/field adaptation | MMG:: | Refines, coarsens, moves, and reconnects elements according to a size field |
| Level-set discretization | MMG:: | Cuts an input mesh with an isovalue and produces a body-fitted mesh or extracted surface |
All three workflows convert MMG::
Required entity behavior
MMG::
mesh.setRequiredVertex(vertexIndex); mesh.setRequiredEdge(edgeIndex); mesh.setRequiredTriangle(triangleIndex); mesh.setRequiredTetrahedron(tetrahedronIndex);
These sets are:
- written to MEDIT as
RequiredVertices,RequiredEdges,RequiredTriangles, andRequiredTetrahedra; - read back from MEDIT into the same Rodin metadata;
- passed to native MMG structures as
MG_REQtags; - recovered from native MMG output when converting back to Rodin;
- restored by the optimizer and level-set wrappers when the original index is still valid in the output.
The test suite covers this metadata path in 2D and 3D, including MEDIT I/O, native MMG conversion, optimization, and level-set discretization. In MMG3D, triangle metadata describes the boundary surface. When face-cell incidence is available, Rodin exports only boundary triangles to MMG's native triangle table. Interior faces of a tetrahedral mesh are not a supported MMG3D RequiredTriangles preservation mechanism.
Uncut level-set entities
For level-set discretization, Rodin has explicit geometry-preservation tests for required entities that are not crossed by the level set:
- in 2D, required vertices, edges, and triangles retain their required metadata and the original entity coordinates remain present in the output;
- in 3D, required vertices, edges, triangles, and tetrahedra retain their required metadata and the original entity coordinates remain present in the output.
The tests check the geometry and required metadata of entities away from the level-set cut.
Cut-through level-set entities
During level-set discretization, MMG can modify a required entity intersected by the isovalue to construct the interface.
In particular, for 3D level-set discretization, if the zero level set cuts a required boundary triangle face in a tetrahedral mesh, MMG may replace that triangle. Interior tetrahedral faces are not passed to MMG as boundary triangles. The same caveat applies to other cut-through entities. In this situation MMG can emit a warning containing Required entity ignored.
The regression tests record this MMG behavior.
NoSplit and material labels
LevelSetDiscretizer::
MMG::Mesh result = MMG::LevelSetDiscretizer() .split(interior, { interior, exterior }) .noSplit(protectedReference) .discretize(levelSet);
noSplit(ref) retains the material reference ref during phase classification. The geometry of intersected entities remains subject to MMG's interface-construction step.
The characterization tests cover the following cut-through combinations:
| Protected entity | Extra labels or requirements | Exact original geometry preserved? |
|---|---|---|
| edge in a 2D triangle mesh | required edge and noSplit on containing triangles | no |
| triangle in a 2D mesh | individual label, with or without required triangle | no |
| edge in a 3D tetrahedral mesh | required edge and noSplit on adjacent tetrahedra | no |
| triangle face in a 3D tetrahedral mesh | required triangle and/or individual face label | no |
| triangle face in a 3D tetrahedral mesh | noSplit on adjacent tetrahedra | no |
| triangle face in a 3D tetrahedral mesh | required vertices, edges, face, and adjacent tetrahedra | no |
| tetrahedron in a 3D mesh | required tetrahedron and noSplit on its material reference | no |
The practical rule is:
- if the level set does not cut the required entity, Rodin's tested behavior is preservation of the required metadata and original geometry;
- if the level set cuts the entity, MMG may alter it to conform the output mesh to the interface, even when
MG_REQ, individual labels, adjacent tetrahedron labels, andnoSplitare used.
Workarounds for protected geometry
If an element or face must remain untouched, treat that requirement as an input validity condition before calling MMG level-set discretization:
- preflight the level-set values on the protected entity and reject the step if the isovalue crosses it;
- change or clamp the level set so the protected entity lies entirely on one side of the cut;
- pre-partition the mesh so the protected surface is already part of the mesh interface before level-set discretization;
- use
noSplit(ref)to configure material-reference splitting.
Test coverage
The MMG unit suite exercises:
- required vertex, edge, triangle, and tetrahedron API lifecycle;
- MEDIT I/O round trips for required entities;
- native MMG conversion with required entities;
- optimization preservation of required metadata;
- level-set discretization preservation for uncut required geometry in 2D and 3D;
- cut-through characterization with
MG_REQ, labels, adjacent tetrahedra, local closure requirements, andnoSplit.