toponetx.CellComplex#

class toponetx.CellComplex(cells=None, regular: bool = True, **kwargs)[source]#

Bases: Complex

Class representing a cell complex.

A cell complex is a mathematical structure that is built up from simple building blocks called cells. These cells can be thought of as generalized versions of familiar shapes, such as points, line segments, triangles, and disks. By gluing these cells together in a prescribed way, one can create complex geometrical objects that are of interest in topology and geometry.

Cell complexes can be used to represent various mathematical objects, such as graphs, manifolds, and discrete geometric shapes. They are useful in many areas of mathematics, such as algebraic topology and geometry, where they can be used to study the structure and properties of these objects.

In TNX the class CellComplex supports building a regular or non-regular 2d cell complex. The class CellComplex only supports the construction of 2d cell complexes. If higher dimensional cell complexes are desired then one should utilize the class CombinatorialComplex.

Mathematically, in TNX a cell complex it a triplet $(V, E, C)$ where $V$ is a set of nodes, $E$ is a set of edges and $C$ is a set of 2-cells. In TNX each 2-cell C is consists of a finite sequence of nodes $C=(n_1,…,n_k,n_1)$ with $kgeq 2$. All edges between two consecutive nodes in C belong to E. Regular cells have unique nodes in C whereas non-regular cells allow for duplication.

In TNX, cell complexes are implemented to be dynamic in the sense that they can change by adding or subtracting objects (nodes, edges, 2-cells) from them.

  1. Dynamic construction of cell complexes, allowing users to add or remove objects from these

    structures after their initial creation.

  2. Compatibility with the NetworkX library, enabling users to leverage the powerful algorithms

    and data structures provided by this package.

  3. Support for attaching arbitrary attributes and data to cells in the complex, allowing users to store

    and manipulate additional information about these objects.

  4. Efficient storage and manipulation of complex data structures, using advanced data structures

    such as sparse matrices.

  5. Robust error handling and validation of input data, ensuring that the package is reliable and easy to use.

Parameters:
cellsiterable, optional

A list of cells to add to the complex.

regularbool, default=True

If True, then the complex is regular, otherwise it is non-regular.

**kwargskeyword arguments, optional

Attributes to add to the complex as key=value pairs.

Attributes:
complexdict

A dictionary that can be used to store additional information about the complex.

Methods

add_cell(cell[, rank, check_skeleton])

Add a single cell to cell complex.

add_cells_from(cell_set[, rank, check_skeleton])

Add cells to cell complex.

add_edge(u_of_edge, v_of_edge, **attr)

Add edge.

add_edges_from(ebunch_to_add, **attr)

Add edges.

add_node(node, **attr)

Add a single node to cell complex.

adjacency_matrix(rank[, signed, weight, index])

Compute adjacency matrix for a given rank.

all_cell_to_node_coadjacency_matrix([s, ...])

Return coadjecency matrix of cells with respect to nodes.

cell_neighbors(cell[, s])

Return the neighboring cells of the given cell.

clear()

Remove all cells from a cell complex.

clone()

Create a clone of the CellComplex.

coadjacency_matrix(rank[, signed, weight, index])

Compute coadjacency matrix for a given rank.

degree(node[, rank])

Compute the number of cells of certain rank that contain node.

dirac_operator_matrix([signed, weight, index])

Compute dirac operator matrix matrix.

down_laplacian_matrix(rank[, signed, ...])

Compute down laplacian.

euler_characterisitics()

Return the euler characteristics of the cell complex.

from_networkx_graph(G)

Add edges and nodes from a graph G to self.

from_trimesh(mesh)

Convert from trimesh object.

get_cell_attributes(name, rank)

Get node attributes from graph.

get_cell_data(cell, rank[, attr_name])

Retrieve data associated with a specific cell in the complex.

get_edge_attributes(name)

Get edge attributes.

get_filtration(name)

Get filtration.

get_linegraph([s, cells])

Create line graph of self.

get_node_attributes(name)

Get node attributes.

hodge_laplacian_matrix(rank[, signed, ...])

Compute the Hodge Laplacian matrix for this cell complex.

incidence_matrix(rank[, signed, weight, index])

Incidence matrix for the cell complex indexed by nodes x cells.

is_connected()

Determine if cell complex is s-connected.

is_insertable_cycle(cell[, check_skeleton, ...])

Determine if a cycle is insertable to the cell complex.

load_mesh(file_path[, process])

Load a mesh.

neighbors(node)

Return nodes in cell complex which share s cell(s) with node.

node_to_all_cell_adjacnecy_matrix([s, ...])

Compute s-adjacency matrix between nodes with respect to 2-cells.

node_to_all_cell_incidence_matrix([weight, ...])

Nodes/all cells incidence matrix for the indexed by nodes X cells.

number_of_cells([cell_set])

Compute the number of cells in cell_set belonging to cell complex.

number_of_edges([edge_set])

Compute number of edges in edge_set belonging to cell complex.

number_of_nodes([node_set])

Compute number of nodes in node_set belonging to cell complex.

order()

Compute the number of nodes in the cell complex.

remove_cell(cell)

Remove a single cell from Cell Complex.

remove_cells(cell_set)

Remove cells from a cell complex that are in cell_set.

remove_equivalent_cells()

Remove equivalent cells.

remove_node(node)

Remove the given node from the cell complex.

remove_nodes(node_set)

Remove nodes from cells.

remove_singletons()

Remove singleton nodes (see CellComplex.singletons()).

restrict_to_cells(cell_set[, keep_edges])

Construct cell complex using a subset of the cells in cell complex.

restrict_to_nodes(node_set)

Restrict cell complex to nodes.

set_cell_attributes(values, rank[, name])

Set cell attributes.

set_cell_data(cell, rank, attr_name, attr_value)

Set data for a specific cell in the complex.

set_edge_attributes(values[, name])

Set edge attributes.

set_filtration(values[, name])

Set filtration.

set_node_attributes(values[, name])

Set node attributes.

singletons()

Return list of singleton cell.

size(cell[, node_set])

Compute number of nodes in node_set that belong to cell.

skeleton(rank)

Compute skeleton.

to_colored_hypergraph()

Convert to colored hypergraph.

to_combinatorial_complex()

Convert this cell complex to a combinatorial complex.

to_hasse_graph()

Create Hasse graph of self.

to_hypergraph()

Convert this cell complex to a hypergraph.

up_laplacian_matrix(rank[, signed, weight, ...])

Compute up laplacian.

Examples

Iteratively construct a cell complex:

>>> CC = tnx.CellComplex()
>>> CC.add_cell([1, 2, 3, 4], rank=2)
>>> # the cell [1, 2, 3, 4] consists of the cycle (1,2), (2,3), (3,4), (4,5)
>>> # tnx creates these edges automatically if they are not inserted in the underlying graph
>>> CC.add_cell([2, 3, 4, 5], rank=2)
>>> CC.add_cell([5, 6, 7, 8], rank=2)

You can also pass a list of cells to the constructor:

>>> c1 = tnx.Cell((1, 2, 3))  # a cell here is always assumed to be 2d
>>> c2 = tnx.Cell((1, 2, 3, 4))
>>> CC = tnx.CellComplex([c1, c2])

TopoNetX is also compatible with NetworkX, allowing users to create a cell complex from a NetworkX graph:

>>> g = nx.Graph()
>>> g.add_edge(1, 0)
>>> g.add_edge(2, 0)
>>> g.add_edge(1, 2)
>>> CC = tnx.CellComplex(g)
>>> CC.add_cells_from([[1, 2, 4], [1, 2, 7]], rank=2)
>>> CC.cells

By default, a regular cell complex is constructed. You can change this behaviour using the regular parameter when constructing the complex.

>>> # non-regular cell complex
>>> # by default CellComplex constructor assumes regular cell complex
>>> CC = tnx.CellComplex(regular=False)
>>> CC.add_cell([1, 2, 3, 4], rank=2)
>>> CC.add_cell([2, 3, 4, 5, 2, 3, 4, 5], rank=2)  # non-regular 2-cell
>>> c1 = tnx.Cell((1, 2, 3, 4, 5, 1, 2, 3, 4, 5), regular=False)
>>> CC.add_cell(c1)
>>> CC.add_cell([5, 6, 7, 8], rank=2)
>>> CC.is_regular
__init__(cells=None, regular: bool = True, **kwargs) → None[source]#

Initialize a new instance of the Complex class.

Parameters:
**kwargskeyword arguments, optional

Attributes to add to the complex as key=value pairs.

Methods

__init__([cells, regular])

Initialize a new instance of the Complex class.

add_cell(cell[, rank, check_skeleton])

Add a single cell to cell complex.

add_cells_from(cell_set[, rank, check_skeleton])

Add cells to cell complex.

add_edge(u_of_edge, v_of_edge, **attr)

Add edge.

add_edges_from(ebunch_to_add, **attr)

Add edges.

add_node(node, **attr)

Add a single node to cell complex.

adjacency_matrix(rank[, signed, weight, index])

Compute adjacency matrix for a given rank.

all_cell_to_node_coadjacency_matrix([s, ...])

Return coadjecency matrix of cells with respect to nodes.

cell_neighbors(cell[, s])

Return the neighboring cells of the given cell.

clear()

Remove all cells from a cell complex.

clone()

Create a clone of the CellComplex.

coadjacency_matrix(rank[, signed, weight, index])

Compute coadjacency matrix for a given rank.

degree(node[, rank])

Compute the number of cells of certain rank that contain node.

dirac_operator_matrix([signed, weight, index])

Compute dirac operator matrix matrix.

down_laplacian_matrix(rank[, signed, ...])

Compute down laplacian.

euler_characterisitics()

Return the euler characteristics of the cell complex.

from_networkx_graph(G)

Add edges and nodes from a graph G to self.

from_trimesh(mesh)

Convert from trimesh object.

get_cell_attributes(name, rank)

Get node attributes from graph.

get_cell_data(cell, rank[, attr_name])

Retrieve data associated with a specific cell in the complex.

get_edge_attributes(name)

Get edge attributes.

get_filtration(name)

Get filtration.

get_linegraph([s, cells])

Create line graph of self.

get_node_attributes(name)

Get node attributes.

hodge_laplacian_matrix(rank[, signed, ...])

Compute the Hodge Laplacian matrix for this cell complex.

incidence_matrix(rank[, signed, weight, index])

Incidence matrix for the cell complex indexed by nodes x cells.

is_connected()

Determine if cell complex is s-connected.

is_insertable_cycle(cell[, check_skeleton, ...])

Determine if a cycle is insertable to the cell complex.

load_mesh(file_path[, process])

Load a mesh.

neighbors(node)

Return nodes in cell complex which share s cell(s) with node.

node_to_all_cell_adjacnecy_matrix([s, ...])

Compute s-adjacency matrix between nodes with respect to 2-cells.

node_to_all_cell_incidence_matrix([weight, ...])

Nodes/all cells incidence matrix for the indexed by nodes X cells.

number_of_cells([cell_set])

Compute the number of cells in cell_set belonging to cell complex.

number_of_edges([edge_set])

Compute number of edges in edge_set belonging to cell complex.

number_of_nodes([node_set])

Compute number of nodes in node_set belonging to cell complex.

order()

Compute the number of nodes in the cell complex.

remove_cell(cell)

Remove a single cell from Cell Complex.

remove_cells(cell_set)

Remove cells from a cell complex that are in cell_set.

remove_equivalent_cells()

Remove equivalent cells.

remove_node(node)

Remove the given node from the cell complex.

remove_nodes(node_set)

Remove nodes from cells.

remove_singletons()

Remove singleton nodes (see CellComplex.singletons()).

restrict_to_cells(cell_set[, keep_edges])

Construct cell complex using a subset of the cells in cell complex.

restrict_to_nodes(node_set)

Restrict cell complex to nodes.

set_cell_attributes(values, rank[, name])

Set cell attributes.

set_cell_data(cell, rank, attr_name, attr_value)

Set data for a specific cell in the complex.

set_edge_attributes(values[, name])

Set edge attributes.

set_filtration(values[, name])

Set filtration.

set_node_attributes(values[, name])

Set node attributes.

singletons()

Return list of singleton cell.

size(cell[, node_set])

Compute number of nodes in node_set that belong to cell.

skeleton(rank)

Compute skeleton.

to_colored_hypergraph()

Convert to colored hypergraph.

to_combinatorial_complex()

Convert this cell complex to a combinatorial complex.

to_hasse_graph()

Create Hasse graph of self.

to_hypergraph()

Convert this cell complex to a hypergraph.

up_laplacian_matrix(rank[, signed, weight, ...])

Compute up laplacian.

Attributes

cells

Return cells.

dim

Return maximum dimension.

edges

Return edges.

is_regular

Check the regularity condition.

maxdim

Return maximum dimension.

nodes

Return nodes.

shape

Return shape.

complex

add_cell(cell: tuple | list | Cell, rank: int | None = None, check_skeleton: bool = False, **attr)[source]#

Add a single cell to cell complex.

Parameters:
cellhashable

If hashable the cell returned will be empty.

rank{0, 1, 2}

Rank of the cell to be added.

check_skeletonbool, default=False

If true, this function checks the skeleton whether the given cell can be added.

**attrkeyword arguments, optional

Attributes to add to the cell as key=value pairs.

Examples

>>> CC = tnx.CellComplex()
>>> c1 = tnx.Cell((2, 3, 4), color="black")
>>> CC.add_cell(c1, weight=3)
>>> CC.add_cell([1, 2, 3, 4], rank=2, color="red")
>>> CC.add_cell([2, 3, 4, 5], rank=2, color="blue")
>>> CC.add_cell([5, 6, 7, 8], rank=2, color="green")
>>> CC.cells[(1, 2, 3, 4)]["color"]
'red'
add_cells_from(cell_set: Iterable[tuple | list | Cell], rank: int | None = None, check_skeleton: bool = False, **attr) → None[source]#

Add cells to cell complex.

Parameters:
cell_setiterable of hashables or Cell

Iterable of cells to add to the complex.

rankint, optional

The rank of cells to be added. If cell_set consists of Cell objects, this parameter is ignored.

check_skeletonbool, default=False

If true, this function checks the skeleton whether the given cell can be added.

**attrkeyword arguments, optional

Attributes to add to the cells as key=value pairs.

add_edge(u_of_edge: Hashable, v_of_edge: Hashable, **attr) → None[source]#

Add edge.

Parameters:
u_of_edgehashable

First node of the edge.

v_of_edgehashable

Second node of the edge.

**attrkeyword arguments, optional

Attributes to add to the edge as key=value pairs.

add_edges_from(ebunch_to_add: Iterable[tuple], **attr) → None[source]#

Add edges.

Parameters:
ebunch_to_addIterable of edges

Each edge must be given as a tuple (u, v).

**attrkeyword arguments, optional

Attributes to add to the edges as key=value pairs.

add_node(node: Hashable, **attr) → None[source]#

Add a single node to cell complex.

Parameters:
nodehashable

The node to be added.

**attrkeyword arguments, optional

Attributes to add to the node as key=value pairs.

adjacency_matrix(rank: int, signed: bool = False, weight: str | None = None, index: bool = False)[source]#

Compute adjacency matrix for a given rank.

Parameters:
rankint

The rank for which an adjacency matrix should be computed.

signedbool, default=False

Whether the returned adjacency matrix should be signed (i.e., respect orientations) or unsigned.

weightstr, optional

The name of the simplex attribute to use as weights for the hodge laplacian matrix. If None, the matrix is binary.

indexbool, default=False

Whether to return the indices of the rows and columns of the adjacency matrix.

Returns:
indicesdict

Dictionary mapping each row and column of the coadjacency matrix to a cell. Only returned if index is True.

adjacency_matrixscipy.sparse.csr.csr_matrix

The adjacency matrix of rank rank of this cell complex.

all_cell_to_node_coadjacency_matrix(s: int = 1, weight: str | None = None, index: bool = False) → csc_matrix | tuple[dict, dict, csc_matrix][source]#

Return coadjecency matrix of cells with respect to nodes.

Parameters:
sint, default=1

Minimum number of nodes that cells must share to be considered adjacent.

weightstr, optional

The name of the cell attribute to use as weights for the coadjacency matrix. If None, the matrix is binary.

indexbool, optional

Whether to return the indices of the rows and columns of the adjacency matrix.

Returns:
indicesdict

Dictionary assigning each row and column of the coadjacency matrix to a cell. Only returned if index is True.

scipy.sparse.csr.csc_matrix

The coadjacency matrix.

Notes

Two cells (1 dimensional or 2 dimensional) are s-coadjacent iff they share s nodes.

Examples

>>> CX = tnx.CellComplex([[1, 2, 3, 4], [2, 3, 6]])
>>> index, m = CX.all_cell_to_node_coadjacency_matrix(s=1, index=True)
>>> # m_ij iff cell i is coadjacency to cell j. Dimension of cells i,j are arbirary
>>> print(m.todense(), index)
cell_neighbors(cell, s: int = 1)[source]#

Return the neighboring cells of the given cell.

Parameters:
cellCell or Iterable

The cell for which to find neighbors.

sint, default=1

Minimum number of nodes shared by neighboring cell.

Returns:
list

List of cell neighbors.

property cells: CellView#

Return cells.

Returns:
CellView

The cell view of the Complex.

clear()[source]#

Remove all cells from a cell complex.

clone() → Self[source]#

Create a clone of the CellComplex.

Returns:
CellComplex

A copy of this CellComplex.

Examples

>>> CC = tnx.CellComplex()
>>> CC.add_cell([1, 2, 3, 4], rank=2, weight=5)
>>> CC.add_cell([2, 3, 4, 5], rank=2)
>>> CC.add_cell([5, 6, 7, 8], rank=2)
>>> CC.add_node(0)
>>> CC.clone()
coadjacency_matrix(rank: int, signed: bool = False, weight: str | None = None, index: bool = False)[source]#

Compute coadjacency matrix for a given rank.

Parameters:
rankint

Rank of the coadjacency matrix.

signedbool

Whether to return the signed or unsigned coadjacency matrix.

weightstr, optional

The name of the cell attribute to use as weights for the coadjacency matrix. If None, the matrix is binary.

indexbool, default=False

Whether to return the indices of the rows and columns of the coadjacency matrix.

Returns:
indicesdict

Dictionary mapping each row and column of the coadjacency matrix to a cell. Only returned if index is True.

coadjacency_matrixscipy.sparse.csr.csr_matrix

The coadjacency matrix of this cell complex.

degree(node: Hashable, rank: int = 1) → int[source]#

Compute the number of cells of certain rank that contain node.

Parameters:
nodehashable

Identifier for the node.

rankint, default=1

Smallest size of cell to consider in degree.

Returns:
int

Number of cells of rank at least rank that contain node.

property dim: int#

Return maximum dimension.

Returns:
int

The maximum dimension of the Cell Complex.

dirac_operator_matrix(signed: bool = True, weight: str | None = None, index: bool = False)[source]#

Compute dirac operator matrix matrix.

Parameters:
signedbool, default=False

Whether the returned dirac matrix should be signed (i.e., respect rientations) or unsigned.

weightstr, optional

The name of the cell attribute to use as weights for the dirac operator matrix. If None, the matrix is binary.

indexbool, default=False

Whether to return the indices of the rows and columns of the dirac operator matrix.

Returns:
row_indices, col_indicesdict

List identifying rows and columns of the dirac operator matrix. Only returned if index is True.

scipy.sparse.csr.csc_matrix

The dirac operator matrix of this cell complex.

Examples

>>> G = nx.path_graph(3)
>>> CC = tnx.CellComplex(G)
>>> CC.add_cell([1, 2, 3, 4], rank=2)
>>> CC.dirac_operator_matrix()
down_laplacian_matrix(rank: int, signed: bool = True, weight: str | None = None, index: bool = False)[source]#

Compute down laplacian.

Parameters:
rank{1, 2}

Rank of the down Laplacian matrix.

signedbool

Whether to return the signed or unsigned down laplacian.

weightstr, optional

The name of the cell attribute to use as weights for the hodge laplacian matrix. If None, the matrix is binary.

indexbool, default=False

Whether to return the indices of the rows and columns of the laplacian.

Returns:
indicesdict

Dictionary assigning each row and column of the laplacian matrix to a cell. Only returned if index is True.

down_laplacianscipy.sparse.csr.csr_matrix

The down laplacian matrix of this cell complex.

Examples

>>> G = nx.path_graph(3)
>>> CC = tnx.CellComplex(G)
>>> CC.add_cell([1, 2, 3, 4], rank=2)
>>> CC.add_cell([1, 2, 3, 4], rank=2)
>>> CC.add_cell([2, 3, 4, 1], rank=2)
>>> CC.add_cell([1, 2, 4], rank=2)
>>> CC.add_cell([3, 4, 8], rank=2)
>>> CC.down_laplacian_matrix(2)
property edges: EdgeView#

Return edges.

Returns:
EdgeView

The edge view of the Complex.

euler_characterisitics() → int[source]#

Return the euler characteristics of the cell complex.

Returns:
int

The Euler characteristics of the cell complex.

from_networkx_graph(G: Graph) → None[source]#

Add edges and nodes from a graph G to self.

Parameters:
Gnx.Graph

A NetworkX graph.

Examples

>>> CC = tnx.CellComplex()
>>> CC.add_cells_from([[1, 2, 4], [1, 2, 7]], rank=2)
>>> G = nx.Graph([(0, 1), (0, 2), (1, 2)])
>>> CC.from_networkx_graph(G)
>>> CC.edges
classmethod from_trimesh(mesh) → Self[source]#

Convert from trimesh object.

Parameters:
meshtrimesh.Trimesh

A trimesh object.

Returns:
CellComplex

The cell complex generated from the trimesh provided.

Examples

>>> import trimesh
>>> mesh = trimesh.Trimesh(
...     vertices=[[0, 0, 0], [0, 0, 1], [0, 1, 0]],
...     faces=[[0, 1, 2]],
...     process=False,
... )
>>> CC = tnx.CellComplex.from_trimesh(mesh)
>>> CC[0]["position"]
get_cell_attributes(name: str, rank: int) → dict[tuple[Hashable, ...], Any][source]#

Get node attributes from graph.

Parameters:
namestr

Attribute name.

rankint

The rank for which to return attribute values.

Returns:
dict

Dictionary mapping each cell of rank rank to the value of the given attribute name.

Examples

>>> G = nx.path_graph(3)
>>> d = {
...     ((1, 2, 3, 4), 0): {"color": "red", "attr2": 1},
...     (1, 2, 4): {"color": "blue", "attr2": 3},
... }
>>> CC = tnx.CellComplex(G)
>>> CC.add_cell([1, 2, 3, 4], rank=2)
>>> CC.add_cell([1, 2, 3, 4], rank=2)
>>> CC.add_cell([1, 2, 4], rank=2)
>>> CC.add_cell([3, 4, 8], rank=2)
>>> CC.set_cell_attributes(d, 2)
>>> CC.get_cell_attributes("color", 2)
{((1, 2, 3, 4), 0): 'red', (1, 2, 4): 'blue'}
get_cell_data(cell, rank, attr_name: str | None = None)[source]#

Retrieve data associated with a specific cell in the complex.

Parameters:
cellstr or tuple

The cell to retrieve data from.

rankint

The rank of the cell.

attr_namestr, optional

The name of the attribute to retrieve. Default is None.

Returns:
object

The value associated with the specified cell and attribute.

Raises:
KeyError

If the specified cell or attribute is not found.

Notes

  • For rank 0 cells (nodes), the data is retrieved from the ‘nodes’ dictionary.

  • For rank 1 cells (edges), the data is retrieved from the ‘edges’ dictionary.

  • For rank 2 cells (other cells), the data is retrieved from the ‘cells’ dictionary.

get_edge_attributes(name: str) → dict[tuple, Any][source]#

Get edge attributes.

Parameters:
namestr

Attribute name.

Returns:
dict

Dictionary mapping each edge to the value of the given attribute name.

Examples

>>> G = nx.path_graph(3)
>>> CC = tnx.CellComplex(G)
>>> CC.add_cell([1, 2, 3, 4], rank=2)
>>> d = {
...     (1, 2): {"color": "red", "attr2": 1},
...     (2, 3): {"color": "blue", "attr2": 3},
... }
>>> CC.set_edge_attributes(d)
>>> CC.get_edge_attributes("color")
{(1, 2): 'red', (2, 3): 'blue'}
get_filtration(name: str) → dict[Hashable, Any][source]#

Get filtration.

Parameters:
namestr

The attribute name that holds the filtration values.

Returns:
dict

Dictionary mapping each cell to the value of the given attribute name.

Notes

This is equivalent to getting a feature defined on the entire cell complex

Examples

>>> G = nx.path_graph(3)
>>> CC = tnx.CellComplex(G)
>>> d = {0: 1, 1: 0, 2: 2, (0, 1): 1, (1, 2): 3}
>>> CC.set_filtration(d, "f")
>>> CC.get_filtration("f")
{0: 1, 1: 0, 2: 2, (0, 1): 1, (1, 2): 3}
get_linegraph(s: int = 1, cells: bool = True) → Graph[source]#

Create line graph of self.

If cells=True (default), the cells will be the vertices of the line graph. Two vertices are connected by an s-line-graph edge if the corresponding cell complex edges intersect in at least s cell complex nodes.

If cells=False, the cell complex nodes will be the vertices of the line graph. Two vertices are connected if the nodes they correspond to share at least s incident cell complex edges.

Parameters:
sint

The width of the connections.

cellsbool, optional

Determines if cells or nodes will be the vertices in the line graph.

Returns:
nx.Graph

A NetworkX graph representing the s-linegraph of the Cell Complex.

Examples

>>> CC = tnx.CellComplex()
>>> CC.add_cell([0, 1, 2, 3, 4], rank=2)
>>> CC.get_linegraph()
get_node_attributes(name: str) → dict[tuple, Any][source]#

Get node attributes.

Parameters:
namestr

Attribute name.

Returns:
dict

Dictionary mapping each node to the value of the given attribute name.

Examples

>>> G = nx.path_graph(3)
>>> CC = tnx.CellComplex(G)
>>> CC.add_cell([1, 2, 3, 4], rank=2)
>>> d = {1: {"color": "red", "attr2": 1}, 2: {"color": "blue", "attr2": 3}}
>>> CC.set_node_attributes(d)
>>> CC.get_node_attributes("color")
{1: 'red', 2: 'blue'}
hodge_laplacian_matrix(rank: int, signed: bool = True, weight: str | None = None, index: bool = False) → csr_matrix | tuple[dict, csr_matrix][source]#

Compute the Hodge Laplacian matrix for this cell complex.

Parameters:
rank{0, 1, 2}

Dimension of the Laplacian matrix.

signedbool

Whether to return the signed or unsigned hodge laplacian.

weightstr, optional

The name of the cell attribute to use as weights for the hodge laplacian matrix. If None, the matrix is binary.

indexbool, default=False

Indicates whether to return the indices that define the hodge laplacian matrix.

Returns:
indicesdict

Dictionary assigning each row and column of the incidence matrix to a cell. Only returned if index is True.

scipy.sparse.csr.csc_matrix

The Hodge Laplacian matrix of rank rank.

Examples

>>> CC = tnx.CellComplex()
>>> CC.add_cell([1, 2, 3, 4], rank=2)
>>> CC.add_cell([3, 4, 5], rank=2)
>>> CC.hodge_laplacian_matrix(1)
incidence_matrix(rank: int, signed: bool = True, weight: str | None = None, index: bool = False) → csr_matrix | tuple[dict, dict, csr_matrix][source]#

Incidence matrix for the cell complex indexed by nodes x cells.

Parameters:
rankint

The rank for which an incidence matrix should be computed.

signedbool, default=True

Whether the returned incidence matrix should be signed (i.e., respect orientations) or unsigned.

weightstr, optional

The name of the simplex attribute to use as weights for the incidence matrix. If None, the matrix is binary.

indexbool, optional

Whether to return the indices of the rows and columns of the incidende matrix.

Returns:
row_indices, col_indicesdict

Dictionary assigning each row and column of the incidence matrix to a cell. Only returned if index is True.

scipy.sparse.csr.csc_matrix

The incidence matrix.

Examples

>>> CC = tnx.CellComplex()
>>> CC.add_cell([1, 2, 3, 4], rank=2)
>>> CC.add_cell([3, 4, 5], rank=2)
>>> B0 = CC.incidence_matrix(0)
>>> B1 = CC.incidence_matrix(1)
>>> B2 = CC.incidence_matrix(2)
>>> B1.dot(B2).todense()
>>> B0.dot(B1).todense()

Note that in this example, the first three cells are equivalent and hence they have similar incidence to lower edges they are incident to.

>>> G = nx.path_graph(3)
>>> CC = tnx.CellComplex(G)
>>> CC.add_cell([1, 2, 3, 4], rank=2)
>>> CC.add_cell([4, 3, 2, 1], rank=2)
>>> CC.add_cell([2, 3, 4, 1], rank=2)
>>> CC.add_cell([1, 2, 4], rank=2)
>>> CC.add_cell([3, 4, 8], rank=2)
>>> B1 = CC.incidence_matrix(1)
>>> B2 = CC.incidence_matrix(2)
>>> B1.dot(B2).todense()

Non-regular cell complex example:

>>> CC = tnx.CellComplex(regular=False)
>>> CC.add_cell([1, 2, 3, 2], rank=2)
>>> CC.add_cell([3, 4, 5, 3, 4, 5], rank=2)
>>> B1 = CC.incidence_matrix(1)
>>> B2 = CC.incidence_matrix(2)
>>> print(B2.todense())  # observe the non-unit entries
>>> B1.dot(B2).todense()

>>> CC = tnx.CellComplex()
>>> CC.add_cell([1, 2, 3, 4], rank=2)
>>> CC.add_cell([3, 4, 5], rank=2)
>>> row, column, B1 = CC.incidence_matrix(1, index=True)
>>> print(row)
>>> print(column)
>>> print(B1.todense())
is_connected()[source]#

Determine if cell complex is s-connected.

Returns:
bool

True if the cell complex is connected, False otherwise.

is_insertable_cycle(cell: tuple | list | Cell, check_skeleton: bool = True, warnings_dis: bool = False) → bool[source]#

Determine if a cycle is insertable to the cell complex.

Checks regularity if this CellComplex is regular, existence of required edges if check_skeleton is True, and that the cell has a minimum length of 2.

Parameters:
cellCell | tuple | list

The cell to check.

check_skeletonbool, default=True

Whether to check that all edges induced by the cell are part of the underlying graph. If False, missing edges will be ignored.

warnings_disbool, default=False

Whether to print a warning with the reason why the cell is not insertable.

Returns:
bool

True if the cell can be inserted, otherwise False.

property is_regular: bool#

Check the regularity condition.

Returns:
bool

Returns True if the regularity condition is satisfied.

Examples

>>> CC = tnx.CellComplex(regular=False)
>>> CC.add_cell([1, 2, 3, 4], rank=2)
>>> CC.add_cell([2, 3, 4, 5, 2, 3, 4, 5], rank=2)  # non-regular 2-cell
>>> c1 = tnx.Cell((1, 2, 3, 4, 5, 1, 2, 3, 4, 5), regular=False)
>>> CC.add_cell(c1)
>>> CC.add_cell([5, 6, 7, 8], rank=2)
>>> CC.is_regular
False
classmethod load_mesh(file_path, process: bool = False) → Self[source]#

Load a mesh.

Parameters:
file_pathstr or pathlib.Path

The file path of the data to be loaded.

processbool, default=False

Whether trimesh should process the mesh before loading it.

Returns:
CellComplex

The cell complex corresponding to the mesh.

Notes

file supported : obj, off, glb

Examples

>>> CC = tnx.CellComplex.load_mesh("bunny.obj")
property maxdim: int#

Return maximum dimension.

Returns:
int

The maximum dimension for Cell Complex.

neighbors(node)[source]#

Return nodes in cell complex which share s cell(s) with node.

Parameters:
nodehashable

Node in the cell complex for which to find neighbors.

Returns:
list

List of neighbors.

Raises:
KeyError

If node is not in the cell complex.

node_to_all_cell_adjacnecy_matrix(s: int = 1, weight: str | None = None, index: bool = False) → csc_matrix | tuple[dict, dict, csc_matrix][source]#

Compute s-adjacency matrix between nodes with respect to 2-cells.

Parameters:
sint, default=1

The dimension of the cells to consider.

weightstr, optional

If not given, all nonzero entries are 1.

indexbool, default=False

Whether to return the indices of the rows and columns of the incidence matrix.

Returns:
indicesdict

Dictionary assigning each row and column of the incidence matrix to a node. Only returned if index is True.

scipy.sparse.csr.csc_matrix

The adjacency matrix.

Notes

Two nodes are s-adjacent iff there exists a cell (1 dimensional or 2 dimensional) share contain them.

Examples

>>> CC = tnx.CellComplex()
>>> CC.add_cell([1, 2, 3, 4], rank=2)
>>> CC.add_cell([3, 4, 5], rank=2)
>>> CC.node_to_all_cell_adjacnecy_matrix().todense()
matrix([[0., 2., 1., 2., 0.],
        [2., 0., 2., 1., 0.],
        [1., 2., 0., 3., 2.],
        [2., 1., 3., 0., 2.],
        [0., 0., 2., 2., 0.]])
>>> # observe the contrast with the regular 0-adjacency matrix
>>> CC.adjacency_matrix(0).todense()
matrix([[0., 1., 0., 1., 0.],
        [1., 0., 1., 0., 0.],
        [0., 1., 0., 1., 1.],
        [1., 0., 1., 0., 1.],
        [0., 0., 1., 1., 0.]])
node_to_all_cell_incidence_matrix(weight: str | None = None, index: bool = False) → csc_matrix | tuple[dict, dict, csc_matrix][source]#

Nodes/all cells incidence matrix for the indexed by nodes X cells.

Parameters:
weightstr, optional

The name of the cell attribute to use as weights for the incidence matrix. If None, the matrix is binary.

indexbool, default=False

Whether to return the indices of the rows and columns of the incidence matrix.

Returns:
row_indicesdict

Dictionary assigning each row of the incidence matrix to a node. Only returned if index is True.

col_indicesdict

Dictionary assigning each column of the incidence matrix to a cell. Only returned if index is True.

incidence_matrixscipy.sparse.csr.csc_matrix

The incidence matrix.

property nodes: NodeView#

Return nodes.

Returns:
NodeView

The node view of the Complex.

number_of_cells(cell_set: Iterable[tuple | list | Cell] | None = None) → int[source]#

Compute the number of cells in cell_set belonging to cell complex.

Parameters:
cell_setiterable of cells, optional

Cells can be represented as a tuple, list, or Cell object. If None, then return the number of cells in cell complex.

Returns:
int

The number of cells in cell_set belonging to cell complex.

number_of_edges(edge_set: Iterable[tuple] | None = None) → int[source]#

Compute number of edges in edge_set belonging to cell complex.

Parameters:
edge_setan iterable of edges, optional

If None, then return the number of edges in cell complex.

Returns:
int

The number of edges in edge_set belonging to cell complex.

number_of_nodes(node_set: Iterable[Hashable] | None = None)[source]#

Compute number of nodes in node_set belonging to cell complex.

Parameters:
node_setan iterable of nodes, optional

If None, then return the number of nodes in cell complex.

Returns:
int

Number of nodes in node_set belonging to cell complex.

order() → int[source]#

Compute the number of nodes in the cell complex.

Returns:
int

Number of nodes in the cell complex.

remove_cell(cell: tuple | list | Cell)[source]#

Remove a single cell from Cell Complex.

Parameters:
cellcell’s node_set or Cell

The cell to remove from this cell complex.

Notes

Deletes reference to cell, keep it boundary edges in the cell complex

remove_cells(cell_set: Iterable[tuple | list | Cell])[source]#

Remove cells from a cell complex that are in cell_set.

Parameters:
cell_setiterable of hashables or RankedEntities

The cells to remove from this cell complex.

remove_equivalent_cells() → None[source]#

Remove equivalent cells.

Remove cells from the cell complex which are homotopic. In other words, this is equivalent to identifying cells containing the same nodes and are equivalent up to cyclic permutation.

Notes

Remove all 2d- cells that are homotopic (equivalent to each other)

Examples

>>> G = nx.path_graph(3)
>>> CC = tnx.CellComplex(G)
>>> CC.add_cell([1, 2, 3, 4], rank=2)
>>> CC.add_cell([1, 2, 3, 4], rank=2)
>>> CC.add_cell([2, 3, 4, 1], rank=2)
>>> CC.add_cell([1, 2, 4], rank=2)
>>> CC.add_cell([3, 4, 8], rank=2)
>>> print(CC.cells)
>>> CC.remove_equivalent_cells()
remove_node(node: Hashable) → None[source]#

Remove the given node from the cell complex.

This method removes the given node from the cell complex, along with any cells that contain the node.

Parameters:
nodehashable

The node to be removed from the cell complex.

Raises:
RuntimeError

If the given node does not exist in the cell complex.

remove_nodes(node_set: Iterable[Hashable]) → None[source]#

Remove nodes from cells.

This also deletes references in cell complex nodes.

Parameters:
node_setiterable of hashables or Entities

Nodes in the cell complex.

remove_singletons() → None[source]#

Remove singleton nodes (see CellComplex.singletons()).

restrict_to_cells(cell_set: Iterable[Cell | tuple], keep_edges: bool = False)[source]#

Construct cell complex using a subset of the cells in cell complex.

Parameters:
cell_setIterable[Cell | tuple]

A subset of elements of the cell complex’s cells (self.cells) and edges (self.edges). Cells can be represented as Cell objects or tuples with length > 2.

keep_edgesbool, default=False

If False, discards edges not required by or included in cell_set If True, all previous edges are kept.

Returns:
CellComplex

A new cell complex restricted to the cells in cell_set.

Examples

>>> c1 = tnx.Cell((1, 2, 3))
>>> c2 = tnx.Cell((1, 2, 4))
>>> c3 = tnx.Cell((1, 2, 5))
>>> CC = tnx.CellComplex([c1, c2, c3])
>>> CC.add_edge(1, 0)
>>> cx1 = CC.restrict_to_cells([c1, (0, 1)])
>>> cx1.cells
CellView([Cell((1, 2, 3))])
restrict_to_nodes(node_set: Iterable[Hashable])[source]#

Restrict cell complex to nodes.

This constructs a new cell complex by restricting the cells in the cell complex to the nodes referenced by node_set.

Parameters:
node_setiterable of hashables

The nodes to restrict the cell complex to.

Returns:
CellComplex

A new cell complex restricted to the nodes in node_set.

Examples

>>> c1 = tnx.Cell((1, 2, 3))
>>> c2 = tnx.Cell((1, 2, 4))
>>> c3 = tnx.Cell((1, 2, 5))
>>> CC = tnx.CellComplex([c1, c2, c3])
>>> CC.add_edge(1, 0)
>>> CC.restrict_to_nodes([1, 2, 3, 0])
set_cell_attributes(values: dict[Hashable | tuple | list | Cell, dict] | dict[Hashable | tuple | list | Cell, Any], rank: int, name: str | None = None) → None[source]#

Set cell attributes.

Parameters:
valuesdict

Dictionary of attribute values to set. If name is specified, the dictionary must be of the form cell -> value. Otherwise, the dictionary must be of the form cell -> (attribute -> value).

rank{0, 1, 2}

0 for nodes, 1 for edges, 2 for 2-cells. ranks > 2 are currently not supported.

namestr, optional

Attribute name to use for setting the attribute values.

Notes

If the dict contains cells that are not in self.cells, they are silently ignored.

Examples

After computing some property of the cell of a cell complex, you may want to assign a cell attribute to store the value of that property for each cell:

>>> CC = tnx.CellComplex()
>>> CC.add_cell([1, 2, 3, 4], rank=2)
>>> CC.add_cell([1, 2, 4], rank=2)
>>> CC.add_cell([3, 4, 8], rank=2)
>>> d = {(1, 2, 3, 4): "red", (1, 2, 4): "blue"}
>>> CC.set_cell_attributes(d, name="color", rank=2)
>>> CC.cells[(1, 2, 3, 4)]["color"]
'red'

If you provide a dictionary of dictionaries as the second argument, the entire dictionary will be used to update cell attributes:

>>> G = nx.path_graph(3)
>>> CC = tnx.CellComplex(G)
>>> CC.add_cell([1, 2, 3, 4], rank=2)
>>> CC.add_cell([1, 2, 3, 4], rank=2)
>>> CC.add_cell([1, 2, 4], rank=2)
>>> CC.add_cell([3, 4, 8], rank=2)
>>> d = {

… (1, 2, 3, 4): {“color”: “red”, “attr2”: 1}, … (1, 2, 4): {“color”: “blue”, “attr2”: 3}, … } >>> CC.set_cell_attributes(d, rank=2) >>> CC.cells[(1, 2, 3, 4)][0][“color”] ‘red’

set_cell_data(cell, rank, attr_name: str, attr_value)[source]#

Set data for a specific cell in the complex.

Parameters:
cellstr or tuple

The cell to set data for.

rankint

The rank of the cell.

attr_namestr

The name of the attribute to set.

attr_valueobject

The value to set for the attribute.

Raises:
KeyError

If the specified cell is not found.

Notes

  • For rank 0 cells (nodes), the data is stored in the ‘nodes’ dictionary.

  • For rank 1 cells (edges), the data is stored in the ‘edges’ dictionary.

  • For rank 2 cells (other cells), the data is stored in the ‘cells’ dictionary.

set_edge_attributes(values: dict[tuple, dict] | dict[tuple, Any], name: str | None = None) → None[source]#

Set edge attributes.

Parameters:
valuesdict

Dictionary of attribute values to set. If name is specified, the dictionary must be of the form edge -> value. Otherwise, the dictionary must be of the form edge -> (attribute -> value).

namestr, optional

Attribute name to use for setting the attribute values.

Examples

>>> G = nx.path_graph(3)
>>> CC = tnx.CellComplex(G)
>>> CC.add_cell([1, 2, 3, 4], rank=2)
>>> d = {
...     (1, 2): {"color": "red", "attr2": 1},
...     (2, 3): {"color": "blue", "attr2": 3},
... }
>>> CC.set_edge_attributes(d)
>>> CC.edges[(1, 2)]["color"]
'red'
set_filtration(values: dict[Hashable | tuple | list | Cell, dict] | dict[Hashable | tuple | list | Cell, Any], name: str | None = None) → None[source]#

Set filtration.

Parameters:
valuesdict

Dictionary of filtration values to set. If name is specified, the dictionary must be of the form cell -> value. Otherwise, the dictionary must be of the form cell -> (attribute -> value).

namestr, optional

The attribute name to use to store the filtration values.

Notes

This is equivalent to setting a real-valued feature defined on the entire cell complex

If the dict contains cells that are not in self.cells, they are silently ignored.

Examples

>>> G = nx.path_graph(3)
>>> CC = tnx.CellComplex(G)
>>> d = {0: 1, 1: 0, 2: 2, (0, 1): 1, (1, 2): 3}
>>> CC.set_filtration(d, "f")
set_node_attributes(values: dict[Hashable, dict] | dict[Hashable, Any], name: str | None = None) → None[source]#

Set node attributes.

Parameters:
valuesdict

Dictionary of attribute values to set. If name is specified, the dictionary must be of the form node -> value. Otherwise, the dictionary must be of the form node -> (attribute -> value).

namestr, optional

Attribute name to use for setting the attribute values.

Examples

>>> G = nx.path_graph(3)
>>> CC = tnx.CellComplex(G)
>>> CC.add_cell([1, 2, 3, 4], rank=2)
>>> d = {1: {"color": "red", "attr2": 1}, 2: {"color": "blue", "attr2": 3}}
>>> CC.set_node_attributes(d)
>>> CC[1]["color"]
'red'
property shape: tuple[int, int, int]#

Return shape.

Returns:
tuple[int, int, int]

The tuple containing the number of entities corresponding to the nodes, edges, and cells of the Cell Complex respectively.

singletons()[source]#

Return list of singleton cell.

A singleton cell is a node of degree 0.

Returns:
list of Hashable

List of singleton nodes in this cell complex.

Examples

>>> CC = CellComplex()
>>> CC.add_cell([1, 2, 3, 4], rank=2)
>>> CC.add_cell([2, 3, 4, 5], rank=2)
>>> CC.add_cell([5, 6, 7, 8], rank=2)
>>> CC.add_node(0)
>>> CC.add_node(10)
>>> CC.singletons()
[0, 10]
size(cell: tuple | list | Cell, node_set: Iterable[Hashable] | None = None) → int[source]#

Compute number of nodes in node_set that belong to cell.

If node_set is None then returns the size of cell.

Parameters:
cellhashable

The uid of an cell in the cell complex.

node_setan iterable of node elements

Node elements.

Returns:
int

Number of nodes in node_set that belong to cell.

skeleton(rank: int)[source]#

Compute skeleton.

Parameters:
rank{0, 1, 2}

The rank of the skeleton.

Returns:
Iterable

The atoms of given rank in this complex.

Raises:
ValueError

If rank is not 0, 1 or 2.

to_colored_hypergraph()[source]#

Convert to colored hypergraph.

A cell complex is a type of combinatorial complex. The rank of an element in a cell complex is its dimension, so vertices have rank 0, edges have rank 1, and faces have rank 2.

Returns:
ColoredHyperGraph

The colored hypergraph corresponding to this cell complex.

Examples

>>> CC = tnx.CellComplex()
>>> CC.add_cell([1, 2, 3, 4], rank=2, weight=1)
>>> CC.add_cell([2, 3, 4, 5], rank=2, weight=4)
>>> CC.add_cell([5, 6, 7, 8], rank=2, weight=0)
>>> CC.add_node(0, color="red")
>>> CCC = CC.to_colored_hypergraph()
>>> CCC.cells
to_combinatorial_complex()[source]#

Convert this cell complex to a combinatorial complex.

A cell complex is a type of combinatorial complex. The rank of an element in a cell complex is its dimension, so vertices have rank 0, edges have rank 1, and faces have rank 2.

Returns:
CombinatorialComplex

The combinatorial complex corresponding to this cell complex.

Examples

>>> CC = tnx.CellComplex()
>>> CC.add_cell([1, 2, 3, 4], rank=2, weight=1)
>>> CC.add_cell([2, 3, 4, 5], rank=2, weight=4)
>>> CC.add_cell([5, 6, 7, 8], rank=2, weight=0)
>>> CC.add_node(0, color="red")
>>> CCC = CC.to_combinatorial_complex()
>>> CCC.cells
to_hasse_graph() → DiGraph[source]#

Create Hasse graph of self.

Returns:
nx.DiGraph

A NetworkX Digraph representing the Hasse graph of the Cell Complex.

Examples

>>> CC = tnx.CellComplex()
>>> CC.add_cell([1, 2, 3, 4], rank=2)
>>> CC.to_hasse_graph()
to_hypergraph()[source]#

Convert this cell complex to a hypergraph.

Returns:
Hypergraph

The hyergraph corresponding to this cell complex.

Examples

>>> CC = tnx.CellComplex()
>>> CC.add_cell([1, 2, 3, 4], rank=2, color="red")
>>> CC.add_cell([2, 3, 4, 5], rank=2)
>>> CC.add_cell([5, 6, 7, 8], rank=2)
>>> CC.to_hypergraph()
up_laplacian_matrix(rank: int, signed: bool = True, weight: str | None = None, index: bool = False)[source]#

Compute up laplacian.

Parameters:
rank{0, 1}

dimension of the up Laplacian matrix.

signedbool

Whether the returned laplacian matrix should be signed (i.e., respect orientations) or unsigned.

weightstr, optional

The name of the cell attribute to use as weights for the up laplacian matrix. If None, the matrix is binary.

indexbool, default=False

Whether to return the indices of the rows and columns of the laplacian matrix.

Returns:
row_indices, col_indiceslist

List identifying the rows and columns of the laplacian matrix with the cells of this complex. Only returned if index is True.

up_laplacianscipy.sparse.csr.csr_matrix

The upper laplacian matrix of this cell complex.

Examples

>>> CC = tnx.CellComplex()
>>> CC.add_cell([1, 2, 3, 4], rank=2)
>>> CC.add_cell([3, 4, 5], rank=2)
>>> L1_up = CC.up_laplacian_matrix(1)

>>> CC = tnx.CellComplex()
>>> CC.add_cell([1, 2, 3], rank=2)
>>> CC.add_cell([3, 4, 5], rank=2)
>>> index, L1_up = CC.up_laplacian_matrix(1, index=True)
On this page
Edit on GitHub