Skip to main content

TipTop Quickstart Tutorial

✏️ Note: We recommend first testing your TipTop installation using the provided example files: TIPTOP-EXAMPLE.py or TIPTOP-EXAMPLE.ipynb (for Jupyter users).

To begin, open a terminal or command prompt and activate the virtual environment you previously created (see the TipTop Installation Tutorial):

conda activate tiptop

or, on Windows PowerShell:

.\tiptop\Scripts\activate

Running a Simulation with TipTop​

To run a simulation with TipTop, you will need:

  • ➡️ A launch script (see: How to set up a launch script for TipTop?) which:

    • Loads the simulation parameters from a .ini file (e.g., minimalPar.ini)
    • Initializes the necessary modules
    • Starts the simulation

    📄 An example script, TIPTOP-EXAMPLE.py, is available in the examples/ folder of our GitHub repository. You can use it as a template to create your own simulations:

    TIPTOP-EXAMPLE.py
    from tiptop.tiptop import *
    plt.ion()

    overallSimulation("./", "minimalPar", './', 'test')

    ✏️ Note:

    • The first and second arguments of overallSimulation are the path to the folder containing the input .ini file and the name of that file (without the extension).
    • The third and fourth arguments specify where to save the output results (in .fits format) and and the name of the resulting .fits file.

    A detailed documentation on the overallSimulation function can be found here.

    📄 A more complete run script (TIPTOP_RUN.py), which extracts key performance metrics (e.g., Strehl ratio, FWHM) from the output file and generates PSF visualizations, is available here. You can use it as a template and adapt the input/output paths, filenames, and plotting options for your own simulations.

  • ➡️ a parameter file in .ini format, for example:

    minimalPar.ini
    [telescope]
    TelescopeDiameter=8.
    Resolution = 128

    [atmosphere]
    Seeing = 0.6

    [sources_science]
    Wavelength = [1.6e-6]
    Zenith = [0.]
    Azimuth = [0.]

    [sources_HO]
    Wavelength = 750e-9

    [sensor_science]
    PixelScale = 40
    FieldOfView = 256

    [sensor_HO]
    PixelScale = 832
    FieldOfView = 6
    NumberPhotons = [200.]
    SigmaRON = 0.

    [DM]
    NumberActuators = [20]
    DmPitchs = [0.25]

    A user-friendly interface is available to help you generate custom .ini files by selecting an instrument from the available options (see: Available AO Instruments) and specifying parameter values. Access it by clicking the button below:

    ✏️ Note: For a detailed explanation of the .ini parameter file structure and syntax, please refer to the Parameter Files page. Guidance on configuring TipTop for your chosen adaptive optics system is available in How to set up TipTop according to the AO mode?.

Simulation Output​

The output of a TipTop simulation consists of Point Spread Functions (PSFs) computed using the parameters specified in your .ini file.

If the doPlot parameter of the overallSimulation function is set to True, the following PSFs will be displayed after the simulation runs:

  • The AO-corrected PSF(s)
  • The seeing-limited PSF
  • The diffraction limited PSF

These PSFs are also saved in a .fits file for further analysis and post-processing.

FITS File Structure & Contents

The FITS file contains multiple HDUs (Header/Data Units), each storing different types of data related to the PSFs generated during the simulation. The content is organized as follows:

  • HDU 0 – PRIMARY
    Contains metadata about the simulation, the instrument, and observational parameters. It does not contain image data but provides essential contextual information.
  • HDU 1 – AO-Corrected PSF
    Stores the cube of AO-corrected PSFs as a multi-dimensional image array with dimensions (FieldOfView, FieldOfView, Nsrc, Nwvl), where FieldOfView corresponds to the camera’s field of view in pixels as defined in the [sensor_science] section of your .ini file, Nsrc is the number of science sources, and Nwvl is the number of wavelengths specified in the Wavelength parameter of the [sources_science] section.
  • HDU 2 – Seeing-Limited PSF
    Contains the seeing-limited (open-loop) PSF in a 2D image array of size (FieldOfView, FieldOfView).
  • HDU 3 – Diffraction-Limited PSF
    Contains the diffraction-limited PSF, also stored as a 2D image array of size (FieldOfView, FieldOfView).
  • HDU 4 – PSDs (if savePSDs=True)
    Contains the Power Spectral Density (PSD), stored as a 3D array.
  • HDU 4 or 5 – Final PSFs Radial Profiles
    Contains the 1D radial profiles of the PSFs, stored as an 3D array.
    ✏️Note: The HDU number depends on whether the PSDs are saved.

Here is an example FITS structure produced with the minimalPar.ini configuration:

No.    Name      Ver    Type      Cards   Dimensions   Format
  0  PRIMARY       1 PrimaryHDU      84   ()      
  1                1 ImageHDU        21   (256, 256, 1)   float64 #AO-corrected PSFs
  2                1 ImageHDU        10   (256, 256)      float64 #Open-loop PSF   
  3                1 ImageHDU        10   (256, 256)      float64 #Diffraction limited PSF
  4                1 ImageHDU        11   (256, 256, 1)   float64 #High Order PSD (if saved)  
  5                1 ImageHDU        11   (128, 1, 2)     float64 #PSFs profiles

✏️Note: By default, the FITS file header includes the Strehl Ratio (SR) and Full Width at Half Maximum (FWHM) values for each PSF (addSrAndFwhm is set to True by default). To retrieve and display the SR, FWHM and Encircled energy metrics, you need to set the returnMetrics option to True (see the documentation on the overallSimulation function).
⚠️ If returnMetrics is set to True, the FITS file is not saved.