API Reference

TipTop

class tiptop_ipy.TipTop(instrument=None, ini_file=None)[source]

Main interface to the TIPTOP microservice.

Usage:

tt = TipTop("MICADO_SCAO")           # Load from template
tt["atmosphere", "Seeing"] = 0.6      # Tweak parameters
tt["telescope", "ZenithAngle"] = 15.0
result = tt.generate_psf()            # Run simulation
result.plot()                         # View PSF

Parameters:

instrument (str, optional) – Template name (e.g. “MICADO_SCAO”, “ERIS”, “MORFEO”). Matched case-insensitively against available templates.
ini_file (str, optional) – Path to a custom .ini file.
provided. (Either instrument or ini_file must be)
given (If neither is)
used. (defaults are)

MAX_FOV = 512

Hard limit on sensor_science.FieldOfView when loading INI files.

Templates and user INI files may specify very large fields of view (e.g. 2048 for MICADO) that cause the ESO server to time out. Values above this cap are silently reduced on load. Users can still increase the value afterwards via tt["sensor_science", "FieldOfView"] = N.

__getitem__(key)[source]

Access config values.

tt[“atmosphere”] returns the whole section dict. tt[“atmosphere”, “Seeing”] returns a single value.

__setitem__(key, value)[source]

Set config values.

tt[“atmosphere”, “Seeing”] = 0.6 tt[“atmosphere”] = {“Seeing”: 0.6, …} # replace whole section

generate_psf(timeout=120, force_simulation=False, save_psds=False)[source]

Send config to TIPTOP server and return a TipTopResult.

Validates config before sending and shows progress feedback.

Parameters:

timeout (int) – Request timeout in seconds.
force_simulation (bool) – If True, bypass the server cache and force a fresh simulation.
save_psds (bool) – If True, include the high-order PSD in the output FITS file.

Returns:

result – The simulation result with PSF data.

Return type:

TipTopResult

validate()[source]

Check config for errors/warnings without sending.

Returns:: issues – List of error/warning strings. Empty = valid.
Return type:: list[str]

save(path)[source]

Save current config as .ini file.

Parameters:: path (str) – Output file path.

load(path)[source]

Load config from .ini file, replacing current config.

Parameters:: path (str) – Path to .ini file.

reset()[source]: Reset to original template values.

diff()[source]

Show what changed from the template.

Returns:: changes – Nested dict of {section: {key: (old, new)}} for changed values.
Return type:: dict

property sections: List of config section names.

property ini_contents: The INI string representation of the current config.

property wavelengths

Science wavelengths as an astropy Quantity in microns.

Reads sources_science.Wavelength (stored in metres internally) and returns values as u.um.

Returns:: wavelengths – Wavelengths in microns.
Return type:: astropy.units.Quantity

property positions

Science source positions as (x, y) Quantities in arcsec.

Computed from sources_science.Zenith (radial distance) and sources_science.Azimuth (angle in degrees).

Returns:: x, y – Cartesian coordinates in arcsec.
Return type:: astropy.units.Quantity

add_off_axis_positions(positions)[source]

Set science source positions from (x, y) coordinates.

Converts Cartesian (x, y) to polar (Zenith, Azimuth) and updates sources_science.Zenith and sources_science.Azimuth.

Parameters:: positions (tuple or list of tuples) – A single (x, y) tuple or a list of (x, y) tuples. If values are astropy Quantities, they are converted to arcsec. If plain floats, assumed to be in arcsec.

Examples

tt = TipTop("ERIS")
tt.add_off_axis_positions((0, 0))           # on-axis only
tt.add_off_axis_positions([(0, 0), (5, 5)])  # on-axis + 5",5"

# With units
import astropy.units as u
tt.add_off_axis_positions([(0, 0)*u.arcsec, (5, 5)*u.arcsec])

__repr__()[source]: Return repr(self).

classmethod list_instruments()[source]

List available instrument templates.

Returns:: names – Sorted list of instrument template names.
Return type:: list[str]

static ping()[source]

Check if the TIPTOP server is reachable.

Returns:: reachable
Return type:: bool

TipTopResult

class tiptop_ipy.TipTopResult(hdulist)[source]

Wraps the FITS HDUList returned by the TIPTOP server.

Provides convenient access to PSF data, coordinates, plotting, and Jupyter display.

The TIPTOP server returns a FITS file with 5 HDUs:

[0] PrimaryHDU — header with config parameters and timing
[1] ImageHDU PSF CUBE — AO-corrected PSF(s), shape (N, FOV, FOV)
[2] ImageHDU OPEN-LOOP PSF — seeing-limited PSF, shape (FOV, FOV)
[3] ImageHDU DIFFRACTION LIMITED PSF — perfect PSF, shape (FOV, FOV)
[4] ImageHDU Final PSFs profiles — radial profiles

For multi-wavelength requests, there is one PSF CUBE HDU per wavelength. Coordinates are stored in the PSF CUBE header cards (CCX0000, CCY0000, …).

Parameters:: hdulist (fits.HDUList) – The FITS HDUList from the TIPTOP server.

hdulist

The underlying FITS data.

Type:: fits.HDUList

property psf

The PSF image data from the first PSF CUBE HDU.

For single-position results this is shape (1, H, W). For multi-position results this is shape (N, H, W).

property open_loop_psf: The seeing-limited (open-loop) PSF, shape (H, W).

property diffraction_psf: The diffraction-limited PSF, shape (H, W).

property has_psd: Whether the result contains a Power Spectral Density HDU.

property psd: The high-order PSD, shape (nPointings, N, N), units nm².

property x: X-axis coordinates of PSF positions in arcsec.

property y: Y-axis coordinates of PSF positions in arcsec.

property n_wavelengths: Number of wavelength channels (PSF CUBE HDUs).

property strehl: Strehl ratios for each position (from PSF CUBE header).

property fwhm: FWHM values in mas for each position (from PSF CUBE header).

psf_cube(wavelength_index=0)[source]

Get PSF cube for a specific wavelength index.

Parameters:: wavelength_index (int) – Index into the list of wavelength channels.
Returns:: data – PSF cube or image.
Return type:: np.ndarray

nearest_psf(x, y, wavelength_index=0)[source]

Return the PSF nearest to (x, y) in arcsec.

Parameters:

x (float) – Position in arcsec.
y (float) – Position in arcsec.
wavelength_index (int) – Which wavelength channel to use.

Returns:

psf – 2D PSF image.

Return type:

np.ndarray

plot(log_scale=True, wavelength_index=0, position_index=0, **kwargs)[source]

Quick PSF plot with matplotlib. Works in Jupyter.

Parameters:

log_scale (bool) – Use log10 scaling for the colormap.
wavelength_index (int) – Which wavelength channel to plot.
position_index (int) – Which position in the cube to plot.
**kwargs – Passed to matplotlib.pyplot.imshow.

writeto(filename, overwrite=False)[source]

Save FITS to disk.

Parameters:

filename (str) – Output file path.
overwrite (bool) – Overwrite existing file.

__repr__()[source]: Return repr(self).

INI Parser

Reliable INI parser for TIPTOP-style .ini files.

TIPTOP .ini files are non-standard: they use Python list literals, scientific notation, None values, both ‘;’ and ‘#’ comments, and sometimes have ‘=’ inside string values.

tiptop_ipy.ini_parser.parse_ini(path_or_string)[source]

Parse a TIPTOP .ini file into nested dict {section: {key: value}}.

Parameters:: path_or_string (str or Path) – Either a file path or the raw INI string contents.
Returns:: config – Nested dictionary of {section: {key: value}}.
Return type:: dict[str, dict[str, Any]]

tiptop_ipy.ini_parser.write_ini(config, path=None)[source]

Write config dict to .ini format string (and optionally to file).

Parameters:

config (dict[str, dict[str, Any]]) – Nested dictionary of {section: {key: value}}.
path (str or Path, optional) – If provided, write to this file path.

Returns:

ini_string – The formatted INI string.

Return type:

str

Validation

Config validation against the defaults.yaml schema.

tiptop_ipy.validation.validate_config(config, defaults=None)[source]

Validate a config dict against the defaults.yaml schema.

Parameters:

config (dict[str, dict[str, Any]]) – The configuration to validate (from ini_parser.parse_ini).
defaults (dict, optional) – The defaults schema. If None, loads from defaults.yaml.

Returns:

issues – List of warning/error strings. Empty list means valid.

Return type:

list[str]

Server Configuration

tiptop_ipy.set_server(name_or_url)[source]

Set the TIPTOP server.

Parameters:: name_or_url (str) – Either a server name (“eso”, “univie”) or a full URL.

Examples

>>> set_server("univie")       # University of Vienna (default)
>>> set_server("http://...")    # Custom URL

tiptop_ipy.get_server()[source]: Return the current TIPTOP server URL.

tiptop_ipy.SERVERS = {'eso': 'https://www.eso.org/p2services/any/tiptop', 'univie': 'https://tiptop.univie.ac.at/api'}

dict() -> new empty dictionary dict(mapping) -> new dictionary initialized from a mapping object’s

(key, value) pairs

dict(iterable) -> new dictionary initialized as if via:: d = {} for k, v in iterable:

d[k] = v
dict(**kwargs) -> new dictionary initialized with the name=value pairs: in the keyword argument list. For example: dict(one=1, two=2)

Utilities

tiptop_ipy.utils.list_instruments(include_path=False)[source]

List available instrument template names.

Parameters:: include_path (bool) – If True, return full paths instead of just names.
Returns:: names – Sorted list of instrument names (without .ini extension) or full paths if include_path is True.
Return type:: list[str]

tiptop_ipy.utils.query_tiptop_server(ini_content, timeout=120, force_simulation=False, save_psds=False)[source]

Send an INI config to the TIPTOP server and return the FITS result.

Routes to ESO (synchronous) or custom server (async polling) based on the current server URL set via set_server() or TIPTOP_SERVER_URL.

Parameters:

ini_content (str) – The raw contents of a TIPTOP config .ini file.
timeout (int) – Request timeout in seconds.
force_simulation (bool) – If True, bypass the server cache and force a fresh simulation. Only supported on custom servers (not ESO).
save_psds (bool) – If True, include the high-order PSD in the output FITS file. Only supported on custom servers (not ESO).

Returns:

hdus – A FITS file with extensions: - [0] PrimaryHDU: header info - [1] ImageHDU: PSF cube(s) - [-1] ImageHDU: (2, N) cartesian coordinates of PSF positions

Return type:

fits.HDUList