From d09c74fe312fa0977a6e03654e069490aa3c6f4a Mon Sep 17 00:00:00 2001 From: s742o Date: Fri, 27 Mar 2026 15:52:21 +0100 Subject: [PATCH 1/5] Documentation review #1 - Links and ref fixing - Some rephrasing done --- docs/overview/about.rst | 4 ++-- docs/overview/cite.rst | 2 +- docs/overview/faq.rst | 10 +++++----- docs/setup/download.rst | 2 +- docs/setup/requirements.rst | 12 ++++++------ matRad/dicom/matRad_loadHLUT.m | 3 ++- 6 files changed, 17 insertions(+), 16 deletions(-) diff --git a/docs/overview/about.rst b/docs/overview/about.rst index 3ccfb003e..c189451a2 100644 --- 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 `_. -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 `. For detailed technical information about matRad and its functions please check out the :ref:`Technical Documentation `. Please send us an `email `_ 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 `_ within the `Division of Medical Physics in Radiation Oncology `_ at the `German Cancer Research Center DKFZ `_ in `Heidelberg `_. +matRad development is driven by the research group `Radiotherapy Optimization `_ within the `Division of Medical Physics in Radiation Oncology `_ at the `German Cancer Research Center DKFZ `_ in `Heidelberg `_. 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 `__. diff --git a/docs/overview/cite.rst b/docs/overview/cite.rst index 123396dc9..178689e33 100644 --- 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 `_ by Eduardo Cisternas Jimenéz: +The first paper about matRad was submitted to the `2015 World Congress on Medical Physics & Biomedical Engineering `_ by Eduardo Cisternas Jimenéz: `matRad – a multi-modality open source 3D treatment planning toolkit `_. .. collapse:: matRad conference paper - BibTeX diff --git a/docs/overview/faq.rst b/docs/overview/faq.rst index 2e58206e2..32fd8b298 100644 --- a/docs/overview/faq.rst +++ b/docs/overview/faq.rst @@ -24,15 +24,15 @@ We suggest to visit our `GitHub Discussion Forum `. + 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 `. .. 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 `_ during the dose calculation: - * matRad first checks if there is any `.hlut` file provided by the user in the `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 `_). 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). + * matRad first checks if there is any `.hlut` file provided by the user in the `userdata/hluts `_ 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, stored in the `matRad/hluts `_ directory, with the following naming convention: matRad_default_RADIATIONMODALITY.hlut (e.g. `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 +42,8 @@ We suggest to visit our `GitHub Discussion Forum _` - * `MATLAB Answers thread _` + * `matRad Issue #550 `_ + * `MATLAB Answers thread `_ .. admonition:: Why are my constraints not being met and coverage is always bad? :class: dropdown diff --git a/docs/setup/download.rst b/docs/setup/download.rst index 30f52a666..76fd32e65 100644 --- 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 ------------------------------------------------- diff --git a/docs/setup/requirements.rst b/docs/setup/requirements.rst index 441b205fd..391e5c092 100644 --- 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 ` 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 `_. @@ -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 the built-it 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) `_ and `matRad_calcPhotonDose (line 61) `_, respectively. While this induces inaccuracy in the planning process, this might be a viable option for educational purposes. \ No newline at end of file +* 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 `matRad_ParticlePencilBeamEngineAbstract (line 472) `_ and `matRad_PhotonPencilBeamSVDEngine (line 37) `_, respectively. While this induces inaccuracy in the planning process, this might be a viable option for educational purposes. \ No newline at end of file diff --git a/matRad/dicom/matRad_loadHLUT.m b/matRad/dicom/matRad_loadHLUT.m index 23acd8767..7ab6a6ccd 100644 --- 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 From 910047bb34b80bca1fa7526d9e456a3dd1004a07 Mon Sep 17 00:00:00 2001 From: s742o Date: Fri, 27 Mar 2026 16:26:11 +0100 Subject: [PATCH 2/5] Part of Documentation review #1 --- docs/quickstart/index.rst | 2 +- docs/setup/download.rst | 8 +++----- 2 files changed, 4 insertions(+), 6 deletions(-) diff --git a/docs/quickstart/index.rst b/docs/quickstart/index.rst index 100af51fe..05a9483d1 100644 --- 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 index 76fd32e65..cf88bf76e 100644 --- a/docs/setup/download.rst +++ b/docs/setup/download.rst @@ -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 `_, a `liver case `_, a `prostate case `_, a `box phantom `_, and AAPM's `TG119 phantom `_. Otherwise you need to start with a `DICOM import of your own patient data `_. +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 `_, a `liver case `_, a `prostate case `_, a `box phantom `_, and AAPM's `TG119 phantom `_. Otherwise you need to start with a :ref:`DICOM import of your own patient data `. - -An overview of the functions of the |matRad_logo| GUI can be found `here `_. - -If you want to import patient data, check out `the dicom import functionality `_. \ No newline at end of file +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 `. \ No newline at end of file From 17c540ff1d664c1aaa2f93079f1421dbb771cdda Mon Sep 17 00:00:00 2001 From: s742o Date: Fri, 27 Mar 2026 17:26:50 +0100 Subject: [PATCH 3/5] Documentation review #2 --- docs/setup/requirements.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/setup/requirements.rst b/docs/setup/requirements.rst index 391e5c092..d6849af83 100644 --- a/docs/setup/requirements.rst +++ b/docs/setup/requirements.rst @@ -43,7 +43,7 @@ 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 the built-it 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. +Especially on Mac, there might be substantial issues due to their extremely 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 --------------------- From b37f7d48acd9ffa81c0e9297b813126f770c236c Mon Sep 17 00:00:00 2001 From: s742o Date: Mon, 30 Mar 2026 10:25:52 +0200 Subject: [PATCH 4/5] Documentation review #1: corrections --- docs/overview/faq.rst | 3 ++- docs/setup/requirements.rst | 2 +- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/overview/faq.rst b/docs/overview/faq.rst index 32fd8b298..dc193d376 100644 --- a/docs/overview/faq.rst +++ b/docs/overview/faq.rst @@ -31,7 +31,8 @@ We suggest to visit our `GitHub Discussion Forum `_ during the dose calculation: - * matRad first checks if there is any `.hlut` file provided by the user in the `userdata/hluts `_ directory, with the following naming convention: MANUFACTURER-MODEL-ConvolutionKernel_CONVOLUTIONKERNEL_RADIATIONMODALITY.hlut (e.g. Philips-AcQSimCT-ConvolutionKernel-000000_protons.hlut). + * 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 `_ 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 `_ directory, with the following naming convention: matRad_default_RADIATIONMODALITY.hlut (e.g. `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). diff --git a/docs/setup/requirements.rst b/docs/setup/requirements.rst index d6849af83..cf224fcab 100644 --- a/docs/setup/requirements.rst +++ b/docs/setup/requirements.rst @@ -43,7 +43,7 @@ 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 extremely 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. +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 --------------------- From 651106e342757beece8934bd18cd3cc2dfdb4d54 Mon Sep 17 00:00:00 2001 From: s742o Date: Thu, 2 Apr 2026 16:45:16 +0200 Subject: [PATCH 5/5] Minimum requirements: referencing to class fixed --- docs/setup/requirements.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/setup/requirements.rst b/docs/setup/requirements.rst index cf224fcab..8fec76841 100644 --- a/docs/setup/requirements.rst +++ b/docs/setup/requirements.rst @@ -55,4 +55,4 @@ 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 ``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 `matRad_ParticlePencilBeamEngineAbstract (line 472) `_ and `matRad_PhotonPencilBeamSVDEngine (line 37) `_, respectively. While this induces inaccuracy in the planning process, this might be a viable option for educational purposes. \ No newline at end of file +* 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. \ No newline at end of file