Parameter files explained

Introduction

This page provides an explanation of the structure and syntax of the .ini parameter files required by TipTop (see the TipTop Quickstart Tutorial). It details what your parameter file should contain and the various parameters you can set. Example parameter files are available in our GitHub repository, and one is also presented in the TipTop Quickstart Tutorial.

The parameter files are divided in sections and they can contain multiple parameter. It is very important that each parameter be placed in the appropriate section. The section starts with its name between [] and ends either with the end of file or with the next section. The order they are placed in the file does not matter.

Overview

The following table resume the what the parameter file should contain and what is mandatory.

Section	Required?
[telescope]	Yes
[atmosphere]	Yes
[sources_science]	Yes
[source_HO]	Yes
[source_LO]	No/Yes if [sensor_LO defined]
[sources_Focus]	No/Yes if [sensor_Focus defined]
[sensor_science]	Yes
[sensor_HO]	Yes
[sensor_LO]	No/Yes if [sources_LO defined]
[sensor_Focus]	No/Yes if [sources_Focus defined]
[DM]	Yes
[RTC]	No/Yes if [sensor_LO defined]
[Computation]	No

Detailed descriptions of each section are provided below.

Parameter Sections in Detail

[telescope]

[telescope] parameters

Parameter	Required?	Type	Description
TelescopeDiameter	Yes	float	Set the outer diameter of the telescope pupil in unit of meters.
Resolution	Yes	integer	Default: 256 Number of pixels across the pupil diameter.
ObscurationRatio	No/Yes if LO	float	Default: 0.0 Defines the central obstruction due to the secondary as a ratio of the TelescopeDiameter. Warning: `MavisLO.py`` does not have a default value for this parameter.
ZenithAngle	No/Yes if LO	float	Default: 0.0 Set the pointing direction of the telescope in degree with respect to the zenith. Used to compute airmass, to scale atmospheric layers and stars altitude.
PupilAngle	No	float	Default: 0.0 Unknown effect
PathPupil	No	string	Default: '' Path to the pupil model in .fits file (if provided, the pupil model is interpolated). if absent or '', not used.
PathStaticOn	No	string	Default: None Path to a map of static aberrations (nm) in .fits file. if absent or '', not used.
zCoefStaticOn	No	list of float	Default: None None, vector with zernike amplitudes (nm) of a static aberration. if absent not used.
PathStaticOff	No	string	Default: None No clue what this does. if absent or '', not used. From P3, not supported in TipTop.
PathStaticPos	No	string	Default: None No clue From P3, not supported in TipTop.
PathApodizer	No	string	Default: '' Path to a fits file that contain a binary map corresponding to a pupil apodizer (TBC). if absent or '', not used. From P3, not supported in TipTop.
PathStatModes	No	string	Default: '' Path to a .fits file that contain a cube of map of mode in amplitude which lead to a rms of 1 in nanometer of static aberation. if absent or '', not used. Unsure how this works. From P3, not supported in TipTop.
coefficientOfTheStaticMode	No used	string	Default: '' Place holder (TBC) need to find how does the pathStatModes fits file work. From P3, not supported in TipTop.
windPsdFile	No	string	Default: '' File name of a .fits file with a 2D array with a frequency vector and PSD of tip and tilt windshake.
extraErrorNm	No	float	Default: 0.0 nm RMS of the additional wavefront error to be added (an error that is not otherwise considered).
extraErrorExp	No	float	Default: -2. Exponent of the power of spatial frequencies used to generate the PSD associated with extraErrorNm.
extraErrorMin	No	float	Default: 0.0 Minimum spatial frequency for which PSD associated with extraErrorNm is > 0
extraErrorMax	No	float	Default: 0.0 Maximum spatial frequency for which PSD associated with extraErrorNm is > 0 Note: 0 means maximum frequency is the one present in the spatial frequency array of the PSDs.
extraErrorLoNm	No	float	Default: 0.0 nm RMS of the additional error to be added (an error that is not otherwise considered). It can be a list of two values, the on-axis error and the error at the edge of the technical field ([telescope] TechnicalFoV) Note: (1) only makes sense if [sensor_LO] is present (2) if not present extraErrorNm is used on LO directions.
extraErrorLoExp	No	float	Default: -2. Exponent of the power of spatial frequencies used to generate the PSD associated with extraErrorLoNm.
extraErrorLoMin	No	float	Default: 0.0 Mminimum spatial frequency for which PSD associated with extraErrorLoNm is > 0
extraErrorLoMax	No	float	Default: 0.0 Maximum spatial frequency for which PSD associated with extraErrorLoNm is > 0 Note: 0 means maximum frequency is the one present in the spatial frequency array of the PSDs.
jitter_FWHM	No	float	Default: None Additional kernel to be convolved with PSF, it could be a scalar (FWHM in mas) for a round kernel or a list of three values [FWHM_mas_max, FWHM_mas_min, angle_rad].
glFocusOnNGS	No	string	Default: False Global focus control with natural guide stars. Multi-conjugate systems only. Requires NumberLenslets >= 2 in sensor_LO or a specific global focus sensor ([sources_Focus] and [sensor_Focus] sections).
TechnicalFoV	No/Yes if LO	float	Default: ?? Set the size of the technical field of view (diameter) is Used in laser and multi-conjugate AO systems. Warning: This is not optional in MavisLO.py

[atmosphere]

[atmosphere] parameters

Parameter	Required?	Type	Description
Seeing	Yes	float	Set the seeing at Zenith in arcsec. If not set TipTop uses ro_Value.
Wavelenght	No/Yes if LO	float	Default: 500e-9 Wavelength of definition of the atmosphere statistics. Warning: not optional in MavisLO.py
Lo	No/Yes if LO	float	Default: 25.0 Outer Scale of the atmosphere in meters. Warning: not optional in MavisLO.py
Cn2Weights	No/Yes if LO	list of float	Default: [1.0] Relative contribution of each layer. The sum of all the list element must be 1. Must have the same length as Cn2Heights, WindSpeed and WindDirection. Warning: required if Cn2Heights, WindSpeed or WindDirection are defined. Warning: extremely confusing error message if absent when it must be defined.
Cn2Heights	No/Yes if LO	list of float	Default: [0.0] Altitude of layers in meters. Must have the same length as Cn2Weights, WindSpeed and WindDirection. Warning: required if Cn2Weights, WindSpeed or WindDirection are defined. Warning: extremely confusing error message if absent when it must be defined.
WindSpeed	No/Yes if LO	list of float	Default: [10.0] Wind speed values for each layer in m/s. Must have the same length as Cn2Weights, Cn2Heights and WindDirection. Warning: required if Cn2Weights, Cn2Heights or WindDirection are defined. Warning: extremely confusing error message if absent when it must be defined.
WindDirection	No	list of float	Default: a list of 0 of the length of WindSpeed Wind direction for each layer in degrees. 0 degree is along the x axis then anticlockwise. Must have the same length as Cn2Weights, Cn2Heights and WindSpeed.
ro_Value	No	float	Set the atmospere Fried parameter. If not set TipTop uses Seeing.
testWindspeed	No	float	Used only for tests

[sources_science]

[sources_science] parameters

Parameter	Required?	Type	Description
Wavelength	Yes	list of float or float	List of wavelengths in meters. When more than one elements is present the output PSF saved in the fits file is a 4D array with dimension (Nw, Ns, Npix, Npix), where Nw is the number of wavelengths required ([sources_science] Wavelength), Ns is the number of directions required ([sources_science] Zenith and Azimuth) and Npix is the size required for the PSFs ([sensor_science] FieldOfView). If a single elements is present the fits file is a 3D array with dimension (Ns, Npix, Npix). Instead the profiles will be a 3D array (fourth fits file extension) with dimensions (2*Nw, Ns, Npix/2). The first Nw elements contain the radius and the second Nw elements the profile values (the first radius and profile pair is radius=data[0,0,:] profile=data[Nw,0,:], the second is radius=data[1,0,:] profile=data[Nw+1,0,:], …) json file: two lists, radius and psf with dimensions (Nw, Ns, Npix/2). In this case more memory is required and small differences with respect to monochromatic PSF will be present because: (1) errors Differential refractive anisoplanatism and Chromatism from P3 are computed for a single wavelength (the shortest one) (2) effective field-of-view of the PSF is typically larger to guarantee that the PSF at the shortest wavelength has the required field-of-view (3) The PSF is typically computed with a higher sampling to guarantee that the longest wavelength has the required sampling and then the PSFs at the shorter wavelengths are rebinned.
Zenith	Yes	list of float	Zenithal coordinate in arcsec (distance from axis) of science sources. Must be the same length as Azimut.
Azimuth	Yes	list of float	Azimuthal coordinate in degree (angle from the ref. direction: polar axis is x-axis) of science sources. Must be the same length as Zenith.

[sources_HO]

[sources_HO] parameters

Parameter	Required?	Type	Description
Wavelength	Yes	float	Sensing wavelength for Hight Order modes in meters_ Warning: gives a confusing error message if absent.
Zenith	No	list of float	Default: [0.0] Zenithal coordinate of each guide stars in arcsec (distance from axis). Must be the same length as Azimuth, even if Azimuth is defined, this is optional.
Azimuth	No	list of float	Default: [0.0] Azimuthal coordinate in degree (angle from the ref. direction: polar axis is x-axis) of each guide stars. Must be the same length as Zenith, even if Zenith is defined, this is optional.
Height	No	float	Default: 0.0 Altitude of the guide stars (0 if infinite). Consider that all guide star are at the same height.

[sources_LO]

✏️Note: This section is completely optional ([sensor_LO] section is required to have the LO part simulated).

[sources_LO] parameters

Parameter	Required?	Type	Description
Wavelength	Yes	float	Sensing wavelength for Low Order modes in meters.
Zenith	Yes	list of float	Zenithal coordinate of each guide stars in arcsec (distance from axis). Must be the same length as Azimuth.
Azimuth	Yes	list of float	Azimuthal coordinate in degree (angle from the reference direction: polar axis is x-axis) of each guide stars. Must be the same length as Zenith.

[sources_Focus]

✏️Note: This section is completely optional. The [sources_Focus] section is required to have the global focus part simulated considering specific focus sensors and not the LO sensors. This happens when the key glFocusOnNGS in the [telescope] section is True and multiple DMs are present.
Note that the coordinates (Zenith and Azimuth) of the NGSs are the same of the [sources_LO] section.

[sources_Focus] parameters

Parameter	Required?	Type	Description
Wavelength	Yes	float	Sensing wavelength for global focus modes in meters.

[sensor_science]

[sensor_science] parameters

Parameter	Required?	Type	Description
PixelScale	Yes	float	Pixel/spaxel scale in milliarcsec. Warning: confusing error message if missing.
FieldOfView	Yes	float	Field of view of the camera in pixel/spaxel. Warning: confusing error message if missing.

✏️Note: following parameters were added to uniformise all the sensor (HO and LO), but they are not used.
Binning, NumberPhotons, SpotFWHM, SpectralBandwidth, Transmittance, Dispersion, SigmaRON, Dark, SkyBackground, Gain, ExcessNoiseFactor, Wavelength, FieldOfView

[sensor_HO]

The High Order WaveFront Sensor can be a Pyramid WFS or a Shack-Hartmann. Regardless of the WFS, the following parameters can de defined.

[sensor_HO] parameters

Parameter	Required?	Type	Description
NumberLenslets	No	list of int	Default: [20] Number of WFS lenslets. Used the same way in Shack-Hartmann wavefront sensor and Pyramid. Also used for noise computation if NoiseVariance is not set.
SizeLenslets	No	list of float	Default: [Telescope] TelescopeDiameter/[sensor_HO] NumberLenslet Lenslet Size of WFS lenslets in meters. Why a list of float? This overrides the ratio between telescope size and Number of lenslet used to compute the matrix size.
PixelScale	Yes	integer	High Order WFS pixel scale in [mas]. Not used when a Pyramid wavefront sensor has been selected. Warning: gives a confusing error message if missing.
FieldOfView	Yes	integer	Number of pixels per subaperture. Not used when a Pyramid wavefront sensor has been selected (4 pixels are used in this case). Warning: gives a confusing error message if missing.
WfsType	No	string	Default: Shack-Hartmann Type of wavefront sensor used for the High Order sensing. Other available option: Pyramid.
NumberPhotons	No	list of int	Default: [Inf] Flux return in [nph/frame/subaperture]. It can be computed as: (0-magn-flux [ph/s/m2]) * (size of sub-aperture [m])^2 * (1/SensorFrameRate_HO) * (total throughput) * (10^(-0.4*magn_source_HO))
SpotFWHM	No	list of list of float	Default: [[0.0,0.0,0.0]] High Order spot parameters: two axes scale values in milliarcsec (only max value is used) and angle (angle is not used). Why list?
SpectralBandwidth	No	float	Default: 0.0 Not used, spectral bandwidth of the filter (imaging mode)? Why specific to the imaging mode? What is the effect?
Transmittance	No	list of float	Default: [1.0] Used for PSF computation and flux scaling but not with noise computation. Transmittance at the considered wavelengths for polychromatic mode. How do you set polychromatic mode? Each element can not have a value superior to 1?
Dispersion	No	list of list of float	Default: [[0.0,0.0]] Dispersion x/y at the considered wavelength in pixel. Must be the same size than Transmittance. Chromatic dispertion for PSF computation only. In HarmoniSCAO_1 first the default and the thing given are not even the same shape but on top the default breaks the must be the same size as the transmitance… Also sorry for my ignorance: dispersion of what? Isn’t this maybe redundant with SpotFWHM ?
Gain	No	float	Default: 1.0 Pixel gain. Do you mean camera gain or loop goin?
ExcessNoiseFactor	No	float	Default: 2.0 Excess noise factor. TODO: default should be 1
NoiseVariance	No	unknown	Default: None? Noise Variance in rad2. If not empty, this value overwrites the analytical noise variance calculation.
SigmaRON	No	float	Default: 0.0 Read-out noise std in [e-], used only if the NoiseVariance is not set.
addMcaoWFsensConeError	No	string	Default: False Additional error to consider the reduced sensing volume due to the cone effect. Multi-conjugate systems only.

Wavefront sensor requirements

In the two following section we list the parameters that are specific to each wavefront sensor. If you define a parameter for one WFS while another WFS is defined The parameter will be ignired. For example, if you define the parameter SigmaRON, while WfsType is Pyramid, SigmaRON is ignored.

Shack-Hartmann requirements

Parameter	Required?	Type	Description
Algorithm	not used	string	Default: wcog Other options: cog (simple center-of-gravity), tcog (center-of-gravity with threshold), qc (quad-cell)
WindowRadiusWCoG	not used	int	Default: 2.0 FWHM in pixel of the gaussian weighting function.

Pyramid requirements

Parameter	Required?	Type	Description
Modulation	Yes	float	Default: None If the chosen wavefront sensor is the Pyramid, spot modulation radius in lambda/D units. This is ignored if the WFS is Shack-Hartmann. Warning: gives a confusing message if missing when required.
Binning	No	integer	Default: 1 Binning factor of the detector, only used in the pyramid case, optional for pyramid.

Can be set but not used

Parameter	Required?	Type	Description
Dark	not used	float	Default: 0.0 Dark current in [e-/s/pix].
SkyBackground	not used	float	Default: 0.0 Sky background [e-/s/pix].
ThresholdWCoG	not used	float?	Default: 0.0 Threshold Number of pixels for windowing the low order WFS pixels.
NewValueThrPix	not used	float	Default: 0.0 New value for pixels lower than ThresholdWCoG. Is there a reason to want to force these values to something else?

[sensor_LO]

✏️Note: This section is optional, if this section is not present only the HO part will be used (for ex. to simulate a SCAO NGS).

[sensor_LO] parameters

Parameter	Required?	Type	Description
PixelScale	Yes	float	LO WFS pixel scale in [mas].
FieldOfView	Yes	integer	Not used. Number of pixels per subaperture.
NumberPhotons	Yes	list of int	Detected flux in [nph/frame/subaperture]. Must be the same length as NumberLenslet. It can be computed as: (0-magn-flux [ph/s/m2]) * (size of subaperture [m])**2 * (1/SensorFrameRate_LO) * (total throughput) * (10**(-0.4*magn_source_LO)).
NumberLenslets	Yes	list of int	Default: [1] Number of WFS lenslets. Must be the same length as NumberPhotons.
SigmaRON	Yes	float	Default: 0.0 Read out noise in [e-].
Dark	Yes	float	Default: 0.0 Dark current [e-/s/pix].
SkyBackground	Yes	float	Default: 0.0 Sky background [e-/s/pix].
ExcessNoiseFactor	Yes	float	Default: 2.0 Excess noise factor.
WindowRadiusWCoG	Yes	integer	Default: 1 Radius in pixel of the HWHM of the weights map of the weighted CoG the low order WFS pixels. Warning: if set to ‘optimize’, gain is automatically optimized by TipTop (closest int to half of PSF FWHM), otherwise the float value set is used.
ThresholdWCoG	Yes	float	Default: 0.0 Threshold Number of pixels for windowing the low order WFS pixels.
NewValueThrPix	Yes	float	Default: 0.0 New value for pixels lower than threshold.
filtZernikeCov	No	string	Default: False Filter for the zernike covariance. The zernike cov. is used to quantify for the TT tomographic (anisoplanatic) error. This filter accounts for the HO correction of an MCAO system. Multi-conjugate systems only. Warning: Do not use in systems with a single DM.

Can be set but not used

Parameter	Required?	Type	Description
Binning	not used	integer	Default: 1 Binning factor of the detector.
SpotFWHM	not used	list of list of int	Default: [[0.0,0.0,0.0]] Low Order spot scale in [mas].
Gain	not used	float	Default: 1 Camera gain.
Algorithm	not used	string	Default: wcog CoG computation algorithm.

[sensor_Focus]

✏️Note: This section is completely optional. The [sensor_Focus] section is required to have the global focus part simulated considering specific focus sensors and not the LO sensors. This happens when the key glFocusOnNGS in the [telescope] section is True and multiple DMs are present.

[sensor_Focus] parameters

Parameter	Required?	Type	Description
PixelScale	Yes	float	Focus WFS pixel scale in [mas].
FieldOfView	Yes	integer	Not used. Number of pixels per subaperture.
NumberPhotons	Yes	list of int	Detected flux in [nph/frame/subaperture]. Must be the same length as NumberLenslet. It can be computed as: (0-magn-flux [ph/s/m2]) * (size of subaperture [m])**2 * (1/SensorFrameRate_Focus) * (total throughput) * (10**(-0.4*magn_source_Focus)).
NumberLenslets	Yes	list of int	Default: [1] Number of WFS lenslets. Must be the same length as NumberPhotons.
SigmaRON	Yes	float	Default: 0.0 Read out noise in [e-].
Dark	Yes	float	Default: 0.0 Dark current [e-/s/pix].
SkyBackground	Yes	float	Default: 0.0 Sky background [e-/s/pix].
ExcessNoiseFactor	Yes	float	Default: 2.0 Excess noise factor.
WindowRadiusWCoG	Yes	integer	Default: 1 Radius in pixel of the HWHM of the weights map of the weighted CoG the global focus WFS pixels. Warning: if set to ‘optimize’, gain is automatically optimized by TipTop (closest int to half of PSF FWHM), otherwise the float value set is used.
ThresholdWCoG	Yes	float	Default: 0.0 Threshold Number of pixels for windowing the global focus WFS pixels.
NewValueThrPix	Yes	float	Default: 0.0 New value for pixels lower than threshold.

[DM]

[DM] parameters

Parameter	Required?	Type	Description
DmPitchs	Yes	list of float	DM actuators pitch in meters, on the meta pupil at the conjugasion altitude, used for fitting error computation. Warning: if it smaller than [sensor_HO] SizeLenslets (=[Telescope] TelescopeDiameter/[sensor_HO] NumberLenslet ) aliasing error will be significant. Must be the same length as NumberActuators.
NumberActuators	No	list of int	Default: computed from diameter, technical FoV, DM altitude and DM pitch. Number of actuator on the pupil diameter. Must be the same length as DmPitchs. Warning: not used in TipTop!
InfModel	No	string	Default: gaussian DM influence function model. Not used in TipTop but used in the psf reconstruction. What are the other possible one?
InfCoupling	No	list of float	Default: [0.2] DM influence function model mechanical coupling. Not used in TipTop but used in the psf reconstruction. Unclear what this does. Must be the same length as NumberActuators?
DmHeights	No/Yes if LO or multi DMs	list of float	Default: [0.0] DM altitude in meters. Must be the same length as NumberActuators and DmPitchs.
OptimizationZenith	No	list of float	Default: [0.0] Zenith position in arcsec (distance from axis) of the direction in which the AO correction is optimized. Must be the same length as OptimisationAzimuth and OptimizationWeight. These are for wide field AO system, should be a requirement for MCAO and GLAO.
OptimizationAzimuth	No	list of float	Default: [0.0] Azimuth in degrees (angle from the ref. direction: polar axis is x-axis) of the direction in which the AO correction is optimized. Must be the same length as OptimizationZenith and OptimizationWeight. These are for wide field AO system, should be a requirement for MCAO and GLAO.
OptimizationWeight	No	list of float	Default: [1.0] Weights of the optimisation directions. Must be the same length as OptimizationZenith and OptimizationAzimuth. These are for wide field AO system, should be a requirement for MCAO and GLAO.
OptimizationConditioning	No	float	Default: 1.0e2 Matrix Conditioning threshold in the truncated SVD inversion.
NumberReconstructedLayers	No	integer	Default: 10 Only used for wide field AO system, (meaning more than one guide star is defined). Number of reconstructed layers for tomographic systems. Shouldn’t this be defaulted to 1 for SCAO sakes?
AoArea	No	string	Default: circle Shape of the AO-corrected area. Any other options are not defined and will give a squarre correction area.

[RTC]

✏️Note: This section is optional, if this section is not present the defaul values are used.

[RTC] parameters

Parameter	Required?	Type	Description
LoopGain_HO	No	float	Default: 0.5 High Order Loop gain. Warning: if system to be simulated is a multi-conjugate system this parameter is not used.
SensorFrameRate_HO	No	float	Default: 500.0 High Order loop frequency in [Hz].
LoopDelaySteps_HO	No	integer	Default: 2 High Order loop delay in [frame].
LoopGain_LO	No/Yes if LO	float or string	Default: None Low Order loop gain, Warning: if set to ‘optimize’, gain is automatically optimized by TipTop, otherwise the float value set is used.
SensorFrameRate_LO	No/Yes if LO	float	Default: None Loop frequency in [Hz]. If [sensor_LO] section is present it must be set.
LoopDelaySteps_LO	No/Yes if LO	integer	Default: None Low Order loop delays in [frames]. If [sensor_LO] section is present it must be set.
LoopGain_Focus	No/Yes if Focus	float or string	Default: None Global focus loop gain. Warning: if set to ‘optimize’, gain is automatically optimized by TipTop, otherwise the float value set is used.
SensorFrameRate_Focus	No/Yes if Focus	float	Default: None Global focus loop frequency in [Hz]. If [sensor_Focus] section is present it must be set.
LoopDelaySteps_Focus	No/Yes if Focus	integer	Default: None Global focus loop delays in [frames]. If [sensor_Focus] section is present it must be set.

[COMPUTATION]

✏️Note: This section is optional, if this section is not present the defaul values are used.

[COMPUTATION] parameters

Parameter	Required?	Type	Description
platform	No	string	Default: GPU Set to it to CPU to forcy the library to use numpy instead of cupy.
integralDiscretization1	No	float	Default: 1000.0 Discretization used in the integrals (astro-tiptop/SEEING library).
integralDiscretization2	No	float	Default: 4000.0 Discretization used in the integrals (astro-tiptop/SEEING library).