GRBP_clusterList.c File Reference

Utility routines to manage the cluster used to initially detect a GRB. More...

#include <GRBP_clusterList.h>
#include <GRBP_cluster.h>
#include <GRBP_photon.h>
#include <GRBP_probCalculate.h>
#include <round.h>
#include <touch.h>
#include <wrap.h>
#include <tmr.h>
#include <dprintf.h>
#include <GRBP_DB/GRBP_DB_clusterList.h>
#include <PBI/FFS.ih>
#include <math.h>
#include <string.h>
#include <stdio.h>

Defines

#define report_timing()

#define hist_timing(_hist, _tbeg, _tend)

#define clear_timing()

#define report_declare(statement)

#define report_newline()

#define report_photon_header(_cut_distance)

#define report_photon_add_0(_list,_cur,_jp,_distance)

#define report_photon_add_replace(_list,_cur,_jp,_nxt) ;

#define report_photon_ignore_retire(_bl,_cur)

#define report_photon_add_last(_pointer,_new_cnt)

#define report_photon_last_probabilities(_log10_pdts,_rsumlog10_pdists,_rsumlog10_pdts)

#define report_photon_probabilities(_new_cnt,_log10_pdist,_log10_pdts,_rsumlog10_pdists,_rsumlog10_pdts)

Functions

static __inline void cluster_reset (GRBP_cluster *cluster, int cnt)

Resets this cluster's stored context.

static __inline int bit_list_sizeof (int cluster_count)

Computes the size, in bytes, for the bit list containing the list of neighbors.

static __inline void bit_list_init (unsigned int *bl, int cluster_count, int cur)

Initializes the bit list by clearing all the bits and setting bit cur. Note that full 32-bits are cleared, so more bits may actually be cleared than specified.

static __inline void bit_list_clear (unsigned int *bl, int beg, int end, int max)

Clears the exclusive bits from beg to end. If beg is greater than end, the list is cleared in a wrap-around sense using max as the wrap point.

static __inline int neighbor_list_sizeof (int cluster_count, int photon_count)

Computes the size, in bytes, for the variable sized portion of a neighbor list containing a maximum cluster_count neighbors. and a cross reference index of maximum photon_count.

static __inline float calc_spatial (const GRBP_probSpatialCtl *ctl, double costhetamax, double log10_costhetamax, double distance)

Wrapper routine to centralize the calculation of the log of the spatial probability.

static __inline float calc_temporal (const GRBP_probTemporalCtl *ctl, double background_rate, double delta_time)

Wrapper routine to centralize the calculation of the log of the temporal probability.

int GRBP_clusterListSizeof (int cluster_count, int photon_count)

Calculates the size, in bytes, to hold a cluster list with cluster_count clusters and a cross-reference array of for photon_count photons.

unsigned char * GRBP_clusterListConstruct (GRBP_clusterList *clusterList, const GRBP_DB_clusterList *cfg, int photonCount, unsigned char *ptr)

Constructs the cluster list according to the specified values.

void GRBP_clusterListAdd (GRBP_clusterList *clusterList, const GRBP_clusterPrms *prms, double time, double energy, double dx, double dy, double dz)

Adds photon to the clusterList using prms as the source of the parameters which control the calculation of the probabilities, both temporal and spatial, as well as the admittance criteria to call a photon a neighbor of another photon.

void GRBP_clusterListReset (GRBP_clusterList *clusterList)

Resets the specified cluster list.

Detailed Description

Utility routines to manage the cluster used to initially detect a GRB.

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


   CVS $Id: GRBP_clusterList.c,v 1.5 2011/03/30 22:11:50 russell Exp $

This contains the heart of the GRB detection code and, in order to avoid N**2 behaviour, it is also the trickiest piece of code. A cluster is formed around each new photon. In addition, all other clusters are updated, retiring the oldest photon and replacing it with the new photon. In order to support multiple windows, the detection variable, the total probability of a cluster, is keep as a running sum. By doing this, the probability of a cluster of any size, up to a configurable maximum size, can be computed simple by subtracting the values associated with oldest and newest photon.

The maximum size of the cluster affects not only the maximum depth one can look, but also has a large impact on the number of CPU cycles used. This is because every new photon must be used to establish its own cluster (proportional to the maximum depth) and to update each existing cluster (again proportional to the maximum depth.) It is expected that values up to around 100 can be supported if the rate of new photons is around 200Hz.

Function Documentation

static __inline void bit_list_clear	(	unsigned int *	bl,
		int	beg,
		int	end,
		int	max
	)			`[static]`

Clears the exclusive bits from beg to end. If beg is greater than end, the list is cleared in a wrap-around sense using max as the wrap point.

Parameters:

	bl	The target bit list
	beg	The bit after this will be the first bit cleared
	end	The bit before this will be the last bit cleared
	max	The size of the circular bit list

References wrap_hi().

Referenced by GRBP_clusterListAdd().

static __inline void bit_list_init	(	unsigned int *	bl,
		int	cluster_count,
		int	cur
	)			`[static]`

Initializes the bit list by clearing all the bits and setting bit cur. Note that full 32-bits are cleared, so more bits may actually be cleared than specified.

Parameters:

	bl	The bit list to initialize
	cluster_count	The number of bits to clear
	cur	The bit to set

Referenced by GRBP_clusterListAdd().

static __inline int bit_list_sizeof ( int cluster_count ) [static]

Computes the size, in bytes, for the bit list containing the list of neighbors.

Returns:: The size, in bytes, for the bit list containing the list of neighbors

Parameters:

cluster_count

The number of neighbors

Referenced by GRBP_clusterListConstruct(), and neighbor_list_sizeof().

static __inline float calc_spatial	(	const GRBP_probSpatialCtl *	ctl,
		double	costhetamax,
		double	log10_costhetamax,
		double	distance
	)			`[static]`

Wrapper routine to centralize the calculation of the log of the spatial probability.

Returns:: The log, base 10, of the spatial probability

Parameters:

	ctl	The control handle used for the lookup method
	costhetamax	The maximum cos (theta) angle, used to normalize the acceptance
	log10_costhetamax	The log, base 10, of costhetamax
	distance	The angular separation distance

This function encapsulates one of two methods of calculation. A lookup table method and one that uses the transcendentals (log and exp). The lookup method is faster by a factor of 2-4. Encapsulating these functions here made it easier to study the timing differences

References GRBP__probSpatialCalculate().

Referenced by GRBP_clusterListAdd().

static __inline float calc_temporal	(	const GRBP_probTemporalCtl *	ctl,
		double	background_rate,
		double	delta_time
	)			`[static]`

Wrapper routine to centralize the calculation of the log of the temporal probability.

Returns:: The log, base 10, of the temporal probability

Parameters:

	ctl	The control handle used for the lookup method
	background_rate	The background rate in Hertz.
	delta_time	The time difference between this event and the previous event.

This function encapsulates one of two methods of calculation. A lookup table method and one that uses the transcendentals (log and exp). The lookup method is faster by a factor of 2-4. Encapsulating these functions here made it easier to study the timing differences

References GRBP__probTemporalCalculate().

Referenced by GRBP_clusterListAdd().

static __inline void cluster_reset	(	GRBP_cluster *	cluster,
		int	cnt
	)			`[static]`

Resets this cluster's stored context.

Parameters:

	cluster	The cluster context to reset
	cnt	The neighbor count

Referenced by GRBP_clusterListReset().

void GRBP_clusterListAdd	(	GRBP_clusterList *	clusterList,
		const GRBP_clusterPrms *	prms,
		double	time,
		double	energy,
		double	dx,
		double	dy,
		double	dz
	)

Adds photon to the clusterList using prms as the source of the parameters which control the calculation of the probabilities, both temporal and spatial, as well as the admittance criteria to call a photon a neighbor of another photon.

Parameters:

	clusterList	The target cluster list.
	prms	The parameters controlling the promotion of a photon into a cluster.
	time	The time associated with the photon being added
	energy	The energy, in Mev, of the photon
	dx	The x direction cosine
	dy	The y direction cosine
	dz	The y direction cosine

References _GRBP_probabilityPrms::background_rate, _GRBP_clusterList::beg, bit_list_clear(), bit_list_init(), _GRBP_neighborList::bl, calc_spatial(), calc_temporal(), _GRBP_clusterList::clusters, _GRBP_clusterUpdateList::cnt, _GRBP_clusterList::cnt, _GRBP_probabilityPrms::costhetamax, _GRBP_clusterPrms::costwosigdist, _GRBP_clusterList::cur, _GRBP_neighborList::info, _GRBP_neighborList::last, _GRBP_clusterUpdateList::list, _GRBP_probabilityPrms::log10_costhetamax, _GRBP_clusterList::max, _GRBP_clusterPrms::probability, _GRBP_probabilityPrms::psc, _GRBP_probabilityPrms::ptc, _GRBP_neighborList::rsumlog10pdists, _GRBP_neighborList::rsumlog10pdts, _GRBP_neighborInfo::sum_log10_pdists, _GRBP_neighborInfo::sum_log10_pdts, _GRBP_neighborList::time, _GRBP_clusterList::upd, and wrap_hi().

Referenced by GRBP_cacheAdd().

unsigned char* GRBP_clusterListConstruct	(	GRBP_clusterList *	clusterList,
		const GRBP_DB_clusterList *	cfg,
		int	photonCount,
		unsigned char *	ptr
	)

Constructs the cluster list according to the specified values.

Returns:: A pointer to the next available memory location

Parameters:

	clusterList	The cluster list to construct
	cfg	The cluster list configuration
	photonCount	The number of photons on the master photon list. This is used to for a cross-reference list between a photon and a cluster member
	ptr	Pointer to the memory to carve the dynamically allocated arrays from.

References bit_list_sizeof(), _GRBP_clusterList::clusters, GRBP_clusterListReset(), _GRBP_clusterUpdateList::list, _GRBP_clusterList::max, and _GRBP_clusterList::upd.

Referenced by GRBP_cacheConstruct().

void GRBP_clusterListReset ( GRBP_clusterList * clusterList )

Resets the specified cluster list.

Parameters:

clusterList

The cluster list to reset

References _GRBP_clusterList::beg, cluster_reset(), _GRBP_clusterList::clusters, _GRBP_clusterList::cnt, _GRBP_clusterList::cur, and _GRBP_clusterList::max.

Referenced by GRBP_cacheReset(), and GRBP_clusterListConstruct().

int GRBP_clusterListSizeof	(	int	cluster_count,
		int	photon_count
	)

Calculates the size, in bytes, to hold a cluster list with cluster_count clusters and a cross-reference array of for photon_count photons.

Returns:: The number of bytes to hold the specified cluster list.

Parameters:

	cluster_count	The number of clusters and, implicitly, the size of each cluster (i.e. the number of neighbors), of the cluster list
	photon_count	The number of photons on the master photon list. This is used to for a cross-reference list between a photon and a cluster member

References neighbor_list_sizeof().

Referenced by GRBP_cacheSizeof().

static __inline int neighbor_list_sizeof	(	int	cluster_count,
		int	photon_count
	)			`[static]`

Computes the size, in bytes, for the variable sized portion of a neighbor list containing a maximum cluster_count neighbors. and a cross reference index of maximum photon_count.

Returns:: The size, in bytes, for the variable sized portion of a neighbor list containing a maximum cluseter_count neighbors and a cross reference indexing list of maximum photon_count

Parameters:

	cluster_count	The number of neighbors
	photon_count	The maximum cross-reference index

References bit_list_sizeof().

Referenced by GRBP_clusterListSizeof().


Defines
#define	report_timing()
#define	hist_timing(_hist, _tbeg, _tend)
#define	clear_timing()
#define	report_declare(statement)
#define	report_newline()
#define	report_photon_header(_cut_distance)
#define	report_photon_add_0(_list,_cur,_jp,_distance)
#define	report_photon_add_replace(_list,_cur,_jp,_nxt) ;
#define	report_photon_ignore_retire(_bl,_cur)
#define	report_photon_add_last(_pointer,_new_cnt)
#define	report_photon_last_probabilities(_log10_pdts,_rsumlog10_pdists,_rsumlog10_pdts)
#define	report_photon_probabilities(_new_cnt,_log10_pdist,_log10_pdts,_rsumlog10_pdists,_rsumlog10_pdts)
Functions
static __inline void	cluster_reset (GRBP_cluster *cluster, int cnt)
	Resets this cluster's stored context.
static __inline int	bit_list_sizeof (int cluster_count)
	Computes the size, in bytes, for the bit list containing the list of neighbors.
static __inline void	bit_list_init (unsigned int *bl, int cluster_count, int cur)
	Initializes the bit list by clearing all the bits and setting bit cur. Note that full 32-bits are cleared, so more bits may actually be cleared than specified.
static __inline void	bit_list_clear (unsigned int *bl, int beg, int end, int max)
	Clears the exclusive bits from beg to end. If beg is greater than end, the list is cleared in a wrap-around sense using max as the wrap point.
static __inline int	neighbor_list_sizeof (int cluster_count, int photon_count)
	Computes the size, in bytes, for the variable sized portion of a neighbor list containing a maximum cluster_count neighbors. and a cross reference index of maximum photon_count.
static __inline float	calc_spatial (const GRBP_probSpatialCtl *ctl, double costhetamax, double log10_costhetamax, double distance)
	Wrapper routine to centralize the calculation of the log of the spatial probability.
static __inline float	calc_temporal (const GRBP_probTemporalCtl *ctl, double background_rate, double delta_time)
	Wrapper routine to centralize the calculation of the log of the temporal probability.
int	GRBP_clusterListSizeof (int cluster_count, int photon_count)
	Calculates the size, in bytes, to hold a cluster list with cluster_count clusters and a cross-reference array of for photon_count photons.
unsigned char *	GRBP_clusterListConstruct (GRBP_clusterList clusterList, const GRBP_DB_clusterList cfg, int photonCount, unsigned char *ptr)
	Constructs the cluster list according to the specified values.
void	GRBP_clusterListAdd (GRBP_clusterList clusterList, const GRBP_clusterPrms prms, double time, double energy, double dx, double dy, double dz)
	Adds photon to the clusterList using prms as the source of the parameters which control the calculation of the probabilities, both temporal and spatial, as well as the admittance criteria to call a photon a neighbor of another photon.
void	GRBP_clusterListReset (GRBP_clusterList *clusterList)
	Resets the specified cluster list.