LSModel Class¶

class
localsolver::
LSModel
¶ Mathematical optimization model.
A model is composed of expressions (some of which are decisions), organized as a tree. Then, some expressions of the model can be constrained or optimized. Once your optimization model is created and closed, the solver can be launched to resolve it. Note that you cannot modify a model which has been closed: you must reopenit (with open()) or instantiate another LocalSolver environment to optimize another model.
See: LSExpression See: LSOperator
Summary¶
createConstant 
Creates a constant expression representing the given value. 
createExpression 
Creates an expression of the given type, with the given ordered operands. 
createNativeFunction 
Creates a native function. 
createFunction 
Creates a function. 
boolVar 
Creates a boolean decision. 
floatVar 
Creates a float decision. 
intVar 
Creates an integer decision. 
sum 
Creates a sum expression. 
sub 
Creates a substraction expression. 
call 
Creates a call expression. 
prod 
Creates a product expression. 
max 
Creates a maximum expression. 
min 
Creates a minimum expression. 
or_ 
Creates a OR expression. 
and_ 
Creates an AND expression. 
xor_ 
Creates a XOR expression. 
not_ 
Creates a NOT expression. 
eq 
Creates an equality expression. 
neq 
Creates a disequality expression. 
geq 
Creates an inequality expression greater than or equal to. 
leq 
Creates an inequality expression less than or equal to. 
gt 
Creates an inequality expression greater than. 
lt 
Creates an inequality expression less than. 
iif 
Creates a ternary conditional expression. 
abs 
Creates an absolute value expression. 
dist 
Creates a distance expression. 
div 
Creates a division expression. 
mod 
Creates a modulo expression. 
array 
Creates an array expression. 
at 
Creates a “at” expression for Ndimensional array. 
scalar 
Creates an expression for the scalar product between two arrays. 
ceil 
Creates a ceil expression. 
floor 
Creates a floor expression. 
round 
Creates a rounding expression. 
sqrt 
Creates a square root expression. 
log 
Creates a log expression. 
exp 
Creates an exponential expression. 
pow 
Creates a power expression. 
cos 
Creates a cosine expression. 
sin 
Creates a sine expression. 
tan 
Creates a tangent expression. 
piecewise 
Creates a piecewise linear expression. 
listVar 
Creates a list decision with the given length. 
count 
Creates a count expression. 
indexOf 
Creates an indexOf expression. 
contains 
Creates a contains expression. 
partition 
Creates a partition expression. 
disjoint 
Creates a disjoint expression. 
nativeFunction 
Creates a native function expression. 
function 
Creates a function expression. 
range 
Creates a range expression. 
getNbExpressions 
Gets the number of expressions added to this model. 
getExpression 
Gets the expression with the given index in this model. 
getNbDecisions 
Gets the number of decisions in the model. 
getDecision 
Gets the decision with the given index. 
addConstraint 
Adds the given expression to the list of constraints. 
constraint 
Shortcut for addConstraint(expr). 
removeConstraint 
Removes the given expression from the list of constraints. 
getNbConstraints 
Gets the number of constraints added to this model. 
getConstraint 
Gets the constraint with the given index. 
addObjective 
Adds the given expression to the list of objectives to optimize. 
minimize 
Shortcut for addObjective(expr, OD_Minimize). 
maximize 
Shortcut for addObjective(expr, OD_Maximize). 
removeObjective 
Removes the objective at the given position in the list of objectives. 
getNbObjectives 
Gets the number of objectives added to this model. 
getObjective 
Gets the objective with the given index. 
getObjectiveDirection 
Gets the direction of the objective with the given index. 
getNbOperands 
Gets the number of operands in the model. 
close 
Closes the model. 
open 
Opens or reopens the model. 
isClosed 
Returns true if the model is closed, false otherwise. 
toString 
Returns a string representation of this model. 
Functions¶

LSExpression
createConstant
(lsint value)¶ Creates a constant expression representing the given value.
Only allowed in state S_Modeling. Note that if a constant has been already created with the same value, this method can return the same expression, but it is not guaranteed. The exact behavior is implementation defined.
Return: Created constant expression. Parameters: value  Value of the constant.

LSExpression
createConstant
(lsdouble value)¶ Creates a constant expression representing the given value.
Only allowed in state S_Modeling. Note that if a constant has been already created with the same value, this method can return the same expression, but it is not guaranteed. The exact behavior is implementation defined.
Return: Created constant expression. Parameters: value  Value of the constant
 template <typename... TN>

LSExpression
createExpression
(LSOperator op, TN... operands)¶ Creates an expression of the given type, with the given ordered operands.
Only allowed in state S_Modeling. The operands can be doubles, integers or previously declared LSExpressions. It is also possible to use this method with iterators. In that case, you have to call this method with 2 operands exactly that must be iterators of the same type, pointing respectively to the initial and final positions of the operands.
Return: Created expression.
Templates: TN  types of the operands to add. Types allowed: constant types, LSExpression or iterators.
Parameters:  op  Type of expression to create.
 operands  Operands.

LSExpression
createNativeFunction
(LSNativeFunction *func)¶ Creates a native function.
Once you instanciated it, you have to pass arguments to your function and call it. For that, you have to create expressions of type O_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 S_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 threadsafe. According to the “nbThreads” parameter, LocalSolver can be multithreaded. In that case, your native functions must be thread safe. If you cannot guarantee the threadsafety of your code, we strongly recommend you to limit the search of LocalSolver to one thread with LSParam#setNbThreads.
Note 3: LocalSolver do not manage memory of objects created outside of its environment. Thus, you have to explicitely delete your LSNativeFunction at the end of the search.
Return: The expression associated to the function. See: O_NativeFunction Since: 6.0 Parameters: func  Native function to call.
 template <typename A>

LSExpression
createFunction
(const A &functor)¶ Creates a function.
A function is a particular expression composed of two parts:
 The arguments of the function (which are also LSExpressions of type O_Argument)
 The body of the function. The body is an LSExpression that will be used to evaluate the result of the function. The body can be any LSExpression composed of any operands and operators supported by LocalSolver. Thus, the body expression can use the arguments of the function but can also capture and refer to expressions declared outside of the function.
You have to provide the body of the function as a std::function (C++ function or lambda). Please note that the provided std::function will not be used directly during the solving process, but will be evaluated once by the API with a number of LSExpression of type O_Argument that corresponds to the number of arguments your std::function expects. The returned LSExpression resulting of this evaluation will be used as the body of the LocalSolver function O_Function.

LSExpression
boolVar
()¶ Creates a boolean decision.
Binary decision variable with domain { 0, 1 }. This method is a shortcut for
createExpression(O_Bool)
.See: O_Bool See: createExpression Since: 5.5

LSExpression
floatVar
(lsdouble lb, lsdouble ub)¶ Creates a float decision.
Decision variable with domain [lb, ub]. This method is a shortcut for
createExpression(O_Float, lb, ub)
.See: See: Since: 5.5
Parameters:  lb  Lower bound of the decision variable.
 ub  Upper bound of the decision variable.

LSExpression
intVar
(lsint lb, lsint ub)¶ Creates an integer decision.
Decision variable with domain [lb, ub]. This method is a shortcut for
createExpression(O_Int, lb, ub)
.See: See: Since: 5.5
Parameters:  lb  Lower bound of the decision variable.
 ub  Upper bound of the decision variable.
 template <typename... TN>

LSExpression
sum
(TN... operands)¶ Creates a sum expression.
This method is a shortcut for
createExpression(O_Sum, operands)
.See: O_Sum See: createExpression Since: 5.5
 template <typename T0, typename T1>

LSExpression
sub
(T0 expr0, T1 expr1)¶ Creates a substraction expression.
This method is a shortcut for
createExpression(O_Sub, expr0, expr1)
.See: O_Sub See: createExpression Since: 5.5
 template <typename... TN>

LSExpression
call
(TN... operands)¶ Creates a call expression.
This method is a shortcut for
createExpression(O_Call, operands)
.See: O_Call See: createExpression Since: 6.0
 template <typename... TN>

LSExpression
prod
(TN... operands)¶ Creates a product expression.
This method is a shortcut for
createExpression(O_Prod, operands)
.See: O_Prod See: createExpression Since: 5.5
 template <typename... TN>

LSExpression
max
(TN... operands)¶ Creates a maximum expression.
This method is a shortcut for
createExpression(O_Max, operands)
.See: O_Max See: createExpression Since: 5.5
 template <typename... TN>

LSExpression
min
(TN... operands)¶ Creates a minimum expression.
This method is a shortcut for
createExpression(O_Min, operands)
.See: O_Min See: createExpression Since: 5.5
 template <typename... TN>

LSExpression
or_
(TN... operands)¶ Creates a OR expression.
This method is a shortcut for
createExpression(O_Or, operands)
.See: O_Or See: createExpression Since: 5.5
 template <typename... TN>

LSExpression
and_
(TN... operands)¶ Creates an AND expression.
This method is a shortcut for
createExpression(O_And, operands)
.See: O_And See: createExpression Since: 5.5
 template <typename... TN>

LSExpression
xor_
(TN... operands)¶ Creates a XOR expression.
This method is a shortcut for
createExpression(O_Xor, operands)
.See: O_Xor See: createExpression Since: 5.5
 template <typename T0>

LSExpression
not_
(T0 expr0)¶ Creates a NOT expression.
This method is a shortcut for
createExpression(O_Not, expr0)
.See: O_Not See: createExpression Since: 5.5
 template <typename T0, typename T1>

LSExpression
eq
(T0 expr0, T1 expr1)¶ Creates an equality expression.
This method is a shortcut for
createExpression(O_Eq, expr0, expr1)
.See: O_Eq See: createExpression Since: 5.5
 template <typename T0, typename T1>

LSExpression
neq
(T0 expr0, T1 expr1)¶ Creates a disequality expression.
This method is a shortcut for
createExpression(O_Neq, expr0, expr1)
.See: O_Neq See: createExpression Since: 5.5
 template <typename T0, typename T1>

LSExpression
geq
(T0 expr0, T1 expr1)¶ Creates an inequality expression greater than or equal to.
This method is a shortcut for
createExpression(O_Geq, expr0, expr1)
.See: O_Geq See: createExpression Since: 5.5
 template <typename T0, typename T1>

LSExpression
leq
(T0 expr0, T1 expr1)¶ Creates an inequality expression less than or equal to.
This method is a shortcut for
createExpression(O_Leq, expr0, expr1)
.See: O_Leq See: createExpression Since: 5.5
 template <typename T0, typename T1>

LSExpression
gt
(T0 expr0, T1 expr1)¶ Creates an inequality expression greater than.
This method is a shortcut for
createExpression(O_Gt, expr0, expr1)
.See: O_Gt See: createExpression Since: 5.5
 template <typename T0, typename T1>

LSExpression
lt
(T0 expr0, T1 expr1)¶ Creates an inequality expression less than.
This method is a shortcut for
createExpression(O_Lt, expr0, expr1)
.See: O_Lt See: createExpression Since: 5.5
 template <typename T0, typename T1, typename T2>

LSExpression
iif
(T0 condExpr, T1 trueExpr, T2 falseExpr)¶ Creates a ternary conditional expression.
This method is a shortcut for
createExpression(O_If, condExpr, trueExpr, falseExpr)
.See: O_If See: createExpression Since: 5.5
 template <typename T0>

LSExpression
abs
(T0 expr0)¶ Creates an absolute value expression.
This method is a shortcut for
createExpression(O_Abs, expr0)
.See: O_Abs See: createExpression Since: 5.5
 template <typename T0, typename T1>

LSExpression
dist
(T0 expr0, T1 expr1)¶ Creates a distance expression.
This method is a shortcut for
createExpression(O_Dist, expr0, expr1)
.See: O_Dist See: createExpression Since: 5.5
 template <typename T0, typename T1>

LSExpression
div
(T0 expr0, T1 expr1)¶ Creates a division expression.
This method is a shortcut for
createExpression(O_Div, expr0, expr1)
.See: O_Div See: createExpression Since: 5.5
 template <typename T0, typename T1>

LSExpression
mod
(T0 expr0, T1 expr1)¶ Creates a modulo expression.
This method is a shortcut for
createExpression(O_Mod, expr0, expr1)
.See: O_Mod See: createExpression Since: 5.5
 template <typename... TN>

LSExpression
array
(TN... operands)¶ Creates an array expression.
This method is a shortcut for
createExpression(O_Array, operands)
.See: O_Array See: createExpression Since: 5.5
 template <typename T0, typename... TN>

LSExpression
at
(T0 arrayExpr, TN... operands)¶ Creates a “at” expression for Ndimensional array.
This method is a shortcut for
createExpression(O_At, arrayExpr, operands)
.See: O_At See: createExpression Since: 5.5
 template <typename T0, typename T1>

LSExpression
scalar
(T0 expr0, T1 expr1)¶ Creates an expression for the scalar product between two arrays.
This method is a shortcut for
createExpression(O_Scalar, expr0, expr1)
.See: O_Scalar See: createExpression Since: 5.5
 template <typename T0>

LSExpression
ceil
(T0 expr0)¶ Creates a ceil expression.
This method is a shortcut for
createExpression(O_Ceil, expr0)
.See: O_Ceil See: createExpression Since: 5.5
 template <typename T0>

LSExpression
floor
(T0 expr0)¶ Creates a floor expression.
This method is a shortcut for
createExpression(O_Floor, expr0)
.See: O_Floor See: createExpression Since: 5.5
 template <typename T0>

LSExpression
round
(T0 expr0)¶ Creates a rounding expression.
This method is a shortcut for
createExpression(O_Round, expr0)
.See: O_Round See: createExpression Since: 5.5
 template <typename T0>

LSExpression
sqrt
(T0 expr0)¶ Creates a square root expression.
This method is a shortcut for
createExpression(O_Sqrt, expr0)
.See: O_Sqrt See: createExpression Since: 5.5
 template <typename T0>

LSExpression
log
(T0 expr0)¶ Creates a log expression.
This method is a shortcut for
createExpression(O_Log, expr0)
.See: O_Log See: createExpression Since: 5.5
 template <typename T0>

LSExpression
exp
(T0 expr0)¶ Creates an exponential expression.
This method is a shortcut for
createExpression(O_Exp, expr0)
.See: O_Exp See: createExpression Since: 5.5
 template <typename T0, typename T1>

LSExpression
pow
(T0 expr0, T1 expr1)¶ Creates a power expression.
This method is a shortcut for
createExpression(O_Pow, expr0, expr1)
.See: O_Pow See: createExpression Since: 5.5
 template <typename T0>

LSExpression
cos
(T0 expr0)¶ Creates a cosine expression.
This method is a shortcut for
createExpression(O_Cos, expr0)
.See: O_Cos See: createExpression Since: 5.5
 template <typename T0>

LSExpression
sin
(T0 expr0)¶ Creates a sine expression.
This method is a shortcut for
createExpression(O_Sin, expr0)
.See: O_Sin See: createExpression Since: 5.5
 template <typename T0>

LSExpression
tan
(T0 expr0)¶ Creates a tangent expression.
This method is a shortcut for
createExpression(O_Tan, expr0)
.See: O_Tan See: createExpression Since: 5.5
 template <typename T0, typename T1, typename T2>

LSExpression
piecewise
(T0 expr0, T1 expr1, T2 expr2)¶ Creates a piecewise linear expression.
This method is a shortcut for
createExpression(O_Piecewise, expr, expr1, expr2)
.See: O_Piecewise See: createExpression Since: 5.5

LSExpression
listVar
(lsint n)¶ Creates a list decision with the given length.
A list is an collection of integers within a domain [0, n1]. This method is a shortcut for
createExpression(O_List, n)
.See: O_List See: createExpression Since: 5.5
 template <typename T0>

LSExpression
count
(T0 expr0)¶ Creates a count expression.
This method is a shortcut for
createExpression(O_Count, expr0)
.See: O_Count See: createExpression Since: 5.5
 template <typename T0, typename T1>

LSExpression
indexOf
(T0 expr0, T1 expr1)¶ Creates an indexOf expression.
This method is a shortcut for
createExpression(O_IndexOf, expr0, expr1)
.See: O_IndexOf See: createExpression Since: 5.5
 template <typename T0, typename T1>

LSExpression
contains
(T0 expr0, T1 expr1)¶ Creates a contains expression.
This method is a shortcut for
createExpression(O_Contains, expr0, expr1)
.See: O_Contains See: createExpression Since: 7.5
 template <typename... TN>

LSExpression
partition
(TN... operands)¶ Creates a partition expression.
This method is a shortcut for
createExpression(O_Partition, operands)
.See: O_Partition See: createExpression Since: 5.5
 template <typename... TN>

LSExpression
disjoint
(TN... operands)¶ Creates a disjoint expression.
This method is a shortcut for
createExpression(O_Disjoint, operands)
.See: O_Disjoint See: createExpression Since: 5.5

LSExpression
nativeFunction
(LSNativeFunction *func)¶ Creates a native function expression.
This method is a shortcut for
createNativeFunction(func)
.See: O_NativeFunction See: createNativeFunction Since: 6.0
 template <typename T>

LSExpression
function
(T functor)¶ Creates a function expression.
This method is a shortcut for
createFunction(functor)
.See: O_Function See: createFunction Since: 7.0
 template <typename T0, typename T1>

LSExpression
range
(T0 expr0, T1 expr1)¶ Creates a range expression.
This method is a shortcut for
createExpression(O_Range, expr0, expr1)
.See: O_Range See: createExpression Since: 7.0

int
getNbExpressions
() const¶ Gets the number of expressions added to this model.
Return: Number of expressions.

LSExpression
getExpression
(int exprIndex) const¶ Gets the expression with the given index in this model.
Return: Expression with the given index. Parameters: exprIndex  Index of the expression.

LSExpression
getExpression
(const std::string &name) const¶ Gets the expression with the given name.
Throws an exception if no expression with the given name exists.
Return: Expression with the given name. Parameters: name  Name.

int
getNbDecisions
() const¶ Gets the number of decisions in the model.
This corresponds to the number of decision variables declared in the model.
Return: Number of decisions.

LSExpression
getDecision
(int decisionIndex) const¶ Gets the decision with the given index.
Return: Decision with the given index. Parameters: decisionIndex  Index of the decision.

void
addConstraint
(const LSExpression &expr)¶ Adds the given expression to the list of constraints.
It means that the value of this expression must be constrained to be equal to 1 in any solution found by the solver. Hence, only boolean expressions (that is, expressions whose value is boolean) can be constrained. Only allowed in state S_Modeling. If the expression is already a constraint, this method does nothing and returns immediately.
Try to avoid hard constraints as much as possible, because LocalSolver (and more generally local search) is not suited for solving hardly constrained problems. In particular, banish constraints that are not surely satisfied in practice. Ideally, only combinatorial constraints (which induce the combinatorial structure of your problem) have to be set. All the other constraints can be relaxed as primary objectives in order to be “softly” satisfied (goal programming). For instance, constraint a <= b can be transformed into minimize max(ba, 0).
Parameters: expr  Expression.

void
constraint
(const LSExpression &expr)¶ Shortcut for
addConstraint(expr)
.See: addConstraint Since: 5.5 Parameters: expr  Expression.

void
removeConstraint
(const LSExpression &expr)¶ Removes the given expression from the list of constraints.
If the expression was not constrained, this method does nothing and returns immediately. Only allowed in state S_Modeling.
Since: 5.0 Parameters: expr  Expression.

void
removeConstraint
(int constraintIndex)¶ Removes the constraint at the given position in the list of constraints.
Only allowed in state S_Modeling.
Since: 5.0 Parameters: constraintIndex  position of the constraint to remove.

int
getNbConstraints
() const¶ Gets the number of constraints added to this model.
Return: Number of constraints.

LSExpression
getConstraint
(int constraintIndex) const¶ Gets the constraint with the given index.
Return: Constraint with the given index. Parameters: constraintIndex  Index of the constraint.

void
addObjective
(const LSExpression &expr, LSObjectiveDirection direction)¶ Adds the given expression to the list of objectives to optimize.
The same expression can be added more than once. Only allowed in state S_Modeling. Note that the objectives will be optimized in the order in which they have been added to the model. It is useful for lexicographic multiobjective optimization, and more particularly for goal programming.
Parameters:  expr  Expression.
 direction  Optimization direction of this objective.

void
minimize
(const LSExpression &expr)¶ Shortcut for
addObjective(expr, OD_Minimize)
.See: addObjective Since: 5.5 Parameters: expr  Expression.

void
maximize
(const LSExpression &expr)¶ Shortcut for
addObjective(expr, OD_Maximize)
.See: addObjective Since: 5.5 Parameters: expr  Expression.

void
removeObjective
(int objectiveIndex) const¶ Removes the objective at the given position in the list of objectives.
Note that the objectives created after the removed one have their index decreased by 1. Phases are not modified when an objective is removed. It is the user’s responsibility to change the objective index of each phase to keep it coherent (with LSPhase#setOptimizedObjective), or to disable it (with LSPhase#setEnabled). Only allowed in state S_Modeling.
Since: 5.0 Parameters: objectiveIndex  position of the objective to remove.

int
getNbObjectives
() const¶ Gets the number of objectives added to this model.
Return: Number of objectives.

LSExpression
getObjective
(int objectiveIndex) const¶ Gets the objective with the given index.
Return: Objective with the given index. Parameters: objectiveIndex  Index of the objective.

LSObjectiveDirection
getObjectiveDirection
(int objectiveIndex) const¶ Gets the direction of the objective with the given index.
Return: Objective direction. Parameters: objectiveIndex  Index of the objective.

int
getNbOperands
() const¶ Gets the number of operands in the model.
This corresponds to the number of operands for all expressions declared in the model. It is an analog of the number of non zeros in matrix model encountered in mathematical programming: it gives an hint about the size and the density of your model.
Return: Number of operands.

void
close
()¶ Closes the model.
Only allowed in state S_Modeling. Once the model is closed, no expression, constraints or objectives can be added. The model must be closed before starting its resolution.

void
open
()¶ Opens or reopens the model.
When this method is called, the solver is placed in state S_Modeling. Only allowed in state S_Stopped.

bool
isClosed
() const¶ Returns true if the model is closed, false otherwise.
Return: True if the model is closed.

std::string
toString
() const¶ Returns a string representation of this model.
This representation provides:
 The number of expressions, decisions, constraints, and objectives.
 The density of the model. Useful for debugging or logging purposes.
Return: String representation.