IceHive C++ API Reference¶
-
class AbsHit¶
- #include <HitSorting.h>
A abstract description of a hit This type needs to be as small as possible so that copies are cheap.
Subclassed by HitSorting::Hit
Public Functions
-
OMKeyHash::SimpleIndex GetDOMIndex() const¶
simply return the DOMindex of this hit
-
double GetTime() const¶
simply return the Time of this hit
Protected Functions
-
AbsHit(OMKeyHash::SimpleIndex domIndex, const double time)¶
Constructor
- Parameters:
domIndex – The index of the DOM where the hit occurred
time – The time of the hit
Private Members
-
OMKeyHash::SimpleIndex domIndex¶
The index of the DOM on which this hit occurred, within the set of hit DOMs of the current event.
-
double time¶
The actual time of the hit.
-
OMKeyHash::SimpleIndex GetDOMIndex() const¶
-
template<typename base, class internal>
class AsymmetricIndexMatrix : public IceHiveHelpers::IndexMatrix<base, internal>¶ - #include <IceHiveHelpers.h>
dynamic symmetric BiIndexed map; input is anything [0..x][0..x]; all fields are filled NOTE beware, there is no explicit check if you leave the indexable range, that is your responsibile
Public Functions
-
inline AsymmetricIndexMatrix(const int biSize)¶
allocate enough memory
- Parameters:
biSize – that is the range of the biIndex
Private Functions
-
inline virtual unsigned int BiIndex_To_UniIndex(const unsigned int indexA, const unsigned int indexB) const¶
convert from Bi-indexed representation to a linear index
-
inline AsymmetricIndexMatrix(const int biSize)¶
-
class AsymmetricIndexMatrix_Double : public IceHiveHelpers::AsymmetricIndexMatrix<double, std::vector<double>>¶
- #include <IceHiveHelpers.h>
specialized class for Double
Public Functions
-
inline AsymmetricIndexMatrix_Double(const unsigned int biSize)¶
-
inline AsymmetricIndexMatrix_Double(const unsigned int biSize)¶
-
struct CausalCluster¶
- #include <HiveSplitter.h>
An object which keeps track of a group of hits which are (mostly) causally connected to each other, and the number of distinct DOMs on which those hits occurred.
Public Functions
-
CausalCluster()¶
constructor
-
void insert(const HitSorting::Hit &h, const unsigned int multiplicity)¶
Add a new hit to the cluster.
- Parameters:
h – The hit to add
multiplicity – The threshold for a group of hits within the time window to form a subevent
-
double earliestTime() const¶
Finds the time of the earliest hit in this cluster.
- Returns:
The earliest hit time or infinity if the cluster is empty
-
void takeComplete(const CausalCluster &c)¶
Take all hits in other’s complete list and merge them into this cluster’s complete list.
- Parameters:
c – the cluster to be merged
-
inline bool isActive()¶
is this cluster still active; thus can there still be found connected hits?
Public Members
-
std::list<HitSorting::Hit> hits¶
The ordered queue of hits within this cluster which are still within the time window of the current time.
-
std::map<unsigned int, unsigned int> doms¶
Keeps track of the number of hits on each of the doms present in this cluster, keys are dom indices.
-
HitSorting::HitSet complete¶
The hits which have formed a group surpassing the multiplicity and are now outside the time window.
-
HitSorting::Hit endHit¶
The most recent hit contributing to meeting the multiplicity condition.
-
bool multiplicityMet¶
!!! Whether the multiplicity condition is met
-
CausalCluster()¶
-
class DOMHoneyComb
- #include <Hive-lib.h>
A class that stores a central string and its surrounding rings; NOTE Ring 0 is the center-string.
Public Functions
-
StringNbr GetCenter() const
get the central string
-
inline unsigned int GetNRings() const
get the number of implemented Rings
-
Ring GetRing(const unsigned int ringnbr) const¶
get the strings of the ring [ringnbr]
- Parameters:
ringnbr – number of the ring that should be returned
- Returns:
the strings contained on [ringnbr]
-
void AddRing(const unsigned int ringnbr, const Ring &ring)¶
Adds the strings of ring [ringnbr] to honey
- Parameters:
ringnbr – number of the ring to set
ring – strings contained on that ring
-
void SetRing(const unsigned int ringnbr, const Ring &ring)¶
erases the previous ring [ringnbr], set the new strings of ring
- Parameters:
ringnbr – number of the ring to set
ring – strings contained on that ring
-
DOMHoneyComb()
Constructor with NO argument.
-
DOMHoneyComb(const StringNbr center, const Ring &ring1)¶
Constructor with 1 ring.
- Parameters:
center – the center of the HoneyComb
ring1 – strings that belong to the first ring
-
DOMHoneyComb(const StringNbr center, const Ring &ring1, const Ring &ring2)¶
Constructor with 2 rings.
- Parameters:
center – the center of the HoneyComb
ring1 – strings that belong to the first ring
ring2 – strings that belong to the second ring
-
DOMHoneyComb(const StringNbr center, std::vector<Ring> &rings)¶
constructor with arbitrary number of rings
- Parameters:
center – the center of the HoneyComb
rings – vector of rings and their contained strings
-
void AddStringToRing(const StringNbr center, const unsigned int ringnbr, const StringNbr string)¶
Add the single string [string] to the honeycomb at central string [center] on ring [ringnbr].
- Parameters:
center – the central string
ringnbr – the ring on which to add the string to
string – that should be added
-
StringNbr GetCenter() const
-
class Hit : public HitSorting::AbsHit
- #include <HitSorting.h>
A description of a Hit, which can be traced to a HitObject of arbitray type.
Public Functions
-
Hit()¶
blank constructor [[DEPRICATED]]; sometimes need a blank constructor for comparisions/replacements
-
template<class Response>
const HitObject<Response> &GetAssociatedHitObject() const¶ get the associated HitObject to this hit
-
template<class Response>
const HitSorting::HitObject<Response> &GetAssociatedHitObject() const¶
Private Functions
Private Members
Friends
- friend class HitObject
-
Hit()¶
-
template<class Response>
class HitObject¶ - #include <HitSorting.h>
the representation of a Hit as a pair of a OMKet and a (detector-)response-object like a pulse/lunch/hit/whatever this class is templated and needs exzplicitly the the specialization of the GetTime()-routine
Public Functions
-
inline HitObject(OMKey omkey, Response response_obj)¶
constructor
- Parameters:
omkey – a OMKey this response was registered on
response_obj – the Response object
-
inline double GetTime() const¶
get the characteristic time-stamp of this pulse/launch/hit/whatever;
-
inline HitObject(OMKey omkey, Response response_obj)¶
-
struct Hive
- #include <Hive-lib.h>
complex type that holds all magic information associated DOMHoneyCombRegister use this type when working with different DOMHoneyCombRegisters, where the scaling of the rings are different
Public Functions
-
Hive(const unsigned int scaleFactor, const DOMHoneyCombRegister &combs, unsigned int max_rings)¶
constructor
Public Members
-
unsigned int scaleFactor_
relative scaling factor (in comparison to regular IceCube string spacings)
-
unsigned int max_rings_
the maximum amount of registered rings
-
DOMHoneyCombRegister combs_
the Register holding all information
-
Hive(const unsigned int scaleFactor, const DOMHoneyCombRegister &combs, unsigned int max_rings)¶
-
class HiveCleaning¶
- #include <HiveCleaning.h>
The main cleaning class.
Public Functions
-
HiveCleaning(const HiveCleaning_ParameterSet ¶ms = HiveCleaning_ParameterSet())¶
Constructor from a ParameterSet.
-
void Configure(const HiveCleaning_ParameterSet ¶ms)¶
(Re)configure the module
-
void CheckParams_n_Setup()¶
Probe the feasibility of parameter ranges and do setup work.
-
void BuildLookUpTables(const I3Geometry &geo)¶
Build the VicinityMap from the parameters keep things simple and call this function from Geometry-frame.
- Parameters:
geo – pointer to the I3Geometry from Geometry frame
-
HitSorting::HitSeries Clean(const HitSorting::HitSeries &hits)¶
ACTION Perform the Splitting:
Get the Pulse-Series from the Frame and read all Hits into a time ordered Hit-Series.
Than Call the Main-Alorithm and iterate over all thee Hits and try to form clusters of Hits and add Hits to them, discard them or form a new cluster.
When Hit-Series is exhausted and Clusters/Subevents have been found write them to the datastream (either as seperate frames or into the same frame).
Save the Splitcount also if that is wanted,
Push everyting back into the pipeline.
Clean-up the memory.- Parameters:
hits – the hits to process on
- Returns:
a EventStartStops
Protected Types
-
typedef std::map<unsigned int, Limits::RingLimits> RingLimitPairsMap¶
even better accessable limit parameter format for a whole group of parameters
Protected Attributes
-
HiveCleaning_ParameterSet params_¶
A parameter-set to run on.
-
RingLimitPairsMap RingVicinityPairsMap_¶
The RingLimits for displacement.
Private Functions
- SET_LOGGER ("HiveCleaning")
Private Members
-
HiveGeometry hivegeo_¶
Geometry and Topology of the Hive that is describing the detector.
-
IceHiveHelpers::SymmetricIndexMatrix_Bool vicinityMap_¶
look-up table for dom-distances: if value==NAN, these DOMS should not be reconnected
-
HiveCleaning(const HiveCleaning_ParameterSet ¶ms = HiveCleaning_ParameterSet())¶
-
struct HiveCleaning_ParameterSet¶
- #include <HiveCleaning.h>
A set of parameters that steer HiveCleaning.
Public Functions
-
HiveCleaning_ParameterSet()¶
constructor
Public Members
-
int multiplicity¶
PARAM: A required Multiplicity to the number of surrounding hit DOMs.
-
double timeStaticMinus¶
PARAM: Maximum negative time within DOMs in vicinity are still considered.
-
double timeStaticPlus¶
PARAM: Maximum positive time within DOMs in vicinity are still considered.
-
bool selfconnect¶
PARAM: Allow for DOMs to self-connect.
-
Limits::RingLimits SingleDenseRingVicinityPairs¶
PARAM: limits for the single, double and tripple dense vicinity connection.
-
Limits::RingLimits DoubleDenseRingVicinityPairs¶
-
Limits::RingLimits TripleDenseRingVicinityPairs¶
-
HiveCleaning_ParameterSet()¶
-
struct HiveGeometry¶
- #include <Hive-lib.h>
-
class HiveSplitter
- #include <HiveSplitter.h>
The main splitter module.
Public Functions
-
HiveSplitter(const HiveSplitter_ParameterSet ¶ms = HiveSplitter_ParameterSet())
Constructor from a ParameterSet.
-
void Configure(const HiveSplitter_ParameterSet ¶ms)
(Re)configure the module
-
void CheckParams_n_Setup()
Probe the feasibility of parameter ranges and do setup work.
-
void BuildLookUpTables(const I3Geometry &geo)¶
Build the DistanceMap and VicinityMap from the parameters keep things simple and call this function from Geometry-frame.
- Parameters:
geo – pointer to the I3Geometry from Geometry frame
-
HitSorting::HitSeriesSeries Split(const HitSorting::HitSeries &hits)¶
ACTION Perform the Splitting:
Get the Pulse-Series from the Frame and read all Hits into a time ordered Hit-Series.
Than call the Main-Algorithm and iterate over all the hits, try to form clusters of Hits and add Hits to them, discard them or form a new cluster.
When Hit-Series is exhausted and Clusters/Subevents have been found write them to the data-stream (either as separate frames or into the same frame).
Save the SplitCount also if that is wanted,
Push everything back into te pipeline.
Clean-up the memory.- Parameters:
hits – the hits to process
- Returns:
a series of hits, which are the subevents (timeorder in sequence and in hit-order)
Protected Types
-
typedef std::map<unsigned int, Limits::RingLimits> RingLimitPairsMap¶
even better accessable limit parameter format for a whole group of parameters
Protected Attributes
-
HiveSplitter_ParameterSet params_¶
PARAM: A parameter-set to run on.
-
RingLimitPairsMap RingLimitPairsMap_¶
The RingLimits for light and particle propagation.
-
RingLimitPairsMap RingVicinityPairsMap_¶
The RingLimits for displacement.
Private Functions
- SET_LOGGER ("HiveSplitter")
-
bool CausallyConnected(const HitSorting::Hit &h1, const HitSorting::Hit &h2)¶
Determine whether two hits are related Two hits are compared, where h1 should be the earlier hit, ortherwise they are switched (self-correcting). First is checked if h1 has h2 in the inclusion volume, Than the causal connection determined by the Norm is imposed.
- Parameters:
h1 – the earlier hit, to be compared
h2 – the later hit, to be compared
- Returns:
true, if Hit1 is causally connected to Hit2; false, if not
-
void AddHit(const HitSorting::Hit &h)¶
The main driver for the entire algorithm: Adds a new hit to all clusters with which it is connected (including subsets of existing clusters). By ‘advancing’ the clusters this function also causes subevents to be built when possible.
- Parameters:
h – the hit to add
-
void AdvanceClusterInTime(hivesplitter::detail::CausalCluster &cluster, const double time)¶
Move this cluster forward in time to t, dropping hits which are no longer within the time window, the request to merge clusters is accounted for
- Parameters:
cluster – the cluster that is worked on
time – The current time to which the cluster should be moved
-
bool AddHitToCluster(hivesplitter::detail::CausalCluster &c, const HitSorting::Hit &h, const unsigned int multiplicity)¶
Attempt to add Hit h to existing cluster c, or to the subset of c with which it is connected by enough hits in c to meet the multiplicity condition.
- Parameters:
c – the cluster to add to
h – the hit to add
multiplicity – this multiplicity of connected DOMs minus 1 in the subgroup must be met!
- Returns:
true, if h was added to c, or to a new subset of c; false, if h was not placed in any cluster
-
void AddSubEvent(HitSorting::HitSet &newSet)¶
Inserts a cluster of hits into the set of subevents, after merging it with any existing subevents with which it shares at least one hit This function also moves any subevents which can no longer grow into the finished subevent collection.
- Parameters:
newSet – the set to add
-
void FinalizeSubEvents()
Pushes all hits through the clusters and completes all subevents, on the assumption that no more future hits will be added.
Private Members
-
HiveGeometry hivegeo_¶
Geometry and Topology of the Hive that is describing the detector.
-
IceHiveHelpers::SymmetricIndexMatrix_Double distanceMap_¶
look-up table for dom-distances: if value==NAN, these DOMS should not be reconnected
-
IceHiveHelpers::SymmetricIndexMatrix_Bool vicinityMap_¶
look-up table for dom-vicinity: if value==false, these DOMS should not be reconnected
-
std::list<hivesplitter::detail::CausalCluster> clusters_
all in-progress causal clusters
-
std::list<hivesplitter::detail::CausalCluster> newClusters_
temporary storage for causal clusters generated while adding a single hit
-
std::list<HitSorting::HitSet> partialSubEvents_
all in-progress subevents
-
hivesplitter::detail::HitSetSequence subEvents_
set of completed subevents which are in time-order (in every aspect)
-
HiveSplitter(const HiveSplitter_ParameterSet ¶ms = HiveSplitter_ParameterSet())
-
struct HiveSplitter_ParameterSet
- #include <HiveSplitter.h>
A set of parameters that steer HiveSplitter.
Public Functions
-
HiveSplitter_ParameterSet()
constructor
Public Members
-
unsigned int multiplicity¶
PARAM: Required multiplicity of connected DOMs with hits in the time-window to form a subevent.
-
double timeWindow¶
PARAM: Time span within which the multiplicity requirement must be met.
-
double timeStatic¶
PARAM: Time within DOMs in vicinity are still considered.
-
double timeCVMinus¶
PARAM: Maximum negative deviation from speed of light travel time which will allow a pair of hits to be considered connected.
-
double timeCVPlus¶
PARAM: Maximum positive deviation from speed of light travel time which will allow a pair of hits to be considered connected.
-
double timeCNMinus¶
PARAM: Maximum negative deviation from light propagation time which will allow a pair of hits to be considered connected.
-
double timeCNPlus¶
PARAM: Maximum positive deviation from light propagation time which will allow a pair of hits to be considered connected.
-
bool selfconnect¶
PARAM: Allow for DOMs to self-connect.
-
Limits::RingLimits SingleDenseRingLimitPairs¶
PARAM: limits for the single, double and tripple dense light connection.
-
Limits::RingLimits DoubleDenseRingLimitPairs¶
-
Limits::RingLimits TripleDenseRingLimitPairs¶
-
Limits::RingLimits SingleDenseRingVicinityPairs¶
PARAM: limits for the single, double and tripple dense vicinity connection.
-
Limits::RingLimits DoubleDenseRingVicinityPairs¶
-
Limits::RingLimits TripleDenseRingVicinityPairs¶
-
HiveSplitter_ParameterSet()
-
template<class Response>
class I3HiveCleaning : public I3ConditionalModule¶ - #include <I3HiveCleaning.h>
The main icetray module.
Public Functions
-
I3HiveCleaning(const I3Context &context)¶
Constructor: configure Default values, register Parameters, register Outbox.
-
~I3HiveCleaning()¶
Destructor.
-
void Configure()¶
Configure method to interact with icetray.
-
void PerformCleaning(I3FramePtr frame)¶
General call method to interact with icetray : Needs to be hooked up to an execution stream.
-
void Geometry(I3FramePtr frame)¶
Geometry call method to interact with Geometry-frame.
-
void Finish()¶
report some numbers of interest
Protected Attributes
-
HiveCleaning_ParameterSet hc_param_set_¶
PARAMs which are delivered to HiveCleaning.
Private Types
-
typedef I3Map<OMKey, ResponseSeries> ResponseSeriesMap¶
-
typedef boost::shared_ptr<ResponseSeriesMap> ResponseSeriesMapPtr¶
-
typedef boost::shared_ptr<const ResponseSeriesMap> ResponseSeriesMapConstPtr¶
-
typedef I3RecoPulseSeriesMapMask ResponseSeriesMapMask¶
-
typedef I3RecoPulseSeriesMapMaskPtr ResponseSeriesMapMaskPtr¶
-
typedef I3RecoPulseSeriesMapMaskConstPtr ResponseSeriesMapMaskConstPtr¶
Private Functions
- SET_LOGGER ("I3HiveCleaning")
-
void Reconfigure(I3FramePtr frame)¶
Reconfigure the subordinated modules
- Parameters:
frame – a frame containing the GCD objects, as forward propagated hand-downs
Private Members
-
HiveCleaning *hiveCleaning_¶
most private HiveCleaning instance
-
I3HiveCleaning(const I3Context &context)¶
-
template<class Response>
class I3HiveCluster : public I3ConditionalModule¶ - #include <I3HiveCluster.h>
The main icetray module.
Public Functions
-
I3HiveCluster(const I3Context &context)¶
Constructor: configure Default values, register Parameters, register Outbox.
-
~I3HiveCluster()¶
Destructor.
-
void Configure()¶
Configure method to interact with icetray.
-
void PerformCleaning(I3FramePtr frame)¶
General call method to interact with icetray : Needs to be hooked up to an execution stream.
-
void Geometry(I3FramePtr frame)¶
Geometry call method to interact with Geometry-frame.
Protected Attributes
-
HiveSplitter_ParameterSet hs_param_set_¶
PARAMs which are delivered to HiveCleaning.
Private Types
-
typedef I3Map<OMKey, ResponseSeries> ResponseSeriesMap¶
-
typedef boost::shared_ptr<ResponseSeriesMap> ResponseSeriesMapPtr¶
-
typedef boost::shared_ptr<const ResponseSeriesMap> ResponseSeriesMapConstPtr¶
-
typedef I3RecoPulseSeriesMapMask ResponseSeriesMapMask¶
-
typedef I3RecoPulseSeriesMapMaskPtr ResponseSeriesMapMaskPtr¶
-
typedef I3RecoPulseSeriesMapMaskConstPtr ResponseSeriesMapMaskConstPtr¶
Private Functions
- SET_LOGGER ("I3HiveCluster")
-
void Reconfigure(I3FramePtr frame)¶
Reconfigure the subordinated modules
- Parameters:
frame – a frame containing the GCD objects, as forward propagated hand-downs
Private Members
-
HiveSplitter *hiveSplitter_¶
most private HiveCleaning instance
-
I3HiveCluster(const I3Context &context)¶
-
template<class Response>
class I3IceHive : public I3ConditionalModule, private I3Splitter¶ - #include <I3IceHive.h>
The main module which unites the algorithms HiveSplitter and TriggerSplitter.
Public Functions
-
I3IceHive(const I3Context &context)¶
Constructor: configure Default values, register Parameters, register Outbox.
-
virtual ~I3IceHive()¶
Destructor.
-
void Finish()¶
Finish routine printing a little bit of information.
-
void Configure()¶
Configure Method to interact with icetray.
-
void DAQ(I3FramePtr frame)¶
DAQ call Method to interact with icetray.
-
void Geometry(I3FramePtr frame)¶
Geometry call method to interact with Geometry-frame.
-
void Calibration(I3FramePtr frame)¶
Calibration call method to interact with Calibration-frame.
-
void DetectorStatus(I3FramePtr frame)¶
DetectorStatus call method to interact with Status-frame.
Protected Attributes
-
bool saveSplitCount_¶
PARAM: Whether to save an integer in the frame indicating the number of subevents generated.
-
bool updateTrigHierarchy_¶
PARAM: Update the TriggerHierarchy with the cut out triggers.
-
HiveSplitter_ParameterSet hs_param_set_¶
Params which are delivered to HiveSplitter.
-
TriggerSplitter_ParameterSet ts_param_set_¶
Params which are delivered to TriggerSplitter.
-
bool triggerSplitterOpt_¶
PARAM: Use TriggerSplitter prior to HiveSplitter.
-
double readWindowMinus_¶
PARAM: Length of readout window to pad before event/trigger [ns].
-
double readWindowPlus_¶
PARAM: Length of readout window to pad after event/trigger [ns].
Private Types
-
typedef I3Map<OMKey, ResponseSeries> ResponseSeriesMap¶
-
typedef boost::shared_ptr<ResponseSeriesMap> ResponseSeriesMapPtr¶
-
typedef boost::shared_ptr<const ResponseSeriesMap> ResponseSeriesMapConstPtr¶
-
typedef I3RecoPulseSeriesMapMask ResponseSeriesMapMask¶
-
typedef I3RecoPulseSeriesMapMaskPtr ResponseSeriesMapMaskPtr¶
-
typedef I3RecoPulseSeriesMapMaskConstPtr ResponseSeriesMapMaskConstPtr¶
Private Functions
- SET_LOGGER ("I3IceHive")
-
void ConfigureSplitters(const I3FramePtr frame)¶
(Re)configure the splitters with new GCD objects
- Parameters:
frame – the frame that should have GCD objects present
-
I3TriggerHierarchy AugmentTriggerHierarchy(I3TriggerHierarchy trigHier, const int start_time, const int end_time, const int configID = IH_CONFIG_ID) const¶
update the triggerHierarchy with a subtrigger for IceHive
- Parameters:
trigHier – the triggerHierarchy to augment
start_time – the starttime of the trigger
end_time – the starttime of the trigger
configID – a Configuraturation ID for the added Trigger
Private Members
-
double noisePadding_¶
pad that many ns noise in front and back of the events
-
HiveSplitter *hiveSplitter_¶
most private HiveSplitter instance
-
TriggerSplitter *triggerSplitter_¶
most private TriggerSplitter instance
-
bool configuration_changed_¶
has any of the vital objects changed?
-
bool G_frame_seen_¶
store if we have seen all necessary frames GCD
-
bool C_frame_seen_¶
-
bool D_frame_seen_¶
-
I3IceHive(const I3Context &context)¶
-
class I3RecoPulseSeriesMap_HitFacility : public HitSorting::OMKeyMap_HitFacility<I3RecoPulse>¶
- #include <HitSorting.h>
specialize OMKeyMap_HitFacility to I3RecoPulse, and add the functionality to produce Masks
Public Functions
-
I3RecoPulseSeriesMap_HitFacility(I3FramePtr frame, const std::string &key)¶
constructor
- Parameters:
frame – frame to extract a map from
key – key in the frame at which we going to find a ResponseMap/Mask
-
template<class HitContainer>
HitContainer GetHits(const std::string &key = "") const¶ get the subset of hits which corresponds to the mask at this key
- Parameters:
key – a the key of a Map/mask that pulses should be extracted from; needs to inherit from map; blank parameter returns the Hits from the bae-object map_
- Returns:
the container filled with timeordered Hits
-
template<class Container>
I3RecoPulseSeriesMapMask MaskFromHits(const Container &hits) const¶ Revert once extracted Hits back to a subMap and a final ResponseMask of the original ResonseMap
- Parameters:
hits – a container with the hits to revert
- Returns:
the subResponseMapMask
Private Functions
- SET_LOGGER ("I3RecoPulseSeriesMap_HitFacility")
-
I3RecoPulseSeriesMap_HitFacility(I3FramePtr frame, const std::string &key)¶
-
template<typename base, class internal>
class IndexMatrix¶ - #include <IceHiveHelpers.h>
a two-dimentional map holding entries of type ‘base’ ‘internal’ representation is a linear array of some art, which can be evaluated in any field and typecast to ‘base’
- Template Parameters:
base – a basic, or complex datatype
internal – a vectorized array, which supports operator[]
Subclassed by IceHiveHelpers::AsymmetricIndexMatrix< base, internal >, IceHiveHelpers::SymmetricIndexMatrix< base, internal >
Public Functions
Protected Functions
-
inline IndexMatrix(const unsigned int biSize, const unsigned int mapSize)¶
hidden constructor
Protected Attributes
-
unsigned int biSize_¶
the size of the indexable range
Private Functions
-
virtual unsigned int BiIndex_To_UniIndex(const unsigned int indexA, const unsigned int indexB) const = 0¶
-
class LimitPair¶
- #include <IceHiveHelpers.h>
Public Functions
-
inline LimitPair(const double m, const double p)¶
-
inline LimitPair(const double m, const double p)¶
-
template<class Response>
class OMKeyMap_HitFacility¶ - #include <HitSorting.h>
A class which helps to extract hits from an ResponseMap Object in the frame; which also holds all the functionality so you do not do anything stupid
Public Functions
-
OMKeyMap_HitFacility(I3FramePtr frame, const std::string &key)¶
constructor
- Parameters:
frame – frame to extract a map from
key – key in the frame at which we going to find a ResponseMap/Mask
-
template<class HitContainer>
HitContainer GetHits() const¶ Extract Hit-objects from the ResponseMap and put/insert them into the container
- Returns:
the container filled with timeordered Hits
-
template<class HitContainer>
ResponseSeriesMap MapFromHits(const HitContainer &hits) const¶ Revert once extracted Hits back to a subMap of the original ResonseMap
- Parameters:
hits – a container with the hits to revert
- Returns:
the subResponseMap
-
const HitObject<Response> &GetHitObject(const Hit &h) const¶
Get the HitObject associated to this hit
- Parameters:
h – the hit
- Returns:
the associated ResponseObject
-
template<class HitContainer>
HitSorting::OMKeyMap_HitFacility<Response>::ResponseSeriesMap MapFromHits(const HitContainer &hits) const¶
Protected Attributes
-
const I3FramePtr frame_¶
PARAM: the frame this might have been extracted from.
-
boost::shared_ptr<const ResponseSeriesMap> map_¶
hold a pointer to the OMKeyMap the Hits have been extracted from
Private Functions
- SET_LOGGER ("OMKeyMap_HitFacility")
-
OMKeyMap_HitFacility(I3FramePtr frame, const std::string &key)¶
-
class RingLimits¶
- #include <IceHiveHelpers.h>
-
class StringTopo¶
- #include <Hive-lib.h>
-
struct subEventTimeOrder¶
- #include <HiveSplitter.h>
wrapper around HitSets to establish timeorder in the set of SubEvents
Public Functions
-
inline bool operator()(const HitSorting::HitSet &lhs, const HitSorting::HitSet &rhs) const¶
implement the order principle
-
inline bool operator()(const HitSorting::HitSet &lhs, const HitSorting::HitSet &rhs) const¶
-
class SubTrigger¶
A reduced readout window, with functions to trim.
Public Functions
-
inline SubTrigger(const double start, const double end, offset_map_t *offsets, const double min_offset, const double max_offset)¶
constructor : explicit
-
HitSorting::HitSeries GetPulses(const HitSorting::HitSeries &hits) const¶
Select pulses that fall within this subtrigger.
- Parameters:
hits – the hits which contain this subwindow
- Returns:
the subevent wich is enveloped by this trigger
-
inline SubTrigger(const double start, const double end, offset_map_t *offsets, const double min_offset, const double max_offset)¶
-
template<typename base, class internal>
class SymmetricIndexMatrix : public IceHiveHelpers::IndexMatrix<base, internal>¶ - #include <IceHiveHelpers.h>
dynamic symmetric BiIndexed -map; input is anything [0..x][0..x]; only upper half and diagonal is filled NOTE beware, there is no explicit check if you leave the indexable range, that is your responsibility
Public Functions
-
inline SymmetricIndexMatrix(const unsigned int biSize)¶
constructor
- Parameters:
biSize – that is the range of the biIndex
Private Functions
-
inline virtual unsigned int BiIndex_To_UniIndex(const unsigned int indexA, const unsigned int indexB) const¶
convert from Bi-indexed representation to a linear index
-
inline SymmetricIndexMatrix(const unsigned int biSize)¶
-
class SymmetricIndexMatrix_Double : public IceHiveHelpers::SymmetricIndexMatrix<double, std::vector<double>>¶
- #include <IceHiveHelpers.h>
specialized class for Double
Public Functions
-
inline SymmetricIndexMatrix_Double(const int biSize)¶
-
inline SymmetricIndexMatrix_Double(const int biSize)¶
-
struct Topology¶
- #include <Hive-lib.h>
describe the topologogy of OMKeys: where topo is: 0 for not on any topology 1,2,3… assorted to that topology by number N
Public Members
-
unsigned int max_strings_¶
the maximum string index hold in this map
-
TopologyRegister topoReg_¶
the register which holds all the information
-
unsigned int max_strings_¶
-
class TriggerSplitter¶
- #include <TriggerSplitter.h>
The TriggerSplitter Module with the functionality tp split up RecoPulses by trigger information.
Public Functions
-
TriggerSplitter(const TriggerSplitter_ParameterSet ¶ms = TriggerSplitter_ParameterSet())¶
Constructor from a ParameterSet.
-
void Configure(const TriggerSplitter_ParameterSet ¶ms)¶
(Re)configure the module
-
void CheckParams_n_Setup()¶
Probe the feasibility of parameter ranges and do setup work.
-
void DefaultOffsetMap()¶
Builds blank offset nmap with default-values for all further operation.
-
void BuildOffsetMap(const I3Calibration &calibration, const I3DetectorStatus &status)¶
Builds centrally needed objects of the module at configuration time.
-
HitSorting::HitSeriesSeries Split(const I3TriggerHierarchy &trigHier, const HitSorting::HitSeries &hits)¶
Perform the Splitting.
- Parameters:
trigHier – the TriggerHierarchy, which is used as the template fo splitting the pulses
hits – the hits which are about to be split
- Returns:
a series of subevents which got split; not neccessarily containing all the pulses from the original series
Public Static Attributes
Protected Attributes
-
double noSplitDt_¶
PARAM: a lower bound on the separation of each trigger.
-
double tWindowMinus_¶
PARAM: the negative padding of triggers (TriggerWindow)
-
double tWindowPlus_¶
PARAM: the positive padding of triggers (TriggerWindow)
Private Types
-
typedef std::map<OMKeyHash::SimpleIndex, double> offset_map_t¶
Private Functions
- SET_LOGGER ("TriggerSplitter")
-
double GetLaunchDT(const I3DOMCalibration &calib, const I3DOMStatus &status) const¶
subroutine for CalcLaunchedDTs
estimate the delay between launches (trigger) times and pulse times This is an un-doing of what is done in I3WaveCalibrator::GetStartTime() to shift the times In no way is this a general physical estimate of the various delays, and therefore, this calculates a wavecalibrator setting dependent parameter. fadc delay is included to account for the longest DT situation of having a pulse start in the first FADC bin
Private Members
-
offset_map_t offsets_¶
a map to hold all offsets per DOM
-
double min_offset_¶
holds the global maximum and mimimum offsets
-
double max_offset_¶
-
TriggerSplitter(const TriggerSplitter_ParameterSet ¶ms = TriggerSplitter_ParameterSet())¶
-
struct TriggerSplitter_ParameterSet¶
- #include <TriggerSplitter.h>
A collection of parameters for the TriggerSplitter.
Public Functions
-
TriggerSplitter_ParameterSet()¶
Constructor : parameterless.
-
TriggerSplitter_ParameterSet()¶
-
struct Trigs¶
a simplifed Trigger representation
Public Functions
-
namespace builder¶
Namespace that provides information of Strings and DOMs to which detector topology they belong NOTE Definitions can be personal preference and are subject to change once the IC86 detector should be further expanded.
Typedefs
-
typedef unsigned int OmTopo¶
-
typedef std::map<unsigned int, StringTopo> TopologyRegister¶
in such an object the topology of a detector can be stored
-
typedef unsigned int OmTopo¶
-
namespace HitSorting
provides functionality to extract and sort Hit-objects
Typedefs
-
typedef HitSorting::HitObject<I3RecoPulse> I3RecoPulse_HitObject¶
-
typedef HitSorting::HitObject<I3DOMLaunch> I3DOMLaunch_HitObject¶
-
typedef HitSorting::HitObject<I3MCHit> I3MCHit_HitObject¶
-
typedef HitSorting::HitObject<I3MCPulse> I3MCPulse_HitObject¶
-
typedef OMKeyMap_HitFacility<I3DOMLaunch> I3DOMLaunchSeriesMap_HitFacility¶
-
typedef OMKeyMap_HitFacility<I3MCHit> I3MCHitSeriesMap_HitFacility¶
-
typedef OMKeyMap_HitFacility<I3MCPulse> I3MCPulseSeriesMap_HitFacility¶
Functions
-
std::ostream &operator<<(std::ostream &oss, const HitSorting::AbsHit &h)¶
-
template<class Response>
double GetInferredTime(const Response &r)¶ Get a sensible time-information of an object: this might be exact time, start-time, or whatever makes sense to order objects in time.
- Parameters:
r – the respones object interesed in
-
template<>
double GetInferredTime(const I3RecoPulse &r)¶
-
template<>
double GetInferredTime(const I3DOMLaunch &r)¶
-
template<class Response>
bool time_sort(const Response &i, const Response &j)¶ establish time-ordering
-
template<class Response>
std::ostream &operator<<(std::ostream &oss, const HitSorting::HitObject<Response> &h)¶ dump the HitObject
-
std::ostream &operator<<(std::ostream &oss, const Hit &h)
Dump the object into a string-stream (this is bound to python as string-cast)
-
template<class ordered_set>
bool SetsIntersect(const ordered_set &lhs, const ordered_set &rhs) Test whether any item in a sorted container is also found in another container NOTE: requirements: iterator and operator< (order!) defined
- Parameters:
lhs – the one container
rhs – the other container having the same sorting as lhs_iter
- Returns:
(true) if lhs and rhs intersect by at least one element
-
template<class ordered_set>
bool SetsIdentical(const ordered_set &lhs, const ordered_set &rhs) a helper function that compares two sets and evaluates the identity by evaluating the identity of every element NOTE: requirements: iterator and operator< (order!) defined
- Parameters:
lhs – the one container
rhs – the other container having the same sorting as lhs_iter
- Returns:
(true) if sets are identical in every element
-
template<class ordered_set>
ordered_set UniteSets(const ordered_set &lhs, const ordered_set &rhs) Return the union of lhs and rhs.
- Parameters:
lhs – the one container
rhs – the other container having the same sorting as lhs_iter
- Returns:
the union of the sets
-
template<class Response, class HitObjectContainer>
HitObjectContainer OMKeyMap_To_HitObjects(const I3Map<OMKey, std::vector<Response>> &pulses)¶ Function to buffer up Pulses from an RecoPulseSeriesMap into an ordered vector of compact Hits.
- Parameters:
pulses – the Pulses to buffer up
- Returns:
the retrieval ordered HitSeries
-
typedef HitSorting::HitObject<I3RecoPulse> I3RecoPulse_HitObject¶
-
namespace hivesplitter¶
-
namespace detail¶
Typedefs
-
typedef std::list<CausalCluster> CausalClusterList¶
-
typedef std::set<HitSorting::HitSet, subEventTimeOrder> HitSetSequence¶
Functions
-
bool isSubset(const CausalCluster &sub, const CausalCluster &super)¶
Test whether the hits in sub are a subset of super
- Parameters:
sub – cluster with certain hits which might be a subset
super – cluster with a series of hits which might be a superset
- Returns:
true, if sub is a subset of super
-
typedef std::list<CausalCluster> CausalClusterList¶
-
namespace honey
In this namespace build objects which have hexagonal structure, just like IceCube: That is strings surrounded by rings of strings aka honey-Combs in different sizes. Each
Typedefs
-
typedef unsigned int StringNbr¶
an alias for what it is
-
typedef std::map<StringNbr, DOMHoneyComb> DOMHoneyCombRegister
Look-up table for the HoneyCombs, indexed by StringNbr.
Functions
-
void MutualAddStringToRing(DOMHoneyCombRegister &combs, const StringNbr center_A, const StringNbr center_B, const unsigned int ringnbr)¶
Register this string [center_A] as on ring[ringnbr] on string [center_B] and vise vers.
- Parameters:
combs – the combs these strings should be registered to
center_A – the string to register
center_B – the other string to register
ringnbr – the ring that strings should be registered to; should not be further than number of already registered rings plus 1
-
bool IsRingX(const DOMHoneyCombRegister &combs, const StringNbr center, const unsigned int ringnbr, const StringNbr string)¶
is this [string] on ring[ringnbr] of [center]
- Parameters:
combs – the combs to look up this ring
center – center string around to look
ringnbr – ring number around center the string should be located on
string – the string to be found
- Returns:
true, if string could be correctly located; false, if not;
-
inline bool IsRing1(DOMHoneyCombRegister &combs, const StringNbr center, const StringNbr string)¶
shorthand
-
inline bool IsRing2(DOMHoneyCombRegister &combs, const StringNbr center, const StringNbr string)¶
shorthand
-
int WhichRing(const DOMHoneyCombRegister &combs, const StringNbr center, const StringNbr string, const unsigned int search_depth = 1000)¶
Which ring is this on?
- Parameters:
combs – the Combs to look this strings up on
center – the center from which the ring should be found
string – the string to locate on any ring
search_depth – the maximum ring that this string is searched for (does limit the amount of computation)
- Returns:
0, if it is the center; n, if it is on ring n; -1, if string is not registered;
-
DOMHoneyCombRegister Abstract(const DOMHoneyCombRegister combs)
Abstract a combs to next smaller RingSize definitions The assignment is done by prescribed rings : combs[ring0]->abstracted[ring0], combs[ring1]->abstracted[ring2], combs[ring2]->abstracted[ring4], …
- Parameters:
combs – the filled Combs to abstract
- Returns:
the abstracted Hive
-
int ExpandRings(DOMHoneyCombRegister &combs, const unsigned int scale_factor = 1)¶
Expands combs and adds new rings to it The combs must have at least 1 ring assigned and equal ring size on all strings, it must also be a mutually complete (every string links against each other)
- Parameters:
combs – the filled combs to expand
scale_factor – expand by using that many rings (this should be a scale to the next complete reverse abstraction)
- Returns:
n number of newly added rings -1 if not possible
-
DOMHoneyCombRegister UniteHive(const DOMHoneyCombRegister &combs1, const DOMHoneyCombRegister &combs2)
Unite two combs into one.
- Parameters:
combs1 – the first combs to unite
combs2 – the second combs to unite
- Returns:
the new united Hives
-
std::string DumpCenter(const DOMHoneyCombRegister &combs, const StringNbr center)¶
Dump an entire entry of an combs.
- Parameters:
combs – the Hive to dump the entry from
center – the entry to dump
- Returns:
the dumped central string
-
typedef unsigned int StringNbr¶
-
namespace IC86Topology¶
Some topological functions useful for the IC86 detector configuration.
Functions
-
namespace IceHiveHelpers¶
Typedefs
-
typedef AsymmetricIndexMatrix<bool, boost::dynamic_bitset<>> AsymmetricIndexMatrix_Bool¶
-
typedef SymmetricIndexMatrix<bool, boost::dynamic_bitset<>> SymmetricIndexMatrix_Bool¶
Functions
-
template<class Response>
I3Map<OMKey, std::vector<Response>> GetPulsesInTimeRange(const I3Map<OMKey, std::vector<Response>> &pulses, const double tw_start, const double tw_stop)¶ Give me all pulses from this ResponseMap which fall within (inclusive) this time-window A simple selection function.
- Parameters:
pulses – from this pulses
tw_start – starting at this time
tw_stop – ending at this time
- Returns:
the subset of pulses
-
template<class Response>
I3Map<OMKey, std::vector<Response>> GetPulsesInTimeRange(const I3Map<OMKey, std::vector<Response>> &pulses, const I3TimeWindow &tw)¶ Give me all pulses from this ResponseMap, which fall within (inclusive) this time-window A simple selection function.
- Parameters:
pulses – from this pulses
tw – within this time-window
- Returns:
the subset of pulses
-
I3TriggerHierarchy ClipTriggerHierarchy(const I3TriggerHierarchy &trigHier, const double tw_start, const double tw_stop, const std::vector<int> &configIDs = std::vector<int>())¶
Clip out the triggers with the given configIDs and within the specified TimeWindow Take all triggers firing within the specified time-window (triggers can thereby extend beyond the specified time-window) If no trigger-configIDs are specified take every trigger in the time-window regardlessly Each TroughPut-trigger, not the global, will have the length of the original trigger (a neccessity to maintain object-structure)
- Parameters:
trigHier – find triggers in there
configIDs – the configured Trigger-IDs of thoese we gonna look for
tw_start – the start time from which clipping commenses
tw_stop – the stop time until which clipping commenses
- Returns:
a clipped trigger Hierarchy
-
I3TriggerHierarchy ClipTriggerHierarchy(const I3TriggerHierarchy &trigHier, const I3TimeWindow &twindow, const std::vector<int> &configIDs = std::vector<int>())¶
Clip out the triggers with the given configIDs and within the specified TimeWindow Take all triggers firing within the specified time-window (triggers can thereby extend beyond the specified time-window) If no trigger-configIDs are specified take every trigger in the time-window regardlessly Each TroughPut-trigger, not the global, will have the length of the original trigger (a neccessity to maintain object-structure)
- Parameters:
trigHier – find triggers in there
configIDs – the configured Trigger-IDs of thoese we gonna look for
twindow – the time window around which we gonna look for triggers
- Returns:
a clipped trigger Hierarchy
-
typedef AsymmetricIndexMatrix<bool, boost::dynamic_bitset<>> AsymmetricIndexMatrix_Bool¶
-
namespace Limits¶
-
namespace OMKeyHash
Defines hashing of OMKeys and ModuleKeys.
Typedefs
-
typedef unsigned int SimpleIndex
a hash type for OMKeys: indexing range [0, MAX_STRINGS*MAX_OMS-1]
-
typedef unsigned int StringNbr
string numbers are unsigned integers in the range [1, MAX_STRINGS]
-
typedef unsigned int OmNbr
OM numbers are unsigned integers in the range [1, MAX_OMS].
Functions
- static const unsigned int MAX_STRINGS (86)
number of strings in the detector
- static const unsigned int MAX_OMS (64)
number of OMs on each string
-
inline StringNbr SimpleIndex2StringNbr(const SimpleIndex simpleIndex)
convert SimpleIndex to string number
- Parameters:
simpleIndex – plain index
- Returns:
string number
-
inline OmNbr SimpleIndex2OmNbr(const SimpleIndex simpleIndex)
convert SimpleIndex to OM number
- Parameters:
simpleIndex – plain index
- Returns:
OM number
-
inline SimpleIndex StringOmNbr2SimpleIndex(const StringNbr string, const OmNbr om)
convert pair of string and OM numbers to SimpleIndex
- Parameters:
string – string number
om – OM number
- Returns:
plain index
-
inline SimpleIndex OMKey2SimpleIndex(const OMKey &omkey)
convert OMKey to SimpleIndex
- Parameters:
omkey – OMKey
- Returns:
plain index
-
inline SimpleIndex ModuleKey2SimpleIndex(const ModuleKey &mkey)
convert ModuleKey to SimpleIndex
- Parameters:
mkey – ModuleKey
- Returns:
plain index
-
inline OMKey SimpleIndex2OMKey(const SimpleIndex simpleIndex)
convert SimpleIndex to OMKey
- Parameters:
simpleIndex – plain index
- Returns:
OMKey
-
inline ModuleKey SimpleIndex2ModuleKey(const SimpleIndex simpleIndex)
convert SimpleIndex to ModuleKey
- Parameters:
simpleIndex – plain index
- Returns:
ModuleKey
Variables
-
static const unsigned int MAX_SIMPLEINDEX = MAX_STRINGS * MAX_OMS - 1
effective number of hashing range
-
typedef unsigned int SimpleIndex
-
namespace std
STL namespace.
- file HitSorting.cxx
- #include “IceHive/HitSorting.h”
(c) 2012 the IceCube Collaboration
$Id$
- Version
$Revision$
- Date
$Date$
- Author
Marcel Zoll marcel.zoll@fysik.su.se
- file HitSorting.h
- #include <numeric>#include “OMKeyHash.h”#include “dataclasses/physics/I3RecoPulse.h”#include “dataclasses/physics/I3DOMLaunch.h”#include “dataclasses/physics/I3MCHit.h”#include “simclasses/I3MCPulse.h”#include “dataclasses/I3MapOMKeyMask.h”
(c) 2012 the IceCube Collaboration
$Id$
Provides functionality to extract and sort Hit-objects from various kinds of representations of hits in icetray
- Version
$Revision$
- Date
$Date$
- Author
mzoll marcel.zoll@fysik.su.se
- file Hive-lib.cxx
- #include <stdlib.h>#include <vector>#include <map>#include <algorithm>#include <boost/assign/list_of.hpp>#include <iostream>#include <cstdio>#include <fstream>#include <boost/lexical_cast.hpp>#include “IceHive/Hive-lib.h”
(c) 2012 the IceCube Collaboration
$Id$
- Version
$Revision$
- Date
$Date$
- Author
Marcel Zoll marcel.zoll@fysik.su.se
- file Hive-lib.h
- #include <cstdlib>#include <vector>#include <set>#include <map>#include “icetray/OMKey.h”
(c) 2012 the IceCube Collaboration
$Id$
- Version
$Revision$
- Date
$Date$
- Author
Marcel Zoll marcel.zoll@fysik.su.se
- file HiveCleaning.cxx
- #include “IceHive/HiveCleaning.h”#include “icetray/I3Units.h”#include <math.h>#include <algorithm>#include <boost/foreach.hpp>#include “IceHive/Hive-lib.h”
(c) 2012 the IceCube Collaboration
$Id$
- Version
$Revision$
- Date
$Date$
- Author
Marcel Zoll marcel.zoll@fysik.su.se
- file HiveCleaning.h
- #include <limits>#include <list>#include <map>#include <sstream>#include “dataclasses/I3Map.h”#include “dataclasses/geometry/I3Geometry.h”#include “IceHive/OMKeyHash.h”#include “IceHive/HitSorting.h”#include “IceHive/Hive-lib.h”#include “IceHive/IceHiveHelpers.h”
(c) 2012 the IceCube Collaboration
The central algorithm to split I3RecoPulseSeriesMaps by arguments of clustering
- Rcs
HiveCleaning.h 99900 2013-02-26 10:10:43Z mzoll
- Version
- Rcs
99900
- Date
- Rcs
2013-02-26 11:10:43 +0100 (Tue, 26 Feb 2013)
- Author
Marcel Zoll marcel.zoll@fysik.su.se
- file HiveSplitter.cxx
- #include <dataclasses/geometry/I3OMGeo.h>#include <IceHive/HiveSplitter.h>#include <algorithm>#include <math.h>#include <boost/foreach.hpp>
(c) 2012 the IceCube Collaboration
$Id$
- Version
$Revision$
- Date
$Date$
- Author
Marcel Zoll marcel.zoll@fysik.su.se
Variables
-
static const LimitPair ic[] = {LimitPair(-300., 300.), LimitPair(-272.7, 272.7), LimitPair(-165.8, 165.8)}¶
-
static const LimitPair dc[] = {LimitPair(-150., 150.), LimitPair(-131.5, 131.5), LimitPair(-40.8, 40.8)}¶
-
static const LimitPair p[] = {LimitPair(-150., 150.), LimitPair(-144.1, 144.1), LimitPair(-124.7, 124.7), LimitPair(-82.8, 82.8)}¶
-
static const LimitPair v_ic[] = {LimitPair(-300., 300.), LimitPair(-272.7, 272.7), LimitPair(-165.8, 165.8)}
-
static const LimitPair v_dc[] = {LimitPair(-150., 150.), LimitPair(-131.5, 131.5), LimitPair(-40.8, 40.8)}
-
static const LimitPair v_p[] = {LimitPair(-150., 150.), LimitPair(-144.1, 144.1), LimitPair(-124.7, 124.7), LimitPair(-82.8, 82.8)}
- file HiveSplitter.h
- #include <limits>#include <list>#include <map>#include “dataclasses/I3Constants.h”#include “dataclasses/geometry/I3Geometry.h”#include “IceHive/OMKeyHash.h”#include “IceHive/HitSorting.h”#include “IceHive/Hive-lib.h”#include “IceHive/IceHiveHelpers.h”
(c) 2012 the IceCube Collaboration
The central algorithm to split ResponseSeriesMaps by arguments of clustering
- Rcs
HiveSplitter.h 99900 2013-02-26 10:10:43Z mzoll
- Version
- Rcs
99900
- Date
- Rcs
2013-02-26 11:10:43 +0100 (Tue, 26 Feb 2013)
- Author
Marcel Zoll marcel.zoll@fysik.su.se
- file I3HiveCleaning.cxx
- #include “IceHive/I3HiveCleaning.h”
(c) 2012 the IceCube Collaboration
$Id$
- Version
$Revision$
- Date
$Date$
- Author
Marcel Zoll marcel.zoll@fysik.su.se
- file I3HiveCleaning.h
- #include “icetray/I3ConditionalModule.h”#include “icetray/I3Units.h”#include “dataclasses/geometry/I3Geometry.h”#include “dataclasses/physics/I3RecoPulse.h”#include “dataclasses/I3MapOMKeyMask.h”#include <boost/make_shared.hpp>#include “IceHive/HiveCleaning.h”#include “icetray/I3Int.h”#include “dataclasses/physics/I3EventHeader.h”
(c) 2012 the IceCube Collaboration
The IceTray I3Module wrapper around the central algorithm HiveCleaning
- Rcs
I3HiveCleaning.h 99900 2013-02-26 10:10:43Z mzoll
- Version
- Rcs
99900
- Date
- Rcs
2013-02-26 11:10:43 +0100 (Tue, 26 Feb 2013)
- Author
Marcel Zoll marcel.zoll@fysik.su.se
Functions
-
I3_MODULE(I3HiveCleaning<I3RecoPulse>)¶
- file I3HiveCluster.cxx
- #include “IceHive/I3HiveCluster.h”
(c) 2012 the IceCube Collaboration
$Id$
- Version
$Revision$
- Date
$Date$
- Author
Marcel Zoll marcel.zoll@fysik.su.se
- file I3HiveCluster.h
- #include “icetray/I3ConditionalModule.h”#include “icetray/I3Units.h”#include “dataclasses/geometry/I3Geometry.h”#include “dataclasses/physics/I3RecoPulse.h”#include “dataclasses/I3MapOMKeyMask.h”#include <boost/make_shared.hpp>#include “IceHive/HiveSplitter.h”#include “icetray/I3Int.h”#include “dataclasses/physics/I3EventHeader.h”
(c) 2012 the IceCube Collaboration
The IceTray I3Module wrapper around the HiveSplitter and use of it as a cleaning module
- Rcs
I3HiveCluster.h 99900 2013-02-26 10:10:43Z mzoll
- Version
- Rcs
99900
- Date
- Rcs
2013-02-26 11:10:43 +0100 (Tue, 26 Feb 2013)
- Author
Marcel Zoll marcel.zoll@fysik.su.se
Functions
-
I3_MODULE(I3HiveCluster<I3RecoPulse>)¶
- file I3IceHive.cxx
- #include “IceHive/I3IceHive.h”
(c) 2012 the IceCube Collaboration
$Id$
- Version
$Revision$
- Date
$Date$
- Author
Marcel Zoll marcel.zoll@fysik.su.se
- file I3IceHive.h
- #include “icetray/I3ConditionalModule.h”#include “phys-services/I3Splitter.h”#include “icetray/I3Units.h”#include “icetray/I3Int.h”#include “dataclasses/I3Constants.h”#include “dataclasses/geometry/I3Geometry.h”#include “dataclasses/calibration/I3Calibration.h”#include “dataclasses/status/I3DetectorStatus.h”#include “dataclasses/physics/I3RecoPulse.h”#include “dataclasses/I3MapOMKeyMask.h”#include <boost/make_shared.hpp>#include “IceHive/HiveSplitter.h”#include “IceHive/TriggerSplitter.h”#include “dataclasses/physics/I3EventHeader.h”#include “IceHive/IceHiveHelpers.h”
(c) 2012 the IceCube Collaboration
The IceTray I3Module wrapper around the central algorithm HiveSplitter and TriggerSplitter, which in turn use a API trough SubEventStartStop
- Rcs
I3IceHive.h 99900 2013-02-26 10:10:43Z mzoll
- Version
- Rcs
99900
- Date
- Rcs
2013-02-26 11:10:43 +0100 (Tue, 26 Feb 2013)
- Author
Marcel Zoll marcel.zoll@fysik.su.se
(c) 2012 the IceCube Collaboration
$Id$
The IceTray I3Module wrapper around the central algorithm
HiveSplitter and TriggerSplitter, which in turn use a API trough SubEventStartStop- Version
$Revision$
- Date
$Date$
- Author
Marcel Zoll marcel.zoll@fysik.su.se
Defines
-
IH_CONFIG_ID¶
Functions
-
I3_MODULE(I3IceHive<I3RecoPulse>)¶
Instantiate IceHive for the use with I3RecoPulses, aka working on I3RecoPulseSeriesMap(Masks)
- file IC86Topology.cxx
- #include “tools/IC86Topology.h”
(c) 2013 the IceCube Collaboration
$Id$
Some topological functions useful for the IC86 detctor configuration NOTE file in work progress
- Version
$Revision$
- Date
$Date$
- Author
- file IC86Topology.h
- #include “icetray/OMKey.h”
(c) 2013 the IceCube Collaboration
$Id$
Some topological functions useful for the IC86 detector configuration
- Version
$Revision$
- Date
$Date$
- Author
- file IceHiveHelpers.cxx
- #include “IceHive/IceHiveHelpers.h”#include <boost/foreach.hpp>#include <algorithm>#include <vector>
copyright (c) 2011 the IceCube Collaboration $Id$
A modular algorithm as an rewrite from project IceHive by Naoko
- Date
- Rcs
2013-10-22
- Author
mzoll marcel.zoll@fysik.su.se
- file IceHiveHelpers.h
- #include “icetray/OMKey.h”#include “dataclasses/I3Map.h”#include “dataclasses/I3TimeWindow.h”#include “dataclasses/physics/I3TriggerHierarchy.h”#include <boost/foreach.hpp>#include <boost/dynamic_bitset.hpp>
- file IdealGeometry.cxx
- #include “tools/IdealGeometry.h”#include <boost/make_shared.hpp>#include <boost/foreach.hpp>
Functions
-
I3Geometry GenerateTestGeometry()¶
Generate a TestGeometry construct an artificially ideal IceCube geometry, that is:
exactly centered at string 36
the major axis of the hexagonal grid follows the x-axis
all strings are at their exact position in the hexagonal structure
The charcteristic inter string spacing is 125 meters
the detector center is 1948 meter below the ice-surface
OM30 on regular IC-strings rests in the detector XY plane
DOMs are spaced 17m in IC, 10/7m in DC
IceTop tanks are located exactly on top of the strings at the surface
-
I3_MODULE(I3GeoDeliver)¶
-
I3Geometry GenerateTestGeometry()¶
- file IdealGeometry.h
- #include “icetray/I3Module.h”#include “dataclasses/geometry/I3Geometry.h”#include <boost/make_shared.hpp>
(c) 2013 the IceCube Collaboration
$Id$
tools to create an ideal I3Geometry for testcases and stuff
- Version
$Revision$
- Date
$Date$
- Author
mzoll marcel.zoll@fysik.su.se
(c) 2013 the IceCube Collaboration
$Id$
tool to create an ideal I3Geometry for test-cases and stuff
- Version
$Revision$
- Date
$Date$
- Author
mzoll marcel.zoll@fysik.su.se
Functions
-
I3Geometry GenerateTestGeometry()
Generate a TestGeometry construct an artificially ideal IceCube geometry, that is:
exactly centered at string 36
the major axis of the hexagonal grid follows the x-axis
all strings are at their exact position in the hexagonal structure
The charcteristic inter string spacing is 125 meters
the detector center is 1948 meter below the ice-surface
OM30 on regular IC-strings rests in the detector XY plane
DOMs are spaced 17m in IC, 10/7m in DC
IceTop tanks are located exactly on top of the strings at the surface
- file index.dox
- file OMKeyHash.h
- #include “icetray/OMKey.h”#include “dataclasses/ModuleKey.h”
(c) 2012 the IceCube Collaboration
$Id$
Provide hashing of OMKeys and ModuleKeys that is well ordered, complete, hierarchical and minimal injective into the natural numbers (N) aka. unsigned integers This makes it implicitly usable as an unique Hash (bidirectional) and as a Index-range in regular array-applications
- Version
$Revision$
- Date
$Date$
- Author
mzoll marcel.zoll@fysik.su.se
- file TriggerSplitter.cxx
- #include <boost/foreach.hpp>#include <boost/make_shared.hpp>#include <boost/assign.hpp>#include <icetray/I3Units.h>#include <dataclasses/I3Double.h>#include <dataclasses/I3TimeWindow.h>#include <dataclasses/I3MapOMKeyMask.h>#include <dataclasses/TriggerKey.h>#include <dataclasses/physics/I3Trigger.h>#include <dataclasses/physics/I3TriggerHierarchy.h>#include <dataclasses/physics/I3RecoPulse.h>#include <algorithm>#include <vector>#include <string>#include <cfloat>#include “IceHive/TriggerSplitter.h”#include “IceHive/HitSorting.h”#include “IceHive/IceHiveHelpers.h”
copyright (c) 2011 the IceCube Collaboration $Id$
A modular algorithm as an rewrite from project TriggerSplitter by Naoko
- Date
- Rcs
2013-10-22
- Author
mzoll marcel.zoll@fysik.su.se
Variables
-
static const int trigIDs[] = {1006, 1007, 1011, 21001}¶
- file TriggerSplitter.h
- #include “dataclasses/TriggerKey.h”#include “dataclasses/physics/I3Trigger.h”#include “dataclasses/physics/I3TriggerHierarchy.h”#include “dataclasses/calibration/I3Calibration.h”#include “dataclasses/status/I3DetectorStatus.h”#include “icetray/I3Units.h”#include “IceHive/OMKeyHash.h”#include “IceHive/HitSorting.h”
copyright (c) 2011 the IceCube Collaboration
- Rcs
TriggerSplitter.cxx 94325 2012-10-20 15:13:28Z mzoll
A modular algorithm as an rewrite from project TriggerSplitter by naoko
- Date
- Rcs
2013-10-22
- Author
mzoll marcel.zoll@fysik.su.se
- dir IceHive
- dir IceHive
- dir IceHive
- dir icetray
- dir private
- dir public
- dir tools
- dir tools
- page index
- Author
Marcel Zoll
Overview¶
The origin of the project is a re-implementation of the TopologicalTrigger (ttrigger) algorithm by D. Chirkin into TopologicalSplitter rewritten and coded by C. Weaver. In a number of consecutive steps the code has been refined and expended with better understanding on the base-lining physics and implementation mechanics. The result is a general clustering algorithm, that can be used as both, cleaning and splitter.
The main objective of the algorithm is to construct (all) subsets from the input pulses such that each pulse in the subset is causally connected to at least N other, earlier pulses in the set, within a time window T, and then to form subevents by merging all causal subsets which overlap.
The novelty with this module is that the detector is described by hexagonal cylinders (honey combs) which build up the detector. In the final detector geometry thereby around each string surrounding rings of strings can be defined, so called rings.
By this segmentation of the detector for each DOM the surrounding rings can be identified and on each of them a certain region of included DOMs defined, the so called eligible volume.
In this way the individual active volume can be steered much more exactly and the global active Volume kept to a minimum so that splitting power and physics against noise separation power is increased.Additionally the module has learned the trigger-splitting algorithm, so that from a full pulse/hit-series only those time-windows can be selected, which are centered around a given fired trigger. The trigger-splitting algorithm and is function is better looked up in the project TriggerSplitter.
Another new module is HiveCleaning, which removes isolated hits from an hit-series and thereby delivers a more precise description of the detector.
Templating¶
templated IceHive modules¶
The project is more or less completely templated for the use with any Pulse(/Hit) I3Object which is shipped in a PulseSeriesMap(Mask). Current Requirements are that the Pulse-object has a ‘’.GetTime()’’ and ‘’.GetCharge()’’ operative and the PulseSeriesMap or the castable object has the signature I3Map<OMKey, vector<Pulse> >.
The end output off all modules is per definition a bit-mask with the characteristics as it is implemented in “icetray/I3OMKeyMapMask”.
If other Pulse I3Object types are desired, which do not fulfil these requirements the according functions can always be specialized to the specific case.
NOTE FUTURE However the currently only the specialization of “I3OMKeyMapMask” to “I3RecoPulseSeriesMapMask” is implemented and the modules of IceHive have been restricted to this use only. If this implementation should be reopened and implemented for general Pulse I3Objects, then the additional functionality can be reintegrated into the IeHive-modules by adapting the type-definitions under the ‘’definitions’’-sections of the Module-declaration.
templated Libraries¶
All libraries in IceHive have been written in the hindsight of portability to other foreign code or projects, which also includes the massive use of templates.
Clustering algorithm¶
The clustering of HiveSplitter works by multiplicity arguments imposed on overlapping causal connected hits. The causal connection of any two hits is checked evaluating the earlier hit (E) against the later one (L). The evaluation is done by the requirement that L is in the eligible volume of E and fulfils a causal argument. Hence both checks enforce time-ordering.
Eligible Volume¶
The eligible Volume is shaped exclusively by the RingLimits passed on by the user. It does include different numbers of DOMs up and down on the strings organized in rings around the earlier hit (E).
Each DOM in this eligible volume can be a potential neighbour hit, which can contribute to fulfilling the multiplicity requirement and thereby forming a cluster.
The eligible volume is not mutually inclusive (hit1 including hit2 in eligible volume, does not automatically imply hit2 includes hit1), if RingLimits parameters are not configured symmetrically. This is actually one of the main features of this approach. By different shapes of this eligible volume (more/less rings, asymmetries in plus/minus, more/less included DOMs per ring) the acceptance of different track directions can be exactly steered.
However it is wise to stick to a rather isotropic neutral 4 pi acceptance configuration, if not entirely sure what one is doing.
Causal Argument¶
If two hits are compared and found to be included in the eligible volume they are checked if the earlier hit does have a causal argument to cause the later hit. This argument takes parameters of distance and timing and returns a binary expression. The causal argument in IceHive is an estimator which incorporates three different physical plausibilities how two hits are connected:
Spacial Offset: Hits are on the same light front (Cherenkov-cone) but topological distant from each other Light Propagation: Hits are causally connected through the outwards propagation of light. Particle Propagation: Hits are causally connected through the moving particle, which is the source of further light. Hits are at the same topological place.
Multiplicity¶
The parameter Multiplicity is the requirement on the number of overlapping causal connected hits to any one other hit found, in order for it accepted into a cluster. The multiplicity must be fulfilled within a time limit set by parameter TimeWindow.
So to say for a Multiplicity of 4(=default) and a TimeWindow of 2ms: A cluster does form, if 4 hits are found within a 2ms, where each of them is causally connected (within the time ordering). Once a cluster is formed more hits are added to, if the new (later) hit does causally connect to at least 4 (former) hits from that cluster, within the time-window.
Lookup-tables¶
This project relies greatly on the use of LookUp-tables to circumvent repetitive computation in the comparison of any two OMKeys. An example for such a lookup-table is the distance map between OMKeys, where the program the request to this property is very frequent (at least once per hit). Their initialization is a fast process (5sec) at programm-start and they are hold in memory during runtime.
Currently they are implemented as plain two dimensional arrays, which are as big as the number of OMKeys squared. Explicitly the indexing through the
OMKeyHash::SimpleIndex is used. This allows direct access to the requested property, which is a much faster process than iterators or other stl::map-operations.While in principle such square maps are reducible, because they are symmetrical, this is not necessarily desired: such maps can additionally store and transport more information than just the requested property; for example, by setting entries to NAN or any other deliberate value, certain arising cases in the computation can be directly treated and handled inside the map. For example if the connection between OMKey0 at index[0] and OMKey1 at index[1] should be probed by their distance, but OMKey1 should never connect to OMKey0 regardless, this can be solved in the map by
map[0][0]= 0.
map[1][1]= 0.
map[0][1]= 5.
map[1][0]= NANScaleability of algorithm¶
In fact IceHive or rather HiveSplitter works-off pulses in a linear fashion comparable to a stack. Therefore the algorithm scales always linear
with the number of injected Pulses. This is very important property if applications to very long events or even a long expose sample or even stream of Pulses is considered.
If the algorithm should be found to be performing well enough for application to the direct detector output (DOMLaunches) this enables the direct rewrite into a trigger.
HiveLib¶
HiveLib is the Driving core of this module: It is a library that provides fast look-up of the IceCube Detector Configuration expressed in terms of Rings of strings surrounding a chosen central string. Right now a maximum number of 2 rings are indexed for IceCube, 4 for DeepCore and 8 for PINGU-spaced strings.
All necessary functionality is provided through interfaces, so there is no need for direct class interactions.
Normally, you should choose the representation of rings that suffice your needs, so do not describe inter-IceCube spacings by a DeepCore-spaced configuration, as it will be slow and have gap rings (every second one). However, if you really want to, there is the possibility to abstract a given configuration to the next lower level.
Different Geometries¶
There might come a time where the current implementation for IC86 will no longer suffice the needs and the module needs to be adapted.
IceHive has not been adapted to such a general use-case with an arbitrary Geometry yet, because some of the generalizations are hard to do, require a lot of smart functions and are sometimes impossible to anticipate.
The necessary adoptions to a new geometry is no easy task and needs caution in every step. Here should be some guidelines what needs to be done in such case:OMKeyHash: Check if the viable ranges of OMKeys still fulfils the needs of the new detector. If possible find a new hash-function that still maps all OMKeys (completeness), uses consecutive hashes (compact) and is fast to compute. Hive-lib: New OMKeys and their special geometries need to be defined. This involves the description of all new OMKeys in the “Topology” and the description of all deployed strings in the Hives of the according sub-geometry. Feel free to use the functions provided in Hive-lib to newly construct or expand from current detector geometry. HiveSplitter: Adapt the Hive-Selections in the BuildDistanceMap-function to the new OMKeys HiveCleaning: Adapt the Hive-Selections in the BuildDistanceMap-function to the new OMKeysRunning the algorithm as a trigger¶
The algorithm of HiveSplitter can also be used just to identify clusters of hits in the detector (see also the HiveCluster-module). This fact can be used to run the HiveSplitter
algorithm to identify occurrences of clustering hits in the detector, a dead give-away for physics being present.
The algorithm is currently not explicitly supporting asynchronous operation on a stream of hits, but can easily adapted to do so. This is due to the fact that the internals of
HiveSplitter are independent of the exact shape of the outside object that a Hit, the internal representation, actually represents. Also the algorithm is linear, thus the algorithm is working off hits in a stack-like fashion.Here is what you have to do if you choose to undergo this endeavour: You going to need to take apart the HiveSplitter::Split() routine. Expose its internal functions and objects: A stack of Hits (deque|Hits|), which is the front buffer. It must be possible to insert hits at the back, while hits are worked off from the front. The driving routine HiveSplitter::AddHit() needs to take the ‘oldest’ hit from the front of the stack and work the algorithm. call to the HiveSplitter::FinializeClusters() only when all processing is finished, aka all hits have been worked off. The subEvents of concluded clusters needs either to be exposed so that all finished events can be read of at any time. Take another look at the internal registers and buffers, that expired objects are removed from them (memory clean-up).
Algorithm¶
This section aims to summarize the process-flow of the HiveSplitter/I3IceHive algorithm. It is a low-level description of the algorithm driving the HiveSplitter, which is used to find clusters of pulses in the IceCube detector, which then later can be identified to individual subevents. Please note: this text does not try to relate used techniques and idioms to the physics in the detector; this can be found in the formal documentation of the project. Concepts which are important in this context, but will not be discusses in this section: Hexagonal Geometry of the detector, Hashing concepts, The causal connection Computation of Time-residuals, .
This section will only describe the use of the IceHive-module when ONLY the HiveSplitter is configured.
Implementation¶
The project presents to the icetray-user a high-level I3Module ‘I3IceHive’, while the driving (splitter) algorithm is implemented underneath in a module ‘HiveSplitter’, which aims to rely as little as possible on specific implementations and imports from icetray.
The high-level I3Module interacts with the icetray environment, handles the parsing of parameters, handles objects in the I3Frame and prepares them for processing with the splitter-algorithm. The splitter algorithm on the other hand configures its routines and lookup-tables only once, and is then providing a simple function Split(), where Pulses/Hits are passed to and the output is the split series of Pulses into subevents.
General processing flow¶
The Execution of the Module is handled in four steps: Initialization: where the module gets set up and preconfigured; note that not all fields are initialized because some information, for example geometry information, is still missing. Configuration of the splitter: where with information from the GCD-frames the splitter can be fully configured, which involves explicitly the set-up of look-up tables Execution: where a block of to process information is handed to the module in the form of a I3Frame. The necessary objects are read, the splitter algorithm is run, and the output is written back to the frame as I3Objects. Termination: where the run-time of the Module ends. Internal occupied memory is freed and a summary about runtime-statistics written to the screen.
Observe that the names of these steps are not isentical with the function names used in IceTray.
This document focuses on the Configuration and Execution part, as it is driving routine of the Module
Initialization time¶
The Module is added to the tray by the usual tray.AddModule-routine:
from icecube import IceHive tray.AddModule(“I3IceHive<I3RecoPulse>”, name, Param1 = value, Param2 = value …)
It is worth to mention that the high-level Module I3IceHive is templated, so that I3RecoPulse can be substituted by any other I3Pulse/Hit object found in the frame as an OMKeyMapMask
.
The parameters and their function are described in the projects documentation.
Adding the module to the tray, calls the Constructor I3IceHive() of the high-level I3Module. All user-definable options are at this time initialized with default-values. Also a pointer to the HiveSplitter is initialized; however, the pointer remains unset, as there is not enough information to set it up, yet.
Once the tray has successfully set up all added modules and services, it will call the I3IceHive.Configure() methode. Here the user-defined parameter values are passed to the high-level I3Module. The ones relevant to the splitter algorithm are wrapped in an object HiveSplitter_Parameters. With this set of parameters the splitter is initialized and the previously mentioned pointer is set.
At this initialization all parameter values of the Splitter will be set, however, look-up tables will still remain initialized, because the remaining ingredient, geometry information, is still missing.
Configuration time¶
The first frames that pass by the I3Module are expected to contain GCD-information. Pointers to this necessary information objects are buffered up. With this last missing piece of information the splitter routine can be finally fully configured: the Geometry is passed to the Splitter module, and its routine HiveSplitter::BuildLookUpTables().
At this point a major component of the algorithm is executed, which builds look-up tables from the configured parameters and position of the DOMs. These tables will be used later in the evaluation of the CausallyConnected criterium.
Two matrix will be initialized and filled:
DOM-vicinity map, which is a
SimpleIndexMatrice_Bool DOM-distance map, which is a SimpleIndexMatrice_DoubleBoth of them are plain 2-dimensional matrices, which consternate if in the comparison of any two DOMs, these should be considered ‘close’. Individual DOMs (OMKeys) are mapped to consecutive hash-values for this process. Both matrices have square-form, but are not necessarily symmetric; meaning their values can be accessed as matrix(DOM_1)(DOM_2) as well as matrix(DOM_2)(DOM_1)
; however, only in the case of symmetry the elements will be equal.
Both type of maps use a mechanism to store one or two layers of information:
The SimpleIndexMatrice_Bool matrix, whichs underlying container is a bitmap, can only store binary states, where true denotes a positive and false a negative evaluation. The SimpleIndexMatrice_Double matrix, whichs underlying container is a vector of doubles, stores a finite double-value for positive evaluations, and NAN for a negative evaluation. The double-value in itself can additionally store further information, which we will use here to store the spacial distance between pairs of DOMs.If a pair of DOMs is ‘close’ to each other is determinated by the RingDistanceLimits for the DOM-distance map and by the VicinityDistanceLimits for the DOM-vicinity map respectively. Here for each DOM the realtive position of the comparative DOM is evaluated. For example DOM_A compared to DOM_B is on the n-th ring and in vertical distance z. If DOM_B is in the specified region around DOM_A given through the DistanceLimits, the field for this DOM-pair is set to their spacial distance or, in the case of the Vicinity map, just true. In the case that DOM_B is outside the region around DOM_A the field is set to NAN or false respectively. The information on which ring DOMs rest relative to each other is provided through the library Hive-lib.
Thereby all DOM-pairs are evaluated and all fields in the look-up are initialized. The map/matrices will in the end look like this:
horizontal index_x, vertical index_y; x,y the hashed DOM index, where #(x)=#(y)=#(OMKey); index row annotates IceTop-strings (T) (=OM 61,62,63,64 per string), entries: 0 denotes double(0), d denotes a real double-value, N denotes NAN | x … T T T T … T T T T ….. T T T T (too distant ring) T T T T ..
y | 0 d d d N N N N … N N N N d d d d d N N N … N N N N ….. N N N N N N N N N N N N … N N N N | d 0 d d d N N N … N N N N N d d d d d N N … N N N N ….. N N N N N N N N N N N N … N N N N | d d 0 d d d N N … N N N N N N d d d d d N … N N N N ….. N N N N N N N N N N N N … N N N N | d d d 0 d d d N … N N N N N N N d d d d d … N N N N ….. N N N N N N N N N N N N … N N N N | N d d d 0 d d d … N N N N N N N N d d d d … N N N N ….. N N N N N N N N N N N N … N N N N | N N d d d 0 d d … N N N N N N N N N d d d … N N N N ….. N N N N N N N N N N N N … N N N N | N N N d d d 0 d … N N N N N N N N N N d d … N N N N ….. N N N N N N N N N N N N … N N N N | N N N N d d d 0 … N N N N N N N N N N d d … N N N N ….. N N N N N N N N N N N N … N N N N | … N N N N … N N N N … N N N N … N N N N T | N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N T | N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N T | N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N T | N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N | d N N N N N N N … N N N N 0 d d d N N N N … N N N N ….. N N N N N N N N N N N N … N N N N | d d N N N N N N … N N N N d 0 d d d N N N … N N N N ….. N N N N N N N N N N N N … N N N N | d d d N N N N N … N N N N d d 0 d d d N N … N N N N ….. N N N N N N N N N N N N … N N N N | d d d d N N N N … N N N N d d d 0 d d d N … N N N N ….. N N N N N N N N N N N N … N N N N | N d d d d N N N … N N N N N d d d 0 d d d … N N N N ….. N N N N N N N N N N N N … N N N N | N N d d d d N N … N N N N N N d d d 0 d d … N N N N ….. N N N N N N N N N N N N … N N N N | N N N d d d d N … N N N N N N N d d d 0 d … N N N N ….. N N N N N N N N N N N N … N N N N | N N N N d d d d … N N N N N N N N d d d 0 … N N N N ….. N N N N N N N N N N N N … N N N N | … N N N N … N N N N … N N N N … N N N N T | N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N T | N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N T | N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N T | N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N | ….. N N N N ….. N N N N ….. N N N N ….. N N N N T | N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N T | N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N T | N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N T | N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N | N N N N N N N N … N N N N N N N N N N N N … N N N N ….. N N N N 0 d d d N N N N … N N N N | N N N N N N N N … N N N N N N N N N N N N … N N N N ….. N N N N d 0 d d d N N N … N N N N | N N N N N N N N … N N N N N N N N N N N N … N N N N ….. N N N N d d 0 d d d N N … N N N N | N N N N N N N N … N N N N N N N N N N N N … N N N N ….. N N N N d d d 0 d d d N … N N N N | N N N N N N N N … N N N N N N N N N N N N … N N N N ….. N N N N N d d d 0 d d d … N N N N | N N N N N N N N … N N N N N N N N N N N N … N N N N ….. N N N N N N d d d 0 d d … N N N N | N N N N N N N N … N N N N N N N N N N N N … N N N N ….. N N N N N N N d d d 0 d … N N N N | N N N N N N N N … N N N N N N N N N N N N … N N N N ….. N N N N N N N N d d d 0 … N N N N | … N N N N … N N N N … N N N N … N N N N | N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N | N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N | N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N | N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N | … N N N N … N N N N ….. N N N N ….. N N N N
Observe the block-wise structure and repetitiveness.
Run time¶
After the HiveSplitter
and its look-up tables are build, the algorithm is now fully initialized. The controlling I3IceHive-Module triggers on DAQ-frames, and tries to split the PulseSeries, which is found at the specified key. This process is done in three steps
Preparation Splitting Pulses/Hits Writing of Output
Input and preparation¶
When the algorithm is confronted with a frame containing the required PulseSeriesMap the processing commences. First the PulseSeriesMap object is de-serialized from the frame (necessary in the case of masks) and every (Reco)Pulse is converted into a simplified Hit-object, holding only essential information of the pulse: OMKey that the Pulse occurred on (Hash-value) Time the Pulse occurred and a pointer to the original pulse, for the back conversion
Thereby every Pulse in the PulseSeriesMap is represented by a single Hit in an (linear) HitSeries. The series of hits is then time-sorted, so the end-product is a vector of Hits as they occurre in time.
This time-ordered HitSeries is passed on to the HiveSplitter algorithm which works them off front to back in a first-in-first-out (fifo) fashion.
Working off pulses¶
The general processing is as follows:
Every analysed hit is checked if it is causally connected to the hits in any pre-existing cluster. If it is connect to hits in that cluster within a specified time-window the hit is added to it. If the hit can not be added to any other cluster, it will form a new ‘starting’ cluster by its own. By this process starting clusters will iteratively grow as new hits are added to them. If by this process any cluster exceeds a multiplicity requirement on the number of connected DOMs with hits within the time-window, the cluster is made marked as ‘permanent’. Hits will be only added to such permanent clusters if they too connect to a sufficient amount of DOMs in the given time-window.
As the hits are processed in time-order the currently processed hit is always guarantied to be the latest seen hit. This fact is heavily used in the algorithm! Cluster always track how many and which hits are mutually connected within the progressive time-window. From this register of possible connection partners the hits are removed, which are later than the time-window compared to the currently processed hit.
This means that if the number of DOMs found in this register of a permanent cluster falls below the multiplicity requirement, no more hits can be added to that cluster at any time. The cluster is destined to ‘conclude’ as with time the rest of the hits will also be shifted out of the register.
As a whole this implements a mechanism where single hits first build ‘starting’ clusters, which expand with added hits until they eventually fulfil the multiplicity requirement and become ‘permanent’; as no more hits can be added to an cluster, it ‘concludes’ and takes not part in the further processing. Also some starting Clusters will never reach the multiplicity requirement and be removed without ever becoming permanent.
The algorithm also implements the merging of clusters, which will happen if any two clusters share one common hit, as it was added to both in a previous operation step. This is a bit disputed process because it is theoretically not very selective, however, proves in application strong enough to ensure ordered operation.
At any time that a permanent cluster concludes, it is removed from the register of active active clusters and is hits are moved to the output as a subEvent.
Through this prescription all hits are worked off, to the point where no hits remain. At that point all clusters are forced to conclude: permanent clusters are move to the output and starting clusters are discarded. Effectively only hits which could be collected to any permanent cluster will be found in the output, and there only once assigned to that very cluster. All other hits were effectively disregarded in the process, as they where atributed as non-clustering hits (probable noise).
The algorithm will then assemble all subEvents into a time-ordered vector of subEvents, where the time is determined by the first hit. This is then returned to the outside, controlling IceHive-module.
Writing of Output¶
With the list of SubEvents and the hits that belong to them, the I3IceHive-module creates for every SubEvent a new (sub) P-frame. By construction every such subevent-frame is required to have an I3EventHeader present with an incremental subevent-ID. This and the RecoPulseSeriesMap(Mask) of the SubEvent are written to the frame.
In principle this does conclude the job of an icetray-EventSplitter. Still more convenience objects are written to the frame, which are helpful for further analysis and processing purposes. For example all hits which are attributed to noise are mixed into the subEvent to provide a PulseSeries which has all noise-pulses present minus any pulses from any other subEvent happening at the same time. Also a modified I3TriggerHierarchy is written to the frame, adapted to the time-extension of that SubEvent. Optional it is augmented with a new trigger-key reflecting the IceHive algorithm.