Skip to content

SyneRBI/PETRIC

Repository files navigation

PETRIC: PET Rapid Image reconstruction Challenge

website wiki register leaderboard discord

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.

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, CIL, and CUDA are already installed (using synerbi/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.:

  • apt.txt: passed to apt install

  • environment.yml: passed to conda install, e.g.:

    name: winning-submission
    channels: [conda-forge, nvidia]
    dependencies:
    - cupy
    - cuda-version =11.8
    - pip
    - pip:
      - git+https://github.com/MyResearchGroup/prize-winning-algos
  • requirements.txt: passed to pip install, e.g.:

    cupy-cuda11x
    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:

Organiser setup

The organisers will execute (after installing nvidia-docker & downloading https://petric.tomography.stfc.ac.uk/data/ to /path/to/data):

# 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. install metrics & GPU libraries
conda install monai tensorboard tensorboardx jupytext cudatoolkit=11.8
pip uninstall torch # monai installs pytorch (CPU), so remove it
pip install tensorflow[and-cuda]==2.14  # last to support cu118
pip install torch --index-url https://download.pytorch.org/whl/cu118
pip install git+https://github.com/TomographicImaging/Hackathon-000-Stochastic-QualityMetrics
# 4. optionally, conda/pip/apt install environment.yml/requirements.txt/apt.txt
# 5. run your submission
python petric.py &
# 6. optionally, serve logs at <http://localhost:6006>
tensorboard --bind_all --port 6006 --logdir ./output

FAQ

See the wiki/Home and wiki/FAQ for more info.

Tip

petric.py will effectively execute:

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)

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 Algorithms 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 for details

Any modifications to petric.py are ignored.