Merge branch 'main' into fista

.github/dependabot.yml

@@ -0,0 +1,10 @@
+version: 2
+updates:
+
+- package-ecosystem: "github-actions"
+  directory: "/"
+  schedule:
+    interval: "daily"
+  groups:
+    all-actions:
+      patterns: [ "*" ]

.github/workflows/docker.yml

@@ -4,10 +4,14 @@ on:
   pull_request:
     paths-ignore:
       - "**.md"
+  push:
+    branches:
+      - main
+
 
 jobs:
   get_dockerfiles:
-    name: Get list of dockerfiles for different containers
+    name: Get list of Docker files for different containers
     runs-on: ubuntu-latest
     outputs:
       docker_toml: ${{ steps.filter.outputs.docker_toml }}
@@ -24,14 +28,16 @@ jobs:
           filters: |
             docker_toml:
               - 'docker/*'
-              - 'pyproject.toml'
-              - '/.github/docker.yml'
+              - '.github/workflows/docker.yml'
 
-      - run: |
+      - name: Do we need to do something?
+        run: |
+          echo "Push to main? ${{ github.event_name }} "
           echo "Rebuild containers? ${{ steps.filter.outputs.docker_toml }}"
 
-      - id: set-matrix
-        if: steps.filter.outputs.docker_toml == 'true'
+      - name: Define docker image names
+        id: set-matrix
+        if: steps.filter.outputs.docker_toml == 'true' || github.event_name == 'push'
         run: |
           cd ./docker/
           ls
@@ -43,15 +49,15 @@ jobs:
           echo "imagenames=$imagenames" >> $GITHUB_OUTPUT
 
       - name: Dockerfile overview
-        if: steps.filter.outputs.docker_toml == 'true'
+        if: steps.filter.outputs.docker_toml == 'true' || github.event_name == 'push'
         run: |
           echo "final list of dockerfiles: ${{ steps.set-matrix.outputs.dockerfiles }}"
           echo "final list of images: ${{ steps.set-matrix.outputs.imagenames }}"
 
   push_test:
     name: Create test images and push to GCR
     needs: get_dockerfiles
-    if: ${{ needs.get_dockerfiles.outputs.docker_toml == 'true' }}
+    if: needs.get_dockerfiles.outputs.docker_toml == 'true' || github.event_name == 'push'
     runs-on: ubuntu-latest
     permissions:
       packages: write
@@ -68,6 +74,9 @@ jobs:
           dockerfile=${{ matrix.dockerfile }}
           echo "image_name=${dockerfile/Dockerfile_/ghcr.io/ptb-mr/mrpro_}" >> $GITHUB_OUTPUT
 
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
       - name: Login to GitHub Packages
         uses: docker/login-action@v3
         with:
@@ -76,7 +85,7 @@ jobs:
           password: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Build and push Docker image
-        uses: docker/build-push-action@v5
+        uses: docker/build-push-action@v6
         with:
           context: ./docker
           file: ./docker/${{ matrix.dockerfile }}
@@ -86,7 +95,7 @@ jobs:
   test:
     name: Test docker containers
     needs: [get_dockerfiles, push_test]
-    if: ${{ needs.get_dockerfiles.outputs.docker_toml == 'true' }}
+    if: needs.get_dockerfiles.outputs.docker_toml == 'true' || github.event_name == 'push'
     runs-on: ubuntu-latest
     permissions:
       pull-requests: write
@@ -114,9 +123,9 @@ jobs:
           pytest -n 4 -m "not cuda"
 
   push_latest:
-    name: Create latest images and push to GCR
+    name: Pull latest images and push to GCR with new tag
     needs: [get_dockerfiles, test]
-    if: ${{ needs.get_dockerfiles.outputs.docker_toml == 'true' }}
+    if: needs.get_dockerfiles.outputs.docker_toml == 'true' || github.event_name == 'push'
     runs-on: ubuntu-latest
     permissions:
       packages: write

.github/workflows/docs.yml

@@ -44,7 +44,7 @@ jobs:
           done
 
       - name: Check if any notebooks have been changed
-        uses: tj-actions/verify-changed-files@v19
+        uses: tj-actions/verify-changed-files@v20
         id: verify-changed-notebooks
         with:
           files: ./examples/*.ipynb
@@ -184,7 +184,7 @@ jobs:
         run: sphinx-build -b html ./docs/source ./docs/build/html
 
       - name: Deploy to GitHub Pages
-        uses: peaceiris/actions-gh-pages@v3
+        uses: peaceiris/actions-gh-pages@v4
         with:
           publish_branch: github-pages
           github_token: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/pytest.yml

@@ -2,8 +2,6 @@ name: PyTest
 
 on:
   pull_request:
-    paths-ignore:
-      - "**.md"
 
 jobs:
   get_dockerfiles:
@@ -81,7 +79,7 @@ jobs:
 
       - name: Pytest coverage comment
         id: coverageComment
-        uses: MishaKav/[email protected].51
+        uses: MishaKav/[email protected].52
         with:
           pytest-coverage-path: ./pytest-coverage.txt
           junitxml-path: ./pytest.xml

LICENSE

@@ -186,7 +186,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright [yyyy] [name of copyright owner]
+   Copyright 2023 Physikalisch-Technische Bundesanstalt
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

README.md

@@ -1,35 +1,90 @@
 # MRpro
 
-MR image reconstruction and processing package specifically developed for PyTorch.
-
-This package supports ismrmrd-format for MR raw data. All data containers utilize PyTorch tensors to ensure easy integration in PyTorch-based network schemes.
-
 ![Python](https://img.shields.io/badge/python-3.11%20%7C%203.12-blue)
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 ![Coverage Bagde](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/ckolbPTB/48e334a10caf60e6708d7c712e56d241/raw/coverage.json)
 
-If you want to give MRpro a try you can use
-[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/PTB-MR/mrpro.git/main?labpath=examples)
+MR image reconstruction and processing package specifically developed for PyTorch.
+
+- **Source code:** <https://github.com/PTB-MR/mrpro>
+- **Documentation:** <https://ptb-mr.github.io/mrpro/>
+- **Bug reports:** <https://github.com/PTB-MR/mrpro/issues>
+- **Try it out:** [![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/PTB-MR/mrpro.git/main?labpath=examples)
+
+## Awards
+
+- 2024 ISMRM QMRI Study Group Challenge, 2nd prize for Relaxometry (T2* and T1)
+
+## Main features
+
+- **ISMRMRD support** MRpro supports [ismrmrd-format](https://ismrmrd.readthedocs.io/en/latest/) for MR raw data.
+- **PyTorch** All data containers utilize PyTorch tensors to ensure easy integration in PyTorch-based network schemes.
+- **Cartesian and non-Cartesian trajectories** MRpro can reconstruct data obtained with Cartesian and non-Cartesian (e.g. radial, spiral...) sapling schemes. MRpro automatically detects if FFT or nuFFT is required to reconstruction the k-space data.
+- **Pulseq support** If the data acquisition was carried out using a [pulseq-based](http://pulseq.github.io/) sequence, the seq-file can be provided to MRpro and the used trajectory is automatically calculated.
+- **Signal models** A range of different MR signal models are implemented (e.g. T1 recovery, WASABI).
+- **Regularised image reconstruction** Regularised image reconstruction algorithms including Wavelet-based compressed sensing or total variation regularised image reconstruction are available.
+
+## Examples
+
+In the following we show some code snippets to highlight the use of MRpro. Each code snippet only shows the main steps. A complete working notebook can be found in the provided link.
+
+### Simple reconstruction
 
-You find the documentation [here](https://ptb-mr.github.io/mrpro/)
+Read in the data and trajectoy and reconstruct an image by applying a density compensation function and then the adjoint of the Fourier operator and the adjoint of the coil sensitivity operator.
+
+```python
+# Read the trajectory from the ISMRMRD file
+trajectory = mrpro.data.traj_calculators.KTrajectoryIsmrmrd()
+# Load in the Data from the ISMRMRD file
+kdata = mrpro.data.KData.from_file(data_file.name, trajectory)
+# Perform the reconstruction
+reconstruction = mrpro.algorithms.reconstruction.DirectReconstruction.from_kdata(kdata)
+img = reconstruction(kdata)
+```
+
+Full example: <https://github.com/PTB-MR/mrpro/blob/main/examples/direct_reconstruction.py>
+
+### Estimate quantitative parameters
+
+Quantitative parameter maps can be obtained by creating a functional to be minimised and calling a non-linear solver such as ADAM.
+
+```python
+# Define signal model
+model = MagnitudeOp() @ InversionRecovery(ti=idata_multi_ti.header.ti)
+# Define loss function and combine with signal model
+mse = MSEDataDiscrepancy(idata_multi_ti.data.abs())
+functional = mse @ model
+[...]
+# Run optimization
+params_result = adam(functional, [m0_start, t1_start], max_iter=max_iter, lr=lr)
+```
+
+Full example: <https://github.com/PTB-MR/mrpro/blob/main/examples/qmri_sg_challenge_2024_t1.py>
+
+### Pulseq support
+
+The trajectory can be calculated directly from a provided pulseq-file.
+
+```python
+# Read raw data and calculate trajectory using KTrajectoryPulseq
+kdata = KData.from_file(data_file.name, KTrajectoryPulseq(seq_path=seq_file.name))
+```
+
+Full example: <https://github.com/PTB-MR/mrpro/blob/main/examples/pulseq_2d_radial_golden_angle.py>
 
 ## Contributing
 
 ### Installation for developers
 
-1. Clone the repo
+1. Clone the MRpro repository
 2. Create/select a python environment
-3. Open a terminal in the "MRpro" main folder
-4. Install "MRpro" in editable mode with linting and testing: ``` pip install -e ".[lint,test]" ```
-5. Setup Pre-Commit Hook: ``` pre-commit install ```
+3. Install "MRpro" in editable mode including test dependencies: ``` pip install -e ".[test]" ```
+4. Setup pre-commit hook: ``` pre-commit install ```
 
 ### Recommended IDE and Extensions
 
-We recommend to use [Microsoft Visual Studio Code](https://code.visualstudio.com/download).
-
-A list of recommended extensions for VSCode is given in the [.vscode/extensions.json](.vscode\extensions.json)
-
+We recommend to use [Microsoft Visual Studio Code](https://code.visualstudio.com/download). A list of recommended extensions for VSCode is given in the [.vscode/extensions.json](.vscode\extensions.json)
 
-### Documentation
+### Style
 
-Please have a look at our [contributor guide](https://ptb-mr.github.io/mrpro/contributor_guide.html) for more information on the structure of the repository, naming conventions and other useful information. 
+Please have a look at our [contributor guide](https://ptb-mr.github.io/mrpro/contributor_guide.html) for more information on the structure of the repository, naming conventions and other useful information.

docs/source/_static/custom.css

@@ -2,3 +2,8 @@
 html {
     --pst-font-size-base: 15px;
 }
+
+/* Adjust the width of the content window */
+.wy-nav-content {
+    max-width: 75% !important;
+}

docs/source/api.rst

@@ -1,10 +1,20 @@
 API
 ===
 
-This is the mrpro api documentation.
+This is the MRpro Application Programming Interface (API) documentation.
 
+MRpro Algorithms
+----------------
 
-MRPro Data
+.. autosummary::
+   :toctree: _autosummary
+   :template: module_template.rst
+   :recursive:
+
+   mrpro.algorithms
+
+
+MRpro Data
 ----------
 
 .. autosummary::
@@ -15,7 +25,18 @@ MRPro Data
    mrpro.data
 
 
-MRPro Phantoms
+MRpro Operators
+---------------
+
+.. autosummary::
+   :toctree: _autosummary
+   :template: module_template.rst
+   :recursive:
+
+   mrpro.operators
+
+
+MRpro Phantoms
 --------------
 
 .. autosummary::
@@ -26,7 +47,7 @@ MRPro Phantoms
    mrpro.phantoms
 
 
-MRPro Utilities
+MRpro Utilities
 ---------------
 
 .. autosummary::

docs/source/conf.py

@@ -45,7 +45,7 @@
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
-html_theme = 'pydata_sphinx_theme'
+html_theme = 'sphinx_rtd_theme'
 html_title = name
 html_show_sphinx = False
 html_static_path = ['_static']

docs/source/contributor_guide.rst

@@ -1,6 +1,6 @@
-======================
-Guide for Contributors
-======================
+=================
+Contributor Guide
+=================
 
 Repo structure
 ==============
@@ -19,11 +19,12 @@ automatically created from *pyproject.toml* using GitHub actions.
     Files to create this documentation.
 
 **binder**
-    *requirements.txt* to install all dependencies when starting a binder session.
+    *environment.yml* to install MRpro when starting a binder session.
 
 **examples**
-    Python scripts showcasing how MRpro can be used. Any data needed has to be automatically downloaded from
-    an online repository (e.g. zenodo). The scripts are automatically translated to jupyter notebooks using GitHub
+    Python scripts showcasing how MRpro can be used. Any data needed has to be available from
+    an online repository (e.g. zenodo) such that it can be automatically downloaded. The scripts 
+    are automatically translated to jupyter notebooks using GitHub
     actions. Individual cells should be indicated with ``# %%``. For markdown cells use ``# %% [markdown]``.
     The translation from python script to jupyter notebook is done using
     `jupytext <https://jupytext.readthedocs.io/en/latest/>`_ . See their documentation for more details.

docs/source/faq.rst

@@ -1,6 +1,6 @@
-==========================
-Frequently asked questions
-==========================
+===
+FAQ
+===
 
 What is encoded-space and recon-space?
 ======================================

docs/source/index.rst

@@ -1,19 +1,16 @@
-.. MRPro documentation
+.. MRpro documentation
 
-Welcome to MRPro's documentation!
+Welcome to MRpro's documentation!
 =================================
 
 .. toctree::
    :maxdepth: 1
 
+   api
+   examples
    user_guide
    contributor_guide
-   examples
    faq
-   api
-
-
-
 
 Indices and tables
 ==================

docs/source/user_guide.rst

@@ -1,6 +1,6 @@
-===============
-Guide for Users
-===============
+==========
+User Guide
+==========
 
 MRpro is a MR image reconstruction and processing framework specifically developed to work well with pytorch.
 The data classes utilize torch tensors for storing data such as MR raw data or reconstructed image data.