-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
2 changed files
with
139 additions
and
102 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,113 +1,37 @@ | ||
| # PETRIC: PET Rapid Image reconstruction Challenge | ||
| # MaGeZ contribution to the PETRIC reconstruction challenge | ||
|
|
||
| [](https://www.ccpsynerbi.ac.uk/events/petric/) | ||
| [][wiki] | ||
| [][register] | ||
| [][leaderboard] | ||
| [](https://discord.gg/Ayd72Aa4ry) | ||
| This repository contains algorithms developed by the MaGeZ team submitted to | ||
| the [2024 PETRIC reconstruction challenge](https://github.com/SyneRBI/PETRIC). | ||
|
|
||
| ## Participating | ||
| ## Authors | ||
|
|
||
| The organisers will provide GPU-enabled cloud runners which have access to larger private datasets for evaluation. To gain access, you must [register]. The organisers will then create a private team submission repository for you. | ||
| - Matthias Ehrhardt, Univeristy of Bath, United Kingdom | ||
| - Georg Schramm, KU Leuven, Belgium | ||
| - Zeljko Kereta, Univeristy College London, United Kingdom | ||
|
|
||
| [register]: https://github.com/SyneRBI/PETRIC/issues/new/choose | ||
| ## Algorithms | ||
|
|
||
| ## Layout | ||
| ### ALG1 | ||
|
|
||
| The organisers will import your submitted algorithm from `main.py` and then run & evaluate it. | ||
| Please create this file! See the example `main_*.py` files for inspiration. | ||
| Better-preconditioned SVRG based on the works of: | ||
| - R. Twyman et al., "An Investigation of Stochastic Variance Reduction Algorithms for Relative Difference Penalized 3D PET Image Reconstruction," in IEEE TMI, 4, 2023, [link](https://ieeexplore.ieee.org/document/9872020) | ||
| - J. Nuyts et al., ""A concave prior penalizing relative differences for maximum-a-posteriori reconstruction in emission tomography," in IEEE TNS, 49, 2022, [link](https://ieeexplore.ieee.org/document/998681) | ||
|
|
||
| [SIRF](https://github.com/SyneRBI/SIRF), [CIL](https://github.com/TomographicImaging/CIL), and CUDA are already installed (using [synerbi/sirf](https://github.com/synerbi/SIRF-SuperBuild/pkgs/container/sirf)). | ||
| Additional dependencies may be specified via `apt.txt`, `environment.yml`, and/or `requirements.txt`. | ||
| The update can be summarized as: | ||
| $$ | ||
| x^+ = x + \alpha P \tilde{\nabla} f(x) | ||
| $$ | ||
| where $\tilde{\nabla} f(x)$ is the SVRG stochatic gradient of a subset and | ||
| $P$ is diagonal preconditioner calculated as the harmonic mean of of | ||
| $x / A^T 1$ and the diagonal of the Hessian of the RDP, as proposed. | ||
| in Nuyts et al. | ||
| The scalar step size $alpha$ is set to 2 in the first epochs and then decreased | ||
| to 1 and finally to 0.5 in late epochs. | ||
|
|
||
| - (required) `main.py`: must define a `class Submission(cil.optimisation.algorithms.Algorithm)` and a (potentially empty) list of `submission_callbacks`, e.g.: | ||
| + [main_BSREM.py](main_BSREM.py) | ||
| + [main_ISTA.py](main_ISTA.py) | ||
| + [main_OSEM.py](main_OSEM.py) | ||
| - `apt.txt`: passed to `apt install` | ||
| - `environment.yml`: passed to `conda install`, e.g.: | ||
| ### ALG2 | ||
|
|
||
| ```yml | ||
| name: winning-submission | ||
| channels: [conda-forge, pytorch, nvidia] | ||
| dependencies: | ||
| - cupy | ||
| - cuda-version =11.8 | ||
| - pytorch-cuda =11.8 | ||
| - tensorflow-gpu | ||
| - cudatoolkit =11.8.0 | ||
| - pip | ||
| - pip: | ||
| - git+https://github.com/MyResearchGroup/prize-winning-algos | ||
| ``` | ||
| foo bar | ||
|
|
||
| - `requirements.txt`: passed to `pip install`, e.g.: | ||
| ### ALG3 | ||
|
|
||
| ```txt | ||
| cupy-cuda11x | ||
| torch --index-url https://download.pytorch.org/whl/cu118 | ||
| tensorflow[and-cuda] | ||
| git+https://github.com/MyResearchGroup/prize-winning-algos | ||
| ``` | ||
|
|
||
| > [!TIP] | ||
| > You probably should create either an `environment.yml` or `requirements.txt` file (but not both). | ||
|
|
||
| You can also find some example notebooks here which should help you with your development: | ||
| - https://github.com/SyneRBI/SIRF-Contribs/blob/master/src/notebooks/BSREM_illustration.ipynb | ||
|
|
||
| ## Organiser setup | ||
|
|
||
| The organisers will execute (after installing [nvidia-docker](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html) & downloading <https://petric.tomography.stfc.ac.uk/data/> to `/path/to/data`): | ||
|
|
||
| <!-- TODO: use synerbi/sirf:latest-gpu after the next SIRF release --> | ||
|
|
||
| ```sh | ||
| # 1. git clone & cd to your submission repository | ||
| # 2. mount `.` to container `/workdir`: | ||
| docker run --rm -it --gpus all -p 6006:6006 \ | ||
| -v /path/to/data:/mnt/share/petric:ro \ | ||
| -v .:/workdir -w /workdir synerbi/sirf:edge-gpu /bin/bash | ||
| # 3. optionally, conda/pip/apt install environment.yml/requirements.txt/apt.txt | ||
| # 4. install metrics & run your submission | ||
| pip install git+https://github.com/TomographicImaging/Hackathon-000-Stochastic-QualityMetrics | ||
| python petric.py & | ||
| # 5. optionally, serve logs at <http://localhost:6006> | ||
| tensorboard --bind_all --port 6006 --logdir ./output | ||
| ``` | ||
|
|
||
| ## FAQ | ||
|
|
||
| See the [wiki/Home][wiki] and [wiki/FAQ](https://github.com/SyneRBI/PETRIC/wiki/FAQ) for more info. | ||
|
|
||
| > [!TIP] | ||
| > `petric.py` will effectively execute: | ||
| > | ||
| > ```python | ||
| > from main import Submission, submission_callbacks # your submission (`main.py`) | ||
| > from petric import data, metrics # our data & evaluation | ||
| > assert issubclass(Submission, cil.optimisation.algorithms.Algorithm) | ||
| > Submission(data).run(numpy.inf, callbacks=metrics + submission_callbacks) | ||
| > ``` | ||
| <!-- br --> | ||
| > [!WARNING] | ||
| > To avoid timing out (currently 10 min runtime, will likely be increased a bit for the final evaluation after submissions close), please disable any debugging/plotting code before submitting! | ||
| > This includes removing any progress/logging from `submission_callbacks` and any debugging from `Submission.__init__`. | ||
| - `data` to test/train your `Algorithm`s is available at <https://petric.tomography.stfc.ac.uk/data/> and is likely to grow (more info to follow soon) | ||
| + fewer datasets will be available during the submission phase, but more will be available for the final evaluation after submissions close | ||
| + please contact us if you'd like to contribute your own public datasets! | ||
| - `metrics` are calculated by `class QualityMetrics` within `petric.py` | ||
| + this does not contribute to your runtime limit | ||
| + effectively, only `Submission(data).run(np.inf, callbacks=submission_callbacks)` is timed | ||
| - when using the temporary [leaderboard], it is best to: | ||
| + change `Horizontal Axis` to `Relative` | ||
| + untick `Ignore outliers in chart scaling` | ||
| + see [the wiki](https://github.com/SyneRBI/PETRIC/wiki#metrics-and-thresholds) for details | ||
| Any modifications to `petric.py` are ignored. | ||
| [wiki]: https://github.com/SyneRBI/PETRIC/wiki | ||
| [leaderboard]: https://petric.tomography.stfc.ac.uk/leaderboard/?smoothing=0#timeseries&_smoothingWeight=0 | ||
| foo bar |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,113 @@ | ||
| # PETRIC: PET Rapid Image reconstruction Challenge | ||
|
|
||
| [](https://www.ccpsynerbi.ac.uk/events/petric/) | ||
| [][wiki] | ||
| [][register] | ||
| [][leaderboard] | ||
| [](https://discord.gg/Ayd72Aa4ry) | ||
|
|
||
| ## Participating | ||
|
|
||
| The organisers will provide GPU-enabled cloud runners which have access to larger private datasets for evaluation. To gain access, you must [register]. The organisers will then create a private team submission repository for you. | ||
|
|
||
| [register]: https://github.com/SyneRBI/PETRIC/issues/new/choose | ||
|
|
||
| ## Layout | ||
|
|
||
| The organisers will import your submitted algorithm from `main.py` and then run & evaluate it. | ||
| Please create this file! See the example `main_*.py` files for inspiration. | ||
|
|
||
| [SIRF](https://github.com/SyneRBI/SIRF), [CIL](https://github.com/TomographicImaging/CIL), and CUDA are already installed (using [synerbi/sirf](https://github.com/synerbi/SIRF-SuperBuild/pkgs/container/sirf)). | ||
| Additional dependencies may be specified via `apt.txt`, `environment.yml`, and/or `requirements.txt`. | ||
|
|
||
| - (required) `main.py`: must define a `class Submission(cil.optimisation.algorithms.Algorithm)` and a (potentially empty) list of `submission_callbacks`, e.g.: | ||
| + [main_BSREM.py](main_BSREM.py) | ||
| + [main_ISTA.py](main_ISTA.py) | ||
| + [main_OSEM.py](main_OSEM.py) | ||
| - `apt.txt`: passed to `apt install` | ||
| - `environment.yml`: passed to `conda install`, e.g.: | ||
|
|
||
| ```yml | ||
| name: winning-submission | ||
| channels: [conda-forge, pytorch, nvidia] | ||
| dependencies: | ||
| - cupy | ||
| - cuda-version =11.8 | ||
| - pytorch-cuda =11.8 | ||
| - tensorflow-gpu | ||
| - cudatoolkit =11.8.0 | ||
| - pip | ||
| - pip: | ||
| - git+https://github.com/MyResearchGroup/prize-winning-algos | ||
| ``` | ||
| - `requirements.txt`: passed to `pip install`, e.g.: | ||
|
|
||
| ```txt | ||
| cupy-cuda11x | ||
| torch --index-url https://download.pytorch.org/whl/cu118 | ||
| tensorflow[and-cuda] | ||
| git+https://github.com/MyResearchGroup/prize-winning-algos | ||
| ``` | ||
|
|
||
| > [!TIP] | ||
| > You probably should create either an `environment.yml` or `requirements.txt` file (but not both). | ||
|
|
||
| You can also find some example notebooks here which should help you with your development: | ||
| - https://github.com/SyneRBI/SIRF-Contribs/blob/master/src/notebooks/BSREM_illustration.ipynb | ||
|
|
||
| ## Organiser setup | ||
|
|
||
| The organisers will execute (after installing [nvidia-docker](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html) & downloading <https://petric.tomography.stfc.ac.uk/data/> to `/path/to/data`): | ||
|
|
||
| <!-- TODO: use synerbi/sirf:latest-gpu after the next SIRF release --> | ||
|
|
||
| ```sh | ||
| # 1. git clone & cd to your submission repository | ||
| # 2. mount `.` to container `/workdir`: | ||
| docker run --rm -it --gpus all -p 6006:6006 \ | ||
| -v /path/to/data:/mnt/share/petric:ro \ | ||
| -v .:/workdir -w /workdir synerbi/sirf:edge-gpu /bin/bash | ||
| # 3. optionally, conda/pip/apt install environment.yml/requirements.txt/apt.txt | ||
| # 4. install metrics & run your submission | ||
| pip install git+https://github.com/TomographicImaging/Hackathon-000-Stochastic-QualityMetrics | ||
| python petric.py & | ||
| # 5. optionally, serve logs at <http://localhost:6006> | ||
| tensorboard --bind_all --port 6006 --logdir ./output | ||
| ``` | ||
|
|
||
| ## FAQ | ||
|
|
||
| See the [wiki/Home][wiki] and [wiki/FAQ](https://github.com/SyneRBI/PETRIC/wiki/FAQ) for more info. | ||
|
|
||
| > [!TIP] | ||
| > `petric.py` will effectively execute: | ||
| > | ||
| > ```python | ||
| > from main import Submission, submission_callbacks # your submission (`main.py`) | ||
| > from petric import data, metrics # our data & evaluation | ||
| > assert issubclass(Submission, cil.optimisation.algorithms.Algorithm) | ||
| > Submission(data).run(numpy.inf, callbacks=metrics + submission_callbacks) | ||
| > ``` | ||
| <!-- br --> | ||
| > [!WARNING] | ||
| > To avoid timing out (currently 10 min runtime, will likely be increased a bit for the final evaluation after submissions close), please disable any debugging/plotting code before submitting! | ||
| > This includes removing any progress/logging from `submission_callbacks` and any debugging from `Submission.__init__`. | ||
| - `data` to test/train your `Algorithm`s is available at <https://petric.tomography.stfc.ac.uk/data/> and is likely to grow (more info to follow soon) | ||
| + fewer datasets will be available during the submission phase, but more will be available for the final evaluation after submissions close | ||
| + please contact us if you'd like to contribute your own public datasets! | ||
| - `metrics` are calculated by `class QualityMetrics` within `petric.py` | ||
| + this does not contribute to your runtime limit | ||
| + effectively, only `Submission(data).run(np.inf, callbacks=submission_callbacks)` is timed | ||
| - when using the temporary [leaderboard], it is best to: | ||
| + change `Horizontal Axis` to `Relative` | ||
| + untick `Ignore outliers in chart scaling` | ||
| + see [the wiki](https://github.com/SyneRBI/PETRIC/wiki#metrics-and-thresholds) for details | ||
| Any modifications to `petric.py` are ignored. | ||
| [wiki]: https://github.com/SyneRBI/PETRIC/wiki | ||
| [leaderboard]: https://petric.tomography.stfc.ac.uk/leaderboard/?smoothing=0#timeseries&_smoothingWeight=0 |