dolfinx.graph

Graph representations and operations on graphs.

Functions

`adjacencylist`(data[, offsets])	Create an `AdjacencyList` for int32 or int64 datasets.
`comm_graph`(map[, root])	Build a parallel communication graph from an index map.
`comm_graph_data`(graph)	Build from a communication graph data structures for use with NetworkX.
`comm_to_json`(graph)	Build and JSON string from a communication graph.

Classes

AdjacencyList(cpp_object)

Creates a Python wrapper for the exported adjacency list class.

class dolfinx.graph.AdjacencyList(cpp_object: _cpp.graph.AdjacencyList_int32 | _cpp.graph.AdjacencyList_int64 | _cpp.graph.AdjacencyList_int_sizet_int8__int32_int32)[source]

Bases: object

Creates a Python wrapper for the exported adjacency list class.

Note

Do not use this constructor directly. Instead use adjacencylist().

Parameters:: wrap. (The underlying cpp instance that this object will)

property array: ndarray[tuple[int, ...], dtype[int32 | int64]]

Array representation of the adjacency list.

Note

This is available only for adjacency lists with no additional link (edge) data.

Returns:: Flattened array representation of the adjacency list.

links(node: int32 | int64) → ndarray[tuple[int, ...], dtype[int32 | int64]][source]

Retrieve the links of a node.

Note

This is available only for adjacency lists with no additional link (edge) data.

Parameters:: of. (Node to retrieve the connectivity)
Returns:: Neighbors of the node.

property num_nodes: int32

Number of nodes in the adjacency list.

Returns:: Number of nodes.

property offsets: ndarray[tuple[int, ...], dtype[int32]]

Offsets for each node in the array().

Returns:: Array of indices with shape (num_nodes+1).

dolfinx.graph.adjacencylist(data: ndarray[tuple[int, ...], dtype[int32 | int64]], offsets: ndarray[tuple[int, ...], dtype[int32]] | None = None) → AdjacencyList[source]

Create an AdjacencyList for int32 or int64 datasets.

Parameters:

data – The adjacency array. If the array is one-dimensional, offsets should be supplied. If the array is two-dimensional the number of edges per node is the second dimension.
offsets – The offsets array with the number of edges per node.

Returns:

An adjacency list.

dolfinx.graph.comm_graph(map: IndexMap, root: int = 0) → AdjacencyList[source]

Build a parallel communication graph from an index map.

The communication graph is a directed graph that represents the communication pattern for a distributed array, and specifically the forward scatter operation where the values for owned indices are sent to ghosting ranks. The graph is built from an index map, which describes the local and ghosted indices of the array.

Edges in the graph represent communication from the owning rank to ranks that ghost the data. The edge data holds the (0) target node, (1) edge weight, and (2) an indicator for whether the sending and receiving ranks share memory (local==1) or if the ranks do not share memory (local==0). The node data holds the local size (number of owned indices) and the number of ghost indices.

The graph can be processed using comm_graph() to build data structures that can be used to build a NetworkX directed graph.

Note

This function is collective across all MPI ranks. The communication graph is returned on the root rank. All other ranks return an empty graph

Parameters:

map – Index map to build the communication graph from.
root – Rank that will return the communication graph. Other ranks return an empty graph.

Returns:

An adjacency list representing the communication graph.

dolfinx.graph.comm_graph_data(graph: AdjacencyList) → tuple[list[tuple[int, int, dict[str, int]]], list[tuple[int, dict[str, int]]]][source]

Build from a communication graph data structures for use with NetworkX.

Parameters:: graph – Communication graph to build data from. Normally created by comm_graph().
Returns:: A tuple of two lists. The first list contains the edge data, where an edge is a (nodeID_0, nodeID_1, dict) tuple, where dict holds edge data. The second list hold node data, where a node is a (nodeID, dict) tuple, where dict holds node data.

dolfinx.graph.comm_to_json(graph: AdjacencyList) → str[source]

Build and JSON string from a communication graph.

The JSON string can be used to construct a NetworkX graph. This is helpful for cases where a simulation is executed and the graph data is written to file as a JSON string for later analysis.

Parameters:: graph – The communication graph to convert. Normally created by calling comm_graph().
Returns:: A JSON string representing the communication graph.