CPMpy gurobi interface (cpmpy.solvers.gurobi)

Interface to Gurobi Optimizer’s Python API.

Gurobi Optimizer is a highly efficient commercial solver for Integer Linear Programming (and more).

Always use cp.SolverLookup.get("gurobi") to instantiate the solver object.

Installation

Requires that the ‘gurobipy’ python package is installed:

$ pip install gurobipy

Gurobi Optimizer requires an active licence (for example a free academic license) You can read more about available licences at https://www.gurobi.com/downloads/

See detailed installation instructions at: https://support.gurobi.com/hc/en-us/articles/360044290292-How-do-I-install-Gurobi-for-Python-

The rest of this documentation is for advanced users.

List of classes

CPM_gurobi

Interface to Gurobi's Python API

Module details

Supports FloatSum objectives.

class cpmpy.solvers.gurobi.CPM_gurobi(cpm_model=None, subsolver=None)

Interface to Gurobi’s Python API

Creates the following attributes (see parent constructor for more):

• grb_model: object, TEMPLATE’s model object

The DirectConstraint, when used, calls a function on the grb_model object.

Documentation of the solver’s own Python API: https://docs.gurobi.com/projects/optimizer/en/current/reference/python.html

add(cpm_expr: Expression | bool | bool | Sequence[Expression | bool | bool | Sequence[NestedBoolExprLike] | ndarray] | ndarray) → CPM_gurobi

Eagerly add a constraint to the underlying solver.

Any CPMpy expression given is immediately transformed (through transform()) and then posted to the solver in this function.

This can raise ‘NotImplementedError’ for any constraint not supported after transformation

The variables used in expressions given to add are stored as ‘user variables’. Those are the only ones the user knows and cares about (and will be populated with a value after solve). All other variables are auxiliary variables created by transformations.

Parameters:

cpm_expr (NestedBoolExprLike) – CPMpy expression, or list thereof

Returns:

self

get_core()

For use with s.solve(assumptions=[...]). Only meaningful if the solver returned UNSAT.

Typically implemented in SAT-based solvers

Returns a small subset of assumption literals that are unsat together. (a literal is either a _BoolVarImpl or a NegBoolView in case of its negation, e.g. x or ~x) Setting these literals to True makes the model UNSAT, setting any to False makes it SAT

has_objective()

Returns whether the solver has an objective function or not.

static installed()

static license_ok()

maximize(expr: Expression | FloatSum) → None

Post the given expression to the solver as objective to maximize

maximize() can be called multiple times, only the last one is stored

minimize(expr: Expression | FloatSum) → None

Post the given expression to the solver as objective to minimize

minimize() can be called multiple times, only the last one is stored

classmethod mus_native(soft, hard=[])

Compute a MUS using Gurobi’s native IIS (Irreducible Inconsistent Subsystem) algorithm.

The main ‘difficulty’ is that Gurobi’s native IIS algorithm expects individual constraints, while CPMpy always takes a ‘grouped’ perspective (e.g. one soft constraint can be a conjunction, or it can be a global that is decomposed/rewritten into multiple constraints).

The code takes care to leave soft constraints corresponding to a single Gurobi constraint as-is, and adds a new 01 variable plus an implication/’indicator’ constraint for each constraint in the group.

Parameters:

• soft – List of soft constraints over which a MUS needs to be found

• hard – List of hard constraints that always need to be satisfied

Returns a MUS (list of constraints from soft that is unsatisfiable together, and subset minimal).

property native_model

Returns the solver’s underlying native model (for direct solver access).

objective(expr: Expression | FloatSum, minimize: bool = True) → None

Post the given expression to the solver as objective to minimize/maximize

‘objective()’ can be called multiple times, only the last one is stored

Note

technical side note: any constraints created during conversion of the objective are premanently posted to the solver

objective_value() → int | None

Returns the value of the objective function of the latest solver run on this model

Returns:

an integer or ‘None’ if it is not run, or a satisfaction problem

objective_value_: int | None

print_display(display: Expression | Sequence[Expression] | ndarray | Callable[[], None] | None) → None

Helper function for printing the display argument used in solveAll().

Parameters:

display – either a CPMpy Expression, OR a list of expressions, OR a callback function (no-arg) to call.

solution_hint(cpm_vars: List[_NumVarImpl], vals: List[int | bool])

Gurobi supports warmstarting the solver with a (in)feasible solution. The provided value will affect branching heurstics during solving, making it more likely the final solution will contain the provided assignment.

To learn more about solution hinting in gurobi, see: https://docs.gurobi.com/projects/optimizer/en/current/reference/attributes/variable.html#varhintval

Optionally, you can also set the relative priority of the hint, using:

solver.solver_var(cpm_var).setAttr("VarHintPri", <priority>)

Parameters:

• cpm_vars – list of CPMpy variables

• vals – list of (corresponding) values for the variables

solve(time_limit: float | None = None, solution_callback: Callable | None = None, display: Expression | Sequence[Expression] | ndarray | Callable[[], None] | None = None, **kwargs)

Call the gurobi solver

Parameters:

• time_limit (float, optional) – maximum solve time in seconds

• solution_callback – Gurobi callback function, takes precedence over display when both are set.

• display – generic solution callback for use during optimization. either a list of CPMpy expressions, OR a callback function which gets called after the variable-value mapping of the intermediate solution. default/None: nothing is displayed

• **kwargs – any keyword argument, sets parameters of solver object

Arguments that correspond to solver parameters: Examples of gurobi supported arguments include:

• Threads : int

• MIPFocus : int

• ImproveStartTime : bool

• FlowCoverCuts : int

For a full list of gurobi parameters, please visit https://www.gurobi.com/documentation/9.5/refman/parameters.html#sec:Parameters

solveAll(display: Expression | Sequence[Expression] | ndarray | Callable[[], None] | None = None, time_limit: float | None = None, solution_limit: int | None = None, call_from_model=False, **kwargs)

Compute all solutions and optionally display the solutions.

This is the generic implementation, solvers can overwrite this with a more efficient native implementation

Parameters:

• display – either a list of CPMpy expressions, OR a callback function, called with the variables after value-mapping default/None: nothing displayed

• time_limit – stop after this many seconds (default: None)

• solution_limit – stop after this many solutions (default: None)

• call_from_model – whether the method is called from a CPMpy Model instance or not

• argument (any other keyword)

Returns: number of solutions found

solver_var(cpm_var)

Creates solver variable for cpmpy variable or returns from cache if previously created or returns a constant if the variable is a constant

solver_vars(cpm_vars: Iterable[Expression | int | integer | bool]) → list[Any]

Like solver_var() but for arbitrary shaped lists/tensors

status()

static supported()

Check for support in current system setup. Return True if the system has package installed or supports solver, else returns False.

Returns:

Solver support by current system setup.

Return type:

[bool]

supported_global_constraints: frozenset[str] = frozenset({'abs', 'max', 'min', 'mul', 'pow'})

supported_reified_global_constraints: frozenset[str] = frozenset({})

transform(cpm_expr: Expression | bool | bool | Sequence[Expression | bool | bool | Sequence[NestedBoolExprLike] | ndarray] | ndarray) → list[Expression]

Transform arbitrary CPMpy expressions to constraints the solver supports

Implemented through chaining multiple solver-independent transformation functions from the cpmpy/transformations/ directory.

See the Adding a new solver docs on readthedocs for more information.

Parameters:

cpm_expr (NestedBoolExprLike) – CPMpy expression, or list thereof

Returns:

transformed constraints

Return type:

list[Expression]

static version() → str | None

Returns the installed version of the solver’s Python API.