CVXPY solver interface¶
-
class
solver_cvxpy.
SolverCVXPY
(n_beams=None, **options)[source]¶ Interface between
conrad
andcvxpy
optimization library.SolverCVXPY
interpretsconrad
treatment planning problems (based on structures with attached objectives, dose constraints, and dose matrices) to build equivalent convex optimization problems usingcvxpy
‘s syntax.The class provides an interface to modify, run, and retrieve solutions from optimization problems that can be executed on a CPU (or GPU, if
scs
installed with appropriate backend libraries).-
problem
¶ cvxpy.Minimize
CVXPY representation of optimization problem.
-
constraint_dual_vars
¶ dict
Dictionary, keyed by constraint ID, of dual variables associated with each dose constraint in the CVXPY problem representation. The dual variables’ values are stored here after each optimization run for access by clients of the
SolverCVXPY
object.
-
build
(structures, exact=False, **options)[source]¶ Update
cvxpy
optimization based on structure data.Extract dose matrix, target doses, and objective weights from structures.
Use doses and weights to add minimization terms to
SolverCVXPY.problem.objective
. Use dose constraints to extendSolverCVXPY.problem.constraints
.(When constraints include slack variables, a penalty on each slack variable is added to the objective.)
Parameters: structures – Iterable collection of Structure
objects.Returns: String documenting how data in structures
were parsed to form an optimization problem.Return type: str
-
clear
()[source]¶ Reset
cvxpy
problem to minimal representation.- The minmal representation consists of:
- An empty objective (Minimize 0),
- A nonnegativity constraint on the vector of beam intensities (\(x \ge 0\)).
- Reset dictionaries of:
- Slack variables (all dose constraints),
- Dual variables (all dose constraints), and
- Slope variables for convex restrictions (percentile dose constraints).
-
get_dual_value
(constr_id)[source]¶ Retrieve dual variable for queried constraint.
Parameters: constr_id ( str
) – ID of queried constraint.Returns: None
ifconstr_id
does not correspond to a registered dual variable. Value of dual variable otherwise.
-
get_dvh_slope
(constr_id)[source]¶ Retrieve slope variable for queried constraint.
Parameters: constr_id ( str
) – ID of queried constraint.Returns: None
ifconstr_id
does not correspond to a registered slope variable. ‘NaN’ (asnumpy.np.nan
) if constraint built as exact. Reciprocal of slope variable otherwise.
-
get_slack_value
(constr_id)[source]¶ Retrieve slack variable for queried constraint.
Parameters: constr_id ( str
) – ID of queried constraint.Returns: None
ifconstr_id
does not correspond to a registered slack variable.0
if corresponding constraint built without slack. Value of slack variable if constraint built with slack.
-
init_problem
(n_beams, use_slack=True, use_2pass=False, **options)[source]¶ Initialize
cvxpy
variables and problem components.Create a
cvxpy.Variable
of length-n_beams
to representthe beam intensities. InvokeSolverCVXPY.clear()
to build minimal problem.Parameters: - n_beams (
int
) – Number of candidate beams in plan. - use_slack (
bool
, optional) – IfTrue
, next invocation ofSolverCVXPY.build()
will build dose constraints with slack variables. - use_2pass (
bool
, optional) – IfTrue
, next invocation ofSolverCVXPY.build()
will build percentile-type dose constraints as exact constraints instead of convex restrictions thereof, assuming other requirements are met. - **options – Arbitrary keyword arguments.
Returns: None
- n_beams (
-
n_beams
¶ Number of candidate beams in treatment plan.
-
objective_value
¶ Objective value at end of solve.
-
solve
(**options)[source]¶ Execute optimization of a previously built planning problem.
Parameters: **options – Keyword arguments specifying solver options, passed to cvxpy.Problem.solve()
.Returns: True
ifcvxpy
solver converged.Return type: bool
Raises: ValueError
– If specified solver is neither ‘SCS’ nor ‘ECOS’.
-
solveiters
¶ Number of solver iterations performed.
-
solvetime
¶ Solver run time.
-
status
¶ Solver status.
-
x
¶ Vector variable of beam intensities, x.
-
x_dual
¶ Dual variable corresponding to constraint x >= 0.
-