API Reference

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)[source]#

Filen mode used for opening files.

append = 10#: Append data to file

read = 30#: Read data from file

write = 20#: Write data to file

class io4dolfinx.SubmeshCheckpoint(submesh: Mesh, cell_map: EntityMap, vertex_map: EntityMap, node_map: ndarray[tuple[Any, ...], dtype[int32]], post_code: ndarray[tuple[Any, ...], dtype[int64]])[source]#

A submesh re-derived from a parent mesh that was read from a checkpoint.

cell_map: EntityMap#: Map from cells of submesh to entities of the parent

node_map: ndarray[tuple[Any, ...], dtype[int32]]#: Map from geometry nodes of submesh to nodes of the parent

property parent_entities: ndarray[tuple[Any, ...], dtype[int32]]#: Parent entities of the submesh cells, aligned with post_code.

post_code: ndarray[tuple[Any, ...], dtype[int64]]#: Index the cell had in the stored submesh, per local cell (owned and ghost). This is the key both submeshes agree on: transfer_submesh_function() derives from it the post office holding each cell, and so routes the data from the stored submesh to this one.

submesh: Mesh#: The submesh, derived from the parent with dolfinx.mesh.create_submesh()

vertex_map: EntityMap#: Map from vertices of submesh to vertices of the parent

io4dolfinx.get_backend(backend: str | None = None) → IOBackend[source]#

Get backend class from backend name.

Parameters:: backend – Name of the backend to get
Returns:: Backend class

io4dolfinx.get_default_backend()[source]#: Get the global default backend for io4dolfinx.

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

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', mesh_name: str | None = None) → Function[source]#

Read data from the cells of a mesh.

Note

Backend has to implement io4dolfinx.backends.IOBackend.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.
mesh_name – Name of the mesh in the file the data belongs to. Defaults to the mesh written without an explicit name.

Returns:

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

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
mesh_name – Name of the mesh in the file to act on. Defaults to the mesh written without an explicit name, so existing checkpoints and call sites are unaffected.

io4dolfinx.read_function_from_legacy_h5(filename: Path, comm: Comm, u: Function, group: str = 'mesh', step: int | None = None, vector_group: str | None = None, backend: str | None = None)[source]#

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: Comm, backend_args: dict[str, Any] | None = None, backend: str = 'h5py', mesh_name: str | None = None) → list[str][source]#

Read all function names from a file.

Parameters:

filename – Path to file
comm – MPI communicator to launch IO on.
backend_args – Arguments to backend
mesh_name – Name of the mesh in the file to act on. Defaults to the mesh written without an explicit name, so existing checkpoints and call sites are unaffected.

Returns:

A list of function names.

io4dolfinx.read_mesh(filename: Path | str, comm: Comm, 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 | None = None, max_facet_to_cell_links: int = 2, mesh_name: str | None = None) → Mesh[source]#

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.
mesh_name – Name of the mesh in the file to act on. Defaults to the mesh written without an explicit name, so existing checkpoints and call sites are unaffected.

Returns:

The distributed mesh

io4dolfinx.read_mesh_from_legacy_h5(filename: Path, comm: Comm, group: str, cell_type: str = 'tetrahedron', backend: str | None = None, max_facet_to_cell_links: int = 2) → Mesh[source]#

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 | None = None, mesh_name: str | None = None) → MeshTags[source]#

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
mesh_name – Name of the mesh in the file to act on. Defaults to the mesh written without an explicit name, so existing checkpoints and call sites are unaffected.

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', mesh_name: str | None = None) → Function[source]#

Read data from the nodes of a mesh.

Note

Backend has to implement io4dolfinx.backends.IOBackend.read_point_data().

Parameters:

filename – Path to file
name – Name of point data
mesh – The corresponding dolfinx.mesh.Mesh.
time – Time-step to read from.
mesh_name – Name of the mesh in the file the data belongs to. Defaults to the mesh written without an explicit name.

Returns:

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

io4dolfinx.read_submesh(filename: Path | str, parent: Mesh, mesh_name: str, parent_mesh_name: str | None = None, backend_args: dict[str, Any] | None = None, backend: str | None = None) → SubmeshCheckpoint[source]#

Re-derive a stored submesh from a parent mesh that has been read back.

The result is a genuine dolfinx.mesh.create_submesh() submesh, so its entity maps are accepted by dolfinx.fem.form() for mixed-dimensional assembly against parent.

It does not carry the checkpointed data. Read that onto the standalone submesh with io4dolfinx.read_mesh() and io4dolfinx.read_function(), then move it across with transfer_submesh_function().

Parameters:

filename – File holding the parent mesh and the post codes, i.e. whatever was passed as parent_filename to write_submesh()
parent – The parent mesh, as read back from the checkpoint
mesh_name – Name the submesh was stored under
parent_mesh_name – Name the parent mesh is stored under
backend_args – Arguments for the backend
backend – Which backend to use

Returns:

The re-derived submesh and the maps relating it to parent.

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.
mesh_name – Name of the mesh in the file to act on. Defaults to the mesh written without an explicit name, so existing checkpoints and call sites are unaffected.

Returns:

The time-stamps

io4dolfinx.reconstruct_mesh(mesh: Mesh, coordinate_element_degree: int) → Mesh[source]#

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.set_default_backend(backend: str)[source]#: Set the global default backend for io4dolfinx.

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

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.transfer_submesh_function(u_source: Function, u_dest: Function, post_code: ndarray[tuple[Any, ...], dtype[int64]])[source]#

Move data from a standalone submesh onto one re-derived from a parent.

u_source lives on the submesh as it was stored – read with io4dolfinx.read_mesh() and io4dolfinx.read_function() – and u_dest on the submesh read_submesh() derived from the parent. The two meshes cover the same cells but number their vertices differently and are partitioned independently, so the transfer cannot be a copy.

Every cell of u_dest’s mesh has a known counterpart in u_source’s, so each interpolation point is routed straight to the process and cell that can evaluate it, with no geometric point location. This is an evaluation followed by a scatter and a local interpolation: it assembles no form and needs no entity map between the two meshes, which would have no meaning as neither is derived from the other.

Parameters:

u_source – Function on the submesh as stored
u_dest – Function to fill, on the submesh re-derived from the parent
post_code – For each cell of u_dest’s mesh (owned and ghost), the index that cell had in the stored submesh, which is what the cell is routed by. From SubmeshCheckpoint.post_code.

Raises:

NotImplementedError – For H(div)/H(curl) spaces on a manifold submesh with a DOLFINx lacking FiniteElement.physical_base_value_size, whose interpolation would return wrong values without reporting an error.

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

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.

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
mesh_name – Name of the mesh in the file to write the data against. Defaults to the mesh written without an explicit name.

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 | None = None, mesh_name: str | None = None)[source]#

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
mesh_name – Name of the mesh in the file to act on. Defaults to the mesh written without an explicit name, so existing checkpoints and call sites are unaffected.

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 | None = None)[source]#

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

Note

Requires backend to implement io4dolfinx.backends.IOBackend.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 | None = None, mesh_name: str | None = None)[source]#

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
mesh_name – Name of the mesh in the file to act on. Defaults to the mesh written without an explicit name, so existing checkpoints and call sites are unaffected.

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

Write mesh to checkpoint file in original input ordering.

Note

Requires backend to implement io4dolfinx.backends.IOBackend.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 | None = None, on_input_mesh: bool = False, mesh_name: str | None = None)[source]#

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
on_input_mesh – If True, the meshtags are written with the node ordering of the input mesh.
mesh_name – Name of the mesh in the file to act on. Defaults to the mesh written without an explicit name, so existing checkpoints and call sites are unaffected.

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.
mesh_name – Name of the mesh in the file to write the data against. Defaults to the mesh written without an explicit name.

io4dolfinx.write_submesh(filename: Path | str, submesh: Mesh, parent: Mesh, cell_map: Any, mesh_name: str, parent_mesh_name: str | None = None, parent_filename: Path | str | None = None, time: float = 0.0, mode: FileMode = FileMode.append, backend_args: dict[str, Any] | None = None, backend: str | None = None)[source]#

Write a submesh, and the post codes that tie it back to its parent.

The submesh is stored as an ordinary independent mesh under mesh_name, so io4dolfinx.read_mesh() and io4dolfinx.read_function() read it back with no special handling. Alongside it goes a tag of post codes: every parent entity that became a submesh cell is given the index that cell has in the stored submesh. The entities are addressed by their parent geometry nodes, which is what lets read_submesh() find them again in a re-partitioned parent; the values come back as SubmeshCheckpoint.post_code.

The post codes tag entities of the parent, so they are stored in the parent’s namespace, in parent_filename. Leave that unset to keep everything in one checkpoint, or point it at the parent’s own file to keep the two apart; the submesh always goes to filename. Either way the parent must already have been written there with io4dolfinx.write_mesh().

Parameters:

filename – Path to write the submesh to
submesh – The submesh, as returned by dolfinx.mesh.create_submesh()
parent – The mesh the submesh was derived from
cell_map – Map from submesh cells to parent entities, as returned by dolfinx.mesh.create_submesh()
mesh_name – Name to store the submesh under
parent_mesh_name – Name the parent mesh is stored under
parent_filename – File holding the parent mesh, if not filename
time – Time stamp associated with the submesh geometry
mode – Whether to create the file or append to it
backend_args – Arguments for the backend
backend – Which backend to use

API Reference

Contents

API Reference#