
====================================  tc   ===================================

   tc (undulator tuning curves) calculates on-axis brilliance tuning curves for
   an ideal undulator insertion device using the Bessel function approximation
   (regular planar device or helical device).

   The calculation is performed by the program TC ("tuning curves") which is
   executed from the XTC interface. The effects of the particle beam
   emittance and beam energy spread are taken into account. TC documentation
   follows:

C+
C Last modification date of this file: Tue Nov 25 13:18:33 CST 2014
C Roger J. Dejus (dejus@aps.anl.gov)
C
C PROGRAM DESCRIPTION:
C  Program to calculate on-axis brilliance tuning curves for an ideal undulator
C  insertion device (regular planar device or a helical device). The program
C  uses the Bessel function approximation which is valid for an ideal device,
C  e.g., no magnetic field errors. The effect of the particle beam emittance and
C  the beam energy spread is taken into account.
C
C AUTHORS:
C  Roger J. Dejus
C  The Advanced Photon Source
C  Experimental Facilities Division
C  Argonne National Laboratory
C
C CREATION DATE:
C  22-APR-1996
C
C INPUT PARAMETERS:
C  The input parameters are divided into sections related to the storage ring,
C  the undulator device, and the brilliance calculation.
C Machine Parameters:
C  ENERGY		Storage ring energy              (GeV)
C  CUR		        Storage ring current             (mA)
C  SIGE		        Energy spread (sigma(E)/E)
C  SIGX		        RMS beam size (horizontal)       (mm)
C  SIGY		        RMS beam size (vertical)         (mm)
C  SIGX1	        RMS beam divergence (horizontal) (mrad)
C  SIGY1	        RMS beam divergence (vertical)   (mrad)
C Undulator Parameters:
C  PERIOD	        Undulator period length          (cm)
C  N			Number of periods
C Scan Parameters:
C  EMIN			Lower energy limit for FIRST harmonic (eV)
C  EMAX			Upper energy limit for FIRST harmonic (eV)
C  NE	                Number of energy points
C  IHMIN		Minimum harmonic of interest
C  IHMAX		Maximum harmonic of interest
C  IHSTEP		Step size for the harmonics
C Brilliance Parameters:
C  IHEL			Type of device; ihel=0: regular planar, ihel=1: helical
C  METHOD               Method
C  			METHOD={0,1}Non-zero emittance;
C                                   infinite-N +convolution (Dejus'' approach)
C  			METHOD=2    Non-zero emittance;
C                                   infinite-N +convolution (Walker''s approach)
C  			METHOD=3    Non-zero emittance; finite-N (Walker''s)
C
C  IK			Print K-values & powers; ik=0: quiet, ik=1: print
C  NEKS			Number of energy points for peak search: Default 100, or
C			use 0 for default.
C COMMON BLOCKS:
C  None.
C
C DESIGN ISSUES:
C  The down shift in energy due to the beam emittance is most noticable for
C  small values of K, and therefore, for each harmonic, the energy shift is
C  calculated for K = Kmin. The shifted peak is then used to define the energy
C  interval over which the on-axis brilliance is calculated. The peak of this
C  function is stored and subsequently saved in a file vs. energy (eV). The
C  user enters the scanning range in energy (eV) for the first harmonic, even in
C  the case when higher harmonics are chosen (using IHMIN > 1). The beam energy
C  spread is included by using a straightforward convolution at the fixed energy
C  of the peak. Beam energy spreads typically in the range 1% to 0.01% can be
C  used. It is valid to set the beam energy spread to zero. The number of energy
C  points for peak search NEKS is used at each K-value and would typically be
C  set to the default value unless the down shift in energy is being sought with
C  high accuracy. For high accuracy typically use NEKS = 1000.
C
C COPYRIGHT:
C  This routine must only be used at The Advanced Photon Source and must not
C  be tranferred or used at any other location without the consent of the
C  author.
C
C FILES USED:
C Input files
C  tc.dat (tc.inp for XOP)
C Output files
C  tc.plt (tc.out for XOP)
C
C KEYWORDS:
C  Undulator Tuning Curve, Undulator On-Axis Brilliance.
C
C LINK/LIBRARY ISSUES:
C  Calls routine USB that calls routines BRIGHTE and HUNT.
C  BRIGHTE calculates the brightness and HUNT searches an array of real
C  numbers (from Numerical Recipes).
C
C PORTABILITY ISSUES:
C  Runs on DEC 3000/400 AXP alpha (Tru64Unix v5.0), SUN (Solaris: SunOS
C  Release v5.6), and Windows 95/98/NT (Pentium and higher).
C
C  Updated October 8, 2013 (Argonne National Laboratory), tested on:
C  *** Linux Red Hat Enterprise Linux Workstation release 6.3 (Santiago) ***
C  Red Hat Enterprise Linux (RHEL) 64-bit with the Intel(R) Fortran
C  Intel(R) 64 Compiler XE for applications running on Intel(R) 64,
C  Version 13.1.1.163 Build 2013031, and with GFORTRAN, gcc version 4.4.6 20120305
C  (Red Hat 4.4.6-4) (GCC).
C  *** Sun Solaris SunOS 5.10 Generic_147440-27 sun4u sparc SUNW,Sun-Blade-2500 ***
C  Sun Fortran 90/95 8.4 SunOS_sparc Patch 128231-02 2009/10/20 with the -f77 switch.
C  and with GFORTRAN, gcc version 4.5.1 (GCC).
C  Windows 7/8 64-bit and MacOS X 10.6 (and newer) are also supported.
C  The GFORTRAN compiler (GCC) v4.8.1 was used for compilations on Windows and (GCC) v4.6.1 on MacOS.
C
C  Updated November 24, 2014 (Argonne National Laboratory)
C  *** Linux Red Hat Enterprise Linux Workstation release 6.5 (Santiago) ***
C  Red Hat Enterprise Linux (RHEL) 64-bit with the Intel(R) Fortran
C  Intel(R) 64 Compiler XE for applications running on Intel(R) 64,
C  Version 14.0.1 Build 20131008
C  GNU Fortran (GCC) 4.4.7 20120313 (Red Hat 4.4.7-4)
C  Copyright (C) 2010 Free Software Foundation, Inc.
C
C  *** Sun Solaris SunOS 5.10 Generic_147440-27 sun4u sparc SUNW,Sun-Blade-2500 ***
C  Sun Fortran 90/95 8.4 SunOS_sparc Patch 128231-02 2009/10/20 with the -f77 switch.
C  GNU Fortran (GCC) 4.5.1
C  Copyright (C) 2010 Free Software Foundation, Inc.
C
C  *** Windows 7/8 64-bit ***
C  GNU Fortran (GCC) 4.9.1
C  Copyright (C) 2014 Free Software Foundation, Inc.
C
C  *** MacOS X 10.6 - 10.10 ***
C  GNU Fortran (GCC) 4.9.2 20141029 (prerelease)
C  Copyright (C) 2014 Free Software Foundation, Inc.
C
C TIMING:
C  Generally, the execution is fast. For example, the first three odd
C  harmonics (1, 3, 5) for Undulatar A at the APS over the full tuning range is
C  calculated in about 10 s using the default parameters for the infinite-N
C  method with convolution and zero beam energy spread. The finite-N method is
C  about 10 times slower. Introduction of the beam energy spread increases the
C  execution time by typically 40%. The timing above is given for the default
C  value of NEKS (=100) and the number of points/harmonic ne = 20.
C  Updated October 8, 2013 (Argonne National Laboratory):
C  *** Linux Red Hat Enterprise Linux Workstation release 6.3 (Santiago) ***
C  Execution time with beam energy spread included and NEKS=200 and NE=80
C  is about 3.0 s for 20 harmonics (1, 3, ... 37, 39) (Intel Xenon X5650, 2.67 GHz).
C  It is about 30 s for the same case on a Sun Workstation (sun4u sparc Sun-Blade-2500)
C
C EXAMPLES:
C Ex. 1 using the input file ~/test/tc.txt (output file becomes tc.plt in the current working directory)
C % tc ~/test/tc.txt
C Ex. 2 using the default input file tc.dat in the current working directory (the output file becomes tc.plt).
C % tc
C Ex. 3 using the input abc in the current working directory (the output file becomes abc.plt).
C % tc abc
C
C VERSION:
C  1.95
C
C MODIFICATION HISTORY:
C	 Date     | Name  | Description
C ----------------+-------+-----------------------------------------------------
C 10-MAY-1996     | RJD   | Tuning variable is K.
C ----------------+-------+-----------------------------------------------------
C 21-MAY-1996     | RJD   | Changed tuning variable to E1 and added descriptive
C                 |       | text describing the input/output. First official
C                 |       | release, v1.2.
C ----------------+-------+-----------------------------------------------------
C 13-MAR-1997     | RJD   | Added beam energy spread using a straightforward
C                 |       | convolution at the fixed energy of the peak.
C                 |       | Modified calculation of the variable nek. Added the
C                 |       | variable ik which controls printing of K-values.
C                 |       | Current version is v1.3.
C ----------------+-------+-----------------------------------------------------
C 18-MAR-1997     | RJD   | Modified upper limit of peak search from 1.0 to
C                 |       | fc2 = 1.002. Added parameter SPECLIM which defines
C                 |       | the minimum Brilliance to retain in the calculation.
C                 |       | Current version is v1.4.
C ----------------+-------+-----------------------------------------------------
C 21-MAR-1997     | RJD   | Modified lower limit of peak search from fc =
C                 |       | 0.990d0*ep/eiz to fc = 0.985d0*ep/eiz so that the
C                 |       | the peak of the higher odd harmonics will be found
C                 |       | (or is more likely to be found) when the beam energy
C                 |       | spread is taken into account.
C                 |       | Current version is v1.5.
C ----------------+-------+-----------------------------------------------------
C 15-JUL-1997     | RJD   | Added information about total emitted power and
C                 |       | on-axis power density to the printout when the print
C                 |       | variable ik is set to 1. Current version is v1.6.
C ----------------+-------+-----------------------------------------------------
C 29-SEP-1997     | RJD   | Added printout of zero emittance energy (first
C                 |       | column in output file). Current version is v1.7.
C ----------------+-------+-----------------------------------------------------
C 06-OCT-1997     | RJD   | The parameter NEKS which determines the number of
C                 |       | energy points for the peak search at each K-value
C                 |       | was added to the input file. Default = 100 (or enter
C                 |       | 0). Min and max is 100 and 10000, respectively.
C ----------------+-------+-----------------------------------------------------
C 14-NOV-1997     | RJD   | The variable neks declared as integer*4.
C                 |       | Current version is v1.9.
C ----------------+-------+-----------------------------------------------------
C 16-JUL-2000     | RJD   | Minor change in the code to compile error-free on
C                 |       | Unix and Windows (no change in results vs. v1.9).
C                 |       | Current version is v1.91.
C ----------------+-------+-----------------------------------------------------
C 18-JAN-2001     | RJD   | Changed parameter NEKS1 from 200 to 500 and upper
C                 |       | range (ekmax = 1.00*eiz -> ekmax = 1.002*eiz) to
C                 |       | avoid peak searching error for second harmonic at
C                 |       | Kmin for small emittance and large N. Results for
C                 |       | for odd harmonics may also differ slightly from
C                 |       | previous version because peak shifts are different.
C                 |       | Current version is v1.92.
C ----------------+-------+-----------------------------------------------------
C 09-FEB-2011     | RJD   | Added statement to ensure that the emittance
C                 |       | down-shifted peak "ep" is less then the zero-emittance
C                 |       | calculated energy "eiz." The down-shift is set to be
C                 |       | always larger than 5e-4. Errors may otherwise occur for
C                 |       | very small emittances and long devices (large N).
C                 |       | Statement added - see RJD 02/08/11:
C                 |       | if (ep .gt. 0.9995d0*eiz) ep = 0.9995d0*eiz
C                 |       | Current version is v1.92a.
C ----------------+-------+-----------------------------------------------------
C 17-SEP-2013     | RJD   | Extented parameter H_SZ so that arrays can store
C                 |       | information for up to 100 harmonics.
C                 |       | Omitting brightness values below 5% of the max brightness of
C                 |       | of the previous harmonic. Also check for overlapping harmonics.
C                 |       | Reverted lower limit of peak search for fc from
C                 |       | 0.985d0*ep/eiz to fc = 0.990d0*ep/eiz.
C                 |       | Omitted peak search in gauss_convol and use eiz for ep
C                 |       | instead. Brightness values are slightly different from prior
C                 |       | version.
C                 |       | Current version is v1.92b.
C ----------------+-------+-----------------------------------------------------
C 11-OCT-2013     | RJD   | Changed calls to date and time routines. Now uses the
C                 |       | date_and_time routine. Updated character arrays accordingly.
C                 |       | Reset emax to a value calculated from Kmin=0.2 if it is larger
C                 |       | than the max value for a given ring energy and undulator period length
C                 |       | to avoid a common user input error. Prints warning.
C                 |       | Updated general support information.
C                 |       | Current version is v1.93.
C ----------------+-------+-----------------------------------------------------
C 25-OCT-2013     | RJD   | Updated ekmin range for odd and even harmonics for an helical undulator.
C                 |       | It now typically works for harmonics up to 10 or so.
C                 |       | Current version is v1.94.
C ----------------+-------+-----------------------------------------------------
C 25-OCT-2013     | RJD   | Updated ekmin range for odd and even harmonics for an helical undulator.
C                 |       | It now typically works for harmonics up to 10 or so.
C                 |       | Current version is v1.94.
C ----------------+-------+-----------------------------------------------------
C 10-JUN-2014     | RJD   | Updated so that an arbitrary input file can be used on the command line.
C                 |       | If no input file is given on the command line then the file 'tc.dat'
C                 |       | is assumed ('tc.inp' for the XOP version). The output filename is created
C                 |       | from the rootname, which is derived from the input filename using the string after
C                 |       | the last directory separator (/) without its trailing file extension (if it exists).
C                 |       | The output filename is the rootname with the extension (.plt) appended (.out for the
C                 |       | XOP version). Search "standalone" for changing defaults.
C 24-NOV-2014     | RJD   | Updated compiler info section above. Version number unchanged. Uses updated usb.f (v1.21).
C                 |       | Current version is v1.95.
C ----------------+-------+-----------------------------------------------------
C-