
******************************************************************************
******************************************************************************
 
!!    UU      UU  RRRRRR      GGGGGGG  EEEEEEEE  NNN      NN  TTTTTTTTTT    !!
!!    UU      UU  RR   RR   GGGGGGGGG  EE        NNNN     NN  TTTTTTTTTT    !!
!!    UU      UU  RR   RR  GGG         EE        NN NN    NN      TT        !!
!!    UU      UU  RR  RR   GG          EEEEEEE   NN  NN   NN      TT        !!
!!    UU      UU  RRRRR    GG    GGGG  EEEEEEE   NN   NN  NN      TT        !!
      UU      UU  RR  RR   GGG     GG  EE        NN    NN NN      TT
!!    UUU    UUU  RR   RR   GGGGGGGGG  EE        NN     NNNN      TT        !!
!!     UUUUUUUU   RR    RR    GGGGGGG  EEEEEEEE  NN      NNN      TT        !!
 
******************************************************************************
******************************************************************************
 
           A program for calculating Undulator Radiation properties.
 
          Authors : R.P.Walker and B.Diviacco, Sincrotrone Trieste
 
                 Reference : R.P.Walker and B.Diviacco,
Proc. 4th Int. Conf. Synchrotron Radiation Instrumentation, Chester, July 1991,
            to be published in Rev. Sci. Instrum. Jan. 1992,
                 Sincrotrone Trieste report ST/M-91/12
 
Modification record :
06/11/89 - Version 1
           first distributed version
19/03/90 - Version 1.1
           changes in output format to include power information
           new  MODE=6 for radiation power calculations
           addition of beam current parameter (CUR)
           elimination of an error in MODE=1 ICALC=1
15/05/90 - Version 2
           includes polarization parameters and eliptical
           trajectories (KX, KY parameters)
04/09/91 - Version 3.0
           includes crossed undulator
           new definition of l4
           changes to MODE=6 method of calculation and parameters
           various other small changes
*******************************************************************
 
The following are complete up-to-date instructions for running URGENT.
Please use the latest version available.
 
1. INTRODUCTION
 
 URGENT is designed for the accurate and efficient calculation of
the basic properties (angular, spectral, polarization, power density)
of the radiation generated in ideal plane, helical or elliptical undulators,
and also the crossed-undulators scheme [Nikitin,Kim].
 
 It can take into account :
- non-zero electron beam emittance (size and divergence)
- finite number of undulator periods (N)
- multiple harmonics contributing at a given photon energy
but also has options for :
- zero emittance
- infinite N
- single harmonic
 
 The main approximations are :
- ideal electron trajectory (i.e. no tapering or field errors)
- far-field.
 
 It is written in standard FORTRAN 77, calls no library routines,
and needs no graphics package and so should be easily transportable.
 
 URGENT uses the Bessel function method to calculate the basic radiation
angular flux density function in an efficient manner. An appropriate
choice is made of routine depending on whether the magnet is plane or
helical, in order to minimize cpu time.
 
 
2. DATA INPUT
 
 The data is read on unit 5 (FOR005) in free-format (READ(5,*)).
There are 6 lines, containing the following parameters  :
 
1) ITYPE, PERIOD, KX, KY, PHASE, N
2) EMIN, EMAX, NE
3) ENERGY, CUR, SIGX, SIGY, SIGX1, SIGY1
4) D, XPC, YPC, XPS, YPS, NXP, NYP
5) MODE, ICALC, IHARM
6) NPHI, NSIG, NALPHA, DALPHA, NOMEGA, DOMEGA
 
A value must be entered for each parameter, even if not relevant for
the calculation that is to be performed. Parameters ITYPE, N, NE, NXP,
NYP, MODE, ICALC, IHARM, NPHI, NSIG, NALPHA, NOMEGA are integers.
 
The parameters have the following meaning :
 
Line 1 : Undulator
ITYPE - either ITYPE=1 : plane/helical/elliptical magnet
            or ITYPE=2 : crossed undulator
PERIOD - magnet period (m)
KX, KY - magnet deflection parameters coresponding to a horizontal and
         vertical field direction respectively
PHASE - phase difference between the two undulators in the crossed undulator
        scheme (degrees)
N - number of magnet periods
 
Line 2 : Photon Energy
EMIN - minimum photon energy (eV) (>0)
EMAX - maximum photon energy (eV)
NE - number of photon energy intervals (<5000)
 
Line 3 : Electron Beam
ENERGY - electron beam energy (GeV)
CUR - electron beam current (A)
SIGX, SIGY - rms horizontal and vertical electron beam sizes (mm)
SIGX1, SIGY1 - rms horizontal and vertical electron beam divergences (mrad)
 
Line 4 : Observation point and range of acceptance
D - distance from centre of undulator to the observation point (m)
XPC, YPC - horizontal and vertical position of the observation point
           or centre of the range of acceptance (mm or mrad)
XPS, YPS - TOTAL horizontal and vertical acceptance (mm or mrad)
NXP, NYP - number of intervals into which the acceptance is divided in the
           horizontal and vertical directions (<50)
 
Line 5 : Calculation Method
MODE -  type of calculation, having the following possible values :
   MODE=1 angular/spatial flux density distribution at photon energy EMIN
          In this case EMAX, NE are irrelevant.
   MODE=2 spectrum of angular/spatial flux density at position XPC, YPC
          In this case XPS, YPS, NXP and NYP are irrelevant.
   MODE=3 spectrum of on-axis brightness.
          In this case D, XPC, YPC, XPS, YPS, NXP and NYP are irrelevant.
   MODE=4 spectrum of flux integrated over the defined range of acceptance.
   MODE=5 spectrum of flux integrated over all angles
          In this case D, XPC, YPC, XPS, YPS, NXP and NYP are irrelevant.
   MODE=6 angular/spatial distribution of power density in a given harmonic
          or range of harmonics; central power density and integrated power
          over the range of acceptance, listed for each harmonic
          In this case EMIN, EMAX, NE are irrelevant
          Note : to increase the options available MODE=-6 can also
          be used (see below under IHARM).
 
ICALC - calculation method, having the following possible values :
   For MODE=1,2,3,4 :   ICALC=1 non-zero emittance, finite N
                        ICALC=2 non-zero emittance, infinite N
                        ICALC=3 zero emittance, finite N
   For MODE=5 :         ICALC=1 finite N
                        ICALC=2 infinite N
   For MODE=6 :         ICALC=1 non-zero emittance
                        ICALC=2 zero emittance
 
IHARM - number of harmonics to be included, having the following values :
   For MODE=1,2,3,4,5 with ICALC=1,2 :
             IHARM=-1 include all harmonics contributing at a
             given point and given photon energy
             IHARM=0 use only the lowest order contributing harmonic
             IHARM=i use only the i'th harmonic
   For MODE=1,2,3,4 with ICALC=3 : IHARM is not relevant
   For MODE=6 :
         IHARM=i  angular/spatial distribution of power density for harmonic i
         IHARM=-i include all harmonics from 1 to i
            MODE=-6 :
            angular/spatial distribution of power density for each harmonic
          + angular/spatial distribution of power density for sum of harmonics
          + central power density and integrated power for each i
            MODE=6 :
            angular/spatial distribution of power density for sum of harmonics
          + central power density and integrated power for each i
         IHARM=0  include harmonics up to some limit determined by the program
            MODE=-6 or MODE=6 as above
 
LINE 6 : Calculation Parameters
- All of the following parameters can be set to zero in which
case they default to the values given in brackets [].
 
NPHI -   no. of steps in phi between 0 and pi/2.0 [20]. NPHI < 100.
         used in (MODE=1,2,3,4,5 ICALC=1,2)
NSIG -   no. of standard deviations of electron beam dimensions (size and
         divergence) to be included [4].
         used in (MODE=1,2,3,4 ICALC=1,2) and (MODE=6 ICALC=1)
NALPHA - no. of steps in angle alpha (gamma*theta) [15]. NALPHA < 100.
         used in (MODE=1 ICALC=1).
DALPHA - range of angles in alpha**2 to be used, in units of the angular
         equivalent of 1/N [2.0].
         used in (MODE=1 ICALC=1) and ICALC=3.
NOMEGA - no. of steps in photon energy for the natural lineshape [16].
         NOMEGA < 5000.
         used in (MODE=2,3,4,5 ICALC=1)
DOMEGA - range of photon energies to be included in the natural lineshape
         in units (energy of fundamental/N) [2.0] i.e. the default value
         covers the range +/- 2/N of the natural lineshape.
         used in (MODE=2,3,4,5 ICALC=1)
 
 
NOTES :
 
i/ For (MODE=2,3,4,5 ICALC=1 ITYPE=1) the finite N spectrum is obtained by
convoluting the infinite N spectrum with the natural lineshape.
To make this easy the point spacing in photon energy must be the same
for the two curves. This can be achieved as follows :
- set NE=0, in which case the spacing is set by the values of NOMEGA and
  DOMEGA and NE is set accordingly.
- set NE to the approximate number of points desired in the energy range
  EMIN,EMAX. A new value of NE is then calculated which gives the closest
  match with the spacing of the natural lineshape.
In either case  EMAX will also be adjusted so that the convolution
can be carried out correctly over the defined energy region.
In order to get an accurate convolution the program insists that
the rule (NOMEGA/DOMEGA) >= 4 is respected.
 
ii/ In cases with non-zero emittance (MODE=1,2,3,4,ICALC=1,2 and MODE=6,
ICALC=1) both SIGX and SIGY may be zero, but both SIGX1 and SIGY1 must
be non-zero.
 
iii/ If D is set to zero, this indicates that angular flux and power density
is to be calculated rather than spatial flux and power density in MODEs
1,2,4 and 6. In this case SIGX and SIGY are ignored, and the acceptance
(XPC, YPC, XPS, YPS) is entered in mrad rather than mm units.
 
iv/ If the acceptance is centred on the axis (XPC=YPC=0.0) then only
one quarter of the acceptance needs to be calculated because of symmetry.
In this case the range from (0,0) to (XPS/2.0,YPS/2.0) will be divided
into NXP, NYP intervals. The printed values of integrated flux and power,
including Stokes parameters will however be correct for the total acceptance.
 
v/ Theta (alpha/gamma) is the angle between the undulator axis and the
direction of observation. Phi is the angle between the projection of the
angle of observation in the x-y plane and the x-axis.
 
vi/ MODE=6 : In addition to power density the program now also prints total
flux density (photons/s/mrad**2 or mm**2), and as well as integrated power
the total flux (photons/s). The central value means at the centre of the
defined acceptance in the case of a 2D acceptance (NXP>0, NYP>0). In other
cases it refers to the first point. It is permitted to enter NXP=0 or NYP=0
to obtain values of the power density for example as a function of vertical
or horizontal position (angle) respectively.
 
vii/ For the crossed undulator (ITYPE=2) the following special rules apply :
- KX is set to 0.0; both undulators are assummed to have deflection parameter KY
- each undulator is assumed to have N periods
- only MODE = 1, 2 or 4 can be used
- NPHI <= 25
- The calculation method is different to that for standard
magnets (ITYPE=1); finite N is taken into account directly and no
convolution with the natural lineshape is necessary. ICALC=1 or ICALC=2
can be entered equally; NOMEGA and DOMEGA are irrelevant. DALPHA is needed
in all cases, NALPHA for ICALC=1,2.
 
3. DATA OUTPUT
 
Data are output on unit 6 (FOR006). In all cases the main data start on line 33.
 
The input parameters are firstly printed. Parameters on lines 1,2,4,6 that
are not relevant for the type of calculation required are set to zero.
The on-axis photon energy and wavelength, and the total power and peak power
density (zero emittance) are also given. The power density is only given for
the plane and helical (KX=KY) case.
 
The units used throughout are as follows :
 
Photon energy                   [eV]
Wavelength                      [Angstrom]
Spatial flux density=Irradiance [photons/s/mm**2/0.1%bandwidth]
Angular flux density            [photons/s/mrad**2/0.1%bandwidth]
Brightness                      [photons/s/mm**2/mrad**2/0.1%bandwidth]
Flux                            [photons/s/0.1%bandwidth]
Spectral power density          [Watts/mm**2 or mrad**2/eV bandwidth]
Power density                   [Watts/mm**2 or mrad**2]
Spectral power                  [Watts/eV bandwidth]
Power                           [Watts]
 
 
4. POLARIZATION
 
 Angular/spatial flux densities and integrated flux are given in terms
of polarization parameters l1, l2, l3, l4 where :
   l1 = s1/s0  l2 = s2/s0  l3 = s3/s0
   and l4 = 1 - sqrt((l1**2)+(l2**2)+(l3**2))
s0, s1, s2 and s3 are the Stokes parameters, integrated over the
beam emittance, range of acceptance etc. :
   s0 = total intensity
   s1 = difference in intensity between radiation polarized linearly in the
        horizontal direction and in the vertical direction
   s2 = difference in intensity between radiation polarized linearly in the
        directions at +45 degrees and -45 degrees with respect to the
        horizontal and vertical directions
   s3 = difference in intensity between radiation polarized circularly in the
        right-handed and left-handed sense
Thus, the fraction of radiation that is polarized is
                  sqrt((l1**2)+(l2**2)+(l3**2))
and l4 represents the fraction of radiation that is unpolarized.
l1, l2 and l3 vary between -1 and +1; l4 varies between 0 and 1.
Note the change in definition of l4 from URGENT version 2. It now is in
agreement with the definition of Born and Wolf, Principles of Optics p.555.
 
 With the assumption that the undulator fields are parallel to the x and y
axes, and that electron beam distributions that are symmetrical with respect
to the x and y axes -
In general : l2 = 0 on-axis, or with an acceptance that is symmetric with
respect to the x and y axes
In a plane undulator (KX=0, KY#0) : l3 = 0 always
 
 
5. COMMENTS AND SUGGESTIONS
 
 In a program of this sort it is impossible to guarantee that sensible
results will be obtained in all circumstances. Thus, the user should (as with
any reasonably complicated computer program) judge himself whether the
results are sensible by the usual techniques of changing the input
parameters (e.g. number of energy intervals, number of points in the
acceptance etc.) in order to check that the results remain reasonably
consistent, or change in the expected way (changing for example the
emittance parameters, or choosing options for infinite N etc.)
 
 In most cases the default values for parameters in line 6 are appropriate,
i.e. enter 0 0 0 0 0 0.
 
 The default values should give accurate values of the flux to a level
of the order 0.1% of the main peak. If accuracy is wanted to lower values,
it may be necessary to increase NSIG (e.g. 6).
 
 For MODE=1,2,3,4,5 if in doubt use IHARM=-1; the data output will include
information on which harmonics were actually used in the calculation.
 
 For MODE=2,3,4,5 there is little difference in the calculation time for
spectra with ICALC=1 or 2, however ICALC=2 allows the photon energy interval
to be set independently of any natural lineshape criterion, which can be
useful for either a preliminary calculation or in some particular cases [e.g.
at high photon energies compared to the first harmonic where the infinite
N approximation is a good approximation to the finite N result].
 
 For cases with small emittance and small photon energy ICALC=3 can
be a reasonable approximation (MODE=1,2,3,4).
 
 For cases with large emittance and large photon energy ICALC=2 can
be a reasonable approximation (MODE=1,2,3,4).
 
 For MODE=6, when the electron beam emittance (divergence) is small
compared to 1/gamma, ICALC=2 is a good approximation. When the emittance
and pinhole are sufficiently small that different harmonics in the spectrum
do not overlap, the power density and integrated power in the individual
harmonics can conveniently be calculated directly (IHARM=0), rather than by
spectral calculations for each separate harmonic.
 
 Some problems can occur in computing spectra in the case with small
emittance and small photon energy i.e. the "diffraction limited" case.
Here it is necessary to make sure that the infinite N spectrum first
calculated by the program is sensible - i.e. has sufficient points in
it (determined by the photon energy interval used) and in the case of
integrating over a pinhole is suitably "smooth" (determined by the
spacing of points in the pinhole). A reasonable criterion for the
latter is that the spacing XPS/NXP should be as follows :
           XPS/NXP < 2.0 * SQRT((SIGX*SIGX)+(D*D*SIGX1*SIGX1))
and the same in the vertical plane.
 
6. USING THE PROGRAM
 
 The FORTRAN source program comes in a single part : URGENT.FOR
which should be compiled and linked to form an executable program.
No external routines are called. Although the program has been developed on
a VAX, it compiles under FOR/STANDARD and has also been compiled on a PC.
 
 Most calculations can be performed in an interactive mode
in a few seconds to a few minutes cpu time. A simple VAX
COM file to run the program URGENT.EXE reading the data from INP.DAT and
outputing to OUT.DAT is as follows :
 
   $ ASSIGN INP.DAT FOR005
   $ ASSIGN OUT.DAT FOR006
   $ RUN URGENT
   $ DEASS FOR005
   $ DEASS FOR006
   $ EXIT
 
 A sample input file is as follows :
 
   1 0.056 0.0 3.39 0.0 81
   295. 303. 0
   2.0 0.4 0.228 0.044 0.033 0.017
   20.0   0. 0. 2. 2. 10 10
   4 1 3
   0 0 0 0 0 0
 
In this example the flux is integrated over a 2 mm x 2 mm
pinhole 20 m from the source, for a 5.6 cm period undulator in ELETTRA
at 2 GeV 400mA, near the third harmonic. The photon energy range is defined,
but not the interval - which is determined by the program for compatibility
with the natural lineshape. For this run the calculation time on a VAXSTATION
3100/MOD.30 is 21 s for 27 photon energy points.
 
 
7. PROGRAM DISTRIBUTION and FURTHER INFORMATION
 
 The program may be freely copied to anyone else who would like it.
However, it is in the best interest of anyone who uses the program to
let me know so that they can receive further updates of the program.
 
 Anyone who has difficulty in using the program and requires advice
should feel free to contact me. Comments on the operation of the
program and suggestions for new developments would also be welcome.
 
 Communication is preferred by e-mail :
 
           Bitnet - R.WALKER@ELETTRA.TRIESTE.IT
           DecNet - SYNCTS::WALKER or 40082::WALKER
 
alternatively :
 
                R.P.Walker
                Sincrotrone Trieste
                Area di Ricerca
                Padriciano 99
                34012 Trieste
                Italy
 
tel.       39-40-37581
fax.       39-40-226338
 
 
R.P.Walker,
September 4th, 1991
 
 
