SimplexTree

SimplexTree.SimplexTree(self, simplices=None, s_type=tuple)

SimplexTree provides lightweight wrapper around a Simplex Tree data structure.

This class exposes a native extension module wrapping a simplex tree implemented with modern C++.

The Simplex Tree was originally introduced in the paper: > Boissonnat, Jean-Daniel, and Clément Maria. “The simplex tree: An efficient data structure for general simplicial complexes.” Algorithmica 70.3 (2014): 406-427.

Attributes

Name Type Description
n_simplices number of simplices
dimension maximal dimension of the complex
id_policy policy for generating new vertex ids
vertices 0-simplices in the complex.
edges 1-simplices in the complex.
triangles 2-simplices in the complex.
quads 3-simplices in the complex.
connected_components connected component ids.

Methods

Name Description
adjacent Finds adjacent vertices of a collection of vertices.
card Returns the cardinality of various skeleta of the complex.
coface_roots Returns the roots whose subtrees span the cofaces of sigma.
cofaces Returns the cofaces of sigma.
collapse Performs an elementary collapse on two given simplices.
contract Performs an pair contraction.
degree Computes the degree of select vertices in the trie.
expand Performs a k-expansion of the complex.
faces Returns the p-faces of a given simplex.
find Finds whether simplices exist in Simplex Tree.
insert Inserts simplices into the Simplex Tree.
link Returns the simplices in the link of sigma.
maximal Returns the maximal simplices in the complex.
reindex Reindexes the vertex labels of the complex.
remove Removes simplices into the Simplex Tree.
simplices Returns the p-simplices in the complex.
skeleton Returns the simplices in the p-skeleton of sigma.
traverse Traverses the simplex tree in the specified order, calling f on each simplex encountered.
vertex_collapse Maps a pair of vertices into a single vertex.

adjacent

SimplexTree.SimplexTree.adjacent(vertices)

Finds adjacent vertices of a collection of vertices.

card

SimplexTree.SimplexTree.card(p=None)

Returns the cardinality of various skeleta of the complex.

Parameters

Name Type Description Default
p Optional[int] dimension parameter. Defaults to None. None

Returns

Name Type Description
cardinalities Union[int, tuple] if p is an integer, the number of p-simplices in the complex. Otherwise a tuple indicating the number of simplices of all dimensions.

coface_roots

SimplexTree.SimplexTree.coface_roots(sigma=[])

Returns the roots whose subtrees span the cofaces of sigma.

Note that sigma itself is included in the set of its cofaces.

Parameters

Name Type Description Default
sigma Collection the simplex to obtain cofaces of. Defaults to the empty set (root node). []

Returns

Name Type Description
coface_roots list[Collection] the coface roots of sigma.

cofaces

SimplexTree.SimplexTree.cofaces(sigma=[])

Returns the cofaces of sigma.

Note, by definition, sigma is defined as a coface of itself.

Parameters

Name Type Description Default
sigma Collection the simplex to obtain cofaces of. []

Returns

Name Type Description
cofaces list[Collection] the cofaces of sigma.

collapse

SimplexTree.SimplexTree.collapse(sigma, tau)

Performs an elementary collapse on two given simplices.

Checks whether its possible to collapse \sigma through \tau, and if so, both simplices are removed. A simplex \sigma is said to be collapsible through one of its faces \tau if \sigma is the only coface of \tau (excluding \tau itself).

Parameters

Name Type Description Default
sigma Collection maximal simplex to collapse required
tau Collection face of sigma to collapse required

Returns

Name Type Description
bool whether the pair was collapsed

Examples

from simplextree import SimplexTree
st = SimplexTree([[0,1,2]])
print(st)
Simplex Tree with (3, 3, 1) (0, 1, 2)-simplices
st.collapse([0,1,2], [1,2])
print(st)
Simplex Tree with (3, 2) (0, 1)-simplices

contract

SimplexTree.SimplexTree.contract(pair)

Performs an pair contraction.

This function performs an pair contraction: given a pair of vertices (va, vb), vertex vb is said to contract to va if vb is removed from the complex and the link of va is augmented with the link of vb.

Some notes about pair are in order: - pair is not sorted like other simplex inputs - The second vertex is always contracted to the first - pair need not be an existing simplex (edge) in the complex - Contraction is not symmetric.

Parameters

Name Type Description Default
pair Collection pair to contract required

Returns

Name Type Description
None whether the pair was contracted

Examples

from simplextree import SimplexTree
st = SimplexTree([[0,1,2]])
st.print()
0 1 2 0 0 1 0
      1 2 2 1
            2
st.contract([0,2])
st.print()
0 1 0
    1

degree

SimplexTree.SimplexTree.degree(vertices=None)

Computes the degree of select vertices in the trie.

Parameters

Name Type Description Default
vertices Optional[ArrayLike] If no vertices are specified, all degrees are computed. Non-existing vertices by default have degree 0. None

Returns

Name Type Description
Union[ArrayLike, int] degree of each vertex id given in ‘vertices’.

expand

SimplexTree.SimplexTree.expand(k, f=None)

Performs a k-expansion of the complex.

This function is particularly useful for expanding clique complexes beyond their 1-skeleton.

Parameters

Name Type Description Default
k int maximum dimension to expand to. required
f Optional[Callable[[Collection], bool]] boolean predicate which returns whether a simplex should added to the complex (and further expanded). None

Examples

from simplextree import SimplexTree
from itertools import combinations
st = SimplexTree(combinations(range(8), 2))
print(st)
Simplex Tree with (8, 28) (0, 1)-simplices
st.expand(2, lambda s: 2 in s)  # Expand only triangles containing 2 as a vertex
print(st)
Simplex Tree with (8, 28, 21) (0, 1, 2)-simplices
st.expand(2) # Expand all 2-cliques
print(st)
Simplex Tree with (8, 28, 56) (0, 1, 2)-simplices

faces

SimplexTree.SimplexTree.faces(p=None, sigma=None)

Returns the p-faces of a given simplex.

find

SimplexTree.SimplexTree.find(simplices)

Finds whether simplices exist in Simplex Tree.

Parameters

Name Type Description Default
simplices Iterable[Collection] Iterable of simplices to insert (each of which are SimplexLike) required

Returns

Name Type Description
found np.ndarray boolean array indicating whether each simplex was found in the complex
Note
    If the iterable is an 2-dim np.ndarray, then the p-simplex to find is given by each contiguous p+1 stride.
    Otherwise, each element of the iterable to casted to a Simplex and then searched for in the tree.

insert

SimplexTree.SimplexTree.insert(simplices)

Inserts simplices into the Simplex Tree.

By definition, inserting a simplex also inserts all of its faces. If the simplex already exists in the complex, the tree is not modified.

Parameters

Name Type Description Default
simplices Iterable[Collection] Iterable of simplices to insert (each of which are SimplexLike) required
Note

If the iterable is an 2-dim np.ndarray, then a p-simplex is inserted along each contiguous p+1 stride. Otherwise, each element of the iterable to casted to a Simplex and then inserted into the tree.

Examples

from simplextree import SimplexTree
st = SimplexTree([range(3)])
print(st)
Simplex Tree with (3, 3, 1) (0, 1, 2)-simplices
st.insert([[0,1]])
print(st)
Simplex Tree with (3, 3, 1) (0, 1, 2)-simplices

maximal

SimplexTree.SimplexTree.maximal()

Returns the maximal simplices in the complex.

reindex

SimplexTree.SimplexTree.reindex(labels=None)

Reindexes the vertex labels of the complex.

remove

SimplexTree.SimplexTree.remove(simplices)

Removes simplices into the Simplex Tree.

By definition, removing a face also removes all of its cofaces. If the simplex does not exist in the complex, the tree is not modified.

Parameters

Name Type Description Default
simplices Iterable[Collection] Iterable of simplices to insert (each of which are SimplexLike). required
Note
    If the iterable is an 2-dim np.ndarray, then a p-simplex is removed along each contiguous p+1 stride.
    Otherwise, each element of the iterable to casted to a Simplex and then removed from the tree.

Examples

st = SimplexTree([range(3)])
print(st)
Simplex Tree with (3, 3, 1) (0, 1, 2)-simplices
st.remove([[0,1]])
print(st)
Simplex Tree with (3, 2) (0, 1)-simplices

simplices

SimplexTree.SimplexTree.simplices(p=None)

Returns the p-simplices in the complex.

skeleton

SimplexTree.SimplexTree.skeleton(p=None, sigma=[])

Returns the simplices in the p-skeleton of sigma.

Note that, when dim(sigma) <= p, sigma is included in the skeleton.

Parameters

Name Type Description Default
p Optional[int] the dimension of the skeleton. None
sigma Collection the simplex to obtain cofaces of. Defaults to the empty set (root node). []

Returns

Name Type Description
list Iterable[Collection] the simplices in the p-skeleton of sigma.

traverse

SimplexTree.SimplexTree.traverse(
    order='preorder',
    f=builtins.print,
    sigma=[],
    p=0,
)

Traverses the simplex tree in the specified order, calling f on each simplex encountered.

Supported traversals include breadth-first / level order (“bfs”, “levelorder”), depth-first / prefix (“dfs”, “preorder”). faces, cofaces, coface roots (“coface_roots”), p-skeleton, p-simplices, maximal simplices (“maximal”), and link.

Where applicable, each traversal begins its traversal sigma, which defaults to the empty set (root node).

Parameters

Name Type Description Default
order str the type of traversal of the simplex tree to execute. 'preorder'
f Callable a function to evaluate on every simplex in the traversal. Defaults to print. builtins.print
sigma Collection simplex to start the traversal at, where applicable. Defaults to the root node (empty set). []
p int dimension of simplices to restrict to, where applicable. Defaults to 0. 0

Returns

Name Type Description
None None

vertex_collapse

SimplexTree.SimplexTree.vertex_collapse(u, v, w)

Maps a pair of vertices into a single vertex.

Parameters

Name Type Description Default
u int the first vertex in the free pair. required
v int the second vertex in the free pair. required
w int the target vertex to collapse to. required

Returns

Name Type Description
collapsed bool whether the collapse was performed.