pyrtc is an adaptive optics real-time control toolkit written in Python.
The user-facing name stays pyrtc.
For packaging only, the published PyPI package name is pyrtcao, while the Python import name remains pyRTC:
pip install pyrtcaoimport pyRTCDocumentation: https://pyrtc-ao.readthedocs.io/en/latest/
Developer Guide: https://pyrtc-ao.readthedocs.io/en/latest/guides/developers_guide.html
The benchmark section is intentionally near the top because performance is a primary design constraint for pyrtc.
These measurements were captured on the current GPU-enabled host with the closed-loop synthetic benchmark harness:
python -m benchmarks.ao_loop_bench --output benchmarks/readme_benchmark_report.json --iterations 300 --warmup 30 --system-sizes 10 20 60
python benchmarks/readme_benchmark_table.py --report benchmarks/readme_benchmark_report.json --output benchmarks/readme_benchmark_table.mdThe benchmark drives deterministic modal disturbances through synthetic PYWFS and SHWFS image formation, slope reduction, and a dense control update. That makes the reported numbers much closer to a real single-iteration AO control path than the earlier kernel-only table.
| Component | Value |
|---|---|
| CPU | AMD Ryzen 9 9950X3D 16-Core Processor |
| CPU Threads | 32 |
| GPU | NVIDIA GeForce RTX 5090 |
| GPU Memory | 32607 MiB |
| NVIDIA Driver | 580.126.09 |
| Python | 3.12.0 |
| Torch | 2.10.0+cu128 |
| CUDA | 12.8 |
Values are reported as p99 throughput / p99 latency.
| Loop | 10x10 CPU | 10x10 GPU | 20x20 CPU | 20x20 GPU | 60x60 CPU | 60x60 GPU |
|---|---|---|---|---|---|---|
| PYWFS full loop | 58.1 kHz / 17.2 us | 4.5 kHz / 219.9 us | 26.6 kHz / 37.6 us | 4.6 kHz / 218.5 us | 270 Hz / 3703.4 us | 3.0 kHz / 335.2 us |
| SHWFS full loop | 78.2 kHz / 12.8 us | 5.1 kHz / 195.0 us | 26.6 kHz / 37.6 us | 5.1 kHz / 196.7 us | 268 Hz / 3730.7 us | 3.5 kHz / 289.7 us |
For this host, the important pattern is the one we care about operationally: CPU wins the small 10x10 and 20x20 synthetic loops because launch overhead dominates, but the GPU is about an order of magnitude faster once the loop reaches the 60x60 regime. That crossover now shows up for both pyramid and Shack-Hartmann synthetic loops in the README numbers.
The benchmark artifacts committed for this host are:
benchmarks/readme_benchmark_report.jsonbenchmarks/readme_benchmark_table.md
Adaptive optics (AO) systems measure optical aberrations and apply corrections quickly enough to recover image quality in dynamic environments. pyrtc is aimed at the software layer that connects those measurements, reconstructions, and corrections.
The project is designed for:
- laboratory AO systems and hardware integration work
- simulated AO development and algorithm prototyping
- moderate-performance real-time control in Python
- controller research, including machine-learning-assisted control paths
The repo is being prepared for a 1.0.0 release. The current release policy is conservative:
- User-facing project name:
pyrtc - PyPI distribution name:
pyrtcao - Python import name:
pyRTC - CLI prefix:
pyrtc-* - Primary supported release surface for
1.0.x: Linux, Python 3.9-3.13 - macOS and Windows: smoke-tested in GitHub Actions, but not part of the primary supported deployment story for
1.0.0 - GPU behavior: benchmark-validated on a Linux CUDA host for synthetic loop workloads, but still target-environment validation required for operational use
- Hardware integrations: examples and reference implementations, not universal plug-and-play support
- Component-based AO pipeline built around wavefront sensing, slope processing, control, correction, telemetry, and science imaging
- Soft-RTC mode for single-process development and simulation workflows
- Hard-RTC mode for process-isolated hardware integration via shared memory and launcher utilities
- Optional viewer and benchmarking tools for stream inspection and performance checks
- Example hardware adapters and simulation-oriented examples under
pyRTC/hardwareandexamples/
pip install pyrtcaoOptional extras:
pip install pyrtcao[docs]
pip install pyrtcao[gpu]
pip install pyrtcao[viewer]git clone https://github.com/jacotay7/pyRTC.git
cd pyRTC
pip install .Optional source extras:
pip install .[docs]
pip install .[gpu]
pip install .[viewer]If GPU mode is configured through gpuDevice but PyTorch is unavailable, supported paths fall back to CPU mode with a warning instead of failing immediately.
Verify the install:
python -c "import pyRTC; print(pyRTC.__all__)"The best first end-to-end path today is the no-hardware synthetic Shack-Hartmann workflow under examples/synthetic_shwfs/.
Key files:
examples/synthetic_shwfs/config.yamlexamples/synthetic_shwfs/run_soft_rtc.py
Run it with:
python examples/synthetic_shwfs/run_soft_rtc.py --duration 15Every primary CLI and example entry point now uses the shared pyRTC logger. By default you get timestamped INFO logs on the console. You can override that per run with --log-level DEBUG, write per-process logs with --log-dir logs/, or force one exact file with --log-file session.log.
The same settings can be exported for multi-process or repeated runs:
export PYRTC_LOG_LEVEL=INFO
export PYRTC_LOG_DIR=./logs
export PYRTC_LOG_COLOR=1
python examples/synthetic_shwfs/run_soft_rtc.py --duration 15It publishes the normal wfs, signal2D, wfc2D, psfShort, and psfLong streams, so the standard viewer tools work unchanged while you evaluate the control flow and subclassing points.
Recommended composite viewer command while the demo is running:
pyrtc-view wfs signal2D wfc2D psfShort psfLong --geometry 2x3The documentation will live on Read the Docs. Placeholder entry points for now:
pyrtc is organized around a small set of component abstractions:
WavefrontSensorSlopesProcessLoopWavefrontCorrectorScienceCameraTelemetry
These components exchange data through shared-memory streams and can be assembled in two main ways:
soft-RTC: all relevant components run in one Python processhard-RTC: hardware-facing pieces run in separate Python processes and communicate through launchers/shared memory
Use soft-RTC first unless you have a clear need for process isolation or hardware-driver separation.
Real AO deployments are hardware-specific. The repo includes two kinds of support for that:
- abstract core classes for the AO pipeline
- example integrations in
pyRTC/hardware
These hardware files should be treated as reference implementations and starting points, not as a guarantee that every SDK and device combination will work unchanged.
For no-hardware exploration, start with the synthetic SHWFS example. For a richer simulated optical path, the OOPAO-based example remains available, but it is an external dependency and should be treated as the second example, not the first one.
Viewer and CLI tools:
pyrtc-view wfs --log-level INFO
pyrtc-shm-monitor --log-dir logs
pyrtc-clear-shms --log-level DEBUG
pyrtc-measure-latency signal wfc --log-file latency.logPerformance smoke report:
python benchmarks/perf_smoke.py --output perf_smoke_report.json --log-dir logsSynthetic closed-loop AO benchmark:
pyrtc-ao-loop-bench --output ao_loop_bench_report.json --iterations 300 --warmup 30 --system-sizes 10 20 60
python benchmarks/readme_benchmark_table.py --report ao_loop_bench_report.json --output ao_loop_benchmark_table.md
python benchmarks/check_perf_baseline.py --current ao_loop_bench_report.json --baseline benchmarks/ao_loop_bench_baseline.jsonCore compute benchmark:
pyrtc-core-bench --quick --cpu-only --output core_compute_bench_report.json --log-level INFORun without --cpu-only to include GPU kernels when CUDA and PyTorch are available.
The committed closed-loop baseline for the README host is benchmarks/ao_loop_bench_baseline.json.
The shared logging environment variables are:
PYRTC_LOG_LEVEL: default log level, usuallyINFOorDEBUGPYRTC_LOG_DIR: write one log file per process into a directoryPYRTC_LOG_FILE: write to one exact file path for single-process runsPYRTC_LOG_COLOR: set to0to disable ANSI colorsPYRTC_LOG_CONSOLE: set to0to disable console logging when file logs are enough
Hard-RTC child processes inherit these settings automatically through the launcher, so one PYRTC_LOG_DIR is enough to collect parent and child logs together.
- The package is being prepared for a stable community-facing release, but not every platform or hardware stack is validated equally.
- Linux is the primary supported environment for
1.0.x. - macOS and Windows have smoke workflow coverage, but release validation and deployment guidance remain Linux-first.
- GPU support is validated in this repo through synthetic CPU/GPU benchmark coverage and should still be checked in the target environment before operational use.
- Example scripts and hardware adapters are intended to shorten development time, not replace system-specific commissioning.
Maintainer and contributor workflow guidance is being consolidated into the docs. For now, use the Developer Guide placeholder link near the top of this README.
For release validation from a source checkout, the built-wheel smoke path is automated:
python -m build
python -m twine check dist/*
python pyRTC/scripts/validate_dist_install.py --dist-dir distThe tracked release plan for the first stable version lives in RELEASE_1_0_PLAN.md.
The GitHub Actions publish workflow lives in .github/workflows/publish-package.yml.
For feedback, collaboration, and feature requests: jtaylor@keck.hawaii.edu