sim::SimChannel Class Reference

Energy deposited on a readout channel by simulated tracks. More...

#include <SimChannel.h>

Classes
struct	CompareByTDC

Public Types
typedef TDCIDE::first_type	StoredTDC_t
	Type for TDC tick used in the internal representation. More...
typedef std::vector< TDCIDE >	TDCIDEs_t
	Type of list of energy deposits for each TDC with signal. More...
typedef unsigned int	TDC_t
typedef IDE::TrackID_t	TrackID_t
	Type of track ID (the value comes from Geant4) More...

Public Member Functions
	SimChannel ()
	SimChannel (raw::ChannelID_t channel)
	Constructor: immediately sets the channel number. More...
void	AddIonizationElectrons (TrackID_t trackID, TDC_t tdc, double numberElectrons, double const *xyz, double energy)
	Add ionization electrons and energy to this channel. More...
raw::ChannelID_t	Channel () const
	Returns the readout channel this object describes. More...
std::vector< sim::IDE >	TrackIDsAndEnergies (TDC_t startTDC, TDC_t endTDC) const
	Return all the recorded energy deposition within a time interval. More...
TDCIDEs_t const &	TDCIDEMap () const
	Returns all the deposited energy information as stored. More...
double	Charge (TDC_t tdc) const
	Returns the total number of ionization electrons on this channel in the specified TDC. More...
double	Energy (TDC_t tdc) const
	Returns the total energy on this channel in the specified TDC [MeV]. More...
std::vector< sim::TrackIDE >	TrackIDEs (TDC_t startTDC, TDC_t endTDC) const
	Returns energies collected for each track within a time interval. More...
bool	operator< (const SimChannel &other) const
	Comparison: sorts by channel ID. More...
bool	operator== (const SimChannel &other) const
	Comparison: true if SimChannels have the same channel ID. More...
std::pair< TrackID_t, TrackID_t >	MergeSimChannel (const SimChannel &channel, int offset)
	Merges the deposits from another channel into this one. More...
template<typename Stream >
void	Dump (Stream &&out, std::string indent, std::string first_indent) const
	Dumps the full content of the SimChannel into a stream. More...
template<typename Stream >
void	Dump (Stream &&out, std::string indent="") const
	Documentation at Dump(Stream&&, std::string, std::string) const. More...

Private Member Functions
TDCIDEs_t::iterator	findClosestTDCIDE (StoredTDC_t tdc)
	Return the iterator to the first TDCIDE not earlier than tdc. More...
TDCIDEs_t::const_iterator	findClosestTDCIDE (StoredTDC_t tdc) const
	Return the (constant) iterator to the first TDCIDE not earlier than tdc. More...

Private Attributes
raw::ChannelID_t	fChannel
	readout channel where electrons are collected More...
TDCIDEs_t	fTDCIDEs
	list of energy deposits for each TDC with signal More...

Detailed Description

Energy deposited on a readout channel by simulated tracks.

This class stores the list of all energies deposited on a readout channel. The number of electrons is stored as well.

The information is organized by time: it is divided by TDC ticks, and each TDC tick where some energy was deposited appears in a separate entry, while the quiet TDC ticks are omitted. For each TDC, the information is stored as a list of energy deposits; each deposit comes from a single Geant4 track and stores the location where the ionization happened according to the simulation (see sim::IDE class).

Note that there can be multiple energy deposit records (that is sim::IDE) for a single track in a single TDC tick.

Definition at line 140 of file SimChannel.h.

Member Typedef Documentation

typedef TDCIDE::first_type sim::SimChannel::StoredTDC_t

Type for TDC tick used in the internal representation.

Definition at line 144 of file SimChannel.h.

typedef unsigned int sim::SimChannel::TDC_t

Type for TDC tick used in the interface (different type than raw::TDCtick_t! and from internal representation! but same meaning!)

Definition at line 162 of file SimChannel.h.

typedef std::vector<TDCIDE> sim::SimChannel::TDCIDEs_t

Type of list of energy deposits for each TDC with signal.

Definition at line 147 of file SimChannel.h.

typedef IDE::TrackID_t sim::SimChannel::TrackID_t

Type of track ID (the value comes from Geant4)

Definition at line 165 of file SimChannel.h.

Constructor & Destructor Documentation

sim::SimChannel::SimChannel

(

)

Definition at line 44 of file SimChannel.cxx.

    : fChannel(raw::InvalidChannelID)
  {}

sim::SimChannel::SimChannel ( raw::ChannelID_t  channel )

explicit

Constructor: immediately sets the channel number.

Definition at line 49 of file SimChannel.cxx.

    : fChannel(channel)
  {}

Member Function Documentation

void sim::SimChannel::AddIonizationElectrons	(	TrackID_t	trackID,
		TDC_t	tdc,
		double	numberElectrons,
		double const *	xyz,
		double	energy
	)

Add ionization electrons and energy to this channel.

Parameters

trackID	ID of simulated track depositing this energy (from Geant4)
tdc	TDC tick when this deposit was collected
numberElectrons	electrons created at this point by this track
xyz	coordinates of original location of ionization (3D array) [cm]
energy	energy deposited at this point by this track [MeV]

The number of electrons can be fractional because of simulated efficiency and physics effects.

Definition at line 54 of file SimChannel.cxx.

  {
    // look at the collection to see if the current TDC already
    // exists, if not, add it, if so, just add a new track id to the
    // vector, or update the information if track is already present

    // no electrons? no energy? no good!
    if ((numberElectrons < std::numeric_limits<double>::epsilon())
      || (energy <= std::numeric_limits<double>::epsilon()))
    {
      // will throw
      MF_LOG_ERROR("SimChannel")
      << "AddIonizationElectrons() trying to add to TDC #"
      << tdc
      << " "
      << numberElectrons
      << " electrons with "
      << energy
      << " MeV of energy from track ID="
      << trackID;
      return;
    } // if no energy or no electrons

    auto itr = findClosestTDCIDE(tdc);

    // check if this tdc value is in the vector, it is possible that
    // the lower bound is different from the given tdc, in which case
    // we need to add something for that tdc
    if(itr        == fTDCIDEs.end() ||
       itr->first != tdc){
      std::vector<sim::IDE> idelist;
      idelist.emplace_back(trackID,
                           numberElectrons,
                           energy,
                           xyz[0],
                           xyz[1],
                           xyz[2]
                           );
      fTDCIDEs.emplace(itr, tdc, std::move(idelist) );
    }
    else { // we have that TDC already; itr points to it

      // loop over the IDE vector for this tdc and add the electrons
      // to the entry with the same track id
      for(auto& ide : itr->second){

        if (ide.trackID != trackID ) continue;

        // make a weighted average for the location information
        double weight    = ide.numElectrons + numberElectrons;
        ide.x            = (ide.x * ide.numElectrons + xyz[0]*numberElectrons)/weight;
        ide.y            = (ide.y * ide.numElectrons + xyz[1]*numberElectrons)/weight;
        ide.z            = (ide.z * ide.numElectrons + xyz[2]*numberElectrons)/weight;
        ide.numElectrons = weight;
        ide.energy       = ide.energy + energy;

        // found the track id we wanted, so return;
        return;
      } // for

      // if we never found the track id, then this is the first instance of
      // the track id for this tdc, so add ide to the vector
      itr->second.emplace_back(trackID,
                               numberElectrons,
                               energy,
                               xyz[0],
                               xyz[1],
                               xyz[2]
                               );

    } // if new TDC ... else

  } // SimChannel::AddIonizationElectrons()

raw::ChannelID_t sim::SimChannel::Channel ( ) const

inline

Returns the readout channel this object describes.

Definition at line 329 of file SimChannel.h.

{ return fChannel; }

double sim::SimChannel::Charge

(

TDC_t

tdc

)

const

Returns the total number of ionization electrons on this channel in the specified TDC.

Definition at line 134 of file SimChannel.cxx.

  {
    double charge = 0.;

    auto itr = findClosestTDCIDE(tdc);

      // check to see if this tdc value is in the map
    if(itr        != fTDCIDEs.end() &&
       itr->first == tdc){

        // loop over the list for this tdc value and add up
        // the total number of electrons
      for(auto ide : itr->second){
        charge += ide.numElectrons;
      } // end loop over sim::IDE for this tdc

    } // end if this tdc is represented in the map

    return charge;
  }

template<class Stream >

void sim::SimChannel::Dump	(	Stream &&	out,
		std::string	indent,
		std::string	first_indent
	)		const

Dumps the full content of the SimChannel into a stream.

Template Parameters

Stream

an ostream-like stream object

Parameters

out	the stream to send the information into
indent	indentation of the lines (default: none)
first_indent	indentation for the first line (default: as indent)

Definition at line 337 of file SimChannel.h.

{
  out << first_indent << "channel #" << Channel() << " read " << fTDCIDEs.size()
    << " TDCs:\n";
  double channel_energy = 0., channel_charge = 0.;
  for (const auto& TDCinfo: fTDCIDEs) {
    auto const tdc = TDCinfo.first;
    out << indent << "  TDC #" << tdc
      << " with " << TDCinfo.second.size() << " IDEs\n";
    double tdc_energy = 0., tdc_charge = 0.;
    for (const sim::IDE& ide: TDCinfo.second) {
      out << indent
        << "    (" << ide.x << ", " << ide.y << ", " << ide.z << ") "
        << ide.numElectrons << " electrons, " << ide.energy << " MeV (trkID="
        << ide.trackID << ")\n";
      tdc_energy += ide.energy;
      tdc_charge += ide.numElectrons;
    } // for IDEs
    out << indent << "    => TDC #" << tdc << " CH #" << Channel()
      << " collected " << tdc_charge << " electrons and " << tdc_energy
      << " MeV\n";
    channel_energy += tdc_energy;
    channel_charge += tdc_charge;
  } // for TDCs
  out << indent << "  => channel #" << Channel() << " collected "
    << channel_charge << " electrons and " << channel_energy << " MeV\n";
} // sim::SimChannel::Dump<>()

template<typename Stream >

void sim::SimChannel::Dump ( Stream &&  out, std::string  indent = ""  ) const

inline

Documentation at Dump(Stream&&, std::string, std::string) const.

Definition at line 304 of file SimChannel.h.

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

double sim::SimChannel::Energy

(

TDC_t

tdc

)

const

Returns the total energy on this channel in the specified TDC [MeV].

Definition at line 156 of file SimChannel.cxx.

  {
    double energy = 0.;

    auto itr = findClosestTDCIDE(tdc);

      // check to see if this tdc value is in the map
    if(itr        != fTDCIDEs.end() &&
       itr->first == tdc){

        // loop over the list for this tdc value and add up
        // the total number of electrons
      for(auto ide : itr->second ){
        energy += ide.energy;
      } // end loop over sim::IDE for this tdc

    } // end if this tdc is represented in the map

    return energy;
  }

SimChannel::TDCIDEs_t::iterator sim::SimChannel::findClosestTDCIDE ( StoredTDC_t  tdc )

private

Return the iterator to the first TDCIDE not earlier than tdc.

Definition at line 342 of file SimChannel.cxx.

  {
    return std::lower_bound
      (fTDCIDEs.begin(), fTDCIDEs.end(), tdc, CompareByTDC());
  }

SimChannel::TDCIDEs_t::const_iterator sim::SimChannel::findClosestTDCIDE ( StoredTDC_t  tdc ) const

private

Return the (constant) iterator to the first TDCIDE not earlier than tdc.

Definition at line 349 of file SimChannel.cxx.

  {
    return std::lower_bound
      (fTDCIDEs.begin(), fTDCIDEs.end(), tdc, CompareByTDC());
  }

std::pair< SimChannel::TrackID_t, SimChannel::TrackID_t > sim::SimChannel::MergeSimChannel	(	const SimChannel &	channel,
		int	offset
	)

Merges the deposits from another channel into this one.

Parameters

channel	the sim::SimChannel holding information to be merged
offset	track ID offset for the merge

Returns

range of the IDs of the added tracks

The information from the specified simulated channel is added to the current one. This is achieved by appending the energy deposit information (sim::IDE) at each TDC tick from the merged channel to the list of existing energy deposits for that TDC tick.

In addition, the track IDs of the merged channel are added an offset, so that they can be distinguished from the existing ones. This is useful when simulating tracks with multiple Geant4 runs. Geant4 will reuse track IDs on each run, and using the highest number of track ID from one run as the offset for the next avoids track ID collisions. Note however that this function does not perform any collision check, and it is caller's duty to ensure that the offset is properly large. The return value is a pair including the lowest and the largest track IDs added to this channel, equivalent to the lowest and the highest track IDs present in the merged channel, both augmented by the applied offset.

The channel number of the merged channel is ignored.

Definition at line 281 of file SimChannel.cxx.

  {
    if( this->Channel() != channel.Channel() )
      throw std::runtime_error("ERROR SimChannel Merge: Trying to merge different channels!");

    std::pair<TrackID_t,TrackID_t> range_trackID(std::numeric_limits<int>::max(),
                                                 std::numeric_limits<int>::min());

    for(auto const& itr : channel.TDCIDEMap()){

      auto tdc  = itr.first;
      auto const& ides = itr.second;

      // find the entry from this SimChannel corresponding to the tdc from the other
      auto itrthis = findClosestTDCIDE(tdc);

      // pick which IDE list we have to fill: new one or existing one
      std::vector<sim::IDE>* curIDEVec;
      if(itrthis        == fTDCIDEs.end() ||
         itrthis->first != tdc){
        fTDCIDEs.emplace_back(tdc, std::vector<sim::IDE>());
        curIDEVec = &(fTDCIDEs.back().second);
      }
      else
        curIDEVec = &(itrthis->second);

      for(auto const& ide : ides){
        curIDEVec->emplace_back(ide, offset);
        auto tid = std::abs(ide.trackID)+offset;
        if( tid < range_trackID.first  )
          range_trackID.first = tid;
        if( tid > range_trackID.second )
          range_trackID.second = tid;
      }//end loop over IDEs

    }//end loop over TDCIDEMap


    return range_trackID;

  }

bool sim::SimChannel::operator< ( const SimChannel &  other ) const

inline

Comparison: sorts by channel ID.

Definition at line 326 of file SimChannel.h.

{ return fChannel < other.Channel(); }

bool sim::SimChannel::operator== ( const SimChannel &  other ) const

inline

Comparison: true if SimChannels have the same channel ID.

Definition at line 327 of file SimChannel.h.

{ return fChannel == other.Channel(); }

sim::SimChannel::TDCIDEs_t const & sim::SimChannel::TDCIDEMap ( ) const

inline

Returns all the deposited energy information as stored.

Returns

all the deposited energy information as stored in the object

The returned list is organized in pairs. Each pair contains all ionization information in a single TDC tick (collection of sim::IDE), and the number of that tick. The information is sorted by increasing TDC tick.

See the class description for the details of the ionization information content.

Definition at line 328 of file SimChannel.h.

{ return fTDCIDEs; }

std::vector< sim::TrackIDE > sim::SimChannel::TrackIDEs	(	TDC_t	startTDC,
		TDC_t	endTDC
	)		const

Returns energies collected for each track within a time interval.

Parameters

startTDC	TDC tick opening the time window
endTDC	TDC tick closing the time window (included in the interval)

Returns

a collection of energy and fraction from each track in interval

See also

TrackIDsAndEnergies()

This method returns the energy deposited on this channel by each track ID active in the specified TDC time interval.

Each entry pertains a single track ID. For each entry, all energy deposit information is merged into a single record. It includes:

• energy of the track, as the integral in the time interval [MeV]
• energy fraction respect to the total (see below)
• the ID of the track depositing this energy

The energy fraction is the energy deposited by the track on this channel in the specified time interval, divided by the total of the energy deposited by all tracks on this channel in that same time interval.

Entries are sorted by track ID number.

Definition at line 246 of file SimChannel.cxx.

  {

    std::vector<sim::TrackIDE> trackIDEs;

    if(startTDC > endTDC ){
      mf::LogWarning("SimChannel::TrackIDEs") << "requested tdc range is bogus: "
                                              << startTDC << " " << endTDC
                                              << " return empty vector";
      return trackIDEs;
    }

    double totalE = 0.;
    std::vector<sim::IDE> const ides = TrackIDsAndEnergies(startTDC, endTDC);
    for (auto const& ide : ides)
      totalE += ide.energy;

    // protect against a divide by zero below
    if(totalE < 1.e-5) totalE = 1.;

    // loop over the entries in the map and fill the input vectors
    for (auto const& ide : ides){
      if(ide.trackID == sim::NoParticleId) continue;
      trackIDEs.emplace_back(ide.trackID, ide.energy/totalE, ide.energy, ide.numElectrons);
    }

    return trackIDEs;
  }

std::vector< sim::IDE > sim::SimChannel::TrackIDsAndEnergies	(	TDC_t	startTDC,
		TDC_t	endTDC
	)		const

Return all the recorded energy deposition within a time interval.

Parameters

startTDC	TDC tick opening the time window
endTDC	TDC tick closing the time window (included in the interval)

Returns

a collection of energy deposit information from all tracks

This method returns the energy deposited on this channel by each track ID active in the specified TDC time interval.

Each entry pertains a single track ID. For each entry, all energy deposit information is merged into a single record. It includes:

• energy and number of electrons, as the integral in the time interval
• position, as average weighted by the number of electrons
• the ID of the track depositing this energy

Entries are sorted by track ID number.

Definition at line 180 of file SimChannel.cxx.

  {
    // make a map of track ID values to sim::IDE objects

    if(startTDC > endTDC ){
      mf::LogWarning("SimChannel") << "requested tdc range is bogus: "
                                   << startTDC << " " << endTDC
                                   << " return empty vector";
      return {}; // returns an empty vector
    }

    std::map<TrackID_t, sim::IDE> idToIDE;

      //find the lower bound for this tdc and then iterate from there
    auto itr = findClosestTDCIDE(startTDC);

    while(itr != fTDCIDEs.end()){

      // check the tdc value for the iterator, break the loop if we
      // are outside the range
      if(itr->first > endTDC) break;

      // grab the vector of IDEs for this tdc
      auto const& idelist = itr->second;
      // now loop over them and add their content to the map
      for(auto const& ide : idelist){
        auto itTrkIDE = idToIDE.find(ide.trackID);
        if( itTrkIDE != idToIDE.end() ){
          // the IDE we are going to update:
          sim::IDE& trackIDE = itTrkIDE->second;

          double const nel1   = trackIDE.numElectrons;
          double const nel2   = ide.numElectrons;
          double const en1    = trackIDE.energy;
          double const en2    = ide.energy;
          double const energy = en1  + en2;
          double const weight = nel1 + nel2;

            // make a weighted average for the location information
          trackIDE.x            = (ide.x*nel2 + trackIDE.x*nel1)/weight;
          trackIDE.y            = (ide.y*nel2 + trackIDE.y*nel1)/weight;
          trackIDE.z            = (ide.z*nel2 + trackIDE.z*nel1)/weight;
          trackIDE.numElectrons = weight;
          trackIDE.energy = energy;
        } // end if the track id for this one is found
        else{
          idToIDE[ide.trackID] = sim::IDE(ide);
        }
      } // end loop over vector

      ++itr;
    } // end loop over tdc values

      // now fill the vector with the ides from the map
    std::vector<sim::IDE> ides;
    ides.reserve(idToIDE.size());
    for(auto const& itr : idToIDE){
      ides.push_back(itr.second);
    }

    return ides;
  }

Member Data Documentation

raw::ChannelID_t sim::SimChannel::fChannel

private

readout channel where electrons are collected

Definition at line 150 of file SimChannel.h.

TDCIDEs_t sim::SimChannel::fTDCIDEs

private

list of energy deposits for each TDC with signal

Definition at line 151 of file SimChannel.h.

---

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

• lardataobj/lardataobj/Simulation/SimChannel.h
• lardataobj/lardataobj/Simulation/SimChannel.cxx