# OAA_LIB-utilities Library Help

This page was created by the IDL library routine `mk_html_help`. For more information on this routine, refer to the IDL Online Help Navigator or type:

         ? mk_html_help

at the IDL command line prompt.

Last modified: Tue May 15 16:15:50 2007.

# List of Routines

- AIR_RELATIVE_PERMITTIVITY
- AMAX
- AMIN
- ANIMATION
- BISECTION
- CIRCUS_MAX
- COMPLEMENT
- COMP_COLORS
- CONV2BIN
- CONV2HEX
- CREBIN
- CW_FILENAME
- DERIV_2D
- DEW_POINT
- DIAGONAL_MATRIX
- DUAL_PLOT
- EPSILON
- EQUALIZE_LIMITS
- EXTRACT_DIAGONAL
- FFT1
- FIND_IN_PATH
- FIND_TAG
- FP_OPEN
- FP_READ
- FP_SEND_COMMAND
- G_HYPERG[1]
- G_HYPERG[2]
- IDX2RGB
- IDX_ARRAY
- IMAGE_AR
- IMAGE_SHOW
- INTERSECTION
- IS_EVEN
- IS_WRITABLE_DIR
- LIN2D_FIT
- LIN2D_FITXY
- LIST2RANGES
- MAKE_XY
- MK_VECTOR
- PRESSURE_PSD
- PSEUDO_INVERT
- QROMLOG
- RAND_SEQ
- READ_ASCII_ARRAY
- READ_ASCII_STRUCTURE
- REORDER_MATRIX
- SEP_PATH
- SET_DIAGONAL
- SHIFT_AND_ADD
- SINC
- SURF_FIT
- SVP
- TELL_TYPE
- TEST_TYPE
- TIMING
- TVSCL1
- TYPE2NBITS
- UNDEFINE
- UNION
- WDEL
- WIND_PSD
- WRITE_ARRAY_ASCII
- WRITE_LABELS
- WRITE_STRUCT
- WRITE_STRUCTURE_ASCII
- WRITE_STRUCTURE_MAP
- XSHOW
- XYPLOTERR

# Routine Descriptions

##

[Next Routine] [List of Routines]

     NAME:

    	INDDIM

     PURPOSE:

     	Format change array index from linear to 2D dimensional

     CATEGORY:

    	Array routine

     CALLING SEQUENCE:

     	vect = indimm(index, dim)

     INPUTS:

     	index: index linear vector

    	dim: dim 2D square (only scalar)

     OUTPUTS:

    	vect: array with 2D coordinates

     KEYWORDS:

    	TRANSPOSE: give the vectors in a tranpsose way

     MODIFICATION HISTORY:

     	Written by:	Xompero Marco, Mar 2003.

(See utilities\inddim.pro)

## AIR_RELATIVE_PERMITTIVITY

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

     eps_r = air_relative_permittivity(h, T, P)

     the function returns the electric relative permittivity
     of the air as a function of relative humidity (h, 0 to 1),
     temperature (T [K]) and pressure (P [Pa])

     HISTORY

     Jul 2006 written by A. Riccardi, INAF-OAA

(See utilities\air_relative_permittivity.pro)

## AMAX

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

     AMAX

     same as max, but it returns the N-dimensional subscript
     in Max_Subscript, where N is the number of dimensions of
     the input array

     MODIFICATON HISTORY

        Written by: A. Riccardi, Osservatorio Astrofisico di Arcetri, ITALY
                    riccardi@arcetri.astro.it

(See utilities\amax.pro)

## AMIN

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

     AMIN

     same as min, but it returns the N-dimensional subscript
     in Min_Subscript, where N is the number of dimensions of
     the input array

     MODIFICATON HISTORY

        Written by: A. Riccardi, Osservatorio Astrofisico di Arcetri, ITALY
                    riccardi@arcetri.astro.it

(See utilities\amin.pro)

## ANIMATION

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

     ANIMATION

     show an animation of the frames stored in the input array.

     animation, cube[, /VERB][, SHOWF=velue][, SSHOWF=velue][, MINI=value][, MAXI=value] $
                    [, PIXELS=velue][, DEC=value]

     cube:   3-dim real array[xdim,ydim,nframes]

     SHOWF:  integer, scalar. Number of frames to show in the anmations
     SSHOWF: integer, scalar. Starting frame to show
     MINI:   real scalar. Minimum value used to scale the colors
     MAXI:   real scalar. Maximum value used to scale the colors
     PIXELS: integer, scalar. Zoom factor for the frame display
     DEC:    integer, scalar. Decimation of the frames in cube to diaplay

     by G. Brusa, Osservatorio Astrofisico di Arcetri (OAA)

(See utilities\animation.pro)

## BISECTION

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

     BISECTION

     apply the bisection method to find a zero of the function func_name in
     the interval start_interval

     res=bisection(start_interval, func_name[, TOL=value])

     start_interval: real 2-element vector. Interval containing the zero of the function
     func_name:      string, scalar. Name of the function having the zero in start_interval

     TOL:            real scalar. Tollerance of the solution. Default value=1d-6.

     MODIFICATON HISTORY

        Written by: A. Riccardi, Osservatorio Astrofisico di Arcetri, ITALY
                    riccardi@arcetri.astro.it

(See utilities\bisection.pro)

## CIRCUS_MAX

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

     CIRCUS_MAX

     This function returns the center and the radius of the smallest
     circle containing all the non-zero points in the 2D array mask.
     Center and radius are returned in pixel coordinates of the x-axis.

     ret = circus_max(mask [, ASPECT_RATIO=aspect][, /DISPLAY])

     ASPECT_RATIO:  deltaY/deltaX. Set it to the right value if x-pixels
                    and y-pixels have not the same linear scale. Aspect
                    ratio is set to 1 by default.
     DISPLAY:       Set it to display the graphical result of the fitting.

     ret = [x0,y0,Radius], where:

     Radius is the cirle radius in pixel units of x-axis
     x0 is the x coordinate in pixel units of x-axis
     y0 is the y coordinate in pixel units of y-axis

     HISTORY

     Apr 2004: written by M. Xompero

     14 Apr 2004: A. Riccardi.
      *Unused CENTER keyword removed.
      *help fixed

(See utilities\circus_max.pro)

## COMPLEMENT

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

     not_included = complement(list, larger_list, out_list, count)

     return in out_list the complement of list in the larger_list.
     list must be included in larger_list. If it is not included
     not_included=1B (=0B otherwise).
     count: # of elements in out_list. If the complement is empty
     the out_list is undefined (i.e. n_elements(out_list)=0) and count=0L

     if the range of the union between list and larger_list is larger then 256*1025
     the routine could be slow (depending on the length of larger_list)

     MODIFICATON HISTORY

        Written by: A. Riccardi, Osservatorio Astrofisico di Arcetri, ITALY
                    riccardi@arcetri.astro.it

(See utilities\complement.pro)

## COMP_COLORS

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

       COMP_COLORS

     returns a vector of n RGB (long integer) values of different colors

      colors = comp_colors(n)

     MODIFICATON HISTORY

        Written by: A. Riccardi, Osservatorio Astrofisico di Arcetri, ITALY
                    riccardi@arcetri.astro.it

(See utilities\comp_colors.pro)

## CONV2BIN

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

     CONV2BIN

     converts data in strings containing their binary representation

     str = conv2bin(data)

     str has the same dimentions as data. Dcomplex, objref, pointers and
     structures are not handled.

     HISTORY
       31 May 2004, written by A. Riccardi (AR)
       10 Aug 2004, AR
         bug with no scalar input fixed.

(See utilities\conv2bin.pro)

## CONV2HEX

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

     CONV2HEX

     converts data in strings containing their hexadecimal representation

     str = conv2hex(data)

     str has the same dimentions as data. Dcomplex, objref, pointers and
     structures are not handled.

     HISTORY
       31 May 2004, written by A. Riccardi

(See utilities\conv2hex.pro)

## CREBIN

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

     CREBIN

     The function is a wrapper of the REBIN function that is also able to manage
     complex and dcomplex variables. If the array is complex/dcomplex, CREBIN returns a
     complex/dcomplex array having a rebinned real and imaginary part. The input array
     cannot have more then 8 dimensions.

     SYNTAX

     Same as REBIN

     HISTORY

     24 Mar 2002, written by A. Riccardi
     Osservatorio Astrofisico di Arcetri, ITALY
     riccardi@arcetri.astro.it

(See utilities\crebin.pro)

## CW_FILENAME

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

     NAME:
           CW_FILENAME

     PURPOSE:

     CATEGORY:
    	Compound widgets.

     CALLING SEQUENCE:
    	widget = CW_FILENAME(parent)

     INPUTS:
           PARENT - The ID of the parent widget.

     KEYWORD PARAMETERS:
    	UVALUE - Supplies the user value for the widget.
           VALUE  - Supplies the initial filename (scalar string)

           TITLE        -+
           ALL_EVENTS    |
           FRAME         |
           FIELDFONT     +--- See cw_field function
           FONT          |
           NOEDIT        |
           RETURN_EVENTS |
           XSIZE        -+

           PATH         -+
           FILTER        +--- See Dialog_pickfile function
           FIX_FILTER    |
           MUST_EXIST   -+

           GET_PATH - if set only directories can be input

     OUTPUTS:
           The ID of the created widget is returned.

     PROCEDURE:
    	WIDGET_CONTROL, id, SET_VALUE=value can be used to change the
    		current value displayed by the widget.

    	WIDGET_CONTROL, id, GET_VALUE=var can be used to obtain the current
    		value displayed by the widget.

     MODIFICATION HISTORY:
           April 1999, written by A. Riccardi

(See utilities\cw_filename.pro)

## DERIV_2D

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

     DERIV_2D

     INPUT:
     x:	x-vector. N-elements.
     y:	y-vector. M-elements
     func:	NxM-elements matrix to derive

     OUTPUT:
     de_x:	x-derivative matrix
     de_y: y-derivative matrix

     MODIFICATION HISTORY:
       Written by: A. Riccardi, Osservatorio Astrofisico di Arcetri, ITALY

(See utilities\deriv_2d.pro)

## DEW_POINT

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

     DEW_POINT

     computes the dew and frost point

     t_point = dew_point(vp [, /FROST][, /KELVIN])

     vp:      float scalar or vector. Vapour pressure in hPa
              vp = vp*(hr/100.0), where vp is saturation vapour
              pressure in hPa and hr is relative humidity in
              percentage (0-100)
     KEYWORDS:
       FROST: if it is set, the frost point is returned. Default is
              dew point.

       KELVIN: if it is set, the dew/frost point is returned in
               kelvin. Defaults is Celtius degrees.

     HISTORY
       2002: written by G. Brusa, CAAO Steward Obs., USA
             gbrusa@as.arizona.edu

(See utilities\dew_point.pro)

## DIAGONAL_MATRIX

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

        DIAGONAL_MARIX

      ret = diagonal_matrix(diag)

      Returns a diagonal matrix having the same data type of diag and
      diag as diagonal elements.

     21 Oct, 2002 Written by A. Riccardi, INAF-Osservatorio Astrofisico di Arcetri (Italy)
                  riccardi@arcetri.astro.it

(See utilities\diagonal_matrix.pro)

## DUAL_PLOT

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

     it draws a plot with different left and right y-scales. If X2TOP is set, then
     different bottom and top x scales are plotted.

(See utilities\dual_plot.pro)

## EPSILON

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

     NAME:
           EPSILON

     PURPOSE:
           This function returns the machine precision.

     CATEGORY:
           Utilities.

     CALLING SEQUENCE:

           Result = EPSILON()

     KEYWORD PARAMETERS:
           DOUBLE: If set calculates double type machine precision. Float
                   otherwise.

     OUTPUTS:
           This function returns the machine precision: the smallest floating
           point eps that: 1. + eps ne 1. (1.d + eps ne 1.d if DOUBLE is set).

     EXAMPLE:
           Test if matrix C have zero elements using a tollerance.

               Eps = EPSILON()
               Toll = MAX(ABS(C)) * Eps
               IF (WHERE((C LT Toll) AND (C GT -Toll)))(0) ne -1 THEN $
                   PRINT, 'C have zero-stimated elements'

     MODIFICATION HISTORY:
           Written by:     A. Riccardi; April, 1995

(See utilities\epsilon.pro)

## EQUALIZE_LIMITS

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

     EQUALIZE_LIMITS

      Computes the range including most of the values of the input array or vector.
      It is usefull to display images with spikes to filter out.

      The function returns a range eq_range=[r1,r2] of image values for which:
      the number of image values with values less then r1 is lower then LOW_THESHOLD
      the number of image values with values less then r2 is lower then HIGH_THESHOLD

      eq_range = equalize_limits(image[, LOW_THRESHOLD=value][, HIGH_THRESHOLD=value] $
                                 [, BINSIZE=value])

      default values:
      LOW_THRESHOLD=0.01
      HIGH_THRESHOLD=0.99
      BINSIZE=(max_image_value-min_image_value)/1000

     MODIFICATION HISTORY

     Written by: A. Riccardi, Osservatorio di Astrofisico di Arcetri, ITALY
                 riccardi@arcetri.astro.it

(See utilities\equalize_limits.pro)

## EXTRACT_DIAGONAL

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

     EXTRACT_DIAGONAL

     Result = EXTRACT_DIAGONAL(A)

     INPUT
     A:	square matrix

     OUTPUT
     vector containg the diagonal elements of A matrix

     MODIFICATION HISTORY

     Written by: A. Riccardi, Osservatorio Astrofisico di Arcetri, ITALY

(See utilities\extract_diagonal.pro)

## FFT1

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

     FFT1

     perform FFT for real data, providing the correct scaling
     and PSD (pixels^2/Hz)

     HISTORY:
        ?? 19??  Written by Guido Brusa, Osservatorio Astrofisico di Arcetri
                 brusa@arcetri.astro.it

(See utilities\fft1.pro)

## FIND_IN_PATH

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

     FIND_IN_PATH

     The function searches a file in all the directories specified
     in the !PATH system variable

     SYNTAX

       res = find_in_path(filename, /VERBOSE)

     INPUTS

       filename:  scalar string. File name to search for. only the
                  filename without any path. Wild characters are allowed.

     OUTPUT

       res:       empty string ("") if no file has been found. Vector of
                  strings containing the results of the search if
                  successful.

     HISTORY

       22 Mar 2002:  Written by A. Riccardi
                     Osservatorio Astrofisico di Arcetri, Italy
                     riccardi@arcetri.astro.it

(See utilities\find_in_path.pro)

## FIND_TAG

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

      NAME:
       FIND_TAG

      PURPOSE:
       This routine helps you to find a forgetten field into a large structure.

      USAGE:
       FIND_TAG, regexp, struct, strout

      INPUT:
       regexp: string. Regular expression special chacacters are permitted. (See IDL help)
       struct: struct. This is the place where we are looking for the tag.

      OUTPUT:
       strout: (optional) string array. Result of the matching. If nothing is found,
                it return an empty string. If the struct parameter is wrong, it's set to
                an integer value -1.

      NOTE:
       None.

      PACKAGE:
       OAA_LIB/UTILITIES

      HISTORY:

      07 Dec 2004
       Created by Marco Xompero (MX)
       marco@arcetri.astro.it

(See utilities\find_tag.pro)

## FP_OPEN

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

     NAME:
    	FP_OPEN

     PURPOSE:
    	Open the communication with a field point device.

     CATEGORY:
    	Communication initialization.

     CALLING SEQUENCE:
    	err =  fp_open(com_port_str, fp_config, VERBOSE=verb, PORT_ID=port_id)

     INPUTS:
    	com_port_str: input structure.
    					If the device is driven by socket, it needs two fields:
    								- ip_address: 	ipaddress of the device
    								- port:			port number
    					If the device is a COM port, it's need only the string name of the port.
     OUTPUT:
    	fp_config: 	configuration structure

     KEYWORDS:
    	VERBOSE: prints more informations.
    	PORT_ID: return the port_id opened.

     PROCEDURE:
    	The procedure collects the configuration data of the field point device and return all in the structure fp_config.
     	 To close a open connection with the field point, just have a "free_lun" of port_id.
     	 If there is no port_id keyword specified, the connection is closed at the and of the routine automatically.

     MODIFICATION HISTORY:

    	Created by Armando Riccardi on 2003

    	Modified 2003/07/16 busoni
    	 Added control if Empty Base is present
    	 Added section for FP-AI-100

    	Modified 2004/01/16 riccardi
    	 Socket communication is now supported thru serial<->TCP/IP converter
     	 Added VERBOSE and PORT_ID keywords
     	 Changes in case of trapped error (an error code is returned without stopping)
     	08 Apr 2004 M.Xompero
     	 Arg_present test fixed

(See utilities\fp_open.pro)

## FP_READ

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

     NAME:
    	FP_READ

     PURPOSE:
    	READ the field point data.

     CATEGORY:
    	Data acquisition.

     CALLING SEQUENCE:
    	err = fp_read (fp_setting, module_idx, channel_list, UNIT=unit, VERBOSE=verb, $
    						PORT_ID=port_id , ERROR=return_error, FP_ERROR=err_resp)

     INPUTS:
     	fp_setting:

     OUTPUT:
    	fp_config: 	configuration structure
    	module_idx: int index of the module fp to read
    	channel_list: int list of the channels to read

     KEYWORDS:
    	VERBOSE: prints more informations.
    	UNIT:	return measur unit of the data read.
    	PORT_ID: port_id on which to read the data.
    	ERROR: error code return
    	FP_ERROR: field point error string

     PROCEDURE:
    	The procedure read the data from the field point device by fp_send_command.pro

     MODIFICATION HISTORY:

    	Created by Armando Riccardi on 2003

    	16 Jan 2004: A. Riccardi
      	Added PORT_ID, ERROR and FP_ERROR keywords.
         In case of error the function returns 0 and
         fills ERROR with a error code. FP_ERROR
         returns the value contained in the fp_send_command
         ERROR_RESP keyword.
    ; 08 Apr 2004: M. Xompero
    		Arg_present test fixed

(See utilities\fp_read.pro)

## FP_SEND_COMMAND

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

     NAME:
    	FP_SEND_COMMAND

     PURPOSE:
    	Send a command to the Field Point device.

     CATEGORY:
    	Device driver.

     CALLING SEQUENCE:
    	err = fp_send_command (com_data, command_in, resp, N_ITERATIONS=n_iter $
                            , ERROR_RESP=err_resp, VERBOSE=verb, PORT_ID=port_id)

     INPUTS:
    	com_data: input structure.
    					If the device is driven by socket, it needs two fields:
    								- ip_address: 	ipaddress of the device
    								- port:			port number
    					If the device is a COM port, it's need only the string name of the port.
    	command_in: command to send

     OUTPUT:
    	resp:		data collected

     KEYWORDS:
    	VERBOSE: prints more informations.
    	PORT_ID: return the port_id opened.
    	ERROR_RESP: error code response
    	N_ITERATIONS: return the iteration made for an exact checksum (min 1)

     PROCEDURE:
    	The procedure send the command to the Field Point davice and return the data if they are corrects.

     MODIFICATION HISTORY:

    	Created by Armando Riccardi on 2003

     	16 Jan 2004: A. Riccardi
     		Socket communication is now supported thru serial<->TCP/IP converter
     		Added VERBOSE and PORT_ID keywords

     	08 Apr 2004: M. Xompero
     		Arg_present test fixed

(See utilities\fp_send_command.pro)

## G_HYPERG[1]

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

     NAME:
           G_HYPERG

     PURPOSE:
           Evaluates generalized hypergeometric function.

     CATEGORY:
           Special function.

     CALLING SEQUENCE:

           Result = G_HYPERG(Alpha, Beta, Z)

     INPUTS:
           Alpha: 	real or double vector.

    		Beta:	real or double vector.

    		Z:		float, double or complex. Evaluating point.

     KEYWORD PARAMETERS:
           eps:	float. Fractional precision requested. If it isn't set
    				then eps=1.e-6 is assumed.

     OUTPUTS:
           This function returns:

    		Sum(n=0 to N)((Alpha)n/(Beta)n*z^n/n!)

    		where:
    		(Alpha)n = (Alpha(0))n*...*(Alpha(P-1))n
    		(a)n = a*(a+1)*...*(a+n-1)
    		P=n_elements(Alpha)
    		(same as Beta)

    		N max value of n in the sum. Truncation of the series.
    		N is stimated from eps

     RESTRICTIONS:
           P=n_elements(Alpha)
    		Q=n_elements(Beta)
    		Generalized hipergeometric series converges always if P<=Q,
    		conerges for abs(Z)<1. if P=Q+1 and diverges for all z not equal
    		to zero id P>Q+1.
    		If P=Q+1, s=Re(total(Alpha)-total(Beta)) then the series converges
    		for all abs(Z)=1 if s<0; it converges for all abs(Z)=1 and Z not eq 1
    		if 0<=s<1 and diverges if s>=1.

     EXAMPLE:

     MODIFICATION HISTORY:
           Written by:     A. Riccardi; July, 1995.

(See utilities\g_hyperg.pro)

## G_HYPERG[2]

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

     NAME:
           G_HYPERG

     PURPOSE:
           Evaluates generalized hypergeometric function.

     CATEGORY:
           Special function.

     CALLING SEQUENCE:

           Result = G_HYPERG(Alpha, Beta, Z)

     INPUTS:
           Alpha: 	real or double vector.

    		Beta:	real or double vector.

    		Z:		float, double or complex. Evaluating point.

     KEYWORD PARAMETERS:
           eps:	float. Fractional precision requested. If it isn't set
    				then eps=1.e-6 is assumed.

     OUTPUTS:
           This function returns:

    		Sum(n=0 to N)((Alpha)n/(Beta)n*z^n/n!)

    		where:
    		(Alpha)n = (Alpha(0))n*...*(Alpha(P-1))n
    		(a)n = a*(a+1)*...*(a+n-1)
    		P=n_elements(Alpha)
    		(same as Beta)

    		N max value of n in the sum. Truncation of the series.
    		N is stimated from eps

     RESTRICTIONS:
           P=n_elements(Alpha)
    		Q=n_elements(Beta)
    		Generalized hipergeometric series converges always if P<=Q,
    		conerges for abs(Z)<1. if P=Q+1 and diverges for all z not equal
    		to zero id P>Q+1.
    		If P=Q+1, s=Re(total(Alpha)-total(Beta)) then the series converges
    		for all abs(Z)=1 if s<0; it converges for all abs(Z)=1 and Z not eq 1
    		if 0<=s<1 and diverges if s>=1.

     EXAMPLE:

     MODIFICATION HISTORY:
           Written by:     A. Riccardi; July, 1995.

(See utilities\test_g_hyperg.pro)

## IDX2RGB

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

     IDX2RGB

       the function returns the RGB long numbers corresponding to the
       indexes of the current color table given by idx

     rgbcodes = idx2rgb(idx, /SCALE)

       if SCALE keyword is set, idx is scaled to fit the 0-255 range.

(See utilities\idx2rgb.pro)

## IDX_ARRAY

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

       IDX_ARRAY

      The function convert a one-dimensional indexes of a
      N-dimensional array (returned by the where function,
      as instance) in vectors containinig the corresponding
      collections of N-dimensional indexes

       idx_vec = idx_array(idx, array)
      or
       idx_vec = idx_array(idx, size(array), /SIZE_OF_ARRAY)

      	idx:   input. non floating point M-elemnts vector.
              one-dimensional index of array[*]
       array: input. N-dimensional array.

       index_vec: output, long NxM array.

      EXAMPLE:

     IDL> a=fltarr(10,5,6)
     IDL> a[7,2:3,5]=1
     IDL> idx=where(a eq 1)
     IDL> print, idx
              277         287
     IDL> print, idx_array(idx, a)
     IDL> print, idx_array(idx, a)
                7           2           5
                7           3           5
     IDL> print, idx_array(idx, size(a), /SIZE_OF_ARRAY)
                7           2           5
                7           3           5

     HISTORY:
        04 Dic 2002. Written by A. Riccardi. INAF, OAA, Italy
                     riccardi@arcetri.astro.it

(See utilities\idx_array.pro)

## IMAGE_AR

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

    resample an image sampled with a different step in y and x axis to the same step.
    usage : resampled_image=image_ar(aspect_ratio,image)
    			aspect_ratio is the image aspect ratio

(See utilities\image_ar.pro)

## IMAGE_SHOW

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

     NAME:
       IMAGE_SHOW

     PURPOSE:
       Display an image.

     CATEGORY:
       General graphics.

     CALLING SEQUENCE:

     image_show, input, x_vec, y_vec, NX=nx, NY=ny, XAXIS=xax, YAXIS=yax $
        , WINDOW_SCALE = window_scale, ASPECT = aspect, MAX_VALUE = max_value $
        , MIN_VALUE = min_value, SHOW_BAR = show_bar, INV = inv, POSIZ = posiz $
        , DIG = dig, INTERP=interp, _EXTRA=plot_keywords, SCALE = scale $
        , BAR_TITLE=ytitle_bar, NOERASE=noerase, NO_GT=no_gt, NO_LT=no_lt $
        , TITLE=title, YTITLE=ytitle, YTICKF_BAR=ytickf_bar, YSTYLE=ystyle $
        , XSTYLE=xstyle, COL_INVERT=col_invert, LOG=log, XBAR=xbar $
        , CONTOUR=do_contour, NLEV = nlev ,PERCENT = percent, EQUALIZE=equalize

     INPUTS:
       input:  If x_vec and y_vec are not present, "input" is the two-dimensional array
               to display. If x_vec and y_vec are present, "input" is a vector of values
               of the map to dispaly in the corresponding irregular grid defined by x_vec
               and y_vec.

       x_vec, y_vec  cannot be used when "input" is a two-dimensional array. If they are
               defined, they have to be vectors with the same size as "input". In the last
               case TRIGRID is used to obtain a regular gridded two-dimensional array
               to display.

     KEYWORD PARAMETERS:

       NX,NY:  Used only when three parameters are passed. Same keywords as TRIGRID.

    	XAXIS:	Two elements array containing minimum and maximum x-axis values

    	YAXIS:	Two elements array containing minimum and maximum y-axis values

       WINDOW_SCALE:   Set this keyword to scale the window size to the image size.
           Otherwise, the image size is scaled to the window size.
           This keyword is ignored when outputting to devices with
           scalable pixels (e.g., PostScript).

       ASPECT: Set this keyword to requested image's aspect ratio (y/x).
           1 implies square pixels.  If WINDOW_SCALE is set, the
           aspect ratio is automatically retained.

       MAX_VALUE: Set this keyword to change the limit of the lookup table

       MIN_VALUE: Set this keyword to change the limit of the lookup table

       SHOW_BAR: Set this keyword to show the color lookup table

       INV: Set this keyword to invert the lookup table (can be used to
            reduce the amount of toner/ink used when printing certain images)

       POSIZ: Returns the device coordinates of the displayed image
              (can be used to overplot something on the main image)

       DIG: Sets the number of digits used to label the ticks of the lookup table
               (otherwise set automatically)

       INTERP: Uses an interpolation method as described in the routine
               poly_2d

    	_EXTRA: Allows to use the general keywords used with the plot routine to
               insert titles and other features (see help on plot).

       SCALE:  Scales x and y axis (not used on XAXIS or YAXIS values)

    	BAR_TITLE: Allows to insert a title over the color bar

       XBAR:    0.0 < xbar < 1.0, normalized starting point of the color bar
                in the horizontal direction of the plotting window.
                0.75 by default

       NOERASE: If set, the window or page is not erased before plotting

       YTICKF_BAR: tick format strin of the color bar labels

       COL_INVERT: invert the background and foreground colors

       LOG:    if set, display the array values using logarithmic scale

       CONTOUR:  if set, overplot a contour plot on the array map

       NLEV:   number of levels to use in the contour plot (10 by default)

       PERCENT: if set, contour label are expressed in percent value of
                 the plotting range

       EQUALIZE: if set, the function equalize_limit is called to compute
                 the optimal color cuts. MIN_VALUE and MAX_VALUE keywords
                 override the EQUALIZE setting. In order to restrict the
                 computation of the equalized limits over a subset of data,
                 set this keyword to the corresponding list of elements to use.

     OUTPUTS:
       No explicit outputs.

     COMMON BLOCKS:
       None.

     SIDE EFFECTS:
       The currently selected display is affected.

     RESTRICTIONS:
       None.

     PROCEDURE:
       If the device has scalable pixels, then the image is written over
       the plot window.

     MODIFICATION HISTORY:
       DMS, May, 1988. (image_cont)
    	several times. G. Brusa Zappellini (Osservatorio Astrofisico di Arcetri)
                      brusa@arcetri.astro.it.
       Mar 2002. A. Riccardi (OAA) riccardi@arcetri.astro.it
                 Keywords CONTOUR, NLEV, PERCENT added.
                 Computation of the optimal value for DIG if is not not passed.
       Mar 2002. AR, Implemented the possibility to pass an irregularly gridded set of points.
       Dic 2002. GBZ, added the XBAR keyword
       Dic 2002. AR, Error in the computation of the optimal value of dig fixed.
                     Image x-size is computed as 95% of xbar.
                     Definition of NX and NY keyword fixed.
                     New data type (code numbers from 12 to 15, see SIZE function) are
                     now accepted. The data type check is performed earlier in the code.
                     Check on the x_vec and y_vec data type added.
                     keyword EQUALIZE added
       June 2003. AR, A subset of data can be now used to compute the equalized limits
                     (see EQUALIZE keyword)
                     ASPECT keyword implements the possibility to have non-squared
                     pixels
       May 2006. AR, fixed computation of number of digits in case minimum value
                 is zero

(See utilities\image_show.pro)

## INTERSECTION

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

     empty_inters = intersection(list1, list2, out_list)

     if the range of the union between list1 and list2 is larger then 256*1025
     the routine could be slow (depending on the length of list2)

(See utilities\intersection.pro)

## IS_EVEN

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

     NAME:
           IS_EVEN

     PURPOSE:
           IS_EVEN returns true (1B) if its argument is even.
    		False (0B) otherwais.

     CATEGORY:
           Utility

     CALLING SEQUENCE:
           Result = IS_EVEN(Value)

     INPUTS:
    		Value:	scalar or array.

     OUTPUT:
    		Result: byte scalar or array (same size of Value).

     MODIFICATION HISTORY:
           Written by:     A. Riccardi; March, 1995.

(See utilities\is_even.pro)

## IS_WRITABLE_DIR

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

     NAME

        IS_WRITABLE_DIR

     SYNTAX

        ret = is_writable_dir(dirname)

     dirname: scalar string containing the directory name to test.

     ret:     scalar byte. 1B if it is possible to write in dirname. 0B otherwise.

     April 1999, written by A. Riccardi (OAA)

(See utilities\is_writable_dir.pro)

## LIN2D_FIT

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

     NAME:
         LIN2D_FIT

     PURPOSE:
         The procedure fits a 2-dim (or 1-dim as a particular case)
         linear operator A described by the following relationship:

         y = A ## x

         where A is a real LxN (L>=1,N>=2) matrix and x and y are real NxM and LxM
         matrices respectively.
         The M>N corresponds to a proper fitting case.
         x is assumed without error and the columns of y are assumed to have
         the same variance-covariance matrix C (LxL) and no covariance
         between the columns themselves.
         The elements of C are related to covariances of y, by:

          = C[j,l]*I[i,k]

         where I is the MxM identity matrix and i,k are the column
         indexes and j,l the row indexes of y following the IDL conventions.

     CATEGORY:
         Fitting Routines

     CALLING SEQUENCE:
         lin2d_fit, x, y, A

     INPUTS:
         x:     real NxM matrix. N is the number of columns of A.
                  M is the number of measured sets. Each set is stored
                  in a column of x.

         y:     real LxM matrix. L is the number of rows of A.
                  M is again the number of measured sets. Each set is
                  stored in a column of y.

     KEYWORD PARAMETERS:
        COVAR_Y:      real LxL symmetric matrix. Covariance of each
                        column of y.

        CHISQ:        named variable. Provides the sum of the squared errors.

        DOUBLE:       set this keyword to force double precision calculation.

        SIGMA:        named variable. Returns the standard deviation of
                        the elements of A.

        SINGULAR:     named variable. Contains the number of singular
                        values equal to zero.

        COVAR_FACTOR: named variable. Contains the NxN matrix F that can
                        be used to compute the covariances for the
                        elements of A (LxN):

                         = C[i,k]*F[j,l]

        YFIT:         named variable. Contains the vector A ## x, where
                        A is the fitted matrix.

     OUTPUTS:
        A:            named variable. Real LxN matrix. It contains the result
                        of the fitting.

     MODIFICATION HISTORY:

           Thu Aug 20 18:04:57 1998, Osservatorio Astrofisico di Arcetri,
                                     Adaptive Optics Group.
           Feb 03 2000, A.Riccardi. The possibility to fit non-square
                                    matrices A is added.

(See utilities\lin2d_fit.pro)

## LIN2D_FITXY

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

     NAME:
         LIN2D_FITXY

     PURPOSE:
         The procedure fits a 2-dim linear operator A described by the
         following relationship:

         y = A ## x

         where A is a real LxN matrix and x and y are real NxM and LxM matrices
         respectively. M is the number of measurements. N>1 and L>=1.
         The M>N corresponds to a proper fitting case.
         the columns of x and y are assumed to have the same
         variance-covariance matrix Cx and Cy repsectively for and no covariance
         between the columnes themselves.
         The elements of Cx and Cy are related to covariances of x and y, by:

          = Cx[j,l]*I[i,k]
          = Cy[j,l]*I[i,k]

         where I is the NxN identity matrix in the case of Cx and LxL in the case of Cy.

     CATEGORY:
         Fitting Routines

     CALLING SEQUENCE:
         lin2d_fit, x, y, A

     INPUTS:
         x:     real NxM matrix. N is the dimension of the domain of A.
                  M is the number of measured sets

         y:     real LxM matrix. L is the dimension of the image space of A.
                M is the same as before.

     KEYWORD PARAMETERS:
        COVAR_X:      real NxN symmetric matrix. Covariance of each
                        column of x.

        COVAR_Y:      real LxL symmetric matrix. Covariance of each
                        column of y.

        CHISQ:        named variable. Provides the sum of the squared errors.

        DOUBLE:       set this keyword to force double precision calculation.

        SIGMA:        named variable. Returns the standard deviation of
                        the elements of A.

        SINGULAR:     named variable. Contains the number of singular
                        values equal to zero.

        COVAR_FACTOR: named variable. Contains the NxN matrix F that can
                        be used to compute the covariances for the
                        elements of A:

                         = C[i,k]*F[j,l]

        YFIT:         named variable. Contains the vector A ## x, where
                        A is the fitted matrix.

        EPS:          float or double scalar. Minimum relative pecision requested
                        in the computation of the elements of the fitted matrix.
                        If undefined 1e-3 is assumed.

     OUTPUTS:
        A:            named variable. Real NxN matrix. It contains the result
                        of the fitting.

     MODIFICATION HISTORY:

           Thu Aug 20 18:04:57 1998, Osservatorio Astrofisico di Arcetri,
                                     Adaptive Optics Group.

(See utilities\lin2d_fitxy.pro)

## LIST2RANGES

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

     LIST2RANGES

     This function returns a list of couples of numbers
     giving the ranges of consecutive numbers in the input list.

     ranges = LIST2RANGES(list, range_count [,BREAK_MODULUS=br])

     INPUTS

       list:            byte, short-int or long-int vector. The list don't need to
                        be ordered or having unique elements.

     OUTPUTS

       ranges:          byte, short-int or long-int array. Same type as list.
                        List of ranges of consecutive values
                        in list. The array has 2 columns and range_count rows.

       range_count:     named variable. This variable is set in output to the number of
                        indipendent ranges found in the list vector.

     KEYWORDS

       BREAK_MODULUS:   byte, short-int or long-int scalar. If defined
                        to a value N, it forces a range to be splitted
                        when k*N is included in the range
                        (k=+/-1,+/-2,+/-3,...). In other words it avoids
                        that k*N-1 and k*N are included in the same range.

     EXAMPLE

       list = [3, 14, 2, 13, 4, 1, 13, 11, -1, 5, 0]
       print, list2ranges(list, count)

       -1  5
       11  11
       13  14

       print, count

       3

       The result means that the list can be considered as 3
       not overlapping groups of numbers, the first ranging from
       -1 to 5, the second from 11 to 11 and the last from 13 to 14.

       The same list, using the BREAK_MODULUS keyword:
       list = [3, 14, 2, 13, 4, 1, 13, 11, -1, 5, 0]
       print, list2ranges(list, count, BREAK_MODULUS=5)

       -1   4
        5   5
       11  11
       13  14

       print, count

       4

     HISTORY:

           Nov 27 1999, Armando Riccardi (AR)

           Mar 10 2004: AR, BREAK_MODULUS keyword added.

(See utilities\list2ranges.pro)

## MAKE_XY

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

     NAME:
           MAKE_XY

     PURPOSE:
           This procedure generates zero-centered domains in
           cartesian plane or axis, tipically for pupil sampling
           and FFT usage.

     CATEGORY:
           Optics.

     CALLING SEQUENCE:

           MAKE_XY, Sampling, Ratio, X [, Y]

     INPUTS:
           Sampling:   integer scalar. Number of sampling points per dimension of
                       the domain. Sampling>=2 and must be even.

           Ratio:  floating scalar. Extension of sampled domain:
                       -Ratio <= x [,y] <= +Ratio
                   Ratio < Sampling

           X:      variable. Not used as input.

     OPTIONAL INPUTS:
           Y:      variable. Not used as input. Specify this variable if you
                   want the y coordinates in the 2-dimension domain case
    				(see VECTOR keyword).

     KEYWORD PARAMETERS:
           DOUBLE: set it to have double type output.

           POLAR:  set it to have domain sampling in polar coordinates. If
                   VECTOR keyword is set, POLAR setting is not considered.

           VECTOR: if set, 1-dimensional domain is sampled and you needn't
                   specify Y variable as input.

           ZERO_SAMPLED:   if set, origin of the domain is sampled.

    		QUARTER:	if set, only 1st quadrant is returned. The array (vector)
    					returned has Sampling/2 X Sampling/2 (Sampling/2) elements.

    		FFT:	if set, order the output values for FFT purposes.
    				For example, vector -5,-3,-1,+1,+3,+5 is returned as
    				+1,+3,+5,-5,-3,-1.

     OUTPUTS:
           X:  floating vector or squared matrix. Returns X values of sampled
               points. Radial values if POLAR is set.

     OPTIONAL OUTPUTS:
           Y:  floating squared matrix. Returns Y values of sampled points.
               Azimuthal angle values if POLAR is set. If VECTOR is set and
               Y is specified as input, it is left unchanged.

           HOW IS SAMPLED THE DOMAIN:

               -ZERO_SAMPLING is not set-
               the edge of the domain is not sampled and the sampling is
               symmetrical respect to origin.

                   Ex: Sampling=4, Ratio=1.
                       -1   -0.5    0    0.5    1    Domain (Ex. X axis)
                        |     |     |     |     |
                           *     *     *     *       Sampling points

               -ZERO_SAMPLING is set-
               the lower edge is sampled and the sampling is not symmetrical
               respct to the origin.

                   Ex: Sampling=4, Ratio=1.
                       -1   -0.5    0    0.5    1    Domain (Ex. X axis)
                        |     |     |     |     |
                        *     *     *     *          Sampling points

    			If FFT keyword is set, output values are ordered for
    			FFT purposes:

               Ex: 2-dimensional domain: N = Sampling
               X or Y(0:N/2-1, 0:N/2-1)   1st quadrant (including origin
                                          if ZERO_SAMPLEDis set)
               X or Y(N/2:N, 0:N/2-1)     2nd quadrant
               X or Y(N/2:N, N/2:N)       3rd quadrant
               X or Y(0:N/2-1, N/2:N)     2nd quadrant

     EXAMPLE:
           Compute the squared absolute value of FFT of function
           (x+2*y)*Pupil(x^2+y^2) and display the result.
           Pupil(r)=1. if r<=1., 0. otherwise.

           MAKE_XY, 256, 1., X, Y
           Pupil = X*X+Y*Y LE 1.
           TV_SCL, ABS(FFT((X+2*Y)*Pupil))^2

     MODIFICATION HISTORY:
           Written by:     A. Riccardi; April, 1995.

(See utilities\make_xy.pro)

## MK_VECTOR

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

        MK_VECTOR

        Result = MK_VECTOR(Sampling, Min, Max)

        Returns a vector with Sampling elements from Min to Max.

        KEYWORDS

            DOUBLE:     force double precision values

            LOGARITMIC: if set, element of the vector are equispatiated on
                        a logaritmic scale

(See utilities\mk_vector.pro)

## PRESSURE_PSD

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

     PRESSURE_PSD

     PSD of Dynamic wind pressure fluctuations. A Kaimal wind turbulrnce model is ; used.

     p_psd = pressure_psd(f [,z [,v10]] [,ROUGHNESS=z0] [,AIR_DENSITY=rho]
                          [,STATIONARY_PRESSURE])

     f:      real-number scalar or vector. (input) Temporal frequency vector
             in [Hz]
     z:      real-number, scalar. (optional input) See z in WIND_PSD function
     v10:    real-number, scalar. (optional input) See v10 in WIND_PSD function.

     p_psd:  real-number, same size of f. (output) Dynamic wind pressure [N/m^2]

     ROUGHNESS:  real-number, scalar. (optional input) See z0 in WIND_PSD function.
     AIR_DENSITY:real-number, scalar. (optional input) Air density in [Kg/m^3]
     STATIONARY_PRESSURE: Named variable. (optional output) Stationary value of
                          wind pressure [N/m^2]

     HISTORY
      11 Dec 2002, written by A. Riccardi, INAF-OAA, Italy
                   riccardi@arcetri.astro.it

(See utilities\pressure_psd.pro)

## PSEUDO_INVERT

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

     PSEUDO_INVERT

     returns the pseudo-inverted matrix of a given matrix. The pseudo-inverted matrix is computed
     using singular value decomposition method filtering out the singular values w having:
      w < max(w)*eps
     If eps is not specified in the keywords, machine precision value is used.

     a_plus = PSEUDO_INVERT(a [,/DOUBLE][,EPS=eps][,W_VEC=w_vec][,U_MAT=u][,V_MAT=v] $
                            [,INV_W=inv_w][,IDX_ZEROS=idx][,COUNT_ZEROS=count][,/VERBOSE])

     a = u##diagonal_matrix(w)##transpose(u)
     IDX_ZEROS: indexes of vector w related to singular vectors filtered out (-1 if none)
     COUNT_ZEROS: number of singular vectors filtered out
     INV_W: pseudo-inverted of diagonal(w) (equal to diagonal(1/w) if no vectors filtered out)
     /DOUBLE: force double precision computation

     HISTORY:
     09/03/2006: written by A. Riccardi (AR), riccardi@arcetri.astro.it.

(See utilities\pseudo_invert.pro)

## QROMLOG

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

     QROMLOG

     res = QROMLOG(func_name, a, b)

     same keywords as QROMO. If MIDEXP is set, only the parameter "a" is accepted ("b" is
     supposed to be infinity).

     a and b must be strictly positive and b>a

     the function computes the integral

     \b               \b                   \log(b)
     | f(x)*dx    as   | x*f(x)*d(log(x)) = | exp(z)*f(exp(z))*dz
     \a                \a                   \log(a)

     Mar 2002: written by A. Riccardi (Osservatorio Astrofisico di Arcetri)
               riccardi@arcetri.astro.it

(See utilities\qromlog.pro)

## RAND_SEQ

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

     RAND_SEQ

     This function computes a real random sequence having a flat power
     spectral density inside the frequency range [f_min,f_max] and 0
     outside. The variance (i.e. the total power) of the output sequence is 1.

     seq = RAND_SEQ(f_min, f_max, dt, n_samples, SEED=seed, SPECTRUM=spec)

     f_min:   float, scalar. On input the lower limit of the bandpass.
              On output the lower limit used by the function because of the
              finite sampling.

     f_max:   float, scalar. The same as above for the higher limit of the
              bandpass.

     dt:      float, scalar. The sampling step of the sequence.

     n_samples: long or short integer, scalar. The number of sampling points
                in the sequence.

     SEED:    see randomu procedure.

     ZERO_DC_LEVEL: if set force zero-mean sequence even if f_min is equal to 0.

     SPECTRUM: named variable. On output this variable contains the spectrum of
               the sequence.

     FREQ_VECTOR: named variable. On output the frequency vector related to
                  SPECTRUM.

     BIN_STEP: integer scalar. By default is 1. The step (in frequency bins) between
               two successive excited frequencyes. If it is 1 (or not defined) the
               power spectral density of the output signals is a box starting from
               f_min to f_max. If it is greater then one, the power spectral density
               is a sequence of equispaced Dirac's deltas starting from f_min, one
               every BIN_STEP frequency bins. The higher excited frequency bin is less
               then or equal to f_max.

     HISTORY:
       written by Armando Riccardi (AR)
       riccardi@arcetri.astro.it

       06 Aug 2004 Marco Xompero (MX)
        Now the number of samples can be ini, unit, long, ulong.

(See utilities\rand_seq.pro)

## READ_ASCII_ARRAY

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

     NAME:
            READ_ASCII_ARRAY

     PURPOSE:
            The READ_ASCII_ARRAY function reads a text file containing the definition
            of an array. See below for format definition of the text file.

     SYNTAX:
            array = read_ascii_array(filename)

     RETURN VALUE:
            returns the array defined in filename. In case of error the return
            value is undefined.

     ARGUMENTS:
       filename:  scalar string containing the name of the text file that contains the
                  array definition. The file has to have the ".txt" extension.

     DEFINITION OF THE FILE FORMAT

     The format of a text file describing an array is the following:

     ;optional comment or blank lines
     type dim1_len dim2_len ... dimn_len ; optional description
     array_val1 array_val2 ... array_valn
     array_valn+1 ... array_valm
     ...
     ...array_val_last

     Empty lines or lines having ";" or "#" as first non-blank character (optional
     comment lines) are skipped.

     The optional description must start with ";" or "#" character and cannot include
     any other ";" or "#" character.

     The first non-comment line contains the array type (type) and
     the size of each dimension of the array (dim1_len dim2_len ... dimn_len).
     Type can be one of the following case insensitive string:
            byte       (byte)
            int        (16bit short integer)
            long       (32bit long integer)
            float      (floating point)
            double     (double-precision floating point)
            complex    (complex floating-point)
            string     (double-quoted string, like "foo")
            dcomplex   (complex double-precision floating)
            uint       (unsigned 16bit short integer)
            ulong      (unsigned 32bit long integer)
            long64     (64bit long integer)
            ulong64    (unsigned 64bit long integer)

     Type and dimension sizes are separated by (single or multiple) tabs or spaces.
     The ordering of dimensions follows the standard standard IDL/Fortran index
     ordering (from the most to the least fast index, i.e. column-major format in the
     2D-array case).

     The array values start form the second non-comment line. The number of array values
     per line is arbitrary and can be different line by line.
     No comment or blank lines or pending comment are allowed among array values and
     between the first value and the type and dimension size line.
     The ordering of the array values follows the IDL/Fortran ordering (column-major format
     in case of 2D-arrays), with the first index running faster than the second, the second
     runnig faster than the third, etc..

     If type is string, the array string items are not limited by single or double
     quotes. The whole line (including leading or pending spaces) is consideres as
     correct array item value.

     Hexadecimal format is NOT supported for content of int, long, uint, ulong,
     long64 and ulong64 types, yet.
     Complex and dcomplex types are not supported, yet.

     FORMAT HISTORY:
       11 Dec 2003: Created by A. Riccardi riccardi@arcetri.astro.it
       30 May 2004: Help modified: NO hex format supported

(See utilities\read_ascii_array.pro)

## READ_ASCII_STRUCTURE

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

     NAME:
            READ_ASCII_STRUCTURE

     PURPOSE:
            The READ_ASCII_STRUCTURE function reads a text file containing the definition
            of a structure. See below for format definition of the text file.

     SYNTAX:
            struc = read_ascii_structure(filename)

     RETURN VALUE:
            returns the structure defined in filename. In case of error the return
            value is undefined.

     ARGUMENTS:
       filename:  scalar string containing the name of the text file that contains the
                  sructure definition. The file has to have the ".txt" extension.

     DEFINITION OF THE FILE FORMAT

     The format of a text file describing a structure is the following:

     ;optional comment or blank lines
     name1   type1   content1 ;optional description
     ;optional comment or blank lines
     name2   type2   content2 ;optional description
     ...
     ;optional comment or blank lines
     nameN   typeN   contentN ;optional description

     Empty lines or lines having ";" or "#" as first non-blank character (optional
     comment lines) are skipped.

     Fields are separated by (single or multiple) spaces or tabs.

     name: valid IDL variable name
     type: one of the following case insensitive strings:
            array      (see 'Content of array' section)
            byte       (content is a scalar byte)
            int        (content is a scalar 16bit short integer)
            long       (content is a scalar 32bit long integer)
            float      (content is a scalar floating point)
            double     (content is a scalar double-precision floating point)
            complex    (content is a scalar complex floating-point)
            string     (content is a double-quoted string, like "foo")
            structure  (see 'Content of strcture' section)
            dcomplex   (content is a scalar complex double-precision floating)
            uint       (content is a scalar unsigned 16bit short integer)
            ulong      (content is a scalar undigned 32bit long integer)
            long64     (content is a scalar 64bit long integer)
            ulong64    (content is a scalar unsigned 64bit long integer)

     Content of int, long, uint, ulong, long64 and ulong64 types can be
     given in hexadecimal format pre-pending x (or X), like x1F8C
     Complex and dcomplex are not supported, yet.

     CONTENT OF ARRAY
     The content of an array can refere to an external file or can be specified in-line.

     In the first case we have two possibilities: text files or FITS files. In case of text
     files the content is a double-quoted string addressing
     the array definition, like "./conf/array.txt". Only ".txt" extension is allowed.
     See read_ascii_array.pro help for a complete desription of the array definition format.
     Use unix-like ("/") directory separator.

     In case of FITS files the content is again a double-quoted string addressing
     the FITS file, like "./conf/array.fits" or "./conf/array.fts". Only ".fits" or ".fts"
     extensions are allowed. Use unix-like ("/") directory separator. Astrolib is required.

     The content of small arrays can be defined in-line using the same format used for
     array definition files:

     varname  array  ; no content after array string
       (array definition, see read_ascii_array help)
     end

     CONTENT OF STRUCTURES
     The content of a structure can refere to an external file or can be specified in-line.
     In the first case the content is a double-quoted string addressing
     the structure definition, like "./conf/struc.txt". The format is the same described in
     this help. Only ".txt" extension is allowed. Use unix-like ("/") directory separator.
     The content of small structures can be defined in-line using the same format used for
     structure definition files:

     varname  structure  ; no content after array string
        ... (structure definition, see above)
     end

     Example:

     ;start of structure definitin file
     name   string "test" ;string definition
     var    float  1.2    ;float definition
     struc1 structure "./struc.txt" ; indirect structure definition

     struc2 structure     ;in-line structure definition
         aa     int    5  ;int definition
         dd     double 6d0;double definition
     end                  ;end of in-line structure definition

     mat1   array  "./array.txt" ; indirect array definition

     mat2   array         ;in-line structure definition
         long 2 3         ;type and dimesion size definition
         123 233
         333 44
         6   1234
     end                  ;end of in-line structure definition

     ppp    ulong64 6457648638  ;unsigned 64-bit long int definition
     ; end of structure definition file

     HISTORY
      Created: 13 Dec 2003, A. Riccardi (AR), riccardi@arcetri.astro.it
    	04 Feb 2004		AR and M.Xompero (MX)
    					Fixed the bug in extensions retrieval.
       April 2005      D.Zanotti(DZ), comment unuseful keyword regex in row 279.

(See utilities\read_ascii_structure.pro)

## REORDER_MATRIX

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

     reorder a matrix of orthonormal modes with respect to a reference matrix of
     orthonormal modes

               modes: matrix of modes (by columns) to reorder
     reference_modes: matrix of reference modes (by columns)

     modes and reference_modes have to have the same number of rows
     Modes in both matrixes have to be normalized like follows:

     transpose(modes)##modes = Identity_matrix
     transpose(reference_modes)##reference_modes = Identity_matrix

     HISTORY:

     29 May 2003 written by A. Riccardi (Osservatorio di Arcetri, Italy)
                 riccardi@arcetri.astro.it

(See utilities\reorder_matrix.pro)

## SEP_PATH

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

     NAME:
        SEP_PATH

     PURPOSE:

        The SEP_PATH function separates the different components of a
        string containing a pathname. It returns the filename, a vector
        of subdirectories in which the filename should be located and the
        root directory, if present (in the Windows OS the latter contains
        the drive tag). The function works ONLY with the unix and Windows
        Operative System families.

     CATEGORY:

     CALLING SEQUENCE:

        filename = sep_path(path)

     INPUTS:

        path:      scalar string. The path string to process.

     KEYWORD PARAMETERS:

        ROOT_DIR:     named variable. Scalar string. The root or current
                      directory path. A disk specification is prepended
                      disk+root
                      in the path. A null string ("") if not defined in
                      path.
        SUBDIRECTORY: named variable. Vector of strings. The sequence of
                      subdirectories contained in path.

     OUTPUTS:

        filename:     scalar string. The filename if present in path,
                      otherwise a null string is returned.
                      Any trailing substring of path that doesn't end
                      with a directory-separator character is considered
                      to be a filename.

     MODIFICATION HISTORY:

        April 1999, written by A. Riccardi (OAA)

(See utilities\sep_path.pro)

## SET_DIAGONAL

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

     SET_DIAGONAL

     SET_DIAGONAL, A, Diag

     INPUT
     A:	matrice quadrata nXn
     Diag:	vettore di lunghezza n (diagonale da settare in A)

     OUTPUT
     In uscita la matrice A ha per diagonale Diag

(See utilities\set_diagonal.pro)

## SHIFT_AND_ADD

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

     SHIFT_AND_ADD

     this function returns the shift-and-add result of the input image cube

     saa_image = shift_and_add(image_cube, BACKGROUND=bg, /AVERAGE, IDX_HISTORY=idx_hist)

     image_cube:  input, real 3-dim array. image_cube[N,M,L]. L images of
                  size NxM

     BACKGROUNG:  optional input, real NxM array. Background to remove from
                  each image before processing it.
     AVERAGE:     If it is set, shift_and_add/L is returned instead of
                  shift_and_add

     IDX_HISTORY: optional output. named variable. The list of coordinates of
                  the peak value is returned in this variable

     HISTORY:
       05 Dic 2002. Written by A. Riccardi. INAF-OAA, Italy
                    riccardi@arcetri.astro.it
       06 Dic 2002. AR. IDX_HISTORY keyword added.

(See utilities\shift_and_add.pro)

## SINC

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

     sinc(x) = 1 if x eq 0
             = sin(2*!PI*x)/(2*!PI*x) otherwise

     it's the Fourier transform of Pup(x)= 1 if x le 1
                                           0 otherwise

     Aug 2003  A.R. fixed bug when x=[0]

(See utilities\sinc.pro)

## SURF_FIT

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

     NAME:
    	SURF_FIT

     PURPOSE:
    	This function determines a polynomial fit to a surface.

     CATEGORY:
    	Curve and surface fitting.

     CALLING SEQUENCE:
    	Result = SURF_FIT(x, y, z, idx_list, COEFF=coeff, ZOUT=zout, UPLUS=uplus, $
                    ZERN=zern, UOUT=uout, UMAT=u, ONLY_COEFF=only_coeff)

     INPUTS:
     	x:
       y:
       z:
       idx_list:

     OUTPUT:
    	This function returns a fitted array.

     KEYWORDS:
       ZERN:
       COEFF:
       ZOUT:
       UPLUS:
       UOUT:
       UMAT:
       ONLY_COEFF:

     PROCEDURE:
     	Fit a 2D array Z as a polynomial function of x and y.
     	The function fitted is:
      	    F(x,y) = Sum over i and j of kx(j,i) * x^i * y^j
     	where kx is returned as a keyword and i+j le degree.

     MODIFICATION HISTORY:
    	July, 1993, DMS		Initial creation

(See utilities\surf_fit.pro)

## SVP

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

     SVP

     computes the saturation vapour pressure over water in Pa.
     It is valid in the range 0-100C, it is but used beyond this
     range.

     svp = svp(t [, /KELVIN])

     t:     float scalar or vector. Temperature

     KEYWORDS:
       KELVIN: if it is set, the input temperature is in Kelvin.
               Default is Celtius degrees.

     HISTORY
       2002: written by G. Brusa, CAAO Steward Obs., USA
             gbrusa@as.arizona.edu

(See utilities\svp.pro)

## TELL_TYPE

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

    TELL_TYPE
    result = tell_type(n_type, F_TYPE=format_type)

     returns the name of the type code

    n_type: type codes return by the size function.

    KEYWORDS

     F_TYPE: return the format type associated to the n_type.

     HISTORY
     written by D.Zanotti(DZ)
     Osservatorio Astrofisico di Arcetri, ITALY
     zanotti@arcetri.astro.it

(See utilities\tell_type.pro)

## TEST_TYPE

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

     NAME:
           test_type

     PURPOSE:
           test_type returns 1B if the type of the parameter var
           is NOT equal to one of the types specified in the keywords.
           Otherwise it returns 0B.

     CATEGORY:
           Utility

     CALLING SEQUENCE:
           err = test_type(var)

     INPUTS:
           var:          variable to test.

     OPTIONAL INPUTS:
           None.

     KEYWORD PARAMETERS:
           BYTE:         if set test for a byte
           INT:          if set test for an integer
           LONG:         if set test for a longword integer
           FLOAT:        if set test for a single precision floating point
           DOUBLE:       if set test for a double precision floating point
           COMPLEX:      if set test for a single precision complex
           DCOMPLEX:     if set test for a double precision complex
           STRING:       if set test for a string
           STRUCTURE:    if set test for a structure
           POINTER:      if set test for a pointer
           OBJ_REF:      if set test for an object reference
           UINT          if set test for an unsigned integer
           ULONG         if set test for an unsigned longword integer
           L64           if set test for a 64-bit integer
           UL64          if set test for an unsigned 64-bit integer
           UNDEFINED:    if set test for undefined

           NOFLOATING:   if set tests for integer numbers, overriding
                           the BYTE, INT, LONG, UINT, ULONG, L64 and UL64 keywords.
           REAL:         if set tests for real numbers, overriding the BYTE, INT,
                           LONG, UINT, ULONG, L64, UL64, FLOAT and DOUBLE keywords.
           NOREAL:       if set tests for complex numbers, overriding
                           the COMPLEX and DCOMPLEX keywords.
           NUMERIC:      if set tests for any numeric data, overriding the BYTE,
                           INT, LONG, UINT, ULONG, L64, UL64, FLOAT, DOUBLE,
                           COMPLEX, DCOMPLEX, REAL, NOREAL, NOFLOATING keywords.
           DIM_SIZE:     a named variable to receive a long array.
                           Firt element: number of dimensions. Following
                           elements: the number of elements for each dimension.
                           The number of dimensions is 0 if var is a scalar,
                           or is undefined.
           N_ELEMENTS:   a named variable to receive a long scalar.
                           The total number of elements.
           TYPE:         a named variable to receive a long scalar.
                           The type of the input (see SIZE)

     OUTPUTS:
           err:          byte scalar. 0B if var match one of the
                         requested types, 1B otherwise

     OPTIONAL OUTPUTS:
           See keywords

     COMMON BLOCKS:
           None.

     SIDE EFFECTS:
           None.

     RESTRICTIONS:
           None.

     PROCEDURE:
           Use the SIZE function.

     EXAMPLE:
           if test_type(var, /LONG, N_ELEMENTS=n_var) then $
             message, "The variable is not a long"
           if n_var ne 1 then $
             message, "The variable must be a scalar"

     MODIFICATION HISTORY:
           May 1998. Written by A. Riccardi (AR). INAF-OAA, Italy
                     riccardi@arcetri.astro.it
           Dic 2002. UINT, ULONG, L64 and UL64 keywords added.
                     An error message added if an unknown data type code
                     is found.

(See utilities\test_type.pro)

## TIMING

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

     NAME:
           TIMING

     PURPOSE:
           This function compute time elapsed since last calling.

     CATEGORY:
           Utilities.

     CALLING SEQUENCE:

           Result = TIMING(T)

     INPUTS:
           T:      long integer variable. System time returned by last calling
                   of TIMING.

     OUTPUTS:
           Result: float. Time elapsed since last calling in minutes. If
                   T is undefined, Result is -1..

           T:      long integer. Updated to current system time for future use.

     RESTRICTIONS:
           If T variable is modified since last calling, the Result is uncorrect.

     EXAMPLE:
           Print the time needed to execute a sequence of stantments:

           Dummy = TIMING(T)
           ...
           ...
           ...
           PRINT, TIMING(T)

     MODIFICATION HISTORY:
           Written by:     A. Riccardi; Month, 1995.
           July, 1994      Any additional mods get described here.  Remember to
                           change the stuff above if you add a new keyword or
                           something!

(See utilities\timing.pro)

## TVSCL1

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

        TVSCL1

(See utilities\tvscl1.pro)

## TYPE2NBITS

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

     TYPE2NBITS

     the function returns the number of bits per elements of input data.

     n_bits = type2nbits(data, [TYPE=type])

     KEYWORDS

      TYPE:   optional named variable. On output contains the IDL code of the
              data type of input.

     HISTORY
       31 May 2004, written by A. Riccardi

(See utilities\type2nbits.pro)

## UNDEFINE

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

       UNDEFINE

      undefine the passed variable.

      undefine, var

      EXAMPLE

     IDL> a=1
     IDL> help, a
     A               INT       =        1
     IDL> undefine, a
     IDL> help, a
     A               UNDEFINED =

       HISTORY

     1999 created by A. Riccardi
     28 Jul 2004 Marco Xompero (MX)
      It undefines more variable in the same command line.

(See utilities\undefine.pro)

## UNION

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

     list_union = union(list1, list2)

     list1, list2: numeric scalar or vector or array
     list_union: union (without repeated elements) of the input lists

(See utilities\union.pro)

## WDEL

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

     NAME

      WDEL

     wdel

     delete all the windows currently defined.

     April 1999, A.R. (AOO)

(See utilities\wdel.pro)

## WIND_PSD

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

     WIND_PSD

     Kaimal Longitudinal Wind Turbulence: power spectral density (PSD) of wind
     speed fluctuations. The used formulation is valid for a few tens of meters
     from the ground (logarithmic profile of the stationary wind speed with
     respect to z)

     v_psd = wind_psd(f [, z [, v10]] [,ROUGHNESS=z0] [,STATIONARY_SPEED=v])

     f:      real-number scalar or vector. (input) Temporal frequency vector
             in [Hz]
     z:      real-number, scalar. (optional input) Height from the ground [m].
             Default value is 10.0m.
     v10:    real-number, scalar. (optional input) Stationary wind speed at 10m
             from the ground [m/s]. Default value 10.0m/s.
     z0:     real-number, scalar. (optional input) roughness constant [m], 0.01-0.1m
             for open grassland, 0.3-1.0m for forest and suburban areas.
             Default value: 0.3m

     v_psd:  real-number, same size of f. (output) Wind speed PSD [N/m^2]

     STATIONARY_SPEED: named variable. (optional output) sationary wind speed at
                       height z. [m/s]

     HISTORY

      11 Dec 2002, written by A. Riccardi, INAF-OAA
                   riccardi@arcetri.astro.it

(See utilities\wind_psd.pro)

## WRITE_ARRAY_ASCII

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

    Write_array_ascii, vector, FILENAME=filename
    Purpose:
     Write an array in an ascii file txt
    INPUT:
     vector: array to write in tne file
    KEYWORD
     FILENAME: name of file where writes the array in ascci format.
    HISTORY
     created by D.Zanotti(DZ)
      Osservatorio Astrofisico di Arcetri, ITALY

(See utilities\write_array_ascii.pro)

## WRITE_LABELS

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

        WRITE_LABELS

        WRITE_LABELS, Label_file

        Label_file: name of the file where store coordinates and labels in.

     History

       Sometime, created by A. Riccardi, Osservatorio astrofisico di Arcetri (Italy)
       21 Oct, 2002 - free_lun is used instead of close

(See utilities\write_labels.pro)

## WRITE_STRUCT

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

    WRITE_STRUCT
    err = write_struct(unit_s, struct_value, name_str)

    PURPOSE:
     Writes a in-line struct in a text file, if the in-line struct
     cointains an array or another struct, for the struct another
     text file is created and  refered in the source text file.

    unit_s: The unit number associated with the opened file.
    struct_value: the structure to write in the file txt.
    name_str: name of the structure

    KEYWORDS
     None.

     HISTORY
     written by D.Zanotti(DZ)
     Osservatorio Astrofisico di Arcetri, ITALY
     zanotti@arcetri.astro.it

(See utilities\write_struct.pro)

## WRITE_STRUCTURE_ASCII

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

    WRITE_STRUCTURE_ASCII, name_struct, FILENAME=filename

    PURPOSE:
     writes a structure in a file text in order to the text definition
     format.

       name_struct: The structure to write in the text file.

     KEYWORDS:
       FILENAME: the name of text file, if not set a default_name is
       used.

     HISTORY
     written by D.Zanotti(DZ)
     Osservatorio Astrofisico di Arcetri, ITALY
     zanotti@arcetri.astro.it

(See utilities\write_structure_ascii.pro)

## WRITE_STRUCTURE_MAP

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

    WRITE_STRUCTURE_MAP

    write_structure_map, name_struct, FILENAME=filename

    PURPOSE
      writes a structure of  address map in a text file.

    name_struct: address map structure to write.

    KEYWORDS
    FILENAME: name of txt file.

    HISTORY:
    written by D.Zanotti (DZ)
    Osservatorio di Astrofisico di Arcetri
    zanotti@arcetri.astro.it

(See utilities\write_structure_map.pro)

## XSHOW

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

     NAME:
       XSHOW

     PURPOSE:
       Wrapper to IMAGE_SHOW with zoom capabilities.
       Display min and max values of the input vector
       Left-click and drag to zoom
       Middle-click to unzoom
       Rigth-click to popup contect menu:
           -  save in jpg format
           -  show info window
           -  quit

     CATEGORY:
       General graphics.

     CALLING SEQUENCE:

     xshow, input, x_vec, y_vec, /LABEL, ZOOM_SCALE=zoom_scale, XSIZE=xsize,
          YSIZE=ysize, KEYWORDS  with the KEYWORDS of IMAGE_SHOW

     INPUTS:
       input:  If x_vec and y_vec are not present, "input" is the two-dimensional array
               to display. If x_vec and y_vec are present, "input" is a vector of values
               of the map to dispaly in the corresponding irregular grid defined by x_vec
               and y_vec.

       x_vec, y_vec  cannot be used when "input" is a two-dimensional array. If they are
               defined, they have to be vectors with the same size as "input". In the last
               case TRIGRID is used to obtain a regular gridded two-dimensional array
               to display.
     KEYWORDS:
       ZOOM_SCALE: if set, change the limit of the lookup table according to the zoom view.
                   Otherwise constants limits are used. See MAX(MIN)_VALUE in IMAGE_SHOW

       LABEL: If set display a status bar with selected pixel (coords and value) and
              with minmax of input (coords and value)

       XSIZE: Set width of the window

       YSIZE: Set height of the window

     OUTPUTS:
       No explicit outputs.

     COMMON BLOCKS:
       None.

     SIDE EFFECTS:
       The currently selected display is affected.

     RESTRICTIONS:
       None.

     MODIFICATION HISTORY:
       22 May 2005  written by Lorenzo Busoni (LB)
       23 May 2005  A. Riccardi (AR), multiple instances bug fixed
       24 May 2005  LB, window resize handling and zoombox display added
       25 May 2005  LB, color table is stored in the parameter structure
                        info window added
                        XSIZE,YSIZE added
       26 May 2005  LB, save_jpg and small zooms bugs fixed

(See utilities\xshow.pro)

## XYPLOTERR

[Previous Routine] [List of Routines]

     NAME:
    	XYPLOTERR

     PURPOSE:
    	Overplot data points with accompanying error bars for x and y.

     CATEGORY:
    	Plotting, 2-dimensional.

     CALLING SEQUENCE:
    	OPLOTERR,  X,  Y , ErrX, ErrY, PSYM=Psym

     INPUTS:
    	Y:	The array of Y values.

    	Err:	The array of error bar values.

     OPTIONAL INPUT PARAMETERS:
    	X:	An optional array of X values.  The procedure checks whether
    		or not the third parameter passed is a vector to decide if X
    		was passed.

    		If X is not passed, then INDGEN(Y) is assumed for the X values.

    	PSYM:	The plotting symbol to use (default = +7).

     COMMON BLOCKS:
    	None.

     SIDE EFFECTS:
    	None.

     RESTRICTIONS:
    	Arrays cannot be of type string.  There must be enough points to
    	plot.

     PROCEDURE:
    	A plot of X versus Y with error bars drawn from Y - ERR to Y + ERR
    	is written to the output device over any plot already there.

     MODIFICATION HISTORY:
    	William Thompson	Applied Research Corporation
    	July, 1986		8201 Corporate Drive
    				Landover, MD  20785
           kdb, March, 1997  - Fixed a problem if 1 element arrays where used.

(See utilities\xyploterr.pro)