matRad API Documentation

matRad is separted into a top-level API that consists of a few functions to run the treatment planning workflow resting on the top-level of the the matRad folder / module. The core implementation is organized in several subdirectories / submodules that are called by the API functions and can be used for more fine-grained development. Startup and configuration functions are located in the root of the repository.

Note

The root-level scripts (matRad.m, matRadGUI.m, matRad_rc.m etc.) are not auto-documented here. See the Using the matRad.m script guide for usage information.

Below, the top-level matRad functions are explained. For more specialized functions, refer to the documentation of the respective Modules / Subfolders.

Global Configuration

matRad’s global configuration class MatRad_Config is used to set up the environment and configuration for the matRad application. It is implemented as a Singleton pattern and thus consistent throughout a matRad session.

At the core, the class handles user folders, caches the environment (Matlab/Octave), provides matRad’s version, and stores default parameters. The class also provides logging functionality enabling control over output via log levels.

class MatRad_Config

Bases: handle

MatRad_Config MatRad Configuration class This class is used globally through Matlab to handle default values and logging and is declared as global matRad_cfg.

Usage:

matRad_cfg = MatRad_Config.instance();

Copyright 2019-2026 the matRad development team.

This file is part of the matRad project. It is subject to the license terms in the LICENSE file found in the top-level directory of this distribution and at https://github.com/e0404/matRad/LICENSE.md. No part of the matRad project, including this file, may be copied, modified, propagated, or distributed except according to the terms contained in the LICENSE file.

MatRad_Config Constructs an instance of this class. The configuration is implemented as a singleton and used globally Therefore its constructor is private For instantiation, use the static MatRad_Config.instance();

Property Summary
logLevel = 4

Logging

keepLog = false

Stores the full log in memory

writeLog = false

Writes the log to a file on-the-fly

defaults
disableGUI = false

Disable GUI

devMode = false
eduMode = false
gui
userfolders

Cell array of user folders containing machines, patients, hluts. Default contains the userdata folder in the matRad root directory

propDoseCalc

Default Properties

propOpt
propStf
messageLog = {}
logFileHandle
env

For storing the Environment & its version

envVersion
isOctave

Helper bool to check for Octave

isMatlab

Helper bool to check for Matlab

matRad_version

MatRad version string

matRadRoot

Path to matRadRoot

matRadSrcRoot

Path to matRadSrcRoot (“matRad” subfolder of matRadRoot)

primaryUserFolder

Points to the first entry in userfolders

exampleFolder

Contains examples

thirdPartyFolder

Contains third party tools/libraries used in matRad

Method Summary
delete(~)

might not be desired by users rmpath(genpath(matRad_cfg.matRadRoot));

displayToConsole(type, formatSpec, varargin)
displayToConsole lowest-level logging function for matRad.

Display to console will be called from the public wrapper functions dispError, dispWarning, dispInfo, dispDebug

Input:

  • type – type of the log information. Needs to be one of ‘error’, ‘warning’, ‘info’ or ‘debug’.

  • formatSpec – string to print using format specifications similar to fprintf

  • varargin – variables according to formatSpec

reset()

Set all default properties for matRad’s computations

setDefaultProperties()

setDefaultProperties set matRad’s default computation properties

setDefaultPropertiesForTesting()

setDefaultPropertiesForTesting sets matRad’s default properties during testing to reduce computational load

setDefaultPropertiesForEduMode()
setDefaultGUIProperties()

Detect current theme

dispDebug(formatSpec, varargin)

dispDebug print debug messages (log level >= 4)

Input:

  • formatSpec – string to print using format specifications similar to fprintf

  • varargin – variables according to formatSpec

dispInfo(formatSpec, varargin)

dispInfo print information console output (log level >= 3)

Input:

  • formatSpec – string to print using format specifications similar to fprintf

  • varargin – variables according to formatSpec

dispError(formatSpec, varargin)

dispError print errors (forwarded to “error” that will stop the program) (log level >= 1)

Input:

  • formatSpec – string to print using format specifications similar to ‘error’

  • varargin – variables according to formatSpec

dispWarning(formatSpec, varargin)

dispError print warning (forwarded to ‘warning’) (log level >= 2)

Input:

  • formatSpec – string to print using format specifications similar to ‘warning’

  • varargin – variables according to formatSpec

dispDeprecationWarning(formatSpec, varargin)

dispDeprecationWarning wrapper for deprecation warnings forwarded to displayToConsole

writeLogToFile(filename)

writeLogToFile writes the log kept in MatRad_Config to file. Note that the switch keepLog must be enabled for MatRad_Config to store all logging output.

getEnvironment()

getEnvironment function to get the software environment matRad is running on

getDefaultProperties(pln, fields)

Function to load all non-set parameters into pln struct

configureEnvironment()
updateUserfolders()

obtain userfolders

static instance()

instance creates a singleton instance of MatRad_Config In MatRad_Config, the constructor is private to make sure only on global instance exists. Call this static function to get or create an instance of the matRad configuration class

static loadobj(sobj)

Overload the loadobj function to allow downward compatibility with workspaces which where saved as an older version of this class

Top-level API functions

matRad_version(matRadRoot)

matRad function to get the current matRad version (and git information when used from within a repository

call

[versionString,matRadVer] = matRad_version() [versionString,matRadVer] = matRad_version(matRadRoot)

Input:

matRadRoot – Optional Root Directory. This is for call in matRad initialization when MatRad_Config is not yet available

Output:

  • versionString – Readable string build from version information

  • matRadVer – struct with version information

References

Copyright 2020-2026 the matRad development team.

This file is part of the matRad project. It is subject to the license terms in the LICENSE file found in the top-level directory of this distribution and at https://github.com/e0404/matRad/LICENSE.md. No part of the matRad project, including this file, may be copied, modified, propagated, or distributed except according to the terms contained in the LICENSE file.

matRad_planAnalysis(resultGUI, ct, cst, stf, pln, varargin)

matRad plan analysis function This function performs analysis on radiation therapy plans, including DVH (Dose-Volume Histogram) and quality indicators. It optionally displays these analyses based on input parameters.

Input:

  • resultGUI – matRad resultGUI struct containing the analysis results

  • ct – matRad ct struct with computed tomography data

  • cst – matRad cst cell array with structure definitions

  • stf – matRad stf struct with beam information

  • pln – matRad pln struct with plan information

  • name / value pairs – Optional parameters for analysis customization

  • refGy – (optional) Dose values for V_XGy calculation (default: [40 50 60])

  • refVol – (optional) Volume percentages for D_X calculation (default: [2 5 95 98])

Output:

resultGUI – Updated resultGUI with analysis data

matRad_doseRecalc(cst, pln, recalc, ct, apertureInfo, calcDoseDirect, dij)

nearest existing Dij column.

call

recalc = matRad_doseRecalc(cst,pln,recalc,ct,apertureInfo) recalc = matRad_doseRecalc(cst,pln,recalc,ct,apertureInfo,calcDoseDirect) recalc = matRad_doseRecalc(cst,pln,recalc,ct,apertureInfo,calcDoseDirect,dij)

input

cst, ct: patient data pln: original optimisation plan (anchor angles + propOpt) recalc: recalc options struct (interpNew, dijNew,

continuousAperture, pln with recalc spacing, …)

apertureInfo: aperture info from the optimisation result calcDoseDirect: (optional, default true) use direct dose calc dij: (optional) Dij for back-projection when ~calcDoseDirect

output

recalc: updated struct with stf, apertureInfo, and resultGUI

Copyright 2015 the matRad development team.

This file is part of the matRad project. It is subject to the license terms in the LICENSE file found in the top-level directory of this distribution and at https://github.com/e0404/matRad/LICENSES.txt. No part of the matRad project, including this file, may be copied, modified, propagated, or distributed except according to the terms contained in the LICENSE file.

matRad_preconditionFactors(apertureInfo)

accordingly.

call

apertureInfo = matRad_preconditionFactors(apertureInfo)

input

apertureInfo: aperture shape info struct

output

apertureInfo: aperture shape info struct with new factors

References

[1] http://onlinelibrary.wiley.com/doi/10.1118/1.4914863/full

matRad_calcDoseForward(ct, cst, stf, pln, w)

matRad forward dose calculation (no dij)

call

resultGUI = matRad_calcDoseForward(ct,cst,stf,pln) %If weights stored in stf resultGUI = matRad_calcDoseForward(ct,cst,stf,pln,w)

Input:

  • ct – ct cube

  • cst – matRad cst cell array

  • stf – matRad steering information struct

  • pln – matRad plan meta information struct

  • w – optional (if no weights available in stf): bixel weight vector

Output:

resultGUI – matRad result struct

References

Copyright 2015-2026 the matRad development team.

This file is part of the matRad project. It is subject to the license terms in the LICENSE file found in the top-level directory of this distribution and at https://github.com/e0404/matRad/LICENSE.md. No part of the matRad project, including this file, may be copied, modified, propagated, or distributed except according to the terms contained in the LICENSE file.

matRad_recalcApertureInfo(recalc, apertureInfoOld)
call

recalc = matRad_recalcApertureInfo(recalc,apertureInfo)

input

recalc: apertureInfo:

output

recalc:

References

matRad_generateStf(ct, cst, pln, visMode)

matRad steering information generation

call

stf = matRad_generateStf(ct,cst,pln)

Input:

  • ct – ct cube

  • cst – matRad cst struct

  • pln – matRad plan meta information struct

Output:

stf – matRad steering information struct

References

Copyright 2015-2026 the matRad development team.

This file is part of the matRad project. It is subject to the license terms in the LICENSE file found in the top-level directory of this distribution and at https://github.com/e0404/matRad/LICENSE.md. No part of the matRad project, including this file, may be copied, modified, propagated, or distributed except according to the terms contained in the LICENSE file.

matRad_directApertureOptimization(dij, cst, apertureInfo, resultGUI, pln)

matRad function to run direct aperture optimization

call

[optResult,optimizer] = matRad_directApertureOptimization(dij,cst,apertureInfo,optResult,pln)

Input:

  • dij – matRad dij struct

  • cst – matRad cst struct

  • apertureInfo – aperture shape info struct

  • optResult – resultGUI struct to which the output data will be added, if this field is empty optResult struct will be created

  • pln – matRad pln struct

Output:

  • optResult – struct containing optimized fluence vector, dose, and shape info

  • optimizer – used optimizer object

References

[1] http://dx.doi.org/10.1118/1.4914863

Copyright 2015-2026 the matRad development team.

This file is part of the matRad project. It is subject to the license terms in the LICENSE file found in the top-level directory of this distribution and at https://github.com/e0404/matRad/LICENSE.md. No part of the matRad project, including this file, may be copied, modified, propagated, or distributed except according to the terms contained in the LICENSE file.

matRad_sequencing(resultGUI, stf, dij, pln, visBool)

matRad inverse planning wrapper function

call

resultGUI = matRad_sequencing(resultGUI,stf,dij,pln)

Input:

  • dij – matRad dij struct

  • stf – matRad stf struct

  • pln – matRad pln struct

  • resultGUI – struct containing optimized fluence vector, dose, and (for biological optimization) RBE-weighted dose etc.

Output:

resultGUI – struct containing optimized fluence vector, dose, and (for biological optimization) RBE-weighted dose etc.

References

Copyright 2016-2026 the matRad development team.

This file is part of the matRad project. It is subject to the license terms in the LICENSE file found in the top-level directory of this distribution and at https://github.com/e0404/matRad/LICENSE.md. No part of the matRad project, including this file, may be copied, modified, propagated, or distributed except according to the terms contained in the LICENSE file.

matRad_fluenceOptimization(dij, cst, pln, stf, wInit)

matRad inverse planning wrapper function

call

[resultGUI,optimizer] = matRad_fluenceOptimization(dij,cst,pln) [resultGUI,optimizer] = matRad_fluenceOptimization(dij,cst,pln,wInit)

Input:

  • dij – matRad dij struct

  • cst – matRad cst struct

  • pln – matRad pln struct

  • wInit – (optional) custom weights to initialize problems

Output:

  • resultGUI – struct containing optimized fluence vector, dose, and (for biological optimization) RBE-weighted dose etc.

  • optimizer – Used Optimizer Object

References

Copyright 2016-2026 the matRad development team.

This file is part of the matRad project. It is subject to the license terms in the LICENSE file found in the top-level directory of this distribution and at https://github.com/e0404/matRad/LICENSE.md. No part of the matRad project, including this file, may be copied, modified, propagated, or distributed except according to the terms contained in the LICENSE file.

matRad_calcDeliveryMetrics(result, pln, stf)
call

matRad_calcDeliveryMetrics(result,pln)

input

result: result struct from fluence optimization/sequencing pln: matRad plan meta information struct

output

All plans: total MU VMAT plans: total time, leaf speed, MU rate, and gantry rotation speed distributions

matRad_calcDoseInfluence(ct, cst, stf, pln)

matRad dose calculation automaticly creating the appropriate dose engine for the given pln struct and called the associated dose calculation funtion

call

dij = matRad_calcDoseInfluence(ct,cst,stf,pln)

Input:

  • ct – ct cube

  • cst – matRad cst cell array

  • stf – matRad steering information struct

  • pln – matRad plan meta information struct

Output:

dij – matRad dij struct

References

Copyright 2015-2026 the matRad development team.

This file is part of the matRad project. It is subject to the license terms in the LICENSE file found in the top-level directory of this distribution and at https://github.com/e0404/matRad/LICENSE.md. No part of the matRad project, including this file, may be copied, modified, propagated, or distributed except according to the terms contained in the LICENSE file.

Modules / Subfolders