Phase Space Source#

Description#

The Phase Space source is a source type within GATE that utilizes a prebuilt Phase Space to emit particles. Each particle emitted at the beginning of an event is based on the particle’s state (position, energy, direction, particle type, and weight) stored in the Phase Space file.

To use this source, declare a PhaseSpaceSource within the add_source method. The file path of the desired Phase Space source must be provided. Only ROOT files are supported as input for this source.

By default, the parameter names corresponding to the particle states align with the ROOT output generated by the PhaseSpaceActor. However, users can provide custom ROOT files and specify alternative parameter names for the particle state components. The Phase Space file is read sequentially starting from the beginning by default. The entry_start option allows users to specify a custom starting point within the file.

To optimize performance and reduce computational costs associated with event-by-event file access, a batch of (N) particles is preloaded into the computer’s RAM. The batch size (N) is user-definable, with 100,000 being a recommended trade-off between memory usage and performance.

Additionally, users can apply positional offsets or rotation matrices to the positions and directions read from the Phase Space file. By default, the positions and directions of particles are defined relative to the coordinates of the parent volume. Setting the global_flag option to True changes this behavior, allowing particles to be emitted according to the world coordinate system.

Below is an example Python script for defining a Phase Space source:

source = sim.add_source("PhaseSpaceSource", "phsp_source_global")
source.attached_to = user_plane_source.name
source.position_key = "PrePositionLocal"
source.direction_key = "PreDirectionLocal"
source.PDGCode_key = "PDGCode"
source.energy_key = "KineticEnergy"
source.weight_key = "Weight"
source.entry_start = np.random.randint(0, 10**9, 1)[0]
source.batch_size = 100000
source.global_flag = False
source.translate_position = False
source.rotate_direction = False

This macro works in single-threaded mode. To enable multithreading, the entry_start parameter must be defined as a list of indices, where the length of the list corresponds to the number of allocated threads. For example:

source.entry_start = np.random.randint(0, 10**9, sim.number_of_threads)

If any of the provided entry_start indices exceed the size of the Phase Space file, the index will be adjusted automatically using the modulo operator relative to the file size.

Reference#

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

Source of particles from a (root) phase space. Read position + direction + energy + weight from the root and use them as event.

If “global flag” is True, the position/direction are global, ie in the world coordinate system. If it is False, it uses the coordinate system of the volume it is attached to.

The Time in the phsp is not implemented (yet)

User input parameters and default values:

  • PDGCode_key:

  • activity:

    • Default value: 0

    • Description: Activity of the source in Bq (exclusive with ‘n’)

  • attached_to:

    • Default value: world

    • Description: Name of the volume to which the source is attached.

  • batch_size:

    • Default value: 10000

    • Description: Batch size to read the phsp

  • direction_key:

    • Default value: PreDirectionLocal

    • Description: Key in the phsp that contain the direction of the particle. Automatically set the direction_key_x, direction_key_y, direction_key_z keys by adding _X _Y _Z

  • direction_key_x:

    • Default value: None

    • Description: Key in the phsp that contain the direction X of the particle

  • direction_key_y:

    • Default value: None

    • Description: Key in the phsp that contain the direction Y of the particle

  • direction_key_z:

    • Default value: None

    • Description: Key in the phsp that contain the direction Z of the particle

  • dynamic_params (set internally, i.e. read-only):

    • Default value: None

    • Description: Dictionary of dictionaries, where each dictionary specifies how the parameters of this object should evolve over time during the simulation. You cannot set this parameter directly. Instead, use the ‘add_dynamic_parametrisation()’ method of your object.If None, the object is static (default).

  • end_time:

    • Default value: None

    • Description: End time of the source

  • energy_key:

    • Default value: KineticEnergy

    • Description: Key in the phsp that contain the energy of the particle

  • entry_start:

    • Default value: None

    • Description: Starting particle in the phase-space (for MT, provide a list of entries, one for each thread)

  • generate_until_next_primary:

    • Default value: False

    • Description: FIXME

  • global_flag:

    • Default value: False

    • Description: If true, the positions of the generated particles in the phase-space are in the world coordinate system. If false, they are relative to the volumethis source is attached to

  • half_life:

    • Default value: -1

    • Description: Half-life decay (-1 if no decay). Only when used with ‘activity’

  • isotropic_direction:

    • Default value: False

    • Description: If true, It enables to generate a particle with a position energy and weight according to the provided phase but with an isotropic momentum.

  • mother:

    • Deprecated: The user input parameter ‘mother’ is deprecated. Use ‘attached_to’ instead.

  • n:

    • Default value: 0

    • Description: Number of particle to generate (exclusive with ‘activity’)

  • name (must be provided):

    • Default value: None

  • particle:

    • Default value:

    • Description: FIXME

  • phsp_file:

    • Default value: None

    • Description: Filename of the phase-space file (root). This is required

  • position:

    • Default value: {‘translation’: [0, 0, 0], ‘rotation’: array([[1., 0., 0.],, [0., 1., 0.],, [0., 0., 1.]])}

    • Description: Default position+rotation if it is not read in the phsp

  • position_key:

    • Default value: PrePositionLocal

    • Description: Key in the phsp that contain the position of the particle. Automatically set the position_key_x, position_key_y, position_key_z keys by adding _X _Y _Z

  • position_key_x:

    • Default value: None

    • Description: Key in the phsp that contain the position X of the particle

  • position_key_y:

    • Default value: None

    • Description: Key in the phsp that contain the position Y of the particle

  • position_key_z:

    • Default value: None

    • Description: Key in the phsp that contain the position Z of the particle

  • primary_PDGCode:

    • Default value: 0

    • Description: FIXME

  • primary_lower_energy_threshold:

    • Default value: 0

    • Description: FIXME

  • rotate_direction:

    • Default value: False

    • Description: FIXME

  • start_time:

    • Default value: None

    • Description: Starting time of the source

  • translate_position:

    • Default value: False

    • Description: FIXME

  • verbose:

    • Default value: False

    • Description: FIXME

  • verbose_batch:

    • Default value: False

    • Description: FIXME

  • weight_key:

    • Default value: Weight

    • Description: Key in the phsp that contain the weight of the particle