Merge branch 'develop' into 'main'

Patch Release v0.2.2

See merge request e040/e0404/pyRadPlan!65

Author: wahln

.github/workflows/tests.yml

@@ -0,0 +1,71 @@
+name: Python package
+
+on:
+  push:
+    branches:
+      - '**'
+  pull_request:
+    branches:
+      - main
+      - develop
+  workflow_dispatch:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+        - uses: actions/checkout@v4
+
+        - name: Setup Python ${{ matrix.python-version }}
+          uses: actions/setup-python@v5
+          with:
+            python-version: ${{ matrix.python-version }}
+            cache: pip
+
+        - name: Install dependencies
+          run: |
+            python -m pip install --upgrade pip
+            python -m pip install pytest pytest-cov ruff
+            python -m pip install -e .
+
+        - name: Run tests with pytest
+          run: pytest test --junitxml=.testreports/report.xml -o junit_family=legacy --cov=pyRadPlan --cov-report term --cov-report xml:.testreports/coverage.xml --cov-report html:.testreports/html
+        
+        - name: Upload test reports to Codecov
+          uses: codecov/test-results-action@v1
+          with:
+            token: ${{ secrets.CODECOV_TOKEN }}
+            flags: 'py${{ matrix.python-version }}'
+            files: .testreports/report.xml
+        
+        - name: Upload coverage reports to Codecov
+          if: matrix.python-version == '3.11'
+          uses: codecov/codecov-action@v5
+          with:
+            token: ${{ secrets.CODECOV_TOKEN }}
+            files: .testreports/coverage.xml # optional
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+        - uses: actions/checkout@v4
+        - name: Setup Python 3.11
+          uses: actions/setup-python@v5
+          with:
+            python-version: 3.12
+            cache: pip
+        - name: Install dependencies
+          run: |
+            python -m pip install --upgrade pip
+            python -m pip install ruff
+            python -m pip install -e .
+        - name: Lint with ruff
+          run: ruff check --output-format=github
+          continue-on-error: true
+        - name: Check formatting with ruff
+          run: ruff format --check

.gitlab-ci.yml

@@ -111,6 +111,7 @@ docs:
             - .cache/pip/
         policy: pull
     script:
+        - source .venv/bin/activate
         - pip install sphinx
         - pip install sphinx-autodoc-typehints
         - pip install autodoc_pydantic

README.md

@@ -1,4 +1,14 @@
 # pyRadPlan
+[![Tests](https://github.com/e0404/pyRadPlan/actions/workflows/tests.yml/badge.svg)](https://github.com/e0404/pyRadPlan/actions/workflows/tests.yml)
+[![codecov](https://codecov.io/gh/e0404/pyRadPlan/graph/badge.svg?token=S1KCYDU17G)](https://codecov.io/gh/e0404/pyRadPlan)
+[![pypi version](https://img.shields.io/pypi/v/pyRadPlan)](https://pypi.org/project/pyRadPlan/)
+![pyversion](https://img.shields.io/pypi/pyversions/pyRadPlan)
+![contributors](https://img.shields.io/github/contributors-anon/e0404/pyRadPlan)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+![License](https://img.shields.io/github/license/e0404/pyRadPlan)
+
+
+
 pyRadPlan is an open-source radiotherapy treatment planning toolkit designed for interoperability with [matRad](http://www.matRad.org).
 
 Development is lead by the [Radiotherapy Optimization group](https://www.dkfz.de/radopt) at the [German Cancer Research Center (DKFZ)](https://www.dkfz.de)

docs/conf.py

@@ -7,14 +7,17 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 import os
 import sys
+from pyRadPlan import __version__
 
 print(os.path.abspath("../pyRadPlan"))
 sys.path.insert(0, os.path.abspath("../pyRadPlan"))  # Adjust to your source folder
 
 project = "pyRadPlan"
 copyright = "2024, e0404"
 author = "e0404"
-release = "0.0.1"
+
+version = __version__
+release = __version__
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration

pyRadPlan/core/datamodel.py

@@ -1,8 +1,7 @@
-"""Module datamodel.py
-Basic Model for all pyRadPlan Datastructures.
-"""
+"""Basic Model for all pyRadPlan Datastructures."""
 
 from typing import Any, Union
+import numpy as np
 from pydantic import (
     AliasGenerator,
     BaseModel,
@@ -14,16 +13,17 @@
 
 class PyRadPlanBaseModel(BaseModel):
     """
-    Base class for all pyRadPlan data structures, especially the ones that
-    should be matRad
-    compatible
-    This class extends Pydantic's BaseModel.
+    Base class for all pyRadPlan data structures.
+
+    Especially useful for structures that should be matRad compatible.
+    Extends Pydantic's BaseModel to use pydantic validation and serialization.
 
     Attributes
     ----------
     model_config : ConfigDict
-        Configuration for the model, including alias generation, population by name, arbitrary
-        types allowed, assignment validation, and attribute creation from dictionary.
+        Configuration for the model, including alias generation, population by
+        name, arbitrary types allowed, assignment validation, and attribute
+        creation from dictionary.
     """
 
     model_config = ConfigDict(
@@ -35,15 +35,56 @@ class PyRadPlanBaseModel(BaseModel):
         from_attributes=True,  # Allows to create a model from a dictionary
     )
 
+    def __eq__(self, other: Any) -> bool:
+        """
+        Specialized __eq__ method to compare two pyRadPlanBaseModel instances.
+
+        It first tries to compare the instances using the super().__eq__ method.
+        If this fails, it compares the dictionaries. This is due to some issues
+        comparing numpy arrays within the models.
+        """
+        try:
+            return super().__eq__(other)
+        except ValueError:
+            if self.__dict__.keys() != other.__dict__.keys():
+                return False
+            stack = [(self.__dict__, other.__dict__)]
+            while stack:
+                dict_a, dict_b = stack.pop()
+                if dict_a.keys() != dict_b.keys():
+                    return False
+                for key in dict_a:
+                    if isinstance(dict_a[key], dict) and isinstance(dict_b[key], dict):
+                        stack.append((dict_a[key], dict_b[key]))
+                    elif isinstance(dict_a[key], np.ndarray) and isinstance(
+                        dict_b[key], np.ndarray
+                    ):
+                        if not np.array_equal(dict_a[key], dict_b[key]):
+                            return False
+                    elif dict_a[key] != dict_b[key]:
+                        return False
+            return True
+
+    def __ne__(self, other: Any) -> bool:
+        """
+        Specialized __ne__ method to compare two PyRadPlanBaseModel instances.
+
+        This method returns the negation of the __eq__ method.
+        """
+        if isinstance(other, self.__class__):
+            return not self.__eq__(other)
+        else:
+            return True
+
     def to_matrad(self, context: Union[str, dict] = "mat-file") -> Any:
         """
-        Interface method to serialize a pyradplan datastructure to be matRad
-        compatible.
+        Perform matRad compatible serialization.
 
         Parameters
         ----------
         context : str, optional
-            The context in which the datastructure should be serialized, by default 'mat-file'.
+            The context in which the datastructure should be serialized,
+            by default 'mat-file'.
 
         Returns
         -------
@@ -52,9 +93,9 @@ def to_matrad(self, context: Union[str, dict] = "mat-file") -> Any:
 
         Notes
         -----
-        Currently, the only supported context is 'mat-file'. In the future, this could be
-        extended to support other contexts, such as direct calling via the matlab engine or
-        oct2py.
+        Currently, the only supported context is 'mat-file'. In the future,
+        this could be extended to support other contexts, such as direct
+        calling via the matlab engine or oct2py.
         """
         self_copy = deepcopy(self)
         if isinstance(context, dict):

pyRadPlan/dij/__init__.py

@@ -1,5 +1,6 @@
 """Module for Dij Datamodel and related functions."""
 
 from pyRadPlan.dij._dij import Dij, create_dij, validate_dij
+from pyRadPlan.dij._compose_beam_dijs import compose_beam_dijs
 
-__all__ = ["Dij", "create_dij", "validate_dij"]
+__all__ = ["Dij", "create_dij", "validate_dij", "compose_beam_dijs"]

pyRadPlan/dij/_compose_beam_dijs.py

@@ -0,0 +1,55 @@
+import numpy as np
+
+from scipy.sparse import hstack
+from ._dij import Dij
+
+
+def compose_beam_dijs(dijs: list[Dij]) -> Dij:
+    """Compose multiple Dij objects into a single Dij object.
+
+    Parameters
+    ----------
+    dijs : list[Dij]
+        List of Dij objects to be composed.
+
+    Returns
+    -------
+    Dij
+        Composed Dij object.
+    """
+
+    qs = dijs[0].quantities
+
+    num_of_beams = 0
+    beam_num = np.array([], dtype=int)
+    ray_num = np.array([], dtype=int)
+    bixel_num = np.array([], dtype=int)
+
+    for i, dij in enumerate(dijs):
+        beam_num = np.append(beam_num, dij.beam_num + num_of_beams)
+        ray_num = np.append(ray_num, dij.ray_num)
+        bixel_num = np.append(bixel_num, dij.bixel_num)
+        num_of_beams = num_of_beams + dij.num_of_beams
+
+    matrices = {}
+    for q in qs:
+        tmp_matrices = [getattr(dij, q) for dij in dijs]
+
+        new_matrix = np.empty_like(tmp_matrices[0], dtype=object)
+
+        for i, scen_matrix in enumerate(tmp_matrices[0].flat):
+            if scen_matrix is not None:
+                new_matrix.flat[i] = hstack([tmp_matrix.flat[i] for tmp_matrix in tmp_matrices])
+
+        matrices.update({q: new_matrix})
+
+    return Dij(
+        ct_grid=dijs[0].ct_grid,
+        dose_grid=dijs[0].dose_grid,
+        matrices=matrices,
+        num_of_beams=num_of_beams,
+        beam_num=beam_num,
+        ray_num=ray_num,
+        bixel_num=bixel_num,
+        **matrices
+    )

pyRadPlan/dij/_dij.py

@@ -62,6 +62,13 @@ def total_num_of_bixels(self) -> int:
     def num_of_voxels(self) -> int:
         """Number of voxels in the dose influence matrix."""
         return self.physical_dose.flat[0].shape[0]
+    
+    @computed_field
+    @property
+    def quantities(self) -> list[str]:
+        """Name of available uantities matrices."""
+        potential_quantities = ["physical_dose", "let_dose", "alpha_dose", "sqrt_beta_dose"]
+        return [q for q in potential_quantities if getattr(self, q) is not None]
 
     @field_validator("physical_dose", "let_dose", "alpha_dose", "sqrt_beta_dose", mode="before")
     @classmethod
@@ -119,6 +126,25 @@ def validate_grid(cls, grid: Union[Grid, dict]) -> Union[Grid, dict]:
             grid = Grid.model_validate(grid)
         return grid
 
+    @field_validator("beam_num", mode="before")
+    @classmethod
+    def validate_unique_indices_in_beam_num(
+        cls, v: np.ndarray, info: ValidationInfo
+    ) -> np.ndarray:
+        """
+        Validate the number of unique indices in beam_num.
+
+        Raises
+        ------
+            ValueError: Number of unique indices does not match number of beams.
+        """
+        num_of_beams = info.data["num_of_beams"]
+        if len(np.unique(v)) != num_of_beams:
+            raise ValueError(
+                "Number of unique indices in beam_num does not match number of beams."
+            )
+        return v
+
     @field_validator("beam_num", "ray_num", "bixel_num", mode="after")
     @classmethod
     def validate_numbering_arrays(cls, v: np.ndarray, info: ValidationInfo) -> np.ndarray:
@@ -146,25 +172,8 @@ def validate_numbering_arrays(cls, v: np.ndarray, info: ValidationInfo) -> np.nd
                             "Numbering arrays shape inconsistent with number of bixels"
                         )
 
-        return v
-
-    @field_validator("beam_num")
-    @classmethod
-    def validate_unique_indices_in_beam_num(
-        cls, v: np.ndarray, info: ValidationInfo
-    ) -> np.ndarray:
-        """
-        Validate the number of unique indices in beam_num.
-
-        Raises
-        ------
-            ValueError: Number of unique indices does not match number of beams.
-        """
-        num_of_beams = info.data["num_of_beams"]
-        if len(np.unique(v)) != num_of_beams:
-            raise ValueError(
-                "Number of unique indices in beam_num does not match number of beams."
-            )
+        if info.context and "from_matRad" in info.context and info.context["from_matRad"]:
+            v -= 1
         return v
 
     # Serialization
@@ -346,7 +355,12 @@ def create_dij(data: Union[dict[str, Any], Dij, None] = None, **kwargs) -> Dij:
         if isinstance(data, Dij):
             return data
 
-        return Dij.model_validate(data)
+        if "beamNum" in data and np.min(data["beamNum"]) != 0:
+            # add context when from matRad
+            context = {"from_matRad": True}
+        else:
+            context = {"from_matRad": False}
+        return Dij.model_validate(data, context=context)
 
     return Dij(**kwargs)