org.lcsim.util

Class OverlayDriver

java.lang.Object

org.lcsim.util.Driver

org.lcsim.util.OverlayDriver

public class OverlayDriver
extends Driver

Driver to overlay one or more events from another SLCIO source over the current event. A bunch train can be modeled by setting the number of bunch crossings and the time between those bunch crossings. The number of events overlaid per bunch crossing is drawn from a Poisson distribution and its mpv is set by the weight. Time windows can be set for each collection to model a realistic readout. They control which hits to keep and are applied relative to the time of the original event plus a time of flight correction. A separate collection of McParticles is created only for the particles from the overlaid events.

Author:

Christian Grefe

Nested Class Summary

Nested classes/interfaces inherited from class org.lcsim.util.Driver

Driver.AbortRunException, Driver.NextEventException

Field Summary

Fields

Modifier and Type	Field and Description
protected List<MCParticle>	allMcParticles
protected org.apache.commons.math.distribution.PoissonDistribution	backgroundDistribution
protected int	bunchCrossings
protected double	bunchSpacing
protected static double	c
protected Map<String,Map<Long,SimCalorimeterHit>>	caloHitMap
protected boolean	fullCaloProcessing
protected static SpacePoint	interactionPoint
protected String	mcOverlayName
protected Map<MCParticle,MCParticle>	mcParticleReferences
protected String	mcSignalName
protected LCIOEventSource	overlayEvents
protected List<Integer>	overlayList
protected List<MCParticle>	overlayMcParticles
protected double	overlayWeight
protected boolean	randomizeOverlay
protected boolean	randomizeTrainOverlay
protected boolean	randomSignal
protected Map<String,Double>	readoutTimes
protected boolean	signalAtZero
protected int	signalBunchCrossing
protected double	signalTime
protected double	tofCaloOffset

Fields inherited from class org.lcsim.util.Driver

HLEVEL_DEFAULT, HLEVEL_FULL, HLEVEL_HIGH, HLEVEL_NORMAL, HLEVEL_OFF

Constructor Summary

Constructors

Constructor and Description
OverlayDriver() Default constructor

Method Summary

Methods

Modifier and Type	Method and Description
protected void	addOverlayMcParticle(MCParticle particle) Copies an mc particle and stores it together with the copy in a map.
void	clearReadoutTimes() Removes all readout times that were set.
static MCParticle	copyMcParticle(MCParticle mcParticle) Deep copy of an mc particle.
protected SimCalorimeterHit	copySimCalorimeterHit(SimCalorimeterHit hit, EventHeader.LCMetaData meta, boolean hasPDG) Deep copy of an SimCalorimeterHit.
protected SimTrackerHit	copySimTrackerHit(SimTrackerHit hit, EventHeader.LCMetaData meta) Deep copy of an SimTrackerHit.
protected void	detectorChanged(Detector detector) Called by the framework before process method when the detector geometry changes.
protected void	endOfData() Called when all data processing is finished.
protected static double	getLosTof(Hit hit) Calculates the time of flight from the interaction point to the position of the given hit along a straight line.
protected static EventHeader	getNextEvent(LCIOEventSource lcio) Goes to the next event in the LCIOEventSource and returns it.
protected boolean	mergeCollections(EventHeader.LCMetaData collection, EventHeader.LCMetaData overlayCollection, double overlayTime) Merges two collections and applies a time offset to all entries in the overlay collection.
protected void	mergeEvents(EventHeader event, EventHeader overlayEvent, double overlayTime) Merges all collections from the given events and applies a time offset to all entries in all collections of the overlay event.
protected List	moveCollectionToTime(EventHeader.LCMetaData collection, double time) Shifts a collection in time.
protected void	moveEventToTime(EventHeader event, double time) Shifts an event in time.
protected void	process(EventHeader event) Called by the framework to process an event.
protected void	putCollection(EventHeader.LCMetaData collection, List entries, EventHeader event) Adds a collection to an event using the meta data information from the given collection and the entries from the given list.
void	setBunchCrossings(int n) Sets the number of bunch crossings in a train.
void	setBunchSpacing(double t) Sets the time between two bunch crossings.
void	setFullCaloProcessing(boolean fullCaloProcessing) Selects if calorimeter hits are treated in full detail or simplified.
void	setOverlayFiles(String[] fileList)
void	setOverlayName(String name) Sets a name as an identifier for the overlaid events.
void	setOverlayWeight(double weight) Sets the number of overlay event used per bunch crossing.
void	setRandomizeOverlay(boolean randomizeOverlay) Selects if overlay events are read in random order from the overlay event source.
void	setRandomizeTrainOverlay(boolean randomizeTrainOverlay) Selects if the overlay events are randomly placed within the bunch train instead of in a serial way
void	setReadoutTime(String[] collection) Sets the readout time window for an LCCollection.
void	setShuffleOverlay(boolean shuffleOverlay) Deprecated. replaced by setShuffleTrainOverlay
void	setSignalAtZero(boolean signalAtZero) Selects if the time of the signal event is placed at time 0, so that all other bunch crossings are shifted accordingly.
void	setSignalBunchCrossing(int bunchCrossing) Sets the bunch crossing of the signal event.
void	setSignalName(String name) Sets a name as an identifier for the signal events.
protected static EventHeader	skipEvents(LCIOEventSource lcio, int nEvents) Returns the event from the LCIOEventSource after skipping a given number of events.
protected void	startOfData() Called before the first event is processed, or after a rewind.
protected void	suspend() Called by the framework when event processing is suspended.

Methods inherited from class org.lcsim.util.Driver

add, clearStatistics, contains, doProcess, drivers, getConditionsManager, getHistogramLevel, getLogger, getName, getRandom, pathToMother, printStatistics, processChildren, remove, resume, setHistogramLevel, setLogLevel, setRandom

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

c

protected static double c

interactionPoint

protected static SpacePoint interactionPoint

tofCaloOffset

protected double tofCaloOffset

bunchCrossings

protected int bunchCrossings

bunchSpacing

protected double bunchSpacing

randomSignal

protected boolean randomSignal

fullCaloProcessing

protected boolean fullCaloProcessing

randomizeTrainOverlay

protected boolean randomizeTrainOverlay

randomizeOverlay

protected boolean randomizeOverlay

signalAtZero

protected boolean signalAtZero

signalTime

protected double signalTime

signalBunchCrossing

protected int signalBunchCrossing

mcOverlayName

protected String mcOverlayName

mcSignalName

protected String mcSignalName

overlayEvents

protected LCIOEventSource overlayEvents

overlayWeight

protected double overlayWeight

overlayList

protected List<Integer> overlayList

backgroundDistribution

protected org.apache.commons.math.distribution.PoissonDistribution backgroundDistribution

readoutTimes

protected Map<String,Double> readoutTimes

caloHitMap

protected Map<String,Map<Long,SimCalorimeterHit>> caloHitMap

overlayMcParticles

protected List<MCParticle> overlayMcParticles

allMcParticles

protected List<MCParticle> allMcParticles

mcParticleReferences

protected Map<MCParticle,MCParticle> mcParticleReferences

Constructor Detail

OverlayDriver

public OverlayDriver()

Default constructor

Method Detail

setBunchCrossings

public void setBunchCrossings(int n)

Sets the number of bunch crossings in a train. This is the maximum number of bunch crossings overlaid, independent of readout times.

Parameters:

n - the number of bunch crossings in a bunch train, default is 1

setBunchSpacing

public void setBunchSpacing(double t)

Sets the time between two bunch crossings.

Parameters:

t - the time between two bunch crossings in ns, default is 1 ns

setSignalBunchCrossing

public void setSignalBunchCrossing(int bunchCrossing)

Sets the bunch crossing of the signal event. In case of a negative value the bunch crossing will be selected randomly. In case of a value higher than the total amount of bunch crossings in a train it will be placed in the last bunch crossing. Default is a random bunch crossing. crossing.

Parameters:

bunchCrossing - the bunch crossing of the signal event

setOverlayName

public void setOverlayName(String name)

Sets a name as an identifier for the overlaid events. It names the sub collection used to identify the overlaid McParticles.

Parameters:

name - identifier for the overlay events

setSignalName

public void setSignalName(String name)

Sets a name as an identifier for the signal events. It names the sub collection used to identify the signal McParticles.

Parameters:

name - identifier for the overlay events

setOverlayWeight

public void setOverlayWeight(double weight)

Sets the number of overlay event used per bunch crossing. The actual number per event is drawn from a Poisson distribution with the weight being the most probable value of the distribution. A weight of 0 will instead add one overlay event per bunch crossing.

Parameters:

weight - the most probable number of overlay events added per bunch crossing

setOverlayFiles

public void setOverlayFiles(String[] fileList)

setReadoutTime

public void setReadoutTime(String[] collection)

Sets the readout time window for an LCCollection. The list of strings has to have an exact length of two with the following pattern: "CollectionName time", where the time is given in ns.

Parameters:

collection - a string of the form "CollectionName time"

clearReadoutTimes

public void clearReadoutTimes()

Removes all readout times that were set.

setFullCaloProcessing

public void setFullCaloProcessing(boolean fullCaloProcessing)

Selects if calorimeter hits are treated in full detail or simplified. The simple mode just takes the time of the first contribution in a SimCalorimeterHit in order to check if it falls into a relevant time window (keeping all contributions). The full mode checks all contributions and only keeps those inside the time window.

Parameters:

fullCaloProcessing - use full detailed mode (default false)

setShuffleOverlay

public void setShuffleOverlay(boolean shuffleOverlay)

Deprecated. replaced by setShuffleTrainOverlay

Parameters:

shuffleOverlay -

setRandomizeTrainOverlay

public void setRandomizeTrainOverlay(boolean randomizeTrainOverlay)

Selects if the overlay events are randomly placed within the bunch train instead of in a serial way

Parameters:

shuffleOverlay - shuffle the overlay events (default true)

setRandomizeOverlay

public void setRandomizeOverlay(boolean randomizeOverlay)

Selects if overlay events are read in random order from the overlay event source.

Parameters:

randomizeOverlay -

setSignalAtZero

public void setSignalAtZero(boolean signalAtZero)

Selects if the time of the signal event is placed at time 0, so that all other bunch crossings are shifted accordingly. Otherwise the first bunch crossing is at time 0 and the signal event at the time of its bunch crossing.

Parameters:

signalAtZero - set time of signal to 0 (default true)

startOfData

protected void startOfData()

Description copied from class: Driver

Called before the first event is processed, or after a rewind.

Overrides:

startOfData in class Driver

detectorChanged

protected void detectorChanged(Detector detector)

Description copied from class: Driver

Called by the framework before process method when the detector geometry changes. This method is gauranteed to be called once before the first call to process.

Overrides:

detectorChanged in class Driver

process

protected void process(EventHeader event)

Description copied from class: Driver

Called by the framework to process an event. Don't forget to call super.process(event) to cause the child processes to be executed. In addition the process event call can throw some special exceptions:

• NextEventException - aborts further processing of this event
• StopRunException - causes event processing to be stopped

Overrides:

process in class Driver

Parameters:

event - The event to be processed

See Also:

Driver.NextEventException, Driver.AbortRunException

suspend

protected void suspend()

Description copied from class: Driver

Called by the framework when event processing is suspended.

Overrides:

suspend in class Driver

endOfData

protected void endOfData()

Description copied from class: Driver

Called when all data processing is finished.

Overrides:

endOfData in class Driver

getNextEvent

protected static EventHeader getNextEvent(LCIOEventSource lcio)

Goes to the next event in the LCIOEventSource and returns it. If the end of the source is reached, the source is rewound and the first event will be returned. If any other error occurs, i.e. the source does not exist, null is returned instead.

Parameters:

lcio - The LCIO source

Returns:

The next event in the LCIO file

skipEvents

protected static EventHeader skipEvents(LCIOEventSource lcio,
                     int nEvents)

Returns the event from the LCIOEventSource after skipping a given number of events. If the end of the source is reached, the source is rewound and the remaining events are skipped counting from the first event. If any other error occurs, i.e. the source does not exist, null is returned instead.

Parameters:

lcio - The LCIO source

nEvents - The number of events to skip

Returns:

getLosTof

protected static double getLosTof(Hit hit)

Calculates the time of flight from the interaction point to the position of the given hit along a straight line.

Parameters:

hit -

putCollection

protected void putCollection(EventHeader.LCMetaData collection,
                 List entries,
                 EventHeader event)

Adds a collection to an event using the meta data information from the given collection and the entries from the given list.

Parameters:

collection - the collection to take the meta data from

entries - the list of entries to put into the event

event - the event to put the collection

moveEventToTime

protected void moveEventToTime(EventHeader event,
                   double time)

Shifts an event in time. Moves all entries in all collections in the event by the given offset in time.

Parameters:

event - the event to move in time

time - the time shift applied to all entries in all collections

moveCollectionToTime

protected List moveCollectionToTime(EventHeader.LCMetaData collection,
                        double time)

Shifts a collection in time. Moves all entries in the collection by the given offset in time. If a readout time is set for the given collection, all entries outside of that window will be removed.

Parameters:

collection - the collection to move in time

time - the time shift applied to all entries in the collection

Returns:

returns the list of moved entries

mergeEvents

protected void mergeEvents(EventHeader event,
               EventHeader overlayEvent,
               double overlayTime)

Merges all collections from the given events and applies a time offset to all entries in all collections of the overlay event.

Parameters:

event - the event where everything is merged into

overlayEvent - the event overlaid

overlayTime - the time offset for the overlay event

addOverlayMcParticle

protected void addOverlayMcParticle(MCParticle particle)

Copies an mc particle and stores it together with the copy in a map. Adds it to the list of mc particles as well as the overlay mc particles. Also copies and keeps all ancestors.

Parameters:

event -

particle -

copyMcParticle

public static MCParticle copyMcParticle(MCParticle mcParticle)

Deep copy of an mc particle. Necessary in order to be able to close an overlay event. The parent and daught relations are not set for the copied mc particle. Because those should most likely also point to copies this should be handled somewhere else.

Parameters:

mcParticle - The mc particle to be copied

Returns:

the copied mc particle

copySimTrackerHit

protected SimTrackerHit copySimTrackerHit(SimTrackerHit hit,
                              EventHeader.LCMetaData meta)

Deep copy of an SimTrackerHit. Necessary in order to be able to close an overlay event.

Parameters:

hit - The hit to be copied

meta - The meta data that will be attached to the hit

Returns:

The copied SimTrackerHit

copySimCalorimeterHit

protected SimCalorimeterHit copySimCalorimeterHit(SimCalorimeterHit hit,
                                      EventHeader.LCMetaData meta,
                                      boolean hasPDG)

Deep copy of an SimCalorimeterHit. Necessary in order to be able to close an overlay event.

Parameters:

hit - The hit to be copied

meta - The meta data that will be attached to the hit

hasPDG - Flag if the pdg code of the mc contriutions should be saved

Returns:

The copied SimCalorimeterHit

mergeCollections

protected boolean mergeCollections(EventHeader.LCMetaData collection,
                       EventHeader.LCMetaData overlayCollection,
                       double overlayTime)

Merges two collections and applies a time offset to all entries in the overlay collection.

Parameters:

collection - the collection where the overlay collection is merged into

overlayCollection - the collection overlaid

overlayTime - the time offset for the overlay collection

Returns:

returns false if unable to merge collections, otherwise true