OptQuest 10.2 Optimization API

The OptQuest 10 API is one declarative interface with bindings for Java, C#, C++, C and Python. The same model definition and the same calls work in all five languages. A COM interface gives Automation clients (VBA, VBScript, VB6 and Excel) the C# calls. In Java, the OptQuest 9 API is still supported, and OptTek has no plan to deprecate it. In C#, C++, C and Python, the OptQuest 10 API is the only interface to the OptQuest Engine.

Overview

What Is Optimization?

Optimization finds the values of decision variables that give the best result for an objective while they satisfy the constraints. The OptQuest® Engine, developed by OptTek Systems, Inc., answers questions such as these:

• Resource allocation: How should a budget be split across uses to maximize return when product demand, machine reliability and raw-material supply are uncertain?
• Production scheduling: Which machine configuration is most efficient when demand and operating conditions change?
• Material flow: Where should raw materials be placed, and in which order released, to minimize waiting time?
• Workforce planning: How should staff be allocated to reduce lead time and labor cost?
• Portfolio optimization: How should an investment portfolio be allocated to maximize return?

For most problems, it is not practical to evaluate every combination of values. The OptQuest Engine chooses which combinations to evaluate next based on the results of all of the previously evaluated solutions. ### OptQuest Engine

Search Algorithm and Metaheuristics

The OptQuest Engine is a black-box global optimizer. It makes no assumption about the shape of the objective or the constraints. It needs no formula that gives the outputs from the inputs, and no derivatives, only the values that your evaluation returns. The engine uses metaheuristics: it records how earlier trial solutions performed, and it combines good trial solutions to make new ones. For a simulation that gives a different result each time it runs, the engine can evaluate each trial solution several times and combine the results (see § Concepts › Stochastic Simulation Optimization).

Algorithm Composition

The engine combines several known techniques along with proprietary custom approaches for various problem types:

• Linear and mixed-integer programming: when the objective and the constraints are linear, the engine can solve the problem exactly.
• Design of experiments: the engine spreads the first trial solutions over the ranges of the variables.
• Scatter search: the engine keeps a reference set of the best trial solutions and makes new trial solutions by combining members of the set.
• Local search: a Nelder-Mead search for continuous variables, and moves of one step for discrete variables.
• Enumeration: when the variables have few enough combinations, the engine evaluates all of them.
• A Kriging metamodel: with two or more variables, the engine fits an approximation to the trial solutions evaluated so far and uses it to propose new ones.

Concepts

This chapter introduces the parts of an OptQuest model and the loop the engine uses to evaluate solutions. Read it for orientation. The signature of every function mentioned here is in § API Documentation.

Model Components

In the OptQuest Engine, a model is a structured description of an optimization problem. It has one or more decision variables, one or more objectives and, optionally, one or more constraints. With a single objective, OptQuest refines a single best solution that maximizes or minimizes it. With several objectives, OptQuest builds a Pareto frontier: the set of solutions that represent the best trade-offs among the objectives. See § Overview › OptQuest Engine for a summary of the search algorithms.

Names

Every model component (variable, output, expression, objective, constraint, group and sample metric) has a name. These rules apply:

• Names are matched without regard to case. Flow and flow are the same name, in the API and in expressions. So a model cannot have both Flow and flow: the second Add call fails because the name already exists. The name lists (GetInputNames and GetOutputNames) report each name as you wrote it when you added it.
• A name must be unique across the whole model.
• A variable name must not be the name of a function or a constant of the expression language, such as rate, max, pi or e (see § Reference › Functions and Constants Available In Expressions). In Java the Add call throws COptQuestException with the message “The variable name is a reserved function name.” In the other languages the Add call succeeds, and the model fails when it initializes, with the same message.
• A name must not be empty, and it must not contain whitespace or semicolons.
• A variable name must not start with a digit. Objective, constraint, group and sample-metric names may.
• Use ASCII characters only. The native clients (C, C++, C#, COM and every binding built on them) exchange names with the engine as single-byte text, so a non-ASCII name is mangled.
• The element names supplied to a composite variable (permutation members, mixture components, sequence components, choices, DAG, tree and path nodes, topological sequence tasks, policy sequence items and features) follow the same rules and must not contain commas. Several model-definition statements separate their elements with a comma, so a comma inside an element name splits it.

The element names that the engine generates itself can contain commas (m@1,2). You read those back from the name lists. The members of a selection variable, an exchangeable group, a fix group and a float group are names of variables that are already in the model, so a member can be a generated element name with commas, such as m@1,2 or n@1,2,3.

Names in expressions. An expression in an expression variable, an objective, a constraint or a sample metric refers to a variable by a name that GetInputNames or GetOutputNames returns. For a container or special purpose variable, that is an element name, such as v@2, dir@theta or pol@i1, and never the base name (v, dir, pol). The base name has no value of its own. A model with an expression that names a base name, such as pol <= 7, fails when it initializes, and the error gives the reason “The name is the base name of a container or manifold variable. Use its element names, such as name@1.” and the base name. The engine messages call a special purpose variable a manifold variable. The Notes of each type list its element names. Write an element name that contains a comma in brackets, for example [m@1,2].

Decision Variables

Decision variables are the parameters the optimizer is allowed to vary. The API groups them in these families. Each family is documented in § API Documentation › Decision Variables:

• Standard: continuous, integer, discrete, binary, design (deprecated), enumeration, tuple and geolocation.
• Container: vectors, matrices and arbitrary-dimensional (ND) arrays of continuous, integer, discrete or binary elements.
• Permutation (deprecated): an ordering of named elements. The engine creates one integer position variable per element. Use a sequence variable instead.
• Special purpose: variables whose values must stay inside a structured set, such as an angle on an arc, a ranking of items or a matrix of limited rank. In every solution that the engine generates, the values are inside the set. The combinatorial family has mixtures (simplex), sequences, multi-stage sequences, policy sequences, choices, multi-choices, assignments, item and budgeted selections, partitions, DAGs, trees, paths and topological sequences. The geometric family has angles, spherical angles, regions and spherical regions. The smooth family has low-rank matrices, time-series vectors, and B-spline, Catmull-Rom spline and Fourier representations of vectors and matrices, each with or without a baseline correction.
• Random: random draws from a named probability distribution (Beta, Cauchy, Chi-Square, Exponential, Gamma, Log-Normal, Normal, Pareto, Poisson, Power, Spherical Elevation, Student’s t, Uniform and Weibull). The engine draws a new value at the start of every replication.

Restrictions and groupings that apply to variables after they exist (exclusive ranges, selection gates, exchangeable groups and fix/float groups) are documented in § API Documentation › Variable Modifiers.

Output Variables

Output variables hold results that the simulation (or an external computation) must supply for each trial solution. OptQuest does not assign values to them. Use an output variable whenever an objective or constraint depends on a quantity that cannot be written as a closed-form expression of the input variables. If the evaluator does not call SetValue for an output before it submits the solution, the output stays NaN. For the effect on the objectives and constraints, see § API Documentation › Output Variables. The API supports scalar outputs, output vectors, output matrices and arbitrary-dimensional output ND variables.

Expression Variables

Expression variables are derived values. The optimizer does not choose them and the simulation does not set them. Each expression variable has a string expression, in the same language as objectives and constraints, that the engine recomputes after every solution evaluation. An expression variable can reference input, output and other expression variables. Objectives, constraints, sample metrics and further expression variables can reference it in turn.

Objectives

An objective is an expression over decision variables and output variables that measures a goal. Each objective has a direction:

• Maximize: the engine seeks the highest value of the expression (for example, profit).
• Minimize: the engine seeks the lowest value (for example, cost).

For example, an objective can be maximize 2*VariableA + 3*VariableB, where VariableA and VariableB are input or output variables. With several objectives, OptQuest finds the set of non-dominated solutions: the frontier of the trade-offs among the objectives.

For stochastic models (with replications), SetObjectiveStatistic selects which statistic of the per-replication objective values (mean, median, percentile, standard deviation, variance, coefficient of variation, min, max or sum) is the value that the optimizer compares, and SetObjectiveConfidence lets the engine stop replicating early once a configured confidence interval is reached. See § API Documentation › Objectives.

Constraints

A constraint is an expression that limits the feasible region. It can reference variables, objectives or both. OptQuest supports:

• Linear constraints, such as a*VariableA + b*VariableB <= c, where the coefficients and the bound are constants.
• Non-linear constraints, such as pow(VariableA, 2) + VariableB <= 100. See § Reference › Functions and Constants Available In Expressions for the operators and functions.

The engine enforces a constraint at one of two times, depending on what the constraint references:

• A constraint that references only input (decision) variables is enforced before the evaluator runs. The engine makes sure that the evaluator receives only input values that satisfy these constraints, so the simulator never has to handle or reject an infeasible input combination. If no input values can satisfy these constraints, the run ends with the termination reason Infeasible (12).
• A constraint that references an output variable (directly, or through an expression variable that depends on an output) cannot be checked until the simulation has run. The evaluator always runs. If the outputs violate the constraint, the engine records the solution and marks it infeasible. The engine still learns from these solutions and steers the search away from the infeasible region.

A constraint over the variable names of a special purpose variable, or over a random variable, is also checked after evaluation. The element names of a container variable, and the names of an item selection or a budgeted selection variable, are ordinary inputs, so a constraint over them is enforced before evaluation. See § API Documentation › Decision Variables › Special Purpose Variables: Common Behavior.

The engine has no strict inequality: it reads < as <= and > as >=. It also accepts a violation of a constant bound up to a small tolerance, 1e-5 for each variable in a linear constraint over inputs. See § API Documentation › Constraints › Add Constraint.

The Optimization Loop

OptQuest is built for black-box simulation optimization, where the objective depends on the outputs of a simulation. The objective can be non-convex, discontinuous or non-differentiable. The engine runs this loop:

1. Generate: build a trial solution by assigning a value to every input variable within its domain, subject to the constraints.
2. Evaluate: compute the output values from the trial solution’s inputs, with a simulation, a complex function or an analytical expression.
3. Learn: assess the evaluated solution to learn about the objective and the solution space.
4. Refine: use what has been learned to generate the next trial solution.

The four workflows that run this loop (managed, concurrent, asynchronous managed and manual) are documented in § Optimization Workflows.

Model Immutability

An OptQuestModel has two stages: definition and execution. During definition, the client adds decision variables, output variables, expression variables, objectives, constraints and sample metrics, and configures their statistic and confidence parameters. Execution begins the first time the engine builds its internal representation of the model, which is the first call to any of these methods:

• Optimize(...) or Sample(...), in every overload (managed, concurrent or asynchronous).
• CreateSolution(), GetEmptySolution() or CopySolution(src), used by manual workflows.
• AddAllSolutions(srcModel), used to import evaluated solutions from another model.
• The solution methods Submit(), Reject(), Predict(), Evaluate(), Update(), AddSuggested(), AddEvaluated() and AddRequired(), which all need an initialized model.

You can also start execution explicitly with Initialize(). This is useful to find out whether the model is well formed before any solution is generated.

The first of these calls builds the engine’s internal data structures from the declared components and makes the model immutable. From then on, every configuration method is rejected, including the ones that do not add components. That includes adding decision, output and expression variables, objectives, constraints and sample metrics; the statistic settings (SetObjectiveStatistic, SetOutputStatistic); and the run-control settings SetReplications, SetSerialReplications, SetStopCycles, SetStopImprovement, SetStopTime, StopOnSuccessfulMILP, SuggestedSolutionsOnly, SetParallelHint, SetRandomSeed, SetSampleMethod, SetSampleVariogram and the SetSampleRDS* family. Such a call fails in the language’s standard way (see § Concepts › Error Handling).

These operations stay valid after initialization:

• Calling Optimize(...) or Sample(...) again. Successive runs accumulate solutions in the same model.
• Reading solutions and metadata: GetBestSolutions, GetAllSolutions, GetNumberOfCompletedIterations, GetMaxReplications, GetTerminationReason, Describe and GetLastError.
• Controlling a running asynchronous optimization with Interrupt() and Continue() on the model. In Java, C#, C++ and C, the channel object has its own Interrupt(), and a Continue() that reports whether the interrupt signal was raised rather than resuming the run. See § API Documentation › Running Managed Optimization and Sampling › Channel Continue, Interrupt and Get Number Of Parallel.
• Importing solutions from another model with AddAllSolutions(otherModel), which combines the results of independent runs without re-evaluation.

Immutability is a one-way transition. No call returns an initialized model to the definition stage. To change the structure of a model after a run, create a new OptQuestModel, define it again, and use AddAllSolutions to import the old solutions into it if you want them.

Stochastic Simulation Optimization

OptQuest supports stochastic simulations, where identical inputs can produce different outputs. Each trial solution (one combination of decision-variable values) is evaluated N independent times, called N replications, and the engine aggregates the per-replication results into one score that it uses to guide the search. The evaluator and the monitor are both called once per replication. For a trial with twenty replications, both callbacks run twenty times before the engine moves to the next trial. Across those twenty calls the decision-variable values are identical. Only random variables (declared with Add*RandomVariable) and any randomness inside the simulator itself change between replications.

There are two ways to configure the number of replications:

• Fixed replications: the engine runs the same number of replications for every trial solution. Configure it with SetReplications(reps). C has no single-argument form; pass the same value for min and max.
• Variable replications with convergence monitoring: the engine runs at least min replications, then stops when the objective meets its confidence interval or when it reaches max. Configure it with SetReplications(min, max) and SetObjectiveConfidence. Without SetObjectiveConfidence, the engine runs max replications for every trial solution. SetObjectiveStatistic and SetOutputStatistic set how the engine combines the replications into one value. They do not stop the replications early.

min must be at least 1 and max at least min. A max of 1 runs without replications. A confidence interval needs two observations, so a min of 1 with a larger max runs at least two replications per trial.

See § API Documentation › Optimization Configuration and § API Documentation › Objectives for the signatures.

Error Handling

Each language reports errors in its own way:

• Java: throws COptQuestException. The exception message and call stack contain the full error description.
• C#, C++, Python: the failing function returns false. Call GetLastError() on the model (get_last_error() in Python) for the same description that Java would place in its exception. Python adds one case of its own: an argument the binding itself refuses before the call, such as a ragged list of rows, a mixture bounds list of the wrong length or a path of fewer than two nodes, raises ValueError with the method name. A refusal by the client or by the engine still returns False.
• C: the failing function returns 0. A non-zero return means success. Call OQGetLastError(model) for the description.

For the solution-level operations (Submit, Reject, Predict, Evaluate, Update, AddSuggested, AddEvaluated, AddRequired), read the error from the solution rather than the model: Java throws the same exception type; C#, C++ and Python call GetLastError() / get_last_error() on the OptQuestSolution; C calls OQGetLastSolutionError(sol). See § API Documentation › Utility Functions for the signatures.

GetLastError() / OQGetLastError() is sticky: a successful call does not clear it, so the text can be left over from an earlier, unrelated failure. Use the return code to decide whether a call failed, and read the error text only after a return code that is a failure value.

The description that GetLastError() / OQGetLastError() returns is a pointer into a per-thread buffer. It stays valid until the next GetLastError() call on the same thread. Another thread that records an error (a worker under a parallel Optimize, for instance) cannot invalidate a pointer this thread holds. Copy the string if it must outlive the next call.

No exception and no fault crosses the C boundary. When an OQ* function gets a NULL handle or a NULL array or string argument, or when an exception is raised inside the library, the function returns the call’s own failure value: 0 for the bool-valued calls, -1 for the int-valued counts and reasons, NaN for a value, "" for a borrowed string, and NULL for a handle or an allocated reply. Where a handle is available, the reason is recorded against it. A model is still usable after a call is refused this way. Array arguments must not be NULL unless their count is zero.

Submit and Reject do not follow the return convention above. In Java, C#, C++ and C they return the engine’s running count of completed iterations on success and exactly -1 on failure. The count is 0 for a successful call while no iteration has completed yet (the first replication of a trial under replications, for example), so 0 is a success. Test these two functions with >= 0 (or != -1), never with != 0 or > 0. Predict, Evaluate, Update, AddSuggested, AddEvaluated and AddRequired follow the ordinary convention. Python’s submit() and reject() apply the >= 0 test internally and return False only on failure.

Common Errors

These are the errors and the silent results that new users see most often. The quoted text is what GetLastError() returns in C#, C++, C and Python. In Java, an engine error throws COptQuestException with the same description, and a call that the client refuses returns false with no message. A message from the engine contains the description shown, followed by a call stack.

Your First Optimization

This section gives a complete program and its output. The program finds the values of x and y that give the smallest cost. The engine asks for one set of values of x and y at a time. That set of values is a trial solution. For each trial solution, the engine calls the evaluator, which stands in for your simulation. The evaluator reads the inputs, computes the output and writes the output back. One iteration is one trial solution with all its replications (see § Stochastic Simulation Optimization). This model has no replications, so each iteration is one call of the evaluator.

In Java, GetValue and SetValue declare throws COptQuestException, so the evaluator catches that exception.

import com.opttek.optquest.COptQuestException;
import com.opttek.optquest.IOptQuestEvaluator;
import com.opttek.optquest.OptQuestModel;
import com.opttek.optquest.OptQuestSolution;
import java.util.List;

public class FirstOptimization {
    public static void main(String[] args) throws COptQuestException {
        OptQuestModel model = new OptQuestModel();
        // model.SetLicense("your-license-key");   // without a license, a run stops after 50 iterations
        model.AddContinuousVariable("x", -10, 10);    // decision variables and their bounds
        model.AddContinuousVariable("y", -10, 10);
        model.AddOutputVariable("cost");              // a result that the evaluator writes
        model.AddMinimizeObjective("obj", "cost");    // what "best" means

        IOptQuestEvaluator evaluator = sol -> {
            try {
                double x = sol.GetValue("x");
                double y = sol.GetValue("y");
                double cost = (x - 3.0) * (x - 3.0) + (y + 1.0) * (y + 1.0);   // replace with your simulation
                sol.SetValue("cost", cost);
                return true;                          // true: use this result
            } catch (COptQuestException e) {
                return false;                         // false: reject this trial solution
            }
        };

        model.Optimize(40, evaluator);                // run 40 iterations

        List<OptQuestSolution> best = model.GetBestSolutions();
        if (!best.isEmpty()) {
            OptQuestSolution b = best.get(0);
            System.out.println("x = " + b.GetValue("x") + ", y = " + b.GetValue("y")
                    + ", cost = " + b.GetValue("obj") + ", feasible = " + b.IsFeasible());
        }
        System.out.println("iterations = " + model.GetNumberOfCompletedIterations()
                + ", termination reason = " + model.GetTerminationReason());
    }
}

The same program in Python:

import optquest

def evaluate(sol):
    x = sol.get_value("x")
    y = sol.get_value("y")
    cost = (x - 3.0) ** 2 + (y + 1.0) ** 2      # replace with your simulation
    sol.set_value("cost", cost)
    return True                                 # True: use this result

model = optquest.OptQuestModel()
# model.set_license("your-license-key")         # without a license, a run stops after 50 iterations
model.add_continuous_variable("x", -10, 10)     # decision variables and their bounds
model.add_continuous_variable("y", -10, 10)
model.add_output_variable("cost")               # a result that evaluate() writes
model.add_minimize_objective("obj", "cost")     # what "best" means

model.optimize(40, evaluate)                    # run 40 iterations

best = model.get_best_solutions()
if best:
    b = best[0]
    print(f"x = {b.get_value('x')}, y = {b.get_value('y')}, "
          f"cost = {b.get_value('obj')}, feasible = {b.is_feasible()}")
print(f"iterations = {model.get_number_of_completed_iterations()}, "
      f"termination reason = {model.get_termination_reason()}")

The Java program prints:

x = 2.9083081205692034, y = -0.7155144834659386, cost = 0.08933940987120347, feasible = true
iterations = 40, termination reason = 6

The Python program prints the same values, with True in place of true. The engine uses the same random seed each time, so each run of the program gives the same result (see § Set Random Seed).

The minimum is at x = 3 and y = -1, where the cost is 0. Termination reason 6 is Max Iterations: the run completed the 40 iterations that the program asked for. More iterations give a result closer to the minimum. With a license set, the same program gave these best costs:

Without a license, the model runs in demo mode, and a run stops after 50 iterations (see § Set License).

To adapt the program to your problem:

1. Add one decision variable for each quantity that you control. For a comparison of the variable types, see § Choosing a Variable Type.
2. Add one output variable for each result of your simulation that an objective or a constraint uses.
3. Add the objective, and add the constraints if you have them.
4. In the evaluator, call your simulation and write every output variable with SetValue. If the simulation fails, return false to reject the trial solution.
5. Set the number of iterations, run the optimization, and read the best solution.

The full order of the calls is at the start of § API Documentation. The other ways to run the loop are in § Optimization Workflows.

Optimization Workflows

OptQuest offers four workflows for driving the optimization loop: a managed workflow, in which the engine owns the loop; a concurrent variant, in which the engine spreads evaluation across threads; an asynchronous variant, in which the host application stays responsive during a long run; and a manual workflow, in which the client performs every step itself.

The code examples below are in Java. The OptQuest 10 API is the same in all five languages: C#, C++, C and Python use their own syntax with otherwise identical signatures. The COM interface has the C# calls, with the differences listed in § Reference › Linking OptQuest To Your Project › COM. The signature of every workflow is in § API Documentation › Running Managed Optimization and Sampling and § API Documentation › Manual Optimization.

Managed Optimization

In managed optimization the engine runs the optimization loop.

Simple Optimization

When the objectives and constraints are direct functions of the input variables (no external simulation), OptQuest runs the loop with no evaluation callback. The client specifies only the number of iterations.

OptQuestModel model = new OptQuestModel();

// Define input variables, objectives, and constraints
// ...

// Perform 100 iterations of the optimization loop
model.Optimize(100);

Simulation-Based Optimization

When the outputs come from a simulation, the client supplies a callback that evaluates each solution. OptQuest calls it once for each replication of each trial solution.

OptQuestModel model = new OptQuestModel();

// Define input variables, objectives, and constraints
// ...

// Perform 100 iterations, invoking customEvaluation for each solution
model.Optimize(100, customEvaluation);

Concurrent Optimization

For expensive evaluations, OptQuest evaluates several solutions in parallel. The client specifies the number of threads. OptQuest creates the solutions, dispatches them across the threads and synchronizes the generate and learn steps.

OptQuestModel model = new OptQuestModel();

// Define input variables, objectives, and constraints
// ...

// Perform 100 iterations with 5 concurrent threads, invoking customEvaluation
model.Optimize(5, 100, customEvaluation);

Asynchronous Managed Optimization

For a long run, the client starts the optimization on a background thread and keeps the main thread responsive. The main thread can interrupt the run through a channel.

OptQuestModel model = new OptQuestModel();

// Define input variables, objectives, and constraints
// ...

// Create a channel for 5 concurrent optimizations
OptQuestModelChannel channel = model.CreateAsyncChannel(5);

// Start asynchronous optimization in a background thread
Thread background = new Thread(() -> {
    try {
        // Blocks until 100 solutions are evaluated or interrupted
        model.Optimize(channel, 100, customEvaluation);
    } catch (COptQuestException e) {
        e.printStackTrace();
    }
});
background.start();

// Interrupt optimization in response to a user event
channel.Interrupt();

// Wait for the optimization to terminate gracefully
background.join();

Python has no channel object. Start model.optimize(...) on a background thread, pass npar to it directly, and call model.interrupt() on the model from the main thread. model.continue_opt() clears the interrupt so that a later optimize() can run.

Manual Optimization

For fine-grained control, the client performs each step of the loop itself. Use it for HPC, distributed and other custom concurrent setups, in which the client requests each next solution, then manages evaluation and submission.

OptQuestModel model = new OptQuestModel();
model.AddContinuousVariable("x", 0, 10);
model.AddOutputVariable("y");
model.AddMinimizeObjective("obj", "y");

for (int i = 0; i < 100; i++) {
    // Ask the engine for the next trial solution
    OptQuestSolution solution = model.CreateSolution();
    if (!solution.IsValid()) {
        break;   // the run has ended; read GetTerminationReason() for the reason
    }

    // Read the inputs, compute the outputs and write them back by name
    double x = solution.GetValue("x");
    double y = runSimulation(x);   // your code
    solution.SetValue("y", y);

    // Give the result to the engine: -1 is a failure, 0 or more is a success
    if (solution.Submit() < 0) {
        break;
    }
}

List<OptQuestSolution> best = model.GetBestSolutions();
if (!best.isEmpty()) {
    System.out.println("x = " + best.get(0).GetValue("x") + ", y = " + best.get(0).GetValue("y"));
}

With runSimulation(x) equal to (x - 2) * (x - 2) and no license, the program prints x = 2.000606391779585, y = 3.6771099034838766E-7. In demo mode, the 51st CreateSolution returns an invalid solution with the termination reason Max Demo Iterations (14), so the loop ends after 50 passes.

Without replications, each pass of the loop evaluates one trial solution. With replications, each pass evaluates one replication. In Java, CreateSolution and Submit throw COptQuestException when the engine reports an error. In C#, C++ and Python, call GetLastError() on the solution after Submit reports a failure.

Adaptive Sampling

Adaptive Sampling, introduced in OptQuest 10, is an alternative to optimization for exploring a design space. Optimization seeks one best point, a minimum or a maximum. Adaptive Sampling builds an accurate picture of the response surface across the whole domain with as few evaluations as possible. Use it when the goal is to understand the behavior of the domain: trends, boundaries and regions of interest, rather than a single optimum.

The sampling engine works like the optimization engine. It generates trial solutions, evaluates them and uses the results to guide the next choice. The difference is the goal. Adaptive Sampling monitors a user-defined metric, which has a value and an uncertainty (error). The engine builds an internal model of the metric across the domain, predicts the response in unexplored areas and selects the next solution where it expects to learn the most. The engine refines the model with each evaluated solution.

Sampling Loop

The Adaptive Sampling loop has five steps:

1. Generate: build a trial solution by assigning a value to every input variable within its domain.
2. Evaluate: compute the output values from the trial solution’s inputs, with a simulation, a complex function or an analytical expression.
3. Model: update the internal model of the response surface from all evaluated solutions.
4. Select: find the most informative region of the domain under the current model.
5. Refine: generate the next trial solution in that region.

Sampling Strategies

Each strategy defines what “informative” means. Select one by passing its flag to SetSampleMethod (see § API Documentation › Adaptive Sampling Configuration). The constants below are the C names. The constants for the other languages are listed with SetSampleMethod.

• Uniform Sampling (OQSampleMethodUniform): the simplest and fastest strategy. The engine generates solutions that cover the domain evenly and increases the sample density until the run ends. It does not look at the metric, so it suits an initial exploration of the domain.
• Variance-Based Sampling (OQSampleMethodVariance): for stochastic simulations. The engine uses both the response and its error, accounts for the correlation between solutions, and samples next where the uncertainty is highest (the least-known area). This reduces the global uncertainty of the response fastest.
• Boundary-Finding Sampling (OQSampleMethodZero): the engine samples where the metric is predicted to cross zero. To find a different contour, subtract the wanted value from the metric expression. For example, to map radio signal strength in a city, use a metric of signal - 0.5. The engine then samples densely along the contour where signal = 0.5, which maps the transition boundary.
• Gradient-Based Sampling (OQSampleMethodGradient): the engine samples where the response changes fastest (the largest gradient). Use it to find the dynamic parts of the domain.
• Minimum Response Sampling (OQSampleMethodMin): like optimization, but with a sampling goal. The engine samples densely where the response is small, so the low-response region is characterized in detail without a search for the exact minimum.
• Maximum Response Sampling (OQSampleMethodMax): the opposite of minimum response sampling. The engine samples densely where the response is large.
• Response Distribution Sampling (OQSampleMethodRDS): the engine tracks the probability density of the responses and compares it to a wanted distribution. The engine puts new samples where it predicts that they bring the measured density closer to the wanted one. A common use is to produce balanced training data for a machine-learning model. See § Reference › Probability Distributions for the algorithm and the supported distributions.

The flags above can be combined with the OQSampleMethodStochastic, OQSampleMethodDynamic and OQSampleMethodAsync modifiers. See § Set Sampling Method for the full combination table.

Applications

Adaptive Sampling suits applications that need a picture of the whole domain, such as:

• Characterizing trade-offs in multi-variable systems.
• Mapping boundaries or transition zones.
• Exploring stochastic or noisy simulations to quantify uncertainty.
• Finding regions of rapid change or extreme response for further analysis.
• Creating training data with a wanted probability distribution.

API Documentation

This chapter documents every function of the OptQuest 10 API, with its signature in Java, C#, C++, C and Python. A COM interface for Automation clients (VBA, VBScript, VB6, Excel) is the COM form of the C# interface; see § Reference › Linking OptQuest To Your Project › COM for its naming and marshalling differences. Unless an entry says otherwise, the Java, C# and C++ implementations behave identically. In C the caller frees some resources by hand, and each entry that needs it says so. Any language that can call C functions can use the C interface.

To define a model, call the functions in this order:

1. Create the model: create an OptQuestModel. It holds every model component.
2. Add input variables: add one or more decision variables. They define the search space.
3. Add output variables (optional): add an output variable for each result of the simulation that an objective or constraint needs and that cannot be written as an expression of the inputs.
4. Define objectives: add one or more objectives, each an expression over input and output variables with a maximize or minimize direction.
5. Define constraints (optional): add constraints as expressions over the variables to limit the feasible region.
6. Configure the run: set replications, stopping criteria, the sampling method and the other run settings as needed.
7. Run: call one of the managed Optimize or Sample methods, or drive the loop by hand, then read the solutions back.

Conventions

The rules below apply to every entry in this chapter. The entries do not repeat them.

Return Values and Errors

A function that has no other result reports success or failure this way:

• Java returns true on success and false when it refuses the call (for example, a duplicate name or an unknown variable). A method whose signature declares throws COptQuestException throws that exception when the engine reports an error. A method without the clause never throws.
• C#, C++ and Python return true on success and false on failure. Call GetLastError() on the model for the description. For the solution methods (Submit, Reject, Predict, Evaluate, Update, AddSuggested, AddEvaluated, AddRequired and SetValue), call GetLastError() on the solution instead.
• C returns a non-zero value on success and 0 on failure. Call OQGetLastError(model) after a model function and OQGetLastSolutionError(sol) after a solution function.

Submit and Reject return an iteration count instead of a flag; see their entries. The sticky error text, the per-thread error buffer and the rule that no exception crosses the C boundary are described in § Concepts › Error Handling. An entry has its own Returns section only when its function does not follow this rule.

Names

Every name argument follows the rules in § Concepts › Names: unique across the model, not empty, no whitespace, no semicolons, ASCII only, and not starting with a digit for a variable. The element names supplied to a composite variable must not contain commas either. The members of a selection variable and of a group can be generated element names with commas, such as m@1,2. A function that receives a name that breaks these rules fails.

A variable name must also not be the name of a function or a constant of the expression language. In Java, the Add call fails. In the other languages, the Add call succeeds, and the model fails when it initializes.

Numbering

The index and position numbers that OptQuest reports start at 1. These are:

• the selected tuple of a Tuple Variable and the selected location of a Geolocation Variable;
• the option of a Design or Choice Variable;
• the bin of an Assignment Variable and the group of a Partition Variable;
• the rank of a Sequence, Multi-Stage Sequence or Topological Sequence Variable, and the position of an element of a Permutation Variable;
• the position of a node on a Path Variable;
• the element numbers in generated names, such as v@1 for the first element of a vector;
• the iteration number (GetIteration) and the replication number (GetReplication).

Java, C#, C, C++ and Python number their arrays from 0. To use a reported value k as an index into your own array, read element k - 1. A value of 0 has its own meaning: an Assignment bin of 0 means that the item is in no bin, and a Path position of 0 means that the node is not on the path.

These numbers start at 0: the index i of GetBestSolutionsAt(i), GetAllSolutionsAt(i), GetInputNameAt(i) and GetOutputNameAt(i) in C and C++, and the counter on the --- line of a GETBESTSOLUTIONS or GETALLSOLUTIONS reply in the Standard I/O Interface.

Strings and Arrays in C and C++

Every string argument is a null-terminated const char*. An array of strings is a const char** with its element count passed alongside. The entries state only the layout of arrays that is not obvious from the signature.

Model Lifecycle

Create Model

Description

Creates a new OptQuestModel. The model holds every component you add to it. Create the model before you add variables, objectives or constraints.

Notes

• In Java, C#, C++ and Python the constructor allocates the resources.
• In C, OQCreateModel() returns an HOptQuestModel handle. Free it with OQDeleteModel() when you are done with the model.

Delete Model

Description

Releases the resources of an OptQuestModel. Java, C# and Python reclaim the object through garbage collection. In C++ the destructor runs when the object goes out of scope. In C, call OQDeleteModel on the handle.

Notes

• In C++, scope the OptQuestModel object so that its destructor runs when you are done with it.

Set License

Description

Sets the license key that an OptTek representative supplied. If SetLicense is never called, or is called with an empty string, the model runs in demo mode: every optimization stops after 50 iterations regardless of the requested iteration count. CreateSolution then returns an invalid solution, and GetTerminationReason reports Max Demo Iterations (14). A managed Optimize returns false with no error text.

Log Setup

Description

Writes an XML description of the model’s configuration to the file at filespec. Use it for debugging, or to share a model with OptTek support.

Notes

• filespec must be a valid, writable file path. It may contain spaces.
• The setup log is well formed only after its closing elements are written. The engine writes them when you delete the model, so a log read after the model is gone is complete. A Java caller that holds the OptQuestModel object directly can write them without deleting the model by calling CleanUp(), which also releases the solution log. Calling CleanUp() more than once is harmless.

Log Solutions

Description

Writes every solution evaluated during optimization or sampling to the file at filespec. Use it to share solution data with OptTek support for troubleshooting or analysis.

Notes

• filespec must be a valid, writable file path. It may contain spaces.

Initialize Model

Description

Builds the engine’s internal representation of the model and moves the model from the definition stage to the execution stage. After this call the model is immutable (see § Concepts › Model Immutability).

The call is optional: every method that needs an initialized model calls it first. Call it explicitly to find out whether the model is well formed before any solution is generated. Without the explicit call, you see the error later as a generic failure of the first CreateSolution() or Optimize(). With it, you can inspect the error at a known point.

Notes

• Initializing an already-initialized model is harmless. The call returns the result of the first initialization.
• A model that is refused before the engine is asked stays in the definition stage, so the Add* and Set* methods keep working and you can correct the model and initialize it again. The most common case is a model with no objective, reported as ERROR the model has no objective.
• A model that the engine itself refuses moves to the execution stage all the same, because the engine has already received it. AddContinuousVariable("o", "nonexistent") followed by Initialize() returns ERROR ... The variable was not found, and every later Add*/Set* call and every later Initialize() returns ERROR already initialized. Build a new model to correct that class of error.

Describe Model

Description

Returns the model as the block of definition commands that the binding sends to the engine. This is the text documented in § Reference › Standard I/O Interface › Model Definition Commands. Use it as a debugging aid: the text is what the binding built from your API calls, including the numeric formatting used on the wire, and you can capture it and replay it through the STDIO interface.

Returns

• The model definition block, one command per line.

Notes

• In C and C++, the model owns the returned pointer. The next call to Describe invalidates it.

Decision Variables

A decision variable is a value the optimizer chooses. Every function in this group adds one variable, or one family of generated variables under a base name, to the model. The families are:

• Standard: regular variables with one value each.
• Container: many independent standard variables under one base name.
• Permutation (deprecated): an ordering of named elements, one position variable per element. Use a sequence variable instead.
• Special purpose: a value inside a structured set. In every solution that the engine generates, the value is inside the set.
• Random: a random draw at the start of every replication.

Read the names of the variables in a model, including the generated element names, with GetInputNames (§ Working With Solutions › Get Variable Names).

Choosing a Variable Type

Find your decision in the first column. The full rules of each type are in its entry below.

These types are close to each other:

• Sequence and Permutation give the same ranks, from 1 to n. The Permutation Variable is deprecated, so use Sequence. In an optimization, Predict refuses a model that has a Permutation Variable and accepts a model that has a Sequence Variable. In Adaptive Sampling, Predict accepts both.
• Choice and Design give the same values, from 1 to the number of options. The Design Variable is deprecated, so use Choice.
• Choice, Enumeration and Tuple each select one entry. A Choice Variable reports the number of the option. An Enumeration Variable reports the number from your list. A Tuple Variable reports the number of the row, and the optimizer treats rows with close values as similar options.
• Multi-Choice, Item Selection and Budgeted Selection each select several items. If there are rules between the items, such as “if item 1 is selected, you can’t pick item 2 or 3”, use Item Selection. If the only rule is a count range, such as “pick 3 to 5”, the engine finds the best selection sooner with Multi-Choice. A Multi-Choice Variable uses the names that you give, and an Item Selection Variable numbers the candidates from 1. A Budgeted Selection Variable adds a cost for each candidate and a budget. The Selection Variable in § Variable Modifiers is different: it is one on/off flag for a group of other variables.
• Assignment and Partition each put items into groups. An Assignment Variable puts each item into a numbered bin, and bin 2 is a different bin from bin 3. A Partition Variable puts the items into groups that have no labels, so the engine reports one numbering for each division of the items into groups.
• Tree, DAG and Path each give a set of links between nodes. A Tree Variable connects every node, and it has one root, which you can fix. A DAG Variable allows any set of links that has no loop, including no links at all; with a start node, an end node and the connected option, it allows only graphs that run from the start node to the end node. Both types accept precedences. A Path Variable gives one route with no branches.
• Sequence and Topological Sequence each give an order. A Sequence Variable allows any order. A Topological Sequence Variable allows only the orders that obey your “A before B” rules.

Standard

Each function adds one decision variable named name.

Add Continuous Variable

Description

Adds a continuous variable with the inclusive bounds min and max.

Add Integer Variable

Description

Adds an integer variable whose values are the integers from min to max inclusive.

Add Discrete Variable

Description

Adds a discrete variable whose values run from min to max inclusive in steps of step. The range must hold a whole number of steps.

Add Binary Variable

Description

Adds a binary variable whose value is 0 or 1.

Add Design Variable

Deprecated. Use the Choice Variable (§ Add Choice Variable) instead. It gives the number of the selected option, from 1 to the number of options.

Description

Adds a design variable with num distinct choices. Its value is an index from 1 to num; for example, the indices 1, 2 and 3 can stand for the options red, blue and green.

Add Enumeration Variable

Description

Adds an enumeration variable whose value is one of the numbers in items.

Notes

• In C and C++, items is a pointer to an array of n doubles.

Add Tuple Variable

Description

Adds a tuple variable that selects one of the tuples in tuples. The value the solution reports is the 1-based index of the selected tuple. Each tuple is a point in n-dimensional space, and the optimizer uses the Euclidean distance between tuples to judge which choices are close to each other.

Notes

• In C and C++, tuples is a pointer to an array of nt tuples, each a pointer to nv doubles.

Add Geolocation Variable

Description

Adds a geolocation variable that selects one of the (latitude, longitude) pairs in locations. The value the solution reports is the 1-based index of the selected pair. The optimizer uses the angular distance between locations on a sphere to judge which choices are close to each other.

Notes

• In C and C++, locations is a pointer to an array of nl pairs, each a pointer to 2 doubles.

Container

A container function creates one independent standard variable per element and registers each one with the engine as an ordinary input variable. The elements share the bounds (and, for the discrete forms, the step) that you pass. They behave the same as variables added one at a time, and there is no performance cost compared with adding them one at a time. Use a container when many similar variables belong together (weights, coefficients, coordinates, grid parameters) and you want less code and uniform names.

Element names are 1-based and, for two or more dimensions, row-major:

Every dimension must be at least 1, and dims must not be empty. Use the ND form when the decision has more than two dimensions, or when you want the same indexing style for every rank. In an expression, write a name that contains a comma in square brackets, [<name>@1,2], so that the comma is not read as an argument separator. In C and C++, dims is a pointer to an array of ndims ints.

Add Vector Variable

Description

Adds a vector variable: n continuous variables. The elements are ordinary input variables.

Each element holds a continuous value from min to max.

Notes

• Variable names: <name>@1 to <name>@n, one for each element.

Add Matrix Variable

Description

Adds a matrix variable: an m by n matrix of continuous variables. The elements are ordinary input variables.

Each element holds a continuous value from min to max.

Notes

• Variable names: <name>@<row>,<col> for each element, with 1-based row and column numbers, row by row. Each name contains a comma, so write it in brackets in an expression: [<name>@1,2].

Add ND Variable

Description

Adds an N-dimensional variable: an array of continuous variables with the shape dims. The elements are ordinary input variables.

Each element holds a continuous value from min to max.

Notes

• Variable names: <name>@<i1>,<i2>,... for each element, with one 1-based index for each dimension. The last index changes fastest. With two or more dimensions, each name contains a comma, so write it in brackets in an expression: [<name>@1,2,3].

Add Integer Vector Variable

Description

Adds an integer vector variable: n integer variables. The elements are ordinary input variables.

Each element takes the values min, min + 1, min + 2, and so on, up to max. Give whole-number bounds to get whole-number values.

Notes

• Variable names: <name>@1 to <name>@n, one for each element.

Add Integer Matrix Variable

Description

Adds an integer matrix variable: an m by n matrix of integer variables. The elements are ordinary input variables.

Each element takes the values min, min + 1, min + 2, and so on, up to max. Give whole-number bounds to get whole-number values.

Notes

• Variable names: <name>@<row>,<col> for each element, with 1-based row and column numbers, row by row. Each name contains a comma, so write it in brackets in an expression: [<name>@1,2].

Add Integer ND Variable

Description

Adds an integer N-dimensional variable: an array of integer variables with the shape dims. The elements are ordinary input variables.

Each element takes the values min, min + 1, min + 2, and so on, up to max. Give whole-number bounds to get whole-number values.

Notes

• Variable names: <name>@<i1>,<i2>,... for each element, with one 1-based index for each dimension. The last index changes fastest. With two or more dimensions, each name contains a comma, so write it in brackets in an expression: [<name>@1,2,3].

Add Discrete Vector Variable

Description

Adds a discrete vector variable: n discrete variables. The elements are ordinary input variables.

Each element takes the values min, min + step, min + 2 × step, and so on. The largest value is the one nearest to max, so it can differ from max when max - min is not a whole multiple of step.

Notes

• Variable names: <name>@1 to <name>@n, one for each element.
• step: step between values; must be greater than 0.

Add Discrete Matrix Variable

Description

Adds a discrete matrix variable: an m by n matrix of discrete variables. The elements are ordinary input variables.

Each element takes the values min, min + step, min + 2 × step, and so on. The largest value is the one nearest to max, so it can differ from max when max - min is not a whole multiple of step.

Notes

• Variable names: <name>@<row>,<col> for each element, with 1-based row and column numbers, row by row. Each name contains a comma, so write it in brackets in an expression: [<name>@1,2].
• step: step between values; must be greater than 0.

Add Discrete ND Variable

Description

Adds a discrete N-dimensional variable: an array of discrete variables with the shape dims. The elements are ordinary input variables.

Each element takes the values min, min + step, min + 2 × step, and so on. The largest value is the one nearest to max, so it can differ from max when max - min is not a whole multiple of step.

Notes

• Variable names: <name>@<i1>,<i2>,... for each element, with one 1-based index for each dimension. The last index changes fastest. With two or more dimensions, each name contains a comma, so write it in brackets in an expression: [<name>@1,2,3].
• step: step between values; must be greater than 0.

Add Binary Vector Variable

Description

Adds a binary vector variable: k binary variables. The elements are ordinary input variables.

Each element holds 0 or 1.

Notes

• Variable names: <name>@1 to <name>@k, one for each element.

Add Binary Matrix Variable

Description

Adds a binary matrix variable: an m by n matrix of binary variables. The elements are ordinary input variables.

Each element holds 0 or 1.

Notes

• Variable names: <name>@<row>,<col> for each element, with 1-based row and column numbers, row by row. Each name contains a comma, so write it in brackets in an expression: [<name>@1,2].

Add Binary ND Variable

Description

Adds a binary N-dimensional variable: an array of binary variables with the shape dims. The elements are ordinary input variables.

Each element holds 0 or 1.

Notes

• Variable names: <name>@<i1>,<i2>,... for each element, with one 1-based index for each dimension. The last index changes fastest. With two or more dimensions, each name contains a comma, so write it in brackets in an expression: [<name>@1,2,3].

Permutation

A permutation variable is an ordinary decision variable. The position variables it creates are the values that the optimizer sets and the simulator reads. It is in its own family and is not one of the special purpose variables. Its element names use the same @ notation as theirs.

Add Permutation Variable

Deprecated. Use the Sequence Variable (§ Add Sequence Variable) instead. It gives the same ranks, from 1 to n, under element names of the same form, and it also has a top-k mode.

Description

Adds a permutation variable named group over the elements in names. The engine creates one integer decision variable per element, named <group>@<name>. Its value is the position of that element in the order, from 1 to n. Every trial solution is a complete permutation: each position appears exactly once. The strings in names must be distinct.

Example

model.AddPermutationVariable("group", new String[]{"a","b","c"});

This creates three decision variables: group@a, group@b and group@c. In the generate step, OptQuest writes the position of each element into its variable. If group@a = 1, group@b = 3 and group@c = 2, the evaluator must compute its outputs for the order {a, c, b}.

Notes

• In C and C++, names is a pointer to an array of n strings.

Special Purpose Variables: Common Behavior

A special purpose variable is a decision variable whose values must stay inside a structured set, for example an angle on an arc, a ranking of a list of items, or a matrix of limited rank. In every solution that the engine generates, and in every suggested solution, the values of a special purpose variable are inside its set. The simulator needs no code to handle values that are not valid.

In the Java class library, COptQuestManifoldVariable is the base class of the special purpose variable types, and the Javadoc calls them manifold variables. A saved model file uses the XML element ManifoldVariable for them.

The special purpose variable types are:

• Combinatorial: Choice, Multi-Choice, Mixture, Sequence, Multi-Stage Sequence, Policy Sequence, Topological Sequence, Assignment, Item Selection, Budgeted Selection, Partition, DAG, Tree and Path.
• Geometric: Angle, Spherical Angle, Region and Spherical Region.
• Smooth: Low-Rank Matrix, Time-Series Vector, B-spline, Spline and Fourier, each with its correction variants.

The Permutation variable is in its own family and is not one of the special purpose variables. Its element names use the same @ notation as theirs. See § API Documentation › Decision Variables › Add Permutation Variable.

Variable Names

A special purpose variable creates its variables under generated names of the form <name>@<suffix>, where <name> is the base name. The Notes of each type list the variable names and the values they hold. Use these names, not the base name, in expressions, objectives and constraints. See § Concepts › Names.

GetInputNames returns the variable names of every special purpose variable, because they are inputs: the engine sets them, and the evaluator reads them. The exceptions are the coefficient, contribution and confidence names of a policy sequence variable, whose values the engine computes. GetOutputNames returns those.

The variable names of the Item Selection and Budgeted Selection variables are ordinary binary inputs: the engine chooses these values directly. The engine adds the rules of these two types and of the Assignment variable to the model as constraints, so a solution that breaks a rule is infeasible.

Evaluated and Required Solutions

The engine uses the values of the special purpose variables in an evaluated solution or a required solution as given, so supply values that are inside the set of each variable. In a suggested solution, the engine can change values that are not inside the set.

Constraint Enforcement Timing

The engine checks a constraint over the variable names of a special purpose variable, other than an Item Selection or a Budgeted Selection variable, after evaluation, the same way it checks a constraint over an output. The simulator always receives values that follow the rules of the variable type. Only the constraint check is deferred. A solution that breaks such a constraint is marked infeasible after its evaluation, so it costs a full evaluation.

When the declaration of the variable can express a restriction, declare it there: an arc on an Angle Variable, per-component bounds and sumTo on a Mixture Variable, a count or capacity range on a selection or assignment type. A restriction declared that way holds for every solution that the engine generates, and it costs no evaluation. Use a constraint over the variable names only when the declaration cannot express the rule.

The Notes of each type below list only what is specific to that type. The behavior in this section applies to every special purpose variable.

Special Purpose: Combinatorial

Add Choice Variable

Description

Adds a choice variable. Its value is one option out of k options. Use a choice variable when the decision is one selection from options that have no natural order, such as a machine type, a supplier or an operating mode.

In every solution that the engine generates, exactly one option is selected.

In a suggested solution, the engine rounds the value to the nearest whole number from 1 to k.

Notes

• Variable names: <name>@choice, the 1-based index of the selected option, a whole number from 1 to k.
• The Choice Variable replaces the Design Variable, which is deprecated; see § API Documentation › Decision Variables › Add Design Variable.

Add Multi-Choice Variable

Description

Adds a multi-choice variable. Its value is a subset of the choices that has from minSelect to maxSelect members. Use a multi-choice variable when the decision is an unordered selection of several items and a count range is the only rule, such as which sensors to turn on or which assets to include. If there are rules between the items, use the Item Selection Variable (§ Add Item Selection Variable).

In every solution that the engine generates, each choice is either selected or not, and the number of selected choices is from minSelect to maxSelect.

In a suggested solution, the engine selects each choice whose value is greater than 0.5. If the suggested solution selects more than maxSelect choices, the engine keeps the selected choices that come first in choices. If it selects fewer than minSelect, the engine adds the unselected choices that come first.

Notes

• Variable names: <name>@<choice> for each choice, in the order of choices. Each holds 1 if the choice is selected and 0 if it is not.
• In C and C++, choices is a pointer to an array of numChoices strings.

Add Mixture Variable

Description

Adds a mixture variable. Its value is a set of continuous weights, one for each component, and the weights sum to sumTo. Use a mixture variable when the decision is a set of proportions, such as portfolio weights, blend fractions or allocation ratios.

In every solution that the engine generates, the weights sum to sumTo within 1e-12, and each weight is within the bounds of its component.

With a negative lower bound, the weights can go below zero, down to that bound.

Notes

• Variable names: <name>@<component> for each component, in the order of components. Each holds the weight of that component.
• sumTo must be greater than zero.
• lowerBounds and upperBounds are optional in every language and form a matched pair: supply both (each of length k) or neither (null, NULL or None). The call fails if only one is supplied.
• In C and C++, components is a pointer to an array of k strings; lowerBounds and upperBounds are each a pointer to an array of k doubles.

Add Sequence Variable

Description

Adds a sequence variable. Its value is a priority order of the components. Use a sequence variable when the decision is an order of discrete items, such as a job sequence or the priority of sensor tasks.

In every solution that the engine generates, the ranks are valid. In a full ranking, the values are a permutation of 1 to n, where n is the number of components and 1 is the highest priority. In a top-k ranking, the first topK components get the ranks 1 to topK, and every other component gets the rank topK + 1.

When a suggested solution gives two components the same rank, the component that comes first in components gets the better rank.

Notes

• Variable names: <name>@<component> for each component, in the order of components. Each holds the integer rank of that component.
• topK: null for a full ranking, or the number of components to rank. A value of n or more gives a full ranking, and a value less than 1 is used as 1. With topK = 1, the most important component gets rank 1, and every other component gets rank 2.
• In Java, pass null for topK to request a full ranking. In C#, pass null (the parameter type is int?). In Python, omit top_k or pass None. In C and C++, topK is a pointer to a single int; pass NULL for a full ranking.
• In C and C++, components is a pointer to an array of k strings.
• The Sequence Variable replaces the Permutation Variable, which is deprecated; see § API Documentation › Decision Variables › Add Permutation Variable.

Add Multi-Stage Sequence Variable

Description

Adds a multi-stage sequence variable. Its value is one priority order for each stage, over the components of that stage. Use a multi-stage sequence variable when the decision is a set of orders, one for each stage, such as the job order on each of several machines.

In every solution that the engine generates, the ranks in each stage are a permutation of 1 to the number of components in that stage, where 1 is the highest priority. The engine ranks each stage separately.

A component name can appear in only one stage. To rank the same item in two stages, give it a different name in each stage.

When a suggested solution gives two components of a stage the same rank, the component that comes first in that stage gets the better rank.

Notes

• Variable names: <name>@<component> for every component, stage by stage, in the order of stageGroups. Each holds the integer rank of that component within its stage.
• In C and C++, stageGroups is a pointer to an array of numStages stages, each a pointer to its own array of component name strings, and stageSizes is a pointer to an array of numStages ints that gives the size of each stage.

Add Policy Sequence Variable

Description

Adds a policy sequence variable. Its value is a linear scoring rule over the features of a set of items: one weight for each feature, and a priority score for each item. Use a policy sequence variable when a good order depends on a few item attributes, and the weights themselves are a useful result, for example dispatch order by urgency and setup family.

In every solution that the engine generates, the item scores come from one set of feature weights applied to the feature matrix. Sort the items by descending score to get the ranked list: a higher score means a higher priority. This is the opposite of a sequence variable, where 1 is the highest priority.

The engine computes every value of a policy sequence variable. The item scores are inputs. The coefficients, the contributions and the confidences are outputs. The five families of names are in the Notes. Item names and feature names share one set of names, so every item name and feature name must be different from all the others.

Give the feature values in their own units. The engine scales the columns, so you do not need to scale them. In a suggested solution, the engine reads only the item scores, and it can change them. For an evaluated or required solution, the engine computes the coefficient, contribution and confidence outputs from the policy that best fits the supplied item scores. It does not change the scores.

Each item name and feature name must not contain whitespace, a semicolon, a comma or @.

Notes

• Variable names:
  • <name>@<itemName> for each item, an input: the priority score of that item.
  • <name>@<featureName> for each feature, an output: the coefficient of that feature, which is the change in score for one unit of the feature. Multiply each raw feature value of an item by its coefficient and add the products to score a new item. That sum can differ from the reported score by a constant that is the same for every item, so it gives the same order.
  • <name>@<featureName>@contribution for each feature, an output: the signed share of that feature in the rule, in [-1, 1]. The absolute values of all the contributions sum to 1.
  • <name>@<featureName>@confidence for each feature, an output: a confidence in [0, 1] for the weight of that feature. A feature whose values are all equal gets 0.
  • <name>@<itemName>@confidence for each item, an output: a confidence in [0, 1] that the item is in the right place relative to its neighbors in the order. With one item, the value is 1.
• In C and C++, featureMatrix is a pointer to an array of n rows, each a pointer to an array of k doubles; n is the item count (rows) and k is the feature count (columns). itemNames has length n and featureNames has length k. In Java, C# and Python the counts come from the supplied matrix and name arrays.

Add Topological Sequence Variable

Description

Adds a topological sequence variable. Its value is an order of the tasks in which every task comes after its predecessors. Use a topological sequence variable when the decision is the order in which to do a set of tasks, and some tasks must always come before others, such as project steps with dependencies or an assembly sequence.

In every solution that the engine generates, the order keeps every precedence: a predecessor always has a smaller rank than the task that depends on it.

In a suggested solution, the engine keeps an order that meets every precedence, and it gives equal ranks different values in the order of tasks. If the order breaks a precedence, the engine changes it: at each step, of the tasks that can go next, the task with the smallest suggested rank goes next.

The engine checks that no task lists itself as a predecessor and that the precedences form no cycle. It ignores names in predecessors that are not in tasks.

predecessors gives the dependencies. In Java, C# and Python it is a map from a dependent task to the list of tasks that must finish before it. In C and C++ it is an array of [dependent, predecessor] pairs; a task with several predecessors appears in several pairs.

Notes

• Variable names: <name>@<task> for each task, in the order of tasks. Each holds the integer rank of that task in the order, where 1 is first and n is last. The ranks are a permutation of 1 to n.
• In C and C++, tasks is a pointer to an array of numTasks strings, and predecessors is a pointer to an array of numPairs two-element string pairs.

Add Assignment Variable

Description

Adds an assignment variable. Its value is an assignment of each of m items to one of n bins. Use an assignment variable when the decision assigns items to bins, such as jobs to machines or tasks to workers. Three overloads set the rules:

• Simple (name, m, n): every item is in exactly one bin, and a bin can hold any number of items.
• Homogeneous (name, m, n, mustAssign, binCapacityMin, binCapacityMax): when mustAssign is true, every item is in exactly one bin, and when it is false, every item is in at most one bin. Every bin holds from binCapacityMin to binCapacityMax items.
• Heterogeneous (name, m, n, mustAssign[], binCapacitiesMin[], binCapacitiesMax[]): item i is in exactly one bin when mustAssign[i] is true, and in at most one bin when it is false. Bin j holds from binCapacitiesMin[j] to binCapacitiesMax[j] items.

The engine adds the assignment rules to the model as constraints, so a solution that breaks a rule is infeasible.

In a suggested solution, the engine rounds each value to the nearest bin index, and it puts an item whose value is outside 1 to n in no bin. The engine can then change the assignment so that it meets the rules.

In Python, one method covers the three forms: omit must_assign for the simple form, pass a bool or int for the homogeneous form, or pass a sequence for the heterogeneous form.

In C, the homogeneous function takes mustAssign as an int (0 = false, non-zero = true), and the heterogeneous function takes the flags as const int* with the same convention.

Notes

• Variable names: <name>@1 to <name>@m, one for each item. Each holds the 1-based index of the bin that holds the item, or 0 when the item is in no bin, which can happen only when the item does not have to be assigned.
• m (items) and n (bins) must each be at least 1.
• The call fails if a bin maximum is negative or less than its minimum, if the bin minimums add up to more than m items, or if the bins cannot hold every item that must be assigned.
• In C and C++, for the heterogeneous overload, mustAssign is a pointer to an array of m flags, and binCapacitiesMin and binCapacitiesMax are each a pointer to an array of n ints.

Add Item Selection Variable

Description

Adds an item selection variable. Its value is a selection of candidates from a pool of n. Use an item selection variable when the decision is which candidates to include, such as which sites to open. Two overloads set the number of candidates to select:

• Exact (name, n, k): exactly k candidates are selected. This is the range form with kMin = kMax = k.
• Range (name, n, kMin, kMax): from kMin to kMax candidates are selected.

The engine adds the selection rule to the model as a constraint, so a solution that selects a different number of candidates is infeasible. The variable names are ordinary binary inputs. Expressions can reference them without brackets, and the engine enforces a constraint over them before evaluation, for example sel@2 + sel@5 <= 1.

In Python, one method covers both forms: omit k_max for the exact form, or supply it for the range form with k as the minimum.

In C, the exact form is OQAddItemSelectionVariable and the range form is OQAddItemSelectionVariableRange.

Notes

• Variable names: <name>@1 to <name>@n, one for each candidate. Each holds 1 if the candidate is selected and 0 if it is not.
• n must be at least 1. The call fails if no selection of n candidates has from kMin to kMax members, for example when k is greater than n or kMin is greater than kMax.
• To turn a group of variables on or off with one binary flag, use the Selection Variable (§ Variable Modifiers) instead.

Add Budgeted Selection Variable

Description

Adds a budgeted selection variable. Its value is a selection of candidates from a pool of n whose total cost is within a budget. Use a budgeted selection variable when the decision is which candidates to include within a budget, such as which projects to fund. Two overloads set the rules:

• Simple (name, n, costs, budgetMax): the total cost of the selected candidates is at most budgetMax.
• Full (name, n, costs, budgetMin, budgetMax, kMin, kMax): the total cost is from budgetMin to budgetMax, and the number of selected candidates is from kMin to kMax. A budgetMin of 0 or less sets no smallest total.

The engine adds the budget and count rules to the model as constraints, so a solution that breaks a rule is infeasible. The variable names are ordinary binary inputs, and expressions can reference them without brackets.

In Python, one method covers both forms: supply only budget_max for the simple form, or supply any non-default budget_min, k_min or k_max for the full form.

In C, the simple form is OQAddBudgetedSelectionVariable and the full form is OQAddBudgetedSelectionVariableFull.

Notes

• Variable names: <name>@1 to <name>@n, one for each candidate. Each holds 1 if the candidate is selected and 0 if it is not.
• n must be at least 1, and costs must have one entry for each candidate. A cost can be negative.
• The call fails if budgetMax is less than the lowest possible total cost, if budgetMin is positive and greater than budgetMax or than the highest possible total cost, or if no selection has from kMin to kMax candidates.
• In C and C++, costs is a pointer to an array of n doubles.

Add Partition Variable

Description

Adds a partition variable. Its value is a division of m items into exactly k groups. The groups have no order, and no group is empty. Use a partition variable when the decision divides items into groups, such as crews into shifts or customers into delivery zones.

In every solution that the engine generates, every group has at least one item, and the same division into groups always gets the same group numbers.

In a suggested solution, the engine rounds each value to the nearest group number from 1 to k. It then fills any empty group and numbers the groups again, so the values can change.

Notes

• Variable names: <name>@1 to <name>@m, one for each item. Each holds the 1-based number of the group that holds the item. Item 1 is always in group 1. For each later item, the group number is at most one more than the largest group number among the items before it.
• m must be at least k, and k must be at least 1.

Add DAG Variable

Description

Adds a DAG variable. Its value is a directed acyclic graph (DAG) over the given nodes: a set of directed edges with no cycle. Use a DAG variable when the decision is a set of one-way links with no loop, such as dependencies between tasks or a flow network.

In every solution that the engine generates, the edges form no cycle. Without options, any DAG over the nodes can occur, including the graph with no edges. You can restrict the graphs with these options:

• startNode: this node has no incoming edge.
• endNode: this node has no outgoing edge.
• connected: every node can be reached from the start node, and every node can reach the end node. It needs a start node, an end node or both. With only a start node, the rule is only about reaching the nodes from the start node, and with only an end node, it is only about reaching the end node.
• predecessors: a map from a node to the nodes that must come before it. No directed path runs from a node to one of its predecessors. A precedence does not add an edge.

In a suggested solution, a value greater than 0.5 is an edge. The engine keeps a suggested DAG that follows the options as it is. If the suggested edges form a cycle or break an option, the engine removes edges until the graph follows the options, and with connected it adds edges until every node is connected.

Notes

• Variable names: <name>@<nodeFrom>,<nodeTo> for every ordered pair of nodes, including a node paired with itself: the full n by n adjacency matrix, row by row in the order of nodeNames. Each holds 1 if the edge from nodeFrom to nodeTo is present and 0 if it is not. The diagonal is always 0. Each name contains a comma, so write it in brackets in an expression: [<name>@A,B].
• startNode and endNode may be null, NULL, None or an empty string: no fixed start or end. predecessors may be empty, null, NULL or None. The short form without options is the same as all options unset.
• The model refuses a start or end node that is not one of the nodes, a start node that is also the end node, connected with no start node and no end node, a start node that has a predecessor, an end node that is a predecessor, a node that lists itself as a predecessor, and precedences that form a cycle. Names in predecessors that are not nodes are ignored. In Java the Add call throws COptQuestException. In the other languages the model fails when it initializes.
• In C and C++, nodeNames is a pointer to an array of n strings, and predecessors is a pointer to an array of numPairs pairs [dependent, predecessor]; a node with several predecessors appears in several pairs. In C, connected is 0 or 1.

Add Tree Variable

Description

Adds a tree variable. Its value is a directed spanning tree over the given nodes: one node is the root, every other node has exactly one incoming edge, and every node can be reached from the root. Use a tree variable when the decision is a hierarchy that connects every node, such as a cueing network or a reporting structure.

In every solution that the engine generates, the edges form a spanning tree. The tree has exactly n - 1 edges and no cycle. You can restrict the trees with these options:

• rootNode: this node is the root of every tree. Without it, any node can be the root.
• predecessors: a map from a node to the nodes that must come before it. A node never comes above one of its predecessors: no path from the root to a predecessor passes through the node. A precedence does not make a node the parent of another.

In a suggested solution, a value greater than 0.5 is an edge. The engine keeps a suggested tree that follows the options as it is. Otherwise, the engine keeps one incoming edge for each node other than the root, and it uses a suggested edge where it can.

Notes

• Variable names: <name>@<nodeFrom>,<nodeTo> for every ordered pair of nodes, including a node paired with itself: the full n by n adjacency matrix, row by row in the order of nodeNames. Each holds 1 if the edge from nodeFrom to nodeTo is present and 0 if it is not. The diagonal is always 0. Each name contains a comma, so write it in brackets in an expression: [<name>@A,B].
• rootNode may be null, NULL, None or an empty string: any node can be the root. predecessors may be empty, null, NULL or None. The short form without options is the same as both options unset.
• The model refuses a root that is not one of the nodes, a root that has a predecessor, a node that lists itself as a predecessor, and precedences that form a cycle. Names in predecessors that are not nodes are ignored. In Java the Add call throws COptQuestException. In the other languages the model fails when it initializes.
• In C and C++, nodeNames is a pointer to an array of n strings, and predecessors is a pointer to an array of numPairs pairs [dependent, predecessor]; a node with several predecessors appears in several pairs.

Add Path Variable

Description

Adds a path variable. Its value is a simple path through some of the given nodes: an order of nodes in which no node appears twice. Use a path variable when the decision is a route that visits some of the candidate nodes, such as a patrol route or a delivery tour.

In every solution that the engine generates, the path is valid. The positions of the nodes on the path are 1 to L, where L is the length of the path, with no gap and no repeat. The start node, when given, has position 1. The end node, when given and different from the start node, has position L. When the start node and the end node are the same node, it has position 1 only. Every required node is on the path. The path can have only one node.

In a suggested solution, the engine puts a node whose value is 0 or less off the path, and it uses the other values only for the order of the nodes. The engine numbers the positions again, and it adds the start node, the end node and the required nodes when they are missing.

Notes

• Variable names: <name>@<node> for each node, in the order of nodeNames. Each holds the 1-based position of that node on the path, or 0 if the node is not on the path.
• At least two candidate nodes are required.
• startNode and endNode may be null, NULL or None (no fixed start or end). requiredNodes may be empty, null, NULL or None.
• When startNode equals endNode, the path does not return to the start node. The evaluator handles the return leg, for example by adding the closing edge in the objective.
• In C and C++, nodeNames is a pointer to an array of numNodes strings, and requiredNodes is a pointer to an array of nRequired strings.

Special Purpose: Geometric

A geometric variable places a point on a circle, on a sphere or inside a polygon. All angles are in degrees.

Add Angle Variable

Description

Adds an angle variable. Its value is an angle in degrees on an arc of the circle. Use an angle variable when the decision is a direction in a plane, such as a panel orientation or a turbine yaw.

In every solution that the engine generates, the angle is on the arc from minDeg to maxDeg. When the difference between maxDeg and minDeg is 360 or more, the arc is the full circle. Otherwise the arc goes from minDeg to maxDeg in the direction of increasing angle, so an arc with minDeg greater than maxDeg, such as 320 to 40, crosses 0.

The engine reports the angle as its equivalent in [0, 360), which can differ from the range that you declare. For example, for an arc declared from -45 to 45, the engine reports 315 for -45. To compare the value with the declared bounds, first subtract 360 while the value is greater than maxDeg.

Notes

• Variable names: <name>@theta, the angle in degrees.

Add Spherical Angle Variable

Description

Adds a spherical angle variable. Its value is a direction in three dimensions, given as an elevation and an azimuth in degrees. Use a spherical angle variable when the decision is a pointing direction, such as an antenna boresight or a sensor line of sight.

In every solution that the engine generates, the elevation is from minThetaDeg to maxThetaDeg, and the azimuth is on the arc from minPhiDeg to maxPhiDeg. The azimuth arc follows the same rules as the arc of an angle variable: a difference of 360 or more is the full circle, and an arc with minPhiDeg greater than maxPhiDeg crosses 0.

The engine reports the azimuth as its equivalent in [0, 360), which can differ from the range that you declare. For example, for an azimuth declared from -60 to 60, the engine reports 300 for -60. The engine reports the elevation as it is, within the declared range.

Notes

• Variable names:
  • <name>@theta: the elevation in degrees, from -90 (straight down) through 0 (the horizon) to 90 (straight up).
  • <name>@phi: the azimuth in degrees, where 0 is north and 90 is east.
• Elevation convention: -90° is straight down, 0° is the horizon and +90° is straight up. This is not the physics colatitude in [0, 180].
• The elevation bounds must lie within [-90°, +90°], minThetaDeg must not exceed maxThetaDeg, and neither may be NaN. Otherwise the call fails in the usual way for the language. The azimuth bounds are unrestricted.

Add Region Variable

Description

Adds a region variable. Its value is a point (x, y) in a plane polygon. Use a region variable when the decision is a location inside a region, such as a site inside a property boundary.

In every solution that the engine generates, the point is inside the polygon or on its boundary. The polygon can be non-convex. A point is inside by the even-odd rule, so a polygon whose edges cross each other is also accepted.

Give the vertices in either order, clockwise or counterclockwise. You do not need to repeat the first vertex at the end.

Notes

• Variable names: <name>@x and <name>@y, the coordinates of the point, in the units of the polygon.
• polygon is a list of [x, y] vertices; there must be at least 3.
• In C and C++, polygon is a pointer to an array of nVertices pointers, each to a vertex of coordsPerVertex doubles (2 for this variable).

Add Spherical Region Variable

Description

Adds a spherical region variable. Its value is a point (latitude, longitude) in a polygon on the surface of the Earth. Use a spherical region variable when the decision is a location inside a geographic region, such as a sensor site inside a border.

In every solution that the engine generates, the point is inside the region or on its boundary. The edges of the polygon are great-circle arcs, not lines of constant latitude.

List the vertices clockwise, as on a map with north up: the region is on your right as you walk from each vertex to the next. This is the Esri rule for the outer ring of a polygon. The same vertices in counterclockwise order give the rest of the Earth. A region can enclose a pole, span more than 180 degrees of longitude, or be larger than a hemisphere. For a region around the North Pole, list the vertices from east to west. You do not need to repeat the first vertex at the end. The boundary must not cross itself.

Notes

• Variable names:
  • <name>@theta: the latitude of the point, in degrees.
  • <name>@phi: the longitude of the point, in degrees, from -180 to 180.
• polygon is a list of [latitude, longitude] vertices in degrees, latitude first; there must be at least 3 different vertices. A vertex that repeats the one before it is ignored.
• The model refuses a latitude outside [-90, 90], a coordinate that is not a finite number, fewer than 3 different vertices, two consecutive vertices that are antipodal (the edge between them is not defined), and a boundary that doubles back on itself or encloses no area. In Java the Add call throws COptQuestException. In the other languages the model fails when it initializes.
• In C and C++, polygon is a pointer to an array of nVertices pointers, each to a vertex of coordsPerVertex doubles (2 for this variable).

Special Purpose: Smooth

Use a smooth variable when your decision is a long list or a large table of numbers, and neighboring values are expected to be close. Examples are an hourly pumping schedule, a temperature profile along a reactor, and a table of set points by month and zone. For each smooth type you set one small number: a number of knots, a number of cosine terms or a rank. In every solution that the engine generates, the values have a shape that this number allows, and every element is from min to max.

Each type has a correction variant. It takes a baseline, initial, and adds a smooth correction to it, so the values are initial + correction. Use a correction variant to keep a known profile or table and optimize only a smooth adjustment to it. The engine first moves each entry of initial into [min, max].

Variable names follow the container convention: <name>@1 … <name>@length for a vector, <name>@<row>,<col> for a matrix, and <name>@1 … <name>@(longScale × shortScale) for a time-series vector.

Add Low-Rank Matrix Variable

Description

Adds a low-rank matrix variable. Its value is a rows by cols matrix that is a constant matrix plus a correction of low rank. Use a low-rank matrix variable when the decision is a large table that you can describe with a few row and column patterns.

In every solution that the engine generates, every entry is from min to max, and the matrix is the constant matrix (min + max) / 2 plus a correction of rank at most rank. So the matrix itself can have rank rank + 1.

The value of rank is the number of row patterns that the engine can combine. With rank 1, each row of the matrix is the middle value (min + max) / 2 plus one row pattern, multiplied by an amount that can differ from row to row. Each extra unit of rank adds one more row pattern. With rank 0, every entry is the middle value.

Notes

• Variable names: <name>@<row>,<col> for each entry, with 1-based row and column numbers, row by row. Each name contains a comma, so write it in brackets in an expression: [<name>@1,2].
• rank: largest rank of the correction. A value greater than the number of rows or columns is reduced to it, and a value of 0 or less gives a constant matrix.

Add Low-Rank Correction Matrix Variable

Description

Adds a low-rank correction matrix variable. Its value is a baseline matrix, initial, plus a correction of low rank. Use a low-rank correction matrix variable to keep a known table and change it with a few row and column patterns.

In every solution that the engine generates, every entry is from min to max, and the matrix is initial plus a correction of rank at most rank, except where an entry of initial is on min or max and the correction points past that bound: there the engine keeps the entry on the bound, and the correction can have a higher rank. The engine first moves each entry of initial into [min, max].

Notes

• Variable names: <name>@<row>,<col> for each entry, with 1-based row and column numbers, row by row. Each name contains a comma, so write it in brackets in an expression: [<name>@1,2].
• initial: the baseline matrix; its shape sets the number of rows and columns.
• rank: largest rank of the correction. A value greater than the number of rows or columns is reduced to it, and a value of 0 or less gives a constant matrix.
• In C and C++, initial is a pointer to an array of rows pointers, each to a row of cols doubles.

Add Incremental Low-Rank Correction Matrix Variable

Description

Adds an incremental low-rank correction matrix variable. Its value is a baseline matrix, initial, plus a correction of rank 1. Use this variable to build a correction one rank at a time. Run an optimization, pass its best value as initial of the next variable of this type, and repeat. Each variable adds a correction of rank 1 and does not keep the corrections of earlier variables.

In every solution that the engine generates, every entry is from min to max, and the matrix is initial plus a correction of rank at most 1, except where an entry of initial is on min or max and the correction points past that bound: there the engine keeps the entry on the bound, and the correction can have a higher rank. The engine first moves each entry of initial into [min, max].

Notes

• Variable names: <name>@<row>,<col> for each entry, with 1-based row and column numbers, row by row. Each name contains a comma, so write it in brackets in an expression: [<name>@1,2].
• initial: the baseline matrix; its shape sets the number of rows and columns.
• rank: the number of this step in the sequence, from 1. It does not change the values. A value less than 1 is refused. In Java the call throws an exception. In the other languages the call succeeds, and the model fails when it initializes, with the error “Invalid rank for an incremental variable: rank=N. The rank must be at least 1.”
• In C and C++, initial is a pointer to an array of rows pointers, each to a row of cols doubles.

Add Time-Series Vector Variable

Description

Adds a time-series vector variable. Its value is a vector of longScale × shortScale values. The engine arranges the values row by row as a longScale by shortScale matrix, and the matrix is a constant plus a correction of low rank. Use a time-series vector variable when the decision is a long vector with a repeating pattern, such as hourly values over many days.

In every solution that the engine generates, every value is from min to max, and the matrix is the constant matrix (min + max) / 2 plus a correction of rank at most rank.

The value of rank is the number of patterns that the engine can combine. With days as rows, hours as columns and rank 1, each day is the middle value (min + max) / 2 plus one pattern over the hours, multiplied by an amount that can differ from day to day. So every day has the same shape, and the size of the change can differ from day to day. Each extra unit of rank adds one more pattern. With rank 0, every value is the middle value.

Notes

• Variable names: <name>@1 to <name>@n, where n is longScale × shortScale. The engine numbers the entries row by row. The entry in row r and column c of the matrix, both counted from 1, is <name>@k, where k = (r - 1) × shortScale + c. For example, with shortScale = 24, hour 5 of day 3 is <name>@53.
• longScale: number of rows of the matrix, for example the number of days; must be at least 1.
• shortScale: number of columns of the matrix, for example the number of hours in a day; must be at least 1.
• rank: largest rank of the correction. A value greater than the number of rows or columns is reduced to it, and a value of 0 or less gives a constant matrix.

Add Time-Series Correction Vector Variable

Description

Adds a time-series correction vector variable. Its value is a baseline vector, initial, plus a correction. The engine arranges the values row by row as a longScale by shortScale matrix, and the correction to that matrix has low rank. Use a time-series correction vector variable to keep a known profile and change it with a few repeating patterns.

In every solution that the engine generates, every value is from min to max, and the matrix is initial plus a correction of rank at most rank, except where an entry of initial is on min or max and the correction points past that bound: there the engine keeps the entry on the bound, and the correction can have a higher rank. The engine first moves each entry of initial into [min, max].

Notes

• Variable names: <name>@1 to <name>@n, where n is longScale × shortScale. The engine numbers the entries row by row. The entry in row r and column c of the matrix, both counted from 1, is <name>@k, where k = (r - 1) × shortScale + c. For example, with shortScale = 24, hour 5 of day 3 is <name>@53.
• initial: the baseline vector; it must have longScale × shortScale values.
• longScale: number of rows of the matrix, for example the number of days; must be at least 1.
• shortScale: number of columns of the matrix, for example the number of hours in a day; must be at least 1.
• rank: largest rank of the correction. A value greater than the number of rows or columns is reduced to it, and a value of 0 or less gives a constant matrix.
• In C and C++, initial is a pointer to an array of longScale × shortScale doubles in row-major order.

Add Incremental Time-Series Correction Vector Variable

Description

Adds an incremental time-series correction vector variable. Its value is a baseline vector, initial, plus a correction. The engine arranges the values row by row as a longScale by shortScale matrix, and the correction to that matrix has rank 1. Use this variable to build a correction one rank at a time. Run an optimization, pass its best value as initial of the next variable of this type, and repeat. Each variable adds a correction of rank 1 and does not keep the corrections of earlier variables.

In every solution that the engine generates, every value is from min to max, and the matrix is initial plus a correction of rank at most 1, except where an entry of initial is on min or max and the correction points past that bound: there the engine keeps the entry on the bound, and the correction can have a higher rank. The engine first moves each entry of initial into [min, max].

Notes

• Variable names: <name>@1 to <name>@n, where n is longScale × shortScale. The engine numbers the entries row by row. The entry in row r and column c of the matrix, both counted from 1, is <name>@k, where k = (r - 1) × shortScale + c. For example, with shortScale = 24, hour 5 of day 3 is <name>@53.
• initial: the baseline vector; it must have longScale × shortScale values.
• longScale: number of rows of the matrix, for example the number of days; must be at least 1.
• shortScale: number of columns of the matrix, for example the number of hours in a day; must be at least 1.
• rank: the number of this step in the sequence, from 1. It does not change the values. A value less than 1 is refused. In Java the call throws an exception. In the other languages the call succeeds, and the model fails when it initializes, with the error “Invalid rank for an incremental variable: rank=N. The rank must be at least 1.”
• In C and C++, initial is a pointer to an array of longScale × shortScale doubles in row-major order.

Add BSpline Vector Variable

Description

Adds a B-spline vector variable. Its value is a vector of length values on a smooth curve defined by numKnots knots. Use a B-spline vector variable when the decision is a long profile that changes smoothly, such as a setpoint schedule.

The curve is a uniform cubic B-spline. It is smooth, and it does not pass through its knots: each value is a weighted average of the nearby knot values. The knots are at evenly spaced elements, with the first and last knots at the two ends.

In every solution that the engine generates, every element is from min to max.

Notes

• Variable names: <name>@1 to <name>@length, one for each element.
• numKnots: number of knots; fewer knots give a smoother curve. A value less than 2 is used as 2, and a value greater than the number of elements is used as that number.

Add Spline Vector Variable

Description

Adds a spline vector variable. Its value is a vector of length values on a smooth curve through numKnots knots. Use a spline vector variable when the decision is a long profile that changes smoothly, such as a setpoint schedule.

The curve is a centripetal Catmull-Rom spline. It is smooth, and it passes through its knots. The knots are at evenly spaced elements, with the first and last knots at the two ends.

In every solution that the engine generates, every element is from min to max.

Notes

• Variable names: <name>@1 to <name>@length, one for each element.
• numKnots: number of knots; fewer knots give a smoother curve. A value less than 2 is used as 2, and a value greater than the number of elements is used as that number.

Add BSpline Correction Vector Variable

Description

Adds a B-spline correction vector variable. Its value is a baseline vector, initial, plus a correction on a smooth curve defined by numKnots knots. Use a B-spline correction vector variable to keep a known profile and change it smoothly.

The curve is a uniform cubic B-spline. It is smooth, and it does not pass through its knots: each value is a weighted average of the nearby knot values. The knots are at evenly spaced elements, with the first and last knots at the two ends.

In every solution that the engine generates, every element is from min to max. The engine first moves each entry of initial into [min, max].

Notes

• Variable names: <name>@1 to <name>@length, one for each element. The number of elements is the length of initial.
• initial: the baseline vector; its length sets the number of elements.
• numKnots: number of knots; fewer knots give a smoother curve. A value less than 2 is used as 2, and a value greater than the number of elements is used as that number.
• In C and C++, initial is a pointer to an array of n doubles.

Add Spline Correction Vector Variable

Description

Adds a spline correction vector variable. Its value is a baseline vector, initial, plus a correction on a smooth curve through numKnots knots. Use a spline correction vector variable to keep a known profile and change it smoothly.

The curve is a centripetal Catmull-Rom spline. It is smooth, and it passes through its knots. The knots are at evenly spaced elements, with the first and last knots at the two ends.

In every solution that the engine generates, every element is from min to max. The engine first moves each entry of initial into [min, max].

Notes

• Variable names: <name>@1 to <name>@length, one for each element. The number of elements is the length of initial.
• initial: the baseline vector; its length sets the number of elements.
• numKnots: number of knots; fewer knots give a smoother curve. A value less than 2 is used as 2, and a value greater than the number of elements is used as that number.
• In C and C++, initial is a pointer to an array of n doubles.

Add BSpline Matrix Variable

Description

Adds a B-spline matrix variable. Its value is a rows by cols matrix on a smooth surface defined by a grid of knots. Use a B-spline matrix variable when the decision is a large table that changes smoothly in both directions.

The surface is a uniform cubic B-spline. It is smooth, and it does not pass through its knots: each value is a weighted average of the nearby knot values. The knots form a knotRows by knotCols grid at evenly spaced rows and columns, with knots at all four edges.

In every solution that the engine generates, every entry is from min to max.

Notes

• Variable names: <name>@<row>,<col> for each entry, with 1-based row and column numbers, row by row. Each name contains a comma, so write it in brackets in an expression: [<name>@1,2].
• knotRows: number of knot rows; fewer give a smoother surface down the columns. A value less than 2 is used as 2, and a value greater than the number of rows is used as that number.
• knotCols: number of knot columns; fewer give a smoother surface along the rows. A value less than 2 is used as 2, and a value greater than the number of columns is used as that number.

Add Spline Matrix Variable

Description

Adds a spline matrix variable. Its value is a rows by cols matrix on a smooth surface through a grid of knots. Use a spline matrix variable when the decision is a large table that changes smoothly in both directions.

The surface is a centripetal Catmull-Rom spline. It is smooth, and it passes through its knots. The knots form a knotRows by knotCols grid at evenly spaced rows and columns, with knots at all four edges.

In every solution that the engine generates, every entry is from min to max.

Notes

• Variable names: <name>@<row>,<col> for each entry, with 1-based row and column numbers, row by row. Each name contains a comma, so write it in brackets in an expression: [<name>@1,2].
• knotRows: number of knot rows; fewer give a smoother surface down the columns. A value less than 2 is used as 2, and a value greater than the number of rows is used as that number.
• knotCols: number of knot columns; fewer give a smoother surface along the rows. A value less than 2 is used as 2, and a value greater than the number of columns is used as that number.

Add BSpline Correction Matrix Variable

Description

Adds a B-spline correction matrix variable. Its value is a baseline matrix, initial, plus a correction on a smooth surface defined by a grid of knots. Use a B-spline correction matrix variable to keep a known table and change it smoothly.

The surface is a uniform cubic B-spline. It is smooth, and it does not pass through its knots: each value is a weighted average of the nearby knot values. The knots form a knotRows by knotCols grid at evenly spaced rows and columns, with knots at all four edges.

In every solution that the engine generates, every entry is from min to max. The engine first moves each entry of initial into [min, max].

Notes

• Variable names: <name>@<row>,<col> for each entry, with 1-based row and column numbers, row by row. Each name contains a comma, so write it in brackets in an expression: [<name>@1,2].
• initial: the baseline matrix; its shape sets the number of rows and columns.
• knotRows: number of knot rows; fewer give a smoother surface down the columns. A value less than 2 is used as 2, and a value greater than the number of rows is used as that number.
• knotCols: number of knot columns; fewer give a smoother surface along the rows. A value less than 2 is used as 2, and a value greater than the number of columns is used as that number.
• In C and C++, initial is a pointer to an array of rows pointers, each to a row of cols doubles.

Add Spline Correction Matrix Variable

Description

Adds a spline correction matrix variable. Its value is a baseline matrix, initial, plus a correction on a smooth surface through a grid of knots. Use a spline correction matrix variable to keep a known table and change it smoothly.

The surface is a centripetal Catmull-Rom spline. It is smooth, and it passes through its knots. The knots form a knotRows by knotCols grid at evenly spaced rows and columns, with knots at all four edges.

In every solution that the engine generates, every entry is from min to max. The engine first moves each entry of initial into [min, max].

Notes

• Variable names: <name>@<row>,<col> for each entry, with 1-based row and column numbers, row by row. Each name contains a comma, so write it in brackets in an expression: [<name>@1,2].
• initial: the baseline matrix; its shape sets the number of rows and columns.
• knotRows: number of knot rows; fewer give a smoother surface down the columns. A value less than 2 is used as 2, and a value greater than the number of rows is used as that number.
• knotCols: number of knot columns; fewer give a smoother surface along the rows. A value less than 2 is used as 2, and a value greater than the number of columns is used as that number.
• In C and C++, initial is a pointer to an array of rows pointers, each to a row of cols doubles.

Add Fourier Vector Variable

Description

Adds a Fourier vector variable. Its value is a vector of length values that is a sum of the numFreq lowest-frequency cosine terms. Use a Fourier vector variable when the decision is a long profile that varies smoothly, such as a daily cycle.

The first term is a constant. The second term is half of a cosine wave across the whole vector. Each next term adds one more half wave, so the later terms add finer detail. With one term, every element has the same value. For element i, counted from 1, term k is cos(π k (i - 0.5) / length), where k counts from 0.

In every solution that the engine generates, every element is from min to max.

Notes

• Variable names: <name>@1 to <name>@length, one for each element.
• numFreq: number of cosine terms, including the constant term; fewer give a smoother vector. A value less than 1 is used as 1, and a value greater than the number of elements is used as that number.

Add Fourier Matrix Variable

Description

Adds a Fourier matrix variable. Its value is a rows by cols matrix that is a sum of the lowest-frequency cosine terms: freqRows terms down the columns and freqCols terms along the rows. Use a Fourier matrix variable when the decision is a large table that varies smoothly in both directions.

The terms are products of a cosine down the columns and a cosine along the rows, like the terms of the vector type. With one term down the columns, every row is the same. With one term along the rows, every column is the same.

In every solution that the engine generates, every entry is from min to max.

Notes

• Variable names: <name>@<row>,<col> for each entry, with 1-based row and column numbers, row by row. Each name contains a comma, so write it in brackets in an expression: [<name>@1,2].
• freqRows: number of cosine terms down each column; fewer make the rows more alike. A value less than 1 is used as 1, and a value greater than the number of rows is used as that number.
• freqCols: number of cosine terms along each row; fewer make the columns more alike. A value less than 1 is used as 1, and a value greater than the number of columns is used as that number.

Add Fourier Correction Vector Variable

Description

Adds a Fourier correction vector variable. Its value is a baseline vector, initial, plus a correction that is a sum of the numFreq lowest-frequency cosine terms. Use a Fourier correction vector variable to keep a known profile and change it smoothly.

The first term is a constant. The second term is half of a cosine wave across the whole vector. Each next term adds one more half wave, so the later terms add finer detail. With one term, the correction has the same value at every element. For element i, counted from 1, term k is cos(π k (i - 0.5) / n), where k counts from 0 and n is the length of initial.

In every solution that the engine generates, every element is from min to max. The engine first moves each entry of initial into [min, max].

Notes

• Variable names: <name>@1 to <name>@length, one for each element. The number of elements is the length of initial.
• initial: the baseline vector; its length sets the number of elements.
• numFreq: number of cosine terms, including the constant term; fewer give a smoother vector. A value less than 1 is used as 1, and a value greater than the number of elements is used as that number.
• In C and C++, initial is a pointer to an array of n doubles.

Add Fourier Correction Matrix Variable

Description

Adds a Fourier correction matrix variable. Its value is a baseline matrix, initial, plus a correction that is a sum of the lowest-frequency cosine terms: freqRows terms down the columns and freqCols terms along the rows. Use a Fourier correction matrix variable to keep a known table and change it smoothly.

The terms are products of a cosine down the columns and a cosine along the rows, like the terms of the vector type. With one term down the columns, every row of the correction is the same. With one term along the rows, every column of the correction is the same.

In every solution that the engine generates, every entry is from min to max. The engine first moves each entry of initial into [min, max].

Notes

• Variable names: <name>@<row>,<col> for each entry, with 1-based row and column numbers, row by row. Each name contains a comma, so write it in brackets in an expression: [<name>@1,2].
• initial: the baseline matrix; its shape sets the number of rows and columns.
• freqRows: number of cosine terms down each column; fewer make the rows more alike. A value less than 1 is used as 1, and a value greater than the number of rows is used as that number.
• freqCols: number of cosine terms along each row; fewer make the columns more alike. A value less than 1 is used as 1, and a value greater than the number of columns is used as that number.
• In C and C++, initial is a pointer to an array of rows pointers, each to a row of cols doubles.

Random

Each function in this family adds a variable named name whose value is a random draw. At the start of every replication the engine draws a new value from the named distribution. Within one replication the value is fixed; between replications it changes. Without SetReplications, each trial solution has one replication, so it gets one draw, and its result depends on that one draw. To compare trial solutions by the combined result of several draws, call SetReplications with more than one replication (see § Stochastic Simulation Optimization). The evaluator reads it like any other input, and GetInputNames lists it. The distributions follow the scipy.stats definitions given in § Reference › Probability Distributions.

Add Beta Random Variable

Description

Adds a Beta-distributed variable with the shape parameters alpha and beta, both greater than 0.

Add Cauchy Random Variable

Description

Adds a Cauchy-distributed variable with the location parameter location and the scale parameter scale, which must be greater than 0.

Add Chi-Square Random Variable

Description

Adds a Chi-square-distributed variable with df degrees of freedom, a positive integer.

Add Exponential Random Variable

Description

Adds an exponentially distributed variable with the scale parameter scale, which must be greater than 0.

Add Gamma Random Variable

Description

Adds a Gamma-distributed variable with the shape parameter shape and the scale parameter scale, both greater than 0.

Add Log-Normal Random Variable

Description

Adds a log-normally distributed variable with the shape parameter shape and the scale parameter scale, both greater than 0.

Add Normal Random Variable

Description

Adds a normally distributed variable with the mean mean and the standard deviation sigma, which must be greater than 0.

Add Pareto Random Variable

Description

Adds a Pareto-distributed variable with the shape parameter gamma (greater than 0), the location parameter loc and the scale parameter scale (greater than 0). The smallest possible value is loc + scale. SetSampleRDSPareto uses the same three parameters.

Add Poisson Random Variable

Description

Adds a Poisson-distributed variable with the rate parameter lambda, which must be greater than 0. In Python the parameter is lambda_, because lambda is a keyword.

Add Power Random Variable

Description

Adds a random variable whose value is from rmin to rmax. Use power to set where most of the values are. With power = 1, every value in the range is equally likely. With power = 2, the values are the distances from the center of points spread evenly over the area of a ring with the radii rmin and rmax. With power = 3, they are the distances from the center of points spread evenly over the volume of a spherical shell. With a larger power, more values are near rmax. With a power between 0 and 1, more values are near rmin.

The probability density is proportional to x^(power - 1):

pdf(x) = power * x^(power - 1) / (rmax^power - rmin^power) for rmin <= x <= rmax.

With power = 1, the density is the constant 1 / (rmax - rmin).

power must be greater than 0, rmin must be at least 0, and rmax must be greater than rmin. A power of 0 or less is rejected; the uniform case is power = 1.

Add Spherical Elevation Random Variable

Description

Adds a spherical elevation variable, drawn uniformly by surface area from the band of the unit sphere between the elevations min and max in degrees. Uniform by surface area, rather than uniform by angle, means that values near the horizon are more likely than values near the poles. This matches a random pointing direction on a band of the sphere, as used in radar, antenna and surveillance models. The elevation convention is the engineering one: -90° is straight down, 0° is the horizon and +90° is straight up. The bounds must lie within [-90°, +90°].

Add Student T Random Variable

Description

Adds a Student’s t-distributed variable with df degrees of freedom, a positive integer.

Add Uniform Random Variable

Description

Adds a uniformly distributed variable on [min, max], where max must be greater than min.

Add Weibull Random Variable

Description

Adds a Weibull-distributed variable with the shape parameter shape and the scale parameter scale, both greater than 0.

Output Variables

An output variable holds a value that the simulation writes for each trial solution. The engine never assigns it. The evaluator sets it with SetValue before the solution is submitted. In a solution from CreateSolution, and in the solution that a managed optimization gives to the evaluator, each output is NaN until the evaluator sets it, in each replication. If the evaluator does not set an output, each objective and constraint that uses it is NaN, and the solution is infeasible. The engine reports no error, and an infeasible solution with a NaN objective ranks after the other infeasible solutions. Set every output before you submit a solution, or reject the solution. A solution that you add with AddEvaluated keeps the output values that you give it. The output vector, matrix and ND functions create one output variable per element with the same element names as the container decision variables.

Add Output Variable

Description

Adds an output variable named name.

Set Output Statistic Parameters

Description

Sets how the engine aggregates the output variable name across the replications of a trial. The setting is ignored when the model runs without replications. statistic is one of the values in the table below. statisticValue is used only with Percentile, where it selects the percentile as a fraction in [0, 1] (0.95 for the 95th percentile); a value outside that range is refused. The other statistics ignore it.

Notes

• The output variable must exist before this call.
• With None, the result is the same as with no call: the engine uses the mean of the replications. An output that an objective with its own statistic reads is the exception. The engine does not combine that output, so GetValue on it returns the value of the replication that completed last. See § API Documentation › Objectives › Set Objective Statistic Parameters.

Add Output Vector Variable

Description

Adds an output vector variable: n output variables. The elements are ordinary output variables, and GetOutputNames returns their names.

The simulator writes a value to each element before it submits the solution.

Notes

• Variable names: <name>@1 to <name>@n, one for each element.

Add Output Matrix Variable

Description

Adds an output matrix variable: a rows by cols matrix of output variables. The elements are ordinary output variables, and GetOutputNames returns their names.

The simulator writes a value to each element before it submits the solution.

Notes

• Variable names: <name>@<row>,<col> for each element, with 1-based row and column numbers, row by row. Each name contains a comma, so write it in brackets in an expression: [<name>@1,2].

Add Output ND Variable

Description

Adds an output N-dimensional variable: an array of output variables with the shape dims. The elements are ordinary output variables, and GetOutputNames returns their names.

The simulator writes a value to each element before it submits the solution.

Notes

• Variable names: <name>@<i1>,<i2>,... for each element, with one 1-based index for each dimension. The last index changes fastest. With two or more dimensions, each name contains a comma, so write it in brackets in an expression: [<name>@1,2,3].
• In C and C++, dims is a pointer to an array of ndims ints.

Expression Variables

An expression variable is a derived value. The engine recomputes it from its formula after every evaluation.

Add Expression Variable

Description

Adds an expression variable named name with the formula expression. The formula can reference input variables, output variables and expression variables that were added earlier. After every solution evaluation the engine recomputes the value. You can read it with OptQuestSolution.GetValue(name) and reference it in objectives, constraints, sample metrics and later expression variables. SetValue cannot assign it; the engine always derives it from the formula. The functions available in a formula are listed in § Reference › Functions and Constants Available In Expressions.

Notes

• An expression variable can reference other expression variables. The engine detects a circular dependency and reports an error when the model is initialized.
• Reference a container or special purpose variable by its element names, such as dir@theta, not by its base name. A base name makes the model fail when it initializes. See § Concepts › Names.
• An objective or a constraint that uses an expression variable is not linear, even when the formula of the expression variable is linear. StopOnSuccessfulMILP has no effect on such a model. To keep it in effect, write the formula into the objectives and constraints.

Variable Modifiers

Use the functions in this group on variables that already exist in the model. Add the variables first, then apply the modifier. Use an exclusive range to remove part of the domain of a variable. Use a selection variable to switch a group of variables on and off with one binary flag. Use an exchangeable group to declare identical items whose values you can exchange without a change to the result. Use a fix group or a float group to exploit structure in your problem by directing OptQuest to fix or float a group of variables during the search.

Add Exclusive Range to Variable

Description

Excludes the open interval (min, max) from the domain of the variable name. The values min and max themselves stay feasible; only the values strictly between them are excluded. The variable must already exist. Call the function again to exclude another interval from the same variable.

Example

model.AddContinuousVariable("speed", 0, 100);
// Never run between 40 and 60: those speeds resonate with the structure
model.AddVariableExclusiveRange("speed", 40, 60);

Add Selection Variable

Description

Adds a binary input variable named name that gates a group of other variables. When the flag is 1, the variables in selVars take part in the optimization as usual. When the flag is 0, the engine sets each of them to its lower bound for that solution. Every variable in selVars must already exist.

Example

model.AddContinuousVariable("pump_size", 10, 50);
model.AddIntegerVariable("pump_count", 1, 4);
// "use_pump" is a new binary variable. When it is 0, pump_size is 10 and pump_count is 1.
model.AddSelectionVariable("use_pump", new String[]{"pump_size", "pump_count"});

Notes

• In C and C++, selVars is a pointer to an array of n strings.
• This function gates a group of variables on one binary flag. For a k-of-n selection over a flat pool of items, use the Item Selection Variable instead.

Add Exchangeable Group

Description

Declares a group named name of identical items whose values you can exchange without a change to the result. In each trial solution that the optimizer generates, it puts the items in ascending order of their values, in the order that you list them. Thus the optimizer does not evaluate two solutions that differ only by an exchange of items. This call adds no variable to the model.

There are two forms. The flat form takes a list of variable names, one variable for each item. In each trial solution that the optimizer generates, the first variable in the list has the smallest value. The grouped form takes a list of rows. Each row holds the variables of one item, and every row has the same number of variables in the same order. The optimizer orders the rows by the value of their first variable, then by the second variable when the first values are equal, and so on. In Python one function covers both forms: a flat sequence of strings selects the flat form, and a sequence of sequences selects the grouped form. In C they are separate entry points, OQAddExchangeableGroupFlat and OQAddExchangeableGroup.

A common use is placing several identical items. For example, three identical machines in a factory, each with a location to optimize:

model.AddContinuousVariable("machine1_x", min_x, max_x);
model.AddContinuousVariable("machine1_y", min_y, max_y);
model.AddContinuousVariable("machine2_x", min_x, max_x);
model.AddContinuousVariable("machine2_y", min_y, max_y);
model.AddContinuousVariable("machine3_x", min_x, max_x);
model.AddContinuousVariable("machine3_y", min_y, max_y);
model.AddExchangeableGroup("machines", new String[][]{{"machine1_x","machine1_y"},
                                                      {"machine2_x","machine2_y"},
                                                      {"machine3_x","machine3_y"},
                                                     });

With the group, the optimizer has fewer solutions to search. Three integer variables from 0 to 4 have 125 combinations of values, and 35 of them are different when the order does not matter. Without a group, the optimizer will evaluate all 125 combinations and then stop with the termination reason OptimalFound (5). With an exchangeable group defined, it will evaluate only combinations and then stop with the same reason.

Use an exchangeable group only for items that have the same type, the same bounds and the same role in your evaluation. If the items differ but they are added to an exchangable group, for example machines with different capacities, two solutions with the two items exchanged are different solutions, but the optimizer will evaluate only one of them.

Notes

• Each member must be a decision variable that is already in the model: a continuous, integer, discrete, binary, design, enumeration, tuple, geolocation or selection variable, or an element of a vector, matrix, N-dimensional, item-selection or budgeted-selection variable under its generated name, such as v@1, m@1,2 or n@1,2,3. The values of a special purpose variable, such as dir@theta, are not accepted. Names are matched without regard to case.
• Put a variable in no more than one exchangeable group. The call accepts a variable that is already in another group, but the order of the second group can break the order of the first. In a test with the groups (a, b) and (b, c), a was greater than b in 20 of the 55 evaluated solutions.
• The optimizer evaluates a solution that you give with Add Suggested with the values that you give, in any order.
• Java returns false if the model is already initialized, if the name is not valid or is already in use, or if a member is not an accepted decision variable of the model. If the rows do not all have the same number of variables, Java throws a COptQuestException with the message “Variable definitions are of unequal length.” Python raises ValueError for rows of different lengths.
• Outside Java, the call returns the failure value, and GetLastError() returns one of these messages:
  • ERROR the model has no input variable named <name> for a member name without @ that is not a decision variable of the kinds above, for example the base name of a vector variable, a random variable, an output variable or an expression variable.
  • ERROR <name> is not a variable that a group can hold for a member name with @ that is not an element of the kinds above: for example the value dir@theta of an angle variable, the value of a mixture, sequence, choice or other special purpose variable, an element outside the size of its variable such as v@4 for a vector of 3 elements, or a name that no variable of the model generates.
  • ERROR group member names cannot be empty or contain whitespace or semicolon for an empty member name or a member name that holds whitespace or a semicolon.
  • ERROR a comma in an exchangeable group member must be followed by a digit for a member name such as a,b. In the model definition, the members of a group are joined with commas, and the engine joins a part that starts with a digit to the member before it, because a variable name cannot start with a digit. Every generated element name has a digit after each comma. This message applies only to an exchangeable group.
  • ERROR n must be at least 1 for an empty flat list, and ERROR ng must be at least 1 or ERROR nv must be at least 1 for a grouped form with no rows or with empty rows.
  • ERROR duplicate name, ERROR name cannot be empty or contain whitespace or semicolon or ERROR already initialized for the group name and the model state.
• In C and C++, group is a pointer to an array of ng groups, each a pointer to nv strings.

Add Fix Group

Description

Declares a fix group named name: AddFixGroup can help OptQuest exploit structure in a problem by directing OptQuest to fix a group of variables during the search. In some generated solutions later in the search, the variables of the fix group will be assigned values based on the best solution found so far, while the other variables are given new values. Use a fix group when you want diversity in the search to focus on the other variables.

A fix group of a set of variables gives the same trial solutions as a float group of all the other variables, so declare the smaller set.

Example

// Search the rest of the model with the three pump settings held at
// their values in the best solution found so far.
model.AddFixGroup("pumps", new String[]{"pump1", "pump2", "pump3"});

Notes

• Each member must be a decision variable that is already in the model, of the same kinds as for Add Exchangeable Group. Names are matched without regard to case.
• For each group that you add, the optimizer makes its own trial solutions. The call accepts a variable that is already in another group.
• An empty list of members is accepted.
• Java returns false if the model is already initialized, if the name is not valid or is already in use, or if a member is not an accepted decision variable of the model. Outside Java, the call returns the failure value with the messages listed for Add Exchangeable Group.
• In C and C++, variables is a pointer to an array of n strings.

Add Float Group

Description

Declares a float group named name: AddFloatGroup can help OptQuest exploit structure in a problem by directing OptQuest to float a group of variables during the search. A float group is the inverse of a fix group. In some generated solutions later in the search, the float variables will take new values, while and the other variables will be assigned values based on the best solution found so far. Use a float group when you want diversity in the search to focus on these variables.

A fix group of a set of variables gives the same trial solutions as a float group of all the other variables, so declare the smaller set.

Example

// Search the two setpoints with every other variable held at its value
// in the best solution found so far.
model.AddFloatGroup("setpoints", new String[]{"t1", "t2"});

Notes

• Each member must be a decision variable that is already in the model, of the same kinds as for Add Exchangeable Group. Names are matched without regard to case.
• For each group that you add, the optimizer makes its own trial solutions. The call accepts a variable that is already in another group.
• An empty list of members is accepted.
• Java returns false if the model is already initialized, if the name is not valid or is already in use, or if a member is not an accepted decision variable of the model. Outside Java, the call returns the failure value with the messages listed for Add Exchangeable Group.
• In C and C++, variables is a pointer to an array of n strings.

Objectives

Add Objective

Description

Adds an objective named name that minimizes or maximizes expression. AddMinimizeObjective and AddMaximizeObjective are shorthand for AddObjective with the direction MIN or MAX. direction accepts only those two tokens, in any case; the call fails for any other token. expression is a formula over input and output variables. The functions it can use are listed in § Reference › Functions and Constants Available In Expressions. When the model has more than one objective, OptQuest runs a multi-objective optimization and produces a Pareto frontier of trade-off solutions.

Set Multi-Objective Goal

Description

Sets a target range for the objective name in a multi-objective optimization. The range is from min to max inclusive. The objective must already exist. OptQuest uses the goal to decide where to search. After its first cycle of search phases, OptQuest uses the rest of the run to fill gaps between neighboring solutions on the Pareto frontier, while the frontier has at least two solutions. It fills first the largest gap next to a frontier solution whose objective values are inside the most goal ranges. When no frontier solution is inside every range, OptQuest uses the solutions that are inside the most ranges.

OptQuest does not use the goal to decide feasibility, and it does not remove the solutions outside the range from the Pareto frontier. The frontier that GetBestSolutions returns can include solutions outside the range. The setting is ignored in a single-objective model.

Set Objective Statistic Parameters

Description

Sets how the engine aggregates the objective name across the replications of a trial. The setting is ignored when the model runs without replications. statistic is one of the values in the table below. statisticValue is used only with Percentile, where it selects the percentile as a fraction in [0, 1] (0.95 for the 95th percentile); a value outside that range is refused. The other statistics ignore it.

Notes

• The objective must exist before this call.
• With None, or with no call, the engine combines each output that the objective reads across the replications, with the statistic of that output (the mean unless SetOutputStatistic sets another). Then it computes the objective expression once from those values. For an objective y*y and two replications with y = 1 and y = 3, the objective is 4.0.
• With any other statistic, the engine computes the objective expression in each replication and applies the statistic to those values. For the same replications, Mean gives 5.0 and Max gives 9.0. The engine does not combine an output that such an objective reads, so GetValue on that output returns the value of the replication that completed last.
• A statistic on the objective and a statistic other than None on an output that the objective reads are refused together. The model fails when it initializes, with the message “You have defined a statistic on a COptQuestStringObjective and the expression contains a COptQuestUserControlledVariable that also contains a statistic.”

Set Objective Confidence Parameters

Description

Sets the early-stopping confidence parameters for the objective name in a variable-replication optimization. The setting is ignored when the replication count is fixed or the model runs without replications. The parameters are:

• ctype: the confidence type, from the first table below.
• clevel: the confidence level, from the second table below.
• epct: the acceptable error, as a fraction of the mean of the replications. It must be greater than 0 and less than 1. For 5 percent, pass 0.05. The engine checks the value when the model initializes, not at this call. With a value outside that range, the run fails with the message “Bad value for the replication confidence error percent.”

With these set, OptQuest stops replicating a trial solution when the half-width of the confidence interval at the level clevel is at most epct times the absolute value of the mean of the replications.

Confidence testing works only with the mean. If the objective, or an output that it uses, has a statistic other than Mean, the model fails when it initializes, with the message “You must use the Mean statistic when using replication confidence.” With no statistic set, the engine uses the mean.

ctype selects one of two rules. Type 1 continues replicating until the confidence level is reached or the maximum number of replications is run. Type 2 also stops early when OptQuest determines that the current solution cannot fall within the confidence interval of the best solution. Type 2 applies to single-objective models.

clevel selects the confidence level of the interval:

Notes

• The objective must exist before this call.

Constraints

Add Constraint

Description

Adds a constraint named name with the formula expression. The formula can reference input variables, output variables, expression variables and objectives, and it can be linear or non-linear. The functions it can use are listed in § Reference › Functions and Constants Available In Expressions.

Notes

• A constraint that references only input variables is enforced before the evaluator runs, so the simulator never sees an infeasible input. A constraint that references an output variable is checked after evaluation, and the solution is marked infeasible if it fails. See § Concepts › Model Components › Constraints.
• A constraint over the variable names of a special purpose variable, other than an Item Selection or a Budgeted Selection variable, is checked after evaluation. See § Decision Variables › Special Purpose Variables: Common Behavior.
• Reference a container or special purpose variable by its element names, such as dir@theta, not by its base name. A base name, as in dir <= 7, makes the model fail when it initializes. See § Concepts › Names.
• The engine reads < as <= and > as >=. A solution on the bound satisfies x + y < 7.
• When the bound is a constant, the engine accepts a small violation. For a linear constraint over input variables only, the tolerance is 1e-5 for each variable in the constraint, and the engine applies it to the value of the expression with its coefficients. x + y <= 7 accepts x + y up to 7.00002, and 10*x + 10*y <= 70 accepts 10x + 10y up to 70.00002. For a constraint that reads an output variable, and for a non-linear constraint, the tolerance is 1e-5 on the value of the expression. The engine uses the same tolerances for >= and =.

Adaptive Sampling Configuration

Add Sampling Metric

Description

Adds a sampling metric named name for Adaptive Sampling. responseExpression is a formula over input and output variables that gives the response the sampler tracks. errorExpression is a formula that gives the uncertainty (error) of that response; pass "0" when the response is exact. The functions the formulas can use are listed in § Reference › Functions and Constants Available In Expressions. The engine creates two values, <name>@response and <name>@error, that you can read from a solution and reference in expressions.

model.AddSampleMetric("metric", response, error);

This creates metric@response and metric@error.

Notes

• Both expressions are required. The binding sends the two to the engine on one line, joined by ;, so the call refuses an empty or whitespace-only responseExpression or errorExpression, and refuses a ; inside either.
• The engine uses the metric only during Adaptive Sampling and ignores it in an optimization.

Set Sampling Method

Description

Sets the sampling method for Adaptive Sampling. method is a bitwise OR of the flags in the table below. The flags determine how the sampling engine builds its internal model and selects the next sample points. See § Adaptive Sampling for the strategies.

The Stochastic<Method> constants (StochasticVariance, StochasticUniform, StochasticZero, StochasticGradient, StochasticMin, StochasticMax, StochasticRDS) are shorthand for Stochastic | Async | <Method>, the usual combination for a stochastic simulation. Every language has the same names.

Sampling Method Categories

The flags fall into two groups. The model-building flags (Stochastic, Dynamic, Async) control how the engine builds its internal model. The feedback flags (Uniform, Variance, Zero, Gradient, Min, Max, RDS) control how it selects the next sample point.

Model-Building Methods

• Stochastic: When this flag is off (the default), the engine searches for the single best next sample point, which can focus too narrowly and can be expensive. When it is on, the engine draws the next point at random from the domain, weighted by predicted quality. The engine then explores more of the domain and produces points faster.
• Dynamic: For a fast simulation, building the internal model can take longer than an evaluation. When this flag is on, the engine monitors the evaluation times and generates several sample points at once to keep the simulations busy, at some cost in model accuracy.
• Async: When this flag is on, the engine builds the internal model on a background thread, so model building and evaluation overlap. If a new point is requested before the model is updated, the engine uses the previous model. With a fast simulation, the engine completes more evaluations in the same time when this flag is on.

Feedback Methods

These flags define the criterion for the next sample point, based on the metric’s estimated value and uncertainty. Several feedback flags can be combined with bitwise OR. The engine then produces one sample per enabled flag per request.

• Uniform: distributes the samples evenly across the domain with a space-filling sequence and ignores the metric. This is the fastest way to cover the domain.
• Variance: samples where the variance is highest (the least-known areas). With this flag the engine reduces the global variance and builds a response surface that is accurate everywhere.
• Zero: samples where the metric is closest to zero, to map boundaries and transition zones.
• Gradient: samples where the response changes fastest.
• Min: samples densely where the metric is smallest.
• Max: samples densely where the metric is largest.
• RDS: samples where more points are needed to reach the wanted probability distribution. See § Reference › Probability Distributions. When RDS is included, you must also set the wanted distribution with one of the SetSampleRDS* functions.

Set Sampling Variogram

Description

Sets the variogram that the engine uses to build the internal surrogate model during Adaptive Sampling. By default the engine chooses a variogram with a heuristic. Call this function to select one of the variograms in the table below instead. Most users do not need this function: use the default unless OptTek support advises a different variogram.