*******************************************************************************
****************  CESR BSM DAQ online analysis utilities  *********************
*******************************************************************************

After raw (menu option 2) or navg (menu option 6) data taking, one can fit the
bunch by bunch distributions using bsmfitallavg.exe by typing: bsmfitallavg
bsmvvv_paw_xxxxx.dat whereby it is assumed one has typed
@[CESR.PALMER.TS101.COM]init earlier on and vvv and xxxxx are as described in
an earlier section.

Note that the sizes and positions in the bsmvvv_fit_xxxxx.dat output file
already have the "size calibration" applied to the data (e.g. following
calibrations made on 18-September-2006 (see TWIKI logs), these were 8.6 for
electrons and 10.4 for positrons). These calibrations are hardcoded in the
bsmfitallavg source.

One can also automate this process by using a script like ECLOUD_ETRAIN.COM or
ECLOUD_PTRAIN.COM (these have for instance been used in ECLOUD experiments).
These scripts will execute bsmfitallavg.exe and the results (bunch positions
and sizes as a function of bunch number) are plotted using wlplot. Details
about wlplot can be found at

http://cesrelog.lns.cornell.edu/documents/control/software/wlplot.html 

Note that for ECLOUD experiments, before taking data one can use the script
SETUP_ECLOUD_E.COM or SETUP_ECLOUD_P.COM to copy the apropriate files. Use
SETUP_OPER.COM for normal operations.

*************************************************************************

Description of fortran program bsmfitallavg This program fits a Gaussian to the
geometric bunch distribution as measured by the BSM; this is done turn by turn
for all bunches. Note that this program is NOT intended to calculate sigma and
position of bunches to a high degree of accuracy; the sole purpose is to
provide a quick online analysis of the measurement data, which can help
validating the measurement. High accuracy analysis takes much longer and
therefore tpically needs to be done offline.

Source and executable located on the VAX:
Current version in USER$DISK:[CESR.PALMER.TS101.BSM]
Development version in USER$DISK:[CESR.PALMER.TS101.BSM.DEV]

Source and executable located on the LINUX server:
/nfs/acc/temp/ts101/BSM/fitter

To run the executable, type:
bsmfitallavg <measurement file>

An example of a measurement file name is bsm23e_paw_01113.dat, which is assumed
to be of a binary format.

After starting this executable, it will read the corresponding
"bsmvvv_cur_xxxxx.dat" file as well as the corresponding bunmap text file (vvv
and xxxxx have been defined earlier in this readme.txt file). It will also read
graph limits from bsmvvv_plot.dat, but at present these are no longer used.

Subsequently the program will list an output similar to the one below:
 Filename entered                  :
bsm23e_paw_01113.dat;1
 Associated beam current filename  :
bsm23e_cur_01113.dat;1
 Associated plot parameter filename:
bsm23e_plot.dat
 Particle type                     : p
numBnch  =           16
numAvg   =         1024
numTpA   =            1
numTurns =         1024
bunch#           1 =TB163
bunch#           2 =TB001
bunch#           3 =TB002
bunch#           4 =TB003
bunch#           5 =TB004
bunch#           6 =TB005
bunch#           7 =TB006
bunch#           8 =TB007
bunch#           9 =TB008
bunch#          10 =TB009
bunch#          11 =TB010
bunch#          12 =TB013
bunch#          13 =TB014
bunch#          14 =TB015
bunch#          15 =TB016
bunch#          16 =TB017
Enter bunch# to serve as pedestal (1..16)

Here one would enter 1 (which corresponds to TB163); this bunch is needed for
pedestal subtraction.

The next prompt would be:
Enter bunch# to serve as first bunch (1..16)

Here one would enter 2 (which corresponds to TB001) 

Next, the program will read the data file and ask:
Spline (1), FWHM (2), Levi (3) or Quit (0)?

Here 3 different ways of fitting a Gaussian are proposed: one based on a spline
fit, one based on Full Width Half Max (FWHM; note that the FWHM of a Gaussian
is ~ 2.35 * sigma) and finally an algorithm developped by Levi Schachter, based
on error minimization. The by far fastest routine is the FWHM based one. If one
selects FWHM (2), one is prompted again: Enter threshold

Here one can set a threshold w.r.t. the measured amplitude of the Gaussian. If
for instance one  sets this threshold to 100, only data with measured
amplitudes higher than 100 will be fitted. Those which are lower will not be
fitted (amplitude and sigma will be set to 0).

At this point the fitter will go through the first bunch, and fit for all the
turns. It will print fitted turn by turn data to the output file
bsmXZfit_TB001.dat, where X is the particle typ (e for e- or p for e+ and Z is
the fitting method (in this case represented by the letter "g"). After the
first bunch it will go through the next, creating its turn by turn fitted data
file and so on.

An example output for the first 5 turns of this example is given below:
     1      1.800      0.311  15664.000   -720.000
     2      1.813      0.395  13680.000   -976.000
     3      1.714      0.252  14544.000   -816.000
     4      1.712      0.241  14272.000   -416.000
     5      1.745      0.297  11504.000   -256.000
Note:
Column 1 = turn number
Column 2 = position (mm) (includes calibration, hardcoded in the fitter)
Column 3 = size (mm)     (includes calibration, hardcoded in the fitter)
Column 4 = amplitude (in 4 * ADC counts)
Column 5 = baseline  (in 4 * ADC counts)

After all bunches have been fitted, for each bunch data will be averaged over
all turns and an overview of these results will be written to file
bsmvvv_fit_xxxxx.dat;1 (in this case this would be bsm23e_fit_01113.dat;1 )

The contents of bsm23e_fit_01113.dat;1 look like:
TB001      1      2      1.606      0.300  14004.891   -931.875
TB002      2      3      1.631      0.296  15124.125  -1155.000
TB003      3      4      1.665      0.285  14952.766   -885.594
TB004      4      5      1.694      0.286  14524.672   -675.156
TB005      5      6      1.674      0.278  14093.406   -586.250
TB006      6      7      1.706      0.280  14886.203   -593.984
TB007      7      8      1.673      0.278  14701.672   -621.984
TB008      8      9      1.679      0.279  14679.766   -596.328
TB009      9     10      1.656      0.273  14332.391   -542.125
TB010     10     11      1.664      0.271  13803.750   -532.109
TB013     11     12      1.659      0.276  14099.484   -464.984
TB014     12     13      1.662      0.279  14266.328   -837.156
TB015     13     14      1.677      0.282  14236.234   -648.641
TB016     14     15      1.667      0.271  13439.641   -478.953
TB017     15     16      1.669      0.272  13633.375   -442.672

where:
Column 1 = bunch name
Column 2 = bunch number (starting from 1)
Column 3 = bunch number (starting from the # entered on the prompt: 
           "Enter bunch# to serve as first bunch")
Column 4 = averaged position (mm) (includes calibration, hardcoded in the 
           fitter)
Column 5 = averaged size (mm)     (includes calibration, hardcoded in the 
           fitter)
Column 6 = averaged amplitude (in 4 * ADC counts)
Column 7 = averaged baseline  (in 4 * ADC counts)

As mentioned earlier, a script such as ECLOUD_ETRAIN.COM can be used to run
bsmfitallavg and to  automatically subsequently plot the bunch sizes and
positions as a function of bunch number.