Details: Filters#

Overview#

Filters are objects attached to Actors that accept or reject a particle, track, or step based on specific criteria. If a filter rejects a step, the actor will ignore it (e.g., a PhaseSpaceActor will not record the particle, or a KillActor will not kill it).

Gate provides a “Pythonic” syntax to create and combine filters naturally using logical operators.

from opengate.actors.filters import GateFilterBuilder

# 1. Initialize the filter factory
F = GateFilterBuilder()

# 2. Create a complex filter logic
# Example: Keep only gammas with Energy > 100 keV AND (Time < 10 ns OR Unscattered)
my_filter = (F.ParticleName == "gamma") & (F.KineticEnergy > 100 * keV) & \
            ((F.GlobalTime < 10 * ns) | F.Unscattered)

# 3. Attach to an actor
actor.filter = my_filter

You can attach the same filter to multiple actors.

Syntax and Logic#

The GateFilterBuilder factory (conveniently abbreviated as F in a user script) allows you to build filters based on simulation attributes.

Attribute Comparison#

You can compare attributes (like Energy, Time, Position) using standard Python comparison operators: <, <=, >, >=, ==, !=. The results of the comparison statement is the actual filter to be attached to the actor.

# Energy filter
f1 = F.KineticEnergy > 10 * MeV

# Position filter (X coordinate)
f2 = F.PostPosition_X < 0 * mm

# String/Particle filter
f3 = F.ParticleName == "proton"

# String "contains" filter (e.g., matches "proton", "anti_proton")
f4 = F.ParticleName.contains("proton")

Logical Combination#

Filters can be combined using bitwise operators:

  • AND (&): Both conditions must be true.

  • OR (|): At least one condition must be true.

  • NOT (~): Invert the condition.

Warning

Parentheses are mandatory! Due to Python’s operator precedence, you must wrap every comparison in parentheses when combining them.

  • Correct: (F.KineticEnergy > 10) & (F.ParticleName == "gamma")

  • Wrong: F.KineticEnergy > 10 & F.ParticleName == "gamma" (Raises a syntax error)

Available Attributes#

You can filter on any attribute available in the GateDigiAttributeManager (C++ class). Common attributes include:

  • KineticEnergy, TotalEnergyDeposit

  • GlobalTime, LocalTime

  • PostPosition_X, PostPosition_Y, PostPosition_Z

  • PreDirection_X, PreDirection_Y, PreDirection_Z

  • ParticleName, CreatorProcess

  • TrackID, ParentID, RunID, EventID

Special Filters#

Unscattered Primary Filter#

This filter accepts particles that are primary particles and have not yet undergone any interaction (scattering).

# Syntax 1: Using the property directly
f = F.UnscatteredPrimaryFlag

# Syntax 2: Explicit comparison
f = (F.UnscatteredPrimaryFlag == True)

# Syntax 3: Reject unscattered (keep only scattered)
f = ~F.UnscatteredPrimaryFlag

Reference#

class GateFilterBuilder[source]#

Entry point for the sugar syntax: F = GateFilterBuilder()

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

A filter to be attached to an actor.

User input parameters and default values:

  • name (must be provided):

    • Default value: None

  • negate:

    • Default value: False

    • Description: If True, invert the result of this filter.

  • policy:

    • Deprecated: Use boolean filter

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

Base class for attribute comparisons (Float, Int, String).

User input parameters and default values:

  • attribute:

    • Default value: None

    • Description: Attribute name to be considered.

  • compare_operation:

    • Default value: None

    • Description: Comparison operator shorthand such as lt, le, gt, ge, eq.

  • compare_value:

    • Default value: None

    • Description: Reference value used by the comparison.

  • name (must be provided):

    • Default value: None

  • negate:

    • Default value: False

    • Description: If True, invert the result of this filter.

  • policy:

    • Deprecated: Use boolean filter

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

User input parameters and default values:

  • filters:

    • Default value: []

    • Description: todo

  • name (must be provided):

    • Default value: None

  • negate:

    • Default value: False

    • Description: If True, invert the result of this filter.

  • operator:

    • Default value: None

    • Allowed values: (‘and’, ‘or’)

    • Description: todo

  • policy:

    • Deprecated: Use boolean filter

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

User input parameters and default values:

  • name (must be provided):

    • Default value: None

  • negate:

    • Default value: False

    • Description: If True, invert the result of this filter.

  • policy:

    • Deprecated: Use boolean filter