****************************************************************************** ****************************************************************************** !! 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