Old MolPol DAQ Analysis

Making Polarization measurements

Overview

Start dbedit on adaq1, select "mollerpol_l" database and set in "beam_pol" configuration table in row "code" parameter "adcevents" from 9 to 2: " ... adcevents=2"
Make at least two CODA runs in order to use both coil polarities.

Data analysis:

old DAQ: adaq1:~/paw/moller/

  > paw
  paw> exec run run=15625
  paw> exec lg_spectra run=15625
  paw> exec time run=15625
  paw> lcd mag_optim
  paw> exec anpow_set e0=7.37 (E0 - beam energy in GeV)
  paw> exec asym11 anpow=0.7735 gate=0.033 run=15625 (gate=0.033 for 30Hz helicity frequency and gate=0.0008 for 1kHz)

It is possible to read these files from the ~moller home directory using any account defined in the adaqfs computer system

Logic of the above series of programs:
- Establish the run in run.kumac, which also calls the rawrd.com (and it calls the rawread_Linux.exe code) to grab and decode the data and store it in NTuples.
- Execute lg_spectra.kumac with a run number.
  - This runs run.kumac again, as well as getrun.kumac, in order to obtain the data for that run and store it in PAW memory.
  - That data is then stored in a 1D histogram (identified by the run number + the channel number + some more digits) and is plotted from the NTuple.

Kumacs

pawlogon.kumac

pawlogon.kumac is located in the ~/paw/moller/ directory, containing Moller Polarimeter analysis specific aliases and initialization.

The pawlogon.kumac is run automatically at PAW startup, so it should not be neglected.
It sets graphing option settings, defines .ps file saving and printing aliases, and initializes.
The initialization macro is ini.kumac

ini.kumac

ini.kumac is located in the ~/paw/moller/ directory

It creates a series of vectors and does initial runs if the link command is > 0 (default it is not).
It creates pedes, pedcut, calib, par, and err variables and reads the default pedes.da and calib.dat files to fill them
It also does something with energy histograms, but I think it is just initializing them and assigning them to LUNs 69-78, 80, 81, 90, and 91
Command line arguments and defaults:
- MACRO ini link=0

run.kumac

run.kumac is located in the ~/paw/moller/ directory.

Initializes the run number to be used by getrun.kumac (which feeds the current run number into asym11.kumac or asym15.kumac, the analysis script of interest)
Command line arguments and defaults:
- MACRO run run=0 reload=0 clear=0 name=moller_data dirg=XX rawext=dat
- And the only thing that changes from the defaults is the run number when run from the command line as "paw> exec run run=NUMBER" (as shown in the section above)
Functionality:
- Reads nact (number of actions?) as $VDIM(lrun) and nfil (number of files) as $VLEN(lrun) (and these should be the same since dim was omitted and is assumed to be 1 for the $VDIM command).
- Sets dirg (data directory?) to /adaq1/data1/moller or /work/halla/moller/disk1/exp depending on the computer you log in from.
- Reads through the file list and throws away all empties and grabs an available LUN to run with (and uses goto's to skip around in the kumac, instead of function definitions as one would do in C++).
- "mfind file:" tries to read the actual files into PAW's memory.
- nf variable reads the number of lines in the NTuple file list's files = [fnamntu].
- If it finds a file then it runs it through rawrd.com and keeps reading the files.
- Outputs the current lun (NTuple data file loaded into memory) as mrun to be used in later analysis (lg_spectra.kumac)
The logic of getting the number of runs and assigning them to the temporary LUN or run number holding vectors looks circular in this program, but that is probably because it is cycling through LUN numbers to find an empty LUN to attach the data into.

getrun.kumac

getrun.kumac is located in the ~/paw/moller/ directory.

Takes the run number (set in run.kumac, on the command line, or in whatever script this gets run in), checks if there is data for that run, and fills irun and ilun with that data and stores it in PAW memory (this is executed from lg_spectra.kumac after running run.kumac in the same program).
Command line arguments and defaults:
- MACRO getrun lun=0 run=0
- And the only thing that changes from the defaults is the run number when run from the command line as "paw> exec run run=NUMBER" (as shown in the section above)
Functionality:
- Reads the mrun and lrun vectors that were set in run.kumac and assigns their LUN contents to the irun and ilun output vectors for later use.

rawrd.com

rawrd.com is located in the ~/bin/ directory (with the base version located in ~/analysis/raw-ntup/) and is a BASH "command" file (not a PAW KUMAC) which converts a raw CODA data file into a PAW NTuple.

cd's and runs from the ~/analysis/raw-ntup/ folder.
Ultimately will run a rawread_Linux.exe executable (in the same ~/analysis/raw-ntup/ folder) on the raw CODA data it finds.
Searches for and symlinks to a raw data file found in diraw=/adaqs3/data4/ folder (default, but in the run.kumac file it is adaq1/data1/moller/).
Defines the raw file to be read as filer=$diraw/"*_"$run."$dext" (where $dext is a user input variable, defaulting to "dat", and $run is also user input from the run.kumac place where it is run).
- Basically this means it searches in the user defined place (defaults to /adaqs3/data4/) for files with the name structure anything_RunNumber.dat and executes the rawread_Linux.exe executable on them (which I assume is compiled from the rawread.f fortran code).
Resulting output files have suffix .nt (for NTuple).
Most of the script is moving symlinks around and checking for non-trivial file size and permissions.

rawread.f/rawread_Linux.exe

rawread.f is a Fortran code located in the ~/analysis/raw-ntup/ folder that is compiled by the lnkr bash script (and renamed) into rawread_Linux.exe and serves as a decoder for raw CODA data from the Moller Polarimeter DAQ.

Reads a raw CODA file and turns it into an NTuple.
Reads all of the CODA Moller Polarimeter DAQ specific data file header words and crawls through the CODA data file's initialization words until it gets to the raw data itself
Reads out event data and banked data into arrays
Stores data into relevant NTuple branches
It knows what lengths the different data types should be and robustly diagnoses errors, but this means any deviation from the standard expected data types, header words, or bank structures will fail to be decoded correctly, and the reasoning for most of the decoding is not clear or commented in the code. So making any changes would require expert knowledge or a lot of digging for information.

Functionality of rawread.f

This is a compiled fortran program

It has a max event length of 8192, and max number of events of 10 million, and max number of books of 200 thousand.
It includes ../inc/cevcoda.inc, crntup.inc, crntup1.inc, and crflag.inc
- These are responsible for defining the variables and what they are for event data and converting from raw into NTuples.
Lines 1 - 277 are the main program, and the second half of the program defines functions for use inside the main program.
Lines 279 - 337 are the NTuple opening RNTUPIN(return_value) method.
- This just generates a new NTuple with the structure needed to put events into later.
- If it somehow fails (when executing CALL HROPEN(2,'adctdc','adctdc.nt','N',lrec,istat)) then its return value will be 1, and it and the main program will terminate.
- The 2 in there means that it is trying to open lun number 2 (I am grasping at straws, but those that use kumac/paw frequently may be able to help).
Lines 339 - 363 are the event initialization REVEINI method.
Lines 365 - 551 are the primary moller event decoding MOLDECEV(nwords,buffer) method.
Lines 553 - 577 are the NTuple filling RNTUPEV method.
Lines 579 - 593 are the NTuple closing RNTUPCL method.

What does the data actually look like?

Running the evio2xml command on a data file lets us see the contents of a data file in plain text.

evio2xml /adaq1/data1/moller/moller_data_15025.dat
Then the output looks like so (see especially the first few events, the last few, and a vimdiff of the first and second full events).

Going through it in detail:

Event 1 and 2 have 5 words, 3 of which are inside of a bank.
All other events have 53 words (though only 44 of them are inside of a big bank, and another smaller bank with 3 words only increments for the event number).
23 of the 44 words change, and usually only in the last 3 hexidecimal places (~ +- 4000 in decimal, out of potentially tens of billion)

lnkr

lnkr is a shell script located in ~/analysis/raw-ntup that checks the OS type and uses the appropriate compilation procedure for that. For linux (what we are using) it does:

gfortran rawread.f /site/coda/2.5/Linux/lib/libcoda.a -L /apps/cernlib/i386_rhel5/2005/lib -lpacklib -o rawread_"$os".exe
The script only works if you are logged into the "hamoller" computer (same credentials)

lg_spectra.kumac

lg_spectra.kumac is located in the ~/paw/moller/ directory.

Fills and fits the lead glass calorimeter (LG) spectra with pedestal subtraction
Command line arguments and defaults:
- MACRO lg_spectra id0=-1 nlun=0 run=0 fill=1 chw=4 ncha=256 icut=0 fit=0 cut=0 ped=1 clear=1
- And the only thing that changes from the defaults is the run number when run from the command line as "paw> exec lg_spectra run=NUMBER" (as shown in the section above).
- id0 is the histogram offset, nlun is NTUPLE name (lun21 or lll - for the chain) or run number.
- 'fill' = 0 means only fit but the default is = 1, chw = channel width, nchan = number of channels.
- icut = additional cut on channel number, chw goes to histogram bin width in ADC channels.
- fit fits the plots, cut = 0 no additional cut, if = b then use cut $[n] to fill the plots.
- ped = 0 means do not subtract pedestals, but the default is set to 1.
- clear > 0 will erase all histograms at the beginning for a new run, and is default set to 1.
Functionality:
- Creates parlg vector (3 by 12). Gets filled at the end with the contents of the par(entries 1 through 3) vector in a loop over i from 1 to 12.
- Takes the run from the PAW exec command line and runs getrun.kumac to get the current run data.
- Reads pedestal data from pedes_N.dat where N is chosen based on the current run number (hardcoded list of runnumbers in the kumac file), and then shifts the pedestal cut value around based on an external cut (if there is one, default set to 0 meaning there is no affect) given by icut.
- A 1D histogram is created with the limits from the pedestal cut to the max value (channel width * N channels), it is then filled with the data obtained from getrun.kumac and stored in ilun (which comes from the mrun variable in run.kumac) which is transmitted into lun->nlun, and the iadc number of ADC entries' (set in rawread.f) data points are read in (again this is a rather convoluted procedure, but I think it makes sense).
- There are several options for how this program will either calculate or read the data and plot the data, but the default is to simply read the .dat file and cut on nadc>11 and plot for all 12 channels (this line, number 120 in the file, is actually very unclear, but I think it makes sense).

time.kumac

time.kumac is located in the ~/paw/moller/ directory.

Takes the run number (set in run.kumac, on the command line, or in whatever script this gets run in), gets the data with getrun.kumac and assigns the data to lun and run to be plotted later.
Command line arguments and defaults:
- MACRO time lun=0 run=0 id0=-1 fill=1 log=0 n1=155 n2=190 clear=1 siz=0.4
- And the only thing that changes from the defaults is the run number when run from the command line as "paw> exec run run=NUMBER" (as shown in the section above).
Functionality:
- Defines a bunch of Time sequence histograms and loops over them filling them with the data from the LUN loaded in getrun.kumac, and then plots them.

anpow_set.kumac

anpow_set.kumac is a short macro located in the ~/paw/moller/mag_optim/ directory.

Takes the beam energy in GeV and calculates the analyzing power for asymmetry (asym11.kumac).
Command line arguments and defaults:
- MACRO anpow_set e0=6.0
- And the only thing that changes from defaults is the beam energy (set in the command line as shown above).
Functionality:
- Calculates ap1, ap11, and ap = ap1 + ap11 from complicated functions
  - ap1=$sigma(0.80505-0.67685E-01*[e0]+0.24454E-01*[e0]**2-0.37949E-02*[e0]**3)
  - ap11=$sigma(0.27325E-03*[e0]**4-0.74346E-05*[e0]**5)
  - ap=[ap1]+[ap11]
In the analysis scheme shown above the analyzing power is read from the standard output and entered by hand in the asym11 program, rather than it setting an environment variable as is done in many other places.

Asymmetry Kumac

Because the asymmetry calculation macro is so long and has so many sub-macros, it gets its own section.

asym11.kumac

asym11.kumac is the primary macro involved in analyzing data for the Moller polarimeter and is located in the ~/paw/moller/ directory. "11" stands for 2011, when it was updated to work with the tilted Iron Foil target.

Calculates polarized moller scattering EM asymmetry (for tilted polarized iron foil target)
Command line arguments and defaults:
- MACRO asmym11 id0=-1 nlun=0 run=0 ncha=-1 n1=1 n2=999999 nevadc=-1 angl=19.95 anpow=0.7481 ptar=0.08036 norm=1 norbcm=1 nocut=0 coil=0 gate=0.033 mxdiff=50 clear=1 delay=-1 heladc=0 nococut=0 nosubbg=0 tauto=1 pr=5 force=0
- id0 is the histogram offset, nlun is the NTuple name
- angl is the target angle (default setting is 19.95), and anpow is the analyzing power (default to 0.7481, and it is set manually in the prescription described in the above section), and ptar is the target polarization (defaults to 0.08036)
- pr is the target polarization normalization coefficient (set to 5 default), nevadc is the number of adc triggers per window to select (<0 == all, and default is -1, so all), and heladc>0 means take the helicity from the ADCs (default == 0, so no)
Functionality:
- It clears any old histograms in memory, executes run.kumac for safety, and loads the settings from get_settings.kumac or get_settings_2009.kumac depending on run number < 13000 or > 13000 - loads the settings in run_sett() - 120 long array - and assigns variables to the various run_sett entries.
- Executes asymwr11.kumac is force>0 (which it is not by default, ), and run_scalu.kumac or run_scal11.kumac depending on the gate number value (default is 0.033, which executes run_scalu.kumac).
- Makes a bunch of 1D histograms for the asymmetry in the calorimeters and scintillators (line 144)
- Makes a bunch of NTuples using a_asymm.f (line 151, etc.)
- Automatically finds the target foil being used (if tauto>1, which it is by default) and automatically finds the polarization using get_targpol.kumac

get_settings.kumac

get_settings.kumac is the old version of reading settings from a file into a vector for later use, located in ~/paw/moller/ directory.

Gets the settings into an array run_sett(100)
Command line arguments and defaults:
- MACRO get_settings run=0 clear=0
Functionality:
- Finds the settings file

if $INDEX([host],'adaq')>0 then
dirm=/adaqfs/home/moller/daq/coda2/RunInfo
elseif $INDEX([host],'haplix')>0 then
dirm=/data2c/user/gen/moller/exp
elseif $INDEX([host],'ch-dom')>0 then
dirm=/v3/user/gen/data/moller/exp
endif
fmong='mollerrun_'//[run]//'.set'

- Calls get_set.f and fills the vectors with the settings information
- Calls targpos.f([run]) at the end

get_sett.f

Located in ~/paw/moller directory

Subroutine, actually reads the settings file (fort.2) with variable definition (fort.1)
Called in get_settings.kumac

targpos.f

Located in ~/paw/moller directory

Subroutine, finds the beam/target coordinates and the target number using the run_sett vector (from get_settings.kumac) and puts results back into that vector (entries target number = 101, x position = 102, and y position = 103.
Called at the end of get_settings.kumac

get_settings_2009.kumac

Located in ~/paw/moller directory get_settings_2009.kumac is identical to the standard one described above, except that it has multiple options for the run_settings.tab files depending on run number, and it has a goto (to skip irrelevant steps?)

asymwr11.kumac

asymwr11.kumac is located in ~/paw/moller directory, and writes the asymmetry ntuple file.

Command line arguments and defaults:
- MACRO run_scalu run=0 clear=0 dirg=XX delay=9 gate=0.033
Functionality:
- Loads in the run_sett.f settings, gets the get_targpol.kumac target polarization, and reads data from the NTuple file using getrun.kumac and run.kumac if needed.
- Writes data to scal.nt NTuple using zugtofile10.f to parse, and puts it into the NTuple with antwri.f.

zugtofile10.f

zugtofile10.f is the main data parsing code that actually writes the NTuple file from the raw data for use in polarization calculations and should probably be read through more carefully.

Real Function that takes scaler data and writes to NTuples, located in ~/paw/moller directory. Called towards the end of asymwr11.kumac for creating an NTuple with parameters developed earlier.
- Writes the data "trains" in reverse order, delayed by the helicity delay time (typically 8 cycles).
- Stores the helicity signals, target angle, helmholtz current, and all scaler data from raw into NTuple (stored in RAM? To be saved to file in antwri.f?)

antwri.f

antwri.f is (Asymmetry NTuple Write, I assume) the subroutine that writes an NTuple of scaler train data - it is not clear to me how this is a different purpose than zugtofile10.f, but it is significantly simpler and doesn't parse nearly as much information, so maybe it is making a smaller and simpler NTuple for another purpose. It is called at the end of asymwr11.kumac

Subroutine that writes a scaler train NTuple and is located in ~/paw/moller directory.
- Uses information developed earlier and the "zug" from zugtofile10.f (I think) to make a new NTuple output file.
- Includes antpini.f, antevini.f, antfil.f, and inc/cntasym.inc.

inc/cntasym.inc

inc/cntasym.inc is "Data for the asymmetry NTUPLE", located in ~/paw/moller/inc directory

It defines a bunch of the variable names that are to be used in antwri.f

antpini.f (and antevini.f, antfil.f)

antpini.f is a subroutine that initialize and assign variables to NTuple branches, located in ~/paw/moller directory. The others are just modifying a few values.

run_scalu.kumac

run_scalu.kumac attaches a scaler ntuple file with a given run number (starts with LUN #51)

Command line arguments and defaults:
- MACRO run_scalu run=0 clear=0 dirg=XX delay=9 gate=0.033
Functionality:
- Behaves a lot like get_run.kumac, and executes run.kumac and asymwr1.kumac if there is no scaler NTuple available
- Reads from moller_scal_[run].nt file (and the only run_scal11.kumac difference is that there is now a folder called moller_scal\ and the files it reads are inside with names *[run].nt ("modified for led runs")
- It looks like the main result of this kumac is to assign a 1 or 0 in a vector called ktyruns based on whether or not the run is an "_led_" run (obtained by cat'ing the NTuple that is being read in)

a_asymm.f

get_targpol.kumac

Terminology

PAW

PAW = "Physics Analysis Workstation", is an interpreted Fortran based language used in High Energy and Nuclear Physics data analysis.
PAW (CERN User's Guide) is "PAW is an interactive utility for visualizing experimental data on a computer graphics display. It may be run in batch mode if desired for very large and time consuming data analyses; typically, however, the user will decide on an analysis procedure interactively before running a batch job." - which basically means it does the same kind of interpreted analysis work that ROOT does, except in Fortran instead of C++.
PAW was designed and used with Fortran and systems that had some hardware limitations, which is where a number of the anachronistic things like pre-reserved memory slots, postscript printing, and finite line-widths originated, and is why PAW has been largely replaced by ROOT in modern nuclear and particle physics applications.

KUIP

KUIP = "Kit for a User Interface Package", is the user interface designed to work with PAW. It is analogous to ROOT, and includes a command line interface (CLI) and GUI interfaces similar to ROOT's TBrowser and assorted histogram and canvas interfaces, and they operate similarly.
CERN user guide here.
KUMACs are "KUIP Macros" and are interpreted PAW macro scripts that can be run in batch mode.

LUN/lun

LUN = "Logical Unit Number" - a lun is a METAFILE descriptor number ranging from 1 to 100.
From Brad Sawatsky's PAW FAQ: "Some PAW commands ( HISTOGRAM/FILE, FORTRAN/FILE etc ...) have a parameter named lun. This parameter is a "logical unit number" on which are attached files. Some of these "logical unit number" are reserved by PAW and associated packages. The following table gives the list of the reserved units."
- The table says 5-19 are reserved, and so are most of 81-91 and 97 - therefore most of the KUMACs discussed here start with lun 21.
To print a file do
- fort/file lun {filename.ps} - opens the file lun
- meta lun - makes it into a .ps file
- close lun - closes