CVXPY solver interface

class solver_cvxpy.SolverCVXPY(n_beams=None, **options)

Interface between conrad and cvxpy optimization library.

SolverCVXPY interprets conrad treatment planning problems (based on structures with attached objectives, dose constraints, and dose matrices) to build equivalent convex optimization problems using cvxpy‘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)

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 extend SolverCVXPY.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()

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)

Retrieve dual variable for queried constraint.

Parameters:constr_id (str) – ID of queried constraint. Returns:None if constr_id does not correspond to a registered dual variable. Value of dual variable otherwise.

get_dvh_slope(constr_id)

Retrieve slope variable for queried constraint.

Parameters:constr_id (str) – ID of queried constraint. Returns:None if constr_id does not correspond to a registered slope variable. ‘NaN’ (as numpy.np.nan) if constraint built as exact. Reciprocal of slope variable otherwise.

get_slack_value(constr_id)

Retrieve slack variable for queried constraint.

Parameters:constr_id (str) – ID of queried constraint. Returns:None if constr_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)

Initialize cvxpy variables and problem components.

Create a cvxpy.Variable of length-n_beams to representthe beam intensities. Invoke SolverCVXPY.clear() to build minimal problem.

Parameters:

• n_beams (int) – Number of candidate beams in plan.
• use_slack (bool, optional) – If True, next invocation of SolverCVXPY.build() will build dose constraints with slack variables.
• use_2pass (bool, optional) – If True, next invocation of SolverCVXPY.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

Number of candidate beams in treatment plan.

objective_value

Objective value at end of solve.

solve(**options)

Execute optimization of a previously built planning problem.

Parameters:**options – Keyword arguments specifying solver options, passed to cvxpy.Problem.solve(). Returns:True if cvxpy 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.