N-tuple Derived Quantity Functions (DQFs)

In the notes that follow Pi (P1, P2, P3 ...) denotes the ith parameter. The following DQFs are currently available:-

AND - Logical AND.
BITS - Bit extraction
BITS_10 - Decimal bit extraction
CCC_INFO - Card/Crate/Channel information.
CONFIG_INFO - - Summary Crate/Card/Channel information
COPY - Copy n words.
DATA_SPLITTER - Assign event to data set.
DIFFERENCE - Difference for real parameters.
DIRSUN - Direction of Sun.
DISTANCE - Distance between points.
DIVIDE - Divide two numbers.
DMM - Data Mask Access.
DMM_GET_EMASK - Data Mask Retrieval.
DOT - Vector dot product.
EQ - Logical EQual.
EQUALS - Sums real parameters.
FLOAT_DIFFERENCE - Difference for integers.
FLOAT_EQUALS - Sums integer parameters.
FLT_TEST - Call FLT Hardwired Test.
FT_UNC - Fitter Uncertainties.
GE - Logical Greater than or Equal to.
GET_LINK - Record Data Structure Link.
GET_MCGN - Locate MCGN associated with MCTK
GT - Logical Greater Than.
HALF_WORDS - Use to preserve bits.
IMPACT_PARAMETER - Closest approach to origin.
IN_LIST - Logical Value in List.
IN_RANGE - Logical Between limits.
LE - Logical Less than or Equal to.
LT - Logical Less Than.
JUMP* - Jump to Another Part of the N-tuple.
MAGNITUDE - Magnitude of vector.
MAP_CCC_LCN - Map Card/Crate/Channel -> Logical Channel No.
MAP_TO_PANEL - Map point to panel.
MAP_TO_PMT - Map point to PMT.
MCVX_BACKTRACK - Backtrack up a MCVX/TK Chain.
MULTIPLY - Multiply two numbers.
N_ON_NCD - Did a neutron capture in a NCD?
NCD_SCOPE_PEAK - Find peak on NCD scope
NE - Logical Not Equal.
NEUTRON - Did a neutron occur?
NEXT_BOU - Boundary distance.
NOT - Logical NOT.
NTIME - N-tuple time
NTIME_DIFFERENCE - N-tuple time difference.
NZBANK - Count banks in linear chain.
OR - Logical OR.
PMT_XYZ - PMT coordinates.
RECORD_NUMBER - Record number on input stream.
REGION_SERIAL - Region serial.
REGION_TYPE - Region type.
RESERVED - Just reserves variable.
RUN_TIME - Time since start of run.
SINGLE_DIFFERENCE - Difference for double precision.
SINGLE_EQUALS - Sums double precision parameters.
THETA_PHI - Vector angles.
TIME_DIFFERENCE - Time difference.
TRACK_EXTRAP - XYZ extrapolation of a line segment.
UNPACK_INTERACT - Unpack interaction code.

RESERVED - Just reserves variable.

RESERVED is used to reserve a word in an n-tuple without assigning it a value. It is often used in conjuction with a DQF that returns multiple values, for example THETA_PHI:-

EQUALS - Sums real parameters.

EQUALS take a variable number of parameters, and sums them. Normally only one parameter is supplied and then the n-tuple value is just equal to the word in the data structure (hence the DQF name). E.g.

FLOAT_EQUALS - Sums integer parameters.

FLOAT_EQUALS take a variable number of parameters, all of which are integer, floats and then sums them. Normally only one parameter is supplied and then the n-tuple value is just equal to the floated word in the data structure (hence the DQF name). E.g.

SINGLE_EQUALS - Sums double precision parameters.

SINGLE_EQUALS works on double precision values in an analogous way to FLOAT_EQUALS
. Use SINGLE_EQUALS to sum one or more double precision values P1... should be the addresses of the first word of the two word pair e.g. for the MCVX bank it should be KMCVX_TIM.

DIFFERENCE - Difference for real parameters.

Computes the difference P1 - P2 between 2 real parameters P1, P2.

FLOAT_DIFFERENCE - Difference for integers.

FLOAT_DIFFERENCE takes two integer parameters P1,P2, floats them and computes the difference P1 - P2.

SINGLE_DIFFERENCE - Difference for double precision.

SINGLE_DIFFERENCE takes two double precision parameters P1,P2, converts them to single precision and computes the difference P1 - P2.

MAGNITUDE - Magnitude of vector.

MAGNITUDE computes the magnitude of a real 3 vector. P1 must be the address of the first word of the vector.

DISTANCE - Distance between points.

DISTANCE computes the distance between teo real 3 vector. P1 and P2 must be the addresses of the first words of the vectors.

THETA_PHI - Vector angles.

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 the vectors U, V and W. The first angle is THETA --- the polar angle relative to W, and the second value is PHI --- the azimuthal angle relative to the U of the vector projected into the U V plane. The function has one compulsory parameter P1 and two optional parameters P2 and P3 which define the coordinate system as follows.

1. If neither P2 nor P3 are defined then:-

        W  =  Z axis
        V  =  Y axis
        U  =  X axis
   

   This version is useful for looking at the absolute orientation of a vector. theta theta_phi MCTK+2; phi reserved;
2. If P2 is defined but not P3 then:-

        W  = P2
        V  =  W cross product with X axis
        U  =  V cross product with  W
   

   This version is useful for looking at the orientation of one vector relative to another e.g. a track scatter: P1 is the outgoing track and P2 the incident one. theta theta_phi MCVX-2+2, MCVX-1+2; phi reserved;
3. If both P2 and P3 are defined then:-

        W  = P2
        V  =  W cross product with P3
        U  =  V cross product with  W
   

   This version is useful for looking at tracks as they cross boundaries: P1 is the outgoing track, P2 is the boundary normal and P3 the incident. theta theta_phi MCVX-1+2,MCVX+12,MCVX-2+2; phi reserved;

DOT - Vector dot product.

DOT is the dot product of a real 3 vector. P1 must be the address of the first word of the vector.

REGION_TYPE - Region type.

REGION_TYPE is used to extract region type number 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.

In the single argument form, the first arg. is the region code word e.g.:-

REGION_SERIAL - Region serial.

REGION_SERIAL is used to extract region serial number 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.

In the single argument form, the first arg. is the region code word e.g.:-

UNPACK_INTERACT - Unpack interaction code.

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.

PMT_XYZ - PMT coordinates.

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 P1

MAP_TO_PMT - Map point to PMT.

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

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.

NEXT_BOU - Boundary distance.

NEXT_BOU is given the status word of an MCTK bank (i.e. MCTK+0 or MCVX-1+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.

HALF_WORDS - Use to preserve bits.

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

NZBANK - Count banks in linear chain.

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

MAP_TO_PANEL - Map point to panel.

MAP_TO_PANEL returns 3 variables; the X,Y and Z in panel coordinate space space of a point whose detector space coordinates are P2. The number (which may be part of a region code) of the panel being mapped to, is P1.

Note: The panel coordinate system is the local space as described in ge_panels.inc except that the origin is the panel centre, not the first hexagon.

TIME_DIFFERENCE - Time difference.

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

AND - Logical AND.

AND performs a logical AND of its parameters and returns true (1.) or false (0.).

OR - Logical OR.

OR performs a logical OR of its parameters and returns true (1.) or false (0.).

NOT - Logical NOT.

NOT performs a logical NOT of its parameter and returns true (1.) or false (0.).

LT - Logical Less Than.

LT performs a logical Less Than and returns true (1.) if the first parameter is less than the second. Otherwise it returns false (0.).

LE - Logical Less than or Equal to.

LE performs a logical Less than or Equal to and returns true (1.) if the first parameter is less than or equal to the second. Otherwise it returns false (0.).

GT - Logical Greater Than.

GT performs a logical Greater Than and returns true (1.) if the first parameter is greater than the second. Otherwise it returns false (0.).

GE - Logical Greater than or Equal to.

GE performs a logical Logical Greater than or Equal to and returns true (1.) if the first parameter is greater than or equal to the second. Otherwise it returns false (0.).

EQ - Logical EQual.

EQ performs a logical EQual and returns true (1.) if the first parameter is equal to the second. Otherwise it returns false (0.).

NE - Logical Not Equal.

NE performs a logical Not Equal and returns true (1.) if the first parameter is not equal to the second. Otherwise it returns false (0.).

IN_RANGE - Logical Between limits.

IN_RANGE performs a logical between limits and returns true (1.) if the second parameter is greater than or equal to the first and less than or equal to the third. Otherwise it returns false (0.).

BITS - Bit extraction

BITS extracts P3 bits, starting at bit P2, from the integer parameter P1. The bit numbering convention has bit 0 as the least significant bit. The resulting set of bits are treated as an integer and floated.

NTIME - N-tuple time

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

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

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

NTIME_DIFFERENCE - N-tuple time difference.

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

DIRSUN - Direction of Sun.

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

COPY - Copy n words.

COPY transfer a set of words directly into another part of the DQF. The general form is:-

• _my_data is a previously defined data entry. This is the point in the n-tuple that will receive the data.
• source is the source of the data. It can be any type of parameter. If this parameter is omitted, the source is taken to be the word in the n-tuple that precedes the current entry.
• num_words is the number of words to be copied. If this parameter is omitted, 1 is assumed.

It can also be used to form simple counters, exploiting the fact that the EQUALS DQF sums its parameters if more than one:-

GET_LINK - Record Data Structure Link.

GET_LINK stores a data structure link. For example:-

The primary use of GET_LINK is to prepare a link for MCVX_BACKTRACK

GET_MCGN - Locate MCGN associated with MCTK

GET_MCGN attemps to locate the MCGN associated with a given MCTK:-

For example, to get the MC radiative corrections for an electron:-

MCVX_BACKTRACK - Backtrack up a MCVX/TK Chain.

The MCVX_BACKTRACK DQF is used to backtrack from an MCVX through its incident track link to an MCTK and hence to the MCVX that produced it. Here it applies a test, which if failed, causes the backtrack to repeat. In this way the track producing the initial MCVX can, if required, be backtracked to its source. The DQF is used as follows:-

• _my_tk is a link to an MCTK. If MCVX_BACKTRACK fails then the DQF returns an undefined result and the normal rules for discarding n-tuple entries apply. If you keep the entry then the link _my_tk will be zero in this case. If the backtrack succeeds then _my_tk will be the MCTK leaving the MCVX, that the backtracking located, which leads to the MCVX that was the start point for the scan. For example, if scanning back from a sink vertex for a photon, looking for its creation vertex _my_tk will be the track at the point at which the photon left its creation vertex. Other photons may also be created at this vertex, so you need _my_tk to identify the one you have backtracked.
• _my_vx is a link to the MCVX that is the starting point for the backtrack. It has to be a link stored in the n-tuple using GET_LINK because, if the backtrack succeeds, it is replaced by the vertex that was found. If the backtrack fails it will get set to zero.
• vertex_class is the type of vertex class that the DQF is looking for. For example to look for an interaction vertex, vertex_class should be $KMCVX_INT (or 3).
• test_type is the type of test to be applied. For all types of vertex class, test type 0 means any vertex of that class will do. If the test type is omitted, 0 is assumed.
• test_args are additional parameters that may be required depending upon the test type. Test type 0 requires no further parameters so, to backtrack until an interaction vertex is found:- ' _my_tk mcvx_backtrack _my_vx, $KMCVX_INT; ' Rather than list here all the tests that MCVX_BACKTRACK provides, the user should consult the specification section of:- mcvx_backtrack.for

A Word of Caution

JUMP* - Jump to Another Part of the N-tuple.

There are 4: JUMP, JUMP_TRUE, JUMP_FALSE and JUMP_UNDEFINED. JUMP jumps uncoditionally, the remainder are supplied with a test and if the test condition is satisfied, jump. After jumping to another part of the n-tuple entry, filling continues from there. They are used as follows:-

• _ is the name for the entry. The DQF returns the value of its second arguement, except for JUMP, which just returns 1.0. As this information is singularly uninteresting the `unnamed'' name _ is recommended. It may be reused on all jump DQFs, so relieving the user of the chore of inventing names for junk!
• dqf_name is one of:-
  • JUMP which is an unconditional jump; there is no second parameter in this case.
  • JUMP_TRUE which means the jump will happen if the test value is true. True is any value except 0. or the undefined value.
  • JUMP_FALSE which means the jump will happen if the test value is false i.e. 0.
  • JUMP_UNDEFINED which means the jump will happen if the test value is undefined.
• relative_offset is the number of entries, relative to the current one, to jump. The offset can be:-

  • negative literal e.g. -2 to jump backwards. For example -2 jumps back two entries. Jumping back up the n-tuple runs a risk: if the test is always satisfied, the program goes into an endless loop. To avoid this, collection of the current n-tuple is aborted and an informational ZTELL warning is issued, if too many jumps are executed.

    Attempting to jump back before the first entry discards the current n-tuple.

  • an earlier entry name e.g. _my_vx to jump backwards. In this case the entry name which acts like a label for the jump. This form is preferred as it will continue to work even if new new entries are inserted between the jump target and the jump DQF.

  • positive literal e.g. +1. to jump forward, for example +1 which jumps on just one entry (which is quite pointless as that is what will be processed next if the test fails).

  • a later entry name to jump forwards by referring to an entry name further down the n-tuple. As with jumping backwards, this form is preferred.

    Forward jumps must be treated with caution, jumping over entries will leave them at their undefined entry, even if you have requested that partial entries are to be discarded.

    Attempting to jump forward beyond the last entry signals that the current n-tuple is complete and is ready to be stored.

• test_value is the value to be tested. Most likely this will refer to a previous entry that holds the result of some DQF test. If this parameter is omitted, then the value stored in the preceeding word is used, which is useful if the test condition is only needed for the jump, eg.:-

The primary use of the JUMP DQFs is to allow fine tuning of the DQF MCVX_BACKTRACK For example, suppose you wish to backtrack from a scanned point MCVX to the first upstream interaction vertex which has its creation bit (KMCVX_CRE) set. This could be done as follows:-

CCC_INFO - Card/Crate/Channel info.

This is an interface to the CCC_INFO function in SNOMAN and is used to retrieve information on a particular CCC DAQ Circuit Number. The first argument specifies the type of information required:-

Example:-

IN_LIST - Logical Value in List.

This function will return a '1.' if the value given by the first parameter is contained in a list pointed to by the second. If only 2 parameters are given, then the second should be a link to a titles bank that contains the list:-

The usage with 3 parameters is more general. The second parameter points to the first word of the list, and the third gives the length (it should be floating point). Eg:-

RECORD_NUMBER - Record number on input stream.

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.:-

FLT_TEST - Call FLT Hardwired Test.

FLT_TEST performs the Event Filter (FLT) hardwired test supplied as parameter 1 See the Event Filter section of the Iser Manual. Note: all hardwired tests are negative.

MULTIPLY - Multiply two numbers.

MULTIPLY simply multiples its two parameters. For example:-

NCD_SCOPE_PEAK - Find peak on NCD scope

Given a link to an NEMS bank, NCD_SCOPE_PEAK finds the widest negative peak "above" background. It does a very simplistic estimate of the height, width and centre as well as computing the background height and RMS. If no peak is found, the peak parameters are set to zero. Example:-

RUN_TIME - Time since start of run.

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

MAP_CCC_LCN - Map Card/Crate/Channel -> Logical Channel No.

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

IMPACT_PARAMETER - Closest approach to origin.

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.:-

TRACK_EXTRAP - XYZ extrapolation of a line segment.

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.:-

DMM - Data Mask Access.

DMM gives access to DAMN and DARN data masks. P1 is always the mask number and uses the following convention:-

1. DMM P1

   Return 1.0 if any bit in mask P1 is on. For example:- 'test dmm 2; ' Return 1.0 if any bit on the DARN bank 2 mask is set.

2. DMM P1,P2

   Return 1.0 if any of bits set in P2 is set for the mask P1. For example:- 'test dmm 0,7; ' Return 1.0 if any of bits 0, 1 or 2 of the DAMN bank 0 is set.

3. DMM P1,P2,P3

   Perform the operation defined by P3 on mask P1 using the bits selected in P2 operation = action*100 + value action = 0 OR test of selected bits against value = 1 AND test of selected bits against value = 2 SET selected bits to value value = 0 0 (false) = 1 1 (true) = 2 (undefined) = 10 not 0 (not allowed for SET) = 11 not 1 ( " " " " ) = 12 not 2 ( " " " " ) Examples:- 'test dmm 0,12,111; ' Return 1. if bits 2 and 3 of DAMN bank 0 are both not 1 (either 0 or undefined). 'test dmm 3,5,201; ' Set bits 0 and 2 of DARN 3 mask to 1. Return 1. When DMM is used to set bits it always returns 1.

DMM_GET_EMASK - Data Mask Retrieval.

DMM_GET_EMASK retrieves the full 32 bits of a DAMN or DARN data mask. P1 is always the mask number and uses the following convention:-

• Applied Mask: Bit is set if test applied.
• Result Mask: Bit is set if test applied and succeeded.

DIVIDE - Divide two numbers.

DIVIDE simply divides its first parameter by its second. For example:-

FT_UNC - Fitter Uncertainties.

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:-

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.

DATA_SPLITTER - Assign Event to a Data Set.

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

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.

BITS_10 - Decimal bit extraction

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.

CONFIG_INFO - Summary Crate/Card/Channel information

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:

NEUTRON - Did a Neutron Occur?

This function returns 1 if a neutron was created during event generation and 0 otherwise. This is particularly useful for low energy background analyses and appears in the standard ntuples.

Note this function only operates on Monte Carlo data and will not unfortunately tell you if a real event contains a neutron or not.

N_ON_NCD - Did a neutron capture in a NCD?

This function returns 1 if a neutron captured within NCD and 0 otherwise. More specifically, it loops through all vertices and checks whether within a live volume an (n,p) process (328) occured.

Note this function only operates on Monte Carlo data and will not unfortunately tell you if a real neutron capture on an NCD or not.