{"id":51887253,"url":"https://github.com/teerthsharma/topological-ml-toolkit","last_synced_at":"2026-07-25T22:30:29.947Z","repository":{"id":370350049,"uuid":"1294339786","full_name":"teerthsharma/topological-ml-toolkit","owner":"teerthsharma","description":"Rust + Python Topological ML Toolkit for persistent homology, Betti-curve features, manifold embeddings, topology docs, backend contracts, and E2E benchmarks for sklearn/PyTorch/TensorFlow-style pipelines.","archived":false,"fork":false,"pushed_at":"2026-07-23T00:31:58.000Z","size":1067,"stargazers_count":9,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-23T02:12:59.017Z","etag":null,"topics":["assembly","avx512","benchmarks","computational-topology","cpp","cuda","data-science","machine-learning","no-std","persistent-homology","python","pytorch","rust","scientific-computing","scikit-learn","tda","tensorflow","topological-data-analysis","topology","triton"],"latest_commit_sha":null,"homepage":"https://teerthsharma.github.io/topological-ml-toolkit/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/teerthsharma.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-07-08T22:40:18.000Z","updated_at":"2026-07-23T00:30:31.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/teerthsharma/topological-ml-toolkit","commit_stats":null,"previous_names":["teerthsharma/topological-ml-toolkit"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/teerthsharma/topological-ml-toolkit","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/teerthsharma%2Ftopological-ml-toolkit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/teerthsharma%2Ftopological-ml-toolkit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/teerthsharma%2Ftopological-ml-toolkit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/teerthsharma%2Ftopological-ml-toolkit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/teerthsharma","download_url":"https://codeload.github.com/teerthsharma/topological-ml-toolkit/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/teerthsharma%2Ftopological-ml-toolkit/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35895136,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-07-20T02:08:10.276Z","status":"online","status_checked_at":"2026-07-25T02:00:06.922Z","response_time":64,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["assembly","avx512","benchmarks","computational-topology","cpp","cuda","data-science","machine-learning","no-std","persistent-homology","python","pytorch","rust","scientific-computing","scikit-learn","tda","tensorflow","topological-data-analysis","topology","triton"],"created_at":"2026-07-25T22:30:28.923Z","updated_at":"2026-07-25T22:30:29.930Z","avatar_url":"https://github.com/teerthsharma.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Topological ML Toolkit\n\nTopological ML Toolkit is a Rust and Python library for turning the shape of\ndata into features, diagnostics, and benchmarked ML pipeline components.\n\nTopological machine learning asks a practical question: what structure remains\nstable when data is noisy, embedded differently, sampled unevenly, or passed\nthrough a model? Instead of looking only at coordinates, it measures connected\ncomponents, loops, voids, covers, neighborhoods, trajectories, and consistency\nconstraints. Those measurements can become normal ML features, model-debugging\nsignals, or routing rules.\n\nThe goal is not to make topology feel exotic. The goal is to make it usable by\npeople who already build sklearn, PyTorch, TensorFlow, and Rust systems.\n\n## What It Can Do\n\n- Convert point clouds into persistence diagrams and Betti numbers.\n- Convert time series into delay-coordinate point clouds.\n- Export graph-ready diagram traces for documentation and notebooks.\n- Build fixed-width Betti-curve feature matrices with a sklearn-style\n  `PHFeaturizer`.\n- Keep active claims tied to tests and E2E benchmark artifacts.\n- Expose backend contracts for Safe Rust, Python reference, C++, ASM AVX-512,\n  Triton, PyTorch, and TensorFlow without pretending gated acceleration is done.\n\n## Why Topology Helps ML\n\nTopology gives ML engineers features that are stable under deformation. That is\nuseful when the exact coordinate system is less important than the structure:\n\n- clusters merging or splitting;\n- loops in sensor traces, embeddings, robotics paths, or periodic signals;\n- holes and voids in sampled manifolds;\n- shape changes across model layers;\n- drift in activation geometry;\n- covers and neighborhoods that can drive batching or routing;\n- local consistency failures across distributed or multi-view systems.\n\nA normal pipeline can use those signals as numeric features:\n\n```text\nraw data -\u003e point cloud / embedding / trajectory -\u003e topology -\u003e feature matrix -\u003e ML model\n```\n\n## Current Working Surface\n\nRust crate: `topoml-core`\n\n- `PointCloud`\n- `PersistenceConfig`\n- `ComplexKind`\n- `persistent_homology`\n- `time_delay_embedding`\n\nPython package: `topoml`\n\n- `persistent_homology(points, max_dim, max_radius)`\n- `persistence_similarity_trajectory(points, max_dim, max_radius, tolerance)`\n- `rescale_persistence_diagram(diagram, scale)`\n- `time_delay_embedding(samples, dimension, tau)`\n- `PersistenceDiagram.betti_at(radius)`\n- `PersistenceDiagram.to_plotly_trace(dimension)`\n- `PHFeaturizer(max_dim, radii, homology_dims)`\n- `BettiCurve(radii, homology_dims)`\n- `PersistenceImage(width, height, sigma)`\n- `point_cloud_signature`, `graph_signature`, and `activation_signature`\n- `TensorBundleSpec`, `TensorAlgebraElement`, `interop_bundle`, and\n  `interop_add` for explicit tensor-space interoperability rules\n- `TopologyAugmenter`, `topological_sample_weights`, and\n  `TopologyRandomForestClassifier` for topology-augmented training baselines\n- `make_sklearn_pipeline(estimator, ...)` for optional real sklearn `Pipeline`\n  integration without importing sklearn during `import topoml`\n- `BenchmarkDataset`, `make_noisy_circle`, `make_two_circles`, and\n  `make_cluster_bridge` for deterministic tutorials and benchmark smoke tests\n- `metric_cover(points, radius)` and `nerve_graph(cover)`\n- `mapper_graph(points, filter_values, intervals, overlap, cluster_radius)`\n- `sheaf_consistency_residual(sections, restrictions)`\n- `path_homotopy_signature`, `activation_strata`, `finite_orbit_signature`,\n  `equivariance_residual`, `scott_fixed_point`, and\n  `weak_convergence_residual`\n- `finite_topology_signature`, `dynamical_signature`,\n  `braid_crossing_signature`, and `mesh_euler_characteristic` for finite\n  point-set, dynamics, braid, and low-dimensional diagnostics\n- `write_dashboard(path, title, diagram, feature_matrix, metadata)`\n- backend metadata and backend selection contracts\n- strict backend adapters through `select_backend_adapter`\n\n## Quickstart\n\n```python\nimport numpy as np\nimport topoml\n\npoints = np.array([[0.0, 0.0], [0.2, 0.0], [5.0, 0.0]])\ndiagram = topoml.persistent_homology(points, max_dim=0, max_radius=10.0)\n\nprint(diagram.betti_at(0.1).beta0)  # 3 connected components\nprint(diagram.betti_at(0.3).beta0)  # 2 connected components\nprint(diagram.betti_at(6.0).beta0)  # 1 connected component\n```\n\nFeature extraction for a normal ML pipeline:\n\n```python\nimport numpy as np\nimport topoml\n\nclouds = [\n    np.array([[0.0, 0.0], [0.1, 0.0], [5.0, 0.0]]),\n    np.array([[0.0, 0.0], [0.2, 0.0], [0.4, 0.0]]),\n]\n\nfeatures = topoml.PHFeaturizer(max_dim=0, radii=[0.0, 0.15, 1.0]).fit_transform(clouds)\nprint(features)\n```\n\nPrototype topology diagnostics:\n\n```python\ncover = topoml.metric_cover(points, radius=0.25)\nnerve = topoml.nerve_graph(cover)\n\nmapper = topoml.mapper_graph(\n    points,\n    filter_values=points[:, 0],\n    intervals=3,\n    overlap=0.25,\n    cluster_radius=0.5,\n)\n\nfinite = topoml.finite_topology_signature({\"a\", \"b\"}, [set(), {\"a\"}, {\"a\", \"b\"}])\ndynamics = topoml.dynamical_signature([3.0, 2.0, 1.2, 1.6, 1.1])\n```\n\nStatic dashboard export:\n\n```python\ntopoml.write_dashboard(\n    \"artifacts/dashboard.html\",\n    title=\"Topology inspection\",\n    diagram=diagram,\n    feature_matrix=features,\n    metadata={\"dataset\": \"example\"},\n)\n```\n\nTopology-aware training baseline:\n\n```python\nmodel = topoml.TopologyRandomForestClassifier(\n    radii=[0.0, 0.25, 0.5, 1.0],\n    max_dim=1,\n    random_state=7,\n)\nmodel.fit(point_clouds, labels, base_features=tabular_features)\nprint(model.score(point_clouds, labels, base_features=tabular_features))\n```\n\nTensor-space interoperability:\n\n```python\nxy = topoml.TensorBundleSpec((\"x\", \"y\"), (1.0, 1.0))\nyz = topoml.TensorBundleSpec((\"y\", \"z\"), (1.0, -1.0))\nambient = topoml.interop_bundle(xy, yz)\nprint(ambient.basis)  # (\"x\", \"y\", \"z\")\n```\n\nOptional sklearn pipeline:\n\n```python\nfrom sklearn.tree import DecisionTreeClassifier\n\npipeline = topoml.make_sklearn_pipeline(\n    DecisionTreeClassifier(random_state=0),\n    radii=[0.0, 0.15, 1.0],\n    max_dim=0,\n)\npipeline.fit(point_clouds, labels)\n```\n\nBenchmark fixture:\n\n```python\ncircle = topoml.make_noisy_circle(n_samples=64, noise=0.0, random_state=7)\nprint(circle.expected_betti)  # {\"beta0\": 1, \"beta1\": 1}\n```\n\nRunnable tutorial scripts:\n\n```powershell\npython examples/point_cloud_ph.py\npython examples/sklearn_pipeline.py\npython examples/dashboard_export.py --out artifacts/tutorial-dashboard.html\n```\n\nEach script emits JSON evidence and is checked by the test suite and E2E claim\ngate. See `docs/tutorials/index.md` for the graph-first walkthroughs.\n\n## Backend Roadmap\n\n| Backend | Status | Purpose | Gate before claims |\n| --- | --- | --- | --- |\n| Safe Rust | Active | Bounded exact Vietoris-Rips PH | Known Betti fixtures pass |\n| Python reference | Active | Data-science API and graphs | Python contract tests pass |\n| C++ | Active H0 native path | Portable native extension path | H0 barcode equivalence vs Python and baseline fixtures |\n| ASM AVX-512 | Active hardware-gated distance dispatch | L2-squared hot path | CPUID/XCR0 gate plus NumPy equivalence |\n| CUDA | Active optional native runtime wrapper | Pairwise L2 and threshold-edge preprocessing prototype | `nvcc`, CUDA runtime/device, and NumPy equivalence |\n| Triton | Active optional CUDA runtime wrapper | Pairwise L2 topology preprocessing prototype | `torch.cdist` parity when torch, Triton, and CUDA are available |\n| PyTorch | Active optional adapter | Tensor/module adapters | CPU framework CI plus torch.compile-safe behavior |\n| TensorFlow | Active optional adapter | Tensor adapters | CPU framework CI with eager and graph-mode parity |\n\nActive hardware-gated means the implementation exists but only selects when the\nmachine and OS expose the required CPU state. Active optional adapter means the\nimplementation exists and is gated, but the heavy framework or CUDA dependency\nis still optional. Runtime-gated backends must fail clearly rather than silently\nfalling back to a slower or different implementation.\n\n```python\nresult = topoml.select_backend_adapter(\"triton\", raise_unavailable=False)\nprint(result.available)       # depends on torch, Triton, CUDA, and parity gates\nprint(result.missing_gates)   # explicit runtime gates when unavailable\n```\n\n## Benchmark Discipline\n\nThis repository treats performance statements as claims that must be executable.\n\nThe E2E claim benchmark currently verifies:\n\n- known \\(H_0\\) cluster merges;\n- known \\(H_1\\) square-cycle behavior;\n- time-delay embedding output shape;\n- fixed-width `PHFeaturizer` output;\n- prototype finite topology, cover, nerve, Mapper, sheaf residual, homotopy,\n  strata, orbit, equivariance, Scott fixed-point, weak convergence, sampled\n  dynamics, braid-crossing, and mesh Euler diagnostics;\n- optional real sklearn pipeline integration when scikit-learn is installed;\n- graph-first gallery pages with explicit claim boundaries;\n- self-contained HTML dashboard export;\n- runnable tutorial scripts for point-cloud PH, optional sklearn integration,\n  and dashboard export;\n- backend metadata separation between active, runtime-gated, and planned work;\n- import safety for optional heavy stacks;\n- real CPU PyTorch and TensorFlow adapter integration in CI;\n- benchmark-smoke timing records for the active Python reference path.\n- CI-gated parity against `ripser` and `GUDHI` on small Vietoris-Rips\n  fixtures.\n\nManual CUDA tensor benchmark for GPU machines:\n\n```powershell\npython benchmarks/benchmark_cuda_tensors.py --out artifacts/cuda-tensor-topology.json\n```\n\nThis benchmark allocates real CUDA tensors, runs a CUDA-backed PyTorch projection\nand `torch.cdist`, times the GPU section with CUDA events, and then runs the\ncurrent topology reduction on the selected activation cloud. It refuses to emit\nfake CUDA results when CUDA is unavailable.\n\nRun it locally:\n\n```powershell\npython benchmarks/e2e_claims.py --json-out artifacts/e2e-claims.json --md-out artifacts/e2e-claims.md\npython benchmarks/benchmark_triton_schedule.py --out artifacts/triton-schedule.json\npython benchmarks/benchmark_tda_baselines.py --out artifacts/tda-baselines.json\npython benchmarks/benchmark_persistence_similarity.py --out artifacts/persistence-similarity.json --points 32 64 --frames 8 16 --repetitions 10\n```\n\n## Local Checks\n\n```powershell\ncargo fmt --all -- --check\ncargo clippy -p topoml-core --all-targets -- -D warnings\ncargo test -p topoml-core\ncargo check -p topoml-core --no-default-features\npython -m pytest python/tests -q\npython benchmarks/e2e_claims.py --json-out artifacts/e2e-claims.json --md-out artifacts/e2e-claims.md\npython -m mkdocs build --strict\n```\n\n## Documentation\n\nThe GitHub Pages site teaches topology first, then ML usage, then backend and\nbenchmark contracts. It includes generated SVG diagrams for filtrations,\nbarcodes, Betti curves, and embeddings.\n\nDocs are built with MkDocs:\n\n```powershell\npython scripts/generate_gallery.py\npython -m mkdocs serve\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fteerthsharma%2Ftopological-ml-toolkit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fteerthsharma%2Ftopological-ml-toolkit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fteerthsharma%2Ftopological-ml-toolkit/lists"}