topogeoml 0.0.3__tar.gz

topogeoml-0.0.3/.gitignore

@@ -0,0 +1,68 @@
+# Byte-compiled / optimized
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+
+# Distribution / packaging
+.Python
+build/
+dist/
+*.egg-info/
+*.egg
+wheels/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# Testing / coverage
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.hypothesis/
+coverage.xml
+*.cover
+
+# Type checking
+.mypy_cache/
+.ruff_cache/
+.pyre/
+.pytype/
+
+# Jupyter
+.ipynb_checkpoints/
+*.ipynb_checkpoints
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*~
+.DS_Store
+
+# Project
+*.log
+/data/
+!topogeoml/data/
+checkpoints/
+runs/
+wandb/
+mlruns/
+artifacts/
+
+# Submission / scratch
+scratch/
+submissions/
+*.parquet
+*.pkl
+*.npz
+
+# OS
+Thumbs.db
+.DS_Store

topogeoml-0.0.3/CHANGELOG.md

@@ -0,0 +1,145 @@
+# Changelog
+
+All notable changes to TopoGeomML will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.0.3] — 2026-06-05
+
+Packaging/distribution release — no library or result changes.
+
+### Added
+
+- **PyPI distribution.** `topogeoml` is now published to PyPI via GitHub Actions Trusted Publishing (OIDC, no stored token), with a CycloneDX SBOM, build-provenance + SBOM attestations, and Sigstore signing — the same release pipeline used across the author's other packages. Install with `pip install topogeoml` (add the `[torch]` extra for the differentiable layers in `topogeoml.nn`).
+
+## [0.0.2] — 2026-05-24
+
+Headline: **the framework has its first strict positive-difference real-data claim** (hypothesis 003, NCI1). The v0.0.2 release gate set in `docs/hypotheses/HYPOTHESIS-002-hodge-proteins.md` §5 ("strictly beats MLP at p_BH < 0.01") is met by the `hodge-mp-residual` arm on NCI1 (p_BH = 4.83 × 10⁻³, +8.6 pp). A preregistered hypothesis series (H001–H007, 27 falsifiable sub-predictions) investigates the mechanism through systematic elimination.
+
+### Added — empirical results (all 30-seed, BCa CIs, paired Wilcoxon + BH-FDR; per-seed reports in `notebooks/results/`)
+
+- **PR #11 — Topology-divergence callback validated.** `ShapeOfLearningCallback.divergence_score` fires no later than a textbook val-loss-ratio watchdog on a controlled overfitting regime (200-sample `sklearn.load_digits`, p_raw = 5.77 × 10⁻⁴, r = +1.0).
+- **PR #15 (hypothesis 001) — MUTAG ablation, five-arm matched-capacity.** Symmetric Laplacian normalisation is sufficient to make a one-layer Hodge MP match an MLP baseline on MUTAG (p_BH = 0.714). The combinatorial Laplacian underperforms by 9 pp (p_BH = 5.66 × 10⁻⁴). The residual variant *underperforms* MLP at this scale (p_BH = 0.019).
+- **PR #16 (hypothesis 002) — PROTEINS replication.** Two-dataset equality holds for the symm-normalised arm (p_BH = 0.548). The MUTAG combinatorial-L harm does not replicate (Δ shrinks by ~10×). Strong "topology beats MLP" claim refuted on PROTEINS.
+- **PR #19 (hypothesis 003) — NCI1, the headline.** On 4110 chemical-compound graphs, the symm-normalised + residual variant **strictly beats** MLP at p_BH = 4.83 × 10⁻³ (median Δ = +0.086, BCa 95% CI: [0.581, 0.625] vs MLP's [0.513, 0.566]). The residual variant *inverts* its verdict from MUTAG to NCI1 — residuals scale with dataset size at this architectural class.
+
+### Added — public API surface
+
+**Neural-network layers** (requires torch)
+- `topogeoml.nn.diff_ph` — differentiable Vietoris-Rips persistent homology via critical-edge indexing (Hofer 2017 / Carrière 2021). Public surface: `rips_diagram_torch`, `finite_lifetimes`, `total_persistence_loss`, `persistence_entropy_loss`, `betti_matching_loss`.
+- `topogeoml.nn.cubical_diff_ph` — differentiable lower-star cubical persistent homology on 2-D/3-D images, with `CubicalTopologyLoss(nn.Module)` for image-segmentation training in the Clough et al. 2020 style.
+- `topogeoml.training.ShapeOfLearningCallback` — empirically validated topology-divergence watchdog for PyTorch training loops (see PR #11 row above).
+
+**Benchmark framework** (`benchmarks/`)
+- 4 backends × 4 measurement axes with statistically defensible reporting; `python -m benchmarks` CLI with `--quick` smoke tier.
+- `benchmarks.stats` — bootstrap CI (percentile, BCa, block), Mann-Whitney U + Cliff's δ, Wilcoxon signed-rank + rank-biserial, Benjamini-Hochberg FDR. All citations in module docstring.
+- `benchmarks.hodge` — graph-classification subsystem with five matched-capacity classifier arms (combinatorial L, symm L̃, +residual, +2-stacked+residual, MLP control) and three dataset adapters (MUTAG, PROTEINS, NCI1).
+
+**Documentation + discipline**
+- `LEADERBOARD.md` — single navigable record of every empirical claim with reproducibility instructions and discipline rules.
+- `docs/hypotheses/HYPOTHESIS-001-hodge-mutag.md` through `HYPOTHESIS-003-hodge-nci1.md` — preregistered hypothesis docs with falsifiable sub-predictions and post-hoc resolved outcomes.
+
+### Changed
+
+- The README's roadmap is narrower and honest: no "drift-tensor", no "TOPOLOGICA proprietary", no "GPU-batched", no peer-review or DOI promises. v0.0.2 is gated on the NCI1 positive claim; v1.0 is conditional on a deeper empirical record and a methods paper.
+- The "Hodge MP layer: minimal, not state-of-the-art" caveat in `LIMITATIONS.md` §1.8 is preserved; the framework now ships *five* Hodge arms in the benchmark, and the architectural element that produces the NCI1 win (residual + normalisation) is named explicitly.
+
+### Fixed
+
+- **Critical bug in `benchmarks/hodge/models.py` (PR #12).** The original `HodgeMessagePassing` layer was instantiated inside `forward_one()` per graph, so its weights were never registered with the optimizer and were re-randomised on every forward call. The pre-PR-#12 MUTAG numbers measured a 2-layer MLP through a random topology filter, not the Hodge architecture. Two regression tests prevent recurrence.
+- **`benchmarks/cli.py` exit-code logic** — `SkippedNonDifferentiable` and `UnavailableBackend` cells no longer count as failures (PR #16, #17). Real cell failures now surface on stderr.
+- **Bench workflow torch/torchvision ABI mismatch** — install both from the CPU wheel index so `torchvision::nms` resolves (PR #17).
+
+### Deferred indefinitely (no implementation timeline)
+- PH metric cascade (Euclidean → Spectral → Fermat)
+- TopoNetX integration for non-simplicial complexes
+- GPU-batched Rips
+- MLflow / W&B tracking
+- Multi-rank simplicial neural network (full SCN)
+- Real DRIVE numbers — pipeline shipped (PR #9), user-side GPU run pending
+
+### Added — academic infrastructure
+
+- `docs/RESEARCH_REPORT.md` — structured technical report documenting the full preregistered hypothesis series (H001–H007) with results, discussion, and bounded claims
+- `CITATION.cff` — CFF 1.2.0 machine-readable citation (GitHub renders "Cite this repository")
+- `.zenodo.json` — Zenodo deposit metadata for DOI minting
+- `CONTRIBUTING.md` — academic collaboration guidelines (preregistration pattern, code standards, statistical discipline)
+- `REPRODUCING.md` — per-hypothesis reproduction guide with commands, wall-clock estimates, and expected outputs
+
+### Changed
+
+- `pyproject.toml`: version bumped to 0.0.2, classifier updated to "Development Status :: 4 - Beta", URLs fixed to `smaniches/TopoGeoML`
+- `README.md`: badges updated, status section rewritten to reflect positive results, mechanism-investigation section added, roadmap updated, citation section updated with CITATION.cff reference
+
+### Quality gates for v0.0.2
+- `ruff check topogeoml tests benchmarks scripts notebooks`: clean
+- `pytest`: 497 passed (up from 118 at v0.0.1)
+- `coverage(topogeoml/ + benchmarks/)`: 100%
+- `mypy topogeoml`: 0 errors (CI enforcement deferred to a separate PR pending constrained-env reproduction)
+- 6 CI workflows on main, all green
+
+## [0.0.1] — 2026-05-20
+
+Initial pre-stable release. The eleven-item v0.0.1 scope lock is fully implemented.
+
+### Added
+
+**Core mathematical objects**
+- `PersistenceDiagram` frozen dataclass with mandatory `DiagramProvenance`
+- `RipsFiltration` via ripser with float64 enforcement and provenance recording
+- `PersistenceImageVectorizer` (Adams et al. 2017) via persim
+- `BettiCurveVectorizer` (vectorized sampling on uniform grid)
+- `SimplicialComplex` with lexicographic simplex ordering and automatic face closure
+- `boundary_matrix(k)` — signed sparse boundary operator ∂_k over R
+- `is_chain_complex` — verifies ∂_{k-1} ∂_k = 0 within numerical tolerance
+- `hodge_laplacian(k)` — symmetric PSD sparse Laplacian L_k = ∂_k^T ∂_k + ∂_{k+1} ∂_{k+1}^T
+- `betti_numbers` via dense eigendecomposition (discrete Hodge theorem)
+- `cubical_mask_diagnostic` — β_0/β_1 + Euler characteristic for binary 2D masks (3D β_0 only)
+
+**Data adapters**
+- `graph_to_clique_complex` — NetworkX graph or adjacency matrix → SimplicialComplex with bounded max_dim
+
+**Pipelines**
+- `TopologyFeaturePipeline` — sklearn `BaseEstimator + TransformerMixin`, supports list-of-arrays and 3D ndarray inputs, captures `FitProvenance`
+
+**Audits**
+- `audit_embedding` — Rips-based topology audit of embedding matrices with NN-distance threshold heuristic
+- `EmbeddingTopologyAudit` dataclass with β_0/β_1 estimates, total persistence, longest H_1 lifetime
+
+**Neural-network layers (requires torch)**
+- `HodgeMessagePassing` — minimal one-round propagation x' = σ(L̃_k @ x @ W + b)
+- `normalize_hodge_laplacian` — symmetric normalization D^{-1/2} L D^{-1/2}
+- `sparse_scipy_to_torch` — sparse format converter
+- `build_hodge_layer_from_complex` — convenience constructor
+
+**Experiments**
+- `load_experiment_config` — YAML loader with dataclass validation
+- `write_results` — JSON writer with config echo, environment snapshot, UTC timestamp, numpy-aware serialization
+- `ExperimentConfig`, `DatasetConfig`, `PipelineConfig`, `ValidationConfig`, `OutputConfig` dataclasses
+- `examples/run_experiment.py` — end-to-end YAML → JSON runner
+- `examples/configs/synthetic_shapes.yaml` — first benchmark config
+
+**Documentation**
+- `LIMITATIONS.md` — explicit scope cuts, failure modes, and unvalidated claims
+- `README.md` — quick-start for each of the 11 items, architecture diagram, contracts, citation block
+
+**Infrastructure**
+- `pyproject.toml` (hatchling backend, MIT license, optional extras: `torch`, `tda`, `higher-order`, `api`, `dev`, `all`)
+- GitHub Actions CI matrix (Python 3.11/3.12 × Ubuntu/macOS)
+- PEP 561 `py.typed` marker
+
+### Verified
+- Boundary identity ∂² = 0 on triangle, tetrahedron, two-triangle complexes
+- Hodge β recovery: D² (1,0,0); S¹ (1,1); S² (1,0,1); disjoint vertices; disjoint triangles
+- L_0 on path graph reduces to standard combinatorial graph Laplacian
+- Cubical β on disk (1,0), annulus (1,1), two disks (2,0), disk-with-two-holes (1,2)
+- Clique complex topology on K_3, K_4, C_4, K_4-boundary
+- Hodge MP forward/backward, gradient flow, shape contracts, layer stacking
+- Embedding audit on single-circle (β_1=1), two-circle (β_1=2) layouts
+- YAML round-trip, JSON output schema with mandatory fields, numpy serialization
+- End-to-end synthetic-shapes benchmark: 5-fold CV accuracy 1.0000 ± 0.0000
+
+### Test suite
+
+118 tests passing, 3 skipped (torch-gated: Hodge MP layer, differentiable PH, ShapeOfLearning callback — collected and run only when the `[torch]` extra is installed). Verified on Python 3.11 and 3.12, Ubuntu and macOS, via `.github/workflows/ci.yml`.

topogeoml-0.0.3/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Santiago Maniches / TOPOLOGICA LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.