Skip to main content

pyTomoAO

Tests Docs Code health Ruff PyPI version Python versions License: MIT

📖 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() (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 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:

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)

Source distribution for pyTomoAO 2.1.0
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)

Table of built distributions (wheels) for pyTomoAO 2.1.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page