This page is for an old version of Hexaly Optimizer. We recommend that you update your version and read the documentation for the latest stable release.

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