Planning History¶

Define classes used to record solver inputs/outputs and maintain a treatment planning history.

class history.PlanningHistory[source]¶

Class for tracking treatment plans generated by a Case.

runs¶: list of RunRecord – List of treatment plans in history, in chronological order.

run_tags¶: dict – Dictionary mapping tags of named plans to their respective indices in PlanningHistory.runs

last_feasible¶: Solver feasibility flag from most recent treatment plan.

last_info¶: Solver info from most recent treatment plan.

last_solvetime¶: Solver runtime from most recent treatment plan.

last_solvetime_exact¶: Second-pass solver runtime from most recent treatment plan.

last_x¶: Vector of beam intensities from most recent treatment plan.

last_x_exact¶: Second-pass beam intensities from most recent treatment plan.

no_run_check(property_name)[source]¶

Test whether history includes any treatment plans.

Helper method for property getter methods.

Parameters:	property_name (`str`) – Name to use in error message if exception raised.
Returns:	None
Raises:	`ValueError` – If no treatment plans exist in history, i.e., `PlanningHistory.runs` has length zero.

tag_last(tag)[source]¶

Tag most recent treatment plan in history.

Parameters:	tag – Name to apply to most recently added treatment plan. Plan can then be retrieved with slicing syntax: # (history is a :class:`PlanningHistory` instance) history[tag]
Returns:	None
Raises:	`ValueError` – If no treatment plans exist in history.

class history.RunOutput[source]¶

Record of solver outputs associated with a treatment planning run.

optimal_variables¶

dict – Dictionary of optimal variables returned by solver. At a minimum, has entries for the beam intensity vectors for the first-pass and second-pass solver runs. May include entries for:

x (beam intensities),

y (voxel doses),

mu (dual variable for constraint x>= 0), and

nu (dual variable for constraint Ax == y).

optimal_dvh_slopes¶: dict – Dictionary of optimal slopes associated with the convex restriction of each percentile-type dose constraint. Keyed by constraint ID.

solver_info¶: dict – Dictionary of solver information. At a minimum, has entries solver run time (first pass/restricted constraints, and second pass/exact constraints).

solvetime¶: Run time for first-pass solve (restricted dose constraints).

solvetime_exact¶: Run time for second-pass solve (exact dose constraints).

x¶: Optimal beam intensities from first-pass solve.

x_exact¶: Optimal beam intensities from second-pass solve.

class history.RunProfile(structures=None, use_slack=True, use_2pass=False, gamma='default')[source]¶

Record of solver input associated with a treatment planning run.

use_slack¶: bool – True if solver allowed to construct convex problem with slack variables for each dose constraint.

use_2pass¶: bool – True if solver requested to construct and solve two problems, one incorporating convex restrictions of all percentile-type dose constraints, and a second problem formulating exact constraints based on the feasible output of the first solver run.

objectives¶: dict – Dictionary of objective data associated with each structure in plan, keyed by structure labels.

constraints¶: dict – Dictionary of constraint data for each dose constraint on each structure in plan, keyed by constraint ID.

gamma¶: Master scaling applied to slack penalty term in objective when dose constraint slacks allowed.

pull_constraints(structures)[source]¶

Extract and store dictionaries of constraint data from structures.

Parameters:	structures – Iterable collection of `Structure` objects.
Returns:	None

pull_objectives(structures)[source]¶

Extract and store dictionaries of objective data from structures.

Parameters:	structures – Iterable collection of `Structure` objects.
Returns:	None

class history.RunRecord(structures=None, use_slack=True, use_2pass=False, gamma='default')[source]¶

profile¶: RunProfile – Record of the objective weights, dose constraints, and relevant solver options passed to the convex solver prior to planning.

output¶: RunOutput – Output from the solver, including optimal beam intensities, i.e., the treatment plan.

plotting_data¶: dict – Dictionary of plotting data from case, with entries corresponding to the first (and potentially only) plan formed by the solver, as well as the exact-constraint version of the same plan, if the two-pass planning method was invoked.

feasible¶: Solver feasibility flag from solver output.

info¶: Solver information from solver output.

nonzero_beam_count¶: Number of active beams in first-pass solution.

nonzero_beam_count_exact¶: Number of active beams in second-pass solution.

solvetime¶: Run time for first-pass solve (restricted dose constraints).

solvetime_exact¶: Run time for second-pass solve (exact dose constraints).

x¶: Optimal beam intensitites from first-pass solution.

x_exact¶: Optimal beam intensitites from second-pass solution.

x_pass1¶: Alias for RunRecord.x.

x_pass2¶: Alias for RunRecord.x_exact.