View source for Old MolPol DAQ Analysis

== Making Polarization measurements ==
=== Overview ===
<ol>
<li>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'''"
<li>Make at least two CODA runs in order to use both coil polarities.			
<li> Data analysis:
* old DAQ:  ''adaq1:~/paw/moller/''
<pre>
  > 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)
</pre>
* It is possible to read these files from the ~moller home directory using any account defined in the adaqfs computer system 
</li>
</ol>
* 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.
* 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 [https://mocha.physics.sunysb.edu/cameronc/files/molpol/Run_15025_evio2xml_truncated.txt looks like so] (see especially the [https://mocha.physics.sunysb.edu/cameronc/files/molpol/evio2xml_1.png first few events], [https://mocha.physics.sunysb.edu/cameronc/files/molpol/evio2xml_end.png the last few], and [https://mocha.physics.sunysb.edu/cameronc/files/molpol/diff_evt_3_4.png 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 ([http://www2.pv.infn.it/~sc/cern/paw.pdf 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 [http://cds.cern.ch/record/209205/files/CM-P00065574.pdf 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 [https://userweb.jlab.org/~brads/Manuals/pawfaq/ 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
== Command Descriptions ==
See also [http://www.hep.vanderbilt.edu/~focuser/reference_manual/ Command Reference Manual]
* ve/cr = Vector/Create
* $VDIM(name,dim) = returns the size of vector "name" along the "dim" dimension (default = 1 if not explicitly set)
* $VLEN(name) = returns the location of the last non-zero element of a vector (acts like $VDIM but for 1 dimensional arrays)
* $SHELL(command,n) = returns the nth line of output from the given shell command
* [macro variable] = gets interpreted as a number if possible (macro variables are all initially strings, but PAW does a lot of gymnastics to convert strings into numbers intelligently, and there are ways to force interpretations to happen or not to happen in ways you want - see [http://www2.pv.infn.it/~sc/cern/paw.pdf section 3.5 of the PAW guide] for lots of detail)
* $SIGMA(vector operations) = uses the SIGMA vector manipulation application to return a PAW vector