...11-Jun-2007
*******************************************************************************
****************   CESR BPM DAQ program (controls side)   *********************
*******************************************************************************

Located on VMS machine.
Current version in USER$DISK:[CESR.PALMER.TS101.BSM]
Development version in USER$DISK:[CESR.PALMER.TS101.BSM.DEV]

Before doing any work, type:

     @[CESR.PALMER.TS101.COM]init

This will assign some symbols, which can be of use when for instance analyzing
measurement data.

To compile either of these 2 versions, type @doit once you're in the correct
directory.

Once a new version of software has been tested in the .dev directory, one can
use the "backup" command to copy files to the main directory ("backup" will 
retain the creation date and time of the file"), e.g.
backup myfile.f;3 [-]myfile.f;3

Note that if one swaps modules, one will need to modify the GET_ADC_BUF.F
source code to reflect this change. This routine is used for getting data from
the DSP over the ethernet. Different modules have different (Coldfire) ethernet
addresses. A list of these addresses can be found in a table at:

https://wiki.lepp.cornell.edu/lepp/bin/view/CESR/Bunch/Coldfire_inventory 

The device number used in GET_ADC_BUF.F corresponds to the number in the
hostname that can be found in the above mentioned table. 

*******************************************************************************
To get the DSP executable from UNIX (assuming tanke as user), type:

ftp /user=tanke cesr34 
  "get cesr_home/ts101V4/bsm_v1/Debug/dsp_bsm_v1.ldr dsp_bsm_v1.ldr"

To flash the DSP memory type one of the following:
@DL_BSM_DAQLAB_2
@DL_BSM_DAQLAB_3
@DL_BSM23E
@DL_BSM23W
@DL_CHESS
The first one in case the DSP is connected to XBUS line 2 in the DAQLAB
The second one in case the DSP is connected to XBUS line 3 in the DAQLAB
The third one in case the DSP is connected at BSM23E
The fourth one in case the DSP is connected at BSM23W
The fifth one in case the DSP is connected in CHESS hutch B1
*******************************************************************************
To run the executable, type:
run BSM_V1.EXE

After which the program will pose some questions and propose a menu of routines
(see further down for the menu). After selecting a routine, the executable will
read default settings from a file like XXXX.INP, where the name XXXX describes
the location (currently GEO23W (for BSM23W), GEO23E (for BSM23E) and GEOCXR
(for the CHESS Xray unit in hutch B1) of the DSP and the type of routine (raw,
navg, tscan) for which the defaults are valid. Note that GEO23E_RT.INP,
GEO23W_RT.INP and GEOCXR_RT.INP are used by the geo routine. Below is an
example of such a file, GEO23W_RT_RAW.INP, which has default settings for raw
data taking at 23W. Note that the first 45 lines are ignored (they are still
there for historic reasons).


00000000000000000000000000000000  <--- Ignore lines from here up to
00000000000000000000000010000000       and including line 45
00000000000000000000000000000000
00000000000000000000000000000000
00000000000000000000000000000000
00000000000000000000000000000000
10000000000000000000100000000000
00000000000100000000000000000000
00010000000000000000000100000000
00000000000000100000000000000000
00000010000000000000000000100000
00000000000000000100000000000000
 0   48800
 1   48950
 2   48865
 3   48825
 4   48935
 5   48525
 6   48740
 7   48660
 8   48930
 9   48725
10   48710
11   49090
12   48890
13   49040
14   48700
15   48940
16   48700
17   48770
18   48630
19   48680
20   48676
21   48660
22   48470
23   48790
24   48760
25   48845
26   48805
27   48350
28   48820
29   48480
30   48680
31   48520
1                        <--- Ignore lines upto and including this line
8192                     <--- # of turns to take raw data over 
100                      <--- # of turns/average (used in other routines,
                              dummy value here)
240                      <--- Tglobal setting (global timing)
100, 100, 80, 110        <--- Card timings for cards 0,1,2 and 3 respectively 
-100, -1000, 10, 20, 450 <--- Shutter related parameters: channel current 
                              limit, total current
                              limit, shutter overcurrent cycles, 
                              HV overcurrent, HV setting
12                       <--- Dummy

The HV pedestal values can be read in from file HVPEDS.INP or be taken when
there is no beam in the machine. (Still to do: make one HVPEDS.INP file for 23W
and another one for 23E). Typically, when these needed to be reloaded, new
pedestals were taken when there was no beam in the machine. 

Note that for the BSM, the basic idea in terms of data acquisition is to first
of all have the HV switched on, such that the system can warm up. Further more,
upon existing the program, the HV will be turned off automatically. At any time
one can switch off the HV by typing the following on the command line:

@SET_23W_PMT_HV_OFF.COM
for BSM23W or the following for BSM23E:
@SET_23E_PMT_HV_OFF.COM

After choosing a routine, one can choose to have most settings taken from the
XXXX.INP file or  to enter them by hand. In either case, the last question
before acquisition starts will be one asking for the type of hardware trigger.

Bunches are given names (like T02B05E for Train2Bunch5 e- and T04B01P for
Train4Bunch1 e+. Bunch names used by BSM_V1.EXE are stored in the bunmap.txt
file. Again, a certain number of alternative bunch name files have been created
(e.g. PBUNMAP_ECLOUD.TXT) which can by copied to bunmap.txt prior to executing
BSM_V1.EXE.

*******************************************************************************
As mentioned, to run the executable, type:
run BSM_V1.EXE

You will get the following prompts:
Control Room (c) or Test (t) environment ?  
        Choose c for BSM23W, BSM23E or BSMCXR, t for tests in DAQlab. 
Assuming c:
BSM 23W (1), 23E (2) or CHESS X-ray (3) ?
        Assuming 2:

You will get a menu that looks like this:

           BSM23E (positrons) main menu

Exit                                            (0)
Time scan                                       (1)
Get raw data                                    (2)
Get sets of raw data (software triggered)       (3)
Get sets of averaged data                       (4)
Get updated geometric distribution for 1 bunch  (5)
Get n averaged data                             (6)
Test BSM Shutter                                (7)
Enter your choice ==>

After choosing a routine, one will see the following prompt:
Use default settings from file (y/n)
        If one wishes to be prompted, select y, otherwise select n.

For each of the data taking routines, one will need to select the bunches one
wants to take data on. 

If in prompt mode, a graphics menus will come up that allows one to select the
bunches data should be taken for. Typically one should also select at least one
"empty" bunch (i.e. one that holds no beam current) to serve as a pedestal in
the pedestal subtraction for further data analysis after the measurement. Note
that for routine (5) one should select one bunch only; no pedestals. The
default values are in the files ebunches.dat, bunches.dat and pbunches.dat;
these defaults can be changed by clicking on the save button in the graphics
display. If one does not click on the save button, the bunches selected will be
used for the measurement, but will not be stored in the file as new default.

If not in prompt mode, assuming @[CESR.PALMER.TS101.COM]init was typed earlier,
one may set the bunch selection before the measurement by typing
set_dsp_bunches xxxxx.dat

where xxxxx.dat can be any bunch selection file (e.g. ebunches.dat or
PBUNCHES_ECLOUD.DAT). The contents of a bunch selection file looks something
like:

00000000000000000000000000000000
00000000000000000000000000000000
00000000000000000000000000000000
00000000000000000000000000000000
00000000000000000000000000000000
00000000000000000001000000000000
         172
00000000001000000000000000000010
01000000000000000000010000000000
00000000000001000000000000000000
00001000000000000000000010000000
00000000000000001000000000000000
00000000000000000000000000010000

The first 6 lines contain zeroes and ones; these correspond to the 183 possible
bunches in CESR, whereby a 1 means the bunch is selected, a 0 means it is not.
There are an extra 9 zeroes here, which are not used for bunch selection, but
are needed for the format. The next line is a number in the range (0..182) and
is the DSP bunch number corresponding to T1B1 in CESR.

The last 6 lines correspond to the bunches which may be used for pedestals.
These one may set by typing:
           
   set_dsp_pedestals xxxxx.dat

where xxxxx.dat can be any bunch selection file (e.g. ebunches.dat or
PBUNCHES_ECLOUD.DAT). Again, a script may be used to copy a file like
PBUNCHES_ECLOUD.DAT to pbunches.dat. Note that pbunches.dat is the relevant
file for BSM23E, ebunches.dat is the relevant file for BSM23W and bunches.dat
is the relevant file for BSMCXR. 

*******************************************************************************
Output files produced by these routines are typically:

1) bsmvvv_cur_xxxxx.dat where vvv is 23W, 23E or CXR
2) bsm_paw_xxxxx.dat

where xxxxx is a five digit number that increments by one for each new
measurement. This number is updated in file FILE_NUM.INP

The first file (bsmvvv_cur_xxxxx.dat) contains general measurement and beam
related data as they were at the moment data were taken:

First line:  #selected bunches, # of turns, #turns per average
             that if #turns per average=1, the # of averages=# of turns)
Second line: selected bunch #, DSP bunch #

Following line(s) as second line if more than one bunch; followed by trigger
type, PMT HV setting, global and card timings, lattice name, bunch by bunch
info (currents, L, L/I), beamsizes, various  settings in the machine (including
synch light mirror positions) and saveset numbers. Towards the end there is a
timestamp and the status of the PMT current monitor board. Regarding channel
mapping pertaining to the current monitor board (CMB), please refer to:

https://wiki.lepp.cornell.edu/lepp/bin/view/CESR/Bunch/
        BSM23WLog_2005#April_25_2005_J_Dobbins_PMT_Chan

Specs of the CMB can be found at:
https://wiki.lepp.cornell.edu/lepp/bin/view/CESR/Bunch/CurrMonSpec

The second file contains the data taken. Note:
for timing scan (menu option 1);     files written to current directory. The 
                                     channel by channel data are in order
                                     of PMT channel number (see the following 
                                     link to learn about the mapping
                                     between ADC and PMT channel number:
https://wiki.lepp.cornell.edu/lepp/bin/view/CESR/
   Bunch/BSM23WLog_2005#April_25_2005_J_Dobbins_PMT_Chan

                                     In the case of timing scans, a third file
                                     (yyy=adc) will be  written, where channel
                                     by channel data are in order of ADC
                                     channel number. Four more files will be
                                     written like the third one, but  this time
                                     one file per ADC board. These files are
                                     are:
                                     ADCboard_0.dat
                                     ADCboard_1.dat
                                     ADCboard_2.dat
                                     ADCboard_3.dat

for raw data (menu option 2);        files written to current directory. The
                                     paw file is in binary  format. A third
                                     file will be written, containing pedestal
                                     values (here yyy=ped)

for multi-raw (menu option 3);       files written to current directory. Also
                                     in this case a third file will be written,
                                     containing pedestal values (here yyy=ped)

for averaged data (menu option 4);   files written to current directory. In
                                     this case a  third file will be written
                                     (yyy=plt) 
                                     (doesn't quite read the defaults right)

no files created for (menu option 5)

for n averaged data (menu option 6); files written to current directory. Data
                                     will be in binary format.

for testing shutter (menu option 7); files written to current directory. Also
                                     in this case a third file will be written,
                                     containing pedestal values (here yyy=ped).
                                     A fourth file (yyy=tsc) is also written;
                                     it contains the RMS values of the data in
                                     the mrt file.

*******************************************************************************
Brief description of routine (1): Time scan

For the selected bunches and channels, a timing scan will be made. In this
routine Tglobal will be stepped through whereby for each step, data will be 
measured as an average over a user specified number of turns. The step size is
set by the user. The DSP code stores these averages in SRAM and the VAX code
will read these out using the XBUS.  Output files are bsm_paw_xxxxx.dat (PMT or
geometric order), bsm_adc_xxxxx.dat (ADC order) and bsm_cur_xxxxx.dat
 
*******************************************************************************
Brief description of routine (2): Get raw data

For the selected bunches and channels, raw data will be taken over a user
specified number of turns. The VAX code will read these raw data directly from
the ADC buffers using the CBI_NET (ethernet). 

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

Brief description of routine (3): Get sets of raw data ("multi-raw",software
triggered) For the selected bunches and channels, raw data will be taken over a
user specified number of turns. After the first acquisition, the user will be
asked if another acquisition is required etc. The VAX code will read these raw
data directly from the ADC buffers using the XBUS. 

*******************************************************************************
Brief description of routine (4): Get averaged data

Sets of data will be taken whereby each set of data corresponds to data
averaged over a user specified number of turns (n_turns) for selected bunches
seen by all ADC  channels. These sets of data will contain averages which are
not "continuous". The  VAX code will read these averages from SRAM using the
XBUS. 

*******************************************************************************
Brief description of routine (5): Get updated geometric distribution for 1
bunch:

The geometric distribution plotted is one for averaged data. The number of
turns to average over can be changed in the apropriate .INP file. Interrupt the
plotting by typing a q. After this return to the main menu by typing  q again,
select s to change scale (subsequently one can select autoscale (default) or a
user definded vertical scale) c to simply continue acquisition. 

*******************************************************************************
Brief description of routine (6): Get n averaged data

N sets of data will be taken whereby each set of data corresponds to data
averaged over a user specified number of turns (n_turns) for selected bunches
seen by all ADC  channels. Data will be acquired over N * n_turns turns,
meaning that the data taken are "continuous" in time, the averages are
"continuous" averages. The VAX code  will read these averages from SRAM using
the XBUS. 

*******************************************************************************
Brief description of routine (7): Shutter test
Simple testing of the Current Monitor Board and shutter

*******************************************************************************
Output files have been (manually) copied to the linux/unix server:
/nfs/acc/temp/ts101/BPM23W_data , /nfs/acc/temp/ts101/BPM23E_data and
/nfs/acc/temp/ts101/BSMXRAY_data

Note that before doing so, it is advised to convert binary files to ASCII
before transferring them to the server (compatibility issue!). The reason why
binary  files have been used on the VAX is to gain speed in writing the data
files (they may be over 100 Mb !).

Use 
ftp -i cesr29
from a linux or unix box to transfer the files. sftp is not advised (it changes
the format). The -i option allows one to use the mget command inside ftp.

*******************************************************************************
*********************  CESR BSM DAQ data conversion  **************************
*******************************************************************************

Raw data files are written to a VAX disk in binary format because this is
faster than writing in ASCII (thus reducing the time between measurements).
However, VAX and UNIX/LINUX binaries are incompatible, whereas ASCII files can
be freely exchanged. 

To convert the binary measurement file to ASCII, one can use the following
executable, the source of which is a fortran program:
[CESR.PALMER.TS101.BSM]SORT_BUNCHES_B.EXE

Upon execution, it will ask for a (binary) file name; an example would be
bsm23e_paw_01113.dat;1

To make a straight conversion from binary to ascii, answer the prompts as
follows:
     
Enter starting bunch number 1 
Enter ending bunch number 16 <-- last bunch in the list

The program will create the new ASCII data file, which will include "_mod"
behind the measurement number (in this case: bsm23e_paw_01113_mod.dat;1 ). 

One can also use this program to change the order of the data around; some
analysis tools are set up to have the pedestal bunch as the last one in the
list, not the  first one).