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 LSOperator

Summary¶

Functions¶
`createConstant`	Creates a constant expression representing the given value.
`createNativeFunction`	Creates a native function.
`createExpression`	Creates an expression of the given type.
`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 an 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 1-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.
`partition`	Creates a partition expression.
`disjoint`	Creates a disjoint expression.
`function`	Creates a function 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

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.

LSExpression createExpression(LSOperator op)¶

Creates an expression of the given type.

The expression is created without operand. Only allowed in state S_Modeling. This method cannot be used to create constants: use createConstant(lsint) or createConstant(lsdouble) instead.

Return:	Created expression.
Parameters:	op - Type of expression to create.

template <typename T0>

LSExpression createExpression(LSOperator op, T0 expr0)¶

Creates an expression of the given type, with the given operand.

Only allowed in state S_Modeling. Useful for creating unary expressions. The operand can be a double, an integer or a previously declared LSExpression.

Return:	Created expression.
Templates:	T0 - type of the operand to add. Types allowed: constant types or LSExpression.
Parameters:	op - Type of expression to create. expr0 - Operand 0.

template <typename T0, typename T1>

LSExpression createExpression(LSOperator op, T0 expr0, T1 expr1)¶

Creates an expression of the given type, with the given ordered operands.

Only allowed in state S_Modeling. Useful for creating binary expressions.

The operands can be doubles, integers or previously declared LSExpressions. It is also possible to use this method with iterators. In that case, expr0 and expr1 must be iterators of the same type, pointing respectively to the initial and final positions of the operands

Return:	Created expression.
Templates:	T0 - type of the operand to add. Types allowed: constant types, LSExpression or iterator. T1 - type of the operand to add. Types allowed: constant types, LSExpression or iterator.
Parameters:	op - Type of expression to create. expr0 - Operand 0. expr1 - Operand 1.

template <typename T0, typename T1, typename T2>

LSExpression createExpression(LSOperator op, T0 expr0, T1 expr1, T2 expr2)¶

Creates an expression of the given type, with the given ordered operands.

Only allowed in state S_Modeling. Useful for creating ternary expressions (in particular, O_If expressions). The operands can be doubles, integers or previously declared LSExpressions.

Return:	Created expression.
Templates:	T0 - type of the operand to add. Types allowed: constant types or LSExpression. T1 - type of the operand to add. Types allowed: constant types or LSExpression. T2 - type of the operand to add. Types allowed: constant types or LSExpression.
Parameters:	op - Type of expression to create. expr0 - Operand 0. expr1 - Operand 1. expr2 - Operand 2.

LSExpression boolVar()¶

Creates a boolean decision.

Binary decision variable with domain [0.1].

See:	O_Bool
Since:	5.5

LSExpression floatVar(lsdouble min, lsdouble max)¶

Creates a float decision.

Decision variable with domain [min,max].

See:	O_Float
Since:	5.5

LSExpression intVar(lsint min, lsint max)¶

Creates an integer decision.

Decision variable with domain [min,max].

See:	O_Int
Since:	5.5

LSExpression sum()¶

Creates a sum expression.

See:	O_Sum
Since:	5.5

template <typename T0>

LSExpression sum(T0 expr0)¶

Creates a sum expression.

See:	O_Sum
Since:	5.5

template <typename T0, typename T1>

LSExpression sum(T0 expr0, T1 expr1)¶

Creates a sum expression.

See:	O_Sum
Since:	5.5

template <typename T0, typename T1>

LSExpression sub(T0 expr0, T1 expr1)¶

Creates a substraction expression.

See:	O_Sub
Since:	5.5

template <typename T0>

LSExpression call(T0 expr0)¶

Creates a call expression.

See:	O_Call
Since:	6.0

template <typename T0, typename T1>

LSExpression call(T0 expr0, T1 expr1)¶

Creates a call expression.

See:	O_Call
Since:	6.0

template <typename T0, typename T1, typename T2>

LSExpression call(T0 expr0, T1 expr1, T2 expr2)¶

Creates a call expression.

See:	O_Call
Since:	6.0

LSExpression prod()¶

Creates a product expression.

See:	O_Prod
Since:	5.5

template <typename T0>

LSExpression prod(T0 expr0)¶

Creates a product expression.

See:	O_Prod
Since:	5.5

template <typename T0, typename T1>

LSExpression prod(T0 expr0, T1 expr1)¶

Creates a product expression.

See:	O_Prod
Since:	5.5

LSExpression max()¶

Creates a maximum expression.

See:	O_Max
Since:	5.5

template <typename T0>

LSExpression max(T0 expr0)¶

Creates a maximum expression.

See:	O_Max
Since:	5.5

template <typename T0, typename T1>

LSExpression max(T0 expr0, T1 expr1)¶

Creates a maximum expression.

See:	O_Max
Since:	5.5

LSExpression min()¶

Creates a minimum expression.

See:	O_Min
Since:	5.5

template <typename T0>

LSExpression min(T0 expr0)¶

Creates a minimum expression.

See:	O_Min
Since:	5.5

template <typename T0, typename T1>

LSExpression min(T0 expr0, T1 expr1)¶

Creates a minimum expression.

See:	O_Min
Since:	5.5

LSExpression or_()¶

Creates an OR expression.

See:	O_Or
Since:	5.5

template <typename T0>

LSExpression or_(T0 expr0)¶

Creates an OR expression.

See:	O_Or
Since:	5.5

template <typename T0, typename T1>

LSExpression or_(T0 expr0, T1 expr1)¶

Creates an OR expression.

See:	O_Or
Since:	5.5

LSExpression and_()¶

Creates an AND expression.

See:	O_And
Since:	5.5

template <typename T0>

LSExpression and_(T0 expr0)¶

Creates an AND expression.

See:	O_And
Since:	5.5

template <typename T0, typename T1>

LSExpression and_(T0 expr0, T1 expr1)¶

Creates an AND expression.

See:	O_And
Since:	5.5

LSExpression xor_()¶

Creates a XOR expression.

See:	O_Xor
Since:	5.5

template <typename T0>

LSExpression xor_(T0 expr0)¶

Creates a XOR expression.

See:	O_Xor
Since:	5.5

template <typename T0, typename T1>

LSExpression xor_(T0 expr0, T1 expr1)¶

Creates a XOR expression.

See:	O_Xor
Since:	5.5

template <typename T0>

LSExpression not_(T0 expr0)¶

Creates a NOT expression.

See:	O_Not
Since:	5.5

template <typename T0, typename T1>

LSExpression eq(T0 expr0, T1 expr1)¶

Creates an equality expression.

See:	O_Eq
Since:	5.5

template <typename T0, typename T1>

LSExpression neq(T0 expr0, T1 expr1)¶

Creates a disequality expression.

See:	O_Neq
Since:	5.5

template <typename T0, typename T1>

LSExpression geq(T0 expr0, T1 expr1)¶

Creates an inequality expression greater than or equal to.

See:	O_Geq
Since:	5.5

template <typename T0, typename T1>

LSExpression leq(T0 expr0, T1 expr1)¶

Creates an inequality expression less than or equal to.

See:	O_Leq
Since:	5.5

template <typename T0, typename T1>

LSExpression gt(T0 expr0, T1 expr1)¶

Creates an inequality expression greater than.

See:	O_Gt
Since:	5.5

template <typename T0, typename T1>

LSExpression lt(T0 expr0, T1 expr1)¶

Creates an inequality expression less than.

See:	O_Lt
Since:	5.5

template <typename T0, typename T1, typename T2>

LSExpression iif(T0 expr0, T1 expr1, T2 expr2)¶

Creates a ternary conditional expression.

See:	O_If
Since:	5.5

template <typename T0>

LSExpression abs(T0 expr0)¶

Creates an absolute value expression.

See:	O_Abs
Since:	5.5

template <typename T0, typename T1>

LSExpression dist(T0 expr0, T1 expr1)¶

Creates a distance expression.

See:	O_Dist
Since:	5.5

template <typename T0, typename T1>

LSExpression div(T0 expr0, T1 expr1)¶

Creates a division expression.

See:	O_Div
Since:	5.5

template <typename T0, typename T1>

LSExpression mod(T0 expr0, T1 expr1)¶

Creates a modulo expression.

See:	O_Mod
Since:	5.5

LSExpression array()¶

Creates an array expression.

See:	O_Array
Since:	5.5

template <typename T0, typename T1>

LSExpression array(T0 expr0, T1 expr1)¶

Creates an array expression.

See:	O_Array
Since:	5.5

template <typename T0, typename T1>

LSExpression at(T0 arrayExpr, T1 index1)¶

Creates a “at” expression for 1-dimensional array.

See:	O_At
Since:	5.5

template <typename T0, typename T1, typename T2>

LSExpression at(T0 arrayExpr, T1 index1, T2 index2)¶

Creates a “at” expression for 2-dimensional array.

See:	O_At
Since:	5.5

template <typename T0, typename T1, typename T2, typename T3>

LSExpression at(T0 arrayExpr, T1 index1, T2 index2, T3 index3)¶

Creates a “at” expression for 3-dimensional array.

See:	O_At
Since:	5.5

template <typename T0, typename T1>

LSExpression scalar(T0 expr0, T1 expr1)¶

Creates an expression for the scalar product between two arrays.

See:	O_Scalar
Since:	5.5

template <typename T0>

LSExpression ceil(T0 expr0)¶

Creates a ceil expression.

See:	O_Ceil
Since:	5.5

template <typename T0>

LSExpression floor(T0 expr0)¶

Creates a floor expression.

See:	O_Floor
Since:	5.5

template <typename T0>

LSExpression round(T0 expr0)¶

Creates a rounding expression.

See:	O_Round
Since:	5.5

template <typename T0>

LSExpression sqrt(T0 expr0)¶

Creates a square root expression.

See:	O_Sqrt
Since:	5.5

template <typename T0>

LSExpression log(T0 expr0)¶

Creates a log expression.

See:	O_Log
Since:	5.5

template <typename T0>

LSExpression exp(T0 expr0)¶

Creates an exponential expression.

See:	O_Exp
Since:	5.5

template <typename T0, typename T1>

LSExpression pow(T0 expr0, T1 expr1)¶

Creates a power expression.

See:	O_Pow
Since:	5.5

template <typename T0>

LSExpression cos(T0 expr0)¶

Creates a cosine expression.

See:	O_Cos
Since:	5.5

template <typename T0>

LSExpression sin(T0 expr0)¶

Creates a sine expression.

See:	O_Sin
Since:	5.5

template <typename T0>

LSExpression tan(T0 expr0)¶

Creates a tangent expression.

See:	O_Tan
Since:	5.5

template <typename T0, typename T1, typename T2>

LSExpression piecewise(T0 expr0, T1 expr1, T2 expr2)¶

Creates a piecewise linear expression.

See:	O_Piecewise
Since:	5.5

LSExpression listVar(lsint a)¶

Creates a list decision with the given length.

See:	O_List
Since:	5.5

template <typename T0>

LSExpression count(T0 expr0)¶

Creates a count expression.

See:	O_Count
Since:	5.5

template <typename T0, typename T1>

LSExpression indexOf(T0 expr0, T1 expr1)¶

Creates an indexOf expression.

See:	O_IndexOf
Since:	5.5

LSExpression partition()¶

Creates a partition expression.

See:	O_Partition
Since:	5.5

template <typename T0, typename T1>

LSExpression partition(T0 expr0, T1 expr1)¶

Creates a partition expression.

See:	O_Partition
Since:	5.5

LSExpression disjoint()¶

Creates a disjoint expression.

See:	O_Disjoint
Since:	5.5

template <typename T0, typename T1>

LSExpression disjoint(T0 expr0, T1 expr1)¶

Creates a disjoint expression.

See:	O_Disjoint
Since:	5.5

LSExpression function(LSNativeFunction *func)¶

Creates a function expression.

This method is a shortcut for createNativeFunction.

See:

O_NativeFunction

createNativeFunction

Since:

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

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