/opt/conda/envs/dxtr/lib/python3.12/site-packages/pyvista/plotting/utilities/xvfb.py:48: PyVistaDeprecationWarning: This function is deprecated and will be removed in future version of PyVista. Use vtk-osmesa instead.
  warnings.warn(

Complexes¶

In the following we introduce the main classes of the complexes module: Simplex, AbstractSimplicialComplex, SimplicialComplex and SimplicialManifold. The goal is to showcase their basic manipulations (i.e. instanciation, visualization, reading, writing) and highlight their key features. For more advanced use cases, the interested reader should visit the Dxtr in action section of this documentation.

Simplices¶

Simplices are the geometrical building units that consitute simplicial complexes when combined together. In the Dxtr library, simplices can be instanciated with the Simplex class and a list of indices:

In [2]:

Copied!

from dxtr import Simplex

ids = [0, 1, 2, 3]

splx = Simplex(ids)
from dxtr import Simplex

ids = [0, 1, 2, 3]

splx = Simplex(ids)

Note: the Simplex class is designed as a dataclass, i.e. a minimalist container that is not meant to be extensively modified.

Such a simplex is said to be abstract as it is not embedded in any geometrical space. Maybe the most important property of an abstract simplex is its topological dimension, aka degree (often noted k) are accessible through the dim property. The abstract nature of a simplex can be checked through the isabstract propery:

In [3]:

Copied!

if splx.isabstract:
    print(f'{splx} is an abstract simplex of topological dimension {splx.dim}.')
if splx.isabstract:
    print(f'{splx} is an abstract simplex of topological dimension {splx.dim}.')

Simplex(indices=[0, 1, 2, 3]) is an abstract simplex of topological dimension 3.

In order to get a geometrical simplex, one needs to provide position vectors for its indices:

In [4]:

Copied!





vtcs = [[0, 0, 0], [1, 0, 0], [0, 1, 0], [0, 0, 1]]

splx.set_vertices(vtcs)

if not splx.isabstract:
    print(f'{splx} is not abstract anymore:')
for idx, vtx in zip(splx.indices, splx.vertices):
    print(f'    Its index #{idx} is located at position {vtx}.')
vtcs = [[0, 0, 0], [1, 0, 0], [0, 1, 0], [0, 0, 1]]

splx.set_vertices(vtcs)

if not splx.isabstract:
    print(f'{splx} is not abstract anymore:')
for idx, vtx in zip(splx.indices, splx.vertices):
    print(f'    Its index #{idx} is located at position {vtx}.')

Simplex(indices=[0, 1, 2, 3]) is not abstract anymore:
    Its index #0 is located at position [0 0 0].
    Its index #1 is located at position [1 0 0].
    Its index #2 is located at position [0 1 0].
    Its index #3 is located at position [0 0 1].

Once embedded, simplices acquire some geometrical properties, such as a volume and a circumcenter:

In [5]:

Copied!

vol = splx.volume
cctr = splx.circumcenter

print(f'{splx} is centered around {cctr} and has a volume of {vol:.2e}.')
vol = splx.volume
cctr = splx.circumcenter

print(f'{splx} is centered around {cctr} and has a volume of {vol:.2e}.')

Simplex(indices=[0, 1, 2, 3]) is centered around [0.5 0.5 0.5] and has a volume of 1.67e-01.

Note: The volume of a (k)-simplex, here has to be understood as the k-volume: For a (1)-simplex it is the length of the associated edge, for a (2)-simplex it is the surface area of the associated triangle, for a (3)-simplex, the volume of the associated tetrahedron. This notion can be generalized to any dimension.

Simplices equipped with a geometry can be displayed with the visualize() function from the visu module:

In [6]:

Copied!

from dxtr.visu import visualize

visualize(splx)
from dxtr.visu import visualize

visualize(splx)

Note: For more information about the visu module and its possibilities, please check the dedicated tutorial in the Dxtr in action section of this documentation.

Considered alone, simplices are not very useful. Things get interesting when they are combined into simplicial complexes.

Abstract simplicial complexes¶

An abstract simplicial complexes corresponds to a set of simplices for which no geometrical embedding has been specified. It is therefore a purely topological entity. For further details, check the dedicated paragraph in the DEC in a nutshell section of this documentation.

Within the Dxtr library, such abstract complexes can be instanciated from a list of indices. These indices will form top level simplices of the complex.

Note: At instanciation, a name can be specified, but it is not mandatory.

In [7]:

Copied!

from dxtr.complexes import AbstractSimplicialComplex

top_simplex_indinces = [[0,1,2,3], [1,2,3,4], [4,5,6], [6,7]]

asc = AbstractSimplicialComplex(top_simplex_indinces, name='Gil-Orestel')

print(f'{asc} is an abstract simplicial complex of dim {asc.dim}.')
from dxtr.complexes import AbstractSimplicialComplex

top_simplex_indinces = [[0,1,2,3], [1,2,3,4], [4,5,6], [6,7]]

asc = AbstractSimplicialComplex(top_simplex_indinces, name='Gil-Orestel')

print(f'{asc} is an abstract simplicial complex of dim {asc.dim}.')

dxtr.abstractsimplicialcomplex | INFO: Building a 3-Abstract Simplicial Complex with 2 3-simplices

Gil-Orestel is an abstract simplicial complex of dim 3.

Note: The dimension of an (abstract) simplicial complex corresponds to the topological dimension of its highest-degree simplex.

When instanciated, the AbstractSimplicialComplex class calls a _build_topology() "pseudo-private" method that is directly inspired by the work of Nathan Bell and Anil Hirani in the PyDEC library.

The AbstractSimplicialComplex class is constructed as a list of modules (UserList[Module]). A module corresponds to a list of all the simplices (UserList[Simplex]) with the same degree within the considered simplicial complex.

In [8]:

Copied!





for k, splcs in enumerate(asc):
    print(f'list of ({k})-simplices:')
    for splx in splcs:
        print(f'  - {splx.indices}')
for k, splcs in enumerate(asc):
    print(f'list of ({k})-simplices:')
    for splx in splcs:
        print(f'  - {splx.indices}')

list of (0)-simplices:
  - (np.int64(0),)
  - (np.int64(1),)
  - (np.int64(2),)
  - (np.int64(3),)
  - (np.int64(4),)
  - (np.int64(5),)
  - (np.int64(6),)
  - (np.int64(7),)
list of (1)-simplices:
  - (np.int64(0), np.int64(1))
  - (np.int64(0), np.int64(2))
  - (np.int64(0), np.int64(3))
  - (np.int64(1), np.int64(2))
  - (np.int64(1), np.int64(3))
  - (np.int64(1), np.int64(4))
  - (np.int64(2), np.int64(3))
  - (np.int64(2), np.int64(4))
  - (np.int64(3), np.int64(4))
  - (np.int64(4), np.int64(5))
  - (np.int64(4), np.int64(6))
  - (np.int64(5), np.int64(6))
  - (np.int64(6), np.int64(7))
list of (2)-simplices:
  - (np.int64(0), np.int64(1), np.int64(2))
  - (np.int64(0), np.int64(1), np.int64(3))
  - (np.int64(0), np.int64(2), np.int64(3))
  - (np.int64(1), np.int64(2), np.int64(3))
  - (np.int64(1), np.int64(2), np.int64(4))
  - (np.int64(1), np.int64(3), np.int64(4))
  - (np.int64(2), np.int64(3), np.int64(4))
  - (np.int64(4), np.int64(5), np.int64(6))
list of (3)-simplices:
  - (np.int64(0), np.int64(1), np.int64(2), np.int64(3))
  - (np.int64(1), np.int64(2), np.int64(3), np.int64(4))

The number of simplices of each degree can be obtained either through the shape property of the complex or through the size property of each module:

In [9]:

Copied!





print(f'Number of simplices within {asc}: {asc.shape}.')
print('This means that there are:')
for k, mdl in enumerate(asc):
    print(f'  - {mdl.size} ({k})-simplices.')
print(f'Number of simplices within {asc}: {asc.shape}.')
print('This means that there are:')
for k, mdl in enumerate(asc):
    print(f'  - {mdl.size} ({k})-simplices.')