General concepts » Input, output, and visualization » XDMF format

Using the XDMF format for visualization and time series data.

Introduction

The eXtensible Data Model and Format (XDMF) is a data format designed for scientific computing. It uses a split-file architecture:

  • An XML file (.xdmf) that describes the structure of the data
  • One or more HDF5 files (.h5) that store the actual numerical data

This design combines human-readable metadata with efficient binary storage, with mesh and field data stored separately from their description. XDMF files can be directly opened in ParaView for visualization.

The XDMF class

The XDMF class provides a high-level interface for writing XDMF files. Output is organized by grids:

  1. Create an XDMF writer
  2. Associate a mesh with a named grid
  3. Add fields (scalar, vector, tensor) to the grid
  4. Write snapshots, optionally with time stamps

Basic usage

#include <Rodin/Geometry.h>
#include <Rodin/Variational.h>
#include <Rodin/IO/XDMF.h>

using namespace Rodin;
using namespace Rodin::Geometry;
using namespace Rodin::Variational;

int main()
{
  Mesh mesh;
  mesh = mesh.UniformGrid(Polytope::Type::Triangle, {16, 16});
  mesh.scale(1.0 / 15.0);

  P1 vh(mesh);
  GridFunction u(vh);
  u = [](const Geometry::Point& p) { return p.x() * p.y(); };

  IO::XDMF xdmf("MyOutput");
  xdmf.grid().setMesh(mesh).add("u", u);
  xdmf.write().flush();

  return 0;
}

This creates:

  • MyOutput.xdmf — XML metadata file (open this in ParaView)
  • MyOutput.mesh.h5 — HDF5 file containing the mesh data
  • MyOutput.u.000000.h5 — HDF5 file containing the field data

Working with grids

A grid in XDMF associates a mesh with named fields. The writer returns a handle to the default grid or to a grid selected by name.

IO::XDMF xdmf("Simulation");
auto grid = xdmf.grid();          // default grid name
auto domain = xdmf.grid("Domain");  // named grid

Setting the mesh

Each grid must have a mesh associated with it before writing.

auto grid = xdmf.grid();
grid.setMesh(mesh);

Adding fields

Fields are added using the add() method. The field can be a named GridFunction or provided with an explicit name.

// Option 1: Name the grid function and add it
GridFunction u(vh);
u.setName("velocity");
grid.add(u);

// Option 2: Provide a name when adding
grid.add("pressure", p);

Registration borrows the mesh and fields. Their spaces and coefficients must remain valid whenever a snapshot is written. After remeshing, construct the new spaces and register the current fields before the next write.

Static output

For a single snapshot, call write() without a time parameter.

IO::XDMF xdmf("StaticResult");
xdmf.grid().setMesh(mesh).add("solution", u);
xdmf.write().flush();

Time-dependent output

Call write(t).flush() after updating the registered fields to record a snapshot at time $t$ .

IO::XDMF xdmf("TimeEvolution");
auto grid = xdmf.grid();
grid.setMesh(mesh);
grid.add("u", u);

for (size_t k = 0; k < numSteps; ++k)
{
  Real t = k * dt;

  // Update your solution...
  u = [t](const Geometry::Point& p)
  {
    return std::sin(Math::Constants::pi() * p.x()) * std::exp(-t);
  };

  // Write snapshot at time t
  xdmf.write(t).flush();
}

ParaView's time controls step through the evolution of the solution.

Mesh policy

By default, the mesh is considered static (exported once). Set it before the output loop and keep its geometry and topology unchanged. Calling setMesh() again resets the grid's static-mesh export state. For a mesh that changes over time, configure the writer to export the mesh at each time step.

IO::XDMF xdmf("AdaptiveSim");
auto grid = xdmf.grid();
grid.setMesh(mesh, IO::XDMF::MeshPolicy::Transient);
grid.add(u);

Field types

XDMF supports different types of fields.

Scalar fields

Scalar fields have one component per node.

P1 vh(mesh);                 // scalar P1 space
GridFunction temperature(vh);
temperature = [](const Geometry::Point& p) { return p.x() + p.y(); };

grid.add("temperature", temperature);

Vector fields

Vector fields have multiple components per node. Create the finite element space with the number of components.

P1 vh(mesh, 2);              // 2D vector P1 space
GridFunction velocity(vh);
velocity = [](const Geometry::Point& p)
{
  return Math::Vector<Real>{{ -p.y(), p.x() }};
};

grid.add("velocity", velocity);

File patterns

The XDMF writer uses customizable file naming patterns. The default patterns are:

FileDefault PatternExample
XDMF XML{stem}.xdmfMyOutput.xdmf
Mesh HDF5{stem}.{grid}.mesh.h5MyOutput.mesh.h5
Field HDF5{stem}.{grid}.{name}.{index}.h5MyOutput.u.000000.h5

Available placeholders:

  • {stem} — The base name passed to the XDMF constructor
  • {grid} — The name of the grid
  • {name} — The name of the field
  • {index} — The time step index
  • {rank} — The MPI rank (for distributed output)

Opening files in ParaView

To visualize XDMF output in ParaView:

  1. Open ParaView
  2. Use File > Open and select the .xdmf file
  3. Click Apply in the Properties panel
  4. Select a field from the dropdown menu to colorize the mesh
  5. For time-dependent data, use the time controls at the top

Complete example

The Poisson tutorial derives the problem, solves it and exports the computed field.

The complete program is available in Poisson.cpp.

See also