Python package docs¶

InDelsTopo: A Python package to analyze topological properties of sets of words when their main source of variation are insertions and deletions, using the Insertion Chain Complex framework.

`version = '0.1.0'` `module-attribute` ¶

`Block` ¶

Bases: ChainBlockBase

Represents a Block in the Insertion Chain Complex.

A Block can be a valid block or "0" if the provided data corresponds to an invalid block. It has the formal expression x_0(1,a_1)x_1...(1,a_m)x_m, where the a_i are single symbols from an alphabet, and the x_i are words over that alphabet (including possibly the empty word). Internally, blocks are stored as a list of factors x_0, ..., x_k and a list of edge symbols a_1, ..., a_k, represented as SymPy expressions and symbols.

Blocks can be initialized from a string expression or directly via x_factors and edges.

Attributes:

Name	Type	Description
`dim`	`int`	Number of edges (dimension) of the block.
`max_word`	`SymPy expression`	Maximal word of the block.
`min_word`	`SymPy expression`	Minimal word of the block.
`#`	`_x_factors (list of SymPy expressions or int`	Factors of the block.
`#`	`_edges (list of SymPy symbols`	Symbols forming the edges of the block.
`#`	`_alphabet (Alphabet`	Alphabet used for letters in the block.
`#`	`_expression (SymPy expression`	SymPy product representing the block.

Initializes a Block.

A Block can be either a valid block or the zero block. It is internally represented by a list of factors _x_factors and a list of edge symbols _edges.

The block can be initialized from

A string expression in the form "x_0(1,a_1)x_1...(1,a_m)x_m" (handling powers '^' or '*' and product symbols '', '.', or concatenation),
Directly from _x_factors and _edges lists,

Parameters:

Name	Type	Description	Default
`expression`	`str`	String representation of the block.	`None`
`alphabet`	`Alphabet`	Alphabet defining the letters. Defaults to an empty Alphabet.	`None`
`prod_symbol`	`str`	Product symbol to use ('', '*', or '.'). Inferred from the expression if None.	`None`
`x_factors`	`list of SymPy expressions or int`	Factors x_0, ..., x_k of the block.	`[int(0)]`
`edges`	`list of SymPy symbols`	Edge symbols a_1, ..., a_k corresponding to the block.	`None`

`get_face` ¶

Return the face σ(indices_plus, indices_minus) of the block σ.

indices_plus and indices_minus are disjoint subsets of {1, ..., m}, where m is the dimension of the block. They must be given as lists of integers, and may be empty. The output is the block σ(indices_plus, indices_minus), which is either a valid Block of dimension m − |indices_plus ∪ indices_minus| or the zero Block.

Parameters:

Name	Type	Description	Default
`indices_plus`	`list of int`	Indices in {1, ..., m} of edges (1, a_i) collapsed to a_i.	required
`indices_minus`	`list of int`	Indices in {1,..., m} of edges (1, a_i) collapsed to 1.	required

Returns:

Name	Type	Description
`face`	`Block`	The resulting face block σ(indices_plus, indices_minus) if valid, or the zero Block, otherwise.

`get_upper_facets` ¶

Return the list of upper facets of the block.

Each upper facet is obtained by collapsing a single edge (1, a_i) to a_i, for i = 1, ..., m, where m is the dimension of the block.

Returns:

Name	Type	Description
`upper_facets`	`list[Block]`	A list of Blocks representing the upper facets of the block.

`get_lower_facets` ¶

Return the list of lower facets of the block.

Each lower facet is obtained by collapsing a single edge (1, a_i) to 1, for i = 1, ..., m, where m is the dimension of the block. Invalid blocks are excluded from the output.

Returns:

Type	Description
	list of Block: A list of valid Blocks representing the lower facets of the block.

`get_all_facets` ¶

Return all facets of the block. Combines both the upper and lower facets of the block.

Returns:

Type	Description
	list of Block: A list of Blocks representing all facets of the block.

`get_all_faces` ¶

Return all faces of the block, ordered by dimension.

Faces are obtained recursively by taking all facets of the block, then all facets of those facets, and so on, down to dimension 0.

Parameters:

Name	Type	Description	Default
`include_self`	`bool`	If True, include the block itself in the returned list. Defaults to False.	`False`

Returns:

Type	Description
	list of Block: A list of Blocks representing all faces, orted by increasing dimension.

`get_vertex` ¶

Return the vertex v_I(σ) of the block determined by a sequence of I = indices.

The vertex is obtained by collapsing the edges (1,a_i) indexed by 'I' into a_i, and the remaining ones to 1. Returns the vertex as a 0-block, or as a SymPy expression if as_word=True.

Parameters:

Name	Type	Description	Default
`indices`	`list of int`	Indices in {1,..., dim(σ)}	required
`as_word`	`bool`	If True, return the vertex as a SymPy expression (word). If False, return the corresponding Block. Defaults to True.	`True`

Returns:

Type	Description
	Block or SymPy Expression: The resulting vertex as a Block or Sympy expression,
	depending on `as_word`.

`get_all_vertices` ¶

Return all vertices of the block.

Parameters:

Name	Type	Description	Default
`as_words`	`bool`	If True, return vertices as SymPy expressions (words). If False, return them as Block objects. Defaults to True.	`True`

Returns:

Type	Description
	list of Block or SymPy Expression: All vertices of the block as Blocks
	or words, depending on `as_words`.

`boundary` ¶

Computes the boundary of a block.

`Chain` ¶

Bases: ChainBlockBase

Represents a chain in the Insertion Chain Complex: a linear combination of valid blocks with integer coefficients.

It can be initialized from a string expression, a list of coefficients and blocks, or a dictionary mapping blocks to coefficients.

Supports algebraic operations (addition, subtraction, and scalar multiplication), equality checking, string and LaTeX representations, and computation of the boundary.

Attributes:

Name	Type	Description
`dim`	`int`	Maximum dimension among the blocks in the chain, or -1 if empty.
`_expression(SymPy`	`expression`	represents the chain as a sum of block expressions.
`_alphabet`	`Alphabet`	The Alphabet instance used for all blocks in the chain.
`_dict_blocks`	`dict`	(for internal use only) dictionary mapping Block objects to integer coefficients.
`_prod_symbol`	`str`	Either '', '*', or '.'.

Represents a chain in the Insertion Chain Complex: a linear combination of valid blocks with integer coefficients.

Each term can include an integer coefficient followed by a block, e.g., '2abc(1,a)b^ac(1,b)ac - (1,c)(1,a)b^2'.

The class can be initialized from

a string expression (preferred way for end users),
a list of coefficients and blocks, or
a dictionary mapping blocks to coefficients.

Parameters:

Name	Type	Description	Default
`expression`	`str`	Chain written as a string of blocks. This is the preferred way for end users to construct a chain.	`None`
`alphabet`	`Alphabet`	Alphabet object defining the set of letters. If set to None, a new empty alphabet is created.	`None`
`prod_symbol`	`str`	Product symbol to use in blocks. Must be one of {'', '', '.'}. If None, it is inferred from the expression: '' if '*' appears, '.' if '.' appears, or '' otherwise.	`None`
`list_coeffs`	`list of int`	Integer coefficients of the chain terms. Must be provided together with `list_blocks`. Ignored if `expression` or `dict_blocks` is given.	`None`
`list_blocks`	`list of Block`	Block objects corresponding to the coefficients in `list_coeffs`. Ignored if `expression` or `dict_blocks` is given.	`None`
`dict_blocks`	`dict`	Dictionary mapping Block objects to integer coefficients. If provided, it takes precedence over `expression`,`list_coeffs`, and `list_blocks`.	`None`

`boundary` ¶

Return the boundary of the chain as a new Chain.

`get_dict_blocks` ¶

Return a copy of the internal blocks dictionary.

`Alphabet` ¶

Represents an alphabet of symbols used to build words.

Each symbol in the alphabet is represented as a noncommutative SymPy symbol. For every letter, an associated "edge" symbol (or 1-block symbol) is also created. For example, the letter 'a' has a corresponding edge symbol '(1,a)'. Internally, these symbols are handled as elements of a noncommutative SymPy monoid, allowing symbolic manipulations of words as products.

This class provides methods to: - Add individual letters. - Update the alphabet with multiple new letters. - Convert words (sequences of letters) into symbolic products of letters.

Attributes:

Name	Type	Description
`letters`	`dict`	Maps letter strings to their SymPy symbol representation.
`edges`	`dict`	Maps letter strings to their corresponding edge (1-block) symbols.
`letters_str`	`list`	List of letter strings currently in the alphabet.

Initialize an Alphabet with optional letters.

Parameters:

Name	Type	Description	Default
`letters_str`	`list of str`	Initial letters for the alphabet. If None, an empty alphabet is created. Duplicate letters are removed.	`None`

Side Effects

Initializes the following attributes: - letters (dict): Maps letter strings to SymPy symbols. - edges (dict): Maps letter strings to corresponding edge symbols. - letters_str (list): List of unique letter strings in the alphabet.

`get` ¶

Return the symbolic representation of a letter or its edge.

Parameters:

Name	Type	Description	Default
`letter`	`str`	The letter to retrieve.	required
`dim`	`int`	Dimension; 0 for the letter symbol, 1 for the edge symbol. Defaults to 0.	`0`

Returns:

Type	Description
	SymPy.Symbol: The corresponding SymPy symbol.

`add_letter` ¶

Add a new letter to the alphabet if it does not already exist.

Parameters:

Name	Type	Description	Default
`symbol`	`str`	The new letter to add.	required

`update_letters` ¶

Add multiple letters to the alphabet, ignoring duplicates.

Parameters:

Name	Type	Description	Default
`letters_str`	`iterable of str`	letters to add.	required

`cast_word` ¶

Convert a word (sequence of letters) into a symbolic product.

Parameters:

Name	Type	Description	Default
`word`	`iterable of str`	The word to convert, as a list of symbols or a string.	required
`check_letters`	`bool`	If True, updates the alphabet with any new letters found in the word. Defaults to True.	`True`

Returns:

Name	Type	Description
`expression`	`Expr`	SymPy expression of the word, using the symbols in this alphabet.

`Filtration` ¶

Represents a lower-star filtration on a Letter Insertion Chain Complex C[W], for a set of words W with associated heights.

It stores the blocks of the complex at each dimension with their corresponding heights. Provides methods for computing the Euler Characteristic Curve, persistent homology barcodes (with Z/Z2 coefficients), and a graphical representation of (accurate for low dimensions).

One can access the k-th dimensional blocks by indexing the filtration as 'K[k]'. This returns a dictionary mapping each k-block to its height.

Attributes:

Name	Type	Description
`dim`	`int`	Maximum dimension of the filtration.
`filtration_dict`	`dict`	Maps dimension d to a dictionary of blocks and their heights.
`filtration_values`	`list`	Sorted list of heights used in the filtration.
`_alphabet`	`Alphabet`	Alphabet containing all symbols in W.
`_prod_symbol`	`str`	Product symbol used for constructing blocks ('*', '.', or '' for concatenation).
`_positions_dict`	`dict or None`	Stores vertex positions for graph representations.

Notes

It initializes as an empty filtration. It can be made into the filtration of insertion chain complexes of a set of words W by using the method compute_d_skeleton(W, heights).
Blocks can be added or removed by using the methods add_blocks and remove_blocks.

Example:

>>> W = ["ab", "aab", "abb"]
>>> heights = [0.1, 0.3, 0.5]
>>> K = Filtration() # Creates an empty complex
>>> K.compute_d_skeleton(W, heights, max_dim=5) # makes K = a filtration of C[W]
>>> K[1]  # Access 1-dimensional blocks and their heights
{a(1,a)b: 0.3, ab(1,b): 0.5}

Returns an empty Filtration object.

Parameters:

Name	Type	Description	Default
`alphabet`	`Alphabet`	Alphabet object defining valid symbols. If None, a new empty `Alphabet` is created.	`None`
`prod_symbol`	`str`	The product symbol to use. Must be one of {'', '', '.'}. If None, it is inferred from the expression: set to '' if '*' appears, to '.' if '.' appears, or to '' (concatenation) otherwise.	`None`

`compute_d_skeleton` ¶

Compute the d-skeleton of the Insertion Chain Complex generated by a set of words, C[W]. This method replaces any existing data in the Filtration with a new complex supported on W.

This method constructs all valid blocks up to the specified maximum dimension (max_dim) for a given set of words W with associated heights. It begins by computing the 0- and 1-skeletons (vertices and edges), then iteratively extends to higher dimensions.

It updates the internal filtration_dict to the blocks supported on W.

Parameters:

Name	Type	Description	Default
`W`	`list of str or Block`	List of words (or blocks, if `already_blocks=True`) forming the base of the complex.	required
`heights`	`list of float`	Height values associated with each word. If None, defaults to ones.	`None`
`max_dim`	`int`	Maximum dimension of the skeleton to compute. Defaults to 10.	`10`
`alphabet`	`Alphabet`	Alphabet object used together with the internal `self._alphabet` and any letters inferred from `W`. If provided, its symbols are merged with `self._alphabet`; otherwise, the new symbols are inferred entirely from the given words.	`None`
`prod_symbol`	`str`	Product symbol for block construction ('*', '.', or ''). If None, inferred automatically.	`None`
`check_duplicates`	`bool`	Whether to verify that input words are unique. Defaults to True.	`True`
`already_blocks`	`bool`	If True, assumes the input `W` is already a list of `Block` objects instead of strings. Defaults to False.	`False`
`verbose`	`bool`	If True, prints progress information during computation.	`False`

Example:

>>> W = ['a*b', 'a*b*b', 'a*a*b','']
>>> K = Filtration()
>>> K.compute_d_skeleton(W, heights=[0.1, 0.3, 0.2,0.4], max_dim=2)
>>> K[1]
{a*b*(1,b): 0.3, a*(1,a)*b: 0.2}

`add_blocks` ¶

Add new blocks to the Filtration.

Extends the current Filtration by inserting additional blocks and their faces. This method allows dynamically modifying an existing filtration while ensuring, as much as possible, that the result remains a valid filtration (i.e., if α ≤ β, then F.get_complex(α) ⊆ F.get_complex(β)).

Intended for expert use only, since the resulting structure may not always be a full Insertion Chain Complex C[W], but rather a subcomplex if some supporting blocks are missing. The result may depend on the order in which the blocks are provided.

The behavior depends on the value of update_values:

- If ``update_values=True``, the heights of existing faces and super-faces
  are updated as needed to maintain the filtration property. This ensures
  that the new blocks can be inserted with the provided heights.

- If ``update_values=False`` (default), the method adds the blocks only if
  their heights are consistent with the current filtration. Otherwise, the
  maximum among the heights of their faces is used instead.

Parameters:

Name	Type	Description	Default
`list_blocks`	`list[Block] or list[str]`	List of blocks to be added to the Filtration. If `already_blocks` is False (default), the elements are assumed to be strings representing blocks and will be converted. If True, they are assumed to be existing `Block` objects.	required
`list_heights`	`list[float] or float or None`	Heights assigned to each block. If a single numeric value is provided, it is used for all blocks. If None, all blocks receive height 1.	`None`
`prod_symbol`	`str or None`	Product symbol used in block representation (e.g., '*', '.', or ''). If not specified, it is inferred from the input blocks.	`None`
`already_blocks`	`bool`	If True, elements of `list_blocks` are assumed to be valid `Block` objects. If False (default), the method attempts to convert the input into blocks.	`False`
`update_values`	`bool`	If True, existing heights of faces and super-faces are updated as needed to maintain consistency when inserting the new blocks. If False (default), only new faces are added and the provided heights are applied when valid; otherwise, the lowest consistent height is used instead.	`False`

Raises:

Type	Description
`ValueError`	If `list_heights` is a list whose length does not match `list_blocks`. If `list_heights` is not a list, a numeric value, or None. If the height of a block is lower than the height of one of its faces already present in the filtration (when `update_values=False`).

Notes

The internal alphabet and product symbol are updated to ensure consistency.
The resulting filtration may vary depending on the order in which blocks are inserted.
Updating an existing filtration in this way may be more computationally expensive than reconstructing a new Filtration directly from a set of words.

`remove_blocks` ¶

Remove blocks from the Filtration.

Deletes specified blocks and optionally their super-faces from the Complex. Intended for expert use only, since the resulting structure may not be a full Insertion Chain Complex C[W], but rather a subcomplex if some supported blocks are missing.

Parameters:

Name	Type	Description	Default
`list_blocks`	`list of Block or string`	A list of blocks to remove. If `already_blocks` is False (default), the elements are assumed to be strings representing blocks and will be converted. If True, they are assumed to be existing Block objects.	required
`prod_symbol`	`str or None`	Product symbol used in block representation ( '*', '.', or ''). If not specified, it is inferred from the input blocks.	`None`
`include_upfaces`	`bool`	If True, all super faces of the specified blocks are also removed, so the result is a subcomplex. Default is True.	`True`
`already_blocks`	`bool`	If True, the elements of `list_blocks` are assumed to be valid Block objects. If False (default), the method attempts to convert the input into blocks.	`False`

`get_complex` ¶

Constructs and returns a Complex object that includes all blocks from the filtration whose height is less than or equal to the specified value. The construction can also be limited to a specified maximum dimension.

Parameters:

Name	Type	Description	Default
`height`	`float or int`	The maximum filtration value to include. If None, the largest available filtration value is used.	`None`
`max_dim`	`int`	The maximum dimension to include in the complex. If None, the full dimension of the filtration is used.	`None`

Returns:

Name	Type	Description
`complex`	`Complex`	A Complex object containing all blocks up to the specified height and dimension.

`get_euler_curve` ¶

This method evaluates the Euler characteristic of the complex at different filtration heights and returns the resulting curve as paired x- and y-values.

Parameters:

Name	Type	Description	Default
`x_values`	`list of float or int`	Filtration heights at which to compute the Euler characteristic. If None, all existing filtration values are used.	`None`

Returns:

Name	Type	Description
`tuple`		list of float or int: Sorted filtration heights (x-values). list of int: Corresponding Euler characteristic values (y-values).

`get_persistent_homology_barcodes` ¶

Compute persistent homology barcodes for the filtration using Z2 coefficients.

The method performs a lower-star filtration on the complex according to the vertex heights and computes persistent homology up to the specified dimension.

Parameters:

Name	Type	Description	Default
`max_dim`	`int`	Maximum dimension to compute accurately. The skeleton of dimension up to max_dim+1 is used for this computation if it was previously computed. If None or greater than the filtration's dimension, all dimensions are included.	`None`
`inf_value`	`float`	Value to assign to features that do not die within the filtration. Defaults to infinity.	`inf`
`get_height_indices`	`bool`	If True, also return the indices corresponding to the birth and death heights in the filtration. Defaults to False.	`False`

Returns:

Type	Description
	dict or tuple: - If `get_height_indices=False`: A dictionary mapping dimension `d` to a list of tuples `(birth, death)` representing persistent homology intervals. - If `get_height_indices=True`: A tuple of two dictionaries: 1. Barcodes as above. 2. Corresponding indices of birth and death heights in `filtration_values`.

Notes

The algorithm uses a boundary matrix over Z2 and reduces it following the standard persistence algorithm (see arxiv:1506.08903). Features that never die are assigned inf_value as their death time.

`get_graph` ¶

Generate a graphical representation of the filtration up to a specified dimension.

Positions of vertices can be computed automatically or provided manually. Only accurate for low-dimensional complexes (typically dim <= 3).

Parameters:

Name	Type	Description	Default
`height`	`float`	Maximum height value for including blocks in the graph. Defaults to the maximum filtration value.	`None`
`height_id`	`int`	Index into the sorted list of filtration values. Used if `height` is None. Defaults to None.	`None`
`show_labels`	`bool`	Whether to display labels on the vertices. Defaults to True.	`True`
`max_dim`	`int`	Maximum dimension of blocks to include in the graph. Defaults to 5.	`5`
`positions`	`dict`	Dictionary of vertex positions. If None, positions are computed automatically. Once computed, they are reused everytime this method is called, unless recompute is set to True.	`None`
`initial_positions`	`dict`	Initial positions used to seed the automatic layout algorithm.	`None`
`fixed`	`list or None`	List of vertex keys to fix in place when computing positions. Defaults to None.	`None`
`recompute`	`bool`	Whether to recompute vertex positions even if already stored. Defaults to False.	`False`
`colors_by_dim`	`list of str`	List of colors to use for each dimension. If None, defaults to ['black', 'gray', 'yellow', 'red', 'blue', 'purple'].	`None`
`ax`	`Axes3DSubplot`	A Matplotlib Axes object to draw the plot on. If None, a new figure and axes are created. Defaults to None.	`None`

Returns:

Type	Description
	matplotlib.axes.Axes: Matplotlib axes object containing the drawn graph.

`get_alphabet` ¶

Returns the alphabet attribute.

`get_block_height` ¶

Returns the height of the block in the filtration or None if it is not in the filtration.

Parameters:

Name	Type	Description	Default
`block`	`Block or string`	A block to check its height. If `already_blocks` is False (default),	required
`already_block`	`bool`	If True, `block` is assumed to be a valid Block object. If False (default), the method attempts to convert the input into a block.	`False`

`Complex` ¶

Represents an Insertion Chain Complex C[W] for a set of words W.

The class stores the blocks of the complex in each dimension and provides methods to compute topological invariants such as the Euler characteristic and Betti numbers (over Z_2 or Z when using a SageMath kernel). It also supports graphical visualization of the complex in low dimensions.

The k-dimensional blocks can be accessed via indexing syntax: K[k] returns the list of k-blocks.

Attributes:

Name	Type	Description
`dim`	`int`	Maximum dimension of the complex.
`complex_dict`	`dict[int, list[Block]]`	Maps each dimension to its corresponding list of blocks.
`height`	`float \| None`	Height value associated with the complex.
`_alphabet`	`Alphabet`	Alphabet object containing all symbols used in W.
`_prod_symbol`	`str`	Product symbol used in the blocks.
`_positions_dict`	`dict \| None`	Stores vertex positions for graphical visualization.

Notes

This class can be used to build and analyze Insertion Chain Complexes directly, or as a sublevel complex of a filtration.
Homology computations over Z require SageMath; otherwise, only Z_2 computations are available using SciPy.
It initializes as an empty complex. It can be made into the insertion chain complex of a set of words W by using the method compute_d_skeleton(W).
Blocks can be added or removed by using the methods add_blocks and remove_blocks.

Example:

>>> W = ["ab", "aab", "abb"]
>>> K = Complex() # Creates an empty complex
>>> K.compute_d_skeleton(W) # makes K = C[W]
>>> K[1]  # Access 1-dimensional blocks
[a(1,a)b, ab(1,b)]

Initialize an Insertion Chain Complex.

This constructor creates a new complex object, which can either start empty (with no blocks) or be initialized from a given dictionary of blocks. Optionally, the complex can store a height value, useful when representing a level in a filtration.

Parameters:

Name	Type	Description	Default
`alphabet`	`Alphabet \| None`	The alphabet containing all symbols to be used. Defaults to None.	`None`
`prod_symbol`	`str \| None`	Product symbol used for block construction, Must be one of {'', '', '.'}. If None, it is inferred from the expression: set to '' if '*' appears, to '.' if '.' appears, or to '' (concatenation) otherwise.	`None`
`complex_dict`	`dict[int, list[Block]] \| None`	Mapping from dimension `d` to the list of d-dimensional blocks. If provided, it initializes the complex structure directly. Defaults to None.	`None`
`height`	`float \| None`	Height value associated with the complex, used when part of a filtration. Defaults to None.	`None`

`compute_d_skeleton` ¶

Compute the d-skeleton of the Insertion Chain Complex generated by a set of words, C[W]. This method replaces any existing data in the Complex with a new complex supported on W.

This method constructs all valid blocks up to the specified maximum dimension (max_dim) for a given set of words W. It begins by computing the 0- and 1-skeletons (vertices and edges), then iteratively extends to higher dimensions.

It updates the internal complex_dict to the blocks supported on W.

Parameters:

Name	Type	Description	Default
`W`	`list of str or Block`	List of words (or blocks, if `already_blocks=True`) forming the base of the complex.	required
`height`	`float`	Height value associated with the complex, used when part of a filtration. Defaults to None.	`None`
`max_dim`	`int`	Maximum dimension of the skeleton to compute. Defaults to 10.	`10`
`alphabet`	`Alphabet`	Alphabet object used together with the internal `self._alphabet` and any letters inferred from `W`. If provided, its symbols are merged with `self._alphabet`; otherwise, the new symbols are inferred entirely from the given words.	`None`
`prod_symbol`	`str`	Product symbol for block construction ('*', '.', or ''). If None, inferred automatically.	`None`
`check_duplicates`	`bool`	Whether to verify that input words are unique. Defaults to True.	`True`
`already_blocks`	`bool`	If True, assumes the input `W` is already a list of `Block` objects instead of strings. Defaults to False.	`False`
`verbose`	`bool`	If True, prints progress information during computation.	`False`

Example:

>>> W = ['a*b', 'a*b*b', 'a*a*b','']
>>> K = Filtration()
>>> K.compute_d_skeleton(W, heights=[0.1, 0.3, 0.2,0.4], max_dim=2)
>>> K[1]
{a*b*(1,b): 0.3, a*(1,a)*b: 0.2}

`get_maximal_blocks` ¶

Return the maximal blocks of the complex, ordered by subfaces.

A block is maximal if it is not a subface of any higher-dimensional block. The method identifies all such maximal blocks in each dimension and returns them as a dictionary.

Returns:

Type	Description
	dict[int, list[Block]]: A dictionary mapping each dimension to a list
	of maximal blocks (i.e., blocks not covered by higher-dimensional ones).

Notes

Empty dimensions are removed from the output dictionary.

`get_complex` ¶

Return a subcomplex of the current complex up to the specified dimension.

If max_dim is not provided or is greater than or equal to the current dimension, the method returns the complex itself. Otherwise, it returns a new Complex object containing only the blocks up to dimension max_dim.

Parameters:

Name	Type	Description	Default
`max_dim`	`int or None`	Maximum dimension of blocks to include in the returned complex. If None or greater than the complex dimension, the full complex is returned.	`None`

Returns:

Name	Type	Description
`Complex`		A subcomplex containing blocks up to dimension `max_dim`.

`add_blocks` ¶

Add new blocks to the Complex.

Extends the current Complex by inserting additional blocks and their faces. Intended for expert use only, since the resulting structure may not be a full Insertion Chain Complex C[W], but rather a subcomplex if some supported blocks are missing.

Parameters:

Name	Type	Description	Default
`list_blocks`	`list[Block] or list[str]`	List of blocks to be added to the Filtration. If `already_blocks` is False (default), the elements are assumed to be strings representing blocks and will be converted. If True, they are assumed to be existing `Block` objects.	required
`prod_symbol`	`str or None`	Product symbol used in block representation ('*', '.', or ''). If not specified, it is inferred from the input blocks.	`None`
`already_blocks`	`bool`	If True, elements of `list_blocks` are assumed to be valid `Block` objects. If False (default), the method attempts to convert the input into blocks.	`False`

Notes

The internal alphabet and product symbol are updated to ensure consistency.

`remove_blocks` ¶

Remove blocks from the Complex.

Deletes specified blocks and optionally their super-faces from the Complex. Intended for expert use only, since the resulting structure may not be a full Insertion Chain Complex C[W], but rather a subcomplex if some supported blocks are missing.

Parameters:

Name	Type	Description	Default
`list_blocks`	`list of Block or string`	A list of blocks to remove. If `already_blocks` is False (default), the elements are assumed to be strings representing blocks and will be converted. If True, they are assumed to be existing Block objects.	required
`prod_symbol`	`str or None`	Product symbol used in block representation ( '*', '.', or ''). If not specified, it is inferred from the input blocks.	`None`
`include_upfaces`	`bool`	If True, all super faces of the specified blocks are also removed, so the result is a subcomplex. Default is True.	`True`
`already_blocks`	`bool`	If True, the elements of `list_blocks` are assumed to be valid Block objects. If False (default), the method attempts to convert the input into blocks.	`False`

`euler_characteristic` ¶

This method computes the Euler characteristic of the complex.

`get_graph` ¶

Generate a graphical representation of the complex up to a specified dimension.

Positions of vertices can be computed automatically or provided manually. Only accurate for low-dimensional complexes (typically dim <= 3).

Parameters:

Name	Type	Description	Default
`show_labels`	`bool`	Whether to display labels on the vertices. Defaults to True.	`True`
`max_dim`	`int`	Maximum dimension of blocks to include in the graph. Defaults to 5.	`5`
`positions`	`dict`	Dictionary of vertex positions. If None, positions are computed automatically. Once computed, they are reused everytime this method is called, unless recompute is set to True.	`None`
`initial_positions`	`dict`	Initial positions used to seed the automatic layout algorithm.	`None`
`fixed`	`list or None`	List of vertex keys to fix in place when computing positions. Defaults to None.	`None`
`recompute`	`bool`	Whether to recompute vertex positions even if already stored. Defaults to False.	`False`
`colors_by_dim`	`list of str`	List of colors to use for each dimension. If None, defaults to ['black', 'gray', 'yellow', 'red', 'blue', 'purple'].	`None`
`ax`	`Axes3DSubplot`	A Matplotlib Axes object to draw the plot on. If None, a new figure and axes are created. Defaults to None.	`None`

Returns:

Type	Description
	matplotlib.axes.Axes: Matplotlib axes object containing the drawn graph.

`get_betti_numbers_z2` ¶

Returns the betti numbers in Z_2 coefficients up to the specified dimension max_dim.

`get_chain_complex_sage` ¶

Construct and return the associated chain complex as a SageMath object.

This method is intended to be used in a SageMath kernel. It builds a chain complex using Sage's ChainComplex() constructor. Optionally, it can also return the blocks sorted within each dimension.

Parameters:

Name	Type	Description	Default
`get_ordered_blocks`	`bool`	If True, also return the blocks ordered by their expressions within each dimension. Defaults to False.	`False`

Returns:

Type	Description
	ChainComplex or tuple[ChainComplex, dict[int, list[Block]]]: - If `get_ordered_blocks` is False, returns a ChainComplex object representing the boundary operators. - If `get_ordered_blocks` is True, returns a tuple `(ChainComplex, Blocks_ordered)`, where `Blocks_ordered` is a dictionary of lists of blocks sorted by expression.

Notes: - Requires SageMath to be installed and accessible in the current environment. - If SageMath is not found, the function prints a warning and returns None. - Any other errors during construction are caught and printed.

`get_homology_sage` ¶

Return the homology of the associated chain complex using SageMath.

This method should be run in a SageMath kernel. It constructs a SageMath chain complex and computes its homology using Sage's built-in homology() method.

Parameters:

Name	Type	Description	Default
`save_chain_complex`	`bool`	If True, the chain complex is saved as an attribute (`self._sage_chain_complex`) to speed up future computations.	`False`
`used_saved_chain_complex`	`bool`	If True, it will attempt to use the saved chain_complex attribute, otherwise, it will be computed from scratch.	`True`
`**kwargs`		Additional keyword arguments passed directly to SageMath's `homology()` method.	`{}`

Returns:

Type	Description
	The homology object returned by SageMath.

`get_alphabet` ¶

Returns the alphabet attribute.

Python package docs¶

__version__ = '0.1.0' module-attribute ¶

Block ¶

get_face ¶

get_upper_facets ¶

get_lower_facets ¶

get_all_facets ¶

get_all_faces ¶

get_vertex ¶

get_all_vertices ¶

boundary ¶

Chain ¶

boundary ¶

get_dict_blocks ¶

Alphabet ¶

get ¶

add_letter ¶

update_letters ¶

cast_word ¶

Filtration ¶

compute_d_skeleton ¶

add_blocks ¶

remove_blocks ¶

get_complex ¶

get_euler_curve ¶

get_persistent_homology_barcodes ¶

get_graph ¶

get_alphabet ¶

get_block_height ¶

Complex ¶

compute_d_skeleton ¶

get_maximal_blocks ¶

get_complex ¶

add_blocks ¶

remove_blocks ¶

euler_characteristic ¶

get_graph ¶

get_betti_numbers_z2 ¶

get_chain_complex_sage ¶

get_homology_sage ¶

get_alphabet ¶

`version = '0.1.0'` `module-attribute` ¶

`Block` ¶

`get_face` ¶

`get_upper_facets` ¶

`get_lower_facets` ¶

`get_all_facets` ¶

`get_all_faces` ¶

`get_vertex` ¶

`get_all_vertices` ¶

`boundary` ¶

`Chain` ¶

`boundary` ¶

`get_dict_blocks` ¶

`Alphabet` ¶

`get` ¶

`add_letter` ¶

`update_letters` ¶

`cast_word` ¶

`Filtration` ¶

`compute_d_skeleton` ¶

`add_blocks` ¶

`remove_blocks` ¶

`get_complex` ¶

`get_euler_curve` ¶

`get_persistent_homology_barcodes` ¶

`get_graph` ¶

`get_alphabet` ¶

`get_block_height` ¶

`Complex` ¶

`compute_d_skeleton` ¶

`get_maximal_blocks` ¶

`get_complex` ¶

`add_blocks` ¶

`remove_blocks` ¶

`euler_characteristic` ¶

`get_graph` ¶

`get_betti_numbers_z2` ¶

`get_chain_complex_sage` ¶

`get_homology_sage` ¶

`get_alphabet` ¶