Describes the waveform from a single photoelectron. More...

#include <SampledWaveformFunction.h>

Inheritance diagram for icarus::opdet::SampledWaveformFunction< T >:

Classes
struct	WaveformSpecs_t
	Specifies the waveform shape and features. More...

Public Types
using	ADCcount = typename Base_t::ADCcount
	Type for ADC counts (floating point). More...

using	Time = typename Base_t::Time
	Type of time being used. More...

Public Types inherited from icarus::opdet::PhotoelectronPulseFunction< T >
using	ADCcount = util::quantities::counts_f
	Type for ADC counts (floating point). More...

using	Time = T
	Type of time being used. More...

Public Member Functions
	SampledWaveformFunction (WaveformSpecs_t specs, Time peakTime, float gain)
	Constructor: initializes from an hard-coded shape. More...

Parameter accessors.
float	gain () const
	Returns the gain the waveform is representing. More...

Public Member Functions inherited from icarus::opdet::PhotoelectronPulseFunction< T >
virtual	~PhotoelectronPulseFunction ()=default

ADCcount	evaluateAt (Time time) const
	Evaluates the pulse at the given time. More...

ADCcount	operator() (Time time) const
	Alias of `evaluateAt()`. More...

Time	peakTime () const
	Returns the time at which the first peak is found. More...

ADCcount	peakAmplitude () const
	Returns the amplitude of the first peak in ADC counts. More...

ADCcount	baseline () const
	Returns the baseline of the pulse in ADC counts. More...

int	polarity () const
	Returns the polarity of the pulse (`+1`: positive, or `-1`: negative). More...

void	dump (std::ostream &out, std::string const &indent, std::string const &firstIndent) const
	Prints on stream the parameters of this shape. More...

void	dump (std::ostream &&out, std::string const &indent="") const

std::string	toString (std::string const &indent, std::string const &firstIndent) const
	Returns the parameters of this shape as a descriptive string. More...

std::string	toString (std::string const &indent="") const

Private Types
using	Base_t = icarus::opdet::PhotoelectronPulseFunction< T >

Private Member Functions
Time	sampleDuration () const
	The duration of each sample. More...

virtual ADCcount	doEvaluateAt (Time time) const override
	Evaluates the pulse at the given time. More...

virtual Time	doPeakTime () const override
	Returns the time at which the first peak is found. More...

virtual ADCcount	doPeakAmplitude () const override
	Returns the amplitude of the first peak in ADC. More...

virtual void	doDump (std::ostream &out, std::string const &indent, std::string const &firstIndent) const override
	Prints on stream the parameters of this shape. More...

bool	hasSample (std::ptrdiff_t index) const
	Returns whether a sample with the specified index is within the range. More...

ADCcount	integral () const
	Returns the integral of the waveform. More...

std::vector< ADCcount >	buildSamples (float targetGain) const
	Transforms the input waveform. More...

Static Private Member Functions
static std::size_t	findPeak (std::vector< ADCcount > const &samples)
	Returns the index of the sample under the peak of the waveform. More...

Private Attributes
WaveformSpecs_t const	fSource
	Waveform information. More...

std::vector< ADCcount > const	fSamples
	All samples. More...

float const	fGain
	The gain this waveform represents. More...

std::size_t const	fPeakSample
	The sample with the absolute peak. More...

Time const	fRefTime
	The time of the start of sample #0. More...

Additional Inherited Members
Protected Member Functions inherited from icarus::opdet::PhotoelectronPulseFunction< T >
virtual ADCcount	doEvaluateAt (Time time) const =0
	Implementation of the function evaluation at `time`. More...

virtual ADCcount	doBaseline () const
	Returns the baseline of the pulse. More...

virtual int	doPolarity () const
	Returns the polarity of the pulse (+1 or -1). More...

Detailed Description

template<typename T>
class icarus::opdet::SampledWaveformFunction< T >

Describes the waveform from a single photoelectron.

Template Parameters

T	type of time unit to be used

This functor (class behaving like a function) describes the shape of the response to a single photoelectron in a non-analytical form from a sequence of samples.

The peak time is assigned to the sample with the largest value.

See more details in the constructor.

Definition at line 34 of file SampledWaveformFunction.h.

Member Typedef Documentation

template<typename T >

using icarus::opdet::SampledWaveformFunction< T >::ADCcount = typename Base_t::ADCcount

Type for ADC counts (floating point).

Definition at line 58 of file SampledWaveformFunction.h.

template<typename T >

using icarus::opdet::SampledWaveformFunction< T >::Base_t = icarus::opdet::PhotoelectronPulseFunction<T>

private

Definition at line 54 of file SampledWaveformFunction.h.

template<typename T >

using icarus::opdet::SampledWaveformFunction< T >::Time = typename Base_t::Time

Type of time being used.

Definition at line 60 of file SampledWaveformFunction.h.

Constructor & Destructor Documentation

template<typename T >

icarus::opdet::SampledWaveformFunction< T >::SampledWaveformFunction	(	WaveformSpecs_t	specs,
		Time	peakTime,
		float	gain
	)

Constructor: initializes from an hard-coded shape.

Parameters

waveformSpecs	all information on the single photoelectron response
peakTime	time to assign to the peak
gain	the gain of the optical detector

The shape described in waveformSpecs is shifted in time so that evaluation at peakTime (evaluateAt(peakTime)) returns the peak amplitude; more precisely, peakTime is set to match the start of the largest sample.

The gain is rescaled starting from the one in the waveform specifications.

The polarity of the waveform is deduced by the value at peak.

Definition at line 177 of file SampledWaveformFunction.h.

   : fSource    { std::move(waveformSpecs) }
   , fSamples   { buildSamples(gain) }
   , fGain      { gain }
   , fPeakSample{ findPeak(fSamples) }
   , fRefTime   { peakTime - fPeakSample * sampleDuration() }
   {}

Member Function Documentation

template<typename T >

auto icarus::opdet::SampledWaveformFunction< T >::buildSamples ( float targetGain ) const

private

Transforms the input waveform.

Parameters

waveform	input waveform (in millivolt and for a known gain)
targetGain	the desired gain

Returns: a sequence of samples in ADC

The returned waveform has the same time domain as the input one, but is expressed in ADC instead of voltage (conversion is perfectly linear, 2 V across 14 bits), and rescaled to meet the target gain.

Definition at line 231 of file SampledWaveformFunction.h.

 {
   
   /*
    * Sample conversion
    * ------------------
    * 
    * The waveform is expected in millivolt, and it expresses the response with/
    * the photodetector set at a known gain.
    * Our target is a waveform in ADC and the target gain in argument.
    * The conversion factor is based on the full range of the digitizer,
    * that is 2 V across 14 bit.
    */
   constexpr float VoltageRange = 2'000.0; // millivolt
   constexpr unsigned short int ADCbits = 14;
   
   // 2 V in 14 bits (=> 8.192):
   constexpr float mVtoADC = (1 << ADCbits) / VoltageRange;
   
   // if either the starting gain is unknown or the target gain is not specified,
   // do not scale the gain
   float const gainFactor = (fSource.gain != 0.0 && targetGain != 0.0)
     ? (targetGain / fSource.gain): 1.0;
   float const factor = gainFactor * mVtoADC;
   
   auto voltageToADC = [factor](float mV)
     { return static_cast<ADCcount>(factor * mV); };
   
   std::vector<ADCcount> samples;
   samples.reserve(fSource.samples.size());
   std::transform(fSource.samples.begin(), fSource.samples.end(),
     back_inserter(samples), voltageToADC);
   
   return samples;
   
 } // icarus::opdet::SampledWaveformFunction<>::buildSamples()

template<typename T >

void icarus::opdet::SampledWaveformFunction< T >::doDump	(	std::ostream &	out,
		std::string const &	indent,
		std::string const &	firstIndent
	)		const

overrideprivatevirtual

Prints on stream the parameters of this shape.

Parameters

out	the stream to write into
indent	indentation string, prepended to all lines except first
indentFirst	indentation string prepended to the first line

Reimplemented from icarus::opdet::PhotoelectronPulseFunction< T >.

Definition at line 199 of file SampledWaveformFunction.h.

 {
   
   out << firstIndent
       << "Pulse '" << fSource.name << "' (v. " << fSource.version
       << ", " << fSource.date << "):"
     << "\n" << indent << "  " << fSource.description
     << "\n" << indent
       << "  from " << fSamples.size() << "x " << sampleDuration() << " samples"
       << ", peak at " << Base_t::peakTime()
       << " with amplitude " << Base_t::peakAmplitude()
     << "\n" << indent
       << "  start at " << fRefTime << ", gain " << fGain
       << " (integral: " << integral() << ")"
     << '\n'
     ;
   
 } // icarus::opdet::SampledWaveformFunction<>::doDump()

template<typename T >

auto icarus::opdet::SampledWaveformFunction< T >::doEvaluateAt ( Time time ) const

overrideprivatevirtual

Evaluates the pulse at the given time.

Parameters

time	time to evaluate the shape at

The scale of the time is defined by the peak time passed at construction.

Definition at line 188 of file SampledWaveformFunction.h.

 {
   std::ptrdiff_t const iSample = static_cast<std::ptrdiff_t>
     (std::floor((time - fRefTime)/sampleDuration()));
   return hasSample(iSample)? fSamples[iSample]: ADCcount{ 0 };
 } // icarus::opdet::SampledWaveformFunction<>::doEvaluateAt()

template<typename T >

virtual ADCcount icarus::opdet::SampledWaveformFunction< T >::doPeakAmplitude ( ) const

inlineoverrideprivatevirtual

Returns the amplitude of the first peak in ADC.

Reimplemented from icarus::opdet::PhotoelectronPulseFunction< T >.

Definition at line 129 of file SampledWaveformFunction.h.

130 { return fSamples[fPeakSample]; }

icarus::opdet::SampledWaveformFunction::fPeakSample

std::size_t const fPeakSample

The sample with the absolute peak.

Definition: SampledWaveformFunction.h:107

icarus::opdet::SampledWaveformFunction::fSamples

std::vector< ADCcount > const fSamples

All samples.

Definition: SampledWaveformFunction.h:103

template<typename T >

virtual Time icarus::opdet::SampledWaveformFunction< T >::doPeakTime ( ) const

inlineoverrideprivatevirtual

Returns the time at which the first peak is found.

Implements icarus::opdet::PhotoelectronPulseFunction< T >.

Definition at line 125 of file SampledWaveformFunction.h.

126 { return fRefTime + fPeakSample * sampleDuration(); }

icarus::opdet::SampledWaveformFunction::fRefTime

Time const fRefTime

The time of the start of sample #0.

Definition: SampledWaveformFunction.h:109

icarus::opdet::SampledWaveformFunction::sampleDuration

Time sampleDuration() const

The duration of each sample.

Definition: SampledWaveformFunction.h:112

icarus::opdet::SampledWaveformFunction::fPeakSample

std::size_t const fPeakSample

The sample with the absolute peak.

Definition: SampledWaveformFunction.h:107

template<typename T >

std::size_t icarus::opdet::SampledWaveformFunction< T >::findPeak ( std::vector< ADCcount > const & samples )

staticprivate

Returns the index of the sample under the peak of the waveform.

Definition at line 272 of file SampledWaveformFunction.h.

 {
   assert(!samples.empty());
   auto const sbegin = samples.begin();
   auto const [ min, max ] = std::minmax_element(sbegin, samples.end());
   // assume baseline 0:
   return ((min->abs() > max->abs())? min: max) - sbegin;
 } // icarus::opdet::SampledWaveformFunction<T>::findPeak()