Grout: Qt Framework for Symbolic Dynamics

• Grout is a Qt-based C++ software framework that automates the analysis of one-dimensional symbolic substitutions by computing invariants such as Čech cohomology groups.
• It employs methods from symbolic dynamics, aperiodic tiling theory, and algebraic topology to verify recognisability and explore conjectures like the strong coincidence conjecture.
• The framework features a user-friendly GUI for managing substitution inputs and exporting results in LaTeX/TikZ, facilitating effective mathematical communication.

Grout is a Qt-based C++ software framework for automating the analysis of one-dimensional symbolic substitutions and their associated tiling spaces. It is designed to compute combinatorial and topological invariants—most notably the Čech cohomology groups—of recognisable and primitive substitutions on finite alphabets, combining algorithms from symbolic dynamics, aperiodic tiling theory, and algebraic topology within a graphical user interface. Grout’s architecture encodes the core definitions and results of the field directly in code, enabling systematic, efficient study of substitution systems, the verification of recognisability, exploration of conjectures (such as the strong coincidence conjecture), and rapid export of results in TikZ/LaTeX for mathematical presentation and research purposes (Balchin et al., 2015, Rust et al., 2017).

1. Mathematical Foundations and Definitions

Grout operates on substitutions $\varphi\colon \mathcal{A} \to \mathcal{A}^+$ for a finite ordered alphabet $\mathcal{A} = \{a^1, \dots, a^l\}$, extended by concatenation to words. The language $\mathcal{L}_\varphi$ consists of all finite subwords admitted by repeated application of $\varphi^n(a)$, $n \geq 0$. The corresponding subshift $X_\varphi \subseteq \mathcal{A}^{\mathbb{Z}}$ is the set of bi-infinite sequences all of whose finite factors lie in $\mathcal{L}_\varphi$. The associated one-dimensional tiling space is defined as:

$\Omega_\varphi = (X_\varphi \times [0,1])/ \sim$

where $(s,0)\sim (\sigma(s),1)$ and $\sigma$ denotes the left shift. This compact metric space is endowed with a natural $\mathcal{A} = \{a^1, \dots, a^l\}$0-action by translation (Balchin et al., 2015, Rust et al., 2017).

The substitution matrix $\mathcal{A} = \{a^1, \dots, a^l\}$1 is given by $\mathcal{A} = \{a^1, \dots, a^l\}$2. Primitivity of $\mathcal{A} = \{a^1, \dots, a^l\}$3 (existence of $\mathcal{A} = \{a^1, \dots, a^l\}$4 such that $\mathcal{A} = \{a^1, \dots, a^l\}$5) is verified by iterating the matrix until all entries are strictly positive. The Perron–Frobenius theorem guarantees a unique positive eigenvalue $\mathcal{A} = \{a^1, \dots, a^l\}$6 and associated left/right eigenvectors, normalized canonically for tile lengths and frequencies.

Recognisability is checked combinatorially: every $\mathcal{A} = \{a^1, \dots, a^l\}$7 has a unique $\mathcal{A} = \{a^1, \dots, a^l\}$8-preimage up to shift if, for some suitably large $\mathcal{A} = \{a^1, \dots, a^l\}$9, each $\mathcal{L}_\varphi$0 of length $\mathcal{L}_\varphi$1 factors uniquely as $\mathcal{L}_\varphi$2, with $\mathcal{L}_\varphi$3. The return words to a fixed letter and the corresponding recognisability test are implemented explicitly (Balchin et al., 2015, Rust et al., 2017).

2. Computed Invariants and Simplicial Complexes

Grout produces a range of combinatorial and algebraic invariants:

• Substitution matrix ($\mathcal{L}_\varphi$4): Eigenvalue $\mathcal{L}_\varphi$5 (tile-inflation factor); eigenvectors represent canonical tile lengths and frequencies.
• Factor complexity ($\mathcal{L}_\varphi$6): Number of admitted $\mathcal{L}_\varphi$7-letter words, enumerated by iterating a seed string until the set of $\mathcal{L}_\varphi$8-factors stabilizes.
• Return words: Computed for any fixed letter; used in recognisability checks and for constructing properisations.
• Barge–Diamond complex (BD): Vertices $\mathcal{L}_\varphi$9 for each $\varphi^n(a)$0; two-letter admitted words form the edges. The induced morphism $\varphi^n(a)$1 on the BD complex is iterated to determine the eventual range $\varphi^n(a)$2, supporting the computation of cohomology via the BD exact sequence.
• Anderson–Putnam complex (AP): Vertices are two-letter words, edges are three-letter admitted words; the collared substitution $\varphi^n(a)$3 gives the induced map on $\varphi^n(a)$4.
• Properisation: From the return words to a fixed letter, Grout constructs a pre-left-proper primitive recognisable substitution $\varphi^n(a)$5, enabling computation of the direct-limit cohomology via $\varphi^n(a)$6.

The following table summarizes the principal mathematical invariants and complexes:

Invariant/Complex	Principal Output	Computational Method
$\varphi^n(a)$7, $\varphi^n(a)$8	Tile lengths, frequencies	Matrix algebra, eigen-decomposition
Factor complexity	$\varphi^n(a)$9, $n \geq 0$0-letter words$n \geq 0$1	Seed iteration, subword enumeration
Barge–Diamond (BD)	Cohomology $n \geq 0$2	Graph iteration, eventual range, exact seq
Anderson–Putnam (AP)	Cohomology via $n \geq 0$3	Boundary matrix, kernel, induced map
Properisation	Left-proper substitution $n \geq 0$4, direct-limit cohom.	Return word factorization, matrix analysis

3. Algorithmic Implementation

All core computations are implemented in modern C++ with Qt-based GUI components:

• Iterated substitution: Builds words/sequences under repeated application of the rule using the string-based Substitution class.
• Matrix operations: Incidence matrices use a simple square-matrix template, supporting multiplication and QR-based eigenanalysis (to two decimal places).
• Combinatorics: Uniqueness of word sets or edge sets is enforced with std::set<std::string>.
• Topological invariants: Computation of Čech cohomology groups is available through three methods:
  • BD: Uses the eventual range $n \geq 0$5 of the BD complex and an exact sequence relating $n \geq 0$6, the direct limit of $n \geq 0$7, and $n \geq 0$8.
  • AP: Kernel and image of boundary matrices are computed by Gaussian elimination; the map $n \geq 0$9 on cycles determines the direct limit.
  • Properisation: Factors return-word substitutions, constructs $X_\varphi \subseteq \mathcal{A}^{\mathbb{Z}}$0, and computes its direct-limit.
• Recognisability: Algorithm iterates over return words $X_\varphi \subseteq \mathcal{A}^{\mathbb{Z}}$1 and checks equality of their substituted concatenations.
• Strong coincidence: For Pisot substitutions, Grout implements a systematic search for first coincidences, reporting levels reached with no known counterexamples up to $X_\varphi \subseteq \mathcal{A}^{\mathbb{Z}}$2 and sample sizes exceeding $X_\varphi \subseteq \mathcal{A}^{\mathbb{Z}}$3 over three-letter alphabets (Rust et al., 2017).

Algorithmic details, including pseudocode for iteration, primitivity tests, factor enumeration, return-word search, and properisation are documented in (Balchin et al., 2015).

4. GUI Features and Workflow

Grout’s graphical user interface provides:

• Input validation: Regex-based enforcement of valid substitution entries; alphabet size matching.
• Computation toggles: Menu-driven calculation of specific invariants (substitution matrices, factor complexity, return words, recognisability, BD/AP complexes, cohomology by all three methods).
• Diagram and data export: One-click generation of LaTeX/TikZ output for all computed diagrams and results; a “Save/Load Example” facility and “Copy Short‐String Encoding” for sharing substitutions.
• Responsive performance: Complexity and return-word enumeration halt as soon as sets stabilize; AP computations may slow with large three-letter word sets due to exponential growth of the boundary-matrix dimension.

5. Case Studies and Example Substitutions

Illustrative examples preloaded in Grout include classical substitutions:

• Fibonacci: $X_\varphi \subseteq \mathcal{A}^{\mathbb{Z}}$4; $X_\varphi \subseteq \mathcal{A}^{\mathbb{Z}}$5, $X_\varphi \subseteq \mathcal{A}^{\mathbb{Z}}$6. Tile frequencies and lengths arise from normalized eigenvectors. Factor complexity $X_\varphi \subseteq \mathcal{A}^{\mathbb{Z}}$7. Cohomology is $X_\varphi \subseteq \mathcal{A}^{\mathbb{Z}}$8. BD and AP complexes both recover the known rank (Balchin et al., 2015, Rust et al., 2017).
• Thue–Morse: $X_\varphi \subseteq \mathcal{A}^{\mathbb{Z}}$9, $\mathcal{L}_\varphi$0, PF eigenvalue $\mathcal{L}_\varphi$1. Complexity $\mathcal{L}_\varphi$2 for $\mathcal{L}_\varphi$3, then grows. BD and AP methods both yield $\mathcal{L}_\varphi$4 for the cohomology (Rust et al., 2017).
• Extended families: Tribonacci, n-ibonacci, and disconnected BD subcomplex cases, with fully detailed pipeline from combinatorics through all cohomology algorithms.

6. Performance Considerations and Limitations

Complexity enumeration and return-word search are efficient for small alphabets and word lengths. The AP approach scales poorly with $\mathcal{L}_\varphi$5 due to the growth of the boundary-matrix; searching its kernel is exponential in this dimension. Properisation generally increases the alphabet size but keeps it manageable. Currently, Grout does not implement closed-form formulas for $\mathcal{L}_\varphi$6 (e.g., for Sturmian sequences), and growth-rate detection is absent. Derived-sequence phenomena in properisation are left for further study, and effective recognisability for nonprimitive or nonaperiodic cases remains an open problem (Balchin et al., 2015).

7. Impact and Future Directions

Grout consolidates key routines in symbolic dynamics and tiling theory in a single, documented, and export-friendly package. Its utility for large-scale searches has enabled empirical checks of conjectures across broad parameter spaces, evidenced by high-performance computing runs for the strong coincidence conjecture. Potential directions include improved algorithms for the AP method (e.g., sparse-matrix or homology-reduction techniques), implementation of closed-form complexity enumerators, and enhanced recognisability and eigenstructure computation for large alphabets (Balchin et al., 2015, Rust et al., 2017).