Localsolver  6.0
Package localsolver

The classical version of LocalSolver is designed to solve large scale optimization problem in boolean, integer and continuous decisions. The model is described as a set of mathematical expressions that can be constrained or optimized. More...

Classes

class  LocalSolver
 LocalSolver environment. More...
class  LSCollection
 Value type for collection expressions (lists). More...
class  LSException
 LocalSolver exception. More...
class  LSExpression
 Mathematical modeling expression. More...
class  LSInconsistency
 Inconsistency core of the optimization model. More...
class  LSModel
 Mathematical optimization model. More...
class  LSNativeContext
 Context for native functions. More...
class  LSParam
 Solving parameters. More...
class  LSPhase
 Optimization phase. More...
class  LSSolution
 Solution to the optimization model. More...
class  LSStatistics
 Statistics of the search. More...
class  LSVersion
 Version and copyright info. More...

Enumerations

enum  LSCallbackType {
  PhaseStarted,
  PhaseEnded,
  Display,
  TimeTicked,
  IterationTicked
}
 List of types that can be used with callbacks. More...
enum  LSErrorCode {
  Api,
  File,
  Model,
  Callback,
  License,
  Solver,
  Internal,
  Modeler
}
 List of error codes used by LSException. More...
enum  LSObjectiveDirection {
  Minimize,
  Maximize
}
 Objective directions. More...
enum  LSOperator {
  Bool,
  Float,
  Const,
  Sum,
  Sub,
  Prod,
  Max,
  Min,
  Eq,
  Neq,
  Geq,
  Leq,
  Gt,
  Lt,
  If,
  Not,
  And,
  Or,
  Xor,
  Abs,
  Dist,
  Div,
  Mod,
  Array,
  At,
  Scalar,
  Ceil,
  Floor,
  Round,
  Sqrt,
  Log,
  Exp,
  Pow,
  Cos,
  Sin,
  Tan,
  Int,
  Piecewise,
  List,
  Count,
  IndexOf,
  Partition,
  Disjoint,
  NativeFunction,
  Call
}
 Mathematical operators available for modeling. More...
enum  LSSolutionStatus {
  Inconsistent,
  Infeasible,
  Feasible,
  Optimal
}
 Solution status: Optimal, Feasible, Infeasible or Inconsistent. More...
enum  LSState {
  Modeling,
  Running,
  Paused,
  Stopped
}
 State of LocalSolver environment. More...

Functions

delegate void LSCallback (LocalSolver solver, LSCallbackType type)
 LSCallback delegate.
delegate double LSNativeFunction (LSNativeContext context)
 Native function delegate.

Detailed Description

The classical version of LocalSolver is designed to solve large scale optimization problem in boolean, integer and continuous decisions. The model is described as a set of mathematical expressions that can be constrained or optimized.

Enumeration Type Documentation

List of types that can be used with callbacks.

Each type corresponds to a specific event that can occur during the resolution.

Since version 4.0

Enumerator:
PhaseStarted 

Event that occurs when a phase is started.

PhaseEnded 

Event that occurs when a phase ends.

Display 

Event that occurs regularly before, after and during the search to display useful information about the model and the resolution.

The time between two such events can be tuned with the TimeBetweenDisplays parameter.

See Also
LSParam.SetTimeBetweenDisplays
TimeTicked 

Event that occurs regularly during the resolution.

The time between two such events can be tuned with the TimeBetweenTicks parameter.

See Also
LSParam.setTimeBetweenTicks

Since version 6.0

IterationTicked 

Event that occurs regularly during the resolution.

The number of iterations between two such events can be tuned with the IterationsBetweenTicked parameter.

See Also
LSParam.setIterationBetweenTicks

Since version 6.0

List of error codes used by LSException.

Enumerator:
Api 

Code used for errors related to API functions.

Used when you call a function in a wrong way or with inappropriate parameters. Examples of error messages:

  • Argument 'argName' cannot be null.
  • Argument 'argName' does not belong to this instance of LocalSolver.
  • Argument 'argName' must be positive.
  • Argument 'argName' cannot be an empty string.
  • This method is only allowed in state Modeling (the model must not be closed).
File 

Code used when an error related to input/output operations occurs.

Examples of error messages:

  • File doesn't exist.
  • File is corrupted.
  • Cannot open file.
  • File format is not recognized.
Model 

Code used when a problem related to the structure of the model occurs.

Examples of error messages:

  • At least one objective is required in the model.
  • A cycle of length 'n' was detected in the model.
  • Number of operands ('n') is too small: at least 'm' operands are expected for 'operator'.
  • Operand 'n' of 'operator' must be 'type'. Type provided: 'otherType'.
Callback 

Code used when an error is encountered in a user callback.

License 

Code used when a problem related to licensing occurs.

That could be a problem with the license itself (expiration, hardware signature, ...), or a problem related to input/output or networking operations. Examples of error messages:

  • Incorrect license number.
  • This license key is not compatible with the current hardware. Please contact your reseller.
  • Property prop is missing in file [file]
  • Fail to contact the token server. Check your connection.
  • This license is not compatible with the current hardware.
  • No token available. All tokens are currently in use.
Solver 

Code used when a problem occurs during the resolution such a division by zero or an index out of bounds.

Keep in mind that, during the search variables are likely to take values that do not satisfy the constraints (for instance in the feasibility stage). Consequently when an division by zero or array overflow occurs in your model, it probably means that the denominator of a modulo or the index of a array can take invalid values. You can fix this using min and max expressions for instance:

z <- x % y

can be replaced by

z<-x % max(1,y)

. Examples of error messages:

  • Division by zero.
  • Index out of bounds for 'at' operator (index: 'indexId', array size: 'n')
Internal 

Internal LocalSolver error.

Modeler 

Code used when an error is encountered in the modeler.

Objective directions.

See Also
LSModel.AddObjective
Enumerator:
Minimize 

Minimization.

Maximize 

Maximization.

Mathematical operators available for modeling.

These operators are used to type the expressions created in LocalSolver mathematical optimization model.

See Also
LSModel, LSExpression
Enumerator:
Bool 

Boolean decision.

Decisional operator with no operand. Decision variable with domain {0,1}.

Float 

Float decision.

Decisional operator with two operands min and max. Decision variable with domain [min,max].

Since version 4.0

Const 

Constant.

Unary operator. Can be equal to any integer. Note that constants 0 or 1 are considered as boolean. Constants are implicitly created when passing integer arguments to LSModel::CreateExpression or LSExpression::AddOperand.

Sum 

Sum.

N-ary arithmetic operator. SUM(e1,e2,...,eN) is equal to the sum of all operands e1,e2,...,eN. This operator returns an integer or a double according to the type of its operands.

Sub 

Substraction.

Binary arithmetic operator. SUB(x, y) is equal to the value of x - y. This operator returns an integer or a double according to the type of its operands.

Since version 4.0

Prod 

Product.

N-ary arithmetic operator. PROD(e1,e2,...,eN) is equal to the product of all operands e1,e2,...,eN. This operator returns an integer or a double according to the type of its operands.

Max 

Maximum.

N-ary arithmetic operator. MAX(e1,e2,...,eN) is equal to the maximum value among all operands e1,e2,...,eN. This operator returns an integer or a double according to the type of its operands.

Min 

Minimum.

N-ary arithmetic operator. MIN(e1,e2,...,eN) is equal to the minimum value among all operands e1,e2,...,eN. This operator returns an integer or a double according to the type of its operands.

Eq 

Equal.

Binary relational operator. EQ(a,b) = 1 if a == b, and 0 otherwise. This operator returns a boolean.

Neq 

Not equal to.

Binary relational operator. NEQ(a,b) = 1 if a != b, and 0 otherwise. This operator returns a boolean.

Geq 

Greater than or equal to.

Binary relational operator. GEQ(a,b) = 1 if a >= b, and 0 otherwise. This operator returns a boolean.

Leq 

Lower than or equal to.

Binary relational operator. LEQ(a,b) = 1 if a <= b, and 0 otherwise. This operator returns a boolean.

Gt 

Strictly greater than.

Binary relational operator. GT(a,b) = 1 if a > b, and 0 otherwise. This operator returns a boolean.

Lt 

Strictly lower than.

Binary relational operator. LQ(a, b) = 1 if a < b, and 0 otherwise. This operator returns a boolean.

If 

If-Then-Else.

Ternary conditional operator. IF(a,b,c) is equal to b if a is true, and c otherwise. Note that the first operand must be a boolean (that is, equal to 0 or 1). This operator returns a boolean, an integer or a double according to the type of the second and third operands.

Not 

Not.

Unary logical operator. NOT(a) = 1 - a. Note that the operand must be boolean (that is, equal to 0 or 1). This operator returns a boolean.

And 

And.

N-ary logical operator. AND(e1,e2,...,eN) is equal to 1 (true) if all operands e1,e2,...,eN are 1, and 0 otherwise. Note that all operands must be boolean (that is, equal to 0 or 1). This operator returns a boolean.

Or 

Or.

N-ary logical operator. OR(e1,e2,...,eN) is equal to 0 if all operands e1,e2,...,eN are 0, and 1 otherwise. Note that all operands must be boolean (that is, equal to 0 or 1). This operator returns a boolean.

Xor 

Exclusive or (also called "xor").

N-ary logical operator. XOR(e1,e2,...,eN) is equal to 0 if the number of operands with value 1 among e1,e2,...,eN is even, and 1 otherwise. Remarkable case: XOR(a,b) = 1 if a == b, and 0 otherwise. Note that all operands must be boolean (that is, equal to 0 or 1). This operator returns a boolean.

Abs 

Absolute value.

Unary arithmetic operator. ABS(e) = e >= 0 ? e : -e. This operator returns an integer or a double according to the type of its operand.

Dist 

Distance between two numbers.

Binary arithmetic operator. DIST(a,b) = ABS(a-b). This operator returns an integer or a double according to the type of its operands.

Div 

Division.

Binary arithmetic operator. This operator always returns a double. Note that until version 4.0, the division was an integer division if both operands were integers.

Mod 

Modulo (remainder of the integer division).

Binary arithmetic operator. MOD(a,b) = r such that a = q * b + r with q, r integers and |r| < b. An error will be thrown if b equals 0 at an iteration of the search. Note that the operands must be integers. This operator returns an integer.

Array 

Array.

An array is a collection of elements. Indexes begin at 0. It could be used with operators like at or scalar. An array can contain operands of type double, integer or boolean. Note that an array cannot contain another array.

Since version 2.1

At 

Returns the element of an array.

MyArray[i] returns the i element of the array MyArray. An error will be thrown if i is out of range. This operator returns a boolean, an integer or a double according to the type of the operands in the array.

Since version 2.1

Scalar 

Scalar product.

SCALAR(a, x) = sum(a[i]*x[i]) with a and x two arrays. This operator returns an integer or a double according to the type of the operands in the arrays.

Since version 2.1

Ceil 

Ceil.

Unary arithmetic operator. Returns a value rounded to the next highest integer. This operator returns an integer.

Since version 3.0

Floor 

Floor.

Unary arithmetic operator. Returns a value rounded to the next lowest integer. This operator returns an integer.

Since version 3.0

Round 

Round.

Unary arithmetic operator. Returns a value rounded to the nearest integer. This operator returns an integer.

Since version 3.0

Sqrt 

Square root.

Unary arithmetic operator. This operator returns a double.

Since version 3.0

Log 

Natural logarithm (base-e).

Unary arithmetic operator. This operator returns a double.

Since version 3.0

Exp 

Base-e exponential.

Unary arithmetic operator. This operator returns a double.

Since version 3.0

Pow 

Power operator.

POW(x, y) is equals to the value of x to the power of y. This operator returns a double.

Since version 3.0

Cos 

Cosine.

Unary arithmetic operator. This operator returns a double.

Since version 3.0

Sin 

Sine.

Unary arithmetic operator. This operator returns a double.

Since version 3.0

Tan 

Tangent.

Unary arithmetic operator. This operator returns a double.

Since version 3.0

Int 

Integer decision variable.

Decisional operator with two operands min and max. Decision variable with domain [min,max].

Since version 5.0

Piecewise 

Piecewise-linear function operator.

The piecewise linear function is defined by two arrays of numbers giving the breakpoints of the function. This operator has exactly 3 operands: The first two operands must be two arrays of equal lengths (necessarily larger or equal to 2). These arrays must contain constant numbers (int or double). The first array must contain numbers in ascending order. The third operand must be an integer or double expression. An exception will be thrown if its value is strictly smaller that the first element of the first array, or strictly larger than the last element of the first array. This operator returns a double. piecewise(x,y,z) returns the image of z by the function defined by geometric points (x[0],y[0]), (x[1],y[1]), ..... (x[n-1],y[n-1]), For instance piecewise({0,50,100},{0,10,100},75) returns 55. Discontinuities are allowed in the definition of the function, that is to say that two geometric points can share the same x-coordinate. By convention the value taken by the function at such a discontinuous point is the one associated to the last occurrence of this x-coordinate in array x. For instance piecewise({0,50,50,100},{0,0.1,0.9,1},50) returns 0.9;

Since version 5.0

List 

A list is an collection of integers within a range [0,n-1] where n is the unique argument of this operator.

Mathematically a list is a permutation of a subset of [0,n-1]. This operator takes exactly one parameter: a constant strictly positive integer. All values in the list will be pairwise different, non negative and strictly smaller that this number. The elements of the list can be accessed with the at operator (-1 will be returned for indices beyond the number of elements in the list and for negative indices).

Since version 5.5

Count 

The number of elements in a collection.

This operator takes exactly one argument of type list.

Since version 5.5

IndexOf 

The index of a value in a list (-1 if the value is not in the list).

This operator takes exactly two arguments: the first one is a list, the second one is an integer expression.

Since version 5.5

Partition 

Partition.

N-ary logical operator. Partition(l1,l2,...,lN) is true if all lists l1,l2..lN form a partition of their common range. All parameters of this operator must be lists on the same range.

Since version 5.5

Disjoint 

Disjoint.

N-ary logical operator. Disjoint(l1,l2,...,lN) is true if all lists l1,l2..lN are pairwise disjoint. All parameters of this operator must be lists on the same range.

Since version 5.5

NativeFunction 

Native function.

Native functions are used to retrieve the value of expressions from external functions written with your favorite language. Native functions are created with the dedicated method LSModel::CreateNativeFunction.

See Also
LSNativeFunction

Since version 6.0

Call 

Call a particular function.

The first operand must be a function (like O_NativeFunction). The other operands are passed to the function as arguments.

Since version 6.0

Solution status: Optimal, Feasible, Infeasible or Inconsistent.

See Also
LSSolution
Enumerator:
Inconsistent 

Solution and model are inconsistent.

The solver was able to prove that the model admits no feasible solution. Note that even a model without any constraint can be infeasible because some expressions induce implicit constraints: for instance defining sqrt(x) implicitly constrains x to be non-negative.

Infeasible 

Solution is infeasible (some constraints are violated).

Feasible 

Solution is feasible but optimality was not proven.

Optimal 

Solution is optimal (all objective bounds are reached).

State of LocalSolver environment.

See Also
LocalSolver.GetState
Enumerator:
Modeling 

Model is being built.

Running 

Solver is running.

Paused 

Solver is paused.

Stopped 

Solver is stopped.

Function Documentation

delegate void localsolver.LSCallback ( LocalSolver  solver,
LSCallbackType  type 
)

LSCallback delegate.

Implementing the LSCallback delegate enables users to call functions to react to specific events or to call a function regularly during the search. It can be used for example to control when to stop the search or to display some specific information during the search.

Note: When a callback is called, the solver is paused. In that state, you can call all the methods marked as "allowed in state <see cref="LSState::Paused" />". Calling any other method will throw an error.

Parameters
solverThe solver calling the function.
typeThe type of event that triggered the call.
delegate double localsolver.LSNativeFunction ( LSNativeContext  context)

Native function delegate.

To use your own functions with LocalSolver, you have to proceed in 3 steps:

  1. Implement the delegate in a method. The method must take the native context and must return a double value. This native context contains the values of the expressions passed to the function. A distinction is made between integer arguments (bool, int) and floating point arguments (double).
  2. Instanciate the function as an LSExpression with LSModel::CreateNativeFunction or the dedicated shortcut LSModel::Function.
  3. Pass arguments to your function and call it. For that, you have to create expressions of type LSOperator::Call. The first operand must be your native function. The other operands must be LSExpressions. Their value will be made accessible to your native function through the native context.

Note 1: Most of the time your native function will be called when the solver is in state LSState::Running. Do not attempt to call any method of the solver (to retrieve statistics, values of LSExpressions or whatever) in that state or an exception will be thrown. The only accessible function is LocalSolver::Stop().

Note 2: Your functions must be thread-safe. According to the "nbThreads" parameter, LocalSolver can be multi-threaded. In that case, your native functions must be thread safe. If you cannot guarantee the thread-safety of your code, we strongly recommend you to limit the search of LocalSolver to one thread with LSParam::SetNbThreads.