Contains all timing reference information for the detector. More...
#include <DetectorClocksData.h>
Public Member Functions | |
DetectorClocksData (double const g4_ref_time, double const trigger_offset_tpc, double const trig_time, double const beam_time, ElecClock const &tpc_clock, ElecClock const &optical_clock, ElecClock const &trigger_clock, ElecClock const &external_clock) | |
Returns a complete detinfo::DetectorClocksData object. More... | |
double | TriggerOffsetTPC () const |
double | TPCTime () const |
double | G4ToElecTime (double const g4_time) const |
double | TriggerTime () const |
Trigger electronics clock time in [us]. More... | |
double | BeamGateTime () const |
Beam gate electronics clock time in [us]. More... | |
ElecClock const & | TPCClock () const noexcept |
Borrow a const TPC clock with time set to Trigger time [us]. More... | |
ElecClock const & | OpticalClock () const noexcept |
Borrow a const Optical clock with time set to Trigger time [us]. More... | |
ElecClock const & | TriggerClock () const noexcept |
Borrow a const Trigger clock with time set to Trigger time [us]. More... | |
ElecClock const & | ExternalClock () const noexcept |
Borrow a const Trigger clock with time set to External Time [us]. More... | |
double | TPCTick2TrigTime (double const tick) const |
double | TPCTick2BeamTime (double const tick) const |
double | OpticalTick2TrigTime (double const tick, size_t const sample, size_t const frame) const |
double | OpticalTick2BeamTime (double const tick, size_t const sample, size_t const frame) const |
double | ExternalTick2TrigTime (double const tick, size_t const sample, size_t const frame) const |
double | ExternalTick2BeamTime (double const tick, size_t const sample, size_t const frame) const |
double | Time2Tick (double const time) const |
Returns the specified electronics time in TDC electronics ticks. More... | |
double | TPCTick2TDC (double const tick) const |
double | TPCG4Time2TDC (double const g4time) const |
double | OpticalTick2TDC (double const tick, size_t const sample, size_t const frame) const |
double | OpticalG4Time2TDC (double const g4time) const |
double | ExternalTick2TDC (double const tick, size_t const sample, size_t const frame) const |
double | ExternalG4Time2TDC (double const g4time) const |
double | TPCTick2Time (double const tick) const |
Given TPC time-tick (waveform index), returns electronics clock [us]. More... | |
double | OpticalTick2Time (double const tick, size_t const sample, size_t const frame) const |
double | ExternalTick2Time (double const tick, size_t const sample, size_t const frame) const |
double | TPCTDC2Tick (double const tdc) const |
Given electronics clock count [tdc] returns TPC time-tick. More... | |
double | TPCG4Time2Tick (double const g4time) const |
Given G4 time returns electronics clock count [tdc]. More... | |
template<typename Stream > | |
void | debugReport (Stream &out) const |
Private Member Functions | |
double | doTPCTime () const |
Implementation of TPCTime() . More... | |
double | doTime2Tick (double const time) const |
Implementation of Time2Tick() . More... | |
Private Attributes | |
double | fTriggerTime |
Trigger time in [us]. More... | |
double | fTriggerOffsetTPC |
Time offset from trigger to TPC readout start. More... | |
double | fBeamGateTime |
BeamGate time in [us]. More... | |
double | fG4RefTime |
Electronics clock counting start time in G4 time frame [us]. More... | |
ElecClock | fTPCClock |
ElecClock | fOpticalClock |
ElecClock | fTriggerClock |
ElecClock | fExternalClock |
Contains all timing reference information for the detector.
The timing information object can be obtained in art from any implementation of detinfo::DetectorClocksService
, and in non-_art_ contexts from any detinfo::DetectorClocks
provider implementation:
in art context without a current event, and better:
in art context when a current event is defined and available.
The content of this object is static and disconnected from the context it was extracted from. The actual timing information can be updated event by event. In general, a new object might be needed for each event or run change.
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:
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)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:
simb::MCParticle
(usually the generators store a single trajectory point for each particle) _[ns]_simb::MCParticle
produced by LArG4
module or equivalent _[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.
While this system is carefully designed to give physicists an headache, detinfo::DetectorClocksData
attempts to tame this complexity by providing methods to convert from one time to the other. Also see detinfo::DetectorTimings
for a higher level interface.
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 | s | |||||
hardware trigger | TriggerTime() | TPCClock() | TriggerClock() | OpticalClock() | ExternalClock() | |||
beam gate point | BeamGateTime() | |||||||
electronics time | Time2Tick() | |||||||
(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 electronics time frames below.
The names are not thoroughly consistent, but they roughly follow the following rules:
TrigTime
(but see below)BeamTime
(but see below)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 frameTDC
G4
or G4Time
TPCTick
is TPC electronics clock ticks, measured from the TPC electronics start timeTick
(without further qualification) is equivalent to "TPCTick" aboveTPC
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)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.
A clock object (ElecClock
) contains settings for a specific hardware clock. DetectorClocksData
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.
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. Definition at line 283 of file DetectorClocksData.h.
|
inline |
Returns a complete detinfo::DetectorClocksData
object.
g4_ref_time | start of simulation time in electronics time scale [ns] |
trigger_offset_tpc | hardware trigger time in electronics time (see the full description below) |
trigger_time | the default hardware trigger time in electronics time |
beam_time | the default beam gate opening time in electronics time |
tpc_clock | use a copy of this as TPC clock object |
optical_clock | use a copy of this as optical detector clock object |
trigger_clock | use a copy of this as trigger clock object |
external_clock | use a copy of this as external clock object |
Details of the definition of the different parameters:
g4_ref_time
is the simulation (Geant4) start time in electronics time scale, i.e. when time 0.0
of simulation happens in the electronics time scale *trigger_offset_tpc
: time elapsed between the start of the TPC readout clock and the hardware trigger; it can be expressed in one of two ways:
For example, trigger_offset_tpc
of -1600.0
means that the TDC clock starts 1.6 milliseconds before the hardware trigger. trigger_offset_tpc
of 3200.0
means that the trigger arrives at the exact start of tick 3200 of the TPC readout. In this example, if the sampling frequency of that readout is 2 MHz, these two settings are equivalent.
Definition at line 326 of file DetectorClocksData.h.
|
inline |
Beam gate electronics clock time in [us].
Definition at line 384 of file DetectorClocksData.h.
|
inline |
Definition at line 577 of file DetectorClocksData.h.
|
inlineprivate |
Implementation of Time2Tick()
.
Definition at line 624 of file DetectorClocksData.h.
|
inlineprivate |
Implementation of TPCTime()
.
Definition at line 617 of file DetectorClocksData.h.
|
inlinenoexcept |
Borrow a const Trigger clock with time set to External Time [us].
Definition at line 424 of file DetectorClocksData.h.
|
inline |
Given G4 time [ns], returns corresponding External electronics clock count [tdc]
Definition at line 528 of file DetectorClocksData.h.
|
inline |
Given External time-tick (waveform index), sample and frame number, returns time [us] w.r.t. beam gate time stamp
Definition at line 472 of file DetectorClocksData.h.
|
inline |
Given External time-tick (waveform index), sample and frame number, returns time electronics clock count [tdc]
Definition at line 521 of file DetectorClocksData.h.
|
inline |
Given External time-tick (waveform index), sample and frame number, returns electronics clock [us]
Definition at line 553 of file DetectorClocksData.h.
|
inline |
Given External time-tick (waveform index), sample and frame number, returns time [us] w.r.t. trigger time stamp
Definition at line 464 of file DetectorClocksData.h.
|
inline |
Given Geant4 time [ns], returns relative time [us] w.r.t. electronics time T0
Definition at line 370 of file DetectorClocksData.h.
|
inlinenoexcept |
Borrow a const Optical clock with time set to Trigger time [us].
Definition at line 404 of file DetectorClocksData.h.
|
inline |
Given G4 time [ns], returns corresponding Optical electronics clock count [tdc]
Definition at line 514 of file DetectorClocksData.h.
|
inline |
Given Optical time-tick (waveform index), sample and frame number, returns time [us] w.r.t. beam gate time stamp
Definition at line 457 of file DetectorClocksData.h.
|
inline |
Given Optical time-tick (waveform index), sample and frame number, returns time electronics clock count [tdc]
Definition at line 507 of file DetectorClocksData.h.
|
inline |
Given Optical time-tick (waveform index), sample and frame number, returns electronics clock [us]
Definition at line 546 of file DetectorClocksData.h.
|
inline |
Given Optical time-tick (waveform index), sample and frame number, returns time [us] w.r.t. trigger time stamp
Definition at line 450 of file DetectorClocksData.h.
|
inline |
Returns the specified electronics time in TDC electronics ticks.
Definition at line 480 of file DetectorClocksData.h.
|
inlinenoexcept |
Borrow a const TPC clock with time set to Trigger time [us].
Definition at line 394 of file DetectorClocksData.h.
|
inline |
Given G4 time [ns], returns corresponding TPC electronics clock count [tdc]
Definition at line 500 of file DetectorClocksData.h.
|
inline |
Given G4 time returns electronics clock count [tdc].
Definition at line 570 of file DetectorClocksData.h.
|
inline |
Given electronics clock count [tdc] returns TPC time-tick.
Definition at line 564 of file DetectorClocksData.h.
|
inline |
Given TPC time-tick (waveform index), returns time [us] w.r.t. beam gate time
Definition at line 443 of file DetectorClocksData.h.
|
inline |
Given TPC time-tick (waveform index), returns electronics clock count [tdc]
Definition at line 493 of file DetectorClocksData.h.
|
inline |
Given TPC time-tick (waveform index), returns electronics clock [us].
Definition at line 539 of file DetectorClocksData.h.
|
inline |
Given TPC time-tick (waveform index), returns time [us] w.r.t. trigger time stamp
Definition at line 436 of file DetectorClocksData.h.
|
inline |
Returns the TPC electronics start time in electronics time.
Definition at line 362 of file DetectorClocksData.h.
|
inlinenoexcept |
Borrow a const Trigger clock with time set to Trigger time [us].
Definition at line 414 of file DetectorClocksData.h.
|
inline |
detinfo::DetectorClocks::TriggerOffsetTPC()
This offset is set via configuration parameter TriggerOffsetTPC
.
Definition at line 350 of file DetectorClocksData.h.
|
inline |
Trigger electronics clock time in [us].
Definition at line 377 of file DetectorClocksData.h.
|
private |
BeamGate time in [us].
Definition at line 605 of file DetectorClocksData.h.
|
private |
Definition at line 613 of file DetectorClocksData.h.
|
private |
Electronics clock counting start time in G4 time frame [us].
Definition at line 608 of file DetectorClocksData.h.
|
private |
Definition at line 611 of file DetectorClocksData.h.
|
private |
Definition at line 610 of file DetectorClocksData.h.
|
private |
Definition at line 612 of file DetectorClocksData.h.
|
private |
Time offset from trigger to TPC readout start.
Definition at line 602 of file DetectorClocksData.h.
|
private |
Trigger time in [us].
Definition at line 599 of file DetectorClocksData.h.