Quickstart

Overview

This quickstart guide will quickly describe how to use the current pixie16 analysis. The guide assumes you have no desire to know how the analysis performs various tasks but only want to know how to make the program run and do something useful. If you are unfamiliar with C++ please refer to the C++ primer for a description of a few C++ features used in the code that have no FORTRAN equivalents. This chapter will use a sample ldf file taken from an RMS experiment with a 40x40 DSSD and one MCP. This tutorial assumes you have a working knowledge of the DAMM program for viewing *.his files.

Complilation

I assume that ROOT has not been installed on your computer and you do not want to compile with ROOT capabilities. In this case make sure that declarations of USEROOT and STANDALONEROOT are commented out in the Makefile.
  # use a "#" on the beginning of a line to comment it out of the Makefile
  #USEROOT = 1
  #STANDALONEROOT = 1
  

The next flag that must be set correctly is whether your data was taken with the new pixie16 readout. This readout was developed for the high data rates at the back of the RMS. If you have DSSD RMS data taken after March 20th 2008 then it is likely you have used the new pixie16 readout scheme. If so, then make sure the -Dnewreadout flag is set in the following line of the Makefile.

  G++FLAGS  = -O3 -Wall -Wno-deprecated -fPIC $(CINCLUDEDIRS) -Dnewreadout
If you have older DSSD RMS data or beta decay spectroscopy data from LeRIBSS (or similar setup) then you have most likely not used the new readout scheme and the -Dnewreadout flag should be commented out.
  G++FLAGS  = -O3 -Wall -Wno-deprecated -fPIC $(CINCLUDEDIRS)# -Dnewreadout

Also, make sure that the appropriate compilers are inserted into the Makefile. The Makefile assumes that g++ (C++), gcc (C), and g77 (FORTRAN) compilers are present on your computer. If your compilers have different names please alter the definitions inside the Makefile (at the location shown below) to match your system.

  #--------- define compilers
  G77 = g77
  GCC = gcc
  G++ = g++
  
Additionally, you must point the make file to the appropriate location where you have installed the static scanor libraries. The ones needed are scanorlib.a, orphlib.a, acqlib.a, and ipclib.a. Alter locations of these static libraries by changing the definitions of DIRA2 and DIRB in the Makefile
  DIRA2=/usr/hhirf/g77/
  DIRB= /usr/acq2/lib/

  LIBS = $(DIRA2)scanorlib.a \
         $(DIRA2)orphlib.a \
         $(DIRB)acqlib.a  $(DIRB)ipclib.a
  

If you do not have these libraries then please visit the HRIBF computing web page to download the appropriate packages.

Compile the code with the command

  make
  

Input Preparation

In order to successfully run the pixie16 analysis two initialization files are required, map.txt and cal.txt. map.txt describes the mapping of pixie16 input channels to specific detectors and cal.txt sets the calibration for each detector. Both files are included in the tutorial directory and should be copied to the main scan_c++ directory to run this tutorial. Both files are described in more detail below.

Map.txt

The file map.txt contains a total of 7 parameters for each pixie16 channel. The 7 parameters are necessary for completely specifying the detector plugged into that channel. The 7 parameters are:

Comments in the map.txt file are always preceded by "//". An example of the map.txt file for use at the RMS with a DSSD and one MCP would look like this:

  //example map.txt file
  // mod id  chan id  damm    det_type   det_subtype  det_loc  trace
          0        0   600  dssd_front    dssd_front        0      1
          0        1   601  dssd_front    dssd_front        1      1
          0        2   602  dssd_front    dssd_front        2      1
          0        3   603  dssd_front    dssd_front        3      1
          ... 
          4        0   900   dssd_back     dssd_back        0      1
          4        1   901   dssd_back     dssd_back        1      1
          ... 
          5        0   927         mcp    1position1        0      1
          5        1   927         mcp    1position2        0      1
          5        2   927         mcp    1position3        0      1
          5        3   927         mcp    1position4        0      1
          ...
  
It is critical that all combinations of module number and channel number are represented in the map.txt file and are in sequential order. If a channel is not used in the experiment or is not required in the analysis the detector type and detector subtype must both be set to "ignore" in the map.txt line corresponding to that module and channel number. To ignore the 0 and 1 channel on module 2 the map.txt file would look like:
  //example map.txt file ignoring module 2 channels 0 and 1
  //mod id   chan id  damm    det_type   det_subtype  det_loc  trace
         0         0   600  dssd_front    dssd_front        0      1
         0         1   601  dssd_front    dssd_front        1      1
         0         2   602  dssd_front    dssd_front        2      1
         0         3   603  dssd_front    dssd_front        3      1
         ...
         2         0   900  ignore            ignore        0      1
         2         1   901  ignore            ignore        1      1
         ...
  

Cal.txt

The other necessary file for running the program is cal.txt. As the name suggests this file contains the calibration parameters for the detectors used in the analysis. For each channel that was defined in map.txt that is not set to "ignore" a line must be present in cal.txt and include:

There is currently no default calibration parameters for detectors. Only channels set to "ignore" have default parameters. The upper limit of the calibration (exclusive) is either (1) the lower limit of the next calibration or (2) the maximum value set by MAX_PAR in the 'param.h' file. Comments in the cal.txt file are always preceded by "//". An example of the cal.txt file for one 2nd order polynomial looks like this:

  //example cal.txt file for 1 - 2nd order polynomial
  //det    det    det   num   poly    low   cal val  cal val  cal val
  //loc   type    sub   cal  order  range     inter    slope     quad
      0   dssd   dssd     1      2    0.0     0.0        1.0      0.0
         front  front
      1   dssd   dssd     1      2    0.0     0.0        1.0      0.0
         front  front
  ...
  

An example of a calibration file for two 2nd order polynomials is shown below. The first calibration ranges from 0.0 to 16000. The second calibration has a range from 16000 to the maximum set by MAX_PAR in the 'param.h' file.

  //example cal.txt file for 2 - 2nd order polynomials
  //det    det    det   num   poly    low    cal   cal   cal   low    cal   cal   cal
  //loc   type    sub   cal  order  range  inter slope  quad        inter slope  quad
      0   dssd   dssd     2      2    0.0    0.0   1.0   0.0 16000    0.0   1.0   0.0
         front  front  
      1   dssd   dssd     2      2    0.0    0.0   1.0   0.0 16000    0.0   1.0   0.0
         front  front
  ...
  

Event Creation

Events are created by grouping together channels which triggered at similar times. This time window is controlled by the variable "diff_t" in the pixie_std.cpp file in the Scan_List() function. A list of channels sorted by time from lowest to highest is scanned in this function from beginning to end. If two successive channels in the list are within "diff_t" time they are grouped together in an event. The variable is in units of pixie16 clock ticks and must be multiplied by 10 to obtain the event width in ns. Please note that the "diff_t" time window is only applied to successive events. Thus it is possible (depending on the total trigger rate) to have events that are longer than the specified time window.

Retrieving Information from the Event

After an event has been created it is sent for processing. The first step of processing is to calibrate the individual channels and summarize the information contained in the event. For each detector type that is present in the event an object called detector_summary is created. This object holds detector related information such as the location of the maximum energy deposition and the multiplicity of the detector among other things. For example, the following command will retrieve the maximum energy that was deposited in the front of the DSSD in this event.
  int maxe = revt.get_pdet_sum_map_entry("dssd_front")->get_max_energy();
where revt is the name of the variable holding the raw event information and maxe will contain the maximum energy deposited in the front of the detector. Similarly, the strip number where the maximum energy was deposited is retrieved with the following command:
  int stripno = revt.get_pdet_sum_map_entry("dssd_front")->get_max_energy_loc();
Therefore a plot of strip number versus energy for the front of the DSSD can be obtained by plotting the variable stripno against maxe (using the syntax described later in the plotting section).

To retrieve the multiplicity associated with the front of the DSSD the following command is used

  int fmult = revt.get_pdet_sum_map_entry("dssd_front")->get_mult();

If you already have a pointer to the detector summary of interest then the multiplicity could be retrieved using the pointer itself as follows

  int fmult = pdet_s->get_mult();   or
  int fmult = pdet_s.get_mult();
where pdet_s is a pointer to the detector_summary and the choice between a "->" or "." depends on whether pdet_s is a pointer by value or pointer by reference, respectively. The reference manual can provide a list of all commands to retrieve information from the detector_summary or the rawevent.

Plotting

All plotting is controlled through the "plot" function defined in the detector_driver.cpp file. This function is a C++ wrapper that has been placed around the DAMM count1cc and set2cc subroutines. This allows for the code to be easily changed between damm and ROOT histograms. For those using DAMM to view the output of the analysis all plots are created in the "drrsub.f" file located in the scan directory. For example, to plot a one dimensional histogram of energies into a DAMM spectrum numbered 101 the command would be
  plot(101,energy);
You can send any type of numerical value to the plot function. The variable is cast into an integer before being passed to the DAMM plotting functions. A two dimensional histogram is plotted with the command
  plot(101,energy,stripno);
and a three dimensional histogram (plotting a trace for example) uses the command
  plot(101,xval,row,traceval);

Program Execution

After compilation the executable pixie_ldf_c will be present. Run the pixie_ldf_c program as you would any other scan program as follows
  ./pixie_ldf_c hisname
  
Where "hisname" is the name of the damm histogram that will be created.

For this exercise you will use the tutorial.ldf file located in the LDF directory. At the scanor prompt load in the appropriate ldf file as follows

  SCANOR->file tutorial/tutorial.ldf
  
Next start the analysis with the following command
  SCANOR->go
  

After starting a variety of output should be printed to the screen. The first lists all the detectors that are being used in the analysis. For the tutorial file the dssd_front, dssd_back, and mcp detector types are used in the analysis. Next is a list of all module and channel number combinations and their respective calibrations. As a sanity check the total number of channels that the code has identified is given and should be equal to the number of calibration lines. Lastly, when new detectors are added to the code the number of possible detectors is given from two places in the code and the numbers should be identical.

After completion of the analysis, end the SCANOR program

  SCANOR->end
  

Start damm and open your histogram. You can display 741, 742, 743, and 744 to see the strip versus energy profile of the dssd for implants and decays on the front and back of the dssd. Spectrum 923 provides a 2D plot of the position sensitive MCP.

These spectra are filled following the experiment specific event processing in the detector_driver (defined in the detector_driver.cpp file) by invoking the appropriate plotting routines. The 741, 742, 743, and 744 spectra are all filled using the dssd object and mcp 923 spectrum is filled by the mcp object. The plotting routines of the dssd and mcp objects are invoked from the detector_driver by the following commands

  dssdsub.dssdplot(revt, *temppoint[0], *temppoint[1], type);
  mcpsub.mcpplot(revt);
If either the front or back of the DSSD triggers the plotting routine from dssd_sub is called with four parameters: the rawevent, the detector summary corresponding to the front and the back of the dssd, and a description of the type of event being processed. Using the multiplicities from the front and back detector summaries a decision is made as to whether there is a front-back coincidence or not and spectra are filled accordingly with the maximum energy deposited and the associated strip number.

To create a decay multiplicity spectrum for the front of the DSSD you need to first create the spectrum in drrsub.f and fill it in dssd_sub.cpp. Create the spectrum in drrsub.f by inserting the following line

  call hd1d(1743,2,64,64,0,63, 'DSSD decay front mult')
  
Fill the decay front multiplicity spectrum by going inside the the "if(type == decay)" and "if(side == front)" condition and inserting the following line after the filling of spectrum 743.
  plot(1743,pdet_front.get_mult());
  

Save the two files and recompile the pixie16 scan program and rerun the analysis on tutorial.ldf. Open the resulting damm file and you should have a new multiplicity spectrum.

Next create a decay multiplicity 2 gated version of spectrum 743. First create the new spectrum in the drrsub.f file by inserting the following line

  call hd2d(2743,2,8192,8192,0,0,64,64,0,0, 'DSSD Strip v E-DF,mult2')
  
Next insert the filling command inside the ''if(type == decay)`` and ''if(side == fbcoin)'' condition.
  if(pdet_front.get_mult()==2) plot(2743,pdet_front.get_max_energy(),pdet_front.get_max_energy_loc());
  

Save, recompile and rerun the analysis and you should now have a multiplicity 2 gated 743 spectrum in spectrum 2743.

Common Errors

To familiarize yourself with some of the more important workings of the code we will now perform a few common tasks that will result in the failure of the analysis code.

Problems with map.txt

The easiest mistake is misspelling the detector name. Open the file map.txt and change the entry for module 0 channel 15 to the following
  //example incorrect map.txt file
  // mod id  chan id  damm    det_type   det_subtype  det_loc  trace
          ...
          0       15   616    dssd_fro    dssd_front       16      1
          ...
  
This type of error will be caught by the scan program and the following warning will be issued.
  The detector called ``dssd_fro'' read in
  from the file map.txt is unknown to this program!
  This is a fatal error.  Program execution halted.
  If you believe this detector should exist please
  edit the 'get_known_detectors' function inside the
  'detector_driver.cpp' file.

  The currently known detectors include:
  dssd_front, dssd_back, ge, timeclass, si,
  position, ifront_dssd, scint, mcp
  

This warning states that you are trying to use a detector (dssd_fro) for which no default behavior has been assigned. This error is the likely result of a misspelling and the valid detector names are listed as well. If you need to add a new detector type please refer to ***. Note: the program does not check to make sure that the detector subtype is spelled correctly. Therefore if you have code that makes use of this information (the MCP is one example) then make sure the spelling is consistent between map.txt and the analysis code.

Additional Note: Please carefully verify that all possible combinations of module and channel numbers have been included in the map.txt file. If the program attempts to retrieve data from a channel that has not been defined a ``Segmentation fault'' will result.

Problems with cal.txt

The next common error is not having the correct number of lines in the calibration file. Open cal.txt and change the calibration line for dssd_front strip number 16 to the following
  //example cal.txt file for 1 - 2nd order polynomial
  //det    det    det   num   poly    low   cal val  cal val  cal val
  //loc   type    sub   cal  order  range     inter    slope     quad
     15   dssd   dssd     1      2    0.0     0.0        1.0      0.0
         front  front
  
Now you should have two lines referring to dssd_front strip number 15. Trying to run with this cal.txt produces the following error.
  The entry in map.txt with det_type = dssd_front
  det_subtype = dssd_front
  and det_location = 16
  was not found in the cal.txt file, please fix this
  Program terminating
  
All entries in the map.txt file should have a corresponding entry in the cal.txt file.

Generated on Wed May 14 10:07:06 2008 for pixie16 by  doxygen 1.5.5