opentps.core.processing.planOptimization package

Subpackages

Submodules

opentps.core.processing.planOptimization.optimizationWorkflows module

optimizeIMPT(plan: RTPlan, planStructure: PlanDesign)

Optimizes an IMPT plan

Parameters:

  • plan (RTPlan) – The plan to be optimized

  • planStructure (PlanDesign) – The plan design containing the optimization parameters

opentps.core.processing.planOptimization.planInitializer module

class BeamInitializer

Bases: object

This class is used to initialize a beam with spots and layers.

Variables:

  • calibration (AbstractCTCalibration) – The CT calibration used to convert the CT image to RSP image.

  • spotSpacing (float) – The spacing between spots in mm.

  • layerSpacing (float) – The spacing between layers in mm.

  • targetMargin (float) – The margin around the target in mm.

  • beam (PlanIonBeam) – The beam to initialize.

initializeBeam()

Initialize the beam with spots and layers.

class PlanInitializer

Bases: object

placeSpots(spotSpacing: float, layerSpacing: float, targetMargin: float = 0.0, layersToSpacingAlignment=False, proximalLayers=1, distalLayers=1)

opentps.core.processing.planOptimization.planOptimization module

class ARCPTPlanOptimizer(method, plan, **kwargs)

Bases: PlanOptimizer

This class is used to optimize an arc proton therapy plan (ARCPT). It inherits from PlanOptimizer.

Variables:

method (str) – The optimization method. It can be one of the following: - ‘FISTA’ - ‘LS’ - ‘MIP’ - ‘SPArcling’

class BoundConstraintsOptimizer(plan: RTPlan, method='Scipy-LBFGS', bounds=(0.02, 5), **kwargs)

Bases: PlanOptimizer

This class is used to optimize a plan with bound constraints. It inherits from PlanOptimizer.

Variables:

bounds (tuple (default: (0.02, 5))) – The bounds.

formatBoundsForSolver(bounds=None)

Format the bounds for the solver with respect to the number of fractions.

Parameters:

bounds (tuple (default: None)) – The bounds. If None, the bounds are set to self.bounds.

Returns:

The formatted bounds.

Return type:

list

optimize(nIterations=None)

Optimize the plan.

Parameters:

nIterations (tuple (default: None)) – The number of iterations for the first and second optimization. If None, the number of iterations is set to self.opti_params[‘maxit’] // 2 if first bound is 0, else it is set to self.opti_params[‘maxit’].

Returns:

  • numpy.ndarray – The optimized weights.

  • numpy.ndarray – The total dose.

  • float – The cost.

property xSquared
class IMPTPlanOptimizer(method, plan: RTPlan, **kwargs)

Bases: PlanOptimizer

This class is used to optimize an Intensity Modulated Proton Therapy (IMPT) plan. It inherits from PlanOptimizer. :ivar method: The optimization method. It can be one of the following:

  • ‘Scipy-BFGS’

  • ‘Scipy-LBFGS’

  • ‘Gradient’

  • ‘BFGS’

  • ‘LBFGS’

  • ‘FISTA’

  • ‘LP’

getConvergenceData()

Get the convergence data.

Returns:

The convergence data.

Return type:

dict

class PlanOptimizer(plan: RTPlan, **kwargs)

Bases: object

This class is used to optimize a plan.

Variables:

  • plan (RTPlan) – The plan to optimize.

  • opti_params (dict) – The optimization parameters.

  • functions (list) – The list of functions to optimize.

  • solver (Solver (default: bfgs.ScipyOpt('L-BFGS-B'))) – The solver to use. By default, no bounds are set. Machine delivery constraints can (and should) be enforced by setting the bounds.

  • thresholdSpotRemoval (float) – The threshold weight below which spots are removed from the plan and beamlet matrix.

  • xSquared (bool) – If True, the weights are squared. True by default to avoid negative weights.

  • GPU_acceleration (bool (default : False)) – If True, the evaluation of the doseFidelity function is done with cupy (this attribute should only be modified with the “use_GPU_acceleration” function)

computeDose()
getConvergenceData(method)

Get the convergence data.

Parameters:

method (str) – The optimization method.

Returns:

The convergence data.

Return type:

dict

initializeFidObjectiveFunction()

Initialize the dose fidelity objective function.

initializeWeights()

Initialize the weights.

Returns:

x0 – The weights.

Return type:

numpy.ndarray

optimize()

Optimize the plan.

Returns:

  • numpy.ndarray – The optimized weights.

  • numpy.ndarray – The total dose.

  • float – The cost.

postProcess(result)

Post-process the optimization result. !! The spots and the according weight bellow the thresholdSpotRemoval are removed from the plan and beamlet matrix !! The optimized weights are saved in self.plan.spotMUs

Parameters:

result (dict) – The optimization result.

Returns:

  • numpy.ndarray – The total dose.

  • float – The value of the objective function.

stop_GPU_accelration()

stop the use of GPU acceleration

use_GPU_acceleration()

Enable the uses of the GPU via cupy and cupyx (both library need to be installed as well as CUDA).

property xSquared

opentps.core.processing.planOptimization.planOptimizationConfig module

class PlanOptimizationConfig(*args, **kwargs)

Bases: AbstractApplicationConfig

This class is used to store the configuration of the plan optimization. Inherit from AbstractApplicationConfig.

Attribute

imptSolverstr

The solver used for the IMPT optimization. Default is ‘Scipy-LBFGS’.

imptMaxIterint

The maximum number of iterations for the IMPT optimization. Default is 100.

property imptMaxIter: int
property imptSolver: str

opentps.core.processing.planOptimization.planPreprocessing module

class ExtendedBeam

Bases: PlanIonBeam

Class to extend the PlanIonBeam class with a list of layers. Inherits from PlanIonBeam.

Variables:

laverIndices (Sequence[int]) – The indices of the layers in the beam.

classmethod fromBeam(beam: PlanIonBeam)

Creates a new ExtendedBeam from a PlanIonBeam.

Parameters:

beam (PlanIonBeam) – The beam to copy.

Returns:

The new beam.

Return type:

ExtendedBeam

property layersIndices: Sequence[int]
class ExtendedPlanIonLayer(nominalEnergy: float = 0.0)

Bases: PlanIonLayer

Class to extend the PlanIonLayer class with a list of spots. Inherits from PlanIonLayer.

Variables:

  • spots (Sequence[PlanIonSpot]) – The spots in the layer.

  • spotIndices (Sequence[int]) – The indices of the spots in the layer.

  • id (int) – The id of the layer.

  • beamID (int) – The id of the beam the layer belongs to.

classmethod fromLayer(layer: PlanIonLayer)

Creates a new ExtendedPlanIonLayer from a PlanIonLayer.

Parameters:

layer (PlanIonLayer) – The layer to copy.

Returns:

The new layer.

Return type:

ExtendedPlanIonLayer

property spotIndices: Sequence[int]
property spots: Sequence[PlanIonSpot]
extendPlanLayers(plan: RTPlan) → RTPlan

Extends the plan with a list of layers and spots for each beam.

Parameters:

plan (RTPlan) – The plan to extend.

Returns:

The extended plan.

Return type:

RTPlan

opentps.core.processing.planOptimization.tools module

class WeightStructure(plan: RTPlan)

Bases: object

This class defines the weight structure object interface. This class is required to generate arc plans It is intended to define several structures and utilities such as list of weights/energies grouped by layer or by beam but also functions computing ELST, sparsity of the plan, etc.

Variables:

  • plan (RTPlan) – The plan to be optimized

  • beamletMatrix (scipy.sparse.csc_matrix) – The beamlet matrix of the plan

  • x (numpy.ndarray) – The weights of the beamlets

  • nSpots (int) – The total number of spots in the plan

  • nBeams (int) – The total number of beams in the plan

  • nLayers (int) – The total number of layers in the plan

  • nSpotsInLayer (numpy.ndarray) – The number of spots in each layer

  • nSpotsInBeam (numpy.ndarray) – The number of spots in each beam

  • nLayersInBeam (numpy.ndarray) – The number of layers in each beam

  • energyLayers (list) – The energies of each layer

  • nSpotsGrouped (int) – The total number of spots in the plan after grouping

  • sparseMatrixGrouped (scipy.sparse.csc_matrix) – The beamlet matrix of the plan after grouping

  • xGrouped (numpy.ndarray) – The weights of the beamlets after grouping

  • spotsGrouped (list) – The list of spots after grouping

  • beamsGrouped (list) – The list of beams after grouping

  • layersGrouped (list) – The list of layers after grouping

  • spotNewID (list) – The list of new spot IDs after grouping

computeELSparsity(x, nLayers)

return the percentage of active energy layers in the plan (non-null weight) input: - x: spot weights - nLayers: threshold on number of active layers in each beam

Parameters:

  • x (numpy.ndarray) – The weights of the beamlets

  • nLayers (int) – The threshold on number of active layers in each beam

Returns:

The percentage of active energy layers in the plan (non-null weight) = Sparsity

Return type:

float

computeIrradiationTime(x)

return the irradiation time of the plan (in seconds)

Parameters:

x (numpy.ndarray) – The weights of the beamlets

Returns:

  • float – The Energy layer switching time (ELST) in seconds

  • int – The number of upwards energy switching

  • int – The number of downwards energy switching

computeNOfLayers()

return total number of energy layers in the plan

Returns:

The total number of energy layers in the plan

Return type:

int

getBeamStructure(x)

transform 1d weight vector into list of layers vectors ordered by beam [[[b1e1],[b1e2],…],[[b2e1],[b2e2],…],…,[[bBe1],…,[bBeE]]]

Parameters:

x (numpy.ndarray) – The weights of the beamlets

Returns:

The list of layers vectors ordered by beam

Return type:

list

getEnergyStructure(x)

transform 1d weight vector into list of weights vectors ordered by energy layer and beam [b1e1,b1e2,…,b2e1,b2e2,…,bBeE]

Parameters:

x (numpy.ndarray) – The weights of the beamlets

Returns:

The list of weights vectors ordered by energy layer and beam

Return type:

list

getListOfActiveEnergies(x, regCalc=True)

return list of energies of the active layers (non-null weight) ! zero if layer is not active (len = nLayers)

Parameters:

  • x (numpy.ndarray) – The weights of the beamlets

  • regCalc (bool (default=True)) – If True, the list of energies of the active layers is returned for regularized calculation

Returns:

The list of energies of the active layers

Return type:

list

getListOfActiveLayersInBeams(x)

return list of number of active energy layers in each beam (len = nBeams)

Parameters:

x (numpy.ndarray) – The weights of the beamlets

Returns:

The list of number of active energy layers in each beam

Return type:

list

getMUPerBeam(x)

return list of MUs in each beam (len=nBeams)

Parameters:

x (numpy.ndarray) – The weights of the beamlets

Returns:

The list of MUs in each beam

Return type:

list

getMUPerLayer(x)

return list of MUs in each layer (len=nLayers)

Parameters:

x (numpy.ndarray) – The weights of the beamlets

Returns:

The list of MUs in each layer

Return type:

list

getSpotIndex()

return 3 lists of size=nSpots: *spotsBeams: beam index of each spot *spotsLayers: layer index of each spot *spotsEnergies: energy of each spot

Returns:

  • list – The list of beam indices of each spot

  • list – The list of layer indices of each spot

  • list – The list of energies of each spot

getWeightsStruct()

return 3 arrays and 1 list of arrays * nOfSpotsInLayer: array with number of spots in each layer (size=nLayers) * nOfSpotsInBeam: array with number of spots in each beam (size=nBeams) * nOfLayersInBeam: array with number of layers in each beam (size=nBeams) * energies: list of arrays with energies of each beam (len=nBeams)

Returns:

  • numpy.ndarray – The number of spots in each layer

  • numpy.ndarray – The number of spots in each beam

  • numpy.ndarray – The number of layers in each beam

groupSol()

group solution x (weights) into the object

groupSpots(groupSpotsby=10)

Group spot by a given parameter. Allows to get a faster optimal solution to be used as a warm start for higher scale problem

Parameters:

groupSpotsby (int (default=10)) – The number of spots to be grouped

isActivated(el: PlanIonLayer) → bool

return True if layer is activated (non-null weight)

Parameters:

el (PlanIonLayer) – The layer to be checked

Returns:

True if layer is activated (non-null weight)

Return type:

bool

loadSolution(x)

load solution x (weights) into the object

ungroupSol()

ungroup solution x (weights) into the object

evaluateClinical(dose, contours, clinDict)

Evaluate clinical constraints

Parameters:

  • dose (numpy.ndarray) – The dose matrix

  • contours (list) – The list of contours

  • clinDict (dict) – The dictionary of clinical constraints

getEnergyWeights(energyList)

return list of energy layer weights (len = nLayers); if upward energy switching or same energy: cost = 5.5 if downward energy switching: cost = 0.6 [FIX ME]: first layer ?

Parameters:

energyList (list) – The list of energies of each layer

Returns:

The list of energy layer weights

Return type:

list

Module contents