PortPy 1.2.0

Highlights

Beamlet dose prediction (portpy.ai) — a full pipeline for predicting individual
beamlet dose columns with a 3D deep-learning model, and assembling them into a predicted
influence matrix A_pred. This lets you build a plannable influence matrix without a
dose engine. Includes preprocessing, dataset, training/testing, and matrix assembly, with
an end-to-end example (examples/beamlet_dose_prediction.ipynb).

New portpy.ai.inference subpackage — the inference half of the above, usable on its
own: beam-frame geometry (gantry/collimator/couch), ray-aligned BEV patch extraction,
GPU resampling via torch.grid_sample, and two predictors (RayUNetPredictor,
PatientGridPredictor) behind build_ray_unet_predictor / build_patient_grid_predictor.
Importing the package pulls no torch; torch loads lazily inside the predictors.

Two sampling grids — beamlet dose can be predicted on a world-aligned patient grid or
a ray-aligned BEV patch, selectable with grid="patient" | "bev" through preprocessing,
training and inference.

Plan quality scorecards — Evaluation.compute_total_quality_score() scores a plan
against a scorecard and returns a per-criterion table. Two scorecards ship with the
package (Lung 60Gy and Prostate SBRT), plus adapt_scorecard_prescription() to
rescale a scorecard written for a different prescription.

New models — UNet3D alongside an expanded networks3d
registry (beamlet_unet, ray_unet3d, ray_attention_resunet3d, mednext).

New protocol — Prostate_5Gy_5Fx, with clinical criteria and IMRT/VMAT optimization
parameters.

Bug fixes

• Influence matrix: crash on some of the shipped patients. preprocess_beams raised
  IndexError while slicing MLC_leaf_idx for patients whose stored leaf table is
  inconsistent with the beamlet grid. The field is no longer needed: the VMAT RT-plan
  writer now derives leaf pairs per row from leaf_pair_row_match, which is also correct
  for rows spanning different numbers of leaves.
• Leaf sequencing worked for only some patients. leaf_sequencing_siochi matched
  beamlet rows against the stored leaf table with an exact int() comparison, which only
  succeeded when that table happened to be whole-millimetre. It now resolves leaf rows
  from the MLC leaf edges and works for every patient.
• Influence matrix assembly was quadratic in beam count. get_influence_matrix grew
  the matrix one beam at a time; it now concatenates once. Output is bit-identical.
  Largest measured effect: a 191-beam breast case went from 306 s to 5.4 s.
• Windows: import portpy.photon broke a later import torch. The VMAT SCP utilities
  loaded the Intel MKL runtime eagerly; that import is now deferred until first use.
• Clinical criteria: negative or unresolvable dose limits and goals are dropped instead
  of raising, and "coldest" (CV/DC) dose-volume constraints are supported.

Installation fixes

pip install -r requirements.txt previously failed because the file was UTF-16 encoded.
It is now UTF-8 and mirrors the core dependencies in pyproject.toml.

• Removed ecos and qdldl — C extensions that required a compiler when no wheel matched
  the user's Python. They are unused by PortPy.
• Added clarabel to core dependencies, so a fast free solver is available by default.
• Relaxed the exact jinja2==3.1.5 pin, which conflicted with other packages.
• requirements.txt no longer forces the commercial Mosek solver on source installs;
  it stays an optional extra (pip install portpy[mosek]).

Testing

New tests/test_ai_module.py (26 tests) covering beam geometry conventions, the 3D UNet
forward pass, and GPU resampling accuracy. CI installs CPU-only torch so these run on
every push.

Full changelog: v1.1.4...v1.2.0

What's Changed

• Add prediction-based dose mimicking to VMAT column generation by @sijiaww in #18

Minor bug fixes

• Use max tol of overlap organs properly in dvh constraint
• Fix bugs in clinical_criteria.py

What's Changed

• Created a download script for downloading PortPy compatible data from hugging face based on user inputs. (commit de58260)
• Add CVaR for dvh constraint helper in Optimization by @sijiaww in #15

Minor Bug fixes

• Fix VMAT SCP MU scaling and clinical criteria logic by @sijiaww in #14
• Fix bugs in clinical criteria.py (commit de58260)
• Add VMAT optimization template for prostate 26Fx

Pull requests

• @sijiaww made their contribution for enforcing dvh constraints using CVaR in #15

Minor bug fixes in portpy.ai module

Version 1.1.1

New Features

• Support for dose calculation for any custom patient (Eclipse TPS users only).
  See eclipse_photon_dose_calculation.ipynb for details.
• Added 129 prostate patients to hugging face for ready to use with PortPy
• Added new methods to DataExplorer for accessing data directly from Hugging Face.
• Added unit tests and GitHub workflows for CI/CD.

Improvements

• Removed redundant max constraints in optimization.py.
• Improved docstrings in ClinicalCriteria for better clarity.

Pull Request Highlights

• Fixed misleading docstring in the create_cvxpy_problem method. (PR #11 by @lwins-lights)

Major Updates

• Data hosting moved to Hugging Face for robust and accessible dataset storage
• Integrated direct download of patient datasets from Hugging Face within PortPy
• Improved visualization for dose distribution and clinical criteria evaluation
• Added online data augmentation support in portpy.ai for better training generalization
• Updated Jupyter notebooks and Python scripts to reflect new data structure and features
• New interactive web app to explore/download data: PortPy Dataset Visualization on Hugging Face Spaces

Bug Fixes

• Minor bug fixes in portpy.ai module

Updates for version v1.0.8 (Major)

• Add photon dose calculation module for custom patients outside PortPy dataset
• Create example notebook for doing influence matrix dose calculation of custom patient outside PortPy data and optimize the plan using PortPy

Minor bug fixes

• Add more colors to visualization.py for additional structures
• Add create_ct_dose_voxel_map.py for photon dose calc
• Expand functionality for convert_dose_rt_dicom_to_portpy.py if ct object is not available.
• Fix poetry bug to pip install submodules

1- Updates for SCP based VMAT optimization. (Use column generation for good initial start). Fix bugs
2- Get voxel coordinates
2- Use pyproject.toml instead of setup.py for build
3- Fix bugs in structures.py for "-" in struct name.
4- Fix visualization.py.

Version 1.0.5 Changes:

1. Update PortPy.AI module with easy to run notebooks
2. Update PortPy visualization.py for better dvh fonts and apperance
3. Update vmat scp dose prediction
4. Add random leaf position initialization feature to VMAT SCP

Make Mosek and pydicom optional dependencies. One can install them if needed using pip install portpy[mosek] or pip install portpy[pydicom]