calo::LinearEnergyAlg Class Reference

Calibrates the energy of the clusters. More...

#include "LinearEnergyAlg.h"

Classes
struct	BirksParameters
struct	Config
	Algorithm configuration. More...
struct	ConstantRecombParameters
struct	ModBoxParameters
struct	ModelName
struct	RecombinationConfig
	Configuration of parameters of the box model. More...

Public Types
enum	RecombinationModel_t { kModBox, kBirks, kConstant, nRecombinationModel }

Public Member Functions
Construction and configuration
	LinearEnergyAlg (Config const &config)
	Constructor with configuration validation. More...
	LinearEnergyAlg (fhicl::ParameterSet const &pset)
	Constructor with configuration validation. More...
Set up
void	setup (detinfo::DetectorProperties const &detproperty, detinfo::DetectorClocks const &detclock, geo::GeometryCore const &geometry)
	Sets up the algorithm. More...
template<typename Stream >
void	DumpConfiguration (Stream &&out, std::string indent, std::string firstIndent) const
	Prints the current algorithm configuration. More...
template<typename Stream >
void	DumpConfiguration (Stream &&out, std::string indent="") const
	Prints the current algorithm configuration. More...
Operations
template<typename BeginHitIter , typename EndHitIter >
double	CalculateClusterEnergy (recob::Cluster const &cluster, BeginHitIter beginHit, EndHitIter endHit) const
	Calculates the energy of a single cluster. More...
template<typename Hits >
double	CalculateClusterEnergy (recob::Cluster const &cluster, Hits &&hits) const
	Calculates the energy of a single cluster. More...
std::vector< double >	CalculateEnergy (std::vector< art::Ptr< recob::Cluster >> const &clusters, art::Assns< recob::Cluster, recob::Hit > const &hitsPerCluster) const
	Calculates the energy of the shower. More...

Private Member Functions
void	initialize ()
double	CalculateHitEnergy (recob::Hit const &hit) const
	Returns the corrected energy from the hit. More...
double	RecombinationCorrection (double dEdx) const
	TODO: make it more flexible. More...
double	ModBoxInverse (double dEdx) const
double	BirksInverse (double dEdx) const

Private Attributes
geo::GeometryCore const *	geom = nullptr
	Pointer to the geometry to be used. More...
detinfo::DetectorProperties const *	detp = nullptr
	Pointer to the detector property. More...
detinfo::DetectorClocks const *	detc = nullptr
	Pointer to the detector clock. More...
bool	fUseArea
int	fRecombModel
ModBoxParameters	recombModBoxParams
	Parameters for recombination box model; filled only when this model is selected. More...
BirksParameters	recombBirksParams
	Parameters for recombination Birks model; filled only when this model is selected. More...
ConstantRecombParameters	recombConstParams
	Parameters for constant recombination factor; filled only when this model is selected. More...
double	fElectronLifetime
double	fDeconNorm

Static Private Attributes
static constexpr double	kWion = 23.6e-9
	ionization potenial in LAr, 23.6 eV = 1e, Wion in GeV/e More...
static constexpr double	kRecombFactor = 0.62
	constant correction used in the current MicroBooNE shower reconstruction More...

Detailed Description

Calibrates the energy of the clusters.

Configuration

Example of configuration:

EnergyAlgo: {
  UseArea: true
  Recombination: {
    Model: Birks
    A3t: 0.8
    k3t: 0.0486
  }
}

Parameters:

• UseArea (flag, _mandatory): whether to use hit integral (recob::Hit::Integral()) instead of hit peak amplitude for charge estimation
• Recombination (mandatory table): configures the recombination model to be used and its parameters:
  • Model (string, mandatory): specifies one of the supported recombination models: Birks, ModBox or Constant. Each requires its own specific configuration parameters.
    • Birks, Birks Law model (see S.Amoruso et al., NIM A 523 (2004) 275) requires configuration parameters:
      • A3t (real, default: util::kRecombA)
      • k3t (real, default: util::kRecombk) in kV/cm*(g/cm^2)/MeV
    • ModBox, box model requires configuration parameters:
      • A (real, default: util::kModBoxA)
      • B (real, default: util::kModBoxB) in kV/cm*(g/cm^2)/MeV
    • Constant recombination factor, requires configuration parameters:
      • factor (real, mandatory): the recombination factor, uniformly applied to all hits

Definition at line 79 of file LinearEnergyAlg.h.

Member Enumeration Documentation

enum calo::LinearEnergyAlg::RecombinationModel_t

Enumerator
kModBox
kBirks
kConstant
nRecombinationModel

Definition at line 89 of file LinearEnergyAlg.h.

                              {
      kModBox,
      kBirks,
      kConstant,
      nRecombinationModel
    };

Constructor & Destructor Documentation

calo::LinearEnergyAlg::LinearEnergyAlg

(

Config const &

config

)

Constructor with configuration validation.

Parameters

config

configuration parameter structure

For the configuration, see LinearEnergyAlg documentation.

Definition at line 82 of file LinearEnergyAlg.cxx.

References calo::LinearEnergyAlg::ModBoxParameters::A, calo::LinearEnergyAlg::BirksParameters::A, calo::LinearEnergyAlg::ModBoxParameters::B, calo::LinearEnergyAlg::ConstantRecombParameters::factor, fRecombModel, fUseArea, calo::LinearEnergyAlg::BirksParameters::k, kBirks, kConstant, kModBox, recombBirksParams, recombConstParams, calo::LinearEnergyAlg::Config::Recombination, and recombModBoxParams.

  : fUseArea( config.UseArea() )
//  , fRecombFactor( 1. )
  , fElectronLifetime( 1e10 ) // needs to be read from service
  , fDeconNorm( 200 )
{
  auto const& recombParams = config.Recombination();
  if ( recombParams.modelIsModBox()) {
    fRecombModel = kModBox;
    recombModBoxParams.A = recombParams.A();
    recombModBoxParams.B = recombParams.B();
  }
  else if ( recombParams.modelIsBirks()) {
    fRecombModel = kBirks;
    recombBirksParams.A = recombParams.A3t();
    recombBirksParams.k = recombParams.k3t();
  }
  else if ( recombParams.modelIsConstant()) {
    fRecombModel = kConstant;
    recombConstParams.factor = recombParams.factor();
  }
  else {
    throw std::runtime_error
      ( "Unsupported recombination mode: '" + recombParams.Model() + "'" );
  }
  
  if (!fUseArea) {
    throw std::runtime_error("Energy correction based on hit peak amplitude not implemented yet.");
  }
  
}

calo::LinearEnergyAlg::LinearEnergyAlg ( fhicl::ParameterSet const &  pset )

inline

Constructor with configuration validation.

Parameters

pset	FHiCL configuration parameter set

See also

SpacePointIsolationAlg(Config const&)

Translates the parameter set into a configuration object and uses the validating constructor to initialise the object.

For the configuration, see LinearEnergyAlg documentation.

Definition at line 198 of file LinearEnergyAlg.h.

      : LinearEnergyAlg(fhicl::Table<Config>(pset, {})())
      {}

Member Function Documentation

double calo::LinearEnergyAlg::BirksInverse ( double  dEdx ) const

private

Definition at line 229 of file LinearEnergyAlg.cxx.

References calo::LinearEnergyAlg::BirksParameters::A, detinfo::DetectorProperties::Density(), detp, detinfo::DetectorProperties::Efield(), calo::LinearEnergyAlg::BirksParameters::k, kWion, and recombBirksParams.

Referenced by RecombinationCorrection().

                                                            {
  // Correction for charge quenching using parameterization from
  // S.Amoruso et al., NIM A 523 (2004) 275

  double A3t     = recombBirksParams.A;
  double K3t     = recombBirksParams.k;                // in KV/cm*(g/cm^2)/MeV
  double rho     = detp->Density();                    // LAr density in g/cm^3
  double Efield  = detp->Efield();                     // Electric Field in the drift region in KV/cm
  K3t           /= rho;                                // KV/MeV

  double dQdx = ( A3t/kWion ) / ( K3t / Efield * dEdx + 1);

  return dQdx;
}

template<typename BeginHitIter , typename EndHitIter >

double calo::LinearEnergyAlg::CalculateClusterEnergy	(	recob::Cluster const &	cluster,
		BeginHitIter	beginHit,
		EndHitIter	endHit
	)		const

Calculates the energy of a single cluster.

Template Parameters

BeginHitIter	type of iterator to the first associated hit
EndHitIter	type of iterator to the past-the-last associated hit

Parameters

cluster	list of clusters we want the energy of
hits	pointers to all hits associated to the cluster
beginHit	iterator to the first hit associated to the cluster
endHit	iterator to past-the-last hit associated to the cluster

Returns

the calibrated energy of the specified cluster [GeV]

Todo:

Describe the algorithm

The hits are stored as (constant) pointers.

Definition at line 393 of file LinearEnergyAlg.h.

References CalculateHitEnergy(), DumpConfiguration(), E, and fhicl::detail::atom::value().

Referenced by CalculateClusterEnergy(), CalculateEnergy(), and DumpConfiguration().

{
  static_assert( // check the hits type
    std::is_same<std::decay_t<decltype(**beginHit)>, recob::Hit>::value,
    "The hits must be stored as recob::Hit pointers!" // any pointer will do
    );
  
  double E = 0.0; // total cluster energy
  
  for (auto hitIter = beginHit; hitIter != endHit; ++hitIter) {
    
    E += CalculateHitEnergy(**hitIter);
    
  } // for
    
  return E;
  
} // calo::LinearEnergyAlg::CalculateEnergy()

template<typename Hits >

double calo::LinearEnergyAlg::CalculateClusterEnergy ( recob::Cluster const &  cluster, Hits &&  hits  ) const

inline

Calculates the energy of a single cluster.

Template Parameters

Hits	a range of hits associated with the cluster

Parameters

cluster	list of clusters we want the energy of
hits	pointers to all hits associated to the cluster

Returns

the calibrated energy of the specified cluster [GeV]

See also

CalculateClusterEnergy(recob::Cluster const&. BeginHitIter, EndHitIter)

The hits are stored as (constant) pointers into a "range", that is any object (e.g. a STL vector) supporting begin() and end() iterators.

Definition at line 290 of file LinearEnergyAlg.h.

References evd::details::begin(), CalculateClusterEnergy(), CalculateEnergy(), evd::details::end(), hits(), and lar::dump::vector().

      {
        using std::begin; using std::end;
        return CalculateClusterEnergy(cluster, begin(hits), end(hits));
      }

std::vector< double > calo::LinearEnergyAlg::CalculateEnergy	(	std::vector< art::Ptr< recob::Cluster >> const &	clusters,
		art::Assns< recob::Cluster, recob::Hit > const &	hitsPerCluster
	)		const

Calculates the energy of the shower.

Parameters

clusters	list of clusters we want the energy of
hitsPerCluster	associations of all clusters to all hits

Returns

a vector with one energy per input cluster [GeV]

See also

CalculateClusterEnergy()

A vector is returned with a entry per plane in the TPC of the clusters. The energy has a very negative value (std::numeric_limits<double>::lowest()) for the planes with no cluster. See CalculateClusterEnergy() for the algorithm details.

Definition at line 147 of file LinearEnergyAlg.cxx.

References CalculateClusterEnergy(), E, geom, recob::Cluster::ID(), geo::TPCGeo::Nplanes(), recob::Cluster::Plane(), util::flags::to_string(), and geo::GeometryCore::TPC().

Referenced by CalculateClusterEnergy().

{  // input clusters and hits, shower direction?
  
  if (clusters.empty()) return {}; // no clusters!!

  // prepare the energies vector with one entry per plane
  // (we get the total number of planes of the TPC  the cluster is in from geometry)
  // and initialize them to a ridiculously negative number to start with

  std::vector<double> clusterEnergies;
  geo::TPCID refTPC = clusters[0]->Plane();
  clusterEnergies.resize
    (geom->TPC(refTPC).Nplanes(), std::numeric_limits<double>::lowest());
  
  if ( clusters.size() > clusterEnergies.size() ) {
    mf::LogError("LinearEnergyAlg") << clusters.size() << " clusters for "
      << clusterEnergies.size() << " wire planes!";
  }

  for (art::Ptr<recob::Cluster> const& cluster: clusters) {
    
    auto const plane = cluster->Plane();
    if (plane != refTPC) {
      throw std::runtime_error(
        "Cluster ID=" + std::to_string(cluster->ID())
        + " is expected on TPC " + std::string(refTPC)
        + " but is found on plane " + std::string(plane)
        );
    }
    
    // hitsAssociatedWith() searches for the right association links
    // to the cluster we are processing
    double const E = CalculateClusterEnergy
      (*cluster, hitsAssociatedWith(cluster, hitsPerCluster));
    
    auto const planeNo = plane.Plane;
    if (clusterEnergies[planeNo] >= 0.) {
      mf::LogWarning("LinearEnergyAlg")
        << "Warning! two or more clusters share plane "
        << plane << "! (the last with energy " << E
        << ", the previous " << clusterEnergies[planeNo] << " GeV)";
    }
    clusterEnergies[planeNo] = E;
    
  } // for all clusters
  
  return clusterEnergies;
  
} // calo::LinearEnergyAlg::CalculateEnergy()

double calo::LinearEnergyAlg::CalculateHitEnergy ( recob::Hit const &  hit ) const

private

Returns the corrected energy from the hit.

Parameters

hit	the hit to be corrected

Returns

the corrected hit energy [GeV]

Todo:

document the algorithm here

Definition at line 123 of file LinearEnergyAlg.cxx.

References detc, fDeconNorm, fElectronLifetime, recob::Hit::Integral(), kWion, recob::Hit::PeakTime(), RecombinationCorrection(), and detinfo::DetectorClocks::TPCTick2TrigTime().

Referenced by CalculateClusterEnergy().

{

  double const t = detc->TPCTick2TrigTime( hit.PeakTime() );
  double const LifetimeCorr = std::exp( t / fElectronLifetime );
  
  // hit charge (ADC) -> Coulomb -> Number of electrons -> eV
  // TODO: implement the non-UseArea option
  double dE = hit.Integral() * kWion * fDeconNorm;
  
  // dE * lifetime correction
  dE *= LifetimeCorr;
  
  // dE / recombination factor
  double const dEdx = 2.3;
  double const RecombCorr = RecombinationCorrection( dEdx ) * kWion / dEdx;
  dE /= RecombCorr;
  
  return dE;
  
} // calo::LinearEnergyAlg::CalculateHitEnergy()

template<typename Stream >

void calo::LinearEnergyAlg::DumpConfiguration	(	Stream &&	out,
		std::string	indent,
		std::string	firstIndent
	)		const

Prints the current algorithm configuration.

Template Parameters

Stream

type of output stream

Parameters

out	output stream where to write the information
indent	indentation for all lines
firstIndent	special indentation for the first line

The configuration parameters are printed in human-readable form. The output starts at the current line of the stream, and it terminates with a new line.

This method does not require the algorithm to have been set up (via Setup()), since it just prints user configuration as given at construction time.

Definition at line 417 of file LinearEnergyAlg.h.

References calo::LinearEnergyAlg::ModBoxParameters::A, calo::LinearEnergyAlg::BirksParameters::A, calo::LinearEnergyAlg::ModBoxParameters::B, calo::LinearEnergyAlg::ModelName::Birks, calo::LinearEnergyAlg::ModelName::Constant, calo::LinearEnergyAlg::ConstantRecombParameters::factor, fRecombModel, fUseArea, calo::LinearEnergyAlg::BirksParameters::k, kBirks, kConstant, kModBox, calo::LinearEnergyAlg::ModelName::ModBox, recombBirksParams, recombConstParams, and recombModBoxParams.

Referenced by CalculateClusterEnergy(), DumpConfiguration(), and setup().

{
  
  out << firstIndent << "LinearEnergyAlg configuration:"
    << "\n" << indent << "  use hit " << (fUseArea? "area": "peak amplitude")
      << " for charge estimation"
    << "\n" << indent << "  recombination model: ";
  switch ( fRecombModel ) {
    case kModBox:
      out << ModelName::ModBox
        << "\n" << indent << "    A = " << recombModBoxParams.A
        << "\n" << indent << "    B = " << recombModBoxParams.B;
      break;
    case kBirks:
      out << ModelName::Birks
        << "\n" << indent << "    A = " << recombBirksParams.A
        << "\n" << indent << "    k = " << recombBirksParams.k;
      break;
    case kConstant:
      out << ModelName::Constant
        << "\n" << indent << "    k = " << recombConstParams.factor;
      break;
    default:
      out << "invalid (" << ((int) fRecombModel) << ")!!!";
  } // switch
  out << "\n";
  
} // calo::LinearEnergyAlg::DumpConfiguration()

template<typename Stream >

void calo::LinearEnergyAlg::DumpConfiguration ( Stream &&  out, std::string  indent = ""  ) const

inline

Prints the current algorithm configuration.

Template Parameters

Stream

type of output stream

Parameters

out	output stream where to write the information
indent	(default: none) indentation for all lines (including the first one)

The configuration parameters are printed in human-readable form. The output starts at the current line of the stream, and it terminates with a new line.

Definition at line 248 of file LinearEnergyAlg.h.

References CalculateClusterEnergy(), and DumpConfiguration().

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

void calo::LinearEnergyAlg::initialize ( )

private

Definition at line 115 of file LinearEnergyAlg.cxx.

References detp, detinfo::DetectorProperties::ElectronLifetime(), and fElectronLifetime.

Referenced by setup().

                                     {

  fElectronLifetime = detp->ElectronLifetime();

}

double calo::LinearEnergyAlg::ModBoxInverse ( double  dEdx ) const

private

Definition at line 216 of file LinearEnergyAlg.cxx.

References calo::LinearEnergyAlg::ModBoxParameters::A, calo::LinearEnergyAlg::ModBoxParameters::B, detinfo::DetectorProperties::Density(), detp, detinfo::DetectorProperties::Efield(), kWion, and recombModBoxParams.

Referenced by RecombinationCorrection().

                                                             {
  // Modified Box model correction has better behavior than the Birks
  // correction at high values of dQ/dx.
  double rho     = detp->Density();                    // LAr density in g/cm^3
  double Efield  = detp->Efield();                     // Electric Field in the drift region in KV/cm
  double Beta    = recombModBoxParams.B / (rho * Efield);
  double Alpha   = recombModBoxParams.A;

  double dQdx = std::log ( Alpha + Beta * dEdx ) / ( Beta * kWion );

  return dQdx;
}

double calo::LinearEnergyAlg::RecombinationCorrection ( double  dEdx ) const

private

TODO: make it more flexible.

Definition at line 200 of file LinearEnergyAlg.cxx.

References BirksInverse(), calo::LinearEnergyAlg::ConstantRecombParameters::factor, fRecombModel, kBirks, kConstant, kModBox, ModBoxInverse(), and recombConstParams.

Referenced by CalculateHitEnergy().

                                                                       {

  switch ( fRecombModel ) {
    case kModBox:
      return this->ModBoxInverse( dEdx );
    case kBirks:
      return this->BirksInverse( dEdx );
    case kConstant:
      return recombConstParams.factor;
    default:
      throw std::logic_error
        ("Unexpected! recombination model in RecombinationCorrection()");
  }
}

void calo::LinearEnergyAlg::setup ( detinfo::DetectorProperties const &  detproperty, detinfo::DetectorClocks const &  detclock, geo::GeometryCore const &  geometry  )

inline

Sets up the algorithm.

Parameters

geometry

the geometry service provider

Acquires the geometry description. This method must be called every time the geometry is changed.

Definition at line 214 of file LinearEnergyAlg.h.

References detc, detp, DumpConfiguration(), geom, art::detail::indent(), and initialize().

      { detp = &detproperty; detc = &detclock; geom = &geometry; initialize(); }

Member Data Documentation

detinfo::DetectorClocks const* calo::LinearEnergyAlg::detc = nullptr

private

Pointer to the detector clock.

Definition at line 339 of file LinearEnergyAlg.h.

Referenced by CalculateHitEnergy(), and setup().

detinfo::DetectorProperties const* calo::LinearEnergyAlg::detp = nullptr

private

Pointer to the detector property.

Definition at line 336 of file LinearEnergyAlg.h.

Referenced by BirksInverse(), initialize(), ModBoxInverse(), and setup().

double calo::LinearEnergyAlg::fDeconNorm

private

Definition at line 358 of file LinearEnergyAlg.h.

Referenced by CalculateHitEnergy().

double calo::LinearEnergyAlg::fElectronLifetime

private

Definition at line 357 of file LinearEnergyAlg.h.

Referenced by CalculateHitEnergy(), and initialize().

int calo::LinearEnergyAlg::fRecombModel

private

Definition at line 342 of file LinearEnergyAlg.h.

Referenced by DumpConfiguration(), LinearEnergyAlg(), and RecombinationCorrection().

bool calo::LinearEnergyAlg::fUseArea

private

Definition at line 341 of file LinearEnergyAlg.h.

Referenced by DumpConfiguration(), and LinearEnergyAlg().

geo::GeometryCore const* calo::LinearEnergyAlg::geom = nullptr

private

Pointer to the geometry to be used.

Definition at line 333 of file LinearEnergyAlg.h.

Referenced by CalculateEnergy(), and setup().

constexpr double calo::LinearEnergyAlg::kRecombFactor = 0.62

staticprivate

constant correction used in the current MicroBooNE shower reconstruction

Definition at line 362 of file LinearEnergyAlg.h.

constexpr double calo::LinearEnergyAlg::kWion = 23.6e-9

staticprivate

ionization potenial in LAr, 23.6 eV = 1e, Wion in GeV/e

Definition at line 360 of file LinearEnergyAlg.h.

Referenced by BirksInverse(), CalculateHitEnergy(), and ModBoxInverse().

BirksParameters calo::LinearEnergyAlg::recombBirksParams

private

Parameters for recombination Birks model; filled only when this model is selected.

Definition at line 347 of file LinearEnergyAlg.h.

Referenced by BirksInverse(), DumpConfiguration(), and LinearEnergyAlg().

ConstantRecombParameters calo::LinearEnergyAlg::recombConstParams

private

Parameters for constant recombination factor; filled only when this model is selected.

Definition at line 349 of file LinearEnergyAlg.h.

Referenced by DumpConfiguration(), LinearEnergyAlg(), and RecombinationCorrection().

ModBoxParameters calo::LinearEnergyAlg::recombModBoxParams

private

Parameters for recombination box model; filled only when this model is selected.

Definition at line 345 of file LinearEnergyAlg.h.

Referenced by DumpConfiguration(), LinearEnergyAlg(), and ModBoxInverse().

---

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

• /cvmfs/larsoft.opensciencegrid.org/products/larreco/v07_10_02/source/larreco/Calorimetry/LinearEnergyAlg.h
• /cvmfs/larsoft.opensciencegrid.org/products/larreco/v07_10_02/source/larreco/Calorimetry/LinearEnergyAlg.cxx