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 1..N] <- bool();
s <- sum[i in 1..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 1..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.

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.

count(collection)¶

Returns the number of elements in a list or set (from 0 to the domain size of the collection).

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

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)¶

Returns the array sorted in ascending order.

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.

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. Default value is 0.

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

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

lsIterationBetweenTicks¶: Interval in iterations between two iteration ticks during the search. This number must be 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 (minimimastion case) or upper (maximisation 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.

Deprecated functions¶

These functions are deprecated. They are replaced by modules of the standard library. They are only provided for compatibility reasons. New features will only be added through modules. We strongly discourage you to use them in your new projects.

Warning

These functions are deprecated and will be removed in a next version of LocalSolver. Use the provided modules instead.

split(string, delimiter)¶: Split a string according the provided delimiter. Use the more general string.split() function of the string module.

toString(value)¶: Returns the string representation of a value.

toInt(string)¶: Returns the int representation of the provided string. Use string.toInt() function of the string module instead.

toDouble(string)¶: Returns the floating-point representation of the provided string. Use string.toDouble() function of the string module instead.

trim(string)¶: Returns a copy of the string with leading and trailing whitespaces removed. Use string.trim() function of the string module instead.

length(string)¶: Returns the length of the string. Use string.length() function of the string module instead.

substring(string, start)¶
substring(string, start, length): Returns a new string that is a substring of the provided string. Use string.substring() function of the string module instead.

startsWith(string, prefix)¶: Returns true if the string starts with the given prefix. Use string.startsWith() function of the string module instead.

endsWith(string, prefix)¶: Returns true if the string ends with the given suffix. Use string.endsWith() function of the string module instead.

lowerCase(string)¶: Returns a new string with all the characters converted to lower case. Use string.toLowerCase() function of the string module instead.

upperCase(string)¶: Returns a new string with all the characters converted to upper case. Use string.toUpperCase() function of the string module instead.

replace(string, search, replace)¶: Return a copy of the string with all occurrences of substring search replaced by replace. Use string.replace() function of the string module instead.

openRead(filename)¶: Opens file filename in reading mode. For a better support of Unicode characters, use the function io.openRead() instead.

openWrite(filename)¶: Opens file filename in writing mode. For a better support of Unicode characters, use the function io.openWrite() instead.

openAppend(filename)¶: Opens file filename in appending mode. For a better support of Unicode characters, use the function io.openAppend() instead.

close(file)¶: Closes the current file. Use the function inputstream.close() or outputstream.close() of the io module instead.

eof(file)¶: Returns true if the end of file is reached. Use the function inputstream.eof() of the io module instead.

readInt(file)¶: Reads and returns the next integer available in the file. Use the function inputstream.readInt() of the io module instead.

readDouble(file)¶: Reads and returns the next floating-point number available in the file. Use the function inputstream.readDouble() of the io module instead.

readString(file)¶: Reads and returns the next sequence of non whitespace characters. Use the function inputstream.readString() of the io module instead.

readln(file)¶: Reads ands returns the next line in the stream. Use the function inputstream.readln() of the io module instead.

add(map, value)¶: Adds the given value in the map. Use the function map.add() of the map module instead.

keys(map)¶: Returns the keys of the map in a new map. Use the function map.keys() of the map module instead.

values(map)¶: Returns the values of the map in a new map. Use the function map.values() of the map module instead.

error(message)¶: Quit LocalSolver and print the given message as an error. If you want to throw errors, use exceptions instead.