Merge pull request JeffersonLab#183 from JeffersonLab/tofcalMoreDoc

Tofcal more doc

TOF_calib/README

@@ -2,22 +2,40 @@ TOF TDC calibration of ALL paddle PMTS
 --------------------------------------
 This is a new calibration version that is modified to use the ADC signal amplitudes
 to determine the walk correction of the TDC times.
-The main script that controls all steps of the calibration "DOC_CALIB.csh" is modified
+The main script that controls all steps of the calibration "DO_CALIB.csh" is modified
 to do the meantime script and time difference script in parallel threads to improve
 speed when running on the farm nodes (requires two cores(nodes)).
-Of course prior to running the script the root files need to be available.
+Of course prior to running these scripts the basic root files need to be available.
 
-after the calibration there are python and root scripts that facilitate reviewing the results
+After the calibration there are python and root scripts that facilitate reviewing the results
 and writing the resulting calibration parameters to the database tables.
 
-The data base tables are new and have an appendix "_NEWAMP" to the table names.
+The latest CCDB data base tables that are now used to write the calibration results are:
+/TOF2/walkcorr_type : this contains a flag to indicate which walk correction type was used
+/TOF2/timewalk_parms_5PAR : contains the walk correction parameters
+/TOF2/timing_offsets_5PAR : contains the final timing offsets of the TDCs values of each PMT
+/TOF2/propagation_speed : contains the effective speed of light in each paddle
+/TOF2/adc_timing_offsets : contains the timing offsets for the ADCs values of each PMT
 
+Note: the "TOF2/" directory is to indicate that the calibration code is up to date to handle
+      the new TOF geometry. The code is backwards compatible to use the old geometry "TOF/".
 
-A) analyze data with plugin "TOF_calib"
-   creates root files in "localdir/tofdata_run####.root"            
-   add root files  together: "hadd big99999.root tofdata_run####.root ... tofdata_run####.root"
 
-B) All the callibration is now done with one command
+FIRST GENERATE THE ROOT FILES FROM RAW DATA REQUIRED FOR CALIBRATION:
+------------------------------------------------------------------------
+   analyze data with plugin "TOF_calib" (src/plugins/Calibration/TOF_calib/)
+   creates root files in "localdir/tofdata_run####_*.root"            
+   add root files  together: "hadd big99999.root tofdata_run#####_*.root"
+
+   Note: this is done prior to any calibration attempt. Most of the time this is done by a dedicated
+         operator who handles other detector skim data as well.
+   Note: For regular GlueX running about 60 raw evio files are required to get sufficient statistics
+         for the calibration. Generally the size of the summed up root file should be 10GB or more.
+         "summed up" means the root files from each evio file are added together using "hadd".
+
+THE ACTUAL CALIBRATION IS DONE IN STEPS CONTROLLED BY THE MASTER SCRIPT "DO_CALIB.CSH"
+---------------------------------------------------------------------------------------
+   All the callibration is now done with one command
    ./DO_CALIB.csh "####" where "####" is the run number
    the input data files is expected to be in localdir
    with the name "tofdata_run####.root"
@@ -27,18 +45,18 @@ The Following is a descrption of all the root scripts and shell scripts used:
 
 1) DO_CALIB.csh : main shell scripts that does it all
 
-2a) src/WALK.C root wrapper to compile the src/walk1.C scripts to run faster.
-    a) in root: .L src/walk1.C+g;
-    b) in root: walk1(####);
-
-2b) calculate walk correction parameters with src/walk1.C 
-    output: tof_walk_parameters_run####dat
-            tof_TDC_ADC_timediff_run####.dat
-            walk_results_run%%%%.root
-            tof_walk_parameters_run####.DB                : the walk parameters from the fit
-            adc_vs_tdc_relative_global_time_run####.DB    : global time difference between TDC and ADC
-            adc_vs_tdc_relative_time_run####.DB           : relative time differnece between TDC and ADC times
-
+2)  calculate walk correction parameters with src/walk1.C 
+    output: tof_walk_parameters_run#####dat
+            tof_TDC_ADC_timediff_run#####.dat
+            walk_histos_run#####.root
+            walk_results_run#####.root
+            tof_walk_parameters_run#####.DB                : the walk parameters from the fit
+            adc_vs_tdc_relative_global_time_run#####.DB    : global time difference between TDC and ADC
+            adc_vs_tdc_relative_time_run#####.DB           : relative time differnece between TDC and ADC time
+    Note: this one of the most critical steps and will result in the largest values of correction
+          for the timing. The functional form of the walk correction has been modifed several times and
+          as a result the subsequent use of these parameters is controlled by a flag located in the CCDB data base
+          table /TOF2/walkcorr_type. 
 
 3) domeantime.csh to calculate all meantimes for both planes
    it uses the root script wrapper src/MT1.C to compile and run
@@ -75,7 +93,7 @@ The Following is a descrption of all the root scripts and shell scripts used:
    tofpmt_tdc_offsets_all.dat
    tofpmt_tdc_offsets_all_run####.DB
 
-8) root -b -q "src/DOALLFIT.C(RUNNUMBER,10)"
+8) root -b -q "src/dofitall.C(RUNNUMBER,10)"
    get offsets for single ended readout paddles located at the center of the TOF
    runs src/dofitall.C
    output files:
@@ -90,6 +108,10 @@ The Following is a descrption of all the root scripts and shell scripts used:
                xTvsEPMTcorrN
                TimingX          timing histograms
 
+9) root -b -q "src/doadctimeoffsets.C+($RUN)"
+   calculate the timing offsets for the ADC time values based on their relative value to the 
+   corrected TDC times.
+