e0404 · wahln · Apr 5, 2026 · Mar 27, 2026 · Mar 27, 2026 · Mar 27, 2026
diff --git a/docs/overview/about.rst b/docs/overview/about.rst
@@ -8,7 +8,7 @@ About |matRad_logo_header|
 
 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 <http://www.mathworks.com/products/matlab>`_.
 
-This wiki is the main source of information for users working with, and developers contributing to matRad. If you do not already have a local copy of matRad or you want to know how to get started, have a look at the `Quick Start Guide <!>`_. For detailed technical information about matRad and its functions please check out the `Technical Documentation <!>`_.
+This wiki is the main source of information for users working with, and developers contributing to matRad. If you do not already have a local copy of matRad or you want to know how to get started, have a look at the :ref:`Quick Start Guide <quickstart>`. For detailed technical information about matRad and its functions please check out the :ref:`Technical Documentation <techdoc>`.
 
 Please send us an `email <mailto:matrad@dkfz.de?Subject=matRad newsletter>`_ if you want to receive the matRad newsletter that informs about the latest developments on an irregular basis.
 
@@ -41,6 +41,6 @@ If you have any questions or wish to contribute to the development of matRad, yo
 Development team
 ----------------
 
-matRad development is driven by the research group `Radiotherapy Optimization <http://www.dkfz.de/radopt>`_ within the `Division of Medical Physics in Radiation Oncology <http://www.dkfz.de/en/medphys>`_ at the `German Cancer Research Center DKFZ <http://www.dkfz.de>`_ in `Heidelberg <https://goo.gl/maps/BBo2E>`_.
+matRad development is driven by the research group `Radiotherapy Optimization <http://www.dkfz.de/radopt>`_ within the `Division of Medical Physics in Radiation Oncology <http://www.dkfz.de/en/medical-physics-in-radiation-oncology/>`_ at the `German Cancer Research Center DKFZ <http://www.dkfz.de/en/>`_ in `Heidelberg <https://goo.gl/maps/BBo2E>`_.
 
 We are always looking for beta testers that can provide external feedback on our code and developers that would like to take an active role in the future. Do not hesitate and `get in touch <mailto:contact@matrad.org>`__.
diff --git a/docs/overview/cite.rst b/docs/overview/cite.rst
@@ -36,7 +36,7 @@ The main citation for matRad is `Development of the open-source dose calculation
 
 ----
 
-The first paper about matRad was submitted to the `2015 World Congress on Medical Physics & Biomedical Engineering <http://wc2015.org/>`_ by Eduardo Cisternas Jimenéz:
+The first paper about matRad was submitted to the `2015 World Congress on Medical Physics & Biomedical Engineering <https://iupesm.org/wc2015/>`_ by Eduardo Cisternas Jimenéz:
 `matRad – a multi-modality open source 3D treatment planning toolkit <https://github.com/e0404/matRad/wiki/documents/matRad_Full_Paper_Eduardo.pdf>`_.
 
 .. collapse:: matRad conference paper - BibTeX

diff --git a/docs/overview/faq.rst b/docs/overview/faq.rst
@@ -24,15 +24,16 @@ We suggest to visit our `GitHub Discussion Forum <https://github.com/e0404/matRa
 .. admonition:: How can I model custom particle machines in matRad?
     :class: dropdown
 
-    You need to provide your own base data file according to our examples (*proton_Generic.mat*, *carbon_Generic.mat*). More information about the format is summarized on :ref:`this page <basedata_particles>`.
+    You need to provide your own base data file according to our examples (*proton_Generic.mat*, *helium_Generic.mat*, *carbon_Generic.mat*). More information about the format is summarized on :ref:`this page <basedata_particles>`.
 
 
 .. admonition:: How can I use a custom HLUT table in matRad?
     :class: dropdown
 
     matRad has the following procedure for reading HU lookup tables via `matRad_loadHLUT.m <https://github.com/e0404/matRad/blob/c22da7d2a593b7ae56277ce124074c55fe4d45dd/dicom/matRad_loadHLUT.m>`_ during the dose calculation:
-    *  matRad first checks if there is any `.hlut` file provided by the user in the `hlutlibrary <https://github.com/e0404/matRad/tree/master/dicom/hlutLibrary>`_ directory, with the following naming convention: MANUFACTURER-MODEL-ConvolutionKernel_CONVOLUTIONKERNEL_RADIATIONMODALITY.hlut (e.g. Philips-AcQSimCT-ConvolutionKernel-000000_protons.hlut).
-    *  If there is no file with this name available, matRad would use its own default lookup table with the following naming convention: matRad_default_RADIATIONMODALITY.hlut (e.g. `matRad_default.hlut <https://github.com/e0404/matRad/blob/c22da7d2a593b7ae56277ce124074c55fe4d45dd/dicom/hlutLibrary/matRad_default.hlut>`_). This file comprises two columns, first is the HU units and second is the corresponding electron density/stopping power (comments indicated by starting a line with "#" will be omitted).
+        *  First, it checks whether a matching `.hlut` file exists in the internal `matRad/hluts` library using the full naming convention: MANUFACTURER-MODEL-ConvolutionKernel_CONVOLUTIONKERNEL_RADIATIONMODALITY.hlut (e.g. Philips-AcQSimCT-ConvolutionKernel-000000_protons.hlut).
+        *  If not found, matRad checks for a user-provided `.hlut` file in the `userdata/hluts <https://github.com/e0404/matRad/tree/master/userdata/hluts>`_ directory, with the same naming convention.
+        *  If there is no file with this name available, matRad would use its own default lookup table, stored in the `matRad/hluts <https://github.com/e0404/matRad/tree/master/matRad/hluts>`_ directory, with the following naming convention: matRad_default_RADIATIONMODALITY.hlut (e.g. `matRad_default.hlut <https://github.com/e0404/matRad/blob/c22da7d2a593b7ae56277ce124074c55fe4d45dd/dicom/hlutLibrary/matRad_default.hlut>`_). This file comprises two columns, first is the HU units and second is the corresponding electron density/stopping power (comments indicated by starting a line with "#" will be omitted).
 
     Generating your own custom HLUT table can therefore be done in two ways, either making a custom file with the mentioned naming convention or changing the default tables provided by matRad (not recommended).
 
@@ -42,8 +43,8 @@ We suggest to visit our `GitHub Discussion Forum <https://github.com/e0404/matRa
     This issue may be caused by conflicts between MATLAB and window-snapping apps on macOS (Rectangle, BetterTouchTool, Magnet etc.).
     May be remedied by quitting the app or disabling the "Window Snapping " feature then restarting MATLAB.
     For further information refer to :
-    * `matRad Issue #550 <https://github.com/e0404/matRad/issues/550>_`
-    * `MATLAB Answers thread <https://de.mathworks.com/matlabcentral/answers/422244-why-do-buttons-apps-or-the-editor-in-matlab-respond-slowly-or-hang-on-macos>_`
+        * `matRad Issue #550 <https://github.com/e0404/matRad/issues/550>`_
+        * `MATLAB Answers thread <https://de.mathworks.com/matlabcentral/answers/422244-why-do-buttons-apps-or-the-editor-in-matlab-respond-slowly-or-hang-on-macos>`_
 
 .. admonition:: Why are my constraints not being met and coverage is always bad?
     :class: dropdown

diff --git a/docs/quickstart/index.rst b/docs/quickstart/index.rst
@@ -8,7 +8,7 @@
 Quick Start
 ===========
 
-It's the first time you want to use matRad?
+New to matRad? This quick start guide will help you get started.
 
 First, get a local copy of matRad by download or git cloning. Having done that, we recommend you navigate into the folder in Matlab and execute
 

diff --git a/docs/setup/download.rst b/docs/setup/download.rst
@@ -10,7 +10,7 @@
 Download and Install |matRad_logo_header|
 =========================================
 
-To get |matRad_logo| have two options:
+To get |matRad_logo| you have two options:
 
 1. Source Code with Matlab or Octave installation
 -------------------------------------------------
@@ -48,9 +48,7 @@ Steps for installation:
 Patient/Phantom files
 ---------------------
 
-The patient files should be included with the installer and will be installed into the desired location. For Windows, for example, they can be found within the "application" folder of the chosen installation directory. Moreover, we also provide extra links to the open source patient files stored in |matRad_logo|'s native ``*.mat`` format for a `head and neck case <https://github.com/e0404/matRad/blob/master/phantoms/HEAD_AND_NECK.mat>`_, a `liver case <https://github.com/e0404/matRad/blob/master/phantoms/LIVER.mat>`_, a `prostate case <https://github.com/e0404/matRad/blob/master/phantoms/PROSTATE.mat>`_, a `box phantom <https://github.com/e0404/matRad/blob/master/phantoms/BOXPHANTOM.mat>`_, and AAPM's `TG119 phantom <https://github.com/e0404/matRad/blob/master/phantoms/TG119.mat>`_. Otherwise you need to start with a `DICOM import of your own patient data <The-dicom-import>`_.
+The patient files should be included with the installer and will be installed into the desired location. For Windows, for example, they can be found within the "application" folder of the chosen installation directory. Moreover, we also provide extra links to the open source patient files stored in |matRad_logo|'s native ``*.mat`` format for a `head and neck case <https://github.com/e0404/matRad/blob/master/matRad/phantoms/HEAD_AND_NECK.mat>`_, a `liver case <https://github.com/e0404/matRad/blob/master/matRad/phantoms/LIVER.mat>`_, a `prostate case <https://github.com/e0404/matRad/blob/master/matRad/phantoms/PROSTATE.mat>`_, a `box phantom <https://github.com/e0404/matRad/blob/master/matRad/phantoms/BOXPHANTOM.mat>`_, and AAPM's `TG119 phantom <https://github.com/e0404/matRad/blob/master/matRad/phantoms/TG119.mat>`_. Otherwise you need to start with a :ref:`DICOM import of your own patient data <dicomimport>`.
 
-
-An overview of the functions of the |matRad_logo| GUI can be found `here <The-matRad-GUI>`_.
-
-If you want to import patient data, check out `the dicom import functionality <The-dicom-import>`_.
+Once loaded, both built-in and custom phantoms can be visualized in the matRad GUI and navigated by scrolling through the slices.
+An overview of the functions of the |matRad_logo| GUI can be found :ref:`here <guioverview>`.
diff --git a/docs/setup/requirements.rst b/docs/setup/requirements.rst
@@ -19,7 +19,7 @@ Or you can use the standalone application, which does not require a MATLAB insta
 MATLAB
 ^^^^^^
 
-We develop and test matRad mainly with MATLAB version **2022b and later**. Our automatic testing framework via GitHub Actions currently uses R2022b as well as the latest MATLAB version. If you run into a problem with these or any other version, please let us know, but do not expect us to try to stay compatible with all other versions. The main reason for limiting us to these MATLAB versions are incompatibilities in the mex interface to IPOPT (especially on Windows). Other incompatibilities often reveal themselves as missing functions (like ``isstring``, for example).
+We develop and test matRad mainly with MATLAB version **2022b and later**. Our automatic testing framework via GitHub Actions currently uses R2022b as well as the latest MATLAB version. If you encounter problems with these or other MATLAB versions, please let us know. However, we do not guarantee compatibility with all versions. The main reason for limiting us to these MATLAB versions is incompatibilities in the mex interface to IPOPT (especially on Windows). Other incompatibilities often reveal themselves as missing functions (like ``isstring``, for example).
 
 MATLAB Toolboxes
 ^^^^^^^^^^^^^^^^
@@ -34,7 +34,7 @@ Note that compatibility with Octave is not our primary goal, but it is also part
 Standalone
 ^^^^^^^^^^
 
-The standalone is built for Windows, Linux, and Mac. Only the Windows standalone is currently regularly tested.
+The :ref:`standalone <settingup>` is built for Windows, Linux, and Mac. Only the Windows standalone is currently regularly tested.
 Linux and Mac users should be able to run the standalone, but third party tools like IPOPT, ompMC or MCsquare might not run reliably.
 If you find bugs on your operating system, report them to us as `GitHub issue <https://github.com/e0404/matRad/issues>`_.
 
@@ -43,16 +43,16 @@ Operating System
 
 Since we work in the programming environment MATLAB, operating system incompatibilities are not that common. They may arise, in particular, when using mex interfaces. Our precompiled mex interfaces should work on Windows 10 & 11, Ubuntu 18.04 (and later), and MacOS High Sierra. Please let us know if you run into issues, but the first step should always be trying to compile the mex interfaces yourself.
 
-Especially on Mac, there might be substantial issues due to their annoying quarantine system, which prevents the execution of downloaded files. If you run into this problem, you need to remove the respective quarantine flags, especially from mex files you'd like to use.
+Especially on Mac, there might be substantial issues due to their annoying quarantine system, which prevents the execution of downloaded files. If you run into this problem, you need to remove the respective quarantine flags, especially from mex files you intend to use.
 
 Hardware Requirements
 ---------------------
 
-There are no hard minimum requirements to do dose calculation and optimization with matRad. We do treatment planning tutorials also with systems with 2GB RAM, but that means that 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 16GB RAM or more.
+There are no hard minimum requirements to do dose calculation and optimization with matRad. We do treatment planning tutorials also with systems with 2GB RAM, but that means that the cases you are looking at are somewhat small (low spatial resolution, few beams, and rather photon-based plans, as the ion-based plans are more computationally demanding). If you want to do treatment planning at realistic resolutions, we recommend 16GB RAM or more.
 
 If you run into memory problems, you have basically three options:
 
 * Buy more RAM ;)
 * Import your data at low spatial resolution, which is possible during DICOM import. Remember that reducing the resolution by a factor of 2 will reduce memory consumption by a factor of 8! Alternatively or additionally, reduce the resolution of the dose calculation grid using the option ``pln.propDoseCalc.doseGrid.resolution``.
-* Reduce the number of pencil-beams by choosing larger ``bixelWidth`` or, for particles only, the longitudinal spot spacing.
-* Restrict the dose calculation area by specifying tighter lateral cut-off values in `matRad_calcParticleDose (line 211) <https://github.com/e0404/matRad/blob/master/matRad_calcParticleDose.m#L211>`_ and `matRad_calcPhotonDose (line 61) <https://github.com/e0404/matRad/blob/master/matRad_calcPhotonDose.m#L61>`_, respectively. While this induces inaccuracy in the planning process, this might be a viable option for educational purposes.
+* Reduce the number of pencil-beams by choosing larger ``pln.propStf.bixelWidth`` or, for particles only, the longitudinal spot spacing ``pln.propStf.longitudinalSpotSpacing``.
+* Restrict the dose calculation area by specifying tighter lateral cut-off values in :class:`DoseEngines.matRad_ParticlePencilBeamEngineAbstract` and :class:`DoseEngines.matRad_PhotonPencilBeamSVDEngine`, respectively. While this induces inaccuracy in the planning process, this might be a viable option for educational purposes.
diff --git a/matRad/dicom/matRad_loadHLUT.m b/matRad/dicom/matRad_loadHLUT.m
@@ -75,7 +75,8 @@
     end       
 
     if sum(existIx) == 0
-        produce an error to enter catch statment below :)
+        %produce an error to enter catch statment below :)
+        error('No valid custom hlut table found.');
     else
         hlutFileName = hlutFileCell{existIx};
     end