#include <StiHitContainer.h>

Inheritance diagram for StiHitContainer:

Public Member Functions
	StiHitContainer (const string &name, const string &description, Factory< StiHit > *factory)

virtual void	add (StiHit *)

virtual unsigned int	size () const

virtual void	reset ()

virtual void	unset ()

virtual void	clear ()

virtual void	sortHits ()

void	setMaxTimes (int nTimes)
	Set max time for all hits.

vector< StiHit * > &	getHits ()
	Get hits selected by the given filter. If no filter is given (i.e. filter==0)

vector< StiHit * > &	getHits (Filter< StiHit > &filter)
	Get hits selected by the given filter. If no filter is given (i.e. filter==0)

vector< StiHit * > &	getHits (StiHit &ref, double dY, double dZ, bool fetchAll=false)

vector< StiHit * > &	getHits (double position, double refAngle, double y, double z, double dY, double dZ, bool fetchAll=false)

vector< StiHit * > &	getHits (StiKalmanTrackNode &, bool fetchAll=false)
	Get hits satisfying the given position and search radius specified with a Kalman track node.

vector< StiHit * > &	getHits (double refangle, double position)

vector< StiHit * > &	getHits (const StiDetector *)
	Get all hits from the specified detector component.

vector< StiHit * >::iterator	hitsBegin (const StiDetector *)

vector< StiHit * >::iterator	hitsEnd (const StiDetector *)

const HitMapToVectorAndEndType &	hits () const

HitMapToVectorAndEndType &	hits ()

StiHit *	getNearestHit (StiHit &ref, double dY, double dZ, bool fetchAll=false)

StiHit *	getNearestHit (double position, double refAngle, double y, double z, double dY, double dZ, bool fetchAll=false)

Factory< StiHit > *	getHitFactory ()
	Get the hit factory.

StiHit *	getHit ()
	Get a hit instance from the factory.

bool	hasKey (double refangle, double position)

bool	hasDetector (const StiDetector *layer)

Public Member Functions inherited from Named
void	setName (const string &newName)
	Set the name of the object.

const string &	getName () const
	Get the name of the object.

bool	isName (const string &aName) const
	Determine whether name equals given name.

Public Member Functions inherited from Described
void	setDescription (const string &description)
	Set the Describe of the object.

const string	getDescription () const
	Get the Describe of the object.

bool	isDescribed () const
	Determine whether Describe is set, i.e object has a Describe.

bool	isDescription (const string &description) const
	Determine whether Describe equals given Describe.

bool	sameDescriptionAs (const Described &described) const
	Determine whether Describe equals that of given object.

Protected Attributes
HitMapToVectorAndEndType::key_type	_key

StiHit	_minPoint

StiHit	_maxPoint

StiHit	_utilityHit

vector< StiHit * >::iterator	_start

vector< StiHit * >::iterator	_stop

vector< StiHit * >	_selectedHits

HitMapToVectorAndEndType	_map

Factory< StiHit > *	_hitFactory

Protected Attributes inherited from Named
string	_name

Protected Attributes inherited from Described
string	_description

Friends
ostream &	operator<< (ostream &, const StiHitContainer &)

Additional Inherited Members
Protected Member Functions inherited from Named
	Named (const string &aName=" ")
	Only derived class are Named.

Protected Member Functions inherited from Described
	Described (const string &aDescribe=" ")
	Only derived class are Described.

Detailed Description

StiHitContainer is exactly that–a container for StiHits! Because of the sheer number of hits in a STAR event, StiHitContainer is designed to provide efficient access to a subset of hits that are within a user specified volume. This is accomplished by mapping between a two dimensional key and an STL container of hits. This mapping will be discussed in further detail below. There is a natural connection between the hits and the detector from which came. However, for implementation purposes, it is convenient to keep these two entities (HitContainer and DetectorContainer) separate, but keep a well defined method of communication between the two. In such a way one can maintain a HitContainer and DetectorContainer that can exist in different representations. That is, one can have a hit container that is well behaved in local coordinates which map very naturally to the detector model as well as a HitContainer that can behave naturally in global coordinates, which do not map naturally to the detector model.

The coordinates of the hits stored are described in StiHit. It should be noted that the ITTF project treats the STAR TPC as if it were 12 sectors, each extending to +-200 cm. That is, we map hits from sectors 13-24 to a coordinate system defined by sectors 1-12. That way we do not need to make any distinction between hits that come from different sides of the TPC central membrane. This is motivated by the fact that the east and west sectors mark a clear distinction in data taking, but that distinction is unimportant in pattern recognition.

First we describe the storage of the hits. StiHitContainer treats the hits from a common detector plane (e.g., TPC padrow 13, sector 12) as a sorted std::vector<StiHit*>. The hits are sorted via the functor StizHitLessThan. This functor has a binary predicate that orders hits in a strict less than ordering based upon global z value (see above). Next, StiHitContainer stores these hit-vectors in a std::map<HitMapKey, std::vector<StiHit*>, MapKeyLessThan >. Class HitMapKey is a simple struct that stores two values: refAngle and position, and MapKeyLessThan is a simple struct that defines a stric less-than ordering for HitMapKey objects. These values are described in StiHit. By specifying a HitMapKey, then, one can achieve extremely efficient retrieval of the hit-vector for a given detector plane.

Next we will discuss the retrieval of hits from the container. As stated above, one can gain access to a hit-vector for a given detector plane by specifying the position and refAngle of a detector (see method hits(double,double). Additionally, one can access the hit-map itself (or at least a const reference to it!) via the method hits(). However, as stated before, StiHitContainer is capable of efficient retrievl of a subset of the hits in an event. This subset can be defined as a subset of the hits from a given detector plane. Perhaps it is easier to elucidate via an example. Suppose one is interested in the hits corresponding to TPC sector 12, padrow 13. Then, this sector/padrow combination can be easily mapped to a position and refAngle. In this detector one can always specify a 'local' coordinate system where any hit is then fully described by two numbers: local y and z (see StiHit for more inforamtion), where y is the distance along the plane (padrow) and z is the global z. Now, suppose one is interested in hits that are within some volume centered at (y0,z0) and bounded by +-deltaD in y and +-deltaZ in z (deltaD is now poorly named–it was meant to represent distance D along a plane). Then, to retrieve the hits from this volume one must call the setDeltaD() and setDeltaZ() methods to establish the bounds. Then one must call one of the setRefPoint() methods. After this, the container has selected the hits within the specified volume, and they can be retreived via the iterator like interface specified by hasMore() and getHit().

Additionally, StiHitContainer has been modified to provide a similar interface to the primary vertices in a STAR event. Access to the verices is via the methods addVertex() and vertices(). Each vertex is mapped to an StiHit object and stored in a hit-vector.

StiHitContainer must be cleared, filled, and sorted for each event. A manual call to sortHits() is necessary to achieve the most efficient container implementation.

Author: M.L. Miller (Yale Software)

Note: StiHitContainer does not own the hits that it stores.

Warning: struct MapKeyLessThan is used for ordering the HitMapKey objects. For a map, this means that this less-than operation is also used to defined equality. Because this involves operations on doubles that are not guarunteed to be exactly identical (the values can come from hits as well as detectors), struct MapKeyLessThan has a built in tolerance that allows for the situation when two HitMapKey objects are actually equal but have very slightly differing values for the doubles they store. These tolerances are currently set in the definition of the struct HitMapKey.

Definition at line 151 of file StiHitContainer.h.

Member Function Documentation

void StiHitContainer::add ( StiHit * hit )

virtual

Null implementation. We provide this virtual function for the situation when StiHitContainer::instance() behaves polymorphically, e.g., when it actually points to a StiRootDrawableDetector object. In that situation, a call to update() will propogate to the most derived class, allowing that class to perform necessary tasks (e.g., append hits to display).

The time complexity of push_back has two components:
1) The correct hit-vector must be retrieved (or inserted if it doesn't exist) from the map. This portion is O(logN) where N is the number of hit-vectors in the map. See the documentation of the hits() method for an estimate of N.
2) The point must be added to the hit-vector. This is guarunteed to be a constant time process, where the constant is determined by the vendor STL implementation.

Warning: A call to push_back() invalidates the sorted state of the container. Thus, once all hits have been added to the container, then one must call sortHits().

Definition at line 89 of file StiHitContainer.cxx.

References StiHit::detector().

void StiHitContainer::clear ( void )

virtual

A call to clear() must call std::vector<StiHit*>::clear() for all vectors stored in the map. Thus a call to clear is of O(N) *M where N is the number of keys in the map (see documenation of hits() for an estimate of N) and M is the time required to clear each vector.

Definition at line 122 of file StiHitContainer.cxx.

Referenced by StiKalmanTrackFinder::clear().

vector< StiHit * > & StiHitContainer::getHits	(	StiHit &	ref,
		double	dY,
		double	dZ,
		bool	fetchAll = `false`
	)

Get hits specified by the filter condition implied by the given position and search radius.

The sub-volume is identified by the following algorithm:
1) Identify the detector plane of intereset via the position and refAngle of the StiHit pointer passed.
2) Find those hits that satisfy abs(hit->z-z_i)<deltaZ. This is accomplished via a call to the STL algorithms lower_bound and upper_bound.
3) Find thos hits that satisfy abs(hit->y-y_i)<deltaD. This can only be accomplished via a linear search over those hits satisfying condition

The time complexity of getHits has several components:
1) The correct hit-vector must be retrieved from the map. This is of O(logN) where N is the number of keys in the map (see documentation of hits() for an estimate of the size of N).
2) The calls to lower_bound and upper_bound are each of O(logM) where M is the number of hits in the sorted vector.
3) The linear search over those hits that satisfy criterion 2. This is of O(P) where P is the number of points that passed criterion 2.
This algorithm is easily modifiable to perform the search in the opposite order (search in y, then z instead of z, then y). See the source code for the necessary conversion actions.

Definition at line 199 of file StiHitContainer.cxx.

References StiHit::detector(), StiHit::isUsed(), StiHit::position(), and StiHit::refangle().

vector< StiHit * > & StiHitContainer::getHits	(	double	position,
		double	refAngle,
		double	y,
		double	z,
		double	dY,
		double	dZ,
		bool	fetchAll = `false`
	)

inline

Get hits satisfying the given position and search radius. Position specified with "position,refAngle,y,z" Search radius specified with dY,dZ

Definition at line 224 of file StiHitContainer.h.

vector< StiHit * > & StiHitContainer::getHits	(	double	refangle,
		double	position
	)

inline

Get all hits from the specified detector component The values of refangle and position are used to fill an existing HitMapToVectorAndEndTypeKey object. This object is used to key the retrieval of a vector of hits associated with the specified position. For more on the definition of refangle and position, please see StiHit documentation.
A call to hits(double,double) corresponds to the retrieval of an object from an STL map based on a key. Such a retrieval is guarunteed to be of O(logN) time complexity, where N is the number of keys in the map. For our practices, N is roughly equal to (TPC) 12*45 + (SVT layer 1) 2*4 + (SVT layer 2) 2*6 + (SVT layer 3) 2*8 + (SSD) 20.

Definition at line 249 of file StiHitContainer.h.

unsigned int StiHitContainer::size ( ) const

virtual

The time complexity of size is of O(logN) where N is the number of keys in the map. For an estimate of N please see the documnation for hits() method.

Definition at line 138 of file StiHitContainer.cxx.

Referenced by StiForwardTrackMaker::MakeInSti().

void StiHitContainer::sortHits ( )

virtual

This function calls the STL sort algorithm for each hit-vector in the map. The StiHit objects are ordered via the struct StizHitLessThan.

Note: A call to push_back(StiHit*) invalidates the sorted state of the container. Thus any number of x calls to push_back(StiHit*) must be followed by a call to sortHits().
The time complexity of sortHits() has two components:
1) The time to access each vector in the map. This is of O(N) where N is the number of keys in the map (see documentation of hits() for an estimate of N).
2) The time to sort an individual vector. This is of O(M logM) where M is the number of hits in stored in the vector.

Definition at line 272 of file StiHitContainer.cxx.

The documentation for this class was generated from the following files:

Sti/StiHitContainer.h
Sti/StiHitContainer.cxx

Public Member Functions

Protected Attributes

Friends

Additional Inherited Members

Detailed Description

Member Function Documentation