How to execute matRad

(There has been an update to matRad, the changes are not yet worked into this guide)
To execute the matRad script using MATLAB you need to:

1. Open matRad folder in MATLAB
2. Set patient-specific parameters
3. Execute inverse planning
4. Import additional patient data

If you prefer to only use the GUI to execute matRad, check out the [matRadGUI tutorial](How to execute matRadGUI).

## Step 1: Open matRad folder in MATLAB

To use matRad you need to open the matRad folder in MATLAB. Open MATLAB and navigate to the location of the files, if you have cloned the repository it is most likely located in your local Github folder (e.g."C:\Users\username\Documents\GitHub\matRad").

Inside the matRad folder there are several MATLAB-functions used to run matRad, named "matRad_*.m, and *.mat files containing base data and exemplary patient data sets. The main script to run matRad is called "matRad.m". It can be executed section by section.

## Step 2: Set patient-specific parameters In the first section the patient specific parameters have to be set ([see image below](#parametersScreenshot)).:

1. Which patient (-data) should be loaded
2. Which beam angles should be used
3. Which radiation mode should be used

**Selecting a patient** The lines 35-39 in the [screenshot](#parametersScreenshot) show the patient data sets available by default. Un-comment the data set you wish to use. The dose parameters for the different Volumes (min. dose, max. dose, penalties) are set within the patient data set (cst). If you wish you can adjust these parameters before executing matRad. **Selecting beam angles** The lines 45-46 in the [screenshot](#parametersScreenshot) are used to set the gantry and couch angles. Here you can set any angles from 0-359°. Make sure, that you always create pairs of gantry and couch angles, otherwise you won't be able to execute the inverse planning! **Selecting radiation mode** The Radiation mode can be set in line 50 in the [screenshot](#parametersScreenshot). You can choose between photons, protons and carbon. If you decide to use protons or carbon, it is possible to set the lateral spot spacing (line 44). You can als chose between a physical optimization (_'none'_), an optimization of the biological effect (_'effect'_) or an optimization of the RBE-weighted dose (_'RBExD'_) by adjusting the parameter _pln.bioOptimization_ in line 51.

The desired number of fractions can be set in line 52 in the screenshot.

The other parameters set in this section are generated automatically and should not be changed.

_Screenshot of the parameters section_ ## Step 3: Execute inverse planning The matRad.m script can now be executed step by step:

1. load settings
2. initial visualization
3. generate steering file
4. dose calculation
5. inverse planning for IMRT
6. sequencing
7. visualization of the resulting treatment plan
8. calculate DVH

To evaluate a single section you have to "activate" it (left mouse-click inside section) and then use "ctrl + enter" or use right mouse-click -> Evaluate Current Section.

**1. load settings**

Now you can execute the first section. You should see the variables cst, ct and pln in your Worspace.

**2. initial visualization**

After the patient data is loaded you can execute the second Section to open the GUI:

In the GUI you can view the patient CT, change the the plan parameters and adjust the optimization parameters.

The usage of the GUI is explained to more detail in the [matRadGUI tutorial](How to execute matRadGUI). Here we will focus on the "manual" execution of the matRad script. To "manually" change the optimization parameters you can adjust the cst-cell (see cst-cell documentation for more information).

**2. generate steering file**

In this section the steering file (stf) is created and the matRad steering information is stored as a struct.

The Command Window should show you the progress

**3. dose calculation**

In this section the dose influence matrix for the defined beam angles is calculated.

Again the progress should be shown in the Command Window.

**5. Fluence optimization**

In this section the fluence is optimized to find the bixel (photons) or spot (protons/carbon) weights minimizing the objective function.

During this process, the current objective function value is displayed:

Once the objective function is minimized, the dose distribution, using the optimized beam weights, is calculated and visualized:

**6. sequencing**

For photon IMRT the application of a multileaf collimator is necessary. By sequencing the applicable dose distribution can be simulated. The third input of matRad_xiaLeafSequencing(wOpt,stf,7,0) is the number of stratification levels. You can adjust this number to use the number of levels you want.

Once the sequencing is finished, the new dose distribution is calculated and visualized:

**7. calculate DVH**

In this section the Dose-Volume-Histograms are calculated and visualized.

## Step 4: Import additional patient data

This functionality is not yet fully supported