icarus::opdet::CustomPulseFunction< T > Class Template Reference

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

#include <CustomPulseFunction.h>

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

Classes
struct	PulseStats_t
	Record of collected information on the pulse shape. 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...
using	ParameterValue_t = double
	Type of value for parameters (TFormula). More...
using	NameAndValue_t = std::pair< std::string, ParameterValue_t >
	Type of parameter name/value definition. More...
using	PulseParameters_t = std::vector< NameAndValue_t >
	Type of list of all function parameters. 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
	CustomPulseFunction (std::string const &expression, PulseParameters_t const &parameters, Time peakTime)
	Constructor: chooses shape and the values of its parameters. More...
	CustomPulseFunction (std::string const &expression, PulseParameters_t const &parameters, std::string const &peakTime)
Parameter accessors.
ParameterValue_t	parameter (std::string const &name) const
	Returns the value of the parameter specified by name. 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
	CustomPulseFunction (std::string const &expression, PulseParameters_t const &parameters)
	Constructor implementation. 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 counts. 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...
PulseStats_t	extractStats (Time peakTime) const
	Extracts statistics from pulse shape. More...

Static Private Member Functions
static std::string	checkMissingParameters (TFormula const &formula, PulseParameters_t const &parameters)
static std::string	checkExcessParameters (TFormula const &formula, PulseParameters_t const &parameters)
static void	setParameters (TFormula &formula, PulseParameters_t const &parameters)
	Sets the value of the parameters of formula. More...

Private Attributes
TFormula	fFormula
	Formula of the shape. More...
PulseStats_t	fStats
	Collected information about the pulse. 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::CustomPulseFunction< T >

Describes the waveform from a single photoelectron.

Template Parameters

Time	type of time unit to be used

This functor (class behaving like a function) describes the shape of the response to a single photoelectron as a custom shape.

The shape is a formula interpreted via ROOT's TFormula. It is assumed to start at time 0.0 (in Time units).

Definition at line 38 of file CustomPulseFunction.h.

Member Typedef Documentation

template<typename T >

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

Type for ADC counts (floating point).

Definition at line 61 of file CustomPulseFunction.h.

template<typename T >

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

private

Definition at line 57 of file CustomPulseFunction.h.

template<typename T >

using icarus::opdet::CustomPulseFunction< T >::NameAndValue_t = std::pair<std::string, ParameterValue_t>

Type of parameter name/value definition.

Definition at line 68 of file CustomPulseFunction.h.

template<typename T >

using icarus::opdet::CustomPulseFunction< T >::ParameterValue_t = double

Type of value for parameters (TFormula).

Definition at line 65 of file CustomPulseFunction.h.

template<typename T >

using icarus::opdet::CustomPulseFunction< T >::PulseParameters_t = std::vector<NameAndValue_t>

Type of list of all function parameters.

Definition at line 71 of file CustomPulseFunction.h.

template<typename T >

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

Type of time being used.

Definition at line 63 of file CustomPulseFunction.h.

Constructor & Destructor Documentation

template<typename T >

icarus::opdet::CustomPulseFunction< T >::CustomPulseFunction	(	std::string const &	expression,
		PulseParameters_t const &	parameters,
		Time	peakTime
	)

Constructor: chooses shape and the values of its parameters.

Parameters

expression	mathematical expression of pulse shape
parameters	the list of named parameters and their values
peakTime	expression of time of the maximum amplitude of the shape

The shape mathematical expression must be compatible with ROOT 6 TFormula. The formula must have a single independent variable, time measured in the Time scale. The value 0 of that time corresponds to when the photoelectron is emitted from the photocathode.

The peak time argument is used to report when the peak happens. It would be possible to compute it in a general way, but the implementation of that functionality is complicate enough to get it right and fast, that it's better to rely on user's knowledge. The value may be either a number or a string. The number (Time) directly represents the time of the peak, while the expression is another TFormula expression that can use the same parameters as the shape expression, so that for example it is possible to indicate the peak time of a shape like exp(-(x - [mu])**2) as [mu]. In this case, the peak time expression must use no variable.

Definition at line 197 of file CustomPulseFunction.h.

  : CustomPulseFunction(expression, parameters)
{
  fStats = extractStats(peakTime);
} // icarus::opdet::CustomPulseFunction<>::CustomPulseFunction(Time)

template<typename T >

icarus::opdet::CustomPulseFunction< T >::CustomPulseFunction	(	std::string const &	expression,
		PulseParameters_t const &	parameters,
		std::string const &	peakTime
	)

Definition at line 210 of file CustomPulseFunction.h.

  : CustomPulseFunction(expression, parameters) 
{
  TFormula peakExpr("CustomPulseFunctionPeak", peakTime.c_str(), false);
  
  // excess parameters are allowed because they might belong to `expression`
  std::string const msg = checkMissingParameters(peakExpr, parameters);
  if (!msg.empty()) throw std::runtime_error("CustomPulseFunction:" + msg);
  
  setParameters(peakExpr, parameters);
  fStats = extractStats(Time{ peakExpr.Eval(0.0) }); // dummy value
  
} // icarus::opdet::CustomPulseFunction<>::CustomPulseFunction(string)

template<typename T >

icarus::opdet::CustomPulseFunction< T >::CustomPulseFunction ( std::string const &  expression, PulseParameters_t const &  parameters  )

private

Constructor implementation.

Definition at line 231 of file CustomPulseFunction.h.

  : fFormula{
      "CustomPulseFunction", // fixed name, hope ROOT does not mess it up...
      expression.c_str(),
      false // addToGlobList
    }
{
  std::string const msg = checkMissingParameters(fFormula, parameters)
    + checkExcessParameters(fFormula, parameters);
  if (!msg.empty()) throw std::runtime_error("CustomPulseFunction:" + msg);

  setParameters(fFormula, parameters);
} // icarus::opdet::CustomPulseFunction<>::CustomPulseFunction(impl)

Member Function Documentation

template<typename T >

std::string icarus::opdet::CustomPulseFunction< T >::checkExcessParameters ( TFormula const &  formula, PulseParameters_t const &  parameters  )

staticprivate

Returns a message about parameters which are not in formula.

Returns

a message about excess parameters, empty if none

Definition at line 318 of file CustomPulseFunction.h.

{
  std::set<std::string> offered;
  for (auto const& nameAndValue: parameters)
    offered.insert(nameAndValue.first);
  std::set<std::string> required;
  for (auto const iPar: util::counter(formula.GetNpar()))
    required.insert(formula.GetParName(iPar));
  
  std::set<std::string> excess;
  std::set_difference(
    offered.cbegin(), offered.cend(), required.cbegin(), required.cend(),
    std::inserter(excess, excess.begin())
    );
  if (excess.empty()) return {}; // success
  
  std::string msg
    { "\n * " + std::to_string(excess.size()) + " unused parameters:" };
  for (auto const& name: excess) msg += "\n   - '" + name + "'";
  
  return msg;
  
} // icarus::opdet::CustomPulseFunction<>::checkExcessParameters()

template<typename T >

std::string icarus::opdet::CustomPulseFunction< T >::checkMissingParameters ( TFormula const &  formula, PulseParameters_t const &  parameters  )

staticprivate

Returns a message about parameters in formula missing in parameters.

Returns

a message about missing parameters, empty if none

Definition at line 290 of file CustomPulseFunction.h.

{
  std::set<std::string> required;
  for (auto const iPar: util::counter(formula.GetNpar()))
    required.insert(formula.GetParName(iPar));
  std::set<std::string> offered;
  for (auto const& nameAndValue: parameters)
    offered.insert(nameAndValue.first);
  
  std::set<std::string> missing;
  std::set_difference(
    required.cbegin(), required.cend(), offered.cbegin(), offered.cend(),
    std::inserter(missing, missing.begin())
    );
  if (missing.empty()) return {}; // success
  
  std::string msg
    { "\n * " + std::to_string(missing.size()) + " parameters missing:" };
  for (auto const& name: missing) msg += "\n   - '" + name + "'";
  
  return msg;
  
} // icarus::opdet::CustomPulseFunction<>::checkMissingParameters()

template<typename T >

void icarus::opdet::CustomPulseFunction< 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 266 of file CustomPulseFunction.h.

{
  out
    << firstIndent << "Custom pulse shape: " << fFormula.GetTitle()
    << "\n" << indent << "  peak " << fStats.peakAmplitude
      << " at " << fStats.peakTime
    ;
  if (fFormula.GetNpar() > 0) {
    out << "\n" << indent << "Parameters (" << fFormula.GetNpar() << "):";
    for (auto const iPar: util::counter(fFormula.GetNpar())) {
      out << "\n" << indent << "  [" << fFormula.GetParName(iPar) << "] = "
        << fFormula.GetParameter(iPar);
    } // for
  } // if parameters
  out << '\n';
} // icarus::opdet::CustomPulseFunction<>::doDump()

template<typename T >

virtual ADCcount icarus::opdet::CustomPulseFunction< T >::doEvaluateAt ( Time  time ) const

inlineoverrideprivatevirtual

Evaluates the pulse at the given time.

Parameters

time	time to evaluate the shape at

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

Definition at line 149 of file CustomPulseFunction.h.

    { return ADCcount::castFrom(fFormula.Eval(static_cast<double>(time))); }

template<typename T >

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

inlineoverrideprivatevirtual

Returns the amplitude of the first peak in ADC counts.

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

Definition at line 156 of file CustomPulseFunction.h.

    { return fStats.peakAmplitude; }

template<typename T >

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

inlineoverrideprivatevirtual

Returns the time at which the first peak is found.

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

Definition at line 153 of file CustomPulseFunction.h.

{ return fStats.peakTime; }

template<typename T >

auto icarus::opdet::CustomPulseFunction< T >::extractStats ( Time  peakTime ) const

private

Extracts statistics from pulse shape.

Definition at line 252 of file CustomPulseFunction.h.

{
  PulseStats_t stats;
  
  stats.peakTime = peakTime;
  stats.peakAmplitude = (*this)(peakTime);
  stats.negativePulse = stats.peakAmplitude < ADCcount{ 0 };
  
  return stats;
} // icarus::opdet::CustomPulseFunction<>::extractStats()

template<typename T >

ParameterValue_t icarus::opdet::CustomPulseFunction< T >::parameter

(

std::string const &

name

)

const

Returns the value of the parameter specified by name.

template<typename T >

void icarus::opdet::CustomPulseFunction< T >::setParameters ( TFormula &  formula, PulseParameters_t const &  parameters  )

staticprivate

Sets the value of the parameters of formula.

Definition at line 346 of file CustomPulseFunction.h.

{
  for (auto const& [ name, value ]: parameters) {
    auto const iPar = formula.GetParNumber(name.c_str());
    if (iPar < 0) continue;
    formula.SetParameter(iPar, value);
  } // for
} // icarus::opdet::CustomPulseFunction<>::setParameters()

Member Data Documentation

template<typename T >

TFormula icarus::opdet::CustomPulseFunction< T >::fFormula

private

Formula of the shape.

Definition at line 129 of file CustomPulseFunction.h.

template<typename T >

PulseStats_t icarus::opdet::CustomPulseFunction< T >::fStats

private

Collected information about the pulse.

Definition at line 131 of file CustomPulseFunction.h.

---

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

• CustomPulseFunction.h