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.
The library is compatible with the DOLFINx nightly release, v0.10.0, and v0.9.0.
python3 -m pip install io4dolfinxFor specific backend requirements (like ADIOS2 or H5PY), see the Installation Guide.
Here is a minimal example of saving and loading a simulation state (Checkpointing).
frompathlibimportPathfrommpi4pyimportMPIimportdolfinximportio4dolfinx# 1. Create a mesh and functioncomm=MPI.COMM_WORLDmesh=dolfinx.mesh.create_unit_square(comm, 10, 10)
V=dolfinx.fem.functionspace(mesh, ("Lagrange", 1))
u=dolfinx.fem.Function(V)
u.interpolate(lambdax: x[0] +x[1])
u.name="my_function"# 2. Write checkpoint# The mesh must be written before the functionfilename=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")io4dolfinx supports custom user backends. You can switch backends by passing backend="name" to IO functions.
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
h5pybackend.
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.
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
vtkhdfbackend. - XDMF (eXtensible Model Data Format):
.xdmf. Thexdmfbackend supports theHDF5encoding, to ensure performance in parallel. - PyVista (IO backend is meshio): The pyvista backend uses {py:func}
pyvista.readto read in meshes, point data and cell data.pyvistarelies on meshio for most reading operations (including the XDMF ascii format).
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.
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.
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.
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.
Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests to us.
io4dolfinx includes a comprehensive test suite that ensures functionality across different backends and compatibility with legacy data formats, see the Testing Guide for details.
This project is licensed under the MIT License - see the LICENSE file for details.