An Example NTPR Bank

All the main features of the NTPR bank can be explained with reference to the simple example shown below.

 
*DO   NTPR  100  -i(25I 1F 3I -H)     #.   NTuPl Request
#.
20*0                    #.   Database Header  (to be defined)
#.
#.      User Data.
#.
3*0                     #.   3 Reserved words (don't touch!).
1                       #.   Enable flag: =0 Disable, =1 Enable.
5000                    #.   Primary allocation (not critical).
-999999.                #.   "Undefined" value.
1                       #.   Discard partial entry: =0 No, =1 Yes.
0                       #.   Scan D/S: =0 No, =1 Yes.
0                       #.   Options:  Bit 0: Call NTP_PACK_USER
0                       #.             Bit 1: Collapse N-tuple
' mcdata; '             #.   N-tuple name.
#.
#.      There now come a series of field entries.
#.
#.   Variable     Function        Parameter(s)
#.    Name
#.
' revent   magnitude         MCVX+$KMCVX_PSX;                  '
' rfit     magnitude         FTTV+$KFTXV_X;                    '
' nhits    float_equals      EV+$KEV_NPM;                      '
' tfit     equals            FTTV+$KFTXV_T;                    '
' chi2     equals            FTT+$KFTT_CHI;                    '
' rdev     distance          FTTV+$KFTXV_X,   MCVX+$KMCVX_PSX; '
' numiter  float_equals      FTT+$KFTX_ITER;                   '
' xdev     difference        FTTV+$KFTXV_X,   MCVX+$KMCVX_PSX; '
' ydev     difference        FTTV+$KFTXV_Y,   MCVX+$KMCVX_PSY; '
' zdev     difference        FTTV+$KFTXV_Z,   MCVX+$KMCVX_PSZ; '
' nfit     float_equals      FTT+$KFTX_PMT_USED;               '
' nearly   float_equals      FTT+$KFTX_EARLY;                  '
' nlate    float_equals      FTT+$KFTX_LATE ;                  '
' theta    theta_phi         MCTK+$KMCTK_DRX;                  '
' phi      reserved;                                           '
#.
'  END_OF_NTUPLE; '     #.  This marks the end of the ntuple.

*DO NTPR 100

The first point to note is that the bank number (100 in this case) is the N-tuple id. If creating more than one N-tuple by having multiple NTPRs they must all have different bank numbers. If duplicates are found a warning is given and the first version kept.

Reserved words

The user data starts with a set of reserved words used by SNOMAN for its own secretive purposes. They should be set to zero but in any case SNOMAN ignores any value stored in them on input.

Enable flag

This flag provides a convenient way to switch off an N-tuple without having to remove it from its titles file. You can build up a suite of your own NTPR banks and then switch them on or off as required.

Primary allocation

This number is passed to the HBOOK routine HBOOKN. It is an estimate of the size of the bank needed to hold all N-tuple entries that will be generated during the run. As the name suggests HBOOK is quite capable of appending secondary allocations if necessary so this number, while it should be sensible, is not critical.

``Undefined'' value

This value is used to preset every variable in the N-tuple entry. It is only important if you accept partial entries, see below. It should not be a value could possibly appear in a normal N-tuple. The value will be rejected if 0. or 1.

Discard partial entry

It may not always be possible to complete an N-tuple entry because the DQF parameters are unacceptable for a number of reasons:-

• The required bank may be missing or may not be large enough to contain the required word.

• The data exists but has the undefined value. For example, if an entry is undefined then any subsequent entry that uses it as a DQF parameter (see section 6.6) will also be undefined. It is for this reason that the undefined value must be chosen with care; it is used to differentiate good and undefined data. The values 1. and 0. are used in logical DQFs see 6.6 to denote true and false which is why these values are always rejected as the undefined value.

• The data is defined is not be valid for the function.

Under these circumstances you have two choices:-

• Keep the entry but have undefined variables filled with the ``undefined'' value specified.

• Discard the entry, by setting this word to 1.

Scan D/S

Some of the banks in the event data structure have multiple versions e.g. MCVX. For an NTPR that refers to such a bank the question arises as to which should be used. You have two choices:-

• Take the first bank that comes.

• Take every legal combination, by setting this word to 1.

It is worth spelling out the phrase ``every legal combination'' in a little detail. Suppose an NTPR refers to MCVX and MCTK, then every legal combination means every MCVX with each of the MCTKs it supports i.e. its outgoing MCTKs. If the MCVX is a sink it will have no outgoing MCTK. In this case whether the combination is allowed depends on the setting of the Discard partial entry word.

Even more combinations can be generated for multiple banks that do not lie on a single path back up to the MAST bank. Suppose the NTPR also referred to the FTT and that there was more than one EV each with its own FTT. Now every legal combination includes all MCVX/MTCK combinations with EVERY FTT.

Warning: Collecting data from multiple banks that do not lie on a single path back up to the MAST can give multiple contributions from each bank.

For this reason asking to scan a data structure should be used with caution in these situations; creating too many entries will result in the HBOOK memory becoming full. It is probably better to have two or more NTPR banks in this case or use the limits on one or more variables (see next section) to restrict the number. It is also worth checking the termination printout. Along with the number of n-tuples output, written as histograms and discarded, the number of times that the NTPR produced 0 entries, 1 entries and more than one entries is listed. If you only expect one entry per event, but you see more, then you may not have fully thought through all the consequences of the phrase ``every legal combination''!

Options

This defines a set of one-bit options. Currently two are defined:-

Call NTP_PACK_USER

This is the complete DIY alternative! It can be used in 2 ways:-

• For complete control the user sets up a NTPR in which all variables use the RESERVED function, see section 6.10. This ensures the N-tuple is booked but not filled. Once for each MAST bank NTP_PACK_USER is called and you can fill it with anything you like.

• The NTPR bank uses other functions in which case NTP_PACK_USER will be called each time an entry is filled. This allows you to append your data to an otherwise standard one. It also allows you to examine the contents and veto the entry if you want to.

SNOMAN has a dummy NTP_PACK_USER which contains details on how to use it.

Collapse N-tuple

This creates a collapsed the n-tuple consisting of a single row. It is produced by summing the contents of each column. See section 6.9

The remainder of the bank consists of free format text, it is case insensitive; it is converted to upper case during processing. Note that each line is terminated by a semi-colon (needed because the end of line position is lost when the bank is read in) and is surrounded by single quotes. Just for tidiness the single quotes have been aligned in the example but this is not necessary.

N-tuple name

The first line is an arbitrary N-tuple name that must not exceed 8 characters.

Field entries

The following lines each define a single variable of the N-tuple. The order in which they appear in the NTPR bank determines the order in which they will be stored in the N-tuple. They are described in detail in the next section.

END_OF_NTUPLE

The last line declares the end of the N-tuple.