Function:     FITGAUSS2D

Purpose:      Fit 2d-gaussian to data in a box

Category:     MATH

File:         fitgauss2d.c

Author:       M. Vogelaar

Notes:        The function FUNC and the subroutine DERV for a 2-dim 
              gauss must be defined outside this function.

Use:          INTEGER FITGAUSS2D( 
                                DATAI,      Input          REAL ARRAY
                                NDATX,      Input          INTEGER
                                NDATY,      Input          INTEGER
                                GRIDX,      Input          DOUBLE PRECISION
                                GRIDY,      Input          DOUBLE PRECISION
                                PARLIST,    Input/Output   REAL ARRAY
                                ERRLIST,    Output         REAL ARRAY 
                                MPAR,       Input          INTEGER ARRAY
                                TOL,        INPUT          REAL
                                ITS,        INPUT          INTEGER
                                LAB,        INPUT          REAL 
                                CLIP        INPUT          REAL ARRAY )
                                
                               
                              
             FITGAUSS2D 
                  >=0: Fit found, return fit parameters in PARLIST, errors
                       in ERRLIST. FITGAUSS2D is the number of iterations
                       returned by the least squares fit routine.
                   -1: Too many free parameters, maximum is 32.
                   -2: No free parameters.
                   -3: Not enough degrees of freedom.
                   -4: Maximum number of iterations too small to obtain a 
                       solution which satisfies TOL.
                   -5: Diagonal of matrix contains elements which are zero.
                   -6: Determinant of the coefficient matrix is zero.
                   -7: Square root of negative number.
                   -8: Fit aborted because array size exceeds maximum
                       (128*128).
                   -9: Fit aborted because all data are blank.
                  -10: Length box equals 1 in x or y direction.
                  -11: Position of (gauss) maximum not in this box.
                  -12: Sum of data values equals 0.
                  -13: Initial estimate amplitude and zero level are mot
                       different.
                  -14: FWHM in x or y direction smaller than 0

             NDATX     Length of DATAI in X direction
             NDATY     Length of DATAI in Y direction
             GRIDX     Grid spacing in X
             GRIDY     Grid spacing in Y
             PARLIST   On input, these can be initial estimates for the fit.
                       If however, one of the values is blank on input, the
                       function calculates initial estimates. The return 
                       values are the fit parameters. The array elements are:
                       1) Amplitude in map units
                       2) FWHMx, Full width at half maximum in physical
                          coordinates in x-direction.
                       3) FWHMy, FWHM in y-direction.
                       4) X0, centre x-coordinate as offset in physical 
                          coordinates wrt. lower left corner of box,
                          usually centre in pixels times grid spacing.
                       5) Y0, centre y-coordinate.
                       6) angle in RADIANS wrt. positive X-axis!
                       7) zero level in map units
             ERRLIST   List with error estimates, in the same order as 
                       FITLIST, as calculated in a least squares fit.
             MPAR      For each of the 7 parameters in the 2d-gauss fit, this
                       mask determines whether the parameter is free 
                       (MPAR(n) = 1) or fixed (MPAR(n) = 0) in the fit.
             TOL       Relative tolerance. LSQFIT stops when successive 
                       iterations fail to produce a decrement in reduced 
                       chi-squared less than TOL. If TOL is less than the 
                       minimum tolerance possible, TOL will be set to this 
                       value. This means that maximum accuracy can be 
                       obtained by setting TOL=0.0.
             ITS       Maximum number of iterations in fit routine.
             LAB       Mixing parameter, LAB determines the initial
                       weight of steepest descent method relative to
                       the Taylor method. LAB should be a small
                       value (i.e. 0.01). LAB can only be zero when
                       the partial derivatives are independent of
                       the parameters. In fact, in this case LAB
                       should be exactly equal to zero.
             CLIP      Two values. The first value is a lower threshold 
                       and the second an upper threshold to the 
                       data that will be used in the fit. Examples:
                       1) Use only values between 2 and 4 (2,4 included):
                          CLIP(1) = 2 and CLIP(2) = 4 
                       2) Use values lower than (and equal to) 2:
                          CLIP(1) = BLANK and CLIP(2) = 2
                       3) Use values greater than (and equal to) 2:
                          CLIP(1) = 2 and CLIP(2) = BLANK
                       4) Use all values in the box:
                          CLIP(1) = BLANK and CLIP(2) = BLANK
                       
                          
                       

Update:       Sep  14, 1992: VOG, Document created.