CTP Definition Files

The main aspect of CTP seen by a user is the definition file(s) that are used to define parameters, tests, histograms and reports. All of these types of definitions may be mixed within a single file, with the various types delineated by begin and end lines. Each of these control lines has keywords to denote the type of definition and a name for the block of definitions. The use of these blocks is discussed below.

Parameter Definitions

The parameter component of CTP supplies a means by which the parameters, constants, control flags, string variables, etc., of a data acquisition or analysis system may be initialized with readable ASCII files. It is similar to the NAMELIST package available with many Fortran compilers. The following is a sample of a definition file that sets several parameters used in an analyzer.

begin parm constants
  proton = 938.272   ; <- Comment character
  neutron = 939.57
  pion = 139.57
  pizero = 134.97
  ; The following fills an array
  offsets = 0.34, 5.7, 0.1, -.4
            0.0, .1356, -1.3, 8.6
  ; array fills may take multiple lines
  thmin = -50
  thmax = 50
  phimin = -40
  phimax = 40
  ; Lines from begin to end are called a block
  hbook_filename = 'hist.dat' ; String
  report_filename = 'endrun.txt' ; String
end parm constants

In order for the variables of these names to be set in the analyzer, these variables must be registered by the analyzer before this block of parameters is ``booked''. This registering and booking is described in section III.

Test/Cut Definitions

A test package provides a means of gathering the logic decisions of event analysis in a concise yet readable ASCII file maintained separately from the analyzer code. The results of tests are typically used to condition the incrementing of histograms. Scalers of test results are useful for computing yields and efficiencies.

In the following example of a test block, fptheta, fpphi, mass, and the array njunk are event data that are computed each event by the analyzer. The variables thmin, thmax, phimin, and phimax are parameters that are set in the previous example.

begin test hms
 goodthe = (fptheta > thmin)&&(fptheta < thmax)
 goodphi = (fpphi > phimin)&&(fpphi < phimax)
 goodphase = goodthe && goodphi
       ; Acceptable phase space of particle
 electron = mass < 10
       ; Must be an electron
 clean(1) = njunk(1) < 2
       ; Less than 2 junk hits per plane
 clean(2) = njunk(2) < 2
 clean(3) = njunk(3) < 2
 clean(4) = njunk(4) < 2
 clean(5) = njunk(5) < 2
 clean(6) = njunk(6) < 2
 allclean = clean(1)&&clean(2)&&clean(3)
       &&clean(4)&&clean(5)&&clean(6)
 goodparticle = goodphase&&electron&&allclean
 missingmass = ebeam - e1 - e2
end test

The expressions on the right hand side use any combination of a set unary and binary operators similar to the standard C operators. These operators are shown in table 1.

Table: Operators allowed in test expressions. In order of precedence.

()	Fortran Array element reference
[]	C Array element reference
-	Unary Minus
!	Logical Negation
~	Ones Complement
*	Multiplication
/	Division
//	Division, result integerized
%	Modulus
+	Addition
-	Subtraction
<<	Left Shift
>>	Right Shift
<	Less than
<=	Less than or equal to
>	Greater than
>=	Greater than or equal
==	Equal to
!=	Not equal to
&	Bitwise AND
^	Bitwise XOR
|	Bitwise OR
&&	Logical AND
^^	Logical XOR
||	Logical OR
=	Assignment operator
,	C Comma operator

A limited set of single argument functions are also available as shown in table 2.

Table: Functions allowed in test expressions.

abs()	Absolute value
sqrt()	Square root

The results of the expressions will be logical or arithmetic values depending on the operators. The variables on the left hand side of the expressions are the test results. The variables need not be registered by the analyzer, but must be if the test result is needed directly by the analyzer or is a real value. Test result variables that have not been registered may still be used in subsequent test expressions and as test flags in the histogram package, but these variables will all be established as integers.

Histogram Definitions

The histogram part of the analysis package is essentially a book keeper for HBOOK[]. It reads a list of what variables are to be histogrammed over what limits. Using the information in the configuration file, histograms are booked with standard HBOOK calls. For each event, all the histograms (subject to test conditions) are incremented. The programmer is thus saved from managing the source code for booking and filling.

begin hist hms
 ;Histname, Data source, nbins, low, high, test_flag $title
 h1,mass,1000,0,2000,goodphase $Mass distribution of good tracks
 h2,fptheta,(thmax-thmin)/2,thmin,thmax,allclean $Angular distr at focal plane

 ;Histname, X Data source, Y Data source, nxbins, xlow, xhigh
 ; , nybins, ylow, yhigh, test_flag $title
 twod,mass,fptheta,100,0,2000,25,-50,50,allclean $A 2-D histogram
end hist

The format for defining histograms is at present a simple comma separated list of arguments. The first item on each line is the histogram ``name''. This name may be used to display the histogram in the histogram display application. The second item is the variable name of the quantity to be histogrammed. The analyzer must set this variable for each event. The next three items are the number of bins followed by the lower and upper limits of the histogram. (The binning arguments have the same meaning as in the HBOOK1 call.) These three arguments may be expressions that include registered variables. These expressions are evaluated at the time that the histograms are booked. The last item is a test flag. The histogram will only be incremented for events where the test flag is true. Both the variable to histogram and the test flag may be an array named followed by an index in parentheses. This index may also be an expression that is evaluated at the time the histogram is booked. If the line defining a histogram contains a $, the remainder of the line will be used as the histogram title. A similar format exists for 2 dimensional histograms.

Report Templates

A typical analyzer writes a text file at the end of a run that contains various summary information about the run. This ``print out'' might contain information such as test scaler values, hardware scalers, parameters, and calculation of physics results based on these quantities. CTP includes a ``report generator'' that can be adequete for many such print outs. This allows the content and format of summary sheets to be changed without modifying the analyzer code.

begin report endrun
The test block "hms" was called {block.test.hms} times.
{goodphase.scaler} events passed the phase space cuts for
an efficiency of {goodphase.scaler/block.test.hms}
e(good theta) = {x=goodthe.scaler/block.test.hms}
e(good phi)   = {y=goodphi.scaler/block.test.hms}
e(electrons)  = {electron.scaler/block.test.hms}

Time of run ~ {scalers(159)*timnorm} sec.

S1X+                     Counts              Rate
scalers(17) = S1X1+ = {scalers(17)} = {scalers(17)/(scalers(159)*timnorm)}
scalers(25) = S1X2+ = {scalers(25)} = {scalers(25)/(scalers(159)*timnorm)}
scalers(18) = S1X3+ = {scalers(18)} = {scalers(18)/(scalers(159)*timnorm)}
scalers(26) = S1X4+ = {scalers(26)} = {scalers(26)/(scalers(159)*timnorm)}
end report endrun

Note that reports can access test scalers.

Describe the vlist hack used to list out all registered variables.

Accessing data in variable length ``Hit'' lists

Include files

A CTP definition file may contain one or more definition blocks of any of the above types. To aid with modularity or readability of the file, include statements may be placed in the definition file. The include statement has the form:

#include "filename"

These include statements may be used to include whole definition blocks, or one or more may be placed within blocks. The include files can be nested to arbitrary depths.

Registering Local Variables

The variables used in CTP input files generally need to be registered in the analyzer. However, as some of the examples here show, there are many uses for CTP variables that are not known to the analyzer code. The uses of these variables, known as local variables, might be used as test results variables, locally calculated quantities to histogram, constants used to setting other parameters or array indices, etc.

When a CTP parameter, test, or gethit block is booked, any unregistered result variables will be created automatically. However, CTP may not always create the variables with the desired data type. Furthermore, CTP will print out a warnings when variables has been registered automatically. As these warnings can be disconcerting to the user and they can guide in identifying variables that the analyzer programmer has failed to properly register, a means has been provided to register variables within CTP blocks.

Some examples:

#integer.test allclean
#integer goodparticle, electron
#double.event missingmass
#real positions(10), emass

The allowed types are integer, real, double, and string. The types may be optionally qualified with a class, usually parm, test, or event.