Arithmetic DQFs

Arithmetic DQFs return floating point numbers.

Figure 6.1: Arithmetic Derived Quantity Functions (Part 1)

Figure 6.2: Arithmetic Derived Quantity Functions (Part 2)

Table 6.1 lists all available Arithmetic DQFs. There follows here a set of notes to go with that table.

1. EQUALS and FLOAT_EQUALS take a variable number of parameters, they simply sum all the parameters supplied. 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

2. THETA_PHI returns 2 variables so must be followed by a variable using the RESERVED function. The angles are relative to the right handed coordinate system defined by the vectors $\bar U, \bar V$ and $\bar W$. The first angle is $\theta$ -- the polar angle relative to $\bar W$, and the second value is $\phi$ -- the azimuthal angle relative to the $\bar U$ of the vector projected into the $\bar U \bar V$ plane. The function has one compulsory parameter $P_1$ and two optional parameters $P_2$ and $P_3$ which define the coordinate system as follows.
   • If neither $P_2$ nor $P_3$ are defined then:-
     $$\begin{eqnarray*} \bar W & = & \bar Z\\ \bar V & = & \bar Y\\ \bar U & = & \bar X \end{eqnarray*}$$
     
     
     This version is useful for looking at the absolute orientation of a vector.

   • If $P_2$ is defined but not $P_3$ then:-
     $$\begin{eqnarray*} \bar W & = & \bar {P_2}\\ \bar V & = & \bar W \times \bar X \\ \bar U & = & \bar V \times \bar W \end{eqnarray*}$$
     
     
     This version is useful for looking at the orientation of one vector relative to another e.g. a track scatter: $P_1$ is the outgoing track and $P_2$ the incident one.

   • If both $P_2$ and $P_3$ are defined then:-
     $$\begin{eqnarray*} \bar W & = & \bar {P_2}\\ \bar V & = & \bar W \times \bar {P_3} \\ \bar U & = & \bar V \times \bar W \end{eqnarray*}$$
     
     
     This version is useful for looking at tracks as they cross boundaries: $P_1$ is the outgoing track, $P_2$ is the boundary normal and $P_3$ the incident track.

3. REGION_TYPE and REGION_SERIAL are used to extract region type and serial numbers from an integer region code. Region codes are 7 digits long and so cannot be stored in a floating point word without loss of accuracy.

4. UNPACK_INTERACT returns 3 variables: ppp,ttt,ccc in that order, corresponding to the three parts of the interaction code stored in the MCVX bank. If required, the DQF NZBANK can be used to count the number of outgoing tracks at a vertex.

5. SINGLE_EQUALS and SINGLE_DIFFERENCE work on double precision values in an analogous way to FLOAT_EQUALS and FLOAT_DIFFERENCE. Use SINGLE_EQUALS to sum one or more double precision values and SINGLE_DIFFERENCE for their differences. $P_1$... should be the addresses of the first word of the two word pair e.g. for the MCVX bank it should be KMCVX_TIM.

6. PMT_XYZ returns 3 variables; the X,Y and Z in detector space of a PMT whose number (which may be part of a region code) is $P_1$.

7. MAP_to_PMT returns 3 variables; the X,Y and Z in PMT coordinate space space of a point whose detector space coordinates are $P_2$. The number (which may be part of a region code) of the PMT being mapped to, is $P_1$.

   Note: The PMT coordinate system has the Z axis along the axis of symmetry pointing towards the front of the PMT. The origin is within the PMT, approximately 17cm below the front face of the concentrator.

8. NEXT_BOU is given the status word of an MCTK bank (i.e. MCTX+0 or MCVX-$KMCVX_MCTK+0 etc.). It uses the direction cosines from this MCTK bank and the position from the supporting MCVX bank to return the distance to the next boundary in the given direction. If status bit 1 of MCTK is set, i.e. the track does not come directly from its supporting vertex then NEXT_BOU returns the undefined value.

9. HALF_WORDS can be used as a way of transferring all bits intact to an ntuple e.g. if storing the seed. $P_1$ is treated as a 32-bit unsigned bit pattern. The function returns 2 variables, the top half of $P_1$ followed by the bottom half of $P_1$, both as 16-bit unsigned integers that have been converted to floating point.

10. NZBANK should be passed the address of a bank and will return the number of banks in the linear chain, including the starting bank. For example:-

     
        '    num_mctk   nzbank      MCVX-$KMCVX_MCTK;    '
    

    will store the number of tracks at the vertex. Unlike other DQFs, if the address of the bank is 0, it will not be treated as an undefined parameter, so counting banks in an empty linear chain will give a zero.

11. MAP_to_PANEL returns 3 variables; the X,Y and Z in panel coordinate space of a point whose detector space coordinates are $P_2$. The number (which may be part of a region code) of the panel being mapped to, is $P_1$. The panel coordinate space is the local space as described in ge_panels.inc except that the origin is the panel centre, not the first hexagon.

12. TIME_DIFFERENCE computes the time difference between two absolute or relative times. For example:-

     
        ' d_tfit  time_difference  MCVX+$KMCVX_TIM,FTTV+$KFTXV_T; '
    

    gives the time difference between the fitted time (from the time fitter) and a vertex time. This function passes its arguments as the first two arguments to the utility routine TIME_DIFFERENCE. Please consult that routine to see exactly what pairs of times can be compared and what assumptions are made when computing time differences.

13. BITS extract $P_3$ bits from the integer $P_1$ starting at bit number $P_2$. The bit numbering convention used has bit 0 as the least significant bit.

14. NTIME returns 4 variable N-tuple time. If one parameter is supplied it should be the address of a Universal Date Stamp, for example:-

        ' time_jdy     ntime       EV+$KEV_JDY;  '
        ' time_sec     reserved               ;  '
        ' time_msec    reserved               ;  '
        ' time_nsec    reserved               ;  '
    

    and NTIME returns:-

    • Julian date
    • Universal secs
    • Universal microsecs
    • Universal nsecs

    see section 7.2.

    If two parameters are supplied the first should be the Global trigger time and the second parameter is a dummy (just used to signal that the 50MHz clock is being used). For example:-

        ' time_jdy     ntime       EV+$KEV_GTR,0;  '
        ' time_sec     reserved               ;    '
        ' time_msec    reserved               ;    '
        ' time_nsec    reserved               ;    '
    

    In this case NTIME returns:-

    • Minus processed event number
    • Universal secs
    • Universal microsecs
    • Universal nsecs

    This second form can be useful when analysing some of the early data, if the 10MHz clock was not running. The format can be recognised as the first word is negative. It is a minus the processed event number and can be used to provide protection against one rollover; assuming that events are processed in time order. NTIME_DIFFERENCE can accepts both formats, but they must not be mixed within a single call.

15. NTIME_DIFFERENCE computes the nsec time difference between 2 n-tuple times. For example:-

     
        ' dtime     ntime_difference  time_jdy_1, time_jdy_2;'
    

16. DIRSUN returns the direction of the sun in detector coordinates ( x=East, y=North, z=zenith ) for a given time. For example:-

     
        ' drxsun    dirsun       EV+$KEV_JDAY;  '
        ' drysun    reserved;                   '
        ' drzsun    reserved;                   '
    

17. CCC_INFO returns status information on a particular Card/Crate/Channel (ie DAQ circuit number). It takes two parameters, the first specifying the type of information required, and the second giving the CCC number. For example:-

     '  thresh   ccc_info    $CCC_THRESH,       pmt+$KPMT_PIN; '
     '  thresh_z ccc_info    $CCC_THRESH_ZERO,  pmt+$KPMT_PIN; '
     '  status   ccc_info    $CCC_STATUS,       pmt+$KPMT_PIN; '
     '  hv       ccc_info    $CCC_HV,           pmt+$KPMT_PIN; '
     '  tube_ok  ccc_info    $CCC_TUBE_ON_LINE, pmt+$KPMT_PIN; '
     '  chan_ok  ccc_info    $CCC_CHAN_ON_LINE, pmt+$KPMT_PIN; '
    

    where symbol table mnemonics are used to specify the type. Their meanings are as follows:-

    Mode	Mnemonic	Data returned
    1	CCC_THRESH	8-bit discriminator setting
    5	CCC_THRESH_ZERO	8-bit discriminator zero
    3	CCC_STATUS	4 byte status. See ccc_info.for
    6	CCC_HV	8-bit high voltage.
    7	CCC_TUBE_ON_LINE	= 0 if PMT offline, = 1 if on-line
    8	CCC_CHAN_ON_LINE	= 0 if channel offline, = 1 if on-line

    The full status returned by CCC_STATUS is 4 bytes long and hence cannot be converted to floating without precision loss, so only one byte is returned. By default this is byte 0, the crate byte, although others can be selected by supplying a third parameter. Example:-

     '  cra_stat   ccc_info    $CCC_STATUS,   pmt+$KPMT_PIN, 0; '
     '  car_stat   ccc_info    $CCC_STATUS,   pmt+$KPMT_PIN, 1; '
     '  cha_stat   ccc_info    $CCC_STATUS,   pmt+$KPMT_PIN, 2; '
     '  pmt_stat   ccc_info    $CCC_STATUS,   pmt+$KPMT_PIN, 3; '
    

18. RECORD_NUMBER returns the total number of records from all files (in parallel or concatenated) that have been returned by the input processor so far. It can be useful when tracking down problems in the data. Once the record number is known, the SKIP option on the FILE command can be used to quickly retrieve the event. E.g.:-

        ' rec_no     record_number            ;  '
    

19. FLT_TEST performs the Event Filter (FLT) hardwired test $P_1$. See section 9.1. Note: all hardwired tests are negative.

20. MULTIPLY multiplies two numbers together. E.g.:-

        ' six        multiply   2.,3.;           '
    

21. RUN_TIME returns the time since the start of the run in seconds. It uses the routine RUN_TIME.

        ' run_time   run_time;                   '
    

    By default is stores the number in single precision, but supplying a parameter, whose value is immaterial, it produces a double precision result:-

        ' run_time   run_time, 1;                 '
        ' Run_tim2   reserved;                    '
    

    This is not generally useful in an n-tuple, as PAW only knows about single precision floating point numbers in row-wise n-tuples, but is used by the Random Access Analyser (see section 8.1).

22. MAP_CCC_LCN returns the Logical Channel Number (LCN = Crate / Card / Channel for a given CCC (Card / Crate / Channel). E.g.:-

        ' lcn  map_ccc_lcn   PMT+$KPMT_PIN;           '
    

23. IMPACT_PARAMETER returns the radius of the point on a line closest to the origin. The first parameter must be a point X,Y,Z and the second parameter must be a vector U,V,W of direction cosines. E.g.:-

      ' impct_p impact_parameter MCVX+$KMCVX_PSX, MCTK+$KMCTK_DRX; '
    

    For this example, this will give a measure of the asymettry of the Cherenkov cone for the particle given in the MCVX bank. A large impact parameter means the cone is skewed; a small impact parameter means the hit pattern should be circular. This is useful number for things like muon tracks, where the impact parameter is the only parameter that can break spherical symmetry.

24. TRACK_EXTRAP extrapolates a vertex and track direction to give the XYZ components of the line segment at a given radius from the origin. The first parameter must be a point X,Y,Z and the second parameter must be a vector U,V,W of direction cosines. The third parameter is optional; if left unspecified, the point is at the minimum radius (the impact parameter).

    E.g.:-

      ' shell_x track_extrap MCVX+$KMCVX_PSX, MCTK+$KMCTK_DRX  900;'
      ' shell_y reserved;                                          ' 
      ' shell_z reserved;                                          '
    

    This will give the X,Y,Z coordinates of a point along the track direction with a distance 900 cm from the origin. This is useful for finding things like the position a high-energy muon leaves a spherical region (assuming a straight track), given only it's intial vertex.

25. DIVIDE simply divides its first parameter by its second. E.g.:-

    ' two     divide     6., 3.;  '
    

    If the absolute value of the result exceeds 1.e+30 the result is set undefined.

26. FT_UNC takes the fitter vertex bank as the argument. The fitter vertex bank contains 10 variables which define the covariance matrix. This dqf finds the track supported by the fit vertex and evaluates the uncertainty in the fit along the direction of the fit. The second variable returned is a crude average perpendicular to the fit direction. (The value of sigma squared in two orthogaonal but arbitrary directions perpendicular to the fit are averaged. Then the square root is taken.) Please keep in mind that the parallel uncertainty is very well defined but the perpendicular isn't. For example:-

        par           ft_unc            fttv;
        perp          reserved
    

    If there is no fit direction (ie no ftxt) then the dqf will return undefined, so it will not bomb the code if used with the quad fitter for example. If the covariance matrix is not defined by the fitter, then the result will be unpredicatble. (It will not be zero unless the ftxv bank is lifted with initialization to zero of bank contents; it is up to fitter authors to define this.)

    Currently only FTT supports this option, although it would be straight-foward to add to any time-based fitter.

27. DATA_SPLITTER takes as an argument the number of sets the user wishes the data split into (with no argument this number defaults to 3). Therefore

        data_set     data_splitter      3;
    

    is equivalent to

        data_set     data_splitter;
    

    The DQF returns an integer indicating to which data set the current event belongs. For example a user defined filter that splits the data into 3 sets and only allows events in data set 1 to pass would look like this:-

    $enable_test   1
    $define_test   1     $no_scan
    $define_test   1     $line_1 'data_set  data_splitter 3;             '
    $define_test   1     $line_2 'test      eq            data_set,1.;   '
    

    Assuming that the user (or default) has specified that the data should be split into 3 sets then the code works in the following way:-

    First the code grabs the time stamp of the current event, then, using the start and end times of the current run, it splits the runs into 3 consecutive time bins and works out which time bin the current event sits in. There then follows a mapping from time bin to data set. Currently the algorithm for doing this is to add the run number to the time bin and call the result "shifted_bin" and then to calculate 1 + MOD(shifted_bin, 3). The result of this is the data set to which the current event has been assigned.

    The time bins do get pseudorandomly rearranged into data sets, but in such a way that consecutive run numbers just have their time bins cyclically permuted by one step relative to each other. This could be changed in future if it is not considered sufficiently random. The important point is that the mapping is deterministic - an event assigned to data set 2 by a SNOMAN run will always be assigned to data set 2 by any other SNOMAN job.

28. BITS_10 extracts P3 decimal "bits" (i.e. digits), starting at digit P2, from the integer parameter P1. The numbering convention has digit 0 as the least significant digit. The resulting set of digits are treated as an integer and floated.

     '    year         bits_10           EV+$KEV_DTE,4,4; '
     '    month        bits_10           EV+$KEV_DTE,2,2; '
     '    day          bits_10           EV+$KEV_DTE,0,2; '
    

    In the above example the year, month and day are extracted from EV's local date stamp.

29. CONFIG_INFO - summary crate/card/channel information

    Number of parameters: 0

    This function returns summary information on the detector configuration from the DQXX banks. The information is returned as an 6-element array of real values:

    Element Description

    1. # of crates operational (operational == present, receiving GTs, online, and HV .ne. 0)

    2. # of slots operational (operational == crate, MB, PMTICs, DCs all present, eCPU readout enabled, relays all on)

    3. # of relays on

    4. # of channels with 100ns trigger enabled

    5. # of channels with sequencer enabled

    6. # of channels with HV on (HV on == PMTIC channel resistor present and relay on and crate HV .ne. 0)

    Example of use as part of an ntuple definition:

    #.   Variable     Function          Parameter(s)
    #.    Name
    #.
    '  ncrates  config_info; '
    '  nslots reserved;'
    '  nrelays reserved;'
    '  n100ns reserved;'
    '  nseq   reserved;'
    '  nch_hvon reserved;'
    '  END_OF_NTUPLE; '    #.  This marks the end of the ntuple.
    

    Note, if number of crates operational is zero, the rest of the values default to zero. A likely cause of this condition is if the correct DQXX bank is not found in the database.