Metadata-Version: 2.4
Name: manifold-microscope
Version: 0.3.0
Summary: The data manifold under the microscope.
Author: Marios Koulakis
License-Expression: BSD-3-Clause
Project-URL: Homepage, https://github.com/koulakis/manifold-microscope
Project-URL: Repository, https://github.com/koulakis/manifold-microscope
Project-URL: Issues, https://github.com/koulakis/manifold-microscope/issues
Keywords: manifold learning,differential geometry,geometric deep learning,datasets,curvature
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: experiments_and_analysis/models/beta_vae/LICENSE
License-File: docs/source/third_party/beta_vae.rst
Requires-Dist: torch>=2.2.0
Requires-Dist: numpy>=1.22.0
Requires-Dist: tqdm
Requires-Dist: opencv-python
Requires-Dist: Pillow
Requires-Dist: scipy
Requires-Dist: geomloss
Requires-Dist: joblib
Requires-Dist: sympy
Requires-Dist: scikit-learn
Requires-Dist: seaborn
Requires-Dist: einops>=0.8.0
Provides-Extra: docs
Requires-Dist: Sphinx==8.1.3; extra == "docs"
Requires-Dist: sphinx-rtd-theme==3.0.2; extra == "docs"
Provides-Extra: benchmark
Requires-Dist: torchvision; extra == "benchmark"
Requires-Dist: typer; extra == "benchmark"
Requires-Dist: pynndescent>=0.5.13; extra == "benchmark"
Requires-Dist: pytorch-lightning; extra == "benchmark"
Requires-Dist: PyYAML; extra == "benchmark"
Requires-Dist: matplotlib; extra == "benchmark"
Requires-Dist: pandas; extra == "benchmark"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: ruff==0.17.3; extra == "dev"
Requires-Dist: pyright[nodejs]==1.1.414; extra == "dev"
Requires-Dist: pre-commit==4.6.2; extra == "dev"
Dynamic: license-file

# The Data Manifold under the Microscope

[![Documentation Status](https://readthedocs.org/projects/manifold-microscope/badge/?version=latest)](https://manifold-microscope.readthedocs.io/en/latest/?badge=latest)
[![PyPI Downloads](https://static.pepy.tech/badge/manifold-microscope)](https://pepy.tech/projects/manifold-microscope)

`manifold-microscope` provides toy and image datasets, plus finite-difference estimates of volume, scalar curvature and reach on parameter grids. It accompanies [Marios Koulakis and Constantin Seibold, *The Data Manifold under the Microscope* (ICML 2026)](https://proceedings.mlr.press/v306/koulakis26a.html).

[Documentation on Read the Docs](https://manifold-microscope.readthedocs.io/en/latest)

## Install <img src="docs/images/colorful_mathematical_surface_microscope.png" alt="" width="280" align="right">

Python ≥3.10:

```bash
python -m pip install manifold-microscope
```

For the experiment scripts:

```bash
python -m pip install "manifold-microscope[benchmark]"
```

## Quickstart: scalar curvature on a sphere

```python
import numpy as np
from microscope.computations_grid.curvature import scalar_curvature

radius = 2.0
latitude = np.linspace(-0.7, 0.7, 41)  # Avoid the coordinate singularities at the poles.
longitude = np.linspace(0, 2 * np.pi, 48, endpoint=False)
u, v = np.meshgrid(latitude, longitude, indexing="ij")
points = radius * np.stack(
    [np.cos(u) * np.cos(v), np.cos(u) * np.sin(v), np.sin(u)], axis=-1
)
curvature = scalar_curvature(
    points,
    difference_intervals=[latitude[1] - latitude[0], longitude[1] - longitude[0]],
    cyclic_dimensions=[1],
    patch_sizes=[13, 17],
    device="cpu",
)
print(f"Mean scalar curvature: {curvature.mean():.3f}")
# Approximately 0.5: a sphere has scalar curvature 2 / radius**2.
```

Grid APIs with a `device` argument select CUDA when available, otherwise CPU.
Custom experiment configs default to CPU; the paper presets explicitly request
`cuda:0` and fail if it cannot initialize. See the [experiment guide](https://manifold-microscope.readthedocs.io/en/latest/guide/experiments.html)
for device overrides, training budgets, progress controls and output formats.

## Documentation and paper reproduction

The [online documentation](https://manifold-microscope.readthedocs.io/en/latest) follows development. Start with the guides and API references below.

For the paper figures, use **version 0.2.0** (Git tag `v0.2.0`). Check out
that tag and install its experiment dependencies as described in the
[reproduction guide](https://manifold-microscope.readthedocs.io/en/latest/guide/reproducibility.html). Later releases may
introduce different numerical methods, including extrinsic curvature or faster
reach searches, and may produce different results. Version 0.2.0 is the fixed
reference for the paper workflow.

- [Installation](https://manifold-microscope.readthedocs.io/en/latest/guide/installation.html) and [getting started](https://manifold-microscope.readthedocs.io/en/latest/guide/getting_started.html)
- API reference: [datasets](https://manifold-microscope.readthedocs.io/en/latest/api_reference/datasets.html), [geometry](https://manifold-microscope.readthedocs.io/en/latest/api_reference/geometry.html), and [experiments](https://manifold-microscope.readthedocs.io/en/latest/api_reference/experiments.html)
- [Paper reproduction](https://manifold-microscope.readthedocs.io/en/latest/guide/reproducibility.html)
- [Configuration and defaults](https://manifold-microscope.readthedocs.io/en/latest/guide/configuration.html)
- [Outputs and reuse](https://manifold-microscope.readthedocs.io/en/latest/guide/outputs.html)
- [Build and publish the docs](https://manifold-microscope.readthedocs.io/en/latest/guide/building.html)
- [Dataset and geometry notebooks](notebooks/datasets_and_measures)
- [Development checks and pre-commit setup](CONTRIBUTING.md)

**Note:** The original paper experiments were not fully seeded. Current presets
specify seeds, but plots may still vary slightly across runs or devices.

[BSD-3-Clause license](LICENSE); adapted β-VAE code has a separate [MIT attribution and license](docs/source/third_party/beta_vae.rst).

## Citation

If you use our code in your work, please cite our paper:

```bibtex
@InProceedings{pmlr-v306-koulakis26a,
  title     = {The Data Manifold under the Microscope},
  author    = {Koulakis, Marios and Seibold, Constantin},
  booktitle = {Proceedings of the 43rd International Conference on Machine Learning},
  pages     = {60568--60602},
  year      = {2026},
  volume    = {306},
  series    = {Proceedings of Machine Learning Research},
  publisher = {PMLR},
  url       = {https://proceedings.mlr.press/v306/koulakis26a.html}
}
```
