LArSoft  v06_85_00
Liquid Argon Software toolkit - http://larsoft.org/
detinfo::DetectorClocks Class Referenceabstract

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

#include "DetectorClocks.h"

Inheritance diagram for detinfo::DetectorClocks:
detinfo::DetectorClocksStandard

Public Member Functions

 DetectorClocks (const DetectorClocks &)=delete
 
 DetectorClocks (DetectorClocks &&)=delete
 
DetectorClocksoperator= (const DetectorClocks &)=delete
 
DetectorClocksoperator= (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::ElecClockTPCClock () 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::ElecClockOpticalClock () 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::ElecClockTriggerClock () 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::ElecClockExternalClock () 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:

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
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
timethe 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
samplenumber of sample of the clock time
framenumber 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
g4timesimulation 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
tickthe tick number within the external waveform
samplestart sample of the external waveform
framestart 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
tickthe tick number within the external waveform
samplestart sample of the external waveform
framestart 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
tickthe tick number within the external waveform
samplestart sample of the external waveform
framestart 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
tickthe tick number within the external waveform
samplestart sample of the external waveform
framestart 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
timethe 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
samplenumber of sample of the clock time
framenumber 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
g4timesimulation 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
tickthe tick number within the optical waveform
samplestart sample of the optical waveform
framestart 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
tickthe tick number within the optical waveform
samplestart sample of the optical waveform
framestart 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
tickthe tick number within the optical waveform
samplestart sample of the optical waveform
framestart 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
tickthe tick number within the optical waveform
samplestart sample of the optical waveform
framestart 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
timethe 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
samplenumber of sample of the clock time
framenumber 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
g4timesimulation 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
g4timesimulation 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
tdcan 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
tickthe 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
ticktick 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
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
timethe 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
samplenumber of sample of the clock time
framenumber 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

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