Module docplex.cp.expression

This module contains the basic classes representing the expressions required to describe a constraint programming model.

In particular, it defines the following classes:

None of these classes should be created explicitly. There are various factory functions to do so, such as:

Moreover, some automatic conversions are also provided. For example, a list of tuples of integers is automatically converted into a tuple set.

Detailed description

class docplex.cp.expression.CpoExpr(type, name)[source]

Bases: object

This class is an abstract class that represents any CPO expression node.

It does not contain links to children expressions that are implemented in extending classes. However, method allowing to access to children is provided with default return value.

Constructor:

Parameters:
  • type – Expression type.
  • name – Expression name.
equals(other)[source]

Checks the equality of this expression with another object.

Implementation is required with a different name than __eq__ name because this function is already overloaded to construct model expression with operator ‘==’.

Parameters:other – Other object to compare with.
Returns:True if ‘other’ is equal to this object, False otherwise.
get_max_depth()[source]

Gets the maximum expression depth.

Returns:Max expression depth.
get_name()[source]

Get the name of the expression.

Returns:Name of the expression, None if not defined
is_kind_of(tp)[source]

Checks if the type of this expression type is compatible with another type.

Parameters:tp – Other type to check.
Returns:True if this expression type is a kind of tp.
is_type(xtyp)[source]

Check if the type of this expression is a given one

Parameters:xtyp – Expected type
Returns:True if expression type is the expected one
set_name(name)[source]

Set the name of the expression.

Parameters:name – Expression name, possibly None.
class docplex.cp.expression.CpoFunctionCall(oper, rtype, oprnds)[source]

Bases: docplex.cp.expression.CpoExpr

This class represent all model expression nodes that call a predefined modeler function.

All modeling functions are available in module docplex.cp.modeler.

Constructor :param oper: Operation descriptor :param rtype: Returned type :param oprnds: List of operand expressions.

class docplex.cp.expression.CpoIntExprList[source]

Bases: list

List of integer CPO expressions.

This extension of a standard Python list overwrites __getitem__ to call docplex.cp.modeler.element() constraint if the index is a CPO integer expression.

This object is returned by the constructor method integer_var_list() in this module.

class docplex.cp.expression.CpoIntVar(dom, name)[source]

Bases: docplex.cp.expression.CpoVariable

This class represents an integer variable that can be used in a CPO model.

equals(other)[source]

Checks if this expression is equivalent to another

Parameters:other – Other object to compare with.
Returns:True if ‘other’ is semantically identical to this object, False otherwise.
get_domain()[source]

Gets the domain of the variable.

Returns:List of integers or interval tuples representing the variable domain.
set_domain(domain)[source]

Sets the domain of the variable.

The domain of the variable is a list or tuple of:

  • discrete integer values,
  • list or tuple of 2 integers representing an interval.

For example, here are valid domain definitions:

set_domain([1, 3, 4, 5, 9]) set_domain([1, (3, 5), 9])
Parameters:domain – List of integers or interval tuples representing the variable domain.
class docplex.cp.expression.CpoIntervalVar(start, end, length, size, intensity, granularity, presence, name)[source]

Bases: docplex.cp.expression.CpoVariable

This class represents an interval variable that can be used in a CPO model.

get_end()[source]

Gets the end of the interval.

Returns:End of the interval (interval expressed as a tuple of 2 integers)
get_granularity()[source]

Get the scale of the intensity function.

Returns:Scale of the intensity function, None for default (100)
get_intensity()[source]

Gets the intensity function of this interval var.

Returns:Intensity function (None, or StepFunction).
get_length()[source]

Gets the length interval.

Returns:Length of the interval (interval expressed as a tuple of 2 integers).
get_size()[source]

Gets the size of the interval.

Returns:Size of the interval (interval expressed as a tuple of 2 integers).
get_start()[source]

Gets the start of the interval.

Returns:Start of the interval (interval expressed as a tuple of 2 integers).
is_absent()[source]

Check if this interval variable must be absent.

Returns:True if this interval variable must be absent, False otherwise.
is_optional()[source]

Check if this interval variable is optional.

Returns:True if this interval variable is optional, False otherwise.
is_present()[source]

Check if this interval variable must be present.

Returns:True if this interval variable must be present, False otherwise.
set_absent()[source]

Specifies that this interval variable must be absent.

set_end(intv)[source]

Sets the end of the interval.

Parameters:intv – End of the interval (single integer or interval expressed as a tuple of 2 integers).
set_end_max(mx)[source]

Sets the maximum value of the end of the interval.

Parameters:mx – Max value of the end of the interval.
set_end_min(mn)[source]

Sets the minimum value of the end interval.

Parameters:mn – Min value of the end of the interval.
set_granularity(granularity)[source]

Sets the scale of the intensity function.

Parameters:granularity – Scale of the intensity function (integer).
set_intensity(intensity)[source]

Sets the intensity function of this interval var.

Parameters:intensity – Intensity function (None, or StepFunction).
set_length(intv)[source]

Sets the length interval.

Parameters:intv – Length of the interval (single integer or interval expressed as a tuple of 2 integers).
set_length_max(mx)[source]

Sets the maximum value of the length interval.

Parameters:mx – Max value of the length of the interval.
set_length_min(mn)[source]

Sets the minimum value of the length interval.

Parameters:mn – Min value of the length of the interval min value.
set_optional()[source]

Specifies that this interval variable is optional.

set_present()[source]

Specifies that this IntervalVar must be present.

set_size(intv)[source]

Sets the size of the interval.

Parameters:intv – Size of the interval (single integer or interval expressed as a tuple of 2 integers).
set_size_max(mx)[source]

Sets the maximum value of the size interval.

Parameters:mx – Max value of the size of the interval.
set_size_min(mn)[source]

Sets the minimum value of the size interval.

Parameters:mn – Min value of the size of the interval.
set_start(intv)[source]

Sets the start interval.

Parameters:intv – Start of the interval (single integer or interval expressed as a tuple of 2 integers).
set_start_max(mx)[source]

Sets the maximum value of the start interval.

Parameters:mx – Max value of the start of the interval.
set_start_min(mn)[source]

Sets the minimum value of the start interval.

Parameters:mn – Min value of the start of the interval.
class docplex.cp.expression.CpoSequenceVar(vars, types=None, name=None)[source]

Bases: docplex.cp.expression.CpoVariable

This class represents an sequence variable that can be used in a CPO model.

Variables are stored in ‘children’ attribute

Creates a new sequence variable.

This method creates an instance of sequence variable on the set of interval variables defined by the array ‘vars’. A list of non-negative integer types can be optionally specified. List of variables and types must be of the same size and interval variable vars[i] will have type types[i] in the sequence variable.

Parameters:
  • vars – List of IntervalVars that constitute the sequence.
  • types – List of variable types as integers, same size as vars, or None (default).
  • name – Name of the sequence, None for automatic naming.
get_interval_variables()[source]

Gets the array of variables.

Returns:Array of interval variables that are in the sequence.
get_types()[source]

Gets the array of types.

Returns:Array of variable types (array of integers), None if no type defined.
get_vars()[source]

Gets the array of variables in this sequence variable.

Returns:Array of interval variables
class docplex.cp.expression.CpoStateFunction(trmtx=None, name=None)[source]

Bases: docplex.cp.expression.CpoVariable

This class represents a state function expression node.

State functions are used by interval variables to represent the evolution of a state variable over time.

Creates a new state function.

Parameters:
  • trmtx (optional) – Transition matrix. If not given in the constructor, method set_transition_matrix() should be called after the constructor.
  • name (optional) – Name of the state function.
get_transition_matrix()[source]

Returns the transition matrix.

Returns:Transition matrix, None if none.
set_transition_matrix(trmtx)[source]

Sets the transition matrix.

Parameters:trmtx – Transition matrix, None if none.
class docplex.cp.expression.CpoTransitionMatrix(size=None, values=None, name=None)[source]

Bases: docplex.cp.expression.CpoExpr

This class represents a transition matrix that is used in CPO model to represent transition distances.

Creates a new transition matrix (square matrix of integers).

A transition matrix is a square matrix of non-negative integers that represents a minimal distance between two interval variables. An instance of transition matrix can be used in the no_overlap constraint and in state functions.

  • In a no_overlap constraint the transition matrix represents the minimal distance between two non-overlapping interval variables. The matrix is indexed using the integer types of interval variables in the sequence variable of the no_overlap constraint.
  • In a state function, the transition matrix represents the minimal distance between two integer states of the function.

There are two ways to create a transition matrix:

  • Giving only its size. In this case, a transition matrix is created by this constructor with all values initialized to zero. Matrix values can then be set using set_value() method.
  • Giving the matrix values either as list of rows, each row being a list of integers, or as a single list of integers containing the concatenation of rows. Given value is not duplicated. Any change on the value is reflected in the transition matrix, and any change in the matrix using set_value() is reflected in the source object.
Parameters:
  • size (optional) – Matrix size (width or height). If not given, the values argument must be given.
  • values (optional) – Matrix value as list of integers or list of rows. If not given, the method set_value() should be called to initialize matrix content.
  • name (optional) – Name of the matrix. None by default.
get_all_values()[source]

Returns an iterator on all matrix values, in row/column order

Returns:Iterator on all values
get_matrix()[source]

Returns the complete transition matrix.

Returns:Transition matrix as a list of integers that is the concatenation of all matrix rows.
get_size()[source]

Returns the size of the matrix.

Returns:Matrix size.
get_value(from_state, to_state)[source]

Returns a value in the transition matrix.

Parameters:
  • from_state – Index of the from state.
  • to_state – Index of the to state.
Returns:

Transition value.
set_value(from_state, to_state, value)[source]

Sets a value in the transition matrix.

Parameters:
  • from_state – Index of the from state.
  • to_state – Index of the to state.
  • value – Transition value.
class docplex.cp.expression.CpoTupleSet(size=-1, name=None)[source]

Bases: docplex.cp.expression.CpoExpr

This class is used to represent a set of integer tuples.

Constructor

Parameters:
  • size (optional) – Tuple size; default value is -1 for automatic size.
  • name (optional) – Name of the tuple set. Default is None.
add(tpl)[source]

Appends a tuple at the end of this tuple set.

Parameters:tpl – Tuple to add.
add_set(tpls)[source]

Appends a set of tuples in this tuple set.

Parameters:tpls – Iterator of tuples to add.
get_size()[source]

Returns the size of one tuple in this set.

Returns:Tuple size, -1 if undefined.
get_tuple_set()[source]

Returns the complete tuple set.

Returns:Tuple set (list of tuples)
class docplex.cp.expression.CpoValue(value, type)[source]

Bases: docplex.cp.expression.CpoExpr

CPO model expression node representing a constant value.

Constructor

Parameters:
  • value – Constant value.
  • type – Value type.
class docplex.cp.expression.CpoVariable(type, name)[source]

Bases: docplex.cp.expression.CpoExpr

This class is an abstract class extended by all expression nodes that represent a CPO variable.

Constructor:

Parameters:
  • type – Expression type.
  • name – Variable name.
docplex.cp.expression.DEFAULT_INTEGER_VARIABLE_DOMAIN = (-9007199254740991, 9007199254740991)

Default integer variable domain

docplex.cp.expression.DEFAULT_INTERVAL = (0, 4503599627370494)

Default interval.

docplex.cp.expression.INFINITY = inf

Infinity

docplex.cp.expression.INTERVAL_MAX = 4503599627370494

Maximum interval variable range value

docplex.cp.expression.INTERVAL_MIN = -4503599627370494

Minimum interval variable range value

docplex.cp.expression.INT_MAX = 9007199254740991

Maximum integer value.

docplex.cp.expression.INT_MIN = -9007199254740991

Minimum integer value.

docplex.cp.expression.binary_var(name=None)[source]

Creates a binary integer variable.

An binary variable is an integer variable with domain limited to 0 and 1

Parameters:name (optional) – Variable name, default is None for automatic name.
Returns:CpoIntVar expression
docplex.cp.expression.binary_var_dict(keys, name=None)[source]

Creates a dictionary of binary variables.

This methods creates a dictionary of binary variables associated to a list of keys given as first parameter.

If a name is given, each variable of the list is created with this name concatenated with the string representation of the corresponding key. The parameter ‘name’ can also be a function that is called to build the variable name with the variable key as parameter.

Parameters:
  • keys – Iterable of variable keys.
  • name (optional) – Variable name prefix, or function to be called on dictionary key (example: str). If not given, a name prefix is generated automatically.
Returns:

Dictionary of CpoIntVar objects (OrderedDict).
docplex.cp.expression.binary_var_list(size, name=None)[source]

Creates a list of binary variables.

This methods creates a list of binary variables.

If a name is given, each variable of the list is created with this name concatenated with the index of the variable in the list, starting by zero.

Parameters:
  • size – Size of the list of variables
  • name (optional) – Variable name prefix. If not given, a name prefix is generated automatically.
Returns:

List of binary integer variables.
docplex.cp.expression.build_cpo_expr(val)[source]

Builds an expression from a given Python value.

This method uses a cache to return the same CpoExpr for the same constant.

Parameters:val – Value to convert (possibly already an expression).
Returns:Corresponding expression.
Raises:CpoException if conversion is not possible.
docplex.cp.expression.integer_var(min=None, max=None, name=None, domain=None)[source]

Creates an integer variable.

An integer variable is a decision variable with a set of potential values called ‘domain of the variable’. This domain can be expressed either:

  • as a single interval, with a minimum and a maximum bounds included in the domain,
  • or as an extensive list of values and/or intervals.

When the domain is given extensively, an interval of the domain is represented by a tuple (min, max). Examples of variable domains expressed extensively are:

  • (1, 2, 3, 4)
  • (1, 2, (3, 7), 9)
  • ((1, 2), (7, 9))

Following integer variable declarations are equivalent:

  • v = integer_var(0, 9, “X”)
  • v = integer_var(domain=(0, 1, 2, 3, 4, 5, 6, 7, 8, 9), name=”X”)
  • v = integer_var(domain=(0, (1, 5), (6, 7), 8, 9), name=”X”)
  • v = integer_var(domain=((0, 9)), name=”X”)
Parameters:
  • min – Domain min value. Optional if domain is given extensively.
  • max – Domain max value. Optional if domain is given extensively.
  • name – Optional variable name. If not given, a name is automatically generated.
  • domain – Variable domain expressed as extensive list of values and/or intervals expressed as tuples of integers. Unused if min and max are provided.
Returns:

CpoIntVar expression
docplex.cp.expression.integer_var_dict(keys, min=None, max=None, name=None, domain=None)[source]

Creates a dictionary of integer variables.

This methods creates a dictionary of integer variables associated to a list of keys given as first parameter. All other parameters are identical to those requested by the method integer_var() that allows to create a single integer variable. See the documentation of integer_var() for details.

If a name is given, each variable of the list is created with this name concatenated with the string representation of the corresponding key. The parameter ‘name’ can also be a function that is called to build the variable name with the variable key as parameter.

Parameters:
  • keys – Iterable of variable keys.
  • min – Domain min value. Optional if domain is given extensively.
  • max – Domain max value. Optional if domain is given extensively.
  • name – Optional variable name. If not given, a name is automatically generated.
  • domain – Variable domain expressed as extensive list of values and/or intervals expressed as tuples of integers. Unused if min and max are provided.
Returns:

Dictionary of CpoIntVar objects.
docplex.cp.expression.integer_var_list(size, min=None, max=None, name=None, domain=None)[source]

Creates a list of integer variables.

This methods creates a list of integer variables whose size is given as first parameter. All other parameters are identical to those requested by the method integer_var() that allows to create a single integer variable. See the documentation of integer_var() for details.

If a name is given, each variable of the list is created with this name concatenated with the index of the variable in the list, starting by zero.

Parameters:
  • size – Size of the list of variables
  • min – Domain min value. Optional if domain is given extensively.
  • max – Domain max value. Optional if domain is given extensively.
  • name – Optional variable name. If not given, a name is automatically generated.
  • domain – Variable domain expressed as extensive list of values and/or intervals expressed as tuples of integers. Unused if min and max are provided.
Returns:

List of integer variables.
docplex.cp.expression.interval_var(start=(0, 4503599627370494), end=(0, 4503599627370494), length=(0, 4503599627370494), size=(0, 4503599627370494), intensity=None, granularity=None, optional=False, name=None)[source]

Creates an interval variable.

Represents an interval of integers. Interval variables are used mostly for scheduling to represent a task as an interval of time. In its most basic form, an interval variable can be seen as a pair of two integer variables start and end such that start < end. However there is an important difference: the interval variable can be absent to represent the fact that the interval does not exist at all (which is different from a zero-length interval).

Parameters:
  • start (optional) – Allowed range for the start of the interval (single integer or interval expressed as a tuple of 2 integers).
  • end (optional) – Allowed range for the end the interval (single integer or interval expressed as a tuple of 2 integers).
  • length (optional) – Allowed range for the length the interval (single integer or interval expressed as a tuple of 2 integers).
  • size (optional) – Allowed range for the size the interval (single integer or interval expressed as a tuple of 2 integers).
  • intensity (optional) – StepFunction that specifies relation between size and length of the interval.
  • granularity (optional) – Scale of the intensity function.
  • optional (optional) – Optional presence indicator.
  • name (optional) – Name of the variable. If not given, a name is generated automatically.
Returns:

IntervalVar expression.
docplex.cp.expression.interval_var_dict(keys, start=(0, 4503599627370494), end=(0, 4503599627370494), length=(0, 4503599627370494), size=(0, 4503599627370494), intensity=None, granularity=None, optional=False, name=None)[source]

Creates a list of interval variables.

If a name is given, each variable of the array is created with this name concatenated with the index of the variable in the list.

Parameters:
  • keys – Iterable of variable keys.
  • start (optional) – Allowed range for the start of the interval (single integer or interval expressed as a tuple of 2 integers).
  • end (optional) – Allowed range for the end the interval (single integer or interval expressed as a tuple of 2 integers).
  • length (optional) – Allowed range for the length the interval (single integer or interval expressed as a tuple of 2 integers).
  • size (optional) – Allowed range for the size the interval (single integer or interval expressed as a tuple of 2 integers).
  • intensity (optional) – StepFunction that specifies relation between size and length of the interval.
  • granularity (optional) – Scale of the intensity function.
  • optional (optional) – Optional presence indicator.
  • name (optional) – Variable name prefix, or function to be called on dictionary key (example: str). If not given, a name prefix is generated automatically.
Returns:

Dictionary of CpoIntervalVar objects.
docplex.cp.expression.interval_var_list(asize, start=(0, 4503599627370494), end=(0, 4503599627370494), length=(0, 4503599627370494), size=(0, 4503599627370494), intensity=None, granularity=None, optional=False, name=None)[source]

Creates a list of interval variables.

If a name is given, each variable of the array is created with this name concatenated with the index of the variable in the list.

Parameters:
  • asize – Size of the list of variables
  • start (optional) – Allowed range for the start of the interval (single integer or interval expressed as a tuple of 2 integers).
  • end (optional) – Allowed range for the end the interval (single integer or interval expressed as a tuple of 2 integers).
  • length (optional) – Allowed range for the length the interval (single integer or interval expressed as a tuple of 2 integers).
  • size (optional) – Allowed range for the size the interval (single integer or interval expressed as a tuple of 2 integers).
  • intensity (optional) – StepFunction that specifies relation between size and length of the interval.
  • granularity (optional) – Scale of the intensity function.
  • optional (optional) – Optional presence indicator.
  • name (optional) – Name of the variable. If not given, a name is generated automatically.
Returns:

List of interval variables.
docplex.cp.expression.sequence_var(vars, types=None, name=None)[source]

Creates a new sequence variable (list of interval variables).

This method creates an instance of sequence variable on the set of interval variables defined by the array ‘vars’. A list of non-negative integer types can be optionally specified. List of variables and types must be of the same size and interval variable vars[i] will have type types[i] in the sequence variable.

Parameters:
  • vars – List of IntervalVars that constitute the sequence.
  • types – List of variable types as integers, same size as vars, or None (default).
  • name – Name of the sequence, None for automatic naming.
Returns:

IntervalVar expression.
docplex.cp.expression.state_function(trmtx=None, name=None)[source]

Create a new State Function

Parameters:
  • trmtx – Transition matrix
  • name – Name of the state function
Returns:

CpoStateFunction expression
docplex.cp.expression.transition_matrix(size=None, values=None, name=None)[source]

Creates a new transition matrix (square matrix of integers).

A transition matrix is a square matrix of non-negative integers that represents a minimal distance between two interval variables. An instance of transition matrix can be used in the no_overlap constraint and in state functions.

  • In a no_overlap constraint the transition matrix represents the minimal distance between two non-overlapping interval variables. The matrix is indexed using the integer types of interval variables in the sequence variable of the no_overlap constraint.
  • In a state function, the transition matrix represents the minimal distance between two integer states of the function.

There are two ways to create a transition matrix:

  • Giving only its size. In this case, a transition matrix is created by this constructor with all values initialized to zero. Matrix values can then be set using set_value() method.
  • Giving the matrix values either as list of rows, each row being a list of integers, or as a single list of integers containing the concatenation of rows. Given value is not duplicated. Any change on the value is reflected in the transition matrix, and any change in the matrix using set_value() is reflected in the source object.
Parameters:
  • size (optional) – Matrix size (width or height). If not given, the values argument must be given.
  • values (optional) – Matrix value as list of integers or list of rows. If not given, the method set_value() should be called to initialize matrix content.
  • name (optional) – Name of the matrix. None by default.
Returns:

TransitionMatrix expression.
docplex.cp.expression.tuple_set(size, name=None)[source]

Create tuple set.

The tuple set can be created empty, and then filled using methods provided by the TupleSet object. Another option is to pass the list of all tuples as first parameter of this function.

Parameters:
  • size – Size of one tuple, or initial list of tuples.
  • name – Object name (default is None).
Returns:

TupleSet expression.