38.2. Recording Phase-Space Data

Table of Contents

Phase-space actors

In GATE, phase-space actors are the tools that record the detailed state of particles as they cross a chosen surface or volume during the simulation. For phase-space work you do not change the particle transport itself, you simply place an actor that listens and writes out what happens to particles at a specific location. This is what makes phase-space data reusable in later simulations, as you will see elsewhere in this course.

A phase-space actor is attached to one logical volume in your geometry. Whenever a particle satisfies the actor’s conditions, for example leaving the volume or crossing one of its faces, the actor records a line of data describing that particle at that point. The result is a phase-space file that you can treat as a realistic particle source for another simulation run.

Phase-space actors are conceptually similar to other actors you have already seen such as dose or energy deposition actors. They are configured through the simulation object, they are tied to a volume name, and they write their results to output files. The difference is in what they record: instead of integrated quantities like dose, they write event-by-event, particle-by-particle information.

Attaching a phase-space actor to a volume

To record phase-space data you first decide where in your geometry you want to intercept particles. This is usually a plane or a thin volume placed at some convenient location. Typical examples include a plane just after a linac head, the exit face of a shielding block, or a surface just in front of a detector array.

Once you have such a volume, you create and attach a phase-space actor to it from Python. The details of the Python interface are covered globally in the Actors chapters, so here we focus on what is specific for phase-space actors. The essential configuration steps are:

You specify the actor type as a phase-space actor. You give it a unique name. You attach it to the volume where you want to record particles by using that volume’s name. You select which particle properties to record. You specify the output file where the actor will write its data.

This is how you conceptually place the “virtual detector” that collects the six-dimensional phase-space coordinates of the particles. The actor does not change the geometry or the physics, it only observes and records.

When deciding which volume to use, remember that the actor records particles that cross the volume boundary in a given direction or all crossings depending on its configuration. You usually do not need a thick volume for this. A thin slab with the right position and orientation is enough and simplifies later interpretation because you can treat the recorded plane as a well defined phase-space surface.

Choosing which quantities to record

The strength of a phase-space actor is that you can control which phase-space coordinates and extra quantities it records. The exact list of options will depend on your GATE version, but commonly includes at least:

Particle position at the crossing event, often $x, y, z$ in millimeters, expressed in the global coordinate system. Particle direction as a unit vector, for example $u_x, u_y, u_z$. Particle kinetic energy $E$ in electron-volts or mega-electron-volts. Time $t$ when the particle crosses the surface, in seconds or submultiples. Particle type, usually an integer or string identity such as gamma, e-, e+, proton. Event and track identifiers so that you can group records belonging to the same primary history. Weight, used if you activate variance-reduction features. Parent information in more advanced configurations, for example parent ID or process name.

Each one of these fields corresponds to a branch in the output file. You select just what you need in order to keep the file size manageable and the analysis simple. For example, if you only need directional information and energy to build a spectral-angular source for a downstream simulation, you may omit time and event identifiers. If you are planning to do time-of-flight analysis you must request the time coordinate.

It is common to record at least position, direction, energy, particle type, and time. This gives you the complete basic phase-space state. The table below summarizes the typical contents:

Quantity	Symbol	Typical unit	Purpose
Position	$x,y,z$	mm	Where the particle crosses the plane
Direction cosines	$u_x,u_y,u_z$	unitless	Direction of motion
Kinetic energy	$E$	MeV	Energy spectrum and source definition
Time	$t$	s or ns	Time structure and TOF analysis
Particle type ID		code/string	Particle selection in later analysis
Event / track ID		integer	Grouping by history
Weight	$w$	unitless	Variance reduction, weighted scoring

Whenever you configure the actor, you must make sure that the units used to interpret the data agree with the units chosen in your simulation, as discussed in the Units in GATE chapters. The actor will typically write values already converted to standard units such as millimeters and MeV, but you must confirm this in the documentation or by a simple test run.

Always verify which quantities your phase-space actor records and in which units. Misinterpreting position, direction, energy, or time from a phase-space file will give wrong source definitions and incorrect downstream results.

Recording direction and reference frames

A subtle but important aspect of recording phase-space data is the reference frame used by the actor. Positions are usually stored in the global coordinate system of the simulation, which is fixed and common to all volumes. Directions are stored as unit vectors in that same system. This is convenient when you later reuse the phase-space file in a different simulation with a similar geometry layout.

However, if you plan to reuse the phase-space file in a geometry where the orientation of the recording plane is different, you must understand how the recorded direction relates to your new geometry. In more advanced workflows you may want to express direction relative to a local coordinate system attached to the surface, but for beginners it is enough to remember that directions are usually global.

For each entry, the actor records the three components $u_x, u_y, u_z$ of a unit vector. These satisfy the normalization condition
$$
u_x^2 + u_y^2 + u_z^2 = 1.
$$
You can reconstruct polar and azimuthal angles from these if needed. For example, if you treat $z$ as the axis normal to the surface you can define
$$
\theta = \arccos(u_z), \quad \phi = \arctan2(u_y, u_x).
$$

When you build a phase-space source later, the directions in the file will serve as the initial directions for particles in the new simulation. If you rotate or translate the geometry relative to the original configuration, you must handle that transformation explicitly during source creation. This is part of the material covered when you learn how to use phase-space files as sources.

Output control and file size

Phase-space files can become very large because they store detailed information for many particle crossings. This is an important practical aspect of recording phase-space data. Every recorded crossing corresponds to a row in the file, so file size grows approximately linearly with the number of recorded particles and the number of fields per record.

You have several levers to control file size and output volume:

You can restrict recording to certain particle types, for example only gamma or only protons. You can select only a subset of fields, for example omitting track IDs or parent information that you do not need. You can set energy or time filters to only record particles within a certain energy range or time window. You can reduce the number of primary events in the first simulation if you only need a modest phase-space sample.

The choice of output format also matters. GATE typically writes phase-space data to ROOT files or to dedicated binary formats. ROOT is a good choice when you plan to read the data with ROOT or Uproot, and it provides efficient compression for large trees.

Because you will often want to reuse the same phase-space file many times, it is worth investing some thought into its size and structure. A file that is too small will give you noisy results in downstream simulations, while an excessively large file may be slow to process and difficult to store.

Before running a long simulation with a phase-space actor, estimate the expected file size by doing a short test run. Adjust your recording options and filters to keep the phase-space file both informative and manageable.

Using multiple phase-space actors

In more complex setups you are not limited to a single phase-space actor. You can attach several actors to different volumes in the same simulation. Each one will record phase-space data at its location. This is useful if you want to characterize particle distributions at multiple stages of a beamline or accelerator, or if you want to compare the spectrum before and after a shielding element.

Each phase-space actor has its own name and output file. This allows you to structure your data by stage. For example, one actor might record the phase space at the exit of the accelerator head and another after the patient or phantom. Later you can study changes in spectra, fluence, and angular distributions simply by inspecting the corresponding files.

When using multiple actors, keep in mind that they will all contribute to I/O load. If you record very detailed data at many surfaces, writing to disk can become a bottleneck. In such cases you may want to reduce the number of recorded variables or the number of recorded events per actor, or run separate simulations focused on different locations.

By understanding how to place and configure phase-space actors, you create a flexible bridge between upstream and downstream parts of your simulation campaigns. The actual reuse of these files as sources will be covered in the following chapters on phase-space files and phase-space sources.