Details: Simulation object#
You can configure the general behavior of your simulation via the parameters of the opengate.Simulation object.
Random Number Generator#
The random number generator used by Geant4 can be set with sim.random_engine = "MersenneTwister". The default one is “MixMaxRng” and not “MersenneTwister” because it is recommended by Geant4 for multithreading.
You can set the seed of the random number generator with self.random_seed = 123456789 to any number. Fixing the seed means that the results will be identical if you run the same simulation twice, which can be useful for testing. There are some exceptions to that behavior, for example when using PyTorch-based GAN. By default, it is set to “auto”, which means that the seed is randomly chosen.
Run and timing#
The simulation can be split into several runs, each of them with a given time duration. This is used for example for simulations with a dynamic geometry, e.g. a rotating gantry or a breathing patient. Gaps between the intervals are allowed. By default, the simulation has only one run with a duration of 1 second.
Splitting a simulation into multiple runs is faster than executing a simulation multiple times because Geant4 is initialized only once at the beginning.
In the following example, we define 3 runs, the first has a duration of half a second and starts at 0, the 2nd run goes from 0.5 to 1 second. The 3rd run starts later at 1.5 seconds and lasts 1 second.
sim.run_timing_intervals = [
[0, 0.5 * sec],
[0.5 * sec, 1.0 * sec],
# Watch out: there is (on purpose) a 'hole' in the timeline
[1.5 * sec, 2.5 * sec],
]
Verbosity#
The verbosity, i.e., the messages printed on the screen, are controlled via various parameters:
Visualisation#
You can enable visualisation with sim.visu = True.
GATE 10 can visualize your simulation is different ways, namely using the native Geant4 Qt-based visualization, or via vrml or gdml files. You can select the type of visualization with
- property Simulation.visu_type[source]#
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.
If you set visu_type=’qt’, you can customize the Geant4 visualization commands with
- property Simulation.visu_commands[source]#
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').
Warning
When the simulation contains an opengate.geometry.volumes.ImageVolume, the visualization would need to render every voxel, which is highly inefficient and cannot really be used in practice. Replace the opengate.geometry.volumes.ImageVolume by a opengate.geometry.volumes.BoxVolume with the same size as a work-around for visualization.
VRML#
You can choose VRML visualization with sim.visu_type = "vrml". Opengate uses pyvista for the GUI, so you need to install it with:
pip install pyvista
Alternatively, if you want to use an external VRML viewer, you can save a VRML file with sim.visu_type = "vrml_file_only". In such cases, the GUI is not opened, and you do not need pyvista. In both cases, you need to set sim.visu_filename = "geant4VisuFile.wrl" to save the VRML file.
If you want to personalize the pyvista GUI, you can set sim.visu_type = "vrml_file_only" and execute your own code in your Python script. You can find an example in [test004_simple_visu_vrml.py](OpenGATE/opengate).
GDML#
With GDML visualization, you can only view the geometry, not the paths of the particles. It is enabled with sim.visu_type = "gdml". GDML visualization needs to be enabled in Geant4 with GEANT4_USE_GDML=ON during the compilation, but you need to have xerces-c available on your computer (install it with yum, brew, or apt-get, …).
Opengate uses pyg4ometry for the GUI, so you need to install it with:
pip install pyg4ometry
pyg4ometry uses opencascade libraries, so install opencascade with your package manager. If you want to use an external GDML viewer, you can save the visualization to a GDML file with sim.visu_type = "gdml_file_only". In such cases, the GUI is not open, and you do not need pyg4ometry. In both cases, you need to set sim.visu_filename = "geant4VisuFile.gdml" to save the GDML file.
Multithreading#
- property Simulation.number_of_threads[source]#
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.
Warning
The speedup is not optimal in all situations. First, it takes time to start a new thread, so if the simulation is short, MT does not bring any speedup. Second, if the simulation contains several runs (e.g., for moving volumes), the master thread will wait for all threads to terminate the run before starting another one. This synchronization takes time and impacts the speedup.
However, for other cases, MT is very efficient and brings almost linear speedups, at least for a “low” number of threads (we tested it with 8 threads on dose computation, leading to almost x8 time gain).
Multiprocessing (advanced use)#
The Geant4 kernel can only be executed once per process and cannot be reused in the same process. Therefore, you can (normally) not call sim.run() twice in the same script.
This could be a problem in certain scenarios, e.g. when using interactive Python terminal (ipython) or Python notebooks, or when you would need to run a simulation multiple times from a single script. To overcome this limitation, the simulation can be executed in a separate process (different from the one where your script is running). All you need to do is to set start_new_process=True when running the simulation:
sim.run(start_new_process=True)
When this option is used, the Geant4 engine will be created and run in a separate process, which will be terminated after the simulation is finished. The output of the simulation will be copied back to the main process that called the run() method. This allows for the use of Gate in Python Notebooks, as long as this option is not forgotten.
User hooks#
TODO