LSExpression Class¶

class localsolver.LSExpression¶: Mathematical modeling expression. Expressions are used to build the mathematical optimization model associated to LocalSolver. An expression is composed of an operator (which corresponds to its type) and its operands (which are other expressions of the model).

Summary¶

Attributes¶
`operator`	Operator of the expression.
`index`	Index of the expression.
`value`	Value of the expression in the best solution found by the solver.
`name`	Name of the expression in the model.
`nb_operands`	Number of operands of the expression.
`operands`	Operands of the expression.
`external_context`	External context of an external function.
`blackbox_context`	Black-box context of a black-box function.

Methods¶
`get_operator`	Gets the operator of this expression.
`get_index`	Gets the index of this expression in the model.
`is_constant`	Returns true if this expression is typed as constant in the model, false otherwise.
`is_decision`	Returns true if this expression is typed as decision in the model, false otherwise.
`is_constraint`	Returns true if this expression is tagged as constraint in the model, false otherwise.
`is_objective`	Returns true if this expression is tagged as objective in the model, false otherwise.
`is_double`	Returns true if this expression is a double, false otherwise.
`is_int`	Returns true if this expression is an integer, false otherwise.
`is_bool`	Returns true if this expression is a boolean (ie 0 or 1), false otherwise.
`is_array`	Returns true if this expression is an array, false otherwise.
`is_collection`	Returns true if this expression is a collection (list or set), false otherwise.
`is_function`	Returns true if this expression is a function, false otherwise.
`add_operand`	Add the given operand to this expression.
`add_operands`	Add the given operands to the expression.
`get_operand`	Gets the operand with the given index.
`set_operand`	Replaces the operand of the given index.
`get_nb_operands`	Returns the number of operands of this expression.
`set_value`	Sets the value of this expression in the current solution found by the solver.
`get_value`	Gets the value of this expression in the best solution found by the solver.
`get_external_context`	Gets the external function context of this expression.
`get_blackbox_context`	Gets the black-box function context of this expression.
`is_violated`	Returns true if the given expression is violated in the best solution found by the solver.
`is_undefined`	Returns true if the given expression has an undefined value in the best solution found by the solver.
`is_named`	Returns true if this expression has a name, and false otherwise.
`set_name`	Sets the name of this expression.
`get_name`	Gets the name of this expression or the empty string if no name has been set.

Special methods¶
`__add__`	Creates a new LSOperator.SUM expression.
`__sub__`	Creates a new LSOperator.SUB expression.
`__mul__`	Creates a new LSOperator.PROD expression.
`__div__`	Creates a new LSOperator.DIV expression.
`__mod__`	Creates a new LSOperator.MOD expression.
`__pow__`	Creates a new LSOperator.POW expression.
`__or__`	Creates a new LSOperator.OR expression.
`__and__`	Creates a new LSOperator.AND expression.
`__xor__`	Creates a new LSOperator.XOR expression.
`__invert__`	Creates a new LSOperator.NOT expression.
`__eq__`	Creates a new LSOperator.EQ expression.
`__ne__`	Creates a new LSOperator.NEQ expression.
`__lt__`	Creates a new LSOperator.LT expression.
`__gt__`	Creates a new LSOperator.EQ expression.
`__geq__`	Creates a new LSOperator.GEQ expression.
`__leq__`	Creates a new LSOperator.EQ expression.
`__getitem__`	Creates a new LSOperator.AT expression.
`__call__`	Creates a new LSOperator.CALL expression.
`__str__`	Returns useful info about this expression (according to the state of LocalSolver).

Instance methods¶

LSExpression.get_operator()¶

Gets the operator of this expression.

You can also use the shortcut member operator

Returns:	Operator
Return type:	LSOperator

LSExpression.get_index()¶

Gets the index of this expression in the model.

Returns:	Index in the model of this LSExpression.
Return type:	`int`

LSExpression.is_constant()¶

Returns true if this expression is typed as constant in the model, false otherwise.

Returns:	True if typed as constant.
Return type:	`bool`

LSExpression.is_decision()¶

Returns true if this expression is typed as decision in the model, false otherwise.

Returns:	True if typed as decision.
Return type:	`bool`

LSExpression.is_constraint()¶

Returns true if this expression is tagged as constraint in the model, false otherwise.

Returns:	True if tagged as constraint
Return type:	`bool`

LSExpression.is_objective()¶

Returns true if this expression is tagged as objective in the model, false otherwise.

Returns:	True if tagged as objective.
Return type:	`bool`

LSExpression.is_double()¶

Returns true if this expression is a double, false otherwise. Only allowed in states LSState.PAUSED or LSState.STOPPED.

Returns:	True if the expression is a double.
Return type:	`bool`
Since:	3.0

LSExpression.is_int()¶

Returns true if this expression is an integer, false otherwise. Only allowed in states LSState.PAUSED or LSState.STOPPED. Note that a boolean is also an integer.

Returns:	True if the expression is a double.
Return type:	`bool`
Since:	3.0

LSExpression.is_bool()¶

Returns true if this expression is a boolean (ie 0 or 1), false otherwise. Only allowed in states LSState.PAUSED or LSState.STOPPED.

Returns:	True if the expression is a boolean.
Return type:	`bool`
Since:	3.0

LSExpression.is_array()¶

Returns true if this expression is an array, false otherwise. Only allowed in states LSState.PAUSED or LSState.STOPPED.

Returns:	True if the expression is an array.
Return type:	`bool`
Since:	3.1

LSExpression.is_collection()¶

Returns true if this expression is a collection (list or set), false otherwise. Only allowed in states LSState.PAUSED or LSState.STOPPED.

Returns:	True if the expression is a collection.
Return type:	`bool`
Since:	5.5

LSExpression.is_function()¶

Returns true if this expression is a function, false otherwise. Only allowed in states LSState.PAUSED or LSState.STOPPED.

Returns:	True if the expression is a function.
Return type:	`bool`
Since:	6.0

LSExpression.add_operand(operand)¶

Add the given operand to this expression. The operand can be an LSExpression, a boolean, an integer or a double. Only allowed in state LSState.MODELING.

Parameters:	operand – Operand to add. Can be an LSExpression, a boolean, an integer or a double.

LSExpression.add_operands(operands)¶

LSExpression.add_operands(*operands)

Add the given operands to the expression. Any object that implements the __iter__ method is accepted. Thus, lists, tuples, sets and their comprehensions counterpart are accepted. It is also possible to use this method with a variadic number of arguments.

Each operand can be an LSExpression, a boolean, an integer or a double. Please note that some of these types can be explicitly forbidden for specific operators. For example, doubles are not allowed with the modulo operator.

Parameters:	operands – Operands to add. The object must be iterable.
Since:	5.5

LSExpression.get_operand(op_index)¶

Gets the operand with the given index.

You can also use the shortcut member operands

Parameters:	op_index (`int`) – Index of the operand
Returns:	Operand
Return type:	LSExpression

LSExpression.set_operand(op_index, operand)¶

Replaces the operand of the given index. The new operand can be an LSExpression, a boolean, an integer or a double.

Parameters:	op_index (`int`) – Index of the operand to change operand – New operand.

LSExpression.get_nb_operands()¶

Returns the number of operands of this expression.

You can also use the shortcut member nb_operands or the collection member operands

Returns:	Number of operands
Return type:	`int`

LSExpression.set_value(value)¶

Sets the value of this expression in the current solution found by the solver. Only allowed for decisions. Only allowed in state LSState.STOPPED.

The given value must be compatible with the type of the expression. For example, you cannot set a double value to a boolean expression.

This method is a shortcut for LSSolution.set_value()

You can also use the shortcut member value

Parameters:	value – Value assigned to this expression.

LSExpression.get_value()¶

Gets the value of this expression in the best solution found by the solver. Only allowed in states LSState.PAUSED or LSState.STOPPED.

The type of the returned value depends on the type of the LSExpression. It can be a boolean, an integer, a double, an LSCollection or an LSArray.

This method is a shortcut for LSSolution.get_value()

You can also use the shortcut member value

Returns:	Value of the LSExpression in the best solution.
Return type:	`bool`, `int`, `double` or `LSCollection`

LSExpression.get_external_context()¶

Gets the external function context of this expression. Only allowed if this expression is an external function.

Returns:	Context of the external function
See:	`LSExternalContext`

LSExpression.get_blackbox_context()¶

Gets the black-box function context of this expression. Only allowed if this expression is a black-box function.

Returns:	Context of the black-box function
See:	`LSBlackBoxContext`

LSExpression.is_violated()¶

Returns true if the given expression is violated in the best solution found by the solver.

An expression can be violated in 3 cases:

it is a constraint and its value is 0

it is a a double and its value is NaN (NotANumber)

it is an integer or boolean with no valid value (arithmetic or out of bounds exception).

Only allowed in states LSState.PAUSED or LSState.STOPPED.

This method is a shortcut for LSSolution.is_violated()

Returns:	True if this expression is violated in the best solution.
Return type:	`bool`

LSExpression.is_undefined()¶

Returns true if the given expression has an undefined value in the best solution found by the solver. An expression can be undefined in 2 cases:

It is a a double and its value is NaN (NotANumber).
It is an integer or boolean with no valid value (arithmetic or out of bounds exception).

Only allowed in states LSState.PAUSED or LSState.STOPPED.

This method is a shortcut for LSSolution.is_undefined()

Since:	7.0
Returns:	True if this expression has an undefined value in the best solution.
Return type:	`bool`

LSExpression.is_named()¶

Returns true if this expression has a name, and false otherwise.

Returns:	True if named
Return type:	`bool`

LSExpression.set_name(name)¶

Sets the name of this expression. Only allowed in state LSState.MODELING. The name cannot be empty. Two operators of the model cannot share the same name. Useful for debugging or logging purposes.

You can also use the shortcut member name

Parameters:	name (str) – Name of the LSExpression in the model. The name must be unique.

LSExpression.get_name()¶

Gets the name of this expression or the empty string if no name has been set.

You can also use the shortcut member name

Returns:	Name
Return type:	`str`

Instance attributes¶

All get/set methods have their attribute counterpart. You can use them as shortcuts to improve the readability or your models and codes.

LSExpression.operator¶: Operator of the expression. This attribute is read-only. It is a shortcut for get_operator().

LSExpression.index¶: Index of the expression. This attribute is read-only. It is a shortcut for get_index().

LSExpression.value¶: Value of the expression in the best solution found by the solver. It is a shortcut for get_value() and set_value().

LSExpression.name¶: Name of the expression in the model. The name must be unique. It is a shortcut for get_name() and set_name().

LSExpression.nb_operands¶: Number of operands of the expression. This attribute is read-only. It is a shortcut for get_nb_operands().

LSExpression.operands¶: Operands of the expression. The returned object is iterable, supports the len function and can be indexed with integers. It is a shortcut for get_operand(), get_nb_operands() and set_operand(). Please note, that you still have to use add_operand() to add new operands to the expression.

LSExpression.external_context¶: External context of an external function. This attribute is readonly and only accessible if the expression is indeed an external function. It is a shortcut for get_external_context().

LSExpression.blackbox_context¶: Black-box context of a black-box function. This attribute is readonly and only accessible if the expression is indeed an black-box function. It is a shortcut for get_blackbox_context().

Special operators and methods¶

LSExpression overloads many operators and builtin functions to write models very quickly and efficiently. The overloaded operators are:

The arithmetic operators: +, -, *, %, /, **
The bitwise operators: ~, &, |, ^
The relational operators: ==, !=, >=, <=, >, <
The compound operators: +=, -=, *=, /=, **=, &=, |=, ^=
The special index operator: [] (__getitem__).

Except for the compound operators that can work in-place, calling an overloaded operators creates a completely new LSExpression. For example:

x = model.bool()
y = model.bool()
z = x + y

Creates a new LSExpression z with two operands: x and y.

For that reason, you should avoid creating large nary expressions with x = x + y. It is preferable to use the dedicated compound operators x += y that remove the unecessary intermediate LSExpressions.

LSExpression.__add__(y)¶

LSExpression.__radd__(y)¶

Creates a new LSOperator.SUM expression. It is a shortcut for model.create_expression(LSOperator.SUM, self, y).

Parameters:	y – Second operand. Can be an LSExpression, a boolean, an integer or a double.
Returns:	A new `LSOperator.SUM` expression
Return type:	LSExpression

LSExpression.__sub__(y)¶

LSExpression.__rsub__(y)¶

Creates a new LSOperator.SUB expression. It is a shortcut for model.create_expression(LSOperator.SUB, self, y).

Parameters:	y – Second operand. Can be an LSExpression, a boolean, an integer or a double.
Returns:	A new `LSOperator.SUB` expression
Return type:	LSExpression

LSExpression.__mul__(y)¶

LSExpression.__rmul__(y)¶

Creates a new LSOperator.PROD expression. It is a shortcut for model.create_expression(LSOperator.PROD, self, y).

Parameters:	y – Second operand. Can be an LSExpression, a boolean, an integer or a double.
Returns:	A new `LSOperator.PROD` expression
Return type:	LSExpression

LSExpression.__div__(y)¶

LSExpression.__rdiv__(y)¶

LSExpression.__truediv__(y)¶

LSExpression.__rtruediv__(y)¶

Creates a new LSOperator.DIV expression. It is a shortcut for model.create_expression(LSOperator.DIV, self, y).

Parameters:	y – Second operand. Can be an LSExpression, a boolean, an integer or a double.
Returns:	A new `LSOperator.DIV` expression
Return type:	LSExpression

LSExpression.__mod__(y)¶

LSExpression.__rmod__(y)¶

Creates a new LSOperator.MOD expression. It is a shortcut for model.create_expression(LSOperator.MOD, self, y).

Parameters:	y – Second operand. Can be an LSExpression with integer value, a boolean or an integer.
Returns:	A new `LSOperator.MOD` expression
Return type:	LSExpression

LSExpression.__pow__(y)¶

LSExpression.__rpow__(y)¶

Creates a new LSOperator.POW expression. It is a shortcut for model.create_expression(LSOperator.POW, self, y).

Parameters:	y – Second operand. Can be an LSExpression, a boolean, an integer or a double.
Returns:	A new `LSOperator.POW` expression
Return type:	LSExpression

LSExpression.__or__(y)¶

LSExpression.__ror__(y)¶

Creates a new LSOperator.OR expression. It is a shortcut for model.create_expression(LSOperator.OR, self, y).

Parameters:	y – Second operand. Can be an LSExpression with boolean value, a boolean, an integer or a double.
Returns:	A new `LSOperator.OR` expression
Return type:	LSExpression

LSExpression.__and__(y)¶

LSExpression.__rand__(y)¶

Creates a new LSOperator.AND expression. It is a shortcut for model.create_expression(LSOperator.AND, self, y).

Parameters:	y – Second operand. Can be an LSExpression with boolean value, a boolean, an integer or a double.
Returns:	A new `LSOperator.AND` expression
Return type:	LSExpression

LSExpression.__xor__(y)¶

LSExpression.__rxor__(y)¶

Creates a new LSOperator.XOR expression. It is a shortcut for model.create_expression(LSOperator.XOR, self, y).

Parameters:	y – Second operand. Can be an LSExpression with boolean value, a boolean, an integer or a double.
Returns:	A new `LSOperator.XOR` expression
Return type:	LSExpression

LSExpression.__invert__()¶

Creates a new LSOperator.NOT expression. It is a shortcut for model.create_expression(LSOperator.XOR, self).

Returns:	A new `LSOperator.NOT` expression
Return type:	LSExpression

LSExpression.__eq__(y)¶

Creates a new LSOperator.EQ expression. It is a shortcut for model.create_expression(LSOperator.EQ, self, y).

Parameters:	y – Second operand. Can be an LSExpression, a boolean, an integer or a double.
Returns:	A new `LSOperator.EQ` expression
Return type:	LSExpression

LSExpression.__ne__(y)¶

Creates a new LSOperator.NEQ expression. It is a shortcut for model.create_expression(LSOperator.NEQ, self, y).

Parameters:	y – Second operand. Can be an LSExpression, a boolean, an integer or a double.
Returns:	A new `LSOperator.NEQ` expression
Return type:	LSExpression

LSExpression.__lt__(y)¶

Creates a new LSOperator.LT expression. It is a shortcut for model.create_expression(LSOperator.LT, self, y).

Parameters:	y – Second operand. Can be an LSExpression, a boolean, an integer or a double.
Returns:	A new `LSOperator.LT` expression
Return type:	LSExpression

LSExpression.__gt__(y)¶

Creates a new LSOperator.EQ expression. It is a shortcut for model.create_expression(LSOperator.GT, self, y).

Parameters:	y – Second operand. Can be an LSExpression, a boolean, an integer or a double.
Returns:	A new `LSOperator.GT` expression
Return type:	LSExpression

LSExpression.__geq__(y)¶

Creates a new LSOperator.GEQ expression. It is a shortcut for model.create_expression(LSOperator.GEQ, self, y).

Parameters:	y – Second operand. Can be an LSExpression, a boolean, an integer or a double.
Returns:	A new `LSOperator.GEQ` expression
Return type:	LSExpression

LSExpression.__leq__(y)¶

Creates a new LSOperator.EQ expression. It is a shortcut for model.create_expression(LSOperator.LEQ, self, y).

Parameters:	y – Second operand. Can be an LSExpression, a boolean, an integer or a double.
Returns:	A new `LSOperator.LEQ` expression
Return type:	LSExpression

LSExpression.__getitem__(y)¶

Creates a new LSOperator.AT expression. It is a shortcut for model.create_expression(LSOperator.AT, self, y).

Parameters:	y – Second operand. Can be an LSExpression, a boolean, an integer or a double.
Returns:	A new `LSOperator.LEQ` expression
Return type:	LSExpression

LSExpression.__call__(*args)¶

Creates a new LSOperator.CALL expression. It is a shortcut for model.create_expression(LSOperator.CALL, self, args).

Parameters:	args – Operands. The object must be iterable.
Returns:	A new `LSOperator.CALL` expression
Return type:	LSExpression

LSExpression.__str__()¶

Returns useful info about this expression (according to the state of LocalSolver). Useful for debugging or logging purposes.

Returns:	Info about this search during the solving process.
Return type:	`str`