sim::OpDetBacktrackerRecord Class Reference

Energy deposited on a readout Optical Detector by simulated tracks. More...

#include <OpDetBacktrackerRecord.h>

Classes
struct	CompareByTimePDclock

Public Types
typedef timePDclockSDP_t::first_type	storedTimePDclock_t
	Type for timePDclock tick used in the internal representation. More...
typedef std::vector< timePDclockSDP_t >	timePDclockSDPs_t
	Type of list of energy deposits for each timePDclock with signal. More...
typedef double	timePDclock_t
	Type for iTimePDclock tick used in the interface. More...
typedef SDP::TrackID_t	TrackID_t
	Type of track ID (the value comes from Geant4) More...

Public Member Functions
	OpDetBacktrackerRecord ()
	OpDetBacktrackerRecord (int detNum)
	Constructor: immediately sets the Optical Detector number. More...
void	AddScintillationPhotons (TrackID_t trackID, timePDclock_t timePDclock, double numberPhotons, double const *xyz, double energy)
	Add scintillation photons and energy to this OpticalDetector. More...
int	OpDetNum () const
	Returns the readout Optical Detector this object describes. More...
std::vector< sim::SDP >	TrackIDsAndEnergies (timePDclock_t startTimePDclock, timePDclock_t endTimePDclock) const
	Return all the recorded energy deposition within a time interval. More...
timePDclockSDPs_t const &	timePDclockSDPsMap () const
	Returns all the deposited energy information as stored. More...
double	Photons (timePDclock_t iTimePDclock) const
	Returns the total number of scintillation photons on this Optical Detector in the specified timePDclock. More...
double	Energy (timePDclock_t iTimePDclock) const
	Returns the total energy on this Optical Detector in the specified iTimePDclock [MeV]. More...
std::vector< sim::TrackSDP >	TrackSDPs (timePDclock_t startTimePDclock, timePDclock_t endTimePDclock) const
	Returns energies collected for each track within a time interval. More...
bool	operator< (const OpDetBacktrackerRecord &other) const
	Comparison: sorts by Optical Detector ID. More...
bool	operator== (const OpDetBacktrackerRecord &other) const
	Comparison: true if OpDetBacktrackerRecords have the same Optical Detector ID. More...
std::pair< TrackID_t, TrackID_t >	MergeOpDetBacktrackerRecord (const OpDetBacktrackerRecord &opDetNum, int offset)
	Merges the deposits from another Optical Detector 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 OpDetBacktrackerRecord 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
timePDclockSDPs_t::iterator	findClosestTimePDclockSDP (storedTimePDclock_t timePDclock)
	Return the iterator to the first timePDclockSDP not earlier than timePDclock. More...
timePDclockSDPs_t::const_iterator	findClosestTimePDclockSDP (storedTimePDclock_t timePDclock) const
	Return the (constant) iterator to the first timePDclockSDP not earlier than timePDclock. More...

Private Attributes
int	iOpDetNum
	OpticalDetector where the photons were detected. More...
timePDclockSDPs_t	timePDclockSDPs
	list of energy deposits for each timePDclock with signal More...

Detailed Description

Energy deposited on a readout Optical Detector by simulated tracks.

This class stores a time organized list of scintillation photons detected connected to the G4 tracks they originated from. This class also tracks the energy deposited by those tracks, and what fraction of the energy deposited is realted to the photons detected by this OpDet.

The information is organized by time: it is divided by timePDclock ticks (units of ns), and each timePDclock tick where some energy was deposited appears in a separate entry, while the quiet timePDclock ticks are omitted. For each timePDclock, 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::SDP class).

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

Definition at line 123 of file OpDetBacktrackerRecord.h.

Member Typedef Documentation

typedef timePDclockSDP_t::first_type sim::OpDetBacktrackerRecord::storedTimePDclock_t

Type for timePDclock tick used in the internal representation.

Definition at line 127 of file OpDetBacktrackerRecord.h.

typedef double sim::OpDetBacktrackerRecord::timePDclock_t

Type for iTimePDclock tick used in the interface.

Definition at line 144 of file OpDetBacktrackerRecord.h.

typedef std::vector<timePDclockSDP_t> sim::OpDetBacktrackerRecord::timePDclockSDPs_t

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

Definition at line 130 of file OpDetBacktrackerRecord.h.

typedef SDP::TrackID_t sim::OpDetBacktrackerRecord::TrackID_t

Type of track ID (the value comes from Geant4)

Definition at line 147 of file OpDetBacktrackerRecord.h.

Constructor & Destructor Documentation

sim::OpDetBacktrackerRecord::OpDetBacktrackerRecord

(

)

Definition at line 44 of file OpDetBacktrackerRecord.cxx.

    : iOpDetNum(-1) //set an impossible channel number in the case where this is called without an opticalchannel.
                     //The reason for doing this is to follow the structure of SimChannel, which uses kBogusChannel
  {}

sim::OpDetBacktrackerRecord::OpDetBacktrackerRecord ( int  detNum )

explicit

Constructor: immediately sets the Optical Detector number.

Definition at line 50 of file OpDetBacktrackerRecord.cxx.

    : iOpDetNum(detNum)
  {}

Member Function Documentation

void sim::OpDetBacktrackerRecord::AddScintillationPhotons	(	TrackID_t	trackID,
		timePDclock_t	timePDclock,
		double	numberPhotons,
		double const *	xyz,
		double	energy
	)

Add scintillation photons and energy to this OpticalDetector.

Parameters

trackID	ID of simulated track depositing this energy (from Geant4)
timePDclock	tick when this deposit was collected (ns)
numberPhotons	detected at the OpticalDetector at this time from this track
xyz	coordinates of original location of ionization/scintillation (3D array) [cm]
energy	energy deposited at this point by this track [MeV]

The iTimePDclock from OpFastScintillation (where OpDetBacktrackerRecords originate) is done with CLHEP::ns (units of nanoseconds).

Definition at line 55 of file OpDetBacktrackerRecord.cxx.

  {
    /**
     * The iTimePDclock from OpFastScintillation (where OpDetBacktrackerRecords originate) is done with CLHEP::ns (units of nanoseconds).
     */
    // look at the collection to see if the current iTimePDclock 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 photons? no good!
    if (( numberPhotons < std::numeric_limits<double>::epsilon() )
        || ( energy<=std::numeric_limits<double>::epsilon()      ))
    {
      // will throw
      MF_LOG_ERROR("OpDetBacktrackerRecord")
      << "AddTrackPhotons() trying to add to iTimePDclock #"
      << iTimePDclock
      << " "
      << numberPhotons
      << " photons with "
      << energy
      << " MeV of energy from track ID="
      << trackID;
      return;
    } // if no photons

    auto itr = findClosestTimePDclockSDP(iTimePDclock);

    // check if this iTimePDclock value is in the vector, it is possible that
    // the lower bound is different from the given TimePDclock, in which case
    // we need to add something for that TimePDclock
    if(itr        == timePDclockSDPs.end() ||
      (abs(itr->first - iTimePDclock) > .50 )){
       //itr->first != iTimePDclock){
      std::vector<sim::SDP> sdplist;
      sdplist.emplace_back(trackID,
                           numberPhotons,
                           energy,
                           xyz[0],
                           xyz[1],
                           xyz[2]
                           );
      timePDclockSDPs.emplace(itr, std::round(iTimePDclock), std::move(sdplist) );
    }
    else { // we have that iTimePDclock already; itr points to it

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

        if (sdp.trackID != trackID ) continue;

        // make a weighted average for the location information
        double weight    = sdp.numPhotons + numberPhotons;
        sdp.x            = (sdp.x * sdp.numPhotons + xyz[0]*numberPhotons)/weight;
        sdp.y            = (sdp.y * sdp.numPhotons + xyz[1]*numberPhotons)/weight;
        sdp.z            = (sdp.z * sdp.numPhotons + xyz[2]*numberPhotons)/weight;
        sdp.numPhotons   = weight;
        sdp.energy       = sdp.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 TimePDclock, so add sdp to the vector
      itr->second.emplace_back(trackID,
                               numberPhotons,
                               energy,
                               xyz[0],
                               xyz[1],
                               xyz[2]
                               );

    } // end of else "We have that iTimePDclock already"

  } // OpDetBacktrackerRecord::AddIonizationElectrons()

template<class Stream >

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

Dumps the full content of the OpDetBacktrackerRecord 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 316 of file OpDetBacktrackerRecord.h.

{
  out << first_indent << "OpDet #" << OpDetNum() << " read " << timePDclockSDPs.size()
    << " timePDclocks:\n";
  double opDet_energy = 0., opDet_photons = 0.;
  for (const auto& timePDclockinfo: timePDclockSDPs) {
    auto const iTimePDclock = timePDclockinfo.first;
    out << indent << "  timePDclock #" << iTimePDclock
      << " with " << timePDclockinfo.second.size() << " SDPs\n";
    double timePDclock_energy = 0., timePDclock_photons = 0.;
    for (const sim::SDP& sdp: timePDclockinfo.second) {
      out << indent
        << "    (" << sdp.x << ", " << sdp.y << ", " << sdp.z << ") "
        << sdp.numPhotons << " photons, " << sdp.energy << "MeV  (trkID="
        << sdp.trackID << ")\n";
      timePDclock_energy += sdp.energy;
      timePDclock_photons += sdp.numPhotons;
    } // for SDPs
    out << indent << "    => timePDclock #" << iTimePDclock << " CH #" << OpDetNum()
      << " collected " << timePDclock_energy << " MeV and "
      << timePDclock_photons <<" photons. \n";
    opDet_energy += timePDclock_energy;
    opDet_photons += timePDclock_photons;
  } // for timePDclocks
  out << indent << "  => channel #" << OpDetNum() << " collected "
    << opDet_photons << " photons and "<< opDet_energy << " MeV.\n" ;
} // sim::OpDetBacktrackerRecord::Dump<>()

template<typename Stream >

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

inline

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

Definition at line 284 of file OpDetBacktrackerRecord.h.

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

double sim::OpDetBacktrackerRecord::Energy

(

timePDclock_t

iTimePDclock

)

const

Returns the total energy on this Optical Detector in the specified iTimePDclock [MeV].

Definition at line 162 of file OpDetBacktrackerRecord.cxx.

  {
    double energy = 0.;

    auto itr = findClosestTimePDclockSDP(iTimePDclock);

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

        // loop over the list for this iTimePDclock value and add up
        // the total number of photons
      for(auto sdp : itr->second ){
        energy += sdp.energy;
      } // end loop over sim::SDP for this TimePDclock

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

    return energy;
  }

OpDetBacktrackerRecord::timePDclockSDPs_t::iterator sim::OpDetBacktrackerRecord::findClosestTimePDclockSDP ( storedTimePDclock_t  timePDclock )

private

Return the iterator to the first timePDclockSDP not earlier than timePDclock.

Definition at line 342 of file OpDetBacktrackerRecord.cxx.

  {
    return std::lower_bound
      (timePDclockSDPs.begin(), timePDclockSDPs.end(), iTimePDclock, CompareByTimePDclock());
  }

OpDetBacktrackerRecord::timePDclockSDPs_t::const_iterator sim::OpDetBacktrackerRecord::findClosestTimePDclockSDP ( storedTimePDclock_t  timePDclock ) const

private

Return the (constant) iterator to the first timePDclockSDP not earlier than timePDclock.

Definition at line 349 of file OpDetBacktrackerRecord.cxx.

  {
    return std::lower_bound
      ( timePDclockSDPs.begin(), timePDclockSDPs.end(), TimePDclock, CompareByTimePDclock() );
  }

std::pair< OpDetBacktrackerRecord::TrackID_t, OpDetBacktrackerRecord::TrackID_t > sim::OpDetBacktrackerRecord::MergeOpDetBacktrackerRecord	(	const OpDetBacktrackerRecord &	opDetNum,
		int	offset
	)

Merges the deposits from another Optical Detector into this one.

Parameters

opDetNum	the sim::OpDetBacktrackerRecord 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 opDetRecord is added to the current one. This is achieved by appending the energy deposit information (sim::SDP) at each iTimePDclock tick from the merged opDetRecord to the list of existing energy deposits for that iTimePDclock tick.

In addition, the track IDs of the merged opDetRecord 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 opDetRecord, equivalent to the lowest and the highest track IDs present in the merged opDetRecord, both augmented by the applied offset.

The opDetNum number of the merged opDetRecord is ignored.

Definition at line 282 of file OpDetBacktrackerRecord.cxx.

  {
    if( this->OpDetNum() != channel.OpDetNum() )
      throw std::runtime_error("ERROR OpDetBacktrackerRecord 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.timePDclockSDPsMap()){

      auto iTimePDclock  = itr.first;
      auto const& sdps = itr.second;

      // find the entry from this OpDetBacktrackerRecord corresponding to the iTimePDclock from the other
      auto itrthis = findClosestTimePDclockSDP(iTimePDclock);

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

      for(auto const& sdp : sdps){
        curSDPVec->emplace_back(sdp, offset);
        if( sdp.trackID+offset < range_trackID.first  )
          range_trackID.first = sdp.trackID+offset;
        if( sdp.trackID+offset > range_trackID.second )
          range_trackID.second = sdp.trackID+offset;
      }//end loop over SDPs

    }//end loop over TimePDclockSDPMap


    return range_trackID;

  }

int sim::OpDetBacktrackerRecord::OpDetNum ( ) const

inline

Returns the readout Optical Detector this object describes.

Definition at line 308 of file OpDetBacktrackerRecord.h.

{ return iOpDetNum; }

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

inline

Comparison: sorts by Optical Detector ID.

Definition at line 305 of file OpDetBacktrackerRecord.h.

{ return iOpDetNum < other.OpDetNum(); }

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

inline

Comparison: true if OpDetBacktrackerRecords have the same Optical Detector ID.

Definition at line 306 of file OpDetBacktrackerRecord.h.

{ return iOpDetNum == other.OpDetNum(); }

double sim::OpDetBacktrackerRecord::Photons

(

timePDclock_t

iTimePDclock

)

const

Returns the total number of scintillation photons on this Optical Detector in the specified timePDclock.

Definition at line 139 of file OpDetBacktrackerRecord.cxx.

  {
    double numPhotons = 0.;

    auto itr = findClosestTimePDclockSDP(iTimePDclock);

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

        // loop over the list for this iTimePDclock value and add up
        // the total number of electrons
      for(auto sdp : itr->second){
        numPhotons += sdp.numPhotons;
      } // end loop over sim::SDP for this TimePDclock

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

    return numPhotons;
  }

sim::OpDetBacktrackerRecord::timePDclockSDPs_t const & sim::OpDetBacktrackerRecord::timePDclockSDPsMap ( ) 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 iTimePDclock tick (collection of sim::SDP), and the number of that tick. The information is sorted by increasing timePDclock tick.

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

Definition at line 307 of file OpDetBacktrackerRecord.h.

{ return timePDclockSDPs; }

std::vector< sim::SDP > sim::OpDetBacktrackerRecord::TrackIDsAndEnergies	(	timePDclock_t	startTimePDclock,
		timePDclock_t	endTimePDclock
	)		const

Return all the recorded energy deposition within a time interval.

Parameters

startTimePDclock	iTimePDclock tick opening the time window
endTimePDclock	iTimePDclock 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 Optical Detector by each track ID active in the specified iTimePDclock 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 photons, as the integral in the time interval
• position, as average weighted by the number of photons
• the ID of the track depositing this energy

Entries are sorted by track ID number.

Definition at line 185 of file OpDetBacktrackerRecord.cxx.

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

    if(startTimePDclock > endTimePDclock ){
      mf::LogWarning("OpDetBacktrackerRecord") << "requested TimePDclock range is bogus: "
                                   << startTimePDclock << " " << endTimePDclock
                                   << " return empty vector";
      return {}; // returns an empty vector
    }

    std::map<TrackID_t, sim::SDP> idToSDP;

      //find the lower bound for this iTimePDclock and then iterate from there
    auto itr = findClosestTimePDclockSDP(startTimePDclock);

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

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

      // grab the vector of SDPs for this TimePDclock
      auto const& sdplist = itr->second;
      // now loop over them and add their content to the map
      for(auto const& sdp : sdplist){
        auto itTrkSDP = idToSDP.find(sdp.trackID);
        if( itTrkSDP != idToSDP.end() ){
          // the SDP we are going to update:
          sim::SDP& trackSDP = itTrkSDP->second;

          double const nPh1   = trackSDP.numPhotons;
          double const nPh2   = sdp.numPhotons;
          double const weight = nPh1 + nPh2;

            // make a weighted average for the location information
          trackSDP.x            = (sdp.x*nPh2 + trackSDP.x*nPh1)/weight;
          trackSDP.y            = (sdp.y*nPh2 + trackSDP.y*nPh1)/weight;
          trackSDP.z            = (sdp.z*nPh2 + trackSDP.z*nPh1)/weight;
          trackSDP.numPhotons = weight;
        } // end if the track id for this one is found
        else{
          idToSDP[sdp.trackID] = sim::SDP(sdp);
        }
      } // end loop over vector

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

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

    return sdps;
  }

std::vector< sim::TrackSDP > sim::OpDetBacktrackerRecord::TrackSDPs	(	timePDclock_t	startTimePDclock,
		timePDclock_t	endTimePDclock
	)		const

Returns energies collected for each track within a time interval.

Parameters

startTimePDclock	iTimePDclock tick opening the time window
endTimePDclock	iTimePDclock 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 Optical Detector by each track ID active in the specified iTimePDclock 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 Optical Detector in the specified time interval, divided by the total of the energy deposited by all tracks on this Optical Detector in that same time interval.

Entries are sorted by track ID number.

Definition at line 247 of file OpDetBacktrackerRecord.cxx.

  {

    std::vector<sim::TrackSDP> trackSDPs;

    if(startTimePDclock > endTimePDclock ){
      mf::LogWarning("OpDetBacktrackerRecord::TrackSDPs") << "requested iTimePDclock range is bogus: "
                                              << startTimePDclock << " " << endTimePDclock
                                              << " return empty vector";
      return trackSDPs;
    }

    double totalPhotons = 0.;
    std::vector<sim::SDP> const sdps = TrackIDsAndEnergies(startTimePDclock, endTimePDclock);
    for (auto const& sdp : sdps)
      totalPhotons += sdp.numPhotons;

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

    // loop over the entries in the map and fill the input vectors
    for (auto const& sdp : sdps){
      if(sdp.trackID == sim::NoParticleId) continue;
      trackSDPs.emplace_back(sdp.trackID, sdp.numPhotons/totalPhotons, sdp.numPhotons);
    }

    return trackSDPs;
  }

Member Data Documentation

int sim::OpDetBacktrackerRecord::iOpDetNum

private

OpticalDetector where the photons were detected.

Definition at line 133 of file OpDetBacktrackerRecord.h.

timePDclockSDPs_t sim::OpDetBacktrackerRecord::timePDclockSDPs

private

list of energy deposits for each timePDclock with signal

Definition at line 134 of file OpDetBacktrackerRecord.h.

---

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

• lardataobj/lardataobj/Simulation/OpDetBacktrackerRecord.h
• lardataobj/lardataobj/Simulation/OpDetBacktrackerRecord.cxx