API Reference

Top-level package for ADIOS2Wrappers.

class io4dolfinx.FileMode(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Filen mode used for opening files.

append = 10

Append data to file

read = 30

Read data from file

write = 20

Write data to file

io4dolfinx.get_backend(backend: str) → IOBackend

Get backend class from backend name.

Parameters:

backend – Name of the backend to get

Returns:

Backend class

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

Read attributes from file.

Parameters:

• filename – Path to file to read from

• comm – MPI communicator used in storage

• name – Name of the attributes

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

• backend – What backend to use for writing.

Returns:

The attributes

io4dolfinx.read_cell_data(filename: Path | str, name: str, mesh: Mesh, time: float | None = None, backend_args: dict[str, Any] | None = None, backend: str = 'xdmf') → Function

Read data from the nodes of a mesh.

Note

Backend has to implement {py:class}`io4dolfinx.backends.read_cell_data`.

Parameters:

• filename – Path to file

• name – Name of point data

• mesh – The corresponding dolfinx.mesh.Mesh.

• time – Time-step to read from.

Returns:

A function in a DG-0 space on the mesh. The cells not found in input is set to zero.

io4dolfinx.read_function(filename: Path | str, u: Function, time: float = 0.0, name: str | None = None, backend_args: dict[str, Any] | None = None, backend: str = 'adios2')

Read checkpoint from file and fill it into u.

Parameters:

• filename – Path to checkpoint

• u – Function to fill

• time – Time-stamp associated with checkpoint

• name – If not provided, u.name is used to search through the input file for the function

io4dolfinx.read_function_from_legacy_h5(filename: Path, comm: Intracomm, u: Function, group: str = 'mesh', step: int | None = None, backend: str = 'adios2')

Read function from a h5-file generated by legacy DOLFIN HDF5File.write or XDMF.write_checkpoint.

Parameters:

• comm – MPI communicator to distribute mesh over

• filename – Path to h5 or xdmf file

• u – The function used to stored the read values

• group – Group within the h5 file where the function is stored, by default “mesh”

• step – The time step used when saving the checkpoint. If not provided it will assume that the function is saved as a regular function (i.e with HDF5File.write)

• backend – The IO backend

io4dolfinx.read_function_names(filename: Path | str, comm: Intracomm, backend_args: dict[str, Any] | None = None, backend: str = 'h5py') → 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.read_mesh(filename: Path | str, comm: Intracomm, ghost_mode: GhostMode = GhostMode.shared_facet, time: float | str | None = 0.0, read_from_partition: bool = False, backend_args: dict[str, Any] | None = None, backend: str = 'adios2', max_facet_to_cell_links: int = 2) → Mesh

Read an ADIOS2 mesh into DOLFINx.

Parameters:

• filename – Path to input file

• comm – The MPI communciator to distribute the mesh over

• ghost_mode – Ghost mode to use for mesh. If read_from_partition is set to True this option is ignored.

• time – Time stamp associated with mesh

• read_from_partition – Read mesh with partition from file

• backend_args – List of arguments to reader backend

• max_facet_to_cell_links – Maximum number of cells a facet can be connected to.

Returns:

The distributed mesh

io4dolfinx.read_mesh_from_legacy_h5(filename: Path, comm: Intracomm, group: str, cell_type: str = 'tetrahedron', backend: str = 'adios2', max_facet_to_cell_links: int = 2) → Mesh

Read mesh from h5-file generated by legacy DOLFIN HDF5File.write or XDMF.write_checkpoint.

Parameters:

• comm – MPI communicator to distribute mesh over

• filename – Path to h5 or xdmf file

• group – Name of mesh in h5-file

• cell_type – What type of cell type, by default tetrahedron.

• backend – The IO backend to use when reading the mesh (must support legacy mesh reading, e.g., “adios2”).

• max_facet_to_cell_links – Maximum number of cells a facet can be connected to.

io4dolfinx.read_meshtags(filename: Path | str, mesh: Mesh, meshtag_name: str, backend_args: dict[str, Any] | None = None, backend: str = 'adios2') → MeshTags

Read meshtags from file and return a dolfinx.mesh.MeshTags object.

Parameters:

• filename – Path to meshtags file (with file-extension)

• mesh – The mesh associated with the meshtags

• meshtag_name – The name of the meshtag to read

• engine – Adios2 Engine

Returns:

The meshtags

io4dolfinx.read_point_data(filename: Path | str, name: str, mesh: Mesh, time: float | None = None, backend_args: dict[str, Any] | None = None, backend: str = 'xdmf') → Function

Read data from the nodes of a mesh.

Note

Backend has to implement {py:class}`io4dolfinx.backends.read_cell_data`.

Parameters:

• filename – Path to file

• name – Name of point data

• mesh – The corresponding dolfinx.mesh.Mesh.

• time – Time-step to read from.

Returns:

A function in the space equivalent to the mesh coordinate element (up to shape).

io4dolfinx.read_timestamps(filename: Path | str, comm: Intracomm, function_name: str, backend_args: dict[str, Any] | None = None, backend: str = 'adios2') → 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.reconstruct_mesh(mesh: Mesh, coordinate_element_degree: int) → Mesh

Make a copy of a mesh and potentially change the element of the coordinate element.

Note

The topology is shared with the original mesh but the geometry is reconstructed.

Parameters:

• mesh – Mesh to reconstruct

• coordinate_element_degree – Degree to use for coordinate element

Returns:

The new mesh

io4dolfinx.snapshot_checkpoint(uh: Function, file: Path, mode: FileMode, backend_args: dict[str, Any] | None = None, backend: str = 'adios2')

Read or write a snapshot checkpoint

This checkpoint is only meant to be used on the same mesh during the same simulation.

Parameters:

• uh – The function to write data from or read to

• file – The file to write to or read from

• mode – Either read or write

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

Write attributes to file.

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

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

• backend – What backend to use for writing.

io4dolfinx.write_cell_data(filename: Path | str, u: Function, time: str | float | None, mode: FileMode, backend_args: dict[str, Any] | None, backend: str = 'vtkhdf')

Write function to file by interpolating into cell midpoints.

Parameters:

• filename – Path to file

• point_data – Data to write to file

• time – Time stamp

• mode – Append or write

• backend_args – The backend arguments

io4dolfinx.write_function(filename: Path | str, u: Function, time: float = 0.0, mode: FileMode = FileMode.append, name: str | None = None, backend_args: dict[str, Any] | None = None, backend: str = 'adios2')

Write function checkpoint to file.

Parameters:

• u – Function to write to file

• time – Time-stamp for simulation

• filename – Path to write to

• mode – Write or append.

• name – Name of function to write. If None, the name of the function is used.

• backend_args – Arguments to the IO backend.

• backend – The backend to use

io4dolfinx.write_function_on_input_mesh(filename: Path | str, u: Function, time: float = 0.0, name: str | None = None, mode: FileMode = FileMode.append, backend_args: dict[str, Any] | None = None, backend: str = 'adios2')

Write function checkpoint (to be read with the input mesh).

Note

Requires backend to implement {py:class}`io4dolfinx.backends.write_function`.

Parameters:

• filename – The filename to write to

• u – The function to checkpoint

• time – Time-stamp associated with function at current write step

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

• name – Name of function. If None, the name of the function is used.

• backend_args – Arguments to backend

• backend – Choice of backend module

io4dolfinx.write_mesh(filename: Path, mesh: Mesh, mode: FileMode = FileMode.write, time: float = 0.0, store_partition_info: bool = False, backend_args: dict[str, Any] | None = None, backend: str = 'adios2')

Write a mesh to file.

Parameters:

• filename – Path to save mesh (without file-extension)

• mesh – The mesh to write to file

• store_partition_info – Store mesh partitioning (including ghosting) to file

io4dolfinx.write_mesh_input_order(filename: Path | str, mesh: Mesh, time: float = 0.0, mode: FileMode = FileMode.write, backend: str = 'adios2', backend_args: dict[str, Any] | None = None)

Write mesh to checkpoint file in original input ordering.

Note

Requires backend to implement {py:class}`io4dolfinx.backends.write_mesh`.

Parameters:

• filename – The filename to write to

• mesh – Mesh to checkpoint

• time – Time-stamp associated with function at current write step

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

• name – Name of function. If None, the name of the function is used.

• backend_args – Arguments to backend

• backend – Choice of backend module

io4dolfinx.write_meshtags(filename: Path | str, mesh: Mesh, meshtags: MeshTags, meshtag_name: str | None = None, backend_args: dict[str, Any] | None = None, backend: str = 'adios2')

Write meshtags associated with input mesh to file.

Note

For this checkpoint to work, the mesh must be written to file using write_mesh() before calling this function.

Parameters:

• filename – Path to save meshtags (with file-extension)

• mesh – The mesh associated with the meshtags

• meshtags – The meshtags to write to file

• meshtag_name – Name of the meshtag. If None, the meshtag name is used.

• backend_args – Option to IO backend.

• backend – IO backend

io4dolfinx.write_point_data(filename: Path | str, u: Function, time: str | float | None, mode: FileMode, backend_args: dict[str, Any] | None, backend: str = 'vtkhdf')

Write function to file by interpolating into geometry nodes.

Parameters:

• filename – Path to file

• u – The function to store

• time – Time stamp

• mode – Append or write

• backend_args – The backend arguments

• backend – Which backend to use.