----- file created by makedoc on: Thu Sep 11 15:03:14 2014
----- Documentation for /scisoft/xop2.4/extensions/shadowvui/src/lib/waviness_calc.pro -----

 NAME: 	WAVINESS_CALC

 PURPOSE:      This program generates a random error surface

               (XSH_WAVINESS implements a Graphical Interface)

               The main method for slope errors (called hereafter waviness) is 
               described in: 
                  M. Sanchez del Rio and A. Marcelli,
                  NIM-A319 (1992) 170-177
                  http://dx.doi.org/10.1016/0168-9002(92)90550-N
 
               An alternative method (called hereafter harmonic_sum) consists
               in a simple sum of harmonics:
                 z = \sum_{n=1}^{N} {b_n cos( 2 \pi l/L + \psi_n) }

                 (see e.g., Eq 11 in Shi et al, J Synchrotron Rad. 21 (2014)
                  http://dx.doi.org/10.1107/S160057751400650X )

               The switching of one or another method is done via the
               sign of "Estimated Slope Error RMS [arcsec]" in the 
               input interface, or input_str.slp in the input structure,
               Set >0 for waviness, <0 for harmonic_sum

 CATEGORY:     SHADOW tools
	
 CALLING SEQUENCE:
	waviness_calc,input_str,out
 INPUTS:
	input_str: a structure with the inputs, as created by waviness_read():
                  or defined in the interface xsh_waviness:
                IDL> help,/str,waviness_read(/default)
                ** Structure <11d0958>, 11 tags...
                   FILE            STRING    'waviness.dat'
                   NPOINTX         LONG               100
                   NPOINTY         LONG               100
                   WIDTH           FLOAT           20.1000
                   XLENGTH         FLOAT           113.100
                   N               LONG                60
                   SLP             FLOAT          0.900000
                   ISEED           LONG          97865651
                   C               DOUBLE    Array[5001]
                   Y               DOUBLE    Array[5001]
                   G               DOUBLE    Array[5001]

                For the default method (waviness):

                   FILE: name of the output file
                   NPOINTX number of points along mirror width
                   NPOINTY number of points along mirror width
                   XLENGTH is the mirror length (apologies for the X)
                   WIDTH is the mirror width
                   N is n_max in Eq.8 (see reference)
                   SLP estimation of the target slope error RMS in arcsec
                       for the default method (waviness). Must be >0
                       For the other method (see later) it must be negative,
                   ISEED seed to initializa random generator
                   C an array of coeff C_n in Eq. 9. 
                     Only the first N+1 indices are read.
                   Y an array of coeff y_n^0 in Eq. 8 normalized.
                     This is the initial constant shift. 
                     One means the profile can be shifted to any position 
                     along the mirror length. Zero means no initial shift.
                   G an array of coeff g_n (random shift) in Eq. 8 normalized.
                       

                For the alternative method (harmonic_sum): 

                   To use this method, SLP must be set negative. 
                   In this method the profile is:
                   z(y) = \sum_{n=1}^{N}
                    { b_0 n^{g_n} cos( 2 \pi (0.5+(y/L) + r_n y_g ) }
                   or in other words, a sum of N harmonics with a power
                   law of exponent g_n.

                   y is the coordinate along the mirror, with zero in the 
                     mirror center.
                   b_0 is a constant equal to abs(SLP) [labeled
                      "Estimated Slope Error RMS [arcsec]" in the interface.
                   g_n is the exponent of n stored in G for each harmonic
                   L is the mirror length XLENGTH
                   r_n is a random value in [0,1) for each harmonic
                   y_g is a normalized interval to apply the random shift
                     stored in Y. 0 means no random shift, 1 means shift in 
                     the full mirror length.
                   Note that in this method C[0],Y[0] and G[0] are not used
                     as summation index starts with one.
 
 OUTPUTS:
       a file with the generated surface in SHADOW/PRESURFACE format

 OPTIONAL OUTPUTS:
	out: a structure with the surface {x:x, y:y, z:z}

 KEYWORDS
       nowrite: if set does not write file for SHADOW. Default: nowrite=0, 
                thus a file with the name defined in the input structure
                is written with the surface in the SHADOW-PRESURFACE format.
	slopes = a flag to calculate the slop error values via slopes(out).
                If set, the following keyword received the calculates data:
       valslopes = an 4-dim array with slope errors RMS in 
                   [X_arcsec,Y_arcsec,X_urad,Y_urad]
       dataslopes = an (2,NX,NY) array with slope errors in rad along 
                    X (in dataslopes[0,*,*]) and Y (in dataslopes[1,*,*])

 MODIFICATION HISTORY:
			June 1991	first version
			September 1991	update 
			October 1991	moved to Sun
			September 1992	distribution version
			February 2006	translated to IDL (srio@esrf.fr)
			2014-09-09 srio@esrf.eu dimensionated to 5000pts.
                                added new method (SLP<0). Added doc.


