Backend API

Backend API#

This module shows what functions and data-classes a new backend should implement to achieve full support of all funcntionality.

class io4dolfinx.backends.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.backends.IOBackend(*args, **kwargs)[source]#

get_default_backend_args(arguments: dict[str, Any] | None) → dict[str, Any][source]#

Get default backend arguments given a set of input arguments.

Parameters:: arguments – Input backend arguments
Returns:: Updated backend arguments

read_attributes(filename: Path | str, comm: Intracomm, name: str, backend_args: dict[str, Any] | 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 attribute group
backend_args – Arguments to backend

Returns:

Dictionary of attributes read from file

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

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.

read_cell_perms(comm: Intracomm, filename: Path | str, backend_args: dict[str, Any] | None) → ndarray[tuple[int, ...], dtype[uint32]][source]#

Read cell permutation from file with given communicator, Split in continuous chunks based on number of cells in the input data.

Parameters:

comm – MPI communicator used in storage
filename – Path to file to read from
backend_args – Arguments to backend

Returns:

Contiguous sequence of permutations (with respect to input data) Process 0 has [0, M), process 1 [M, N), process 2 [N, O) etc.

read_dofmap(filename: str | Path, comm: Intracomm, name: str, backend_args: dict[str, Any] | None) → AdjacencyList[source]#

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:

class}`dolfinx.graph.AdjacencyList`

Return type:

Dofmap as an {py

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.

read_function_names(filename: Path | str, comm: Intracomm, backend_args: dict[str, Any] | 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

Returns:

A list of function names.

read_hdf5_array(comm: Intracomm, filename: Path | str, group: str, backend_args: dict[str, Any] | None) → tuple[ndarray, int][source]#

Read an array from an HDF5 file.

Parameters:

comm – MPI communicator used in storage
filename – Path to file to read from
group – Group in HDF5 file where array is stored
backend_args – Arguments to backend

Returns:

Numpy array read from file
Global starting point on the process. Process 0 has [0, M), process 1 [M, N), process 2 [N, O) etc.

Return type:

Tuple containing

read_legacy_mesh(filename: Path | str, comm: Intracomm, group: str) → tuple[ndarray[tuple[int, ...], dtype[int64]], ndarray[tuple[int, ...], dtype[floating]], str | None][source]#

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

read_mesh_data(filename: Path | str, comm: Intracomm, time: str | float | None, read_from_partition: bool, backend_args: dict[str, Any] | None) → ReadMeshData[source]#

Read mesh data from file.

Parameters:

filename – Path to file to read from
comm – MPI communicator used in storage
time – Time stamp associated with the mesh to read
read_from_partition – Whether to read partition information
backend_args – Arguments to backend

Returns:

Internal data structure for the mesh data read from file

read_meshtags_data(filename: str | Path, comm: Intracomm, name: str, backend_args: dict[str, Any] | None) → MeshTagsData[source]#

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

read_point_data(filename: Path | str, name: str, comm: Intracomm, time: str | float | None, backend_args: dict[str, Any] | None) → tuple[ndarray, int][source]#

Read data from the nodes 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:

Data local to process (contiguous, no mpi comm) and local start range

read_timestamps(filename: Path | str, comm: Intracomm, function_name: str, backend_args: dict[str, Any] | None) → ndarray[tuple[int, ...], dtype[float64 | str]][source]#

Read timestamps from file.

Parameters:

filename – Path to file to read from
comm – MPI communicator used in storage
function_name – Name of the function to read timestamps for
backend_args – Arguments to backend

Returns:

Numpy array of timestamps read from file

snapshot_checkpoint(filename: Path | str, mode: FileMode, u: Function, backend_args: dict[str, Any] | None)[source]#

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

write_attributes(filename: Path | str, comm: Intracomm, name: str, attributes: dict[str, ndarray], backend_args: dict[str, Any] | None)[source]#

Write attributes to file.

Parameters:

filename – Path to file to write to
comm – MPI communicator used in storage
name – Name of the attribute group
attributes – Dictionary of attributes to write
backend_args – Arguments to backend

write_data(filename: Path | str, array_data: ArrayData, comm: Intracomm, time: str | float | None, mode: FileMode, backend_args: dict[str, Any] | None)[source]#

Write a 2D-array to file.

Parameters:

filename – Path to file
array_data – Data to write to file.
comm – The MPI communicator to open the writer with.
time – The time stamp
mode – Append or write
backend_args – The backend arguments

write_function(filename: Path, comm: Intracomm, u: FunctionData, time: float, mode: FileMode, backend_args: dict[str, Any] | None)[source]#

Write a function to file.

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
time – Time stamp associated with function
mode – File-mode to store the function
backend_args – Arguments to backend

write_mesh(filename: Path | str, comm: Intracomm, mesh: MeshData, backend_args: dict[str, Any] | None, mode: FileMode, time: float)[source]#

Write a mesh to file.

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 – Arguments to backend
mode – File-mode to store the mesh
time – Time stamp associated with the mesh

write_meshtags(filename: str | Path, comm: Intracomm, data: MeshTagsData, backend_args: dict[str, Any] | None)[source]#

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

io4dolfinx.backends.get_backend(backend: str) → IOBackend[source]#

Get backend class from backend name.

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

class io4dolfinx.structures.FunctionData(cell_permutations: ndarray[tuple[int, ...], dtype[uint32]], local_cell_range: tuple[int, int], num_cells_global: int, dofmap_array: ndarray[tuple[int, ...], dtype[int64]], dofmap_offsets: ndarray[tuple[int, ...], dtype[int64]], dofmap_range: tuple[int, int], global_dofs_in_dofmap: int, values: ndarray[tuple[int, ...], dtype[floating]], dof_range: tuple[int, int], num_dofs_global: int, name: str)[source]#

Container for distributed function data that will be written to file

cell_permutations: ndarray[tuple[int, ...], dtype[uint32]]#: Cell permutations for dofmap

dof_range: tuple[int, int]#: Range of local function values

dofmap_array: ndarray[tuple[int, ...], dtype[int64]]#: Local function dofmap (using global indices)

dofmap_offsets: ndarray[tuple[int, ...], dtype[int64]]#: Global dofmap offsets

dofmap_range: tuple[int, int]#: Range of dofmap on current process

global_dofs_in_dofmap: int#: Number of entries in global dofmap

local_cell_range: tuple[int, int]#: Range of cells on current process

name: str#: Name of function

num_cells_global: int#: Number of cells in global topology

num_dofs_global: int#: Number of global function values

values: ndarray[tuple[int, ...], dtype[floating]]#: Local function values

class io4dolfinx.structures.MeshData(local_geometry: ndarray[tuple[int, ...], dtype[float32]] | ndarray[tuple[int, ...], dtype[float64]], local_geometry_pos: tuple[int, int], num_nodes_global: int, local_topology: ndarray[tuple[int, ...], dtype[int64]], local_topology_pos: tuple[int, int], num_cells_global: int, cell_type: str, degree: int, lagrange_variant: int, store_partition: bool, partition_processes: int | None = None, ownership_array: ndarray[tuple[int, ...], dtype[int32]] | None = None, ownership_offset: ndarray[tuple[int, ...], dtype[int32]] | None = None, partition_range: tuple[int, int] | None = None, partition_global: int | None = None)[source]#

Container for distributed mesh data that will be stored to disk

cell_type: str#: The cell type

degree: int#: Degree of underlying Lagrange element

lagrange_variant: int#: Lagrange-variant of DOFs

local_geometry: ndarray[tuple[int, ...], dtype[float32]] | ndarray[tuple[int, ...], dtype[float64]]#: Two-dimensional array of node coordinates

local_geometry_pos: tuple[int, int]#: Insert range on current process for geometry nodes

local_topology: ndarray[tuple[int, ...], dtype[int64]]#: Two-dimensional connectivity array for mesh topology

local_topology_pos: tuple[int, int]#: Insert range on current process for topology

num_cells_global: int#: NUmber of cells in global topology

num_nodes_global: int#: Number of nodes in global geometry array

ownership_array: ndarray[tuple[int, ...], dtype[int32]] | None = None#: Ownership array for cells

ownership_offset: ndarray[tuple[int, ...], dtype[int32]] | None = None#: Ownership offset for cells

partition_global: int | None = None#: Global size of partitioning array

partition_processes: int | None = None#: Number of processes in partition

store_partition: bool#: Indicator if one should store mesh partitioning

class io4dolfinx.structures.MeshTagsData(name: 'str', values: 'npt.NDArray', indices: 'npt.NDArray[np.int64]', dim: 'int', num_entities_global: 'int | None' = None, num_dofs_per_entity: 'int | None' = None, local_start: 'int | None' = None, cell_type: 'str | None' = None)[source]#

cell_type: str | None = None#: The cell type

local_start: int | None = None#: Starting index in output array (0<=local_start<num_entities_global)`

name: str#: Name of tag

num_dofs_per_entity: int | None = None#: Number of dofs per entity

num_entities_global: int | None = None#: Global number of entities that will be written out

class io4dolfinx.structures.ReadMeshData(cells: ndarray[tuple[int, ...], dtype[int64]], cell_type: str, x: ndarray[tuple[int, ...], dtype[floating]], lvar: int, degree: int, partition_graph: AdjacencyList | None = None)[source]#

Container containing data that will be read into DOLFINx

cell_type: str#: The cell type of the mesh

cells: ndarray[tuple[int, ...], dtype[int64]]#: Two-dimensional array containing global cell->node connectivity

degree: int#: The degree of the underlying Lagrange element

lvar: int#: The Lagrange variant

partition_graph: AdjacencyList | None = None#: Partitioning information per cell on the process

x: ndarray[tuple[int, ...], dtype[floating]]#: The mesh coordinates

Backend API

Contents

Backend API#