15.3. Creating a Dose Actor

Table of Contents

Attaching dose actors

In GATE, a dose actor is the component that converts raw energy depositions into absorbed dose values. Conceptually, it observes a region of your geometry and accumulates energy per unit mass during the simulation. You attach a dose actor to a volume, then configure how it records dose.

In OpenGATE with Python, you typically create actors from the simulation object. For a dose actor, you specify at least a name, an attached volume, and an output file. Attach the actor only after your geometry is fully defined and before the simulation starts.

A minimal pattern looks like this (names and units are only examples):

python

import opengate as gate
from opengate import g4_units
sim = gate.Simulation()
# ... define world and other volumes ...
phantom = sim.add_volume(
    name="phantom",
    type="Box",
    material="G4_WATER",
    size=[20 * g4_units.cm, 20 * g4_units.cm, 20 * g4_units.cm],
)
dose = sim.add_actor(
    name="dose_actor",
    type="DoseActor",
    attached_to=phantom.name,
)
dose.output = "dose.mhd"

The key point is the attached_to field. The dose actor uses this volume as its scoring region. Depending on the type of dose actor that GATE provides in your version, typical configuration fields include whether to store dose, squared dose, uncertainty, or energy deposition maps. For example:

python

dose.store_absorbed_dose = True
dose.store_squared_dose = True
dose.store_uncertainty = True
dose.store_energy_deposition = False

Only enable what you need, because each extra map increases memory and file size.

A dose actor must always be attached to a specific volume. If the volume name is wrong or the volume is created after the actor, the simulation will run without recording dose, or it may fail with an error. Always define your geometry first, then attach the dose actor to an existing volume.

You can attach multiple dose actors in a single simulation. For example, one actor can score dose in a small organ volume while another scores dose in a larger phantom. Each actor is independent and has its own voxel grid and output file.

If you need a dose actor in the world volume itself, be careful about the grid resolution, because the world can be large. A coarse grid might be sufficient for global maps, while finer grids are usually reserved for anatomical or phantom regions.

Once attached and configured, the actor accumulates dose automatically when you call the simulation run method. There is no need to manually trigger recording. After the run finishes, check the specified output file to access the dose image.

Dose grid configuration

The dose actor produces voxelized dose maps, which means that you need to define how the attached volume is divided into voxels. This is the dose grid. Correct configuration of this grid is essential for meaningful dose results.

A dose grid is usually defined by two related sets of parameters:

The physical size or bounding box of the scoring region.
The number of voxels along each axis.

In OpenGATE, the grid is typically specified relative to the attached volume. A common approach is to set the number of voxels in x, y, and z:

python

dose.size = [phantom.size[0], phantom.size[1], phantom.size[2]]
dose.nb_voxels = [100, 100, 100]

Here the size field matches the phantom dimensions. The number of voxels then defines the voxel size as:

$$
\Delta x = \frac{\text{size}_x}{N_x}, \quad
\Delta y = \frac{\text{size}_y}{N_y}, \quad
\Delta z = \frac{\text{size}_z}{N_z}.
$$

You can compute the voxel spacing explicitly in your code if you want to check that it is reasonable:

python

dx = dose.size[0] / dose.nb_voxels[0]
dy = dose.size[1] / dose.nb_voxels[1]
dz = dose.size[2] / dose.nb_voxels[2]

The absorbed dose in each voxel is defined as
$$
D = \frac{E_{\text{dep}}}{m_{\text{voxel}}}
$$
where $E_{\text{dep}}$ is the total deposited energy in the voxel, and $m_{\text{voxel}}$ is the voxel mass.
Always check that your voxel size is realistic. Too small voxels can lead to very noisy dose values and long simulation times, while too large voxels can smear out important dose gradients.

You can often choose between:

A grid that fully covers the attached volume, using the volume size directly, or
A subvolume grid, where you set a smaller size than the full volume and possibly a specific center.

For example, to focus on a central region inside a phantom:

python

dose.size = [10 * g4_units.cm, 10 * g4_units.cm, 10 * g4_units.cm]
dose.center = [0, 0, 0]
dose.nb_voxels = [100, 100, 100]

This gives 1 mm voxels in a central 10 cm cube, even if the phantom is larger.

The following table summarizes how grid parameters relate to the resulting image:

Parameter	Controls	Typical choice
`size`	Physical extent of scoring grid	Full volume size or region of interest
`center`	Grid position relative to attached vol	Usually at volume center
`nb_voxels`	Resolution of dose map	Higher for sharp gradients, lower for speed
Voxel spacing	Size / nb_voxels	Check to avoid too fine or too coarse voxels

Remember that voxel mass depends on both voxel volume and material density. If your attached volume contains multiple materials, the dose actor uses the local material in each voxel to compute the mass. In a heterogeneous phantom, this means that voxels with the same deposited energy can have different dose values because of different densities.

For large patient CT simulations, grid parameters are often chosen to match the voxel size of the CT image that defines the patient geometry. In simpler phantoms, you can choose voxel size based on the physics scale you want to resolve. For example, in proton therapy, the Bragg peak region may require finer voxels along the beam axis than lateral directions.

Finally, configure the output format from the dose actor. Many GATE dose actors can write MetaImage (MHD) files, where the header contains the voxel dimensions and number of voxels. Always inspect this header to verify that the grid parameters used by the actor match your expectations before using the dose maps for analysis or comparison.

15.3. Creating a Dose Actor

Attaching dose actors

Dose grid configuration

Comments

Where to Move