CPMpy cpo interface (cpmpy.solvers.cpo)

Interface to CP Optimizer’s Python API.

CP Optimizer, also a feature of IBM ILOG Optimization Studio, is a software library of constraint programming tools supporting constraint propagation, domain reduction, and highly optimized solution search.

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

Installation

Requires that the ‘docplex’ python package is installed:

$ pip install docplex

docplex documentation: https://ibmdecisionoptimization.github.io/docplex-doc/

You will also need to install CPLEX Optimization Studio from IBM’s website, and add the location of the CP Optimizer binary to your path. There is a free community version available. https://www.ibm.com/products/ilog-cplex-optimization-studio

See detailed installation instructions at: https://www.ibm.com/docs/en/icos/22.1.2?topic=2212-installing-cplex-optimization-studio

Academic license: https://community.ibm.com/community/user/ai-datascience/blogs/xavier-nodet1/2020/07/09/cplex-free-for-students

The rest of this documentation is for advanced users.

List of classes

CPM_cpo

Interface to CP Optimizer's Python API.
class cpmpy.solvers.cpo.CPM_cpo(cpm_model=None, subsolver=None)[source]

Interface to CP Optimizer’s Python API.

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

  • cpo_model: object, CP Optimizers model object

Documentation of the solver’s own Python API: (all modeling functions) https://ibmdecisionoptimization.github.io/docplex-doc/cp/docplex.cp.modeler.py.html#module-docplex.cp.modeler

add(cpm_expr)[source]

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 (Expression or list of Expression) – 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

classmethod get_docp()[source]
has_objective()[source]

Returns whether the solver has an objective function or not.

static installed()[source]
static license_ok()[source]
maximize(expr)

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)

Post the given expression to the solver as objective to minimize

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

property native_model

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

objective(expr, minimize=True)[source]

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 permanently posted to the solver

objective_value()

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

solution_hint(cpm_vars, vals)

For warmstarting the solver with a variable assignment

Typically implemented in SAT-based solvers

Parameters:

  • cpm_vars – list of CPMpy variables

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

solve(time_limit=None, **kwargs)[source]

Call the CP Optimizer solver

Parameters:

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

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

Arguments that correspond to solver parameters:

Argument

Description

LogVerbosity

Determines the verbosity of the search log. Choose a value from [‘Quiet’, ‘Terse’, ‘Normal’, ‘Verbose’]. Default value is ‘Quiet’.

OptimalityTolerance

This parameter sets an absolute tolerance on the objective value for optimization models. The value is a positive float. Default value is 1e-09.

RelativeOptimalityTolerance

This parameter sets a relative tolerance on the objective value for optimization models. The optimality of a solution is proven if either of the two parameters’ criteria is fulfilled.

Presolve

This parameter controls the presolve of the model to produce more compact formulations and to achieve more domain reduction. Possible values for this parameter are On (presolve is activated) and Off (presolve is deactivated). The value is a symbol in [‘On’, ‘Off’]. Default value is ‘On’.

Workers

This parameter sets the number of workers to run in parallel to solve your model. The value is a positive integer. Default value is Auto. (Auto = use all available CPU cores)

All solver parameters are documented here: https://ibmdecisionoptimization.github.io/docplex-doc/cp/docplex.cp.parameters.py.html#docplex.cp.parameters.CpoParameters

solveAll(display=None, time_limit=None, solution_limit=None, call_from_model=False, **kwargs)[source]

A shorthand to (efficiently) compute all (optimal) solutions, map them to CPMpy and optionally display the solutions.

If the problem is an optimization problem, returns only optimal solutions.

Parameters:

  • display – either a list of CPMpy expressions, OR a callback function, called with the variables after value-mapping. Default is None, meaning nothing is displayed.

  • time_limit – Stop after this many seconds. Default is None.

  • solution_limit – Stop after this many solutions. Default is None.

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

  • **kwargs – Any other keyword arguments.

Returns:

Number of solutions found.

Return type:

int

solver_var(cpm_var)[source]

Creates solver variable for cpmpy variable or returns from cache if previously created

solver_vars(cpm_vars)

Like solver_var() but for arbitrary shaped lists/tensors

status()
static supported()[source]

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]

transform(cpm_expr)[source]

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 (Expression or list of Expression) – CPMpy expression, or list thereof

Returns:

list of Expression