Detailed Description

An implementation of SolverInterface for the commercially-licensed Gurobi solver (https://www.gurobi.com/).

The default build of Drake is not configured to use Gurobi, so therefore SolverInterface::available() will return false. You must compile Drake from source in order to link against Gurobi. For details, refer to the documentation at https://drake.mit.edu/bazel.html#proprietary-solvers.

The GRB_LICENSE_FILE environment variable controls whether or not SolverInterface::enabled() returns true. If it is set to any non-empty value, then the solver is enabled; otherwise, the solver is not enabled.

Gurobi solver supports options/parameters listed in https://docs.gurobi.com/projects/optimizer/en/12.0/concepts/parameters.html. On top of these options, we provide the following additional options

"GRBwrite", set to a file name so that Gurobi solver will write the optimization model to this file, check https://www.docs.gurobi.com/projects/optimizer/en/12.0/reference/python/model.html#Write for more details, such as all supported file extensions. Set this option to "" if you don't want to write to file. Default is not to write to a file.
"GRBcomputeIIS", set to 1 to compute an Irreducible Inconsistent Subsystem (IIS) when the problem is infeasible. Refer to https://docs.gurobi.com/projects/optimizer/en/12.0/reference/python/model.html#Model.computeIIS for more details. Often this method is called together with setting GRBwrite to "FILENAME.ilp" to write IIS to a file with extension "ilp". Default is not to compute IIS.

GurobiSolver supports parallelization during Solve(). If both the "Threads" integer solver option and CommonSolverOption::kMaxThreads have been set by the user, then the value in "Threads" will be used as the number of threads.

If neither the "Threads" integer solver option nor CommonSolverOption::kMaxThreads has been set by the user, then GurobiSolver uses the environment variable GUROBI_NUM_THREADS (if set) as a default value for "Threads".

If none of "Threads", CommonSolverOption::kMaxThreads, or GUROBI_NUM_THREADS are set, then Drake's default maximum parallelism will be used.

#include <drake/solvers/gurobi_solver.h>

Classes
struct	SolveStatusInfo
	Contains info returned to a user function that handles a Node or Solution callback. More...

Public Types
using	Details = GurobiSolverDetails
	Type of details stored in MathematicalProgramResult.
typedef std::function< void(const MathematicalProgram &, const SolveStatusInfo &callback_info, Eigen::VectorXd , VectorXDecisionVariable )>	MipNodeCallbackFunction
	Users can supply a callback to be called when the Gurobi solver finds an intermediate solution node, which may not be feasible.
typedef std::function< void(const MathematicalProgram &, const SolveStatusInfo &callback_info)>	MipSolCallbackFunction
	Users can supply a callback to be called when the Gurobi solver finds a feasible solution.

Public Member Functions
	GurobiSolver ()
	~GurobiSolver () final
void	AddMipNodeCallback (const MipNodeCallbackFunction &callback)
	Registers a callback to be called at intermediate solutions during the solve.
void	AddMipSolCallback (const MipSolCallbackFunction &callback)
	Registers a callback to be called at feasible solutions during the solve.
Does not allow copy, move, or assignment
	GurobiSolver (const GurobiSolver &)=delete
GurobiSolver &	operator= (const GurobiSolver &)=delete
	GurobiSolver (GurobiSolver &&)=delete
GurobiSolver &	operator= (GurobiSolver &&)=delete
Public Member Functions inherited from SolverBase
	~SolverBase () override
MathematicalProgramResult	Solve (const MathematicalProgram &prog, const std::optional< Eigen::VectorXd > &initial_guess=std::nullopt, const std::optional< SolverOptions > &solver_options=std::nullopt) const
	Like SolverInterface::Solve(), but the result is a return value instead of an output argument.
void	Solve (const MathematicalProgram &, const std::optional< Eigen::VectorXd > &, const std::optional< SolverOptions > &, MathematicalProgramResult *) const override
	Solves an optimization program with optional initial guess and solver options.
bool	available () const override
	Returns true iff support for this solver has been compiled into Drake.
bool	enabled () const override
	Returns true iff this solver is properly configured for use at runtime.
SolverId	solver_id () const final
	Returns the identifier of this solver.
bool	AreProgramAttributesSatisfied (const MathematicalProgram &) const override
	Returns true iff the program's attributes are compatible with this solver's capabilities.
std::string	ExplainUnsatisfiedProgramAttributes (const MathematicalProgram &) const override
	Describes the reasons (if any) why the program is incompatible with this solver's capabilities.
	SolverBase (const SolverBase &)=delete
SolverBase &	operator= (const SolverBase &)=delete
	SolverBase (SolverBase &&)=delete
SolverBase &	operator= (SolverBase &&)=delete
Public Member Functions inherited from SolverInterface
virtual	~SolverInterface ()
	SolverInterface (const SolverInterface &)=delete
SolverInterface &	operator= (const SolverInterface &)=delete
	SolverInterface (SolverInterface &&)=delete
SolverInterface &	operator= (SolverInterface &&)=delete

Static Public Member Functions
static std::shared_ptr< License >	AcquireLicense ()
	This acquires a Gurobi license environment shared among all GurobiSolver instances.

Static versions of the instance methods with similar names.
MathematicalProgramResult	Solve (const MathematicalProgram &prog, const std::optional< Eigen::VectorXd > &initial_guess=std::nullopt, const std::optional< SolverOptions > &solver_options=std::nullopt) const
	Like SolverInterface::Solve(), but the result is a return value instead of an output argument.
void	Solve (const MathematicalProgram &, const std::optional< Eigen::VectorXd > &, const std::optional< SolverOptions > &, MathematicalProgramResult *) const override
	Solves an optimization program with optional initial guess and solver options.
static SolverId	id ()
static bool	is_available ()
static bool	is_enabled ()
	Returns true iff the environment variable GRB_LICENSE_FILE has been set to a non-empty value.
static bool	ProgramAttributesSatisfied (const MathematicalProgram &)
static std::string	UnsatisfiedProgramAttributes (const MathematicalProgram &)

Additional Inherited Members
Protected Member Functions inherited from SolverBase
	SolverBase (const SolverId &id, std::function< bool()> available, std::function< bool()> enabled, std::function< bool(const MathematicalProgram &)> are_satisfied, std::function< std::string(const MathematicalProgram &)> explain_unsatisfied=nullptr)
	Constructs a SolverBase with the given default implementations of the solver_id(), available(), enabled(), AreProgramAttributesSatisfied(), and ExplainUnsatisfiedProgramAttributes() methods.
virtual void	DoSolve (const MathematicalProgram &prog, const Eigen::VectorXd &initial_guess, const SolverOptions &merged_options, MathematicalProgramResult *result) const
	Hook for subclasses to implement Solve.
Protected Member Functions inherited from SolverInterface
	SolverInterface ()

Member Typedef Documentation

◆ Details

using Details = GurobiSolverDetails

Type of details stored in MathematicalProgramResult.

◆ MipNodeCallbackFunction

typedef std::function<void(const MathematicalProgram&, const SolveStatusInfo& callback_info, Eigen::VectorXd*, VectorXDecisionVariable*)> MipNodeCallbackFunction

Users can supply a callback to be called when the Gurobi solver finds an intermediate solution node, which may not be feasible.

See Gurobi reference manual for more detail on callbacks: https://docs.gurobi.com/projects/optimizer/en/12.0/reference/numericcodes/callbacks.html The user may supply a partial solution in the VectorXd and VectorXDecisionVariable arguments that will be passed to Gurobi as a candidate feasible solution. See gurobi_solver_test.cc for an example of using std::bind to create a callback of this signature, while allowing additional data to be passed through.

Parameters

MathematicalProgram&	The optimization wrapper, whose current variable values (accessible via MathematicalProgram::GetSolution) will be set to the intermediate solution values.
SolveStatusInfo&	Intermediate solution status information values queried from Gurobi.
VectorXd*	User may assign this to be the values of the variable assignments.
VectorXDecisionVariable*	User may assign this to be the decision variables being assigned. Must have the same number of elements as the VectorXd assignment.

◆ MipSolCallbackFunction

typedef std::function<void(const MathematicalProgram&, const SolveStatusInfo& callback_info)> MipSolCallbackFunction

Users can supply a callback to be called when the Gurobi solver finds a feasible solution.

See Gurobi reference manual for more detail on callbacks: https://docs.gurobi.com/projects/optimizer/en/12.0/reference/numericcodes/callbacks.html See gurobi_solver_test.cc for an example of using std::bind to create a callback of this signature, while allowing additional data to be passed through.

Parameters

MathematicalProgram&	The optimization wrapper, whose current variable values (accessible via MathematicalProgram::GetSolution) will be set to the intermediate solution values.
SolveStatusInfo&	Intermediate solution status information values queried from Gurobi.
void*	Arbitrary data supplied during callback registration.

Constructor & Destructor Documentation

◆ GurobiSolver() [1/3]

GurobiSolver ( const GurobiSolver & )

delete

◆ GurobiSolver() [2/3]

GurobiSolver ( GurobiSolver && )

delete

◆ GurobiSolver() [3/3]

GurobiSolver ( )

◆ ~GurobiSolver()

~GurobiSolver ( )

final

Member Function Documentation

◆ AcquireLicense()

std::shared_ptr< License > AcquireLicense ( )

static

This acquires a Gurobi license environment shared among all GurobiSolver instances.

The environment will stay valid as long as at least one shared_ptr returned by this function is alive. GurobiSolver calls this method on each Solve().

If the license file contains the string HOSTID, then we treat this as confirmation that the license is attached to the local host, and maintain an internal copy of the shared_ptr for the lifetime of the process. Otherwise the default behavior is to only hold the license while at least one GurobiSolver instance is alive.

Call this method directly and maintain the shared_ptr ONLY if you must use different MathematicalProgram instances at different instances in time, and repeatedly acquiring the license is costly (e.g., requires contacting a license server).

Returns: A shared pointer to a license environment that will stay valid as long as any shared_ptr returned by this function is alive. If Gurobi is not available in your build, this will return a null (empty) shared_ptr.

Exceptions

std::exception if Gurobi is available but a license cannot be obtained.

◆ AddMipNodeCallback()

void AddMipNodeCallback ( const MipNodeCallbackFunction & callback )

Registers a callback to be called at intermediate solutions during the solve.

Parameters

callback User callback function.

◆ AddMipSolCallback()

void AddMipSolCallback ( const MipSolCallbackFunction & callback )

Registers a callback to be called at feasible solutions during the solve.

Parameters

callback User callback function.

◆ id()

SolverId id ( )

static

◆ is_available()

bool is_available ( )

static

◆ is_enabled()

bool is_enabled ( )

static

Returns true iff the environment variable GRB_LICENSE_FILE has been set to a non-empty value.

◆ operator=() [1/2]

GurobiSolver & operator= ( const GurobiSolver & )

delete

◆ operator=() [2/2]

GurobiSolver & operator= ( GurobiSolver && )

delete

◆ ProgramAttributesSatisfied()

bool ProgramAttributesSatisfied ( const MathematicalProgram & )

static

◆ Solve() [1/2]

void Solve	(	const MathematicalProgram &	prog,
		const std::optional< Eigen::VectorXd > &	initial_guess,
		const std::optional< SolverOptions > &	solver_options,
		MathematicalProgramResult *	result ) const

overridevirtual

Solves an optimization program with optional initial guess and solver options.

Note that these initial guess and solver options are not written to prog. If the prog has set an initial guess, and initial_guess is set, then initial_guess takes priority. If the prog has set an option for a solver, and solver_options contains a different value for the same option on the same solver, then solver_options takes priority. Derived implementations of this interface may elect to throw std::exception for badly formed programs.

Implements SolverInterface.

◆ Solve() [2/2]

MathematicalProgramResult Solve	(	const MathematicalProgram &	prog,
		const std::optional< Eigen::VectorXd > &	initial_guess = std::nullopt,
		const std::optional< SolverOptions > &	solver_options = std::nullopt ) const

Like SolverInterface::Solve(), but the result is a return value instead of an output argument.

◆ UnsatisfiedProgramAttributes()

std::string UnsatisfiedProgramAttributes ( const MathematicalProgram & )

static

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

drake/solvers/gurobi_solver.h

Detailed Description

Classes

Public Types

Public Member Functions

Static Public Member Functions

Static versions of the instance methods with similar names.

Additional Inherited Members

Member Typedef Documentation

◆ Details

◆ MipNodeCallbackFunction

◆ MipSolCallbackFunction

Constructor & Destructor Documentation

◆ GurobiSolver() [1/3]

◆ GurobiSolver() [2/3]

◆ GurobiSolver() [3/3]

◆ ~GurobiSolver()

Member Function Documentation

◆ AcquireLicense()

◆ AddMipNodeCallback()

◆ AddMipSolCallback()

◆ id()

◆ is_available()

◆ is_enabled()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ ProgramAttributesSatisfied()

◆ Solve() [1/2]

◆ Solve() [2/2]

◆ UnsatisfiedProgramAttributes()