User Guide

This guide covers the main concepts and features in more detail.

Configuration structure

TIPTOP configurations are organised into sections, each controlling a different part of the AO simulation:

Section	Description
`atmosphere`	Turbulence profile: seeing, outer scale, Cn2 layer heights/weights, wind
`telescope`	Pupil geometry: diameter, obscuration, resolution, static aberrations
`sources_science`	Where and at what wavelength to compute PSFs
`sources_HO`	High-order guide star positions and wavelength
`sources_LO`	Low-order guide star positions and wavelength (optional)
`sources_Focus`	Focus sensor source wavelength (MCAO systems only)
`sensor_science`	Science detector: pixel scale, field of view
`sensor_HO`	High-order wavefront sensor: type, lenslets, photon flux
`sensor_LO`	Low-order wavefront sensor (optional)
`sensor_Focus`	Focus sensor parameters (MCAO systems only)
`DM`	Deformable mirror: actuators, pitch, conjugation altitude
`RTC`	Real-time controller: loop gain, frame rate, delay

For full parameter descriptions, see the TIPTOP parameter documentation.

Tuple indexing

TipTop uses tuple indexing for clean parameter access:

# Read
tt["atmosphere", "Seeing"]          # single value
tt["atmosphere"]                     # whole section dict

# Write
tt["atmosphere", "Seeing"] = 0.6    # single value
tt["atmosphere"] = {...}             # replace whole section

SCAO vs MCAO systems

Single-conjugate AO (SCAO) systems like ERIS, MICADO_SCAO, and SPHERE use a single guide star and deformable mirror. Their configurations are simpler: no sources_LO, no sources_Focus/sensor_Focus sections.

Multi-conjugate AO (MCAO) systems like MORFEO and MAVIS use multiple laser guide stars, multiple natural guide stars, and multiple deformable mirrors. Their configurations include additional sections for low-order and focus sensing.

Both types work identically with TipTop — the optional sections are simply absent from SCAO templates.

Multi-wavelength PSFs

Request PSFs at multiple wavelengths by providing a list:

tt["sources_science", "Wavelength"] = [1.2e-6, 1.65e-6, 2.2e-6]
result = tt.generate_psf()

result.n_wavelengths  # 3
j_psf = result.psf_cube(0)  # J-band
h_psf = result.psf_cube(1)  # H-band
k_psf = result.psf_cube(2)  # K-band

Multi-position PSFs

Request PSFs at multiple field positions:

tt["sources_science", "Zenith"] = [0, 10, 20]     # arcsec from axis
tt["sources_science", "Azimuth"] = [0, 90, 180]    # degrees
result = tt.generate_psf()

result.x  # cartesian x-coordinates (arcsec)
result.y  # cartesian y-coordinates (arcsec)

# Get the PSF nearest to a specific position
psf = result.nearest_psf(x=5.0, y=0.0)

Plotting

TipTopResult.plot() provides a quick visualisation:

# Default: log scale, inferno colormap
result.plot()

# Linear scale
result.plot(log_scale=False)

# Specific wavelength and position
result.plot(wavelength_index=1, position_index=2)

# Pass kwargs to imshow
result.plot(cmap="viridis", vmin=-5, vmax=0)

For more control, access the numpy array directly:

import matplotlib.pyplot as plt
from matplotlib.colors import LogNorm

fig, axes = plt.subplots(1, 3, figsize=(15, 5))
for i in range(3):
    axes[i].imshow(result.psf_cube(i)[0], norm=LogNorm())
    axes[i].set_title(f"Wavelength {i}")

Reproducibility with diff()

The diff() method tracks exactly what you changed from the template, making it easy to document your simulation setup:

tt = TipTop("MICADO_SCAO")
tt["atmosphere", "Seeing"] = 0.5
tt["atmosphere", "L0"] = 30.0
tt["telescope", "ZenithAngle"] = 45.0

tt.diff()
# {'atmosphere': {'Seeing': (0.644, 0.5), 'L0': (25.0, 30.0)},
#  'telescope': {'ZenithAngle': (0.0, 45.0)}}

Keeping templates up to date

The check_ini_updates.py utility syncs instrument templates with the upstream TIPTOP repository on GitHub:

# Check for differences
python -m tiptop_ipy.check_ini_updates

# Update local files
python -m tiptop_ipy.check_ini_updates --update