io4dolfinx - A framework for reading and writing data to various mesh formats

io4dolfinx is an extension for DOLFINx that provides advanced input/output capabilities. It focuses on N-to-M checkpointing (writing data on N processors, reading on M processors) and supports reading/writing various mesh formats using interchangeable backends.

Installation

The library is compatible with the DOLFINx nightly release, v0.10.0, and v0.9.0.

python3 -m pip install io4dolfinx

For specific backend requirements (like ADIOS2 or H5PY), see the Installation Guide.

Quick Start

Here is a minimal example of saving and loading a simulation state (Checkpointing).

from pathlib import Path
from mpi4py import MPI
import dolfinx
import io4dolfinx

# 1. Create a mesh and function
comm = MPI.COMM_WORLD
mesh = dolfinx.mesh.create_unit_square(comm, 10, 10)
V = dolfinx.fem.functionspace(mesh, ("Lagrange", 1))
u = dolfinx.fem.Function(V)
u.interpolate(lambda x: x[0] + x[1])
u.name = "my_function"

# 2. Write checkpoint
# The mesh must be written before the function
filename = Path("checkpoint.bp")
io4dolfinx.write_mesh(filename, mesh)
io4dolfinx.write_function(filename, u, time=0.0)

# 3. Read checkpoint
# This works even if the number of MPI processes changes (N-to-M)
mesh_new = io4dolfinx.read_mesh(filename, comm)
V_new = dolfinx.fem.functionspace(mesh_new, ("Lagrange", 1))
u_new = dolfinx.fem.Function(V_new)
io4dolfinx.read_function(filename, u_new, time=0.0, name="my_function")

Features and Backends

io4dolfinx supports custom user backends. You can switch backends by passing backend="name" to IO functions.

Checkpointing (N-to-M)

Many finite element applications requires storage of functions that cannot be associated with the nodes or cells of the mesh. Therefore, we have implemented our own, native checkpointing format that supports N-to-M checkpointing (write data on N processors, read in on M) through the following backends:

• h5py: Requires HDF5 with MPI support to work, but can store, meshes, partitioning info, meshtags, function data and more.
• adios2: Requires ADIOS 2 compiled with MPI support and Python bindings. Supports the same set of operations as the h5py backend.

The code uses the ADIOS2/Python-wrappers and h5py module to write DOLFINx objects to file, supporting N-to-M (recoverable) and N-to-N (snapshot) checkpointing. See: Checkpointing in DOLFINx - FEniCS 23 or the examples in the Documentation for more information.

For scalability, the code uses MPI Neighbourhood collectives for communication across processes.

Mesh IO (Import/Export)

Most meshing formats supports associating data with the nodes of the mesh (the mesh can be higher order) and the cells of the mesh. The node data can be read in as P-th order Lagrange functions (where P is the order of the grid), while the cell data can be read in as piecewise constant (DG-0) functions.

• VTKHDF: The new scalable format from VTK, called VTKHDF is supported by the vtkhdf backend.
• XDMF (eXtensible Model Data Format): .xdmf. The xdmf backend supports the HDF5 encoding, to ensure performance in parallel.
• PyVista (IO backend is meshio): The pyvista backend uses {py:func}pyvista.read to read in meshes, point data and cell data. pyvista relies on meshio for most reading operations (including the XDMF ascii format).

Advanced Usage

The repository contains detailed documented examples in the docs folder:

• Reading and writing mesh checkpoints
• Storing mesh partitioning data (Avoid re-partitioning when restarting)
• Writing mesh-tags
• Writing function checkpoints
• Checkpoint on input mesh

For a full API reference and backend details, see the Documentation.

Legacy DOLFIN Support

io4dolfinx can read checkpoints created by the legacy version of DOLFIN (Lagrange or DG functions).

• Reading meshes from DOLFIN HDF5File-format.
• Reading checkpoints from DOLFIN HDF5File and XDMFFile.

Project Background

Relation to adios4dolfinx

This library is an evolution of adios4dolfinx. It includes all functionality of the original library but has been refactored to support multiple IO backends (not just ADIOS2), making it easier to interface with different meshing formats while keeping the library structure sane.

Statement of Need

As large-scale, long-running simulations on HPC clusters become more common, the need to store intermediate solutions is crucial. If a system crashes or a computational budget is exceeded, checkpoints allow the simulation to resume without restarting from scratch. io4dolfinx extends DOLFINx with this essential functionality.

Contributing

Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests to us.

Testing

io4dolfinx includes a comprehensive test suite that ensures functionality across different backends and compatibility with legacy data formats, see the Testing Guide for details.

LICENSE

This project is licensed under the MIT License - see the LICENSE file for details.