TopoDOS

Persistent homology of quasiperiodic density-of-states curves in Fibonacci tight-binding and boron-carbon-nitrogen systems

TopoDOS is a research project at the intersection of condensed-matter physics, topological data analysis (TDA), and mathematical physics. It studies whether persistent homology can provide stable, interpretable, and complementary descriptors of fragmented quasiperiodic spectra.

The repository combines two connected settings:

• a controlled theory lab based on one-dimensional Fibonacci tight-binding Hamiltonians; and
• a materials lab containing electronic density-of-states (DOS) curves and structural descriptors for 13 boron-carbon-nitrogen (BCN) architectures.

The resulting workflow connects spectra, DOS and integrated DOS (IDOS), persistent homology, finite-size scaling, fractal descriptors, gap labeling, architecture comparison, and topological machine learning.

Scientific questions

TopoDOS is organized around four main questions:

1. Can persistent homology identify and quantify the dominant gaps and multiscale organization of quasiperiodic spectra?
2. How do topological summaries scale with Fibonacci system size and relate to effective fractal dimension?
3. Do PH-selected gaps agree with the Fibonacci gap-labeling group inferred from the IDOS?
4. Do persistent-homology features add information beyond classical spectral and structural descriptors?

For the Fibonacci theory layer, the baseline Hamiltonian is

$$ H(\lambda)

\sum_{i=0}^{N-1}\varepsilon_i(\lambda)\lvert i\rangle\langle i\rvert -t\sum_{i=0}^{N-2} \left( \lvert i\rangle\langle i+1\rvert + \lvert i+1\rangle\langle i\rvert \right), $$

where the onsite values follow a Fibonacci word and $\lambda=\Delta V/t$ controls the quasiperiodic contrast.

Main results represented in the repository

• In the Fibonacci tight-binding model, the longest $H_0$ persistence bars track the dominant nearest-neighbor spectral gaps.
• $\alpha$-total persistence exhibits finite-size power-law behavior, with scaling exponents that vary systematically with the coupling $\lambda$ and relate to box-counting estimates of spectral dimension.
• PH-selected gaps closely match values in the Fibonacci gap-labeling group $\mathbb{Z}+\omega_F\mathbb{Z}$, modulo one, where $\omega_F=\varphi^{-1}$.
• In the BCN data, persistent-homology features capture architecture-dependent spectral structure and show qualitative relationships with macroscopic DOS gaps, although the trends are noisier than in the idealized model.
• Machine-learning experiments compare classical-only, PH-only, and combined feature sets. Classical spectral features are already strong predictors in the present sample; the contribution from PH features is complementary but more subtle.

These are research conclusions for the model, parameter grids, and data included here; they should not be interpreted as universal claims about all quasiperiodic or BCN systems.

Repository structure

TopoDOS-Fibonacci-BCN/
├── data/
│   ├── raw/                 # Input DOS, structural, and Fibonacci data
│   └── processed/           # Spectra, PH outputs, summaries, and ML tables
├── notebooks/               # Numbered analysis workflow
│   ├── data/                # Notebook-local intermediate artifacts
│   └── gap_labeling_notebook_patch/
├── reports/
│   ├── docs/                # Monthly analysis/readiness reports
│   └── figs/                # Generated scientific figures
├── src/
│   ├── materials_lab/       # BCN DOS and structural analysis
│   ├── tda/                 # Persistent-homology calculations and distances
│   └── theory_lab/          # Fibonacci tight-binding model and spectra
└── TopoDOS_Presentation.pdf # Extended project presentation

The repository includes processed arrays, tables, and figures so that the results can be inspected without recomputing every stage.

Notebook workflow

The numbered notebooks form the main reproducibility path:

Notebook	Purpose
01_exploratory_bcn_dos.ipynb	Explore BCN DOS/IDOS curves and assemble basic summaries.
02_fibonacci_tb_spectra.ipynb	Generate Fibonacci tight-binding spectra, DOS/IDOS curves, and spectral butterflies.
03_classical_spectral_descriptors_tb.ipynb	Compute classical spectral and BCN structural descriptors.
04_ph0_tb_spectra.ipynb	Compute $H_0$ persistent homology and Betti curves for one-dimensional spectra.
05_ph_dos_and_butterflies.ipynb	Apply persistent homology to DOS/IDOS curves and parameter-energy point clouds.
06_scaling_and_architecture_comparison.ipynb	Study finite-size scaling, persistence distances, clustering, and embeddings.
07_ph_vs_bandgaps.ipynb	Compare topological summaries with spectral and DOS gaps.
08_ph_vs_fractal_dimension.ipynb	Relate $\alpha$-total-persistence scaling to box-counting dimension.
09_gap_labeling_idos_ph.ipynb	Connect IDOS plateaus, Fibonacci gap labels, and PH-selected gaps.
10_topo_ml_d4_tests.ipynb	Compare classical, topological, and combined machine-learning feature sets.

06_scaling_and_architecture_comparison_improved_labels.ipynb is an alternative presentation-oriented version of Notebook 06 with revised plot labels.

Installation

The notebooks were authored with Python 3.9.10. A Python 3.9 or newer environment is recommended.

git clone https://github.com/GabrielWendell/TopoDOS.git
cd TopoDOS

python -m venv .venv
source .venv/bin/activate

python -m pip install --upgrade pip
python -m pip install \
  jupyterlab numpy pandas scipy matplotlib seaborn smplotlib \
  ripser persim scikit-learn statsmodels shap

On Windows PowerShell, activate the environment with:

.\.venv\Scripts\Activate.ps1

Several figures use Matplotlib's text.usetex=True. A working LaTeX installation is therefore recommended for reproducing the publication-style plots. If LaTeX is unavailable, change that setting to False in the relevant notebook cells.

Running the analyses

Launch Jupyter from the notebook directory because the current notebooks use paths relative to that location:

cd notebooks
jupyter lab

Open the notebooks in numerical order and run their cells from top to bottom. The workflow is sequential: later notebooks read tables and arrays produced by earlier stages.

The project evolved through exploratory research notebooks and preserves some notebook-local intermediate files under notebooks/data/. Keep the repository layout unchanged when reproducing the current results.

Core modules

• src/theory_lab/fibonacci_tb.py generates Fibonacci words, constructs and diagonalizes tridiagonal Hamiltonians, builds DOS/IDOS representations, estimates gaps and box-counting dimensions, and assembles spectral butterflies.
• src/materials_lab/ loads BCN DOS and structural data and computes classical spectral, compositional, and bond-count descriptors.
• src/tda/ph0_eigenvalues.py computes $H_0$ persistence diagrams, Betti curves, total persistence, and batch summaries for spectra.
• src/tda/ph_dos_curves.py implements lower-star and Vietoris-Rips analyses of DOS curves and parameter-energy point clouds.
• src/tda/ph_distances.py provides distances between persistence diagrams and Betti curves.

Selected outputs

Analysis	Example
BCN DOS, IDOS, and a macroscopic gap	DOS+IDOS_BCN_F12.png
Fibonacci spectral butterfly	Spectral_butterfly_plot_F12.png
PH-selected gaps and gap labeling	idos_ph0_selected_gaps_vs_labeled_vals.png
Total-persistence scaling exponents	tb_ph0_tp_scaling_exps.png
BCN architecture embedding	mds_embed_ph_dist_bcn.png
Topological ML interpretation	shap_analysis.png

Additional processed tables are available under data/processed/, including spectral summaries, persistent-homology features, gap-labeling tables, finite-size scaling fits, and cross-validated machine-learning results.

Research status

This repository is an actively developed research snapshot associated with a manuscript in preparation. APIs, notebook paths, filenames, and result tables may change before the archival release. For publication-grade reproduction, use the repository release or commit identified in the final paper.

Citation

If this repository contributes to your work, please cite the associated manuscript:

Gabriel Wendell Celestino Rocha and Gandhimohan Madras Viswanathan, Persistent Homology of Quasiperiodic DOS in Fibonacci and BCN Systems, manuscript in preparation (2026).

A DOI and archival software citation will be added when they become available.

Data and reuse

The repository contains research data and derived artifacts used in the TopoDOS analyses. The terms governing redistribution and reuse of the BCN input data should be confirmed with the authors and documented in the final public release.

Authors

• Gabriel Wendell Celestino Rocha
• Gandhimohan Madras Viswanathan

Questions, issues, and reproducibility reports are welcome through the repository's GitHub issue tracker.

License

No software or data license is currently included in this repository. Until a license is added, no permission for reuse, modification, or redistribution is granted beyond what is allowed by applicable law.