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 reopen-it (with open()) or instantiate another LocalSolver environment to optimize another model.

See:LSExpression
See:LSOperator

Summary

Functions
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 N-dimensional 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 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.

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:

O_Float

See:

createExpression

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:

O_Int

See:

createExpression

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 N-dimensional 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, n-1]. 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(b-a, 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.