xgi.linalg.hodge_matrix

Hodge theory matrices associated to hypergraphs.

Note that the order of the rows and columns of the matrices in this module correspond to the order in which nodes/edges are added to the hypergraph or simplicial complex. If the node and edge IDs are able to be sorted, the following is an example to sort by the node and edge IDs.

>>> import xgi
>>> import pandas as pd
>>> H = xgi.Hypergraph([[1, 2, 3, 7], [4], [5, 6, 7]])
>>> I, nodedict, edgedict = xgi.incidence_matrix(H, sparse=False, index=True)
>>> # Sorting the resulting numpy array:
>>> sortedI = I.copy()
>>> sortedI = sortedI[sorted(nodedict, key=nodedict.get), :]
>>> sortedI = sortedI[:, sorted(edgedict, key=edgedict.get)]
>>> sortedI
array([[1, 0, 0],
       [1, 0, 0],
       [1, 0, 0],
       [0, 1, 0],
       [0, 0, 1],
       [0, 0, 1],
       [1, 0, 1]])
>>> # Indexing a Pandas dataframe by the node/edge IDs
>>> df = pd.DataFrame(I, index=nodedict.values(), columns=edgedict.values())

If the nodes are already sorted, this order can be preserved by adding the nodes to the hypergraph prior to adding edges. For example,

>>> import xgi
>>> H = xgi.Hypergraph()
>>> H.add_nodes_from(range(1, 8))
>>> H.add_edges_from([[1, 2, 3, 7], [4], [5, 6, 7]])
>>> xgi.incidence_matrix(H, sparse=False)
array([[1, 0, 0],
       [1, 0, 0],
       [1, 0, 0],
       [0, 1, 0],
       [0, 0, 1],
       [0, 0, 1],
       [1, 0, 1]])

Functions

xgi.linalg.hodge_matrix.boundary_matrix(S, order=1, orientations=None, index=False)[source]

Generate the boundary matrices of an oriented simplicial complex.

The rows correspond to the (order-1)-simplices and the columns to the (order)-simplices.

Parameters:

S (simplicial complex object) – The simplicial complex of interest
order (int, default: 1) – Specifies the order of the boundary matrix to compute
orientations (dict, default: None) – Dictionary mapping non-singleton simplices IDs to their boolean orientation
index (bool, default: False) – Specifies whether to output dictionaries mapping the simplices IDs to indices

Returns:

B (numpy.ndarray) – The boundary matrix of the chosen order, has dimension (n_simplices of given order - 1, n_simplices of given order)
rowdict (dict) – The dictionary mapping indices to (order-1)-simplices IDs, if index is True
coldict (dict) – The dictionary mapping indices to (order)-simplices IDs, if index is True

References

“Discrete Calculus” by Leo J. Grady and Jonathan R. Polimeni https://doi.org/10.1007/978-1-84996-290-2

xgi.linalg.hodge_matrix.hodge_laplacian(S, order=1, orientations=None, index=False)[source]

A function to compute the Hodge Laplacians of an oriented simplicial complex.

Parameters:

S (simplicial complex object) – The simplicial complex of interest
order (int, default: 1) – Specifies the order of the Hodge Laplacian matrix to be computed
orientations (dict, default: None) – Dictionary mapping non-singleton simplices IDs to their boolean orientation
index (bool, default: False) – Specifies whether to output dictionaries mapping the simplices IDs to indices

Returns:

L_o (numpy.ndarray) – The Hodge Laplacian matrix of the chosen order, has dimension (n_simplices of given order, n_simplices of given order)
matdict (dict) – The dictionary mapping indices to (order)-simplices IDs, if index is True