Builtin functions and variables¶

Core functions¶

println([arg0[, arg1[, ...]]])¶: Writes the arguments to the standard output followed by a new line. If an argument is not convertible to a string, an error is thrown. You can use this function with a variadic number of arguments or with the variadic call syntax. If no argument is given, this function simply prints a new empty line.

print([arg0[, arg1[, ...]]])¶: Same as println() without the new line.

map([arg0[, arg1[, ...]]]): Creates a new map initialized with the given arguments. Keys will start at 0. You can use this function with a variadic number of arguments or with the variadic call syntax. If no argument is given, this function returns an empty map. .

Mathematical operators¶

Most of these operators can be used in two different modes depending on the type of the given arguments:

With integers or doubles: the modeler performs the asked operation and returns an integer or a double. This mode applies only if all arguments are integers or doubles. As soon as one solver expression is given, the second mode is used. However, you can freely mix integers and doubles: the final result will be casted to double if necessary.
With solver expressions: the expression represented by the operator is created and added to the LocalSolver model. This mode is used as soon as one argument is a solver expression.

For example:

// The sum operator creates and adds a new solver expression
// because at least one argument is neither an integer, nor a double.
x[i in 0...N] <- bool();
s <- sum[i in 0...N](x[i]);

// The sum operator returns the sum of odd numbers between
// 1 and N as an integer because all the operands are integers.
odd = sum[i in 0...N : i % 2 == 1](i);

bool()¶

Creates a new boolean decision and adds it to the LocalSolver model. This function always returns a solver expression.

Returns:: A solver expression.

float(lb, ub)¶

Creates a new float decision with the given bounds [lb, ub] and adds it to the LocalSolver model. This function always returns a solver expression. Bounds must be numbers (integers or doubles).

Parameters:

lb – Lower bound.
ub – Upper bound (included).

Returns:

A solver expression.

int(lb, ub)¶

Creates a new integer decision with the given bounds [lb, ub] and adds it to the LocalSolver model. This function always returns a solver expression. Bounds must be integers.

Parameters:

lb (int) – Lower bound.
ub (int) – Upper bound (included).

Returns:

A solver expression.

interval(minStart, maxEnd)¶

Creates a new interval decision included in [minStart, maxEnd) and adds it to the LocalSolver model. This function always returns a solver expression. Bounds must be integers.

Parameters:

minStart (int) – Min start.
maxEnd (int) – Max end.

Returns:

A solver expression.

list(n)¶

Creates a new list decision that can contain integers in [0, n-1]. See lists variables for a description of list variables.

Returns:: A solver expression.

set(n)¶

Creates a new set decision that can contain integers in [0, n-1]. See sets variables for a description of set variables.

Returns:: A solver expression.

sum([arg0[, arg1[, ...]]])¶

Computes or creates a sum expression with the given arguments. Each argument can be a solver expression, a boolean, an integer or a double. It is also possible to use this function with a variadic number of arguments or with the variadic call syntax. If no argument is given, this function returns the integer 0.

Returns:: A solver expression if at least one solver expression is given as argument, a number otherwise.

sub(a, b)¶

Computes the difference between two numbers or creates a sub expression. Each argument can be a solver expression, a boolean, an integer or a double.

Returns:: A solver expression if at least one solver expression is given as argument, a number otherwise.

prod([arg0[, arg1[, ...]]])¶

Computes or creates a product expression with the given arguments. Each argument can be a solver expression, a boolean, an integer or a double. It is also possible to use this function with a variadic number of arguments or with the variadic call syntax. If no argument is given, this function returns the integer 1.

Returns:: A solver expression if at least one solver expression is given as argument, a number otherwise.

div(a, b)¶

Computes the division between two numbers or creates a div expression. Each argument can be a solver expression, a boolean, an integer or a double.

Returns:: A solver expression if at least one solver expression is given as argument, a double otherwise.

mod(a, b)¶

Computes the modulo between two integers or creates a mod expression. Each argument can be a solver expression, a boolean or an integer.

Returns:: A solver expression if at least one solver expression is given as argument, an integer otherwise.

min(arg0[, arg1[, arg2[, ...]]])¶

Computes or creates a min expression with the given arguments. Each argument can be a solver expression, a boolean, an integer or a double. It is also possible to use this function with a variadic number of arguments or with the variadic call syntax, but note that at least one argument is required.

Returns:: A solver expression if at least one solver expression is given as argument, a number otherwise.

max(arg0[, arg1[, arg2[, ...]]])¶

Computes or creates a max expression with the given arguments. Each argument can be a solver expression, a boolean, an integer or a double. It is also possible to use this function with a variadic number of arguments or with the variadic call syntax, but note that at least one argument is required.

Returns:: A solver expression if at least one solver expression is given as argument, a number otherwise.

eq(a, b)¶

Compares the arguments or creates an equality solver expression. Each argument can be a solver expression, a boolean, an integer or a double.

Returns:: A solver expression if at least one solver expression is given as argument, a boolean otherwise.

neq(a, b)¶

Compares the arguments or creates a disequality solver expression. Each argument can be a solver expression, a boolean, an integer or a double.

Returns:: A solver expression if at least one solver expression is given as argument, a boolean otherwise.

geq(a, b)¶

Compares the arguments or creates an inequality ‘greater than or equal to’. solver expression. Each argument can be a solver expression, a boolean, an integer or a double.

Returns:: A solver expression if at least one solver expression is given as argument, a boolean otherwise.

leq(a, b)¶

Compares the arguments or creates an inequality ‘lower than or equal to’ solver expression. Each argument can be a solver expression, a boolean, an integer or a double.

Returns:: A solver expression if at least one solver expression is given as argument, a boolean otherwise.

gt(a, b)¶

Compares the arguments or creates an inequality ‘greater than’ solver expression. Each argument can be a solver expression, a boolean, an integer or a double.

Returns:: A solver expression if at least one solver expression is given as argument, a boolean otherwise.

lt(a, b)¶

Compares the arguments or creates an inequality ‘lower than’ solver expression. Each argument can be a solver expression, a boolean, an integer or a double.

Returns:: A solver expression if at least one solver expression is given as argument, a boolean otherwise.

iif(condition, trueValue, falseValue)¶

Performs the if or creates a ternary conditional expression. The condition can be a solver expression or a boolean. The trueValue and falseValue can be solver expressions, booleans, integers or doubles. If the condition is a boolean, trueValue or falseValue is returned accordingly without any further treatment. Otherwise a new solver expression is returned.

Returns:: A solver expression if the condition is a solver expression, a number otherwise.

not(a)¶

Negates a boolean or creates a boolean not expression. The argument can be a solver expression or a boolean.

Returns:: A solver expression if the argument is a solver expression, a boolean otherwise.

and([arg0[, arg1[, ...]]])¶

Computes or creates a boolean and expression with the given arguments. Each argument can be a solver expression or a boolean. It is also possible to use this function with a variadic number of arguments or with the variadic call syntax. If no argument is given, this function returns the integer 1.

Returns:: A solver expression if at least one solver expression is given as argument, a boolean number otherwise.

or([arg0[, arg1[, ...]]])¶

Computes or creates a boolean or expression with the given arguments. Each argument can be a solver expression or a boolean. It is also possible to use this function with a variadic number of arguments or with the variadic call syntax. If no argument is given, this function returns the integer 0.

Returns:: A solver expression if at least one solver expression is given as argument, a boolean number otherwise.

xor([arg0[, arg1[, ...]]])¶

Computes or creates a boolean xor expression with the given arguments. Each argument can be a solver expression or a boolean. It is also possible to use this function with a variadic number of arguments or with the variadic call syntax. If no argument is given, this function returns the integer 0.

Returns:: A solver expression if at least one solver expression is given as argument, a boolean number otherwise.

abs(a)¶

Computes the absolute value of a number or creates a abs expression. The argument can be a solver expression, a boolean, an integer or a double.

Returns:: A solver expression if the argument is a solver expression, a number otherwise.

dist(a, b)¶

Computes the distance between two numbers or creates a distance expression. Each argument can be a solver expression, a boolean, an integer or a double.

Returns:: A solver expression if at least one solver expression is given as argument, a number otherwise.

pow(a, b)¶

Computes a power b or creates a pow expression. Each argument can be a solver expression, a boolean, an integer or a double.

Returns:: A solver expression if at least one solver expression is given as argument, a double otherwise.

sqrt(a)¶

Computes or creates a square root expression with the given argument. The argument can be a solver expression, a boolean, an integer or a double.

Returns:: A solver expression if the argument is a solver expression, a double otherwise.

log(a)¶

Computes or creates a natural logartihm expression with the given argument. The argument can be a solver expression, a boolean, an integer or a double.

Returns:: A solver expression if the argument is a solver expression, a double otherwise.

exp(a)¶

Computes or creates an exponential expression with the given argument. The argument can be a solver expression, a boolean, an integer or a double.

Returns:: A solver expression if the argument is a solver expression, a double otherwise.

cos(a)¶

Computes or creates a cosine expression with the given argument. The argument can be a solver expression, a boolean, an integer or a double.

Returns:: A solver expression if the argument is a solver expression, a double otherwise.

sin(a)¶

Computes or creates a sine expression with the given argument. The argument can be a solver expression, a boolean, an integer or a double.

Returns:: A solver expression if the argument is a solver expression, a double otherwise.

tan(a)¶

Computes or creates a tangent expression with the given argument. The argument can be a solver expression, a boolean, an integer or a double.

Returns:: A solver expression if the argument is a solver expression, a double otherwise.

ceil(a)¶

Computes the ceiling of the argument or creates a ceil expression. The argument can be a solver expression, a boolean, an integer or a double.

Returns:: A solver expression if the argument is a solver expression, an integer otherwise.

floor(a)¶

Computes the floor of the argument or creates a floor expression. The argument can be a solver expression, a boolean, an integer or a double.

Returns:: A solver expression if the argument is a solver expression, an integer otherwise.

round(a)¶

Returns the closest integer to the argument or creates a round expression. The argument can be a solver expression, a boolean, an integer or a double.

Returns:: A solver expression if the argument is a solver expression, an integer otherwise.

array([arg0[, arg1[, ...]]])¶

Returns an array made of the given elements (possibly arrays). Indexes begin at 0. An array doesn’t have a value by itself, but can contain operands of type boolean, integer, double, array (for multi-dimensional arrays) or collections (lists or sets). In the latter case, the collections must share the same domain and same type (either list or set). All the elements of an array must be of the same type.

Returns:: A solver expression.

at(arr, index0[, index1[, index2[, ...]]])¶

If arr is an array:

Returns the given indexed element of array arr.

The model will be considered as infeasible while no such element exists.

If arr is a list:

Only one index can be given.

Returns the given indexed element of list arr, or -1 if the index is negative of larger or equal to count(list).

Returns:: A solver expression.

scalar(arr1, arr2)¶

Returns the scalar product of the two arrays (of the same length).

Returns:: A solver expression.

piecewise(x, y, z)¶

Parameters:

x – A non-decreasing array of ‘’n’’ constant numbers, with ‘’n’’ >= 2.
y – An array of ‘’n’’ constant numbers
z – An integer or double expression.

Returns the image of z by the piecewise function defined by arrays x and y. See piecewise operator for details.

Returns:: A solver expression.

start(expression)¶

Returns the start of a non-void interval.

Returns:: A solver expression.

end(expression)¶

Returns the end of a non-void interval.

Returns:: A solver expression.

length(expression)¶

Returns the length of a non-void interval. The length of an interval is equivalent to end(interval) - start(interval). It differs from the count on void intervals since the length of a void interval is undefined whereas the count of a void interval is 0.

Returns:: A solver expression.

count(expression)¶

Returns the number of elements in an array, interval, list or set.

Returns:: A solver expression.

contains(expression, value)¶

Returns true if the given expression contains the given value, false otherwise. This operator takes exactly two arguments: the first one is an interval, a collection (list or set) or an array of collections, the second one is the value searched. If expression is an array, all its collections must be of the same type and on the same range.

Returns:: A solver expression.

indexOf(list, elem)¶

Returns the position of the given element in a list, or -1 if the element is not in the list. The returned value is an integer from -1 to count(list)-1

Returns:: A solver expression.

distinct(op1[, op2])¶

Returns the unordered set of distinct values of the given array, or among all the values returned by the function called on each element of the given collection (list or set), interval or range.

Returns:: A solver expression.

intersection(op1, op2)¶

Return the unordered set of the values present in both operands. Both operands can be a collection (list or set) or an array.

Returns:: A solver expression.

partition(coll0[, coll1[, coll2[, ...]]])¶

Returns an expression equal to true when all the operands form a partition of their common domain. All the operands must be collections of the same type (either lists or set) and on the same range. These collections can be stored in a LSArray that will be passed as argument of the partition: PARTITION(array(c1, c2, ..., cN)).

Returns:: A solver expression.

disjoint(coll0[, coll1[, coll2[, ...]]])¶

Returns an expression equal to true when all the operands are pairwise disjoint. All the operands must be collections of the same type (either lists or set) and on the same range. These collections can be stored in a LSArray that will be passed as argument of the disjoint: DISJOINT(array(c1, c2, ..., cN)).

Returns:: A solver expression.

cover(coll0[, coll1[, coll2[, ...]]])¶

Returns an expression equal to true when all the operands form a cover of their common domain. All the operands must be collections of the same type (either lists or set) and on the same range. These collections can be stored in a LSArray that will be passed as argument of the cover: COVER(array(c1, c2, ..., cN)).

Returns:: A solver expression.

find(array, elem)¶

Returns the position of the collection containing the given element in the array. If the element is not in any collections of the array, it returns -1. This operator takes exactly two arguments: the first one is an array of collections, the second one is the element searched. All the collections of the array must be of same type and on the same range.

Returns:: A solver expression.

sort(array[, lambda])¶

Returns the array sorted in ascending order. When used with a lambda as second argument, the operator will sort the array based on the values returned by the lambda. The sort operator guarantees that the order of elements having the same key is preserved.

Returns:: A solver expression.

intExternalFunction(func)¶

Adds your custom function to the model. This function must return an integer value. See external functions for details.

Returns:: A solver expression.

doubleExternalFunction(func)¶

Adds a custom function to the model. This function must return a double value. See external functions for details.

Returns:: A solver expression.

call(func[, arg0[, arg1[, ...]]])¶

Calls a function. It can be used to implement your own operator. See external functions for details.

Returns:: A solver expression.

Global variables¶

These variables can be accessed from any function of your code. They control various aspect of LocalSolver. As any other global variables, they can be directly set on the command line.

They are not available in the main mode. They are replaced by various methods and structures of the localsolver module.

lsTimeLimit¶

The time limit(s) allocated to the search, in seconds. It can be an integer or a collection of integers (always non-negative). Note that the “real” time (that is, total time) spent to resolve the model is considered here and not only the CPU time. The default time limit is set to the largest positive integer on 32 bits, that is 2^31-1 = 2,147,483,647 > 10^9. If lsTimeLimit is set to an integer value, the search will stop after this granted amount of seconds (or earlier if an optimal solution is found). If lsTimeLimit is set to a collection of integers, then the search will proceed by phases:

the first number will be the number of seconds allocated to the optimization of the first objective (1st phase),
the second number will be the number of seconds allocated to the second objective (2nd phase),
and so on…

The number of time limits must be smaller or equal to the number of objectives. Note that if the optimal value of an objective is found before the end of the corresponding phase, the remaining time will be transferred to the next phase.

lsIterationLimit¶

The number(s) of iterations of LocalSolver algorithms allowed in the search. It can be an integer or a collection of integers (always non-negative). The default number of iterations is set to the largest positive integer, that is 2^63-1 = 9,223,372,036,854,775,807 > 10^18. If lsIterationLimit is set to an integer value, the search will stop after this granted amount of iterations (or earlier if an optimal solution is found). If lsIterationLimit is set to a collection of integers, then the search will proceed by phases:

the first number will be the number of iterations allocated to the optimization of the first objective (1st phase),
the second number will be the number of iterations allocated to the second objective (2nd phase),
and so on…

The number of iteration limits must be smaller or equal to the number of objectives. Note that if the optimal value of an objective is found before the end of the corresponding phase, the remaining number of iterations will be transferred to the next phase.

lsNbThreads¶

Number of threads used to parallelize the search. The default value is 0, which means that the number of threads is automatically adapted to your computer and to your optimization model. This parameter is indicative, if needed LocalSolver may use more threads. The actual number of threads can also vary during the search.

Furthermore, if you use external functions with LSP, LocalSolver will use only one thread to avoid concurrent accesses to your external function. Please read Performance issues for more details.

lsSeed¶: The seed of the pseudorandom number generator used by LocalSolver internally to perform its search. This number must be positive or zero. Default value is 0.

lsTimeBetweenDisplays¶: Interval in seconds between two displays during the search. This number must be strictly positive. Default value is 1.

lsTimeBetweenTicks¶: Interval in seconds between two time ticks during the search. This number must be strictly positive. Default value is 1.

lsIterationBetweenTicks¶: Interval in iterations between two iteration ticks during the search. This number must be strictly positive. Default value is 10,000.

lsVerbosity¶

Verbosity level of the solver. The amount of information displayed during the search depends on this parameter. There are 3 different levels:

0: All traces are disabled
1: Normal verbosity. Displays only the most crucial indicators: objectives, elapsed time and number of iterations.
2: Wordy level. Displays additional statistics like the number of decisions of each type.

lsObjectiveThreshold¶

Sets the threshold of the objective. If lsObjectiveThreshold is set to an integer or a double (according to the objective type), the optimization is stopped as soon as the lower (minimization case) or upper (maximization case) threshold is reached.

It can also be a collection of integer or doubles for multi-objectives problems.

lsAnnealingLevel¶: Deprecated since version 8.0: The annealing level doesn’t have a significant influence on the search anymore. The tuning of this parameter won’t be allowed in a future version.

Annealing level of the search. This level must be an integer between 0 and 9.

lsSolution¶

Gives access to the solution object of the solver. With this variable you can query the status of the solution (with lsSolution.status), the bounds and the gaps of the objectives (with lsSolution.objectiveBounds and lsSolution.objectiveGaps).

For more information on all the available fields and features of this variable, please refer to the documentation of LSSolution Class.

This variable is not available during the modeling phase. Therefore, the value of this variable during the execution of the input() and model() methods is nil.

Return type:: LSSolution
Since:: 11.5

lsStatistics¶

Gives access to the statistics of the solver. With this variable you can query the various statistics exposed by the solver at the end of the optimization or during the optimization when the method display is periodically invoked.

The resolution time is available in lsStatistics.runningTime and the number of iterations in lsStatistics.nbIterations. For more information on all the available fields and features of this variable, please refer to the documentation of LSStatistics Class.

This variable is not available during the modeling phase. Therefore, the value of this variable during the execution of the input() and model() methods is nil.

Return type:: LSStatistics
Since:: 11.5