Metadata-Version: 2.4
Name: petls-pytorch
Version: 1.0.1
Summary: GPU-native Persistent Topological Laplacians in PyTorch
Author-email: "Sumner K. Marston" <sumner@sylverity.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/Sylverity/petls-pytorch
Project-URL: Repository, https://github.com/Sylverity/petls-pytorch
Keywords: topological-data-analysis,persistent-laplacian,pytorch,gpu
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: <3.15,>=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: torch>=2.0.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: scipy>=1.10.0
Requires-Dist: gudhi>=3.10.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: matplotlib>=3.7.0
Requires-Dist: tadasets>=0.2.0
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: pytest-benchmark>=4.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.5.0; extra == "dev"
Dynamic: license-file

# PETLS-PyTorch

A PyTorch-native implementation of persistent topological Laplacians, based on the
public PETLS API, PETLS documentation, and the algorithms described in the
**PETLS** paper.

The goal of this project is to make PETLS-style computations easier to use in
Python and PyTorch workflows, especially when downstream code already works with
torch tensors or CUDA devices. The original C++/pybind11 PETLS implementation
remains the reference for correctness.

## Quick Start

```python
import petls_torch

# Alpha complex from point cloud
alpha = petls_torch.Alpha(points=[[0, 0], [1, 0], [0.5, 1]], max_dim=2)
eigs = alpha.spectra(0, 0.0, 1.0)

# Rips complex from distance matrix
rips = petls_torch.Rips(distances=[[0, 1, 1], [1, 0, 1], [1, 1, 0]], max_dim=2)

# Directed flag complex from .flag file
dflag = petls_torch.dFlag("graph.flag", max_dim=3)

# Sheaf Laplacian
sst = petls_torch.sheaf_simplex_tree(st, extra_data, restriction)
psl = petls_torch.PersistentSheafLaplacian(sst)
```

## Relationship to PETLS

`petls_torch` is an independent PyTorch-native implementation of the PETLS
methods and public API behavior, with attribution to the original PETLS paper
and project. Correctness tests compare against the original implementation using
shared inputs and the default tolerances used in this repository.

This project is based on the public PETLS API, PETLS documentation, and the
algorithms described in the PETLS paper. No source code from the original PETLS
implementation is included in this repository.

## API Coverage

| Original PETLS API | PyTorch API | Status |
|--------------------|-------------|--------|
| `Complex` | `Complex` | Implemented |
| `Alpha` | `Alpha` | Implemented |
| `Rips` | `Rips` | Implemented |
| `dFlag` | `dFlag` | Implemented |
| `sheaf_simplex_tree` | `sheaf_simplex_tree` | Implemented |
| `PersistentSheafLaplacian` | `PersistentSheafLaplacian` | Implemented |
| `Profile`, `timer` | `Profile`, `Timer` | Implemented |
| `summaries`, `plot_summary` | `summaries`, `plot_summary` | Implemented |
| `up_Algorithms` enum | `up_Algorithms` enum | Implemented |
| `eigvalsh_wrapper`, `sparse_wrapper`, `matrix_is_diagonal` | Same | Implemented |
| `flipped` optimization | `flipped` + `get_L_top_dim_flipped` | Implemented |
| `nonzero_spectra()` | `nonzero_spectra()` | Implemented |
| `store_L()`, `store_spectra()`, `store_spectra_summary()` | Same | Implemented |
| `time_to_csv()` | `time_to_csv()` | Implemented |

## Directed Flag Files

`dFlag` reads weighted directed graphs from `.flag` files with a `dim 0`
vertex-weight section and an optional `dim 1` directed-edge section:

```text
dim 0
0.0 0.0 0.0 0.0
dim 1
0 1 1.25
1 2 2.50
0 2 3.00
```

The `dim 0` line after the header contains one whitespace-separated vertex
weight per vertex. Each `dim 1` row is `source target weight`, using zero-based
vertex indices. Missing directed edges are absent from the file; self-loops are
not supported. Filtration values for higher-dimensional directed simplices are
the maximum edge weight in each simplex.

## Benchmark Notes

The benchmark results below are included to give a sense of current runtime
behavior on one local machine. They should be read as preliminary measurements,
not as a comprehensive performance study.

The benchmark suite is a performance comparison against the reference PETLS
implementation on identical synthetic inputs. The shared runner is
parameterized with `--package petls` or `--package petls_torch`.

### Hardware

- CPU: Intel i7-14700K
- GPU: NVIDIA RTX 4070 Ti 12GB
- PyTorch 2.x with CUDA 12.x

### Quick Preset

Configuration: torus `n=500` plus sphere `n=300`, `max_dim=2`, 8 filtrations
per dataset.

| Package | Device | Total Time | Mean Trial | Mean Build | Mean Eigs |
|---------|--------|-----------:|-----------:|-----------:|----------:|
| `petls` | CPU | 8.29 s | 172.6 ms | 15.2 ms | 157.4 ms |
| `petls_torch` | CPU | 1.82 s | 37.9 ms | 4.8 ms | 33.1 ms |
| `petls_torch` | CUDA | 1.85 s | 38.5 ms | 4.7 ms | 33.8 ms |

On this workload, the PyTorch implementation is about 4.5x faster than the
reference PETLS run on the same CPU. The CUDA timing is similar to the CPU
timing for this preset, which suggests that eigendecomposition and data sizes
are still small enough that GPU overhead can offset part of the benefit.

### Medium Workload

Configuration: torus `n=500`, `max_dim=3`, 16 filtrations.

| Package | Device | Total Time | Mean Trial | Max Matrix | Status |
|---------|--------|-----------:|-----------:|-----------:|--------|
| `petls` | CPU | > 300 s | unavailable | unavailable | Reached benchmark timeout |
| `petls_torch` | CUDA | 8.80 s | 137.5 ms | 5990 x 5990 | Completed |

For this larger dense-eigendecomposition workload, the PyTorch/CUDA path
completed within the benchmark timeout. The PETLS CPU run reached the configured
300-second timeout in this test configuration.

### Operation Breakdown

Quick preset timings:

```text
petls (CPU)          : build=15.2 ms  eigs=157.4 ms
petls_torch (CPU)    : build=4.8 ms   eigs=33.1 ms
petls_torch (CUDA)   : build=4.7 ms   eigs=33.8 ms
```

In these measurements, most time is spent in eigendecomposition. The PyTorch
implementation benefits from PyTorch's dense linear algebra backends on CPU and
from CUDA support on larger matrix workloads.

## Running Benchmarks

```bash
# Original PETLS
cd /path/to/workspace
python -m benchmark --preset quick --package petls --algorithm eigvalsh

# PETLS-PyTorch on CUDA
python -m benchmark --preset quick --package petls_torch --algorithm eigvalsh --device cuda

# PETLS-PyTorch on CPU
python -m benchmark --preset quick --package petls_torch --algorithm eigvalsh --device cpu

# Custom single run
python -m benchmark \
    --dataset torus --n_points 2000 --complex alpha --max_dim 3 \
    --package petls_torch --algorithm eigvalsh
```

## Installation

```bash
pip install petls-pytorch
```

Requires CPython 3.10, 3.11, 3.12, 3.13, or 3.14.

Release notes are tracked in [CHANGELOG.md](CHANGELOG.md).

Dependencies:

- `torch`
- `numpy`
- `scipy`
- `gudhi`
- `tadasets` for benchmarks

## Test Suite

```bash
cd PETLS-PYTORCH
pytest tests/ -v
```

The test suite covers core functionality, Rips complexes, alpha complexes,
directed flag complexes, sheaf support, eigenvalue utilities, and I/O helpers.

## Citation

If you use `petls_torch` in research, please cite both this PyTorch
implementation and the original PETLS paper.

### PETLS-PyTorch

```bibtex
@software{marston2026petlstorch,
  title        = {PETLS-PyTorch: A PyTorch-native implementation of persistent topological Laplacians},
  author       = {Marston, Sumner K.},
  year         = {2026},
  publisher    = {Sylverity Research},
  url          = {https://github.com/Sylverity/petls-pytorch}
}
```

### Original PETLS paper

```bibtex
@misc{jones2025petlspersistenttopologicallaplacian,
    title={PETLS: PErsistent Topological Laplacian Software},
    author={Benjamin Jones and Guo-Wei Wei},
    year={2025},
    eprint={2508.11560},
    archivePrefix={arXiv},
    primaryClass={math.AT},
    url={https://arxiv.org/abs/2508.11560},
}
```

This project is an independent PyTorch-native implementation based on the
public PETLS API, PETLS documentation, and the PETLS paper. No source code from
the original PETLS implementation is included in this repository.

- Original PETLS repository: https://github.com/bdjones13/PETLS
- PETLS documentation: https://www.benjones-math.com/software/PETLS/
- PETLS paper: https://arxiv.org/abs/2508.11560
