Monte Carlo simulation tools

A collection of useful functions for Monte Carlo simulations.

fredtools.setFieldsFolderStruct(folderPath, RNfileName, folderName='FRED', overwrite=False, displayInfo=False)

Create a folder structure for each field in the treatment plan.

The function creates a folder structure in a given folderPath for each field separately. The folder structure is in the form:

folderPath/folderName:

/ 1_Field2

/ 2_Field3

/ 3_Field1

…

The number at the beginning of the folder name is the delivery number and the number after Field is the ID of the field.

Parameters:

• folderPath (path) – Path to a folder to create the structure.

• RNfileName (path) – Path to RN dicom file of a treatment plan.

• folderName (string, optional) – Name of the folder to create. (def. ‘FRED’)

• overwrite (bool, optional) – Determine if the folder should be overwritten. If true, then all the data in the existing folder will be removed. (def. False)

• displayInfo (bool, optional) – Displays a summary of the function results. (def. False)

Returns:

Path to created folder structure.

Return type:

path

fredtools.readFREDStat(fileNameLogOut, displayInfo=False)

Read FRED simulation statistics information from the log file.

The function reads some statistics information from a FRED run.out logfile. If some information is unavailable, then a NaN or numpy.np.nan is returned.

Parameters:

• fileNameLogOut (string) – A string path to FRED output logfile (usually in out/log/run.out)

• displayInfo (bool, optional) – Displays a summary of the function results. (def. False)

Returns:

A dictionary with the read data.

Return type:

dict

fredtools.writeBeamModel(beamModel, fileName)

Write beam model to YAML.

The function writes the beam model parameters in YAML format for a beam model file. The beam model must be defined as a dictionary. If a value of a given key is a pandas DataFrame, it will be saved to a nicely formatted table.

Parameters:

• beamModel (dict) – Beam model defined as a dictionary with the required keys.

• fileName (string) – A string path to beam model YAML file. It is recommended to use .bm file extension.

See also

readBeamModel

read beam model from YAML beam model file.

interpolateBeamModel

interpolate all beam model parameters for a given nominal energy.

fredtools.readBeamModel(fileName)

Read beam model from a YAML file.

The function reads the beam model parameters from a YAML beam model file. The beam model must be defined as a dictionary. All the pandas DataFrame-like lists will be converted to pandas.DataFrame objects, whereas any items in square brackets will be converted to a numpy array object.

Parameters:

fileName (string) – A string path to beam model YAML file.

Returns:

A dictionary with the beam model and required kays.

Return type:

dict

See also

writeBeamModel

write beam model to YAML file.

interpolateBeamModel

interpolate all beam model parameters for a given nominal energy.

fredtools.interpolateBeamModel(beamModel, nomEnergy, interpolation='linear', splineOrder=3)

Interpolate beam model for a given nominal energy.

The function interpolates all the beam model parameters for a given nominal energies which must be in range of the defined nominal energies in the beam model. The possible interpolation methods are ‘nearest’, ‘linear’ or ‘spline’ with order in range 0-5.

Parameters:

• beamModel (DataFrame) – Beam model defined as a pandas DataFrame object.

• nomEnergy (scalar or list) – The list of nominal energies to interpolate the beam model parameters for.

• interpolation ({'linear', 'nearest', 'spline'}, optional) – Determine the interpolation method. (def. ‘linear’)

• splineOrder (int, optional) – Order of spline interpolation. Must be in range 0-5. (def. 3)

Returns:

Pandas DataFrame with all parameters interpolated.

Return type:

Pandas DataFrame

See also

readBeamModel

read beam model from CSV beam model file.

writeBeamModel

write beam model from DataFrame to a nicely formatted CSV.

fredtools.getFREDVersions()

List the installed FRED varions.

The function lists the FRED versions installed on the machine.

Returns:

List of FRED versions.

Return type:

List of strings

See also

checkFREDVersion

check if the FRED version is installed.

fredtools.checkFREDVersion(version)

Check if the FRED version is installed.

The function validates if the version of FRED, given by the parameter is installed on the machine.

Parameters:

version (str) – Version in format #.#.#.

Returns:

True if the version is installed.

Return type:

bool

See also

getFREDVersions

list the installed FRED varions.

fredtools.getFREDVersion(version='')

Get the full FRED version name.

The function checks if the version of FRED is installed and returns its full version name.

Parameters:

version (str) – Version in format #.#.#.

Returns:

Full version name returned by FRED.

Return type:

str

See also

getFREDVersions

list the installed FRED varions.

fredtools.runFRED(fredInpFileName, version='', params=[], displayInfo=False)

Run FRED simulation.

The function runs FRED simulation defined by the FRED input file name in the given FRED version.

Parameters:

• fredInpFileName (path) – Path string to FRED input file. Usually, it is called fred.inp.

• version (str, optional) – Version of FRED in format #.#.#. If no version is given then the current version installed is used. (def. “”)

• params (str or list of strings, optional) – Additional parameters to FRED engine, for instance [“-C”, “-V5”, “-nogpu”] etc. (def. [])

• displayInfo (bool) – Displays a summary of the function results. (def. False)

Returns:

Standard output of the subprocess method in the form of list of string lines.

Return type:

subprocess stdout

See also

readFREDStat

read FRED simulation statistics information from logfile.

checkFREDVersion

check if the FRED version is installed.

getFREDVersions

list the installed FRED varions.

fredtools.readGATE_HITSActor(fileName)

read GATE hits data for active volume.

The function reads hits results of GATE active volume saved to numpy pickle (.npy) or root (.root) file. All the columns are read but some of them are renamed:

• ds is a step length in [cm]

• Edep is deposited energy in [MeV]

• PDGCode is the same as PDG encoding [1]

Parameters:

fileName (path) – Path string to .npy or .root file.

Returns:

Dataframe with the data.

Return type:

pandas DataFrame

See also

readFREDStat

read FRED simulation statistics information from logfile.

References

[1]

Monte Carlo Particle Numbering Scheme

fredtools.readGATE_PSActor(fileName)

read GATE hits data for active volume.

The function reads hits results of GATE active volume saved to numpy pickle (.npy) or root (.root) file. All the columns are read but some of them are renamed:

• ds is a step length in [cm]

• Edep is deposited energy in [MeV]

• PDGCode is the same as PDG encoding [2]

Parameters:

fileName (path) – Path string to .npy or .root file.

Returns:

Dataframe with the data.

Return type:

pandas DataFrame

See also

readFREDStat

read FRED simulation statistics information from logfile.

References

[2]

Monte Carlo Particle Numbering Scheme

fredtools.readGATEStat(fileNameLogOut, displayInfo=False)

Read GATE simulation statistics information from Simulation Statistic Actor.

The function reads some statistics information from the GATE Simulation Statistic Actor output [3].

Parameters:

• fileNameLogOut (string) – A string path to GATE Simulation Statistic Actor output.

• displayInfo (bool, optional) – Displays a summary of the function results. (def. False)

Returns:

A dictionary with the read data.

Return type:

dict

References

[3]

GATE manual for Simulation Statistic Actor

fredtools.calcRaysVectors(targetPoint, SAD)

Calculate rays positions and direction versors.

The function calculates the ray position and direction versor from the target position. The target point can be a 3-element iterable or Nx3 iterable for multiple points. The Source-To-Axis Distance (SAD) describes the absolute distances of the spreading devices in order [X, Y]. It does not matter if the first divergence is in X or Y, the function takes this information from the distances, but the order [X,Y] must be preserved.

Parameters:

• targetPoint (3-element or Nx3 iterable) – The position of a single target point or positions of N target points.

• SAD (2-element iterable) – The absolute distances of the spreading devices in order [X,Y].

Returns:

A tuple with two Nx3 arrays, where the first is the ray position and the second is the ray direction versor.

Return type:

(Nx3 numpy.array, Nx3 numpy.array)