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
sharefraction 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].