Metadata-Version: 2.4
Name: pyTomoAO
Version: 2.1.0
Summary: An open-source tool for tomographic reconstruction for AO systems
Author-email: Jacob Taylor <jacobataylor7@gmail.com>, Uriel Conod <urielconod@phas.ubc.ca>
License: MIT
Project-URL: Documentation, https://keckobservatory.github.io/pyTomoAO/
Project-URL: Source, https://github.com/KeckObservatory/pyTomoAO
Project-URL: Issues, https://github.com/KeckObservatory/pyTomoAO/issues
Project-URL: Changelog, https://github.com/KeckObservatory/pyTomoAO/blob/main/CHANGELOG.md
Keywords: adaptive optics,tomography,wavefront reconstruction,astronomy
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Astronomy
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
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: numba
Requires-Dist: scipy
Requires-Dist: PyYAML
Provides-Extra: plot
Requires-Dist: matplotlib; extra == "plot"
Provides-Extra: gpu
Requires-Dist: cupy-cuda12x; extra == "gpu"
Provides-Extra: docs
Requires-Dist: sphinx<9,>=7.2; extra == "docs"
Requires-Dist: furo>=2024.1.29; extra == "docs"
Requires-Dist: myst-parser>=2.0; extra == "docs"
Requires-Dist: sphinx-autodoc-typehints>=2.0; extra == "docs"
Requires-Dist: sphinx-copybutton>=0.5.2; extra == "docs"
Requires-Dist: sphinx-design>=0.5; extra == "docs"
Requires-Dist: sphinxcontrib-mermaid>=0.9; extra == "docs"
Provides-Extra: dev
Requires-Dist: ruff==0.15.5; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: matplotlib; extra == "dev"
Dynamic: license-file

# pyTomoAO

[![Tests](https://github.com/KeckObservatory/pyTomoAO/actions/workflows/test.yml/badge.svg)](https://github.com/KeckObservatory/pyTomoAO/actions/workflows/test.yml)
[![Docs](https://github.com/KeckObservatory/pyTomoAO/actions/workflows/docs.yml/badge.svg)](https://github.com/KeckObservatory/pyTomoAO/actions/workflows/docs.yml)
[![Code health](https://github.com/KeckObservatory/pyTomoAO/actions/workflows/code-health.yml/badge.svg)](https://github.com/KeckObservatory/pyTomoAO/actions/workflows/code-health.yml)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
[![PyPI version](https://img.shields.io/pypi/v/pyTomoAO.svg)](https://pypi.org/project/pyTomoAO/)
[![Python versions](https://img.shields.io/pypi/pyversions/pyTomoAO.svg)](https://pypi.org/project/pyTomoAO/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

📖 **[Documentation](https://keckobservatory.github.io/pyTomoAO/)** — installation, configuration reference, tutorials and API reference.

**pyTomoAO** is an open-source Python library for tomographic reconstruction in Adaptive Optics (AO) systems. It reconstructs atmospheric turbulence phase maps from several laser guide star Shack–Hartmann wavefront sensors and projects them onto a deformable mirror.

## Features

- **Minimum-mean-square-error tomographic reconstruction** from multiple LGS wavefront
  sensors, driven by a layered Von Kármán turbulence model. This is the single-DM,
  single-optimisation-direction case used for **LTAO**; MOAO and MCAO are on the roadmap
  below.
- Both a **model-based** reconstructor and one built from a measured **interaction matrix**.
- **Super-resolution** support: per-WFS lenslet rotation and lateral offset.
- Tools for **fitting reconstructed phase maps** onto deformable mirrors.
- **GPU acceleration** through CuPy, selected automatically when it is available, with a
  NumPy/Numba CPU backend otherwise.
- **SLODAR turbulence profiling** from the LGS wavefront sensors' own (pseudo-)open-loop
  slopes, with the LGS cone effect, tip-tilt removal and noise and outer-scale estimation.
  The measured profile feeds straight back into the reconstructor.
- **Interoperability with simulators and telemetry**: conversion of external slope
  conventions (e.g. SPECULA) and a measured slope-noise covariance in place of the default
  regularisation.

## Performance

Time to build a complete tomographic reconstructor, on the configurations bundled with the
package:

| Configuration | LGS | Subaps/WFS | Opt. dirs | Reconstructor | CPU | GPU | Speed-up |
| :------------ | --: | ---------: | --------: | ------------: | ------: | ---------: | -------: |
| `revolt` — 1.2 m, single WFS | 1 | 188 | 1 | 817 × 376 | 0.09 s | **0.011 s** | **8×** |
| `kapa` — Keck 10 m, four LGS | 4 | 304 | 1 | 1312 × 2432 | 2.47 s | **0.081 s** | **30×** |
| `keck` — 7.9 m, field-optimised | 4 | 304 | 49 | 1312 × 2432 | 35.6 s | **0.614 s** | **58×** |

The GPU advantage grows with the problem — **8× to 58×** across these. Field optimisation
over 49 directions takes half a minute on CPU and just over half a second on GPU.

These are the numbers in `examples/benchmark/baseline.json`; reproduce them with:

```sh
python examples/benchmark/benchmark.py                    # all bundled configurations
python examples/benchmark/benchmark.py --check-baseline   # compare against the baseline
```

<details>
<summary>Test setup and methodology</summary>

| | |
| --- | --- |
| CPU | AMD Ryzen 9 9950X3D, 16 cores / 32 threads |
| GPU | NVIDIA RTX 5090, 32 GB |
| RAM | 32 GB |
| Software | Linux, Python 3.12, NumPy 2.2, SciPy 1.16, Numba 0.63, CuPy 13.6 |

Best of five runs. The first build on each backend is discarded: it measures Numba and CuPy
compiling their kernels, not the reconstruction. Timings cover the whole
`build_reconstructor` call — gradient operator, covariance matrices and the regularised
solve — not a kernel in isolation.

The GPU kernels work in single precision, so CPU and GPU reconstructors agree to roughly
1e-4 relative. That is the float32 floor, not a defect; use `force_cpu=True` if you need
float64 end to end.

`examples/benchmark/baseline.json` holds a recorded set of these numbers, and
`--check-baseline` fails if a change makes anything more than 25% slower.

</details>

## Installation

```sh
pip install pyTomoAO
```

or clone the repository:

```sh
git clone https://github.com/KeckObservatory/pyTomoAO.git
cd pyTomoAO
pip install -e .
```

See the [installation guide](https://keckobservatory.github.io/pyTomoAO/getting-started/installation.html) for GPU support and optional extras.

## Usage

Everything is driven by a single YAML configuration file:

```python
from pyTomoAO import example_config
from pyTomoAO.reconstructor import tomographicReconstructor

# Build a tomographic reconstructor from a configuration file
rec = tomographicReconstructor(example_config("kapa"))
rec.build_reconstructor()

# Fold in the DM fitting step to go from slopes straight to commands
FR = rec.assemble_reconstructor_and_fitting(nChannels=4, slopesOrder="simu")
commands = FR @ slopes
```

Full walkthrough: [quickstart](https://keckobservatory.github.io/pyTomoAO/getting-started/quickstart.html) and the [KAPA LTAO tutorial](https://keckobservatory.github.io/pyTomoAO/tutorials/ltao-kapa.html).

## Turbulence profiling (SLODAR)

The tomographic reconstructor is only as good as its turbulence model. `pyTomoAO.slodar`
measures that model from the same LGS wavefront sensors: it computes the slope
cross-covariance maps of every sensor pair and fits thin-layer von Kármán responses, built
from the reconstructor's own covariance kernel and gradient operator, so the profile comes
out in exactly the form the reconstructor uses.

```python
import yaml
from pyTomoAO import example_config, slodarProfiler
from pyTomoAO.reconstructor import tomographicReconstructor

rec = tomographicReconstructor(example_config("kapa"))
prof = slodarProfiler.from_reconstructor(rec)            # same geometry as the reconstructor
result = prof.profile(slopes, removeTT=True, fitL0=True)  # slopes: (nFrames, nLGS*2*nValid) [rad]
print(result)                                            # Cn2 per altitude bin, r0, L0, noise

# Rebuild the reconstructor on the measured profile
config = dict(rec.config, atmosphere_parameters=result.to_atmosphere_config(minFraction=0.01))
with open("config_slodar.yaml", "w") as f:
    yaml.safe_dump(config, f)
rec = tomographicReconstructor("config_slodar.yaml")
rec.build_reconstructor()
```

- **Inputs**: open-loop slopes, or pseudo-open-loop slopes rebuilt from closed-loop telemetry
  with `slodar.pseudo_open_loop_slopes`.
- **Other slope conventions**: slopes from other tools convert with
  `rec.slope_conversion_matrix()` (see `specula_slope_scale` for SPECULA).
- **Validation** against SPECULA LTAO simulations (6 LGS, 20×20 subapertures, 7-layer
  Maunakea profile):
  - SLODAR recovers r0 to within 0.4%, and reconstructors built from the measured profile
    match the true-profile closed-loop Strehl.
  - The outer scale is the parameter that matters most: fit it rather than assume it.

See the [SLODAR user guide](https://keckobservatory.github.io/pyTomoAO/user-guide/slodar.html)
for the method, options and caveats, and `examples/slodar/` for validation scripts,
including an end-to-end SPECULA run.

## Roadmap

- [x] Fundamental tomographic reconstruction algorithms.
- [x] GPU acceleration.
- [x] Deformable mirror fitting routines.
- [x] Detailed documentation and examples.
- [x] SLODAR turbulence profiling from the LGS wavefront sensors.
- [ ] MOAO reconstructor (per-direction outputs).
- [ ] MCAO reconstructor (multiple DM altitudes).

## Development

### Setup

```sh
git clone https://github.com/KeckObservatory/pyTomoAO.git
cd pyTomoAO
pip install -e ".[docs,dev]"
```

### Code Style

Linting and formatting are handled by [ruff](https://docs.astral.sh/ruff/), configured in
`pyproject.toml` and enforced by the `Code health` workflow:

```sh
ruff check .            # lint
ruff format .           # format
ruff format --check .   # what CI checks
```

Naming rules are deliberately disabled: class names such as `tomographicReconstructor` are
public API, and matrix names such as `Gamma` and `Cxx` mirror the equations they implement.
See the [code style guide](https://keckobservatory.github.io/pyTomoAO/development/code-style.html).

### Documentation

The documentation is built with Sphinx and published to GitHub Pages at
<https://keckobservatory.github.io/pyTomoAO/> by the `Documentation` workflow on every push
to `main`. Pull requests build the docs with warnings treated as errors, so a broken link or
docstring fails CI.

To build it locally:

```sh
pip install -e ".[docs]"
make -C docs html          # output in docs/build/html
make -C docs strict        # exactly what CI runs
make -C docs livehtml      # auto-reloading preview (needs sphinx-autobuild)
```

See the [documentation guide](https://keckobservatory.github.io/pyTomoAO/development/documentation.html) for conventions and how publishing works.

### Testing

The `dev` extra installs pytest and coverage:

```sh
pip install -e ".[dev]"
pytest
```

CI runs the suite against Python 3.10–3.14 and applies a coverage threshold. See the
[testing guide](https://keckobservatory.github.io/pyTomoAO/development/testing.html).

## Changelog

See [CHANGELOG.md](CHANGELOG.md) for release history, and the `Unreleased` section for what
is coming next.

## Contributing

Contributions are welcome! Feel free to open issues or submit pull requests. Branch from
`dev` and open the pull request against `dev`; see the
[contributing guide](https://keckobservatory.github.io/pyTomoAO/development/contributing.html)
for conventions. Pull requests must pass the tests, the ruff lint/format checks and the
documentation build, and should add an entry to the changelog.

## License

This project is licensed under the MIT License. See [LICENSE](LICENSE) for details.

## Contact

For questions and discussions, open an issue on GitHub or contact one of:
- **Jacob Taylor** (Software): jacobataylor7@gmail.com
- **Uriel Conod** (Algorithm): urielconod@phas.ubc.ca
