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)