*   last visit 15.Feb.2001 18:20:33   by sturhahn
*
*********************************************
*
*  CONUSS Version 1.5
*  (C) Copyright 1996, Wolfgang Sturhahn.
*  All rights reserved.  
*  Unauthorized reproduction prohibited.
*
*********************************************
*
*  the file's directory :
*    $CONUSSHOME/examples/NBS1
*
***********************************************************
*                                                         *
*  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 hema-
tite single crystal using synchrotron radiation. The expe-
riment was done with an undulator beam and is described in
Kikuta et al., Proceedings of the
               International Conference on Anomalous
               X-ray Scattering, edited by K.Fischer,
               G.Materlik, and C.J.Sparks
               Elsevier Science Publishers
The experimenters observed the (777) pure nuclear reflec-
tion. The crystal was magnetized by a small external field
that was applied in the crystal surface plane in the direc-
tion of the incident radiation. The material was highly
enriched in 57Fe. 

The given execution times may vary due to the performance
of your system. I used a Sun Ultra 1 workstation for the
calculations.

The properties of the scatterer (the hematite single crystal) 
are defined in the MIF 'fe2o3_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),(14)  the Debye temperature of the alpha-iron lattice
           is set to an artificial high value of 99999K and 
           the temperature of the crystal was set to 0K.
           These settings force the Moessbauer-Lamb-factor
           to be 1. The product of ML-factor and abundance
           is then adjusted by parameter (22).
(15)..(20) the unit cell that is defined here is the
           rhomboedric unit cell of hematite which contains
           4 iron and 6 oxygen atoms.
(22)       the product of abundance of 57Fe in this crystal
           and the ML-factor (see also parameters 13,14).
(24)       There are two iron sites in hematite with nearly
           antiparallel magnetic hyperfine fields.
(25)       I assume the crystal to be magnetized uniformly
           by the external field. Therefore averaging is
           not necessary.
(26.1.6)   the magnetic hyperfine field is set to 51.5T.
(26.1.9),  the angle (thata) between magnetic hyperfine field
(26.2.9)   and external magnetic field is set to 85deg. The
           angle phi is taken between the magnetic hyperfine
           field and the vector given by the vector product
           of the surface normal and the external magnetic
           field. This describes the magnetic structure of
           hematite where the magnetization of the unit cell
           is nearly perpendicular to the hyperfine fields.
           The deviation of theta from 90deg. corresponds
           to a slight canting of the hyperfine fields. The
           crystal behaves like a weak ferromagnet but its
           magnetic structure is that of an antiferromagnet
           (see parameter 26.2.9).
(26.1.13), The Euler angles of the electric field gradient
(26.1.14), define the Vzz main axis in the 111 direction.
(26.1.15)  In a hexagonal unit cell this is the c-axis. You
           may check the Euler angles by using CONUSS
           module KVZZ.
           
For more information about the meaning of each input line
please visit the 'CONUSS Users Manual'.

*
***********************************
*                                 *
*  first step     :  run 'kref'   *
*  execution time :  7.4s CPU     *
*                                 *
***********************************
*

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 ROF contains
the normalized reflected electric fields as a function of
energy, angle, 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 reflection
           mode. The reflection amplitudes of the Bragg
           channel will be calculated.
(5)..(7)   These are the Miller indices of the chosen pure
           nuclear Bragg reflection. You may check the 
           possibly existing nuclear reflections by using
           the CONUSS module KPNR.
(8)..(10)  The orientation of the crystal surface is
           parallel to the netplane normals. This is a
           symmetric Bragg reflection.
(11)       The azimuthal angle of the incident beam is
           arbitrary in this geometry.
(12)       The magnetic field was 7deg. off the scattering
           plane.
(13)       this angle is taken between the surface normal
           (8)..(10) and the external magnetic field. 90
           deg. means the field lies in the surface.
(15)..(17) energy range for the calculations. The splitting
           observed from an iron foil is about +-85gamma.
           By choosing +-300gamma for the range I make shure
           that the tails of the outer lines will be included.
(18)       The crystal was very thick compared to the extinction
           depth of the resonant radiation. I give a negative
           value here which is interpreted by CONUSS as an
           infinite thickness. This setting reduces the
           computing time considerably.
(19)..(21) angle range for the calculations. The maximum
           reflectivity occurs at 10micorad and the width
           of the reflection is about 10microrad. I choose
           a range of 80microrad because we will average
           over the divergence of the incident beam later
           (module KFIT). The calculated angle range should
           be a few times the divergence. The step size
           (2microrad) is small enough to resolve the 
           structure of the rocking curve.
           
For more information about the meaning of each input line
please visit the 'CONUSS Users Manual'.

*
***********************************
*                                 *
*  second step    :  run 'kmix'   *
*  execution time :  8.5s CPU     *
*                                 *
***********************************
*

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 angle dependent
intensities of the reflected radiation after illuminating
the crystal with SR pulses.
I will discuss some input lines of the SIF:
 
(1)        name of the ROF created in the prior step
(3)        my choice here is 'time' because I am interested
           in the time dependent intensity reflected by
           the crystal.
(5)        the measurement this calculation will be com-
           pared to was done at KEK, Japan. Single bunch
           operation mode of the storage ring provided
           a few microseconds separation of SR pulses.
           The negative value specified by me tells
           CONUSS to assume an infinit bunch separation.
(7)        the SR beam is only partially polarized in the
           plane perpendicular to the deflecting field
(9)        The canting angle of 0deg. defines the polarization
           of the incident radiation to be perpendicular to
           the scattering plane. The beam is sigma polarized.
           
For more information about the meaning of each input line
please visit the 'CONUSS Users Manual'.

*
***********************************
*                                 *
*  third step     :  run 'kfit'   *
*  execution time :  5s CPU       *
*                                 *
***********************************
*

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 'blocked' which means
           x-, y- ,and dy-data occur in blocks.
(6)..(7)   the fit range starts at 6ns because there seems
           to be some contribution from the prompt peak
           (at t=0ns).
(9)        I use a asymmetric gaussian shape of the time
           resolution of the plastic scintillation detector
           that was used in the experiment.
(10)..(15) The statistical accuracy of the data in the EIF
           is very good. Therefore all internal fit para-
           meters may be fitted.
           
For more information about the meaning of each input line
please visit the 'CONUSS Users Manual'.

*
***********************************
*                                 *
*  fourth step    :  run 'kifc'   *
*  execution time :  1s CPU       *
*                                 *
***********************************
*

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 :  22s CPU       *
*                                  *
************************************
*

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 :  6.5min 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'. For the results,
the output file 'out_kctl' can be inspected.
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:

  (12) azimuthal angle of B_ext / deg. ::  7

new line:

% (12) azimuthal angle of B_ext / deg. ::  7 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).
