Description of EMITCALC Program  (Gregg Penn)

This still needs to be checked that all of the optionswork properly;  the basic cases seem okay.Calculates beam parameters and amplitude cuts. The main differences between this and ECALC9F is that it outputs fewer quantities, there is only one set of hard amplitude cuts calculated at a time, and it outputs a set of 3 invariant emittances.  These emittances should be invariant under any linear Hamiltonian map. It is a little tricky to correctly assign the emittances to the x,y, and z planes;  I tried to find the order that leads to the 'smallest' decoupling matrix, but it is possible the emittances will jump around if the coupling is strong.Of course, sometimes this should be the right behavior anyway. Another fairly big difference is that the vector potential is used explicitly to convert to canonical conjugate variables. Longitudinal coordinates are still time and energy, and x and y are unchanged, but Px and Py are converted to canonical momentum.  This is different from ECALC9F where the moments matrix was defined using mechanical momentum, but the total canonical momentum carried by the beam was used in the parametrization of the moments matrix.

This program reads the input file 'emitcalc.inp'. An example is:
# sample	! description
for009.dat	! input file name
emitcalc.out	! output file name
2		! particle type (0 = use all)
0. 0.		! pzmin, pzmax [GeV/c]; if pzmax<=0., no cut
0 2.0 vp.in	! vector pot. model, assumed B0 [T], input file
0.02  0.1 	! transverse, longitud. amplitude cutoffs [m] (if <=0, no cut)
.false.		! subtract linear corr of transverse coords with E, t
.false.		! subtract nonlinear corr of E, t with transverse amplitude
0  800.		! time overlap model (no overlap if =0), rf frequency
6.		! sigma cut to remove tails (no cut if <=0.)

The vector potential model (line 6) and time overlap model (line 10) may need some explaining.  The vector potential model is necessary for converting transverse momentum into conjugate momentum.  There are 4 models used to determine the transverse coordinates of the vector potential A:
0.  model 0 assumes a uniform solenoid field, which is given in the input file as the second term in line 6.  For all other models, this second term is ignored.
1.  model 1 is roughly similar to what ECALC9F does, but with an extra correction that can be useful for particles at large amplitudes. It uses Bz at the reference particle to determine the magnetic field on axis, but combines it with the local Bz to get a more accurate estimate of the vector potential. When there is no reference particle, it switches to model 2. Note that if the reference particle is not on axis this will lose accuracy.
2.  model 2 also assumes axisymmetric fields, but calculates the vector potential by fitting the values of Bz at all particle locations to an expansion for Bz(r). So no reference particle is needed.
3.  model 3 allows one input a Taylor expansion of Ax and Ay from a file. The first line should be 2 numbers, Ax = c1*x + c2*y, the second line three numbers Ax = c3*x^2 + c4*x*y + c5*y^2, etc., up to y^5 in the fifth line. Then a second set of 5 lines should be the same thing but for Ay.

The time overlap option is mostly as in ECALC9F, it overlaps particles in time modulo the given rf period. The main complication is centering the bunch at t=0, to avoid cutting the beam in half for the given time window. There are two "models" for doing this (model 0 is not to do it at all):
1.  model 1 uses the reference particle to define t=0, if there is no reference particle, model 2 is used2.  
2. model 2 uses a weighting scheme (think of periodic time as the circumference of a circle) to find the central time of the bunch; this is like the phase of the FEL 'bunching parameter'

Other comments:The "asymmetry" output is a test to see how axisymmetric the beam is, it should be a number much smaller than 1 if the beam is roughly axisymmetric. In addition to subtracting out the nonlinear correlation of energy and time with transverse amplitude, there is an option to first remove linearlongitudinal-transverse correlations.  This is done in a very rough way, by "correcting" the transverse coordinates in such a way as to remove dispersions, dispersion derivatives, etc.  Then the transverse beam properties are calculated using these correction coordinates. Note that this is not the same thing as decoupling the degrees of freedom, it's just a rough and simple solution to dealing with large dispersion. On the other hand, in order to "observe" increases in projected emittance due to dispersion, this option should be turned off.