Difference between revisions of "Start Counter Calibration Procedures"

From GlueXWiki
Jump to: navigation, search
(Added section references)
(ST Time Walk Plugin "st_tw_corr_auto")
(17 intermediate revisions by the same user not shown)
Line 1: Line 1:
 +
== '''November 2022: Currently Under Construction!!!''' ==
 +
 +
== '''Warning''' ==
 +
 +
Some of the procedures described here will commit calibration constants to a database that is used by the entire collaboration. Extreme  care must be taken to not inadvertently write to the database. When writing to the database, this should be discussed and coordinated with experts.
 +
 +
No calibrations should be uploaded to the database until after the final third step of the calibration procedures, i.e., until after having checked the impact on the timing resolution. In order to check this impact you should work with a local copy of the database. Do the following:
 +
 +
=== Working with a private SQLite file ===
 +
 +
This follows recommendations from a presentation by Rupesh Dotel and Sean Dobbs<ref> Rupesh Dotel and Sean Dobbs, Start Counter Recalibration, March 5, 2020, [https://halldweb.jlab.org/doc-private/DocDB/ShowDocument?docid=4371 GlueX DocDB #4371]</ref>
 +
 +
* Copy the latest sqlite file (eg : /group/halld/Software/calib/ccdb_sqlite/latest_version.sqlite) to your work directory (in this example the latest version is called ''ccdb_2022-11-10.sqlite''.
 +
* Configure your environment to use the private copy of ccdb (not the master) with
 +
  setenv CCDB_CONNECTION sqlite:///{$PWD}/ccdb_2022-11-10.sqlite
 +
  setenv JANA_CALIB_URL sqlite:///{$PWD}/ccdb_2022-11-10.sqlite
 +
This needs to get done after having set up your GlueX environment; otherwise, setting up the environment will overwrite this. You should check that CCDB uses your local copy by starting an interactive session:
 +
  ccdb -i
 +
This should show you that CCDB is connecting to your local file and not the master file.
 +
 
== Introduction ==
 
== Introduction ==
  
This page describes the calibration procedures for the [Start Counter]. If you are not familiar with the concepts of time-walk effect and propagation time in scintillators, you should read ''Chapter 4: Start Counter Calibration'' in Eric Pooser's dissertation<ref>Pooser, Eric J., "The GlueX Start Counter & Beam Asymmetry <math>\Sigma</math> in Single <math>\pi^{0}</math> Photoproduction" (2016). FIU Electronic Theses and Dissertations. 2450. [https://digitalcommons.fiu.edu/etd/2450 https://digitalcommons.fiu.edu/etd/2450]</ref>.
+
This page describes the calibration procedures for the [[Start Counter]]. If you are not familiar with the concepts of time-walk effect and propagation time in scintillators, you should read ''Chapter 4: Start Counter Calibration'' in Eric Pooser's dissertation<ref>Pooser, Eric J., "The GlueX Start Counter & Beam Asymmetry <math>\Sigma</math> in Single <math>\pi^{0}</math> Photoproduction" (2016). FIU Electronic Theses and Dissertations. 2450. [https://digitalcommons.fiu.edu/etd/2450 https://digitalcommons.fiu.edu/etd/2450]</ref>.
  
 
The procedure employs three plugins, which are used to analyze raw data files (evio):
 
The procedure employs three plugins, which are used to analyze raw data files (evio):
Line 12: Line 32:
  
 
== ST Time Walk Plugin "st_tw_corr_auto" ==
 
== ST Time Walk Plugin "st_tw_corr_auto" ==
This plugin must run in two passes. In the first pass the parameter USE_TIMEWALK_CORRECTION = 0.Therefore this plugin will generate a ROOT file from an EVIO data file that contains histograms of the time difference (self timing) versus pedestal-subtracted pulse peak amplitude for all 30 start counter sectors. A separate ROOT macro (st_tw_fits.C) will analyze and fit these histograms and provide a table for the CCDB. After uploading the constants into the CCDB, the plugin must run the second pass where USE_TIMEWALK_CORRECTION = 1. The Walk corrected times will be calculated during this pass. The ST self timing resolution is calculated using the macro st_tw_resols.C. In this macro verification plots for each sector is also created.
 
  
Plugin Files:
+
The signals from the start counter's silicone photomultipliers (SciPMs) are split into two branches. One is processed by leading edge discriminators; the discriminator output, which is subject to the pulse height dependent time-walk is fed into F1TDCs. The second branch is fed into the FADC250, which record pulse height as well as timing. The FADC time can serve as a reference time to extract the time-walk corrections for the F1TDCs.
 +
 
 +
The plugin, which creates the histograms, and the root macros, which analyze the histograms can be inspected at [https://github.com/JeffersonLab/halld_recon/tree/master/src/plugins/Calibration/st_tw_corr_auto GitHub] and on your local installation at $HALLD_RECON_HOME/src/plugins/Calibration/st_tw_corr_auto. There you will find the following plugin and macro files:
 +
* Plugin Files:
  
 
     JEventProcessor_st_tw_corr_auto.cc
 
     JEventProcessor_st_tw_corr_auto.cc
 
     JEventProcessor_st_tw_corr_auto.h
 
     JEventProcessor_st_tw_corr_auto.h
Macros Files:
+
* Macros Files:
 
     st_tw_fits.C
 
     st_tw_fits.C
 
     st_tw_resols.C
 
     st_tw_resols.C
To run the plugin, use the following command:
 
  
hd_root -PPLUGINS=st_tw_corr_auto /path/to/datafile
+
This plugin must run in two passes. The first pass generates uncorrected timing distributions; a macro extract parameters for the time walk corrections. In the second pass, the time walk corrections are applied and verified. This is controlled from the command line by the parameter SC:USE_TIMEWALK_CORRECTION (see [https://github.com/JeffersonLab/halld_recon/blob/master/src/plugins/Calibration/st_tw_corr_auto/JEventProcessor_st_tw_corr_auto.cc JEventProcessor_st_tw_corr_auto.cc] for details.)
To run the first pass macro , use the command :
+
.x st_tw_fits.C("hd_root.root")
+
  
The file st_timewalks.txt will be created with the needed constants for the walk corrections. To upload these constants into the CCDB use the command:
+
The following shows an example of how to run the plugin on ifarm at Jefferson Lab for a raw data file from the PrimeX fall 2022 run:
Add timewalk_parms_v2 st_timewalks.txt
+
 
After running the plugin for the second time, run the macro st_tw_resols.C using the command
+
  hd_root /cache/halld/RunPeriod-2022-08/rawdata/Run110896/hd_rawdata_110896_000.evio -PPLUGINS=st_tw_corr_auto -PNTHREADS=8 -PSC:USE_TIMEWALK_CORRECTION=0
 +
 
 +
If this worked, you will have a newly created file hd_root.root, which contains five histograms for each of the 30 scintillator paddles of the start counter. For each counter the first three will be filled,
 +
  stt_vs_pp_chan_*
 +
  pp_chan_*
 +
  h_stt_chan_*
 +
The other two will be empty. The first histogram, ''stt_vs_pp_chan_*'', shows ... . This histogram exhibits the pulse height dependent time walk for the FTDC signals. The macro ''st_tw_resols.C'' will fit the time walk correction coefficients. If you have not done yet, you should copy the root macros to your working directory
 +
  cp $HALLD_RECON_HOME/src/plugins/Calibration/st_tw_corr_auto/macros/* .
 +
Now start a root session and then run the first pass macro
 +
  .x st_tw_fits.C("hd_root.root")
 +
 
 +
The file st_timewalks.txt will be created with the needed constants for the walk corrections. '''After verifying that you use a local copy''' you can upload these constants into the local CCDB use the command:
 +
  ccdb add START_COUNTER/timewalk_parms_v2 st_timewalks.txt
 +
 
 +
Now run the second pass of the plugin:
 +
  hd_root /cache/halld/RunPeriod-2022-08/rawdata/Run110896/hd_rawdata_110896_000.evio -PPLUGINS=st_tw_corr_auto -PNTHREADS=8 -PSC:USE_TIMEWALK_CORRECTION=1
 +
Then start a root session and run the second pass macro
 
  .x st_tw_resols.C("hd_root.root")
 
  .x st_tw_resols.C("hd_root.root")
 
Examples of the excpected plots can be found here [https://halldweb.jlab.org/talks/2015/ST_meeting_Nov19_2015.pdf ST_tw_corr]
 
Examples of the excpected plots can be found here [https://halldweb.jlab.org/talks/2015/ST_meeting_Nov19_2015.pdf ST_tw_corr]
 +
 
== ST_Propagation_Time ==
 
== ST_Propagation_Time ==
This plugin must run after we have the walk corrected times from the ST and TOF. The first pass of this plugin will generate a ROOT file from an EVIO data file that contains histograms of the ST propagation time versus Z coordinate of the ST hit location for all 30 start counter sectors. A separate ROOT macro (st_prop_time_v1.C) will analyze and fit these histograms and provide a table for the CCDB through an output text file named (st_prop_time_constants.txt). In order to add these constants to the CCDB use the Command :
+
This plugin must run after we have the walk corrected times from the ST and TOF. '''(How do we know that TOF has been calibrated???)'''
  Add  propagation_time_corr st_prop_time_constants.txt
+
 
 +
Following the example above, you run the plugin:
 +
  hd_root /cache/halld/RunPeriod-2022-08/rawdata/Run110896/hd_rawdata_110896_000.evio -PPLUGINS=ST_Propagation_Time -PNTHREADS=8
 +
Note that on farm with 8 threads, this plugin runs at ~90 Hz. For a first check, you might want to limit the number of events by running with parameter ''-PEVENTS_TO_KEEP=100000'', for example. The author (J.R.) has not yet established how much statistics is necessary for a good calibration.
 +
 
 +
 
 +
The first pass of this plugin will generate a ROOT file from an EVIO data file that contains histograms of the ST propagation time versus Z coordinate of the ST hit location for all 30 start counter sectors. A separate ROOT macro (st_prop_time_v1.C) will analyze and fit these histograms and provide a table for the CCDB through an output text file named (st_prop_time_constants.txt).  
 +
 
 +
'''After verifying that you are working with a local copy of the CCDB''', you can add these constants with the command :
 +
  ccdb add START_COUNTER?propagation_time_corr st_prop_time_constants.txt
  
 
To check that these constants work fine run the plugin in the second pass using the command:
 
To check that these constants work fine run the plugin in the second pass using the command:
Line 43: Line 88:
  
 
When the corrected times are calculated use the ST_Tresolution plugin to calculate the ST time resolution.
 
When the corrected times are calculated use the ST_Tresolution plugin to calculate the ST time resolution.
 +
 
== ST_Tresolution ==
 
== ST_Tresolution ==
 
This plugin must run after the ST propagation time constants are uploaded in the CCDB. This plugin will generate a ROOT file from an EVIO data file that contains histograms of the ST corrected time for each paddle versus Z coordinate of the ST hit location. To run the plugin use the hd_root command mentioned in section 1 of this page. To run the macro use the command :
 
This plugin must run after the ST propagation time constants are uploaded in the CCDB. This plugin will generate a ROOT file from an EVIO data file that contains histograms of the ST corrected time for each paddle versus Z coordinate of the ST hit location. To run the plugin use the hd_root command mentioned in section 1 of this page. To run the macro use the command :

Revision as of 15:56, 18 November 2022

November 2022: Currently Under Construction!!!

Warning

Some of the procedures described here will commit calibration constants to a database that is used by the entire collaboration. Extreme care must be taken to not inadvertently write to the database. When writing to the database, this should be discussed and coordinated with experts.

No calibrations should be uploaded to the database until after the final third step of the calibration procedures, i.e., until after having checked the impact on the timing resolution. In order to check this impact you should work with a local copy of the database. Do the following:

Working with a private SQLite file

This follows recommendations from a presentation by Rupesh Dotel and Sean Dobbs[1]

  • Copy the latest sqlite file (eg : /group/halld/Software/calib/ccdb_sqlite/latest_version.sqlite) to your work directory (in this example the latest version is called ccdb_2022-11-10.sqlite.
  • Configure your environment to use the private copy of ccdb (not the master) with
 setenv CCDB_CONNECTION sqlite:///{$PWD}/ccdb_2022-11-10.sqlite
 setenv JANA_CALIB_URL sqlite:///{$PWD}/ccdb_2022-11-10.sqlite

This needs to get done after having set up your GlueX environment; otherwise, setting up the environment will overwrite this. You should check that CCDB uses your local copy by starting an interactive session:

 ccdb -i

This should show you that CCDB is connecting to your local file and not the master file.

Introduction

This page describes the calibration procedures for the Start Counter. If you are not familiar with the concepts of time-walk effect and propagation time in scintillators, you should read Chapter 4: Start Counter Calibration in Eric Pooser's dissertation[2].

The procedure employs three plugins, which are used to analyze raw data files (evio):

  • 1) Start Counter Time Walk Corrections Plugin (st_tw_corr_auto)
  • 2) Start Counter Propagation Time Corrections Plugin (ST_Propagation_Time)
  • 3) Start Counter Time Resolution Plugin (ST_Tresolution)

These plugins provide histogram files, which subsequently are analyzed with root macros. You can find and inspect these plugins and their associated root macros on GitHub or in your local installation at $HALLD_RECON_HOME/src/plugins/Calibration. A summary of how to run each code and the expected outcomes of the macros will be shown in details below

ST Time Walk Plugin "st_tw_corr_auto"

The signals from the start counter's silicone photomultipliers (SciPMs) are split into two branches. One is processed by leading edge discriminators; the discriminator output, which is subject to the pulse height dependent time-walk is fed into F1TDCs. The second branch is fed into the FADC250, which record pulse height as well as timing. The FADC time can serve as a reference time to extract the time-walk corrections for the F1TDCs.

The plugin, which creates the histograms, and the root macros, which analyze the histograms can be inspected at GitHub and on your local installation at $HALLD_RECON_HOME/src/plugins/Calibration/st_tw_corr_auto. There you will find the following plugin and macro files:

  • Plugin Files:
   JEventProcessor_st_tw_corr_auto.cc
   JEventProcessor_st_tw_corr_auto.h
  • Macros Files:
   st_tw_fits.C
   st_tw_resols.C

This plugin must run in two passes. The first pass generates uncorrected timing distributions; a macro extract parameters for the time walk corrections. In the second pass, the time walk corrections are applied and verified. This is controlled from the command line by the parameter SC:USE_TIMEWALK_CORRECTION (see JEventProcessor_st_tw_corr_auto.cc for details.)

The following shows an example of how to run the plugin on ifarm at Jefferson Lab for a raw data file from the PrimeX fall 2022 run:

 hd_root /cache/halld/RunPeriod-2022-08/rawdata/Run110896/hd_rawdata_110896_000.evio -PPLUGINS=st_tw_corr_auto -PNTHREADS=8 -PSC:USE_TIMEWALK_CORRECTION=0

If this worked, you will have a newly created file hd_root.root, which contains five histograms for each of the 30 scintillator paddles of the start counter. For each counter the first three will be filled,

 stt_vs_pp_chan_*
 pp_chan_*
 h_stt_chan_*

The other two will be empty. The first histogram, stt_vs_pp_chan_*, shows ... . This histogram exhibits the pulse height dependent time walk for the FTDC signals. The macro st_tw_resols.C will fit the time walk correction coefficients. If you have not done yet, you should copy the root macros to your working directory

 cp $HALLD_RECON_HOME/src/plugins/Calibration/st_tw_corr_auto/macros/* .

Now start a root session and then run the first pass macro

 .x st_tw_fits.C("hd_root.root")

The file st_timewalks.txt will be created with the needed constants for the walk corrections. After verifying that you use a local copy you can upload these constants into the local CCDB use the command:

 ccdb add START_COUNTER/timewalk_parms_v2 st_timewalks.txt

Now run the second pass of the plugin:

 hd_root /cache/halld/RunPeriod-2022-08/rawdata/Run110896/hd_rawdata_110896_000.evio -PPLUGINS=st_tw_corr_auto -PNTHREADS=8 -PSC:USE_TIMEWALK_CORRECTION=1

Then start a root session and run the second pass macro

.x st_tw_resols.C("hd_root.root")

Examples of the excpected plots can be found here ST_tw_corr

ST_Propagation_Time

This plugin must run after we have the walk corrected times from the ST and TOF. (How do we know that TOF has been calibrated???)

Following the example above, you run the plugin:

 hd_root /cache/halld/RunPeriod-2022-08/rawdata/Run110896/hd_rawdata_110896_000.evio -PPLUGINS=ST_Propagation_Time -PNTHREADS=8 

Note that on farm with 8 threads, this plugin runs at ~90 Hz. For a first check, you might want to limit the number of events by running with parameter -PEVENTS_TO_KEEP=100000, for example. The author (J.R.) has not yet established how much statistics is necessary for a good calibration.


The first pass of this plugin will generate a ROOT file from an EVIO data file that contains histograms of the ST propagation time versus Z coordinate of the ST hit location for all 30 start counter sectors. A separate ROOT macro (st_prop_time_v1.C) will analyze and fit these histograms and provide a table for the CCDB through an output text file named (st_prop_time_constants.txt).

After verifying that you are working with a local copy of the CCDB, you can add these constants with the command :

 ccdb add  START_COUNTER?propagation_time_corr st_prop_time_constants.txt

To check that these constants work fine run the plugin in the second pass using the command:

hd_root -PPLUGINS=st_tw_corr_auto /path/to/datafile 

Then run the macro st_prop_time_corr_v1.C using the command:

.x st_prop_time_corr_v1.C("hd_root.root")

When the corrected times are calculated use the ST_Tresolution plugin to calculate the ST time resolution.

ST_Tresolution

This plugin must run after the ST propagation time constants are uploaded in the CCDB. This plugin will generate a ROOT file from an EVIO data file that contains histograms of the ST corrected time for each paddle versus Z coordinate of the ST hit location. To run the plugin use the hd_root command mentioned in section 1 of this page. To run the macro use the command :

.x st_time_resolution.C("hd_root.root")

The output of this macro will be 30 canvas of the two dimensional histograms mentioned above in addition to Y projection of these histograms. The time resolution will be ploted in another canvas. Examples of these histograms can be found in the following link ST Propagation Time Correction and Time resolution


References

  1. Rupesh Dotel and Sean Dobbs, Start Counter Recalibration, March 5, 2020, GlueX DocDB #4371
  2. Pooser, Eric J., "The GlueX Start Counter & Beam Asymmetry \Sigma in Single \pi ^{{0}} Photoproduction" (2016). FIU Electronic Theses and Dissertations. 2450. https://digitalcommons.fiu.edu/etd/2450