1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
|
# Reading Legacy DOLFIN Data
`io4dolfinx` provides functionality to read meshes and functions created with the
legacy version of DOLFIN (often referred to as "Old FEniCS"). This allows users to
migrate data from older simulations to DOLFINx.
## Supported Formats
The library supports reading data stored in the **HDF5** format used by legacy DOLFIN.
This includes:
* Meshes stored using `dolfin.HDF5File`.
* Functions stored using `dolfin.HDF5File`.
* Checkpoints stored using `dolfin.XDMFFile` (which produces an `.h5` file alongside the `.xdmf` file).
**Note:** The `.xml` or `.xml.gz` formats are not supported. You must convert these to
HDF5 using legacy DOLFIN before reading them with `io4dolfinx`.
## Reading Meshes
To read a mesh, you must know the **group name** where the mesh is stored within the HDF5 file.
In legacy DOLFIN, this was often `/mesh` or the name you provided to the write function.
```python
from mpi4py import MPI
import io4dolfinx
```
```python
comm = MPI.COMM_WORLD
filename = "legacy_mesh.h5"
```
### Read the mesh
Here 'group' is the path to the mesh inside the HDF5 file (e.g., "/mesh")
```python
mesh = io4dolfinx.read_mesh_from_legacy_h5(
filename=filename,
comm=comm,
group="/mesh",
)
```
```python
print(f"Read mesh with topology dimension: {mesh.topology.dim}")
```
## Reading Functions
Reading a function requires you to first create a compatible **FunctionSpace** and **Function** in DOLFINx.
The data is then read from the file and loaded into this function.
### Simple Function Read
If the function was saved directly using `HDF5File.write(u, "name")`:
```python
import dolfinx
import io4dolfinx
from mpi4py import MPI
```
#### Read the mesh first
```python
comm = MPI.COMM_WORLD
filename = "legacy_data.h5"
mesh = io4dolfinx.read_mesh_from_legacy_h5(filename, comm, group="/mesh")
```
#### Create the appropriate FunctionSpace
You must know the element family and degree used in the legacy simulation
```python
V = dolfinx.fem.functionspace(mesh, ("Lagrange", 1))
```
#### Create the function to hold the data
```python
u = dolfinx.fem.Function(V)
```
#### Read the data
Here 'group' corresponds to the name given when writing in legacy DOLFIN
```python
io4dolfinx.read_function_from_legacy_h5(filename=filename, comm=comm, u=u, group="v")
```
### Reading from XDMF Checkpoints
If the data was saved using `XDMFFile.write_checkpoint`, the HDF5 structure is slightly different (often containing time steps). You can specify the `step` argument to read a specific snapshot.
Assuming mesh and function space V are already created as above
```python
u_checkpoint = dolfinx.fem.Function(V)
```
Read the first time step (step=0). Note that the filename should be the .h5 file generated by the XDMFFile
```python
io4dolfinx.read_function_from_legacy_h5(
filename="checkpoint.h5",
comm=comm,
u=u_checkpoint,
group="v", # The name of the function in the checkpoint
step=0,
)
```
## Reading Vector Functions
Vector functions are read in the same way, provided the `FunctionSpace` is initialized correctly with the vector shape.
```python
W = dolfinx.fem.functionspace(mesh, ("Lagrange", 1, (mesh.geometry.dim,)))
w = dolfinx.fem.Function(W)
```
```python
io4dolfinx.read_function_from_legacy_h5(
filename="legacy_vector.h5", comm=comm, u=w, group="velocity_function"
)
```
## Limitations
* **Function Types:** Only `Lagrange` (Continuous Galerkin) and `DG` (Discontinuous Galerkin)
functions are supported.
* **One Checkpoint per File:** The legacy reader generally expects one checkpoint series per file
structure for XDMF checkpoints.
* **Backends:** The default backend is `adios2`. Ensure you have an MPI-enabled build of HDF5
if using the `h5py` backend explicitly.
|
