*   last visit 29.Jul.2002 18:05:52   by sturhahn
*
*********************************************
*
*  CONUSS Version 1.5
*  (C) Copyright 1996, Wolfgang Sturhahn.
*  All rights reserved.  
*  Unauthorized reproduction prohibited.
*
*********************************************
*
*  the file's directory :
*    $CONUSSHOME/examples/NFS
*
***********************************************************
*                                                         *
*  Purpose :  This file explains shortly the setup that   *
*             defines the CONUSS input parameters and     *
*             what has to done to obtain a simulation     *
*             of the measured time spectrum               *
*  Date    :  May 12, 1996                                *
*  Author  :  Wolfgang Sturhahn                           *
*                                                         *
*  Adress  :  Dr. Wolfgang Sturhahn                       *
*             Argonne National Laboratory                 *
*             Advanced Photon Source                      *
*             9700 South Cass Avenue                      *
*             Argonne, IL 60439, USA                      *
*  PHone   :  +1 630 252 0163                             *
*  FAX     :  +1 630 252 0161                             *
*  E-Mail  :  sturhahn@aps.anl.gov                        *
*                                                         *
***********************************************************
*
*  CONUSS file naming convention:
*
*   RIF  =  Relaxation data Input File
*   DIF  =  Distribution data Input File
*   MIF  =  Material data Input File
*   SIF  =  Standard Input File
*   TOF  =  Transmission data Output File
*   SOF  =  Standard Output File
*   LOF  =  LOg File
*   ROF  =  Reflectivity data Output File
*   IOF  =  Intensity data Output File
*   GOF  =  Graphical data Output File

The experiment that is evaluated by the help of CONUSS in
this directory was to observe the time spectrum of an foil
of alpha-iron using synchrotron radiation.
The foil was magnetized by a small external field that was
parallel to the sigma polarization of the incident radia-
tion. The thickness of the foil was not exactly known. The
foil was 95% enriched in 57Fe.

The given execution times may vary due to the performance
of your system. I used a Sun SPARCstation 20 for the
calculations. 

The properties of the scatterer (the iron foil) are defined
in the MIF 'alfe_in'. I will discuss the valid lines of the MIF:

(1)..(12)  general properties of the MB nucleus 57Fe and
           the associated MB transition
(13)       the Debye temperature of the alpha-iron lattice
           is set to 440K. 
(14)       the temperature of the foil during the experiment.
           The ML factor will be calculated using the Debye-
           model with the temperatures (13) and (14).
(15)..(20) the unit cell that is defined here does not 
           describe the actual structure of alfa-iron but
           defines the volume that one iron atom occupies if
           you assume the density of iron to be 7.86g/cm**3.
(22)       the abundance of 57Fe in this foil is set to 0.95.
(25)       I assume the hyperfine field at each nucleus to
           point in the same direction as defined by the
           external field. Therefore averaging is not needed.
(26.1.6)   the magnetic hyperfine field is set to 33T.
(26.1.9)   the angle between magnetic hyperfine field and
           external magnetic field is set to 180deg. An in-
           crease of the external field will then decrease
           the total magnetic field.
(26.1.18)  the sample is completely magnetized and therefore
           the texture is 100%.
(26.1.20)  the position of the one atom that occupies the
           unit cell as defined by (15)..(20) is actually
           of no concern. It is set arbitrarily.
(27)       there is no other type of atom present than iron.
           
For more information about the meaning of each input line
please visit the 'CONUSS Users Manual'.

*
***********************************
*                                 *
*  first step     :  run 'kref'   *
*  execution time :  2.5s         *
*                                 *
***********************************
*

Run 'kref' first by typing it as command. The module will
read its SIF 'in_kref' and the MIF.
It will produce a ROF, a SOF, and a LOF. The TOF contains
the normalized transmitted electric fields as a function
of energy, thickness, and polarization.
I will discuss some input lines of the SIF:

(1)        name of the MIF
(4)        in this case we run the module in forward
           scattering mode
(5)..(7)   these data is of no concern
(8)..(10)  if you use a crystal you may define the orienta-
           tion of the surface accurately. In the case of
           a foil you can make a choice but it should not
           be the null vector.
(11),(12)  as before this value is of no concern for a non-
           crystalline sample
(13)       this angle is taken between the surface normal
           (8)..(10) and the external magnetic field. 90
           deg. means the field is in the surface. The
           direction of the external field also defines
           the polarization reference vectors. Sigma 
           polarized radiation has its electric field vector
           perpendicular to external field and the direction
           of the incident beam.
(15)..(16) energy range for the calculations. The splitting
           observed from an iron foil is about +-55gamma.
           By choosing +-200gamma for the range I make shure
           that the tails of the outer lines will be included.
           This value might be too small if you use foils
           with very large effective thicknesses.
(18)..(20) thickness range for the calculations. Here I
           assume that the thickness of the foil is some-
           what like 7micron and I calculate a +-2micron
           range.
           
For more information about the meaning of each input line
please visit the 'CONUSS Users Manual'.

*
***********************************
*                                 *
*  second step    :  run 'kmix'   *
*  execution time :  9s           *
*                                 *
***********************************
*

Now run the module 'kmix'. It will read its SIF 'in_kmix'
and up to four TOFs or ROFs. It will create its SOF, LOF,
and an IOF. The IOF contains the time and thickness dependent
intensities of the reflected radiation after illuminating
the foil with SR pulses.
I will discuss some input lines of the SIF:
 
(1)        name of the TOF created in the prior step
(3)        my choice here is time because I am interested
           in the time dependent intensity transmitted by
           the foil.
(5)        the measurement this calculation will be com-
           pared to was done at CHESS. The CESR operation
           provides a 364ns separation of SR pulses.
(7)        the SR beam is only partially polarized in the
           plane perpendicular to the deflecting field
(9)        in our case the canting angle of 80deg. gives
           an angle of 10deg. between the linear polari-
           zation of the incident radiation and the exter-
           nal field.
           
For more information about the meaning of each input line
please visit the 'CONUSS Users Manual'.

*
***********************************
*                                 *
*  third step     :  run 'kfit'   *
*  execution time :  1s           *
*                                 *
***********************************
*

The next step is to run the module 'kfit'. It will read its
SIF 'in_kfit' and the IOF created in the prior step and the
EIF. It will create its SOF, LOF, and a GOF. The GOF contains
the averaged and scaled calculated data, the experimental
data, and the difference between experiment and theory.
You get information about the quality of the simulation by
inspecting the SOF.
Some of the input lines of the SIF will be discussed:

(1)        name of the IOF created in the prior step
(2)        the format of the EIF is '3column' which means
           a (x,y,dy) tripel per line. A peek at the EIF
           shows that the beginning of the data (t<9ns)
           is masked, i.e., these data will never be used
           by 'kfit'. The choice of the region boundaries
           is determined by some background from the prompt
           peak (at t=0ns) that spoils the data for smaller times.
(6)..(7)   the fit range starts at 0ns. However this value
           is overruled by the specification of a masked
           region in the EIF.
(9)        I use a asymmetric gaussian shape of the time reso-
           lution of the APD detector that was used in the
           experiment.
(10)..(15) the time resolution is not fitted because of
           strong correlations between the fit parameters.
           
For more information about the meaning of each input line
please visit the 'CONUSS Users Manual'.

*
***********************************
*                                 *
*  fourth step    :  run 'kifc'   *
*  execution time :  0.5s         *
*                                 *
***********************************
*

The format of the GOF is binary. In general this special
format is not readable for your favorite graphic program.
To convert the GOF use the module 'kifc'. If you graphic
program is able to read ASCII files in 3 column format
(most graphic programs can) run the module by the
command 'kifc 3c'. In this case the files '3c_calc001',
'3c_comp001', and '3c_data' will be created containing 
theory data, difference of theory data and measured data,
and measured data resp. 

*
***********************************
*                                 *
*  alternative    :  run 'conuss' *
*  execution time :  13s          *
*                                 *
***********************************
*

The command 'conuss&' will run the modules 'kref',
'kmix', and 'kfit' in the background. The names of
the SIFs must be 'in_kref', 'in_kmix', and 'in_kfit'.
The command 'conuss rmfi&' will also run the con-
version of the GOF. The command 'conuss rmfix&' will
in addition start the graphical application pro-
gram that was defined at installation time.

*
**********************************************
*                                            *
*  fit the data   :  run 'conuss fit Works&' *
*  execution time :  130s REAL               *
*                                            *
**********************************************
*

The command 'conuss fit Works&' will run the module 'kctl'
in the background. 'Works' will be used as a working directory
and it will be created if it does not exist. The module
uses its own SIF with the name 'in_kctl'.
Some of the input lines of the SIF will be discussed:

(1)..(3)   the names of the SIFs for the CONUSS modules
           that are run by 'kctl'.
(4)        the name of the file that contains a host names.
           Each of the valid lines (the same rules as for
           the other CONUSS input files apply) gives the
           name of a host computer. 'kctl' will distribute
           the load among these hosts. It is imperative that
           all hosts mount the same file system and that
           network security permits the execution of 'rsh'
           UNIX commands on these hosts without password
           verification.
(5)        the maximum number of iteration steps for the
           fit procedure.
(6)        when the quality becomes smaller than this value
           the iteration is stopped. The quality is defined as
             Sum_j dC/dp_j * q_j,
           where C is the Chi^2 value, p_j is a fit parameter,
           and q_j is the most recent correction of that fit
           parameter. A converging iteration procedure produces
           decreasing quality values.

In addition to the parameters that we fitted previously with 'kfit',
we may now specify fit parameters directly in the SIFs of the
modules 'kref', 'kmix', and 'kfit'. In general an arbitrary input
parameter is promoted to a fit parameter by adding a percent
sign (%) to the beginning of the line, e.g.
old line:

  (18) thickness unit / micron  ::  7

new line:

% (18) thickness unit / micron  ::  7  0.1

The second value is the variation that is used for the calculation
of the parameter derivative. Also grouping of fit parameters is
supported, e.g.
old lines:

 parm1 :: 100
 parm2 :: 100

new lines (syntax note: space after '%f', no space between '%' and 'f'):

%f parm1 :: 100 1
%f parm2 :: 100

The parameters will now be fitted simultaneously. They establish
fit group 'f'. This is useful for parameters that are identical
for different sites of nuclei. An alternative is the use of
substitution directives, e.g.
old lines as before..
new lines (syntax note: space between '%' and '@'):

% @ Myparm := 100 1
 parm1 :: @Myparm
 parm2 :: @Myparm

Some fit situations require to keep two or more parameters in
a fixed relationship. For these cases, fit group modifiers can
be specified, e.g.
old lines:

 parm1 :: 100
 parm2 :: 100
 parm3 :: 200
 parm4 ::  50
 parm5 :: 150
 parm6 :: 250

new lines (syntax note: space after '%fs', no space between '%f' and 's'):

%f  parm1 :: 100 1
%f  parm2 :: 100
%fs parm3 :: 200
%fd parm4 ::  50
%fr parm5 :: 150
%fp parm6 :: 250

The modifier 's' will cause 'kctl' to keep the sum of parm3 and
parm1 constant.
The modifier 'd' keeps the difference of parm4 and parm1 constant.
The modifier 'r' keeps the ratio of parm5 and parm1 constant.
The modifier 'p' keeps the product of parm6 and parm1 constant.
The definition of fit groups by name is global,
i.e. common to all SIFs.

If the iteration is successfully finished, i.e. a minimum of Chi^2
was found, the module 'kifc' will be used to convert the GOF (see
above).
