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...

const std::optional< std::unordered_map< symbolic::Variable::Id, int > > &	get_decision_variable_index () const
	Gets decision_variable_index. 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 SolverId &	get_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 AbstractValue &	get_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_t< std::is_same_v< typename Derived::Scalar, symbolic::Variable >, MatrixLikewise< double, Derived > >	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...

void	SetSolution (const symbolic::Variable &var, double value)
	Resets the solution of a single decision variable that is already registered with this result. 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_t< std::is_same_v< typename Derived::Scalar, symbolic::Expression >, MatrixLikewise< symbolic::Expression, Derived > >	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

MathematicalProgramResult &	operator= (const MathematicalProgramResult &)=default

	MathematicalProgramResult (MathematicalProgramResult &&)=default

MathematicalProgramResult &	operator= (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_t< std::is_same_v< typename Derived::Scalar, symbolic::Variable >, MatrixLikewise< double, Derived > >	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 ( const MathematicalProgramResult & )

default

◆ MathematicalProgramResult() [2/3]

MathematicalProgramResult ( MathematicalProgramResult && )

default

◆ MathematicalProgramResult() [3/3]

MathematicalProgramResult ( )

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_objective	The objective value computed from this suboptimal solution.
suboptimal_x	The 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

binding A 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_decision_variable_index()

const std::optional<std::unordered_map<symbolic::Variable::Id, int> >& get_decision_variable_index ( ) const

Gets decision_variable_index.

◆ 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_number The 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:

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/10.1/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.
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.
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/10.1/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.

When K is a psd cone, the returned dual solution is the lower triangle of the dual symmetric psd matrix. Namely for the primal problem

min trace(C*X) s.t A(X) = b X is psd

the dual is

max b'*y s.t A'(y) - C = Z Z is psd.

We return the lower triangular part of Z. You can call drake::math::ToSymmetricMatrixFromLowerTriangularColumns to get the matrix Z.

◆ GetInfeasibleConstraintNames()

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

See get_infeasible_constraints for more information.

Parameters

prog	The MathematicalProgram that was solved to obtain `this` MathematicalProgramResult.
tolerance	A 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

prog	The MathematicalProgram that was solved to obtain `this` MathematicalProgramResult.
tolerance	A 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_t< std::is_same_v<typename Derived::Scalar, symbolic::Variable>, MatrixLikewise<double, Derived> > GetSolution ( const Eigen::MatrixBase< Derived > & var ) const

Gets the solution of an Eigen matrix of decision variables.

Template Parameters

Derived An Eigen matrix containing Variable.

Parameters

var	The 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

var	The decision variable.

Returns: The value of the decision variable after solving the problem.

Exceptions

std::exception if 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

e	The 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

p	A 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_t< std::is_same_v<typename Derived::Scalar, symbolic::Expression>, MatrixLikewise<symbolic::Expression, Derived> > GetSolution ( const Eigen::MatrixBase< Derived > & m ) const

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

Template Parameters

Derived An Eigen matrix containing Expression.

Returns: the Matrix<Expression> that is the result of the substitution.

◆ GetSuboptimalSolution() [1/2]

std::enable_if_t< std::is_same_v<typename Derived::Scalar, symbolic::Variable>, MatrixLikewise<double, Derived> > 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

var	The decision variables.
solution_number	The 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

var	The decision variable.
solution_number	The 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= ( MathematicalProgramResult && )

default

◆ operator=() [2/2]

MathematicalProgramResult& operator= ( const MathematicalProgramResult & )

default

◆ 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.

◆ SetSolution()

void SetSolution	(	const symbolic::Variable &	var,
		double	value
	)

Resets the solution of a single decision variable that is already registered with this result.

Exceptions

std::exception if var is not captured in the mapping decision_variable_index, as the input argument of set_decision_variable_index().

◆ 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:

drake/solvers/mathematical_program_result.h

Detailed Description

Public Member Functions

Constructor & Destructor Documentation

◆ MathematicalProgramResult() [1/3]

◆ MathematicalProgramResult() [2/3]

◆ MathematicalProgramResult() [3/3]

Member Function Documentation

◆ AddSuboptimalSolution()

◆ EvalBinding()

◆ get_abstract_solver_details()

◆ get_decision_variable_index()

◆ get_optimal_cost()

◆ get_solution_result()

◆ get_solver_details()

◆ get_solver_id()

◆ get_suboptimal_objective()

◆ get_x_val()

◆ GetDualSolution()

◆ GetInfeasibleConstraintNames()

◆ GetInfeasibleConstraints()

◆ GetSolution() [1/6]

◆ GetSolution() [2/6]

◆ GetSolution() [3/6]

◆ GetSolution() [4/6]

◆ GetSolution() [5/6]

◆ GetSolution() [6/6]

◆ GetSuboptimalSolution() [1/2]

◆ GetSuboptimalSolution() [2/2]

◆ is_success()

◆ num_suboptimal_solution()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ set_decision_variable_index()

◆ set_dual_solution()

◆ set_optimal_cost()

◆ set_solution_result()

◆ set_solver_id()

◆ set_x_val()

◆ SetSolution()

◆ SetSolverDetailsType()