Metadata-Version: 2.4
Name: abbeflow
Version: 0.2.0
Summary: A learned prior over the optical glass manifold for realistic glass selection in lens design.
Project-URL: Homepage, https://github.com/HarrisonKramer/abbeflow
Author: Kramer Harrison
License: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.10
Requires-Dist: numpy
Requires-Dist: torch
Provides-Extra: dev
Requires-Dist: jupyter; extra == 'dev'
Requires-Dist: matplotlib; extra == 'dev'
Requires-Dist: optiland; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Provides-Extra: train
Requires-Dist: optiland; extra == 'train'
Description-Content-Type: text/markdown

<p align="center">
  <img src="media/abbeflow_diagram.svg" alt="AbbeFlow Diagram" width="100%">
</p>

# AbbeFlow

[![PyPI version](https://img.shields.io/pypi/v/abbeflow.svg?style=flat-square)](https://pypi.org/project/abbeflow/)
[![CI](https://img.shields.io/github/actions/workflow/status/HarrisonKramer/AbbeFlow/tests.yml?label=tests&style=flat-square)](https://github.com/HarrisonKramer/AbbeFlow/actions/workflows/tests.yml)
[![PyTorch](https://img.shields.io/badge/PyTorch-powered-EE4C2C?style=flat-square&logo=pytorch&logoColor=white)](https://pytorch.org/)
[![Python](https://img.shields.io/badge/Python-3.10+-3776AB?style=flat-square&logo=python&logoColor=white)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](https://opensource.org/licenses/MIT)
[![Prior: Neural Spline Flow](https://img.shields.io/badge/Prior-Neural%20Spline%20Flow-blueviolet?style=flat-square)](https://arxiv.org/abs/1906.04032)

AbbeFlow is a differentiable, normalizing-flow-based learned prior over the optical glass catalog manifold. Trained on approximately 1,700 real glasses from major manufacturers (including Schott, Ohara, Hoya, and others), AbbeFlow models the distribution of physical glasses in a 4D Buchdahl dispersion coefficient space. It enables continuous, gradient-based lens optimization while ensuring that glass choices remain on or near the realizable manifold.

For details on the mathematical modeling and formulation, see the [Theoretical Background documentation](https://github.com/HarrisonKramer/AbbeFlow/blob/main/docs/theory.md).

---

## Installation

Install AbbeFlow via pip:

```bash
pip install abbeflow
```

---

## Core Optimization Paradigms

AbbeFlow supports two main paradigms for continuous glass optimization:

1.  **Manifold Penalty Mode**: Optimize refractive index $n_d$ and Abbe number $V_d$ directly, adding a regularizing penalty based on the negative log-probability under the learned prior to the optical merit function:
    $$\mathcal{L} = \mathcal{L}_{\text{aberration}} - \lambda_{\text{glass}} \log p(n_d, V_d)$$
2.  **Latent Space Optimization**: Optimize directly in the unconstrained 4D latent space $\mathbf{z} \in \mathbb{R}^4$, mapping back to the physical glass manifold via the decoder $\mathbf{x} = f^{-1}(\mathbf{z})$, which guarantees physically realistic glass parameters.

---

## Quick Start

AbbeFlow provides a pretrained `GlassFlow` model ready for inference:

```python
from abbeflow import GlassFlow

# Load the pretrained model
gf = GlassFlow.pretrained()

# Compute the log-probability of a glass (manifold prior penalty)
logp = gf.log_prob(nd=1.517, vd=64.2)
print(f"Log probability: {logp.item():.4f}")

# Encode to and decode from the latent space
z = gf.encode(nd=1.517, vd=64.2)
glass = gf.decode(z)
print(f"Decoded glass: nd={glass.nd:.4f}, vd={glass.vd:.2f}")

# Snap to the nearest real catalog glasses
matches = gf.nearest_real(nd=1.517, vd=64.2, k=3)
print("\nNearest catalog glasses:")
for match in matches:
    print(f" - {match.manufacturer} {match.name} (Distance: {match.distance:.4f})")
```

---

## Examples

The following examples are located in the [examples/](https://github.com/HarrisonKramer/AbbeFlow/blob/main/examples) directory and demonstrate how to integrate AbbeFlow into various workflows:

*   **[optimize_with_manifold_prior.py](https://github.com/HarrisonKramer/AbbeFlow/blob/main/examples/optimize_with_manifold_prior.py)**: A comparison of Penalty Mode and Latent Space Mode on a toy optimization problem.
*   **[sample_glasses.py](https://github.com/HarrisonKramer/AbbeFlow/blob/main/examples/sample_glasses.py)**: Demonstrates sampling novel glass formulations and evaluating full dispersion curves.
*   **[find_real_alternatives.py](https://github.com/HarrisonKramer/AbbeFlow/blob/main/examples/find_real_alternatives.py)**: Shows how to find the closest real catalog glasses and locate equivalent cross-catalog substitutes.

---

## API Reference

A detailed overview of all modules, classes, and methods is available in the [API Reference documentation](https://github.com/HarrisonKramer/AbbeFlow/blob/main/docs/api.md).

---

## License

AbbeFlow is released under the [MIT License](https://github.com/HarrisonKramer/AbbeFlow/blob/main/LICENSE).
