TPC SC & GL Calibration: How To?

  This is a brief documentation for the TPC Space-Charge (SC) and Grid-Leak (GL) calibration. 
  Details on the parameters used in the Calib_SC_GL.C macro can be found in the link below (Gene's Blog):
  https://drupal.star.bnl.gov/STAR/blog/genevb/2013/mar/29/unified-spacecharge-gridleak-calibration-winter-2013


1. Attachements:
-:   "SampleDir.tar_.gz" contains all the calibration macros and directories SC&GL calibration for "Run 19 AuAu200 GeV" dataset.
        -:   All other attachments are supplemental materials helpful for SC&GL calibration.    
 
2.  SC&GL Calibration Procedure: How to?
* Log into online Run Browser: https://online.star.bnl.gov/RunLog/
* Select production trigger wanted to calibrate and select a range of runs to include in the TPC calibration.
  - These runs should span the entirty of the particular beam setting.
  - Make sure to sample various luminosities.
  - Copy and paste these runs into a fil, i.e. "st_physics_20154052_raw_3500001.daq"
* Goto https://www.star.bnl.gov/devcgi/FO/genlist.cgi and copy your file list into the empty field.
  - This will print out list that you can read by HPSS and tells it where to resore the particular daq files.
  - Copy that list into something like FileList.lis
* Run hpss_user.pl -f FileList.lis
  - This restorse the daq files from HPSS
 
Setup Calibration:
* Get the current calibration files for space charge and grid leak by calling the following (change the date accordingly):
  Old way:
    - root4star -b -l -q '/afs/rhic.bnl.gov/star/strange/genevb/CODES/MISC/Db.C("Calibrations/tpc/tpcGridLeak", 20130315,000001)'
    - root4star -b -l -q '/afs/rhic.bnl.gov/star/strange/genevb/CODES/MISC/Db.C("Calibrations/rich/spaceChargeCorR2", 20130315,000001)'
  New way:
    - root4star -b -l -q '$STAR/StRoot/macros/calib/Db.C("Calibrations/rich/spaceChargeCorR2", 20130315,000001)')
    - root4star -b -l -q '$STAR/StRoot/macros/calib/Db.C("Calibrations/tpc/tpcGridLeak", 20130315,000001)')
  --> Update CINT filename, only the time stamp, to make useful for later time stamps, for example 
           spaceChargeCorR2.20201210.000000.C --> spaceChargeCorR2.20201210.000100.C
      tpcGridLeak.20201210.000000.C.  --> tpcGridLeak.20201210.000100.C     
 
* Make a directory for your first iteration of the calibration and make the following directories
  - StarDb_GLx.xx, where x.xx is the current grid leak value from the calibration file
    - copy the space charge calibration file to StarDb_GLx.xx/Calibrations/rich/
    - copy the grid leak calibration file to StarDb_GLx.xx/Calibrations/tpc/
  - Make 2 more StarDb_GLx.xx directories where you increase and decrease the GL value by 0.5
    -Modify the gridleak calibration file accordinly to match the +/-0.5 GL value
  - Create histxxx, stderr/GLxxx, stdout/GLxxx, and stdzip/GLxxx, where xxx is the GL value (no decimal, i.e 9.8 becomes 980)
 
* Submit jobs
 - Jobs are submitted via the trial*.xml files.
--> In trial*.xml, modify bfc chain options for the particular dataset, which can be found in "Options in Production" under "Production" in star "Computing" page. Direct link to the page: https://www.star.bnl.gov/devcgi/dbProdOptionRetrv.pl
--> Some options: btof, mtd, btof, etofA, picoWrite, are not required for SC & Gl calibration. These options can be opt out with "-" option as  "-mtd -btof -etofA -picoWrite". 
 --> Be sure that "SCScalerCal" is included.
Submit jobs with the commands below: 
    Step 1. starver DEV. (Load library)
    Step 2. cons.   (compile)
    Step 3. star-submit -policy bnl_condor_cas trial*.xml (submit job)


  - there are 3 in total, one for each GL value (i.e nominal and +/- 0.5 of nominal)
 
* When jobs finished
- Make sure of the following
   - that they used to correct SC and GL values
   - that the SC ntuple was filled. You can do the following SC->GetEntries("sc"), this should give 1
     - if it gives 0, then you did not get enough events satisfying the required cuts.
 
* Running the Calibration
- The calibration is done using the Calib_SC_GL.C macro
- Load the Root file by "root -l -b /star/u/posik/TPC_Calib/TPC_Dir/Run18_AuAu27/Pass1/hist*/Hist*.root"
   - Change the path accordingly
   -Previous iterations can be included in the calibration by using in the above case .../Pass*/hist*/Hist*.root
- Now within Root after the files are loaded call ".x Calib_SC_GL.C+(0,0,-1,1)"
   - This will trigger the macro autofit and give you updated SC and GL calibration results
 
* Calib_SC_GL.C
  - The third argument in the call function can be set to the following
    '-1' = looks for a linear fit using only one scaler
    '-2' = looks for best fit using 2 scalers (also linear)
    '-3' = looks for best fit using 3 scalers (also linear)
    - You can also add any functional dependence on any scaler. For example typing ' "zdcx:zdcx^2" ' will
    use the zdcx scaler to make a quadratic fit.
  - The fourth argument in the call function sets different debug modes.
    '0' = no debug mode
    '1' = allows you to see how well the sc and gl values were fitted (This is usually the option that I use)
    '2' = Prints a lot of information, and even ranks various scaler fits.
  - We can also switch on/off east-west sc asymmetry.
    - This is found near line 131: Int_t EW_ASYMMETRY = kFALSE;
    - When this is set to kFALSE, we force east and west space charge to be symmetric
    - When this is set to kTRUE, we allow for east and west space charge to be asymmetric
         
  - Example Fit output
    USING STDDEV sc => 0.000193 :: gapf => 0.005584    
 
    SpaceCharge & GridLeak fit results {scaler: (3.81793e-09*(bbcx-292019))+(-1.76113e-09*(bbcw))+(1.09465e-07*(vpdw))}:
    g2              :       1.35915 +0/0 or +/- 0.0819402
    g2              :       1.35915 +/- 0.556308
    log(g5)         :       3.36485 +0/-2.1476 or +/- 0.434706
    log(g5)         :       3.36485 +/- 0.434706
    log(SC)         :       -0.00645855     +0.109786/-0.12168 or +/- 0.116902
    log(SC)         :       -0.00645855     +/- 0.115733
    SO              :       -5.16527e-06    +0.000269672/-0.000265086 or +/- 0.000271401
    SO              :       -5.16527e-06    +/- 0.000267379
    log(GL)         :       -1.13591        +1.97068/0 or +/- 6.21614
    log(GL)         :       -1.13591        +/- 6.21614
 
    *** FINAL CALIBRATION VALUES: ***
    sc = (1.0 +/- 0.1157)*(3.793e-09*(bbcx-(2.907e+05 +/- 7.003e+04))+(-1.75e-09*(bbcw))+(1.088e-07*(vpdw)))
      with GL =  0.32 +/-  2.00
 
- The 'USING STDDEV sc => 0.000193 :: gapf => 0.005584' line shows how well the quantities were fitted. The smaller the better.
- sc fit results are in line: "sc = (1.0 +/- 0.1157)*(3.793e-09*(bbcx-(2.907e+05 +/- 7.003e+04))+(-1.75e-09*(bbcw))+(1.088e-07*(vpdw)))"
   - Here we do not care about the +/- uncertainties
- gl result is here: "GL =  0.32 +/-  2.00"
- Updating calibration files:
   -spaceChargeCorR2.20190221.000000.C:
    - In the calibration file (like above), each scaler has a "row.fullFieldB" value, these are the numbers that multiply the scaler
    - In a linear fit, one of the scalers has a value called "row.offset", in the sample calibration output this value is 2.907e05 and is associated with the bbcx scaler.
    - The calibration file also has a "row.ewratio" when forcing symmetry this is just 1. If the fit is done allowing for the asymmetry, then put there the value that you get.
    - "row.detector" is where you specify the scaler. The numerical values can be found in the Calib_SC_GL.C macro near line 310
    - "row.factor" is exponent power on the scaler. For linear fits (like above) this is 1. If you make a non-linear fit then this needs to match the power on the scaler. For example if fitting using "vpdx^0.9", then "row.factor" would need to be set to 0.9 for that term.
    - Each scaler parameter will get its own entery. If you scoll down in the spaceChargeCorR2 file you will see lots of entries, with nearly all having "row.fullFieldB = 0", meaning they are not used.
   -tpcGridLeak.20190221.000000.C
    - The GL database file is simpler. You just enter your GL value from the fit in the "row.MiddleGLStrength", that's it!
- You are now ready to do another iteration where your submitted jobs now use the updated DB calibration files.
 
(Request to experts: Please feel free to add/update any missing informations.) 

-Babu Pokhrel (babu.pokhrel@temple.edu)