pyTomoAO
📖 Documentation — 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:
python examples/benchmark/benchmark.py # all bundled configurations
python examples/benchmark/benchmark.py --check-baseline # compare against the baseline
Test setup and methodology
| 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.
Installation
pip install pyTomoAO
or clone the repository:
git clone https://github.com/KeckObservatory/pyTomoAO.git
cd pyTomoAO
pip install -e .
See the installation guide for GPU support and optional extras.
Usage
Everything is driven by a single YAML configuration file:
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 and the KAPA LTAO tutorial.
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.
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()(seespecula_slope_scalefor 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
for the method, options and caveats, and examples/slodar/ for validation scripts,
including an end-to-end SPECULA run.
Roadmap
- Fundamental tomographic reconstruction algorithms.
- GPU acceleration.
- Deformable mirror fitting routines.
- Detailed documentation and examples.
- SLODAR turbulence profiling from the LGS wavefront sensors.
- MOAO reconstructor (per-direction outputs).
- MCAO reconstructor (multiple DM altitudes).
Development
Setup
git clone https://github.com/KeckObservatory/pyTomoAO.git
cd pyTomoAO
pip install -e ".[docs,dev]"
Code Style
Linting and formatting are handled by ruff, configured in
pyproject.toml and enforced by the Code health workflow:
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.
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:
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 for conventions and how publishing works.
Testing
The dev extra installs pytest and coverage:
pip install -e ".[dev]"
pytest
CI runs the suite against Python 3.10–3.14 and applies a coverage threshold. See the testing guide.
Changelog
See 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
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 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
Metadata
Release files for pyTomoAO 2.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| pytomoao-2.1.0.tar.gz | 129.8 kB | With provenance | Details for pytomoao-2.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| pytomoao-2.1.0-py3-none-any.whl | Python 3 | none | any | Details for pytomoao-2.1.0-py3-none-any.whl |
Total release size: 214.6 kB
Release files / pytomoao-2.1.0.tar.gz
| Download URL | pytomoao-2.1.0.tar.gz |
|---|---|
| Size | 129.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
ec29b861a482642b6945510f9033d498b8e27b0c1c71110465e1778c9e2121d1
|
|
BLAKE2b-256 checksum How to use checksums |
5ea721c2a0467fc3241d680ef26777b4665684e9d8097b9f2bd4b5879d3fc4b8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 31, 2026.
Transparency logRelease files / pytomoao-2.1.0-py3-none-any.whl
| Download URL | pytomoao-2.1.0-py3-none-any.whl |
|---|---|
| Size | 84.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
761056d6582eac498a3f9ea8e5f1ada13acbf90642ef9d8585a9f06b92fae5dc
|
|
BLAKE2b-256 checksum How to use checksums |
e58da6e94f7ab1d0036b824e7a62e3c6801aa7ab65b831d1f5334bb29319e464
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 31, 2026.
Transparency logSecurity for pyTomoAO 2.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for pytomoao-2.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 31, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.