Metadata-Version: 2.5
Name: topogeoml
Version: 0.0.9
Summary: Topology-aware machine learning toolkit for persistent-homology features, differentiable topology losses, simplicial and Hodge operators, signal analysis, and reproducible evaluation.
Project-URL: Homepage, https://github.com/smaniches/TopoGeoML
Project-URL: Repository, https://github.com/smaniches/TopoGeoML
Project-URL: Documentation, https://smaniches.github.io/TopoGeoML/
Project-URL: Changelog, https://github.com/smaniches/TopoGeoML/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/smaniches/TopoGeoML/issues
Author-email: Santiago Maniches <santiago@topologica.ai>
License-Expression: MIT
License-File: LICENSE
Keywords: geometric-deep-learning,hodge-laplacian,machine-learning,persistent-homology,tda,topological-data-analysis,topological-deep-learning,topology
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: networkx>=3.0
Requires-Dist: numpy>=1.24
Requires-Dist: pyyaml>=6.0
Requires-Dist: ripser>=0.6.4
Requires-Dist: scikit-learn>=1.5
Requires-Dist: scipy>=1.10
Provides-Extra: all
Requires-Dist: gudhi>=3.9; extra == 'all'
Requires-Dist: hypothesis>=6.100; extra == 'all'
Requires-Dist: mypy>=1.8; extra == 'all'
Requires-Dist: numpy<2.5; extra == 'all'
Requires-Dist: pytest-benchmark>=4.0; extra == 'all'
Requires-Dist: pytest-cov>=4.1; extra == 'all'
Requires-Dist: pytest>=7.4; extra == 'all'
Requires-Dist: ruff>=0.4; extra == 'all'
Requires-Dist: toponetx>=0.1.0; extra == 'all'
Requires-Dist: torch-geometric>=2.4; extra == 'all'
Requires-Dist: torch>=2.0; extra == 'all'
Provides-Extra: bench
Requires-Dist: gudhi>=3.9; extra == 'bench'
Requires-Dist: torch-geometric>=2.4; extra == 'bench'
Requires-Dist: torch-topological>=0.1.9; extra == 'bench'
Requires-Dist: torch>=2.0; extra == 'bench'
Requires-Dist: torchvision>=0.15; extra == 'bench'
Provides-Extra: dev
Requires-Dist: hypothesis>=6.100; extra == 'dev'
Requires-Dist: mypy>=1.8; extra == 'dev'
Requires-Dist: numpy<2.5; extra == 'dev'
Requires-Dist: pytest-benchmark>=4.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.1; extra == 'dev'
Requires-Dist: pytest>=7.4; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Provides-Extra: higher-order
Requires-Dist: toponetx>=0.1.0; extra == 'higher-order'
Provides-Extra: tda
Requires-Dist: gudhi>=3.9; extra == 'tda'
Provides-Extra: torch
Requires-Dist: torch-geometric>=2.4; extra == 'torch'
Requires-Dist: torch>=2.0; extra == 'torch'
Description-Content-Type: text/markdown

# TopoGeoML

[![Version](https://img.shields.io/badge/version-0.0.9--beta-grey)](CHANGELOG.md)

## 1. What this is and what problem it solves

TopoGeoML 0.0.9 is beta scientific software. This version distributes the post-0.0.8 differentiable cubical persistence and essential-H1 tie corrections; public APIs can change before 1.0.

TopoGeoML is a Python library for using topology in machine learning. It turns point clouds into fixed-length features for scikit-learn, constructs simplicial and Hodge operators, and provides experimental topology losses for PyTorch. The repository also contains a separate graph-classification research record. These are different deliverables: a working library does not imply a positive research result.

**Research authorship:** Santiago Maniches (ORCID [0009-0005-6480-1987](https://orcid.org/0009-0005-6480-1987)) is the sole scientific author of the research contributions and directs this project's development and publication. AI-assisted tools have supported coding, tests, documentation, and internal review; they do not constitute additional scientific authorship or external validation. The upstream libraries and established methods are credited below.

## 2. Why existing approaches fall short

A persistence engine returns birth–death intervals, not a fitted feature transformer, a training loss, or an auditable experiment. Connecting these pieces by hand risks mixing training and evaluation data or assigning gradients to the wrong critical edges. TopoGeoML supplies those connections; it does not replace the underlying numerical libraries.

## 3. What is genuinely new and what is inherited

The repository-specific work is the assembly of train-fitted feature calibration, typed diagram provenance, optional PyTorch critical-value routing, simplicial operators, and evidence-oriented experiment runners. Vietoris–Rips persistent homology comes from `ripser`; the optional cubical and tied-generator computations use `GUDHI` (Geometry Understanding in Higher Dimensions); classical numerical and model interfaces come from NumPy, SciPy, scikit-learn, NetworkX, and PyTorch. Persistence images, Betti curves, and Hodge Laplacians are established methods. The code and test record do not establish a new topology theorem or superiority over competing toolkits. To cite this release, use `CITATION.cff` with `version = {0.0.9}`.

## 4. Quickstart

Use Python **3.11 or 3.12**, Git, an internet connection for installation, and a **Portable Operating System Interface (POSIX) shell** (Linux/macOS). Run these commands exactly, starting outside the repository:

~~~bash
git clone https://github.com/smaniches/TopoGeoML.git
cd TopoGeoML
python3 -m venv .venv
. .venv/bin/activate
python -m pip install .
python examples/circles_vs_lines.py
~~~

A successful run prints `Building synthetic dataset`, cross-validation and training scores, and a `Fit provenance` block. Those scores are observations from your run, not guaranteed benchmark targets. This installs the current checkout, which can differ from the most recently published package version. Windows commands and the smaller direct application programming interface (API) example are in [Usage](docs/USAGE.md).

## 5. Where it breaks

Vietoris–Rips complexes can become expensive for large point clouds; topology summaries discard information; and feature calibration must be learned only on training data. The differentiable one-dimensional homology path rejects ambiguous critical-edge gradients by default rather than inventing a derivative. Explicit GUDHI tie selection does not prove a unique derivative. The graph study includes invalidated, negative, and unfinished experiments. See [Limitations](docs/LIMITATIONS.md) before relying on scientific or scaling claims.

## 6. Technical documentation

[Architecture](docs/ARCHITECTURE.md) · [Design decisions](docs/DESIGN_DECISIONS.md) · [Limitations](docs/LIMITATIONS.md) · [Usage and troubleshooting](docs/USAGE.md)

Research evidence and reproduction: [Status](STATUS.md) · [Claims to evidence](docs/CLAIMS_TO_EVIDENCE.md) · [Reproducing results](REPRODUCING.md).
