Getting Started

This guide is the shortest path from installation to a working pyRTC session.

Package Name

Install the project from PyPI as pyrtcao:

pip install pyrtcao

Import it in Python as pyRTC:

import pyRTC

If you are working from a source checkout instead of PyPI:

git clone https://github.com/jacotay7/pyRTC.git
cd pyRTC
pip install .

Optional extras:

pip install pyrtcao[docs]
pip install pyrtcao[gpu]
pip install pyrtcao[viewer]

Core Concepts

pyRTC is organized around adaptive optics components that exchange data through shared memory streams. The core objects you will usually work with are:

  • WavefrontSensor: produces images

  • SlopesProcess: converts images into wavefront signal products

  • Loop: reconstructs and applies control updates

  • WavefrontCorrector: receives and outputs correction commands

  • ScienceCamera: captures science images and derived metrics

  • Telemetry: persists selected data products to disk

The package supports two common operating styles:

  • soft-RTC: instantiate the objects directly in one Python process

  • hard-RTC: run hardware-facing components in separate processes and interact through launchers/shared memory

For first use, start with soft-RTC or the simulation examples.

Minimal Import Check

After installation, verify that the public package imports cleanly:

python -c "import pyRTC; print(pyRTC.__all__)"

Minimal Component Example

The base component class starts configured functions in worker threads. A minimal configuration looks like:

from pyRTC.pyRTCComponent import pyRTCComponent

component = pyRTCComponent(
         {
                  "affinity": 0,
                  "functions": [],
         }
)

This is useful for understanding the execution model, but practical systems usually instantiate concrete AO components such as WavefrontSensor, Loop, and WavefrontCorrector.

Configuration Basics

Configuration is supplied as nested dictionaries or YAML files. A typical AO setup contains sections such as:

loop:
  gain: 0.1
  numDroppedModes: 0
  functions:
         - standardIntegrator

wfs:
  name: OOPAOWFS
  width: 28
  height: 28
  darkCount: 1000
  functions:
         - expose

slopes:
  type: PYWFS
  signalType: slopes
  functions:
         - computeSignal

wfc:
  name: OOPAOWFC
  numActuators: 100
  numModes: 80
  functions:
         - sendToHardware

Required keys depend on the component. For example, wavefront-corrector configs require name, numActuators, and numModes.

Suggested First Run

For a practical first run, use the synthetic Shack-Hartmann example described in Synthetic SHWFS Example. That path needs no hardware and no external simulator, but it still exercises the standard WavefrontSensor -> SlopesProcess -> Loop -> WavefrontCorrector chain and publishes the same viewer-friendly streams you will use later with real devices.

After that, move to the OOPAO-based path in PYWFS Examples if you want a richer simulated optical model. The script-driven entry point is:

python examples/scao/run_soft_rtc.py --duration 10

Use the companion notebook only once you want to step through the same workflow interactively.

Viewer and Utility Commands

If you installed the viewer extra, the package exposes command-line tools for inspecting shared-memory streams:

pyrtc-view wfs
pyrtc-shm-monitor
pyrtc-clear-shms

The performance benchmark entry point is also available after installation:

pyrtc-core-bench --quick --cpu-only --output core_compute_bench_report.json

Logging

The main CLI tools and example entry points use the shared pyRTC logger. By default they log at INFO level to the console with timestamps.

Useful one-off overrides:

pyrtc-view wfs --log-level DEBUG
pyrtc-shm-monitor --log-dir logs
pyrtc-measure-latency signal wfc --log-file latency.log

You can also set logging once in the shell for multi-process 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 15

Supported environment variables are:

  • PYRTC_LOG_LEVEL

  • PYRTC_LOG_DIR

  • PYRTC_LOG_FILE

  • PYRTC_LOG_COLOR

  • PYRTC_LOG_CONSOLE

When you use hard-RTC, child processes inherit the logging environment automatically.

Troubleshooting

  • If GPU mode is configured but PyTorch is unavailable, pyRTC falls back to CPU mode for supported paths.

  • If viewer commands fail, install the viewer extra: pip install pyrtcao[viewer]

  • If a component fails at startup, check the YAML keys first; several components validate required config fields eagerly.

  • If a multi-process run is hard to diagnose, set PYRTC_LOG_DIR=./logs before launching so each process writes a separate file.

  • For first-time development, stay on Linux unless you have validated your target platform locally.

Next Steps

  • Read the component pages for the classes you plan to extend.

  • Run the simulated example workflow.

  • Decide early whether your deployment needs soft-RTC or hard-RTC mode.