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.