ADIOS2-backend

The library depends on the Python-interface of [DOLFINx]() and an MPI-build of [ADIOS2](https://adios2.readthedocs.io/en/latest/setting_up/setting_up.html#as-package). Therefore ADIOS2 should not be install through PYPI/pip, but has to be installed through Conda, Spack or from source.

Important

ADIOS2<2.10.2 does not work properly with numpy>=2.0.0. Everyone is advised to use the newest version of ADIOS2. This is for instance available through conda or the ghcr.io/fenics/dolfinx/dolfinx:nightly Docker-image.

io4dolfinx.backends.adios2.backend.get_default_backend_args(arguments: dict[str, Any] | None) → dict[str, Any]

Get default arguements (sets engine to BP4).

io4dolfinx.backends.adios2.backend.mesh_prefix(backend_args: dict[str, Any] | None) → str

ADIOS2 variable-name prefix for the mesh named in backend_args.

The default mesh gets an empty prefix, so that it is stored under exactly the names used before checkpoints could hold more than one mesh. Files written by earlier versions therefore stay readable, and a file holding only the default mesh stays readable by them. Any other mesh is namespaced under "<name>/".

Note

This is io4dolfinx’s own checkpoint schema, not ADIOS2’s VTX visualization schema – no vtk.xml attribute is written, and these files are not readable by ParaView’s VTX reader whether they hold one mesh or several. VTX supports only a single mesh per file, so holding several here costs nothing that was ever available. For a visualizable file with several meshes use the vtkhdf backend, whose MultiBlockDataSet is designed for it.

Parameters:

backend_args – Arguments to backend

Returns:

The prefix to prepend to every variable and attribute name of that mesh.

io4dolfinx.backends.adios2.backend.read_attributes(filename: Path | str, comm: Comm, name: str, backend_args: dict[str, Any] | None = None) → dict[str, ndarray]

Read attributes from file using ADIOS2.

Parameters:

• filename – Path to file to read from

• comm – MPI communicator used in storage

• name – Name of the attributes

• engine – ADIOS2 engine to use

Returns:

The attributes

io4dolfinx.backends.adios2.backend.read_cell_data(filename: Path | str, name: str, comm: Comm, time: str | float | None, backend_args: dict[str, Any] | None) → tuple[ndarray[tuple[Any, ...], dtype[int64]], ndarray]

Read data from the cells of a mesh.

Parameters:

• filename – Path to file

• name – Name of point data

• comm – Communicator to launch IO on.

• time – The time stamp

• backend_args – The backend arguments

Returns:

A tuple (topology, dofs) where topology contains the vertex indices of the cells, dofs the degrees of freedom within that cell.

io4dolfinx.backends.adios2.backend.read_cell_perms(comm: Comm, filename: Path | str, backend_args: dict[str, Any] | None = None) → ndarray[tuple[Any, ...], dtype[uint32]]

Read cell permutation from file with given communicator, Split in continuous chunks based on number of cells in the mesh (global).

Parameters:

• adios – The ADIOS instance

• comm – The MPI communicator used to read the data

• filename – Path to input file

• variable – Name of cell-permutation variable

• num_cells_global – Number of cells in the mesh (global)

• engine – Type of ADIOS engine to use for reading data

Returns:

Cell-permutations local to the process

Note

No MPI communication is done during this call

io4dolfinx.backends.adios2.backend.read_dofmap(filename: str | Path, comm: Comm, name: str, backend_args: dict[str, Any] | None = None) → AdjacencyList

Read the dofmap of a function with a given name.

Parameters:

• filename – Path to file to read from

• comm – MPI communicator used in storage

• name – Name of the function to read the dofmap for

• backend_args – Arguments to backend

Returns:

Dofmap as an AdjacencyList

io4dolfinx.backends.adios2.backend.read_dofs(filename: str | Path, comm: Comm, name: str, time: float, backend_args: dict[str, Any] | None = None) → tuple[ndarray[tuple[Any, ...], dtype[float32 | float64 | complex64 | complex128]], int]

Read the dofs (values) of a function with a given name from a given timestep.

Parameters:

• filename – Path to file to read from

• comm – MPI communicator used in storage

• name – Name of the function to read the dofs for

• time – Time stamp associated with the function to read

• backend_args – Arguments to backend

Returns:

Contiguous sequence of degrees of freedom (with respect to input data) and the global starting point on the process. Process 0 has [0, M), process 1 [M, N), process 2 [N, O) etc.

io4dolfinx.backends.adios2.backend.read_function_names(filename: Path | str, comm: Comm, backend_args: dict[str, Any] | None) → list[str]

Read all function names from a file.

Parameters:

• filename – Path to file

• comm – MPI communicator to launch IO on.

• backend_args – Arguments to backend

Returns:

A list of function names.

io4dolfinx.backends.adios2.backend.read_legacy_mesh(filename: Path | str, comm: Comm, group: str) → tuple[ndarray[tuple[Any, ...], dtype[int64]], ndarray[tuple[Any, ...], dtype[floating]], str | None]

Read in the mesh topology, geometry and (optionally) cell type from a legacy DOLFIN HDF5-file.

Parameters:

• filename – Path to file to read from

• comm – MPI communicator used in storage

• group – Group in HDF5 file where mesh is stored

Returns:

• Topology as a (num_cells, num_vertices_per_cell) array of global vertex indices

• Geometry as a (num_vertices, geometric_dimension) array of vertex coordinates

• Cell type as a string (e.g. “tetrahedron”) or None if not found

Return type:

Tuple containing

io4dolfinx.backends.adios2.backend.read_mesh_data(filename: Path | str, comm: Comm, time: str | float | None = 0.0, read_from_partition: bool = False, backend_args: dict[str, Any] | None = None) → ReadMeshData

Read an ADIOS2 mesh data for use with DOLFINx.

Parameters:

• filename – Path to input file

• comm – The MPI communciator to distribute the mesh over

• engine – ADIOS engine to use for reading (BP4, BP5 or HDF5)

• time – Time stamp associated with mesh

• legacy – If checkpoint was made prior to time-dependent mesh-writer set to True

• read_from_partition – Read mesh with partition from file

Returns:

The mesh topology, geometry, UFL domain and partition function

io4dolfinx.backends.adios2.backend.read_meshtags_data(filename: str | Path, comm: Comm, name: str, backend_args: dict[str, Any] | None = None) → MeshTagsData

Read mesh tags from file.

Parameters:

• filename – Path to file to read from

• comm – MPI communicator used in storage

• name – Name of the mesh tags to read

• backend_args – Arguments to backend

Returns:

Internal data structure for the mesh tags read from file

io4dolfinx.backends.adios2.backend.read_timestamps(filename: Path | str, comm: Comm, function_name: str, backend_args: dict[str, Any] | None = None) → ndarray[tuple[Any, ...], dtype[float64 | str]]

Read time-stamps from a checkpoint file.

Parameters:

• comm – MPI communicator

• filename – Path to file

• function_name – Name of the function to read time-stamps for

• backend_args – Arguments for backend, for instance file type.

• backend – What backend to use for writing.

Returns:

The time-stamps

io4dolfinx.backends.adios2.backend.snapshot_checkpoint(filename: Path | str, mode: FileMode, u: Function, backend_args: dict[str, Any] | None)

Create a snapshot checkpoint of a dolfinx function.

Parameters:

• filename – Path to file to read from

• mode – File-mode to store the function

• u – dolfinx function to create a snapshot checkpoint for

• backend_args – Arguments to backend

io4dolfinx.backends.adios2.backend.write_attributes(filename: Path | str, comm: Comm, name: str, attributes: dict[str, ndarray], backend_args: dict[str, Any] | None = None)

Write attributes to file using ADIOS2.

Parameters:

• filename – Path to file to write to

• comm – MPI communicator used in storage

• name – Name of the attributes

• attributes – Dictionary of attributes to write to file

• engine – ADIOS2 engine to use

io4dolfinx.backends.adios2.backend.write_data(filename: Path | str, array_data: ArrayData, comm: Comm, time: str | float | None, mode: FileMode, backend_args: dict[str, Any] | None)

Write a 2D-array to file (distributed across proceses with MPI).

Parameters:

• filename – Path to file

• array_data – Data to write to file

• comm – MPI communicator to open the file with.

• time – Time stamp

• mode – Append or write

• backend_args – The backend arguments

io4dolfinx.backends.adios2.backend.write_function(filename: Path, comm: Comm, u: FunctionData, time: float = 0.0, mode: FileMode = FileMode.append, backend_args: dict[str, Any] | None = None)

Write a function to file using ADIOS2

Parameters:

• comm – MPI communicator used in storage

• u – Internal data structure for the function data to save to file

• filename – Path to file to write to

• engine – ADIOS2 engine to use

• mode – ADIOS2 mode to use (write or append)

• time – Time stamp associated with function

• io_name – Internal name used for the ADIOS IO object

io4dolfinx.backends.adios2.backend.write_mesh(filename: Path | str, comm: Comm, mesh: MeshData, backend_args: dict[str, Any] | None = None, mode: FileMode = FileMode.write, time: float = 0.0)

Write a mesh to file using ADIOS2.

Parameters:

• comm – MPI communicator used in storage

• mesh – Internal data structure for the mesh data to save to file

• filename – Path to file to write to

• backend_args – File mode and potentially the io-name.

• mode – Mode to use (write or append)

• time – Time stamp

io4dolfinx.backends.adios2.backend.write_meshtags(filename: str | Path, comm: Comm, data: MeshTagsData, backend_args: dict[str, Any] | None = None)

Write mesh tags to file.

Parameters:

• filename – Path to file to write to

• comm – MPI communicator used in storage

• data – Internal data structure for the mesh tags to save to file

• backend_args – Arguments to backend