List of Routines

ADN ANB CBD
CNV DEC FSM
MCD OBJ PEX
PRE RTI

Routine Descriptions

ADN

[Next Routine] [List of Routines]
 NAME:
    ADN

 ROUTINE'S PURPOSE:
    ADN manages the simulation for the ADd Noise (ADN) module,
    that is to call the module's initialization routine (adn_init) at the first
    iteration of the simulation project.

 MODULE'S PURPOSE:
    ADN permits to add photon noise, background noise, read-out noise and
    dark-current noise to an image or a cube of images. ADN allows also to
	 simulate the saturation of the CCD as well as the perturbations due to 
    flat-field and bad-pixels.

 CATEGORY:
    main module's routine

 CALLING SEQUENCE:
    error = adn(inp_img_t, out_img_t, par, INIT=init)

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

 INPUTS:
    inp_img_t: structure of type img_t.
    par      : parameters structure.

 INCLUDED OUTPUTS:
    out_img_t: structure of type "img_t" containing the characteristics of
               the noisy map, the following fields are contained in
               this structure:

out_img_t =                             $
   {                                     $
   data_type  : out_type[0]          , $
   data_status: !caos_data.valid     , $
   image      : noisy_map            , $  ; IMAGE with same resolution as PSF.
   npixel     : inp_img_t.npixel     , $  ; Number of pixels (per subaperture)
   resolution : inp_img_t.resolution , $  ; Pixel size [arcsec/pix]
   lambda     : inp_img_t.lambda     , $  ; Mean detection wavelength [m]
   width      : inp_img_t.width      , $  ; Wavelength band width [m]
   time_integ : inp_img_t.time_integ , $  ; Integration time for each image [s]
   time_delay : 0.                   , $  ; [NOT USED WITHIN AIRY]
   psf        : 0B                   , $  ; this is an image, not a PSF
   background : background           , $  ; the value of the background
   snr        : fltarr(360)          , $  ; [NOT YET EVALUATED]
   header     : PTR_NEW('')            $  ; Header (modified by this procedure)
   }
 *out_img_t.header = header  ;update the pointer

 KEYWORD PARAMETERS:
    INIT: initialization 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:
    adn_add_noise.pro : add the noise (Poisson and Gaussian) in the map
    adn_ccd_sat.pro   : CCD saturation control

 MODULE MODIFICATION HISTORY:
    module written : version beta,
                     Serge  Correia   (OAA) [correia@arcetri.astro.it],
                     Marcel Carbillet (OAA) [marcel@arcetri.astro.it].

 ROUTINE MODIFICATION HISTORY:
    routine written: june 2000,
                     Serge Correia (OAA) [correia@arcetri.astro.it].
    modifications  : july 2000,
                     Marcel Carbillet (OAA) [marcel@arcetri.astro.it]:
                    -help completed.
                    -call to adn_prog eliminated (useless).
                   : january 2003,
                     Marcel Carbillet (OAA) [marcel@arcetri.astro.it]:
                    -use of variable "calibration" eliminited for version 4.0
                     of the whole system CAOS.


 MODULE MODIFICATION HISTORY:
    module written : Serge Correia (OAA) [correia@arcetri.astro.it].
    modifications  : for version 1.0,
                     Marcel Carbillet (OAA) [marcel@arcetri.astro.it]:
                    -help completed.
                    -call to adn_prog eliminated (useless).
                   : for version 2.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.
                   : march 2004,
                     Barbara Anconelli (DISI) [anconelli@disi.unige.it]:
                    -now having control over initial seed when generating
		                read-out noise.
                   : april 2004,
                     Barbara Anconelli (DISI) [anconelli@disi.unige.it]:
                    -added possibility of choice between three type of noise:
                     poisson, read-out and dark-current
                    -having control over initial seed when generating also
                     poisson noise and dark-current noise.
                   : october 2005,
                     Gabriele Desidera' (DISI) [desidera@disi.unige.it]:
                    -use of variable "time_integ" now is active.
                    -fixed bug in calculation of dark_current noise
                   : april 2006,
                     Andrea La Camera (DISI) [lacamera@disi.unige.it]:
                    -CCD saturation and full-well capacity parameters added in 
                     order to simulate the saturation of the CCD.
                    -function 'add_ccd_sat.pro' added.
                   : for version 5.0,
                     Andrea La Camera (DISI) [lacamera@disi.unige.it]:
                    -added possibility to simulate multi-frame images.
                     Multi-frame images cannot be saved (by WFT), but can be 
                     only automatically reduced by using PRE.
                    -DITHERING added: each frame can be shifted in 
                     two different ways: 
                     a) random shifts: the positions will be created within a 
                        circle of given radius;
                     b) user defined shifts: the values are stored into a file 
                        and will be loaded in the ADN_ADD_NOISE procedure. 
                        In this case each line of the file must contain X and 
                        Y shifts, separated by a comma.
                     Dithering can be applied to either each frame or every N
                     frames (N is given by the user).
                    -Added the MASKing of the images.
                    -FLAT-FIELD and BAD-PIXELS perturbations added. 
                   : march 2011,
                     Andrea La Camera (DISI) [lacamera@disi.unige.it]:
                    -added another TAB in the GUI containing the possibility  
                     of clipping negative values after RON and converting the
                     output to an arbitrary IDL data type. 
                    -The function "addnoise.pro" has been integrated 
                     within the routine "adn_add_noise.pro".
                   : February 2012,
                     Andrea La Camera (DISI) [lacamera@disi.unige.it]:
                    -New way to call AIRY_HELP. By using the "online_help" 
                     routine, we resolved a known-issue of the Soft.Pack.
                   : May 2012, 
                     Andrea La Camera (DIBRIS) [andrea.lacamera@unige.it]: 
                    -small changes in the GUI + changes in
                     "addnoise.pro" routine. 
                   : May 2016,
                     Andrea La Camera (DIBRIS) [andrea.lacamera@unige.it],
                    -The header of the input/output image is kept
                     up-to-date with noise information
                    -background is now an array (from previous
                     modules or a new array). Small changes to the GUI 

(See adn/adn.pro)


ANB

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
    anb

 ROUTINE'S PURPOSE:
    ANB executes the simulation for the ANalysis Binary (ANB) module.

 MODULE'S PURPOSE:
    ANB module performs the astrometric and photometric analysis on a 
    restored binary type object.   

 CATEGORY:
    main module's routine

 CALLING SEQUENCE:
    error = anb(inp_img_t, $
                par,       $
                INIT=init  )

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

 INPUTS:
    inp_img_t: structure of type img_t (image type).
    par      : parameters structure from anb_gui.

 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:
     1-In some cases, namely when the object is a double star of faint
     magnitude the MMM algorithm can return an incorrect value (0) for
     the background evaluation.
     For this kind of cases it is recommended to use an alternative method
     for background evaluation.

     2- The background estimation done by PRE module can be contaminated
     by the object if the extension
     of the object is a large fraction of the image frame. The estimated mean value
     of the sky background and especially its rms value are then biased.
     A simple solution is to compute directly the mean background using
     the routine n_phot (found in .../caos/lib/, help at the IDL/CAOS prompt with
     the command <>). For example, with a 0.01 arcsec pixel
     size, a telescope collecting surface of 10 m^2, an integration time of 100 s
     and an overall efficiency of 0.3, the K band mean background (per pixel) is:
     
        0.3*(n_phot(0.,BAND="K",DELTA_T=100.,SURF=10.))[1]*0.01^2
     
     Then it is necessary to enter by hand the value found within the PRE module GUI
     (using the option "consider a user-defined background").

 CALLED NON-IDL FUNCTIONS:
       ap_phot_cent.pro
       ap_phot_cent_comp.pro
       detect_binary_star.pro
       legend_windt_m.pro
       make_graph_bin.pro
       model_binary.pro

 ROUTINE MODIFICATION HISTORY:
    routine written: october 2000,
                     Serge Correia (OAA) [marcel@arcetri.astro.it].
    modifications  : february 2003,
                     Marcel Carbillet (OAA) [marcel@arcetri.astro.it]:
                    -use of variable "calibration" eliminited for version 4.0
                     of the whole system CAOS.
                   : may 2011,
                     Marcel Carbillet (Fizeau) [marcel.carbillet@unice.fr]:
                    -help completed.

 MODULE MODIFICATION HISTORY:
    module written : Serge Correia (OAA) [correia@arcetri.astro.it].
    modifications  : for version 2.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 5.0,
                     Marcel Carbillet (Fizeau) [marcel.carbillet@unice.fr]:
                    -GUI resized.
                   : February 2012,
                     Andrea La Camera (DISI) [lacamera@disi.unige.it]:
                    -New way to call AIRY_HELP. By using the "online_help" 
                     routine, we resolved a known-issue of the Soft.Pack.
                   : April 2013,
                     Andrea La Camera (DIBRIS) [andrea.lacamera@unige.it]:
                    -Some small changes in the GUI (Text and position of 
                     the inputs).
                   : march 2016,
                     Andrea La Camera (DIBRIS) [andrea.lacamera@unige.it]:
                     Added verbosity choice [default = no]

(See anb/anb.pro)


CBD

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
    CBD

 ROUTINE'S PURPOSE:
    CBD manages the simulation for the Constrained Blind (or myopic) 
    Deconvolution (CBD) module, that is:
       1-call the module's initialization routine cbd_init at the first
         iteration of the simulation project,
       2-call the module's program routine cbd_prog.

 MODULE'S PURPOSE:
    CBD performs the deconvolution of a cube of images (i.e. p images
    corresponding to different orientations of the baseline) when
    the user don't have a PSF.
    The module gives back an image and an estimate of the PSF(s) and has in
    input a PSF(s) and an image(s).
    If the user has already an initial estimate of the PSF(s) he can give
    it directly in input; otherwise the module generates an estimate by an
    operation based on the autocorrelation operator on the image supplied
    in input.
    It is possible to obtain these two reconstructions by perform
    alternatively two partial reconstructions, the first one to the image(s)
    and the second one to the PSF(s).
    There are two different methods for image deconvolution and just one
    for PSFs reconstruction. In the first case the user can choose between
    the OS-EM method (see for details: "Application of the OS-EM method to the
    restoration of LBT images", M. Bertero and P. Boccacci, A&AS 144,
    May 2000, 181-186) and the LR-EM method.
    CBD fits the PSFs dimensions to the images dimensions, if they do not
    match, through zero-padding.
    The background evaluation performed by PRE module is used to restore
    the object with a correct sky-value, while the reconstructed PSFs are 
    managed without background (this is subtracted before the deconvolution 
    process).
    In this version no stopping rule is given. The rates of convergence may
    be different for different types of objects.
    This algorithm is sensible to the number of the iterations that the user 
    set in the reconstruction box of images and PSFs.
    In the case of a point-like stellar object, it is easy to have a good
    estimate of the initial PSFs.
    In the case of diffuse objects (i.e. galaxies) is more difficult to obtain
    a good estimate about the PSFs shape making the autocorrelation of the
    input image and it is recommended to supply a different one.

 CATEGORY:
    main module's routine

 CALLING SEQUENCE:
    error = cbd(inp_img_t2, out_psf_t, out_img_t, par, INIT=init)

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

 INPUTS:
    inp_img_t2: structure of type img_t, corresponding to images
    par       : parameters structure.

 INCLUDED OUTPUTS:
    out_psf_t: structure of type "img_t" (with one more feature, the filter 
               to use to maintain in band the same PSFS) containing the 
               characteristics of the deconvolved PSF(s).
               The following fields are contained in this structure:
out_psf_t = 				   $
   {          				   $
   data_type  : out_type[0]            , $
   data_status: !caos_data.valid       , $
   image      : cube2                  , $
   psf        : 1B                     , $    ; This is a PSF
   npixel     : N                      , $    ; Number of pixels (per subaperture)
   resolution : inp_img_t2.resolution  , $    ; Pixel size [arcsec/pix]
   lambda     : inp_img_t2.lambda      , $    ; Mean detection wavelength [m]
   width      : inp_img_t2.width       , $    ; Wavelength band width [m]
   time_integ : inp_img_t2.time_integ  , $    ; Integration time for each image [s]
   time_delay : inp_img_t2.time_delay  , $    ; [NOT USED WITHIN AIRY]
   background : make_array(N,N,P)      , $ ; the PSF's background is zero
   snr        : inp_img_t2.snr         , $    ; snr
   header     : PTR_NEW('')       $    ;header of the output PSF
   }
*out_psf_t.header = *inp_img_t2.header

    out_img_t: structure of type "img_t" containing the characteristics of
               the deconvolved object. The following fields are contained in this structure:
out_img_t = 				   $
   {          				   $
   data_type  : out_type[0]     	 , $
   data_status: !caos_data.valid	 , $
   image      : cube            	 , $
   psf        : 0B              	 , $   ; This flag indicates that this is a IMAGE
   npixel     : N              	 , $           ; Number of pixels (per subaperture)
   resolution : inp_img_t2.resolution   , $    ; Pixel size [arcsec/pix]
   lambda     : inp_img_t2.lambda       , $    ; Mean detection wavelength [m]
   width      : inp_img_t2.width        , $    ; Wavelength band width [m]
   time_integ : inp_img_t2.time_integ   , $    ; Integration time for each image [s]
   time_delay : inp_img_t2.time_delay   , $    ; [NOT USED WITHIN AIRY]
   background : inp_img_t2.background   , $    ; background
   snr        : inp_img_t2.snr          , $    ; snr
   header     : PTR_NEW('')         $    ; header of the output object
   }
*out_img_t.header=*inp_img_t2.header

 KEYWORD PARAMETERS:
    INIT: initialization data 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:
    -other routine from the folder .../cbd/cbd_gui_lib.

 ROUTINE MODIFICATION HISTORY:
    routine written: May 2005, 
                     Gabriele Desidera' (DISI) [desidera@disi.unige.it].


 MODULE MODIFICATION HISTORY:
    module written : december 2008, 
                     Gabriele Desidera' (DISI) [desidera@disi.unige.it].
    modifications  : for version 5.0,
                     Gabriele Desidera' (DISI) [desidera@disi.unige.it]:
                    -the module (previously called BLI) has been renamed in 
                     CBD after the work done for the paper (+revisions):
                     G. Desiderà, M. Carbillet, "Strehl-constrained iterative
                     blind deconvolution for post-adaptive-optics data", 2009,
                     A&A 507, pp. 1759-1762.
                   : February 2012,
                     Andrea La Camera (DISI) [lacamera@disi.unige.it]:
                    -output's order exchanged: (WAS) top=PSF, bottom=OBJ;
                     (NOW IS) top=OBJ, bottom=PSF, as it is in the whole 
                     Soft.Pack.AIRY
                    -New way to call AIRY_HELP. By using the "online_help" 
                     routine, we resolved a known-issue of the Soft.Pack.
                   : February 2014, 
                     Andrea La Camera (DIBRIS) [andrea.lacamera@unige.it],
                    -GUI rewritten with TAB, several optional outputs
                     added.  
                   : March 2015,
                    -Add another method of Blind Deconvolution, based on the 
                     paper cited in the file "AIRYSoftPack6.1_From6.0to6.1.txt"
                    -Some changes on the GUI (internal tabs added and
                     several input fields moved here and there).
                   : May 2016,
                     Andrea La Camera (DIBRIS) [andrea.lacamera@unige.it],
                    -RON and GAIN have been moved to PRE (and the
                     values are read into the header)
                    -addded save_obj_fun and save_obj_fun_file
                    -the header is saved in the output structure and
                     eventually modified with the deconvolution parameters.
                    -added optional output save: objective function
                   : February 2017,
                     Andrea La Camera (DIBRIS) [andrea.lacamera@unige.it],
                    - cbd_init.pro debugged

(See cbd/cbd.pro)


CNV

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
    cnv

 ROUTINE'S PURPOSE:
    cnv manages the simulation for the CoNVolution (CNV) module,
    that is to call the module's initialization routine cnv_init at the first
         iteration of the simulation project.

 MODULE'S PURPOSE:
    CNV permits to make a convolution between a 2D (3D) PSFs and an object
    2D (3D) map. The parameters related to the observing conditions (efficiency,
    integration time, telescope surface collecting surface) can be chosen.
    The pixel size of the resulting cube of images is driven by the PSFs pixel
    size, whatever is the object map one. Both the object map and the PSFs
    arrays are by the way put in 2^N (N integer) pixels arrays, if they are
    not originally 2^N arrays. The maximum size for this last operation is
    set to 2048 pixels (that corresponds to N=11).

 CATEGORY:
    main module's routine

 CALLING SEQUENCE:
    error = cnv(inp_img_t, inp_src_t, out_img_t, par, INIT=init)

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

 INPUTS:
    inp_img_t: structure of type img_t.
    inp_src_t: structure of type src_t.
    par      : parameters structure.

 INCLUDED OUTPUTS:
    out_img_t: structure of type "img_t" containing the characteristics of
               the convolved map, the following fields are contained in
               this structure:

out_img_t =                         $
{                                   $
   data_type  : out_type[0]         , $
   data_status: !caos_data.valid    , $
   image      : image               , $ ; IMAGE with same resolution as PSF.
   npixel     : nb_pix_opt          , $ ; Number of pixels (per subaperture)
   resolution : inp_img_t.resolution, $ ; Pixel size [arcsec/pix]
   lambda     : lambda[0]           , $ ; Mean detection wavelength [m]
   width      : width[0]            , $ ; Wavelength band width [m]
   time_integ : par.int_time        , $ ; Integration time for each image [s]
   time_delay : 0.                  , $ ; [NOT USED WITHIN AIRY]
   psf        : 0B                  , $ ; IMAGE=1, PSF=0
   background : back_frame          , $ ; sky background array [ph/pixel] 
   snr        : 0.                  , $ ; [NOT YET EVALUATED]
   header     : PTR_NEW('')           $ ; header of the two structures merged
}
*out_img_t.header = header ; update the pointer

 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:
    The object map and the PSFs arrays are put to 2^N (N integer) pixels
    arrays if they are not originally 2^N arrays.
    Doing it the maximum size is set to 2048 pixels (that corresponds to N=11).

 CALLED NON-IDL FUNCTIONS:

 ROUTINE MODIFICATION HISTORY:
    routine written: june 2000,
                     Serge Correia (OAA) [correia@arcetri.astro.it].
    modifications  : july 2000,
                     Marcel Carbillet (OAA) [marcel@arcetri.astro.it]:
                    -help completed.
                    -call to cnv_prog eliminated (useless).
                    -parameters needed for image complete definition now
                     considered (total efficiency, telescope collecting
                     surface, integration time).
                   : february 2003,
                     Marcel Carbillet (OAA) [marcel@arcetri.astro.it]:
                    -use of variable "calibration" eliminited for version 4.0
                     of the whole system CAOS.
                   : december 2003,
                     Marcel Carbillet (OAA) [marcel@arcetri.astro.it]:
                    -help completed.
                   : october 2005,
                     Gabriele Desidera' (DISI) [desidera@disi.unige.it],
                    -use of variable "time_integ" activated for the output structure.

 MODULE MODIFICATION HISTORY:
    module written : version beta,
                     Serge  Correia   (OAA) [correia@arcetri.astro.it],
                     Marcel Carbillet (OAA) [marcel@arcetri.astro.it].
    modifications  : for version 2.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 5.0;
                     Andrea La Camera (DISI) [lacamera@disi.unige.it]:
                    -added the possibility to convolve objects and PSF
                     "many to many" (it was "one to many").
                    -added possibility to simulate multi-frame images.
                     Multi-frame images cannot be saved (by WFT), but
                     only auto-reduced by PRE module.
                   : February 2012,
                     Andrea La Camera (DISI) [lacamera@disi.unige.it]:
                    -New way to call AIRY_HELP. By using the "online_help" 
                     routine, we resolved a known-issue of the Soft.Pack.
                   : May 2016,
                     Andrea La Camera (DIBRIS) [andrea.lacamera@unige.it],
                    -The header of the input/output image is kept
                     up-to-date with convolution information
                    -background is now an array, which dimensions are
                     the same of the input image.

(See cnv/cnv.pro)


DEC

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
    dec

 ROUTINE'S PURPOSE:
    DEC manages the simulation for the image deconvolution (DEC) module,
    that is:
       1-call the module's initialization routine dec_init at the first
         iteration of the simulation project,
       2-call the module's program routine dec_prog.

 MODULE'S PURPOSE:

       DEC performs the deconvolution of a cube of images (i.e. P images
    corresponding to different orientations of the baseline). There are
    five different methods for image deconvolution, according to the noise
    model. For Poisson noise, the Richardson-Lucy (RL) and the Ordered-Subset 
    Expectation Maximization (OSEM) methods are available. Recently
    (from v.6.1) we added the Scaled Gradient Projection (SGP) method
    [7]. It is an optimized method for solving the minimization of the KL
    divergence. 
       As concerns Gaussian noise both the Image Space Reconstruction
    Algorithm (ISRA) and the OS-ISRA are implemented. (see [1] for details).
       
       DEC also allows to reduce the boundary effects in the reconstructed
    image (see [2,8] for details).
       When the object is complex, as a high dynamic range image, a regularized 
    version of the algorithm can give better results. In this cases, eight 
    different regularizations are available in DEC: Tikhonov (0th order), 
    Tikhonov (2nd order, aka Laplacian), Cross-Entropy, Edge Preserving MRF, 
    High Dynamic Range (HDR), Mistral, Hypersurface, and Tikhonov 1st
    order (see [8] for details). Depending on the regularization chosen, 
    one or a couple of parameters control the efficacy of the regularization. 

       For RL and OSEM methods, two accelerated versions of the
    algorithms are also available, following the Biggs and Andrews
    method (see [3,4] for details).

       The background (now an array) evaluation performed by PRE
    module is used to restore the object with a correct sky-value.

       In this new version of DEC up to five different stopping rules are given. 
    Concerning SGP, RL, and OSEM algorithms, five stopping rules are implemented:
    1) Set a total number of iterations and stop the algorithm when this number
       is reached. This is valid for all available methods;
    2) Stop the iterations when the relative L2-norm of the difference between
       the current iteration and the previous one is less than a given tolerance.
       i.e.   || f(k) - f(k-1) ||^2 / || f(k) ||^2 < tol
       where f(k) is the current iteration, f(k-1) the previous one,
       and ||.||^2 the L2-norm (squared) 
    3) Stop the iterations when the total functional is approximately constant, 
       according to a user-defined tolerance. 
       i.e. | J(k) - J(k-1) | / | J(k) | < tol
       where J(k) is the objective function defined as J_0 + beta * J_R, 
       J_0 the kullback-leibler divergence, J_R the regularization
       functional, and beta the regularization parameter (see [8] for
       more information). In the case of no-regularization (beta=0), 
       then J becomes simply J_0.
    4) Stop the iteration when the discrepancy function crosses a
       given tolerance (that should be around 1). This 
       criterion is called discrepancy principle for Poisson data (see [5]).   
    5) Stop the iterations when the relative r.m.s error reaches a minimum 
       value. This stopping rule can be used only in the case of numerical 
       simulations, when the true object is known.
    The first and the last stopping rules are also available for ISRA and 
    OS-ISRA. 

       In DEC we also implemented an algorithm for super-resolving compact objects
    such as a binary system with an angular separation smaller than the angular
    resolution of the telescope. (see [1,6] for details). The method is based on 
    a simple modification of the RL/OSEM (and SGP)  method and in
    general consist of 3 steps: the first one requires a large number
    of RL/OSEM (or SGP) iterations (typically 10^4, smaller numbers
    in the case of SGP), which are used to estimate the domain of the unresolved 
    object; the second one is a RL/OSEM restoration (typically 5000 iterations) 
    initialized with the mask of the domain, as estimated in step 1. These two 
    steps are used to estimate the positions of the two stars while their 
    magnitudes can be obtained in a possible 3rd step by solving a simple 
    least-squares problem. The first two steps are included in DEC. 
    In the second step it is possible to choose, in the GUI, the image and the 
    mask used to initialized the method. The mask is an image with values 0/1. 
    There are 3 kind of masks: the 1st is a mask based on percentage of the 
    image maximum, the 2nd one is a circular mask, and the 3rd is a 
    user-defined mask.

       Finally the discrepancy, the objective function, and - in the 
    simulation case - the restoration error can be also saved as
    ASCII files. 

    References:
    [1] La Camera et al., 2012, "AIRY: a complete tool for the simulation 
        and the reconstruction of astronomical images",
        Proc. SPIE 8445, 84453D 
    [2] Anconelli et al., 2006, "Reduction of boundary effects in multiple 
        image deconvolution with an application to LBT LINC-NIRVANA", 
        A&A 448, 1217–1224.
    [3] Biggs and Andrews, 1997, "Acceleration of iterative image 
        restoration algorithms", Applied Optics 36, 1766. 
    [4] Biggs and Andrews, 1998, "Asymmetric iterative blind deconvolution 
        of multiframe images", Proc. SPIE 3461, 328–338.
    [5] Bertero et al., 2010, "A discrepancy principle for Poisson data",
        Inverse Problems 26, 5004.
    [6] Anconelli et al., 2005, "Restoration of interferometric images. 
        IV. An algorithm for super-resolution of stellar systems", Astronomy 
        and Astrophysics 431, 747–755.
    [7] Bonettini et al, 2009, "A scaled gradient projection
        method for constrained image deblurring", Inverse
        Problems 25, 015002.
    [8] Prato et al, 2016, "Reconstruction of high-dynamic
        range Poisson data with an application to Io imaging",
        Inverse Problems, submitted.
    [9] La Camera et al, 2016, "The Software Package AIRY 7.0:
        new efficient deconvolution methods for post-adaptive
        optics data", Proc. SPIE, in Adaptive Optics Systems V (AS106)

    Please pay attention to the fact that the TOP BOX-INPUT of the module dec
    is supposed to receive images, while the BOTTOM BOX-INPUT of the module
    dec is supposed to receive PSFs.

 CATEGORY:
    main module's routine

 CALLING SEQUENCE:
    error = dec(inp_img_t1, inp_img_t2, out_img_t, par, INIT=init)

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

 INPUTS:
    inp_img_t1: structure of type img_t, corresponding to PSF's
    inp_img_t2: structure of type img_t, corresponding to images
    par       : parameters structure.

 INCLUDED OUTPUTS:
    out_img_t: structure of type "img_t" containing the characteristics of
               the deconvolved object, the following fields are contained in
               this structure:

out_img_t = 				      $
   {          				      $
   data_type  : out_type[0]     	    , $
   data_status: !caos_data.valid	    , $
   image      : img  	                    , $
   psf        : 0B              	    , $ ; This flag indicates that this is a IMAGE
   npixel     : init.NN              	    , $ ; Number of pixels (per subaperture)
   resolution : inp_img_t2.resolution       , $ ; Pixel size [arcsec/pix]
   lambda     : inp_img_t2.lambda           , $ ; Mean detection wavelength [m]
   width      : inp_img_t2.width            , $ ; Wavelength band width [m]
   time_integ : inp_img_t2.time_integ       , $ ; Integration time for each image [s]
   time_delay : inp_img_t2.time_delay       , $ ; [NOT USED WITHIN AIRY]
   background : inp_img_t2.background       , $ ; background
   snr        : inp_img_t2.snr              , $ ; snr
   header     : PTR_NEW('')                   $ ; header of the output file
   }
*out_img_t.header = *inp_img_t2.header ; update the pointer

 KEYWORD PARAMETERS:
    INIT: initialization data 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:
    -other routine from the folders .../dec/dec_gui_lib 
     and .../dec/dec_lib

 ROUTINE MODIFICATION HISTORY:
    routine written: november 1999, 
                     Massimo Barbati (USG) [massimo@dirac.disi.unige.it].
    modifications  : march 2000,
                     Marcel Carbillet (OAA) [marcel@arcetri.astro.it]:
                    -adapted to dec version of the CAOS structure (v 2.0).
                   : may 2000,
                     Massimo Barbati (USG) [massimo@dirac.disi.unige.it]:
                    -Help form, Restore form.
                    -Variables Names, Comments.
                   : july 2000,
                     Massimo Barbati (USG) [massimo@dirac.disi.unige.it]:
                    -beta version for package AIRY.
                   : july 2000,
                     Marcel Carbillet (OAA) [marcel@arcetri.astro.it]:
                    -help completed + a few minor changes.
                   : Barbara Anconelli (DISI) [anconelli@disi.unige.it]:
                    -help completed.

 MODULE MODIFICATION HISTORY:
    module written : Massimo Barbati (USG) [massimo@dirac.disi.unige.it].
    modifications  : for version 2.0,
                     Barbara Anconelli (DISI) [anconelli@disi.unige.it]:
                    -second output of type "src_t" added.
                    -super-resolution stuff added.
                   : for version 2.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 2.0, 
                     Serge Correia (AIP) [scorreia@aip.de]:
                    -added the possibility to choose between the OS-EM method
                     and the LR/EM method (par.method added). 
                   : for version 2.0,
                     Barbara Anconelli (DISI) [anconelli@disi.unige.it],
                     Marcel Carbillet (OAA) [marcel@arcetri.astro.it]:
                    -"real acquisition" button commented and 2nd output of type
                    "src_t" momentaneously eliminated.
                    -normalization constant "c" from PAR to INIT structure.
                    -background substracted from PSF too now.
                   : for version 3.0,
                     Barbara Anconelli (DISI) [anconelli@disi.unige.it],
                    -added a dec accelerate version of OS-EM method (par.acc 
                     addded)
                    -ISRA method inserted
                    -added regularization for OS-EM method.
                    -visualization of a mask added.
                    -restructuration of interface
                    -choice of differents regularizations type added
                   : for version 4.0,
                     Gabriele Desidera' (DISI) [desidera@disi.unige.it],
                    -use of variable "time_integ" activated for the output structure
                    -added possibility to reduce boundary effect
                   : for version 5.0,
                     Gabriele Desidera' (DISI) [desidera@disi.unige.it],
                    -eliminated variables concerning regularizations with 
                     alpha=0.5 and alpha=1.
                    -image type (img_t) completed (tag "angle" added).                  
                   : may 2011,
                     Andrea La Camera (DISI) [lacamera@disi.unige.it]:
                    -routine debugged.
                   : February 2012,
                     Andrea La Camera (DISI) [lacamera@disi.unige.it]:
                    -New way to call AIRY_HELP. By using the "online_help" 
                     routine, we resolved a known-issue of the Soft.Pack.
                   : April 2012 (for version 6.0),
                     Andrea La Camera (DISI) [lacamera@disi.unige.it]:
                    -module rewritten: new method (OS-ISRA), new regularizations,
                     new accelerations added. Debugging of existing algorithms.
                     Old regularizations and old accelerations have been removed. 
                   : April 2013,
                     Andrea La Camera (DIBRIS) [andrea.lacamera@unige.it],
                    -added gain_ron parameter (gain of the detector, in order to 
                     convert RON from electrons/pixel to ADU/pixel);
                    -added SGP algorithm. Also added the
                     "deconvolve_sgp" sub-routine.
                   : November 2013,
                     Marcel Carbillet (Lagrange) [marcel.carbillet@unice.fr],
                    -1D case debugged (NN=N before right definition of N).
                   : December 2013,
                     Andrea La Camera (DIBRIS) [andrea.lacamera@unige.it],
                    -1D case added (debugged) for SGP method.
                   : May 2016,
                     Andrea La Camera (DIBRIS) [andrea.lacamera@unige.it],
                    -background is now an array (from previous modules)
                    -two new regularizations added:
                     HYPERSURFACE and TIKHONOV 1st ORDER
                    -all the 8 regularizations are available for SGP now
                     (i.e. they are available for ALL methods).
                    -added optional output save: objective function
                    -GUI debugged (small changes on text and
                     displacement of the widgets)
                    -stopping rules modified (same rules for RL,OSEM,SGP)
                    -The header of the input/output image is kept
                     up-to-date with deconvolution information
                   : July 2016,
                     Andrea La Camera (DIBRIS) [andrea.lacamera@unige.it],
                    -bug correction on the GUI (for regularization HS)
                   : July 2017,
                     Andrea La Camera (DIBRIS) [andrea.lacamera@unige.it],
                    -if a stopping rule is satisfied, the variable "last_iter" is 
                     used for storing current iteration, next "this_iter" is set to the 
                     total iteration number, and then "tot_iter" is updated with 
                     the current iteration number (i.e the very last iteration).  

(See dec/dec.pro)


FSM

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
    fsm

 ROUTINE'S PURPOSE:
    FSM executes the simulation for the Find Stars Module (FSM) module.

 MODULE'S PURPOSE:
    FSM module find stars and perform the astrometric and photometric analysis, 
    given a detection threshold expressed in RMS background (like in PRE module 
    the MMM algorithm is used for background evaluation, unless it fails in which 
    case the border of the frame is used to compute this value).
    A final display, in square-root scale, is given with the found stars encircled, 
    as well as the listing of the stars location and aperture photometry.

 CATEGORY:
    main module's routine

 CALLING SEQUENCE:
    error = fsm(inp_img_t, $
                par,       $
                INIT=init  )

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

 INPUTS:
    inp_img_t: structure of type img_t (image type).
    par      : parameters structure from fsm_gui.

 KEYWORD PARAMETERS:
    INIT: initialization 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:
     1-In some cases, namely when the object is a double star of faint
     magnitude the MMM algorithm can return an incorrect value (0) for
     the background evaluation.
     For this kind of cases it is recommended to use an alternative method
     for background evaluation.

     2- The background estimation done by PRE module can be contaminated
     by the object if the extension
     of the object is a large fraction of the image frame. The estimated mean value
     of the sky background and especially its rms value are then biased.
     A simple solution is to compute directly the mean background using
     the routine n_phot (found in .../caos/lib/, help at the IDL/CAOS prompt with
     the command <>). For example, with a 0.01 arcsec pixel
     size, a telescope collecting surface of 10 m^2, an integration time of 100 s
     and an overall efficiency of 0.3, the K band mean background (per pixel) is:
     
        0.3*(n_phot(0.,BAND="K",DELTA_T=100.,SURF=10.))[1]*0.01^2
     
     Then it is necessary to enter by hand the value found within the PRE module GUI
     (using the option "consider a user-defined background").

 CALLED NON-IDL FUNCTIONS:
       amas_phot_m.pro
       astrolib_find.pro
       astrolib_find_module.pro

 ROUTINE MODIFICATION HISTORY:
    routine written: october 2000,
                     Serge Correia (OAA) [correia@arcetri.astro.it].
    modifications  : february 2003,
                     Marcel Carbillet (OAA) [marcel@arcetri.astro.it]:
                    -use of variable "calibration" eliminited for version 4.0
                     of the whole system CAOS.
                   : june 2003,
                     Serge Correia (AIP) [scorreia@aip.de]:
                    -status common variable eliminated.
                   : december 2003,
                     Marcel Carbillet (OAA) [marcel@arcetri.astro.it]:
                    -help completed.
                   : may 2011,
                     Marcel Carbillet (Fizeau) [marcel.carbillet@unice.fr]:
                    -help completed.

 MODULE MODIFICATION HISTORY:
    module written : Serge Correia (OAA) [correia@arcetri.astro.it].
    modifications  : for version 2.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.
                   : February 2012,
                     Andrea La Camera (DISI) [lacamera@disi.unige.it]:
                    -New way to call AIRY_HELP. By using the "online_help" 
                     routine, we resolved a known-issue of the Soft.Pack.

(See fsm/fsm.pro)


MCD

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
    mcd

 ROUTINE'S PURPOSE:
    MCD manages the simulation for the image mcdonvolution (MCD) module,
    that is:
       1-call the module's initialization routine mcd_init at the first
         iteration of the simulation project,
       2-call the module's program routine mcd_prog.

 MODULE'S PURPOSE:

       MCD performs the deconvolution of high dynamic range images
    [1,2,3,4]. The module assumes that the unknown object $\mathbf{f}$ 
    is the sum of two components: the point-like part f_P containing
    the bright sources of the object superimposed on the extended and
    smooth part f_E. Moreover MCD assumes to know the positions of
    the bright sources, i.e. the user must provide a mask M_P which
    is 1 in the pixels of the sources and 0 elsewhere. Alternatively,
    the user can set the mask to 1 in small regions around the known 
    positions. 

    References:
    [1] A. La Camera et al., SPIE Proc. 8455, 84553D (2012).
    [2] A. La Camera et al., PASP 126,(936), 180 (2014).
    [3] M. Prato et al., Inverse Problems (submitted), (2016)
    [4] A. La Camera et al., SPIE Proc. 9909-297 (2016)

    Please pay attention to the fact that the TOP BOX-INPUT of the module mcd
    is supposed to receive images, while the BOTTOM BOX-INPUT of the module
    mcd is supposed to receive PSFs. 
    Concerning the output, the TOP BOX-OUTPUT is for the point-like
    component, while the BOTTOM BOX-OUTPUT is for the diffuse one.

 CATEGORY:
    main module's routine

 CALLING SEQUENCE:
    error = mcd(inp_img_t1, inp_img_t2, out_img_tE, out_img_tP, par, INIT=init)

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

 INPUTS:
    inp_img_t1: structure of type img_t, corresponding to PSF's
    inp_img_t2: structure of type img_t, corresponding to images
    par       : parameters structure.

 INCLUDED OUTPUTS:
    out_img_tE: structure of type "img_t" containing the characteristics of
                the deconvolved object (DIFFUSE COMPONENT), the following 
                fields are contained in this structure:
; out_img_tE = 				      $
;    {          				      $
;    data_type  : out_type[0]     	    , $
;    data_status: !caos_data.valid	    , $
;    image      : img  	                    , $
;    psf        : 0B              	    , $ ; This flag indicates that this is a IMAGE
;    npixel     : init.NN              	    , $ ; Number of pixels (per subaperture)
;    resolution : inp_img_t2.resolution       , $ ; Pixel size [arcsec/pix]
;    lambda     : inp_img_t2.lambda           , $ ; Mean detection wavelength [m]
;    width      : inp_img_t2.width            , $ ; Wavelength band width [m]
;    time_integ : inp_img_t2.time_integ       , $ ; Integration time for each image [s]
;    time_delay : inp_img_t2.time_delay       , $ ; [NOT USED WITHIN AIRY]
;    background : inp_img_t2.background       , $ ; background
;    snr        : inp_img_t2.snr              , $ ; snr
;    header     : PTR_NEW('')                 $   ; header of the output file
;    }
; *out_img_tE.header = *inp_img_t2.header

    out_img_tP: structure of type "img_t" containing the characteristics of
                the deconvolved object (POINT-LIKE COMPONENT), the following 
                fields are contained in this structure:
; out_img_tP = 				      $
;    {          				      $
;    data_type  : out_type[0]     	    , $
;    data_status: !caos_data.valid	    , $
;    image      : img  	                    , $
;    psf        : 0B              	    , $ ; This flag indicates that this is a IMAGE
;    npixel     : init.NN              	    , $ ; Number of pixels (per subaperture)
;    resolution : inp_img_t2.resolution       , $ ; Pixel size [arcsec/pix]
;    lambda     : inp_img_t2.lambda           , $ ; Mean detection wavelength [m]
;    width      : inp_img_t2.width            , $ ; Wavelength band width [m]
;    time_integ : inp_img_t2.time_integ       , $ ; Integration time for each image [s]
;    time_delay : inp_img_t2.time_delay       , $ ; [NOT USED WITHIN AIRY]
;    background : inp_img_t2.background       , $ ; background
;    snr        : inp_img_t2.snr              , $ ; snr
;    header     : PTR_NEW('')                 $   ; header of the output file
;    }
; *out_img_tP.header = *inp_img_t2.header

 KEYWORD PARAMETERS:
    INIT: initialization data 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:
    -other routine from the folder ./mcd_lib

 ROUTINE MODIFICATION HISTORY:
    routine written: June 2016, 
                     Andrea La Camera (DIBRIS) [andrea.lacamera@unige.it].
    modifications  : 

 MODULE MODIFICATION HISTORY:
    module written : Andrea La Camera (DIBRIS) [andrea.lacamera@unige.it].
    modifications  : 
                   : July 2017,
                     Andrea La Camera (DIBRIS) [andrea.lacamera@unige.it],
                    -if a stopping rule is satisfied, the variable "last_iter" is 
                     used for storing current iteration, next "this_iter" is set to the 
                     total iteration number, and then "tot_iter" is updated with 
                     the current iteration number (i.e the very last iteration).  
                    -added common block (called parameters_mcd) to routines
                     mcd_init and mcd_prog in order to correctly save the parameter 
                     "par.delta" (delta_ori) in header. (for future reference: 
                     this can be used for any other parameter)

(See mcd/mcd.pro)


OBJ

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
    obj

 ROUTINE'S PURPOSE:
    OBJ manages the simulation for the OBJect (OBJ) module,
    that is:
      1-call the module's initialization routine obj_init.pro at the first
        iteration of the project
      2-call the module's program routine obj_prog.pro otherwise.

 MODULE'S PURPOSE:
    OBJ permits to define map of different types of astronomical objects as 
    a target for observation and/or subsequent image reconstruction/deconvolution.
    
    Current object types are: single star, binary object, open cluster, 
    planetary nebulae, supernovae remnant, spiral galaxy, Young Stellar Objects (YSOs), 
    stellar surface and user-defined.

    For each object type the map is defined by its dimension [npixel] and pixel size. 

    In particular, some remarks concerning the definition of some objects are the 
    following : 
    
    Single star : pixel located at [npixel/2,npixel/2] containing all the flux 
                  (i.e. unresolved star or point source). 
                  One may pay attention to the fact that such a definition will 
                  creates artifacts if one use PSFs (for both the convolution/
                  modelization and deconvolution) which are centered on 
                  [npixel-1/2,npixel-1/2]. 
                  A work around is to use a dirac map (pixel at [0,0] set to 1, 
                  0 elsewhere) within the user-defined object type. 
    
    Binary object : Formed by two point-source stars for which the barycenter 
                    (not photocenter) is located in [npixel/2,npixel/2]. 
                    In order to center each component on a pixel, the separation
                    and position angle may vary slightly from the one set by 
                    user in the GUI. A warning appears if such a variation is 
                    more than 1%. 

 CATEGORY:
    main module's routine

 CALLING SEQUENCE:
    error = obj(out_obj_t, par, INIT=init)

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

 INPUTS:
    none.

 INCLUDED OUTPUTS:
    out_obj_t: structure of type "src_t" containing the characteristics of
               the selected source, the following fields are contained in
               this structure:
out_obj_t =                       $
   {                              $
   data_type  : info.out_type[0], $
   data_status: !caos_data.valid, $
   off_axis   : init.off_axis,    $
   pos_ang    : init.pos_ang,     $
   dist_z     : init.dist_z,      $
   map        : init.map,         $
   scale_xy   : init.scale_xy,    $
   coord      : init.coord,       $
   scale_z    : init.scale_z,     $
   n_phot     : init.n_phot,      $
   background : init.background,  $
   lambda     : init.lambda,      $
   width      : init.width,       $
   constant   : init.constant,    $
   header     : PTR_NEW('')       $
   }
*out_obj_t.header = header  ; update the pointer

 KEYWORD PARAMETERS:
    INIT: named variable undefined or containing a scalar when obj is
          called for the first time. As output the named variable will
          contain a structure of the initialization data. For the following
          calls of obj, 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:
    The "Object total magnitude" field within the sub-GUIs "YSOs"
    and "Spiral galaxy" remains to the original value although it has been changed
    and the whole set of parameters was saved before.
    This is just a display problem, since the change of this value is effectively
    taken into account (as it can be seen at the IDL/CAOS prompt line).

 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).
    -other routines from the astrolib/astron IDL library
    -other routines from the folder .../obj/obj_lib
                     and the folder .../obj/obj_gui_lib

 ROUTINE MODIFICATION HISTORY:
    program written: may 2000,
                     Serge Correia (OAA) [correia@arcetri.astro.it].
    modifications  : july 2000,
                     Marcel Carbillet (OAA) [marcel@arcetri.astro.it]:
                    -help completed.
                   : february 2003,
                     Marcel Carbillet (OAA) [marcel@arcetri.astro.it]:
                    -use of variable "calibration" eliminited for version 4.0
                     of the whole system CAOS.
                    -call to obj_prog eliminated (useless).
                   : november 2003,
                     Serge Correia (AIP) [scorreia@aip.de]:
                    -help updated.

 MODULE MODIFICATION HISTORY:
    program written: version beta,
                     Serge Correia (OAA) [correia@arcetri.astro.it].
                   : for version 2.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.
                    -obj_prog eliminated since it was irrelevant.
                   : for version 2.0 too,
                     Serge Correia (AIP) [scorreia@aip.de]:
                    -object type single star added.
                    -help updated.
                   : for version 5.0,
                     Andrea La Camera (DISI) [lacamera@disi.unige.it]:
                    -flux constants are now "float" instead of "int",
                    -object type (obj_t) completed (tag angle added),
                    -modeling of elliptical disk, gaussian and stellar surface debugged.
                   : February 2012,
                     Andrea La Camera (DISI) [lacamera@disi.unige.it]:
                    -New sub-GUIs for Planetary Nebula, SNR, Spiral galaxy, YSO, 
                     and user-defined objects. 
                    -Bug fixed in parameter restoring procedure (esp. Planetary 
                     nebula and SNR).
                    -Small changes in the text of the GUI.
                    -New way to call AIRY_HELP. By using the "online_help" 
                     routine, we resolved a known-issue of the Soft.Pack.
                   : May 2016,
                     Andrea La Camera (DIBRIS) [andrea.lacamera@unige.it],
                    -keywords added to the header (that is now created
                     whether the map is saved or not), most commons are:
                     OBJECT, BAND, and PIX_SIZE. All the keywords are
                     described in the FitsHeader_Keywords_definition.txt file. 

(See obj/obj.pro)


PEX

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
    pex

 ROUTINE'S PURPOSE:
    pex manages the simulation for the PEX module, that is to call 
    the module's initialization routine pex_init at the first iteration 
    of the simulation project.

 MODULE'S PURPOSE:
    PEX performs PSF extrapolation from a cube of images (or from a single 
    image). The extraction can be done either when project is "set up" (when 
    parameters of the modules are chosen and saved) or when project runs.
    This operation is divided between PEX_OPEN_GUI and PEX_INIT procedures. 
    PEX_OPEN_GUI: users can load the image, set up scale, zoom, etc., 
             then they can select one or more star with a simple 
             point&click operation, and also select a suitable 
             'radius of extraction' (R) and the value of the beta parameter.
             Users have to complete the information about PSF 
             (pixel-size, band, etc.).
    PEX_INIT: PSF is extracted by following steps:
             For each selected star,
             - centroid of the star is computed and its position is shifted 
               to the center of the image with a sub-pixel precision;
             - a domain of size 2R x 2R is extracted from the central region 
               (this image will be denoted by H);
             - Moffat extrapolation of H(n) (where n=[n1,n2] is the multi-index 
               characterizing the pixels of the image) is executed by following 
               sub-steps:
             -- a first estimation of background is performed with a bilinear 
                function: B(n) = a0 + a1*n1 + a2*n2 
             -- the image H - a1*n1 - a2*n2 is fitted with a circular 
                symmetric Moffat function:
                                      b1
                M0(r) = b0 + -------------------    where r = sqrt(n1^2 + n2^2)
                             (1 + r^2 / b2^2)^beta
             -- the estimated values of the parameters ai and bi are used as 
                initial guesses for a least-squares best-fitting of H(n) with  
                a rotated elliptical Moffat function superimposed with a 
                linear varying background:
	 	                                                   c3
                M(n) = c0 + c1*n1 + c2*n2 + -----------------------------------
                                             (1 + (n1'/c4)^2 + (n2'/c5)^2)^beta
                where n1'=n1*cos(q) + n2*sin(q) and n2'=-n1*sin(q) + n2*cos(q).
                The value of b2 is the initial guess for both c4 and c5, 
                while the initial guess of the rotation angle q in zero.
             -- the extracted image H(n) is merged into the sampled function 
                M(n) defined on the full image and the linearly background is 
                subtracted and the result is normalized to unit volume.
             If several stars are selected in the same image, the median of 
             all the results of previous procedure is computed and this is 
             normalized again to unit volume.

 CATEGORY:
    main module's routine

 CALLING SEQUENCE:
    error = pex(out_img_t, par)

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

 INCLUDED OUTPUTS:
    out_img_t: structure of type "img_t" containing the extracted PSF 
               array, the following fields are contained in
               this structure:
out_img_t =                           $
   {                                  $
   data_type  : out_type[0],          $
   data_status: !caos_data.valid,     $
   image      : image,                $ ; image/psf data cube
   npixel     : _N_out,               $ ; number of pixels
   resolution : par.resolution,       $ ; Pixel size [arcsec/px]
   lambda     : par.lambda,           $ ; Mean detection wavelength [m]
   width      : par.width,            $ ; Wavelength band width [m]
   time_integ : int_time,             $ ; time is zero
   time_delay : 0.,                   $ ; [NOT USED WITHIN AIRY]
   psf        : par.psf,              $ ; IT'S A PSF!
   background : background,           $ ; the PSF's background is zero!
   snr        : fltarr(360),          $ ; [NOT YET EVALUATED]
   header     : PTR_NEW('')           $ ; header of the output
   }
*out_img_t.header = header ; update the pointer

 OUTPUT IMAGE = PSF EXTRACTED

 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:
 PEX_APPEND, PEX_REMOVE, PEX_CIRCLE (called by PEX_GUI, see PEX_GUI_LIB dir)
 PEX_PSF_EXTRAPOLATION (called by PEX_INIT, see PEX_LIB dir)
 MPFIT2DFUN, MPFIT, MPFIT2DPEAK (called by PSF_EXTRAPOLATION - 
     routines written by Craig B. Markwardt, see each file *.pro 
     in PEX_LIB directory for details)
 PEX_CIRCULAR_MASK (called by PEX_PSF_EXTRAPOLATION, see PEX_LIB directory)

 ROUTINE MODIFICATION HISTORY:
    routine written: January 2007,
                     Andrea La Camera (DISI) [lacamera@disi.unige.it].
    modifications  : 

 MODULE MODIFICATION HISTORY:
    module written : Andrea La Camera (DISI) [lacamera@disi.unige.it].
    modifications  
       : January 2007,
         Andrea La Camera (DISI) [lacamera@disi.unige.it]:	
        -PEX module is projected to be used in case of Space-Variant PSF 
         extraction, by splitting the image into severals domains and 
         extracting the PSF from each domain. 
         This operation is NOT IMPLEMENTED YET, however data structures 
         (esp. xsave, ysave and nb_click arrays) include a "domain" 
         subdivision of the image.
         (In case of Space-Invariant PSF, the image coincides with the 
         unique domain).
         PLEASE DON'T DELETE ANY COMMENTED (three ";") LINE.
       : October 2008,
         Andrea La Camera (DISI) [lacamera@disi.unige.it]:
        -Added the possibility to extract the PSF when project runs, LPX_GUI
         now is a sort of "before-gui". A new procedure called LPX_OPEN_GUI has
         been created for managing the Graphical User Interface.        
       : February 2011, 
         Andrea La Camera (DISI) [lacamera@disi.unige.it]:	
        -routine debugged. Domains deleted (not really used) 
       : December 2011,
         Andrea La Camera (DISI) [lacamera@disi.unige.it]:
        -file "find_dim.pro" has been deleted [not really used]
        -files "circular_mask.pro", "psf_extrapolation.pro", "append.pro",
         "remove.pro", and "circle.pro" have been renamed by adding the prefix
         'pex_' to each filename. Apt changes to the functions/procedures.
       : February 2012,
         Andrea La Camera (DISI) [lacamera@disi.unige.it]:
        -New way to call AIRY_HELP. By using the "online_help" 
         routine, we resolved a known-issue of the Soft.Pack.
       : May 2012,
         Andrea La Camera (DIBRIS) [andrea.lacamera@unige.it]:
        -Implemented an automatic search procedure for beta (exponent of the 
         Moffat function).
        -Visualization options changed: scale, zoom and color (*NEW*) can be
         now set up by right-clicking on the draw areas. 
        -Circular mask is computed more efficiently (pex_circular_mask.pro 
         improvements).
       : January 2014,
         Andrea La Camera (DIBRIS) [andrea.lacamera@unige.it]:
        -added the possibility for choosing whether the
         PSF is extrapolated with a Moffat function (already existing)
         of not (only PSF extraction is performed - just added)
       : May 2016,
         Andrea La Camera (DIBRIS) [andrea.lacamera@unige.it],
        -The header of the input/output image is kept
         up-to-date with extrapolation information
        -the background is now an array. 
        -keywords added to the header: SKY_TYPE, SKY_NB, SKY_BGn,
         SKY_FILE, BIAS_MAP, DARK_MAP, FLAT_MAP, BADP_MAP
       : May 2017,
         Andrea La Camera (DIBRIS) [andrea.lacamera@unige.it],
        -Routine MPFIT2DFUN, MPFIT, MPFIT2DPEAK have been removed 
         from PEX_LIB and replaced with the whole 
         package MPFIT by Craig B. Markwardt. 
         See installation instructions for more details.

(See pex/pex.pro)


PRE

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
    pre

 ROUTINE'S PURPOSE:
    pre manages the simulation for the pre-processing (pre) module,
    that is to call the module's initialization routine pre_init at the first
         iteration of the simulation project.

 MODULE'S PURPOSE:
    pre permits to pre-process a cube of images before a subsequent image
    restoration/deconvolution process. More precisely, the module permits:
    - data reduction (also called data calibration),
    - shift-and-add procedure for multi-frame images,
    - positivization of the calibrated images,
    - sky background evaluation,
    - SNR evaluation,
    - images re-centering.

 CATEGORY:
    main module's routine

 CALLING SEQUENCE:
    error = pre(inp_img_t, out_img_t, par, INIT=init ) 

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

 INPUTS:
    inp_img_t: structure of type img_t.
    par      : parameters structure.

 INCLUDED OUTPUTS:
    out_img_t: structure of type "img_t" containing the characteristics of 
               the pre-processed map, the following fields are contained in
               this structure:

out_img_t = $
   {        $
   data_type  : out_type[0]          , $
   data_status: !caos_data.valid     , $
   image      : pre_map              , $ ; image map
   npixel     : inp_img_t.npixel     , $ ; number of pixels
   resolution : inp_img_t.resolution , $ ; pixel size [arcsec/pix]
   lambda     : inp_img_t.lambda     , $ ; mean detection wavelength [m]
   width      : inp_img_t.width      , $ ; wavelength band width [m]
   time_integ : inp_img_t.time_integ , $ ; Integration time for each image [s]
   time_delay : inp_img_t.time_delay , $ ; [NOT USED WITHIN AIRY]
   psf        : inp_img_t.psf        , $ ; image or PSF ?
   background : back                 , $ ; estimated sky background level of the
                                         ; pre-processed maps
   snr        : snr                  , $ ; estimated peak SNR of the
                                         ; pre-processed maps
   header     : PTR_NEW('')       $ ; header of the FITS File (modified event.)
   }
*out_img_t.header = header ; update the pointer

 KEYWORD PARAMETERS:
    INIT: initialization 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:
     1-In some cases, namely when the object is a double star of faint
     magnitude the MMM algorithm can return an incorrect value (0) for
     the background evaluation.
     For this kind of cases it is recommended to use an alternative method
     for background evaluation.

     2- The background estimation done by PRE module can be contaminated
     by the object if the extension
     of the object is a large fraction of the image frame. The estimated mean value
     of the sky background and especially its rms value are then biased.
     A simple solution is to compute directly the mean background using
     the routine n_phot (found in .../caos/lib/, help at the IDL/CAOS prompt with
     the command <>). For example, with a 0.01 arcsec pixel
     size, a telescope collecting surface of 10 m^2, an integration time of 100 s
     and an overall efficiency of 0.3, the K band mean background (per pixel) is:
     
        0.3*(n_phot(0.,BAND="K",DELTA_T=100.,SURF=10.))[1]*0.01^2
     
     Then it is necessary to enter by hand the value found within the PRE module GUI
     (using the option "consider a user-defined background").

 CALLED NON-IDL FUNCTIONS:
    phot_rec.pro : re-center the map wrt the photocenter location
    sky_back_sub : estimate the sky background level of a map 
                   using the astrolib routine SKY. 

 ROUTINE MODIFICATION HISTORY:
    routine written: june 2000,
                     Serge Correia (OAA) [correia@arcetri.astro.it].
    modifications  : july 2000,
                     Marcel Carbillet (OAA) [marcel@arcetri.astro.it]:
                    -help completed.
                    -call to routine pre_prog eliminated (useless).
                   : february 2003,
                     Marcel Carbillet (OAA) [marcel@arcetri.astro.it]:
                    -use of variable "calibration" eliminated for version 4.0
                     of the whole system CAOS.

 MODULE MODIFICATION HISTORY:
    module written : Serge Correia (OAA) [correia@arcetri.astro.it].
    modifications  : for version 1.0,
                     Marcel Carbillet (OAA) [marcel@arcetri.astro.it]:
                    -help completed.
                    -call to pre_prog eliminated (useless).
                   : for version 2.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 2.0 too,
   		             Barbara Anconelli (DISI) [anconelli@disi.unige.it]
	                  -added the possility for the user to subtract sky
		                background from the images.
		              : for version 4.0,
                     Gabriele Desidera' (DISI) [desider@disi.unige.it]:
                    -use of the variable "time_integ" activated.
                   : for version 5.0,
                     Andrea La Camera (DISI) [lacamera@disi.unige.it]:
                    -added possibility to simulate multi-frame images.
                     Multi-frames images cannot be saved (by WFT), but only 
                     auto-reduced by PRE module (this module),
                    -Added DATA REDUCTION for raw images (BAD-PIXEL MAP,
                     FLAT-FIELD MAP, DARK CURRENT MAP and BIAS MAP),
                    -Added SHIFT-AND-ADD method. The values of the shift can 
                     be either stored in a text file (x_shift, y_shift in 
                     every line) or calculated by correlation (with integer or 
                     sub-pixel accuracy),
                    -Apodization has been removed (obsolete),
                    -Changed Re-centering procedure, the new one is based on 
                     correlation among the images (with integer or sub-pixel
                     accuracy),
                    -New GUI's design with "TABs".
                   : February 2012,
                     Andrea La Camera (DISI) [lacamera@disi.unige.it]:
                    -New way to call AIRY_HELP. By using the "online_help" 
                     routine, we resolved a known-issue of the Soft.Pack.
                   : March 2013,
                     Andrea La Camera (DIBRIS) [andrea.lacamera@unige.it]:
                    -routine "find_boundary" renamed to "pre_find_boundary"
                     for compatibility with other libraries (such as the 
                     well-known "Coyote" one);
                   : May 2016,
                     Andrea La Camera (DIBRIS) [andrea.lacamera@unige.it],
                    -background is now an array, which dimensions are
                     the same of the input image. The user can now
                     load the background contained in a FITS file
                     (that must have the correct dimensions). 
                    -deleted procedure "sky_back_sub.pro" (useless!)
                     and added the necessary steps directly in pre_init.
                    -Moved here the definitions of the 
                     Read-Out Noise value and the Gain of the CCD, by 
                     default they are read from the header of the
                     FITS file (be sure they are defined by "RON" and
                     "GAIN" keywords)
                    -keywords added to the header: RON, GAIN,
                     SKY_TYPE, SKY_NB, SKY_BGn, SKY_FILE, 
                     BIAS_MAP, DARK_MAP, FLAT_MAP, BADP_MAP 
                    -bug corrections in the data-reduction procedure
                   : December 2016-January 2017,
                     Marcel Carbillet (Lagrange) [marcel.carbillet@oca.eu]:
                    -Re-centering can now be done also for single images.
                    -Back to correl_optimize from astrolib (instead of
                     correl_optimize2 from CAOS lib., now eliminated), thanks
                     to new keyword INIT_FACTOR, here chosen =4 instead of
                     default 8 (which fails for images as small as 64x64).

(See pre/pre.pro)


RTI

[Previous Routine] [List of Routines]
 NAME:
   RTI

 ROUTINE'S PURPOSE:
    RTI manages the simulation for the RoTate Image (RTI) module,
    that is to call the module's initialization routine rti_init at the first
         iteration of the simulation project.

 MODULE'S PURPOSE:
   To rotate either images or objects in two different ways: 
    - rotation in pixel space: by using the IDL routine "ROT";
    - rotation in frequencies space: by rotating the Fourier transform of the input
   N.B. The rotation can generate artifacts, in particular in the case of 
   point objects/stars.

 CATEGORY:
    main module's routine

 CALLING SEQUENCE:
    error = rti(inp_yyy_t, out_yyy_t, par)
 OUTPUT:
    error: long scalar (error code, see !caos_error var in caos_init.pro).

 INPUTS:
    inp_yyy_t: structure of type "gen_t". 
    par      : parameters structure.

 INCLUDED OUTPUTS:
    out_yyy_t: structure of type "gen_t" containing the rotated
               map/image(s). Depending on the type of data, the
               following fields are contained in this structure:
'img_t': 
      out_yyy_t =  {                             $
                   data_type    : 'img_t'              , $
                   data_status  : !caos_data.valid     , $
                   image        : img_rot              , $
                   psf          : inp_yyy_t.psf        , $
                   npixel       : N*par.out            , $
                   resolution   : inp_yyy_t.resolution , $
                   lambda       : inp_yyy_t.lambda     , $
                   width        : inp_yyy_t.width      , $
                   time_integ   : inp_yyy_t.time_integ , $
                   time_delay   : inp_yyy_t.time_delay , $
                   background   : background           , $
                   snr          : inp_yyy_t.snr        , $
                   header       : PTR_NEW('')            $
                   }
      *out_yyy_t.header = header ; updated the pointer
   'src_t': 
      out_yyy_t = {                                   $
                  data_type  : 'src_t',              $
                  data_status: !caos_data.valid,     $
                  off_axis   : inp_yyy_t.off_axis,   $
                  pos_ang    : inp_yyy_t.pos_ang,    $ 
                  dist_z     : inp_yyy_t.dist_z,     $
                  map        : img_rot,              $
                  scale_xy   : inp_yyy_t.scale_xy,   $
                  coord      : inp_yyy_t.coord,      $
                  scale_z    : inp_yyy_t.scale_z,    $
                  n_phot     : inp_yyy_t.n_phot,     $
                  background : inp_yyy_t.background, $
                  lambda     : inp_yyy_t.lambda,     $
                  width      : inp_yyy_t.width,      $
                  constant   : inp_yyy_t.constant,   $
                  header     : PTR_NEW('')           $
                 }
      *out_yyy_t.header = header ; update the header

 KEYWORD PARAMETERS:

 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:
    program written: March 2007,
         Andrea La Camera (DISI) [lacamera@disi.unige.it]
    modifications  : 

 MODULE MODIFICATION HISTORY:
    program written: March 2007,
         Andrea La Camera (DISI) [lacamera@disi.unige.it]
    modifications  : 
                   : february 2011,
                     Andrea La Camera (DISI) [lacamera@disi.unige.it]
                    -module debugged (in particular, for tags "angle" and 
                     "time_integ")
                   : February 2012,
                     Andrea La Camera (DISI) [lacamera@disi.unige.it]:
                    -New way to call AIRY_HELP. By using the "online_help" 
                     routine, we resolved a known-issue of the Soft.Pack.
                   : May 2016,
                     Andrea La Camera (DIBRIS) [andrea.lacamera@unige.it],
                    -background is now an array.
                    -keywords added to the header: NB_ANGLES,
                     ANGLEn, ROT_TYPE

(See rti/rti.pro)