docplex.mp.advmodel module

class docplex.mp.advmodel.AdvModel(name=None, context=None, **kwargs)[source]

Bases: docplex.mp.model.Model

This class is a specialized version of the docplex.mp.model.Model class with useful non-standard modeling functions.

matrix_constraints(coef_mat, dvars, rhs, sense='le')[source]

Creates a list of linear constraints from a matrix of coefficients, a sequence of variables, and a sequence of numbers.

This method returns the list of constraints built from

A.X <op> B

where A is the coefficient matrix (of size (M,N)), X is the variable sequence (size N), and B is the sequence of right-hand side values (of size M).

<op> is the comparison operator that defines the sense of the constraint. By default, this generates a ‘less-than-or-equal’ constraint.

Example

Model.scal_prod_vars_triple([x, y], [z, t], [2, 3]) returns the expression 2xz + 3yt.

Parameters:
  • coef_mat – A matrix of coefficients with M rows and N columns. This argument accepts either a list of lists of numbers, a numpy array with size (M,N), or a scipy sparse matrix.
  • dvars – An ordered sequence of decision variables: accepts a Python list, numpy array, or a pandas series. The size of the sequence must match the number of columns in the matrix.
  • rhs – A sequence of numbers: accepts a Python list, a numpy array, or a pandas series. The size of the sequence must match the number of rows in the matrix.
  • sense – A constraint sense, accepts either a value of type ComparisonType or a string (e.g ‘le’, ‘eq’, ‘ge’).
Returns:

A list of linear constraints.

Example

If A is a matrix of coefficients with 2 rows and 3 columns:

A = [[1, 2, 3],
     [4, 5, 6]],
X = [x, y, z] where x, y, and z are decision variables (size 3), and

B = [100, 200], a sequence of numbers (size 2),

then:

`mdl.matrix_constraint(A, X, B, 'GE')` returns a list of two constraints
[(x + 2y+3z <= 100), (4x + 5y +6z <= 200)].

Note

If the dimensions of the matrix and variables or of the matrix and number sequence do not match, an error is raised.

matrix_ranges(coef_mat, dvars, lbs, ubs)[source]

Creates a list of range constraints from a matrix of coefficients, a sequence of variables, and two sequence of numbers.

This method returns the list of range constraints built from

L <= Ax <= U

where A is the coefficient matrix (of size (M,N)), X is the variable sequence (size N), L and B are sequence of numbers (resp. the lower and upper bounds of the ranges) both with size M.

Parameters:
  • coef_mat – A matrix of coefficients with M rows and N columns. This argument accepts either a list of lists of numbers, a numpy array with size (M,N), or a scipy sparse matrix.
  • dvars – An ordered sequence of decision variables: accepts a Python list, numpy array, or a pandas series. The size of the sequence must match the number of columns in the matrix.
  • lbs – A sequence of numbers: accepts a Python list, a numpy array, or a pandas series. The size of the sequence must match the number of rows in the matrix.
  • ubs – A sequence of numbers: accepts a Python list, a numpy array, or a pandas series. The size of the sequence must match the number of rows in the matrix.
Returns:

A list of range constraints.

Example:

If A is a matrix of coefficients with 2 rows and 3 columns:

        A = [[1, 2, 3],
             [4, 5, 6]],
        X = [x, y, z] where x, y, and z are decision variables (size 3), and

        L = [101. 102], a sequence of numbers (size 2),
        U = [201, 202]

then::

    `mdl.range_constraints(A, X, L, U)` returns a list of two ranges
    [(101 <= x + 2y+3z <= 102), (201 <= 4x + 5y +6z <= 202)].

Note

If the dimensions of the matrix and variables or of the matrix and number sequence do not match, an error is raised.

quad_matrix_sum(matrix, dvars, symmetric=False)[source]

Creates a quadratic expression equal to the quadratic form of a list of decision variables and a matrix of coefficients.

This method sums all quadratic terms built by multiplying the [i,j]th coefficient in the matrix by the product of the i_th and j_th variables in dvars; in mathematical terms, the expression formed by x’Qx.

Parameters:
  • matrix – A accepts either a list of lists of numbers, a numpy array, a pandas dataframe, or a scipy sparse matrix in COO format. T The resulting matrix must be square with size (N,N) where N is the number of variables.
  • dvars – A list or an iterator on variables.
  • symmetric – A boolean indicating whether the matrix is symmetric or not (default is False). No check is done.
Returns:

An instance of docplex.mp.quad.QuadExpr or 0.

Note

The matrix must be square but not necessarily symmetric. The number of rows of the matrix must be equal to the size of the variable sequence.

The symmetric flag only explores half of the matrix and doubles non-diagonal factors. No actual check is done. This flag has no effect on scipy sparse matrix.

Example

Model.quad_matrix_sum([[[1, 2], [3, 4]], [x, y]) returns the expression x^2+4y^2+5x*yt.

scal_prod_triple(left_terms, right_terms, coefs)[source]

Creates a quadratic expression from two lists of linear expressions and a sequence of coefficients.

This method sums all quadratic terms built by multiplying the i_th coefficient by the product of the i_th expression in left_terms and the i_th expression in right_terms

This method accepts different types of input for its arguments. The expression sequences can be either lists or iterators of objects that can be converted to linear expressions, that is, variables or linear expressions (but no quadratic expressions). The most usual case is variables. The coefficients can be either a list of numbers, an iterator over numbers, or a number.

Example

Model.scal_prod_triple([x, y], [z, t], [2, 3]) returns the expression 2xz + 3yt.

Parameters:
  • left_terms – A list or an iterator on variables or expressions.
  • right_terms – A list or an iterator on variables or expressions.
  • coefs – A list or an iterator on numbers or a number.
Returns:

An instance of docplex.mp.quad.QuadExpr or 0.

Note

If either list or iterator is empty, this method returns zero.

scal_prod_triple_vars(left_terms, right_terms, coefs)[source]

Creates a quadratic expression from two lists of variables and a sequence of coefficients.

This method sums all quadratic terms built by multiplying the i_th coefficient by the product of the i_th expression in left_terms and the i_th expression in right_terms

This method is faster than the standard generic scalar quadratic product method due to the fact that it takes only variables and does not take expressions as arguments.

Example

Model.scal_prod_vars_triple([x, y], [z, t], [2, 3]) returns the expression 2xz + 3yt.

Parameters:
  • left_terms – A list or an iterator on variables.
  • right_terms – A list or an iterator on variables.
  • coefs – A list or an iterator on numbers or a number.
Returns:

An instance of docplex.mp.quad.QuadExpr or 0.

Note

If either list or iterator is empty, this method returns zero.

scal_prod_vars_all_different(terms, coefs)[source]

Creates a linear expression equal to the scalar product of a list of decision variables and a sequence of coefficients.

The variable sequence is a list or an iterator of variables. The coefficients can be either a list of numbers, an iterator over numbers, or a number.

This method is faster than the standard generic scalar product method due to the fact that it takes only variables and does not take expressions as arguments.

Parameters:
  • terms – A list or an iterator on variables only, with no duplicates.
  • coefs – A list or an iterator on numbers, or a number.
Returns:

A linear expression or 0.

Note

If either list or iterator is empty, this method returns zero.

Note

To improve performance, the check for duplicates can be turned off by setting checker=’none’ in the kwargs of the docplex.mp.model.Model object. As this argument turns off checking everywhere, it should be used with extreme caution.

sumsq_vars_all_different(terms)[source]

Creates a quadratic expression by summing squares over a sequence.

The variable sequence is a list or an iterator of variables.

This method is faster than the standard summation of squares method due to the fact that it takes only variables and does not take expressions as arguments.

Parameters:terms – A list or an iterator on variables only, with no duplicates.
Returns:A quadratic expression or 0.

Note

If the list or iterator is empty, this method returns zero.

Note

To improve performance, the check for duplicates can be turned off by setting checker=’none’ in the kwargs of the docplex.mp.model.Model object. As this argument turns off checking everywhere, it should be used with extreme caution.