Skip to content

Mesh Export

The voids.mesh sub-package converts regular porosity and permeability maps into structured mesh files for downstream continuum workflows, including quadrilateral/triangular 2-D exports and hexahedral/tetrahedral 3-D exports.

These helpers preserve the map grid and cell ordering; they do not generate a boundary-conforming mesh of the original segmented pore/bone interface. For the map definitions, schemes, Kozeny-Carman closure, export assumptions, and solver-facing caveats, see Porosity Maps.

The optional Gmsh helpers build in-memory CAD models and preserve physical tags when converting to DOLFINx. They require both the Gmsh executable and Python bindings; the centered-vug workflow is described in FEM Manufactured-Solution Verification.

API

voids.mesh

DolfinxGmshMesh dataclass

DOLFINx mesh and physical tags converted from an in-memory Gmsh model.

Source code in src/voids/mesh/gmsh.py 
13
14
15
16
17
18
19
20
21
22
@dataclass(slots=True)
class DolfinxGmshMesh:
    """DOLFINx mesh and physical tags converted from an in-memory Gmsh model."""

    mesh: Any
    cell_tags: Any | None
    facet_tags: Any | None
    ridge_tags: Any | None
    peak_tags: Any | None
    physical_groups: dict[str, Any]

StructuredMapMesh dataclass

Structured mesh representation for regular porosity/permeability maps.

Attributes:

Name Type Description
points ndarray

Mesh point coordinates. Points are always stored as three-dimensional coordinates so 2-D maps can be written by formats that expect 3-D coordinates with z=0.
cells tuple[tuple[str, ndarray], ...]

A single meshio-compatible cell block. 2-D maps use "quad" cells by default or "triangle" cells when requested. 3-D maps use "hexahedron" cells by default or "tetra" cells when requested.
cell_data dict[str, list[ndarray]]

Cell-wise data arrays whose flattened order follows numpy.ravel(order="C") of the original map arrays.
Source code in src/voids/mesh/structured.py 
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
@dataclass(slots=True)
class StructuredMapMesh:
    """Structured mesh representation for regular porosity/permeability maps.

    Attributes
    ----------
    points :
        Mesh point coordinates. Points are always stored as three-dimensional
        coordinates so 2-D maps can be written by formats that expect 3-D
        coordinates with ``z=0``.
    cells :
        A single meshio-compatible cell block. 2-D maps use ``"quad"`` cells by
        default or ``"triangle"`` cells when requested. 3-D maps use
        ``"hexahedron"`` cells by default or ``"tetra"`` cells when requested.
    cell_data :
        Cell-wise data arrays whose flattened order follows
        ``numpy.ravel(order="C")`` of the original map arrays.
    """

    points: np.ndarray
    cells: tuple[tuple[str, np.ndarray], ...]
    cell_data: dict[str, list[np.ndarray]]

    @property
    def cell_type(self) -> str:
        """Return the meshio cell type used by the structured map mesh."""

        return self.cells[0][0]

    @property
    def cell_count(self) -> int:
        """Return the number of cells in the structured map mesh."""

        return int(self.cells[0][1].shape[0])

    def to_meshio(self, *, include_cell_data: bool = True) -> object:
        """Return a ``meshio.Mesh`` object.

        Parameters
        ----------
        include_cell_data :
            If ``False``, only geometry is included. This is useful for formats
            that do not preserve arbitrary floating-point cell data.
        """

        meshio = _import_meshio()
        return meshio.Mesh(
            points=self.points,
            cells=list(self.cells),
            cell_data=self.cell_data if include_cell_data else {},
        )

    def write(self, path: str | Path, *, file_format: str | None = None) -> Path:
        """Write the mesh with meshio and return the destination path."""

        return _write_mesh(self, path, file_format=file_format)

cell_type property 

cell_type

Return the meshio cell type used by the structured map mesh.

cell_count property 

cell_count

Return the number of cells in the structured map mesh.

to_meshio 

to_meshio(*, include_cell_data=True)

Return a meshio.Mesh object.

Parameters:

Name Type Description Default
include_cell_data bool

If False, only geometry is included. This is useful for formats that do not preserve arbitrary floating-point cell data.

 True
Source code in src/voids/mesh/structured.py 
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
def to_meshio(self, *, include_cell_data: bool = True) -> object:
    """Return a ``meshio.Mesh`` object.

    Parameters
    ----------
    include_cell_data :
        If ``False``, only geometry is included. This is useful for formats
        that do not preserve arbitrary floating-point cell data.
    """

    meshio = _import_meshio()
    return meshio.Mesh(
        points=self.points,
        cells=list(self.cells),
        cell_data=self.cell_data if include_cell_data else {},
    )

write 

write(path, *, file_format=None)

Write the mesh with meshio and return the destination path.

Source code in src/voids/mesh/structured.py 
77
78
79
80
def write(self, path: str | Path, *, file_format: str | None = None) -> Path:
    """Write the mesh with meshio and return the destination path."""

    return _write_mesh(self, path, file_format=file_format)

add_physical_group 

add_physical_group(gmsh, dimension, entities, *, tag, name)

Add a nonempty named physical group and return its integer tag.

Source code in src/voids/mesh/gmsh.py 
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
def add_physical_group(
    gmsh: Any,
    dimension: int,
    entities: Sequence[int],
    *,
    tag: int,
    name: str,
) -> int:
    """Add a nonempty named physical group and return its integer tag."""

    entity_tags = [int(entity) for entity in entities]
    if dimension < 0:
        raise ValueError("dimension must be nonnegative")
    if not entity_tags:
        raise ValueError("entities must not be empty")
    if tag <= 0:
        raise ValueError("tag must be positive")
    if not name.strip():
        raise ValueError("name must not be empty")
    created = int(gmsh.model.addPhysicalGroup(dimension, entity_tags, tag))
    gmsh.model.setPhysicalName(dimension, created, name)
    return created

axis_aligned_boundary_entities 

axis_aligned_boundary_entities(
    gmsh,
    geometric_dimension,
    *,
    bounds=None,
    tolerance=1e-10,
)

Classify axis-aligned facets by their Gmsh bounding boxes.

Curved and interior facets are returned in the second tuple item.

Source code in src/voids/mesh/gmsh.py 
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
def axis_aligned_boundary_entities(
    gmsh: Any,
    geometric_dimension: int,
    *,
    bounds: Sequence[tuple[float, float]] | None = None,
    tolerance: float = 1.0e-10,
) -> tuple[dict[str, list[int]], list[int]]:
    """Classify axis-aligned facets by their Gmsh bounding boxes.

    Curved and interior facets are returned in the second tuple item.
    """

    if geometric_dimension not in {2, 3}:
        raise ValueError("geometric_dimension must be either 2 or 3")
    if tolerance <= 0.0 or not np.isfinite(tolerance):
        raise ValueError("tolerance must be positive and finite")
    resolved_bounds = tuple(bounds or ((0.0, 1.0),) * geometric_dimension)
    if len(resolved_bounds) != geometric_dimension:
        raise ValueError("bounds must contain one (minimum, maximum) pair per axis")
    for lower, upper in resolved_bounds:
        if not np.isfinite(lower) or not np.isfinite(upper) or lower >= upper:
            raise ValueError("each bounds pair must be finite and strictly increasing")

    axis_names = ("x", "y", "z")[:geometric_dimension]
    groups: dict[str, list[int]] = {
        f"{axis_name}_{side}": [] for axis_name in axis_names for side in ("min", "max")
    }
    unclassified: list[int] = []
    facet_dimension = geometric_dimension - 1
    for _, entity in gmsh.model.getEntities(facet_dimension):
        bounding_box = gmsh.model.getBoundingBox(facet_dimension, entity)
        lower_coordinates = bounding_box[:3]
        upper_coordinates = bounding_box[3:]
        matched_name: str | None = None
        for axis, axis_name in enumerate(axis_names):
            lower, upper = resolved_bounds[axis]
            if (
                abs(lower_coordinates[axis] - lower) <= tolerance
                and abs(upper_coordinates[axis] - lower) <= tolerance
            ):
                matched_name = f"{axis_name}_min"
                break
            if (
                abs(lower_coordinates[axis] - upper) <= tolerance
                and abs(upper_coordinates[axis] - upper) <= tolerance
            ):
                matched_name = f"{axis_name}_max"
                break
        if matched_name is None:
            unclassified.append(int(entity))
        else:
            groups[matched_name].append(int(entity))
    return groups, unclassified

configure_uniform_mesh_size 

configure_uniform_mesh_size(
    gmsh,
    target_size,
    *,
    element_order=1,
    size_from_curvature=True,
)

Configure a uniform target size for subsequent Gmsh generation.

Source code in src/voids/mesh/gmsh.py 
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
def configure_uniform_mesh_size(
    gmsh: Any,
    target_size: float,
    *,
    element_order: int = 1,
    size_from_curvature: bool = True,
) -> None:
    """Configure a uniform target size for subsequent Gmsh generation."""

    if target_size <= 0.0 or not np.isfinite(target_size):
        raise ValueError("target_size must be positive and finite")
    if element_order < 1:
        raise ValueError("element_order must be at least 1")
    gmsh.option.setNumber("Mesh.MeshSizeMin", float(target_size))
    gmsh.option.setNumber("Mesh.MeshSizeMax", float(target_size))
    gmsh.option.setNumber("Mesh.MeshSizeFromCurvature", int(size_from_curvature))
    gmsh.option.setNumber("Mesh.ElementOrder", int(element_order))

generate_dolfinx_gmsh_mesh 

generate_dolfinx_gmsh_mesh(
    build_model,
    *,
    name,
    geometric_dimension,
    comm=None,
    model_rank=0,
    terminal_output=False,
)

Build a Gmsh model on one MPI rank and convert it to DOLFINx.

build_model receives Gmsh after a fresh model has been created. It must synchronize the CAD kernel, define physical groups, and generate the mesh.

Source code in src/voids/mesh/gmsh.py 
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
def generate_dolfinx_gmsh_mesh(
    build_model: GmshModelBuilder,
    *,
    name: str,
    geometric_dimension: int,
    comm: Any | None = None,
    model_rank: int = 0,
    terminal_output: bool = False,
) -> DolfinxGmshMesh:
    """Build a Gmsh model on one MPI rank and convert it to DOLFINx.

    ``build_model`` receives Gmsh after a fresh model has been created. It must
    synchronize the CAD kernel, define physical groups, and generate the mesh.
    """

    if not callable(build_model):
        raise TypeError("build_model must be callable")
    if not name.strip():
        raise ValueError("name must not be empty")
    if geometric_dimension not in {2, 3}:
        raise ValueError("geometric_dimension must be either 2 or 3")
    gmsh = require_gmsh()
    try:
        from dolfinx.io import gmsh as dolfinx_gmsh
        from mpi4py import MPI
    except ImportError as exc:  # pragma: no cover - optional environment
        raise ImportError(
            "DOLFINx Gmsh conversion requires dolfinx, mpi4py, and python-gmsh"
        ) from exc

    communicator = MPI.COMM_WORLD if comm is None else comm
    if not 0 <= model_rank < communicator.size:
        raise ValueError("model_rank must identify a rank in comm")
    initialized_here = False
    try:
        if communicator.rank == model_rank:
            if not gmsh.isInitialized():
                gmsh.initialize()
                initialized_here = True
            gmsh.clear()
            gmsh.option.setNumber("General.Terminal", int(terminal_output))
            gmsh.model.add(name)
            build_model(gmsh)
        mesh_data = dolfinx_gmsh.model_to_mesh(
            gmsh.model,
            communicator,
            model_rank,
            gdim=geometric_dimension,
        )
    finally:
        if communicator.rank == model_rank:
            if initialized_here:
                gmsh.finalize()
            else:
                gmsh.clear()
    return DolfinxGmshMesh(
        mesh=mesh_data.mesh,
        cell_tags=mesh_data.cell_tags,
        facet_tags=mesh_data.facet_tags,
        ridge_tags=getattr(mesh_data, "ridge_tags", getattr(mesh_data, "edge_tags", None)),
        peak_tags=getattr(mesh_data, "peak_tags", getattr(mesh_data, "vertex_tags", None)),
        physical_groups=dict(mesh_data.physical_groups),
    )

require_gmsh 

require_gmsh()

Import and return the optional Gmsh Python module.

Source code in src/voids/mesh/gmsh.py 
25
26
27
28
29
30
31
32
33
34
35
def require_gmsh() -> Any:
    """Import and return the optional Gmsh Python module."""

    try:
        import gmsh  # type: ignore[import-untyped]
    except ImportError as exc:  # pragma: no cover - optional environment
        raise ImportError(
            "Gmsh mesh generation requires the Gmsh executable and Python "
            "bindings. In Pixi, install both 'gmsh' and 'python-gmsh'."
        ) from exc
    return gmsh

mesh_format_extension 

mesh_format_extension(format_name)

Return the default filename extension for a supported mesh export format.

Source code in src/voids/mesh/structured.py 
83
84
85
86
87
88
89
90
91
92
93
def mesh_format_extension(format_name: str) -> str:
    """Return the default filename extension for a supported mesh export format."""

    key = str(format_name).strip().lower().lstrip(".")
    try:
        return _FORMAT_EXTENSIONS[key]
    except KeyError as exc:
        supported = ", ".join(sorted(_FORMAT_EXTENSIONS))
        raise ValueError(
            f"Unsupported mesh format {format_name!r}; expected one of {supported}"
        ) from exc

structured_map_mesh 

structured_map_mesh(
    porosity_map,
    *,
    permeability_map=None,
    extra_cell_data=None,
    element_type="auto",
    include_cell_index=True,
    require_finite_cell_data=True,
)

Generate a structured mesh from a regular porosity map.

Parameters:

Name Type Description Default
porosity_map PorosityMap

Cell-average porosity map. Its grid defines the mesh topology and physical coordinates.

 required
permeability_map PermeabilityMap | None

Optional permeability map on the same grid. When supplied, it is written as the "permeability" cell-data field.

 None
extra_cell_data Mapping[str, ndarray] | None

Optional additional cell-data arrays. Each array must have the same shape as porosity_map.values.

 None
element_type MapMeshElement

Mesh cell type. "auto" uses quadrilaterals for 2-D maps and hexahedra for 3-D maps. "triangle" is valid only for 2-D maps and splits each quadrilateral into two triangles. "tetra" and "tetrahedron" are valid only for 3-D maps and split each hexahedron into six tetrahedra.

 'auto'
include_cell_index bool

If True, include a zero-based "cell_index" integer field that maps each mesh cell back to its parent map cell. For simplex exports, the child triangles or tetrahedra from one map cell share the same value.

 True
require_finite_cell_data bool

If True, reject NaN or infinite cell-data values before export.

 True

Returns:

Type Description
StructuredMapMesh

Meshio-compatible points, cell connectivity, and cell-data arrays.
Notes

The mesh is a representation of a regular map grid, not an image-boundary conforming segmentation mesh. Cell n corresponds to porosity_map.values.ravel(order="C")[n].

Source code in src/voids/mesh/structured.py 
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
def structured_map_mesh(
    porosity_map: PorosityMap,
    *,
    permeability_map: PermeabilityMap | None = None,
    extra_cell_data: Mapping[str, np.ndarray] | None = None,
    element_type: MapMeshElement = "auto",
    include_cell_index: bool = True,
    require_finite_cell_data: bool = True,
) -> StructuredMapMesh:
    """Generate a structured mesh from a regular porosity map.

    Parameters
    ----------
    porosity_map :
        Cell-average porosity map. Its grid defines the mesh topology and
        physical coordinates.
    permeability_map :
        Optional permeability map on the same grid. When supplied, it is written
        as the ``"permeability"`` cell-data field.
    extra_cell_data :
        Optional additional cell-data arrays. Each array must have the same shape
        as ``porosity_map.values``.
    element_type :
        Mesh cell type. ``"auto"`` uses quadrilaterals for 2-D maps and
        hexahedra for 3-D maps. ``"triangle"`` is valid only for 2-D maps and
        splits each quadrilateral into two triangles. ``"tetra"`` and
        ``"tetrahedron"`` are valid only for 3-D maps and split each
        hexahedron into six tetrahedra.
    include_cell_index :
        If ``True``, include a zero-based ``"cell_index"`` integer field that
        maps each mesh cell back to its parent map cell. For simplex exports,
        the child triangles or tetrahedra from one map cell share the same
        value.
    require_finite_cell_data :
        If ``True``, reject NaN or infinite cell-data values before export.

    Returns
    -------
    StructuredMapMesh
        Meshio-compatible points, cell connectivity, and cell-data arrays.

    Notes
    -----
    The mesh is a representation of a regular map grid, not an image-boundary
    conforming segmentation mesh. Cell ``n`` corresponds to
    ``porosity_map.values.ravel(order="C")[n]``.
    """

    _validate_map_grid(porosity_map)
    points, cells = _structured_points_and_cells(
        shape=porosity_map.shape,
        cell_size=_map_cell_size(porosity_map),
        origin=_map_origin(porosity_map),
        element_type=element_type,
    )
    base_cell_count = int(np.prod(porosity_map.shape))
    mesh_cell_count = int(cells[1].shape[0])

    cell_data: dict[str, list[np.ndarray]] = {
        "porosity": [
            _expand_cell_data_to_mesh_cells(
                _flatten_cell_data(
                    porosity_map.values,
                    shape=porosity_map.shape,
                    name="porosity",
                    require_finite=require_finite_cell_data,
                ),
                base_cell_count=base_cell_count,
                mesh_cell_count=mesh_cell_count,
            )
        ]
    }

    if permeability_map is not None:
        _validate_matching_map_grid(porosity_map, permeability_map)
        cell_data["permeability"] = [
            _expand_cell_data_to_mesh_cells(
                _flatten_cell_data(
                    permeability_map.values,
                    shape=porosity_map.shape,
                    name="permeability",
                    require_finite=require_finite_cell_data,
                ),
                base_cell_count=base_cell_count,
                mesh_cell_count=mesh_cell_count,
            )
        ]

    if include_cell_index:
        cell_data["cell_index"] = [
            _expand_cell_data_to_mesh_cells(
                np.arange(base_cell_count, dtype=np.int64),
                base_cell_count=base_cell_count,
                mesh_cell_count=mesh_cell_count,
            )
        ]

    if extra_cell_data:
        for raw_name, raw_values in extra_cell_data.items():
            name = str(raw_name)
            if not name:
                raise ValueError("extra_cell_data names must be non-empty strings")
            if name in cell_data:
                raise ValueError(f"Duplicate cell-data name {name!r}")
            cell_data[name] = [
                _expand_cell_data_to_mesh_cells(
                    _flatten_cell_data(
                        raw_values,
                        shape=porosity_map.shape,
                        name=name,
                        require_finite=require_finite_cell_data,
                    ),
                    base_cell_count=base_cell_count,
                    mesh_cell_count=mesh_cell_count,
                )
            ]

    return StructuredMapMesh(points=points, cells=(cells,), cell_data=cell_data)

write_structured_map_mesh 

write_structured_map_mesh(
    porosity_map,
    path,
    *,
    permeability_map=None,
    extra_cell_data=None,
    element_type="auto",
    file_format=None,
    require_finite_cell_data=True,
)

Write a structured map mesh with porosity/permeability cell data.

Parameters:

Name Type Description Default
porosity_map PorosityMap
required
permeability_map PorosityMap
required
extra_cell_data PorosityMap
required
element_type PorosityMap
required
require_finite_cell_data bool

Passed to :func:structured_map_mesh.

 True
path str | Path

Destination mesh path. The file extension normally determines the meshio writer.

 required
file_format str | None

Optional meshio file-format override.

 None
Notes

Netgen .vol export is geometry-oriented in meshio. The writer does not preserve arbitrary floating-point cell-data arrays, so keep the HDF5 map export as the authoritative porosity/permeability field when using Netgen.

Source code in src/voids/mesh/structured.py 
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
def write_structured_map_mesh(
    porosity_map: PorosityMap,
    path: str | Path,
    *,
    permeability_map: PermeabilityMap | None = None,
    extra_cell_data: Mapping[str, np.ndarray] | None = None,
    element_type: MapMeshElement = "auto",
    file_format: str | None = None,
    require_finite_cell_data: bool = True,
) -> Path:
    """Write a structured map mesh with porosity/permeability cell data.

    Parameters
    ----------
    porosity_map, permeability_map, extra_cell_data, element_type,
    require_finite_cell_data :
        Passed to :func:`structured_map_mesh`.
    path :
        Destination mesh path. The file extension normally determines the meshio
        writer.
    file_format :
        Optional meshio file-format override.

    Notes
    -----
    Netgen ``.vol`` export is geometry-oriented in meshio. The writer does not
    preserve arbitrary floating-point cell-data arrays, so keep the HDF5 map
    export as the authoritative porosity/permeability field when using Netgen.
    """

    mesh = structured_map_mesh(
        porosity_map,
        permeability_map=permeability_map,
        extra_cell_data=extra_cell_data,
        element_type=element_type,
        require_finite_cell_data=require_finite_cell_data,
    )
    return mesh.write(path, file_format=file_format)

write_structured_map_meshes 

write_structured_map_meshes(
    porosity_map,
    output_dir,
    *,
    stem,
    permeability_map=None,
    formats=("gmsh", "vtk", "vtu", "netgen"),
    extra_cell_data=None,
    element_type="auto",
    require_finite_cell_data=True,
)

Write the same structured map mesh to several mesh formats.

Parameters:

Name Type Description Default
porosity_map PorosityMap
required
permeability_map PorosityMap
required
extra_cell_data PorosityMap
required
element_type PorosityMap
required
require_finite_cell_data bool

Passed to :func:structured_map_mesh.

 True
output_dir str | Path

Directory where mesh files will be written.

 required
stem str

Filename stem used for every exported file.

 required
formats Sequence[str]

Format labels. Supported labels are "gmsh", "vtk", "vtu", and "netgen". Aliases "msh" and "vol" are also accepted.

 ('gmsh', 'vtk', 'vtu', 'netgen')

Returns:

Type Description
dict[str, Path]

Mapping from the requested format label to the written mesh path.
Source code in src/voids/mesh/structured.py 
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
def write_structured_map_meshes(
    porosity_map: PorosityMap,
    output_dir: str | Path,
    *,
    stem: str,
    permeability_map: PermeabilityMap | None = None,
    formats: Sequence[str] = ("gmsh", "vtk", "vtu", "netgen"),
    extra_cell_data: Mapping[str, np.ndarray] | None = None,
    element_type: MapMeshElement = "auto",
    require_finite_cell_data: bool = True,
) -> dict[str, Path]:
    """Write the same structured map mesh to several mesh formats.

    Parameters
    ----------
    porosity_map, permeability_map, extra_cell_data, element_type,
    require_finite_cell_data :
        Passed to :func:`structured_map_mesh`.
    output_dir :
        Directory where mesh files will be written.
    stem :
        Filename stem used for every exported file.
    formats :
        Format labels. Supported labels are ``"gmsh"``, ``"vtk"``, ``"vtu"``,
        and ``"netgen"``. Aliases ``"msh"`` and ``"vol"`` are also accepted.

    Returns
    -------
    dict[str, pathlib.Path]
        Mapping from the requested format label to the written mesh path.
    """

    out = Path(output_dir)
    out.mkdir(parents=True, exist_ok=True)
    normalized_stem = str(stem).strip()
    if not normalized_stem:
        raise ValueError("stem must be a non-empty string")

    mesh = structured_map_mesh(
        porosity_map,
        permeability_map=permeability_map,
        extra_cell_data=extra_cell_data,
        element_type=element_type,
        require_finite_cell_data=require_finite_cell_data,
    )

    paths: dict[str, Path] = {}
    for fmt in formats:
        key = str(fmt).strip().lower().lstrip(".")
        extension = mesh_format_extension(key)
        path = out / f"{normalized_stem}{extension}"
        paths[key] = mesh.write(path)

    return paths