Scaler Data Class Package for Hall A

Robert Michaels, rom@jlab.org, Jefferson Lab Hall A, Mar 22, 2005

This file: hallaweb.jlab.org/equipment/daq/THaScaler.html

SCALER DATA IN HALL A

In Hall A we have crates of scaler data, see also dstruct.html (write-up about data structure). The present class package is intended to analyze those data and works either as a standlone code suite, or within the context of the new Root/C++ analyzer .

SIMPLEST USAGE

To use scalers inside the Root/C++ analyzer do the following:

Make sure you have a correct scaler.map file in $DB_DIR. Failure to have a correct scaler.map file is the most common beginner's mistake and may lead to strange results.

In your setup script you need to setup the scaler banks and enable them within the analyzer. Example:

 
    THaScalerGroup* LeftScalers = new THaScalerGroup("Left");
    THaScalerGroup* RightScalers = new THaScalerGroup("Right");
    gHaScalers->Add(LeftScalers);
    gHaScalers->Add(RightScalers);
 
    // Enable scalers
    analyzer->EnableScalers();

After the run is analyzed, you may want to use THaScaler::PrintSummary which prints the number of triggers, the integrated charge, etc. This should be called by default anyway, but you can do it explicitly:
```
     
     LeftScalers->PrintSummary();
     RightScalers->PrintSummary();
```

Add scalers to your output tree using THaOutput. Example of lines in the "output.def" file :

begin scalers left
# "default" creates a list of variables (all RATES in Hz) 
# e.g. trigger, current (unnormalized)
   default
# here are counts on the 1024 Hz clock
   lclkcount 4 7 counts
# and here is the rate (1024 Hz, of course)
   lclk 4 7
# counts in BCM scaler
   bcmu1cnt 4 13 counts
   bcmu3cnt 4 6 counts
   bcmu10cnt 4 8 counts
   bcmd1cnt 4 15 counts
   bcmd3cnt 4 10 counts
   bcmd10cnt 4 11 counts
end scalers
#
# (Note, L-arm norm scaler is usually slot 4, R-arm slot 8)

END-RUN NORMALIZATION

You may want to use the THaNormAna class to get the normalization of the runs, i.e. to summarize the number of triggers, deadtime correction, integrated charge. It also provides a method to do BCM calibration. Untar and see README.

STANDALONE CODES

The code can be run as a standalone package. This buys you a few features not available with the analyzer, like reading from VME, analyzing end-run history file, or analyzing the ring-buffer from scaler ROC10/11 data.. Download www.jlab.org/~rom/hana_decode_2.3.tar and www.jlab.org/~rom/hana_scaler_4.0.tar untar and see README, and/or look at the THaScaler programming notes. Of course these codes also come with the Root/C++ analyzer in directories /hana_decode and /hana_scaler. Finally, the codes are probably installed in the experiment's directory (e.g. as I write this there exists a directory ~adaq/e01015/scaler).

The following examples illustrate usage. Note, all these examples are available when you download the scaler code. See README.

Reading the scaler history file and printing stuff out.
Reading a CODA file and computing stuff.
Computing the charge asymmetry (helicity correlated).
Reading from VME directly online and printing stuff.
computing deadtime from scalers in a CODA file.
Filling ntuple with rates to analyze scalers from Left or Right spectrometer for e99117.
Ring buffer and helicity analysis during Spin-duality and GDH.
ROC10/11 data analysis (example 1) during Spin-duality and GDH.
ROC10/11 data analysis (example 2) during Spin-duality and GDH.

DOCUMENTATION of scaler.map FILE

  The scaler.map file is in $DB_DIR for running with the analyzer,
  or in $(pwd) if running the standalone scaler codes.

  It contains a time-dependent text-based mapping of scaler channels
  which permits getting data from THaScaler by names like "bcm_u3".

  For usage prior to Feb 1, 2005, the syntax was limited to the following,
  while the new code still respects these conventions:
 
  1. comments start with #

  2. DATE field: starts the map for a particular date 
     format of date 
         "DATE day month year" 
     example:
         DATE 1 9 2002
   Note, after Feb,'05 "date" may be lower case and is ignored if after a #

   scaler-map-info (see below) is taken from the time between the time 
   of "date" and the time of the next "date".  Apart from that rule, the
   ordering of line in scaler.map is irrelevant. 

  3. scaler-map-info:
  The format of scaler-map-info is as following line:
  short-name  helicity  crate-num  slot-num  start-chan  num-chan  long-name
  where:
     short-name = string corresponding to data member in THaScaler
     helicity :  0 = none, -1 = negative, +1 = positive
     crate :  Crate numbers follow a convention (7=Right, 8=Left, 
              10,11 = synchronous readouts, etc)
     slot:  Comes from 17th-20th bits of VME header, is related to 
            physical slot in VME (usually in order left to right).
            For synch readout, we have slots 1,2,3 defined in THaCrateMap.
     start-chan, num-chan starting and number of channels in raw data
     long-name: Long descriptive string used for plots.
  Note about channel indices:  0 = 1st one (C-style)

  New features after Feb 1, 2005:

  Note, these new features might confuse old versions of THaScalerDB.
  However, if you put the new features after a "# " (i.e. a comment)
  they will be ignored by the old version, but still get used by the new
  version (after Feb '05).  This makes the new scaler.map compatible
  with both the old and new code.  If you are using newer THaScalerDB, 
  however, the "# " (pound followed by space) is optional.

  4. Directives

  Directives are of the general form

    directive-name  Crate index1:data1 index2:data2 index3:data3 ...

  and can be obtained by client code for the particular crate by
  the THaScalerDB::GetDirective() routine.
 
  The following directives control "xscaler" layout.  If absent,
  however, xscaler by default displays one scaler slot per page 
  and labels the channels 1-32.  

    xscaler-layout   -- controls the page layout
    xscaler-tabs     -- tab names of the page
    xscaler-pagename -- names of the pages
    xscaler-pageslot -- relation of page# to slot#
    xscaler-server   -- server IP addresss
    xscaler-clock    -- channel of clock to normalize rates
  
  The following directives permit to tie one crate's data to
  another.  This was necessary since, for example, crate 11
  (event stream EvLeft) is tied to crate 8 (event type 140 data)
  historically.  It allows for much shorter (factor of ~6) 
  scaler.map file.  The "indices" 0,-1,1 are the helicities and
  the "data" are the crate it is tied to.

    crate-tied  EvLeft 0:8 -1:8  1:8

  The helicities -1 and +1 can be tied to another slot (e.g. helicity 0)
  The indices are helicities, and the data are offsets to the slot for 
  helicity 0

    slot-offset Left -1:1 1:-1

Robert Michaels -- e-mail: rom@jlab.org