io4dolfinx 1.1.0__tar.gz

io4dolfinx-1.1.0/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2023 Jørgen S. Dokken, Henrik N.T. Finsberg and Simula Research Laboratory
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

io4dolfinx-1.1.0/PKG-INFO

@@ -0,0 +1,158 @@
+Metadata-Version: 2.4
+Name: io4dolfinx
+Version: 1.1.0
+Summary: Checkpointing functionality for DOLFINx meshes/functions with ADIOS2
+Author-email: "Jørgen S. Dokken" <dokken@simula.no>, "Henrik N.T. Finsberg" <henriknf@simula.no>
+License: Copyright 2023 Jørgen S. Dokken, Henrik N.T. Finsberg and Simula Research Laboratory
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+        
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fenics-dolfinx>=0.10.0
+Requires-Dist: packaging
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: coverage; extra == "test"
+Requires-Dist: ipyparallel; extra == "test"
+Requires-Dist: io4dolfinx[h5py]; extra == "test"
+Requires-Dist: io4dolfinx[pyvista]; extra == "test"
+Requires-Dist: io4dolfinx[xdmf]; extra == "test"
+Provides-Extra: dev
+Requires-Dist: pdbpp; extra == "dev"
+Requires-Dist: ipython; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Provides-Extra: h5py
+Requires-Dist: h5py; extra == "h5py"
+Provides-Extra: pyvista
+Requires-Dist: pyvista; extra == "pyvista"
+Provides-Extra: xdmf
+Requires-Dist: h5py; extra == "xdmf"
+Provides-Extra: docs
+Requires-Dist: jupyter-book<2.0.0; extra == "docs"
+Requires-Dist: ipyparallel; extra == "docs"
+Requires-Dist: ipywidgets; extra == "docs"
+Requires-Dist: jupytext; extra == "docs"
+Requires-Dist: ipykernel<7.0.0; extra == "docs"
+Requires-Dist: sphinx-codeautolink; extra == "docs"
+Requires-Dist: io4dolfinx[h5py]; extra == "docs"
+Requires-Dist: sphinx_external_toc<1.1.0; extra == "docs"
+Provides-Extra: all
+Requires-Dist: io4dolfinx[dev,docs,test]; extra == "all"
+Dynamic: license-file
+
+# io4dolfinx - A framework for reading and writing data to various mesh formats
+
+**io4dolfinx** is an extension for [DOLFINx](https://github.com/FEniCS/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.
+
+```bash
+python3 -m pip install io4dolfinx
+```
+
+For specific backend requirements (like ADIOS2 or H5PY), see the [Installation Guide](./docs/installation.md).
+
+
+## Quick Start
+
+Here is a minimal example of saving and loading a simulation state (Checkpointing).
+
+```python
+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](./docs/backends/h5py.rst): Requires HDF5 with MPI support to work, but can store, meshes, partitioning info, meshtags, function data and more.
+- [adios2](./docs/backends/adios2.rst): Requires [ADIOS 2](https://adios2.readthedocs.io/en/latest/) 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](https://jsdokken.com/checkpointing-presentation/#/) or the examples in the [Documentation](https://jsdokken.com/io4dolfinx/) for more information.
+
+For scalability, the code uses [MPI Neighbourhood collectives](https://www.mpi-forum.org/docs/mpi-3.1/mpi31-report/node200.htm) 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](./docs/backends/vtkhdf.rst): The new scalable format from VTK, called [VTKHDF](https://docs.vtk.org/en/latest/vtk_file_formats/vtkhdf_file_format/index.html) is supported by the `vtkhdf` backend. 
+- [XDMF](./docs/backends/xdmf.rst) (eXtensible Model Data Format): `.xdmf`. The `xdmf` backend supports the `HDF5` encoding, to ensure performance in parallel.
+- [PyVista](./docs/backends/pyvista.rst) (IO backend is meshio): The [pyvista](https://pyvista.org/) backend uses {py:func}`pyvista.read` to read in meshes, point data and cell data. `pyvista` relies on [meshio](https://github.com/nschloe/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](./docs/writing_mesh_checkpoint.py)
+* [Storing mesh partitioning data](./docs/partitioned_mesh.py) (Avoid re-partitioning when restarting)
+* [Writing mesh-tags](./docs/meshtags.py)
+* [Writing function checkpoints](./docs/writing_functions_checkpoint.py)
+* [Checkpoint on input mesh](./docs/original_checkpoint.py)
+
+For a full API reference and backend details, see the [Documentation](https://jsdokken.com/io4dolfinx/).
+
+### 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](https://doi.org/10.21105/joss.06451). 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](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](./docs/testing.md) for details.
+
+
+## LICENSE
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

io4dolfinx-1.1.0/README.md

@@ -0,0 +1,110 @@
+# io4dolfinx - A framework for reading and writing data to various mesh formats
+
+**io4dolfinx** is an extension for [DOLFINx](https://github.com/FEniCS/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.
+
+```bash
+python3 -m pip install io4dolfinx
+```
+
+For specific backend requirements (like ADIOS2 or H5PY), see the [Installation Guide](./docs/installation.md).
+
+
+## Quick Start
+
+Here is a minimal example of saving and loading a simulation state (Checkpointing).
+
+```python
+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](./docs/backends/h5py.rst): Requires HDF5 with MPI support to work, but can store, meshes, partitioning info, meshtags, function data and more.
+- [adios2](./docs/backends/adios2.rst): Requires [ADIOS 2](https://adios2.readthedocs.io/en/latest/) 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](https://jsdokken.com/checkpointing-presentation/#/) or the examples in the [Documentation](https://jsdokken.com/io4dolfinx/) for more information.
+
+For scalability, the code uses [MPI Neighbourhood collectives](https://www.mpi-forum.org/docs/mpi-3.1/mpi31-report/node200.htm) 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](./docs/backends/vtkhdf.rst): The new scalable format from VTK, called [VTKHDF](https://docs.vtk.org/en/latest/vtk_file_formats/vtkhdf_file_format/index.html) is supported by the `vtkhdf` backend. 
+- [XDMF](./docs/backends/xdmf.rst) (eXtensible Model Data Format): `.xdmf`. The `xdmf` backend supports the `HDF5` encoding, to ensure performance in parallel.
+- [PyVista](./docs/backends/pyvista.rst) (IO backend is meshio): The [pyvista](https://pyvista.org/) backend uses {py:func}`pyvista.read` to read in meshes, point data and cell data. `pyvista` relies on [meshio](https://github.com/nschloe/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](./docs/writing_mesh_checkpoint.py)
+* [Storing mesh partitioning data](./docs/partitioned_mesh.py) (Avoid re-partitioning when restarting)
+* [Writing mesh-tags](./docs/meshtags.py)
+* [Writing function checkpoints](./docs/writing_functions_checkpoint.py)
+* [Checkpoint on input mesh](./docs/original_checkpoint.py)
+
+For a full API reference and backend details, see the [Documentation](https://jsdokken.com/io4dolfinx/).
+
+### 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](https://doi.org/10.21105/joss.06451). 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](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](./docs/testing.md) for details.
+
+
+## LICENSE
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

io4dolfinx-1.1.0/pyproject.toml

@@ -0,0 +1,107 @@
+[build-system] # Require setuptool version due to https://github.com/pypa/setuptools/issues/2938
+requires = ["setuptools>=61.0.0", "wheel"]
+
+[project]
+name = "io4dolfinx"
+version = "1.1.0"
+description = "Checkpointing functionality for DOLFINx meshes/functions with ADIOS2"
+authors = [
+    { name = "Jørgen S. Dokken", email = "dokken@simula.no" }, 
+    { name = "Henrik N.T. Finsberg", email = "henriknf@simula.no" }
+]
+license = { file = "LICENSE" }
+readme = "README.md"
+dependencies = ["fenics-dolfinx>=0.10.0", "packaging"]
+
+[project.optional-dependencies]
+test = [
+    "pytest", 
+    "coverage", 
+    "ipyparallel", 
+    "io4dolfinx[h5py]", 
+    "io4dolfinx[pyvista]", 
+    "io4dolfinx[xdmf]"
+]
+dev = ["pdbpp", "ipython", "mypy", "ruff"]
+h5py = ["h5py"]
+pyvista = ["pyvista"]
+xdmf = ["h5py"]
+docs = [
+    "jupyter-book<2.0.0",
+    "ipyparallel",
+    "ipywidgets",
+    "jupytext",
+    "ipykernel<7.0.0",     # Note: Remove once https://github.com/ipython/ipykernel/issues/1450 is in a release
+    "sphinx-codeautolink",
+    "io4dolfinx[h5py]",
+    "sphinx_external_toc<1.1.0",
+]
+all = ["io4dolfinx[test,dev,docs]"]
+
+[tool.pytest.ini_options]
+addopts = ["--import-mode=importlib"]
+testpaths = ["tests"]
+
+[tool.mypy]
+ignore_missing_imports = true
+# Folders to exclude
+exclude = ["docs/", "build/"]
+# Folder to check with mypy
+files = ["src", "tests"]
+
+[tool.ruff]
+src = ["src", "tests", "docs"]
+line-length = 100
+indent-width = 4
+
+[tool.ruff.lint]
+select = [
+    # Pyflakes
+    "F",
+    # Pycodestyle
+    "E",
+    "W",
+    # isort
+    "I001",
+]
+
+
+[tool.ruff.lint.isort]
+known-first-party = ["io4dolfinx"]
+known-third-party = [
+    "basix",
+    "dolfinx",
+    "ffcx",
+    "ufl",
+    "gmsh",
+    "numpy",
+    "pytest",
+]
+section-order = [
+    "future",
+    "standard-library",
+    "mpi",
+    "third-party",
+    "first-party",
+    "local-folder",
+]
+
+[tool.ruff.lint.isort.sections]
+"mpi" = ["mpi4py", "petsc4py"]
+
+
+[tool.bumpversion]
+allow_dirty = false
+commit = true
+message = "Bump version: {current_version} → {new_version}"
+tag = true
+sign_tags = false
+tag_name = "v{new_version}"
+tag_message = "Bump version: {current_version} → {new_version}"
+current_version = "1.1.0"
+
+
+[[tool.bumpversion.files]]
+filename = "pyproject.toml"
+search = 'version = "{current_version}"'
+replace = 'version = "{new_version}"'

io4dolfinx-1.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

io4dolfinx-1.1.0/src/io4dolfinx/__init__.py

@@ -0,0 +1,65 @@
+# Copyright (C) 2023 Jørgen Schartum Dokken
+#
+# This file is part of io4dolfinx
+#
+# SPDX-License-Identifier:    MIT
+
+"""Top-level package for ADIOS2Wrappers."""
+
+from importlib.metadata import metadata
+
+from .backends import FileMode, get_backend
+from .checkpointing import (
+    read_attributes,
+    read_function,
+    read_function_names,
+    read_mesh,
+    read_meshtags,
+    read_timestamps,
+    write_attributes,
+    write_cell_data,
+    write_function,
+    write_mesh,
+    write_meshtags,
+    write_point_data,
+)
+from .original_checkpoint import write_function_on_input_mesh, write_mesh_input_order
+from .readers import (
+    read_cell_data,
+    read_function_from_legacy_h5,
+    read_mesh_from_legacy_h5,
+    read_point_data,
+)
+from .snapshot import snapshot_checkpoint
+
+meta = metadata("io4dolfinx")
+__version__ = meta["Version"]
+__author__ = meta.get("Author", "")
+__license__ = meta["License"]
+__email__ = meta["Author-email"]
+__program_name__ = meta["Name"]
+
+__all__ = [
+    "FileMode",
+    "write_meshtags",
+    "read_meshtags",
+    "read_cell_data",
+    "read_mesh",
+    "write_mesh",
+    "read_function_from_legacy_h5",
+    "read_mesh_from_legacy_h5",
+    "write_function",
+    "read_function",
+    "snapshot_checkpoint",
+    "write_function_on_input_mesh",
+    "write_mesh_input_order",
+    "write_attributes",
+    "write_data",
+    "read_attributes",
+    "read_function_names",
+    "read_point_data",
+    "read_timestamps",
+    "get_backend",
+    "write_cell_data",
+    "write_point_data",
+]