Defining N-tuple Variables

The definition of each variable consists of 3 or 4 components:-

• The variable name. It must not exceed 8 characters unless it is a temporary variable. Avoid using bank names (e.g. MCVX). Temporary variable names start with a leading underscore (_) and may be up to 16 characters long. Temporary variables are removed before the n-tuple is stored. They are useful for holding intermediate cuts results, as described in section 6.6. Link entries (see section 6.7.1) are always treated as temporary.

• The Derived Quantity Function (DQF). The function may do no more than copy the value specified into the variable or could compute some simple function e.g. the distance between 2 points. For a complete list see 6.10.

• A comma separated list of bank addresses that are to be input to the DQF. Note that bank address mnemonics are supported (note the use of the $). You can use numeric offsets:-

   
  ' revent   magnitude         MCVX+3;                  '
  

  but it is safer to stick to:-

   
  ' revent   magnitude         MCVX+$KMCVX_PSX;                  '
  

  One consequence of using symbolic addresses is that changes in the bank layout are automatically tracked (although there are very good reasons not to change bank layouts!). Besides bank addresses, literals and n-tuple variable names can be input to a DQF, see section 6.6 for details.

• An series of options preceeded by a colon. If there are no options then the colon is omitted. Each option is starts with a keyword. Currently two are defined:-

  VETO

  Introduces an upper and lower limit. The entry is discarded if the value is outside the limit. This was the first option to be introduced and orginally had no keyword. For backward compatibility, the keyword is still optional.

  HIST*

  Specifies that the value is to be histogrammed. See section 6.8

So, for example:-

 
' tfit     equals            FTTV+$KFTXV_T;                    '
' rdev     distance          FTTV+$KFTXV_X,   MCVX+$KMCVX_PSX; '

defines 2 variables. It copies the value of word KFTXV_T of the FTTV bank into the variable TFIT. The RDEV variable is the distance between the space points defined by the two vectors which start at word KFTXV_X of FTTV and word KMCVX_PSX of MCVX. So, the parameters that are passed to the function can be either scalar or vector. If vector then it is the first word of the vector that is passed.

All N-tuple variables must be floating point. There are several Derived Quantity Functions: that take integer input parameters e.g.:-

 
'    nhits        float_equals    EV+$KEV_NPM; '

records the number of hits from the EV bank.

Many words in the Data structure are stored as integers. You MUST use a DQF that takes integer parameters when accessing such words.
Don't use FLOAT_EQUALS for large integers; floating only preserves about 7 decimal digits of precision. For large integers use some other DQF such as BITS

A simple cut may be made on any variable by following the parameter list by a colon followed by the VETO option that specifies upper and lower limits like this:-

 
' chi2     equals            FTT+$KFTT_CHI: veto 40. 80.;       '

Note that the VETO keyword is optional; it will be omitted from future examples. The limits which can appear in either order (i.e. upper lower or lower upper) and should be floating point, but integer is tolerated (it is converted to floating point). The entry is discarded if the value is outside the limit. This does NOT include the case when the value has been left at its ``undefined'' value; undefined values always pass cuts. If the cut is likely to reject most of the ntuples then place the variable near the start of the NTPR so that SNOMAN does not waste time processing variables only then to reject the ntuple. Organising an ntuple in this way can save a considerable amount of time.

If only one limit is given, it is taken as the lower and upper limits. Note that single precision floating point numbers have sufficient precision to exactly represent floated integers up to 6 digits long. For example:-

 
' id   float_equals   MCTK+$KMCTK_IDP: $neutron;  '

checks to see if particle id is a neutron.

You have already seen that the input parameters can either be interpreted as scalars or vectors. Normally the output from the function is a scalar but this is not always the case. The function THETA_PHI takes a vector and returns its polar and azimuthal angles. This requires the allocation of 2 variables which is done as follows:-

 
' theta    theta_phi         MCTK+$KMCTK_DRX;                  '
' phi      reserved;                                           '

The RESERVED function takes no parameters, its only purpose is to reserve a named variable. The THETA_PHI function fills out 2 words: THETA and the variable immediately after it i.e. PHI.

It sometimes happens that you want to take data, not from the bank itself, but from a bank related to it via some link. Consider this example:-

 
' tk_len  distance  mcvx +$KMCVX_PSX ,mctk -$KMCTK_MCVX +$KMCVX_PSX;'

The way in which the data structure is scanned ensures that this variable will only be defined for an MCVX with each of its supported (OUTGOING) MCTKs.

Word KMCVX_PSX of the MCVX bank marks the start of its position vector. All data words have positive offsets and all links have negative offsets so the -$KMCTK_MCVX after the MCTK means the bank at its -KMCTK_MCVX link. This is its end vertex so MCTK -$KMCTK_MCVX denotes another MCVX and then the +$KMCVX_PSX takes its position vector. So the above example stores a track length by calculating the distance between its start and end vertices. You can follow links further than one hop by having a series of negative offsets (for example MC -$KMC_MCVX -$KMCVX_MCTK is the first MCTK). The general syntax permits up to 9 negative offsets followed by at most one positive one.

ZEBRA fanatics (if such animals exist!) will notice a deficiency in this scheme. It is not possible to follow the link offset 0 (next bank on the linear chain) and +1 (supporting bank). As banks in a linear chain are independent of each other relationships between them won't, for the most part, have meaning. However being able to step up to the supporting bank can sometimes be useful. For example from an MCVX you can follow the link to its connecting MCTK and then follow the +1 link to reach the MCVX that supports the MCTK. To allow for this the following rather strange construction can be employed:-

 
'    mctk-+1+$KMCVX_PSX;    '

The minus sign indicates a link but the +1 specifies the +1 link (there are no symbolic addresses defined for these as they are the same for all banks) so this example identifies data word KMCVX_PSX of the MCVX that supports the MCTK. In the same way:-

 
'    mctk-+0+$KMCVX_PSX;    '

follows link 0 to the next MCTK and gets word KMCVX_PSX of that bank. For completeness the following is also permitted:-

 
'    mctk+-1;    '

which selects data word -1 (the number of data words in the bank). So the rule is the first sign dictates whether the offset is a link or data, but an optional second sign can be used to get to negative data words or positive links.

Hopefully the derived quantity functions will prove sufficient for most needs but you can supply your own and have it passed the bank words you require. For example:-

 
'    my_value     user 4          mcvx+$KMCVX\_PSX;               '

will call the user routine NTP_DQF_USER passing a pointer to word KMCVX_PSX of MCVX. It is also passed a user function number (in this case 4) so that the user can define a complete set of functions dependent on this number. SNOMAN comes complete with a dummy version of this routine which contains details of how to use it.