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

OMKey GetOMKey() const

simply return the OMKey of this hit

double GetTime() const

simply return the Time of this hit

bool operator==(const AbsHit &rhs) const

Comparison Operator for AbsHits; just compare the (unique) index in the time ordered AbsHit-series.

bool operator<(const AbsHit &rhs) const

for sorting AbsHits we’re mostly interested in their time, and only use their indices as tie-breakers

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

AbsHit(const OMKey omkey, const double time)

Constructor

Parameters:

• omkey – The OMkey 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.

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

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)

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

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

void AddCenter(const StringNbr center)

add the central string

void SetCenter(const StringNbr center)

set 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

Private Members

std::vector<Ring> honey_

member: storing the index of the ring [0…n] and the contained strings;

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

template<class Response>
inline Hit(const HitObject<Response> &base_obj)

constructor; hide it from the user, giving only access to it by friend-classes/functions

Parameters:

base_obj – the HitObject, this new Hit is constructed from and associated with

Private Members

const void *base_obj_ptr_

tracer back to the HitObject that is represented by this simplified object

Friends

friend class HitObject

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 OMKey GetOMKey() const

get the OMKey of this object

inline Response GetResponseObj() const

return the ResponseObject

inline bool operator<(const HitObject &rhs) const

for sorting AbsHits we’re mostly interested in their time, and only use their indices as tie-breakers

Hit CreateAssociatedHit() const

Create a Hit from this object.

Private Members

OMKey omkey_

holds the OMKey

Response response_obj_

holds the pulse/lunch/hit/whatever

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

class HiveCleaning

#include <HiveCleaning.h>

The main cleaning class.

Public Functions

HiveCleaning(const HiveCleaning_ParameterSet &params = HiveCleaning_ParameterSet())

Constructor from a ParameterSet.

void Configure(const HiveCleaning_ParameterSet &params)

(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

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

struct HiveGeometry

#include <Hive-lib.h>

Public Members

std::vector<honey::Hive> hives_

knows all the rings around each string

builder::Topology topo_

knows the topology of each dom

class HiveSplitter

#include <HiveSplitter.h>

The main splitter module.

Public Functions

HiveSplitter(const HiveSplitter_ParameterSet &params = HiveSplitter_ParameterSet())

Constructor from a ParameterSet.

void Configure(const HiveSplitter_ParameterSet &params)

(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)

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

class I3GeoDeliver : public I3Module

A Generator Module for to make a I3Geometry.

Public Functions

I3GeoDeliver(const I3Context &context)

void Configure()

void Process()

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

std::string inputName_

PARAM: Name of the pulses to clean in the frame.

std::string outputName_

PARAM: Name of the cleaned pulses to put into the frame.

HiveCleaning_ParameterSet hc_param_set_

PARAMs which are delivered to HiveCleaning.

I3Frame::Stream stream_

PARAM: which stream to execute on.

Private Types

typedef std::vector<Response> ResponseSeries

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

uint64_t n_frames_

uint64_t n_empty_

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

std::string inputName_

PARAM: Name of the pulses to clean in the frame.

std::string outputName_

PARAM: Name of the cleaned pulses to put into the frame.

HiveSplitter_ParameterSet hs_param_set_

PARAMs which are delivered to HiveCleaning.

I3Frame::Stream stream_

PARAM: which stream to execute on.

Private Types

typedef std::vector<Response> ResponseSeries

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

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

std::string inputName_

PARAM: Name of the pulses to split in the frame.

std::string outputName_

PARAM: Name of the pulses to put in the split frames.

std::string trigHierName_

PARAM: Name of the TriggerHierarchy in the frame.

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 std::vector<Response> ResponseSeries

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

uint64_t n_frames_

uint64_t n_splits_

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_

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")

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

inline base Get(const unsigned int indexA, const unsigned int indexB) const

get the value for field

Parameters:

• indexA – this one

• indexB – and this one

inline void Set(const unsigned int indexA, const unsigned int indexB, const base value)

set the value for field

Parameters:

• indexA – this one

• indexB – and this one

• value – to this value

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

internal internal_

thingy holding information

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)

Public Members

double minus_

double plus_

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 Types

typedef I3Map<OMKey, std::vector<Response>> ResponseSeriesMap

Protected Attributes

const I3FramePtr frame_

PARAM: the frame this might have been extracted from.

const std::string key_

PARAM: name of this map in the frame.

boost::shared_ptr<const ResponseSeriesMap> map_

hold a pointer to the OMKeyMap the Hits have been extracted from

const std::deque<HitObject<Response>> hitObjects_

here are the extracted objects

Private Functions

SET_LOGGER ("OMKeyMap_HitFacility")

class RingLimits

#include <IceHiveHelpers.h>

Public Functions

inline RingLimits()

inline RingLimits(const std::vector<LimitPair> &l)

inline void AddLimitPair(const LimitPair &lp)

inline int NRings()

inline LimitPair GetLimitsOnRing(const int r)

Public Members

std::vector<LimitPair> limitPairs_

class StringTopo

#include <Hive-lib.h>

Public Functions

inline unsigned int GetMaxOms() const

inline int GetOmTopo(unsigned int omNbr) const

inline void AddOmTopo(OmTopo omtopo)

Private Members

std::vector<OmTopo> omtopos_

store the oms: is a consecutive register, where

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

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

Private Members

double start_time_

double end_time_

offset_map_t *offsets_

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

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)

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

class TriggerSplitter

#include <TriggerSplitter.h>

The TriggerSplitter Module with the functionality tp split up RecoPulses by trigger information.

Public Functions

TriggerSplitter(const TriggerSplitter_ParameterSet &params = TriggerSplitter_ParameterSet())

Constructor from a ParameterSet.

void Configure(const TriggerSplitter_ParameterSet &params)

(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

static const double default_offset = 200. * I3Units::ns

Generic offset time between DOMLaunch time and pulse.

static const double default_clockcycle = 25. * I3Units::ns

25 ns refers to FPGA clock cycle

Protected Attributes

std::vector<int> configIDs_

PARAM: list of config ids of all the triggers to split on.

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_

struct TriggerSplitter_ParameterSet

#include <TriggerSplitter.h>

A collection of parameters for the TriggerSplitter.

Public Functions

TriggerSplitter_ParameterSet()

Constructor : parameterless.

TriggerSplitter_ParameterSet(const std::vector<int> &configIDs, const double noSplitDt, const double tWindowMinus, const double tWindowPlus)

Constructor : explicit.

Public Members

std::vector<int> configIDs

the configuration-IDs of the triggers which should be considered

double noSplitDt

A padding: when two (same) triggers are close by this value in time, they won’t be split.

double tWindowMinus

A padding in front which will be added to the trigger time.

double tWindowPlus

A padding in the back which will be added to the trigger time.

struct Trigs

a simplifed Trigger representation

Public Functions

inline bool operator<(const Trigs &other) const

comparision operator for time-ordering

Public Members

double time

start time of the trigger firing

double length

length of the trigger

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

Functions

std::string DumpTopology(const Topology &topo)

dump a topology to the a string

Topology ReadTopologyFromFile(const std::string &fileName)

read from a topology from a filedump

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 std::set<Hit> HitSet

typedef std::vector<Hit> HitSeries

typedef std::list<Hit> HitList

typedef std::vector<HitSeries> HitSeriesSeries

typedef std::deque<Hit> HitDeque

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<>
double GetInferredTime(const I3MCHit &r)

template<>
double GetInferredTime(const I3MCPulse &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)

bool RetrievalOrdered(const Hit &h1, const Hit &h2)

need to implement a ordering principle

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

template<class Response, class HitObjectContainer>
I3Map<OMKey, std::vector<Response>> HitObjects_To_OMKeyMap(const HitObjectContainer &hits)

Convert a series of HitObjects back to a native ResponseSeriesMap.

Parameters:

hits – the HitObjects to revert

Returns:

the ResponseMap of reverted Hits

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

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::set<StringNbr> Ring

a set of strings define a ring (around a central string)

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

std::string DumpHive(const Hive &hive)

Dump an entire hive.

Parameters:

hive – the Hive to dump

Returns:

the dumped hive

Hive ReadHiveFromFile(const std::string &fileName)

Reads an entire Hive from a configuration file.

Parameters:

fileName – the path of the file to read from

namespace IC86Topology

Some topological functions useful for the IC86 detector configuration.

Functions

bool IsICDOM(const OMKey &omkey)

Is this a DOM in IceCube?

bool IsDCDOM(const OMKey &omkey)

Is this a DOM in DeepCore?

bool IsVetoCapDOM(const OMKey &omkey)

Is this DOM in the DeepCore Veto layer?

bool IsDCFidDOM(const OMKey &omkey)

Is this DOM in the denser populated DeepCore region?

bool IsVetoCapFidDOM(const OMKey &omkey)

Is this DOM in the denser populated DeepCore-Veto region?

bool IsDCVetoCapFidDOM(const OMKey &omkey)

Is this DOM in any dense populated region?

bool IsIceTopDOM(const OMKey &omkey)

Is this DOM in IceTop?

bool IsICString(const OMKey &omkey)

Is this string a in the regular IceCube array?

bool IsDCString(const OMKey &omkey)

Is this string in the DeepCore array?

bool IsPinguString(const OMKey &omkey)

Is this string in the Pingu (DeepCore infill) array.

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

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

inline bool IsHashable(const StringNbr string, const OmNbr om)

check if pair of string and OM numbers is hashable

Parameters:

• string – string number

• om – OM number

Returns:

boolean that specifies if the pair is hashable

inline bool IsHashable(const OMKey &omkey)

check if OMKey is hashable

Parameters:

omkey – OMKey

Returns:

boolean that specifies if the OMKey is hashable

Variables

static const unsigned int MAX_SIMPLEINDEX = MAX_STRINGS * MAX_OMS - 1

effective number of hashing range

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

Variables

static const LimitPair v_ic[] = {LimitPair(-70., 70.), LimitPair(-70., 70.)}

static const LimitPair v_dc[] = {LimitPair(-70., 70.), LimitPair(-70., 70.)}

static const LimitPair v_p[] = {LimitPair(-70., 70.), LimitPair(-70., 70.)}

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

mzoll marcel.zoll@icecube.wisc.edu

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

mzoll marcel.zoll@icecube.wisc.edu

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:

1. exactly centered at string 36

2. the major axis of the hexagonal grid follows the x-axis

3. all strings are at their exact position in the hexagonal structure

4. The charcteristic inter string spacing is 125 meters

5. the detector center is 1948 meter below the ice-surface

6. OM30 on regular IC-strings rests in the detector XY plane

7. DOMs are spaced 17m in IC, 10/7m in DC

8. IceTop tanks are located exactly on top of the strings at the surface

I3_MODULE(I3GeoDeliver)

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:

1. exactly centered at string 36

2. the major axis of the hexagonal grid follows the x-axis

3. all strings are at their exact position in the hexagonal structure

4. The charcteristic inter string spacing is 125 meters

5. the detector center is 1948 meter below the ice-surface

6. OM30 on regular IC-strings rests in the detector XY plane

7. DOMs are spaced 17m in IC, 10/7m in DC

8. 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]= NAN

Scaleability 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 OMKeys

Running 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_Double

Both 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.