Letter Insertion Complex

A Python module for building and analyzing Letter Insertion Chain Complexes for a set of words over a finite alphabet. This new tool should be useful in algebraic topology, combinatorics, and applications to computational biology, including topological analysis of DNA and RNA sequences.

---

Features

• Define and generate Insertion Chain Complexes and Filtrations based on sets of words, over any finite alphabet (including alphabets where individual elements may be represented by longer strings).
• Support for computing homology using either:
  • Pure Python/NumPy backend (with coefficients in $\mathbb{Z}/2\mathbb{Z}$).
  • SageMath for symbolic computation with coefficients in any supported ring (including $\mathbb{Z}$).
• Computation of persistent homology barcodes for Filtrations.
• Computation of Euler Characteristic Curves for Filtrations.
• Graphic representation of Complexes (mostly useful for small and simple complexes).
• Efficient data structures to compute and cache chain groups and boundary maps.
• Functions and classes to create and manipulate Blocks.

---

Requirements

• Python 3.8+
• NumPy
• Networkx
• Simpy
• Scipy

Optional (for extended functionality):

• SageMath (for symbolic homology computation)

Install requirements via pip:

pip install numpy
pip install networkx
pip install simpy
pip install Scipy

--

Methods for Complex and Filtration Classes

Complex Class

Represents an insertion chain complex built from words over an alphabet, with tools for topological computations and visualizations.

Methods and Outputs

Method	Description / Output
compute_one_skeleton(list_words, list_heights, already_blocks, max_dim=1, verbose=False)	Computes and populates the 0- and 1-skeleton of the Complex.
compute_d_skeleton(W, heights=None, max_dim=10, already_blocks=False, verbose=False)	Computes and populates the Complex skeleton up to dimension max_dim, updating the Complex dictionaries.
get_Complex(max_dim=None)	Returns a new Complex instance truncated at dimension max_dim (or full if max_dim omitted).
euler_characteristic()	Returns the Euler characteristic (integer) of the complex.
get_graph(show_labels=True, max_dim=5, ...)	Returns a Matplotlib Axes object plotting the complex graph up to max_dim with optional labels.
get_betti_numbers_z2(max_dim=None)	Returns a dictionary of Betti numbers (integer counts) up to dimension max_dim with ℤ₂ coefficients.
get_Chain_Complex_Sage(get_ordered_blocks=False)	Returns the corresponding SageMath ChainComplex object for further algebraic computations (if SageMath available).
get_Homology_Sage(save_chain_complex=False, **kwargs)	Returns the homology groups computed via SageMath for the complex (if SageMath available).

---

Filtration Class

Constructs and manages a lower star filtration for the Letter Insertion Chain Complex, associating filtration values to simplices based on heights.

Methods and Outputs

Method	Description / Output
compute_one_skeleton(list_words, list_heights, already_blocks, max_dim=1, verbose=False)	Computes and populates the 0- and 1-skeleton of the filtration with associated heights.
compute_d_skeleton(W, heights=None, max_dim=10, already_blocks=False, verbose=False)	Computes and populates the filtration skeleton up to dimension max_dim, updating filtration dictionaries.
get_Complex(height=None, max_dim=None)	Returns a Complex object truncated at filtration height height and dimension max_dim.
get_euler_curve(values=None)	Returns a tuple (values, euler_curve) where euler_curve is the Euler characteristic computed at filtration values.
get_persistent_homology_barcodes(max_dim=None, inf_value=inf, get_height_indices=False)	Returns persistent homology barcodes as a dictionary of (birth, death) tuples by dimension, optionally indexed by filtration steps.
get_graph(height=None, height_id=None, show_labels=True, max_dim=5, ...)	Returns a Matplotlib Axes object plotting the filtration complex at given height or filtration step.

---

Notes

• Both classes use the Block data structure representing blocks with associated maximal words.
• Methods rely on external libraries like sympy, networkx, scipy.sparse, and optionally SageMath for algebraic topology computations.
• Graph visualization methods return Matplotlib axis objects for further customization or saving.

---