PortPy Version 1.2.0

1. Add beamlet dose prediction module to portpy.ai
2. create example notebook for it
3. Add scorecard to evaluation.py
4. Update vmat scp to latest version with bug fixes.
5. Make dose prediction module site independent

Minor changes.
Enhance project structure and functionality:
- Update .gitignore to include new data directories.
- Modify __init__.py to import scorecard functions.
- Adjust test assertions for expected solution values.
- Refine optimization.py to use np.inf for max constraints.
- Update pred_dose_to_original_portpy.py for improved plan initialization.
- Revise requirements.txt for updated package versions.
- Enhance single_dataset.py and dosepred3d_dataset.py to handle additional data fields.
- Add new optimization parameters in optimization_params_Prostate_5Gy_5Fx_vmat.json.

Author: gourav3017

.github/workflows/ci.yml

@@ -1,6 +1,7 @@
 name: CI and Publish
 
 on:
+  workflow_dispatch:
   push:
     branches:
       - master

examples/imrt_dose_prediction.ipynb

@@ -90,7 +90,7 @@
    "outputs": [],
    "source": [
     "in_dir = r'../data' # directory where portpy raw data is located\n",
-    "out_dir = r'../ai_data' # directory where processed data to be stored for training and testing model"
+    "out_dir = r'../ai_data_lungs' # directory where processed data to be stored for training and testing model"
    ]
   },
   {
@@ -101,7 +101,11 @@
    "outputs": [],
    "source": [
     "# preprocess portpy data before the training\n",
-    "data_preprocess(in_dir, out_dir)"
+    "# preprocess portpy data\n",
+    "data_preprocess(in_dir, out_dir, site='lung', protocol_name='Lung_2Gy_30Fx', technique_name='imrt')\n",
+    "# for prostate vmat patients, use below code to preprocess the data. You can change the protocol name and technique name as per your requirement\n",
+    "# beam_ids = np.arange(0, 72)\n",
+    "# data_preprocess(in_dir, out_dir, site='prostate', protocol_name='Prostate_5Fx', beam_ids = beam_ids, technique_name='vmat')"
    ]
   },
   {
@@ -141,26 +145,33 @@
    "metadata": {},
    "outputs": [],
    "source": [
+    "# Provide only the arguments you want to override\n",
     "# Provide only the arguments you want to override\n",
     "train_options = {\n",
-    "    \"dataroot\": \"../ai_data\",  # Directory where post-processed training/validation data is located. \n",
-    "    \"checkpoints_dir\": \"../checkpoints\",  # Directory to save model checkpoints during training\n",
-    "    \"netG\": \"unet_128\",  # Generator architecture to use; e.g., 3D UNet with input size 128x128x128\n",
-    "    \"name\": \"portpy_test_3\",  # Name of the training experiment; determines subdirectory for logs and models\n",
-    "    \"model\": \"doseprediction3d\",  # Type of model being trained; for 3D dose prediction tasks\n",
-    "    \"direction\": \"AtoB\",  # Data flow direction; 'AtoB' means input (A) to predicted dose (B)\n",
-    "    \"lambda_L1\": 1,  # Weight for the L1 loss term in the total loss function\n",
-    "    \"dataset_mode\": \"dosepred3d\",  # Dataset class to use for loading 3D dose prediction data\n",
-    "    \"norm\": \"batch\",  # Type of normalization layer to use ('batch', 'instance', etc.)\n",
-    "    \"batch_size\": 1,  # Number of samples per training batch\n",
-    "    \"pool_size\": 0,  # Size of image buffer for previously generated images (0 disables the buffer)\n",
-    "    \"display_port\": 8097,  # Port to use for Visdom visualization server (if enabled)\n",
-    "    \"lr\": 0.0002,  # Initial learning rate for the optimizer\n",
-    "    \"input_nc\": 8,  # Number of input channels (e.g., CT + structure masks)\n",
-    "    \"output_nc\": 1,  # Number of output channels (e.g., predicted dose volume)\n",
-    "    \"display_freq\": 10,  # Frequency (in steps) of displaying images during training\n",
-    "    \"print_freq\": 1,  # Frequency (in steps) of printing training losses to console\n",
-    "    \"gpu_ids\": [0]  # List of GPU IDs to use; e.g., [0] for single-GPU or [0,1] for multi-GPU\n",
+    "    \"dataroot\": \"../../ai_data_lungs\", # directory where processed data is located for training and testing model\n",
+    "    \"checkpoints_dir\": \"../../checkpoints\", # directory where model checkpoints will be saved during training\n",
+    "    \"netG\": \"mednext\", # type of generator network architecture to be used for training. PortPy uses a baseline 3D U-Net architecture for model training. If desired, users can define their own architectures by modifying the networks_3d.py file located in the model directory of the portpy.ai module.\n",
+    "    \"dose_loss\": \"mednext_hybrid\", # dose less function. it can be customized\n",
+    "    \"name\": \"portpy_lung_mednext\", # experiment name\n",
+    "    \"model\": \"doseprediction3d\", # type of model to be trained\n",
+    "    \"direction\": \"AtoB\",\n",
+    "    \"lambda_L1\": 1,\n",
+    "    \"dataset_mode\": \"dosepred3d\",\n",
+    "    \"norm\": \"batch\",\n",
+    "    \"batch_size\": 1,\n",
+    "    \"pool_size\": 0,\n",
+    "    \"display_port\": 8097,\n",
+    "    \"lr\": 0.0001,\n",
+    "    \"n_epochs\": 100,\n",
+    "    \"input_nc\": 8,\n",
+    "    \"output_nc\": 1,\n",
+    "    \"display_freq\": 10,\n",
+    "    \"display_id\":-1,\n",
+    "    \"print_freq\": 1,\n",
+    "    \"augment\": False,  # transform images for data augmentation\n",
+    "    \"gpu_ids\": [0], # Converted to a list since multiple GPUs may be supported\n",
+    "    \"val_phase\": \"val\",\n",
+    "    \"lr_policy\": \"plateau\"\n",
     "}\n",
     "\n",
     "train(train_options)  # Run training directly in Jupyter Notebook"
@@ -174,7 +185,7 @@
    "outputs": [],
    "source": [
     "# You can uncomment and run below in case if you want to run train script from CLI\n",
-    "#!python ../portpy/ai/train.py --dataroot ../ai_data --netG unet_128 --name portpy_test_3 --model doseprediction3d --direction AtoB --lambda_L1 1 --dataset_mode dosepred3d --norm batch --batch_size 1 --pool_size 0 --display_port 8097 --lr 0.0002 --input_nc 8 --output_nc 1 --display_freq 10 --print_freq 1 --gpu_ids 0"
+    "#!python ../portpy/ai/train.py --dataroot ../ai_data_lungs --netG mednext --name portpy_lung_mednext --model doseprediction3d --direction AtoB --lambda_L1 1 --dataset_mode dosepred3d --dose_loss mednext_hybrid --norm batch --batch_size 1 --pool_size 0 --display_port 8097 --lr 0.0002 --input_nc 8 --output_nc 1 --display_freq 10 --print_freq 1 --gpu_ids 0"
    ]
   },
   {
@@ -193,21 +204,23 @@
    "outputs": [],
    "source": [
     "test_options = {\n",
-    "    \"dataroot\": \"../ai_data\",  # Directory where test data is located (post-processed format)\n",
-    "    \"netG\": \"unet_128\",  # Generator architecture to use; should match the model used during training\n",
-    "    \"checkpoints_dir\": \"../checkpoints\",  # Directory where trained model checkpoints are stored\n",
-    "    \"results_dir\": \"../results\",  # Directory to save test outputs (e.g., predicted dose volumes)\n",
-    "    \"name\": \"portpy_test_3\",  # Name of the experiment; used to locate the corresponding checkpoint\n",
-    "    \"phase\": \"test\",  # Indicates the current phase ('train', 'val', or 'test')\n",
-    "    \"mode\": \"eval\",  # Mode of operation; should be 'eval' to run inference\n",
-    "    \"eval\": True,  # If True, sets the model to evaluation mode (disables dropout, batch norm updates)\n",
-    "    \"model\": \"doseprediction3d\",  # Type of model to load; should match the training configuration\n",
-    "    \"input_nc\": 8,  # Number of input channels; must be consistent with the trained model\n",
-    "    \"output_nc\": 1,  # Number of output channels; typically 1 for dose prediction\n",
-    "    \"direction\": \"AtoB\",  # Data flow direction; must be consistent with training\n",
-    "    \"dataset_mode\": \"dosepred3d\",  # Dataset loader to use for loading test data\n",
-    "    \"norm\": \"batch\"  # Type of normalization used in the model; must match training setup\n",
-    "}"
+    "    \"dataroot\": \"../../ai_data_lungs\",\n",
+    "    \"netG\": \"mednext\",\n",
+    "    \"checkpoints_dir\": \"../../checkpoints\",\n",
+    "    \"results_dir\": \"../../results\",\n",
+    "    'dose_loss': 'mednext_hybrid',\n",
+    "    \"name\": \"portpy_lung_mednext\",\n",
+    "    \"phase\": \"test\",\n",
+    "    \"mode\": \"eval\",\n",
+    "    \"eval\": True,  # Boolean flag\n",
+    "    \"model\": \"doseprediction3d\",\n",
+    "    \"input_nc\": 8,\n",
+    "    \"output_nc\": 1,\n",
+    "    \"direction\": \"AtoB\",\n",
+    "    \"dataset_mode\": \"dosepred3d\",\n",
+    "    \"norm\": \"batch\"\n",
+    "}\n",
+    "test(test_options)"
    ]
   },
   {
@@ -250,8 +263,9 @@
    "source": [
     "# For users who does not want to train and test, they can directly preprocess portpy data for dose predicition pipeline and predict using AI model\n",
     "patient_id = 'Lung_Patient_4'\n",
-    "model_name = 'portpy_test_3'\n",
-    "pred_dose = predict_using_model(patient_id=patient_id, in_dir=in_dir, out_dir=out_dir, model_name=model_name, checkpoints_dir='../checkpoints', results_dir='../results')"
+    "model_name = 'portpy_lung_mednext'\n",
+    "pred_dose = predict_using_model(patient_id=patient_id, in_dir=in_dir, out_dir=out_dir, model_name=model_name, checkpoints_dir='../../checkpoints', results_dir='../../results', netG='mednext',\n",
+    "                                site='lung', protocol_name='Lung_2Gy_30Fx')\n"
    ]
   },
   {

portpy/ai/infer_runner.py

@@ -0,0 +1,84 @@
+import os
+
+from portpy.ai.options.test_options import TestOptions
+from portpy.ai.data import create_dataset
+from portpy.ai.models import create_model
+from portpy.ai.util.visualizer import save_images
+from portpy.ai.util import html
+
+# Match the output naming used elsewhere
+npy_out_fnames = ['CT2DOSE']
+
+
+def build_infer_opt(args: dict):
+    """
+    Build a test/inference options object from a dict.
+    """
+    opt = TestOptions().parse()
+    vars(opt).update(args)
+
+    opt.num_threads = 0
+    opt.batch_size = 1
+    opt.serial_batches = True
+    opt.no_flip = True
+    opt.display_id = -1
+
+    return opt
+
+
+class InferenceRunner:
+    """
+    Load model once, run inference many times.
+    """
+
+    def __init__(self, args: dict):
+        self.opt = build_infer_opt(args)
+        self.model = create_model(self.opt)
+        self.model.setup(self.opt)
+
+        if self.opt.eval:
+            self.model.eval()
+
+    def run(self, dataroot: str):
+        """
+        Run inference on the given dataroot and save outputs
+        exactly like test.py would.
+        """
+        self.opt.dataroot = dataroot
+        dataset = create_dataset(self.opt)
+
+        web_dir = os.path.join(
+            self.opt.results_dir,
+            self.opt.name,
+            '{}_{}'.format(self.opt.phase, self.opt.epoch)
+        )
+        if self.opt.load_iter > 0:
+            web_dir = '{:s}_iter{:d}'.format(web_dir, self.opt.load_iter)
+
+        print('creating web directory', web_dir)
+        webpage = html.HTML(
+            web_dir,
+            'Experiment = %s, Phase = %s, Epoch = %s'
+            % (self.opt.name, self.opt.phase, self.opt.epoch)
+        )
+
+        for i, data in enumerate(dataset):
+            self.model.set_input(data)
+            self.model.test()
+
+            visuals = self.model.get_current_visuals()
+            img_path = self.model.get_image_paths()
+
+            if i % 5 == 0:
+                print('processing (%04d)-th image... %s' % (i, img_path))
+
+            save_images(
+                webpage,
+                visuals,
+                img_path,
+                aspect_ratio=self.opt.aspect_ratio,
+                width=self.opt.display_winsize,
+                npy_out_fnames=npy_out_fnames
+            )
+
+        webpage.save()

portpy/ai/train_upkern.py

@@ -0,0 +1,48 @@
+# Copyright 2025, the PortPy Authors
+#
+# Licensed under the Apache License, Version 2.0 with the Commons Clause restriction.
+
+import os
+import sys
+
+project_root = os.path.abspath(os.path.join(os.path.dirname(__file__), "../.."))
+if project_root not in sys.path:
+    sys.path.append(project_root)
+
+from portpy.ai.train import main
+from portpy.ai.options.train_options import TrainOptions
+
+
+def train_upkern(args=None):
+    """
+    Continue training a kernel-3 MedNeXt model as a kernel-5 model using UpKern.
+    Works like train(args), so you can pass only overridden options.
+    """
+    if args is None:
+        opt = TrainOptions().parse()
+    else:
+        default_opt = TrainOptions().parse()
+        vars(default_opt).update(args)
+        opt = default_opt
+
+        for k, v in vars(opt).items():
+            print(f"{k}: {v}")
+
+    # enforce UpKern continuation settings unless user explicitly overrides
+    opt.netG = 'mednext'
+    opt.load_upkern = True
+
+    if not hasattr(opt, 'mednext_kernel_size') or opt.mednext_kernel_size is None:
+        opt.mednext_kernel_size = 5
+
+    if not hasattr(opt, 'mednext_model_id') or opt.mednext_model_id is None:
+        opt.mednext_model_id = 'S'
+
+    if not getattr(opt, 'upkern_pretrained_path', None):
+        raise ValueError("Please provide 'upkern_pretrained_path' for UpKern continuation training.")
+
+    main(opt)
+
+
+if __name__ == '__main__':
+    train_upkern()