Metadata-Version: 2.4
Name: hyperct
Version: 0.3.6
Summary: Low memory hypercube triangulations and sub-triangulations
Home-page: https://github.com/stefan-endres/hyperct
Author: Stefan Endres, Carl Sandrock
Author-email: stefan.c.endres@gmail.com
License: MIT
Project-URL: Documentation, https://hyperct.readthedocs.io/
Project-URL: Bug Reports, https://github.com/stefan-endres/hyperct/issues
Project-URL: Source, https://github.com/stefan-endres/hyperct
Keywords: optimization,triangulation,simplicial-complex,hypercube,computational-geometry
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.7
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.16.0
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: pytest-cov>=2.10; extra == "dev"
Requires-Dist: pytest-benchmark>=3.4; extra == "dev"
Provides-Extra: plotting
Requires-Dist: matplotlib>=3.0; extra == "plotting"
Requires-Dist: polyscope; extra == "plotting"
Provides-Extra: gpu
Requires-Dist: torch>=2.0; extra == "gpu"
Provides-Extra: docs
Requires-Dist: sphinx>=7.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=2.0; extra == "docs"
Requires-Dist: myst-parser>=2.0; extra == "docs"
Requires-Dist: sphinx-autodoc-typehints>=1.25; extra == "docs"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: project-url
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# hyperct

Low memory simplicial complex structures via hypercube triangulations and sub-triangulations.

## When to use hyperct

- **Dynamic meshes with changing topologies**: The library is based on efficiently tracking vertex-vertex connections only which avoids the computational expense of storing simplexes while still allowing many important operations that are applied on simplicial complex structures. Generation-based refinement lets you locally refine and split simplices without rebuilding the entire complex.
- **Computing homologies of very high-dimensional spaces**: the hypercube triangulation scales to hundreds of dimensions while symmetric space reduction cuts complexity by up to O(n!).
- **Working with connectivity of high-dimensional data**: the simplicial complex exposes vertex adjacency, cell membership, and dual mesh structure directly.

## When _not_ to use hyperct

If you need fast conventional computational geometry in low dimensions, dedicated libraries will outperform hyperct:

- **Delaunay / Voronoi tessellations**: [SciPy spatial](https://docs.scipy.org/doc/scipy/reference/spatial.html), [CGAL](https://www.cgal.org/) (via [scikit-geometry](https://github.com/scikit-geometry/scikit-geometry)), [Qhull](http://www.qhull.org/)
- **Unstructured mesh generation**: [Gmsh](https://gmsh.info/), [pygmsh](https://github.com/meshio/pygmsh), [TetGen](https://wias-berlin.de/software/tetgen/) (via [tetgen](https://github.com/pyvista/tetgen)), [MeshPy](https://github.com/inducer/meshpy)
- **Surface meshing & remeshing**: [PyMesh](https://pymesh.readthedocs.io/), [trimesh](https://trimsh.org/), [libigl](https://libigl.github.io/) (via [igl](https://github.com/libigl/libigl-python-bindings))
- **FEM / simulation meshes**: [FEniCS/DOLFINx](https://fenicsproject.org/), [Firedrake](https://www.firedrakeproject.org/)
- **Topological data analysis**: [GUDHI](https://gudhi.inria.fr/), [Ripser](https://github.com/Ripser/ripser), [giotto-tda](https://giotto-ai.github.io/gtda-docs/)

## Features

- Triangulates high-dimensional domains (10D+)
- Symmetry constraints to reduce complexity by O(n!)
- Scalar and vector field associations
- Inequality constraints for non-convex domains
- Multiple refinement strategies (local, global, generation-based)
- Optional GPU acceleration via PyTorch

## Installation

```bash
pip install hyperct
```

### Optional dependencies

- **`hyperct[gpu]`** — PyTorch backend for GPU-accelerated field evaluation and batch vertex processing. Auto-detects CUDA; falls back to CPU when unavailable.
- **`hyperct[plotting]`** — Matplotlib-based visualization of triangulations, scalar fields, and dual meshes (1D/2D/3D). Includes Polyscope for interactive 3D dual mesh visualization.
- **`hyperct[dev]`** — pytest, coverage, and benchmark tooling.

```bash
pip install hyperct[gpu]
pip install hyperct[plotting]
pip install hyperct[gpu,plotting]
```

## Quick start

```python
from hyperct import Complex

# Triangulate a 3D unit hypercube
C = Complex(3)
C.triangulate()
C.split_generation()
C.split_generation()
```

### GPU-accelerated field evaluation

```python
from hyperct import Complex

def my_field(x):
    return sum(xi**2 for xi in x)

C = Complex(3, func=my_field, backend='gpu')
C.triangulate()
C.split_generation()
```

## Requirements

- Python >= 3.7
- NumPy >= 1.16.0
- Optional: PyTorch >= 2.0 (GPU backend)
- Optional: matplotlib >= 3.0, polyscope (plotting)

## License

MIT
