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.read_attributes(filename: Path | str, comm: Intracomm, 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: Intracomm, time: str | float | None, backend_args: dict[str, Any] | None) → tuple[ndarray[tuple[int, ...], 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: Intracomm, filename: Path | str, backend_args: dict[str, Any] | None = None) → ndarray[tuple[int, ...], 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: Intracomm, 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: Intracomm, name: str, time: float, backend_args: dict[str, Any] | None = None) → tuple[ndarray[tuple[int, ...], 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: Intracomm, 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: Intracomm, group: str) → tuple[ndarray[tuple[int, ...], dtype[int64]], ndarray[tuple[int, ...], 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: Intracomm, 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: Intracomm, 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: Intracomm, function_name: str, backend_args: dict[str, Any] | None = None) → ndarray[tuple[int, ...], 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: Intracomm, 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: Intracomm, 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: Intracomm, 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: Intracomm, 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: Intracomm, 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