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.

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:

  1. 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.
  2. 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).

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 – A 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(collection, elem)

Returns true if the given list or set contains the given value, false otherwise.

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 operands must be of the same type (either lists or set).

Returns:A solver expression.
disjoint(coll0[, coll1[, coll2[, ...]]])

Returns an expression equal to true when all the operands are pairwise disjoint. All operands must be of the same type (either lists or set).

Returns:A solver expression.
call(func[, arg0[, arg1[, ...]]])

Calls a function. It can be used to implement your own operator. See native 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 collecion 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 collecion 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 2. By increasing the number of threads, you increase the robustness of the solver (that is, the chance to find better solutions) and the speed of the search. However, we recommend you to avoid running a number of threads which exceeds the number of cores available on your machine.

Furthermore, if you use native functions with LSP, we strongly recommend you to disable the multi-threading of the search and sets this parameter to 1 due to thread contention issue. Please read Performance issues for more details.

lsSeed

The seed of the pseudorandom number generator used by LocalSolver internally to perform its local 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.

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 advanced statistics like the percentage of accepted, infeasible and rejected moves.
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 haven’t a significant influence on the search anymore. The tuning of this parameter won’t be allowed in a future version.

Annealing level of the local search. This level must be an integer between 0 and 9. If set to 0, the search heuristic is equivalent to a standard descent: moves deteriorating the current solution are rejected. By increasing this parameter, you increase the number of uphill moves (that is, moves deteriorating the objective value of the current solution): this increases chances to reach better solutions (diversification), but slows the convergence of the search.

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.