Rodin::IO module

Reading and writing meshes, fields, and associated data.

MeshLoader and MeshPrinter import and export meshes; GridFunctionLoader and GridFunctionPrinter transfer discrete fields. Format-specific backends support MFEM, MEDIT, and HDF5 data, while XDMF writes meshes, multiple fields, and time series for visualization.

Supported mesh and field formats include:

Additionally, the XDMF class provides XDMF 3.0 output for scientific visualization in ParaView, supporting time series and multiple fields.

XDMF Architecture

The XDMF writer uses a two-level design:

  • XDMF — Top-level writer that manages the .xdmf XML file and .h5 HDF5 data. Provides write(), flush(), close(), setPadding().
  • XDMF::Grid — A lightweight handle returned by xdmf.grid() (default) or xdmf.grid("name") (named). Provides setMesh(), add(), hasMesh(), reset() — all returning Grid& for method chaining.
IO::XDMF xdmf("output");
xdmf.grid().setMesh(mesh).add("u", u.getSolution());
xdmf.write();

For MPI-distributed I/O, pass the communicator:

IO::XDMF xdmf("distributed_output", MPI_COMM_WORLD);

File Format Summary

FormatExtensionsKey ClassesNotes
MFEM.mesh, .gfIO::FileFormat::MFEMText-based, compatible with MFEM ecosystem
MEDIT.meshIO::FileFormat::MEDITUsed by MMG, supports attributes
HDF5.h5IO::FileFormat::HDF5Binary, parallel-capable
XDMF.xdmf + .h5IO::XDMF, IO::XDMF::GridParaView visualization, time series

Namespaces

namespace HDF5
HDF5 utility namespace providing type aliases, path constants, RAII handle wrappers, and low-level dataset read/write helpers.
namespace Internal
Internal helpers for PETSc HDF5 serialization primitives.

Classes

template<class T>
class Loader
Base template for loading objects from files or streams.
template<class T>
class Printer
Base template for printing objects to streams.
template<FileFormat Fmt, class Trait>
class MeshLoader
Loader template for meshes with specific file format and context.
See specializations
SpecializationDescription
FileFormat::HDF5, Context::Local
Full specialization
template <>
class MeshLoader<
  FileFormat::HDF5,
  Context::Local>;
HDF5 mesh loader specialization for local (sequential) meshes.
IO::FileFormat::MEDIT, Context::Local
Full specialization
template <>
class MeshLoader<
  IO::FileFormat::MEDIT,
  Context::Local>;
Specialization for loading Sequential meshes in the MEDIT file format.
IO::FileFormat::MFEM, Context::Local
Full specialization
template <>
class MeshLoader<
  IO::FileFormat::MFEM,
  Context::Local>;
Specialization for loading sequential meshes in MFEM format.
FileFormat::HDF5, Context::MPI
Full specialization
template <>
class MeshLoader<
  FileFormat::HDF5,
  Context::MPI>;
Loads a distributed MPI mesh from an HDF5 file.
template<FileFormat Fmt, class Trait>
class MeshPrinter
Printer template for meshes with specific file format and context.
See specializations
SpecializationDescription
FileFormat::HDF5, Context::Local
Full specialization
template <>
class MeshPrinter<
  FileFormat::HDF5,
  Context::Local>;
HDF5 mesh printer specialization for local (sequential) meshes.
FileFormat::MEDIT, Context::Local
Full specialization
template <>
class MeshPrinter<
  FileFormat::MEDIT,
  Context::Local>;
MEDIT mesh printer for local meshes.
FileFormat::MFEM, Context::Local
Full specialization
template <>
class MeshPrinter<
  FileFormat::MFEM,
  Context::Local>;
Specialization for printing sequential meshes in MFEM format.
FileFormat::HDF5, Context::MPI
Full specialization
template <>
class MeshPrinter<
  FileFormat::HDF5,
  Context::MPI>;
Prints a distributed MPI mesh to an HDF5 file.
template<FileFormat Fmt, class FES, class Data>
class GridFunctionLoader
Loader template for grid functions with specific file format.
See specializations
SpecializationDescription
FileFormat::HDF5, FES, Math::Vector<Scalar>
Full specialization
template <
  class FES,
  class Scalar>
class GridFunctionLoader<
  FileFormat::HDF5,
  FES,
  Math::Vector< Scalar >>;
HDF5 grid function loader for local grid functions backed by Math::Vector<Scalar>.
FileFormat::MEDIT, Variational::P1<Range, …>, Math::Vector<…>
Full specialization
template <
  class Range>
requires (!FormLanguage::IsMatrixRange<Range>::Value)
class GridFunctionLoader<
  FileFormat::MEDIT,
  Variational::P1< Range, Geometry::Mesh< Context::Local > >,
  Math::Vector< typename FormLanguage::Traits< Range >::ScalarType >>;
MEDIT grid-function loader for local P1 finite element spaces.
FileFormat::MEDIT, Variational::H1<K, …>, Math::Vector<…>
Full specialization
template <
  size_t K,
  class Range>
requires (!FormLanguage::IsMatrixRange<Range>::Value)
class GridFunctionLoader<
  FileFormat::MEDIT,
  Variational::H1< K, Range, Geometry::Mesh< Context::Local > >,
  Math::Vector< typename FormLanguage::Traits< Range >::ScalarType >>;
MEDIT grid-function loader for local H1 finite element spaces.
FileFormat::MEDIT, FES, Math::Vector<…>
Full specialization
template <
  class FES>
requires ( FormLanguage::IsMatrixRange<typename FormLanguage::Traits<FES>::RangeType>::Value)
class GridFunctionLoader<
  FileFormat::MEDIT,
  FES,
  Math::Vector< typename FormLanguage::Traits< FES >::ScalarType >>;
Reads matrix entries stored as independent MEDIT scalar vertex fields. Higher-order spaces interpolate the vertex field, as required by SolAtVertices.
FileFormat::MFEM, Variational::P1<Range, …>, Math::Vector<…>
Full specialization
template <
  class Range>
requires (!FormLanguage::IsMatrixRange<Range>::Value)
class GridFunctionLoader<
  FileFormat::MFEM,
  Variational::P1< Range, Geometry::Mesh< Context::Local > >,
  Math::Vector< typename FormLanguage::Traits< Range >::ScalarType >>;
Specialization for loading P1 grid functions from MFEM format.
FileFormat::MFEM, Variational::H1<K, …>, Math::Vector<…>
Full specialization
template <
  size_t K,
  class Range>
requires (!FormLanguage::IsMatrixRange<Range>::Value)
class GridFunctionLoader<
  FileFormat::MFEM,
  Variational::H1< K, Range, Geometry::Mesh< Context::Local > >,
  Math::Vector< typename FormLanguage::Traits< Range >::ScalarType >>;
Specialization for loading H1 grid functions from MFEM format.
FileFormat::MFEM, Variational::P0<Range, …>, Math::Vector<…>
Full specialization
template <
  class Range>
requires (!FormLanguage::IsMatrixRange<Range>::Value)
class GridFunctionLoader<
  FileFormat::MFEM,
  Variational::P0< Range, Geometry::Mesh< Context::Local > >,
  Math::Vector< typename FormLanguage::Traits< Range >::ScalarType >>;
Loader for P0 (piecewise constant) grid functions in MFEM format.
FileFormat::MFEM, FES, Math::Vector<Scalar>
Full specialization
template <
  class FES,
  class Scalar>
requires ( FormLanguage::IsMatrixRange<typename FormLanguage::Traits<FES>::RangeType>::Value)
class GridFunctionLoader<
  FileFormat::MFEM,
  FES,
  Math::Vector< Scalar >>;
Loads each MFEM component through the scalar family's node mapping.
FileFormat::HDF5, FES, ::Vec
Full specialization
template <
  class FES>
class GridFunctionLoader<
  FileFormat::HDF5,
  FES,
  ::Vec>;
HDF5 loader for PETSc-backed grid functions.
template<FileFormat Fmt, class FES, class Data>
class GridFunctionPrinter
Printer template for grid functions with specific file format.
See specializations
SpecializationDescription
FileFormat::HDF5, FES, Math::Vector<Scalar>
Full specialization
template <
  class FES,
  class Scalar>
class GridFunctionPrinter<
  FileFormat::HDF5,
  FES,
  Math::Vector< Scalar >> final;
HDF5 grid function printer for local grid functions backed by Math::Vector<Scalar>.
FileFormat::MEDIT, FES, Math::Vector<…>
Full specialization
template <
  class FES>
class GridFunctionPrinter<
  FileFormat::MEDIT,
  FES,
  Math::Vector< typename FormLanguage::Traits< FES >::ScalarType >>;
MEDIT grid-function printer for vector-backed grid functions.
FileFormat::MFEM, FES, Math::Vector<Scalar>
Full specialization
template <
  class FES,
  class Scalar>
requires ( !FormLanguage::IsMatrixRange<typename FormLanguage::Traits<FES>::RangeType>::Value)
class GridFunctionPrinter<
  FileFormat::MFEM,
  FES,
  Math::Vector< Scalar >> final;
Final specialization for printing grid functions with vector data in MFEM format.
FileFormat::MFEM, Variational::H1<K, …>, Math::Vector<Scalar>
Full specialization
template <
  size_t K,
  class Range,
  class Scalar>
requires (!FormLanguage::IsMatrixRange<Range>::Value)
class GridFunctionPrinter<
  FileFormat::MFEM,
  Variational::H1< K, Range, Geometry::Mesh< Context::Local > >,
  Math::Vector< Scalar >> final;
Specialization for printing H1 grid functions with vector data in MFEM format.
FileFormat::HDF5, FES, ::Vec
Full specialization
template <
  class FES>
class GridFunctionPrinter<
  FileFormat::HDF5,
  FES,
  ::Vec> final;
HDF5 printer for PETSc-backed grid functions.
FileFormat::MEDIT, FES, ::Vec
Full specialization
template <
  class FES>
class GridFunctionPrinter<
  FileFormat::MEDIT,
  FES,
  ::Vec> final;
MEDIT printer for PETSc-backed grid functions.
FileFormat::MFEM, FES, ::Vec
Full specialization
template <
  class FES>
requires requires(GridFunctionPrinterBase<FileFormat::MFEM, FES, ::Vec>& printer, std::ostream& stream) { printer.printData(stream); }
class GridFunctionPrinter<
  FileFormat::MFEM,
  FES,
  ::Vec> final;
PETSc storage adapter for supported MFEM finite element collections.
template<class FES, class Data>
class GridFunctionLoaderBase
Base class for concrete grid function loaders.
template<FileFormat Fmt, class FES, class Data>
class GridFunctionPrinterBase
Base class for concrete grid function printers.
See specializations
SpecializationDescription
FileFormat::MEDIT, FES, Data
Full specialization
template <
  class FES,
  class Data>
class GridFunctionPrinterBase<
  FileFormat::MEDIT,
  FES,
  Data>;
Base class for MEDIT grid-function printers.
FileFormat::MFEM, Variational::P0<Range, …>, Data
Full specialization
template <
  class Range,
  class Context,
  class Data>
class GridFunctionPrinterBase<
  FileFormat::MFEM,
  Variational::P0< Range, Geometry::Mesh< Context > >,
  Data>;
Base class for printing P0 (piecewise constant) grid functions in MFEM format.
FileFormat::MFEM, Variational::P1<Range, …>, Data
Full specialization
template <
  class Range,
  class Context,
  class Data>
class GridFunctionPrinterBase<
  FileFormat::MFEM,
  Variational::P1< Range, Geometry::Mesh< Context > >,
  Data>;
Base class for printing P1 (continuous Lagrange) grid functions in MFEM format.
FileFormat::MFEM, Variational::H1<K, …>, Data
Full specialization
template <
  size_t K,
  class Range,
  class Context,
  class Data>
class GridFunctionPrinterBase<
  FileFormat::MFEM,
  Variational::H1< K, Range, Geometry::Mesh< Context > >,
  Data>;
Base class for printing H1 (continuous Lagrange) grid functions in MFEM format.
template<class Context>
class MeshLoaderBase
Base class for loading meshes from files or streams.
template<class Context>
class MeshPrinterBase
Base class for printing meshes to streams or files.
class XDMF
XDMF domain writer for static or transient visualization output.

Enums

enum class FileFormat { MFEM, MEDIT, HDF5 }
Enumeration of supported file formats for mesh and grid function I/O.

Typedefs

template<size_t K, class Range>
using MFEM_H1_PETSc_Local_Printer = GridFunctionPrinter<FileFormat::MFEM, Variational::H1<K, Range, Geometry::Mesh<Context::Local>>, ::Vec>
Local PETSc-backed H1 MFEM printer.
template<size_t K, class Range>
using MFEM_H1_PETSc_MPI_Printer = GridFunctionPrinter<FileFormat::MFEM, Variational::H1<K, Range, Geometry::Mesh<Context::MPI>>, ::Vec>
MPI PETSc-backed H1 MFEM printer.

Functions

auto toCharString(FileFormat fmt) -> const char* constexpr
Converts a FileFormat enum value to its string representation.
auto operator<<(std::ostream& os, FileFormat fmt) -> std::ostream&
Stream output operator for FileFormat enum.
static auto escapeXML(const std::string& value) -> std::string
Escapes XML text and attribute values without changing filesystem names.
static auto padIndex(size_t index, size_t width) -> std::string
Formats an index with leading zeros.
static auto makeRankSuffix(const std::string& rank) -> std::string
Formats the optional MPI rank suffix.
expandPattern
Expands XDMF filename placeholders and normalizes separators.
See declaration
static auto expandPattern(const std::string& pattern, const std::string& stem, const std::string& grid, const std::string& name, const std::string& index, const std::string& rank = "") -> std::string
static void writeXMLHeader(std::ostream& os)
Writes the XDMF XML declaration and root opening tag.
static void writeXMLFooter(std::ostream& os)
Writes the XDMF root closing tag.
static auto indent(size_t level) -> std::string
Constructs indentation for an XML nesting level.
static auto getGeometryType(size_t sdim) -> const char*
Selects the XDMF coordinate-layout name.
static auto makeGridPieceName(const std::string& gridName, size_t rank) -> std::string
Constructs a grid-piece name for an MPI rank.

Enum documentation

enum class Rodin::IO::FileFormat

Enumeration of supported file formats for mesh and grid function I/O.

This enum identifies the different file formats that can be used for reading and writing meshes and grid functions in Rodin.

Enumerators
MFEM

MFEM mesh format - native format for MFEM library.
MEDIT

MEDIT mesh format - used by MMG remeshing software.
HDF5

HDF5 hierarchical binary format for raw mesh/function storage.

Typedef documentation

template<size_t K, class Range>
using MFEM_H1_PETSc_Local_Printer = GridFunctionPrinter<FileFormat::MFEM, Variational::H1<K, Range, Geometry::Mesh<Context::Local>>, ::Vec>

Defined in Rodin/PETSc/IO/MFEM.h

Local PETSc-backed H1 MFEM printer.

template<size_t K, class Range>
using MFEM_H1_PETSc_MPI_Printer = GridFunctionPrinter<FileFormat::MFEM, Variational::H1<K, Range, Geometry::Mesh<Context::MPI>>, ::Vec>

Defined in Rodin/PETSc/IO/MFEM.h

MPI PETSc-backed H1 MFEM printer.

Function documentation

const char* toCharString(FileFormat fmt) constexpr

Converts a FileFormat enum value to its string representation.

Parameters
fmt in File format enum value
Returns C-style string name of the format, or nullptr if invalid

Example

const char* name = toCharString(FileFormat::MFEM);  // Returns "MFEM"

std::ostream& operator<<(std::ostream& os, FileFormat fmt)

Stream output operator for FileFormat enum.

Parameters
os in/out Output stream
fmt in File format to output
Returns Reference to the output stream

Writes the name of a known file format, or the numeric value of an unrecognized format. Numeric fallback preserves diagnostics without inserting a null string into the stream.

Example

std::cout << FileFormat::MEDIT;  // Outputs "MEDIT"

static std::string escapeXML(const std::string& value)

Escapes XML text and attribute values without changing filesystem names.

Parameters
value Unescaped UTF-8 name or HDF5 filename.
Returns XML representation preserving the original decoded string.

static std::string padIndex(size_t index, size_t width)

Formats an index with leading zeros.

Parameters
index Degree-of-freedom index.
width Minimum number of decimal digits.
Returns Decimal index padded to at least the requested width.

static std::string makeRankSuffix(const std::string& rank)

Formats the optional MPI rank suffix.

Parameters
rank Rank identifier; an empty string omits the rank suffix.
Returns An empty string for an empty rank, otherwise the rank prefixed by .r.

static std::string expandPattern(const std::string& pattern, const std::string& stem, const std::string& grid, const std::string& name, const std::string& index, const std::string& rank = "")

Expands XDMF filename placeholders and normalizes separators.

Parameters
pattern Filename pattern containing named placeholders.
stem Value replacing the stem placeholder.
grid Value replacing the grid placeholder.
name Value replacing the name placeholder.
index Value replacing the index placeholder.
rank Rank identifier; an empty string omits the rank suffix.
Returns Expanded filename with separators introduced by empty placeholders normalized.

static void writeXMLHeader(std::ostream& os)

Writes the XDMF XML declaration and root opening tag.

Parameters
os Output stream receiving the formatted data.

static void writeXMLFooter(std::ostream& os)

Writes the XDMF root closing tag.

Parameters
os Output stream receiving the formatted data.

static std::string indent(size_t level)

Constructs indentation for an XML nesting level.

Parameters
level Indentation level, with two spaces per level.
Returns A string containing two spaces per nesting level.

static const char* getGeometryType(size_t sdim)

Selects the XDMF coordinate-layout name.

Parameters
sdim Spatial coordinate dimension, from one to three.
Returns X, XY, or XYZ for spatial dimensions one, two, or three.

static std::string makeGridPieceName(const std::string& gridName, size_t rank)

Constructs a grid-piece name for an MPI rank.

Parameters
gridName Grid name, possibly empty.
rank MPI rank identifying the grid piece.
Returns Grid name followed by _r and the rank, or r and the rank when the grid name is empty.