{"id":49336319,"url":"https://github.com/gabe-rbo/pysurgery","last_synced_at":"2026-06-08T00:02:27.162Z","repository":{"id":349196805,"uuid":"1201395174","full_name":"gabe-rbo/pySurgery","owner":"gabe-rbo","description":"A self-contained python library designed to apply Mathematical Surgery Theory over Manifolds.","archived":false,"fork":false,"pushed_at":"2026-05-29T16:50:05.000Z","size":6770,"stargazers_count":7,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-29T18:11:02.960Z","etag":null,"topics":["4-manifolds","algebraic-topology","cohomology","computational-topology","cw-complex","freedman","homology","intersection-form","julia","manifold","mathematics","python","simplicial-complex","smith-normal-form","surgery-theory","tda","topological-data-analysis"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/pysurgery/","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/gabe-rbo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","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-04-04T16:10:51.000Z","updated_at":"2026-05-29T16:50:09.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/gabe-rbo/pySurgery","commit_stats":null,"previous_names":["gabe-rbo/pysurgery"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/gabe-rbo/pySurgery","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gabe-rbo%2FpySurgery","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gabe-rbo%2FpySurgery/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gabe-rbo%2FpySurgery/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gabe-rbo%2FpySurgery/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gabe-rbo","download_url":"https://codeload.github.com/gabe-rbo/pySurgery/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gabe-rbo%2FpySurgery/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33668186,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-29T02:00:06.066Z","response_time":107,"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":["4-manifolds","algebraic-topology","cohomology","computational-topology","cw-complex","freedman","homology","intersection-form","julia","manifold","mathematics","python","simplicial-complex","smith-normal-form","surgery-theory","tda","topological-data-analysis"],"created_at":"2026-04-27T01:02:17.664Z","updated_at":"2026-05-29T20:00:24.869Z","avatar_url":"https://github.com/gabe-rbo.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003ctable border=\"0\" cellpadding=\"0\" cellspacing=\"0\" style=\"border: none !important; border-collapse: collapse; width: 100%; background-color: transparent;\"\u003e\n    \u003ctr style=\"border: none !important; background-color: transparent;\"\u003e\n      \u003ctd width=\"60%\" align=\"left\" style=\"border: none !important; padding: 20px; vertical-align: top; background-color: transparent;\"\u003e\n\n\u003cdiv align=\"center\"\u003e\n\n# pySurgery\n\n**A high-performance Python library for Computational Surgery Theory.**\n\n\u003c/div\u003e\n\npySurgery is a high-performance Python library for exact computational algebraic topology, computational surgery theory, and geometric analysis. It is designed to compute discrete topological invariants—such as integer homology (including exact torsion), intersection forms, cup products, **characteristic classes for vector bundles**, L-group obstructions, and homeomorphism certificates—at massive scale. The library leverages a tri-language architecture (**Python**, **Julia**, and **JAX/XLA**) to rigorously evaluate complex topological structures, scaling to point clouds exceeding 100,000 points while operating within strict memory bounds.\n\n\u003cdiv align=\"center\"\u003e\n\n[![Tests](https://github.com/gabe-rbo/pysurgery/actions/workflows/tests.yml/badge.svg)](https://github.com/gabe-rbo/pysurgery/actions/workflows/tests.yml)\n[![Lint](https://github.com/gabe-rbo/pysurgery/actions/workflows/lint.yml/badge.svg)](https://github.com/gabe-rbo/pysurgery/actions/workflows/lint.yml)\n\n\u003c/div\u003e\n  \u003c/td\u003e\n\u003ctd width=\"40%\" align=\"center\" style=\"border: none !important; padding: 10px; vertical-align: middle; background-color: transparent;\"\u003e\n       \u003cimg width=\"2000\" height=\"2000\" alt=\"pySurgery logo\" src=\"https://github.com/user-attachments/assets/6be087fc-9c87-433d-aa2e-b9762df6fc89\" style=\"display: block; border: none !important; max-width: 100%; height: auto;\" /\u003e\n    \u003c/td\u003e\n    \u003c/tr\u003e\n  \u003c/table\u003e\n\u003c/div\u003e\n\n\n## Architectural Principles\n\npySurgery relies on three foundational pillars to ensure both scale and mathematical fidelity:\n\n1. **Exact Integer Homology:** Computations of $H_n(X; \\mathbb{Z})$ and corresponding torsion invariants are resolved using exact Smith Normal Form (SNF) over $\\mathbb{Z}$. The library features a state-of-the-art, row-pivoted SNF pre-processor in Python using NumPy object arrays, providing a $10\\times - 50\\times$ speedup over standard SymPy implementations. For massive matrices, it employs a multi-threaded Julia backend featuring an optimal $\\mathcal{O}(V+E)$ leaf-peeling pre-processor.\n2. **State-of-the-Art Performance \u0026 Scaling:** The package natively constructs Alpha, Vietoris-Rips, and Witness complexes without opaque external C++ wrappers. It utilizes **NumPy vectorization** (SIMD-accelerated 2D/3D geometry), **Numba JIT compilation** (for high-speed exact finite-field linear algebra), and **Zero-Allocation solvers** that eliminate Python's $O(N^2)$ memory overhead during incremental basis extraction.\n3. **Hardware-Accelerated Geometric Metrics:** Continuous geometric operations, including Sinkhorn-approximated Gromov-Wasserstein distances, Local PCA tangent-space estimations, and continuous relaxations of topological invariants, are fully vectorized and JIT-compiled via **JAX/XLA**.\n4. **Seamless Language Interoperability:** The tri-language bridge automatically orchestrates **Multi-threaded Julia** execution and handles complex signal management (`PYTHON_JULIACALL_HANDLE_SIGNALS`), ensuring a stable and crash-free experience during heavy parallel topological evaluations.\n\n---\n\n## Comprehensive Capabilities\n\npySurgery goes beyond standard persistent homology, exposing the deep algebraic structures required for manifold classification and surgery theory.\n\n### 1. Combinatorial Topology \u0026 Complex Generation\n* **Discrete Spaces:** Robust native classes for `SimplicialComplex`, `CWComplex`, and `ChainComplex` with lazy-evaluated, cached topological properties (f-vectors, boundaries).\n* **Topological Simplification:** Rigorous `.simplify()` method for homotopy-equivalent reduction via Link Condition edge contractions and high-performance `.quick_mapper()` for modularity-based structural summarization.\n* **Homotopy Equivalence:** Systematic reduction via simplicial **Collapses** (free face removal) and **Discrete Morse Theory** (Forman matching), yielding minimal chain complexes while preserving mathematical integrity. Includes rigorous `.is_homology_isomorphic()` checks via SNF.\n* **Massive Point Clouds:** Native construction of memory-efficient **Alpha Complexes** (2D/3D/ND with EMST connectivity heuristics), **Vietoris-Rips** (via sparse clique enumeration), and **Witness Complexes**.\n* **Parameter-Free Reconstruction:** Implementation of the **Crust Algorithm** for adaptive surface and curve reconstruction without distance thresholds.\n* **Exact Persistence:** Native Julia-backed barcode computation over $\\mathbb{Z}_2$ and $\\mathbb{Q}$ using optimized $R=DV$ matrix reductions with memory-bound guardrails.\n* **Homology \u0026 Cohomology:** Exact computation of Betti numbers and torsion coefficients over $\\mathbb{Z}$, $\\mathbb{Q}$, and $\\mathbb{Z}/p\\mathbb{Z}$. Includes Universal Coefficient Theorem (UCT) decompositions for composite moduli.\n* **Optimal Generators:** Data-grounded $H_1$ generator extraction, yielding cycle representatives optimized by minimum geometric weight over $\\mathbb{F}_2$ annotations.\n\n### 2. Algebraic Topology \u0026 Cohomological Operations\n* **Cup Products:** Full simplicial implementation of the Alexander-Whitney diagonal approximation to evaluate $\\alpha \\smile \\beta$, exposing the ring structure of cohomology.\n* **Characteristic Classes:** Extraction of Stiefel-Whitney classes ($w_i$), Pontryagin classes ($p_i$), and Euler classes ($e$) for manifold tangent bundles and general **Combinatorial Vector Bundles**. Features a local Whitney-Steenrod fast-path for massive manifold meshes.\n* **Steenrod Squares:** Cohomology operations $Sq^k: H^p(X; \\mathbb{Z}_2) \\to H^{p+k}(X; \\mathbb{Z}_2)$ implemented via optimized cup-i products.\n* **Fundamental Group** ($\\pi_1$): Active mathematical object supporting `.is_abelian()`, `.is_trivial()`, and `.order()` via **Todd-Coxeter** coset enumeration. Includes geometric tracing of generators as directed-edge cycles.\n* **Rational Homotopy \u0026 Sullivan Models:** Automated computation of **Sullivan Minimal Models** ($\\pi_n(X) \\otimes \\mathbb{Q}$), formality detection, and Massey product extraction.\n* **Adams Spectral Sequence:** Comprehensive $E_2$-page extraction and **E-infinity Resolver** framework. Supports **Interactive Resolution** for ambiguous differentials and **Lean 4 Formal Verification** for automated theorem proving of homotopy groups.\n* **Higher Structures:** Support for **E-infinity algebras** and functorial **Temporal Topology** sequences for dynamic complexes.\n* **Whitehead Torsion:** $K$-theoretic heuristics for evaluating Whitehead groups ($Wh(\\pi_1)$) and s-cobordism obstructions.\n\n### 3. 4-Manifold Topology \u0026 Intersection Forms\n* **Intersection Forms** ($Q$): Rigorous extraction of symmetric bilinear forms $Q: H_2(M) \\times H_2(M) \\to \\mathbb{Z}$ evaluated on fundamental classes.\n* **Algebraic Classification:** Exact classification of $\\mathbb{Z}$-forms by Rank, Signature, Parity (Type I/II), and Definiteness. Detects foundational components like $E_8$ and Hyperbolic ($H$) forms.\n* **Quadratic Refinements:** Evaluation of $q(\\alpha)$ refinements to compute the **Arf Invariant** over $\\mathbb{Z}/2\\mathbb{Z}$ via symplectic basis reductions.\n* **Kirby Calculus:** Tracking 4-manifold surgery diagrams through algorithmic handle slides and blow-ups/blow-downs.\n\n### 4. Surgery Theory \u0026 Manifold Transformation\n* **Wall Groups** ($L_n(\\pi_1)$): Algorithmic evaluation of surgery obstructions mapping into $L$-groups. Supports product-group decompositions and Shaneson splitting sequences.\n* **Controlled Cohomology:** Evaluation of twisted local systems and bounded controlled cohomology for non-simply-connected manifolds using Fox derivatives.\n* **Twisted Multisignatures:** Multi-threaded Julia kernels for computing exact twisted signatures over group rings $\\mathbb{Z}[\\pi]$ using roots of unity.\n* **Structure Sets** ($\\mathcal{S}(M)$): Navigation of the Surgery Exact Sequence, calculating normal invariants over $\\mathbb{Z}$ and $\\mathbb{Z}/2\\mathbb{Z}$ to determine the existence and uniqueness of manifold structures.\n* **Manual Surgery Engine (`Surgeon`):** A transaction-safe workbench for performing and certifying atomic surgery steps. Supports `attach_handle`, `remove_disks`, and `move` (ambient isotopy) with automatic tracking of surgery obstructions and bordism traces.\n* **Automated Surgery Pipeline (`AutoSurgeon`):** An experimental orchestrator that iteratively unlinks, un-nests, and simplifies connected components into homotopy spheres or contractible manifolds via a multi-phase surgical ladder.\n\n### 5. Homeomorphism Certification \u0026 Witnesses\n* **Dimension-Aware Analyzers:** Specialized homeomorphism classification signals tailored for 2D (genus/orientability), 3D (prime decomposition), 4D (Freedman/Donaldson invariants), and 5D+ (Surgery theory).\n* **Structured Witnesses:** The `homeomorphism_witness` module does not just return True/False; it generates rigorous certificate objects containing the exact theorems invoked, explicit isometry matrices ($U^T Q_1 U = Q_2$), and explicit delineations of missing obstruction data if surgery is required.\n* **Decision DAGs:** High-dimensional homeomorphism decisions are managed via a Directed Acyclic Graph (DAG) of analyzers, ensuring that the most efficient invariant is tested first.\n\n### 6. Multi-Engine Backend Optionality\npySurgery features a flexible backend architecture that allows users to prioritize either environment simplicity or raw performance:\n* **`backend='python'`**: Pure-Python execution (enhanced by NumPy/Numba). Requires zero external dependencies. Ideal for rapid prototyping and small-to-medium complexes.\n* **`backend='julia'`**: Native integration with the Julia engine. Recommended for massive SNF reductions and high-dimensional manifold classification.\n* **`backend='auto'` (Default)**: Automatically detects and leverages the most efficient engine available (Julia \u003e Python).\n* **`backend='jax'`**: Specifically used for continuous metric evaluations and differentiable topological approximations.\n\n---\n\n## Quick Start\n\n### 1. Fundamental Group \u0026 Active Objects\nHomotopy groups are treated as **Active Mathematical Objects** that can be queried for group-theoretic properties directly.\n\n```python\nimport pysurgery as ps\n\n# Extract pi_1 from a CW complex\npi1 = ps.extract_pi_1(cw_complex)\n\n# Active queries\nif pi1.is_abelian():\n    print(f\"Abelian Group of Order: {pi1.order()}\")\n    print(f\"Tietze Simplified: {pi1.simplify()}\")\n\n# Geometric Trace: Generators as edge-cycles in the 1-skeleton\nedges = pi1.simplices_generators()\n```\n\n### 2. Rational \u0026 Higher Homotopy\nUnify Sullivan minimal models and Adams spectral sequence data into a single master contract.\n\n```python\n# Compute pi_n(X) and E2 page in one pass\nhg = ps.HomotopyGroup.from_inputs(complex_data)\n\n# Query rank of pi_3 tensor Q\nrank_3 = hg.rank(3)\n\n# Query 2-torsion filtration at degree 3\ntorsion_3 = hg.torsion(3, p=2)\n```\n\n### 3. Surgery Engine \u0026 Manual Control\nThe `Surgeon` (SurgerySession) allows for transactional, step-by-step manifold modification.\n\n```python\nfrom pysurgery import SurgerySession\n\n# Initialize a surgery session on a manifold M\nsurgeon = SurgerySession(manifold=M, point_clouds={\"cloud1\": coords})\n\n# Remove a D^n disk at a specific site\nsurgeon.remove_disks(types=\"D^3\", at=[(0.1, 0.2, 0.3)])\n\n# Attach a handle (S^1 x D^2) to the boundary of the hole\nhandle = surgeon.attach_handle(\n    at=attaching_sphere_vertices, \n    handle_type=\"S^1xD^2\"\n)\n\n# Finalize and inspect the resulting bordism\nsurgeon.finish()\nprint(surgeon.logs())\n```\n\n### 4. Automated Surgery Pipeline (AutoSurgeon)\nThe `AutoSurgeon` experimental pipeline attempts to automatically simplify complex manifold configurations into homotopy spheres.\n\n```python\nimport pysurgery as ps\n\n# 1. Build an ambient simplicial complex K\nK = ps.SimplicialComplex.from_simplices(simplices, coefficient_ring=\"Z\")\n\n# 2. Initialize the AutoSurgeon orchestrator\nsurgeon = ps.AutoSurgeon(\n    K,\n    point_clouds=coords_map,\n    target_topology=\"homotopy_sphere\"\n)\n\n# 3. Run the automated surgical ladder\nreport = surgeon.run()\n\nprint(f\"Status: {report.status}\") # e.g., \"success\"\nprint(f\"Final Betti: {report.final_components[0].betti}\")\n```\n\n### 5. Interactive \u0026 Formal Adams Resolver\nCompute homotopy groups with human-in-the-loop or formal verification.\n\n```python\n# Initialize the interactive resolver for an Adams E2 page\nresolver = ps.InteractiveAdamsResolver(e2_page)\n\n# Run interactive resolution to settle ambiguous differentials\npage_inf = resolver.run_interactive_resolution()\n\n# Or use Lean 4 to formally prove differentials\nlean_resolver = ps.LeanFormalAdamsResolver(e2_page)\nresult = lean_resolver.resolve_e_infinity_via_lean()\n```\n\n\n### 7. Geometric Analysis \u0026 Immersion\n* **PL Embeddings:** High-performance $\\mathcal{O}(N \\log N)$ KDTree-bounded broad-phase and exact narrow-phase checks for piecewise-linear self-intersections and immersions.\n* **Intrinsic Dimension:** Hardware-accelerated manifold dimension estimators using Maximum Likelihood (Levina-Bickel), Two-NN, and Local PCA tangent-space approximations.\n* **Metric Alignment:** Orthogonal Procrustes, discrete Fréchet distances, and JAX-accelerated Entropic Gromov-Wasserstein alignment for comparing ambient metric spaces.\n* **Geometrization \u0026 Uniformization:** Heuristics for Thurston's 8 geometries, normal surface residual norms, and discrete conformal equivalence metrics for 2D meshes.\n* **Gauss-Bonnet \u0026 Chern-Gauss-Bonnet:** Tools for verifying the relationship between total curvature and Euler characteristic across dimensions, including 4D Weyl and Q-curvature integrations.\n\n### 8. Integrations \u0026 Interoperability\n* **JAX:** Differentiable soft-signatures and high-throughput metric tensors.\n* **Lean 4:** Export functionality to translate discrete simplicial complexes into formal theorem-prover syntax.\n* **PyTorch Geometric:** Bridging topological complexes to graph neural network (GNN) architectures.\n* **Trimesh:** Direct import of 3D asset geometries into rigorous CW/Simplicial complexes.\n\n---\n\n## v2.0.0 Development Status (Beta)\n\npySurgery v2.0.0 is currently in **active development**. While the core topological engines (SNF, Betti numbers, $\\pi_1$) are stable and rigorously tested, several higher-level modules are in various stages of completion:\n\n- **STABLE (Production Ready):** Exact SNF (Python/Julia), Fundamental Group tracing, Intersection Forms, Sullivan Minimal Models, Geometrization (3D), Characteristic Classes.\n- **BETA (Under Construction):** `SurgerySession` (Manual Engine), `AutoSurgeon` (Automated Pipeline), Adams Spectral Sequence $E_2$-pages.\n- **RESEARCH (Experimental):** E-infinity Lean 4 formal resolvers, Temporal Topology bifurcation analysis, Controlled Cohomology local systems.\n\nUsers are encouraged to use the `backend='auto'` setting to automatically benefit from the latest performance optimizations as they land.\n\n---\n\n## Installation\n\npySurgery can be installed via pip:\n\n```bash\npip install pysurgery\n```\n\nTo enable the high-performance Julia backend, ensure Julia is installed and then run:\n\n```bash\npip install \"pysurgery[all]\"\n```\n\n## Development Workflow\n\n### 🚀 Local Version Management\n\nTo prevent desynchronization between your local machine and the remote repository, pySurgery uses a **local-first versioning workflow**. Instead of GitHub Actions creating \"hidden\" commits on the server, the versioning logic is handled directly on your machine via a Git hook.\n\n#### How it works:\n1. When you run `git commit`, an interactive prompt will appear asking if you want to update the version.\n2. If you choose to bump, it displays the next available versions for **Patch**, **Minor**, and **Major**. The update is then bundled directly into your current commit.\n3. When you run `git push`, a silent hook ensures the correct version tag exists and pushes it automatically.\n4. The GitHub Action only triggers on version tags to build and publish the release.\n\n#### Initial Setup:\nAfter cloning the repository, you must install the local Git hook once:\n\n```bash\n# Make the setup script executable\nchmod +x scripts/setup_hooks.sh\n\n# Run the setup script\n./scripts/setup_hooks.sh\n```\n\n\u003e **Developer Note:** This hook ensures you never have to `git pull` just to sync a version bump created by a remote bot. All mathematical and versioning state remains strictly under your local control.\n\n---\n\n### 1. Python Package\n\nInstall directly from PyPI:\n\n```bash\npip install pysurgery\n```\n\nOr install from source:\n\n```bash\ngit clone https://github.com/gabe-rbo/pySurgery.git\ncd pySurgery\npip install -e .\n```\n\n### 2. High-Performance Backends (Required for Scale)\n\nTo process point clouds exceeding $N=1,000$ or to compute exact integer torsion on dense manifolds, the underlying accelerator backends must be configured.\n\n**JAX (GPU/TPU Acceleration):**\n```bash\npip install \"pysurgery[ml]\"\n```\n\n**Julia (Exact Integer Engine):**\nEnsure `julia` is available on your `PATH`, then install the required dependencies:\n```julia\nimport Pkg\nPkg.add([\"AbstractAlgebra\", \"PrecompileTools\", \"Combinatorics\", \"SparseArrays\", \"LinearAlgebra\", \"JSON\", \"IntegerSmithNormalForm\", \"Statistics\", \"Random\"])\n```\n*Optional but recommended for geometric kernels:* `Pkg.add([\"Graphs\", \"SimpleWeightedGraphs\", \"DelaunayTriangulation\"])`.\n\nThese manual `Pkg.add(...)` commands remain the recommended setup for local environments. In CI, and at runtime when Julia auto-install is enabled, the bridge can automatically install any missing required Julia packages when needed.\n\nThe bridge will automatically detect the Julia environment and distribute SNF and multisignature kernels across available CPU threads.\n\n---\n\n## Testing\n\npySurgery utilizes `pytest` for its comprehensive test suite. To run the tests, ensure you have installed the package with test dependencies:\n\n```bash\npip install -e \".[test,all]\"\n```\n\n### Running Tests Locally\n\nExecute the suite using:\n```bash\npytest tests/\n```\n\nFor a detailed report including skipped tests and reasons:\n```bash\npytest -v -rs tests/\n```\n\n### CI Dependencies\n\nThe test suite requires both Python and Julia environments. On GitHub Actions, we utilize `julia-actions/setup-julia` and install the full set of backends to ensure 100% test coverage with zero skips.\n\n---\n\n## Documentation and Examples\n\nFor comprehensive theoretical backgrounds and executable pipelines, refer to the tutorial notebooks located in `examples/`. \n\nThe curriculum covers:\n1. Exact algebra and chain complexes from scratch.\n2. Homology, cohomology, and the Alexander-Whitney cup product.\n3. Surgery exact sequences and structure-set navigation.\n4. End-to-end topological certification and homeomorphism witness generation.\n\n---\n\n## Academic Reference\n\nIf you utilize pySurgery in your research, please refer to the `CITATION.cff` file for appropriate attribution. \n\n## Mathematical Foundations \u0026 Bibliography\n\nThe algorithms and constructs implemented in **pySurgery** are rigorously grounded in foundational topological literature and modern computational research.\n\n### Foundational Theory\n\n*   **Algebraic Surgery:** Ranicki, A. (1980). *Exact sequences in the algebraic theory of surgery*. Princeton University Press.\n*   **Algebraic \u0026 Geometric Surgery:** Ranicki, A. (2002). *Algebraic and geometric surgery*. Oxford University Press.\n*   **Surgery Theory \u0026 L-Groups:** Wall, C. T. (1970). *Surgery on compact manifolds*. Academic Press.\n*   **4-Manifold Classification:** Freedman, M. H. (1982). The topology of four-dimensional manifolds. *Journal of Differential Geometry*, 17(3), 357-453.\n*   **Characteristic Classes:** Milnor, J. W., \u0026 Stasheff, J. D. (1974). *Characteristic classes*. Princeton University Press.\n*   **K-Theory \u0026 Whitehead Torsion:** Milnor, J. W. (1966). Whitehead torsion. *Bulletin of the American Mathematical Society*, 72(3), 358-426.\n*   **Rational Homotopy Theory:** Quillen, D. (1969). Rational homotopy theory. *Annals of Mathematics*, 90(2), 205-295.\n*   **Infinitesimal Computations:** Sullivan, D. (1977). Infinitesimal computations in topology. *Publications Mathématiques de l'IHÉS*, 47, 269-331.\n*   **Adams Spectral Sequence:** Adams, J. F. (1960). On the structure and applications of the Steenrod algebra. *Commentarii Mathematici Helvetici*, 32, 180-214.\n*   **Fox Derivatives:** Fox, R. H. (1953). Free differential calculus. I. Derivation in the free group ring. *Annals of Mathematics*, 57(3), 547-560.\n*   **Todd-Coxeter Algorithm:** Todd, J. A., \u0026 Coxeter, H. S. M. (1936). A practical method for enumerating cosets of a finite abstract group. *Proceedings of the Edinburgh Mathematical Society*, 5(1), 26-34.\n*   **Bass-Heller-Swan Theorem:** Bass, H., Heller, A., \u0026 Swan, R. G. (1964). The Whitehead group of a polynomial extension. *Publications Mathématiques de l'IHÉS*, 22, 61-79.\n*   **Shaneson Splitting:** Shaneson, J. L. (1968). Wall's surgery obstruction groups for G x Z. *Annals of Mathematics*, 88(1), 1-67.\n*   **Kirby Calculus:** Kirby, R. (1978). A calculus for framed links in S^3. *Inventiones mathematicae*, 45(1), 35-56.\n*   **Normal Surface Theory:** Haken, W. (1961). Theorie der Normalflächen. *Acta Mathematica*, 105(3-4), 245-375.\n*   **3-Manifold Geometrization:** Thurston, W. P. (1982). Three-dimensional manifolds, Kleinian groups and hyperbolic geometry. *Bulletin of the American Mathematical Society*, 6(3), 357-381.\n*   **Simplicial Collapses:** Whitehead, J. H. C. (1939). Simplicial spaces, nuclei and m-groups. *Proceedings of the London Mathematical Society*, 2(1), 241-325.\n*   **Steenrod Squares \u0026 Cup-i Products:** Steenrod, N. E. (1947). Products of cocycles and extensions of mappings. *Annals of Mathematics*, 48(2), 290-320.\n*   **Wu Class:** Wu, W. T. (1950). Classes caractéristiques et i-carrés d'une variété. *Comptes Rendus de l'Académie des Sciences*, 230, 508-511.\n*   **Hirzebruch Signature Theorem:** Hirzebruch, F. (1956). *Topological methods in algebraic geometry*. Springer-Verlag.\n*   **Arf Invariant:** Arf, C. (1941). Untersuchungen über quadratische Formen in Körpern der Charakteristik 2. *Journal für die reine und angewandte Mathematik*, 183, 148-167.\n*   **3-Manifold Decomposition:** Milnor, J. (1962). A unique decomposition theorem for 3-manifolds. *American Journal of Mathematics*, 84(1), 1-7.\n*   **Discrete Morse Theory:** Forman, R. (1998). Morse theory for simplicial complexes. *Sém. Lothar. Combin*, 41, 1102-1133.\n*   **E-infinity Algebras:** May, J. P. (1972). *The geometry of iterated loop spaces*. Springer-Verlag.\n*   **Temporal Topology (Vineyards):** Cohen-Steiner, D., Edelsbrunner, H., \u0026 Morozov, D. (2010). Vineyards: Beyond persistence. *Discrete \u0026 Computational Geometry*, 44(2), 315-339.\n*   **Smith Normal Form:** Smith, H. J. S. (1861). On systems of linear indeterminate equations and congruences. *Philosophical Transactions of the Royal Society of London*, 151, 293-326.\n*   **Farrell-Jones Conjecture:** Farrell, F. T., \u0026 Jones, L. E. (1993). Isomorphism conjectures in algebraic K-theory. *Journal of the American Mathematical Society*, 6(2), 249-297.\n*   **Surface Classification:** Radó, T. (1925). Über den Begriff der Riemannschen Fläche. *Acta Litt. Sci. Szeged*, 2, 101-121.\n*   **Suspension Theorem:** Freudenthal, H. (1937). Über die Klassen von Abbildungen der $n$-dimensionalen Sphären auf die $k$-dimensionale Sphäre. *Compositio Mathematica*, 5, 299-314.\n*   **Toda Brackets:** Toda, H. (1962). *Composition methods in homotopy groups of spheres*. Princeton University Press.\n\n### Computational Implementation \u0026 Optimization\n\n*   **Computational Topology Foundations:** Edelsbrunner, H., \u0026 Harer, J. (2010). *Computational topology: An introduction*. American Mathematical Society.\n*   **Optimal Generators:** Dey, T. K., \u0026 Wang, Y. (2022). *Computational topology for data analysis*. Cambridge University Press.\n*   **Alpha Complexes:** Edelsbrunner, H. (1994). The weighted Delaunay triangulation or how to stabilize the radical axis. *Discrete \u0026 Computational Geometry*, 13, 371-390.\n*   **Vietoris-Rips Construction:** Zomorodian, A. (2010). Fast construction of the Vietoris-Rips complex. *Computers \u0026 Graphics*, 34(3), 263-271.\n*   **Witness Complexes:** de Silva, V., \u0026 Carlsson, G. (2004). Topological estimation using witness complexes. *Eurographics Symposium on Point-Based Graphics*, 157-166.\n*   **Orthogonal Procrustes:** Schönemann, P. H. (1966). A generalized solution of the orthogonal Procrustes problem. *Psychometrika*, 31(1), 1-10.\n*   **Exact SNF (Leaf-Peeling):** Bauer, U., \u0026 Kerkhoff, M. (2021). Leaf-peeling for Smith normal form. *Journal of Applied and Computational Topology*, 5, 391-423.\n*   **Quiver Representations (Zig-zag):** Gabriel, P. (1972). Unzerlegbare Darstellungen I. *Manuscripta Mathematica*, 6, 71-103.\n*   **Efficient Persistent Homology:** Bauer, U. (2021). Ripser: efficient computation of Vietoris–Rips persistence barcodes. *Journal of Applied and Computational Topology*, 5, 391-423.\n*   **3-Manifold Simplification (Crushing):** Jaco, W., \u0026 Rubinstein, J. H. (2003). 0-efficient triangulations of 3-manifolds. *Journal of Differential Geometry*, 65(1), 61-168.\n*   **Algorithmic 3-Topology:** Matveev, S. (2003). *Algorithmic topology and classification of 3-manifolds*. Springer Science \u0026 Business Media.\n*   **Sylvester's Law of Inertia (Exact):** Sylvester, J. J. (1852). A demonstration of the theorem that every homogeneous quadratic polynomial is reducible by real orthogonal substitutions to the form of a sum of positive and negative squares. *Philosophical Magazine*, 4(4), 138-142.\n*   **Crust Algorithm:** Amenta, N., Bern, M., \u0026 Kamvysselis, M. (1998). A new Voronoi-based surface reconstruction algorithm. *Proceedings of the 25th annual conference on Computer graphics and interactive techniques*, 415-421.\n*   **Gromov-Wasserstein Distance:** Peyré, G., Cuturi, M., \u0026 Solomon, J. (2016). Gromov-Wasserstein averaging of kernel and distance matrices. *International Conference on Machine Learning*, 2664-2674.\n*   **Levina-Bickel MLE:** Levina, E., \u0026 Bickel, P. J. (2004). Maximum likelihood estimation of intrinsic dimension. *Advances in Neural Information Processing Systems*, 17.\n*   **TwoNN Estimator:** Facco, E., d’Errico, M., Rodriguez, A., \u0026 Laio, A. (2017). Estimating the intrinsic dimension of datasets by a minimal neighborhood information. *Scientific Reports*, 7(1), 12140.\n*   **CkNN Graph:** Berry, T., \u0026 Sauer, T. (2016). Consistent manifold representation for topological data analysis. *Foundations of Data Science*, 1(1), 1-38.\n*   **QuickMapper:** Liu, Y., Xie, Z., \u0026 Yi, J. (2012). A fast algorithm for computing Mapper. *arXiv preprint arXiv:1209.4319*.\n\n---\n\n## License\n\nReleased under the MIT License. See `LICENSE` for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgabe-rbo%2Fpysurgery","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgabe-rbo%2Fpysurgery","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgabe-rbo%2Fpysurgery/lists"}