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

__getitem__(key)[source]¶

Overload operator [].

Allow slicing syntax for plan retrieval.

Parameters:	key – Key corresponding to a tagged treatment plan, or index of a plan in the history’s list of plans.
Returns:	Record of solver inputs and outputs from requested treatment planning run.
Return type:	`RunRecord`
Raises:	`ValueError` – If `key` is neither the key to a tagged run nor a positive integer than or equal to the number of plans in the history.

__iadd__(other)[source]¶

Overload operator +=.

Extend case history by appending other to PlanningHistory.runs.

Parameters:	other (`RunRecord`) – Treatment plan to append to history.
Returns:	Updated `PlanningHistory` object.
Raises:	`TypeError` – If `other` not of type `RunRecord`.

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.