chalc.filtration¶

Module containing utilities to store and manipulate abstract filtered simplicial complexes.

Classes¶

`FilteredComplex`	Class representing a filtered simplicial complex.
`Simplex`	Class representing a simplex in a filtered simplicial complex.

Functions¶

`clique_complex`(→ FilteredComplex)	Returns the \(k\)-skeleton of the complete simplicial complex on \(n\) vertices, with filtration values initialised to zero and all vertices coloured with the colour 0.
`standard_simplex`(→ FilteredComplex)	Returns the filtered simplicial complex corresponding to the standard abstract \(n\)-simplex, with filtration values initialised to zero and all vertices coloured with the colour 0.

Module Contents¶

class FilteredComplex(n: int, k: int)¶

Class representing a filtered simplicial complex.

add_simplex(vertices: list[int], filt_value: float) → bool¶

Add a simplex to a filtered simplicial complex.

Parameters:

vertices – List of vertex labels corresponding to existing vertices in the complex.
filt_value – Filtration value to associate to the new simplex.

Note

Faces of the added simplex that are already present in the simplicial complex will have their filtration values reduced if necessary.

get_label_from_vertex_labels(vertices: list[int]) → int¶

Returns the dictionary key of a simplex with respect to its vertex labels sorted in ascending order, counting all possible sorted subsequences of \((0, ..., N-1)\) of length \(k\), where \(N\) is the number of vertices in the complex. The simplex need not be present in the simplicial complex.

Parameters:: vertices – List of vertex labels of the simplex.

has_simplex(vertices: list[int]) → bool¶

Check for membership of a simplex in the complex.

Parameters:: vertices – Vertex labels of the simplex to check for.

is_filtration() → bool¶: Returns true if the filtration property is satisfied; that is, if each simplex has a filtration value at least as large as each of its faces.

propagate_colours() → None¶: Function to make sure that simplex colours are consistent with the colours of their vertices. You should call this whenever you change the colour of any vertices.

propagate_filt_values(start_dim: int, upwards: bool = True) → None¶

Propagate filtration values upwards or downwards to ensure that every simplex appears after its faces. For example, setting the filtration values in dimension 1 and propagating upwards is akin to the Rips filtration.

Parameters:

start_dim – Dimension from which to start propagating (exclusive).
upwards – If true then values are propagated upwards, downwards otherwise. Defaults to true.

serialised() → list[tuple[list[int], int, float, int]]¶

Serialised representation of the simplicial complex in a format suitable for persistent homology computations.

Returns:

A list x of simplices in the simplicial complex ordered by dimension followed by filtration time. Each simplex \(\sigma\) is represented by a tuple containing the following items.

A list containing the indices in x of the facets of \(\sigma\), sorted in ascending order.
The lexicographic key of \(\sigma\) in the simplicial complex.
The filtration time of \(\sigma\).
The colour bitmask of \(\sigma\).

property dimension: int¶: Current maximum dimension of a maximal simplex in the complex.

property max_dimension: int¶: Maximum dimension of simplex that this complex can store. Set during initialisation.

property max_filtration_time: float¶: Current maximum dimension of a maximal simplex in the complex.

property num_simplices: int¶: The total number of simplices in the complex.

property num_vertices: int¶: Number of vertices in the simplicial complex. Set during initialisation.

property simplices: list[dict[int, Simplex]]¶: A list such that simplices[k] is a dictionary of handles to the \(k\)-simplices in the complex. The key of a \(k\)-simplex in simplices[k] is the lexicographic index of that simplex with respect to its vertex labels sorted in ascending order, counting all possible sorted subsequences of \((0, ..., N-1)\) of length \(k\).

class Simplex¶

Class representing a simplex in a filtered simplicial complex.

set_colour(colour: int) → None¶

Change the colour of a vertex.

Raises:: ValueError – If the simplex is not a vertex or if colour >= MaxColoursChromatic.

Tip

It is recommended to call the member function propagate_colours() from the parent simplicial complex after changing the colour of a vertex.

property colours: int¶: Bitmask of colours in the simplex, where the rightmost bit represents the smallest colour index. More precisely, \(\mathrm{bitmask} = \sum_{c \in \mathrm{colours}(\sigma)} 2^c\). For example, a simplex having vertices of colours 0 and 1 has a colour bitmask of 3.

property dimension: int¶: Dimension of the simplex.

property facets: list[Simplex]¶: Read-only list of handles to the facets of the simplex.

property filtration_value: float¶: Filtration value of the simplex. If you modify this value, you should call propagate_filt_values() from the parent complex to ensure that filtration times remain monotonic.

property label: int¶: Label of the simplex in its parent filtered complex. A \(k\)-simplex \(\sigma\) is labelled by the lexicographic index of \(\sigma\) with respect to its vertex labels sorted in ascending order, counting all possible sorted subsequences of \((0, ..., N-1)\) of length \(k\).

property vertices: list[int]¶: List of (sorted, ascending) vertex labels of the simplex.

clique_complex(n: int, k: int) → FilteredComplex¶: Returns the \(k\)-skeleton of the complete simplicial complex on \(n\) vertices, with filtration values initialised to zero and all vertices coloured with the colour 0.

standard_simplex(n: int) → FilteredComplex¶: Returns the filtered simplicial complex corresponding to the standard abstract \(n\)-simplex, with filtration values initialised to zero and all vertices coloured with the colour 0.