The OptQuest® Engine
C
Developer’s Guide
Version 4.0
OptTek Systems, Inc.
1919 Seventh St.
Boulder, CO 80302, USA
Tel. (303) 447-3255
optinfo@OptTek.com
www.opttek.com
What is Optimization?
Optimization technology allows analysts to search for
optimal solutions to complex business and engineering problems.
One of the uses of the OptQuest® Engine, OptTek’s
optimization software, is to enable the user to find the best answer to
questions such as:
- What is the maximum return on
budgets allocated to different uses, given uncertain product demand,
machine reliability, and raw material availability?
- What is the most effective configuration
of machines for production scheduling under variable conditions of demand
and operation?
- What are the most effective
location and release sequencing of raw materials to minimize waiting time?
- What are the optimal
workforce allocations to minimize lead time and labor costs?
- What are the optimal
allocations for an investment portfolio?
To investigate
every possible scenario can be very time consuming and even impossible in many
cases. The OptQuest Engine replaces the inaccuracy of trial-and-error with a
potent search engine that can pinpoint the best decision. The user can quickly
determine what combination of variables results in achieving their objectives.
The OptQuest Engine incorporates metaheuristics to guide its
search algorithm toward better solutions.
This approach remembers which solutions worked well and recombines them
into new, better solutions. This
technique does not get trapped in local solutions and it doesn’t get thrown off
course by noisy (uncertain) model data.
The OptQuest Engine combines tabu search, scatter search,
integer programming, and neural networks into a single, composite search
algorithm providing maximum efficiency in identifying new scenarios. Our
well-researched technology has been shown to be orders of magnitude faster than
other approaches. The OptQuest Engine is also flexible, intelligent, and easy
to use. And, according to experts in the field, it is the most reliable
optimization software on the market today.
The simplest optimization problem contains:
- decision
variables
- the
objective function which is a mathematical expression describing a
relationship of the decision variables or the result of an operation (such
as simulation) that uses the decision variables as inputs.
- the
goal of the optimization that is to either minimize or maximize the value
of the objective function
More complex problems may include constraints and
requirements. Constraints describe a
linear relationship between decision variables where the right hand side of the
constraint is constant. Examples of
constraints include:
- Var1
+ 2*Var2 <= 1000
- Var1
+ Var2 = 10
A requirement is a mathematical statement describing a
non-linear relationship between the decision variables. The result of the mathematical expression
must be bounded from above or below.
Examples of requirements include:
- 0
<= Var1 * Var2 <= 1000
- VarA4
<= 10000
A requirement may also be a restriction on a response or the
result of a simulation that requires the result to fall within a specified
range. An example of this type of requirement would be:
- $8000
<= the standard of deviation of the total expected return <=
$10000
Optimization is an iterative process where:
·
The OptQuest Engine calculates possible solutions for
the decision variables.
·
The objective function and requirements are evaluated
using the suggested solutions. The
results are analyzed by the OptQuest Engine and a new set of possible solutions
is calculated.
The user controls when the
optimization should stop. The user may
want the optimization to run:
·
For a specified time
·
For a number of iterations
·
Until the user tells it to stop
·
Until the solutions converge to an optimal solution
There are 6 types of decision variables:
A continuous variable may take on
any value between a user specified lower bound and upper bound. A precision value identifies the minimum
amount continuous variables can change. The precision value can be modified by
the user. Refer to Variables Precision.
A discrete variable begins at a
lower bound and increments by a step size up to an upper bound.
An integer variable is a discrete
variable with integer bounds and a step size of 1.
A binary variable is a discrete
variable that can have a value of 0 or 1.
Design variables begin at a lower
bound and increment by a step size to an upper bound. Design variables are used to represent decisions where there is
no clear sense of direction. For example,
design variables are useful in optimization problems where the decision variables
consist of choosing the best alternative from a catalog and the choices are not
in a specific order. Choice #10 may not
be a better choice than choice #1.
Permutation variables are used to solve
a sequencing problem such as the order in which paint should be mixed to
minimize cleanup time between color changes.
The value of a permutation variable represents the location within the
sequence.
The goal of an optimization is to search for values of the
decision variables that provide a maximum value or a minimum value. The user provides an objective function and
tells the optimization software whether the goal is to “Minimize” or “Maximize”
the objective function.
There are two ways to provide an objective function. In the first method, the user provides a way
to calculate a result such as feeding the values of the decision variables into
a simulation model or using the values in a user-coded function. The result of the objective is communicated
back to the OptQuest Engine. The optimization engine analyzes the result and
proceeds to calculate new values for the decision variables.
The second method is available through the class interfaces
for C++ and Java. In this method, an
objective function is given to the OptQuest Engine as a string of variables,
coefficients and operators. The
OptQuest Engine will parse the string, evaluate the objective function, and
analyze the result.
Constraints describe a linear limitation between decision
variables. A constraint is defined as a
list of variables with coefficients, an operator and a value for the right hand
side. The following are examples of
constraints:
- Var1
+ Var2 + Var3 + Var4 + Var5 =
10500
- 0 <=
Var1 + 2*Var2 – Var3 <= 5000
- Var1
- 3*Var5 >= 300
There are two ways to define a constraint. In the first method, the user defines the
pieces of the constraint by defining the operator, the right hand side constant
value, and the list of variables and their coefficients. For the example Var1 +
3*Var5 >= 300, the right hand size would be 300 and the operator would be
>= . The coefficient of Var1 would
be 1 and the coefficient of Var5 would be -3.
The second method is available through the class interfaces
for C++ and Java. In this method, the
constraint is given to the OptQuest Engine as a string. OptQuest Engine will parse the string,
evaluate the constraint. The examples above are all valid constraints that
could be passed to the OptQuest Engine as strings.
A requirement is a mathematical statement describing a
non-linear relationship between the decision variables. A requirement can also be a restriction on a
response that requires its value to fall within a specified range. For example, a requirement for a simulation
problem may be that the the standard of deviation of the total expected return
of an investment portfolio needs to be between $8000 and $10,000.
A requirement always defines a limitation by specifying a
lower bound and/or an upper bound.
There are two ways to define a requirement. In the first method, the user provides a way
to calculate a result such as feeding the values of the decision variables into
a simulation model or using the values in a user-coded function. The result is communicated back to the
OptQuest Engine. The OptQuest Engine checks the result to see if it is within
the requirement’s bounds. If the result
is within the bounds, the solution is considered feasible. If the result is not within the
requirement’s bounds, the solution is considered infeasible. The OptQuest Engine uses the feasibility of
the requirement in its search to find optimal, feasible solutions. Refer to Feasible and Infeasible Solutions.
The second method is available through the class interfaces
for C++ and Java. In this method, a
requirement is given to the OptQuest Engine as a string of variables,
coefficients and operators. The
OptQuest Engine will parse the string, evaluate the requirement and compare the
result against the requirement’s limits. The OptQuest Engine will determine if
the relationship is linear or non-linear and add the appropriate constraint or
requirement.
The class interfaces for C++ and Java allow the user to
control how long an optimization will run by setting stop criteria. If more than one stop criteria are
specified, optimization stops when any one of the criteria is satisfied.
Maximum Number of Iterations
The user specifies an iteration
count. Optimization stops when the
number of iterations exceeds this value.
Maximum Time
The user specifies a time in
seconds. Optimization stops when the
time exceeds this value.
Automatic Stop
When automatic stop is set, the
optimization stops when the result of the objective function stops
improving. The default is to stop when
the value of the objective function does not vary by 0.00001 after 100
iterations. The user can control the automatic stop criteria by setting the
objective precision and the number of expected iterations. Refer to objective
precision and number of iterations.
User Controlled Stop
In this case the optimization will
run until the user tells the optimization to stop.
In the procedural interface, the user controls the length of
the optimization by counting the number of iterations, by keeping track of the elapsed time or by
using the Automatic Stop feature.
Feasible and infeasible solutions
A feasible solution is one that satisfies all constraints
and requirements. Each time the OptQuest Engine generates a new set of values
for the decision variables, it creates constraint feasible solutions.
The objective function and the requirement functions are
evaluated at the end of each iteration of the optimization. The OptQuest Engine uses the results of the
requirement functions to determine if a solution is requirement-feasible. If the
result of a requirement is within the limits of the requirement, the result is
requirement feasible. If the result is
outside the limits of the requirement, the solution is requirement infeasible.
The OptQuest Engine makes finding a feasible solution its
highest priority. Once it has found a feasible solution, it concentrates on
finding better solutions.
The fact that a particular solution may be infeasible does
not imply that the problem itself is infeasible. However, infeasible problems
do exist. For example, suppose that in a Job Shop problem a foreman insists on
finding an optimal configuration with the following constraints:
- drills
+ grinders <= 4
- drills
+ grinders >= 5
Clearly, there is no combination that will satisfy both of these
constraints.
You can make infeasible problems feasible by fixing the
inconsistencies of the relationships modeled by the constraints. The OptQuest
Engine detects optimization models that are constraint-infeasible and reports
them to you. If a model is
constraint-feasible, the OptQuest Engine will always find a feasible solution
and search for the optimal solution (i.e., the best solution that satisfies all
constraints).
The OptQuest Engine cannot detect requirement infeasible
solutions. An example of a requirement
infeasible problem is:
- drills
* grinders <= 20
- drills
* grinders >= 20
If the OptQuest Engine cannot find any feasible solutions,
the user should check the requirements of the problem for feasibility.
The OptQuest Engine keeps track of the objective value for
the current run and the best objective value found so far. The user can ask the OptQuest Engine for
these values at any time and track the changes as the optimization runs.
The performance of the OptQuest Engine can be improved by
selecting meaningful bounds for the decision variables and using meaningful
constraints. The OptQuest Engine will
eliminate sets of decision variable values that are constraint-infeasible.
Optimization performance may suffer when you include
requirements in the optimization problem.
Requirements can be very time-consuming to evaluate if the requirement
requires a lengthy evaluation such as running an entire simulation. Also, the OptQuest Engine tries to rule out
undesirable solutions by examining the results of feasible and infeasible
requirements.
However, the benefits of eliminating undesirable solutions
may outweigh the performance penalty.
If the optimization is to run for a specified amount of time, it may be
necessary to increase the amount of time to compensate for the additional
overhead of requirements.
If an optimization problem uses only discrete variables, the
OptQuest engine will attempt to enumerate all possible solutions. If the enumeration results in a set of
solutions that is too large for the database of solutions, the OptQuest Engine selects a subset of the
enumeration to evaluate.
If a complete enumeration is accomplished, the OptQuest
Engine will report that the optimal solution has been found. If the problem is requirement infeasible,
the OptQuest engine will report the problem is infeasible.
In some cases the user may wish to find the best solutions
for a range of requirement bounds. The
graph of the bound versus the best objective function is called the efficient
frontier. A typical example occurs in
portfolio optimization where the requirement is a limitation on risk and the
objective is the best return. OptQuest
can be used to automatically search for solutions on the efficient frontier by
efficiently adapting to changing requirement bounds.
It can also be useful to know what effect a requirement has
on the optimal solution and what would happen if the requirement were relaxed
or tightened.
The OptQuest Engine allows the user to change the limits of
a requirement “on the fly.” For
example, the optimization could run for some number of iterations, the bounds
of the requirement could be modified and the optimization could continue. When the bounds of a requirement are
modified, the OptQuest Engine rechecks its database of solutions checking to
see if previous solutions are now feasible or infeasible given the new
bounds. Users that vary the bounds of a
requirement should remember to ask the OptQuest Engine for the new “best”
solution.
Users may vary the bounds on any number of requirements, but
it may be difficult to analyze the effect of multiple changes on the results of
the optimization.
Optimization Properties
In some cases, the user may want to set various properties
to better control the optimization. The
optimization properties can be manipulated to control memory allocation,
precision checking and stop options.
Database Size
The database is used to store
unique solutions. When the OptQuest
Engine suggests a solution, it checks the database to see if it is a solution
that has already been tried. The larger
the database, the less likely a solution will be tried more than once. The
minimum database size is 3000. The
default size is 10,000. The maximum
depends on the user’s system.
Objective Precision
The objective precision is used to
compare solutions. If the difference
between two objective function values is less than the objective precision, the
solutions are considered equal. The
precision is specified as the amount of difference in the range of the
objective value, rather than a constant.
For example, an objective value that ranges from 1 to 1000 with a
precision value of .00001 would indicate that objective values that differed by
0.1 or less would be considered the same.
The default value is 0.0001 (10-4).
Variables Precision
The variables precision is used to
compare the values for decision variables. If the difference of the values for
a variable is less than the variables precision, the values are considered
equal. The precision is specified as the amount of difference in the range of
the variable, rather than a constant.
For example, an variable that ranges from 1 to 100 with a precision
value of .00001 would indicate that objective values that differed by 0.01 or
less would be considered the same. The
default value is 0.0001 (10-4).
If the user has a guess about the possible solution(s) for
an optimization problem, the solution(s) can be given to the OptQuest
Engine. Suggested solutions can shorten
the time it takes to find an optimal solution.
If the suggested solutions are added before the optimization is started,
they will be evaluated early in the optimization. If the suggested solutions are added after the optimization has
started, they are added to the end of the list of solutions that will be
evaluated, and it may take many iterations before they are evaluated.
A large optimization problem can take minutes or even hours
to solve and is CPU intensive. The user
may want to see intermediate results or process other tasks such as handling
keystrokes. The C++ and Java class
interface of the OptQuest Engine provides two ways for the user to get control.
- Overriding
the virtual COptQuestOptimization::MonitorStatus(). This method is called once during each
iteration of the optimization. It
is suggested the user retrieve the current and best solutions from this
method.
- Provide
the address of a callback function via the SetCallback() method. The callback function is called
during long processing times such as the initialization of the
optimization problem. It is suggested
this method be used to process key strokes or allow other tasks time to
run.
The procedural interface allows the user to specify a
callback function that is called by the OptQuest Engine during long processing
time. Refer to the procedural interface.
The optimization software is available for the following
platforms and languages:
The “C” and Visual Basic versions of the optimization software
are a procedural interface. The C++ and
Java versions provide an object oriented interface to a C++ or Java object.
The following documents are available from our website at www.OptTek.com
- “The
OptQuestâ
Engine – C++ Developer’s Guide”
- “The
OptQuestâ
Engine – C Developer’s Guide”
- “The
OptQuestâ
Engine – Visual Basic Developer’s Guide”
- “The
OptQuestâ
Engine – Java Developer’s Guide”
Please contact us at optinfo@OptTek.com
for more information on platforms and languages.
The COptQuestOptimization optimization class allows the user
to define and run an optimization problem.
In the simplest case, the user:
- Defines
the decision variables by adding variable objects to the
COptQuestOptimization object
- Defines
the goal of the optimization (maximize or minimize)
- Provides
an Evaluate() method to calculate the objective value.
- Defines
how long the optimization should run by setting stop properties of the
COptQuestOptimization class
For more complex optimizations, the user:
- Defines
constraints by adding constraint objects.
- Defines
requirements by adding requirements objects.
Variables are added to an optimization problem by defining a
variable object and adding the object via the
COptQuestOptimization::AddVariable() method. Note that the class interface
allows the user to optionally assign a name to a variable. These variable names can be used in equation
strings for defining an objective function, constraints and requirements.
Each type of variable has its own class definition.
- COptQuestContinuousVariable
for continuous variables
- COptQuestDiscreteVariable
for discrete variables
- COptQuestIntegerVariable
for integer variables
- COptQuestBinaryVariable
for binary variables
- COptQuestDesignVariable
for design variables
- COptQuestPermutationVariable
for permutation variables.
The user defines the goal of the optimization by calling the
SetMaximize() or SetMinimize() method
of the COptQuestOptimization class.
The objective function evaluates the solution and produces a
result. The user provides an objective function in one of two ways.
Method 1:
The user derives a class from the COptQuestOptimization
class and provides an implementation for the virtual Evaluate() method. The OptQuest Engine calls the Evaluate()
method at the end of each iteration.
The Evaluate() method should retrieve the current value for each
variable by calling the COptQuestVariable::GetCurrentValue() method for each
variable.
The solutions could be used as input to a simulation or
evaluated directly by user code in the Evaluate() method. The result of the evaluation is communicated
back to the OptQuest Engine by the
COptQuestOptimization::SetCurrentObjectiveValue().
Note: If the optimization problem includes requirements that
are not handled as an equation string, the Evaluate() method should also
evaluate the requirements.
Method 2:
The user can define an objective function using the
COptQuestOptimization:: ObjectiveEquation() method. An objective equation is a string defining a relationship between
the variables.
The variable names in the objective equation must match the
names of variable objects added to the COptQuestOptimization object. The objective equation is not evaluated
until optimization begins, so an objective equation string can reference a
variable that has not yet been added to the problem.
Refer to String Equations.
There are two ways to add a constraint to an optimization
problem:
Method 1:
Constraints can be added to a problem by defining a
constraint object and adding it to the COptQuestOptimization object using the
AddConstraint () method
There are 3 types of constraint objects:
- COptQuestEQConstraint
for equality constraints (Var1 + Var2 = 150)
- COptQuestLEConstraint
for less than or equal constraint equations (Var1 + Var2 <= 150)
- COptQuestGEConstraint
for greater than or equal constraint equations (Var1 + Var2 >= 150)
Method 2:
The user can define a constraint equation and add the
equation using the COptQuestOptimization:: ConstraintEquation() method. A constraint equation is a string that
identifies a relationship between the decision variables.
The variable names in the constraint equation must match the
names of variable objects added to the COptQuestOptimization object. The
constraint expression is not evaluated until optimization begins, so a
constraint string can reference a variable that has not yet been added to the
problem.
Refer to String Equations.
There are two ways to add a requirement to an optimization
problem:
Method 1:
Requirements can be added to a problem by defining a requirement
object and adding it to the COptQuestOptimization object using the
AddRequirement () method. The user is
responsible for providing the function associated with the requirement. The
requirement is evaluated as part of the user implementation of the virtual
Evaluate() method. The result of the
requirement is communicated to the OptQuest Engine by the
COptQuestRequirement::SetCurrentValue() method. The OptQuest Engine will determine if the result satisfies the
requirement bounds and mark the solution as requirement feasible or requirement
infeasible.
There are 3 types of requirement objects:
- COptQuestLowerRequirement
is used when the result of a requirement needs to be greater than or equal
to a lower bound. (Var1 * Var2 >= 150)
- COptQuestUpperRequirement
is used when the result of a requirement needs to be less than or equal to
an upper bound. (Var1 * Var2 <= 150)
- COptQuestDualRequirement
is used when the result of a requirement
needs to be between two values.
(50 <= Var1 * Var2 <= 150)
Method 2:
The user can define a requirement equation and add the
equation using the COptQuestOptimization:: ConstraintEquation () method. A requirement equation is a string that
identifies a relationship between the decision variables.
The variable names in the constraint equation must match the
names of variable objects added to the COptQuestOptimization object. The
constraint expression is not evaluated until optimization begins, so a
constraint string can reference a variable that has not yet been added to the
problem.
Refer to String Equations.
Variable Requirements
Variable requirements requires COptQuestRequirement objects
be added to the optimization problem..
To modify the lower bound or upper bound of a requirement, use the
COptQuestRequirement::SetLowerBound() or
COptQuestRequirement::SetUpperBound() method. Since modifying the bounds of a requirement may make previously
infeasible solutions feasible and vice versa, the user should call
COptQuestOptimization:: GetBestObjectiveValue () to get the new, best value.
Suggested solutions can shorten the time it takes to find an
optimal solution. If the suggested
solutions are added before the optimization is started, they will be evaluated
early in the optimization. If the
suggested solutions are added after the optimization has started, they are
added to the end of the list of solutions that will be evaluated, and it may
take many iterations before they are evaluated. It is not necessary to suggest a solution for every variable
involved in the problem.
To add a suggested solution:
- For
each variable involved in the suggested solution, use the
SetSuggestedValue() method of the variable object to set the suggested
value.
- Use
the COptQuestOptimization:: AddSuggestedSolution() method to tell the
optimization object the set of variables makes up one possible solution.
Multiple suggestions can be made by repeating these steps.
After adding variables, defining constraints and defining
requirements, the optimization is run by calling the
COptQuestOptimization::Optimize() method.
The Optimize() method will:
- Check
all string expressions making sure the variable names in the expression
refer to a named variable that has been added to the problem.
- The
OptQuest Engine will pick the optimal method for solving the problem
Problems that have a linear objective function, linear constraints and no
requirements defined will use the MIP solver to solve the problem. All other problems will use non-linear
evaluation methods to solve the problem.
- Check
the set of constraints for constraint feasibility.
- Check
for a valid stop options. At least
one stop property must be set.
- Initialize
the solutions database.
- Begins
iterative process of evaluating solutions
If errors are found during the optimization, they are
reported to the user via a COptQuestException.
Refer to Error Handling.
String Equations
The C++ and Java class interfaces of the OptQuest Engine
allow the user to express the objective function, constraints and requirements
as a string expression. To use this
capability, the user must provide names for the variable objects added to the
COptQuestOptimization object.
The following are examples of valid string expressions
defining an objective function. An
objective function expression cannot use the equality operators =, <=,
>=.
- 250*exp(Var1
+ 0.67*Var2)
The following are examples of valid string expressions
defining a linear constraint.
Constraint expressions must use at least one of the equality operators.
- Var1
+ 3*Var2 = 200
- 500
<= Var1 – Var2 + 3*Var3 10 <=
600
- Var1
+ Var2/10 >= 5
The following are examples of valid string expressions defining
a non-linear constraint (also referred to as a non-linear requirement in this
documentation):
An equation string may use the following operators:
·
+ - * /
·
<=
·
=
·
>=
- abs
- acos
- asin
- atan
- atan2
- ceil
- cos
- cosh
- exp
- floor
- fmod
- log
- log10
- max
- min
- pow
- sin
- sinh
- sqrt
- tan
- tanh
When the OptQuest Engine detects an error, it throws a
COptQuestException. The exception
number can be retrieved by calling the COptQuestException:: ErrorNumber() method.
Calling the COptQuestException:: Description() method will return a string
description of the error.
If the user can identify a problem as a mixed integer
problem, the OptQuest Engine can streamline processing and produce a result in
a shorter amount of time.
A mixed integer problem has:
- Continuous
and/or integer variables
- Linear
constraints
- A
linear objective function
- No
requirements
A mixed integer problem could be a linear problem which
contains only continuous variables or an integer problem which contains only
integer and binary variables. The
COptQuestMIP class is used to optimize mixed integer problems.
Variables are added to an MIP optimization problem by defining
a variable object and adding the object via the COptQuestMIP::AddVariable()
method. Note that the class interface allows the user to optionally assign a
name to a variable. These variable
names can be used in equation strings for defining an objective function,
constraints and requirements.
Each type of variable has its own class definition.
- COptQuestContinuousVariable
for continuous variables
- COptQuestDiscreteVariable
for discrete variables
- COptQuestIntegerVariable
for integer variables
- COptQuestBinaryVariable
for binary variables
The user defines the goal of the optimization by calling the
SetMaximize() or SetMinimize() method
of the COptQuestMIP class.
The objective function evaluates the solution and produces a
result. The user provides an objective function in one of two ways.
Method 1:
The user can define an objective function by defining an
objective function object and adding the object via the COptQuestMIP::
AddObjectiveFunction() method. The
objective function object , COptQuestObjectiveFunction, contains variables and
coefficients for each of the variables..
Method 2:
The user can define an objective function using the
COptQuestMIP:: ObjectiveEquation() method.
An objective equation is a string defining a relationship between the
variables.
The variable names in the objective equation must match the
names of variable objects added to the COptQuestMIP object. The objective equation is not evaluated
until optimization begins, so an objective equation string can reference a
variable that has not yet been added to the problem.
Refer to String Equations.
There are two ways to add a constraint to an MIP
optimization problem:
Method 1:
Constraints can be added to a problem by defining a
constraint object and adding it to the COptQuestMIP object using the
AddConstraint () method
There are 3 types of constraint objects:
- COptQuestEQConstraint
for equality constraints (Var1 + Var2 = 150)
- COptQuestLEConstraint
for less than or equal constraint equations (Var1 + Var2 <= 150)
- COptQuestGEConstraint
for greater than or equal constraint equations (Var1 + Var2 >= 150)
Method 2:
The user can define a constraint equation and add the
equation using the COptQuestMIP:: ConstraintEquation() method. A constraint equation is a string that
identifies a relationship between the decision variables.
The variable names in the constraint equation must match the
names of variable objects added to the COptQuestOptimization object. The
constraint expression is not evaluated until optimization begins, so a
constraint string can reference a variable that has not yet been added to the
problem.
Refer to String Equations.
To begin the optimization, call the COptQuestMIP::Optimize()
method. The Optimize() method will not
return until the MIP has been solved.
Simple problems will solve quickly.
Difficult problems may run for several hours.
If errors are found during the optimization, they are
reported to the user via a COptQuestException.
Refer to Error Handling.
Procedural Interface
To define an
optimization problem using the procedural interface, the user needs to:
- Tell
the OptQuest Engine how many variables, constraints and requirements are
involved in the problem
- Define
the variables
- Define
the constraints
- Define
the requirements
- Provide
code that repeatedly calls the OptQuest Engine to get a solution,
calculates an objective value using the solution, and tells the OptQuest
Engine the results of the evaluation.
- Determine
when to stop the iterative loop that gets solutions and evaluates them.
The first step in defining an optimization problem is to
call OCLSetup(). The parameters to
OCLSetup() indicate how many variables, constraints and requirements are
involved in the problem and the goal of the optimization (maximize or
minimize). OCLSetup() returns a problem
ID which is used as an input on all subsequent procedure calls.
Variables are added to the problem by calling
OCLDefineVar(). Variables are
identified by a number. The variable
number must be between 1 and the total number of variables in the problem. OCLDefineVar() allows the user to specify
the upper and lower bounds and suggest a possible value for the variable.
A constraint defines a linear relationship between the
variables of a problem and is defined by a sum of variables and coefficients
for the variables, an operation and a right hand side constant. Constraints are identified by a number where
the constraint number must be between 1 and the total number of constraints in
the problem. Constraints are added to the problem by a multi-step process and
the constraint number is used to identify the multiple pieces of a single
constraint definition.
The procedures OCLConsCoeff(), OCLConsType() and
OCLConsRHS() are used to create a constraint.
OCLConsCoeff() is called once for each variable involved in the
constraint. The variables are
identified by the variable number that was assigned when the variable was added
to the problem via the OCLDefineVar() procedure. Variables that are not
assigned a coefficient have a default coefficient of 0.0 which means they are
not involved in the constraint evaluation.
A requirement may be a non-linear relationship between the
variables of a problem, or it may be an output such as the result of a
simulation. A requirement is defined by
specifying the low and high value. The
results of the requirement must fall in this range for the solution to be
considered feasible. The user must
provide the functionality for evaluating the requirement. Examples of a requirement are a user-coded
non-linear expression or a simulation output.
The function OCLDefineReq() is used to set the bounds of the
requirement. Requirements are
identified by a number where the requirement number must be between 1 and the total
number of requirements in the problem.
The user is responsible for communicating the results of the requirement
to the OptQuest Engine using the function OCLPutSolution().
The actual optimization is an iterative process involving:
- Getting
the current solutions from the OptQuest Engine
- Evaluating
the objective function and requirements using the solutions
- Telling
the OptQuest Engine the results of the objective function and requirements
The function OCLGetSolution() is used to retrieve the
current solution. Input is a double
precision array of n+1 elements where n is the number of variables in the
problem. OCLGetSolution() places the current value for each variable into the
array. The variable ID used in OCLDefineVar() can be used as an index into the
solutions array. (Note: array element 0 is not used.)
The results of the objective function and the requirements
are given back to OptQuest Engine using the function OCLPutSolution(). The value of the objective function and the
value for all requirements are put into a double precision array of n+1 elements
where n is the number of requirements.
Element 0 is the value of the objective function. Elements 1 to n are the values of the
requirements. The requirement ID used
to define the requirement ( OCLDefineReq()) is
the index to the corresponding requirement in this array.
OCLGetSolution() returns a solution ID which is used as
input to OCLPutSolution(). This allows
the OptQuest Engine to tie the values of the objective function and the
requirements to a particular set of solutions.
The user can control how long the optimization should
run. This could be a number of
iterations or an elapse time. In the
procedural interface, it is the user’s responsibility to stop the
optimization. When an optimization has
completed, the user should call OCLGoodBye() to release all resources
associated with the problem.
The user can get the current results and the best results at
any time during the optimization. OCLGetSolution() will give the current
results. The function OCLGetBest() will
return the best solution as well as the best value for the objective function
and requirements.
Each call of OCLPutSolution() must be paired with a call to
OCLGetSolution() or an error will be returned.
When an optimization has completed (before calling
OCLGoodBye()), the user should make a final call to OCLGetBest() to get the
final result.
The user can suggest values for a possible solution by
setting a suggested value when defining the variable (OCLDefineVar()) or by
calling OCLSugSolution(). Input to
OCLSugSolution() is a double precision array of n elements where n is the
number of variables in the problem. The
variable ID is an index into the input array.
User’s can suggest any number of possible solutions. The solutions are added to the OptQuest
Engine database. If the suggested
solutions are added before the optimization is started, they will one of the
first set of values used for evaluation.
If suggested solutions are added after the optimization has started,
they are added to the end of the list of solutions that will be evaluated. It may take many iterations before they are
used for evaluation.
It is not necessary to assign a value for each
variable. If a variable is assigned the
value returned by OCLGetNull(), the OptQuest Engine will use a value half way
between the lower and upper bound.
In some cases it can be useful to know what effect a
requirement has on the optimal solution and what would happen if the
requirement were relaxed or tightened.
The function OCLDefineReq() can be called to modify the bounds of a
requirement.
Modifying the bounds of a requirement may make previously
infeasible solutions feasible and vice versa, so the user should OCLGetBest()
to get the new, best solutions and objective value.
Large optimization problems can be CPU intensive and can
take a long time to set up or to find a solution set. The user can identify a callback function that will be called
during long running operations. The
user’s call back function can handle keystrokes and allow time for other
processes to run. The function
OCLCallback() identifies the address of the callback function.
The procedures all return an error code. Zero or a positive number indicate the
procedure worked. A negative number
indicates a failure. See Appendix 1 for
the error codes and their meanings.
If the user can identify a problem as a mixed integer
problem, the OptQuest Engine can streamline processing and produce a result in
a shorter amount of time.
A mixed integer problem has:
- Continuous
and/or integer variables
- Linear
constraints
- A
linear objective function
- No
requirements
A mixed integer problem could be a linear problem which
contains only continuous variables or an integer problem which contains only
integer and binary variables. A MIP
problem is set up using the same methods as a non-MIP problem. Refer to Procedural
Interface. The user calls
OCLSetup(), OCLDefineVar() and defines constraints using OCLConsCoeff(),
OCLConsType(), and OCLConsRHS(). Mixed
integer problems do not have requirements.
The objective function is linear and is defined by a set of
calls to OCLDefineObj(). The user
describes the linear relationship between the variables by identifying the
variable and its coefficient. There
should be one call to OCLDefineObj() for each variable in the problem.
The function OCLSolveLP() is called to solve the mixed
integer problem. This function will not
return until the problem is solved. For
small problems, this may be immediate.
For large, complex problems this may take hours.
The solution is returned
in one of the parameters to OCLSolveLP().
Since MIP problems can take a long time to solve, the user
may want to identify a callback function that will be called periodically by
the OptQuest Engine. The user’s call
back function can handle keystrokes and allow time for other processes to
run. The function OCLCallback()
identifies the address of the callback function.
Error Codes
The following error codes are returned by the OptQuest
Engine.
-2803 Step value must be strictly
greater than zero
C Procedural Interface Documentation
Start and Ending an Optimization Session
OCLSetup
This function sets up the optimization problem. The function
triggers the allocation of memory for the number of variables, constraints and
requirements in the problem. It also specifies the direction of the
optimization (i.e., maximize or minimize).
Upon success, the function returns a problem identifier
which is a value greater than zero. If
an error occurred, an error code is returned as the return value. The identifier is an input to all subsequent
OCL function calls.
long OCLSetup(long nvars,
long nperm, long ncons, long nreqs, char *direc, long lic);
nvars The number of decision variables
in the problem (must be an integer).
nperm The number of permutation
variables in the problem (must be an integer).
ncons The number of constraints in the
problem (must be an integer).
nreqs The number of requirements in
the problem (must be an integer).
direc An array of characters
containing the string “MAX” to indicate
maximization or “MIN” to indicate minimization.
lic A valid license number for
the OptQuest Engine
OCLGoodBye
This function deletes a previously defined problem from the
OptQuest Engine and frees the memory associated with the problem. The problem
is identified using the problem identifier nprob returned by OCLSetup. The use of this function is highly
recommended when more than one problem is defined within the same
application. The function returns zero
upon success or an error code upon failure.
long OCLGoodBye(long nprob);
nprob The problem identifier returned
by OCLSetup.
OCLRestart
This function “restarts” the search. It keeps the best
solution in the population and deletes the rest of them as well as all the
solutions not evaluated in the database. Then the process starts by generating
a new population (except for the first element).
The function returns zero upon success or an error code upon
failure.
long OCLRestart(long nprob);
nprob The problem identifier returned
by OCLSetup.
Null Values in OCL
OCLNULL is typically used as a “dummy variable” to ignore an
argument of an OCL function. For
example, if a variable does not have a suggested value, OCLNULL can be used as
the suggested value parameter in the call to OCLDefineVar().
OCLGetNull
This function retrieves the value of OCLNULL. This function
returns a long integer so we use a cast operator if the argument has a
different type.
long OCLGetNull(long
nprob);
nprob The problem identifier returned
by OCLSetup.
OCLSetNull
This function sets the OCLNULL value. The default value of
OCLNULL is –111111111. If this value is a valid value in the user
application, OCLNULL can be changed by
using OCLSetNull(). The user should
call this function before passing OCLNULL as an argument in any other function
in.
The function returns zero upon success or an error code upon
failure.
long OCLSetNull(long nprob, long pval);
nprob The
problem identifier returned by OCLSetup.
pval An
integer indicating the new value for OCLNULL.
Defining Variables
OCLDefineVar
This function is used to define decision variables. The
definition includes the variable number, the lower limit of the range, the
suggested value, the upper limit of the range, the variable type and the step
size (if applicable). Permutation variables do not need to be defined.
The function returns zero upon success or an error code
upon failure.
long OCLDefineVar(long nprob, long var, double low,
double sug, double high, char *type, double step);
nprob The
problem identifier returned by OCLSetup.
var The
number of the variable that is being defined (must be a long integer). This number must be between 1 and the nvars,
number of variables declared in OCLSetup().
low A double indicating the minimum value for the corresponding
variable.
sug A double indicating the suggested value for the
corresponding variable. The suggested value is typically included in the
initial population, unless the value results in an infeasible solution. The
OCLNULL value is passed when no suggested value is available.
high A double indicating the
maximum value for the corresponding variable.
type An array of characters with
the string “CON” to define a continuous variable, “DIS” to define a discrete
variable, or “DSN” to define a design variable.
step The step size for a discrete
or design variable (must be a double). Step sizes may be integer or fractional
values and must be strictly greater than zero. Step sizes for continuous
variables are ignored.
Defining Constraints
OCLConsCoeff
This function defines or changes a constraint coefficient.
This function is meaningful only if ncons is greater than zero in OCLSetup
(i.e. the problem formulation actually contains one or more constraints).
The function returns zero upon success or an error code upon
failure. A common failure consists of attempting to change a coefficient when
no constraints have been declared in OCLSetup or when either the constraint or
the decision variable index is out of range.
long OCLConsCoeff(long nprob, long cons, long var, double
coeffval);
nprob The
problem identifier returned by OCLSetup.
cons The constraint index. This value
must be between 1 and ncons, where ncons is the number of constraints declared
in OCLSetup.
var The variable index of the
coefficient to be defined or changed. This value must be between 1 and nvars,
as declared in OCLSetup.
coeffval The
value of the coefficient.
OCLConsRhs
This function defines the right-hand-side value of a
constraint. This function is meaningful only if ncons is greater than zero in
OCLSetup (i.e. the problem formulation contains one or more constraints).
The function returns zero upon success or an error code upon
failure. A common mistake consists of attempting to define a right-hand-side
value when no constraints have been declared in OCLSetup.
long OCLConsRhs(long nprob, long cons, double rhsval);
nprob The
problem identifier returned by OCLSetup.
cons The constraint index of the
right-hand-side value to be changed. This index must be between 1 and ncons, as
declared in OCLSetup.
rhsval The
value of the right hand side.
OCLConsType
This function defines the type of constraint (i.e.,
greater-than-or-equal, equal, or less-than-or-equal). This function is meaningful
only if ncons is greater than zero in OCLSetup (i.e., the problem formulations
contains one or more constraints).
The function returns zero upon success or an error code upon
failure. A common mistake consists of attempting to define a constraint type
when no constraints have been declared in OCLSetup.
long OCLConsType(long nprob, long cons, long type);
nprob The
problem identifier returned by OCLSetup.
cons The constraint index of the
constraint type being defined or changed. This index must be between 1 and
ncons, as defined in OCLSetup.
type This parameter indicates the
type of the constraint:
·
OCLLE
(less-than-or-equal)
·
OCLGE(greater-than-or-equal
·
OCLEQ (equal).
Defining Requirements
OCLDefineReq
This function is used to define or change a requirement. The
definition includes the requirement number, the lower bound and the upper
bound. At least one of the bounds must to set.
The function returns zero upon success or an error code upon
failure.
long OCLDefineReq(long nprob, long req, double low, double
high);
nprob The
problem identifier returned by OCLSetup.
req The requirement index of the
requirement being defined or changed. This index must be between 1 and nreqs as
defined in OCLSetup.
low A double indicating the
minimum value for the requirement. The OCLNULL value can be used if a lower
bound is not specified.
high A double indicating the
maximum value for the corresponding requirement. The OCLNULL value can be used
if an upper bound is not specified.
Functions for Solutions
OCLGetBest
This function retrieves the best solution found so far
during the OptQuest Engine’s search.
After the optimization has completed, the user should call
this function to get the optimal values for the decision and/or permutation
variables.
OCLGetBest can also be called anytime during the
optimization process to monitor the improvements.
The arguments of this function include two arrays, one for
the solution values and one for the objective function and requirements, if any
are defined. The function returns zero to indicate that the best solution is
requirement-feasible, i.e., the best solution satisfies all the requirements. A
return value of 1 indicates that at least one requirement is violated by the
best solution. Other return values indicate that an error has occurred.
long OCLGetBest(long nprob, double *sol, double *objval);
nprob The
problem identifier returned by OCLSetup.
sol An array of doubles. The values of the variables associated
with the best solution are placed in the sol array. The element sol[0] is not used.
Indices into the sol array correspond to the variable index used as
input to OCLDefineVar. The array must be dimensioned such that the variable
values can be placed in positions 1 to nvar + nperm, as defined in OCLSetup.
objval An array of doubles. The best
value of the objective function is in req[0].
The requirements are in req[1] to req[nreqs] where nreqs is the number
of requirements defined in OCLSetup. The array should have a size of at least
req positions, as defined in OCLSetup.
Note that if no requirements are defined, objval can be dimensioned as a
simple double (one-dimensional) variable. In this case a pointer to this
variable must be passed.
OCLGetSolution
This function retrieves solutions from the database for
evaluation purposes and is a mandatory function in the communication process
between the OptQuest Engine and the user’s application. The function uses an
array of doubles. The values of the
variables are placed in the array. Note that the array must have enough space
to hold all the variables, whose index range from 1 to the number of decision
variables plus the number of permutation variables in the current problem.
If more than one solution can be evaluated at the same time,
this function can be called repeatedly until it returns a zero. This is
especially useful for parallel implementations.
The function returns a unique solution identifier (i.e., an
integer strictly greater than zero) upon success or an error code upon failure.
long OCLGetSolution(long nprob, double *sol);
nprob The
problem identifier returned by OCLSetup.
sol An array of doubles. The
values of the variables associated with the best solution are placed in the sol
array. sol[0] is not used. Indices into
the sol array correspond to the variable index used as input to OCLDefineVar.
The array must be dimensioned such
that the variable values can be placed in positions 1 to nvar + nperm, as
defined in OCLSetup.
OCLPutSolution
This mandatory function is used to put an evaluated solution
back into OCL’s database. A call to OCLPutSolution is used to communicate the
objective function value that corresponds to the solution returned by
OCLGetSolution.
In some settings, however, the solution returned by a call
to OCLGetSolution may change. In this case, the call to OCLPutSolution should
include not only the objective function value but also the values corresponding
to the modified solution.
The function returns zero upon success or an error code upon
failure.
long OCLPutSolution(long nprob, long nsol, double *objval,
double *sol);
nprob The
problem identifier returned by OCLSetup.
nsol A
solution identifier returned by OCLGetSolution.
objval An array of doubles with the
values of the objective function and the requirements. The array should have a
size of at least nreqs+1 elements, as defined in OCLSetup. The objective
function value should be objval[0] and the ith
requirement should be objval[i]. Note that if no requirements are defined, then
objval can be dimensioned as a simple double variable.
OCLNULL may be used to discard the
solution. However, the first 10
solutions cannot be discarded.
sol An array of doubles with the
values of the decision variables. If the solution is the same as the one
generated the last call to OCLGetSolution, the value OCLNULL may be used.
OCLSugSolution
This function is used to suggest a possible. The suggested
solution is placed at the end of the database (and not into the current
population as with OCLSugPopSolution).
Note that the objective value of a suggested solution is
unknown to the search until the solution is returned for evaluation with a call
to OCLGetSolution.
The function returns zero upon success or an error code upon
failure.
long OCLSugSolution(long nprob, double *sol);
nprob The
problem identifier returned by OCLSetup.
sol An array of doubles with the
suggested value for each of the variables. Indices into the sol array
correspond to the variable index used as input to OCLDefineVar. The array must be
dimensioned such that the variable values can be placed in positions 1 to nvar
+ nperm, as defined in OCLSetup.
Optimization Parameters
OCLSetAutoStop
This function sets the automatic stop option. When automatic stop is ON, the optimization
stops when the value of the objective function stops improving.
An objective function is said to stop improving if the objective
function values differ by less than “p” during “n” iterations. The value of “p” is set by calling
OCLSetObjPrecision. The default value
of “p” is 0.0001 (10-4).
“n” is calculated as a percentage of the total number of
iterations. The default for “n” is
100. If the number of iterations is
modified by calling OCLSetSolutions,
“n” is calculated as 5% of the value set by OCLSetSolutions, but “n” cannot be less than 50.
When the search is automatically terminated, OCLGetSolution
returns OCLErr1100. The default for automatic stop is
OCLOFF. The function returns zero upon
success or an error code upon failure.
long OCLSetAutoStop(long nprob, long pval);
nprob The problem
identifier returned by OCLSetup.
pval OCLON or OCLOFF.
OCLSetObjPrecision
This function sets the precision for the improvements in the
objective function value during the search. The precision is specified as the
amount of difference in the range of the objective value, rather than a
constant. For example, an objective
value that ranges from 1 to 1000 with a precision value of .00001 would
indicate that objective values that differed by 0.1 or less would be considered
the same. The default value is 0.0001
(10-4).
The function returns zero upon success or an error code upon
failure.
long OCLSetObjPrecision(long nprob, double pval);
nprob The problem
identifier returned by OCLSetup.
pval The new
precision value.
OCLSetVarPrecision
This function sets the precision for the values of the
decision variables. If the difference of the values for a variable is less than
the variables precision, the values are considered equal. The precision is
specified as the amount of difference in the range of the variable, rather than
a constant. For example, an objective
value that ranges from 1 to 100 with a precision value of .00001 would indicate
that objective values that differed by 0.01 or less would be considered the
same and therefore only one is recorded in the database. The default value is
0.0001 (10-4).
The function returns zero upon success or an error code upon
failure.
long OCLSetVarPrecision(long nprob, double pval);
nprob The problem
identifier returned by OCLSetup.
pval The new
precision value.
OCLSetDatabaseSize
This function sets the maximum size of the database. The database size determines the number of
solutions stored, which affects the memory used and the potential
solution. The minimum size is
3000. The maximum is dependent on the
user’s system. The default is 10,000.
The function returns zero upon success or an error code upon
failure.
long OCLSetDatabaseSize(long nprob, long value);
nprob The problem
identifier returned by OCLSetup.
size The new
value for the size of the database.
OCLSetCheckDup
This function activates or deactivates the check for
duplicated solutions in the database. The default value for this parameter is
OCLON, which means that OptQuest CL checks for duplicated solutions in the
database.
The function returns zero upon success or an error code upon
failure.
long OCLSetCheckDup(long nprob, long pval);
nprob The
problem identifier returned by OCLSetup.
pval An integer indicating whether
or not to check the database for duplication of solutions. A database of
solutions is maintained during the search with the purpose of avoiding
evaluating a solution more than once. This is particularly helpful when
optimizing computationally expensive objective functions. The value OCLON
activates the checking of the database, while OCLOFF deactivates this checking
procedure.
OCLSetSearchStrategies
This function sets the strategies to be used to within the
search process. The function returns zero upon success or an error code upon
failure.
The following
strategies can be manipulated:
- Aggressive update for the population -
A very aggressive update that keeps the very best solutions in the
current population and that sacrifices search diversity for quality. This
setting is recommended when the search has to be performed over a limited
number of objective function evaluations (e.g., less than 1000 calls to
OCLGetSolution). The default value for this strategy is OCLOFF.
- Boundary search - The boundary
search strategy is a mechanism to direct the search towards the
feasibility boundary defined by the bounds on the decision variables and
the set of linear constraints (if defined in the model). The default value
for this parameter is 0.5, which means that the strategy to drive the
values of the decision variables towards the boundary is used 50% of the
time when new solutions are generated. If good solutions are likely to
fall at or near the feasibility boundary, it is recommended to increase
the value of this parameter. Conversely, if good solutions are suspected
to lie near the middle of the variable range (when no constraints are
defined), it is recommended to decrease the default value for the boundary
strategy.
Crossover combination – The OptQuest Engine uses linear
combinations of two solutions stored in the population to create other solutions
for evaluation. For example if Var1 in solution1 has a value of 3.0 and
Var1 in solution 2 has a value of 5.0, a new solution may set Var1 to 4.0.
When crossover search is activated,
the OptQuest Engine produces solutions by taking some values from one solution
and some values from a second solution, producing a new solution. For example, if a problem has 6 variables,
a new solution may be created where the values of variables 1,2 and 3 are from
solution1 and the values for variables 4,5 and 6 are from solution 2.
The default value for this strategy
is OCLOFF.
- Permutation combination - When
solving a permutation problem, this strategy selects among five methods to
combine permutations. The first
and the second one are based on a voting scheme while the third and the
fourth implement two crossover operators. The first one implements
some random elements while the second is more deterministic and the votes
are weighted according to the quality of the solutions. The third
method implements the partially matched crossover operator and the fourth
biases the combination to favor one of the parents randomly
selected. The fifth one is a mixed method that randomly selects
between the first four on each iteration.
The default method is the fifth one. A method is activated by
setting the pval parameter equal to 1, 2, 3, 4 or 5 for each method
respectively.
- Parallel - In some contexts, like
parallel implementations, the user wants to call OCLGetSolution several
consecutive times and then return the value of these solutions
(OCLPutSolution) instead of alternating the calls to both functions as
usual. OCL supports these
“multiple calls” to OCLGetSolution, but the number of available
consecutive calls is not a fixed value but it depends on the search. If OCLGetSolution returns OCLErr2400 it
means that OCLPutSolution must be called since no more solutions are
available at this moment. We can
select between two strategies by setting the pval value equal to 1 or 2. The first one maximizes the number of
available solutions in consecutive calls.
The second one produces similar outputs for different runs of the
program with variable consecutive calls to OCLGetSolution (like when
running the program with 2 processors and comparing the results with the
solutions obtained with 50 processors).
- Regression
Analysis - The regression analysis strategy uses the solutions in the
database to attempt to match a linear equation to the solutions and then
solve that equation using the MIP solver.
The solution from the regression analysis is then provided as a
solution to be evaluated along with the linear combinations generated by
the OptQuest Engine.
The default value for this strategy
is on.
long OCLSetSearchStrategies(long nprob, char *type, double
pval)
nprob The
problem identifier returned by OCLSetup.
type The
type of strategy to be set:
·
“aggressive”
·
“boundary”
·
“crossover”
·
“permutation”
·
“regression”
pval The value
corresponding to the type of strategy to be set.
If type = “aggressive”
then pval is OCLON or OCLOFF
If type = “boundary”
then pval is a value between zero and 1.
If type = “crossover”
then pval is OCLON or OCLOFF .
If type = “permutation”
then pval is 1, 2 or 3.
If type = “parallel”
then pval is 1 or 2.
If type = “regression” then pval is OCLON or OCLOFF
OCLSetSolutions
This function can be used to set the number of optimization
iterations. The OptQuest Engine will
then create a search strategy that is consistent with the number of iterations
that the optimization is expected to run.
If the number of predicted iterations is small, the OptQuest
Engine will use an aggressive search strategy to exploit the solution space as
well as possible. On the other hand, if the number of predicted iterations is
rather large, the OptQuest Engine will use a less greedy strategy to explore
the search space more thoroughly.
The actual number of iterations however does not have to
match the predicted number, so OCLSetSolutions can actually be used to
influence the search strategy regardless of the number of iterations that are
run.
Another way to affect the search is to utilize the function
OCLSetSearchStrategies.
If OCLSetSolutions is not called, the default value is 2000.
The function returns zero upon success or an error code upon failure.
long OCLSetSolutions(long nprob, long pval);
nprob The
problem identifier returned by OCLSetup.
pval An
integer indicating the number of iterations.
OCLSetTaguchi
This function activates or deactivates the use of Taguchi design
of experiments to generate diverse solutions during the search. When this
strategy is activated, Taguchi arrays are used to generate solutions for
problems with up to 49 variables. The following table shows a Taguchi array
that can be used to generate 9 solutions for a problem with 4 variables, where
the values are 1 for the lower bound, 2 for the midpoint and 3 for the upper
bound.
The function has three possible settings: 0 = Taguchi arrays
are deactivated, 1 = Taguchi arrays are active in a deterministic fashion, and
2 = Taguchi are active in a probabilistic fashion. In the probabilistic
setting, solutions are generated either with values probabilistically near the
bounds or the midpoint as recommended in the Taguchi array. The default value
is zero. The function returns zero upon success or an error code upon failure.
long OCLSetTaguchi(long nprob, long pval);
nprob The
problem identifier returned by OCLSetup.
pval The
value of the parameter (i.e., 0, 1 or 2)
Event Handling
OCLCallback
This function is used to return control to the calling
process during long computation times.
Its purpose is to allow the calling program to respond to external
events (e.g. human interactions in the form of mouse or keyboard input).
The OCLCallback function is called to pass a pointer to a
function to the OptQuest Engine. The
OptQuest Engine will call the function during long computation times.
long OCLCallback(long nprob, void *pCallback);
nprob The
problem identifier returned by OCLSetup.
pCallback A
pointer to a user function.
Information Retrieval
OCLGetVersion
This function returns the current version
number of OCL.
char *OCLGetVersion();
OCLGetErrorString
This function returns a string that explains
the errorcode.
char *OCLGetErrorString(long err);
err Error
code returned by an OCL function.
Mixed Integer Programming
OCLDefineObj
Repeated calls to this function define the coefficients for
each of the variables in the objective function.
long OCLDefineObj(long nprob, long var, double coeffval);
nprob The
problem identifier returned by OCLSetup.
var A variable index. This value
must be between 1 and nvars, as declared in OCLSetup.
coeffval The
value of the coefficient to be applied to the variable at index var.
OCLSolveLP
This function is used to solve a Linear Program.
The function will return 0 for an optimal solution, 1 for a
LP/IP failure, 2 for infeasible solution, 3 for an unbounded optimum, or an OCL
error code. If all possible
enumerations were checked, the function will return –5002.
long OCLSolveLP(long nprob, double *obj, double *sol);
nprob The
problem identifier returned by OCLSetup.
obj A pointer to a double. The result of the linear objective will be
placed in obj.
sol A pointer to an array of
doubles. The values of the variables will be placed in sol[1] to sol[nvars]
where nvars was defined in the call to OCLSetup. The sol array should be
dimensioned such that the variable values can be placed in positions 1 to nvar,
as defined in OCLSetup.
Internal Functions
The following functions documented for historic
reasons. They are intended for internal
use only and should not be called.
OCLInitPop
This function triggers the generation of the initial
population. It must be called before
the search process can be started. (It
should also be called before OCLSugSolution can be used.). The generated solutions are stored in
memory. Note that the quality of the solutions is not known until
OCLGetSolution is called. The function
returns zero upon success or an error code upon failure.
long OCLInitPop(long nprob);
nprob The
problem identifier returned by OCLSetup.
OCLGetPopStats
This function retrieves statistics about the current
population. It computes the mean, std. deviation, minimum and maximum values
for decision variables, constraints and requirements of the solutions in the
current population.
The function returns zero upon success or an error code upon
failure.
long
OCLGetPopStats(long nprob, char *type, long i, double *stat);
nprob The
problem identifier returned by OCLSetup.
type There are three possible types:
·
"VAR" - statistics are computed for a
variable in the solution’s population
·
"CON" - the statistics are computed for left hand
side of a constraint in the solution’s population
·
"REQ" - statistics are computed for a
requirement in the solution’s population
i The index of the variable,
constraint or requirement to be computed if type ="VAR", “CON” or
“REQ” respectively.
stat An array of doubles where the
statistics will be placed. stat[1] is the mean value of variable, constraint or
requirement i over the population. stat[2] is the std. deviation of variable,
constraint or requirement i's values over the population. stat[3] is the
maximum value of variable, constraint or requirement i over the population.
stat[4] is the minimum value of variable, constraint or requirement i over the
population
OCLGenerateAllSolutions
This function generates all the solutions to a pure discrete/permutation
problem, i. e. a problem with discrete and permutation variables only.
This might be advantageous for problems with a small
solution space.
However, this function must be used with care,
since generating all solutions is only practical for problems with a small
number of variables defined in narrow ranges. For example, a problem with 10
binary variables has 1,024 solutions. However, a problem with 10 variables that
can take on integer values from 0 to 3 has more than 1 million solutions. The solutions
generated by this function are placed in OptQuest CL’s memory. The solutions
are then retrieved with a call to OCLGetSolution for evaluation. The OCLGenerateAllSolutions function should be
used instead of OCLInitPop.
The function returns the number of solutions generated upon
success or an error code upon failure.
long OCLGenerateAllSolutions(long nprob);
nprob The
problem identifier returned by OCLSetup.
OCLGetPopSolution
This function retrieves solutions from the current
population. This function is available only after all the solutions in the
current population have been evaluated. Therefore, the pair OCLGetSolution()
and OCLPutSolution() needs to be called at least pval times before attempting
to retrieve a solution from the current population (where pval is the number of
solutions in the population as specified by either a call to OCLSetPopSize() or
the default value). The function uses an array of doubles, where the solution
is placed. Note that the array must have enough space to hold all the
variables, whose index range from 1 to the number of decision variables in the
current problem. The function also requires a solution identifier (i.e., an
integer between 1 and the value of pval) that indicates the position of the
solution within the population.
The function returns zero upon success or an error code upon
failure.
long OCLGetPopSolution(long nprob, long nsol, double
*objVal, double *sol);
nprob The
problem identifier returned by OCLSetup.
nsol An identifier indicating a
solution number within the current population. The identifier must be greater
than zero and less than or equal to the population size.
objVal An array of doubles where the
values of the objective function and the requirements will be placed. The array
should have a size of at least req+1 positions, as defined in OCLSetup. Note
that if no requirements are defined, then objval can be dimensioned as a simple
double variable.
sol A pointer to an array of
doubles where the solution will be placed. The array should be dimensioned such
that the variable values can be placed in positions 1 to nvars, as defined in
OCLSetup.
OCLGetStoredSolution
This function
retrieves solutions from the solutions that OptQuest Engine generates during the
search and that are stored in an internal database.
This can be useful
for statistical observations that the user wants to make about the solutions
generated during the search.
The function is
available only after at least one call to the pair OCLGetSolution() and
OCLPutSolution(). The function uses two arrays of doubles, one for the values
of the decision variables and one for the value of the objective function and
requirements. Note that the solution array must be dimensioned to be able to
hold all the variables, whose index range from 1 to the number of decision
variables in the current problem. Likewise, the objective array must be
dimensioned to hold all requirement values. This function also requires a
solution identifier that indicates the solution number within the database.
Clearly, this identifier must be an integer between 1 and the total number of
evaluated numbers in the database.
The function returns
zero upon success or an error code upon failure.
OCLGetStoredSolution(long nprob, long nsol, double *sol,
double *objval);
nprob The
problem identifier returned by OCLSetup.
nsol The number of the solution
within the current population. The identifier must be greater than zero and
less than or equal to the population size.
sol A pointer to an array of
doubles where the solution will be placed. The array should be dimensioned such
that the variable values can be placed in positions 1 to nvar, as defined in
OCLSetup.
objval An
array of doubles that will contain the values of the objective function and the
requirements. The array should have size of at least req+1 positions, as
defined in OCLSetup.
OCLPutPopSolution
This function is used to put a complete solution (i.e.,
decision variable values and objective and requirement values) into the current
population. This means that the function is used to replace a solution that is
currently in the population with a new solution.
In that way, the user can provide the search with (what he
believes is) a good solution that might be helpful to find other good
solutions.
The solution added must be feasible with respect to the
linear constraints, if any have been defined. This function is available only
after all the solutions in the current population have been evaluated.
Therefore, the pair OCLGetSolution and OCLPutSolution needs to be called at
least pval times before attempting to retrieve a solution from the current
population (where pval is the number of solutions in the population as
specified by either a call to OCLSetPopSize or the default value). The function
uses two arrays of doubles, one holding the variable values and the other
holding the objective function and the requirement values. The function also
requires a solution identifier (i.e., an integer strictly greater than zero)
that indicates the position of the solution that will be replaced in the
population. Therefore, this value cannot be greater than the population size.
The function returns zero upon success or an error code upon failure.
long OCLPutPopSolution(long nprob, long nsol, double
*objval, double *sol);
nprob The
problem identifier returned by OCLSetup.
nsol The number of the solution
within the current population, the should be exchanged. This value must be at
least 1 and no more than the current population size.
objval An array of doubles with the
values of the objective function and the requirements. The array should have a
size of at least nreqs+1 positions, as defined in OCLSetup. The objective
function value should be objval[0] and the ith
requirement should be objval[i]. Note that if no requirements are defined, then
objval can be dimensioned as a simple double variable. OCLNULL may be used to
discard the solution.
sol An array of doubles with the
values of the decision variables. The values should be in positions 1 to nvar
of the array.
OCLSugPopSolution
This function is used to place a suggested solution into the
population of solutions that are used for creating new solutions by generated
structured combinations of these solutions.
In that way the user can “assist” the search with (what he
believes are) good solutions.
The most effective use of this function is to suggest
solutions before the population is initialized by a call to OCLInitPop. Note
that the objective value of a suggested solution is unknown to the search until
it is returned for evaluation with a call to OCLGetSolution.
The function returns zero upon success or an error code upon
failure.
long OCLSugPopSolution(long nprob, double *sol);
nprob The
problem identifier returned by OCLSetup.
sol A pointer to an array of
doubles with the variable values corresponding to the suggested solution.
Variable values should be in sol[1] up to sol[nvar], where nvar must be the
value indicating the number of decision variables with which the problem was set
up (the values of nvar in OCLSetup).
OCLSetFileSolutions
This function activates a log file that stores solutions
generated during the search. It is typically called before the search starts to
be able to capture either all or only the best solutions found during the
search. Note that this log file could become very large, if the search is run
for many iterations and the user decides to store all solutions.
The function returns zero upon success or an error code upon
failure.
long OCLSetFileSolutions(long nprob, char *name, char
*mode);
nprob The
problem identifier returned by OCLSetup.
name A
file name. Solutions are written to
this file.
mode There are two possible modes:
“ALL” and “BEST”. If “ALL” is used, then all the solutions generated during the
search are stored in the file. If “BEST” is used, only those solutions that
improve the current best are stored in the file.
OCLSetNNFilter
This function activates a Neural Net for the solutions
returned by OCLGetSolution. The Neural
Net is useful in reducing the number of evaluations needed and should be used
only when evaluations take a significantly long time. The training level can be set from 0 to 5, with 0 being the
lowest level of training. The default
training level is 0.
The function returns zero upon success or an error code upon
failure.
long OCLSetNNFilter(long nprob, long popt, long plvl);
nprob The
problem identifier returned by OCLSetup.
popt The
desired setting for the Neural Net filter:
OCLON or OCLOFF.
plvl The training level for the
Neural Net (or OCLGetNull(nprob) for the default setting.
OCLSetPopSize
This function sets the maximum size of the population. (The
actual population size might vary during the search process, though it will not
exceed the value set with this function.)
OCLSetPopSize must be used before OCLInitPop is called. If
OCLSetPopSize is not called at all, the value is set to the default value of
15.
The function returns zero upon success or an error code upon
failure.
long OCLSetPopSize(long nprob, long pval);
nprob The
problem identifier returned by OCLSetup.
pval An
integer indicating the maximum population size.
OCLSetRandomSeed
This function sets the seed for the random number generator.
The default value is 13171191. This function can be called any time before or
during the search.
The function returns zero upon success or an error code upon
failure.
If you want to repeat an optimization having it return the
same solutions in the same order as a previous run, then set the seed to the
same value each time the optimization is run.
long OCLSetRandomSeed(long nprob, long pval);
nprob The
problem identifier returned by OCLSetup.
pval The
value of the seed for the random number generator.
OCLSetTaguchi
This function activates or deactivates the use of Taguchi
design of experiments to generate diverse solutions during the search. When
this strategy is activated, Taguchi arrays are used to generate solutions for
problems with up to 49 variables. The following table shows a Taguchi array
that can be used to generate 9 solutions for a problem with 4 variables, where
the values are 1 for the lower bound, 2 for the midpoint and 3 for the upper
bound.
The function has three possible settings: 0 = Taguchi arrays
are deactivated, 1 = Taguchi arrays are active in a deterministic fashion, and
2 = Taguchi are active in a probabilistic fashion. In the probabilistic
setting, solutions are generated either with values probabilistically near the
bounds or the midpoint as recommended in the Taguchi array. The default value
is zero. The function returns zero upon success or an error code upon failure.
long OCLSetTaguchi(long nprob, long pval);
nprob The
problem identifier returned by OCLSetup.
pval The
value of the parameter (i.e., 0, 1 or 2)
Neural Network
OCLNNActivation
This function sets the activation functions for the hidden
neurons. The function has two possible settings: 1 = activation function is
defined as sigmoid, 2 =activation function is defined as hyperbolic tangent.
The default value is 1.
(1) 
(2)
The function returns zero upon success or an error code upon
failure
long OCLNNActivation(long nnet,long pval);
nnet An identifier for an OCL
Neural Network data structure that contains the network data. This is the
identifier returned by OCLNNSetup.
pval The
value of the parameter (i.e., 0 or 1)
OCLNNCallback
This function is used to return control to the calling
process during long computation times.
Its purpose is to allow the calling program to respond to external
events (e.g. human interactions in the form of mouse or keyboard input).
See OCLCallback for more information.
long OCLNNCallback(long nprob, void *pCallback);
nprob The
problem identifier returned by OCLSetup.
pCallback A
pointer to a user function.
OCLNNGoodBye
This function deletes a neural net from OptQuest CL’s
memory. The net is identified using the identifier returned by OCLNNSetup.
The function returns zero upon success or an error code upon
failure.
long OCLNNGoodBye(long nnet);
nnet An identifier for an OptQuest
CL neural net data structure that contains the problem data. This is the
identifier returned by OCLNNSetup.
OCLNNPrediction
This function retrieves the output of the net for a given
input. The function uses an array of doubles, where the user places the input
and returns the output in a pointer to a double. This function is available
only after training the net with OCLNNTrain. If the difference between the net
output and the function evaluation under estimation is relatively great, more
training can be performed by simply calling the OCLNNTrain function more times.
Moreover, more data can be added to the train data set before this new train.
The function returns zero upon success or an error code upon
failure.
long OCLNNPrediction(long nnet, double *input, double
*output);
nnet An identifier for an OCL
neural net data structure that contains the network data. This is the
identifier returned by OCLNNSetup.
input An
array of doubles where the input is given.
output A
pointer to a double where the output will be placed.
OCLNNSearchLevel
This function sets the intensification in the search when
training the net. The function has six possible settings: 0,1,..,5. The higher
the value, the better the results when using the net but also the longer the
training process. The default value is 0.
The function returns zero upon success or an error code upon
failure.
long OCLNNSearchLevel(long nnet, long pval);
nnet An identifier for an OCL
neural net data structure that contains the network data. This is the
identifier returned by OCLNNSetup.
pval The
value of the parameter (i.e., 0, 1,2,3,4 or 5).
OCLNNSetup
This function sets up the neural network. The function
triggers the allocation of memory for the nodes and the arcs in the problem
net. It specifies the number of nodes in the input layer, the number of nodes
in the hidden layer and the maximum size of the train data set.
The function returns value strictly greater than zero upon
success or an error code upon failure.
long OCLNNSetup(long nin, long nhidden, long ntrain);
nin An integer indicating the
number of nodes in the input layer (i.e. the number of variables of the
function to be estimated).
nhidden An
integer indicating the number of nodes in the hidden layer.
ntrain An
integer indicating the maximum number of points in the train data set.
OCLNNTrain
This function trains the neural network with the points in
the train data set. This function is available when function OCLNNTrainData
returns 1. The function returns in a pointer to a double the current error over
this set (mean squared errors). The user can call repeatedly to this function
in order to reduce the computed error. The function returns zero upon success
or an error code upon failure.
long OCLNNTrain(long nnet, double *error);
nnet An identifier for an OCL
neural net data structure that contains the network data. This is the
identifier returned by OCLNNSetup.
error A
pointer to a double where the current error will be placed.
OCLNNTrainData
This function is used to put a point with its evaluation
into the train data set. A maximum number of n trains points can be added to
the train data set. This value is user defined when the net is set up
(OCLNNSetup). If more points are added beyond this value, then the first ones
are deleted. The function returns 1 when a minimum number of points has been
added (by default 10). Then the net can be trained.
It should be noted that if a great number of points are
included in the train set, the trained net will be very robust in terms of its
predictions but it will take a long time to train it.
long OCLNNTrainData(long nnet, double *data, double value);
nnet An identifier for an OCL
neural net data structure that contains the network data. This is the
identifier returned by OCLNNSetup.
data An
array of doubles with the point data.
value A
double with the point’s value.