chalc.filtration

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

Classes

Filtration	Class representing a filtered simplicial complex.
Simplex	Class representing a simplex in a filtered simplicial complex.

Functions

complete_complex(→ Filtration)	Compute the \(k\)-skeleton of the complete simplicial complex on \(n\) vertices.
standard_simplex(→ Filtration)	Compute the filtered simplicial complex corresponding to the standard abstract \(n\)-simplex.

Module Contents

class Filtration(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.

property dimension: int

Current maximum dimension of a maximal simplex in the complex.

get_label_from_vertex_labels(vertices: list[int]) → int

Get the dictionary key of a simplex.

The key of a simplex is its lexicographic index 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

Check if the filtration property is satisfied.

Returns true if each simplex has a filtration value at least as large as each of its faces.

property max_dimension: int

Maximum dimension of simplex that this complex can store.

Set during initialisation.

property max_filtration_time: float

Current maximum filtration value 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.

propagate_colours() → None

Ensure 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.

If propagating upwards, the filtration value of each simplex will be set to the maximum filtration value of any of its faces. If propagating downwards, the filtration value of each simplex will be set to the minimum filtration value of any of its cofaces. For example, setting the filtration values in dimension 1 to edge lengths and propagating upwards gives Rips-type 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, list[int]]]

Compute the boundary matrix of the simplicial complex.

Returns:

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

1. A list containing the indices in x of the facets of \(\sigma\), sorted in ascending order.

2. The lexicographic key of \(\sigma\) in the simplicial complex.

3. The filtration time of \(\sigma\).

4. The set of colours of the vertices of \(\sigma\).

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.

property colours: list[int]

Set of colours of the vertices of the simplex.

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\).

set_colour(colour: int) → None

Change the colour of a vertex.

Raises:

ValueError – If the simplex is not a vertex or if

:raises 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 vertices: list[int]

List of (sorted, ascending) vertex labels of the simplex.

complete_complex(n: int, k: int) → Filtration

Compute the \(k\)-skeleton of the complete simplicial complex on \(n\) vertices.

Filtration values are initialised to zero and all vertices coloured with the colour 0.

standard_simplex(n: int) → Filtration

Compute the filtered simplicial complex corresponding to the standard abstract \(n\)-simplex.

Filtration values are initialised to zero and all vertices coloured with the colour 0.