Metadata-Version: 2.4
Name: Cochain
Version: 0.1.0a0
Summary: Differentiable operators for computational topology and DEC.
Project-URL: Repository, https://github.com/luhong88/cochain
Author-email: Lu Hong <honglu88@gmail.com>
License-Expression: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.11
Requires-Dist: einops>=0.7.0
Requires-Dist: jaxtyping>=0.3.0
Requires-Dist: numba>=0.60.0
Requires-Dist: numpy>=2.0.0
Requires-Dist: scipy>=1.17.0
Provides-Extra: examples
Requires-Dist: pytetwild>=0.1.0; extra == 'examples'
Requires-Dist: pyvista[jupyter]>=0.45.0; extra == 'examples'
Provides-Extra: vis
Requires-Dist: polyscope>=2.2.0; extra == 'vis'
Description-Content-Type: text/markdown

# Cochain: differentiable operators for computational topology and DEC

Cochain is a collection of computational topology operators built on PyTorch, designed to facilitate the analysis of discrete topological objects—specifically, simplicial meshes immersed in $\mathbb R^3$ and their associated discrete cochains—within the context of discrete exterior calculus (DEC) and cohomology theory; the underlying chain complexes are defined over $\mathbb{R}$.

## Installation

First, follow the [PyTorch installation guide](https://pytorch.org/get-started/locally/) to install the correct `PyTorch` version for your OS and compute platform. Then, install the base `cochain` package via `pip`:

```bash
pip install cochain
```

`cochain` is tested against `python>=3.11` and `torch>=2.9.0`, but it will likely work with older versions of both.

### Hardware-accelerated dependencies

Some sparse linear algebra routines require the following additional dependencies to enable CUDA-specific accelerations; currently, `cochain` is tested against CUDA 12.

* `CuPy`: see the [installation guide](https://docs.cupy.dev/en/stable/install.html); version `>=14.0.0` is required for compatibility with `NumPy` 2.0.
* `nvmath-python`: see the [installation guide](https://docs.nvidia.com/cuda/nvmath-python/latest/installation.html#); version `>=0.5.0` is required because earlier versions lack the sparse linear solver utils.

### Optional dependencies

* `vis`: installs `Polyscope` for visualization of meshes and cochains.
* `examples`: installs meshing utilities `PyVista` and `PyTetWild`, which are required for generating some example meshes.

These optional dependency groups can be installed using the standard "extras" bracket notation; e.g.,

```bash
pip install cochain[vis,examples]
```

## Features

* Simplicial complexes & combinatorial topology:
    * Piecewise-linear triangular and tetrahedral meshes immersed in $\mathbb{R}^3$.
    * Coboundary operators (discrete exterior derivatives).
    * Reduced coboundary operators via discrete Morse theory.
    * Combinatorial Laplacians on both the primal and dual meshes.
    * Tree-cotree decomposition for 1-Laplacians on triangular meshes.
    * Betti numbers.
* Metric-dependent operators:
    * DEC Hodge stars (circumcentric and barycentric duals) and consistent mass matrices.
    * DEC Hodge Laplacians (for triangular meshes) and weak Laplacians/stiffness matrices (for tetrahedral meshes).
* Cochain operations & mappings:
    * Cup product, anti-symmetrized cup product, and Galerkin ($L^2$-projected) wedge product.
    * Galerkin interior product.
    * Whitney map and de Rham map. 
    * Flat and sharp operators for music isomorphism.
* Sparse linear algebra utils:
    * Block-diagonal mesh batching.
    * PyTorch interfaces for existing sparse linear solvers (SuperLU and cuDSS) and eigensolvers (Lanczos and LOBPCG) that support generalized eigenvalue problems and the shift-invert mode.
    * Autograd support for fixed-topology sparse operations.


### Planned Features

* Harmonic form generator.

## License

This project is licensed under the MIT License; see the `LICENSE` file for details.