14.5. Phase Space Actor
Table of Contents
Particle information
A phase space actor in GATE records detailed information about particles as they cross a chosen surface or volume. Instead of scoring a derived quantity like dose or fluence, it saves the microscopic state of many individual particles. This state is often called the particle phase space and includes at least the particle type, position, direction, and energy, plus optional extra attributes such as time or event identifiers.
When you attach a phase space actor to a volume, GATE writes an entry every time a particle fulfills the actor’s recording condition. Typical conditions are entering a surface, exiting a surface, or simply being inside a scoring plane. Each recorded entry corresponds to one particle crossing and is similar to a “snapshot” of that particle at that location.
Because the phase space actor can easily produce very large files, it is important to think carefully about which particles to record and which attributes are required for your later analysis. For instance, if you only need photons for a detector study, you should filter out all other species in order to reduce file size and speed up the simulation.
A typical phase space record contains at least these items:
- Particle type, for example gamma, electron, positron, proton.
- Spatial coordinates, usually three components $(x, y, z)$ in the simulation reference frame.
- Direction cosines, usually three components $(u_x, u_y, u_z)$ that describe the direction of motion.
- Kinetic energy $E$ of the particle.
- Time $t$ at which the particle reaches the plane or volume.
- Event or track identifiers so that you can relate multiple phase space entries to the same primary event.
A phase space actor records individual particle states, not integrated quantities like dose. You must post-process phase space data to obtain spectra, fluence maps, or other high-level results.
Many workflows use phase space data in two stages. In the first stage, you simulate a complex geometry such as a linac head or a CT tube and record particles on a plane downstream. In the second stage, you use that phase space file as a source in another simulation, for example one that includes only the patient or detector. This reuse significantly reduces computation time, because the expensive upstream transport is performed once and then recycled.
Position
The position stored in a phase space record describes where the particle crosses the scoring surface or volume. In GATE, positions are expressed in the global simulation coordinate system, using the units that you have defined, typically millimeters or centimeters.
For each recorded particle, the phase space actor saves three coordinates $x$, $y$, and $z$. If you use a planar scoring surface, one coordinate will usually be approximately constant for all particles, for example $z = z_0$ for a plane perpendicular to the $z$ axis. The other two coordinates then provide the spatial distribution of the beam over that plane. This is essential when you want to reconstruct fluence profiles or spatial distributions at that location.
In many medical physics applications, the phase space plane is chosen to coincide with a physical interface. For example, in external beam radiotherapy it is common to place a phase space actor just below the treatment head, above the patient or a water phantom. The recorded positions then describe the incident particle field on the patient surface. In PET or SPECT detector studies, a phase space surface can be placed just in front of the crystal to characterize the incoming gamma field.
To interpret these positions correctly, you must be aware of the origin and orientation of your simulation geometry. The world volume has its own coordinate system, and each child volume can be placed with a translation and rotation. The phase space actor output is always in the global frame, so if you want to express results in a local detector coordinate system, you may need to apply coordinate transformations during analysis.
Always check the coordinate system and units of phase space positions. Misinterpreting axes or units, for example mixing up mm and cm, can lead to incorrect beam profiles or misaligned dose calculations.
When analyzing phase space positions, common tasks include:
- Building 2D fluence maps in $(x, y)$ at a fixed $z$ plane.
- Extracting 1D beam profiles along one direction, for example $x$ or $y$.
- Computing beam spot size or field size using statistical descriptors such as full width at half maximum.
Energy
The energy stored in a phase space record is the kinetic energy of the particle at the moment it crosses the scoring surface or volume. In GATE and Geant4, energies are typically expressed in units such as keV or MeV, chosen via the units system.
The phase space actor writes one energy value $E$ per recorded particle. This quantity allows you to reconstruct energy spectra, evaluate beam quality, and verify that your transport and physics settings produce the expected energy distributions at a given location.
For an x‑ray or gamma beam, the phase space energy distribution corresponds to the photon spectrum at that plane. For a proton or electron beam, it reflects both the initial spectrum and the energy losses that have occurred upstream, for example in collimators, filters, or air. If you are using a phase space file as an input source for a second simulation, the energies in the file directly define the incident energy distribution on that downstream geometry.
From phase space data, you can form histograms of $E$ to obtain energy spectra. You can also compute mean energy, energy spread, or energy windows. This is particularly useful when validating that your simulation reproduces known spectra from literature or from measurements.
When recording and later reusing phase space data, you must use consistent energy units throughout your simulations and analysis. Mixing keV and MeV in configuration or analysis will produce incorrect spectra and dose estimates.
It is also common to apply energy-based filters directly in the phase space actor. For example, you may choose to record only photons within a specific energy range, such as a PET photopeak window or a megavoltage therapeutic beam range. This reduces file size and ensures that the stored data is tailored to your planned analysis.
Direction
The direction of motion stored by the phase space actor specifies where the particle is heading when it crosses the scoring surface or volume. In GATE, this is expressed as a normalized direction vector with three components, commonly written as $(u_x, u_y, u_z)$, where
$$
\sqrt{u_x^2 + u_y^2 + u_z^2} = 1.
$$
These components are the direction cosines relative to the global coordinate axes. They allow you to reconstruct angular distributions, beam divergence, and scattering patterns. For example, a perfectly collimated beam along the positive $z$ axis would have $u_x \approx 0$, $u_y \approx 0$, and $u_z \approx 1$ for all particles, while a scattered field would exhibit a spread of directions.
Direction information is essential when converting phase space data into angular fluence distributions or when modeling detector response that depends on incident angle. It is also required when phase space files are turned into sources for a second simulation, because the direction vector tells the new simulation how to propagate each particle from the phase space plane into the downstream geometry.
In many analyses, directions are converted to polar and azimuthal angles, for example a polar angle $\theta$ relative to a given axis and an azimuthal angle $\phi$ in the transverse plane. You can derive these from the direction cosines and then build angular histograms. This provides insight into how much of the beam is primary and how much has been scattered by upstream materials.
Always treat direction vectors as normalized quantities. If your analysis inadvertently assumes unnormalized components, any derived angles or angular distributions will be incorrect.
Combining position and direction from the phase space actor lets you fully define lines of flight for each particle at the scoring surface. This combined information is the basis for many advanced applications, such as generating realistic entrance conditions for patient dose calculations, studying detector acceptance as a function of angle, or building detailed phase space sources for complex imaging and therapy simulations.
Views: 0
Where to Move
Move chapter:
- ☰ 1. Introduction to GATE
- ☰ 1.1. What Is GATE?
- ☰ 1.2. Applications of GATE
- ☰ 1.3. GATE vs Geant4
- ☰ 1.4. GATE Simulation Workflow
-
- ☰ 2. Installing GATE
- ☰ 2.1. GATE Requirements
- ☰ 2.2. Creating a Python Environment
- ☰ 2.3. Installing GATE
- ☰ 2.4. Verifying the Installation
- ☰ 2.5. GATE Example Simulations
-
- ☰ 3. Python Basics for GATE
- ☰ 3.1. Variables and Data Types
- ☰ 3.2. Conditional Statements
- ☰ 3.3. Loops
- ☰ 3.4. Functions
- ☰ 3.5. Python Modules
- ☰ 3.6. NumPy Basics
- ☰ 3.7. Working with Files
-
- ☰ 4. Creating Your First GATE Simulation
- ☰ 4.1. Importing GATE
- ☰ 4.2. Creating a Simulation
- ☰ 4.3. Adding the World
- ☰ 4.4. Adding a Particle Source
- ☰ 4.5. Adding an Actor
- ☰ 4.6. Running the Simulation
- ☰ 4.7. Inspecting the Results
-
- ☰ 5. Units in GATE
- ☰ 5.1. Physical Units
- ☰ 5.2. Length Units
- ☰ 5.3. Energy Units
- ☰ 5.4. Time Units
- ☰ 5.5. Radioactivity Units
- ☰ 5.6. Using Units Correctly
-
- ☰ 6. Geometry Fundamentals
- ☰ 6.1. The World Volume
- ☰ 6.2. Creating Volumes
- ☰ 6.3. Box Geometry
- ☰ 6.4. Cylindrical Geometry
- ☰ 6.5. Spherical Geometry
- ☰ 6.6. Position and Translation
- ☰ 6.7. Rotation
-
- ☰ 7. Building Complex Geometry
- ☰ 7.1. Nested Volumes
- ☰ 7.2. Repeated Volumes
- ☰ 7.3. Ring Geometry
- ☰ 7.4. Boolean Geometry
- ☰ 7.5. Geometry Overlap
- ☰ 7.6. Reusable Geometry Functions
-
- ☰ 8. Materials
- ☰ 8.1. Material Definitions
- ☰ 8.2. Geant4 Material Database
- ☰ 8.3. Common Medical Materials
- ☰ 8.4. Detector Materials
- ☰ 8.5. Shielding Materials
- ☰ 8.6. Creating Custom Materials
-
- ☰ 9. Geometry Visualization
- ☰ 9.1. Enabling Visualization
- ☰ 9.2. Displaying Volumes
- ☰ 9.3. Changing the View
- ☰ 9.4. Volume Appearance
- ☰ 9.5. Visualizing Particle Tracks
- ☰ 9.6. Debugging with Visualization
-
- ☰ 10. Particle Sources
- ☰ 10.1. Generic Sources
- ☰ 10.2. Particle Types
- ☰ 10.3. Source Position
- ☰ 10.4. Source Direction
- ☰ 10.5. Source Energy
- ☰ 10.6. Source Activity
-
- ☰ 11. Radioactive Sources
- ☰ 11.1. Radioactive Decay
- ☰ 11.2. Medical Radionuclides
- ☰ 11.3. Positron Emitters
- ☰ 11.4. Gamma Emitters
- ☰ 11.5. Activity Distribution
- ☰ 11.6. Time-Dependent Activity
-
- ☰ 12. Physics Lists
- ☰ 12.1. What Is a Physics List?
- ☰ 12.2. Electromagnetic Physics
- ☰ 12.3. Gamma Physics
- ☰ 12.4. Electron Physics
- ☰ 12.5. Positron Physics
- ☰ 12.6. Hadronic Physics
- ☰ 12.7. Choosing Physics Models
-
- ☰ 13. Production Cuts and Transport Parameters
- ☰ 13.1. What Are Production Cuts?
- ☰ 13.2. Range Cuts
- ☰ 13.3. Region-Based Cuts
- ☰ 13.4. Accuracy vs Performance
-
- ☰ 14. Actors
- ☰ 14.1. What Is an Actor?
- ☰ 14.2. Simulation Statistics Actor
- ☰ 14.3. Energy Deposition Actor
- ☰ 14.4. Dose Actor
- ☰ 14.5. Phase Space Actor
- ☰ 14.6. Particle Fluence
- ☰ 14.7. Actor Filters
-
- ☰ 15. Dose Calculation
- ☰ 15.1. Energy Deposition
- ☰ 15.2. Absorbed Dose
- ☰ 15.3. Creating a Dose Actor
- ☰ 15.4. Dose Images
- ☰ 15.5. Statistical Uncertainty
- ☰ 15.6. Dose Profiles
-
- ☰ 16. Hits and Detector Response
- ☰ 16.1. Particle Interactions in Detectors
- ☰ 16.2. Hits
- ☰ 16.3. Hit Collections
- ☰ 16.4. Hit Attributes
- ☰ 16.5. Hits vs Detector Signals
-
- ☰ 17. Digitizers
- ☰ 17.1. What Is Digitization?
- ☰ 17.2. Digitizer Chain
- ☰ 17.3. Energy Summation
- ☰ 17.4. Readout
- ☰ 17.5. Energy Blurring
- ☰ 17.6. Spatial Blurring
- ☰ 17.7. Energy Thresholds
- ☰ 17.8. Time Blurring
-
- ☰ 18. Singles
- ☰ 18.1. What Are Singles?
- ☰ 18.2. Creating Singles
- ☰ 18.3. Detector Identification
- ☰ 18.4. Energy Windows
- ☰ 18.5. Analyzing Singles
-
- ☰ 19. Coincidences
- ☰ 19.1. What Are Coincidences?
- ☰ 19.2. Coincidence Sorting
- ☰ 19.3. True Coincidences
- ☰ 19.4. Scattered Coincidences
- ☰ 19.5. Random Coincidences
- ☰ 19.6. Coincidence Timing
- ☰ 19.7. Coincidence Output
-
- ☰ 20. Data Output
- ☰ 20.1. Simulation Output
- ☰ 20.2. ROOT Output
- ☰ 20.3. Image Output
- ☰ 20.4. Text-Based Output
- ☰ 20.5. Organizing Simulation Results
-
- ☰ 21. GATE and ROOT
- ☰ 21.1. Reading GATE ROOT Files
- ☰ 21.2. Inspecting Output
- ☰ 21.3. Energy Histograms
- ☰ 21.4. Time Histograms
- ☰ 21.5. Detector Maps
- ☰ 21.6. Filtering Events
-
- ☰ 22. GATE and Python Data Analysis
- ☰ 22.1. Reading Simulation Output with Python
- ☰ 22.2. Energy Spectra
- ☰ 22.3. Position Distributions
- ☰ 22.4. Timing Analysis
- ☰ 22.5. Statistical Analysis
- ☰ 22.6. Visualization
-
- ☰ 23. Voxelized Geometry
- ☰ 23.1. Introduction to Voxelized Geometry
- ☰ 23.2. Image-Based Volumes
- ☰ 23.3. Material Mapping
- ☰ 23.4. CT-to-Material Conversion
- ☰ 23.5. Patient Geometry
- ☰ 23.6. Visualizing Voxelized Geometry
-
- ☰ 24. Image and DICOM Data
- ☰ 24.1. Medical Image Formats
- ☰ 24.2. Reading CT Images
- ☰ 24.3. DICOM CT Data
- ☰ 24.4. RT Structure Sets
- ☰ 24.5. RT Plans
- ☰ 24.6. Coordinate Systems
-
- ☰ 25. Motion and Time-Dependent Simulations
- ☰ 25.1. Time in GATE
- ☰ 25.2. Moving Sources
- ☰ 25.3. Moving Detectors
- ☰ 25.4. Respiratory Motion
- ☰ 25.5. Scanner Rotation
- ☰ 25.6. Dynamic Imaging
-
- ☰ 26. PET Simulation Fundamentals
- ☰ 26.1. PET Physics
- ☰ 26.2. PET Scanner Components
- ☰ 26.3. PET Detector Geometry
- ☰ 26.4. PET Source
- ☰ 26.5. PET Physics Configuration
- ☰ 26.6. PET Detector Response
-
- ☰ 27. Building a PET Scanner
- ☰ 27.1. Creating the Detector Ring
- ☰ 27.2. Creating Detector Blocks
- ☰ 27.3. Creating Detector Crystals
- ☰ 27.4. Assigning Detector IDs
- ☰ 27.5. Adding a PET Source
- ☰ 27.6. Configuring the Digitizer
- ☰ 27.7. Running the PET Simulation
-
- ☰ 28. PET Coincidence Analysis
- ☰ 28.1. Coincidence Events
- ☰ 28.2. Energy Selection
- ☰ 28.3. Coincidence Time Window
- ☰ 28.4. Lines of Response
- ☰ 28.5. True Events
- ☰ 28.6. Scatter Events
- ☰ 28.7. Random Events
- ☰ 28.8. PET Performance Metrics
-
- ☰ 29. Time-of-Flight PET
- ☰ 29.1. TOF PET Principles
- ☰ 29.2. Detector Timing Resolution
- ☰ 29.3. Time Difference
- ☰ 29.4. Timing Blurring
- ☰ 29.5. Analyzing TOF Events
-
- ☰ 30. SPECT Simulation Fundamentals
- ☰ 30.1. SPECT Physics
- ☰ 30.2. SPECT Scanner Components
- ☰ 30.3. SPECT Radionuclides
- ☰ 30.4. Gamma Camera Geometry
- ☰ 30.5. SPECT Source
-
- ☰ 31. Building a Gamma Camera
- ☰ 31.1. Detector Head
- ☰ 31.2. Collimator
- ☰ 31.3. Shielding
- ☰ 31.4. Energy Resolution
- ☰ 31.5. Energy Window
- ☰ 31.6. Projection Data
-
- ☰ 32. SPECT Acquisition
- ☰ 32.1. Rotating Gamma Camera
- ☰ 32.2. Projection Angles
- ☰ 32.3. Acquisition Time
- ☰ 32.4. Energy Windows
- ☰ 32.5. Projection Images
- ☰ 32.6. SPECT Data Analysis
-
- ☰ 33. CT and X-Ray Simulation
- ☰ 33.1. X-Ray Physics
- ☰ 33.2. X-Ray Source
- ☰ 33.3. CT Geometry
- ☰ 33.4. Detector Array
- ☰ 33.5. Rotating CT Geometry
- ☰ 33.6. CT Projection Data
-
- ☰ 34. Radiation Therapy Simulation
- ☰ 34.1. External Beam Radiotherapy
- ☰ 34.2. Photon Beams
- ☰ 34.3. Electron Beams
- ☰ 34.4. Dose Calculation
- ☰ 34.5. Beam Geometry
- ☰ 34.6. Dose Validation
-
- ☰ 35. Proton Therapy Simulation
- ☰ 35.1. Proton Physics
- ☰ 35.2. Proton Beam
- ☰ 35.3. Water Phantom
- ☰ 35.4. Bragg Peak
- ☰ 35.5. Spread-Out Bragg Peak
- ☰ 35.6. Proton Dose Analysis
-
- ☰ 36. Internal Dosimetry
- ☰ 36.1. Radioactive Sources in the Body
- ☰ 36.2. Voxelized Activity Maps
- ☰ 36.3. Energy Deposition
- ☰ 36.4. Dose Maps
- ☰ 36.5. Radionuclide Therapy
- ☰ 36.6. Dose Analysis
-
- ☰ 37. Optical Photon Simulation
- ☰ 37.1. Optical Physics
- ☰ 37.2. Scintillation
- ☰ 37.3. Optical Properties
- ☰ 37.4. Optical Surfaces
- ☰ 37.5. Photodetectors
- ☰ 37.6. Optical Photon Detection
-
- ☰ 38. Phase-Space Data
- ☰ 38.1. What Is a Phase Space?
- ☰ 38.2. Recording Phase-Space Data
- ☰ 38.3. Phase-Space Files
- ☰ 38.4. Phase-Space Sources
- ☰ 38.5. Applications
-
- ☰ 39. Random Numbers and Reproducibility
- ☰ 39.1. Monte Carlo Random Numbers
- ☰ 39.2. Random Seeds
- ☰ 39.3. Independent Simulations
- ☰ 39.4. Reproducible Research
-
- ☰ 40. Multithreading and Performance
- ☰ 40.1. Multithreaded Simulation
- ☰ 40.2. Selecting the Number of Threads
- ☰ 40.3. Simulation Speed
- ☰ 40.4. Optimizing Geometry
- ☰ 40.5. Optimizing Output
- ☰ 40.6. Large Simulations
-
- ☰ 41. Running GATE on HPC Systems
- ☰ 41.1. Why Use HPC?
- ☰ 41.2. Running GATE Without Visualization
- ☰ 41.3. Job Scripts
- ☰ 41.4. Running with Slurm
- ☰ 41.5. Running Multiple Simulations
- ☰ 41.6. Combining Results
-
- ☰ 42. Simulation Validation
- ☰ 42.1. Why Validate a GATE Simulation?
- ☰ 42.2. Geometry Validation
- ☰ 42.3. Physics Validation
- ☰ 42.4. Comparing with Analytical Models
- ☰ 42.5. Comparing with Experimental Data
- ☰ 42.6. Statistical Validation
-
- ☰ 43. Debugging GATE Simulations
- ☰ 43.1. Python Errors
- ☰ 43.2. Geometry Problems
- ☰ 43.3. Material Errors
- ☰ 43.4. Source Problems
- ☰ 43.5. Physics Problems
- ☰ 43.6. Actor Problems
- ☰ 43.7. Digitizer Problems
- ☰ 43.8. Performance Problems
-
- ☰ 44. Writing Better GATE Simulations
- ☰ 44.1. Organizing Simulation Scripts
- ☰ 44.2. Configuration Files
- ☰ 44.3. Avoiding Hard-Coded Values
- ☰ 44.4. Reusable Components
- ☰ 44.5. Output Organization
- ☰ 44.6. Documentation
- ☰ 44.7. Version Control
-
- ☰ 45. Practical Example: Gamma-Ray Detector
- ☰ 45.1. Project Overview
- ☰ 45.2. Creating the World
- ☰ 45.3. Creating the Detector
- ☰ 45.4. Creating a Gamma Source
- ☰ 45.5. Configuring Electromagnetic Physics
- ☰ 45.6. Recording Energy Deposition
- ☰ 45.7. Adding Energy Resolution
- ☰ 45.8. Creating an Energy Spectrum
- ☰ 45.9. Analyzing the Spectrum
-
- ☰ 46. Practical Example: Radiation Shielding
- ☰ 46.1. Project Overview
- ☰ 46.2. Creating the Source
- ☰ 46.3. Creating the Shield
- ☰ 46.4. Selecting Shielding Materials
- ☰ 46.5. Changing Shield Thickness
- ☰ 46.6. Recording Transmitted Photons
- ☰ 46.7. Calculating Transmission
- ☰ 46.8. Calculating Attenuation
- ☰ 46.9. Comparing with the Exponential Attenuation Law
-
- ☰ 47. Practical Example: PET Scanner
- ☰ 47.1. Project Overview
- ☰ 47.2. Creating the PET Ring
- ☰ 47.3. Creating Detector Modules
- ☰ 47.4. Creating Detector Crystals
- ☰ 47.5. Adding an F-18 Source
- ☰ 47.6. Configuring PET Physics
- ☰ 47.7. Recording Hits
- ☰ 47.8. Creating Singles
- ☰ 47.9. Applying Energy Blurring
- ☰ 47.10. Applying the PET Energy Window
- ☰ 47.11. Sorting Coincidences
- ☰ 47.12. Identifying True Coincidences
- ☰ 47.13. Identifying Scattered Coincidences
- ☰ 47.14. Creating Lines of Response
- ☰ 47.15. Saving PET Data
-
Comments
Please login to add a comment.
Don't have an account? Register now!