Tracks detailed information about photonuclear interactions. More...

#include <PhotonuclearTracker.h>

Public Member Functions
	PhotonuclearTracker (const std::string &name, framework::config::Parameters &parameters)
	Constructor.

virtual	~PhotonuclearTracker ()=default
	Destructor.

std::vector< TYPE >	getTypes () override
	Get the types of actions this class handles.

void	beginOfEventAction (const G4Event *event) override
	Called at the beginning of each event.

void	endOfEventAction (const G4Event *event) override
	Called at the end of each event.

void	stepping (const G4Step *step) override
	Called after each simulation step.

void	preUserTrackingAction (const G4Track *track) override
	Called before tracking a new track.

void	postUserTrackingAction (const G4Track *track) override
	Called after tracking a track.

std::vector< ldmx::PhotonuclearInteraction >	getInteractions () const
	Get the collection of PN interactions for this event.

Public Member Functions inherited from simcore::UserAction
	UserAction (const std::string &name, framework::config::Parameters &parameters)
	Constructor.

	DECLARE_FACTORY (UserAction, std::shared_ptr< UserAction >, const std::string &, framework::config::Parameters &)
	factory for user actions

virtual	~UserAction ()=default
	Destructor.

virtual void	beginOfRunAction (const G4Run *)
	Method called at the beginning of a run.

virtual void	endOfRunAction (const G4Run *)
	Method called at the end of a run.

virtual G4ClassificationOfNewTrack	classifyNewTrack (const G4Track *, const G4ClassificationOfNewTrack &cl)
	Method called when a track is updated.

virtual void	newStage ()
	Method called at the beginning of a new stage.

virtual void	prepareNewEvent ()
	Method called at the beginning of a new event.

Static Public Member Functions
static PhotonuclearTracker *	get ()
	Get the current PhotonuclearTracker instance.

Private Member Functions
void	extractTargetInfo (const G4Step *step, int &Z, int &A, std::string &material)
	Extract target nucleus information from the current step.

ldmx::PhotonuclearInteraction::ParticleInfo	createParticleInfo (const G4Track *track)
	Create a ParticleInfo struct from a G4Track.

Private Attributes
std::vector< ldmx::PhotonuclearInteraction >	pn_interactions_
	Collection of PN interactions in this event.

std::map< int, int >	secondary_to_pn_index_
	Maps secondary track ID -> index in pn_interactions_ Used to quickly find which PN interaction a secondary belongs to.

std::map< int, int >	descendant_ancestry_
	Maps descendant track ID -> immediate secondary track ID Propagates through the genealogy to trace back to the original PN secondary.

Static Private Attributes
static PhotonuclearTracker *	instance = nullptr
	Static pointer to the current instance.

Additional Inherited Members
Protected Member Functions inherited from simcore::UserAction
UserEventInformation *	getEventInfo () const
	Get a handle to the event information.

const std::map< int, ldmx::SimParticle > &	getCurrentParticleMap () const
	Get the current particle map.

void	abortEvent (const std::string &reason) const
	Helper to abort an event with a message.

Protected Attributes inherited from simcore::UserAction
std::string	name_ {""}
	Name of the UserAction.

framework::config::Parameters	parameters_
	The set of parameters used to configure this class.

mutable::framework::logging::logger	the_log_
	the logging channel user actions can use `ldmx_log` with

Detailed Description

Tracks detailed information about photonuclear interactions.

This UserAction captures comprehensive details about photonuclear (PN) interactions during simulation, including:

Incident photon kinematics
Target nucleus information
All immediate secondary particles from the cascade
Mapping from cascade products to their final state descendants

The tracker operates by:

Detecting PN interactions in the stepping action (when secondaries are created)
Capturing all immediate secondaries and their G4 track IDs
Tracking descendants through the event via ancestry propagation
Building final state maps when tracks complete

The collected interactions are saved to the event bus as a vector: "PhotonuclearInteractions"

Definition at line 52 of file PhotonuclearTracker.h.

Constructor & Destructor Documentation

◆ PhotonuclearTracker()

simcore::PhotonuclearTracker::PhotonuclearTracker	(	const std::string &	name,
		framework::config::Parameters &	parameters )

Constructor.

Parameters

name	Name of this user action
parameters	Configuration parameters

Definition at line 18 of file PhotonuclearTracker.cxx.

    : UserAction(name, parameters) {
  instance = this;  // Set the static instance pointer
}

References instance.

Member Function Documentation

◆ beginOfEventAction()

void simcore::PhotonuclearTracker::beginOfEventAction ( const G4Event * event )

overridevirtual

Called at the beginning of each event.

Clears the interaction collection and ancestry maps for the new event.

Parameters

event Geant4 event object

Reimplemented from simcore::UserAction.

Definition at line 24 of file PhotonuclearTracker.cxx.

                                                                 {
  // Clear all data structures for the new event
  pn_interactions_.clear();
  secondary_to_pn_index_.clear();
  descendant_ancestry_.clear();
}

References descendant_ancestry_, pn_interactions_, and secondary_to_pn_index_.

◆ createParticleInfo()

ldmx::PhotonuclearInteraction::ParticleInfo simcore::PhotonuclearTracker::createParticleInfo ( const G4Track * track )

private

Create a ParticleInfo struct from a G4Track.

Parameters

track Geant4 track

Returns: ParticleInfo with kinematic data

Definition at line 183 of file PhotonuclearTracker.cxx.

                                                            {
  ldmx::PhotonuclearInteraction::ParticleInfo info;
 
  info.track_id_ = track->GetTrackID();
  info.pdg_id_ = track->GetDefinition()->GetPDGEncoding();
 
  auto position = track->GetPosition();
  info.x_ = position.x();
  info.y_ = position.y();
  info.z_ = position.z();
 
  auto momentum = track->GetMomentum();
  info.px_ = momentum.x();
  info.py_ = momentum.y();
  info.pz_ = momentum.z();
 
  info.energy_ =
      track->GetKineticEnergy() + track->GetDefinition()->GetPDGMass();
  info.time_ = track->GetGlobalTime();
 
  return info;
}

Referenced by stepping().

◆ endOfEventAction()

void simcore::PhotonuclearTracker::endOfEventAction ( const G4Event * event )

overridevirtual

Called at the end of each event.

Final cleanup and validation of collected data.

Parameters

event Geant4 event object

Reimplemented from simcore::UserAction.

Definition at line 31 of file PhotonuclearTracker.cxx.

                                                               {
  ldmx_log(debug) << "Event complete, recorded " << pn_interactions_.size()
                  << " PN interactions";
}

References pn_interactions_.

◆ extractTargetInfo()

void simcore::PhotonuclearTracker::extractTargetInfo	(	const G4Step *	step,
		int &	Z,
		int &	A,
		std::string &	material )

private

Extract target nucleus information from the current step.

Parameters

step	Current Geant4 step
Z	Output: atomic number
A	Output: mass number
material	Output: material name

Definition at line 169 of file PhotonuclearTracker.cxx.

                                                                 {
  const G4Material* mat = step->GetPreStepPoint()->GetMaterial();
  material = mat->GetName();
 
  // Get the element - for compound materials, we take the first element
  // (This is a simplification; the actual nucleus struck may vary)
  const G4Element* element = mat->GetElement(0);
  Z = static_cast<int>(element->GetZ());
  A = static_cast<int>(element->GetA() /
                       (CLHEP::g / CLHEP::mole));  // Convert to mass number
}

Referenced by stepping().

◆ get()

static PhotonuclearTracker * simcore::PhotonuclearTracker::get ( )

inlinestatic

Get the current PhotonuclearTracker instance.

Returns: Pointer to the current instance, or nullptr if not created

Definition at line 139 of file PhotonuclearTracker.h.

139{ return instance; }

References instance.

◆ getInteractions()

std::vector< ldmx::PhotonuclearInteraction > simcore::PhotonuclearTracker::getInteractions ( ) const

inline

Get the collection of PN interactions for this event.

Returns: Vector of PhotonuclearInteraction objects

Definition at line 130 of file PhotonuclearTracker.h.

                                                                 {
    return pn_interactions_;
  }

References pn_interactions_.

◆ getTypes()

std::vector< TYPE > simcore::PhotonuclearTracker::getTypes ( )

inlineoverridevirtual

Get the types of actions this class handles.

Returns: Vector of action types (EVENT, STEPPING, TRACKING)

Implements simcore::UserAction.

Definition at line 73 of file PhotonuclearTracker.h.

                                      {
    return {TYPE::EVENT, TYPE::STEPPING, TYPE::TRACKING};
  }

◆ postUserTrackingAction()

void simcore::PhotonuclearTracker::postUserTrackingAction ( const G4Track * track )

overridevirtual

Called after tracking a track.

Records final state particles when tracks complete, building the descendant map for PN interactions.

Parameters

track Current Geant4 track

Reimplemented from simcore::UserAction.

Definition at line 138 of file PhotonuclearTracker.cxx.

                                                                     {
  int track_id = track->GetTrackID();
 
  // Check if this track is a descendant of a PN secondary
  auto ancestry_it = descendant_ancestry_.find(track_id);
  if (ancestry_it == descendant_ancestry_.end()) {
    return;  // Not related to any PN interaction
  }
 
  // This track is a descendant! Find which immediate secondary it came from
  int immediate_secondary_id = ancestry_it->second;
 
  // Find which PN interaction this secondary belongs to
  auto pn_index_it = secondary_to_pn_index_.find(immediate_secondary_id);
  if (pn_index_it == secondary_to_pn_index_.end()) {
    ldmx_log(warn) << "Inconsistent ancestry mapping for track " << track_id;
    return;
  }
 
  int pn_index = pn_index_it->second;
 
  // Record ALL descendants (intermediate + final state) for full cascade
  // genealogy This provides information beyond SimParticles which only has
  // final state
  pn_interactions_[pn_index].addDescendant(immediate_secondary_id, track_id);
 
  ldmx_log(debug) << "  Recording descendant: track " << track_id
                  << " -> secondary " << immediate_secondary_id
                  << " in PN interaction " << pn_index;
}

References descendant_ancestry_, pn_interactions_, and secondary_to_pn_index_.

◆ preUserTrackingAction()

void simcore::PhotonuclearTracker::preUserTrackingAction ( const G4Track * track )

overridevirtual

Called before tracking a new track.

Propagates ancestry information for descendants of PN secondaries.

Parameters

track Current Geant4 track

Reimplemented from simcore::UserAction.

Definition at line 121 of file PhotonuclearTracker.cxx.

                                                                    {
  // Propagate ancestry information to new tracks
  int track_id = track->GetTrackID();
  int parent_id = track->GetParentID();
 
  // If the parent is a descendant of a PN secondary, this track is too
  auto parent_it = descendant_ancestry_.find(parent_id);
  if (parent_it != descendant_ancestry_.end()) {
    // Propagate the immediate secondary ID to this descendant
    descendant_ancestry_[track_id] = parent_it->second;
 
    ldmx_log(debug) << "  Track " << track_id
                    << " is descendant of PN secondary " << parent_it->second
                    << " (parent=" << parent_id << ")";
  }
}

References descendant_ancestry_.

◆ stepping()

void simcore::PhotonuclearTracker::stepping ( const G4Step * step )

overridevirtual

Called after each simulation step.

Detects PN interactions by examining secondaries created in the step. When a PN interaction is found, captures all details and initializes genealogy tracking.

Parameters

step	Current Geant4 step

Reimplemented from simcore::UserAction.

Definition at line 36 of file PhotonuclearTracker.cxx.

                                                     {
  // Check if any secondaries were created in this step
  const std::vector<const G4Track*>* secondaries =
      step->GetSecondaryInCurrentStep();
  if (!secondaries || secondaries->empty()) return;
 
  // Check if any secondary was created by a photonNuclear process
  bool is_pn_interaction = false;
  for (const G4Track* secondary : *secondaries) {
    const G4VProcess* creator = secondary->GetCreatorProcess();
    if (creator) {
      const G4String& creator_name = creator->GetProcessName();
      if (creator_name.contains("photonNuclear")) {
        is_pn_interaction = true;
        break;
      }
    }
  }
 
  if (!is_pn_interaction) return;
 
  // We have a PN interaction! Create a new PhotonuclearInteraction object
  ldmx::PhotonuclearInteraction pn_interaction;
 
  // Get the incident photon information from the track that took the step
  const G4Track* incident_track = step->GetTrack();
  const G4StepPoint* pre_step = step->GetPreStepPoint();
 
  auto incident_pos = pre_step->GetPosition();
  auto incident_momentum = pre_step->GetMomentum();
 
  pn_interaction.setIncidentPhoton(
      incident_track->GetTrackID(),
      incident_track->GetDefinition()->GetPDGEncoding(),
      pre_step->GetKineticEnergy() +
          incident_track->GetDefinition()->GetPDGMass(),
      incident_momentum.x(), incident_momentum.y(), incident_momentum.z(),
      incident_pos.x(), incident_pos.y(), incident_pos.z(),
      pre_step->GetGlobalTime());
 
  // Get target nucleus information
  int target_z, target_a;
  std::string target_material;
  extractTargetInfo(step, target_z, target_a, target_material);
  pn_interaction.setTarget(target_z, target_a, target_material);
 
  // Set interaction metadata
  G4VPhysicalVolume* volume{incident_track->GetVolume()};
  pn_interaction.setInteractionVolume(volume ? volume->GetName() : "null");
  pn_interaction.setProcessName("photonNuclear");
 
  // Record all immediate secondaries
  int pn_index = pn_interactions_.size();
 
  // Set target Z/A in UserEventInformation for the first PN interaction
  if (pn_index == 0) {
    auto event_info = static_cast<UserEventInformation*>(
        G4EventManager::GetEventManager()->GetUserInformation());
    if (event_info) {
      event_info->setPNTargetZ(target_z);
      event_info->setPNTargetA(target_a);
    }
  }
  for (const G4Track* secondary : *secondaries) {
    auto particle_info = createParticleInfo(secondary);
    pn_interaction.addImmediateSecondary(particle_info);
 
    // Map this secondary to the current PN interaction
    int secondary_id = secondary->GetTrackID();
    secondary_to_pn_index_[secondary_id] = pn_index;
    // Initialize ancestry: immediate secondaries map to themselves
    descendant_ancestry_[secondary_id] = secondary_id;
 
    ldmx_log(debug) << "  Immediate secondary: track_id=" << secondary_id
                    << " pdg=" << particle_info.pdg_id_
                    << " E=" << particle_info.energy_ << " MeV";
  }
 
  // Add the completed PN interaction to the collection
  pn_interactions_.push_back(pn_interaction);
 
  ldmx_log(debug) << "Detected PN interaction #" << pn_index << " with "
                  << secondaries->size() << " secondaries";
}

References ldmx::PhotonuclearInteraction::addImmediateSecondary(), createParticleInfo(), descendant_ancestry_, extractTargetInfo(), pn_interactions_, secondary_to_pn_index_, ldmx::PhotonuclearInteraction::setIncidentPhoton(), ldmx::PhotonuclearInteraction::setInteractionVolume(), ldmx::PhotonuclearInteraction::setProcessName(), and ldmx::PhotonuclearInteraction::setTarget().

Member Data Documentation

◆ descendant_ancestry_

std::map<int, int> simcore::PhotonuclearTracker::descendant_ancestry_

private

Maps descendant track ID -> immediate secondary track ID Propagates through the genealogy to trace back to the original PN secondary.

Definition at line 173 of file PhotonuclearTracker.h.

Referenced by beginOfEventAction(), postUserTrackingAction(), preUserTrackingAction(), and stepping().

◆ instance

PhotonuclearTracker * simcore::PhotonuclearTracker::instance = nullptr

staticprivate

Static pointer to the current instance.

Definition at line 176 of file PhotonuclearTracker.h.

Referenced by get(), and PhotonuclearTracker().

◆ pn_interactions_

std::vector<ldmx::PhotonuclearInteraction> simcore::PhotonuclearTracker::pn_interactions_

private

Collection of PN interactions in this event.

Definition at line 164 of file PhotonuclearTracker.h.

Referenced by beginOfEventAction(), endOfEventAction(), getInteractions(), postUserTrackingAction(), and stepping().

◆ secondary_to_pn_index_

std::map<int, int> simcore::PhotonuclearTracker::secondary_to_pn_index_

private

Maps secondary track ID -> index in pn_interactions_ Used to quickly find which PN interaction a secondary belongs to.

Definition at line 168 of file PhotonuclearTracker.h.

Referenced by beginOfEventAction(), postUserTrackingAction(), and stepping().

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

SimCore/include/SimCore/G4User/PhotonuclearTracker.h
SimCore/src/SimCore/G4User/PhotonuclearTracker.cxx

Public Member Functions

Static Public Member Functions

Private Member Functions

Private Attributes

Static Private Attributes

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ PhotonuclearTracker()

Member Function Documentation

◆ beginOfEventAction()

◆ createParticleInfo()

◆ endOfEventAction()

◆ extractTargetInfo()

◆ get()

◆ getInteractions()

◆ getTypes()

◆ postUserTrackingAction()

◆ preUserTrackingAction()

◆ stepping()

Member Data Documentation

◆ descendant_ancestry_

◆ instance

◆ pn_interactions_

◆ secondary_to_pn_index_