Code documentation

The following documentation is generated directly from the source code. It should enable an overview of the different options which are available for different optimisers.

Optimisers

This module contains the specific optimisation algorithms for TopasOpt. Most functionality is defined in TopasOptBaseClass, which other optimisers inherit from.

class TopasOpt.Optimisers.BayesianOptimiser(bayes_length_scales=None, bayes_UCBkappa=5, bayes_KappaDecayIterations=10, bayes_GP_alpha=0.01, custom_kernel=None, **kwds)

Bases: TopasOptBaseClass

Class to perform optimisation using the Bayesian Optimisation code Specific options are described below, the rest are described in TopasOptBaseClass

Parameters:

bayes_length_scales (None, float, or array (optional)) –
Bayes-specific parameter to defined the length scales used in the gaussian process model. This can be supplied as one of three things: - None: in this case, the default is used: length_scale=1.0 - Number between 0 and 1: in this case, the length scales for each parameter are derived as a percentage of range.

For instance if the user enter 0.1, all length scales will be set to 10% of the range of each variable
- Array-like: Finally, the user is free to simply specify what length scales to use for each parameter.
  Make sure you enter them in alphabetical order as this is the order used internally by the optimizer.
bayes_UCBkappa (float, optional) – Bayes-specific parameter . kappa value in UCB function. A higher value=more exploration. see this notebook for explanation
bayes_KappaDecayIterations (int, optional) – Bayes-specific parameter. Over the last N iterations, kappa will decay to be almost 0 (highly exploitive). For explantion of kappa decay see here
bayes_GP_alpha (float, optional) – Bayes-specific parameter. This parameter handles the smoothness of the gaussian process model. for a noisy objective function, increasing this value can minimise overfitting errors.
custom_kernel (instance of scikit-learn.gaussian_process.kernels.Kernel or derived classes) – You can optionally [construct your own kernel](https://scikit-learn.org/stable/modules/gaussian_process.html) to use in the gaussian process model

RestartOptimisation(): Sometimes for whatever reason an optimisation is stopped prematurely. This function allows you to restart the optimisation by loading the previous log files. You just have to change Optimiser.RunOptimisation() to Optimiser.RestartOptimisation() in your optimisation script; the code will do the rest automatically.

RunOptimisation(): This is the main optimisation loop. For explanation of the various parameters and commands, start with the

class TopasOpt.Optimisers.NelderMeadOptimiser(NM_StartingSimplex=None, **kwds)

Bases: TopasOptBaseClass

Implementation of Nelder-Mead based on scipy. Other options are defined in TopasOptBaseClass

Parameters:: NM_StartingSimplex (None or float or array-like, optional) – This is a Nelder-Mead specific parameter which controls the size of the starting simplex. A value of .1 will create a starting simplex that is spans 10% of the starting values, which is the default behavior. Alternatively one can specify the starting simplex, e.g. for a 2D function starting_sim = [[0.9, 0.9], [0.72, 0.9], [0.9, 0.72]]

RunOptimisation(): Use the scipy.optimize.minimize module to perform the optimisation. Note that most of the ‘action’ is happening in BlackBoxFunction, which is repeated called by the optimiser

class TopasOpt.Optimisers.TopasOptBaseClass(optimisation_params, BaseDirectory, SimulationName, OptimisationDirectory, ReadMeText=None, G4dataLocation='~/G4Data', TopasLocation='~/topas/', ShellScriptHeader=None, Overwrite=False, KeepAllResults=True)

Bases: object

There are many overlapping functionalities required by all optimisation algorithms: logging, calculation of objective function, generation of models…etc. All of these common methods are contained this base class which other optimisation methods inherit. This class is not intended to be used in isolation and won’t work if you try.

Parameters:

optimisation_params (list or array) – Parpytameters to be optimised.
BaseDirectory (string) – Place where all the topas simulation results are stored
SimulationName (string) – Specific folder for this simulation
OptimisationDirectory (string or Path) – location that TopasObjectiveFunction and GenerateTopasScript are located
ReadMeText (string, optional) – If supplied, is written to a readme file in BaseDirectory
G4dataLocation (str) – location of G4data files
TopasLocation (string or pathlib.Path, optional) – location of topas installation. Default is ~/topas if you follow the topas instructions.
ShellScriptHeader (string, optional) – Header to place at the start of the bash file that runs the topas model. This header should contain all the commands you normally perform to set up your terminal environment.
Overwrite (bool, optional) – if True, will automatically overwrite any existing files. If False, will ask first (safer)
KeepAllResults (bool, optional) – if True, all results kept, if false, only most recent results are kept. Note that in either case the log files contain the info from all cases, it’s just a matter of whether you want to store every iteration which can take a lot of space

BlackBoxFunction(x_new): Called Black Box function in the spirit of bayesian optimisation, this function simply takes the most recent parameter guesses, and solves the model.

abstract RunOptimisation(): each inheriting optimizer must supply its own RunOptimisation method

SetUpDirectoryStructure(): Method to set up directory structure. This will attempt to empty the directory if it already exists. If Overwrite=False, it will ask first, otherwise just do it. Also writes the readme text if that exists, and copies all attributes of self to a json file.

TopasScriptGenerator

Convert topas parameter files into a python function that recreates the input files.

class TopasOpt.TopasScriptGenerator.generate_topas_script_generator(OutputDirectory, TopasScriptLocation, IncludeFileStorageDirectory=None, ErrorChecking=True)

Bases: object

This code will take a list topas scripts, and create a python function that returns a list for each script. Each list element contains one line of the topas script, which can be used to automatically regenerate that script. This class will also attempt to handle input/output lines in the topas language such as include lines and input and output of phase space lines.

Parameters:

OutputDirectory (string or pathlib.Path) – location to write the returned python function to
TopasScriptLocation (string or pathlib.Path) – location of all topas scripts which need to be recreated. Note that you do not need to enter ‘include’ files, as these are found automatically. You only need to enter files which will be changing on each iteration. The order of the files must match the order in which they will be run so the code can correctly detect dynamic input/output files.
IncludeFileStorageDirectory (None or string or pathlib.Path (optional)) – Any included files will be copied here. This is to try and ensure the topas scripts are portable. If no path is entered then they will be written to OutputDirectory / IncludeFiles
ErrorChecking (bool, optional) – if True (recommended), will attempt to perform some checks on the input data.

utilities

Supporting classes and functions that don’t belong anywhere else in particular

class TopasOpt.utilities.FigureSpecs

Bases: object

Thought this might be the easiest way to ensure universal parameters accross all figures

AxisFontSize = 14

Font = 'serif'

LabelFontSize = 14

TitleFontSize = 16

TopasOpt.utilities.PlotLogFile(LogFileLoc, save_loc=None)

This function can be used to plot an existing log file

Parameters:

LogFileLoc (string or pathlib.Path) – location of log file
save_loc (string or pathlib.Path) – if supplied, will attempt to save the log file there without displaying it. No error checking included! If not supplied, behaviour is instead to show the plot

TopasOpt.utilities.ReadInLogFile(LogFileLoc)

Read in a log file and return as a dictionary

Parameters:: LogFileLoc (string or pathlib.Path) – path to log file

class TopasOpt.utilities.WaterTankData(AnalysisPath, FileToAnalyse, AbsDepthDose=False, verbose=False)

Bases: object

Read in and analyse a series of topas scoring files in a rectangular phantom (the water tank). The main attribute is the ‘DoseCube’ array. This is the agregate of all the input files. If you only put one file in, then this is simply the agregate of that single file. A number of plotting routines are already provided which operate on this array, but if you need to you can use ExtractDataFromDoseCube to generate any additional data from it.

Basic use:

home = os.path.expanduser("~")
AnalysisPath = home + '/Dropbox (Sydney Uni)/Projects/PhaserSims/topas/Paper_7mm_all/Results/'
FileToAnalyse = GetAllBinFiles(AnalysisPath)
Dose = WaterTankData(AnalysisPath, FileToAnalyse, MirrorData=True)
Dose.Plot_DosePlanes()
# extract some additional data from agregate dose cube, XY plane for example:
[Xpts, Ypts] = np.meshgrid(Dose.x, Dose.y)
Zpts = Dose.PhantomSizeZ * np.ones(Xpts.shape)
XY_data = Dose.ExtractDataFromDoseCube(Xpts, Ypts, Zpts)

Parameters:

AnalysisPath (str or Path) – Location of result files
FileToAnalyse (str, or list of strings) – all result files to read in
AbsDepthDose (bool) – if True, absolute dose instead of normalized dose is plotted
verbose (bool) – if True, various messages are printed

ExtractDataFromDoseCube(Xpts, Ypts, Zpts)

Extract data from the dose cube at positions Xpts, Ypts, Zpts Each of these is an array or list, and they must be the same shape (they can be of any dimensionality as they are flattened inside the function). The data is returned in the same shape as the input points.

Parameters:

Xpts – x points
Ypts – y points
Zpts – z points

Returns:

InterpolatedData: numpy array of Dose at [Xpts, Ypts, Zpts]. Shape is the same as the input coordinate arrays

Plot_DepthDose(): Plot integral depth dose curves of all beamlets

Plot_DosePlanes(AddColorBar=False)

Use the DoseCube data to create a plot through each of the cardinal planes.

Parameters:: AddColorBar – adds color bar if True

Plot_Profiles(dir='X', Zpoints=None)

Plot profiles through integrated data. Can choose dir=’X’ or dir=’Y’ You can also optionally pass multiple Z points; otherwise Z is set to the middle of the phantom

Parameters:

dir – ‘X’ or ‘Y’, controls profile direction
Zpoints – Z coordinates to plot profiles at; if None will plot through the middle of the Phantom

Plot_XYsurface(Zpoints=None): Plot XY plots for multiple Z if Z = None, a single plot through the middle of the water phantom is produced

class TopasOpt.utilities.bcolors

Bases: object

This is just here to enable me to print pretty colors to the linux terminal

BOLD = '\x1b[1m'

ENDC = '\x1b[0m'

FAIL = '\x1b[91m'

HEADER = '\x1b[95m'

OKBLUE = '\x1b[94m'

OKCYAN = '\x1b[96m'

OKGREEN = '\x1b[92m'

UNDERLINE = '\x1b[4m'

WARNING = '\x1b[93m'

TopasOpt.utilities.compare_multiple_results(BinFiles, abs_dose=False, custom_legend_names=None)

this produces depth dose and profile plots for a list of topas .bin files.

Parameters:

BinFiles (list) – list of files to analyse
abs_dose (boolean, optional) – % dose (False) or absolute dose (True)
custom_legend_names (list, optional) – if passed, this list will be used for legend. If not, file names will be used.

TopasOpt.utilities.generate_run_all_scripts_shell_script(script_location, scripts_to_run, topas_location='~/topas38', G4_DATA='~/G4Data')

generate a bash script to run a series of topas scripts

Parameters:

script_location (Path or str) – Directory where the scripts are stored
scripts_to_run (array like) – a list of scripts to run
topas_location (Path or str) – location of the topas executable
G4_DATA (Path or str) – location of the G4data

Returns:

TopasOpt.utilities.get_all_files(PathToData, file_extension): quick script to just collect all the files in the Analysis path :param PathToData: folder where the files are :type PathToData: pathlib.Path or string :param file_extension: extension of files to return, e.g. ‘dcm’ :type file_extension: str :returns Files: list of all found files

class TopasOpt.utilities.newJSONLogger(path: Path)

Bases: JSONLogger

To avoid the annoying behaviour where the bayesian logs get deleted on restart. Thanks to: https://github.com/fmfn/BayesianOptimization/issues/159