Rodin::MMG module

Mesh adaptation through the MMG integration.

Mesh connects Rodin geometry to MMG. Adapt performs metric-driven adaptation, Optimizer improves mesh quality, and LevelSetDiscretizer fits or extracts an isosurface. These workflows support remeshing and interface reconstruction in shape optimization and evolving-geometry simulations.

Key Classes

Class	Purpose
MMG::Mesh	Local mesh type extending Geometry::Mesh<Context::Local> with corner, ridge, and required-entity metadata.
MMG::Adapt	Metric-based adaptation from a nodal size map.
MMG::Optimizer	Mesh-quality optimization without an external metric field.
MMG::LevelSetDiscretizer	Level-set meshing: cuts a background mesh along an isovalue or extracts the isosurface.
MMG::MMG5	Base class providing shared MMG configuration and native conversion helpers.

Workflow Semantics

Optimizer, Adapt, and LevelSetDiscretizer are intentionally different operations:

Workflow	Expected behavior
Optimizer	Improves element quality while keeping the mesh close to the existing local size distribution.
Adapt	Refines, coarsens, moves, and reconnects elements according to a size field.
LevelSetDiscretizer	Alters topology as needed to conform the output mesh to the selected level-set isovalue.

All workflows convert an MMG::Mesh to native MMG structures, run MMG, and convert the result back. The output is a remeshed object; input element indices should be treated as stable only where the wrapper or tests explicitly document preservation.

Auto-Dispatch

The wrappers auto-dispatch to the appropriate MMG backend based on the mesh type:

Mesh type	Backend
2D planar	MMG2D
3D volumetric	MMG3D
Surface in 3D	MMGS

Shared Configuration (MMG5 base)

The MMG wrappers inherit common configuration methods from MMG5; each returns *this for chaining:

Method	Description
setHMin(hmin)	Minimal allowed edge size
setHMax(hmax)	Maximal allowed edge size
setHausdorff(hausd)	Hausdorff distance tolerance for boundary approximation
setGradation(hgrad)	Edge-size gradation ratio between adjacent elements
setAngleDetection(bool)	Enable ridge angle detection for feature preservation

Required Entities

MMG::Mesh stores MMG-specific metadata:

Method	Description
setCorner(vertexIdx)	Mark a vertex as a geometric corner
setRidge(edgeIdx)	Mark an edge as a geometric ridge
setRequiredVertex(idx)	Mark a vertex as required (`MG_REQ`)
setRequiredEdge(idx)	Mark an edge as required (`MG_REQ`)
setRequiredTriangle(idx)	Mark a triangle as required (`MG_REQ`)
setRequiredTetrahedron(idx)	Mark a tetrahedron as required (`MG_REQ`)

Required vertices, edges, triangles, and tetrahedra are serialized through MEDIT, converted to native MMG MG_REQ tags, and restored from native MMG output. The optimizer and level-set wrappers restore required index sets when the original indices are still valid after remeshing. In MMG3D, setRequiredTriangle(idx) applies to boundary triangles exported to MMG's triangle table; interior faces of a tetrahedral mesh are not exported as MMG boundary triangles when face-cell incidence is available.

For level-set discretization, the tested behavior is:

required entities not crossed by the level set retain their required metadata and original geometry in the 2D/3D cases covered by the test suite;
required entities crossed by the level set are not guaranteed to remain intact. MMG may replace them to conform the mesh to the isovalue, even when MG_REQ, individual labels, adjacent tetrahedron labels, local closure requirements, or noSplit(ref) are used.

See MMG behavior and guarantees for the full characterization.

LevelSetDiscretizer API

In addition to MMG5 parameters, LevelSetDiscretizer provides:

Method	Description
setLevelSet(ls)	Isovalue to extract (default: 0.0)
surface(bool)	When true, discretize the isosurface; when false, discretize the subdomain volume
setRMC(rmc)	Removal threshold for small parasitic components
setBoundaryReference(ref)	Material reference for the discretized boundary
setBaseReferences(refs)	Restrict level-set splitting to specified base materials
split(ref, split)	Split one material reference into inside/outside references
noSplit(ref)	Keep one material reference from being split by the material policy

noSplit(ref) is a material-reference splitting policy. It is not an element-integrity guarantee for an individual edge, triangle, or tetrahedron that the level set cuts.

MMG::Mesh cut = MMG::LevelSetDiscretizer()
  .setLevelSet(0.0)
  .split(interior, { interior, exterior })
  .setBoundaryReference(interface)
  .discretize(phi);

Use MMG::Mesh::Build() to construct meshes programmatically via the builder pattern.

Classes

class Adapt: Performs anisotropic/isotropic remeshing from a nodal size map.
struct NoSplitT: Tag type indicating that a material reference must not be split.
struct Split: Interior/exterior labels produced when splitting one material.
class LevelSetDiscretizer: Discretizes implicit geometry defined by a nodal level-set field.
class Mesh: Local mesh enriched with MMG boundary tags and constraints.
class MeshLoader: Loads an Mesh from the MEDIT format.
class Optimizer: Improves mesh quality while preserving characteristic local sizes.
class MeshPrinter: Printer for Mesh in MEDIT/MMG-compatible syntax.
template<class FuncName> class MMG5Exception: Exception type for MMG wrapper failures.
class MMG5: Base class for MMG-backed operations in Rodin.

Typedefs

using SplitMap = UnorderedMap<Geometry::Attribute, std::variant<Split, NoSplitT>>: Material splitting policy map used by level-set discretization.
template<class Range> using GridFunction = Variational::GridFunction<Variational::P1<Range, Geometry::Mesh<Context::Local>>, Math::Vector<Real>>: Grid function type used by the MMG module.
using RealGridFunction = GridFunction<Real>: Scalar MMG grid function alias.
using VectorGridFunction = GridFunction<Math::SpatialVector<Real>>: Vector-valued MMG grid function alias.
using ReturnCode = int: Return-code type used by MMG C API calls.

Functions

auto getISCDMshdistExecutable() -> const char*: Gets the configured path to the mshdist executable.
auto getISCDAdvectExecutable() -> const char*: Gets the configured path to the advect executable.
auto getMMGVerbosityLevel() -> int: Gets the MMG verbosity level selected at configuration time.

Variables

static NoSplitT NoSplit constexpr: Singleton tag instance for convenience in split configuration.
const char* iscdMshdistExecutable constexpr: Path to the ISCD Mshdist executable.
const char* mshdistExecutable constexpr: Path to the Mshdist executable used by MMG helpers.
const char* iscdAdvectionExecutable constexpr: Path to the ISCD Mshdist executable.
const char* advectionExecutable constexpr: Path to the ISCD advection executable used by MMG helpers.
const int verbosityLevel constexpr: Verbosity level for MMG console output.

Typedef documentation

using SplitMap = UnorderedMap<Geometry::Attribute, std::variant<Split, NoSplitT>>

Defined in Rodin/MMG/Common.h

Material splitting policy map used by level-set discretization.

Keys are input material attributes from the source mesh. Values describe whether each material is split into distinct interior/exterior labels (Split) or kept unchanged (NoSplitT).

This map is consumed by setSplit.

template<class Range>
using GridFunction = Variational::GridFunction<Variational::P1<Range, Geometry::Mesh<Context::Local>>, Math::Vector<Real>>

Defined in Rodin/MMG/GridFunction.h

Grid function type used by the MMG module.

Template parameters
Range	Value type (`Real` for scalar fields, `Math::SpatialVector<Real>` for vector fields).

MMG workflows in Rodin operate on first-order nodal fields defined on local meshes. This alias standardizes that representation for scalar and vector quantities transferred to/from MMG solution structures.