Examples and tutorials » Working with MMG » 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:

WorkflowRodin entry pointExpected behavior
Mesh-quality optimizationMMG::OptimizerImproves element quality while staying close to the existing local size distribution
Metric/field adaptationMMG::AdaptRefines, coarsens, moves, and reconnects elements according to a size field
Level-set discretizationMMG::LevelSetDiscretizerCuts an input mesh with an isovalue and produces a body-fitted mesh or extracted surface

All three workflows convert MMG::Mesh to native MMG data structures, run MMG, and convert the result back to Rodin. MMG chooses the output topology and entity numbering. Geometric entities are identified from the returned mesh and metadata.

Required entity behavior

MMG::Mesh stores required vertices, edges, triangles, and tetrahedra.

mesh.setRequiredVertex(vertexIndex);
mesh.setRequiredEdge(edgeIndex);
mesh.setRequiredTriangle(triangleIndex);
mesh.setRequiredTetrahedron(tetrahedronIndex);

These sets are:

  • written to MEDIT as RequiredVertices, RequiredEdges, RequiredTriangles, and RequiredTetrahedra;
  • read back from MEDIT into the same Rodin metadata;
  • passed to native MMG structures as MG_REQ tags;
  • 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::noSplit applies MMG's material split policy to a material reference.

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 entityExtra labels or requirementsExact original geometry preserved?
edge in a 2D triangle meshrequired edge and noSplit on containing trianglesno
triangle in a 2D meshindividual label, with or without required triangleno
edge in a 3D tetrahedral meshrequired edge and noSplit on adjacent tetrahedrano
triangle face in a 3D tetrahedral meshrequired triangle and/or individual face labelno
triangle face in a 3D tetrahedral meshnoSplit on adjacent tetrahedrano
triangle face in a 3D tetrahedral meshrequired vertices, edges, face, and adjacent tetrahedrano
tetrahedron in a 3D meshrequired tetrahedron and noSplit on its material referenceno

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, and noSplit are 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, and noSplit.

See also