Updated to V1.0.4

gourav3017 · gourav3017 · commit d83bc9864ffe · 2024-06-04T16:29:35.000-04:00
diff --git a/examples/vmat_scp_tutorial.ipynb b/examples/vmat_scp_tutorial.ipynb
diff --git a/portpy/photon/influence_matrix.py b/portpy/photon/influence_matrix.py
@@ -695,7 +695,7 @@ def get_bev_2d_grid(self, beam_id: Union[Union[int, str], List[Union[int, str]]]
                        self.beamlets_dict[i]['beam_id'] == beam_id]
                 if not ind:
                     raise ValueError("invalid beam id {}".format(beam_id))
-            if isinstance(ind, int) or isinstance(ind, str):
+            elif isinstance(beam_id, list):
                 for idx in beam_id:
                     try:
                         ind_1 = [i for i in range(len(self.beamlets_dict)) if
diff --git a/portpy/photon/vmat_scp/arcs.py b/portpy/photon/vmat_scp/arcs.py
@@ -3,6 +3,7 @@
 from portpy.photon.influence_matrix import InfluenceMatrix
 import json
 from copy import deepcopy
+from typing import Union, List
 
 class Arcs:
     """
@@ -18,13 +19,23 @@ class Arcs:
                   }
 
         :type arcs_dict: dict
+        :param inf_matrix: object of InfluenceMatrix class
+        :type inf_matrix: object
+        :param file_name: json file containing arcs information
+        :type file_name: str
+        :param data: object of DataExplorer class
+        :type data: object
+
 
     - **Methods** ::
 
-        :get_gantry_angle(beam_id: Optional(int, List[int]):
-            Get gantry angle in degrees
-        :get_collimator_angle(beam_id):
-            Get collimator angle in degrees
+        method get_all_arcs: Get all arcs as a list
+        method get_arc: Get arc based upon arc id
+        method get_initial_leaf_pos: Get initial leaf position based upon BEV or other user defined criteria to start SCP
+        method gen_interior_and_boundary_beamlets: Generate interior and boundary beamlets based upon step size
+        method calc_actual_from_intermediate_sol: Calculate actual solution from intermediate solution
+
+
 
     """
 
@@ -53,6 +64,32 @@ def load_json(self, arcs_json_file):
         f.close()
         return arcs_dict
 
+    def get_all_arcs(self):
+        """
+        Get all arcs as a list
+
+        """
+        return self.arcs_dict['arcs']
+
+    def get_arc(self, arc_id: Union[Union[int, str], List[Union[int, str]]]):
+        """
+        Get arc based upon arc id
+        :param arc_id: arc id for the arc needed
+        :return: list of arcs
+
+        """
+        ind = []
+        if isinstance(arc_id, int) or isinstance(arc_id, str):
+            ind = [i for i in range(len(self.arcs_dict['arcs'])) if
+                   self.arcs_dict['arcs'][i]['arc_id'] == arc_id]
+            if not ind:
+                raise ValueError("invalid arc id {}".format(arc_id))
+        arcs = []
+        for a in ind:
+            arc = self.arcs_dict['arcs'][a]
+            arcs.append(arc)
+        return arcs
+
     def get_max_cols(self):
         max_cols = 0
         arcs = self.arcs_dict['arcs']
@@ -73,11 +110,12 @@ def preprocess(self):
             arc['vmat_opt'] = beams_list
 
     def get_initial_leaf_pos(self, initial_leaf_pos='BEV'):
-        arcs_dict = self.arcs_dict
         """
-        Initialize leaf positions for the scp
+            Initialize leaf positions for the scp.
+            :param initial_leaf_pos: initial leaf position. Default is BEV
+            :return: None
         """
-
+        arcs_dict = self.arcs_dict
         for i, arc in enumerate((arcs_dict['arcs'])):
             beams_list = arc['vmat_opt']
             for j, beam in enumerate(beams_list):
@@ -119,6 +157,11 @@ def gen_interior_and_boundary_beamlets(self, forward_backward: int = 1, step_siz
         """
         Create interior and boundary beamlets based upon step_size and forward backward
 
+        :param forward_backward: forward backward value. Default is 1. If 1, forward, if 0, backward
+        :param step_size_f: step size for forward. Default is 8
+        :param step_size_b: step size for backward. Default is 8
+        :return: None
+
         """
         arcs_dict = self.arcs_dict
         for a, arc in enumerate(arcs_dict['arcs']):
@@ -210,7 +253,12 @@ def gen_interior_and_boundary_beamlets(self, forward_backward: int = 1, step_siz
                 vmat[b]['int_ind'] = int_ind
 
     def calc_actual_from_intermediate_sol(self, sol: dict):
+        """
+        Create actual solution from intermediate solution.
+        :param sol: solution dictionary
+        :return: None
 
+        """
         int_v = sol['int_v']
         bound_v_l = sol['bound_v_l']
         bound_v_r = sol['bound_v_r']
@@ -266,6 +314,10 @@ def update_leaf_pos(self, forward_backward: int, update_reference_leaf_pos: bool
                         1] * (1 - forward_backward)
 
     def update_best_solution(self):
+        """
+        Update best solution if the current solution is better than the best solution.
+        :return: None
+        """
         arcs = self.arcs_dict['arcs']
         for a, arc in enumerate(arcs):
             for b, beam in enumerate(arc['vmat_opt']):
@@ -274,6 +326,11 @@ def update_best_solution(self):
             arc['best_w_beamlet_act'] = arc['w_beamlet_act']
 
     def calculate_beamlet_value(self):
+        """
+        Calculate beamlet values between (0-1) for the intermediate solution.
+        :return: None
+
+        """
         # calculates the beamlet values between (0-1)
         arcs = self.arcs_dict['arcs']
         num_beamlets_so_far = 0
@@ -297,6 +354,16 @@ def calculate_beamlet_value(self):
         return arcs
 
     def calculate_dose(self, inf_matrix: InfluenceMatrix, sol: dict, vmat_params: dict, best_plan: bool = False):
+        """
+
+        Calculate dose from the solution.
+        :param inf_matrix: object of InfluenceMatrix class
+        :param sol: solution dictionary
+        :param vmat_params: vmat parameters
+        :param best_plan: if True, calculate dose for best plan. Default is False
+        :return: solution dictionary containing dose values
+
+        """
         A = inf_matrix.A
         arcs = self.arcs_dict['arcs']
         adj1 = vmat_params['second_beam_adj']
@@ -339,6 +406,10 @@ def calculate_dose(self, inf_matrix: InfluenceMatrix, sol: dict, vmat_params: di
         return sol
 
     def intermediate_to_actual(self):
+        """
+        Convert intermediate solution to actual feasible solution.
+
+        """
         arcs = self.arcs_dict['arcs']
         beamlet_so_far = 0
         # Convert intermediate solution to actual feasible solution
@@ -407,6 +478,13 @@ def intermediate_to_actual(self):
             beamlet_so_far = beamlet_so_far + num_beamlets
 
     def _update_reference_leaf_pos(self):
+        """
+        Update reference leaf position in forward and backward direction. The following leaf positions are updated only if a solution is accepted
+        they are necessary because if a solution is rejected and forward/backward
+        is changed then you need to go back to this reference leaf positions to
+        update your leaf positions
+
+        """
         arcs = self.arcs_dict['arcs']
         for arc in arcs:
 
@@ -434,6 +512,12 @@ def _update_reference_leaf_pos(self):
                         beam['leaf_pos_f'][r][1] = beam['leaf_pos_right'][r]
 
     def _get_leaf_pos_in_beamlet(self, sol):
+        """
+        Get leaf position relative to beamlets.
+        :param sol: solution dictionary
+        :return: None
+
+        """
         arcs = self.arcs_dict['arcs']
         leaf_pos_mu_l = sol['leaf_pos_mu_l']
         leaf_pos_mu_r = sol['leaf_pos_mu_r']
diff --git a/portpy/photon/vmat_scp/vmat_scp_optimization.py b/portpy/photon/vmat_scp/vmat_scp_optimization.py
@@ -15,6 +15,32 @@
 
 
 class VmatScpOptimization(Optimization):
+    """
+    Class for VMAT optimization using Sequential Convex Programming (SCP) method
+
+    - **Attributes** ::
+        :param my_plan: object of class Plan
+        :param inf_matrix: object of class InfluenceMatrix
+        :param clinical_criteria: object of class ClinicalCriteria
+        :param opt_params: dictionary of vmat optimization parameters
+        :param vars: dictionary of variables
+        :param sol: Optional. solution to be passed for the optimization
+        :param arcs: Optional. object of class Arcs
+
+    :Example:
+    >>> vmat_opt = VmatScpOptimization(my_plan=my_plan, inf_matrix=inf_matrix, clinical_criteria=clinical_criteria, opt_params=vmat_opt_params)
+    >>> vmat_opt.run_sequential_cvx_algo(solver='MOSEK', verbose=True)
+
+    - **Methods** ::
+        :run_sequential_cvx_algo(solver: str, verbose: bool = False)
+            Run Sequential Convex Programming algorithm for VMAT optimization
+        :create_cvxpy_intermediate_problem()
+            Creates cvxpy problem for ECHO
+        :resolve_infeasibility_of_actual_solution(sol: dict, *args, **kwargs)
+            Resolve infeasibility of the intermediate solution
+        :create_cvxpy_actual_problem()
+            Construct actual problem for optimizing MU
+    """
     def __init__(self, my_plan: Plan, inf_matrix: InfluenceMatrix = None,
                  clinical_criteria: ClinicalCriteria = None,
                  opt_params: dict = None, vars: dict = None, sol=None, arcs: Arcs = None):
@@ -41,7 +67,10 @@ def __init__(self, my_plan: Plan, inf_matrix: InfluenceMatrix = None,
 
     def create_cvxpy_intermediate_problem(self):
         """
-        Creates cvxpy problem for ECHO
+
+        Creates intermediate cvxpy problem for optimizing interior and boundary beamlets
+        :return: None
+
         """
         # unpack data
         my_plan = self.my_plan
@@ -108,6 +137,9 @@ def create_cvxpy_intermediate_problem(self):
                     voxels_vol_cc = st.get_opt_voxels_volume_cc(struct)
                     self.vars[dO] = cp.Variable(len(voxels), pos=True)
                     obj += [(1 / cp.sum(voxels_vol_cc)) * (obj_funcs[i]['weight']*cp.sum_squares(cp.multiply(cp.sqrt(voxels_vol_cc), self.vars[dO])))]
+                    # inf_int is interior influence matrix, inf_bound_l is left boundary influence matrix, inf_bound_r is right boundary influence matrix
+                    # int_v is interior beamlet intensity, bound_v_l is left boundary beamlet intensity, bound_v_r is right boundary beamlet intensity
+                    # map_adj_int is mapping between interior variable and controlling MU for first and last beam due to inertia, map_adj_bound is similar
                     constraints += [inf_int[voxels, :] @ cp.multiply(int_v, map_adj_int) + inf_bound_l[voxels, :] @ cp.multiply(bound_v_l, map_adj_bound)
                                     + inf_bound_r[voxels, :] @ cp.multiply(bound_v_r, map_adj_bound) <= dose_gy + self.vars[dO]]
                     print('Objective function type: {} , structure:{}, dose_gy:{}, weight:{} created..'.format(
@@ -410,6 +442,7 @@ def create_interior_and_boundary_inf_matrix(self):
         """
         Create influence matrix based on interior and boundary beamlets
 
+        :return: inf_int, inf_bound_l, inf_bound_r
         """
         print("Modifying influence matrix for boundary and interior beamlets. This process may take sometime..")
         A = self.inf_matrix.A
@@ -465,6 +498,8 @@ def create_cvx_params(self, actual_sol_correction: bool = False):
 
         """
         Create cvxpy related matrices for objective function and constraints
+
+
         """
         if not actual_sol_correction:
             arcs = self.arcs.arcs_dict['arcs']
@@ -659,7 +694,9 @@ def calc_actual_objective_value(self, sol: dict, actual_sol_correction: bool = F
 
     def run_sequential_cvx_algo(self, *args, **kwargs):
         """
-        Returns sol and convergence of the sequential convex algorithm for optimizing the plan
+        Returns sol and convergence of the sequential convex algorithm for optimizing the plan.
+        Solver parameters can be passed in args.
+
         """
         # running scp algorithm:
         inner_iteration = int(0)
