docplex.mp.callbacks.cb_mixin module

class docplex.mp.callbacks.cb_mixin.ConstraintCallbackMixin

Bases: ModelCallbackMixin

get_cpx_unsatisfied_cts(cts, sol, tolerance=1e-06)

returns the subset of unsatisfied constraints in a given solution. This is used in custom lazy constraints or user cut callbacks.

Parameters:

• cts – a list of constraints among which to look for unsatisfied

• sol – A solution object

• tolerance – amn optional numerical value used to determine whether a constraint is satisfied or not. Defaut is 1e-6.

Returns:

a list of tuples (ct, lhs, sense, lhs) where: ct is an unsatisfied constraint lhs is the left-hand size, as expected by the cplex callback sense is the constraint sense, as expected by the cplex callback rhs is the rith-and side (a number), as expected by the cplex callback

make_solution_from_watched()

Creates and returns a DOcplex solution instance from watched items.

This method should be called when CPLEX has a new incumbent solution. It builds an intermediate solution from the watched variables and variables mentioned in the registered constraints..

To build a soluton from all variables, use make_complete_solution()

Returns:

An instance of SolveSolution.

register_watched_var(dvar)

Register one variable.

Registered variables will be part of the intermediate solutions.

register_watched_vars(dvars)

Register an iterable of variables.

Registered variables will be part of the intermediate solutions.

class docplex.mp.callbacks.cb_mixin.ModelCallbackMixin

Bases: object

This mixin class is intended as a bridge between DOcplex expression and constraints and CPLEX callback API. It is not intended to be instantiated directly, but to be inherited from in custom callbacks , jointly with a CPLEX callback type.

For example, to define a custom BranchCallback in Docplex, define a new class which inherits both from ModelCallbackMixin and the legacy callback class BranchCallback.

Note

• ModelCallbackMixin should be first in inheritance order,

• the constructor of the custom callback class must take an env parameter to comply

  with the CPLEX API

• the constructor of the custom callback must call two __init__() methods:

  • one for the cplex callback class, taking an env parameter

  • one for the mixin class.

Example

class MyBranch(ModelCallbackMixin, cplex.callbacks.BranchCallback):

def __init__(self, env):

cplex.callbacks.BranchCallback.__init__(self, env) ModelCallbackMixin.__init__(self)

A custom callback must be registered with a Model class using Model.register_callback; this method assumes the custom callback has a model setter property to connect the model to the callback.

See Also:

docplex.mp.model.Model.register_callback()

index_to_var(var_index)

This method converts a variable index to a Var object.

A model must have been associated withthe mixin, otherwise an error is raised.

Parameters:

var_index – A valid variable index, that is a positive integer.

Returns:

A Docplex variable with this index, or None.

static linear_ct_to_cplex(linear_ct)

Converst a DOcplex linear constraint to CPLEX Python data

Parameters:

linear_ct – a DOcplex linear constraint.

Returns:

a 3-tuple containing elements representing the constraint in CPLEX-Python - a list of two lists, indices and coefficients , representing the linear part - a floating point number , the “right hand side” or rhs - a one-letter string (possible values are: ‘L’, ‘E’, ‘G’) representing the sense of the constraint.

Example

Assuming variable X has index 1, the constraint (2X <= 7) will be converted to

ct = 2 * X <= 7 linear_ct_cplex(ct) >>> [[1], [2.0]], 7.0, ‘L’

make_complete_solution()

Creates and returns an intermediate solution with all variables.

Values are taken from the get_values() method of the callback

Returns:

a docplex.mp.solution.SolveSolution object.

make_solution()

Creates and returns an intermediate solution with all variables.

Values are taken from the get_values() method of the callback

Returns:

a docplex.mp.solution.SolveSolution object.

make_solution_from_vars(dvars)

Creates an intermediate solution from a list of variables.

Parameters:

dvars – a list of DOcplex variables.

Returns:

a docplex.mp.solution.SolveSolution object.

property model

This property is used to get the model associated with the mixin.

An exception is raised if no model has been associated with the mixin.

Returns:

an instance of docplex.mp.Model

docplex.mp.callbacks.cb_mixin.print_called(prompt_msg=None)

A decorator function to be used on __call__() methods for derived callbacks.

Use this decorator function to decorate __call__() methods of custom callbacks.

Example:

class MyCallback(ConstraintCallbackMixin, LazyConstraintCallback):

    @print_called('my custom callback called #{0}')
    def __call__(self):
        ...

will print messages, before executing the callback code:

>>> "my custom callback called #1"
>>> "my custom callback called #2"

each time the callback is called

Parameters:

prompt_msg – A format string taking one argument (the number of calls)

Returns:

As decorator, modifies the code of the __call_ method inplace.