Set up a first simulation#

The Simulation object#

Any simulation starts by defining the Simulation object. A script can only contain one such Simulation object.

import opengate as gate
sim = gate.Simulation()

You can set general options via the Simulation object, for example:

import opengate as gate

sim = gate.Simulation()
sim.g4_verbose = False
sim.visu = False
sim.random_seed = 'auto'
sim.number_of_threads = 1

To know all input parameters and their default values, you can do:

import opengate as gate
gate.help_on_user_info(gate.Simulation)

To get help about a specific input parameter, you can do:

import opengate as gate
gate.help_on_user_info(gate.Simulation.number_of_threads)

Components of a simulation#

A simulation usually contains four kinds of main components that will be described in more detail further down:

  • Geometry: all geometrical elements that compose the scene, such as phantoms, detectors, etc. These are referred to as Volumes.

  • Sources: all sources of primary particles.

  • Physics: the physics models used by Geant4 and their parameters.

  • Actors: these are the building blocks that actually extract information from the simulation and generate output, or that interact and steer the simulation. Typical examples are actors that calculate dose deposition on a voxel grid or detect particles and their properties. Note: other Monte Carlo use the term ‘scorer’.

The general structure of a GATE 10 simulation script follows this simple example:

import opengate as gate

if __name__ == "__main__":
    sim = gate.Simulation()
    sim.output_dir = <YOUR_OUTPUT_DIRECTORY_OF_CHOICE>

    wb = sim.add_volume("Box", name="waterbox")
    # configure the volume ...
    cm = gate.g4_units.cm
    wb.size = [10 * cm, 5 * cm, 10 * cm]
    # ...

    source = sim.add_source("GenericSource", name="Default")
    MeV = gate.g4_units.MeV
    Bq = gate.g4_units.Bq
    source.particle = "proton"
    source.energy.mono = 240 * gate.g4_units.MeV
    # ...

    stats = sim.add_actor("SimulationStatisticsActor", "Stats")

    sim.run()

The simulation is started by the command sim.run(). Optionally, the simulation can be run in a subprocess via

sim.run(start_new_process=True)

This is necessary if a simulation is run multiple times from the same script, e.g., in a loop, or when working in an interactive python terminal or notebook.

Important

You should always place the part of the script that actually executes the simulation in a block protected by if __name__ == "__main__":, as in the example above. Key functionalities of GATE 10 will not work otherwise.

Units#

Geant4 physics units are collected in opengate.g4_units and you can assign the ones you need to a variable inside your script for convenience:

import opengate as gate

cm = gate.g4_units.cm
eV = gate.g4_units.eV
MeV = gate.g4_units.MeV
x = 32 * cm
energy = 150 * MeV
print(f'The energy is {energy/eV} eV')

The units behave like in the Geant4 system of units.

References#

class Simulation(*args, **kwargs)[source]#

Main class that store a simulation. It contains: - a set of global user parameters (SimulationUserInfo) - user parameters for Volume, Source, Actors and Filters, Physics - a list of g4 commands that will be set to G4 engine after the initialization

There is NO Geant4 engine here, it is only a set of parameters and options.

User input parameters and default values:

  • check_volumes_overlap:

    • Default value: True

    • Description: If true, Gate will also check whether volumes overlap. Note: Geant4 checks overlaps in any case.

  • dyn_geom_open_close:

    • Default value: True

    • Description: Warning, should be True. Only set it to false if you know what your are doing

  • dyn_geom_optimise:

    • Default value: True

    • Description: ‘Optimise’ geometry when open/close during dynamic simulation.

  • force_multithread_mode:

    • Default value: False

    • Description: Force Geant4 to run multihthreaded even if ‘number_of_threads’ = 1.

  • g4_commands_after_init:

    • Default value: []

    • Description: Geant4 commands which will be called after the G4 runmanager has initialized the simulation.

  • g4_commands_before_init:

    • Default value: []

    • Description: Geant4 commands which will be called before the G4 runmanager has initialized the simulation.

  • g4_verbose:

    • Default value: False

    • Description: Switch on/off Geant4’s verbose output.

  • g4_verbose_level:

    • Default value: 1

    • Description: Geant4 verbosity. With level 0, Geant4 is mostly silent. Level 1 already gives quite a bit of verbose output. Level 2 is very detailed and might affect performance.

  • g4_verbose_level_tracking:

    • Default value: -1

    • Description: Activate verbose tracking in Geant4 via G4 command ‘/tracking/verbose g4_verbose_level_tracking’.

  • init_only:

    • Default value: False

    • Description: Start G4 engine initialisation but do not start the simulation.

  • json_archive_filename:

    • Default value: simulation.json

    • Description: Name of the json file containing all parameters of the simulation. It will be saved in the location specified via the parameter ‘output_dir’. Default filename: simulation.json

  • name (must be provided):

    • Default value: None

  • number_of_threads:

    • Default value: 1

    • Description: Number of threads on which the simulation will run. Geant4’s run manager will run in MT mode if more than 1 thread is requested.Requires Geant4 do be compiled with Multithread flag TRUE.

  • output_dir:

    • Default value: .

    • Description: Directory to which any output is written, unless an absolute path is provided for a specific output.

  • progress_bar:

    • Default value: False

    • Description: Display a progress bar during the simulation

  • random_engine:

    • Default value: MixMaxRng

    • Description: Name of the Geant4 random engine to be used. MixMaxRng is recommended for multithreaded applications.

  • random_seed:

    • Default value: auto

    • Description: Random seed to be used by the random engine. Setting a specific value will make subsequent simulation runs to produce identical results.

  • run_timing_intervals:

    • Default value: [[0.0, 1000000000.0]]

    • Description: A list of timing intervals provided as 2-element lists of begin and end values

  • running_verbose_level:

    • Default value: 0

    • Description: Gate verbosity while the simulation is running.

  • store_input_files:

    • Default value: False

    • Description: Store all input files used in the simulation? Default: False

  • store_json_archive:

    • Default value: False

    • Description: Automatically store a json file containing all parameters of the simulation after the run? Default: False

  • verbose_close:

    • Default value: False

    • Description: Switch on/off verbose output in close() methods.

  • verbose_getstate:

    • Default value: False

    • Description: Switch on/off verbose output in __getstate__() methods.

  • verbose_level:

    • Default value: INFO

    • Allowed values: (‘NONE’, ‘INFO’, ‘DEBUG’, 0, 20, 10)

    • Description: Gate pre-run verbosity. Will display more or fewer messages during initialization.

  • visu:

    • Default value: False

    • Description: Activate visualization? Note: Use low number of primaries if you activate visualization.

  • visu_commands:

    • Default value: [’# default visualization’, ‘#/vis/open OGLSQt’, ‘/vis/open OGL’, ‘/vis/scene/create’, ‘/vis/drawVolume worlds’, ‘/vis/viewer/flush’, ‘# no verbose’, ‘/control/verbose 0’, ‘# Work but generate txt on terminal’, ‘/vis/scene/add/axes 0 0 0 50 cm’, ‘/vis/scene/add/text 10 0 0 cm 20 0 0 X’, ‘/vis/scene/add/text 0 10 0 cm 20 0 0 Y’, ‘/vis/scene/add/text 0 0 10 cm 20 0 0 Z’, ‘# change orientation (for debug)’, ‘#/vis/viewer/set/upVector 0 0 1’, ‘#/vis/viewer/set/viewpointVector 0 1 0’, ‘#/vis/viewer/set/upVector 1 0 0’, ‘#/vis/viewer/set/viewpointVector 0 0 1’, ‘#/vis/viewer/set/upVector 0 1 0’, ‘#/vis/viewer/set/viewpointVector 1 0 0’, ‘/vis/sceneHandler/attach’, ‘/vis/modeling/trajectories/create/drawByParticleID’, ‘/tracking/storeTrajectory 1’, ‘/vis/scene/endOfEventAction accumulate’, ‘/vis/scene/add/trajectories’, ‘/vis/viewer/set/auxiliaryEdge true’]

    • Description: Geant4 commands needed to handle the visualization. By default, the Geant4 visualisation commands are the ones provided in the file opengate/mac/default_visu_commands_qt.mac. Custom commands can be loaded via a .mac file, e.g. sim.visu_commands = gate.read_mac_file_to_commands('my_visu_commands.mac').

  • visu_commands_gdml:

    • Default value: [‘/vis/open OGLI 600x600-0+0’, ‘/vis/viewer/set/autoRefresh false’, ‘/vis/verbose errors’, ‘/vis/drawVolume worlds’, ‘/vis/modeling/trajectories/create/drawByParticleID’, ‘/tracking/storeTrajectory 1’, ‘/vis/scene/add/trajectories’, ‘/vis/scene/endOfEventAction accumulate’, ‘/vis/viewer/set/autoRefresh true’, ‘/vis/verbose warnings’, ‘#/vis/viewer/flush’]

    • Description: Geant4 commands needed to handle the GDML visualization. Only used for vrml-like visualization types.

  • visu_commands_vrml:

    • Default value: [‘/vis/open VRML2FILE’, ‘/vis/drawVolume worlds’, ‘/vis/modeling/trajectories/create/drawByParticleID’, ‘/tracking/storeTrajectory 1’, ‘/vis/scene/add/trajectories’, ‘/vis/scene/endOfEventAction accumulate’, ‘/vis/scene/backgroundColour 0 0 0’, ‘#/vis/viewer/flush’]

    • Description: Geant4 commands needed to handle the VRML visualization. Only used for vrml-like visualization types.

  • visu_filename:

    • Default value: None

    • Description: Name of the file where visualization output is stored. Only applicable for vrml and gdml.

  • visu_type:

    • Default value: vrml

    • Allowed values: (‘qt’, ‘vrml’, ‘gdml’, ‘vrml_file_only’, ‘gdml_file_only’)

    • Description: The type of visualization to be used. ‘qt’ will start a Geant4 Qt interface. The Geant4 visualisation commands can be adapted via the parameter visu_commands.

  • visu_verbose:

    • Default value: False

    • Description: Should verbose output be generated regarding the visualization?

Simulation.run(start_new_process=False)[source]#