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.

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_interval

Returns true if this expression is an interval, 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.

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 int.

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_interval()

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

Returns

True if the expression is an interval.

Return type

bool

Since

12.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, a LSInterval, a LSCollection or a 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, LSInterval, LSCollection or LSArray

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.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 double and its value is NaN (Not a Number)

  • 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 4 cases:

  • It is a double and its value is NaN (Not a Number).

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

  • It is an interval with at least one undefined bound.

  • It is the result of any ill-defined operation (at with out of bounds index or operations on undefined values for instance).

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().

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.NOT, 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