# CAOS_Software_Package_7.0 HELP

## A software package of the CAOS Problem Solving Environment.

## List of Routines

AIC | ATA | ATM
AVE | BQC | BSP
CFB | COM | COR
DMC | DMI | GPR
IBC | IMA | IMG
IWS | LAS | MDS
NLS | PYR | REC
SCD | SLO | SRC
SSC | STF | SWS
TCE | TFL | TTM
WFA

# Routine Descriptions

## AIC

[Next Routine] [List of Routines]

     NAME:
       aic

     ROUTINE'S PURPOSE:
        aic manages the simulation for the Achrom. Interf. Coronagraph (AIC)
        module, that is:
           1-call the module's initialisation routine aic_init at the first
             iteration of the simulation project,
           2-call the module's program routine aic_prog otherwise, managing
             at the same time the possible time integration/delay.

     MODULE'S PURPOSE:
        AIC simulates the Achromatic Interfero-Coronagraph. This is a first attempt.

     CATEGORY:
        main module's routine

     CALLING SEQUENCE:
        error = aic(inp_wfp_t, $ ; input structure
                    out_img_t, $ ; output structure
                    par,       $ ; parameter structure
                    INIT=init  ) ; initialisation data structure

     OUTPUT:
        error: long scalar (error code, see !caos_error var in caos_init.pro).

     INPUTS:
        inp_wfp_t: structure of type wfp_t.
        par      : parameters structure.

     INCLUDED OUTPUTS:
        out_img_t: structure of type img_t.

     KEYWORD PARAMETERS:
        INIT: initialisation data structure.
        TIME: time-evolution structure.

     COMMON BLOCKS:
        common caos_block, tot_iter, this_iter

        tot_iter   : total number of iteration during the simulation run.
        this_iter  : current iteration number.

     SIDE EFFECTS:
        none.

     RESTRICTIONS:
        Among them:
        -No noises (photon noise, RON, dark current noise) and no background
        addition implemented for now.
        -No anisoplanatic difference is simulated between the main star and the
        companion (exactly the same wavefront in entrance of the coronagraph).

     CALLED NON-IDL FUNCTIONS:
        none.

     ROUTINE MODIFICATION HISTORY:
        routine written: september 2003,
                         Marcel Carbillet (OAA) [marcel@arcetri.astro.it],
                         Christophe Verinaud (ESO) [cverinau@eso.org].
        modifications  : april 2016,
                         Marcel Carbillet (Lagrange) [marcel.carbillet@unice.fr]:
                        -adapted to Soft. Pack. CAOS 7.0.

     MODULE MODIFICATION HISTORY:
        module written : Marcel Carbillet (OAA) [marcel@arcetri.astro.it],
                         Christophe Verinaud (ESO) [cverinau@eso.org].
        modifications  : for version 5.0,
                         Marcel Carbillet (LUAN) [marcel.carbillet@unice.fr],
                        -stupid one-value-vector IDL6+ bug corrected (in aic_prog: n_phot->n_phot[0]).
                       : for version 7.0,
                         Marcel Carbillet (Lagrange) [marcel.carbillet@unice.fr]:
                        -adapted.

(See aic/aic.pro)

## ATA

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           ata

     ROUTINE'S PURPOSE:
           ATA manages the simulation for the ATmosphereAdding (ATA) module,
           that is:
           1-call the module's initialisation routine ata_init at the first
             iteration of the simulation project
           2-call the module's program routine ata_prog otherwise.

     MODULE'S PURPOSE:
           ATA receives two "atmospheres" as inputs and returns their sum/difference
           according to weights supplied by user. This module has been developed to
           check performance of the software with MCAO.

     CATEGORY:
           main module's routine

     CALLING SEQUENCE:
           err = ata(inp_atm_t1, inp_atm_t2, out_atm_t, par)

     OUTPUT:
           error     :long scalar (error code, see !caos_error var in caos_init.pro).

     INPUTS:
           inp_atm_t1:incident atmosphere. (Bottom input in Application builder)

           inp_stm_t2:incident atmosphere. (Top input in Application builder)

           par       :parameters structure from ata_gui. In addition to the usual
                      tags associated with the overall management of the program,
                      it contains the following tags:

                      par.wb: assigned weight (+1 or -1) to first input (in
                              AppBuilder, bottom box!!)
                      par.wt: assigned weight (+1 or -1) to second input (in
                              AppBuilder, top box!!)

     INCLUDED OUTPUTS:
           out_atm_t :output atmosphere with intensity arbitrarily normalized to 1.

     KEYWORD PARAMETERS:
           None.

     COMMON BLOCKS:
           common caos_block, tot_iter, this_iter

           tot_iter   : total number of iteration during the simulation run.
           this_iter  : current iteration number.

     SIDE EFFECTS:
           None.

     RESTRICTIONS:
           This module does not consider the effect on the intensity as it is not
           intended to simulate interferometry. It's been developed only to allow
           easy and fast visualization of MCAO when closing the loop.

     CALLED NON-IDL FUNCTIONS:
           none.

     ROUTINE MODIFICATION HISTORY:
           program written: March 2001,
                            B. Femenia   (OAA) [bfemenia@arcetri.astro.it].
           modifications  : january 2003,
                            Marcel Carbillet (OAA) [marcel@arcetri.astro.it]:
                           -use of variable "calibration" eliminited for version 4.0
                            of the whole Software System CAOS.
                          : april 2016,
                            Marcel Carbillet (Lagrange) [marcel.carbillet@unice.fr]:
                           -adapted to Soft. Pack. CAOS 7.0.

     MODULE MODIFICATION HISTORY:
           module written : B. Femenia   (OAA) [bfemenia@arcetri.astro.it].
           modifications  : for version 4.0,
                            Marcel Carbillet (OAA) [marcel@arcetri.astro.it]:
                           -no more use of the common variable "calibration" and
                            the tag "calib" (structure "info") for version 4.0 of
                            the whole Software System CAOS.
                          : for version 7.0,
                            Marcel Carbillet (Lagrange) [marcel.carbillet@unice.fr]:
                           -adapted.

(See ata/ata.pro)

## ATM

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
        atm

     ROUTINE'S PURPOSE:
        atm manages the simulation for the ATMosphere building (ATM) module,
        that is:
           1-call the module's initialisation routine atm_init at the first
             iteration of the simulation project
           2-call the module's program routine atm_prog otherwise.

     MODULE'S PURPOSE:
        ATM generates the turbulent atmosphere. To do so a modelisation of
        the Cn2 profile is considered. In fact, up to six discrete layers,
        each affected by a different Cn2 value are simulated. They are also
        affected by a velocity vector if temporal evolution is required.
        If temporal evolution is considered, the time-base defined
        inside ATM will rule all the subsequent simulation branches.

        Each turbulent layer is a phase screen that can be either generated
        by the module or read from a file where already computed phase screens
        were saved. In that case, the utility PSG (that can be found in
        .../pack_lib/) had been previously used for this purpose,
        and the phase screens can be either squares or stripes. An ad-hoc help
        of the utility PSG can be found in the header of the program "psg.pro".
        Note that in this case the physical length of the wavefronts is still a
        free parameter that can be chosen (as well as the Fried parameter r0).

        A number of non-editable fields are present in the ATM GUI which purpose
        is to help the user in defining the right parameters for her/his
        simulation, or simply to know what are the parameters that define the
        wavefronts used in case the use-already-computed-phase-screens feature
        is selected. These non-editable fields have a title between parenthesis
        - i.e. like "(title)" and not "title".

        phase screen generation:
        ------------------------
        The two methods used for it are explained here after:

          +-----------------------------------------------------------------+
          | (1) Fast Fourier transform (FFT) [+ sub-harmonics adding (SHA)] |
          +-----------------------------------------------------------------+

          In this case the phase screen generation is computed assuming
          either a von Karman modulus or a Kolmogorov one via FFT, with
          compensation for the low-frequencies (if required) by means of SHA
          [Lane et al., 1992].

          Note that the von Karman model differs from the Kolmogorov one because
          an wavefront outer scale of turbulence L0 van be selected.

          Note also that the low-frequencies compensation to be performed in this
          routine can be tested before via the routine 'sha_test' (this can be
          automatically done within the ATM GUI by simply pushing the button
          "PUSH HERE to test subharmonics accuracy").

          The generated FFT phase screens are initially complex arrays, and we
          use both the real and imaginary parts of each of them as two
          independent phase screens [Negrete-Regagnon, 1995]. We then have to
          normalize each of the parts by a factor sqrt(2), for energy reasons.

          If temporal evolution is required, each phase screen is shifted from
          an iteration to the next one by the amount of pixels calculated both
          from the velocity vectors associated to the turbulent layer and from
          the selected time-base. If the number resulting shifting pixels is
          not an integer, the shift is done by interpolating the phase screens.
          (A simulation is then faster - and does not suffer from any possible
          interpolation innacurracy - if both the velocity vectors and the
          time-base are judiciously chosen.)

          +-----------------------------------------------------------------+
          | (2) Zernike polynomials (ZP) method: [+ recursive formula (RF)] |
          +-----------------------------------------------------------------+

          In this case the phase screen generation is performed assuming only a
          Kolmogorov modulus, and the dimensions of the phase screens are the
          pupil's ones.

          These wave screens are changed into phase screens (by multiplying them
          by a factor 2*!pi). Then they have to be scaled for the given value of
          the ratio between the telescope diameter 'D'  and the Fried parameter
          'r0' before to be used, by multiplying them by the factor (D/r0)^(5/6).

          References:
          Lane R. G., Glindeman A. and Dainty J. C., 'Simulation of a Kolmogorov
             Phase Screen', Waves in Random Media 2, 209--224, 1992.
          Negrete-Regagnon P., 'Bispectral Imaging in Astronomy', PhD thesis,
             Imperial College, UK, 1995.

          Modification history of the phase screen generation part:
          Written by Marcel Carbillet, OAA, 1998, but:
          * FFT routine:      - originally written by Enrico Marchetti, ESO, 1997.
                              - modified by Marcel Carbillet, OAA, 1997.
          * SHA routine:      written by Marcel Carbillet, Simone Esposito
                              and Armando Riccardi, OAA, 1998.
          * Zernike routines: written by Armando Riccardi, OAA, 1997.

     CATEGORY:
        main module's routine

     CALLING SEQUENCE:
        error = atm(out_atm_t, par, INIT=init)

     OUTPUT:
        error: long scalar (error code). see !caos_error var in caos_init.pro.

     INPUTS:
        none.

     INCLUDED OUTPUTS:
        out_atm_t: the output structure of ATM, of type "atm_t", containing:
        -screen : 3-variables array of the ensemble of layers' wavefronts of
                  the turbulent atmosphere [m]
        -scale  : spatial scale [m/px]
        -delta_t: base-time [s]
        -alt    : vector of altitudes of the layers [m]
        -dir    : vector of direction of the wind [rd].

     KEYWORD PARAMETERS:
        INIT: initialisation data structure

     COMMON BLOCKS:
        common caos_block, tot_iter, this_iter

        tot_iter   : total number of iteration during the simulation run.
        this_iter  : current iteration number.

     SIDE EFFECTS:
        none.

     RESTRICTIONS:
        -For now, temporal evolution is possible ONLY with FFT phase
        screens, NOT Zernike ones.
        -No more than 6 turbulent layers are allowed (but this is only a limitation
         of the GUI -- easy to override!).
        -If temporal evolution is selected, and if phase stripes (i.e. not
        square phase screens) are considered, the wind directions MUST BE
        along the x- or the y-axis.
        -Pay attention that the possible following GPR module will, a priori, place
        the collecting telescope in the middle of the phase screens. That means that
        if, for example, you have an 8m telescope in the middle of a 14m-large phase
        screen, you will only (14-8)/2=3m available on the left side, and the same at
        the right side of your telescope pupil, for time evolution of your phase
        screens wrt wind velocities, base time, etc., before having a complete cycle
        on your phase screens. This is not a serious problem for pure FFT screens,
        but the fact that the same portion of phase screen will pass again over the
        telescope pupil. If subharmonics are considered this can become, on the other
        hand, a big problem if this limit is overcome, since the last values of the
        border of the atmospheric layers will be repeated ad libitum.

     CALLED NON-IDL FUNCTIONS
        from .../modules/atm/atm_lib:
           atm_psg    : sub-routine for phase screen generation.
           atm_psg_fft: FFT phase screen generation sub-routine.
           atm_psg_sha: sub-harmonics adding sub-routine.
           atm_psg_zer: Zernike phase screen generation sub-routine.
        from .../lib:
           shiffft    : FFT-based phase screen shift sub-routine.

     ROUTINE MODIFICATION HISTORY:
        program written: july 1998,
                         Marcel  Carbillet (OAA) [marcel@arcetri.astro.it]  ,
                         Simone  Esposito  (OAA) [esposito@arcetri.astro.it],
                         Armando Riccardi  (OAA) [riccardi@arcetri.astro.it].
        modifications  : february 1999,
                         Marcel Carbillet (OAA) [marcel@arcetri.astro.it]:
                        -standardization for version 1.0,
                        -phase screens [rd] => wavefronts [m],
                        -a few other modifications for version 1.0.
                       : march 1999,
                         Marcel Carbillet (OAA) [marcel@arcetri.astro.it]:
                        -phase screens/stripes can be read from a file
                         instead of being generated (the "use already
                         computed phase screens" feature).
                        -some controls of parameters consistency and
                         more fields of help-for-decision added.
                       : november 1999,
                         Marcel Carbillet (OAA) [marcel@arcetri.astro.it]:
                        -adapted to version 2.0 (CAOS).
                       : january/february 2003,
                         Marcel Carbillet (OAA) [marcel@arcetri.astro.it]:
                        -use of variable "calibration" eliminited for version 4.0
                         of the whole system CAOS.
                        -help completed (FFT+SHA vs. limited dimension stuff).
                       : march 2016,
                         Ulysse Perruchon-Monge & Adama Sy (Dépt. Physique UNS),
                         Marcel Carbillet (Lagrange) [marcel.carbillet@unice.fr]:
                        -turbulence can now be switched off (by using par.turnatmos).

(See atm/atm.pro)

## AVE

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           ave

     ROUTINE'S PURPOSE:
           AVE manages the simulation for the signals AVEraging (AVE) module,
           that is:
           1-call the module's initialisation routine ave_init at the first
             iteration of the simulation project
           2-call the module's program routine ave_prog otherwise.

     MODULE'S PURPOSE:
           AVE receives two vectors of measures (signals) as inputs and returns their
           averaging.

     CATEGORY:
           main module's routine

     CALLING SEQUENCE:
           err = ave(inp_mes_t, out_mes_t, par)

     OUTPUT:
           error:long scalar (error code, see !caos_error var in caos_init.pro).

     INPUTS:
           inp_mes_t:incoming measures (signals) vector. (Bottom input in Application builder)

           par      :parameters structure from ave_gui. In addition to the usual
                     tags associated with the overall management of the program,
                     it contains the following tags:

                     par.nstars: nb of stars from which signals are averaged.

     INCLUDED OUTPUTS:
           out_mes_t :output vector of measures (signals).

     KEYWORD PARAMETERS:
           None.

     COMMON BLOCKS:
           common caos_block, tot_iter, this_iter

           tot_iter   : total number of iteration during the simulation run.
           this_iter  : current iteration number.

     SIDE EFFECTS:
           None.

     RESTRICTIONS:

     CALLED NON-IDL FUNCTIONS:
           none.

     MODIFICATION HISTORY:
           program written: april 2008,
                            Marcel Carbillet (Fizeau) [marcel.carbillet@unice.fr].
           modifications  : april 2016,
                            Marcel Carbillet (Lagrange) [marcel.carbillet@unice.fr]:
                           -adapted to Soft. Pack. CAOS 7.0.

(See ave/ave.pro)

## BQC

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           bqc

     PURPOSE:
           BQC executes the simulation for the Barycenter/Quad-dell Centroid (BQC) module.
           Based on the choice of detector selected in this module's GUI, namely a
           Quad-cell or a CCD, BQC will apply the Quad-cell calculus or the
           barycenter calculus on the image formed over the chosen detector to estimate
           the overall wavefront tip-tilt/loacal tilt on each subaperture. Then BQC outputs
           a out_mes_t structure where the estimated overall/local tip-tilt
           angles are passed to whatever module is next in the simulation.

     CATEGORY:
           Module

     CALLING SEQUENCE:
           error = bqc(inp_mim_t, $ ; mim_t input  structure
                       out_mes_t, $ ; mes_t ouptut structure
                       par      , $ ; parameters   structure
                       INIT=init  ) ; initialisation data structure

     OUTPUT:
           error: long scalar (error code, see !caos_error var in caos_init.pro).

     INPUTS:
           inp_mim_t: structure of type mim_t. Structure containing the SWS
                      IMAGE, info on CCD used (#pixels, pixel size, covered
                      field, ...)
           par      : parameters structure from bqc_gui.

     INCLUDED OUTPUTS:
           out_mes_t: structure of type mes_t containing the vector of the sensor
                      measurement (here, the x-slopes followed by the y-slopes) as well as
                      some info needed by the reconstructor..

     KEYWORD PARAMETERS:
           INIT     : named variable undefined or containing a scalar when BQC is
                      called for the first time. As output the named variable will
                      contain a structure of the initialization data. For the
                      following calls of BQC, the keyword INIT has to be set to the
                      structure returned by the first call.

     COMMON BLOCKS:
           common caos_block, tot_iter, this_iter

           tot_iter   : int scalar. Total number of iteration during the
                        simulation run.
           this_iter  : int scalar. Number of the current iteration. It is
                        defined only while status eq !caos_status.run.
                        (this_iter >= 1).

     SIDE EFFECTS:
           None.

     RESTRICTIONS:
           None.

     CALLED NON-IDL FUNCTIONS:
           None.

     EXAMPLE:
           write here an example!

     ROUTINE MODIFICATION HISTORY:
           program written: Dec 2003,
                            B. Femenia (GTC) [bfemenia@ll.iac.es].
           modifications  : december 2003,
                            Marcel Carbillet (OAA) [marcel@arcetri.astro.it]:
                           -use of variable "calibration" eliminited for compatibility
                            with version 4.0+ of the whole system CAOS.

     MODULE MODIFICATION HISTORY:
           module written : Dec 2003,
                            B. Femenia (GTC) [bfemenia@ll.iac.es].

           modifications  : december 2003,
                            Marcel Carbillet (OAA) [marcel@arcetri.astro.it]:
                           -for version 4.0+ of CAOS structure.
                            no more use of the common variable "calibration" and
                            the tag "calib" (structure "info") from version 4.0 of
                            the whole system CAOS.

                            December 2003,
                            Bruno Femenia (GTC) [bfemenia@ll.iac.es]
                           -this module does not require INIT structure.

                            September 2004,
                            Bruno Femenia (GTC) [bfemenia@ll.iac.es]
                           -this module does require INIT structure.

                            September 2004,
                            Bruno Femenia (GTC) [bfemenia@ll.iac.es]
                           -adapted to version 5.0 of the Software Package CAOS.

                          : april 2016,
                            Marcel Carbillet (Lagrange) [marcel.carbillet@unice.fr]:
                           -adapted to Soft. Pack. CAOS 7.0.

(See bqc/bqc.pro)

## BSP

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           bsp

     ROUTINE'S PURPOSE:
           BSP manages the simulation for the Beam SPlitter (BSP) module,
           that is:
           1-call the module's initialisation routine bsp_init at the first
             iteration of the simulation project
           2-call the module's program routine bsp_prog otherwise.

     MODULE'S PURPOSE:
           BSP executes the simulation for the Beam SPlitter (BSP) module.  This
           module receives a wavefront and splits it into two wavefronts with the
           same wavefront perturbation and such that the sum of their intensities
           is equal to the intensity of the incident wavefront.

     CATEGORY:
           main module's routine

     CALLING SEQUENCE:
           err = bsp(inp_wfp_t, out_wfp_t1, out_wfp_t2, par)

     OUTPUT:
           error     :long scalar (error code, see !caos_error var in caos_init).

     INPUTS:
           inp_wfp_t :incident wavefront of intensity I.

           par       :parameters structure from bsp_gui. In addition to the usual
                      tags associated with the overall management of the program,
                      it contains the following tag:

                        par.frac: Fraction of total intensity sent to first output
                                  wavefront (in AppBuilder, bottom box!!)

     INCLUDED OUTPUTS:
           out_wfp_t1:output wavefront identical to inp_wfp_t except in intensity
                      which is now I1, such that I1+I2= I.

           out_wfp_t2:output wavefront identical to inp_wfp_t except in intensity
                      which is now I2, such that I1+I2= I.

     KEYWORD PARAMETERS:
           None.

     COMMON BLOCKS:
           common caos_block, tot_iter, this_iter

           tot_iter   : total number of iteration during the simulation run.
           this_iter  : current iteration number.

     SIDE EFFECTS:
           None.

     RESTRICTIONS:
           No chromatic behaviour: it splits the same way all wavelengths
           travelling along the simulation with the wavefront.

     CALLED NON-IDL FUNCTIONS:
           none.

     ROUTINE MODIFICATION HISTORY:
           program written: March 1999,
                            B. Femenia   (OAA) [bfemenia@arcetri.astro.it]

           modifications  : Nov 1999,
                            B. Femenia   (OAA) [bfemenia@arcetri.astro.it]
                           -adapted to new version CAOS (v 2.0).
                          : january 2003,
                            Marcel Carbillet (OAA) [marcel@arcetri.astro.it]:
                           -use of variable "calibration" eliminited for version 4.0
                            of the whole CAOS Software System.

     MODULE MODIFICATION HISTORY:
           module written : B. Femenia   (OAA) [bfemenia@arcetri.astro.it].

           modifications  : for version 2.0,
                            B. Femenia   (OAA) [bfemenia@arcetri.astro.it]:
                           -adapted to new version CAOS (v 2.0).
                          : for version 4.0,
                            Marcel Carbillet (OAA) [marcel@arcetri.astro.it]:
                           -no more use of the common variable "calibration" and
                            the tag "calib" (structure "info") for version 4.0 of
                            the whole CAOS Software System.
                          : april 2016,
                            Marcel Carbillet (Lagrange) [marcel.carbillet@unice.fr]:
                           -adapted to Soft. Pack. CAOS 7.0.

(See bsp/bsp.pro)

## CFB

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
        cfb

     ROUTINE'S PURPOSE:
        CFB manages the simulation for the Calibration FiBer (CFB) module,
        that is:
           1-call the module's initialisation routine cfb_init at the first
             iteration of the project
           2-call the module's program routine cfb_prog otherwise, managing
             at the same time the possible time integration/delay.

     MODULE'S PURPOSE:
        This module simulates the PLANE wavefront coming from a calibration fiber
        together with the calibration source map (i.e. calibration fiber is an
        extended object!!) to be used in special calibration projects for modules
        needing such calibration. Unlike the MCA **special** module (see doc header
        in mca.pro), the use of such module is not restricted to those special
        projects. In fact, the user might also decide to calibrate TCE or REC by
        feeding their **SPECIAL** calibration projects with "real" atmospheric
        corrupted wavefronts obtained with the typical combination of SRC+ATM+GPR
        modules which  can be helpful in some particular situations.
        In summary, CBF produces a "PLANE" wavefront coming from an extended source
        (with a Gaussian irradiance pattern) which is optically located at
        infinity.

     CATEGORY:
        main module's routine

     CALLING SEQUENCE:
        error = cfb(out_wfp_t,   $ ; output structure
                    par          $ ; parameter structure
                   )

     OUTPUT:
        error: long scalar (error code, see !caos_error var in caos_init.pro).

     INPUTS:
        None

     INCLUDED OUTPUTS:
        out_wfp_t: structure of type wfp_t containing the map describing the fiber
                   distribution of light together with a flat wavefront.

     KEYWORD PARAMETERS:
        INIT : initialisation data structure.

     COMMON BLOCKS:
        common caos_ao_block, tot_iter, this_iter

        tot_iter   : total number of iteration during the simulation run.
        this_iter  : current iteration number.

     SIDE EFFECTS:
        none.

     RESTRICTIONS:
        At this point only Gaussian irradiance patterns are considered.

     CALLED NON-IDL FUNCTIONS:
        none.

     ROUTINE MODIFICATION HISTORY:
        program written: Nov 1999,
                         B. Femenia   (OAA) [bfemenia@arcetri.astro.it]

        modifications  : May 2000,
                         B. Femenia   (OAA) [bfemenia@arcetri.astro.it]
                        -updating documentation in header.
                       : january 2003,
                         Marcel Carbillet (OAA) [marcel@arcetri.astro.it]:
                        -use of variable "calibration" eliminited for version 4.0
                         of the whole CAOS Software System.

     MODULE MODIFICATION HISTORY:
        module written : B. Femenia   (OAA) [bfemenia@arcetri.astro.it]

        modifications  : for version 4.0,
                         Marcel Carbillet (OAA) [marcel@arcetri.astro.it]:
                        -no more use of the common variable "calibration" and
                         the tag "calib" (structure "info") for version 4.0 of
                         the whole CAOS Software System.
                       : april 2016,
                         Marcel Carbillet (Lagrange) [marcel.carbillet@unice.fr]:
                        -adapted to Soft. Pack. CAOS 7.0.

(See cfb/cfb.pro)

## COM

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
        com

     ROUTINE'S PURPOSE:
        com manages the simulation for the COMbine measurements (COM) module,
        that is:
           1-call the module's initialisation routine com_init at the first
             iteration of the simulation (or calibration) project,
           2-call the module's program routine com_prog otherwise, managing
             at the same time the possible time integration/delay.

     MODULE'S PURPOSE:

     CATEGORY:
        main module's routine

     CALLING SEQUENCE:
        error = com(inp_mes_t1, $ ; 1st input structure
                    inp_mes_t2, $ ; 2nd input structure
                    out_mes_t,  $ ; output structure
                    par         ) ; parameter structure

     OUTPUT:
        error: long scalar (error code, see !caos_error var in caos_init.pro).

     INPUTS:
        inp_mes_t1: structure of type mes_t.
        inp_mes_t2: structure of type mes_t.
        par       : parameters structure.

     INCLUDED OUTPUTS:
        out_mes_t: structure of type mes_t.

     COMMON BLOCKS:
        common caos_block, tot_iter, this_iter

        tot_iter   : total number of iteration during the simulation run.
        this_iter  : current iteration number.

     SIDE EFFECTS:
        none.

     RESTRICTIONS:
        none.

     CALLED NON-IDL FUNCTIONS:
        none.

     ROUTINE MODIFICATION HISTORY:
        routine written: february-march 2001,
                         Marcel Carbillet (OAA) [marcel@arcetri.astro.it].
        modifications  : march 2003,
                         Marcel Carbillet (OAA) [marcel@arcetri.astro.it]:
                        -adapted to new CAOS system (4.0) and building of
                         Software Package MAOS 1.0.
                       : april 2016,
                         Marcel Carbillet (Lagrange) [marcel.carbillet@unice.fr]:
                        -adapted to Soft. Pack. CAOS 7.0.

     MODULE MODIFICATION HISTORY:
        module written : Marcel Carbillet (OAA) [marcel@arcetri.astro.it].
        modifications  : for version 7.0,
                         Marcel Carbillet (Lagrange) [marcel.carbillet@unice.fr]:
                        -adapted to Soft. Pack. CAOS 7.0.

(See com/com.pro)

## COR

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
        cor

     ROUTINE'S PURPOSE:
        cor manages the simulation for the CORonagraph (COR) module,
        that is:
           1-call the module's initialisation routine cor_init at the first
             iteration of the simulation project,
           2-call the module's program routine cor_prog otherwise, managing
             at the same time the possible time integration/delay.

     MODULE'S PURPOSE:
       COR simulates different types of coronagraphs, namely the Roddier & Roddier,
       the Lyot, and the 4 Quadrant Phase Mask. This is a first attempt.

     CATEGORY:
        main module's routine

     CALLING SEQUENCE:
        error = cor(inp_wfp_t, $ ; input structure
                    out_img_t, $ ; output structure
                    par,       $ ; parameter structure
                    INIT=init  ) ; initialisation data structure

     OUTPUT:
        error: long scalar (error code, see !caos_error var in caos_init.pro).

     INPUTS:
        inp_wfp_t: structure of type wfp_t.
        par      : parameters structure.

     INCLUDED OUTPUTS:
        out_img_t: structure of type img_t.

     KEYWORD PARAMETERS:
        INIT: initialisation data structure.
        TIME: time-evolution structure.

     COMMON BLOCKS:
        common caos_block, tot_iter, this_iter

        tot_iter   : total number of iteration during the simulation run.
        this_iter  : current iteration number.

     SIDE EFFECTS:
        none.

     RESTRICTIONS:
        Among them:
        -No noises (photon noise, RON, dark current noise) and no background
        addition implemented for now.
        -No anisoplanatic difference is simulated between the main star and the
        companion (exactly the same wavefront in entrance of the coronagraph).

     CALLED NON-IDL FUNCTIONS:
        none.

     ROUTINE MODIFICATION HISTORY:
        routine written: september 2003,
                         Marcel Carbillet (OAA) [marcel@arcetri.astro.it],
                         Olivier Lardiere (OAA) [lardiere@arcetri.astro.it].
        modifications  : april 2016,
                         Marcel Carbillet (Lagrange) [marcel.carbillet@unice.fr]:
                        -adapted to Soft. Pack. CAOS 7.0.

     MODULE MODIFICATION HISTORY:
        module written : Marcel Carbillet (OAA) [marcel@arcetri.astro.it],
                         Olivier Lardiere (OAA) [lardiere@arcetri.astro.it].
        modifications  : for version 5.0,
                         Marcel Carbillet (LUAN) [marcel.carbille@unice.fr]:
                        -stupid one-value-vector IDL6+ bug corrected (in cor_prog: n_phot->n_phot[0]).
                       : for version 7.0,
                         Marcel Carbillet (Lagrange) [marcel.carbillet@unice.fr]:
                        -adapted to Soft. Pack. CAOS 7.0.

(See cor/cor.pro)

## DMC

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
        dmc

     ROUTINE'S PURPOSE:
        dmc manages the simulation for the Deformable Mirror Conjugated
        (DMC) module, that is:
           1-call the module's initialisation routine dmc_init at the first
             iteration of the simulation project,
           2-call the module's program routine dmc_prog otherwise, managing
             at the same time the possible time integration/delay.

     MODULE'S PURPOSE:
        This module takes commands from one input and an incident wavefront
        from another input, computes the correcting mirror shape (corresponding
        to the commands: first output) AND the corrected wavefront (incident
        wavefront + correcting mirror shape: second output) -- in terms of
        atmosphere layer, including so a conjugation altitude.

        The inputs are then a COM_T structure and a ATM_T structure. If the COM_T
        structure is undefined (first loop) both the outputs corresponds to a flat
        mirror.

        The outputs are two ATM_T structures, containing the correcting mirror
        shape in one hand (1st output), and the corrected wavefront to be analyzed
        by a wavefront sensor in the other hand.

        During the simulation the DMC module uses the commands coming from the
        reconstructor, computes the corresponding mirror shape, subtract it from
        the incident wavefront and outputs the correcting mirror shape as well as
        the corrected wavefront.

     CATEGORY:
        main module's routine

     CALLING SEQUENCE:
        error = dmc(inp_atm_t, $ ; input atmosphere to be corrected
                    inp_com_t, $ ; input commands for the correction
                    out_atm_c, $ ; output correcting mirror shape
                                 ; (computed from the commands)
                    out_atm_t, $ ; output corrected atmosphere
                                 ; (i.e. inp_atm_t + out_atm_c)
                    par,       $ ; parameters structure
                    INIT=init, $ ; initialisation data structure
                    TIME=time  ) ; time integration/delay management structure

     INPUTS:
        inp_atm_t: structure of type atm_t.
                   This is the incident wavefront on the mirror.
        inp_com_t: structure of type com_t.
                   These are the commands sent to the mirror.

     INCLUDED OUTPUTS:
        out_atm_c: structure of type atm_t.
                   This is the atmosphere corresponding to the input commands.
                   (the so-called correcting mirror shape)
        out_atm_t: structure of type atm_t.
                   This is the reflected-corrected atmosphere.

     KEYWORD PARAMETERS:
        INIT: initialisation data structure.
        TIME: time managing structure

     OUTPUT:
        error: error code [long scalar].

     COMMON BLOCKS:
        common caos_block, tot_iter, this_iter

        tot_iter   : total number of iteration during the simulation run.
        this_iter  : current iteration number.

     SIDE EFFECTS:
        none.

     RESTRICTIONS:
        none.

     CALLED NON-IDL FUNCTIONS:
        ...

     ROUTINE MODIFICATION HISTORY:
        routine written: february 2003,
                         Marcel Carbillet (OAA) [marcel@arcetri.astro.it].

     MODULE MODIFICATION HISTORY:
        module written : february/march 2003,
                         Marcel Carbillet (OAA) [marcel@arcetri.astro.it].
        modifications  : may 2014,
                         Marcel Carbillet (Lagrange) [marcel.carbillet@unice.fr]:
                         debugging of DMI about delay reproduced here below.
                         (january 2005, Christophe Verinaud)
                         (error in the shift of time.old_comm - was ok for a delay
                         of 1 time unit but wrong if delay>1.)
                       : april 2016,
                         Marcel Carbillet (Lagrange) [marcel.carbillet@unice.fr]:
                        -adapted to Soft. Pack. CAOS 7.0.

(See dmc/dmc.pro)

## DMI

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
        dmi

     ROUTINE'S PURPOSE:
        dmi manages the simulation for the Deformable MIrror (DMI) module,
        that is:
           1-call the module's initialisation routine dmi_init at the first
             iteration of the simulation (or calibration) project,
           2-call the module's program routine dmi_prog otherwise, managing
             at the same time the possible time integration/delay.

     MODULE'S PURPOSE:
        This module takes commands from one input and an incident wavefront
        from another input, computes the correcting mirror shape (corresponding
        to the commands: first output) AND the corrected wavefront (incident
        wavefront + correcting mirror shape: second output).

        The inputs are then a COM_T structure and a WFP_T structure. If the COM_T
        structure is undefined (first loop) both the outputs correspond to a flat
        mirror.

        The outputs are two WFP_T structures, containing the correcting mirror
        shape in one hand (1st output), and the corrected wavefront to be analyzed
        by a wavefront sensor in the other hand.

        During a "normal running" simulation (the interaction matrix is already
        computed) the DMI module uses the commands coming from the reconstructor
        computes the corresponding mirror shape, subtract it from the incident
        wavefront and outputs the correcting mirror shape as well as  the
        corrected wavefront.

        The piston mode is always subtracted from the mirror shape.

     CATEGORY:
        main module's routine

     CALLING SEQUENCE:
        error = dmi(inp_wfp_t, $ ; input wavefront to be corrected
                    inp_com_t, $ ; input commands for the correction
                    out_wfp_c, $ ; output correcting mirror shape
                                 ; (computed from the commands)
                    out_wfp_t, $ ; output corrected wavefront
                                 ; (i.e. inp_wfp_t + out_wfp_c)
                    par,       $ ; parameters structure
                    INIT=init, $ ; initialisation data structure
                    TIME=time  ) ; time integration/delay management structure

     INPUTS:
        inp_wfp_t: structure of type wfp_t.
                   This is the incident wavefront on the mirror.
        inp_com_t: structure of type com_t.
                   These are the commands sent to the mirror.

     INCLUDED OUTPUTS:
        out_wfp_c: structure of type wfp_t.
                   This is the wavefront corresponding to the input commands.
                   (the so-called correcting mirror shape)
        out_wfp_t: structure of type wfp_t.
                   This is the reflected-corrected wavefront.

     KEYWORD PARAMETERS:
        INIT: initialisation data structure.
        TIME: time managing structure

     OUTPUT:
        error: error code [long scalar].

     COMMON BLOCKS:
        common caos_block, tot_iter, this_iter, calibration, signature

        tot_iter   : total number of iteration during the simulation run.
        this_iter  : current iteration number.
        calibration: is it a calibration project ? (yes=1B, no=0B)

     SIDE EFFECTS:
        none.

     RESTRICTIONS:
        none.

     CALLED NON-IDL FUNCTIONS:
        ...

     ROUTINE MODIFICATION HISTORY:
        routine written: december 1998,
                         Francoise Delplancke (ESO) [fdelplan@eso.org].
        modifications  : december 1999--january 2000,
                         Marcel Carbillet (OAA) [marcel@arcetri.astro.it]:
                        -adapted to version 2.0 (CAOS).
                        -help updated.
                       : january 2005,
                         Christophe Verinaud (ESO) [cverinau@eso.org]:
                        -delay debugged !!
                         (error in the shift of time.old_comm - was ok for a delay
                         of 1 time unit but wrong if delay>1).
                       : january 2006,
                         Marcel Carbillet (LUAN) [marcel.carbillet@unice.fr]:
                        -help corrected (was related to a very old version of DMI).

     MODULE MODIFICATION HISTORY:
        module written : december 1998,
                         Francoise Delplancke (ESO) [fdelplan@eso.org].
        modifications  : december 1999--may 2000,
                         Marcel Carbillet (OAA) [marcel@arcetri.astro.it]:
                        -largely modified in order to fit with version 2.0 (CAOS)
                         [the output out_mir_t is eliminated thanks to the
                          off-line calibration new feature, and the correcting
                          wavefront is added as an output (out_wfp_c) in order
                          to do not artificially duplicate the DMI module when
                          several sources are present].
                       : january-march 2003,
                         Marcel Carbillet (OAA) [marcel@arcetri.astro.it]:
                        -!caos_error.dmi.* variables eliminated for
                         compliance with the CAOS Software System, version 4.0.
                        -no more use of any common variable except tot_iter
                         and this_iter.
                       : january 2005,
                         Christophe Verinaud (ESO) [cverinau@eso.org]:
                        -delay debugged !!
                         (error in the shift of time.old_comm - was ok for a delay
                         of 1 time unit but wrong if delay>1).
                       : april 2016,
                         Marcel Carbillet (Lagrange) [marcel.carbillet@unice.fr]:
                        -adapted to Soft. Pack. CAOS 7.0.

(See dmi/dmi.pro)

## GPR

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
        gpr

     ROUTINE'S PURPOSE:
        gpr manages the simulation for the Geometrical PRopagation (GPR) module,
        that is:
           1-call the module's initialisation routine gpr_init at the first
             iteration of the simulation project,
           2-call the module's program routine gpr_prog otherwise.

     MODULE'S PURPOSE:
        GPR executes the geometrical propagation between either a source at
        infinity (astronomical object) with a given set of angular coordinates
        or a source at a finite distance (laser guide star), with a
        given set of angular and spatial coordinates, and a telescope with a
        given set of spatial coordinates.

     CATEGORY:
        main module's routine

     CALLING SEQUENCE:
        error = gpr(inp_src_t, $
                    inp_atm_t, $
                    out_wfp_t, $
                    par,       $
                    INIT=init  )

     OUTPUTS:
        error: long scalar (error code, see !caos_error var in caos_init.pro).

     INPUTS:
        inp_src_t: the source characteristics
        inp_atm_t: the atmosphere characteristics

     INPUT PARAMETERS:
        par: the user defined input parameters for the GPR

     INCLUDED OUTPUTS:
        out_wfp_t: Structure containing the phase screen, the
                   telescope parameters (coordinates, diameter,
                   obscuration) and source  parameters.
                   Source coordinates are needed in all cases as
                   photometry/spectrometry or wavelength.
                   Focalisation distance is used in the LGS cases.
                   Map and its scale are needed in the extended source
                   source cases.

     KEYWORD PARAMETERS:
        INIT : initialisation data structure.

     COMMON BLOCKS:
        none.

     SIDE EFFECTS:
        none.

     RESTRICTIONS:
        The method consist to add rescaled phase screen calculated by FFT
        or by Zernike generation.

        In the UPWARD propagation case, the distance between each turbulent
        layer (b) is smaller than the distance between the last turbulent
        layer and the sodium layer (a). So it can be considered as Fresnel
        propagation (Only after the LAS module).

        But in the DOWNWARD propagation case, the distance between each
        turbulent layer (b) is equivalent to the distance between the lowest
        turbulent layer and the telescope (c). We are only in the Fraunhoffer
        propagation case (after the SRC and NLS modules).

                  ~~~~~~~~~~~~~~~~~~~~~~~~  sodium layer 90km or infinite
                             ^                 distance in the natural
                             |                     guide star case
                             |
                             |
                             |
                             |  (a)
                             |
                             |
                             v
                  ***********************    differents turbulent layers
                             |  (b)
                  &&&&&&&&&&&&&&&&&&&&&&&     between 10 and 30km

                  #######################
                             | (c)
                        |__________|        telescope 0km

     ROUTINE MODIFICATION HISTORY:
        routine written: october 1998,
                         Marcel Carbillet (OAA) [marcel@arcetri.astro.it],
                         Elise  Viard     (ESO) [eviard@eso.org].
        modifications  : january 1999,
                         Elise Viard (ESO) [eviard@eso.org]:
                        -modifications made...
                       : february 1999,
                         Marcel Carbillet (OAA) [marcel@arcetri.astro.it]:
                        -a few modifications for version 1.0.
                       : march 1999,
                         Marcel Carbillet (OAA) [marcel@arcetri.astro.it]:
                        -phase stripes (rectangular screens) is now managed.
                       : december 1999,
                         Marcel Carbillet (OAA) [marcel@arcetri.astro.it]:
                        -adapted to version 2.0 (CAOS).
                       : december 2000,
                         Marcel Carbillet (OAA) [marcel@arcetri.astro.it]:
                        -the init section is now done during the run section as
                         well in order to easily consider non-constant (wrt time)
                         sources.
                       : january 2003,
                         Marcel Carbillet (OAA) [marcel@arcetri.astro.it]:
                        -use of variable "calibration" eliminited for version 4.0
                         of the whole CAOS Software System.

     MODULE MODIFICATION HISTORY:
        module written : Marcel Carbillet (OAA) [marcel@arcetri.astro.it],
                         Elise  Viard     (ESO) [eviard@eso.org].
        modifications  : for version 1.0,
                         Marcel Carbillet (OAA) [marcel@arcetri.astro.it]:
                         Elise  Viard     (ESO) [eviard@eso.org].
                        -enhanced and adapted to.
                       : for version 1.0.2,
                         Marcel Carbillet (OAA) [marcel@arcetri.astro.it]:
                        -enhanced and debugged.
                       : for version 2.0,
                         Marcel Carbillet (OAA) [marcel@arcetri.astro.it]:
                        -enhanced and adapted to version 2.0 (CAOS).
                       : for version 3.0,
                         Marcel Carbillet (OAA) [marcel@arcetri.astro.it]:
                        -the init section is now done during the run section as
                         well in order to easily consider non-constant (wrt time)
                         sources.
                        -the case where the LGS is lower than a turbulent layer
                         is now implemented.
                       : for version 3.1,
                         Marcel Carbillet (OAA) [marcel@arcetri.astro.it]:
                        -MCAO case now treated.
                       : for version 4.0,
                         Marcel Carbillet (OAA) [marcel@arcetri.astro.it]:
                        -no more use of the common variable "calibration" and
                         the tag "calib" (structure "info") for version 4.0 of
                         the whole CAOS Software System.

(See gpr/gpr.pro)

## IBC

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
        ibc

     ROUTINE'S PURPOSE:
        ibc executes the simulation for the Interferometric Beam Combiner
        (IBC) module.

     MODULE'S PURPOSE:
        IBC simulates an Interferometric Beam Combiner.

     CATEGORY:
        main module's routine

     CALLING SEQUENCE:
        error = ibc(in1_wfp_t, $
                    in2_wfp_t, $
                    out_wfp_t, $
                    par,       $
                    INIT=init  )

     OUTPUT:
        error: error code [long scalar] (see !caos_error in caos_init.pro).

     INPUTS:
        in1_wfp_t: structure of type wfp_t.
        in2_wfp_t: structure of type wfp_t.
        par      : parameters structure from ibc_gui.

     INCLUDED OUTPUTS:
        out_wfp_t: structure of type wfp_t.

     KEYWORD PARAMETERS:
        ...

     COMMON BLOCKS:
        ...

     SIDE EFFECTS:
        none.

     RESTRICTIONS:
        none.

     CALLED NON-IDL FUNCTIONS:
        none.

     ROUTINE MODIFICATION HISTORY:
        routine written: april-october 1999,
                         Marcel Carbillet (OAA) [marcel@arcetri.astro.it],
                         Serge  Correia   (OAA) [correia@arcetri.astro.it]:
        modifications  : december 1999--february 2000,
                         Marcel Carbillet (OAA) [marcel@arcetri.astro.it]:
                        -adapted to version 2.0 (CAOS).
                       : january 2003,
                         Marcel Carbillet (OAA) [marcel@arcetri.astro.it]:
                        -use of variable "calibration" eliminited for version 4.0
                         of the whole CAOS Software System.
                       : april 2016,
                         Marcel Carbillet (Lagrange) [marcel.carbillet@unice.fr]:
                        -adapted to Soft. Pack. CAOS 7.0.

     MODULE MODIFICATION HISTORY:
        module written : Marcel Carbillet (OAA) [marcel@arcetri.astro.it],
                         Serge  Correia   (OAA) [correia@arcetri.astro.it]:
        modifications  : for version 2.0,
                         Marcel Carbillet (OAA) [marcel@arcetri.astro.it]:
                        -adapted to version 2.0 (CAOS).
                       : for version 3.0,
                         Marcel Carbillet (OAA) [marcel@arcetri.astro.it]:
                        -partial diff. piston correction now taken into account.
                       : for version 4.0,
                         Marcel Carbillet (OAA) [marcel@arcetri.astro.it]:
                        -no more use of the common variable "calibration" and
                         the tag "calib" (structure "info") for version 4.0 of
                         the whole CAOS Software System.
                       : for version 5.1,
                         Marcel Carbillet (LUAN) [marcel.carbillet@unice.fr],
                         Olivier Lardiere (LISE) [lardiere@obs-hp.fr]:
                        -densification feature added (for modelling the
                         "densified pupil" case).
                       : for version 7.0,
                         Marcel Carbillet (Lagrange) [marcel.carbillet@unice.fr]:
                        -adapted to Soft. Pack. CAOS 7.0.

(See ibc/ibc.pro)

## IMA

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           ima

     ROUTINE'S PURPOSE:
           IMA manages the simulation for the IMage Adding (IMA) module,
           that is:
           1-call the module's initialisation routine ima_init at the first
             iteration of the simulation project
           2-call the module's program routine ima_prog otherwise.

     MODULE'S PURPOSE:
           IMA receives two wavefronts as inputs and returns their sum/difference
           according to weights supplied by user. This module has been developed to
           check performance of the software and does not care about
           intensities. Accordingly, the output is assigned the same values of
           n_phot and background (see doc on gpr for info on these tags) of the
           first input, unless IMA is used as a "duplicator" of correction in which
           case it detects which input is the correction and which one is the wf
           to be corrected.

     CATEGORY:
           main module's routine

     CALLING SEQUENCE:
           err = ima(inp_img_t1, inp_img_t2, out_img_t, par)

     OUTPUT:
           error:long scalar (error code, see !caos_error var in caos_init.pro).

     INPUTS:
           inp_img_t1:incoming image. (Bottom input in Application builder)

           inp_img_t2:incoming image. (Top input in Application builder)

           par       :parameters structure from ima_gui. In addition to the usual
                      tags associated with the overall management of the program,
                      it contains the following tags:

                      par.wb: assigned weight (+1 or -1) to first input (in
                              AppBuilder, bottom box!!)
                      par.wt: assigned weight (+1 or -1) to second input (in
                              AppBuilder, top box!!)

     INCLUDED OUTPUTS:
           out_img_t :output wavefront with intensity arbitrarily normalized to 1.

     KEYWORD PARAMETERS:
           None.

     COMMON BLOCKS:
           common caos_block, tot_iter, this_iter

           tot_iter   : total number of iteration during the simulation run.
           this_iter  : current iteration number.

     SIDE EFFECTS:
           None.

     RESTRICTIONS:

     CALLED NON-IDL FUNCTIONS:
           none.

     MODIFICATION HISTORY:
           program written: september 2003,
                            Marcel Carbillet (OAA) [marcel@arcetri.astro.it].
           modifications  : april 2016,
                            Marcel Carbillet (Lagrange) [marcel.carbillet@unice.fr]:
                           -adapted to Soft. Pack. CAOS 7.0.

(See ima/ima.pro)

## IMG

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
        img

     ROUTINE'S PURPOSE:
        img manages the simulation for the IMaGe (IMG) module,
        that is:
           1-calls the module's initialisation routine img_init at the first
             iteration of the simulation project
           2-calls the module's program routine img_prog otherwise, managing
             at the same time the possible time integration/delay.

     MODULE'S PURPOSE:

        IMG executes the simulation of the image formation process on a image
        sensor, be it a standard CCD or a Quad-cell usually employed for
        Tip-Tilt sensing. Thus, IMG is basically a copy of the TTS module with
        some features extracted from the PSF module, both existing in v 1.0 (LAOS)
        of this software. For the sake of clarity the purpose of the PSF and TTS
        modules are reproduced here:

           TTS MODULE
           ----------
           Usually a Tip Tilt Sensor system assumes a detector with a square
           array of pixels and placed at the focal plane of a collecting
           lens. This lens receives a collimated beam which previously has
           gone through a turbulent atmosphere and a telescope (this being
           simulated with the GPR module). The presence of an overall Tip-Tilt
           manifests itself as a displacement of the observed intensity
           diffraction pattern with respect to the case where no Tip-Tilt is
           present (in this case the image appears to be centred at the
           optical axis of the system). A measurement of the position of the
           image (carried out by TCE module) is strongly related to the
           overall Tip-Tilt across the telescope pupil.

              The purpose of the TTS module is to simulate the process of
           imaging through a focusing lens on an intensity detector. Such
           simulation is carried out in the framework of Fraunhofer
           diffraction theory involving an FFT operation. The algorithm also
           takes into account the change of resolution involved when binning
           the intensity pattern with a resolution imposed by pixelization of
           Input wavefront to the resolution imposed by pixel size of detector
           as chosen by user. Such a binning process is performed with
           rebin_ccd and involves no interpolation unlike standard IDL routine
           CONGRID. The output is Shack-Hartman intensity type structure
           containing the intensity on the detector and information on the
           geometry of the detector and method.

              Concerning the detector characteristics the user provides, via
           the Graphic User Interface (GUI), the number of pixels on intensity
           detector, their angular size when placed on focal plane of focusing
           lens, the possible delay time required by detector as well as the
           integration time when a measurement is performed (both times in
           units of atmosphere evolution time) and the wavelength at which TTS
           operates. The user must also provide which kind of detector is used
           (Quad-cell detector or CCD) and has the choice of performing
           simulation with or without effects of photon noise (understood as
           Poisson noise and independent between different pixels), dark-current
           noise (also modeled as a Poisson noise) and read-out noise (as a
           truncated Gaussian process). In case a Quad-cell detector is used, the
           user must specify via the GUI the Gaussian optical fiber to be used in
           the calibration to be carried out by TCE.

           PSF MODULE
           ----------
           psf computes the PSF of the system or the image of the object
           through it. This program manages the initialization and calibration
           steps as well as the time behaviour, and then calls the appropriate
           programs (psf_init and psf_prog).

     CATEGORY:
        main module's routine

     CALLING SEQUENCE:
        error = img(inp_wfp_t, out_img_t1, out_img_t2, par, INIT=init, TIME= time)

     OUTPUT:
        error: long scalar (error code). see !caos_error var in caos_init.pro.

     INPUTS:
        inp_wfp_t: structure of type wfp_t.tructure containing the
                   wavefront to be analysed and several other needed
                   information (pupil, optical path perturbations, ...)

        par      : parameters structure from img_gui. In addition to the tags
                   associated to the management of program, the tags containing
                   the parameters for the scientific calculations are:

                     par.time_integ: No. of iterations to integrate
                     par.time_delay: No. of iterations to delay
                     par.foc_dist  : Distance at which IMG focalises [m]
                     par.npixel    : Nb. detector pixels along x- & y-axes
                     par.pxsize    : Detector pixel size [arcsec]
                     par.qeff      : Quantum efficiency
                     par.lambda    : Mean working wavelength [m]
                     par.width     : Bandwidth [m]
                     par.noise     : 0/1=no/yes for Photon, read-out, dark
                                     current noises.
                     par.read_noise: rms for Read-out noise. [e- rms]
                     par.dark_noise: mean for Dark current noise [e-/s]
                     par.backgradd : 0/1=no/yes for sky background adding
                     par.increase  : Factor by which dimensions of arrays
                                     are enlarged to increase sampling of PSF

     INCLUDED OUTPUTS:
        out_img_t2: structure of type img_t. Structure containing the IMAGE on
                    dedicated sensor plus info on CCD used (#pixels, pixel size,
                    covered field, ...)

        out_img_t1: IDEM, but the image it stores is the PSF.

     KEYWORD PARAMETERS:
        INIT: named variable undefined or containing a scalar when IMG is
              called for the first time. As output the named variable will
              contain a structure of the initialization data. For the following
              calls of IMG, the keyword INIT has to be set to the structure
              returned by the first call.

        TIME: time-evolution structure.

     COMMON BLOCKS:
        common caos_block, tot_iter, this_iter

        tot_iter   : int scalar. Total number of iteration during the
                     simulation run.
        this_iter  : int scalar. Number of the current iteration. It is
                     defined only while status eq !caos_status.run.
                     (this_iter >= 1).

     SIDE EFFECTS:
        None.

     RESTRICTIONS:
        None.

     CALLED NON-IDL FUNCTIONS:
        None.

     EXAMPLE:
        Write here an example!

     ROUTINE MODIFICATION HISTORY:
        program written: Oct 1998, (TTS module)
                         B. Femenia (OAA) [bfemenia@arcetri.astro.it]

                         Nov 1998, (PSF module)
                         F. Delplancke (ESO) [fdelplan@eso.org].

                         Jan 2000, (IMG module)
                         B. Femenia (OAA) [bfemenia@arcetri.astro.it]

        modifications  : february 2000,
                         Marcel Carbillet (OAA) [marcel@arcetri.astro.it]:
                        -the PSF output is rendered as the IMAGE output now (in
                         terms of number of photons and noise considerations).
                        -quantum efficiency + noise problems fixed.
                       : September 2001
                         B. Femenia (OAA) [bfemenia@arcetri.astro.it]
                        -IDL 5.4 handles SEEDs in calls to RANDOM such that now
                         the initial seed has to be fed. Now having control
                         over seeds to generate noise.
                       : September 2002,
                         B. Femenia (GTC) [bfemenia@ll.iac.es]
                        -controlling noise seeds via COMMON blocks will result
                         ambiguous in project with two or more IMG modules.
                       : october 2002,
                         Marcel Carbillet (OAA) [marcel@arcetri.astro.it]:
                        -adding sky background noise to the PSF and the image is now
                         an option only (=> added tag/condition par.backgradd).
                       : january 2003,
                         Marcel Carbillet (OAA) [marcel@arcetri.astro.it]:
                        -use of variable "calibration" eliminited for version 4.0
                         of the whole CAOS Software System.
                       : March 2003,
                         B. Femenia (GTC) [bfemenia@ll.iac.es]
                        -merging versions at OAA and GTC.
                       : may 2016,
                         Marcel Carbillet (Lagrange) [marcel.carbillet@unice.fr]:
                        -adapted to Soft. Pack. CAOS 7.0.

     MODULE MODIFICATION HISTORY:
        module written : Oct 1998, (TTS module)
                         B. Femenia (OAA) [bfemenia@arcetri.astro.it]
                       : Nov 1998, (PSF module)
                         F. Delplancke (ESO) [fdelplan@eso.org].
                       : Jan 2000, (IMG module)
                         B. Femenia (OAA) [bfemenia@arcetri.astro.it]

        modifications  : for version 4.0,
                         Marcel Carbillet (OAA) [marcel@arcetri.astro.it]:
                        -no more use of the common variable "calibration" and
                         the tag "calib" (structure "info") for version 4.0 of
                         the whole CAOS Software System.
                       : for version 4.0 as well,
                         B. Femenia (GTC) [bfemenia@ll.iac.es]:
                        -merging versions at OAA and GTC.
                       : for version 7.0,
                         Marcel Carbillet (Lagrange) [marcel.carbillet@unice.fr]:
                        -adapted.

(See img/img.pro)

## IWS

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           iws

     ROUTINE'S PURPOSE:
           IWS manages the simulation for the Ideal Wavefront Sensing (and
           reconstruction) (IWS) module, that is:
           1-call the module's initialisation routine iws_init at the first
             iteration of the simulation project
           2-call the module's program routine iws_prog otherwise.

     MODULE'S PURPOSE:
           IWS receives a wavefront in input and returns a corrected version of it,
           considering fitting error only.

     CATEGORY:
           main module's routine

     CALLING SEQUENCE:
           err = iws(inp_wfp_t, out_wfp_t, par, INIT=init)

     OUTPUT:
           error:long scalar (error code, see !caos_error var in caos_init.pro).

     INPUTS:
           inp_wfp_t: input wavefront.

           par      : parameters structure from iws_gui. In addition to the usual
                      tags associated with the overall management of the program,
                      it contains the following tags:

                      par.radial_order: Zernike radial order desired (correction).
                      par.part_corr: partial correction desired (on Zernike modes
                      corrected).

     INCLUDED OUTPUTS:
           out_wfp_t :output corrected wavefront.

     KEYWORD PARAMETERS:
           None.

     COMMON BLOCKS:
           common caos_block, tot_iter, this_iter

           tot_iter   : total number of iteration during the simulation run.
           this_iter  : current iteration number.

     SIDE EFFECTS:
           None.

     RESTRICTIONS:
           Fitting error only.

     CALLED NON-IDL FUNCTIONS:
           none.

     MODIFICATION HISTORY:
           program written: april 2015,
                            Marcel Carbillet (Lagrange) [marcel.carbillet@unice.fr].

           modifications  : april 2016,
                            Marcel Carbillet (Lagrange) [marcel.carbillet@unice.fr]:
                           -adapted to Soft. Pack. CAOS 7.0.

     MODULE MODIFICATION HISTORY:
           module written : Marcel Carbillet (Lagrange) [marcel.carbillet@unice.fr].

           modifications  : for verison 7.0,
                            Marcel Carbillet (Lagrange) [marcel.carbillet@unice.fr]:
                           -adapted to Soft. Pack. CAOS 7.0.

(See iws/iws.pro)

## LAS

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
        las

     ROUTINE'S PURPOSE:
        las manages the simulation for the LASer definition (LAS) module,
        that is:
           1-call the module's initialisation routine las_init at the first
             iteration of the simulation project,
           2-call the module's program routine las_prog otherwise.

     MODULE'S PURPOSE:
        LAS executes the simulation of a created laser beam. It creates the
        gaussian beam of the laser and modelise its focalisation in the sodium
        layer, and calculates the number of photons emitted.
        LAS allows the user to define the laser shape. Up to now, it is only
        possible to have a gaussian laser, in continuous wave.
        The input power allows us to obtain the number of photons measured in
        the Shack-Hartmann subapertures.
        The waist coefficient is defined with the following formula:
           waist^2 = 2*sigma^2 => waist = sqrt(2)*sigma
           => waist = FWHM / (2*sqrt(alog(2)))
        The user will have to choose also the distance of focalisation of the
        laser.
        Usually, if we consider the sodium layer, it is about 90km. It is not
        necessary the same value as the mean sodium layer altitude (focusing the
        laser is not easy, so errors in focalisation can be taken into account).
        Finally, the artificial star coordinates must be given.

     CATEGORY:
        main module's routine

     CALLING SEQUENCE:
        error = las(out_src_t, par, INIT=init)

     INPUT PARAMETERS:
        par: the user defined input parameters for the NLS

     KEYWORD PARAMETERS:
        INIT: initialisation data structure.

     OUTPUTS:
        error: error code [long scalar].

     INCLUDED OUTPUTS:
        out_src_t: Structure containing the laser beam map in an
                   arbitrary scale, the number of photons and the
                   wavelength considered, the coordinates of the
                   spot laser in the sky and the altitude of
                   focalisation.

     COMMON BLOCKS:
        common caos_block, tot_iter, this_iter

        tot_iter   : total number of iteration during the simulation run.
        this_iter  : current iteration number.

     SIDE EFFECTS:
        none.

     RESTRICTIONS:
        Can only define a gaussian beam !

     CALLED NON-IDL FUNCTIONS:
        none.

     ROUTINE MODIFICATION HISTORY:
        routine written: october 1998,
                         Marcel Carbillet (OAA) [marcel@arcetri.astro.it],
                         Elise  Viard     (ESO) [eviard@eso.org].
        modifications  : january 1999,
                         Elise Viard (ESO) [eviard@eso.org]:
                        -a few modifications for version 1.0.
                       : december 1999--april 2000,
                         Marcel Carbillet (OAA) [marcel@arcetri.astro.it]:
                        -enhanced and adapted to version 2.0 (CAOS).
                       : january 2003,
                         Marcel Carbillet (OAA) [marcel@arcetri.astro.it]:
                        -use of variable "calibration" eliminited for version 4.0
                         of the whole CAOS Software System.
                       : april 2016,
                         Marcel Carbillet (Lagrange) [marcel.carbillet@unice.fr]:
                        -adapted to Soft. Pack. CAOS 7.0.

     MODULE MODIFICATION HISTORY:
        module written : beta-version,
                         Marcel Carbillet (OAA) [marcel@arcetri.astro.it],
                         Elise  Viard     (ESO) [eviard@eso.org].
        modifications  : version 1.0,
                         Elise  Viard     (ESO) [eviard@eso.org],
                        -a few modifications.
                       : version 2.0,
                         Marcel Carbillet (OAA) [marcel@arcetri.astro.it]:
                        -enhanced and adapted to version 2.0 (CAOS).
                        -useless tag TIME took out
                        -module's help imported from las_prog and corrected.
                        -INIT structure and routine las_prog eliminated (useless).
                       : for version 4.0,
                         Marcel Carbillet (OAA) [marcel@arcetri.astro.it]:
                        -no more use of the common variable "calibration" and
                         the tag "calib" (structure "info") for version 4.0 of
                         the whole CAOS Software System.
                       : for version 7.0,
                         Marcel Carbillet (Lagrange) [marcel.carbillet@unice.fr]:
                        -adapted to Soft. Pack. CAOS 7.0.

(See las/las.pro)

## MDS

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
        mds

     ROUTINE'S PURPOSE:
        mds manages the simulation for the Mirror Deformations Sequencer (MDS)
        module, that is:
           1-call the module's initialisation routine mds_init at the first
             iteration of the project
           2-call the module's program routine mds_prog otherwise.

     MODULE'S PURPOSE:
        MDS generates a sequence of mirror deformations.

     CATEGORY:
        main module's routine

     CALLING SEQUENCE:
        error = mds(out_atm_t, par, INIT=init)

     OUTPUT:
        error: long scalar (error code). see !caos_error var in caos_init.pro.

     INPUTS:
        none.

     INCLUDED OUTPUTS:
        out_atm_t: the output structure of ATM, of type "atm_t", containing:
        -screen : 3-variables array of the ensemble of layers' wavefronts of
                  the turbulent atmosphere [m]
        -scale  : spatial scale [m/px]
        -delta_t: base-time [s]
        -alt    : vector of altitudes of the layers [m]
        -dir    : vector of direction of the wind [rd].

     KEYWORD PARAMETERS:
        INIT: initialisation data structure

     COMMON BLOCKS:
        common caos_block, tot_iter, this_iter

        tot_iter   : total number of iteration during the simulation run.
        this_iter  : current iteration number.

     SIDE EFFECTS:
        none.

     RESTRICTIONS:
        none.

     CALLED NON-IDL FUNCTIONS
        none.

     ROUTINE MODIFICATION HISTORY:
        program written: june 2002,
                         Marcel Carbillet (OAA) [marcel@arcetri.astro.it],
                         Christophe Verinaud (OAA) [verinaud@arcetri.astro.it].
        modifications  : july 2002,
                         Marcel Carbillet (OAA) [marcel@arcetri.astro.it]:
                        -Zernike and user-defined deformations are now both well
                         ordered (piston is defined for iter 0 and then the
                         usefull deformations are sent).
                       : january 2003,
                         Marcel Carbillet (OAA) [marcel@arcetri.astro.it]:
                        -use of variable "calibration" eliminited for version 4.0
                         of the whole CAOS Software System.
                       : april 2016,
                         Marcel Carbillet (Lagrange) [marcel.carbillet@unice.fr]:
                        -adapted to Soft. Pack. CAOS 7.0.

     MODULE MODIFICATION HISTORY:
        module written : Marcel Carbillet (OAA) [marcel@arcetri.astro.it],
                         Christophe Verinaud (OAA) [verinaud@arcetri.astro.it].
        modifications  : for version 4.0,
                         Marcel Carbillet (OAA) [marcel@arcetri.astro.it]:
                        -no more use of the common variable "calibration" and
                         the tag "calib" (structure "info") for version 4.0 of
                         the whole CAOS Software System.
                       : for version 7.0,
                         Marcel Carbillet (Lagrange) [marcel.carbillet@unice.fr]:
                        -adapted to Soft. Pack. CAOS 7.0.

(See mds/mds.pro)

## NLS

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
        nls

     ROUTINE'S PURPOSE:
        nls manages the simulation for the Na-Layer Spot (NLS) module,
        that is:
           1-call the module's initialisation routine nls_init at the first
             iteration of the simulation project,
           2-call the module's program routine nls_prog otherwise.

     MODULE'S PURPOSE:
        NLS simulates the sodium layer spot formation.

        Calculate the laser spot shape using discretisation of the
        sodium layer. Give also in output the coordinates within the
        main telescope axis.

        This module defines the Na layer. Three parameters are needed in input:
        the mean altitude of the sodium layer, its width and the number of
        sub-layers you want to consider. In this version the Na density is
        supposed to be a gaussian with a FHWM equal to 0.7849*width/2. The
        nominal peak density has been normalised using published data (cf
        table1, C.S. Gardner, proc. IEEE, vol 77, no 3, march 1989). For each
        sub-layer, the density itself [m^-2] is determined by calculating the
        area under the gaussian density profile.
        The output (Na-spot) is a 3D object, the laser image being
        calculated in each sub-layer (using the input laser shape, the phase
        screen, a defocused term and the density). When seen by the imager
        modules (IMG, SHS) after downward propagation, the spot coordinates
        (in each sub-layer) are used to shift spot images in order to sum them
        and obtain the seen spot image.

     CATEGORY:
        main module's routine

     CALLING SEQUENCE:
        error = nls(inp_wfp_t, $
                    out_src_t, $
                    par,       $
                    INIT=init  )

     INPUTS:
        inp_wfp_t: Structure containing the phase screen after
                   the upward propagation (sum of differents
                   phase screens) and all parameters concerning
                   the laser (auxiliary telescope coordinates,
                   laser map, source position in the sky,
                   focalisation altitude)

     INPUT PARAMETERS:
        par: the user defined input parameters for the NLS

     KEYWORD PARAMETERS:
        INIT: initialisation data structure.

     OUTPUTS:
        error: error code [long scalar]

     INCLUDED OUTPUTS:
        out_src_t: Structure containing the 3D map of the laser
                   and all the parameters needed for the spot propagation.

     COMMON BLOCKS:
        none.

     SIDE EFFECTS:
        None.

     RESTRICTIONS:
        Saturation effects are not considered.

        NLS parameters are supposed constant during the simulation.

        Be careful! The choice of the number of sub-layers is important. If you
        consider large phase screens and big telescopes, you will create big
        arrays for each sub-layer, so don't consider too many sub-layers
        otherwise computation time will increase rapidly.

        On the contrary, don't consider a too small number of sub-layers
        especially if the distance between the two telescopes (emitter and
        receptor telescopes) is large, otherwise the discretisation will not be
        sufficient and the output image is will be wrong (the shift of the spot
        image will be large, so you will obtain a serie of small spots aligned
        with each others).

     NON-IDL ROUTINES:
        nls_density    : gives the integrated density of the sodium layer
                         for each sub-layer
        nls_defocus.pro: calculates at an altitude z the defocus to add
                         to the focused image.
        nls_map.pro:     calculates the 3D spot in the sodium sub-layers.
        nls_coord.pro:   calculates the coordinates of the 3D spot.
        n_phot:          calculates the number of background photons in a
                         chosen bandwidth (this is a general library
                         function that can be found in lib).

     ROUTINE MODIFICATION HISTORY:
        routine written: july 1998,
                         Marcel Carbillet (OAA) [marcel@arcetri.astro.it],
                         Elise  Viard     (ESO) [eviard@eso.org].
        modifications  : november 1998,
                         Elise Viard (ESO) [eviard@eso.org]:
                        -added possibility to have an input file
                       : january 1999,
                         Elise Viard (ESO) [eviard@eso.org]:
                        -modifications for version 1.0.
                       : march 1999,
                         Marcel Carbillet (OAA) [marcel@arcetri.astro.it]:
                        -debugging: one of the status case was missing.
                       : december 1999,
                         Marcel Carbillet (OAA) [marcel@arcetri.astro.it]:
                        -enhanced and adapted to version 2.0 (CAOS).
                       : may 2000,
                         Marcel Carbillet (OAA) [marcel@arcetri.astro.it]:
                        -help corrected.
                       : september 2000,
                         Marcel Carbillet (OAA) [marcel@arcetri.astro.it],
                         Simone Esposito  (OAA) [esposito@arcetri.astro.it],
                         Bruno  Femenia   (OAA) [bfemenia@arcetri.astro.it]:
                        -the 3D spot is also computed during the init phase now
                         (was needed by the CEN module for reference calculation)
                       : january 2003,
                         Marcel Carbillet (OAA) [marcel@arcetri.astro.it]:
                        -use of variable "calibration" eliminited for version 4.0
                         of the whole CAOS Software System.
                       : april 2016,
                         Marcel Carbillet (Lagrange) [marcel.carbillet@unice.fr]:
                        -adapted to Soft. Pack. CAOS 7.0.

     MODULE MODIFICATION HISTORY:
        module written : beta-version,
                         Marcel Carbillet (OAA) [marcel@arcetri.astro.it],
                         Elise  Viard     (ESO) [eviard@eso.org].
        modifications  : version 1.0,
                         Elise Viard (ESO) [eviard@eso.org]:
                         Marcel Carbillet (OAA) [marcel@arcetri.astro.it]:
                        -modifications for version 1.0.
                       : version 2.0,
                         Marcel Carbillet (OAA) [marcel@arcetri.astro.it]:
                        -enhanced and adapted to version 2.0 (CAOS).
                       : for version 4.0,
                         Marcel Carbillet (OAA) [marcel@arcetri.astro.it]:
                        -no more use of the common variable "calibration" and
                         the tag "calib" (structure "info") for version 4.0 of
                         the whole CAOS Software System.
                       : for version 7.0,
                         Marcel Carbillet (Lagrange) [marcel.carbillet@unice.fr]:
                        -adapted to Soft. Pack. CAOS 7.0.

(See nls/nls.pro)

## PYR

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
        pyr

     ROUTINE'S PURPOSE:
        pyr manages the simulation for the "Pyramid WFS"
        (pyr) module, that is:
           1-calls the module's initialisation routine pyr_init at the first
             iteration of the simulation project
           2-calls the module's program routine pyr_prog otherwise, managing
             at the same time the possible time integration/delay.

     MODULE'S PURPOSE:
        During the initialization (first loop), PYR computes the sensor
        geometry and many other useful parameters for the computation of
        the sensor image. Up to now only the squared geometry issupported.
        The main parameters to adjust are the linear number of sub-pupils
        over the diameter, the mini. illumination ratio and the
        modulation  parameters (best is circular with ~8steps per modulation
        angle expressed in lambda/D: if +- 2 lambda/D --> 16 points).

        The 4 quadrant images of the sensor are computed by Fourier
        optics with two possible algorithms.
        First the complex amplitude in the image plane is computed, then
        it is multiplied by either the transmission mask function
        equivalent to pyramid facets or by a pyramidic phasor (phase
        mask); The latter is faster and permits to take into account
        interferences between the 4 quadrants.
        Finally, a reverse Fourier Transform permits to compute the
        image on the sensor in the pupil plane. In case of modulation,
        the complex amplitude in image plane is shifted in a few steps,
        describing a square (ols version) or circular figure  of the
        image. For each step, the same computation is done and the
        squared moduli of the final image in pupil plane at each step
        are summed up.

        Rem:  Extended source and laser not yet supported.

     CATEGORY:
           main module's routine

     CALLING SEQUENCE:
           error = pyr(inp_wfp_t, out_mim_t1, out_img_t2, par, INIT=init, TIME=time)

     OUTPUT:
           error: long scalar (error code). see !caos_error var in caos_init.pro.

     INPUTS:
           inp_wfp_t: structure of type wfp_t.tructure containing the
                      wavefront to be analysed and several other needed
                      information (pupil, optical path perturbations, ...)

           par      : parameters structure from pyr_gui with tags associated to
                      the management of program and tags containing relevant
                      parameters for the scientific calculations.
                      (See GUI DESCRIPTION section below for further details)

     INCLUDED OUTPUTS:
           out_mim_t1: structure of type mim_t. Structure containing the 4 pupil image
                       on the CCD and the sensor geometry structure.

    	out_img_t2: structure of type img_t. Structure containing the image
                       plane on top of pyramid, integrated during dynamic
    		    modulation.

     KEYWORD PARAMETERS:
           INIT     : named variable undefined or containing a scalar when pyr is
                      called for the first time. As output the named variable will
                      contain a structure of the initialization data. For the
                      following calls of pyr, the keyword INIT has to be set to
                      the structure returned by the first call.

           TIME     : time-evolution structure.

     OPTIONAL OUTPUTS:
           None.

     COMMON BLOCKS:
           common caos_block, tot_iter, this_iter

           tot_iter   : int scalar. Total number of iteration during the
                        simulation run.
           this_iter  : int scalar. Number of the current iteration. It is
                        defined only while status eq !caos_status.run.
                        (this_iter >= 1).

     SIDE EFFECTS:
           None.

     RESTRICTIONS:
           None.

     GUI DESCRIPTION:
           see pyr help.

     ROUTINE MODIFICATION HISTORY:
           program written: june 2001,
                            Christophe Verinaud (OAA) [verinaud@arcetri.astro.it].

           modifications  : october 2002,
                            Christophe Verinaud (OAA) [verinaud@arcetri.astro.it]:
                           -phase mask alternative added.
                          : january 2003,
                            Marcel Carbillet (OAA) [marcel@arcetri.astro.it]:
                           -use of variable "calibration" eliminited for version 4.0
                            of the whole CAOS System.
                           -second output from mim_t to img_t.
                          : may 2016,
                            Marcel Carbillet (Lagrange) [marcel.carbillet@unice.fr]:
                           -adapted to Soft. Pack. CAOS 7.0.

     MODULE MODIFICATION HISTORY:
           module written : Christophe Verinaud (OAA) [verinaud@arcetri.astro.it].

           modifications  : october 2002,
                            Christophe Verinaud (OAA) [verinaud@arcetri.astro.it]:
                           -phase mask alternative added.
                          : january 2003,
                            Marcel Carbillet (OAA) [marcel@arcetri.astro.it]:
                           -no more use of the common variable "calibration" and
                            the tag "calib" (structure "info") for version 4.0 of
                            the whole CAOS Software System.
                           -second output from mim_t to img_t.
                          : february 2003,
                            Christophe Verinaud (ESO) [cverinau@eso.org]:
                           - bug correction for dark noise.
                          : october 2004,
                            Marcel Carbillet (LUAN) [marcel.carbillet@unice.fr]:
                           - stupid one-value-vector IDL6+ bug corrected (in pyrccd_circ.pro: px->px[0]).
                          : may 2016,
                            Marcel Carbillet (Lagrange) [marcel.carbillet@unice.fr]:
                           -adapted to Soft. Pack. CAOS 7.0.

(See pyr/pyr.pro)

## REC

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
        rec

     ROUTINE'S PURPOSE:
        rec manages the simulation for the ReConstruction and Conjugation
        (REC) module, that is:
           1-call the module's initialisation routine rec_init at the first
             iteration of the simulation project,
           2-call the module's program routine rec_prog otherwise.

     MODULE'S PURPOSE:
        This module reconstructs the sensed wavefront in terms of a set of mirror's
        commands.

        The interaction matrix is computed during an off-line calibration process,
        using either Zernike polynomials or user-defined mirror deformations that
        can be influence functions, or whatever set of mirror deformations.

        The inversion process uses the singular value decomposition (SVD) algorithm.

        In case of zonal reconstruction, be aware of not cutting the number of modes
        (here the number of influence functions!) by setting a value to par.modes < the
        number of influence functions, but rather calculate a brand new "wuv" resulting
        from the SVD process performed during iteration zero.

     CATEGORY:
        main module's routine

     CALLING SEQUENCE:
        error = rec(inp_mes_t, $
                    out_com_t, $
                    par,       $
                    INIT=init  $

     OUTPUT:
        error: long scalar (error code, see !caos_error var in caos_init.pro).

     INPUTS:
        inp_mes_t: structure of type mes_t.
        par      : parameters structure.

     INCLUDED OUTPUTS:
        out_com_t: structure of type com_t.

     KEYWORD PARAMETERS:
        INIT: initialisation data structure

     COMMON BLOCKS:
        common caos_block, tot_iter, this_iter

        tot_iter   : total number of iteration during the simulation run.
        this_iter  : current iteration number.

     SIDE EFFECTS:
        none.

     RESTRICTIONS:
        none.

     CALLED NON-IDL FUNCTIONS:
        none.

     ROUTINE MODIFICATION HISTORY:
        routine written: june 2002,
                         Marcel Carbillet (OAA) [marcel@arcetri.astro.it].
        modifications  : january/february 2003,
                         Marcel Carbillet (OAA) [marcel@arcetri.astro.it]:
                        -use of variable "calibration" eliminited for version 4.0
                         of the whole CAOS Software System.
                        -atmosphere-type output eliminated (became useless wrt
                         command-type output + use of new module DMC).
                        -module's name from RCC to REC (eliminating old module REC).
                       : help clarified in order to avoid bad behaviors when
                         dealing with zonal reconstruction (influence functions).
                       : may 2016,
                         Marcel Carbillet (Lagrange) [marcel.carbillet@unice.fr]:
                        -adapted to Soft. Pack. CAOS 7.0.

     MODULE MODIFICATION HISTORY:
        module written : Marcel Carbillet (OAA) [marcel@arcetri.astro.it].

        modifications  : for version 4.0,
                         Marcel Carbillet (OAA) [marcel@arcetri.astro.it]:
                        -no more use of the common variable "calibration" and
                         the tag "calib" (structure "info") for version 4.0 of
                         the whole CAOS Software System.
                        -atmosphere-type output eliminated (became useless wrt
                         command-type output + use of new module DMC).
                        -module's name from RCC to REC (eliminating old module REC).
                       : may 2016,
                         Marcel Carbillet (Lagrange) [marcel.carbillet@unice.fr]:
                        -adapted to Soft. Pack. CAOS 7.0.

(See rec/rec.pro)

## SCD

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
        scd

     ROUTINE'S PURPOSE:
        scd manages the simulation for the Save Calibration Data (SCD) module,
        that is:
           1-call the module's initialisation routine scd_init at the first
             iteration of the simulation project,
           2-call the module's program routine scd_prog otherwise.

     MODULE'S PURPOSE:

     CATEGORY:
        main module's routine

     CALLING SEQUENCE:
        error = scd(inp_mes_t, $ ; mes_t input structure
                    inp_atm_t, $ ; atm_t input structure
                    par,       $ ; parameter structure
                    INIT=init  ) ; initialisation data structure

     OUTPUT:
        error: long scalar (error code, see !caos_error var in caos_init.pro).

     INPUTS:
        inp_atm_t: structure of type atm_t.
        inp_zzz_t: structure of type mes_t.
        par      : parameters structure.

     INCLUDED OUTPUTS:
        none.

     KEYWORD PARAMETERS:
        INIT: initialisation data structure.

     COMMON BLOCKS:
        common caos_block, tot_iter, this_iter

        tot_iter   : total number of iteration during the simulation run.
        this_iter  : current iteration number.

     SIDE EFFECTS:
        none.

     RESTRICTIONS:
        none.

     CALLED NON-IDL FUNCTIONS:
        none.

     ROUTINE MODIFICATION HISTORY:
        routine written: june 2002,
                         Marcel Carbillet (OAA) [marcel@arcetri.astro.it].

        modifications  : january 2003,
                         Marcel Carbillet (OAA) [marcel@arcetri.astro.it]:
                        -use of variable "calibration" eliminited for version 4.0
                         of the whole CAOS Software System.
                       : may 2016,
                         Marcel Carbillet (Lagrange) [marcel.carbillet@unice.fr]:
                        -adapted to Soft. Pack. CAOS 7.0.

     MODULE MODIFICATION HISTORY:
        module written : Marcel Carbillet (OAA) [marcel@arcetri.astro.it].

        modifications  : for version 4.0,
                         Marcel Carbillet (OAA) [marcel@arcetri.astro.it]:
                        -no more use of the common variable "calibration" and
                         the tag "calib" (structure "info") for version 4.0 of
                         the whole CAOS Software System.
                       : may 2016,
                         Marcel Carbillet (Lagrange) [marcel.carbillet@unice.fr]:
                        -adapted to Soft. Pack. CAOS 7.0.

(See scd/scd.pro)

## SLO

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
        slo

     ROUTINE'S PURPOSE:
        slo manages the simulation for the slope computation (slo) module for PYR,
        that is:
           1-call the module's initialisation routine slo_init at the first
             iteration of the simulation project,
           2-call the module's program routine slo_prog otherwise.

     MODULE'S PURPOSE:
        It takes the image coming out of the Pyramid wavefront sensor and
        computes the x- and y signals positions for each sub-aperture.

        GUI details
        -----------
       select algorithm : normalise by total energy or by intensity in each sub.

     CATEGORY:
        main module's routine

     CALLING SEQUENCE:
        error = slo(inp_mim_t, $
                    out_mes_t, $
                    par,       $
                    INIT=init  )

     OUTPUT:
        error: long scalar (error code, see !caos_error var in caos_init.pro).

     INPUT:
        inp_mim_t: structure of type mim_t.
                   It contains the Pyramid wavefront sensor image
                   and some geometrical parameters of the PYR.

     INCLUDED OUTPUT:
        out_mes_t: structure of type mes_t.
                   It contains the vector of the sensor measurements
                   (here, the x-slopes followed by the y-slopes) as well as
                   some info about the sensor shape in case this information
                   has to be checked by the reconstructor.

     KEYWORD PARAMETERS:
        INIT: initialisation data structure.

     COMMON BLOCKS:
        common caos_block, tot_iter, this_iter

        tot_iter   : total number of iteration during the simulation run.
        this_iter  : current iteration number.

     SIDE EFFECTS:
        none.

     RESTRICTIONS:
        none.

     CALLED NON-IDL FUNCTIONS:
        slope.pro

     ROUTINE MODIFICATION HISTORY:
        routine written: june 2001,
                         Christophe Verinaud (OAA) [verinaud@arcetri.astro.it].
        modifications  : january 2003,
                         Marcel Carbillet (OAA) [marcel@arcetri.astro.it]:
                        -use of variable "calibration" eliminited for version 4.0
                         of the whole CAOS Software System.
                       : may 2016,
                         Marcel Carbillet (Lagrange) [marcel.carbillet@unice.fr]:
                        -adapted to Soft. Pack. CAOS 7.0.

     MODULE MODIFICATION HISTORY:
        module written : Christophe Verinaud (OAA) [verinaud@arcetri.astro.it].
        modifications  : october 2002,
                         Christophe Verinaud (OAA) [verinaud@arcetri.astro.it]:
                        -normalization alternative added.
                       : january 2003,
                         Marcel Carbillet (OAA) [marcel@arcetri.astro.it]:
                        -no more use of the common variable "calibration" and
                         the tag "calib" (structure "info") for version 4.0 of
                         the whole CAOS Software System.
                       : may 2016,
                         Marcel Carbillet (Lagrange) [marcel.carbillet@unice.fr]:
                        -adapted to Soft. Pack. CAOS 7.0.

(See slo/slo.pro)

## SRC

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
        src

     ROUTINE'S PURPOSE:
        SRC manages the simulation for the Calibration FiBer (SRC) module,
        that is:
          1-call the module's initialisation routine src_init at the first
            iteration of the project
          2-call the module's program routine src_prog otherwise, managing
            at the same time the possible time integration/delay.

     MODULE'S PURPOSE:
        src executes the simulation for SouRCe (SRC) module.
        The source chosen can be either a natural object or a laser guide star,
        and either a point-like or 2D-object.
        In this last case (2D-objects), the map can be either a
        user-defined one or a map calculated by the module, with a
        uniform disc-like shape or a gaussian one (that can be
        elongated).
        The magnitude of the source can be chosen, as well as its
        spectral type (in case of a natural object) and the values
        of the background in the different Johnson bands (+ a Na band).
        The number of photons computation is then done assuming that a
        natural object is a black body-like one.
        In the laser guide star case, the given magnitude is an
        equivalent V-magnitude.
        Finally, the angular position of the object has to be chosen, as
        well as its distance from the observing telescope (in case of a
        laser guide star).

     CATEGORY:
        main module's routine

     CALLING SEQUENCE:
        error = src(out_src_t, par, INIT=init)

     OUTPUT:
        error: long scalar (error code). see !caos_error var in caos_init.pro.

     INPUTS:
        none.

     INCLUDED OUTPUTS:
        out_src_t: structure of type "src_t" containing the characteristics of
                   the selected source, the following fields are contained in
                   this structure:
                   off_axis  : off-axis of source wrt main tel. [rd]
                   pos_ang   : position angle of source wrt main tel. [rd]
                   dist_z    : dist. main tel.-object [m] (inf. if astro. one)
                   map       : source map (if 2d astronomical object)
                   scale_xy  : map scale (if any) [rd/px]
                   coord     : [not used]
                   scale_z   : [not used]
                   n_phot    : number(s) of photons  [/s/m^2] (vs. wavelength)
                   background: sky background(s) [/s/m^2/arcsec^2] (id.)
                   lambda    : wavelength(s) [m]
                   width     : band-width(s) [m]

     KEYWORD PARAMETERS:
        INIT: named variable undefined or containing a scalar when src is
              called for the first time. As output the named variable will
              contain a structure of the initialization data. For the following
              calls of src, the keyword INIT has to be set to the structure
              returned by the first call.

     COMMON BLOCKS:
        common caos_ao_block, tot_iter, this_iter

        tot_iter   : total number of iteration during the simulation run.
        this_iter  : current iteration number.

     SIDE EFFECTS:
        none.

     RESTRICTIONS:
        none.

     PROCEDURE:
        none.

     CALLED NON-IDL FUNCTIONS:
        n_phot  : for number of photons calculus (see in .../lib).
        spec2mag: to transform a V-magnitude into any other band
                  magnitude (see in .../lib).

     ROUTINE MODIFICATION HISTORY:
        program written: october 1998,
                         Marcel Carbillet (OAA) [marcel@arcetri.astro.it].
        modifications  : february 1999,
                         Marcel Carbillet (OAA) [marcel@arcetri.astro.it]:
                        -a few modifications for version 1.0.
                       : march 1999,
                         Marcel Carbillet (OAA) [marcel@arcetri.astro.it],
                         Simone Esposito  (OAA) [esposito@arcetri.astro.it]:
                        -added 2D-objects calculation feature.
                       : Nov 1999,
                         B. Femenia   (OAA) [bfemenia@arcetri.astro.it]
                         M. Carbillet (OAA) [marcel@arcetri.astro.it]
                        -adapted to new version CAOS (v 2.0).
                       : may 2016,
                         Marcel Carbillet (Lagrange) [marcel.carbillet@unice.fr]:
                        -adapted to Soft. Pack. CAOS 7.0.

     MODULE MODIFICATION HISTORY:
        module written : Marcel Carbillet (OAA) [marcel@arcetri.astro.it].
        modifications  : for version 4.0,
                         Marcel Carbillet (OAA) [marcel@arcetri.astro.it]:
                        -no more use of the common variable "calibration" and
                         the tag "calib" (structure "info") for version 4.0 of
                         the whole CAOS Software System.
                       : may 2016,
                         Marcel Carbillet (Lagrange) [marcel.carbillet@unice.fr]:
                        -adapted to Soft. Pack. CAOS 7.0.

(See src/src.pro)

## SSC

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
        ssc

     ROUTINE'S PURPOSE:
        ssc manages the simulation for the State-Space Control (SSC) module,
        that is:
           1-call the module's initialisation routine ssc_init at the first
             iteration of the simulation project,
           2-call the module's program routine ssc_prog otherwise, managing
             at the same time the possible time integration/delay.

     MODULE'S PURPOSE:

     CATEGORY:
        main module's routine

     CALLING SEQUENCE:
        error = ssc(inp_mes_t, $ ; input structure
                    out_com_t, $ ; output structure
                    par,       $ ; parameter structure
                    INIT=init  ) ; initialisation data structure

     OUTPUT:
        error: long scalar (error code, see !caos_error var in caos_init.pro).

     INPUTS:
        inp_mes_t: structure of type com_t.
        par      : parameters structure.

     INCLUDED OUTPUTS:
        out_com_t: structure of type com_t.

     KEYWORD PARAMETERS:
        INIT: initialisation data structure.

     COMMON BLOCKS:
        common caos_block, tot_iter, this_iter

        tot_iter   : total number of iteration during the simulation run.
        this_iter  : current iteration number.

     SIDE EFFECTS:
        none.

     RESTRICTIONS:
        none.

     CALLED NON-IDL FUNCTIONS:
        none.

     ROUTINE MODIFICATION HISTORY:
        routine written: february 2012,
                         Marcel Carbillet (Lagrange) [marcel.carbillet@unice.fr].
        modifications  : may 2016,
                         Marcel Carbillet (Lagrange) [marcel.carbillet@unice.fr]:
                        -adapted to Soft. Pack. CAOS 7.0.

     MODULE MODIFICATION HISTORY:
        module written : Marcel Carbillet (Lagrange) [marcel.carbillet@unice.fr].
        modifications  : for version 7.0,
                         Marcel Carbillet (Lagrange) [marcel.carbillet@unice.fr]:
                        -adapted.

(See ssc/ssc.pro)

## STF

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
        stf

     ROUTINE'S PURPOSE:
        stf manages the simulation for the STructure Function calculation (STF)
        module.

     MODULE'S PURPOSE:
        STF computes the theoretical structure function from
        the input parameters r0 and L0, and the simulated one from the
        input wavefronts, updating it at each iteration of the
        simulation.

     CATEGORY:
        main module's routine

     CALLING SEQUENCE:
        error = stf(inp_wfp_t, out_stf_t, par, INIT=init)

     INPUT:
        inp_wfp:  structure of type wfp_t

     KEYWORD PARAMETERS:
        INIT: ...

     OUTPUTS:
        error: long scalar (error code).

     COMMON BLOCKS:
        none.

     SIDE EFFECTS:
        none.

     RESTRICTIONS:
        The simulated structure is performed only along the x- and the
        y-axis of the pupil, and then averaged.

     PROCEDURE:
        none.

     ROUTINE MODIFICATION HISTORY:
        routine written: july 1998,
                         Marcel Carbillet (OAA) [marcel@arcetri.astro.it].
        modifications  : december 1999,
                         Marcel Carbillet (OAA) [marcel@arcetri.astro.it]:
                        -adapted to version 2.0 (CAOS).
                       : january 2003,
                         Marcel Carbillet (OAA) [marcel@arcetri.astro.it]:
                        -use of variable "calibration" eliminited for version 4.0
                         of the whole CAOS Software System.
                       : may 2016,
                         Marcel Carbillet (Lagrange) [marcel.carbillet@unice.fr]:
                        -adapted to Soft. Pack. CAOS 7.0.

     MODULE MODIFICATION HISTORY:
        module written : version 1.0,
                         Marcel Carbillet (OAA) [marcel@arcetri.astro.it].
        modifications  : version 2.0,
                         Marcel Carbillet (OAA) [marcel@arcetri.astro.it]:
                        -adapted to version 2.0 (CAOS).
                       : for version 4.0,
                         Marcel Carbillet (OAA) [marcel@arcetri.astro.it]:
                        -no more use of the common variable "calibration" and
                         the tag "calib" (structure "info") for version 4.0 of
                         the whole CAOS Software System.
                       : for version 7.0,
                         Marcel Carbillet (Lagrange) [marcel.carbillet@unice.fr]:
                        -adapted..

(See stf/stf.pro)

## SWS

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
        sws

     ROUTINE'S PURPOSE:

        SWS manages the simulation for the Shack-Hartmann Wavefront Sensor
        (SWS) module, that is:
           1-calls the module's initialisation routine sws_init at the first
             iteration of the simulation (or calibration) project
           2-calls the module's program routine sws_prog otherwise, managing
             at the same time the possible time integration/delay.

     MODULE'S PURPOSE:

           SWS executes the simulation of the Shack-Hartmann Wavefront sensor,
           adopting a similar procedure as the IMG module to enlarge the phase
           screen in the incoming inp_wfp_t so that the SWS CCD pixel is n times (n
           integer) the size of the pixel size due to FFTing the phase screen. By
           doing this we won't need any interpolation process but a fater and
           accurate standard REBIN call. Another improvement concerns the use of
           the much faster FFTW routines over the standard IDL routines. On the
           other hand this module is kept as its minimum so it lacks all the
           advanced features in the original CAOS SHS module. The geometry is
           always assumed to be of Fried type.

     CATEGORY:
           main module's routine

     CALLING SEQUENCE:
           error = sws(inp_wfp_t, out_mim_t, par, INIT=init, TIME= time)

     OUTPUT:
           error: long scalar (error code). see !caos_error var in caos_init.pro.

     INPUTS:
           inp_wfp_t: structure of type wfp_t.tructure containing the
                      wavefront to be analysed and several other needed
                      information (pupil, optical path perturbations, ...)

           par      : parameters structure from sws_gui. Contains the tags
                      associated to the management of program as well as the tags
                      containing the parameters for the scientific calculations.
                      (See GUI DESCRIPTION section below for further details)

     INCLUDED OUTPUTS:
           out_mim_t: structure of type mim_t. Structure containing the SHWFS image
                      on the CCD and the sensor geometry structure.

     KEYWORD PARAMETERS:
           INIT     : named variable undefined or containing a scalar when SWS is
                      called for the first time. As output the named variable will
                      contain a structure of the initialization data. For the
                      following calls of SWS, the keyword INIT has to be set to
                      the structure returned by the first call.

           TIME     : time-evolution structure.

     OPTIONAL OUTPUTS:
           None.

     COMMON BLOCKS:
           common caos_block, tot_iter, this_iter

           tot_iter   : int scalar. Total number of iteration during the
                        simulation run.
           this_iter  : int scalar. Number of the current iteration. It is
                        defined only while status eq !caos_status.run.
                        (this_iter >= 1).

     SIDE EFFECTS:
           None.

     RESTRICTIONS:
           -Only Fried geometry is allowed in initial version.
           -Unlike SHS module, no advanced parameters are allowed.
           -Program assumes that each subaperture samples a square WF with an integer number of
            sampling WF pixels. If this is not the case report error and exit.

     ROUTINE MODIFICATION HISTORY:
           program written: Dec 2003,
                            B. Femenia (GTC) [bfemenia@ll.iac.es].
           modifications  : december 2003,
                            Marcel Carbillet (OAA) [marcel@arcetri.astro.it]:
                           -use of variable "calibration" eliminited from version 4.0
                            of the whole system CAOS.
                          : may 2016,
                            Marcel Carbillet (Lagrange) [marcel.carbillet@unice.fr]:
                           -adapted to Soft. Pack. CAOS 7.0.

     MODULE MODIFICATION HISTORY:
           module written : Dec 2003,
                            B. Femenia (GTC) [bfemenia@ll.iac.es].
           modifications  : for CAOS 4.0+ compatibility,
                            Marcel Carbillet (OAA) [marcel@arcetri.astro.it]:
                           -no more use of the common variable "calibration" and
                            the tag "calib" (structure "info") from version 4.0 of
                            the whole system CAOS.
                          : for version 7.0,
                            Marcel Carbillet (Lagrange) [marcel.carbillet@unice.fr]:
                           -adapted.

(See sws/sws.pro)

## TCE

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
        tce

     PURPOSE:
        TCE executes the simulation for the Tip-tilt CEntroid (TCE) module.
        Based on the choice of detector selected in this module's GUI, namely a
        Quad-cell or a CCD, TCE will apply the Quad-cell calculus or the
        barycenter calculus on the image formed over the chosen detector (and
        obtained with a Tip-Tilt sensor module) to estimate the overall wavefront
        tip-tilt. Then TCE outputs a out_com_t struc. where the estimated tip-tilt
        angles are passed to whatever module is next in the simulation.

     CATEGORY:
        Module

     CALLING SEQUENCE:
        error = tce(          $
                   inp_img_t, $  ; img_t input  structure
                   out_com_t, $  ; com_t output structure
                   par,       $  ; parameters structure
                   INIT=init  $  ; initialisation structure
                   )

     OUTPUT:
        error: long scalar (error code, see !caos_error var in caos_init.pro).

     INPUTS:
        inp_img_t: structure of type img_t. Structure containing the IMG
                   IMAGE, info on CCD used (#pixels, pixel size, covered
                   field, ...)
        par      : parameters structure from tce_gui. At time of writing this
                   version it was unnecessary to pass any science parameter via
                   GUI, but it is left for completeness. Therefore, in this
                   version the par structure associated to TCE only contains
                   tags associated to the management of program, but no
                   parameter relevant to scientific program.

     INCLUDED OUTPUTS:
        out_com_t: structure of type com_t telling the Tip-Tilt Mirror how to
                   act in order to correct a measured TipTilt. Tilt angles are
                   calculated  in radians.

     KEYWORD PARAMETERS:
        INIT     : named variable undefined or containing a scalar when TCE is
                   called for the first time. As output the named variable will
                   contain a structure of the initialization data. For the
                   following calls of TCE, the keyword INIT has to be set to the
                   structure returned by the first call.

     COMMON BLOCKS:
        common caos_block, tot_iter, this_iter

        tot_iter   : int scalar. Total number of iteration during the
                     simulation run.
        this_iter  : int scalar. Number of the current iteration. It is
                     defined only while status eq !caos_status.run.
                     (this_iter >= 1).

     SIDE EFFECTS:
        None.

     RESTRICTIONS:
        None.

     CALLED NON-IDL FUNCTIONS:
        None.

     EXAMPLE:
        write here an example!

     MODIFICATION HISTORY:
        program written: Feb 1999,
                         B. Femenia (OAA) [bfemenia@arcetri.astro.it]
                        -written to match general style and requirements on
                         how to manage initialization process, calibration
                         procedure and time management according to  released
                         templates on Feb 1999.
                       : Nov 1999,
                         B. Femenia   (OAA) [bfemenia@arcetri.astro.it]
                        -adapted to new version CAOS (v 2.0).
                       : Jan 2000,
                         B. Femenia   (OAA) [bfemenia@arcetri.astro.it]
                        -TCE now accepts inputs coming from IMG module whose
                         output structure is now of type img_t.
                       : April 2001,
                         B. Femenia   (OAA) [bfemenia@arcetri.astro.it]
                        -TCE_GUI considers a new field where Q-cell calibration
                         constant is fed.
                       : february 2003,
                         Marcel Carbillet (OAA) [marcel@arcetri.astro.it]:
                        -common variable "calibration" eliminated.
                       : may 2016,
                         Marcel Carbillet (Lagrange) [marcel.carbillet@unice.fr]:
                        -adapted to Soft. Pack. CAOS 7.0.

(See tce/tce.pro)

## TFL

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
        tfl

     ROUTINE'S PURPOSE:
        tfl manages the simulation for the Time FiLtering (TFL) module,
        that is:
           1-call the module's initialisation routine tfl_init at the first
             iteration of the simulation project
           2-call the module's program routine tfl_prog otherwise, managing
             at the same time the possible time integration/delay.

     PURPOSE:
        "tfl.pro" executes the simulation for the Time FiLtering (TFL) module:
        it allows to apply a different discrete recursive filter for
        each element (degree of freedom or DOF) of a time-variable vector of
        input commands. The discrete filter is obtained by the
        discretization of a rational analog filter used as prototype.
        In the current release, the discretization of the prototype
        filter is obtained applying the bilinear (Tustin) transform
        [Oppenheim & Schafer, 1989, sec. 7.1.2] to the analog filter
        tranfer function.

        The parameters associated to an instance of the module TFL can be
        set with the use of the Grafical User Intergace (GUI) called by
        the TFL_GUI function. It allows the user to choose if defining
        the same filter for all the DOF of the input command vector or a
        different one for each DOF. In both the cases the analog filter
        prototype can be defined in the GUI entering the data
        associated to one of following parametric description of
        its Laplace Transfer Function (TF):

         a) "Pure Integrator"; a single pole @ 0Hz with a user defined
                               gain G:
                                           TF(s) = G/s

                               G >= 0.

         b) "Proportional-Integrator-Derivative (PID)";
                               the linear combination of a proportional, an
                               integrator, and a derivative filter with
                               user defined gains K_p, K_i and K_d
                               respectively:

                                                  1            A
                             TF(s) = K_p + K_i * --- + K_d * ----- * s
                                                  s           s+A

                               K_p, K_i, K_d >= 0;  A > 0 (when K_d ne 0).

                               The user can also define the cut frequency
                               A of the low-pass correction of the
                               derivative portion of the filter for noise
                               filtering purposes.

        c) "Gain-Zeros-Poles (GZP)"; a more general representation of a
                               rational filter transfer function in terms
                               of user defined gain G, zeros z[i], and
                               poles p[j]:

                                      (s+z[0])*(s+z[1])*...*(s+z[nz-1])
                          TF(s) = G * ---------------------------------
                                      (s+p[0])*(s+p[1])*...*(s+p[np-1])

                               nz, np <= 4, G >= 0, real z[i], and real p[j]
                                                    ^^^^           ^^^^

        The software allows to load the filter parameters from an ASCII
        file. Only the GZP parametrization is allowed in this case. See
        the file .../modules/tfl/tfl_data/filter_data.dat for more informations.

        Because of the modular structure of the package, the data input
        rate (in terms of samples per second) is not defined until the
        parameters of the other modules are defined and the project is
        initialized, hence the filter data, like zero or pole
        frequencies, are entered using the sampling frequency
        (w_samp=2*pi/T) as a free parameter.
        As instance the GZP representation can be rewitten as:

                             (s/w_samp+z[0]/w_samp)*...*(s/w_samp+z[nz-1]/w_samp)
    TF(s)=G*(2*pi/T)^(nz-np)*----------------------------------------------------
                             (s/w_samp+p[0]/w_samp)*...*(s/w_samp+p[np-1]/w-samp)

        the values for z[i]/w_samp, p[j]/w_samp and G/T^(nz-np) are
        requested in the GUI.
        In order to help the user in the filter definition, the Bode
        plots and the recursive filter implementation are displayed.

        The gain is always entered as positive values, to simulate the
        effect of a 'negative feedback' select the check-button 'Negative
        Feedback' in the GUI.

     CATEGORY:
           main module's routine

     CALLING SEQUENCE:
           error = tfl(          $
                      inp_com_t, $
                      out_com_t, $
                      par,       $
                      INIT=init, $
                      )

     OUTPUT:
           error: long scalar (error code, see !caos_error var in caos_init.pro).

     INPUTS:
           inp_com_t: structure of type com_t:
                       {data_type  : "com_t",                 $
                        data_status: !caos_data.xxx,           $ see caos_init
                        command    : fltarr(n_actuators),     $ commands to filter
                        pass_mat   : mode -> actuator matrix, $
                        tam_ssap   : actuator -> mode matrix  $
                       }

           par      : vector of parameter structures from tfl_gui:
          { tfl,                      $ ; structure named TFL
            module     : module,      $ ; standard module description structure
            max_n_coeff: max_n_coeff, $ ; max number of allowed coeffs
            s_const    : s_const,     $ ; constant factor of the s-domain filt. tf
            n_s_zero   : n_s_zero,    $ ; number of zeros of the s-domain filt. tf
            n_s_pole   : n_s_pole,    $ ; number of poles of the s-domain filt. tf
            s_zero     : s_zero,      $ ; zeros of the s-domain filter tf
            s_pole     : s_pole,      $ ; poles of the s-domain filter tf
            type       : type,        $ ; filter type, usefull for the gui
            method     : method,      $ ; chosen method index from the method list
            double     : double       $ ; coeffs precision: 0B single, 1B double
          }

     INCLUDED OUTPUTS:
           out_com_t: structure of type com_t.
                       {data_type  : "com_t",                 $
                        data_status: !caos_data.xxx,          $ see caos_init
                        command    : fltarr(n_actuators),     $ filtered commands
                        pass_mat   : mode -> actuator matrix, $
                        tam_ssap   : actuator -> mode matrix  $
                       }

     KEYWORD PARAMETERS:
           INIT: named variable undefined or containing a scalar
                 when tfl is called for the first time. As output
                 the named variable will contain
                 a structure of the initialization data. For the
                 following calls of tfl, the keyword INIT has to
                 be set to the structure returned by the first call.

     COMMON BLOCKS:
           common caos_block, tot_iter, this_iter

           tot_iter   : int scalar. Total number of iteration during the
                        simulation run.
           this_iter  : int scalar. Number of the current iteration. It is
                        defined only while status eq !caos_status.run.
                        (this_iter >= 1).

     SIDE EFFECTS:
           none.

     RESTRICTIONS:
           none.

     CALLED NON-IDL FUNCTIONS:
           tustin.pro
           gzp2pid.pro
           pid2gzp.pro
           plot_amp.pro
           plot_phase.pro
           poly_mult.pro
           poly_pow.pro
           poly_sum.pro
           recursive_sf.pro
           tustin.pro
           zero2coeff.pro

     ROUTINE MODIFICATION HISTORY:
           program written: march 1999,
                            Armando Riccardi (OAA) [riccardi@arcetri.astro.it].
           modifications  : Nov 1999,
                            B. Femenia   (OAA) [bfemenia@arcetri.astro.it]
                           -adapted to new version CAOS (v 2.0).
                          : january 2003,
                            Marcel Carbillet (OAA) [marcel@arcetri.astro.it]:
                           -use of variable "calibration" eliminited for version 4.0
                            of the whole CAOS Software System.
                          : february 2004,
                            Marcel Carbillet (OAA) [marcel@arcetri.astro.it]:
                           -help upgraded.
                          : may 2016,
                            Marcel Carbillet (Lagrange) [marcel.carbillet@unice.fr]:
                           -adapted to Soft. Pack. CAOS 7.0.

     MODULE MODIFICATION HISTORY:
           module written : Armando Riccardi (OAA) [riccardi@arcetri.astro.it].
           modifications  : for version 2.0,
                            B. Femenia   (OAA) [bfemenia@arcetri.astro.it]
                           -adapted to new version CAOS (v 2.0).
                          : for version 4.0,
                            Marcel Carbillet (OAA) [marcel@arcetri.astro.it]:
                           -no more use of the common variable "calibration" and
                            the tag "calib" (structure "info") for version 4.0 of
                            the whole CAOS Software System.
                          : for version 7.0,
                            Marcel Carbillet (Lagrange) [marcel.carbillet@unice.fr]:
                           -adapted.

(See tfl/tfl.pro)

## TTM

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           ttm

     PURPOSE:
           TTM executes the simulation for the Tip-Tilt Mirror (TTS) module.  This
           module receives a wavefront and a command from a Tip-Tilt Sensor (TTS)
           so that the mirror is tilted by a given ammount in order to substract to
           the input wavefront the previously measured atmospheric-induced
           tip-tilt. At this stage, this module symply substracts a tilted plane to
           a wavefront. This corresponds to an ideal Tip-Tilt Mirror since no
           dynamic behaviour has been considered within the module. Nevertheless,
           the user can simulate any dynamic behaviour with the TFL module.

     CATEGORY:
           Module

     CALLING SEQUENCE:
           err = ttm(inp_wfp_t, inp_com_t, out_wfp_t1, out_wfp_t2, par, INIT= init)

     OUTPUT:
           error: long scalar (error code, see !caos_error var in caos_init.pro).

     INPUTS:
           inp_wfp_t : structure of type wfp_t containing the incident wavefront on
                       the mirror.
           inp_com_t : structure of type com_t. This structure contains the set of
                       commands sent by the reconstructor (i.e TCE) If undefined (at
                       the first time), the commands are set to 0.
           par       : parameters structure from ttm_gui. At time of writing this
                       version it was unnecessary to pass any science parameter via
                       GUI, but it is left for completeness. Therefore, in this
                       version the par structure associated to TTM only contains
                       tags associated to the management of program, but no
                       parameter relevant to scientific program.

     INCLUDED OUTPUTS:
           out_wfp_t1: structure of type wfp_t containing the original incident
                       wavefront on the mirror but with a tilted plane substracted.

           out_wfp_t2: struct of type wfp_t containing the correction (in this case
                       a tilted plane) applied to incoming wavefront.

     KEYWORD PARAMETERS:
           INIT     : named variable undefined or containing a scalar when ttm is
                      called for the first time. As output the named variable will
                      contain a structure of the initialization data. For the
                      following calls of ttm, the keyword INIT has to be set to the
                      structure returned by the first call.

     COMMON BLOCKS:
           common caos_block, tot_iter, this_iter

           tot_iter   : int scalar. Total number of iteration during the
                        simulation run.
           this_iter  : int scalar. Number of the current iteration. It is
                        defined only while status eq !caos_status.run.
                        (this_iter >= 1).

     SIDE EFFECTS:
           None.

     RESTRICTIONS:
           No dynamic behaviour considerations. PArticular behaviours due to the
           dynamical characteristics of a real mirror can still be simulated
           through proper design of filter response with TFL module.

     EXAMPLE:
           Write here an example!

     ROUTINE MODIFICATION HISTORY:
           program written: Nov 1998,
                            B. Femenia   (OAA) [bfemenia@arcetri.astro.it]
                            M. Carbillet (OAA) [marcel@arcetri.astro.it]
           modifications  : january 2003,
                            Marcel Carbillet (OAA) [marcel@arcetri.astro.it]:
                           -use of variable "calibration" eliminited for version 4.0
                            of the whole CAOS Software System.
                          : may 2016,
                            Marcel Carbillet (Lagrange) [marcel.carbillet@unice.fr]:
                           -adapted to Soft. Pack. CAOS 7.0.

     MODULE MODIFICATION HISTORY:
           module written : Nov 1998,
                            B. Femenia   (OAA) [bfemenia@arcetri.astro.it]
                            M. Carbillet (OAA) [marcel@arcetri.astro.it]
           modifications  : for version 1.0,
                            B. Femenia (OAA) [bfemenia@arcetri.astro.it]
                           -rewritten to match general style and requirements on
                            how to manage initialization process, calibration
                            procedure and time management according to released
                            templates on Feb 1999.
                          : for version 2.0,
                            B. Femenia   (OAA) [bfemenia@arcetri.astro.it]
                           -adapted to new version CAOS (v 2.0).
                          : for version ?.? (1999),
                            B. Femenia   (OAA) [bfemenia@arcetri.astro.it]
                           -a second output containing the CORRECTION is added
                            in order to allow the use of COMBINER feature.
                          : for version 4.0,
                            Marcel Carbillet (OAA) [marcel@arcetri.astro.it]:
                           -no more use of the common variable "calibration" and
                            the tag "calib" (structure "info") for version 4.0 of
                            the whole CAOS Software System.
                          : for version 7.0,
                            Marcel Carbillet (Lagrange) [marcel.carbillet@unice.fr]:
                           -adapted.

(See ttm/ttm.pro)

## WFA

[Previous Routine] [List of Routines]

     NAME:
           wfa

     ROUTINE'S PURPOSE:
           WFA manages the simulation for the WaveFront Adding (WFA) module,
           that is:
           1-call the module's initialisation routine wfa_init at the first
             iteration of the simulation project
           2-call the module's program routine wfa_prog otherwise.

     MODULE'S PURPOSE:
           WFA receives two wavefronts as inputs and returns their sum/difference
           according to weights supplied by user. This module has been developed to
           check performance of the software and does not care about
           intensities. Accordingly, the output is assigned the same values of
           n_phot and background (see doc on gpr for info on these tags) of the
           first input, unless WFA is used as a "duplicator" of correction in which
           case it detects which input is the correction and which one is the wf
           to be corrected.

     CATEGORY:
           main module's routine

     CALLING SEQUENCE:
           err = wfa(inp_wfp_t1, inp_wfp_t2, out_wfp_t, par)

     OUTPUT:
           error:long scalar (error code, see !caos_error var in caos_init.pro).

     INPUTS:
           inp_wfp_t1:incident wavefront. (Bottom input in Application builder)

           inp_wfp_t2:incident wavefront. (Top input in Application builder)

           par       :parameters structure from wfa_gui. In addition to the usual
                      tags associated with the overall management of the program,
                      it contains the following tags:

                      par.wb: assigned weight (+1 or -1) to first input (in
                              AppBuilder, bottom box!!)
                      par.wt: assigned weight (+1 or -1) to second input (in
                              AppBuilder, top box!!)

     INCLUDED OUTPUTS:
           out_wfp_t :output wavefront with intensity arbitrarily normalized to 1.

     KEYWORD PARAMETERS:
           None.

     COMMON BLOCKS:
           common caos_block, tot_iter, this_iter

           tot_iter   : total number of iteration during the simulation run.
           this_iter  : current iteration number.

     SIDE EFFECTS:
           None.

     RESTRICTIONS:
           This module does not consider the effect on the intensity as it is not
           intended to simulate interferometry. It's been developed only to allow
           easy and fast visualization of AO effects on wavefronts.

     CALLED NON-IDL FUNCTIONS:
           none.

     MODIFICATION HISTORY:
           program written: April 1999,
                            B. Femenia   (OAA) [bfemenia@arcetri.astro.it]
           modifications  : Dec 1999,
                            B. Femenia   (OAA) [bfemenia@arcetri.astro.it]
                           -adapted to new version CAOS (v 2.0).
                          : january 2003,
                            Marcel Carbillet (OAA) [marcel@arcetri.astro.it]:
                           -use of variable "calibration" eliminited for version 4.0
                            of the whole CAOS Software System.
                          : may 2016,
                            Marcel Carbillet (Lagrange) [marcel.carbillet@unice.fr]:
                           -adapted to Soft. Pack. CAOS 7.0.

     MODULE MODIFICATION HISTORY:
           module written: B. Femenia   (OAA) [bfemenia@arcetri.astro.it]
           modifcations  : for version 2.0,
                           B. Femenia   (OAA) [bfemenia@arcetri.astro.it]
                           -adapted to new version CAOS (v 2.0).
                          : for version 4.0,
                            Marcel Carbillet (OAA) [marcel@arcetri.astro.it]:
                           -no more use of the common variable "calibration" and
                            the tag "calib" (structure "info") for version 4.0 of
                            the whole CAOS Software System.
                          : for version 7.0,
                            Marcel Carbillet (Lagrange) [marcel.carbillet@unice.fr]:
                           -adapted.

(See wfa/wfa.pro)