4.5 Adding an Actor

Table of Contents

Recording simulation information

In GATE, an actor is a convenient object that observes what happens during a simulation and records selected information. You do not modify the physics or geometry with an actor. Instead, you attach actors to volumes or to the whole simulation, and they produce output such as text files or images.

In your first simulation, the role of an actor is to give you something concrete to look at after the run finishes. For example, you can count how many particles were simulated, or how much energy was deposited in a simple detector volume.

When using OpenGATE from Python, you typically create actors through the simulation object that you already defined in the earlier parts of the chapter. The usual steps are to choose an actor type, create it and give it a name, configure its options, and then attach it to a specific volume if required.

A minimal example looks like this:

python

import opengate as gate
sim = gate.Simulation()
# ... here you would already have defined world, sources, physics, etc.
stats = sim.add_actor("SimulationStatisticsActor", "stats")
stats.save = True
stats.output = "stats.txt"

In this example, "SimulationStatisticsActor" is the type of actor, and "stats" is the name you assign to this particular instance. The save flag tells the actor to write its results to disk at the end of the run, and output gives the filename. You will inspect this file when you reach the next steps of the tutorial.

Actors in GATE are strongly linked to geometry. Many actor types require you to specify a mother or attached_to volume name so they know where to record information. For instance, if you have already created a box that represents a detector and called it "detector", you could attach an energy deposition actor to that box:

python

edep = sim.add_actor("EnergyDepositActor", "edep_in_detector")
edep.mother = "detector"
edep.output = "edep.mhd"
edep.spacing = [1.0, 1.0, 1.0]

Here, the mother field must match exactly the name you gave the volume when you created it. The spacing parameter defines the voxel size of the grid where energy deposition is accumulated. This example shows how an actor can convert the continuous Monte Carlo tracks into a regular image that you can later analyze or visualize.

Actors must be configured before calling the simulation run method. Once you start the simulation with something like sim.run(), you cannot safely add, remove, or reconfigure actors for that run. Always set up all actors immediately after defining your geometry, sources, and physics.

Although there are many actor types in GATE, in your first simulation it is enough to add one or two simple ones. A simulation statistics actor will help you verify that particles were generated and transported. An optional energy deposition or dose actor, attached to a clearly defined volume, will give you a first sense of how the simulation records physical quantities.

Later chapters in this course are dedicated to specific actor families, such as dose, phase space, and fluence actors. At this stage, the important idea is that actors are the main mechanism by which you tell GATE what to record. Without at least one actor, the simulation can run, but you will have nothing to inspect after it finishes.

4.5 Adding an Actor

Recording simulation information

Comments

Where to Move