Localsolver  6.0
Package localsolverblackbox

LocalSolverBlackBox solves blackbox optimization problem where the objective function is unknown and costly to evaluate. The function can have boolean, integer or continuous decisions in a finite range. More...

Classes

class  LocalSolverBlackBox
 LocalSolverBlackBox environment. More...
class  LSBBException
 LocalSolverBlackBox exception. More...
class  LSBBExpression
 Mathematical modeling expression. More...
class  LSBBModel
 Mathematical optimization model. More...
class  LSBBNativeContext
 Context for native functions. More...
class  LSBBParam
 Solving parameters. More...
class  LSBBSolution
 Solution to the optimization model. More...

Enumerations

enum  LSBBErrorCode {
  Api,
  File,
  Model,
  Callback,
  License,
  Solver,
  Internal,
  Modeler
}
 List of error codes used by LSBBException. More...
enum  LSBBObjectiveDirection {
  Minimize,
  Maximize
}
 Objective directions. More...
enum  LSBBOperator {
  Bool,
  Int,
  Float,
  Const,
  NativeFunction,
  Call
}
 Mathematical operators available for modeling. More...
enum  LSBBState {
  Modeling,
  Running,
  Paused,
  Stopped
}
 State of LocalSolverBlackBox environment. More...

Functions

delegate double LSBBNativeFunction (LSBBNativeContext context)
 Native function delegate.

Detailed Description

LocalSolverBlackBox solves blackbox optimization problem where the objective function is unknown and costly to evaluate. The function can have boolean, integer or continuous decisions in a finite range.

Enumeration Type Documentation

List of error codes used by LSBBException.

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 LocalSolverBlackBox.
  • 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 LocalSolverBlackBox error.

Modeler 

Code used when an error is encountered in the modeler.

Objective directions.

See Also
LSBBModel.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
LSBBModel, LSBBExpression
Enumerator:
Bool 

Boolean decision.

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

Int 

Integer decision variable.

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

Float 

Float decision.

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

Const 

Constant.

Unary operator. Can be equal to any integer. Note that constants 0 or 1 are considered as boolean.

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 LSBBModel::CreateNativeFunction.

See Also
LSBBNativeFunction
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.

State of LocalSolverBlackBox environment.

See Also
LocalSolverBlackBox.GetState
Enumerator:
Modeling 

Model is being built.

Running 

Solver is running.

Paused 

Solver is paused.

Stopped 

Solver is stopped.

Function Documentation

delegate double localsolverblackbox.LSBBNativeFunction ( LSBBNativeContext  context)

Native function delegate.

To connect your blackbox function with LocalSolverBlackBox, 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 LSBBExpression with LSBBModel::CreateNativeFunction.
  3. Pass arguments to your function and call it. For that, you have to create expressions of type LSBBOperator::Call. The first operand must be your native function. The other operands must be LSExpressions decisions. 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 LSBBState::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 LocalSolverBlackBox::Stop().