Guide for contributing to physics and detector studies

Introduction

This page contains the instructions required for getting up and running with the simulations for REDTOP proposal. They are based on the assumption that you will be using lcsim-REDTOP and Netbeans. Instructions for setting up the software are available on the lcsim framework page along with three examples to check that the framework, the detector conditions and the data are installed correctly.

The REDTOPcontrib package

In order to organize the contribution from several individual, the REDTOPcontrib Java package has been created. All personal contribution and classes should be located in that package. The name of the contributor should appear on the filename. An example is the gattoRedtopHitAnalysis.java class. If a contributor wants to modify and run a class outside of the REDTOPcontrib package, that class has to be copied in the REDTOPcontrib package and renamed as specified above. The way for doing that correctly in NetBeans is explained below.

Adding a standalone class to REDTOPcontrib package

Step 1: update the local project

The first step is to update your local copy of lcsim-REDTOP to the head version of the svn repository. Below are the instructions. From the main Netbeans window, do the following:

Team->Update...->Update to HEAD

and wait that task to complete (check the progress bar at the bottom of NetBeans main window). Visual instructions are below.

Step 2: refactor copy an existing standalone driver

A stendalone driver is a class called by the REDTOP main event loop. It is used to extract infromations directly from the event and it does not need the full reconstruction  chain. The best way to contribute with a new class is to start from an existing class, by coping it to REDTOPcontrib and modifying it according to your desire. The process of copying a class while maintaining the correct dependencies is “called refactor copy”. Suppose, for example, that you would like to work  at a copy of the RedtopHitAnalysis.java class present in the REDTOPMC. Then you have to follow the steps below.

  • Right-click on the name of the class (RedtopHitAnalysis.java, in this example)
Refactor->Copy...
  • A window would pop-up asking which is the “New name” of the file and the “Package” where to copy RedtopHitAnalysis.java. The former is a name of your choice (preceded by your last name), while the latter is the REDTOPContrib folder. In the present example, the filename is gattoRedtopHitAnalysis

Leave the remaining text box untouched.

  • Push the “Refactor” button. The pop-up window will close and the refactored class appears in the REDTOPcontrib folder.

Step 3: Instruct REDTOP main event loop to run using your new driver

Now, you need to instruct  lcsim-REDTOP to run your driver. The procedure is very similar to Example #2 at the bottom of the LCSIM reconstruction framework web page.

  • Now, we need to give the project the arguments to recognize you driver. In order to do that,  right click on the project package and make sure that the following parameters are present :
    • REDTOP->Properties->Run->Configuration: -> <default-config>
      REDTOP->Properties->Run->Main Class: -> org.lcsim.REDTOP.analysis.DriverLoop
      REDTOP->Properties->Run->Arguments: xxx yyy.aida  REDTOPcontrib.gattoRedtopHitAnalysis zzz.slcio
      REDTOP->Properties->Run->VM Options: -mx1100M

      where (see also the picture below):

    • xxx is the number of events to process;
    • yyy.aida is the filename of the output histogram file;
    • zzz.slcio is the filename of the input data file (slcio format)
  • The pop-up properties window, will, then, look similar to the image below. Edit the “Arguments” input box according to your input/output files ans enter the four arguments mentioned above.

  • Click the OK button. The pop-up window will close
  • Make sure that in the config textbox, at the center of the top toolbar of Netbeans,  the <default-config> is selected.

Step 4: Build and running your driver

  • In the Project panel select the project REDTOP. Right-click on that and, from the popup menu, select: Clean and build;
  • When it is done building, if everything went OK, you will get a green message saying: BUILD SUCCESS. Otherwise, something went wrong: you need to control the error messages and fix the problem accordingly.
  • To run your new, right-click on the REDTOP project name (in the left panel) and select “run”. Alternatively, click on the right green arrow in the middle of Netbeans toolar.

 

Adding a reconstruction driver class to REDTOPcontrib package

Step 1: update the local project

The first step is to update your local copy of lcsim-REDTOP to the head version of the svn repository. Below are the instructions. From the main Netbeans window, do the following:

Team->Update...->Update to HEAD

and wait that task to complete (check the progress bar at the bottom of NetBeans main window). Visual instructions are below.

Step 2: refactor copy a reconstruction driver (a class running in REDTOPReconstruction)

A reconstruction driver is a dependent class called by the reconstruction package rather than directly from the REDTOP main event loop. It is used to modify or add a process to the reconstruction  chain. The best way to contribute with a new class is to start from an existing class, copy to REDTOPcontrib and modifying it according to your plans. The process of copying a class while maintaining the correct dependencies is “called refactor copy”. Suppose, for example, that you would like to work  at a copy of the OTPCClusterer.java class present in the REDTOPReconstruction analysis, then you have to follow the steps below.

  • Right-click on the name of the class (OTPCClusterer.java, in this example)
Refactor->Copy...
  • A window would pop-up asking which is the “New name” of the file and the “Package” where to copy  OTPCClusterer.java. The former is a name of your choice (preceded by your last name), while the latter is the REDTOPContrib folder. In the present example, the filename is gattoOTPCClustererCheater.

Leave the remaining text box untouched.

  • Push the “Refactor” button. The pop-up window will close and the refactored class appears in the REDTOPcontrib folder.

Step 3: Instruct REDTOP reconstruction to run your own driver

Now, you need to instruct  the reconstruction chain to run your driver. The reconstruction chain is formed by the following sequence of classes:

REDTOPReconstruction.REDTOPReconstructionDriver()
    |->  REDTOPReconstruction.REDTOPReconDriverLoi()
               -> REDTOPReconstruction.REDTOPDigiDriver()
                  REDTOPReconstruction.REDTOPEventTrigger()
                  REDTOPReconstruction.OTPCDigiDriver()
                  REDTOPReconstruction.ADRIANOSingleReadoutRawClusterDriver()

Therefore, you need to modify you personal copy  of the class which is supposed to call your driver. There are two instructions to insert:

import REDTOPcontrib.the_name_of-your-refactored_class;

at the beginning of REDTOPReconstruction.REDTOPReconDriverLoi.java. In the current example, that would be:

import REDTOPcontrib.gattoOTPCClustererCheater;

 

The second instruction to insert is an instantiation of your driver:

add(new the_name_of-your-refactored_class());

in the body of  REDTOPReconstruction.REDTOPReconDriverLoi.java (very much dependent on the taks performed by your driver). In the current example, that would be:

add(gattoOTPCClustererCheater());

 

Step 4: Build and running your driver

Since the REDTOP project is already instructed to run the reconstruction, all you have to do is to build and run REDTOP. For doing this, just follow the instruction in Example #3 at the bottom of the LCSIM reconstruction framework web page.

 

Templates for running the physics analyses for the proposal

The following standalone drivers are present in the REDTOPcontrib folder as templates for making a physics analysis, as described in Sec. 1 of the simulation document.

eta3pi analysis: gattoEta3piMCAnalysis.java

Heavy photon analysis (A’ and X(17)): gattoEtaGammaAprimeMCAnalysis.java

pi0-scalar analysis (H-> e+ e- and mu+mu-): gattoEtapi0HMCAnalysis.java

Background files are in: ftp://t1015-svn.fnal.gov/1/v4.1/slcio/ and ftp://t1015-svn.fnal.gov/2/v4.1/slcio/ (example: ftp://t1015-svn.fnal.gov/1/v4.1/slcio/redtop.1800mev.v41.urqmd.10003.00.slcio  and ftp://t1015-svn.fnal.gov/2/v4.1/slcio/redtop.1800mev.v41.inclxx.10053.01.slcio )

Use the instructions above to refactor the class into  your own version.