Drake
MathematicalProgramResult Class Referencefinal

Detailed Description

The result returned by MathematicalProgram::Solve().

It stores the solvers::SolutionResult (whether the program is solved to optimality, detected infeasibility, etc), the optimal value for the decision variables, the optimal cost, and solver specific details.

#include <drake/solvers/mathematical_program_result.h>

Public Member Functions

 MathematicalProgramResult ()
 Constructs the result. More...
 
bool is_success () const
 Returns true if the optimization problem is solved successfully; false otherwise. More...
 
void set_decision_variable_index (std::unordered_map< symbolic::Variable::Id, int > decision_variable_index)
 Sets decision_variable_index mapping, that maps each decision variable to its index in the aggregated vector containing all decision variables in MathematicalProgram. More...
 
void set_solution_result (SolutionResult solution_result)
 Sets SolutionResult. More...
 
const Eigen::VectorXd & get_x_val () const
 Gets the decision variable values. More...
 
SolutionResult get_solution_result () const
 Gets SolutionResult. More...
 
void set_x_val (const Eigen::VectorXd &x_val)
 Sets the decision variable values. More...
 
template<typename C >
void set_dual_solution (const Binding< C > &constraint, const Eigen::Ref< const Eigen::VectorXd > &dual_solution)
 Sets the dual solution associated with a given constraint. More...
 
double get_optimal_cost () const
 Gets the optimal cost. More...
 
void set_optimal_cost (double optimal_cost)
 Sets the optimal cost. More...
 
const SolverIdget_solver_id () const
 Gets the solver ID. More...
 
void set_solver_id (const SolverId &solver_id)
 Sets the solver ID. More...
 
template<typename Solver >
const Solver::Details & get_solver_details () const
 Gets the solver details for the Solver that solved the program. More...
 
const AbstractValueget_abstract_solver_details () const
 (Advanced.) Gets the type-erased solver details. More...
 
template<typename T >
T & SetSolverDetailsType ()
 (Advanced.) Forces the solver_details to be stored using the given type T. More...
 
const Eigen::VectorXd & GetSolution () const
 Gets the solution of all decision variables. More...
 
template<typename Derived >
std::enable_if< std::is_same< typename Derived::Scalar, symbolic::Variable >::value, Eigen::Matrix< double, Derived::RowsAtCompileTime, Derived::ColsAtCompileTime > >::type GetSolution (const Eigen::MatrixBase< Derived > &var) const
 Gets the solution of an Eigen matrix of decision variables. More...
 
double GetSolution (const symbolic::Variable &var) const
 Gets the solution of a single decision variable. More...
 
symbolic::Expression GetSolution (const symbolic::Expression &e) const
 Substitutes the value of all decision variables into the Expression. More...
 
symbolic::Polynomial GetSolution (const symbolic::Polynomial &p) const
 Substitutes the value of all decision variables into the coefficients of the symbolic polynomial. More...
 
template<typename Derived >
std::enable_if< std::is_same< typename Derived::Scalar, symbolic::Expression >::value, Eigen::Matrix< symbolic::Expression, Derived::RowsAtCompileTime, Derived::ColsAtCompileTime > >::type GetSolution (const Eigen::MatrixBase< Derived > &m) const
 Substitutes the value of all decision variables into the Matrix<Expression>. More...
 
template<typename C >
Eigen::VectorXd GetDualSolution (const Binding< C > &constraint) const
 Gets the dual solution associated with a constraint. More...
 
template<typename Evaluator >
Eigen::VectorXd EvalBinding (const Binding< Evaluator > &binding) const
 Evaluate a Binding at the solution. More...
 
Implements CopyConstructible, CopyAssignable, MoveConstructible, MoveAssignable
 MathematicalProgramResult (const MathematicalProgramResult &)=default
 
MathematicalProgramResultoperator= (const MathematicalProgramResult &)=default
 
 MathematicalProgramResult (MathematicalProgramResult &&)=default
 
MathematicalProgramResultoperator= (MathematicalProgramResult &&)=default
 
Solution Pools

Some solvers (like Gurobi, Cplex, etc) can store a pool of (suboptimal) solutions for mixed integer programming model.

template<typename Derived >
std::enable_if< std::is_same< typename Derived::Scalar, symbolic::Variable >::value, Eigen::Matrix< double, Derived::RowsAtCompileTime, Derived::ColsAtCompileTime > >::type GetSuboptimalSolution (const Eigen::MatrixBase< Derived > &var, int solution_number) const
 Gets the suboptimal solution corresponding to a matrix of decision variables. More...
 
double GetSuboptimalSolution (const symbolic::Variable &var, int solution_number) const
 Gets the suboptimal solution of a decision variable. More...
 
int num_suboptimal_solution () const
 Number of suboptimal solutions stored inside MathematicalProgramResult. More...
 
double get_suboptimal_objective (int solution_number) const
 Gets the suboptimal objective value. More...
 
void AddSuboptimalSolution (double suboptimal_objective, const Eigen::VectorXd &suboptimal_x)
 Adds the suboptimal solution to the result. More...
 
Get infeasible constraints

Some solvers (e.g. SNOPT) provide a "best-effort solution" even when they determine that a problem is infeasible. This method will return the descriptions corresponding to the constraints for which CheckSatisfied evaluates to false given the reported solution. This can be very useful for debugging. Note that this feature is available only when the optimization problem is solved through certain solvers (like SNOPT, IPOPT) which provide a "best-effort solution". Some solvers (like Gurobi) don't return the "best-effort solution" when the problem is infeasible, and this feature is hence unavailable.

std::vector< std::string > GetInfeasibleConstraintNames (const MathematicalProgram &prog, std::optional< double > tolerance=std::nullopt) const
 See get_infeasible_constraints for more information. More...
 
std::vector< Binding< Constraint > > GetInfeasibleConstraints (const MathematicalProgram &prog, std::optional< double > tolerance=std::nullopt) const
 See get_infeasible_constraints for more information. More...
 

Constructor & Destructor Documentation

◆ MathematicalProgramResult() [1/3]

◆ MathematicalProgramResult() [2/3]

◆ MathematicalProgramResult() [3/3]

Constructs the result.

Note
The solver_details is set to nullptr.

Member Function Documentation

◆ AddSuboptimalSolution()

void AddSuboptimalSolution ( double  suboptimal_objective,
const Eigen::VectorXd &  suboptimal_x 
)

Adds the suboptimal solution to the result.

See solution pools.

Parameters
suboptimal_objectiveThe objective value computed from this suboptimal solution.
suboptimal_xThe values of the decision variables in this suboptimal solution.

◆ EvalBinding()

Eigen::VectorXd EvalBinding ( const Binding< Evaluator > &  binding) const

Evaluate a Binding at the solution.

Parameters
bindingA binding between a constraint/cost and the variables.
Precondition
The binding.variables() must be the within the decision variables in the MathematicalProgram that generated this MathematicalProgramResult.
The user must have called set_decision_variable_index() function.

◆ get_abstract_solver_details()

const AbstractValue& get_abstract_solver_details ( ) const

(Advanced.) Gets the type-erased solver details.

Most users should use get_solver_details() instead. Throws an error if the solver_details has not been set.

◆ get_optimal_cost()

double get_optimal_cost ( ) const

Gets the optimal cost.

◆ get_solution_result()

SolutionResult get_solution_result ( ) const

Gets SolutionResult.

◆ get_solver_details()

const Solver::Details& get_solver_details ( ) const

Gets the solver details for the Solver that solved the program.

Throws an error if the solver_details has not been set.

◆ get_solver_id()

const SolverId& get_solver_id ( ) const

Gets the solver ID.

◆ get_suboptimal_objective()

double get_suboptimal_objective ( int  solution_number) const

Gets the suboptimal objective value.

See solutionpools".

Parameters
solution_numberThe index of the sub-optimal solution.
Precondition
solution_number should be in the range [0, num_suboptimal_solution()).

◆ get_x_val()

const Eigen::VectorXd& get_x_val ( ) const

Gets the decision variable values.

◆ GetDualSolution()

Eigen::VectorXd GetDualSolution ( const Binding< C > &  constraint) const

Gets the dual solution associated with a constraint.

For constraints in the form lower <= f(x) <= upper (including linear inequality, linear equality, bounding box constraints, and general nonlinear constraints), we interpret the dual variable value as the "shadow price" of the original problem. Namely if we change the constraint bound by one unit (each unit is infinitesimally small), the change of the optimal cost is the value of the dual solution times the unit. Mathematically dual_solution = ∂optimal_cost / ∂bound.

For a linear equality constraint Ax = b where b ∈ ℝⁿ, the vector of dual variables has n rows, and dual_solution(i) is the value of the dual variable for the constraint A(i,:)*x = b(i).

For a linear inequality constraint lower <= A*x <= upper where lower and upper ∈ ℝⁿ, dual_solution also has n rows. dual_solution(i) is the value of the dual variable for constraint lower(i) <= A(i,:)*x <= upper(i). If neither side of the constraint is active, then dual_solution(i) is 0. If the left hand-side lower(i) <= A(i, :)*x is active (meaning lower(i) = A(i, :)*x at the solution), then dual_solution(i) is non-negative (because the objective is to minimize a cost, increasing the lower bound means the constraint set is tighter, hence the optimal solution cannot decrease. Thus the shadow price is non-negative). If the right hand-side A(i, :)*x<=upper(i) is active (meaning A(i,:)*x=upper(i) at the solution), then dual_solution(i) is non-positive.

For a bounding box constraint lower <= x <= upper, the interpretation of the dual solution is the same as the linear inequality constraint.

For a Lorentz cone or rotated Lorentz cone constraint that Ax + b is in the cone, depending on the solver, the dual solution has different meanings:

  1. If the solver is Gurobi, then the user can only obtain the dual solution by explicitly setting the options for computing dual solution.
    auto constraint = prog.AddLorentzConeConstraint(...);
    GurobiSolver solver;
    // Explicitly tell the solver to compute the dual solution for Lorentz
    // cone or rotated Lorentz cone constraint, check
    // https://www.gurobi.com/documentation/9.0/refman/qcpdual.html for
    // more information.
    SolverOptions options;
    options.SetOption(GurobiSolver::id(), "QCPDual", 1);
    MathematicalProgramResult result = solver.Solve(prog, {}, options);
    Eigen::VectorXd dual_solution = result.GetDualSolution(constraint);
    The dual solution has size 1, dual_solution(0) is the shadow price for the constraint z₁² + ... +zₙ² ≤ z₀² for Lorentz cone constraint, and the shadow price for the constraint z₂² + ... +zₙ² ≤ z₀z₁ for rotated Lorentz cone constraint, where z is the slack variable representing z = A*x+b and z in the Lorentz cone/rotated Lorentz cone.
  2. For nonlinear solvers like IPOPT, the dual solution for Lorentz cone constraint (with EvalType::kConvex) is the shadow price for z₀ - sqrt(z₁² + ... +zₙ²) ≥ 0, where z = Ax+b.
  3. For other convex conic solver such as SCS, Mosek, CSDP, etc, the dual solution to the (rotated) Lorentz cone constraint doesn't have the "shadow price" interpretation, but should lie in the dual cone, and satisfy the KKT condition. For more information, refer to https://docs.mosek.com/9.2/capi/prob-def-conic.html#duality-for-conic-optimization as an explanation.

The interpretation for the dual variable to conic constraint x ∈ K can be different. Here K is a convex cone, including exponential cone, power cone, PSD cone, etc. When the problem is solved by a convex solver (like SCS, Mosek, CSDP, etc), often it has a dual variable z ∈ K*, where K* is the dual cone. Here the dual variable DOESN'T have the interpretation of "shadow price", but should satisfy the KKT condition, while the dual variable stays inside the dual cone.

◆ GetInfeasibleConstraintNames()

std::vector<std::string> GetInfeasibleConstraintNames ( const MathematicalProgram prog,
std::optional< double >  tolerance = std::nullopt 
) const

See get_infeasible_constraints for more information.

Parameters
progThe MathematicalProgram that was solved to obtain this MathematicalProgramResult.
toleranceA positive tolerance to check the constraint violation. If no tolerance is provided, this method will attempt to obtain the constraint tolerance from the solver, or insert a conservative default tolerance.

Note: Currently most constraints have the empty string as the description, so the NiceTypeName of the Constraint is used instead. Use e.g. prog.AddConstraint(x == 1).evaluator().set_description(str) to make this method more specific/useful.

◆ GetInfeasibleConstraints()

std::vector<Binding<Constraint> > GetInfeasibleConstraints ( const MathematicalProgram prog,
std::optional< double >  tolerance = std::nullopt 
) const

See get_infeasible_constraints for more information.

Parameters
progThe MathematicalProgram that was solved to obtain this MathematicalProgramResult.
toleranceA positive tolerance to check the constraint violation. If no tolerance is provided, this method will attempt to obtain the constraint tolerance from the solver, or insert a conservative default tolerance.
Returns
infeasible_bindings A vector of all infeasible bindings (constraints together with the associated variables) at the best-effort solution.

◆ GetSolution() [1/6]

const Eigen::VectorXd& GetSolution ( ) const

Gets the solution of all decision variables.

◆ GetSolution() [2/6]

std::enable_if< std::is_same<typename Derived::Scalar, symbolic::Variable>::value, Eigen::Matrix<double, Derived::RowsAtCompileTime, Derived::ColsAtCompileTime> >::type GetSolution ( const Eigen::MatrixBase< Derived > &  var) const

Gets the solution of an Eigen matrix of decision variables.

Template Parameters
DerivedAn Eigen matrix containing Variable.
Parameters
varThe decision variables.
Returns
The value of the decision variable after solving the problem.

◆ GetSolution() [3/6]

double GetSolution ( const symbolic::Variable var) const

Gets the solution of a single decision variable.

Parameters
varThe decision variable.
Returns
The value of the decision variable after solving the problem.
Exceptions
invalid_argumentif var is not captured in the mapping decision_variable_index, as the input argument of set_decision_variable_index().

◆ GetSolution() [4/6]

symbolic::Expression GetSolution ( const symbolic::Expression e) const

Substitutes the value of all decision variables into the Expression.

Parameters
eThe decision variable.
Returns
the Expression that is the result of the substitution.

◆ GetSolution() [5/6]

symbolic::Polynomial GetSolution ( const symbolic::Polynomial p) const

Substitutes the value of all decision variables into the coefficients of the symbolic polynomial.

Parameters
pA symbolic polynomial. Its indeterminates can't intersect with the set of decision variables of the MathematicalProgram from which this result is obtained.
Returns
the symbolic::Polynomial as the result of the substitution.

◆ GetSolution() [6/6]

std::enable_if< std::is_same<typename Derived::Scalar, symbolic::Expression>::value, Eigen::Matrix<symbolic::Expression, Derived::RowsAtCompileTime, Derived::ColsAtCompileTime> >::type GetSolution ( const Eigen::MatrixBase< Derived > &  m) const

Substitutes the value of all decision variables into the Matrix<Expression>.

Template Parameters
DerivedAn Eigen matrix containing Expression.
Returns
the Matrix<Expression> that is the result of the substitution.

◆ GetSuboptimalSolution() [1/2]

std::enable_if< std::is_same<typename Derived::Scalar, symbolic::Variable>::value, Eigen::Matrix<double, Derived::RowsAtCompileTime, Derived::ColsAtCompileTime> >::type GetSuboptimalSolution ( const Eigen::MatrixBase< Derived > &  var,
int  solution_number 
) const

Gets the suboptimal solution corresponding to a matrix of decision variables.

See solution pools

Parameters
varThe decision variables.
solution_numberThe index of the sub-optimal solution.
Precondition
solution_number should be in the range [0, num_suboptimal_solution()).
Returns
The suboptimal values of the decision variables after solving the problem.

◆ GetSuboptimalSolution() [2/2]

double GetSuboptimalSolution ( const symbolic::Variable var,
int  solution_number 
) const

Gets the suboptimal solution of a decision variable.

See solution pools

Parameters
varThe decision variable.
solution_numberThe index of the sub-optimal solution.
Precondition
solution_number should be in the range [0, num_suboptimal_solution()).
Returns
The suboptimal value of the decision variable after solving the problem.

◆ is_success()

bool is_success ( ) const

Returns true if the optimization problem is solved successfully; false otherwise.

For more information on the solution status, the user could call get_solver_details() to obtain the solver-specific solution status.

◆ num_suboptimal_solution()

int num_suboptimal_solution ( ) const

Number of suboptimal solutions stored inside MathematicalProgramResult.

See solution pools.

◆ operator=() [1/2]

MathematicalProgramResult& operator= ( const MathematicalProgramResult )
default

◆ operator=() [2/2]

◆ set_decision_variable_index()

void set_decision_variable_index ( std::unordered_map< symbolic::Variable::Id, int decision_variable_index)

Sets decision_variable_index mapping, that maps each decision variable to its index in the aggregated vector containing all decision variables in MathematicalProgram.

Initialize x_val to NAN.

◆ set_dual_solution()

void set_dual_solution ( const Binding< C > &  constraint,
const Eigen::Ref< const Eigen::VectorXd > &  dual_solution 
)

Sets the dual solution associated with a given constraint.

◆ set_optimal_cost()

void set_optimal_cost ( double  optimal_cost)

Sets the optimal cost.

◆ set_solution_result()

void set_solution_result ( SolutionResult  solution_result)

Sets SolutionResult.

◆ set_solver_id()

void set_solver_id ( const SolverId solver_id)

Sets the solver ID.

◆ set_x_val()

void set_x_val ( const Eigen::VectorXd &  x_val)

Sets the decision variable values.

◆ SetSolverDetailsType()

T& SetSolverDetailsType ( )

(Advanced.) Forces the solver_details to be stored using the given type T.

Typically, only an implementation of SolverInterface will call this method. If the storage was already typed as T, this is a no-op. If there were not any solver_details previously, or if it was of a different type, initializes the storage to a default-constructed T. Returns a reference to the mutable solver_details object. The reference remains valid until the next call to this method, or until this MathematicalProgramResult is destroyed.


The documentation for this class was generated from the following file: