Reference: Auxiliary Attributes#

Overview#

Auxiliary attributes are simulation-level runtime attributes that expose values which may be consumed by ROOT-backed actors such as the PhaseSpaceActor, by generic filters, and by other actors internally.

Some auxiliary attributes are stateful and accumulate or propagate information along a track. Others are getter-only attributes that compute their value directly from the current Geant4 step.

In all cases, the user workflow is the same:

  1. activate the auxiliary attribute in the simulation

  2. configure its parameters

  3. use its name in an actor attribute list and/or a filter

Example:

aux = sim.activate_auxiliary_attribute(
    "InteractionCounterAttribute",
    "InteractionCount__compt",
)
aux.process_name = "compt"

phsp = sim.add_actor("PhaseSpaceActor", "phsp")
phsp.attributes = ["KineticEnergy", aux.name]

F = gate.GateFilterBuilder()
phsp.filter = F(aux.name) > 0

InteractionCounterAttribute#

Description#

Counts how often the current track has undergone a configured Geant4 process.

The user must provide:

  • process_name: name of the Geant4 process to count

Optional:

  • propagate_from_parent_track: if True, secondaries inherit the current counter snapshot from their parent at creation time

Example:

aux = sim.activate_auxiliary_attribute(
    "InteractionCounterAttribute",
    "InteractionCount__compt",
)
aux.process_name = "compt"

Reference#

class InteractionCounterAttribute(*args, **kwargs)[source]#

Count how often the current track has undergone a configured process.

User input parameters and default values:

  • name (must be provided):

    • Default value: None

  • process_name:

    • Default value: None

    • Description: Name of the Geant4 process to count.

  • propagate_from_parent_track:

    • Default value: False

    • Description: If true, secondaries inherit the current count snapshot from their parent at creation time.

Note

The ProcessDefinedStepInVolumeAttribute “hidden actor” was recently (May 2026) replaced by the auxiliary actor. These docs will get corresponding updates soon.

ProcessDefinedStepInVolumeAttributeLegacy#

Description#

Counts how often a configured process defined a step in a configured volume hierarchy for the current track.

The user must provide:

  • process_name

  • volume_name

Optional:

  • propagate_from_parent_track

This attribute is the auxiliary-attribute replacement for the old actor-based ProcessDefinedStepInVolumeAttributeLegacy helper.

Example:

aux = sim.activate_auxiliary_attribute(
    "ProcessDefinedStepInVolumeAttribute",
    "ProcessDefinedStep__compt__water_box",
)
aux.process_name = "compt"
aux.volume_name = "water_box"

LastProcessDefinedStepInVolumeAttribute#

Description#

Stores the last non-transportation process that defined a step in the configured volume hierarchy for the current track.

The user must provide:

  • volume_name

Optional:

  • propagate_from_parent_track

Example:

aux = sim.activate_auxiliary_attribute(
    "LastProcessDefinedStepInVolumeAttribute",
    "LastProcess__water_box",
)
aux.volume_name = "water_box"

Reference#

class LastProcessDefinedStepInVolumeAttribute(*args, **kwargs)[source]#

Store the last non-transportation process that defined a step in the configured volume for the current track. Optionally propagate the current process snapshot to secondaries created along the track.

User input parameters and default values:

  • name (must be provided):

    • Default value: None

  • propagate_from_parent_track:

    • Default value: False

    • Description: If true, secondaries inherit the current process snapshot from their parent at creation time.

  • volume_name:

    • Default value: None

    • Description: Name of the volume in which the last process is evaluated.

LastInteractionPositionInVolumeAttribute#

Description#

Stores the last interaction position seen on the current track inside the configured volume hierarchy. The stored position is taken from the pre-step point of a step whose defining process is not Transportation. If no qualifying interaction has been seen yet, the attribute returns (NaN, NaN, NaN).

The user must provide:

  • volume_name

Optional:

  • propagate_from_parent_track

Example:

aux = sim.activate_auxiliary_attribute(
    "LastInteractionPositionInVolumeAttribute",
    "LastInteractionPosition__water_box",
)
aux.volume_name = "water_box"

Reference#

class LastInteractionPositionInVolumeAttribute(*args, **kwargs)[source]#

Store the last interaction position seen on the current track inside the configured volume hierarchy. The stored position is taken from the pre-step point of the step whose defining process is not Transportation. Optionally propagate the current position snapshot to secondaries created along the track. If no qualifying interaction has been seen yet, the attribute returns (NaN, NaN, NaN).

User input parameters and default values:

  • name (must be provided):

    • Default value: None

  • propagate_from_parent_track:

    • Default value: False

    • Description: If true, secondaries inherit the current interaction position snapshot from their parent at creation time.

  • volume_name:

    • Default value: None

    • Description: Name of the volume in which the interaction position is evaluated.

UnscatteredPrimaryAttribute#

Description#

Exposes a flag indicating whether the current step belongs to an unscattered primary particle.

Returned values:

  • 1: unscattered primary

  • 0: otherwise

This attribute is getter-only and does not use persistent track storage.

Example:

aux = sim.activate_auxiliary_attribute(
    "UnscatteredPrimaryAttribute",
    "UnscatteredPrimaryAuxFlag",
)

F = gate.GateFilterBuilder()
actor.filter = F(aux.name) == 1

Reference#

class UnscatteredPrimaryAttribute(*args, **kwargs)[source]#

Return 1 when the current step belongs to an unscattered primary particle, and 0 otherwise.

User input parameters and default values:

  • name (must be provided):

    • Default value: None