GRBP_locate.c File Reference

Computes the best guess at GRB location for a set of gammas. More...

#include <GRBP_locate.h>
#include <GRBP_location.h>
#include <GRBP_gammaList.h>
#include <GRBP_gamma.h>
#include <GRBP_math.h>
#include <wrap.h>
#include <tmr.h>
#include <touch.h>
#include <PBI/Attribute.h>
#include <grbp_gamma_report.h>
#include <dprintf.h>

Classes

struct _Sdata

Collects the static data used by these routines into one place. More...

Defines

#define DO_CONVERGENCE

#define NULL   ((void *)(0))

#define CUTOFF_DISTANCE   0.99984769516

Defines a cutoff distance corresponding to 1 degree. All gammas closer than this to the seed location will be treated as if they were at the 1 degree.

#define CUTOFF_WEIGHT2   ((180./M_PI) * (180./M_PI))

Defines the weight (squared) corresponding to the cutoff distance.

#define ITERATIONS   10

Defines the maximum number of iterations when doing the location.

#define report_location(_dx, _dy, _dz, _w2_sum)

#define report_new_line()

Typedefs

typedef struct _Sdata Sdata_t

Typedef for struct _Sdata.

Functions

static __inline int seed_find (GRBP_gammaAux *gammas, int beg, int end, int max)

Find the gamma with the highest energy.

static __inline double dot_product (double dx, double dy, double dz, double dx0, double dy0, double dz0)

Computes the dot product between the specified gamma and the vector as defined by the direction cosines.

static __inline double get_weight2 (double dot, double cutoff_distance, float cutoff_weight2, double one, float c0, float c1, float c2)

Computes the distance depend weight squared.

static __inline void complete (GRBP_location *loc, double dx0, double dy0, double dz0, double w2_sum)

Completes the localization process by committing the answer to the GRBP_location structure.

static __inline double normalize (double x, double y, double z, double one)

Computes, but does not apply, the normalization for the specified unnormalized input vector. The user must multiply each of dx, dy and dz by this factor.

static __inline int converged (double tolerance, double one, double dxn, double dyn, double dzn, double dx0, double dy0, double dz0)

Checks if the 1 - dot product of the two sets of direction cosines is smaller than the convergence tolerance.

void estimate (double loc[3], const GRBP_gamma *gammas, int beg, int end, int max, double zero, double one)

Makes an estimate of the position based on the average of the input gammas.

void GRBP_locateAll (GRBP_location *loc, const GRBP_location *guess, GRBP_gammaList *list)

Calculates the position using only those photons in the energy selected list.

void GRBP_locateSelected (GRBP_location *loc, const GRBP_location *guess, GRBP_gamma *gammas)

Calculates the position using only those photons in the energy selected list.

Variables

const Sdata_t Sdata

This is ugly, but moving the constants to a static data structure like this improves the performance.

Detailed Description

Computes the best guess at GRB location for a set of gammas.

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


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

Function Documentation

static __inline void complete	(	GRBP_location *	loc,
		double	dx0,
		double	dy0,
		double	dz0,
		double	w2_sum
	)			`[static]`

Completes the localization process by committing the answer to the GRBP_location structure.

Parameters:

	loc	The location structure to complete
	dx0	The normalized x direction cosine
	dy0	The normalized y direction cosine
	dz0	The normalized z direction cosine
	w2_sum	The sum of the squares of the weights

References _GRBP_location::dx0, _GRBP_location::dy0, _GRBP_location::dz0, and _GRBP_location::w2_sum.

Referenced by GRBP_locateAll(), and GRBP_locateSelected().

static __inline int converged	(	double	tolerance,
		double	one,
		double	dxn,
		double	dyn,
		double	dzn,
		double	dx0,
		double	dy0,
		double	dz0
	)			`[static]`

Checks if the 1 - dot product of the two sets of direction cosines is smaller than the convergence tolerance.

Returns:: Non-zero if true, Zero if false

Parameters:

	tolerance	The convergence criteria
	one	The value 1.0
	dxn	The 'new' x direction cosine
	dyn	The 'new' y direction cosine
	dzn	The 'new' z direction cosine
	dx0	The 'old' x direction cosine
	dy0	The 'old' y direction cosine
	dz0	The 'old' z direction cosine

This function is selected by defining the compile-time symbol DO_CONVERGENCE. If not selected, the location routines always run through the maximum number of iterations.

References dot_product().

Referenced by GRBP_locateAll(), and GRBP_locateSelected().

static __inline double dot_product	(	double	dx,
		double	dy,
		double	dz,
		double	dx0,
		double	dy0,
		double	dz0
	)			`[static]`

Computes the dot product between the specified gamma and the vector as defined by the direction cosines.

Returns:: The dot product

Parameters:

	dx	The gamma x direction cosine
	dy	The gamma y direction cosine
	dz	The gamma z direction cosine
	dx0	The seed x direction cosine
	dy0	The seed y direction cosine
	dz0	The seed z direction cosine

Referenced by converged(), GRBP_locateAll(), and GRBP_locateSelected().

static void estimate	(	double	loc[3],
		const GRBP_gamma *	gammas,
		int	beg,
		int	end,
		int	max,
		double	zero,
		double	one
	)

Makes an estimate of the position based on the average of the input gammas.

Parameters:

	loc	Returned as the direction cosines of the location
	gammas	The list of gammas
	beg	The first gamma in the list
	end	The last gamma in the list
	max	The list's wrap point
	zero	The floating point value for 0.0
	one	The floating point value for 1.0

References _GRBP_gamma::dx, _GRBP_gamma::dy, _GRBP_gamma::dz, and normalize().

Referenced by GRBP_locateAll().

static __inline double get_weight2	(	double	dot,
		double	cutoff_distance,
		float	cutoff_weight2,
		double	one,
		float	c0,
		float	c1,
		float	c2
	)			`[static]`

Computes the distance depend weight squared.

Returns:: The distance depend weight squared

Parameters:

	dot	The dot product, effective cos (opening_angle)
	cutoff_distance	The cutoff distance. Dot products larger than this will be given cutoff_weight2
	cutoff_weight2	The weight squared to assign to gammas that have a dot product larger than cutoff_distance.
	one	The floating point value 1
	c0	Expansion coefficient 0
	c1	Expansion coefficient 1
	c2	Expansion coefficient 2

The basic calculation to be performed is trivial 1/(acos(dot)**2) with a cutoff that prohibits the weight from getting too large. The issue is the performance of the acos. Since the range of the angle is well contained, between about 1-17 degrees, the quantity 1 - dot is constrained to be between 1.5x10-4 and 4.4x10-2. This suggests using an expansion in this variable.

      1/(acos(dot)**2) = x/2 - 1/12 - x/120 - 31x/15120 ...

The first term dominates, so the relevant quantity to measure the error is roughly the ratio of the last term to the first term

      last/first = 31x**2/15120

This is largest when x is the largest, i.e. 4.4x10-2, or about 4.x10-6. Therefore, to 5-6 significant decimal digits, the first three terms are sufficient. Use of this expansion is > 5 times faster than calling the acos. The calculation is dominated by the floating point divide. Other than the leading term the remaining terms are essentially 1-3 cycle operations (multiply and add type instructions).

A further optimization is to demand that the coefficients by extracted and passed into this routine. Modular coding would dictate that these coefficients be contained in this routine. However, the generated code insists on constantly fetching these values out of memory. By making the coefficients arguments to the routine, the generated PPC code for the expansion is the best that can be gotten.

        float x = (one - dot);
   8:   fc 04 08 28     fsub    f0,f4,f1     ;  1  1 - dot
   c:   fc 00 00 18     frsp    f0,f0        ;  1  round to single precision

        w2 = c0 / x +  c1  + x * (c2);
  10:   ed a5 00 24     fdivs   f13,f5,f0    ; 17 c0/x
  14:   ed ad 30 2a     fadds   f13,f13,f6   ;  1   + c1
  18:   ec 60 69 fa     fmadds  f3,f0,f7,f13 ;  1      + x * c2
                                             ; 21 cycles

Referenced by GRBP_locateAll(), and GRBP_locateSelected().

void GRBP_locateAll	(	GRBP_location *	loc,
		const GRBP_location *	guess,
		GRBP_gammaList *	list
	)

Calculates the position using only those photons in the energy selected list.

Parameters:

	loc	The data structure to receive the calculated location
	guess	The location to use as a guess for the first iteration
	list	The circular list of gammas to use

References _GRBP_gammaList::beg, _Sdata::c, complete(), converged(), _Sdata::cutoff_distance, _Sdata::cutoff_weight2, dot_product(), _GRBP_gamma::dx, _GRBP_location::dx0, _GRBP_gamma::dy, _GRBP_location::dy0, _GRBP_gamma::dz, _GRBP_location::dz0, _GRBP_gammaList::end, estimate(), _GRBP_gammaList::gammas, get_weight2(), ITERATIONS, _GRBP_gammaList::max, normalize(), _Sdata::one, _Sdata::tolerance, and _Sdata::zero.

Referenced by GRBP__locate(), and GRBP_windowTier1LatUpdate().

void GRBP_locateSelected	(	GRBP_location *	loc,
		const GRBP_location *	guess,
		GRBP_gamma *	gammas
	)

Calculates the position using only those photons in the energy selected list.

Parameters:

	loc	The data structure to receive the calculated location
	guess	The location to use as a guess for the first iteration
	gammas	The first in the linked list of gammas used to calculate the position.

References _Sdata::c, complete(), converged(), _Sdata::cutoff_distance, _Sdata::cutoff_weight2, dot_product(), _GRBP_gamma::dx, _GRBP_location::dx0, _GRBP_gamma::dy, _GRBP_location::dy0, _GRBP_gamma::dz, _GRBP_location::dz0, get_weight2(), ITERATIONS, normalize(), _GRBP_gamma::nxt, _Sdata::one, _Sdata::tolerance, and _Sdata::zero.

Referenced by GRBP__locate().

static __inline double normalize	(	double	x,
		double	y,
		double	z,
		double	one
	)			`[static]`

Computes, but does not apply, the normalization for the specified unnormalized input vector. The user must multiply each of dx, dy and dz by this factor.

Returns:: The normalization factor

Parameters:

	x	The x component of the vector
	y	The y component of the vector
	z	The z component of the vector
	one	The floating point value 1.0

Referenced by estimate(), GRBP_locateAll(), and GRBP_locateSelected().

static __inline int seed_find	(	GRBP_gammaAux *	gammas,
		int	beg,
		int	end,
		int	max
	)			`[static]`

Find the gamma with the highest energy.

Returns:: Index of the gamma with the highest energy

Parameters:

	gammas	The list of gammas to search
	beg	The index of the first gamma
	end	The index of the last gamma
	max	The size of list (this does the wrap-around of the circular buffer

Warning:: This method of estimating the position has been replace by one of averaging the unweighted direction cosines,

See also:: estimate.

References _GRBP_gammaAux::energy.

Variable Documentation

const Sdata

Initial value:

 
{
    0.0,
    1.0, 
    1.0e-9,
    CUTOFF_DISTANCE,
    CUTOFF_WEIGHT2,
    {1.0/2.0, -1.0/12.0, -1.0/120.0}
}

This is ugly, but moving the constants to a static data structure like this improves the performance.

To get convergence at the level of an arc minute need at tolerance of ~ 1.0 - cos (1 arcmin) = 4.23e-8, will pick 1e-9.


Classes
struct	_Sdata
	Collects the static data used by these routines into one place. More...
Defines
#define	DO_CONVERGENCE
#define	NULL ((void *)(0))
#define	CUTOFF_DISTANCE 0.99984769516
	Defines a cutoff distance corresponding to 1 degree. All gammas closer than this to the seed location will be treated as if they were at the 1 degree.
#define	CUTOFF_WEIGHT2 ((180./M_PI) * (180./M_PI))
	Defines the weight (squared) corresponding to the cutoff distance.
#define	ITERATIONS 10
	Defines the maximum number of iterations when doing the location.
#define	report_location(_dx, _dy, _dz, _w2_sum)
#define	report_new_line()
Typedefs
typedef struct _Sdata	Sdata_t
	Typedef for struct _Sdata.
Functions
static __inline int	seed_find (GRBP_gammaAux *gammas, int beg, int end, int max)
	Find the gamma with the highest energy.
static __inline double	dot_product (double dx, double dy, double dz, double dx0, double dy0, double dz0)
	Computes the dot product between the specified gamma and the vector as defined by the direction cosines.
static __inline double	get_weight2 (double dot, double cutoff_distance, float cutoff_weight2, double one, float c0, float c1, float c2)
	Computes the distance depend weight squared.
static __inline void	complete (GRBP_location *loc, double dx0, double dy0, double dz0, double w2_sum)
	Completes the localization process by committing the answer to the GRBP_location structure.
static __inline double	normalize (double x, double y, double z, double one)
	Computes, but does not apply, the normalization for the specified unnormalized input vector. The user must multiply each of dx, dy and dz by this factor.
static __inline int	converged (double tolerance, double one, double dxn, double dyn, double dzn, double dx0, double dy0, double dz0)
	Checks if the 1 - dot product of the two sets of direction cosines is smaller than the convergence tolerance.
void	estimate (double loc[3], const GRBP_gamma *gammas, int beg, int end, int max, double zero, double one)
	Makes an estimate of the position based on the average of the input gammas.
void	GRBP_locateAll (GRBP_location loc, const GRBP_location guess, GRBP_gammaList *list)
	Calculates the position using only those photons in the energy selected list.
void	GRBP_locateSelected (GRBP_location loc, const GRBP_location guess, GRBP_gamma *gammas)
	Calculates the position using only those photons in the energy selected list.
Variables
const Sdata_t	Sdata
	This is ugly, but moving the constants to a static data structure like this improves the performance.