API Reference

Simulation

tiptop.overallSimulation(path2param, parametersFile, outputDir, outputFile, doConvolve=True, doPlot=False, returnRes=False, returnMetrics=False, addSrAndFwhm=True, verbose=False, getHoErrorBreakDown=False, ensquaredEnergy=False, eeRadiusInMas=50, savePSDs=False, saveJson=False, gpuIndex=0, exactMultiWavelengthPSD=False)

Run a full TIPTOP simulation (HO PSD, LO residuals, PSFs) from a parameter file.

Parameters:
  • path2param (str) – required, path to the folder containing the parameter file.

  • parametersFile (str) – required, name of the parameter file without the extension (.ini or .yml).

  • outputDir (str) – required, path to the folder in which to write the output.

  • outputFile (str) – required, name of the output file without the extension.

  • doConvolve (bool) – optional default: True, if LO is enabled, convolve the HO PSFs with the LO residual (tip/tilt) kernel of each direction. If False, the HO PSFs are returned without this convolution.

  • doPlot (bool) – optional default: False, display the resulting PSFs.

  • returnRes (bool) – optional default: False, return the residual errors instead of saving the results (see return).

  • returnMetrics (bool) – optional default: False, return Strehl ratio, FWHM and encircled energy within eeRadiusInMas instead of saving the results (ignored if returnRes is True).

  • addSrAndFwhm (bool) – optional default: True, add SR, FWHM and EE of each PSF in the header of the output fits file.

  • verbose (bool) – optional default: False, print all messages.

  • getHoErrorBreakDown (bool) – optional default: False, compute and print the HO error breakdown.

  • ensquaredEnergy (bool) – optional default: False, compute the ensquared energy instead of the encircled energy.

  • eeRadiusInMas (float) – optional default: 50, radius used for the encircled energy (if ensquaredEnergy is True, half the side of the square).

  • savePSDs (bool) – optional default: False, also save the PSDs in the output fits file.

  • saveJson (bool) – optional default: False, save the radial PSF profiles in <outputFile>1D_PSF.json.

  • gpuIndex (int) – optional default: 0, index of the GPU used for the simulation (if GPU is available).

  • exactMultiWavelengthPSD (bool) – optional default: False, with more than one science wavelength, compute one exact PSD grid per wavelength, so that each PSF is identical to a single-wavelength run. If False, all wavelengths share one approximate grid. If True, memory and computation time can be significantly higher than with False: the HO PSD (including reconstructor and controller) is computed and stored once per wavelength, so the cost grows roughly with the number of wavelengths.

Returns:

if returnRes, HO residual in nm RMS per science direction (and LO residual in nm RMS per direction, if LO is enabled); if returnMetrics, (sr, fwhm, ee); otherwise None, and the results are saved in <outputDir>/<outputFile>.fits.

Return type:

numpy.ndarray or tuple or None

Asterism selection

tiptop.tiptop.asterismSelection(simulName, path2param, parametersFile, outputDir, outputFile, doPlot=False, returnRes=False, returnMetrics=True, addSrAndFwhm=True, verbose=False, getHoErrorBreakDown=False, ensquaredEnergy=False, eeRadiusInMas=50, doConvolve=False, plotInComputeAsterisms=False, progressStatus=False, gpuIndex=0)

Evaluate the asterisms defined in the [ASTERISM_SELECTION] section (requires LO).

Parameters:
  • simulName (str) – required, name of the simulation, used as prefix of the saved/reloaded .npy files.

  • path2param (str) – required, path to the folder containing the parameter file.

  • parametersFile (str) – required, name of the parameter file without the extension (.ini or .yml).

  • outputDir (str) – required, path to the folder in which to write the output.

  • outputFile (str) – required, name of the output file without the extension.

  • doPlot (bool) – optional default: False, display intermediate plots.

  • returnRes (bool) – optional default: False, return the HO and LO residuals (see return).

  • returnMetrics (bool) – optional default: True, return Strehl ratio, FWHM, encircled energy and covariance ellipses (ignored if returnRes is True).

  • addSrAndFwhm (bool) – optional default: True, add SR and FWHM in the header of the output fits file.

  • verbose (bool) – optional default: False, print all messages.

  • getHoErrorBreakDown (bool) – optional default: False, currently ignored.

  • ensquaredEnergy (bool) – optional default: False, currently ignored.

  • eeRadiusInMas (float) – optional default: 50, radius used for the encircled energy.

  • doConvolve (bool) – optional default: False, convolve the HO PSFs with the LO residual kernel of each asterism.

  • plotInComputeAsterisms (bool) – optional default: False, display the asterisms.

  • progressStatus (bool) – optional default: False, display the progress status.

  • gpuIndex (int) – optional default: 0, index of the GPU used for the simulation (if GPU is available).

Returns:

if returnRes, (HO_res, LO_res, simulation); if returnMetrics, (sr, fwhm, ee, cov_ellipses, simulation); otherwise simulation. None if there is no [ASTERISM_SELECTION] section or LO is not enabled.

Return type:

tuple or asterismSimulation or None

tiptop.tiptop.hoAsterismSelection(simulName, path2param, parametersFile, outputDir, outputFile, doPlot=False, returnRes=False, returnMetrics=True, addSrAndFwhm=True, verbose=False, getHoErrorBreakDown=False, ensquaredEnergy=False, eeRadiusInMas=50, progressStatus=False, gpuIndex=0)

Evaluate the HO asterisms defined in the [HO_ASTERISM_SELECTION] section, using P3 only (no LO).

Parameters:
  • simulName (str) – required, name of the simulation, used as prefix of the saved/reloaded .npy files.

  • path2param (str) – required, path to the folder containing the parameter file.

  • parametersFile (str) – required, name of the parameter file without the extension (.ini or .yml).

  • outputDir (str) – required, path to the folder in which to write the output.

  • outputFile (str) – required, name of the output file without the extension.

  • doPlot (bool) – optional default: False, plot the results.

  • returnRes (bool) – optional default: False, return the HO residuals (see return).

  • returnMetrics (bool) – optional default: True, return Strehl ratio, FWHM and encircled energy (ignored if returnRes is True).

  • addSrAndFwhm (bool) – optional default: True, add SR and FWHM in the header of the output fits file.

  • verbose (bool) – optional default: False, print all messages.

  • getHoErrorBreakDown (bool) – optional default: False, compute the HO error breakdown.

  • ensquaredEnergy (bool) – optional default: False, currently ignored.

  • eeRadiusInMas (float) – optional default: 50, radius used for the encircled energy.

  • progressStatus (bool) – optional default: False, display the progress status.

  • gpuIndex (int) – optional default: 0, index of the GPU used for the simulation (if GPU is available).

Returns:

if returnRes, (HO_res, simulation); if returnMetrics, (sr, fwhm, ee, simulation); otherwise simulation. None if there is no [HO_ASTERISM_SELECTION] section.

Return type:

tuple or asterismSimulationHo or None

tiptop.tiptop.reloadAsterismSelection(simulName, path2param, parametersFile, outputDir, outputFile, doPlot=False, returnRes=False, returnMetrics=True, addSrAndFwhm=True, verbose=False, getHoErrorBreakDown=False, ensquaredEnergy=False, eeRadiusInMas=50, gpuIndex=0)

Reload the results of a previous asterismSelection run (the .npy files saved in outputDir with prefix simulName).

Parameters:
  • simulName (str) – required, name of the simulation, used as prefix of the saved/reloaded .npy files.

  • path2param (str) – required, path to the folder containing the parameter file.

  • parametersFile (str) – required, name of the parameter file without the extension (.ini or .yml).

  • outputDir (str) – required, path to the folder in which to write the output.

  • outputFile (str) – required, name of the output file without the extension.

  • doPlot (bool) – optional default: False, display plots in later processing (e.g. heuristic model fit).

  • addSrAndFwhm (bool) – optional default: True, passed to the simulation object.

  • verbose (bool) – optional default: False, print all messages.

  • getHoErrorBreakDown (bool) – optional default: False, passed to the simulation object.

  • returnRes – currently ignored.

  • returnMetrics – currently ignored.

  • ensquaredEnergy – currently ignored.

  • eeRadiusInMas – currently ignored.

  • gpuIndex (int) – optional default: 0, index of the GPU used (if GPU is available).

Returns:

(sr, fwhm, ee, cov_ellipses, simulation)

Return type:

tuple

tiptop.tiptop.generateHeuristicModel(simulName, path2param, parametersFile, outputDir, outputFile, doPlot=False, doTest=True, share=0.9, eeRadiusInMas=50, gpuIndex=0)

Run asterismSelection, then fit a heuristic model of the asterism metrics on the first share fraction of the fields and, optionally, test it on the remaining ones. The model is saved in outputDir as <parametersFile>_hmodel.

Parameters:
  • simulName (str) – required, name of the simulation, used as prefix of the saved/reloaded .npy files.

  • path2param (str) – required, path to the folder containing the parameter file.

  • parametersFile (str) – required, name of the parameter file without the extension (.ini or .yml).

  • outputDir (str) – required, path to the folder in which to write the output.

  • outputFile (str) – required, name of the output file without the extension.

  • doPlot (bool) – optional default: False, display the fit and test plots.

  • doTest (bool) – optional default: True, test the model on the fields not used for the fit.

  • share (float) – optional default: 0.9, fraction of the fields used for the fit.

  • eeRadiusInMas – currently ignored.

  • gpuIndex (int) – optional default: 0, index of the GPU used (if GPU is available).

Returns:

the asterism simulation object

Return type:

asterismSimulation

Utilities

tiptop.tiptop.gpuSelect(gpuIndex)

Select the GPU used by P3 and MASTSEL (no effect if neither runs on GPU).

Parameters:

gpuIndex (int) – required, GPU index; if larger than the last available index, a warning is printed and the current device is kept.

tiptop.tiptopUtils.plot_directions(parser, ticks_interval=5, labels=None, LO_labels=None, science=True, low_order=True, max_pos=None, add_legend=True)

Polar plot with science and GS (sources_HO and sources_LO) directions

Parameters:
  • parser (configparser object) – required, parameters object

  • ticks_interval (int) – optional default=5, size of interval for ticks in the figure

  • labels (list) – optional default=None, list of strings to be plotted next to the science sources

  • LO_labels (list) – optional default=None, list of strings to be plotted next to the LO sources

  • science (bool) – optional default=True, activate plot of science sources

  • low_order (bool) – optional default=True, activate plot of LO sources

  • max_pos (float) – optional default=None, maximum distance from axis

  • add_legend (bool) – optional default=True, activate legend

Returns:

fig, ax

Return type:

objects

Atmospheric profiles

Parametric Cn2 profiles with given integrated parameters, coherent with the Stereo-SCIDAR Paranal statistics.

Model of a normalized profile w(h) (sum = 1), with f the GL fraction (Cn2 below 1 km):

w = GL bump      share g0 in the ground bin, the rest in a fixed tail up to 1 km
  + background   fixed shape, B (1 - f) / (1 - b_gl)   (its part above 1 km is B (1 - f))
  + 5 bumps      low [1-4 km], lowmid [3-7], mid [5-10], jet [10-17], high [17-25]:
                 Gaussians with a fixed FWHM per window, total power (1 - B)(1 - f)

g0, bump heights and bump power shares are drawn from the Stereo-SCIDAR statistics (Gaussian copula), or set to their medians. theta0 fixes mu = sum(w h^5/3), because theta0 = 0.314 r0 / mu^(3/5); the constraints are solved in closed form (mu is linear in the free parameter):

theta0 only        -> f is solved;
theta0 + f         -> the jet power is solved, exchanged with the other bumps; if the
                      jet reaches a limit, the next bump from the ground up takes over;
f only / neither   -> theta0 is an output (f = Stereo-SCIDAR median if not given).

The model constants are in data/cn2_bump_model.npz, computed by bump_statistics.py (TIPTOP_scripts/atmo) from the Stereo-SCIDAR Paranal database 2016-2021. All the quantities are at zenith and 500 nm.

tiptop.atmoProfile.generateProfile(r0: float, theta0: float = None, glFraction: float = None, layerHeights=array([0., 230., 490., 780., 1130., 1520., 1980., 2500., 3100., 3790., 4590., 5510., 6560., 7770., 9170., 10770., 12620., 14740., 17190., 20000.]), rng: Generator = None, maxTries: int = 100)

Generate a normalized Cn2 profile with given theta0 and/or GL fraction.

See the module docstring for the model.

Parameters:
  • r0 (float) – Fried parameter at 500 nm, zenith [m]. Only used to convert theta0.

  • theta0 (float, optional) – Isoplanatic angle at 500 nm, zenith [arcsec].

  • glFraction (float, optional) – Fraction of the Cn2 below 1 km.

  • layerHeights (array_like or None) – Output layer altitudes [m] (at least one <= 1 km and one above); default: the 20 layers of logGrid(). theta0 and glFraction are imposed on these layers. None returns the 250 m grid GRID.

  • rng (numpy.random.Generator, optional) – Random draw of g0, bump heights and power shares. None gives the median profile.

  • maxTries (int) – Random draws incompatible with (theta0, glFraction) are redrawn up to this many times.

Returns:

  • heights (numpy.ndarray) – Layer altitudes [m].

  • weights (numpy.ndarray) – Normalized Cn2 weights (sum = 1).

  • info (dict) – ‘glFraction’, ‘g0’, ‘bumpHeights’ [m] and ‘bumpPowers’.

Raises:

ValueError – If (theta0, glFraction) cannot be reached by the model.

Warns:

UserWarning – If the GL fraction is outside the range observed at Paranal (p1-p99).

tiptop.atmoProfile.layerWind(windSpeed, windDirection, layerHeights, weights) → tuple

Wind speed and direction on the layers, averaged with Cn2 weights.

Speed: (sum w v^5/3 / sum w)^(3/5) in each layer, so that tau0 is preserved. Direction: Cn2-weighted circular mean.

Parameters:
  • windSpeed (array_like) – Wind speed [m/s] and direction [deg] on GRID (250 m).

  • windDirection (array_like) – Wind speed [m/s] and direction [deg] on GRID (250 m).

  • layerHeights (array_like) – Layer altitudes [m].

  • weights (array_like) – Cn2 weights on GRID (e.g. generateProfile(…, layerHeights=None)).

Returns:

speed, direction – Wind speed [m/s] and direction [deg] on the layers.

Return type:

numpy.ndarray

tiptop.atmoProfile.logGrid(n: int = 20, h0: float = 1500.0, hTop: float = 20000.0) → ndarray

Layer altitudes uniform in log(1 + h/h0), from 0 to hTop.

Spacing ~ (h + h0): about linear below h0, logarithmic above. With the defaults, ~250 m near the ground and ~2.5 km near 20 km. On MORFEO, 20 such layers give the same Strehl ratio as 40 uniform layers within 0.004 on average (TIPTOP_scripts/atmo/ compare_layers.py, 5 conditions of Agapito+ 2021).

Parameters:
  • n (int) – Number of layers.

  • h0 (float) – Transition altitude between linear and logarithmic spacing [m].

  • hTop (float) – Altitude of the highest layer [m].

Returns:

Layer altitudes [m], rounded to 10 m.

Return type:

numpy.ndarray

tiptop.atmoProfile.r0ToSeeing(r0: float, wvl: float = 5e-07) → float

Seeing FWHM [arcsec] from the Fried parameter [m]: seeing = 0.98 wvl / r0.

tiptop.atmoProfile.seeingToR0(seeing: float, wvl: float = 5e-07) → float

Fried parameter [m] from the seeing FWHM [arcsec]: seeing = 0.98 wvl / r0.

tiptop.atmoProfile.theta0FromProfile(heights, weights, r0: float) → float

Isoplanatic angle [arcsec]: theta0 = 0.314 r0 / (sum w h^5/3)^(3/5).

Parameters:
  • heights (array_like) – Layer altitudes [m].

  • weights (array_like) – Cn2 weights, normalized to sum 1.

  • r0 (float) – Fried parameter at the same wavelength [m].