Conversion of times between different formats and references. More...

#include "DetectorClocks.h"

Inheritance diagram for detinfo::DetectorClocks:

Public Member Functions
	DetectorClocks (const DetectorClocks &)=delete

	DetectorClocks (DetectorClocks &&)=delete

DetectorClocks &	operator= (const DetectorClocks &)=delete

DetectorClocks &	operator= (DetectorClocks &&)=delete

virtual	~DetectorClocks ()=default

Configuration information
virtual std::vector< std::string >	ConfigNames () const =0

virtual std::vector< double >	ConfigValues () const =0

Time points and intervals
virtual double	TriggerOffsetTPC () const =0
	Time offset from hardware trigger to TPC electronics start time. More...

virtual double	TriggerTime () const =0
	Harware trigger time (in electronics time frame) [µs]. More...

virtual double	TPCTime () const =0
	Returns the TPC electronics start time in electronics time. More...

virtual double	BeamGateTime () const =0
	Beam gate opening time (in electronics time frame) [µs]. More...

Time conversions
virtual double	G4ToElecTime (double g4_time) const =0
	Given a simulation time [ns], converts it into electronics time [µs]. More...

virtual double	TPCTick2TrigTime (double tick) const =0
	Converts a TPC time (in ticks) into a trigger time [µs]. More...

virtual double	TPCTick2BeamTime (double tick) const =0
	Converts a TPC time (in ticks) into a beam gate time [µs]. More...

Electronics clocks
The clocks are also the main route to discover the sampling frequency and the period of the electronics. For example: double const opticalTickDuration = OpticalClock().TickPeriod(); will retrieve the "official" optical detector clock period. All times from the clocks (including frame lengths) are measured in microseconds, and all the frequencies are measured in megahertz. Clock objects (`detinfo::ElecClock`) are not bound to any reference time. When specifying a time in one of their methods, whatever the reference of that time is, that is also the reference of the values returned by those methods. The same is true for the time set into the clock at construction: when using one of the methods where no time is required, the time set by `ElecClock::SetTime()` or at construction is used, and whatever the reference of that time is, that is also the reference of the values returned by those methods. Some overview information on clocks is given in the Clocks section of this documentation.
virtual const ::detinfo::ElecClock &	TPCClock () const =0
	Lends a constant TPC clock with time set to trigger time. More...

virtual ::detinfo::ElecClock	TPCClock (double time) const =0
	Returns a TPC clock with time set to the specified time. More...

virtual detinfo::ElecClock	TPCClock (unsigned int sample, unsigned int frame) const =0
	Returns a TPC clock with time set to the specified time sample. More...

virtual const detinfo::ElecClock &	OpticalClock () const =0
	Lends a constant optical clock with time set to trigger time. More...

virtual detinfo::ElecClock	OpticalClock (double time) const =0
	Returns a optical clock with time set to the specified time. More...

virtual detinfo::ElecClock	OpticalClock (unsigned int sample, unsigned int frame) const =0
	Returns a optical clock with time set to the specified time sample. More...

virtual const detinfo::ElecClock &	TriggerClock () const =0
	Lends a constant trigger clock with time set to trigger time. More...

virtual detinfo::ElecClock	TriggerClock (double time) const =0
	Returns a trigger clock with time set to the specified time. More...

virtual detinfo::ElecClock	TriggerClock (unsigned int sample, unsigned int frame) const =0
	Returns a trigger clock with time set to the specified time sample. More...

virtual const detinfo::ElecClock &	ExternalClock () const =0
	Lends a constant external clock with time set to trigger time. More...

virtual detinfo::ElecClock	ExternalClock (double time) const =0
	Returns a external clock with time set to the specified time. More...

virtual detinfo::ElecClock	ExternalClock (unsigned int sample, unsigned int frame) const =0
	Returns a external clock with time set to the specified time sample. More...

Conversions from electronics waveform ticks
This section includes also conversions from electronics waveform ticks to other waveform ticks.
virtual double	TPCTDC2Tick (double tdc) const =0
	Given electronics clock count [tdc] returns TPC time-tick. More...

virtual double	TPCTick2TDC (double tick) const =0
	Converts a TPC time tick into a electronics time tick. More...

virtual double	TPCTick2Time (double tick) const =0
	Converts a TPC electronics tick into electronics time [µs]. More...

virtual double	OpticalTick2TrigTime (double tick, size_t sample, size_t frame) const =0
	Converts an optical time tick into a trigger time [µs]. More...

virtual double	OpticalTick2BeamTime (double tick, size_t sample, size_t frame) const =0
	Converts an optical time tick into a beam gate time [µs]. More...

virtual double	OpticalTick2TDC (double tick, size_t sample, size_t frame) const =0
	Converts an optical time tick into ticks from the first optical frame. More...

virtual double	OpticalTick2Time (double tick, size_t sample, size_t frame) const =0
	Converts an optical time tick into time from the first optical frame [µs]. More...

virtual double	ExternalTick2TrigTime (double tick, size_t sample, size_t frame) const =0
	Converts an external time tick into a trigger time [µs]. More...

virtual double	ExternalTick2BeamTime (double tick, size_t sample, size_t frame) const =0
	Converts an external time tick into a beam gate time [µs]. More...

virtual double	ExternalTick2TDC (double tick, size_t sample, size_t frame) const =0
	Given External time-tick (waveform index), sample and frame number, returns time electronics clock count [tdc]. More...

virtual double	ExternalTick2Time (double tick, size_t sample, size_t frame) const =0
	Converts an external time tick into time from the first external frame [µs]. More...

Conversions to electronics waveform ticks
The conversion methods to waveform ticks from other electronics waveform ticks are listed elsewhere, together with all the conversions from electronics ticks.
virtual double	TPCG4Time2TDC (double g4time) const =0
	Converts simulation time into a electronics time tick. More...

virtual double	TPCG4Time2Tick (double g4time) const =0
	Converts simulation time into a TPC electronics time tick. More...

virtual double	OpticalG4Time2TDC (double g4time) const =0
	Converts a simulation time into optical electronics time ticks. More...

virtual double	ExternalG4Time2TDC (double g4time) const =0
	Converts a simulation time into external electronics time ticks. More...

Protected Member Functions
	DetectorClocks ()=default

Detailed Description

Conversion of times between different formats and references.

Valuable and very complete documentation on LArSoft timing is described for MicroBooNE by Herbert Greenlee on a document of October 2017 (DocDB 12290). The content in there includes MicroBooNE-specific and general information, and the former is usually clearly distinguished from the latter.

The following information is more terse and aimed to the documentation of this service provider rather than to the more general topic of timing in LArSoft.

Time definitions

Many different components contribute to the operation of a LArTPC, and more are needed for the simulation. Some of the relevant events and time points associated with time are:

hardware trigger: the instant the trigger happens or is expected; data acquisition reacts at this time (multi-event)
beam gate opening: the instant the beam particles are expected to enter the detector (multi-event)
software trigger: additional logic can provide a more detailed estimation of the physics event time; this usually comes too late for the electronics time to be defined by it (multi-event)
electronics start time: a reference time instant; this is usually matching the instant the TPC readout starts recording raw digits (multi-event)
TPC electronics start time: the instant corresponding to the first sample of the raw digits from TPC; for untampered raw::RawDigit objects, this time matches the general electronics start time definition, and for the model of data acquisition described here, this time is by definition function of the hardware trigger. Trimmed raw::RawDigit with a start portion clipped away will break the assumption of electronics time matching the TPC one (which is defined as seen by raw::RawDigit) (multi-event)
other electronics start times (optical detector, cosmic ray tagger, etc.) represent the instant the respective data acquisition subsystems start digitizing the data from their detectors (multi-event)
event trigger: the instant the physics event is detected (in reconstruction jargon this is a $t_{0}$ ); ideally, for most events involving beam particles this is the a little after beam gate opening, and on top of the hardware trigger (per event)
charge collection: the instant the ionisation from a particle reaches the charge readout (per particle)
photon collection: the instant scintillation photons from a particle reaches the optical readout (per particle)
physics event time: the instant the main interaction happens; this is assigned by the event generator (per event)
Geant4 time start: assigned to each particle by the simulation of propagation through matter (Geant4); note that this is not necessarily the same as the event time. (per event)

In parentheses, it is indicated if such instant is defined for each considered particle, or for the complete physics process ("event") or for all physics processes recorded in the same time window ("multi-event").

We can also define many ways to measure these times with respect to the others. We use the following time scales and frames:

electronics time: from the electronics start time; this is the "glue" time frame connecting most of the others [µs]
TPC time: from the TPC electronics start time [µs]
other electronics times ( optical electronics time, external electronics time, etc.): from the respective start times; note that in LArSoft the definition of these times is not fully defined (see below). [µs]
beam gate time: from the beam gate opening time [µs]
trigger time: from the hardware trigger [µs]
event time: from an event trigger [µs]
generation time: from the time the generators assigns to the main physics event; this is stored in the trajectory points of simb::MCParticle (usually the generators store a single trajectory point for each particle) [ns]
Geant4 time: from the Geant4 time start; this is stored into each trajectory point of simb::MCParticle produced by LArG4 module or equivalent [ns]
simulation time: the same as Geant4 time (and also generation time, which in LArSoft happens to match the former) [ns]

The list above reports in square brackets the "standard" unit, used for that times in that scale by all LArSoft code unless explicitly specified otherwise. For the times bound to readout, there is also an equivalent tick count time (from the TDC), which is an integral value representing the number of elapsed sampling periods of the detector they refer too (and that period may be different for each piece of hardware). Be sure to read the documentation about the methods you want to use to convert ticks, because their implications and assumptions may be quite subtle.

Time conversions

While this system is carefully designed to give physicists an headache, the detinfo::DetectorClocks service provider attempts to tame this complexity by providing methods to convert from one time to the other.

The following table represents the available conversion functions, with the time in the first column as the time to be converted and in the columns the times to convert to:

to →	electronics time	(ticks)	TPC time ticks	trigger time	trigger clock ticks	beam gate time	Optical clock ticks	External clock ticks
(unit)	µs			µs	`TriggerClock()`	µs
hardware trigger	`TriggerTime()`	`TPCClock()`					`OpticalClock()`	`ExternalClock()`
beam gate point	`BeamGateTime()`
electronics time
(ticks)			`TPCTDC2Tick()`
TPC time
(ticks)	`TPCTick2Time()`	`TPCTick2TDC()`		`TPCTick2TrigTime()`		`TPCTick2BeamTime()`
trigger time
(ticks)
Optical
(ticks)	`OpticalTick2Time()`	`OpticalTick2TDC()`		`OpticalTick2TrigTime()`		`OpticalTick2BeamTime()`
External
(ticks)	`ExternalTick2Time()`	`ExternalTick2TDC()`		`ExternalTick2TrigTime()`		`ExternalTick2BeamTime()`
simulation time	`G4ToElecTime()`	`TPCG4Time2TDC()`	`TPCG4Time2Tick()`				`OpticalG4Time2TDC()`	`ExternalG4Time2TDC()`

Note that the complete definition of optical and external time requires additional information: see the note on electonics time frames below.

The names are not thoroughly consistent, but they roughly follow the following rules:

the "trigger time" is named as TrigTime (but see below)
the "beam time" is named as BeamTime (but see below)
the electronics time is named simply as Time; note that e.g. TriggerTime() and BeamGateTime() must be read as Trigger and BeamGate plus Time(), that is they return a Time value (i.e., electronics time) of the hardware trigger instant and beam gate opening instant, in the electronics time frame
the electronics time ticks are labelled TDC
the simulation time is labelled G4 or G4Time
TPCTick is the TPC electronics clock ticks", measured from the @ref DetectorClocksTPCelectronicsTime "TPC electronics start time"
TPC is usually used in conjunction with Tick, where it means TPCTick; but in TPCG4Time2TDC() it is a misnomer (the TDC wins in that the result is in ticks in electronics time reference, not in TPC electronics time)

Note on electronics time frames

The conversion of some electronic time ticks, especially the optical and external ones, assumes that the tick values to be converted are relative to an arbitrary reference, meaning that the absolute (or, e.g., electronics) time for tick 0 is not centrally defined. Instead, it is expected that additional information is provided to locate when this tick 0 actually happens. This is usually done via another pair of arguments, the frame number and the sample number within that frame. In the end, this just moves the questions to when frame 0 sample 0 happens: as those are input arguments, that absolute reference is left to the caller to define; but usually it is referring to the electronics start time.

Clocks

A clock object (detinfo::ElecClock) contains settings for a specific hardware clock. DetectorClocks provides four clock objects:

clock name	purpose	default time
`TPCClock()`	TPC readout and "general" electronics	`TriggerTime()`
`OpticalClock()`	optical detector electronics	`TriggerTime()`
`TriggerClock()`	hardware trigger electronics	`TriggerTime()`
`ExternalClock()`	not specified	`TriggerTime()`

A clock object does not change the time frame: in the conversions between times and ticks, and the other way around, it always assumes that at tick 0 (and frame 0, sample 0, if needed), the time is also 0 (see the note on electronics time frames above). Therefore, once again, a clock object does not help in converting between different time scales, and the output times are in the same time frame as the input.

The "default time" is the time the clock is set when returned by the methods with no argument (e.g. TriggerClock()).

All times (including frame lengths) are measured in microseconds, and all the frequencies are measured in megahertz.

TPCClock() deals with TPC readout, and the "electronics time" clock is defined to have the same parameters as the TPC readout one.

Note: The TriggerClock() clock has little in common with TriggerTime(): the former is an electronics setting for a piece of hardware generating the trigger, while the latter is the instant the hardware trigger actually happened.

Note on configuration (and for implementers)

detinfo::DetectorClocks is an abstract interface enclosing the set of supported queries. A concrete implementation of this interface needs to be provided in order to use this facility. LArSoft provides detinfo::DetectorClocksStandard as a simple, reasonable implementation. Initialization and configuration are designed by each implementation.

Todo:: Add a method to convert electronics time tick into electronics time.

Definition at line 298 of file DetectorClocks.h.

Constructor & Destructor Documentation

detinfo::DetectorClocks::DetectorClocks ( const DetectorClocks & )

delete

detinfo::DetectorClocks::DetectorClocks ( DetectorClocks && )

delete

virtual detinfo::DetectorClocks::~DetectorClocks ( )

virtualdefault

detinfo::DetectorClocks::DetectorClocks ( )

protecteddefault

Member Function Documentation

virtual double detinfo::DetectorClocks::BeamGateTime ( ) const

pure virtual

Beam gate opening time (in electronics time frame) [µs].

Implemented in detinfo::DetectorClocksStandard.

virtual std::vector<std::string> detinfo::DetectorClocks::ConfigNames ( ) const

pure virtual

Returns a list of provider configuration names.

See also: ConfigValues()

Implemented in detinfo::DetectorClocksStandard.

virtual std::vector<double> detinfo::DetectorClocks::ConfigValues ( ) const

pure virtual

Returns a list of provider configuration values (same order as ConfigNames()).

See also: ConfigNames()

Implemented in detinfo::DetectorClocksStandard.

virtual const detinfo::ElecClock& detinfo::DetectorClocks::ExternalClock ( ) const

pure virtual

Lends a constant external clock with time set to trigger time.

Returns: a constant reference to the external clock class

See also: clock notes

This clock has the same timing settings as the external electronics.

The clock can be used to convert into time the number of ticks or a sample in a frame, and vice versa.

The current time of this object can't be changed, and it is set to the trigger time, in the same time scale as TriggerTime(), that is electronics time.

Implemented in detinfo::DetectorClocksStandard.

virtual detinfo::ElecClock detinfo::DetectorClocks::ExternalClock ( double time ) const

pure virtual

Returns a external clock with time set to the specified time.

Parameters

time	the current time of the new clock [µs]

Returns: a clock class with external electronics timing settings

See also: clock notes

This clock has the same timing settings as the external electronics.

The clock can be used to convert into time the number of ticks or a sample in a frame, and vice versa. The current time of this object is set to the specified time, and it can be set to any value afterwards.

Implemented in detinfo::DetectorClocksStandard.

virtual detinfo::ElecClock detinfo::DetectorClocks::ExternalClock	(	unsigned int	sample,
		unsigned int	frame
	)		const

pure virtual

Returns a external clock with time set to the specified time sample.

Parameters

sample	number of sample of the clock time
frame	number of the frame the selected sample belongs to

Returns: a clock class with external electronics settings

See also: clock notes

This clock represents the "external" readout. It can be used to convert into time the number of ticks or a sample in a frame, and vice versa.

The current time of this object is set to the time specified as frame and sample number, and it can be set to any value afterwards.

Implemented in detinfo::DetectorClocksStandard.

virtual double detinfo::DetectorClocks::ExternalG4Time2TDC ( double g4time ) const

pure virtual

Converts a simulation time into external electronics time ticks.

Parameters

g4time simulation time value [ns]

Returns: number of external electronics time ticks from the electronics start time for the specified time

See also: G4ToElecTime(), OpticalG4Time2TDC(), ExternalClock()

This method is similar to OpticalG4Time2TDC(), with the difference that external electronics time is used instead of the optical one.

Implemented in detinfo::DetectorClocksStandard.

virtual double detinfo::DetectorClocks::ExternalTick2BeamTime	(	double	tick,
		size_t	sample,
		size_t	frame
	)		const

pure virtual

Converts an external time tick into a beam gate time [µs].

Parameters

tick	the tick number within the external waveform
sample	start sample of the external waveform
frame	start frame of the external waveform

Returns: beam gate time of the specified tick [µs]

See also: OpticalTick2BeamTime(), ExternalTick2TrigTime(), ExternalClock()

This method works like ExternalTick2TrigTime(), but it returns the result as beam gate time (instead of trigger time).

Implemented in detinfo::DetectorClocksStandard.

virtual double detinfo::DetectorClocks::ExternalTick2TDC	(	double	tick,
		size_t	sample,
		size_t	frame
	)		const

pure virtual

Given External time-tick (waveform index), sample and frame number, returns time electronics clock count [tdc].

Converts an external time tick into ticks from electronics start time

Parameters

tick	the tick number within the external waveform
sample	start sample of the external waveform
frame	start frame of the external waveform

Returns: external clock ticks from the electronics start time

See also: ExternalTick2TrigTime(), OpticalTick2TDC(), ExternalClock()

This method works like OpticalTick2TDC(), but it pertains a waveform recorded using the external clock (ExternalClock()) instead of the optical one (OpticalClock()).

Implemented in detinfo::DetectorClocksStandard.

virtual double detinfo::DetectorClocks::ExternalTick2Time	(	double	tick,
		size_t	sample,
		size_t	frame
	)		const

pure virtual

Converts an external time tick into time from the first external frame [µs].

Parameters

tick	the tick number within the external waveform
sample	start sample of the external waveform
frame	start frame of the external waveform

Returns: time elapsed from the starting frame (see below) [µs]

See also: OpticalTick2TDC(), OpticalTick2TrigTime(), ExternalTick2Time(), OpticalClock()

This method is similar to OpticalTick2Time(), but it refers to the external electronics time and uses the external clock (ExternalClock()) instead of the optical one (OpticalClock()).

As stated more extensively in OpticalTick2Time() documentation, **with the assumption that sample 0 of frame 0 happens at electronics start time, the return value of this method is in electronic time frame.**

Implemented in detinfo::DetectorClocksStandard.

virtual double detinfo::DetectorClocks::ExternalTick2TrigTime	(	double	tick,
		size_t	sample,
		size_t	frame
	)		const

pure virtual

Converts an external time tick into a trigger time [µs].

Parameters

tick	the tick number within the external waveform
sample	start sample of the external waveform
frame	start frame of the external waveform

Returns: trigger time of the specified tick [µs]

See also: OpticalTick2TrigTime(), ExternalTick2BeamTime(), ExternalClock()

This method works like OpticalTick2TrigTime(), but it pertains a waveform recorded using the external clock (ExternalClock()) instead of the optical one (OpticalClock()).

Implemented in detinfo::DetectorClocksStandard.

virtual double detinfo::DetectorClocks::G4ToElecTime ( double g4_time ) const

pure virtual

Given a simulation time [ns], converts it into electronics time [µs].

Implemented in detinfo::DetectorClocksStandard.

Referenced by detsim::SimDriftElectrons::produce().

DetectorClocks& detinfo::DetectorClocks::operator= ( const DetectorClocks & )

delete

DetectorClocks& detinfo::DetectorClocks::operator= ( DetectorClocks && )

delete

virtual const detinfo::ElecClock& detinfo::DetectorClocks::OpticalClock ( ) const

pure virtual

Lends a constant optical clock with time set to trigger time.

Returns: a constant reference to the optical clock class

See also: clock notes

This clock has the same timing settings as the optical readout electronics.

The clock can be used to convert into time the number of ticks or a sample in a frame, and vice versa.

The current time of this object can't be changed, and it is set to the trigger time, in the same time scale as TriggerTime(), that is electronics time.

Implemented in detinfo::DetectorClocksStandard.

Referenced by opdet::ConstructFlash(), and opdet::ConstructHit().

virtual detinfo::ElecClock detinfo::DetectorClocks::OpticalClock ( double time ) const

pure virtual

Returns a optical clock with time set to the specified time.

Parameters

time	the current time of the new clock [µs]

Returns: a clock class with optical readout electronics timing settings

See also: clock notes

This clock has the same timing settings as the optical readout electronics.

The clock can be used to convert into time the number of ticks or a sample in a frame, and vice versa. The current time of this object is set to the specified time, and it can be set to any value afterwards.

Implemented in detinfo::DetectorClocksStandard.

virtual detinfo::ElecClock detinfo::DetectorClocks::OpticalClock	(	unsigned int	sample,
		unsigned int	frame
	)		const

pure virtual

Returns a optical clock with time set to the specified time sample.

Parameters

sample	number of sample of the clock time
frame	number of the frame the selected sample belongs to

Returns: a clock class with optical readout electronics settings

See also: clock notes

This clock represents the optical readout. It can be used to convert into time the number of ticks or a sample in a frame, and vice versa. The current time of this object is set to the time specified as frame and sample number, and it can be set to any value afterwards.

Implemented in detinfo::DetectorClocksStandard.

virtual double detinfo::DetectorClocks::OpticalG4Time2TDC ( double g4time ) const

pure virtual

Converts a simulation time into optical electronics time ticks.

Parameters

g4time simulation time value [ns]

Returns: number of optical electronics time ticks from the electronics start time for the specified time

See also: G4ToElecTime(), ExternalG4Time2TDC(), OpticalClock()

Note that the result is the number of optical ticks (OpticalClock()) from the electronics start time (not the optical electronics start time, which is in fact not absolutely defined).

The result is a real number including a fractional part describing how far within the tick the specified instant g4time is. To effectively have the tick number, truncate the value, e.g.:

auto tick = static_cast<int>(detClocks->OpticalG4Time2TDC(simTime));

Implemented in detinfo::DetectorClocksStandard.

virtual double detinfo::DetectorClocks::OpticalTick2BeamTime	(	double	tick,
		size_t	sample,
		size_t	frame
	)		const

pure virtual

Converts an optical time tick into a beam gate time [µs].

Parameters

tick	the tick number within the optical waveform
sample	start sample of the optical waveform
frame	start frame of the optical waveform

Returns: beam gate time of the specified tick [µs]

See also: OpticalTick2TrigTime(), OpticalTick2TDC(), ExternalTick2BeamTime(), OpticalClock()

This method works like OpticalTick2TrigTime(), but it returns the result as beam gate time (instead of trigger time).

Implemented in detinfo::DetectorClocksStandard.

virtual double detinfo::DetectorClocks::OpticalTick2TDC	(	double	tick,
		size_t	sample,
		size_t	frame
	)		const

pure virtual

Converts an optical time tick into ticks from the first optical frame.

Parameters

tick	the tick number within the optical waveform
sample	start sample of the optical waveform
frame	start frame of the optical waveform

Returns: optical clock ticks elapsed from the starting frame

See also: OpticalTick2TrigTime(), ExternalTick2TDC(), OpticalClock()

The definition of method arguments is the same as in OpticalTick2TrigTime(). This method returns the total number of optical clock ticks elapsed since the first tick, marked as sample 0 of frame 0. Frame and tick periods are defined by the OpticalClock().

Note that while this method does not assume any absolute time point for the frame 0 (see the note on electronics time frames), that time point should nevertheless be assumed to be the electronics start time for consistency with the arguments from other methods like OpticalTick2TrigTime().

Implemented in detinfo::DetectorClocksStandard.

virtual double detinfo::DetectorClocks::OpticalTick2Time	(	double	tick,
		size_t	sample,
		size_t	frame
	)		const

pure virtual

Converts an optical time tick into time from the first optical frame [µs].

Parameters

tick	the tick number within the optical waveform
sample	start sample of the optical waveform
frame	start frame of the optical waveform

Returns: time elapsed from the starting frame (see below) [µs]

See also: OpticalTick2TDC(), OpticalTick2TrigTime(), ExternalTick2Time(), OpticalClock()

This method is similar to OpticalTick2TDC(), but the result is in an absolute time interval rather than a tick count.

The note in OpticalTick2TDC() is also valid: while this method does not assume any absolute time point for the frame 0 (see the note on electronics time frames), that time point should nevertheless be assumed to be the electronics start time for consistency with the arguments from other methods like OpticalTick2TrigTime(). **With that assumption, the return value is in electronic time frame.**

Implemented in detinfo::DetectorClocksStandard.

virtual double detinfo::DetectorClocks::OpticalTick2TrigTime	(	double	tick,
		size_t	sample,
		size_t	frame
	)		const

pure virtual

Converts an optical time tick into a trigger time [µs].

Parameters

tick	the tick number within the optical waveform
sample	start sample of the optical waveform
frame	start frame of the optical waveform

Returns: trigger time of the specified tick [µs]

See also: OpticalTick2BeamTime(), OpticalTick2TDC(), ExternalTick2TrigTime(), OpticalClock()

The idea is that we have a optical waveform which starts at a given frame number, and at sample number within that frame. Given a tick number within that waveform, this method returns the trigger time corresponding at the start of that tick.

More explicitly: tick is the number of tick in the waveform, measured from the start of the waveform, which is tick = 0; this start point of the waveform is specified by a frame and a sample, where the sample 0 of frame 0 is the electronics start time. Both sample and ticks are defined using the period of the optical clock (OpticalClock()), and the frame is defined from the same clock as well.

Implemented in detinfo::DetectorClocksStandard.

virtual const ::detinfo::ElecClock& detinfo::DetectorClocks::TPCClock ( ) const

pure virtual

Lends a constant TPC clock with time set to trigger time.

Returns: a constant reference to the TPC clock object

See also: clock notes

This clock has the same timing settings as the TPC channel readout electronics (which ultimately fills raw::RawDigit objects).

The clock can be used to convert into time the number of ticks or a sample in a frame, and vice versa.

The current time of this object can't be changed, and it is set to the trigger time, in the same time scale as TriggerTime(), that is electronics time.

Implemented in detinfo::DetectorClocksStandard.

Referenced by detsim::SimDriftElectrons::beginJob(), detinfo::DetectorPropertiesStandard::DetectorPropertiesStandard(), larg4::LArVoxelReadout::LArVoxelReadout(), and detinfo::DetectorPropertiesStandard::UpdateClocks().

virtual ::detinfo::ElecClock detinfo::DetectorClocks::TPCClock ( double time ) const

pure virtual

Returns a TPC clock with time set to the specified time.

Parameters

time	the current time of the new clock [µs]

Returns: a clock class with TPC readout electronics timing settings

See also: clock notes

This clock has the same timing settings as the TPC channel readout electronics (which ultimately fills raw::RawDigit objects).

The clock can be used to convert into time the number of ticks or a sample in a frame, and vice versa. The current time of this object is set to the specified time, and it can be set to any value afterwards.

Implemented in detinfo::DetectorClocksStandard.

virtual detinfo::ElecClock detinfo::DetectorClocks::TPCClock	(	unsigned int	sample,
		unsigned int	frame
	)		const

pure virtual

Returns a TPC clock with time set to the specified time sample.

Parameters

sample	number of sample of the clock time
frame	number of the frame the selected sample belongs to

Returns: a clock class with TPC readout electronics settings

See also: clock notes

This clock represents the TPC channel readout (which ultimately fills raw::RawDigit objects). It can be used to convert into time the number of ticks or a sample in a frame, and vice versa. The current time of this object is set to the time specified as frame and sample number, and it can be set to any value afterwards.

Implemented in detinfo::DetectorClocksStandard.

virtual double detinfo::DetectorClocks::TPCG4Time2TDC ( double g4time ) const

pure virtual

Converts simulation time into a electronics time tick.

Parameters

g4time simulation time [ns]

Returns: electronics time tick, including a fractional part

The result is a real number including a fractional part describing how far within the tick the specified instant g4time is. To effectively have the tick number, truncate the value, e.g.:

auto tick = static_cast<int>(detClocks->TPCG4Time2TDC(simTime));

Implemented in detinfo::DetectorClocksStandard.

virtual double detinfo::DetectorClocks::TPCG4Time2Tick ( double g4time ) const

pure virtual

Converts simulation time into a TPC electronics time tick.

Parameters

g4time simulation time [ns]

Returns: TPC electronics time tick, including a fractional part

The result is a real number including a fractional part describing how far within the tick the specified instant g4time is. To effectively have the tick number, truncate the value, e.g.:

auto tick = static_cast<int>(detClocks->TPCG4Time2Tick(simTime));

Implemented in detinfo::DetectorClocksStandard.

virtual double detinfo::DetectorClocks::TPCTDC2Tick ( double tdc ) const

pure virtual

Given electronics clock count [tdc] returns TPC time-tick.

Converts an electronics time tick into a TPC time tick.

Parameters

tdc	an electronics time tick

Returns: the TPC time tick corresponding to tdc

See also: TPCClock(), TPCTime()

Implemented in detinfo::DetectorClocksStandard.

Referenced by detinfo::DetectorPropertiesStandard::ConvertTDCToTicks(), and hit::HitAnaAlg::FindAndStoreMCHitsInRange().

virtual double detinfo::DetectorClocks::TPCTick2BeamTime ( double tick ) const

pure virtual

Converts a TPC time (in ticks) into a beam gate time [µs].

Implemented in detinfo::DetectorClocksStandard.

virtual double detinfo::DetectorClocks::TPCTick2TDC ( double tick ) const

pure virtual

Converts a TPC time tick into a electronics time tick.

Parameters

tick	the tick number within the TPC waveform

Returns: the specified tick in electronics time ticks

See also: TPCTick2Time(), TPCClock()

The idea is that we have a TPC waveform. Given a tick number within that waveform, this method returns the electronics time corresponding to the start of that tick, but in TPC clock ticks (TPCClock()).

More explicitly: tick is the number of tick in the waveform, measured from the start of the waveform, which is tick = 0; the start point of this waveform is the TPC electronics start time.

Implemented in detinfo::DetectorClocksStandard.

Referenced by hit::MCHitAnaExample::analyze(), lar::example::AnalysisExample::analyze(), cheat::BackTracker::ChannelToTrackIDEs(), detinfo::DetectorPropertiesStandard::ConvertTicksToTDC(), cheat::BackTracker::HitToAvgSimIDEs(), cheat::BackTracker::HitToSimIDEs_Ps(), btutil::MCBTAlg::MCQ(), and detsim::SimWireT962::produce().

virtual double detinfo::DetectorClocks::TPCTick2Time ( double tick ) const

pure virtual

Converts a TPC electronics tick into electronics time [µs].

Parameters

tick	tick from the beginning of the TPC waveform

Returns: the electronics time for that tick [µs]

See also: TPCTime(), TPCClock()

Note that the start of the TPC waveform is defined by TPCTime().

Implemented in detinfo::DetectorClocksStandard.

virtual double detinfo::DetectorClocks::TPCTick2TrigTime ( double tick ) const

pure virtual

Converts a TPC time (in ticks) into a trigger time [µs].

Implemented in detinfo::DetectorClocksStandard.

Referenced by calo::LinearEnergyAlg::CalculateHitEnergy().

virtual double detinfo::DetectorClocks::TPCTime ( ) const

pure virtual

Returns the TPC electronics start time in electronics time.

Implemented in detinfo::DetectorClocksStandard.

virtual const detinfo::ElecClock& detinfo::DetectorClocks::TriggerClock ( ) const

pure virtual

Lends a constant trigger clock with time set to trigger time.

Returns: a constant reference to the trigger clock class

See also: clock notes

This clock has the same timing settings as the trigger electronics. Note that, despite the name, the clock tick 0 is not the trigger time itself, but the electronics start time (trigger time is measured in that frame: see TriggerTime()).

The clock can be used to convert into time the number of ticks or a sample in a frame, and vice versa.

The current time of this object can't be changed, and it is set to the trigger time, in the same time scale as TriggerTime(), that is electronics time.

Implemented in detinfo::DetectorClocksStandard.

virtual detinfo::ElecClock detinfo::DetectorClocks::TriggerClock ( double time ) const

pure virtual

Returns a trigger clock with time set to the specified time.

Parameters

time	the current time of the new clock [µs]

Returns: a clock class with trigger electronics timing settings

See also: clock notes

This clock has the same timing settings as the trigger electronics. Note that, despite the name, the clock tick 0 is not the trigger time itself, but the electronics start time (trigger time is measured in that frame: see TriggerTime()).

The clock can be used to convert into time the number of ticks or a sample in a frame, and vice versa. The current time of this object is set to the specified time, and it can be set to any value afterwards.

Implemented in detinfo::DetectorClocksStandard.

virtual detinfo::ElecClock detinfo::DetectorClocks::TriggerClock	(	unsigned int	sample,
		unsigned int	frame
	)		const

pure virtual

Returns a trigger clock with time set to the specified time sample.

Parameters

sample	number of sample of the clock time
frame	number of the frame the selected sample belongs to

Returns: a clock class with trigger electronics settings

See also: clock notes

This clock represents the trigger readout. It can be used to convert into time the number of ticks or a sample in a frame, and vice versa. Note that, despite the name, the clock tick 0 is not the trigger time itself, but the electronics start time (trigger time is measured in that frame: see TriggerTime()).

The current time of this object is set to the time specified as frame and sample number, and it can be set to any value afterwards.

Implemented in detinfo::DetectorClocksStandard.

virtual double detinfo::DetectorClocks::TriggerOffsetTPC ( ) const

pure virtual

Time offset from hardware trigger to TPC electronics start time.

Returns: time from hardware trigger to TPC electronics [µs]

This is the time the TPC readout starts, with respect to the harware trigger time. This is also the time where the TPC clock starts, again respect to the trigger time.

When negative, it means the TDC electronics clock started before the trigger. And it'd better be negative... or your readout missed the trigger!

Implemented in detinfo::DetectorClocksStandard.

Referenced by detinfo::DetectorPropertiesStandard::TriggerOffset().

virtual double detinfo::DetectorClocks::TriggerTime ( ) const

pure virtual

Harware trigger time (in electronics time frame) [µs].

Implemented in detinfo::DetectorClocksStandard.

Referenced by opdet::ConstructFlash(), and opdet::ConstructHit().

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