CPMpy cplex interface (cpmpy.solvers.cplex)

Interface to CPLEX Optimizer using the python ‘docplex.mp’ package

CPLEX, standing as an acronym for ‘Complex Linear Programming Expert’, is a high-performance mathematical programming solver specializing in linear programming (LP), mixed integer programming (MIP), and quadratic programming (QP).

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

Installation

Requires that both the ‘docplex’ and the ‘cplex’ python packages are installed:

$ pip install docplex cplex

Detailed installation instructions available at: https://ibmdecisionoptimization.github.io/docplex-doc/getting_started_python.html

You will also need to install CPLEX Optimization Studio from IBM’s website. 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

It also requires an active licence. 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_cplex

Interface to the CPLEX solver.

Module details

class cpmpy.solvers.cplex.CPM_cplex(cpm_model=None, subsolver=None)[source]

Interface to the CPLEX solver.

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

  • cplex_model: object, CPLEX model object

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

Documentation of the solver’s own Python API: https://ibmdecisionoptimization.github.io/docplex-doc/mp/docplex.mp.model.html

add(cpm_expr_orig)[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

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 premanently 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: List[_NumVarImpl], vals: List[int | bool])[source]

CPLEX supports warmstarting the solver with a (in)feasible solution. This is done using MIP starts which provide the solver with a starting point for the branch-and-bound algorithm.

The solution hint does NOT need to satisfy all constraints, it should just provide reasonable default values for the variables. It can decrease solving times substantially, especially when solving a similar model repeatedly.

To learn more about solution hinting in CPLEX, see: https://ibmdecisionoptimization.github.io/docplex-doc/mp/docplex.mp.model.html#docplex.mp.model.Model.add_mip_start

Parameters:

  • cpm_vars – list of CPMpy variables

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

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

Call the cplex solver

Arguments: - time_limit: maximum solve time in seconds (float, optional) - kwargs: any keyword argument, sets parameters of solver object and cplex parameters

Supported keyword arguments are all solve parameters and cplex parameters:
  • solve_parameters:

    • context (optional) – context to use during solve

    • checker (optional) – a string which controls which type of checking is performed. (type checks etc.)

    • log_output (optional) – if True, solver logs are output to stdout.

    • clean_before_solve (optional) – default False (iterative solving)

  • cplex_parameters:

For a full description of the parameters, please visit https://ibmdecisionoptimization.github.io/docplex-doc/mp/docplex.mp.model.html?#docplex.mp.model.Model.solve

After solving, all solve details can be accessed through self.cplex_model.solve_details: https://ibmdecisionoptimization.github.io/docplex-doc/mp/docplex.mp.sdetails.html#docplex.mp.sdetails.SolveDetails

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

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)

  • argument (any other keyword)

Returns: number of solutions found

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]

supported_global_constraints: frozenset[str] = frozenset({'abs', 'max', 'min'})
supported_reified_global_constraints: frozenset[str] = frozenset({})
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

static version() → str | None[source]

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

Two version numbers get returned: <docplex version>/<solver version>