Commissioning

System configuration file

The configuration file contains the specifications of the computing environment, the preferences of the users and much more. IDEAL cannot run without these specifications. The standard location of the system configuration file is cfg/system.cfg relative to the installation directory of IDEAL.

The syntax of the configuration file is similar to what is found in Microsoft Windows IN files. The configuration is divided in [sections] which contain lists of settings of the form label = value. The labels are case insensitive. The example system.cfg file provided with the IDEAL source contains many explanatory comments that should help the commissioning user to define the correct values.

[directories]

input dicom

Full path of the top directory for finding DICOM input data. This is mainly used by the research GUI, to position the starting location for the input file browser.

tmpdir jobs

Full path of the “work directory” on the shared disk of the cluster. For each IDEAL job, a subfolder will be created in this directory to store all the job specific data, including the intermediate and final results of the cluster subjobs. Upon successful completion of the job, most of the bulky data in the subfolder will be compressed, but not deleted.

first output dicom

Full path of the output directory on the shared disk of the cluster. For each IDEAL job, a subfolder will be created in this directory to store the final output (DICOM dose files and a text summary of the job).

second output dicom

Full path of the directory on an external file system (typically a Windows file share, mounted with SAMBA). The for each job, a copy of the output subfolder is stored here. This setting is optional: leaving this option empty avoids the copy.

logging

Full path of the logging directory. For every IDEAL command, a logging file with all debug level logging output will be stored here.

commissioning

Full path of the so-called “commissioning” directory. This contains site specific calibration and modeling data, such as beam models and HLUT tables, which are described in more detail below.

[mc stats]

There are three possible statistical goals for an IDEAL job: “number of primaries”, “average uncertainty” and “maximum runtime”. The ranges of allowed values and the default values of these goals are specified here, as well as which goals are enabled by default. This information is primarily used by the GUI.

Four values should be specified for each goal, to specify the minimum, default, maximum, and stepsize value, respectively. All values should be positive and the default value should be within the allowed range. It is recommended to choose the stepsize identical to the minimum value. For the goal(s) that should be enabled by default, the word “default” should be put at the end of the configuration line. At least one goal should should be enabled.

For instance:

n minutes per job   =    5        20      10080    5
n ions per beam     =  100   1000000 1000000000  100   default
x pct unc in target =    0.1       1.        99.   0.1

In this example, by default the goal is to simulate 1000000 primaries. The valid values for the number of primaries are in the range from 100 to 1000000000, and in when a GUI user clicks to increment or decrement, then the stepsize is 100. Since Gate uses a signed integer to count primaries, the maximum should be less than the number of cores in the cluster times 2³¹-1=2147483647.

The average uncertainty in the target is defined as the average of the relative uncertainty in the voxels that have a dose larger than the a configurable fraction of the mean dose maximum. We are not using the absolute dose maximum in a voxel, since this tends to fluctuate too much. Instead we find the N highest dose values in the distribution, the mean of those values is the “mean dose maximum”. The number N should be be configured in the system configuration file like this:

n top voxels for mean dose max = 100

The fraction of this “mean dose maximum” that serves as the threshold to mask the voxels that should contribute to the “average uncertainty” is configured like this:

dose threshold as fraction in percent of mean dose max = 50.

In this example configuration, the “mean dose maximum” is computed from the 100 highest dose values and the threshold is set at 50% of that maximum mean dose.

[simulation]

gate shell environment

Full path to a shell file that will be sourced to set the environment variables correct for running Gate (GateRTion). Typically this shell script contains lines like source /path/to/ROOT/bin/thisroot.sh and source /path/to/Geant4/bin/geant4.sh to set the ROOT and Geant4 variables, plus a line like export PATH="/path/to/Gate/bin:$PATH". If GateRTion was compiled with USE_ITK then an additional line adding the ITK library directory may need to be prepended to LD_LIBRARY_PATH as well.

number of cores

This is the number of cores that will be used to simulate a single beam. On a small cluster you will typically set this to the total number of available cores. On a medium/large cluster (>100 cores) you could set it to a smaller number, for instance if you would to leave cores free for other use, if you would like to have several simulation jobs run in parallel or if for some reason there is limited disk space available for the temporary job data (depending on dose grid size, up to a gigabyte per core).

proton physics list

Geant4 physics list for protons. Recommended setting: QGSP_BIC_HP_EMZ

ion physics list

Geant4 physics list for ions. Recommended setting: Shielding_EMZ

rbe factor protons

Usually 1.1

air box margin [mm]

During preprocessing, the CT image is cropped down to enclose the minimum bounding box around the air-padded External ROI and TPS dose distribution. The GATE simulation uses different cut parameters and step sizes inside and outside the cropped CT volume: crude simulation outside, detailed simulation inside. The air padding serves to ensure that the detailed simulation will always start a little bit before the particles enter the External ROI volume. The default margin is 10 mm.

remove dose outside external

Outside the external (in the air, typically) the dose is about the same as inside, but most TPS never show this. If you set this option then IDEAL will mask the final dose output, all voxels outside of the external are forced to have dose equal to zero. This is e.g. useful to avoid artifacts in gamma analysis.

gamma index parameters dta_mm dd_percent thr_gray def

If leave this setting empty, then IDEAL will not attempt any gamma index calculations. If you provide four nonzero values, then IDEAL will try to compute the gamma index distribution with the TPS dose as the reference image, but only for the voxels that are a dose above a given threshold.

• dta_mm: distance parameter in mm

• dd_percent: relative dose difference parameter in percent

• thr_gray: threshold value in Gray

• def: default gamma value for target voxels with dose values below threshold

stop on script actor time interval [s]

On each core, the simulation periodically saves the intermediate result for the dose distribution and for the simulation statistics (including the number of primaries simulated so far), and checks if the job control daemon has set a flag to indicate that the statistical goal (number of primaries, average uncertainty, and/or time out) has been reached and that the simulation should stop. This setting specifies the time interval between such save & check moments. Setting this too short will result in a slow down due to network overload, setting it too long will result in overshooting the statistical goals. Two minutes is a reasonable value for this setting. For medium/large number of cores (>100) it could possibly be good to choose longer times.

htcondor next job start delay [s]

When HTCondor “stages” the GateRTion jobs (starts the jobs on the calculation nodes), it starts them not all at the same time, but rather with a small delay between each job and the next. This is done on purpose, because all jobs will start by reading lots of input and configuration data. We want to avoid or at least reduce the stampede effect in which all these read requests are clogging up the network. The best value for this delay needs to found empirically on your network. On a fast network (and with fast network cards on all nodes), that is 10Gbit/s or faster, with about 50 physical cores, 1 second delay seems enough, but on a slower network, e.g. 1Gbit/s, it is advisable to choose a larger delay, for instance 10 seconds. It is advisable to make sure that this delay value times the number of cores is less than the stop on script actor time interval [s].

minimum dose grid resolution [mm]

The user can configure a dose resolution that is different from the TPS dose resolution by changing the number of voxels. Too fine grained resolution will be costly on resources (RAM, disk space) so there is a limit for this, defined by the minimum size that a dose voxel should have in each dimension.

This may not be the optimal way to guard against resource overusage, but it’s simple and intuitive. In later releases we could define other safeguards, maybe a maximum for the total number of voxels in the dose distribution.

Output options

The dose distribution can be saved in several stages of the calculation and in various formats. You can configure which ones you would like to have:

• run gamma analysis: run and write gamma analysis result to .mhd format

• write mhd unscaled dose: sum of the dose distributions from all simulation jobs, computed in the CT geometry (cropped to a minimal box around the TPS dose distribution and the External ROI). Since the total number of simulated primaries is much smaller than the total number of particles planned, this dose is much lower than the planned dose. This dose can be useful for debugging purposes and if this option is set then this dose will be exported in MHD format.

• write mhd scaled dose: this is the unscaled dose multiplied with the ‘(tmp) correction factor’ (see below) and with the ratio of the number of planned particles over the number of simulated particles. For example, if the correction factor is 1.01, 10¹¹ particles were planned for each of 30 fractions, and 10⁸ particles were simulated, then the scaling factor is 30300.

• write mhd physical dose: this is the scaled dose, resampled (using mass weighted resampling) to the same dose grid as the TPS dose distribution. Saved in MHD format.

• write dicom physical dose: this is the scaled dose, resampled (using mass weighted resampling) to the same dose grid as the TPS dose distribution. Saved in DICOM format.

• write mhd rbe dose: for protons, the “Relative Biological Effect” dose is estimated by mulitplying the physical dose by the RBE factor for protons setting (typically 1.1). Saved in MHD format. IDEAL can currently not compute RBE dose for other particles than protons.

• write dicom rbe dose: Save the RBE dose (for protons) in DICOM format.

• write mhd plan dose: Compute the plan dose (sum of physica/RBE beam doses) and save in MHD format.

• write dicom plan dose: Compute the plan dose (sum of physica/RBE beam doses) and save in DICOM format.

[(tmp) correction factors]

The computed dose distribution for a given treatment plan may need to be corrected by a constant factor to correct for a normalization error that can be due to various causes. Typically this factor is determined using plans and absolute dose measurements on (water) phantoms. In future releases of GateRTion this correction factor will be integrated in the beam model, hence the ‘(tmp)’ in the section name. The correction factor can be defined for each beam line and each radiation type separately, using “TreatmentMachineName RadiationType” as the label and a floating point number (typically close to 1.0) as the value. For combinations of beamlines and radiation types that are not explicitly configured, the “default” value will be used. The radiation type is “proton” for protons and “ion_Z_A_Q” for ions, where Z is the number of protons, A is the atomic number (number of protons plus number of neutrons) and Q is the electric charge of the ion in units of e. The radiation type for carbon ions is ION_6_12_6 and for helium ions it is ION_2_4_2. For example:

default = 1.0
IR2HBL ION_6_12_6 = 1.0
IR2HBL proton = 0.97371
IR2VBL proton = 1.00
IR3HBL proton = 0.97371

[msw scaling]

This section can be used to define an energy dependent scaling of the msw of each spot in the treatment plan. The user defines the scaling by providing the polynomial parameters of p(E) in descending order, where msw’(E) = p(E) * msw(E). The correction factor can be defined for each beam line and each radiation type separately, using “TreatmentMachineName RadiationType” as the label. For example:

default = 0.0 1.0
IR2VBL ION_6_12_6 = 0.0 1.0
IR3HBL ION_6_12_6 =  1.81847493e-09 -1.69699096e-06  3.62323835e-04  9.82505461e-01

[condor memory]

For typical IDEAL jobs, all core will be used. But for calculations with a large CT, high resolution dose distribution and/or many pencil beams, the RAM usage each Gate process can be so high that it’s better not to run on all cores. An IDEAL job submission to HTCondor includes a “memory request”. This will do two things:

1. HTCondor will assume that the job is going to use the requested amount of RAM at some point during the run. In order to avoid oversubscribing the RAM and cause swapping, HTCondor will not start running any new jobs if the sum of the requested amounts of RAM would exceed the available RAM.

2. If a running job uses more than the requested amount of RAM for a too long period of time, then that job will be killed or set on hold by HTCondor (the exact policy details can be configured in the HTCondor configuration files).

You can specify a minimum, default and maximum value of the memory request, in units of megabyte. IDEAL makes an estimate of the required RAM with a simple linear formula: RAM = offset + cA*A + cA*B + .... Here A, B are quantities that are expected to impact the memory usage of the Gate simulation, such as the number of dose voxels, number of CT voxels and the number of spots. The estimate will be different for CT and for phantom simulations (because the phatom does not have “CT voxels”), and for different particles (the cross section tables, which are responsible for an important part of the RAM usage, are significantly larger for carbon ions than for protons). The linearity coefficients (cA, cB, etc.) can be set by the user, based on system observations during a series of test runs with differently sized CTs, phantoms, dose resolutions and plans. The values given in the example below may be a good starting configuration for your local cluster, but may need tweaking depending on the available RAM and other factors.

Example configuration:

# how much memory should condor allocate per job?
# Condor uses the unit "MB", which might mean either 1024*1024 bytes or 1000*1000 bytes.
condor memory request minimum [MB] =  7000
condor memory request default [MB] =  8000
condor memory request maximum [MB] = 50000
condor memory fit proton ct = offset 1200 dosegrid 2.5e-05 ct 1.8e-06
condor memory fit proton phantom = offset 500.0 dosegrid 2.0e-05 nspots 0.0060
condor memory fit carbon ct = offset 1800 dosegrid 5e-05
condor memory fit carbon phantom =  offset 1000.0 dosegrid 8.0e-06
# if e.g. a proton plan gets a dose grid of 200*200*200=8e6 voxels and a ct with 16e6 voxels
# then the memory fit gives 1200 + 8e6*2.5e-5 + 16e6 * 1.8e-6 = 1428.8 MB estimated max RAM usage

[materials]

Everything about materials and material overrides.

materials database

With this setting the basename of the material database should be specified. IDEAL then expects to find a file with this name in the material subdirectory of the Commissioning Data Directory. This file can just be the standard database file GateMaterials.db that is included in the source code package for Gate and defines a large number of materials that are important typical Gate applications but are not included in the standard set of Geant4 materials. The Gate material database is a simple text file, which you can extend with any additional materials that are relevant in your clinic. It is recommended to give such an extended database file a name that makes it clear that this database is different from the standard material database file. E.g.:

materials database = MyClinicalMaterials2020.db

hu density tolerance [g/cm3]

The Schneider 2000 method is used to convert Hounsfield Unit (HU) values to materials, based on a density curve and a material composition table (see section CT protocol Hounsfield Lookup tables). For each new combination of density and composition Geant4 needs to define a new material. The density tolerance value defines the maximum difference between two “equivalent” density values. The full range of HU values is segmented in intervals such that the densities within each interval are equivalent to each other, and only one material defintion is associated with each interval.

Override materials

You may sometimes want to override the material in a region of interest (ROI) in a CT with a particular material from the database, to be used by Gate/Geant4 instead of the materials given by the Schneider tables. A typical use case for this is that in a CT of a water phantom, the volume of the phantom is overridden with G4_WATER, the standard Geant4 definition of water. For all materials that you expect to use for such overrides (Geant4 materials or materials that you provide in the material database file, see above), you should add a line in this section of the system configuration file that associates the name of the material with a density (in units of g/cm3). For instance:

G4_WATER = 1.0
G4_AIR = 0.00120479
G4_GRAPHITE = 2.21
G4_STAINLESS-STEEL = 8.0
G4_ALANINE = 1.42
PMMA = 1.195
Tungsten = 19.3
G4_Ti = 4.54

It would be nice if you only needed to give the list of the names of the allowed materials and that IDEAL would figure out the densities somehow from Geant4’s and Gate’s databases. This may be implemented in a future release, hopefully. For now, you just need to make sure that the density values that you give here are consistent with what the Gate and Geant4 databases are using.

[user roles]

This is the list of users that are expected/allowed to use this installation of IDEAL in a particular role. For users with more than role you need to add one line per role. Each line is of the form ACRONYM, username = role. Here username is a name without whitespaces that contains part of the name of a user plus a word that indicates the role. ACRONYM is a short version of the user name, for instance just the user’s initials. The role can be clinical, commissioning or admin (see Intended Users). Each username and acronym should be unique.

For instance:

OKE, obiwan = clinical
OKE_A, obiwan_admin = admin
OKE_C, obiwan_commissioning = commissioning
LSK, luke = clinical
LSK_C, luke_commissioning = commissioning
LES, leiha = clinical
HSO, han = clinical
DVA, darth = commissioning
YOD_A, yoda_admin = admin
YOD_C, yoda_commissioning = commissioning

Log daemon configuration file

Starting from version 1.1, IDEAL keeps track of all the simulations that have been started, in a global log file. The user has the possibility to have a real time overview of the status of each simulation by launching the log_daemon.py program, from the bin folder. The program runs in the background (hence ‘daemon’) and is responsible for the following tasks:

1. write and update a ‘cfg_log_file’, which reports, for each simulation:

   • submission date and time

   • working directory path

   • IDEAL status

   • condor id

   • condor status, in terms of how many jobs are running, idle, on hold and completed

   • job control daemon status. Is the daemon running?

2. zip the working directories of simulations considered ‘hystorical’ and archive them.

3. in case the user has configured IDEAL to run via the API interface, the daemon is responsible to send back the simulation results, once the simulation is complete.

After installing IDEAL, the user should take care of customizing the log_daemon.cfg file, in the cfg folder.

[Time variables]

historic after

time (in seconds) after which a job is considered hystorical. After this time, the working directory is zipped and moved to “old”.

unsuccessfull after

time after which a job is considered UNSUCCESSFULL after being removed from the condor queue. When a job doesn’t appear anymore in the condor queue, it is one of two cases. Either it was successfully terminated, or it failed, possibly for reasons related to the cluster management.

When a job doesn’t appear in the queue anymore, and after a time equals to the ‘unsuccessfull after’ it is not yet completed, it is marked as unsuccessful.

on hold untill

time that a job can be on hold before being considered UNSUCCESSFULL

running_freq

time (in seconds) between two successive updates of the cfg_log_file

[Paths]

global logfile

path of the global log file. This file will be created by IDEAL, if it doesn’t exist yet.

cfg_log_file

path of the cfg_log_file. This file will be created by IDEAL, if it doesn’t exist yet.

log_daemon_logs

path of the log_daemon.py logs. It is reccommanded to use the same logging directory used by IDEAL.

completed_dir

directory to archive successfully completed jobs

failed_dir

directory to archive failed job

logs_folder

same path as the IDEAL logs

api_cfg

path of the API configuration file

syscfg

path of the system.cfg file

Dictionary of possible condor job status:

submission_err = SUBMISSION ERROR
unsuccessfull = UNSUCCESSFULL
done = DONE
killed_by_log_daem = KILLED BY LOG DAEMON
checking = BEING CHECKED

API configuration file

To be able to use the IDEAL API interface, the user must customize the api.cfg file, in the cfg folder. The file has two main sections:

[receiver]

send result

true or false. If true, the log_daemon will attempt to send the results back. This assumes that there is a ‘receiving’ API running on the client.

an example of such an API can be found in receiver_test.py in the IDEAL’s main directory.

url to send result

e.g. http://127.0.0.1:3000/api/results

url authentication

e.g. http://127.0.0.1:3000/auth. The API uses login data.

[server]

IP host

IP address of the server

credentials db

.db file containing the authorized users login data and information.

ssl cert

path to the ssl certificate, if needed

ssl key

path to the ssl key, if needed

The API runs by default on the https protocol. Therefore, a self signed certificate and related key should be generated. The API can also run on http, with small modifications to the bin/api.py file. In this case, the ssl certificate and key are not needed. For more info, read the dedicated section on the user manual.

Beam line modelling

The beam modelling information stored under the beamlines subdirectories of the Commissioning Data Directory. For each treatment machine in the clinic, a subdirectory to the beamlines directory should be created, with the name equal to the same treatment machine name that is also used in DICOM plan files.

One special beamline directory is common, which can contain specifications (of nozzle components or generic passive elements) that can be used in all beamlines. Subfolders can be created under common to organize the resources.

A beam model consists of two text files, namely a “source properties” text file and a beamline details macro file.

Source properties file

The source properties file is a one of the main inputs for the Gate TPS pencil beam actor. The name of the source properties file should be of the form <TreatmentMachineName>_<RadiationType>_source_properties.txt. For instance, for a beamline named IR2HBL that can be used both for protons and carbon ions, two source properties files should be provided, named IR2HBL_PROTON_source_properties.txt and IR2HBL_ION_6_12_6_source_properties.txt, respectively. The source properties file defines:

• in which plane the source particles will be generated

• source axis distance (X and Y)

• optical properties (beam size, angular spread, emittance; polynomials in energy)

• range properties (energy offset between generation and isocenter, energy spread; polynomial in energy)

• monitor unit calibration (polynomial in energy)

An example of a source properties files can be found in the GateContrib project on GitHub. The procedure for fitting a pencil beam model for Gate is described in [FuchsBeamlineModels2020]. The scripts that were used for that publication are (at the time of writing these docs) not yet open source, but we hope that they soon will be.

Todo

IDEAL currently supports only one single source properties file per radiation type for each beam line. If a beam line is used with e.g. two different spot tunes, e.g. one spot tune with smaller and one with larger spot sizes, then this distinction is not supported by IDEAL. A simple solution (in a future release of IDEAL) might be to include the spot tune label (often this is a short version number, like “3.0”) in the names of the source properties files.

Beamline details macro file

This macro file should be named <TreatmentMachineName>_beamline_details.mac. For the example of a beamline named IR2HBL, this would be IR2HBL_beamline_details.mac. The information in it should be formatted using the Gate/Geant4 macro language

The minimal content for this file is to specify for each supported radiation type and for each of the two lateral directions whether the beam is convergent (or not) in the source generation plane. This is done by defining an alias that will be used by IDEAL in the configuration of the TPS PencilBeam source actor [1]. The names of the two aliases should be <RADIATION_TYPE>_XTHETA and <RADIATION_TYPE>_YPHI; for instance, for a beamline which supports two radiation types, namely a convergent proton beam and a divergent carbon beam, the definitions would be:

/control/alias PROTON_CONVERGENCE_XTHETA     true
/control/alias PROTON_CONVERGENCE_YPHI       true
/control/alias ION_6_12_6_CONVERGENCE_XTHETA false
/control/alias ION_6_12_6_CONVERGENCE_YPHI   false

In addition to the convergence information, the beamline details may contain the definition of the geometry of the parts of the nozzle that are relevant for particle propagation between the generation plane and the isocenter, for example the ionization chambers and collimators (if any).

For elaborate nozzle models, or for modeling several nozzles with common design elements, it may be preferable to split up the code in multiple source files, using the standard Geant4 /control/execute data/macro.mac directive. Those extra files can reside either in the common beamline folder, or in the treatment machine specific beamline subfolder. In the latter case, the names of the extra files and folders should all start with the treatment machine name. Relative paths should be used to refer to the executable macros and other input data. All files and folders in the common folder and in the treatment machine specific folder will be copied into the data subfolder of the Gate working directory for each IDEAL job; hence all paths to input data and to external macros run with /control/execute should be referred to with a path that starts with ./data.

Optional beamline description text file

Finally, each beamline directory optionally can contain a text file <TreatmentMachineName>_description.txt with a short description of the beamline that can be displayed by the IDEAL user interaces to the user.

Alternative beamline models for commissioning/research

A commissioning/research user may create a beamline model directory with a name that is different from all actual “treatment machine names” in the clinic or data set [2]. The beamline model in this directory will only be used if the user explicitly overrides the beamline model to use for IDEAL, instead of the model(s) that have the same name as the treatment machines. This can be desirable for commissioning and research activities (and should be avoided by users in a ‘clinical’ role). For instance, it might be instructive to compare a simple beam model in which primary particles are generated at the exit of the nozzle with a more elaborate model that starts at the entrance of the nozzle and takes all nozzle details into account.

Note that the name of the alternative beamline model should be used everywhere where normally the “treatment machine name” would be used. E.g. if you have a beamline named IR5 and you create an alternative beamline model named MyToyModelForIR5, then the source properties file for protons should be named MyToyModelForIR5_PROTON_source_properties.txt.

Footnotes

[1]

This convergence information should really be part of the source properties file. Also, for some beamlines the convergence may depend on energy, e.g. for low energies the beam is divergent and for higher energies it is convergent. In a future releases of Gate (and GateRTion, and IDEAL) these issues will hopefully be addressed; the convergence information should be part of the source properties file and the parametrization should allow this to be energy dependent.

[2]

It is advisable to choose beamline model names with only alphanumerical characters, so without e.g. spaces, commas and parentheses.

CT protocol Hounsfield Lookup tables

The Commissioning Data Directory should have a CT subdirectory. This directory contains the hlut.conf configuration file and three subdirectories, density, composition and cache.

The hlut.conf configuration file describes for each CT protocol which DICOM tags and values should be used to recognize it, as well as how to convert the HU values to materials. This text file should be edited by the commissioning physicist to provide the data for each of the relevant CT protocols in the clinic where IDEAL is installed.

There are two different ways to define the conversion from HU to materials.

1. For [Schneider2000] type conversion, provide the names of density and composition text files, which are expected to be found in the respective subfolders.

2. Provide a direct HU-to-material conversion table. A list of HU intervals can be given, and for each interval the name of the material is specified. This can be either a Geant4 material (e.g. G4_WATER) or a material that is defined in the GateMaterials.db file (e.g. PMMA).

Examples of the density and composition files for Schneider-type material conversion can be found in the GateContrib project on GitHub: * density * composition

IDEAL will not directly use these tables. Rather, for every new combination of density, composition and density tolerance value (usually set in the system configuration file) it will generate a new material database and an interpolated HU-to-material table, in which associates HU intervals directly with a material from the the new database. The HU intervals are chosen just small enough such that the steps in density between the subsequent materials are less than the density tolerance value. These generated tables are stored in a cache folder CT/cache and will be reused in following IDEAL jobs with the same combination of CT protocol and density tolerance.

Phantoms

In the phantoms subdirectory of the Commissioning directory you can define the phantoms that may be used in IDEAL simulations, instead of the CT image, for instance to simulate patience specific quality assurance (PSQA) measurements.

For every phantom, the definition is given in a pair of files with .cfg and .mac suffixes. The filenames without the suffixes must be identical, that part defines the name of the phantom. The mac file defines the geometry of the phantom; if the phantom is selected, then this will be included into the main Gate macro with /control/execute. The .cfg config file specifies the details of the dose grid and auxiliary text strings for use in help texts and a graphical user interface.

The water phantom installed by the bin/first_install.py should serve as a simple example:

water_box.cfg

# WATER BOX
[documentation]
GUI name = Water Phantom
# tooltip is currently not used but will soon be
tooltip = standard 50x50x40 cm3 water box phantom
# help text is currently not used, but will soon be
# help text can be multiple lines, if intented deeper than the initial line
help text = water phantom
 The water phantom is 50 cm high and long, and 40 cm wide (w.r.t. horizontal beam).
 Default position is with the center of the box at isocenter (0,0,0).
 To move the phantom vertically, change the Y coordinate (positive value means down).
 To move the phantom sideways along the gantry axis, change the Z coordinate (positive value means to the right in BEV).
 To move the phantom sideways perpendicular to the gantry axis, change the X coordinate (positive value means towards the nozzle for a horizontal beam line with gantry angle 90 degrees).

[dose grid]
# size of dose grid, center around origin, will translated by (x_move,y_move,z_move)
x grid size [mm] =  500
y grid size [mm] =  500
z grid size [mm] =  400
# resolution: how many voxels in each dimension
number of x voxels = 250
number of y voxels = 250
number of z voxels = 200
# Boolean flag for DoseActor: MPs are only interested in "dose to water". The material is already water, so no conversion is needed.
dose to water = no

water_box.mac

# WATER BOX # The name should be same as mac file, without the “.mac” suffix /gate/world/daughters/name water_box /gate/world/daughters/insert box /gate/water_box/setMaterial G4_WATER # you can hardcode the size, but if you change the values, remember to change it also in the corresponding .cfg file /gate/water_box/geometry/setXLength 500 mm /gate/water_box/geometry/setYLength 500 mm /gate/water_box/geometry/setZLength 400 mm # in the GUI the user can translate the phantom relative to isocenter # using same coordinate system as CT, HFS, patient angle 0: # Y axis points down, Z axis points to gantry axis, X points to left shoulder of patient if aligned with gantry axis # the x,y,z translation vector is communicated via aliases name_move_[xyz], where “name” is actually the phantom name /gate/water_box/placement/setTranslation {water_box_move_x} {water_box_move_y} {water_box_move_z} mm /gate/water_box/vis/setColor blue

Simulation parameters

The so-called “cut parameters” in Geant4/Gate simulations define the level of detail into which particles need to be tracked. This implies a trade-off between simulation accuracy and speed. Typically, for the volume outside of the patient volume speed is more important than accuracy, while inside the patient volume the priorities are reversed: accuracy is more important than speed.

The three kinds of parameters that need to be configured, per volume and per particle, are the “cut in region”, “minimum remaining” range and the “maximum step size”. Recommended values for clinical applications were reported in [Winterhalter2020].

The settings of the “cut parameters” can be different for computing the dose in the CT or in a custom phantom. IDEAL expects to find these settings settings in Gate macro files named ct-parameters.mac and phantom-parameters.mac, respectively, stored in the material subdirectory of the Commissioning Data Directory.

For CT simulations, the names of the relevant volumes are world, patient_box and patient. The patient volume is the the CT volume, the patient_box is a slightly larger volume that includes a layer of air around the patient, and the world volume encloses everything, including the patient, the nozzle and the particle generation plane.

For phantom simulations, the names of the non-world volumes are given in the phantom specifications. The name of the phantom selected by the user is available via the Geant4 alias {phantom_name}.

An example of the parameter settings for CT is given below.

##########################################################
# cut
##########################################################

# TODO: would be nice to use the Winterhalter values here.

# in air
/gate/physics/Gamma/SetCutInRegion      world 1 m
/gate/physics/Electron/SetCutInRegion   world 1 m
/gate/physics/Positron/SetCutInRegion   world 1 m

# in air close to patient
/gate/physics/Gamma/SetCutInRegion      patient_box 1 mm
/gate/physics/Electron/SetCutInRegion   patient_box 1 mm
/gate/physics/Positron/SetCutInRegion   patient_box 1 mm

# in patient
/gate/physics/Gamma/SetCutInRegion      patient 0.5 mm
/gate/physics/Electron/SetCutInRegion   patient 0.5 mm
/gate/physics/Positron/SetCutInRegion   patient 0.5 mm

##########################################################
# tracking cut
##########################################################

#Tracking cut in air
/gate/physics/SetMinRemainingRangeInRegion world 10 mm
/gate/physics/ActivateSpecialCuts e-
/gate/physics/ActivateSpecialCuts e+

#Tracking cut in air close to patient
/gate/physics/SetMinRemainingRangeInRegion patient_box 1 mm
/gate/physics/ActivateSpecialCuts e-
/gate/physics/ActivateSpecialCuts e+

#Tracking cut in patient
/gate/physics/SetMinRemainingRangeInRegion patient 0.5 mm
/gate/physics/ActivateSpecialCuts e-
/gate/physics/ActivateSpecialCuts e+

##########################################################
# step limiter
##########################################################

#stepLimiter in air
/gate/physics/SetMaxStepSizeInRegion world 1 m
/gate/physics/ActivateStepLimiter proton
/gate/physics/ActivateStepLimiter deuteron
/gate/physics/ActivateStepLimiter triton
/gate/physics/ActivateStepLimiter alpha
/gate/physics/ActivateStepLimiter GenericIon

#stepLimiter in air close to patient
/gate/physics/SetMaxStepSizeInRegion patient_box 1 mm
/gate/physics/ActivateStepLimiter proton
/gate/physics/ActivateStepLimiter deuteron
/gate/physics/ActivateStepLimiter triton
/gate/physics/ActivateStepLimiter alpha
/gate/physics/ActivateStepLimiter GenericIon

#stepLimiter in patient
/gate/physics/SetMaxStepSizeInRegion patient 0.5 mm
/gate/physics/ActivateStepLimiter proton
/gate/physics/ActivateStepLimiter deuteron
/gate/physics/ActivateStepLimiter triton
/gate/physics/ActivateStepLimiter alpha
/gate/physics/ActivateStepLimiter GenericIon