GFC.c File Reference

Gamma Filter Code. More...

#include "EFC/EDM.h"
#include "EFC/EFC_edsFw.h"
#include "EFC/EFC.h"
#include "EFC/GFC.h"
#include "EFC/GFC_cfg.h"
#include "EFC/GFC_status.h"
#include "EFC/TFC_prjFind.h"
#include "EFC/TFC_prjDef.h"
#include "EFC/TFC_tolerances.h"
#include "EFC/TFC_geometry.h"
#include "TFC_geometryDef.h"
#include "GFC_def.h"
#include "GFC_resultDef.h"
#include "ATF_filter.h"
#include "ATF_shadowedTowers.ih"
#include "AFC_splash.h"
#include "CFC_ratio.h"
#include "TFC_tolerancesDef.h"
#include "TFC_triggerFill.h"
#include "TFC_triggerForm.h"
#include "TFC_triggerSortedForm.h"
#include "TFC_acd.h"
#include "TFC_skirt.h"
#include "EDS/EDS_fw.h"
#include "EDS/EBF_cid.h"
#include "EDS/EBF_acd.h"
#include "EDS/EBF_gem.h"
#include "EDS/EBF_tkr.h"
#include "EDS/EBF_dir.h"
#include "EDS/EBF_calEnergy.h"
#include "EDS/EBF_gemLocate.h"
#include "EDS/ECR_cal.h"
#include "EDS/EDR_cal.h"
#include "EDS/EDR_tkr.h"
#include "EDS/EDR_calUnpack.h"
#include "EDS/EDR_tkrUnpack.h"
#include "GEO_DB/GEO_DB_schema.h"
#include "GFC_DB/GFC_DB_schema.h"
#include "CDM/CDM_pubdefs.h"
#include <string.h>

Include dependency graph for GFC.c:


Defines
#define	_MOVE_BIT(_w, _from, _to) (((_w >> _from) & 1) << _to)
	Moves a bit from one location to another.
#define	MASK0_4_OF_6
	A bit mask to be ordered with the dynamic 4/6 coincidence mask. Only patterns with 4/6 layers set are selected by this mask. This is the first of 2 32-bit words, representing patterns 0-0x1f.
#define	MASK1_4_OF_6
	A bit mask to be ordered with the dynamic 4/6 coincidence mask. Only patterns with 4/6 layers set are selected by this mask. This is the second of 2 32-bit words, representing patterns 0x20-0x3f.
Typedefs
typedef enum _ACD_SIDE_TILES_M	ACD_SIDE_TILES_M
	Typedef for enum _ACD_SIDE_TILES_M.
Enumerations
enum	_ACD_SIDE_TILES_M { ACD_SIDE_TILES_M_ROW = (0x1f << 16) \| (0x1f), ACD_SIDE_TILES_M_ROW0 = ACD_SIDE_TILES_M_ROW<<(05), ACD_SIDE_TILES_M_ROW1 = ACD_SIDE_TILES_M_ROW<<(15), ACD_SIDE_TILES_M_ROW2 = ACD_SIDE_TILES_M_ROW<<(2*5), ACD_SIDE_TILES_M_ROW01 = ACD_SIDE_TILES_M_ROW0 \| ACD_SIDE_TILES_M_ROW1, ACD_SIDE_TILES_M_ROW3 = 0x80008000 }
	Enumerates the bit masks used to extract the struck tiles in various rows for both the + and - ACD side tile planes. More...
Functions
static __inline int	isVetoed (unsigned int status, unsigned int vetoes)
	Checks whether any of the veto bits are up.
static __inline unsigned int	cntBits (unsigned int word)
	Counts the bits in the specified word.
static __inline int	evaluateAcd (const GammaCfgAcd *cfg, int status, int energy, unsigned int acd_x, unsigned int acd_y, unsigned int acd_z, unsigned int acd_cnt)
	Rejects events based on CAL energy and ACD info.
static __inline int	evaluateZbottom (const GammaCfgZbottom cfg, int energy, const EBF_dir dir)
	Makes a quick test to see if there is energy in the CAL without the possibility of a track pointing into it.
static __inline int	evaluateCal (const GammaCfgCal cfg, int energy, EBF_dir dir, EDR_cal cal, const ECR_cal calCal)
	Evaluates cuts that can be made solely on the basis of the CAL information.
static __inline int	evaluateAtf (const GammaCfgAtf cfg, int energy, unsigned int acd_x, unsigned int acd_y, unsigned int acd_z, unsigned int tmsk, const EBF_dirCtbDsc contributor)
	Evaluates whether any tower with a track trigger is in coincidence with a shadowing ACD tile.
static __inline int	classifyAcd (unsigned int acd_x, unsigned int acd_y, unsigned int acd_z)
	Sets status bits indicating which part of the ACD has hits. return A status mask indicating those parts of the ACD which have hits.
static __inline int	nominateTowers (const EBF_dir *dir)
	Creates a list of towers with the potential for finding tracks in.
static __inline int	constrainEnergy (int energy)
	Limits the absolute value of the energy to be < 23 bits.
static unsigned int	tkrFilter (const GammaCfgTkr cfg, int energy, unsigned int acd_x, unsigned int acd_y, unsigned int acd_z, unsigned int vetoes, EDR_tkr tlr, TFC_prjs *prjs)
	Performs the most computationally intensive portions of the filtering. This involves TKR pattern recognition and matching to the ACD, skirt region and CAL.
static unsigned int	tkrFind (const GammaCfgTkr cfg, int energy, EBF_dir dir, EDR_tkr tlr, TFC_prjs prjs)
	Does the track finding.
static __inline unsigned int	tkrSetStatus (const GammaCfgTkr *cfg, int energy, int prjCnt)
	Completes tracker status, by evaluating the projection count.
static __inline int	evaluateTkr (const GammaCfgTkr cfg, int energy, unsigned int acd_x, unsigned int acd_y, unsigned int acd_z, unsigned int vetoes, EBF_dir dir, EDR_tkr tkr, TFC_prjs prjs)
	Does the projection finding and evaluates all the cuts based on the found projections.
static __inline int	gammaFilter (GFC gfc, unsigned int pktBytes, EBF_pkt pkt, EBF_siv siv, EDS_fwIxb ixb, unsigned int vetoes, GFC_result result)
	Determines the fate of 1 event.
static int	compileCfgPrms (GammaCfgPrms cfg, const GFC_DB_prms prms)
	Compiles/commits the set of user defined parameters into the the configuration block.
int	GFC_sizeof (int cnt)
	Sizes the gamma filtering control structure.
int	GFC_cfgSizeof (void)
	Sizes the gamma filtering configuration as it is used in the actual filtering progam.
int	GFC_resultSizeof (const GFC *gfc)
	Returns the size, in bytes, of one result vector.
int	GFC_cfgCompile (GFC_cfg cfg, const GFC_DB_prms prms)
	Implements the transformation of the configuration parameters as specified by the user, cfg, into the internal form, ctlCfg.
GFC_cfg *	GFC_cfgSet (GFC gfc, GFC_cfg cfg)
	Makes the specified internal representation of the configuration parameters the current active one.
int	GFC_filter (GFC gfc, unsigned int pktBytes, EBF_pkt pkt, EBF_siv siv, EDS_fwIxb ixb, unsigned int vetoes, GFC_result result)
	Determines the fate of 1 event.
unsigned int	GFC_fwNeeds (void)
	Returns a bit mask of the EDS_fw needs.
unsigned int	GFC_fwObjects (void)
	Returns a bit mask of the EDS_fw objects used by the gamma filter.
Variables
const AFC_splashMap	AFC_SplashMap1x1
	Data structure representing the SplashMap with only nearest neighbors considered to be 'near' tiles.
const ATF_shadowedTowers	ATF_ShadowedTowers2x2

Detailed Description

Gamma Filter Code.

Author:: JJRussell - russell@slac.stanford.edu

   CVS $Id: GFC.c,v 1.11 2007/12/13 18:10:30 russell Exp $

Define Documentation

#define _MOVE_BIT ( _w,
_from,
_to ) (((_w >> _from) & 1) << _to)

Moves a bit from one location to another.

Returns:
A new 32-bit word with the specified bit set to the value of the _from bit in the original word.

Parameters:

_w The word to move the bit from

_from The bit position (LSB = 0) to extract the bit from

_to The bit position (LSB = 0) to move the bit to

#define MASK0_4_OF_6

Value:
((0 << 0x00) | (0 << 0x01) | (0 << 0x02) | (0 << 0x03) | \ (0 << 0x04) | (0 << 0x05) | (0 << 0x06) | (0 << 0x07) | \ (0 << 0x08) | (0 << 0x09) | (0 << 0x0a) | (0 << 0x0b) | \ (0 << 0x0c) | (0 << 0x0d) | (0 << 0x0e) | (1 << 0x0f) | \ (0 << 0x10) | (0 << 0x11) | (0 << 0x12) | (0 << 0x13) | \ (0 << 0x14) | (0 << 0x15) | (0 << 0x16) | (1 << 0x17) | \ (0 << 0x18) | (0 << 0x19) | (0 << 0x1a) | (1 << 0x1b) | \ (0 << 0x1c) | (1 << 0x1d) | (1 << 0x1e) | (1 << 0x1f))
A bit mask to be ordered with the dynamic 4/6 coincidence mask. Only patterns with 4/6 layers set are selected by this mask. This is the first of 2 32-bit words, representing patterns 0-0x1f.

#define MASK1_4_OF_6

Value:
((0 << 0x00) | (0 << 0x01) | (0 << 0x02) | (0 << 0x03) | \ (0 << 0x04) | (0 << 0x05) | (0 << 0x06) | (1 << 0x07) | \ (0 << 0x08) | (0 << 0x09) | (0 << 0x0a) | (1 << 0x0b) | \ (0 << 0x0c) | (1 << 0x0d) | (1 << 0x0e) | (1 << 0x0f) | \ (0 << 0x10) | (0 << 0x11) | (0 << 0x12) | (1 << 0x13) | \ (0 << 0x14) | (1 << 0x15) | (1 << 0x16) | (1 << 0x17) | \ (0 << 0x18) | (1 << 0x19) | (1 << 0x1a) | (1 << 0x1b) | \ (1 << 0x1c) | (1 << 0x1d) | (1 << 0x1e) | (1 << 0x1f))
A bit mask to be ordered with the dynamic 4/6 coincidence mask. Only patterns with 4/6 layers set are selected by this mask. This is the second of 2 32-bit words, representing patterns 0x20-0x3f.
The bits representing the last 6 layers are extracted from the X/Y layer hit masks and placed in the low 6 bits or a new word. This word can take on the values 0x00 to 0x3f (0-63).
If the value of this word is less than 32, then MASK0_4_OF_6 is used. That is, of the low 5 bits, 4 must be set.
If the value of this word is greater than or equal to 32, then MASK1_4_OF_6 is used. That is, of the remaining low 5 bits, 3 must be set.

Enumeration Type Documentation

enum _ACD_SIDE_TILES_M

Enumerates the bit masks used to extract the struck tiles in various rows for both the + and - ACD side tile planes.

Enumerator:

ACD_SIDE_TILES_M_ROW Primitive bit mask for 1 5 tile row of ACD side tiles

ACD_SIDE_TILES_M_ROW0 Row 0 ACD side tiles, bit mask

ACD_SIDE_TILES_M_ROW1 Row 1 ACD side tiles, bit mask

ACD_SIDE_TILES_M_ROW2 Row 2 ACD side tiles, bit mask

ACD_SIDE_TILES_M_ROW01 Rows 0 and 1 ACD side tiles, bit mask

ACD_SIDE_TILES_M_ROW3 Row 3 ACD side tiles, bit mask

Function Documentation

static __inline int classifyAcd ( unsigned int acd_x,

unsigned int acd_y,

unsigned int acd_z

) [static]

Sets status bits indicating which part of the ACD has hits. return A status mask indicating those parts of the ACD which have hits.

Parameters:

acd_x The struck tiles in the ACD X face.

acd_y The struck tiles in the ACD Y face.

acd_z The struck tiles in the ACD Z (top) face.

The ACD is considered to be 3 logical pieces. The top 25 tiles are consider one piece; all the rows of the side faces are another, and only the lower 2 rows of the side faces are the third. A bit is set for each of these three areas which have a hit. Note that these are not mutually exclusive.

static __inline unsigned int cntBits ( unsigned int word ) [static]

Counts the bits in the specified word.

Returns:
The number of bits in the specified word.

Parameters:

word The word to count the bits in

static int compileCfgPrms ( GammaCfgPrms * cfg,

const GFC_DB_prms * prms

) [static]

Compiles/commits the set of user defined parameters into the the configuration block.

Returns:
0 is success, -1 if failure

Parameters:

cfg The destination parameter configuration block

prms The set of user configuration parameters

static __inline int constrainEnergy ( int energy ) [static]

Limits the absolute value of the energy to be < 23 bits.

Returns:
The constrained energy

Parameters:

energy The energy to constrain

This code is a little obscure, but it was the only way I could get the gcc compiler to generate efficient code when the energy is within range, by far the most common case.
This takes advantage of the take that if the energy is within range, the bit positions not within the range are either all 0s or all 1s. This is check in done by shifting those bits off the left end then shifting the result back down. Since the right shift drags the sign bit through, if the energy is within range, the result will be the same.
If the answer is not the same, the code merely has to check whether the energy is positive or negative. That tells one which end of the range the energy has exceeded.

static __inline int evaluateAcd ( const GammaCfgAcd * cfg,

int status,

int energy,

unsigned int acd_x,

unsigned int acd_y,

unsigned int acd_z,

unsigned int acd_cnt

) [static]

Rejects events based on CAL energy and ACD info.

Returns:
The status, possibly augmented with the status indicating no energy in the CAL and a struck tile veto.

Parameters:

cfg The configuration constants for this routine

status The current status of this event.

energy The total energy deposited in the CAL.

acd_x The ACD X side face tiles that are struck.

acd_y The ACD Y side face tiles that are struck.

acd_z The ACD Z TOP face tiles that are struck.

acd_cnt The count of struck ACD tiles.

Events that have no significant energy deposited in the CAL must be completely quiet in the ACD.

static __inline int evaluateAtf ( const GammaCfgAtf * cfg,

int energy,

unsigned int acd_x,

unsigned int acd_y,

unsigned int acd_z,

unsigned int tmsk,

const EBF_dirCtbDsc * contributor

) [static]

Evaluates whether any tower with a track trigger is in coincidence with a shadowing ACD tile.

Returns:
Status bits

Parameters:

cfg The configuration parameters for this routine

energy The energy, in LEUs, of the event..

acd_x The bit mask of struck tiles in the X+/X- side face.

acd_y The bit mask of struck tiles in the Y+/Y- side face.

acd_z The bit mask of struck tiles in the Z top face.

tmsk Bit mask giving the towers with TKR hits (TWR 0 = MSB)

contributor The array of tower contributors.

static __inline int evaluateCal ( const GammaCfgCal * cfg,

int energy,

EBF_dir * dir,

EDR_cal * cal,

const ECR_cal * calCal

) [static]

Evaluates cuts that can be made solely on the basis of the CAL information.

Returns:
Status

Parameters:

cfg The configuration constants for this routine

energy The total energy of the event

dir The event directory

cal The CAL data structure

calCal The CAL calibration constants

This routine makes a simple check based on the energy balance between its layer 0 and the total energy.

The routine depends only on the CAL being minimally unpacked, to the point that the energy in each layer is known.

Note:
At one time a more complicated check on the ratio of the number of logs above a fraction of the total energy to the number total logs was made. This code was removed from active service when the increase in bandwidth allowed more events to taken. This cut was deemed to brutal on the number of gammas in comparison with its rejection power.

static __inline int evaluateTkr ( const GammaCfgTkr * cfg,

int energy,

unsigned int acd_x,

unsigned int acd_y,

unsigned int acd_z,

unsigned int vetoes,

EBF_dir * dir,

EDR_tkr * tkr,

TFC_prjs * prjs

) [static]

Does the projection finding and evaluates all the cuts based on the found projections.

Returns:
Status mask

Parameters:

cfg The tracker cut criteria

energy The energy of the event

acd_x The struck tiles in the planes normal to the X axis

acd_y The struck tiles in the planes normal to the Y axis

acd_z The struck tiles in the planes normal to the Z axis better known as the top plane

vetoes A bit mask of the active veto conditions

dir The event directory

tkr The structure to hold the unpacked TKR data

prjs The structure to hold the found projections

static __inline int evaluateZbottom ( const GammaCfgZbottom * cfg,

int energy,

const EBF_dir * dir

) [static]

Makes a quick test to see if there is energy in the CAL without the possibility of a track pointing into it.

Return values:

0 If there is no energy in the calorimeter or there is a possibility of a track pointing at the energy

GFC_STATUS_M_ZBOTTOM If there is energy in the calorimeter and there is no possibility of a track pointing at it.

Parameters:

cfg The configuration constants for this routine

energy The energy in the calorimeter

dir The directory of event contributors

The check is deliberately crude so that it is extremely cheap. The bit masks of the hit layers for each tower are examined to see if there is even the remotest possibility of extending a track into the calorimeter. Currently 4 or the last 6 planes must have hits in them.

static __inline int gammaFilter ( GFC * gfc,

unsigned int pktBytes,

EBF_pkt * pkt,

EBF_siv siv,

EDS_fwIxb * ixb,

unsigned int vetoes,

GFC_result * result

) [static]

Determines the fate of 1 event.

Returns:
Status mask, if the

< 0, reject
= 0, no decision
> 0, accept

Parameters:

gfc The gamma filter control structure

pktBytes The number of bytes in pkt, includes the packet header

pkt The event data packet

siv The packet's state information vector

ixb The information exchange block

vetoes The list of active vetoes

result The filter result vector

int GFC_cfgCompile ( GFC_cfg * cfg,

const GFC_DB_prms * prms

)

Implements the transformation of the configuration parameters as specified by the user, cfg, into the internal form, ctlCfg.

Return values:

0 Successful

-1 Unrecognized or non-backwardly compatiable user configuration version number.

Parameters:

cfg Filled in with the internal form of the configuration parameters

prms The user form of the configuration parameters

GFC_cfg* GFC_cfgSet ( GFC * gfc,

GFC_cfg * cfg

)

Makes the specified internal representation of the configuration parameters the current active one.

Returns:
Pointer to the current control configuration parameters

Parameters:

gfc The gamma filter control structure

cfg The internal representation of the configuration constants

int GFC_cfgSizeof ( void )

Sizes the gamma filtering configuration as it is used in the actual filtering progam.

Returns:
Returns the size of the gamma filtering configuration control structure

There are two different breeds of the filtering configuration structure. There are two reasons for this. The more familar is the configuration structure that the user fills in. This structure is meant to be convenient for the user, but not for the program. Some of the information in the user structure is transformed into data that the program will find more accessible.

The second reason is that by having a user configuration and an internal configuration, the two can evolve separately. If more parameters are added to the filter, they will find a home in the internal structure. At some time they may be exposed to the user. The correct course of action is to define a new version of the user configuration block. Since the version number is carried along with the configuration constants, the routine transforming the user configuration to its internal representation can evolve and can be made to handle older versions of the user configuration parameters with some degree of grace, at least giving some hope to backward compatibility.

The correct usage model is
ctlCfg = malloc (GFC_cfgSizeof ()); status = GFC_cfgCompile (cfg, usrPrms); GFC_cfgSet (gfc, cfg);

Note:
Because the 'set routine just seeds a pointer to the user configuration, in the control structure. the user is free to swap it out with any other pre-prepared configuration.

int GFC_filter ( GFC * gfc,

unsigned int pktBytes,

EBF_pkt * pkt,

EBF_siv siv,

EDS_fwIxb * ixb,

unsigned int vetoes,

GFC_result * result

)

Determines the fate of 1 event.

Return values:

< 0, rejected

==0,undecided

> 0, accepted

Parameters:

gfc The gamma filter control structure

pktBytes The number of bytes in pkt, includes the packet header

pkt The event data packet

siv The packet's state information vector

ixb The information exchange block

vetoes The active vetoes

result The filter result vector

Overview
This acts as a wrapper of the actual filter. This is were the sampling logic is implemented by the use prescalers. A prescaler is defined by a pair of integers; one giving the current countdown value and the other giving the refresh value. When the countdown value reaches 0, the prescaler is said to expire.

Types of prescaling
There are two kinds of samplings allow.

Pass-thru sampling
Individual veto sampling

Pass-Thru Sampling
Conceptually this is the easiest to understand. When the pass-thru prescaler expires, instead of using the normal veto mask, a 0 is used, effectively causing the filter to evaluate all its cuts but not allowing an cut to veto the event. While easy to understand, the event sample leaked through by this technique will be dominated by events that would normally have been rejected by the very early cuts.

Individual Veto Sampling
This prescaler type allows to ignore the reject decision of each veto bit. While a bit harder to understand than the Pass-Thru Sampling, this technique allows one to tap a predetermined percentage of events failing at each cut. The hope is that one will be a statisitically meaningful sample of events that would have normally failed some of the later cuts in the filter.

unsigned int GFC_fwNeeds ( void )

Returns a bit mask of the EDS_fw needs.

Returns:
A bit mask of the EDS_fw needs

Use
This value should be passed to EDS_fwRegister when registering the filter.

unsigned int GFC_fwObjects ( void )

Returns a bit mask of the EDS_fw objects used by the gamma filter.

Returns:
A bit mask of the EDS_fw needs

Use
This value should be passed to EDS_fwRegister when registering the filter.

int GFC_resultSizeof ( const GFC * gfc )

Returns the size, in bytes, of one result vector.

Return values:

The size, in bytes, of one result vector

Parameters:

gfc The configuration control structure

int GFC_sizeof ( int cnt )

Sizes the gamma filtering control structure.

Returns:
Returns the size of the gamma filtering control structure

Parameters:

cnt Number of configurations to accommodate

static __inline int isVetoed ( unsigned int status,

unsigned int vetoes

) [static]

Checks whether any of the veto bits are up.

Returns:
Non-zero if the status bits contain any of the veto bits.

Parameters:

status The current set of status bits

vetoes The set of veto bits

static __inline int nominateTowers ( const EBF_dir * dir ) [static]

Creates a list of towers with the potential for finding tracks in.

Parameters:

dir The event directory

Returns:
The upper 16 bits contain a mask of the towers with at least a 6 fold coincidence, the lower 16 bits contain a mask of the towers with a 4 fold coincidence. They are exclusive, that is if the tower has a 6 fold coincidence, the 4 fold coincidence is not also set.

static unsigned int tkrFilter ( const GammaCfgTkr * cfg,

int energy,

unsigned int acd_x,

unsigned int acd_y,

unsigned int acd_z,

unsigned int vetoes,

EDR_tkr * tlr,

TFC_prjs * prjs

) [static]

Performs the most computationally intensive portions of the filtering. This involves TKR pattern recognition and matching to the ACD, skirt region and CAL.

Returns:
A summary status bit mask

Parameters:

cfg The tracker configuration and cut criteria

energy The total energy in the CAL

acd_x The bit pattern of struck tiles in the side X+/X- planes

acd_y The bit pattern of struck tiles in the side Y+/Y- planes

acd_z The bit pattern of struck tiles in the top Z plane

vetoes The bit mask of vetoes. If, at any time in this routine a veto bit is added that matches in this word, the routine is aborted.

tlr The unpacked tracker data for the entire LAT

prjs Filled in with the projections for this event

static unsigned int tkrFind ( const GammaCfgTkr * cfg,

int energy,

EBF_dir * dir,

EDR_tkr * tkr,

TFC_prjs * prjs

) [static]

Does the track finding.

Returns:
This routines contribution to the status mask

Parameters:

cfg The tracker configuration constants

energy The energy of the event

dir The event directory

tkr The structure to hold the unpacked TKR data

prjs The structure to hold the found projections

This is used when there is an early accept. Because the EPU side of the GRB processing needs the tracking done, it is done here. A better solution would be for the GRB code to do this for itself. Unfortunately that would take a fairly large effort to make the parameters of the track finding available to the GRB code and to leave enough context around so that it would know to that it must be done. Just not prepared to do it now.

static __inline unsigned int tkrSetStatus ( const GammaCfgTkr * cfg,

int energy,

int prjCnt

) [static]

Completes tracker status, by evaluating the projection count.

Returns:
The contribution of this routine to the status mask

Parameters:

cfg The tracker configuration and cut criteria

energy The total energy in the CAL

prjCnt The count of projections

Generated on Wed Dec 19 03:32:50 2007 by

1.4.4

GFC.c File Reference

Defines

Typedefs

Enumerations

Functions

Variables

Detailed Description

Define Documentation

Enumeration Type Documentation

Function Documentation