icarus::opdet::DiscretePhotoelectronPulse Class Reference

Precomputed digitized shape of a given function. More...

#include <DiscretePhotoelectronPulse.h>

Public Types
using	gigahertz = util::quantities::gigahertz
using	nanoseconds = util::quantities::nanosecond
using	PulseFunction_t = PhotoelectronPulseFunction< nanoseconds >
	Type of shape (times are in nanoseconds). More...
using	ADCcount = PulseFunction_t::ADCcount
using	Time_t = nanoseconds
using	Tick_t = util::quantities::tick
using	SubsampleIndex_t = gsl::index
	Type of index of subsample. More...
using	Subsample_t = SampledFunction_t::SubsampleData_t
	Type of subsample data (a sampling of the full range). More...

Public Member Functions
	DiscretePhotoelectronPulse (PulseFunction_t const &pulseShape, gigahertz samplingFreq, unsigned int nSubsamples=1U, ADCcount samplingThreshold=1e-6_ADCf)
	Constructor: samples the pulse. More...
std::size_t	pulseLength () const
	Returns the length of the sampled pulse in ticks. More...
ADCcount	operator() (Time_t time) const
	Evaluates the shape at the specified time. More...
bool	checkRange (ADCcount limit, std::string const &outputCat) const
	Checks that the waveform tails not sampled are negligible. More...
Access to subsamples.
A subsample is represented by a forward-iterable object. For example: using namespace util::quantities::time_literals; auto const& subsample = dpp.subsampleFor(5_ns); for (auto sample: subsample) // ... Note Direct iterator access is currently not implemented because the underlying implementation of the subsample object (gsl::span) does not support "borrowing" the data. See the note in util::SampledFunction for more details. The issue should be solved with C++20.
decltype(auto)	subsample (SubsampleIndex_t i) const
	Returns the subsample specified by index i, undefined if invalid. More...
decltype(auto)	subsampleFor (Time_t time) const
SubsampleIndex_t	nSubsamples () const
Functional shape
Returns the function which was sampled.
PulseFunction_t const &	shape () const
ADCcount	peakAmplitude () const
	Returns the peak amplitude in ADC counts. More...
nanoseconds	peakTime () const
	Returns the time at the peak from the beginning of sampling. More...
gigahertz	samplingFrequency () const
	Returns the sampling frequency (same units as entered). More...
nanoseconds	samplingPeriod () const
	Returns the sampling period (inverse of frequency). More...
nanoseconds	duration () const
template<typename Stream >
void	dump (Stream &&out, std::string const &indent, std::string const &firstIndent) const
	Prints on stream the parameters of this shape. More...
template<typename Stream >
void	dump (Stream &&out, std::string const &indent="") const

Private Types
using	SampledFunction_t = util::SampledFunction< nanoseconds, ADCcount >
	Internal discretized representation of the sampled pulse shape. More...

Static Private Member Functions
static SampledFunction_t	sampleShape (PulseFunction_t const &pulseShape, gigahertz samplingFreq, unsigned int nSubsamples, ADCcount threshold)
	Builds the sampling cache. More...

Private Attributes
PulseFunction_t const &	fShape
	Analytical shape of the pules. More...
gigahertz	fSamplingFreq
	Sampling frequency. More...
SampledFunction_t	fSampledShape
	Pulse shape, discretized. More...

Detailed Description

Precomputed digitized shape of a given function.

Multiple samplings ("subsamples") are performed with sub-tick offsets.

The sampled function is of type PhotoelectronPulseFunction<util::quantities::nanosecond> (polymorphic implementations are supported).

A reference to the sampled function is kept available, so that function needs to be valid for the lifetime of this object.

Definition at line 58 of file DiscretePhotoelectronPulse.h.

Member Typedef Documentation

using icarus::opdet::DiscretePhotoelectronPulse::ADCcount = PulseFunction_t::ADCcount

Definition at line 65 of file DiscretePhotoelectronPulse.h.

using icarus::opdet::DiscretePhotoelectronPulse::gigahertz = util::quantities::gigahertz

Definition at line 60 of file DiscretePhotoelectronPulse.h.

using icarus::opdet::DiscretePhotoelectronPulse::nanoseconds = util::quantities::nanosecond

Definition at line 61 of file DiscretePhotoelectronPulse.h.

using icarus::opdet::DiscretePhotoelectronPulse::PulseFunction_t = PhotoelectronPulseFunction<nanoseconds>

Type of shape (times are in nanoseconds).

Definition at line 64 of file DiscretePhotoelectronPulse.h.

using icarus::opdet::DiscretePhotoelectronPulse::SampledFunction_t = util::SampledFunction<nanoseconds, ADCcount>

private

Internal discretized representation of the sampled pulse shape.

Definition at line 74 of file DiscretePhotoelectronPulse.h.

using icarus::opdet::DiscretePhotoelectronPulse::Subsample_t = SampledFunction_t::SubsampleData_t

Type of subsample data (a sampling of the full range).

Definition at line 83 of file DiscretePhotoelectronPulse.h.

using icarus::opdet::DiscretePhotoelectronPulse::SubsampleIndex_t = gsl::index

Type of index of subsample.

Definition at line 80 of file DiscretePhotoelectronPulse.h.

using icarus::opdet::DiscretePhotoelectronPulse::Tick_t = util::quantities::tick

Definition at line 78 of file DiscretePhotoelectronPulse.h.

using icarus::opdet::DiscretePhotoelectronPulse::Time_t = nanoseconds

Definition at line 77 of file DiscretePhotoelectronPulse.h.

Constructor & Destructor Documentation

icarus::opdet::DiscretePhotoelectronPulse::DiscretePhotoelectronPulse ( PulseFunction_t const &  pulseShape, gigahertz  samplingFreq, unsigned int  nSubsamples = 1U, ADCcount  samplingThreshold = 1e-6_ADCf  )

inline

Constructor: samples the pulse.

Parameters

pulseShape	the shape to be pulsed; times in nanoseconds
samplingFreq	frequency of samples [gigahertz]
nSubsamples	(default: 1) the number of samples within a tick
samplingThreshold	(default: 10^-6^) pulse shape ends when its value is below this threshold

Samples start from time 0, which is the time of the start of the first tick. This time is expected to be the arrival time of the photoelectron.

The length of the sampling is determined by the sampling threshold: at the first tick after the peak time where the shape function is below threshold, the sampling ends (that tick under threshold itself is also discarded).

The ownership of pulseShape is acquired by this object.

Definition at line 237 of file DiscretePhotoelectronPulse.h.

  : fShape(pulseShape)
  , fSamplingFreq(samplingFreq)
  , fSampledShape
    (sampleShape(shape(), fSamplingFreq, nSubsamples, samplingThreshold))
  {}

Member Function Documentation

bool icarus::opdet::DiscretePhotoelectronPulse::checkRange	(	ADCcount	limit,
		std::string const &	outputCat
	)		const

Checks that the waveform tails not sampled are negligible.

Parameters

limit	threshold below which the waveform is considered negligible
outputCat	_(default: empty)_ message facility output category to use for messages

Returns

whether the two tails are negligible

If outputCat is empty (default) no message is printed. Otherwise, in case of failure a message is sent to message facility (under category outputCat) describing the failure(s).

Definition at line 84 of file DiscretePhotoelectronPulse.cxx.

{
  assert(pulseLength() > 0);
  auto const low = *(fSampledShape.subsample(0).begin());
  auto const high
    = *(fSampledShape.subsample(fSampledShape.nSubsamples() - 1).rbegin());

  bool const bLowOk = (low.abs() < limit);
  bool const bHighOk = (high.abs() < limit);
  if (bLowOk && bHighOk) return true;
  if (!outputCat.empty()) {
    mf::LogWarning log(outputCat);
    log << "Check on sampled photoelectron waveform template failed!";
    if (!bLowOk) {
      log << "\n => low tail at the starting of sampling is already " << low;
    }
    if (!bHighOk) {
      log
        << "\n => high tail at the end of sampling ("
          << duration() << ") is still at " << high
        ;
    }
    log << "\nShape parameters:" << shape().toString("  ", "");
  } // if writing a message on failure
  return false;
} // icarus::opdet::DiscretePhotoelectronPulse::checkRange()

template<typename Stream >

void icarus::opdet::DiscretePhotoelectronPulse::dump	(	Stream &&	out,
		std::string const &	indent,
		std::string const &	firstIndent
	)		const

Prints on stream the parameters of this shape.

Template Parameters

Stream

type of stream to write into

Parameters

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

Definition at line 251 of file DiscretePhotoelectronPulse.h.

{
  out << firstIndent << "Sampled pulse waveform " << pulseLength()
    << " samples long (" << duration()
    << " long, sampled at " << samplingFrequency()
    << ");"
    << "\n" << shape().toString(indent + "  ", indent);
  fSampledShape.dump(out, indent + "  ", indent);
} // icarus::opdet::DiscretePhotoelectronPulse::dump()

template<typename Stream >

void icarus::opdet::DiscretePhotoelectronPulse::dump ( Stream &&  out, std::string const &  indent = ""  ) const

inline

Definition at line 191 of file DiscretePhotoelectronPulse.h.

    { dump(std::forward<Stream>(out), indent, indent); }

nanoseconds icarus::opdet::DiscretePhotoelectronPulse::duration ( ) const

inline

Returns the duration of the waveform in time units.

See Also

pulseLength()

Definition at line 172 of file DiscretePhotoelectronPulse.h.

{ return pulseLength() * samplingPeriod(); }

SubsampleIndex_t icarus::opdet::DiscretePhotoelectronPulse::nSubsamples ( ) const

inline

Definition at line 147 of file DiscretePhotoelectronPulse.h.

{ return fSampledShape.nSubsamples(); }

ADCcount icarus::opdet::DiscretePhotoelectronPulse::operator() ( Time_t  time ) const

inline

Evaluates the shape at the specified time.

Definition at line 117 of file DiscretePhotoelectronPulse.h.

{ return shape()(time); }

ADCcount icarus::opdet::DiscretePhotoelectronPulse::peakAmplitude ( ) const

inline

Returns the peak amplitude in ADC counts.

Definition at line 159 of file DiscretePhotoelectronPulse.h.

{ return shape().peakAmplitude(); }

nanoseconds icarus::opdet::DiscretePhotoelectronPulse::peakTime ( ) const

inline

Returns the time at the peak from the beginning of sampling.

Definition at line 162 of file DiscretePhotoelectronPulse.h.

{ return shape().peakTime(); }

std::size_t icarus::opdet::DiscretePhotoelectronPulse::pulseLength ( ) const

inline

Returns the length of the sampled pulse in ticks.

Definition at line 114 of file DiscretePhotoelectronPulse.h.

{ return fSampledShape.size(); }

auto icarus::opdet::DiscretePhotoelectronPulse::sampleShape ( PulseFunction_t const &  pulseShape, gigahertz  samplingFreq, unsigned int  nSubsamples, ADCcount  threshold  )

staticprivate

Builds the sampling cache.

Definition at line 25 of file DiscretePhotoelectronPulse.cxx.

{
  using namespace util::quantities::time_literals;
  using namespace icarus::waveform_operations;

  // pick the function according to polarity;
  // the pulse polarity is included in the values,
  // the two functions (lambda) are of different type, so they are being wrapped
  // in the common `std::function` type

  // FIXME Clang 7.0.0 can't figure out the parameters of std::function
  // (GCC 8.2 can): specifying them explicitly...
  auto const isBelowThreshold = (pulseShape.polarity() == +1)
#if defined(__clang__) && (__clang_major__ < 8)
    ? std::function<bool(nanoseconds, ADCcount)>(
#else // not Clang <8
    ? std::function(
#endif // defined(__clang__) && (__clang_major__ < 8)
      [baseline=pulseShape.baseline(), threshold](nanoseconds, ADCcount s)
        {
          return
            PositivePolarityOperations<ADCcount>::subtractBaseline(s, baseline)
              < threshold
            ;
        }
      )
#if defined(__clang__) && (__clang_major__ < 8)
    : std::function<bool(nanoseconds, ADCcount)>(
#else // not Clang <8
    : std::function(
#endif // defined(__clang__) && (__clang_major__ < 8)
      [baseline=pulseShape.baseline(), threshold](nanoseconds, ADCcount s)
        {
          return
            NegativePolarityOperations<ADCcount>::subtractBaseline(s, baseline)
              < threshold
            ;
        }
      )
    ;

  return SampledFunction_t{
    std::cref(pulseShape), // function to sample (by reference because abstract)
    0.0_ns,                // sampling start time
    1.0 / samplingFreq,    // tick duration
    isBelowThreshold,      // when to stop the sampling
    static_cast<gsl::index>(nSubsamples), // how many subsamples per tick
    pulseShape.peakTime() // sample at least until here
    };

} // icarus::opdet::DiscretePhotoelectronPulse::sampleShape()

gigahertz icarus::opdet::DiscretePhotoelectronPulse::samplingFrequency ( ) const

inline

Returns the sampling frequency (same units as entered).

Definition at line 165 of file DiscretePhotoelectronPulse.h.

{ return fSamplingFreq; }

nanoseconds icarus::opdet::DiscretePhotoelectronPulse::samplingPeriod ( ) const

inline

Returns the sampling period (inverse of frequency).

Definition at line 168 of file DiscretePhotoelectronPulse.h.

{ return 1.0 / samplingFrequency(); }

PulseFunction_t const& icarus::opdet::DiscretePhotoelectronPulse::shape ( ) const

inline

Definition at line 156 of file DiscretePhotoelectronPulse.h.

{ return fShape; }

decltype(auto) icarus::opdet::DiscretePhotoelectronPulse::subsample ( SubsampleIndex_t  i ) const

inline

Returns the subsample specified by index i, undefined if invalid.

Definition at line 139 of file DiscretePhotoelectronPulse.h.

    { return fSampledShape.subsample(i); }

decltype(auto) icarus::opdet::DiscretePhotoelectronPulse::subsampleFor ( Time_t  time ) const

inline

Returns the index of the subsample whose tick left limit is closest to time (see util::SampledFunction::closestSubsampleIndex()).

Definition at line 144 of file DiscretePhotoelectronPulse.h.

    { return subsample(fSampledShape.closestSubsampleIndex(time)); }

Member Data Documentation

SampledFunction_t icarus::opdet::DiscretePhotoelectronPulse::fSampledShape

private

Pulse shape, discretized.

Definition at line 215 of file DiscretePhotoelectronPulse.h.

gigahertz icarus::opdet::DiscretePhotoelectronPulse::fSamplingFreq

private

Sampling frequency.

Definition at line 212 of file DiscretePhotoelectronPulse.h.

PulseFunction_t const& icarus::opdet::DiscretePhotoelectronPulse::fShape

private

Analytical shape of the pules.

Definition at line 211 of file DiscretePhotoelectronPulse.h.

---

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

• DiscretePhotoelectronPulse.h
• DiscretePhotoelectronPulse.cxx