Donders-Institute · MaCuinea · Mar 31, 2026 · Mar 3, 2026 · Mar 3, 2026 · Mar 3, 2026
diff --git a/.github/workflows/mkdocs.yml b/.github/workflows/mkdocs.yml
@@ -0,0 +1,44 @@
+name: Deploy PRESTUS Docs
+on:
+  push:
+    branches: [ development, main ]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+jobs:
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+
+    - uses: actions/setup-python@v5
+      with:
+        python-version: '3.x'
+
+    - uses: actions/cache@v4
+      with:
+        path: ~/.cache/pip
+        key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt') }}
+
+    - name: Install dependencies
+      run: |
+        pip install -U pip
+        pip install mkdocs mkdocs-material pymdown-extensions
+
+    - name: Build
+      run: mkdocs build --clean
+
+    - uses: actions/upload-pages-artifact@v3
+      with:
+        path: ./site
+
+    - name: Deploy to GitHub Pages
+      id: deployment
+      uses: actions/deploy-pages@v4
diff --git a/.gitignore b/.gitignore
@@ -9,6 +9,12 @@
 *.o[0-9][0-9][0-9][0-9]*
 
 
+######################
+# Ignore mkdocs site #
+######################
+
+site/
+
 ###################
 # Matlab specific #
 ###################
@@ -80,4 +86,5 @@ $RECYCLE.BIN/
 .directory
 .Trash-*
 core.*
-.Rhistory
+.Rhistory
+.claude
diff --git a/README.md b/README.md
@@ -5,6 +5,7 @@
 PRESTUS (PREprocessing & Simulations for Transcranial Ultrasound Stimulation) is an open-source MATLAB toolbox that aims to streamline imaging-informed simulations of Transcanial Ultrasound Stimulation (TUS): from the segmentation of T1-weighted MRI head scans and mapping of medium tissue properties (possibly informed for skull via (pseudo-)CT images) in a simulation grid, to the execution of acoustic and thermal simulations using the widely adopted k-Wave engine. High-performance computing (HPC) support via SLURM and CentOS enables efficient parallelization, and large-scale analyses. Output 3D NifTI images are automatically mapped to a standard template (MNI) space to facilitate group reporting.
 
 Key features include:
+
 - Automated MRI segmentation (using SimNIBS 4 charm) and preprocessing.
 - 2D / 3D grid setup.
 - Multi-layer medium property mapping (water, skin, multi-layer skull, and brain).
@@ -17,55 +18,36 @@ Key features include:
 - 3D NifTI outputs for major reporting metrics (in subject- & MNI-space).
 
 These features make PRESTUS an accessible tool for researchers to plan, validate, and report transcranial ultrasound targeting. 
-The ```documentation``` folder contains evolving documentation of the main workflows and parameters, alongside a tutorial on how to run the integrated pipeline.
-
 A recent overview poster can be found [here](https://jkosciessa.github.io/downloads/2025-FUN25-PRESTUS.pdf).
 
-If you would like to assist the community development of this tool, please consider [CONTRIBUTING](CONTRIBUTING.md).
-
-# Installation
-
-## Donders Institute HPC Cluster
-
-When working on the Donders High-Performance-Computing cluster, PRESTUS and its dependencies (SimNIBS, k-Wave) are already installed. 
-
-Type ``module load simnibs/4.0.0`` (or add the command to your .bashrc so that it is executed automatically once you login) and add ``addpath('/opt/prestus/dev')`` to your matlab path. This will use the most up-to-date version of PRESTUS (i.e., the current development branch). If you want to use an older version you can also use ``addpath('/opt/prestus/0.2.0')``, or older versions. Now you can start matlab R2022b.
+# Documentation
 
-For more information on HPC usage, see [doc_hpc](documentation/doc_hpc.md)
-
-If you want to get started with simulations, you can use the PRESTUS example dataset. This command will copy the dataset to your home directory:
-
-```
-cp /opt/prestus/example_data/PRESTUS_example_data.zip ${HOME}
-```
-
-## Outside the Donders HPC
-
-Follow the [installation guide](documentation/doc_installation.md).
+Please see the [PRESTUS documentation](https://donders-institute.github.io/PRESTUS/).
 
 # Reference
 
-Chetverikov, A.\*, Kosciessa, J. Q.\*, Cornelissen, M., Carpino, E., van der Zee, K., & Verhagen, L. (2025). PRESTUS (0.4.0). Zenodo. https://doi.org/10.5281/zenodo.15965832
+If you use this tool for publications, please cite:
+Kosciessa, J. Q.\*, Chetverikov, A.\*, Cornelissen, M., van der Zee, K., Carpino, E., Wimmers, M., Adelhöfer, N., Meijer, S., & Verhagen, L. (2026). PRESTUS (0.5.0). Zenodo. https://doi.org/10.5281/zenodo.15095860
 
 # Contributors
 
 [![Contributors](https://img.shields.io/github/contributors/Donders-Institute/PRESTUS.svg?color=00B4D8&style=flat-square)](https://github.com/Donders-Institute/PRESTUS/graphs/contributors)
-[![All Contributors](https://img.shields.io/github/all-contributors/Donders-Institute/PRESTUS?color=00B4D8&style=flat-square)](#contributors)
 <!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
 <!-- prettier-ignore-start -->
 <!-- markdownlint-disable -->
 <table>
   <tbody>
     <tr>
-      <td align="center" valign="top" width="14.28%"><a href="http://juliankosciessa.eu"><img src="https://avatars.githubusercontent.com/u/40263608?v=4?s=100" width="100px;" alt="Julian Kosciessa"/><br /><sub><b>Julian Kosciessa</b></sub></a><br /><a href="#code-jkosciessa" title="Code">💻</a> <a href="#ideas-jkosciessa" title="Ideas, Planning, & Feedback">🤔</a> <a href="#tutorial-jkosciessa" title="Tutorials">✅</a> <a href="#maintenance-jkosciessa" title="Maintenance">🚧</a> <a href="#bug-jkosciessa" title="Bug reports">🐛</a> <a href="#doc-jkosciessa" title="Documentation">📖</a></td>
-      <td align="center" valign="top" width="14.28%"><a href="http://andreychetverikov.org"><img src="https://avatars.githubusercontent.com/u/1465806?v=4?s=100" width="100px;" alt="Andrey Chetverikov"/><br /><sub><b>Andrey Chetverikov</b></sub></a><br /><a href="#code-achetverikov" title="Code">💻</a> <a href="#ideas-achetverikov" title="Ideas, Planning, & Feedback">🤔</a> <a href="#tutorial-achetverikov" title="Tutorials">✅</a></td>
-      <td align="center" valign="top" width="14.28%"><a href="https://github.com/KTZ228"><img src="https://avatars.githubusercontent.com/u/51954604?v=4?s=100" width="100px;" alt="Kenneth van der Zee"/><br /><sub><b>Kenneth van der Zee</b></sub></a><br /><a href="#code-KTZ228" title="Code">💻</a> <a href="#ideas-KTZ228" title="Ideas, Planning, & Feedback">🤔</a> <a href="#maintenance-KTZ228" title="Maintenance">🚧</a> <a href="#bug-KTZ228" title="Bug reports">🐛</a></td>
-      <td align="center" valign="top" width="14.28%"><a href="https://github.com/MaCuinea"><img src="https://avatars.githubusercontent.com/u/134381864?v=4?s=100" width="100px;" alt="Margely Cornelissen"/><br /><sub><b>Margely Cornelissen</b></sub></a><br /><a href="#code-MaCuinea" title="Code">💻</a> <a href="#maintenance-MaCuinea" title="Maintenance">🚧</a> <a href="#tutorial-MaCuinea" title="Tutorials">✅</a> <a href="#bug-MaCuinea" title="Bug reports">🐛</a></td>
-      <td align="center" valign="top" width="14.28%"><a href="https://github.com/eleonoracarpino"><img src="https://avatars.githubusercontent.com/u/123380299?v=4?s=100" width="100px;" alt="Eleonora Carpino"/><br /><sub><b>Eleonora Carpino</b></sub></a><br /><a href="#code-eleonoracarpino" title="Code">💻</a> <a href="#ideas-eleonoracarpino" title="Ideas, Planning, & Feedback">🤔</a></td>
-      <td align="center" valign="top" width="14.28%"><a href="https://github.com/mekman"><img src="https://avatars.githubusercontent.com/u/139282?v=4?s=100" width="100px;" alt="Matthias Ekman"/><br /><sub><b>Matthias Ekman</b></sub></a><br /><a href="#bug-mekman" title="Bug reports">🐛</a></td>
-      <td align="center" valign="top" width="14.28%"><a href="https://github.com/sirmrmarty"><img src="https://avatars.githubusercontent.com/u/140894211?v=4?s=100" width="100px;" alt="Martin Wimmers"/><br /><sub><b>Martin Wimmers</b></sub></a><br /><a href="#tutorial-sirmrmarty" title="Tutorials">✅</a> <a href="#bug-sirmrmarty" title="Bug reports">🐛</a></td>
-      <td align="center" valign="top" width="14.28%"><a href="https://github.com/neurodream"><img src="https://avatars.githubusercontent.com/u/117816806?v=4?s=100" width="100px;" alt="Nico Adelhöfer"/><br /><sub><b>Nico Adelhöfer</b></sub></a><br /><a href="#ideas-neurodream" title="Ideas, Planning, & Feedback">🤔</a></td>
-      <td align="center" valign="top" width="14.28%"><a href="http://lennartverhagen.com"><img src="https://avatars.githubusercontent.com/u/12236166?v=4?s=100" width="100px;" alt="Lennart Verhagen"/><br /><sub><b>Lennart Verhagen</b></sub></a><br /><a href="#ideas-lennartverhagen" title="Ideas, Planning, & Feedback">🤔</a></td>
+      <td align="center" valign="top" width="10%"><a href="http://juliankosciessa.eu"><img src="https://avatars.githubusercontent.com/u/40263608?v=4?s=100" width="100px;" alt="Julian Kosciessa"/><br /><sub><b>Julian Kosciessa</b></sub></a><br /><a href="#code-jkosciessa" title="Code">💻</a> <a href="#ideas-jkosciessa" title="Ideas, Planning, & Feedback">🤔</a> <a href="#tutorial-jkosciessa" title="Tutorials">✅</a> <a href="#maintenance-jkosciessa" title="Maintenance">🚧</a> <a href="#bug-jkosciessa" title="Bug reports">🐛</a> <a href="#doc-jkosciessa" title="Documentation">📖</a></td>
+      <td align="center" valign="top" width="10%"><a href="http://andreychetverikov.org"><img src="https://avatars.githubusercontent.com/u/1465806?v=4?s=100" width="100px;" alt="Andrey Chetverikov"/><br /><sub><b>Andrey Chetverikov</b></sub></a><br /><a href="#code-achetverikov" title="Code">💻</a> <a href="#ideas-achetverikov" title="Ideas, Planning, & Feedback">🤔</a> <a href="#tutorial-achetverikov" title="Tutorials">✅</a></td>
+      <td align="center" valign="top" width="10%"><a href="https://github.com/KTZ228"><img src="https://avatars.githubusercontent.com/u/51954604?v=4?s=100" width="100px;" alt="Kenneth van der Zee"/><br /><sub><b>Kenneth van der Zee</b></sub></a><br /><a href="#code-KTZ228" title="Code">💻</a> <a href="#ideas-KTZ228" title="Ideas, Planning, & Feedback">🤔</a> <a href="#maintenance-KTZ228" title="Maintenance">🚧</a> <a href="#bug-KTZ228" title="Bug reports">🐛</a></td>
+      <td align="center" valign="top" width="10%"><a href="https://github.com/MaCuinea"><img src="https://avatars.githubusercontent.com/u/134381864?v=4?s=100" width="100px;" alt="Margely Cornelissen"/><br /><sub><b>Margely Cornelissen</b></sub></a><br /><a href="#code-MaCuinea" title="Code">💻</a> <a href="#maintenance-MaCuinea" title="Maintenance">🚧</a> <a href="#tutorial-MaCuinea" title="Tutorials">✅</a> <a href="#bug-MaCuinea" title="Bug reports">🐛</a></td>
+      <td align="center" valign="top" width="10%"><a href="https://github.com/eleonoracarpino"><img src="https://avatars.githubusercontent.com/u/123380299?v=4?s=100" width="100px;" alt="Eleonora Carpino"/><br /><sub><b>Eleonora Carpino</b></sub></a><br /><a href="#code-eleonoracarpino" title="Code">💻</a> <a href="#ideas-eleonoracarpino" title="Ideas, Planning, & Feedback">🤔</a></td>
+      <td align="center" valign="top" width="10%"><a href="https://github.com/sirmrmarty"><img src="https://avatars.githubusercontent.com/u/140894211?v=4?s=100" width="100px;" alt="Martin Wimmers"/><br /><sub><b>Martin Wimmers</b></sub></a><br /><a href="#code-sirmrmarty" title="Code">💻</a> <a href="#tutorial-sirmrmarty" title="Tutorials">✅</a> <a href="#bug-sirmrmarty" title="Bug reports">🐛</a></td>
+      <td align="center" valign="top" width="10%"><a href="https://github.com/neurodream"><img src="https://avatars.githubusercontent.com/u/117816806?v=4?s=100" width="100px;" alt="Nico Adelhöfer"/><br /><sub><b>Nico Adelhöfer</b></sub></a><br /><a href="#code-neurodream" title="Code">💻</a> <a href="#ideas-neurodream" title="Ideas, Planning, & Feedback">🤔</a></td>
+      <td align="center" valign="top" width="10%"><a href="https://github.com/meijer-s"><img src="https://avatars.githubusercontent.com/u/243970592?v=4&s=100" width="100px;" alt="meijer-s"/><br /><sub><b>meijer-s</b></sub></a><br /><a href="#code-meijer-s" title="Code">💻</a> <a href="#ideas-meijer-s" title="Ideas, Planning, & Feedback">🤔</a></td>
+      <td align="center" valign="top" width="10%"><a href="https://github.com/mekman"><img src="https://avatars.githubusercontent.com/u/139282?v=4?s=100" width="100px;" alt="Matthias Ekman"/><br /><sub><b>Matthias Ekman</b></sub></a><br /><a href="#bug-mekman" title="Bug reports">🐛</a></td>
+      <td align="center" valign="top" width="10%"><a href="http://lennartverhagen.com"><img src="https://avatars.githubusercontent.com/u/12236166?v=4?s=100" width="100px;" alt="Lennart Verhagen"/><br /><sub><b>Lennart Verhagen</b></sub></a><br /><a href="#ideas-lennartverhagen" title="Ideas, Planning, & Feedback">🤔</a></td>
     </tr>
   </tbody>
 </table>
@@ -75,6 +57,8 @@ Chetverikov, A.\*, Kosciessa, J. Q.\*, Cornelissen, M., Carpino, E., van der Zee
 
 <!-- ALL-CONTRIBUTORS-LIST:END -->
 
+If you would like to assist the community development of this tool, please consider [CONTRIBUTING](CONTRIBUTING.md).
+
 # License
 
 Released under GNU General Public License v3.0 (see LICENSE).

diff --git a/configs/calibration_config.yaml b/configs/calibration_config.yaml
@@ -1,26 +1,12 @@
 # The configuration is structured using YAML (https://yaml.org/). Note that YAML uses spaces, not tabs, for identation.
 
-  # Simulation paths (note: specific for calibration) [Change to your directories...]
+  ## Parameters for standalone calibration (using Donders equipment)
+
+  # Simulation paths (no defaults; change to your directories...)
   path_input_axial: '//home/common/matlab/PRESTUS/Axial_profiles/'  # Base path for axial profiles
-  path_input_phase: '//home/common/matlab/PRESTUS/Phase_tables/'  # Base path for phase data
-  path_output: '/project/2425122.01/calibration/data/calibration/'  # Folder path for saving simulation results
-  path_output_profiles: '/project/2425122.01/calibration/data/PRESTUS_virtual_parameters/'  # Folder for saving optimized profile data
-  filename_calibrated_CSV: '' # Filename of calibrated CSV data (default: standalone script generates name based on equipment)
+  path_input_phase: '//home/common/matlab/PRESTUS/Phase_tables/'    # Base path for phase data
 
-  # Internal settings
-
-  submit_medium: 'slurm'                    # Simulation submit mode: matlab (debug; doesn't overwrite; force cpu mode), slurm (recommended), or qsub
-  save_in_calibration_folder: true          # Boolean flag to save outputs in general output folder or simulation-specific folder. If TRUE, simulations are run in calibration output directory; results are appended to existing calibration for this equipment instead of overwritten.
-  skip_front_peak_mm: 10                    # Distance to ignore from the start of axial profile (mm) to avoid near-field peak artifacts
-  optmethod: 'FEXminimize'                  # 'FEXminimize' (open source subtoolbox) | 'GlobalSearch' (MATLAB's Global Optimization Toolbox)
-  weights: 1                                # Weighting of the original profile during fitting (towards 0 = narrower Gaussian; 1 = equal weighting)
-  seed: 251024                              # Random seed for optimization
-  addEPdistance: 1                          # Append distance from transducer bowl to exit plane (if zero point in provided profiles = exit plane, != transducer bowl)
-  interpolateToEP: 1                        # Interpolate values between bowl and exit plane [default: add initial value in empirical measurements]
-  force_kwavearray: 1                       # Force to run free-water simulations with kwavearray?
-  axisymmetric2D: 0                         # [EXPERIMENTAL; default: 0] Convert (default; depends on study config) 3D free-water simulation setup to 2D axisymmetry for efficiency
-
-  # List combinations of setups (e.g., transducer-TPO) and calibration targets.
+  # List combinations of setups (e.g., transducer-TPO) and calibration targets (no defaults)
   # Every [] specification will be performed for the corresponding (ordered) index equipment combination. 
   # Example: all foci within the first [] will be executed for the first equipment combination. 
   # If array is empty ([]), all focal depths of available characterization data will be used.
@@ -35,12 +21,27 @@
     - [35, 83]
     - [35, 83]
 
-  # Example for multiple equipment-depth-intensity combinations:
-  # combinations:
-  #   - IS_PCD15287_01001_IGT_128_ch_comb_10_ch
-  #   - IS_PCD15287_01002_IGT_128_ch_comb_10_ch
-  # focal_depths_wrt_exit_plane:
-  #   - [85]
-  #   - [30, 50]
-  # desired_intensities: 
-  #   - [30]
+  # For curved transducers: are distances in empirical profiles provided from the exit plane?
+  add_FDO: 1   # Append Focal Distance Offset (distance from transducer bowl to exit plane). Use if zero point in provided profiles = exit plane, != transducer bowl.
+
+  ## Parameters for calibration function
+
+  # I/O
+  path_output: '/project/2425122.01/calibration/data/calibration/'                          # Folder for saving simulation results [Change to your directories...]
+  path_output_profiles: '/project/2425122.01/calibration/data/PRESTUS_virtual_parameters/'  # Folder for saving optimized profile data [Change to your directories...]
+  save_in_calibration_folder: true  # Boolean flag to save outputs in general output folder or simulation-specific folder (`parameters.calibration.path_output`). If TRUE, simulations are run in calibration output directory; results are appended to existing calibration for this equipment instead of overwritten.
+  filename_calibrated_CSV: ''       # Filename of calibrated CSV data (default: standalone script generates name based on equipment)
+
+  # Simulation submission overrrides
+  force_kwavearray: 1               # Force to run free-water simulations with kwavearray?
+  axisymmetric2D: 0                 # Convert (default; depends on study config) 3D free-water simulation setup to 2D axisymmetry for efficiency
+
+  # Optimization
+  opt_method: 'FEXminimize'         # 'FEXminimize' (open source subtoolbox) | 'GlobalSearch' (MATLAB's Global Optimization Toolbox)
+  opt_weights: 0                    # Weighting of the original profile during fitting (0 = uniform weighting, >1 increasingly narrow Gaussian FWHM)
+  opt_seed: 251024                  # Random seed for optimization
+  opt_upper_velocity: 0.2           # Upper velocity in global search
+  fit_velocity_to_intensity: true   # Correct velocity after global search to match desired peak intensity
+
+  # Other
+  skip_front_peak_mm: 10            # Distance to ignore from the start of axial profile (mm) to avoid near-field peak artifacts in reporting