21 October 2024
Thessaloniki
Europe/Athens timezone

matRad Installation

The hands-on experience provides the means to handle details on planning the best treatement for particular cases and confronts participants with choises that have to be made regarding different modality treatments provided by matRad, namely, photons, protons and carbon-ions.

matRad is an open-source software for radiation treatment planning of intensity-modulated photon, proton, and carbon ion therapy. matRad is developed for educational and research purposes. It is entirely written in MATLAB.

Participants that wish to fully exploit matRad and take full advantage of the hands-on sessions are expected to have MATLAB licenses obtained via their academic institutions.

However, for those who cannot obtain MATLAB licenses, different options are provided for the matRad installation. Specifically, a standalone version of matRad executable can be used by participants  to perform the hands-on exercises in full, while more features and flexibility are possible if one has access to a MATLAB licenses. Participants are invited to check the detailed instructions below.   

It is best that the installation is already done beforehand following the instructions below and the recordings here 

If a certificate is required, it is necessary to submit the results of the hands-on by email to: hitm.school@cern.ch .

For any issues related to the Treatment Planning Workshop please contact: yiota.foka@cern.ch and/or n.wahl@dkfz-heidelberg.de

Software Installation

Minimum requirements

There are no hard minimum requirements to do dose calculation and optimization with matRad. Treatment planning tutorials can be done with systems with 2GB RAM but the cases you are looking at are somewhat small (low spatial resolution, few beams, rather no particles). If you want to do treatment planning at realistic resolutions, we recommend 8GB RAM or more. More information can be found at https://github.com/e0404/matRad/wiki/Minimum-System-Requirements.

matRad Installation step by step

There are two ways to install matRad. The first (and suggested) one is to use the Matlab source code from within the MATLAB programming environment. It requires a local MATLAB installation. The second way is to use a standalone that installs a runtime that allows the usage of matRad without a valid MATLAB license. However, the functionality is limited to the user interface and thus one would not be able to take part in coding exercises.

- 1st way (recommended): Source Code to use with valid MATLAB installation

You can also work with the current source code when you have Matlab installed (even with Octave, but only without a GUI), which you can get from GitHub here:

https://github.com/e0404/matRad/releases/tag/v2.10.1

There, just download the provided *.zip or *.tar.gz file and extract it to a folder on your hard drive that can be accessed from Matlab.

For completeness and for the ones interested to go deeper, there's also detailed documentation, targeted at people who work with the software (Matlab source code). It can be found at https://github.com/e0404/matRad/wiki explaining a lot about the workflow and the underlying principles.

- 2nd way: matRad Installation as standalone

VIDEO: MatRad Installation Video (Installation_MatRad file)

1. To download matRad, download the installer for your system from https://github.com/e0404/matRad/releases/tag/v2.10.1

2. Run the respective installer for your system

  • Windows: Run the downloaded executable installer
  • Linux: Run the executable install script. Make sure that the *.install file has executable permissions.
  • Mac: Here we provide a dmg containing the installer (Since the installer is not Apple-certified, you might explicitly launch it from the terminal or by right-clicking).

After that, you should be guided through the installation process:

 

Note that the installers will want to download the "Matlab Runtime" from Mathworks in the process. The runtime is quite large (~2GB) and is required to run compiled deployed applications written in Matlab.

3. Run matRad:

Windows: Just like with every other program, you should have a desktop icon.

Linux & Mac: To start matRad, you can use the provided run_matRad.sh script from the terminal. It requires one argument which gives the path to the installed Matlab-Runtime. Refer to the readme_linux.txt and readme_mac.txt in your installation directory for more information.

Patient/Phantom files

The patient files should be included with the installer and will be installed in the desired location. For Windows, for example, they can be found within the "application" folder of the chosen installation directory.

We also provide an extra link for the patient files: Download here!