ModlDoc.txt  D. Aberdam
version 1.2 : 6 nov 1995

1. Algorithm
   Normally you do no need to use this item. The default algorithm is
   the minimization algorithm. The other algorithm, test_deriv, is intended
   to check for the correctness of the derivatives of the EXAFS function
   with respect to the EXAFS parameters.

2. Read_data (in directory  c:\...\exafs\fitt\data\ )
   It is not necessary to read a data_file. If you do not read a data_file,
   you are allowed to make only simulations. Otherwize, you read both
   the shell contribution to k**n*khi(k) obtained by Fourier filtering
   and the "raw" k**n*khi(k).
   Minimization may be operated with respect to the Fourier filtered signal
   or with respect to the raw signal.

3. Parameters (in directory c:\...\exafs\fitt\par\ )
   Here you read the whole set of EXAFS parameters necessary to simulation
   or optimization. You can read the parameters either from a file *.par
   or from the keyboard, if no file exists. It is recommended to create
   such a file, because it helps saving time and reduces the possibility
   of errors.
   Parameter frwd is 0 or 1. it is useful when studying the exafs from a
   metallic second_shell atom which is 'viewed' by the absorber atom through
   a light atom of oxygen. In that case, setting frwd to 1 tells the program
   to take into account the scattering properties of oxygen in the forward
   direction.

4. Standard_deviation of data (sigma)
   The SD are a necessary input to appreciate the quality of the optimization.
   The SD of EXAFS spectra are not easily transposable
   to elaborated k**n*khi(k), and still less easily to Fourier_filtered
   shell_contributions.

   A bad solution is to set artificially sigma's using simple formulae
   such as a constant or a power of k etc...

   A less bad solution is to compute sigma's for "raw" k**n*khi(k)
   with reference to the Fourier_filtered shell signal.
   This works best when the Fourier_filtered shell signal includes
   the contributions of all the shells whose contribution is significant.
   Otherwize it works poorly.

   The sigma's computed in this way reflect the statistic of data acquisition.
   In effect, if spectra are added to built the "raw" k**n*khi(k), the noise
   decreases, and the sigma's computed with reference to the smooth Fourier_
   filtered data are smaller.

   To be useful, this set of computed sigma's must be modified to eliminate
   sigma values close or equal to zero.
   If a sigma value is zero, the program stops because division by sigma is required.
   If a sigma value is close to zero, the weight 1/sigma of the corresponding data point
   is very large so that the corresponding fitted point must be very close to it.
   If not, the quality factor will diplay a very small, not sensible value.

   This operation is done by computing a smoothing of the sigma's 
   using cubic-spline smoothing, until it looks "reasonably" smooth, 
   that is with no inflexion point.

   Whatever the mode of buiding sigma's, they are recorded in a file
   named sigm_exp.dat located in the exafs\fitt\data\ directory.
   This file is over-writed at every run of the program.
   
5. Read Amplitudes and Phases
   Amplitude and phases involved in the scattering of electrons by the absorber
   and the scattering atoms are required to simulate EXAFS Spectra.
   The program allows you to read either McKale, Feff or Reference (Ref) 
   Amplitudes and Phases.
   The input required prior to read is the atomic number of
   the absorbing atom. 
   The atomic numbers of scattering atoms is read in the *.par file, 
   in increasing shell order.
   McKale data are located in the Kale sub_directory.  
   Feff data are located in the Feff sub_directory.
   Reference data are located in the Ref sub_directory.
   Ref files are accompanied by a set of reference parameters 
   (r,nv,dE0,sig, etc...). 
   When reading Feff files, you are prompted to enter (via the keyboard)
   those parameters which are not already set when reading the fEFF file.
   Getting a set of Reference or Feff parameters allows you to take advantage 
   of the phase and amplitude decorrleation routines, much more useful than 
   the minimization routine, in analyzing a single shell.
   The electron mean free path, the amplitude and phase functions are interpolated
   on the experimental momentum grid.
   The interpolated amplitude and phase may be displayed and recorded 
   in ascii files (.ixx).
   Feff phases are determined modulo Pi. It may happen that the simulation of 
   your data (see 6 below) is out of phase. Then answer Yes when prompted to
   shift the Feff phases by Pi. 

   When you tell the program to read Reference amplitudes and phase, 
   it looks for a  file whose name is built as follows : 
   (atomic number of absorber)_(atomic number of scatterer)_(shell index).ref;
   ex : 78_29_1.ref for platinum as an absorber, copper as a scatterer,
   in the 1rst shell.
   If such a file is not found, the program asks for a different fileName.

6. Simulation
   Computes the simulation with the given paramaters.
   You are allowed to change parameters prior to Simulation.
   You are then prompted to select graphically the min and max k values
   for the foregoing optimization or parameter decorrelation. 

   The Inelastic Electron Mean Free Path, IEMFP, alias lambda, is parametrized
   by three parameters, Gam, Eta and Bta according to the formula : 
   lambda = (1/gam) * ( (Eta/k)**4 + k + Bta*k**2 ). 
   The formula is standard, apart the term Bta*k**2 which has been added 
   to fit properly lambdas computed by Feff. 
   It is recommended to avoid fitting lambda's parameters, 
   because the number of parameters then becomes too large. 
   However, it may be useful to adjust these parameters for a series of analyses.
     
7. Extract Amplitudes and Phases
   Use this when you want to extract Ampl and Phases from a signal
   given by a reference material,
   in view of use them to analyse spectra from an unknown material.
   In that case, you have to input parameters which are those of your reference material.

   Some of these parameters (r,Nv) are supposed to be known and input as such.

   dEo must be set to zero to avoid inconsistent shifts of k scales.

   For some of them, (sg2, gam, eta, bta ...) you may be tempted to perform first 
   an optimization. But do not forget : they are in principle known parameters.
   For example, if you do not know "sg2Ref", you put an arbitrary sensible value.
   Similarly, you put sensible values gamRef, etaRef, btaRef for the mean free path.

   The same holds for reference phases and amplitudes read from a feff file. 
   In that case, r, nV, sig are requested. the program automatically sets de to 0,
   and computes gam, eta, bta by fitting the lambda table. 

   The reference amplitude and phase functions are unraveled from these particular
   values of the parameters in order to be comparable to functions computed
   on theoretical bases. In that way, the parameter_values you will get from
   subsequent optimizations are "absolute" values. 
   In particular, the reference amplitude is that of khi(k) and not that of k**n * khi(k);

   Finally, Phases are determined modulo Pi. If it happens that the simulation of 
   your reference data with the extracted amplitude and phases is out of phases, 
   the program shifts automatically the phases by Pi.   
 
 8.DeCorrelation of phases
   The difference phase function phaseDat-phaseRef should extrapolate to
   zero for zero momentum. If it does not, it means that both r and dE0 parameters
   are wrong in the simulation of data.
   In this menu item, the program computes guest_values for r and dE0 such
   that the difference phase funtion extrapolates to zero.
   The program computes a quantity C0(sample)-C0(ref) which will be used
   in the next Menu Item to make a correction on the number of neighbours.

   In the case of disordered samples, the linear fit to the phase difference
   may be replaced by polynomial fitting from which a series of cumulant are computed. 

 9.DeCorrelation of amplitudes
   The logarithm of the ratio of amplitudes amplDat/amplRef, for identical
   values of the mean free path parameters, extrapolates to the zero
   momentum axis at a point with ordinate ln(nV(sample)/nV(Ref))+C0(sample)-C0(ref).

   linear fitting (in k**2 scale) gives the ordinate intercept, from which an improved
   value of the number of neighbours in the sample is deduced.

   The program also computes an improved neighbour distance of the shell atoms 
   in the sample under study using equation r(sample)=C1 + 2*(C2/C1) * (1+C1/lambda);
   The coefficient of the term in k**2 in the lisear fitting
   gives the difference sig**2(sample)-sig**2(ref), from which an improved
   value of sig(sample) is obtained.
   
   In the case of disordered samples, the linear fit to the log of amplitude 
   ratio may be replaced by a polynomial fitting from which a series of cumulant 
   are computed. The Exafs simulation is the computed in terms of the cumulant expansion. 

   Whatever be the fitting of the phase difference and amplitude ratio (linear or not)
   the resulting effective parameters are computed, and there is NO NEAD of going 
   to the minimization routine.  

10.Optimization
   Use this routine for multi-shell analysis, or when using Mckale's tables. 
   Polarization effects are not included in the present version.
   May be performed against either the Fourier_filtered signal
   or the "raw" k**n*khi(k).
   You may fix or vary parameters, or link parameters by a linear constraint
   using the arrow block of the keyboard. par^[ i ]:=add^[ i ] + (mult^[ i ]*base^[ i ])
   where base^[ i ]=par^[ j ].
   The maximum number of parameters you are allowed to vary is computed
   from the Shannon theorem. (These Michalowicz)
   It is displayed before you decide which parameter to vary.

   Parameters for the optimized model are displayed with their standard deviation,
   i. e. the square root of their total variance (diagonal elements of covariance matrix),
   corresponding to a probability p=0.683 to find the "true" value
   of the corresponding parameter in the given interval.
   Warning : this standard deviation is not dependent on the actual value of  the 
  "experimental standard deviation", the sigma's of  4, but only on its derivative with
    respect to k. To estimate the global uncertainties, it is necessary
   to go to the "correlation" item in the program menu,  8.

   The Curvature matrix, the raw and normalized Covariance matrices,
   the eigen values and eigen vectors
   are displayed to examin the effects of correlations.

   Standard_deviations for single parameters are computed according to 
   Numerical Recipies, chap 14, 1986 edition.
   They are obtained from the Covariance matrix for nv=1 variable parameter, 
   corresponding to nf degrees of freedom nf=(2*deltaR*deltaK / pi) - nv. 
   One then computes dki2 such that the probability of a chi-square variable
   with nFreedom degree of freedom being less than dki2 is p=0.683.
   dki2 is obtained from a bisection algoritm rtbis(nv,p,0.5,100,1e-3)
   calling the function GAMMQ(nf/2,dki2/2).

   Std_Dev[par[i]] = sqrt(dki2) * sqrt(cov[i,i]).

   Quality factor QF is also computed according to Numerical Recipies, 
   same reference. Chi2 is the sum of (the square of the differences 
   between model and experimental curves divided by the square of the 
   statistical uncertainty relative to each experimental point, sigma2).
   Be careful, sigma2 has nothing to do with Debye-Waller factor. 
   
   Chi2 = sum[(sqr(yfit-yexp))/sigma2]
   With the same notations as above, n being the number of experimental points,
   Chi2_Red  =   Chi2 / (n-nv)
   QF=GammQ((nf-2)/2,Chi2_Red/2). 

11.Correlations
   This is to display more accurately the correlations between pairs of parameters,
   and to evaluate more realistically the uncertainties on the parameter values.
   The program draws elliptic contours of confidence for the probability p=0.683,
   and is able, too, to compute "actual" contours from a grid, at the cost
   of a significant increase of computing time required by the computation
   of the function on the grid.
   If you want for example an estimate of the uncertainty on nV, the number 
   of neighbours, you proceed as follows : 
   display the correlation ellipses of nV with any other parameter to which 
   it may be significantly correlated, say sg2, gam, etc.
   Select the largest delta_nV obtained in these operations, as the estimate
   of the uncertainty. This estimate includes the contribution of the 
  "experimental standard deviation". Its dependends on the actual value of this
   quantity, not only on its variations with respect to k. 

12.F_T of simulation
   Useful to check whether the parameters output from the optimization
   or input in the simulation are reasonable. The F_T of the raw simulation
   or of the optimized simulation is compared to the F_T of the EXAFS data.
   The F_T of the difference (Simulation minus Data) is also computed.

