GraphOfConvexSets::Edge Class Reference

Detailed Description

An edge in the graph connects between vertex u and vertex v.

The edge also holds a list of cost and constraints associated with the continuous variables.

#include <drake/geometry/optimization/graph_of_convex_sets.h>

Public Member Functions
	~Edge ()
EdgeId	id () const
	Returns the unique identifier associated with this Edge.
const std::string &	name () const
	Returns the string name associated with this edge.
const Vertex &	u () const
	Returns a const reference to the "left" Vertex that this edge connects to.
Vertex &	u ()
	Returns a mutable reference to the "left" Vertex that this edge connects to.
const Vertex &	v () const
	Returns a const reference to the "right" Vertex that this edge connects to.
Vertex &	v ()
	Returns a mutable reference to the "right" Vertex that this edge connects to.
const symbolic::Variable &	phi () const
	Returns the binary variable associated with this edge.
const VectorX< symbolic::Variable > &	xu () const
	Returns the continuous decision variables associated with vertex u.
const VectorX< symbolic::Variable > &	xv () const
	Returns the continuous decision variables associated with vertex v.
solvers::VectorXDecisionVariable	NewSlackVariables (int rows, const std::string &name)
	Creates continuous slack variables for this edge, appending them to an internal vector of existing slack variables.
solvers::Binding< solvers::Cost >	AddCost (const symbolic::Expression &e, const std::unordered_set< Transcription > &use_in_transcription={ Transcription::kMIP, Transcription::kRelaxation, Transcription::kRestriction})
	Adds a cost to this edge, described by a symbolic::Expression e containing only elements of xu() and xv() as variables.
solvers::Binding< solvers::Cost >	AddCost (const solvers::Binding< solvers::Cost > &binding, const std::unordered_set< Transcription > &use_in_transcription={ Transcription::kMIP, Transcription::kRelaxation, Transcription::kRestriction})
	Adds a cost to this edge.
solvers::Binding< solvers::Constraint >	AddConstraint (const symbolic::Formula &f, const std::unordered_set< Transcription > &use_in_transcription={ Transcription::kMIP, Transcription::kRelaxation, Transcription::kRestriction})
	Adds a constraint to this edge.
solvers::Binding< solvers::Constraint >	AddConstraint (const solvers::Binding< solvers::Constraint > &binding, const std::unordered_set< Transcription > &use_in_transcription={ Transcription::kMIP, Transcription::kRelaxation, Transcription::kRestriction})
	Adds a constraint to this edge.
void	AddPhiConstraint (bool phi_value)
	Adds a constraint on the binary variable associated with this edge.
void	ClearPhiConstraints ()
	Removes any constraints added with AddPhiConstraint.
std::vector< solvers::Binding< solvers::Cost > >	GetCosts (const std::unordered_set< Transcription > &used_in_transcription={ Transcription::kMIP, Transcription::kRelaxation, Transcription::kRestriction}) const
	Returns costs on this edge.
std::vector< solvers::Binding< solvers::Constraint > >	GetConstraints (const std::unordered_set< Transcription > &used_in_transcription={ Transcription::kMIP, Transcription::kRelaxation, Transcription::kRestriction}) const
	Returns constraints on this edge.
std::optional< double >	GetSolutionCost (const solvers::MathematicalProgramResult &result) const
	Returns the sum of the costs associated with this edge in result, or std::nullopt if no solution for this edge is available.
std::optional< double >	GetSolutionCost (const solvers::MathematicalProgramResult &result, const solvers::Binding< solvers::Cost > &cost) const
	Returns the cost associated with the cost binding on this edge in result, or std::nullopt if no solution for this edge is available.
std::optional< Eigen::VectorXd >	GetSolutionPhiXu (const solvers::MathematicalProgramResult &result) const
	Returns the vector value of the slack variables associated with ϕxᵤ in result, or std::nullopt if no solution for this edge is available.
std::optional< Eigen::VectorXd >	GetSolutionPhiXv (const solvers::MathematicalProgramResult &result) const
	Returns the vector value of the slack variables associated with ϕxᵥ in result, or std::nullopt if no solution for this edge is available.
Does not allow copy, move, or assignment
	Edge (const Edge &)=delete
Edge &	operator= (const Edge &)=delete
	Edge (Edge &&)=delete
Edge &	operator= (Edge &&)=delete

Friends
class	GraphOfConvexSets

Constructor & Destructor Documentation

Edge() [1/2]

Edge ( const Edge & )

delete

Edge() [2/2]

Edge ( Edge && )

delete

~Edge()

~Edge

(

)

Member Function Documentation

AddConstraint() [1/2]

solvers::Binding< solvers::Constraint > AddConstraint	(	const solvers::Binding< solvers::Constraint > &	binding,
		const std::unordered_set< Transcription > &	use_in_transcription = { Transcription::kMIP, Transcription::kRelaxation, Transcription::kRestriction} )

Adds a constraint to this edge.

Parameters

binding	must contain only elements of xu() and xv() as variables.
use_in_transcription	specifies the components of the problem to which the constraint should be added.

Exceptions

std::exception	if binding.variables() is not a subset of xu() ∪ xv().
std::exception	if xu() ∪ xv() is empty, i.e., when both vertices have an ambient dimension of zero.
std::exception	if no transcription is specified.

AddConstraint() [2/2]

solvers::Binding< solvers::Constraint > AddConstraint	(	const symbolic::Formula &	f,
		const std::unordered_set< Transcription > &	use_in_transcription = { Transcription::kMIP, Transcription::kRelaxation, Transcription::kRestriction} )

Adds a constraint to this edge.

Parameters

f	must contain only elements of xu() and xv() as variables.
use_in_transcription	specifies the components of the problem to which the constraint should be added.

Exceptions

std::exception	if f.GetFreeVariables() is not a subset of xu() ∪ xv().
std::exception	if xu() ∪ xv() is empty, i.e., when both vertices have an ambient dimension of zero.
std::exception	if no transcription is specified.

AddCost() [1/2]

solvers::Binding< solvers::Cost > AddCost	(	const solvers::Binding< solvers::Cost > &	binding,
		const std::unordered_set< Transcription > &	use_in_transcription = { Transcription::kMIP, Transcription::kRelaxation, Transcription::kRestriction} )

Adds a cost to this edge.

binding must contain only elements of xu() and xv() as variables. For technical reasons relating to being able to "turn-off" the cost on inactive edges, all costs are eventually implemented with a slack variable and a constraint:

min g(xu, xv) ⇒ min ℓ, s.t. ℓ ≥ g(xu,xv)

You must use GetSolutionCost() to retrieve the cost of the solution, rather than evaluating the cost directly, in order to get consistent behavior when solving with the different GCS transcriptions.

Parameters

use_in_transcription

specifies the components of the problem to which the constraint should be added.

Note

Linear costs lead to negative costs if decision variables are not properly constrained. Users may want to check that the solution does not contain negative costs.

Returns

the added cost, g(xu, xv).

Exceptions

std::exception	if binding.variables() is not a subset of xu() ∪ xv().
std::exception	if no transcription is specified.

AddCost() [2/2]

solvers::Binding< solvers::Cost > AddCost	(	const symbolic::Expression &	e,
		const std::unordered_set< Transcription > &	use_in_transcription = { Transcription::kMIP, Transcription::kRelaxation, Transcription::kRestriction} )

Adds a cost to this edge, described by a symbolic::Expression e containing only elements of xu() and xv() as variables.

For technical reasons relating to being able to "turn-off" the cost on inactive edges, all costs are eventually implemented with a slack variable and a constraint:

min g(xu, xv) ⇒ min ℓ, s.t. ℓ ≥ g(xu,xv)

You must use GetSolutionCost() to retrieve the cost of the solution, rather than evaluating the cost directly, in order to get consistent behavior when solving with the different GCS transcriptions.

Parameters

use_in_transcription

specifies the components of the problem to which the constraint should be added.

Note

Linear costs lead to negative costs if decision variables are not properly constrained. Users may want to check that the solution does not contain negative costs.

Returns

the added cost, g(xu, xv).

Exceptions

std::exception	if e.GetVariables() is not a subset of xu() ∪ xv().
std::exception	if no transcription is specified.

AddPhiConstraint()

void AddPhiConstraint

(

bool

phi_value

)

Adds a constraint on the binary variable associated with this edge.

Note

We intentionally do not return a binding to the constraint created by this call, as that would allow the caller to make nonsensical modifications to its bounds (i.e. requiring phi == 0.5).

ClearPhiConstraints()

void ClearPhiConstraints

(

)

Removes any constraints added with AddPhiConstraint.

GetConstraints()

std::vector< solvers::Binding< solvers::Constraint > > GetConstraints

(

const std::unordered_set< Transcription > &

used_in_transcription = { Transcription::kMIP, Transcription::kRelaxation, Transcription::kRestriction}

)

const

Returns constraints on this edge.

Parameters

used_in_transcription

specifies the components of the problem from which the constraint should be retrieved.

Exceptions

std::exception

if no transcription is specified.

GetCosts()

std::vector< solvers::Binding< solvers::Cost > > GetCosts

(

const std::unordered_set< Transcription > &

used_in_transcription = { Transcription::kMIP, Transcription::kRelaxation, Transcription::kRestriction}

)

const

Returns costs on this edge.

Parameters

used_in_transcription

specifies the components of the problem from which the constraint should be retrieved.

Exceptions

std::exception

if no transcription is specified.

GetSolutionCost() [1/2]

std::optional< double > GetSolutionCost

(

const solvers::MathematicalProgramResult &

result

)

const

Returns the sum of the costs associated with this edge in result, or std::nullopt if no solution for this edge is available.

GetSolutionCost() [2/2]

std::optional< double > GetSolutionCost	(	const solvers::MathematicalProgramResult &	result,
		const solvers::Binding< solvers::Cost > &	cost ) const

Returns the cost associated with the cost binding on this edge in result, or std::nullopt if no solution for this edge is available.

Exceptions

std::exception

if cost is not associated with this edge.

GetSolutionPhiXu()

std::optional< Eigen::VectorXd > GetSolutionPhiXu

(

const solvers::MathematicalProgramResult &

result

)

const

Returns the vector value of the slack variables associated with ϕxᵤ in result, or std::nullopt if no solution for this edge is available.

This can obtain a different value than the Vertex::GetSolution(), e.g. from edge->xu().GetSolution(result). First, a deactivated edge (defined by Phi ~= 0) will return the zero vector here, while Vertex::GetSolution() will return std::nullopt (rather than divide by zero to recover Xu). Second, in the case of a loose convex relaxation, the vertex version will return the averaged* value of the edge slacks for all non-zero-flow edges.

GetSolutionPhiXv()

std::optional< Eigen::VectorXd > GetSolutionPhiXv

(

const solvers::MathematicalProgramResult &

result

)

const

Returns the vector value of the slack variables associated with ϕxᵥ in result, or std::nullopt if no solution for this edge is available.

See GetSolutionPhiXu() for more details.

id()

EdgeId id

(

)

const

Returns the unique identifier associated with this Edge.

name()

const std::string & name

(

)

const

Returns the string name associated with this edge.

NewSlackVariables()

solvers::VectorXDecisionVariable NewSlackVariables	(	int	rows,
		const std::string &	name )

Creates continuous slack variables for this edge, appending them to an internal vector of existing slack variables.

These slack variables can be used in any cost or constraint on this edge only, and allows for modeling more complex costs and constraints.

operator=() [1/2]

Edge & operator= ( const Edge & )

delete

operator=() [2/2]

Edge & operator= ( Edge && )

delete

phi()

const symbolic::Variable & phi

(

)

const

Returns the binary variable associated with this edge.

It can be used to determine whether this edge was active in the solution to an optimization problem, by calling GetSolution(phi()) on a returned MathematicalProgramResult.

u() [1/2]

Vertex & u

(

)

Returns a mutable reference to the "left" Vertex that this edge connects to.

u() [2/2]

const Vertex & u

(

)

const

Returns a const reference to the "left" Vertex that this edge connects to.

v() [1/2]

Vertex & v

(

)

Returns a mutable reference to the "right" Vertex that this edge connects to.

v() [2/2]

const Vertex & v

(

)

const

Returns a const reference to the "right" Vertex that this edge connects to.

xu()

const VectorX< symbolic::Variable > & xu

(

)

const

Returns the continuous decision variables associated with vertex u.

This can be used for constructing symbolic::Expression costs and constraints.

See also GetSolutionPhiXu(); using result.GetSolution(xu()) may not be what you want.

xv()

const VectorX< symbolic::Variable > & xv

(

)

const

Returns the continuous decision variables associated with vertex v.

This can be used for constructing symbolic::Expression costs and constraints.

See also GetSolutionPhiXv(); using result.GetSolution(xv()) may not be what you want.

Friends And Related Symbol Documentation

GraphOfConvexSets

friend class GraphOfConvexSets

friend

---

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

• drake/geometry/optimization/graph_of_convex_sets.h