Skip to content

pyturb

Fast, GPU-optional atmospheric turbulence for adaptive optics.

pyturb generates the optical path differences (OPD) an adaptive-optics system sees through the atmosphere: full layered turbulence for a representative sky, with per-layer wind, frozen-flow time evolution, off-axis directions, and standard site profiles. It runs on NumPy by default and switches to CUDA (via CuPy) with a single argument.

import pyturb

atm = pyturb.Atmosphere.from_profile(
    "paranal-median", seeing=0.8, zenith_angle=30, diameter=8.0, n=512, seed=1,
)
print(atm.r0, atm.theta0, atm.tau0)          # Fried param, iso angle, tau0

for t, opd in atm.frames(dt=1e-3, steps=200):
    ...                                      # (512, 512) OPD in metres
# periodic default engine: stay under atm.time_to_wrap, or use engine="extrude"

Why pyturb

  • Fast. A 9-layer 512² atmosphere at ~4,600 frames/s on an RTX 4060 (CUDA-graph replay), ~6,700 frames/s as a batched time series, and ~30,000 independent 9-layer 512² OPDs/s on an RTX 5090 — see Performance and Comparison.
  • Correct. The spatial statistics match von Kármán/Kolmogorov theory to a few percent at separations from a few pixels up to a quarter of the screen, enforced by tests — see Validation for the details and limits.
  • Complete. Named site profiles, off-axis tomography, boiling, LGS cone, OPD-native output, scintillated pupil fields, and a diagnostics toolkit (pyturb.analysis).

Install

pip install pyturb                 # CPU
pip install pyturb[cuda12]         # + CuPy for CUDA 12 (or [cuda13], [cuda11])
pip install pyturb[fits]           # + FITS I/O

The cuda12/cuda13 extras include CUDA header wheels (cupy-cudaXXx[ctk]), which CuPy 14 needs to compile its kernels. If you install CuPy on its own and the first GPU call fails with "Failed to find CUDA headers", add the [ctk] extra or set CUDA_PATH to a CUDA toolkit.

Where to next

  • Quickstart — the three-line path to OPD frames.
  • Concepts — r0, L0, Cn², θ0, τ0 for newcomers, and the (y, x) axis conventions.
  • Migrating to 2.0 — the x/y axis change from 1.x.
  • Validation — the evidence, regenerated by CI.
  • Comparison — head-to-head vs aotools, soapy, HCIPy.
  • Interop — recipes for HCIPy, poppy, DM fitting.
  • API reference — every public function and class.