StMuRpsUtil - Roman Pot data analysis utilities (afterburner)

Should you have any questions/comments/remarks regarding this module please contact rafal.sikora@fis.agh.edu.pl.

1. What is StMuRpsUtil
2. Structure
3. Utilities
4. How to use
5. Useful links


What is StMuRpsUtil
StMuRpsUtil is user-friendly utility class which provides a set of post-processing corrections (afterburner) to Roman Pot data stored in StMuRpsCollection class. It has built-in functionalities which expand standard Roman Pot data collection.


Structure
StMuRpsUtil is a ROOT-based class intended to work in the STAR computation environment, as well as local environments e.g. standalone machines. A typical STAR "Maker" format (inheritance from StMaker class) was abandoned in order to gain possibility to run the same code on MuDST files and other storage formats e.g. private picoDST files. The only limitation/requirement is, that Roman Pot data has to be stored in the StMuRpsCollection class.

Usage of StMuRpsUtil invloves creation of single instance of the class at the beginning of analysis, and invocation of StMuRpsUtil::process() and StMuRpsUtil::clear() methods at the beginning and ending of event analysis, respectively. StMuRpsUtil::process() returns pointer to StMuRpsCollection2 class, a mirror class of standard StMuRpsCollection, which contains RP data post-processed using final calibartions. All elements of StMuRpsCollection2 can be accessed in the very same way as of StMuRpsCollection class.


Utlities
StMuRpsUtil provides the following corrections to data:

• run-based alignment calibration
• (to be implemented) run-based time slewing corrections
• (to be implemented) hot strips removal

The following functionalities are available to user:

• user can set position of the vertex that is used in reconstruction of proton kinematics
  

  StMuRpsUtil::updateVertex(double x, double y, double z)

  This method should be invoked before StMuRpsUtil::process(). The unit of arguments is meter.

• (to be implemented) user can select type of selection criteria (loose, medium, tight): only proton tracks passing cuts at selected level are present in the tracks collection
  
  

1. Setup environment to SL16c or newer.

   starver SL16c

   Make sure you have the latest definitions of Roman Pot data classes in your StRoot.


2. Download StMuRpsUtil package from repository.

   cvs co offline/users/rafal_s/StMuRpsUtil

3. Put downloaded StMuRpsUtil catalogue under StRoot path in your analysis directory.

   mv offline/users/rafal_s/StMuRpsUtil myAnalysisDir/StRoot/.

4. Edit setup.h file (myAnalysisDir/StRoot/StMuRpsUtil/setup.h) so that only the following line is uncommented.

   #define RUN_ON_MUDST // set if afterburner is used on MuDST

5. Edit the header file of your analysis maker class.
   Add declaration of StMuRpsUtil class before definition of your analysis maker class, and add pointer to StMuRpsUtil object as the element of your analysis maker class.

   /*...*/
   class StMuRpsUtil;
   /*...*/
   
   class MyAnalysisMakerClass: public StMaker{
     /*...*/
     StMuRpsUtil*  mAfterburner;
     /*...*/
   }

6. Edit the implementation file of your analysis maker class.
   Include StMuRpsUtil and StMuRpsCollection2 headers at the beginning.

   /*...*/
   #include "StMuRpsUtil/StMuRpsUtil.h"
   #include "StMuRpsUtil/StMuRpsCollection2.h"
   /*...*/

   In the analysis maker constructor, create StMuRpsUtil object passing as an argument pointer to StMuDstMaker.

   MyAnalysisMakerClass::MyAnalysisMakerClass(StMuDstMaker* maker): StMaker("MyAnalysisMakerClass"){
     /*...*/
     mAfterburner = new StMuRpsUtil(maker);
   }

   At the beginning of MyAnalysisMaker::Make() method in your analysis maker class, invoke StMuRpsUtil::process() which will provide you post-processed RP data collection. Don't forger to call StMuRpsUtil::clear() at the end of MyAnalysisMaker::Make().

   Int_t MyAnalysisMaker::Make( ){
      /*...*/
      StMuRpsCollection2* muRpsColl = mAfterburner->process(); // <-- muRpsColl can be used to get corrected proton tracks etc. 
   
      /* here analysis of an event */
   
      mAfterburner->clear(); // <-- critical!!!
      return kStOK;
   }

7. Download RP data calibration files from http://www.star.bnl.gov/~rafal_s/protected/rpsCalibrations2015.tar.gz, unpack it and put exatracted catalogues under myAnalysisDir (you should then have myAnalysisDir/Alignment etc.).
    
   
8. Add the following line:
   

   gSystem->Load("StMuRpsUtil.so");

   to the macro which starts the analysis chain. It ensures that afterburner libraries are accessible.
    
   
9. Edit you job submission XML file so that directories with calibration files extracted from rpsCalibrations2015.tar.gz are included into sandbox.

   <SandBox installer="ZIP">
           <Package>
                   <!-- Any other files.... -->
                   <File>file:./Alignment</File>
                   <File>file:./HotStrips</File>
                   <!--        etc.         -->
           </Package>
   </SandBox>