OptQuest 10 Optimization API

The OptQuest 10 API introduces a unified declarative interface across Java, C#, C++, C and Python, ensuring consistency and ease of use. In Java, the legacy OptQuest 9 API remains supported with no plans for deprecation. The OptQuest 10 API is the exclusive interface for accessing the OptQuest Engine in C#, C++, C, and Python.

Overview

What Is Optimization?

Optimization technology empowers analysts to identify optimal solutions for complex business and engineering challenges by systematically evaluating decision variables against defined objectives and constraints.

The OptQuest® Engine, developed by OptTek Systems, Inc., is a powerful optimization tool designed to address critical questions, including:

• Resource Allocation: What is the maximum return on budgets distributed across various uses, considering uncertainties in product demand, machine reliability, and raw material availability?
• Production Scheduling: What is the most efficient machine configuration for production scheduling under fluctuating demand and operational conditions?
• Material Flow: What are the optimal locations and release sequences for raw materials to minimize waiting times?
• Workforce Planning: What are the ideal workforce allocations to reduce lead times and labor costs?
• Portfolio Optimization: What are the optimal allocations for an investment portfolio to maximize returns?

Manually evaluating all possible scenarios is often impractical or infeasible due to time and computational constraints. The OptQuest Engine overcomes these limitations by employing a robust search algorithm that efficiently identifies optimal decisions. This enables users to rapidly determine the variable combinations that best achieve their objectives, eliminating the inefficiencies of trial-and-error approaches.

OptQuest Engine

Search Algorithm and Metaheuristics

The OptQuest Engine employs a sophisticated search algorithm driven by metaheuristics to efficiently identify high-quality solutions. This algorithm leverages historical solution performance to recombine effective solutions, generating better solutions. It is designed to avoid getting stuck in local optima and remains robust against noisy or uncertain model data.

Algorithm Composition

The engine integrates multiple optimization techniques, including:

• Tabu Search: Prevents revisiting recently explored solutions to maintain search diversity.
• Scatter Search: Combines solutions to explore promising regions of the solution space.
• Integer, Linear, and Mixed Integer Programming: Optimally solves problems with discrete decision variables.

This composite approach forms a highly efficient, general-purpose global optimization algorithm, delivering superior performance compared to traditional methods. OptTek’s technology achieves better solution identification faster than competing approaches.

Key Features

• Flexibility: Adapts to a wide range of problem types and structures.
• Intelligence: Dynamically adjusts search strategies based on problem characteristics.
• Ease of Use: Provides a streamlined interface for integration and operation.
• Reliability: Recognized by industry experts as the most dependable optimization software available.

Black-Box Optimization

The OptQuest Engine operates as a “black-box” global optimization solver, requiring minimal user configuration. It employs a diverse set of heuristics and metaheuristics to ensure rapid convergence to globally optimal solutions. The algorithm is guaranteed to perform effectively across all problem domains, making it a versatile tool for complex optimization challenges.

Upgrading from the OptQuest 9 API

The OptQuest 10 API was developed to streamline the definition and management of optimization models and includes native support for parallel execution, eliminating the need for manual thread or queue management as well as provide a consistent pattern across all supported languages.

The transition from the OptQuest 9 API to the OptQuest 10 API is designed to be seamless, offering a direct mapping of functionality with reduced client-side management overhead. In OptQuest 9, the primary interface was the COptQuestOptmization object, where clients defined a subclass with custom virtual function overrides to specify the optimization model and perform solution evaluation using a dependency-injection approach. The OptQuest 10 API encapsulates the optimization model within an opaque, immutable OptQuestModel object, with solution evaluation driven by callback functions.

In OptQuest 9, clients were responsible for creating and managing the lifecycle of objects representing decision variables, objectives, and constraints, which were then added to the custom COptQuestOptmization subclass. The OptQuest 10 API shifts this responsibility to the OptQuestModel, which internally manages these objects. Clients interact with decision variables, objectives, and constraints using unique identifiers rather than direct object references. This encapsulation enhances functionality, enabling features such as reliable optimization pausing and resuming, as well as built-in concurrent evaluation for improved performance in parallel computing environments.

A key change in the OptQuest 10 API is the redefinition of objectives. Unlike OptQuest 9, where objectives could directly receive values from simulations, objectives in OptQuest 10 are strictly defined as expressions composed of input and output variables. To replicate the OptQuest 9 behavior of assigning a simulation output to an objective, clients should define an output variable to capture the simulation result and set the objective expression to reference that output variable. For scenarios replacing a COptQuestUserControlledObjective tied to a simulation output in OptQuest 9, the OptQuest 10 API requires defining an output variable to hold the simulation result and configuring the objective to use this variable in its expression. This approach maintains equivalent functionality while aligning with the new API’s declarative structure.

//to be collected from the simulation
OptQuestModel.AddOutputVariable("simOutput"); 

//the expression for the objective is just the output value
OptQuestModel.AddMinimizeObjective("objective","simOutput"); 

The examples below provides a quick reference to map the the OptQuest 9 API to the OptQuest 10 API.

New Optimization

OptQuest 9

class MyOptimization extends COptQuestOptimization {
 //remember to pass into this object a reference 
 //to all the variables and objectives
 public void Evaluate(COptQuestSolution sol) 
   throws COptQuestException {
    double myVarValue = sol.GetVariableValue(myVar);
    double myOutputValue = //run my simulation;
    sol.SetVariableValue(myOutput, myOutputValue);
 }
}

MyOptimization myOpt = new MyOptimization();

OptQuest 10

OptQuestModel myModel = new OptQuestModel();

Add Decision Variable

OptQuest 9

COptQuestVariable myVar = new COptQuestContinuousVariable(min, max);
myOpt.AddVariable(myVar);

OptQuest 10

myModel.AddContinuousVariable("myVar", min, max);

Add Output Variable

OptQuest 9

COptQuestVariable myOutput = new COptQuestUserControlledVariable();
myOpt.AddVariable(myOutput);

OptQuest 10

myModel.AddOutput("myOutput");

Add Single Objective

OptQuest 9

class MyObjective extends 
 COptQuestUserControlledObjective {
 //remember to pass into this object a reference to all the variables and objectives
 protected void calculateObjective(Solution sol) 
  throws COptQuestException {
   double myVarValue = sol.GetVariableValue(myVar);
   double myOutputValue = sol.GetVariableValue(myOutput);
   double myObjValue = myVarValue+myOutputValue;
   sol.SetObjectiveValue(myObj, myObjValue);
 }
}
COptQuestSingleObjective myObj = new MyObjective()
myObj.SetMinimize();
myOpt.AddObjective(myObj)

OptQuest 10

myModel.AddMinimizeObjective("myObj", "myVar + myOutput");

Add Multi Objective

OptQuest 9

class MyObjective1 extends COptQuestUserControlledObjective {
 //remember to pass into this object a reference to all the variables and objectives
 protected void calculateObjective(Solution sol) 
  throws COptQuestException {
   double myVarValue = sol.GetVariableValue(myVar);
   double myOutputValue = sol.GetVariableValue(myOutput);
   double myObjValue = myVarValue - myOutputValue;
   sol.SetObjectiveValue(myObj1, myObjValue);
 }
}

class MyObjective2 extends 
 COptQuestUserControlledObjective {
 //remember to pass into this object a reference to all the variables and objectives
 protected void calculateObjective(Solution sol) 
  throws COptQuestException {
   double myVarValue = sol.GetVariableValue(myVar);
   double myOutputValue = sol.GetVariableValue(myOutput);
   double myObjValue = myVarValue / myOutputValue;
   sol.SetObjectiveValue(myObj2, myObjValue);
 }
}

COptQuestSingleObjective myObj1 = new MyObjecitve1()
myObj.SetMinimize();
COptQuestSingleObjective myObj2 = new MyObjecitve2()
myObj.SetMaximize();
COptQuestFrontierMultiObjective myMultiObj;
myMultiObj.AddObjective(myObj1)
myMultiObj.AddObjective(myObj2)
myOpt.AddObjective(myMultiObj)

OptQuest 10

myModel.AddMinimizeObjective("myObj1", "myVar - myOutput");
myModel.AddMaximizebjective("myObj2", "myVar / myOutput");

Add Constraint

OptQuest 9

COptQuestConstraint myConstraint = new COptQuestLEConstraint(5);
myConstraint.AddVariable(myVar, 1);
myConstraint.AddVariable(myOutput, -3);
myOpt.AddConstraint(myConstraint);

OptQuest 10

myModel.AddConstraint("myConstraint", "myVar - 3 * myOutput <= 5");

Evaluate Solution

OptQuest 9

Already defined in the Optimization object

OptQuest 10

class MyEvaluator implments IOptQuestEvaluator {
 public bool Evaluate(OptQuestSolution sol) {
  double myVarValue=sol.GetValue("myVar");
  double myOutputValue = //run simulation here;
  sol.SetValue("myOutput",myOutputValue);
 }
}

Run Optimization

OptQuest 9

myOpt.SetMaximumIteration(50);
myOpt.Optimize();

OptQuest 10

myModel.Optimize(50, new MyEvaluator());

Get Best Solution

OptQuest 9

COptQuestSolution best = myOpt.GetBestSolution();
double myBestVal = best.GetVariableValue(myVar);
double myBestObj = best.GetObjectiveValue(myObj);

OptQuest 10

OptQuestSolution best = myModel.GetBestSolutions().getFirst();
double myBestVal = best.GetValue("myVar");
double myBestObj = best.GetValue("myObj");

Get Pareto Frontier of Solutions

OptQuest 9

for (COptQuestSolution frontier : myOpt.GetPatternFrontier()){
 double myBestObj1 = frontier.GetObjectiveValue(myObj1);
 double myBestObj2 = frontier.GetObjectiveValue(myObj2);
} 

OptQuest 10

for (OptQuestSolution frontier : myOpt.GetBestSolutions()){
 double myBestObj1 = frontier.GetValue("myObj1");
 double myBestObj2 = frontier.GetValue("myObj2");
} 

Error Handling

In the Java implementation, exceptions are thrown when errors occur. The exception can be examined along with the call stack to understand the problem. In the C#, C++, and C implementations, if a function encounters an error, it will return an error flag (usually false), and the full description of the error can be retrieved with the GetLastError() function which returns the same information that would be in the Java exception.

Model Optimization

In the OptQuest Engine, a model is a structured representation of an optimization problem, comprising one or more decision variables, one or more objectives, and, optionally, one or more constraints. OptQuest leverages advanced metaheuristic algorithms, including tabu search, scatter search, and neural network-enhanced strategies, to navigate the constrained variable space and identify optimal solutions. When a single objective is defined, OptQuest iteratively refines a single “best” solution to maximize or minimize the objective. For models with multiple objectives, OptQuest generates a Pareto frontier—a set of solutions representing the optimal trade-offs among competing objectives.

Decision Variables

Decision variables form the foundation of an OptQuest model, representing the decision parameters to be optimized. Each variable is characterized by the range of values, which may be continuous (e.g., a real number between 0 and 100), discrete (e.g., integers from 1 to 10), or categorical (e.g., a set of predefined options). Special-purpose data types are also supported, including tuples, geolocations (latitude, longitude), and permutations.

Objectives

Objectives are mathematical expressions that quantify the goals of the optimization problem, constructed from one or more decision variables and/or output variables derived from simulations. Each objective is associated with a direction:

• Maximization: Seeks the highest possible value of the objective function (e.g., maximizing profit).
• Minimization: Seeks the lowest possible value (e.g., minimizing cost).

For example, an objective might be defined as maximize: 2*VariableA + 3*VariableB, where VariableA and VariableB are input or output variables. In multi-objective scenarios, OptQuest identifies a set of non-dominated solutions, balancing trade-offs to provide a comprehensive view of the frontier of equally optimal outcomes.

Constraints

Constraints are mathematical expressions that define the feasible region of the solution space by imposing limits on variables, objectives, or their combinations. OptQuest supports:

• Linear Constraints: Expressions of the form a*VariableA + b*VariableB ≤ c, where coefficients and bounds are constants.
• Non-Linear Constraints: More complex relationships, such as VariableA**2 + VariableB ≤ 100, accommodating real-world problem complexities.

Constraints ensure that solutions remain practical and relevant, filtering out infeasible combinations during the optimization process. They are defined within the OptQuestModel and can reference both input variables and output expressions.

Optimization Process

OptQuest’s metaheuristic algorithms systematically explore the variable space, guided by the defined objectives and constraints. The engine employs a composite search strategy that combines global exploration with local refinement, ensuring efficient convergence to optimal or near-optimal solutions. For multi-objective optimization, the Pareto frontier is iteratively updated to reflect the best trade-offs, enabling users to select solutions that align with their priorities.

The “Optimization Loop”

The OptQuest Engine’s combination of metaheuristic algorithms and machine learning techniques to efficiently navigate complex solution spaces and identify optimal values for one or more objective functions. OptQuest excels in optimizing arbitrary functions, including Integer Programs, Linear Programs, and Mixed Integer Linear Programs. It is particularly well-suited for “black-box” simulation-optimization, where objective functions incorporate outputs from complex simulations. OptQuest can work with any type of objective function, including non-convex, discontinuous, or non-differentiable functions.

The optimization process in OptQuest follows an iterative loop, described as follows:

1. Generate: Construct a trial solution by assigning values to input variables within their defined domains, taking constraints into account.
2. Evaluate: Compute output values using simulation models, complex functions, or analytical expressions based on the trial solution’s input values.
3. Learn: Assess the evaluated trial solution to gain insights into the objective function’s behavior and the solution space’s characteristics.
4. Refine: Leverage accumulated knowledge to generate a new trial solution, strategically guiding the search toward improved objective values.

With each iteration, OptQuest refines its understanding of the solution space, using metaheuristics such as tabu search, scatter search, and neural network-driven pattern recognition to converge toward optimal or near-optimal solutions. This adaptive process ensures robust performance across diverse problem types, including those with noisy or uncertain data, by iteratively improving solution quality without requiring manual intervention or problem-specific tuning.

Managed Optimization

Managed Optimization simplifies the optimization process by automating the “Optimization Loop” for common use cases, reducing the need for custom implementation.

Simple Optimization

When objectives and constraints are direct functions of input variables (no external simulation), OptQuest can iterate through the optimization loop without requiring user-defined evaluation logic. Users specify 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

For scenarios requiring simulation outputs, users provide a callback function to evaluate solutions. OptQuest invokes this function during each iteration.

OptQuestModel model = new OptQuestModel();

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

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

Concurrent Optimization

To optimize computationally expensive simulations, OptQuest supports concurrent evaluation of multiple solutions. Users specify the number of parallel threads, and OptQuest manages the creation and evaluation of solutions across these threads and handles the synchronization of the generation and learning 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);

This approach significantly reduces runtime for resource-intensive evaluations by leveraging parallel processing capabilities.

Asynchronous Managed Optimization

For long-running optimizations, OptQuest supports asynchronous execution to keep the main application responsive. A communication channel enables monitoring and control of the optimization process. This ensures seamless integration into interactive applications, with the ability to pause or stop optimizations as needed.

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(() -> {
    // Blocks until 100 solutions are evaluated or interrupted
    model.optimize(channel, 100, customEvaluation);
}).start();

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

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

Manual Optimization

For applications requiring fine-grained control, OptQuest provides direct access to each step of the Optimization Loop, enabling custom implementations tailored to complex or high-performance computing (HPC) scenarios. This flexible interface supports custom workflows, including concurrent or distributed optimization, by allowing developers to manage solution creation, evaluation, and submission explicitly.

OptQuestModel model = new OptQuestModel();

// Create a trial solution
OptQuestSolution solution = model.createSolution();

// Check if the solution is valid
if (solution.isValid()) {
    // Retrieve input values
    // e.g., double value = solution.getValue(inputVariableId);

    // Compute outputs based on inputs (e.g., via simulation)
    // ...

    // Set output values
    // e.g., solution.setValue(outputVariableId, computedValue);

    // Submit solution for learning
    solution.submit();

    // Optionally retrieve the processed solution
    solution.update();
    // Process the updated solution as needed
}

Adaptive Sampling

Introduced in OptQuest 10, Adaptive Sampling provides a powerful alternative to traditional optimization for exploring the variable design space. Unlike optimization, which seeks a single optimal point (e.g., a minimum or maximum), Adaptive Sampling aims to comprehensively characterize the response surface across the entire domain, efficiently capturing global trade-offs and behaviors.

The Adaptive Sampling engine operates similarly to the optimization engine by generating trial solutions, evaluating them, and using the results to guide further exploration. However, while optimization focuses on converging to an optimal solution, Adaptive Sampling prioritizes building an accurate model of the response surface with minimal evaluations. This makes it ideal for scenarios where understanding the domain’s behavior—such as identifying trends, boundaries, or regions of interest—is the primary goal.

Adaptive Sampling monitors a user-defined metric, which consists of a value and an associated uncertainty (or error). The engine constructs an internal model of this metric’s response across the domain, predicts the response in unexplored areas, and strategically selects the next solution to evaluate based on what is deemed most “interesting.” Each evaluated solution refines the model, enabling increasingly informed selections.

Sampling Loop

The Adaptive Sampling process follows an iterative loop:

1. Generate: Create a trial solution by assigning values to input variables within their defined domains.
2. Evaluate: Compute output values using simulation models, complex functions, or analytical expressions based on the trial solution’s inputs.
3. Model: Update an internal model of the response surface using all evaluated solutions to predict behavior across the domain.
4. Select: Identify the most “interesting” region of the domain based on the current internal model, prioritizing areas that maximize information gain.
5. Refine: Generate a new trial solution targeting the selected region to enhance the model’s accuracy.

Sampling Strategies

Adaptive Sampling offers multiple strategies to define “interesting” regions, tailored to different use cases:

• Uniform Sampling: The simplest and fastest approach, this method generates solutions to evenly cover the domain, progressively increasing sample density until termination. It does not monitor the metric response, making it suitable for initial domain exploration.
• Variance-Based Sampling: Designed for stochastic simulations with inherent uncertainty, this strategy evaluates both the response and its error for each solution, accounting for correlations between solutions. It selects the next solution in the region with the highest uncertainty (least-known area) to maximally reduce global response uncertainty.
• Boundary-Finding Sampling: This mode targets regions where the metric response is predicted to cross a specific value (e.g., zero). Consider the case of creating a map of radio transmitter signal strength in a city. By defining a metric such as signal - 0.5, the engine increases sample density along the contour where the signal equals 0.5, effectively mapping transition boundaries (e.g., where signal strength drops below 50%).
• Gradient-Based Sampling: Focuses on regions with the steepest response changes by targeting areas with the largest gradient. This is useful for identifying dynamic or rapidly changing parts of the domain.
• Minimum Response Sampling: Similar to optimization but with a sampling focus, this strategy increases sample density in regions where the response is smallest. It provides a detailed characterization of low-response areas without solely seeking the exact minimum.
• Maximum Response Sampling: Analogous to minimum response sampling, this approach biases sampling toward regions with the largest response values, enhancing the accuracy of the response surface in high-response areas without focusing exclusively on the maximum.

Applications

Adaptive Sampling is particularly valuable for applications requiring a holistic understanding of a domain, such as:

• Characterizing trade-offs in multi-variable systems.
• Mapping boundaries or transition zones.
• Exploring stochastic or noisy simulations to quantify uncertainty.
• Identifying regions of rapid change or extreme responses for further analysis.

Stochastic Simulation Optimization

OptQuest is designed to handle stochastic simulations, where identical inputs may produce varying outputs due to inherent randomness. To optimize such simulations, OptQuest offers two approaches:

• Fixed Replications: Executes a predefined number of simulation replications for each trial solution to account for variability and ensure robust evaluation.
• Variable Replications with Convergence Monitoring: Dynamically adjusts the number of replications by monitoring a statistical measure of the objective. Replications continue until a specified confidence interval is achieved or a maximum replication limit is reached.

These methods ensure reliable optimization results, even in the presence of stochastic noise, by balancing computational efficiency with statistical accuracy.

API Documentation

This section provides detailed documentation for the OptQuest 10 API functions, covering their definitions in Java, C#, C++, and C. Unless otherwise specified, the Java, C#, and C++ implementations share identical behavior. In the C API, manual resource cleanup is often required, and such cases are explicitly highlighted to ensure proper usage. A custom interface can be written in any language that supports C bindings using the C interface.

Model Definition API Functions

To prepare a model for optimization or adaptive sampling in OptQuest 10, the model must be defined using a structured sequence of API functions. The typical workflow is as follows:

1. Create the Model: Initialize a new OptQuestModel to serve as the container for all model components.
2. Add Input Variables: Define one or more input variables to specify the search space that OptQuest will explore.
3. Add Output Variables (Optional): Include zero or more output variables to represent results from simulations or complex computations that cannot be expressed as simple mathematical functions of input variables.
4. Define Objectives: Specify one or more objectives as mathematical expressions involving input and/or output variables, each associated with a maximization or minimization goal.
5. Define Constraints (Optional): Add zero or more constraints as mathematical expressions of variables to restrict the feasible region of the search space.

Create Model

Description

Initializes and allocates resources for a new OptQuestModel object, which serves as the foundation for defining and optimizing a model in OptQuest 10. This function must be called before adding variables, objectives, or constraints to the model.

Notes

• In Java, C#, C++, and Python the constructor automatically handles resource allocation.
• In C, OQCreateModel() returns a handle (HOptQuestModel) to the model, and the client is responsible for manually freeing resources using the appropriate cleanup function (e.g., OQDeleteModel()).

Delete Model

Description

Releases the resources associated with an OptQuestModel object. In Java and C#, memory management is handled automatically by the garbage collector. In C++ and Python, the destructor of the OptQuestModel class manages resource cleanup when the object goes out of scope. In C, the client must explicitly call OQDeleteModel to free the resources associated with the HOptQuestModel handle.

Notes

• In C++, ensure the OptQuestModel object is properly scoped to trigger the destructor automatically.

Set License

Description

Configures the OptQuestModel with a license key provided by an OptTek representative. If an empty string is passed, the model operates in “demo” mode, limiting optimization to 50 iterations regardless of the requested number.

Returns

• Java, C#, C++, Python: Returns true on success, false on failure. Error details can be retrieved using GetLastError().
• C: Returns a non-zero value on success, zero on failure. Error details can be retrieved using OQGetLastError().

Notes

• In C, the license string must be null-terminated.

Log Setup

Description

Directs OptQuest to generate a log file at the specified filespec path, detailing the model’s configuration. This log is primarily used for debugging or providing model information when collaborating with OptTek support.

Returns

• Java, C#, C++, Python: Returns true on success, false on failure. Error details can be retrieved using GetLastError().
• C: Returns a non-zero value on success, zero on failure. Error details can be retrieved using OQGetLastError().

Notes

• The filespecmust be a valid, writable file path.
• In C, the filespecstring must be null-terminated.

Log Solutions

Description

Instructs OptQuest to create a log file at the specified filespecpath, recording details of solutions evaluated during optimization or sampling. This log is typically used to share solution data with OptTek support for troubleshooting or analysis.

Returns

• Java, C#, C++, Python: Returns true on success, false on failure. Error details can be retrieved using GetLastError().
• C: Returns a non-zero value on success, zero on failure. Error details can be retrieved using OQGetLastError().

Notes

• Ensure the filespecpath is valid and writable.
• In C, the filespecstring must be null-terminated.

Add Continuous Variable

Description

Adds a continuous input variable identified by name, with a domain bounded inclusively by min and max. The name must be unique across all model components (inputs, outputs, constraints, objectives) and must not contain whitespace.

Returns

• Java, C#, C++, Python: Returns true on success, false on failure. Error details can be retrieved using GetLastError().
• C: Returns a non-zero value on success, zero on failure. Error details can be retrieved using OQGetLastError().

Notes

• In C, the name string must be null-terminated.

Add Integer Variable

Description

Adds an integer input variable identified by name, with a domain of integer values bounded inclusively by min and max. The name must be unique and free of whitespace.

Returns

• Java, C#, C++, Python: Returns true on success, false on failure. Error details can be retrieved using GetLastError().
• C: Returns a non-zero value on success, zero on failure. Error details can be retrieved using OQGetLastError().

Notes

• In C, the name string must be null-terminated.

Add Discrete Variable

Description

Adds a discrete input variable identified by name, with values ranging from min to max (inclusive) in increments of step. The range must accommodate an integer number of steps. The name must be unique and free of whitespace.

Returns

• Java, C#, C++, Python: Returns true on success, false on failure. Error details can be retrieved using GetLastError().
• C: Returns a non-zero value on success, zero on failure. Error details can be retrieved using OQGetLastError().

Notes

• In C, the name string must be null-terminated.

Add Binary Variable

Description

Adds a binary input variable identified by name, restricted to values 0 or 1. The name must be unique and free of whitespace.

Returns

• Java, C#, C++, Python: Returns true on success, false on failure. Error details can be retrieved using GetLastError().
• C: Returns a non-zero value on success, zero on failure. Error details can be retrieved using OQGetLastError().

Notes

• In C, the name string must be null-terminated.

Add Design Variable

Description

Adds a design input variable identified by name, representing num distinct choices (e.g., indices {1, 2, 3} mapping to options like {red, blue, green}). The name must be unique and free of whitespace.

Returns

• Java, C#, C++, Python: Returns true on success, false on failure. Error details can be retrieved using GetLastError().
• C: Returns a non-zero value on success, zero on failure. Error details can be retrieved using OQGetLastError().

Notes

• In C, the name string must be null-terminated.

Add Enumeration Variable

Description

Adds an enumeration input variable identified by name, restricted to the discrete values in items. The name must be unique and free of whitespace.

Returns

• Java, C#, C++, Python: Returns true on success, false on failure. Error details can be retrieved using GetLastError().
• C: Returns a non-zero value on success, zero on failure. Error details can be retrieved using OQGetLastError().

Notes

• In C, items is an array of n doubles, and name must be null-terminated.

Add Permutation Variable

Description

Adds a permutation input variable identified by group, representing a unique ordering of the elements in names. Each element in names must be unique, and the variable generates permutations of these elements for optimization. The group and all names must be unique and free of whitespace. OptQuest will create a decision variable for each element in names prefixed by the group label.

Example

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

Will create three decision variables named, group_a, group_b, group_c. During the generate step of the optimization loop, OptQuest will fill the values of those variables with the order they appear in the permutation to test. For example, if group_a=1, group_b=3, and group_c=2, then the solution evaluation should compute the outputs based on the ordering {a,c,b}

Returns

• Java, C#, C++, Python: Returns true on success, false on failure. Error details can be retrieved using GetLastError().
• C: Returns a non-zero value on success, zero on failure. Error details can be retrieved using OQGetLastError().

Notes

• In C, group and each string in names must be null-terminated; names is an array of n strings.

Add Tuple Variable

Description

Adds a tuple input variable identified by name, restricted to the discrete tuples in tuples. Each tuple represents a point in n-dimensional space, where Euclidean distance between tuples is considered during optimization. The name must be unique and free of whitespace.

Returns

• Java, C#, C++, Python: Returns true on success, false on failure. Error details can be retrieved using GetLastError().
• C: Returns a non-zero value on success, zero on failure. Error details can be retrieved using OQGetLastError().

Notes

• In C++ and C, tuples is an array of nt tuples, each with nv values; name must be null-terminated.

Add Geolocation Variable

Description

Adds a geolocation input variable identified by name, restricted to the discrete (latitude, longitude) pairs in locations. Angular distance between locations on a sphere is considered during optimization. The name must be unique and free of whitespace.

Returns

• Java, C#, C++, Python: Returns true on success, false on failure. Error details can be retrieved using GetLastError().
• C: Returns a non-zero value on success, zero on failure. Error details can be retrieved using OQGetLastError().

Notes

• In C++ and C, locations is an array of nl pairs; name must be null-terminated.

Add Exclusive Range to Variable

Description

Excludes the range from min to max (inclusive) from the domain of the variable identified by name. The variable must already exist. Multiple exclusive ranges can be added by calling this function repeatedly. The name must match an existing variable and be free of whitespace.

Returns

• Java, C#, C++, Python: Returns true on success, false on failure. Error details can be retrieved using GetLastError().
• C: Returns a non-zero value on success, zero on failure. Error details can be retrieved using OQGetLastError().

Notes

• In C, the name string must be null-terminated.

Add Output Variable

Description

Adds an output variable identified by name to the OptQuestModel. Unlike input variables, output variables are not assigned values by OptQuest during optimization or sampling. Instead, their values are provided by the client during solution evaluation, typically as results from simulations or complex computations. The name must be unique across all model components (inputs, outputs, constraints, objectives) and must not contain whitespace.

Returns

• Java, C#, C++, Python: Returns true on success, false on failure. Error details can be retrieved using GetLastError().
• C: Returns a non-zero value on success, zero on failure. Error details can be retrieved using OQGetLastError().

Notes

• In C, the name string must be null-terminated.

Set Output Statistic Parameters

Description

Configures the statistical aggregation method for the output variable identified by name when performing multiple replications in stochastic simulations. This setting is ignored for single-replication optimizations. The options for the statistic value are shown in the table below. The statisticValue is only used for selecting the percentile, it is ignored for the other statistic choices

Returns

• Java, C#, C++, Python: Returns true on success, false on failure. Error details can be retrieved using GetLastError().
• C: Returns a non-zero value on success, zero on failure. Error details can be retrieved using OQGetLastError().

Notes

• The output variable must exist before calling this function.
• In C, the name string must be null-terminated.

Add Objective

Description

Adds an objective to the OptQuestModel, identified by name, with the goal of either minimizing or maximizing the specified expression. The expression is a mathematical formula referencing input and/or output variables by their names, supporting functions outlined in the Supported Mathematical Functions section. When multiple objectives are defined, OptQuest automatically performs multi-objective optimization, generating a Pareto-efficient frontier of solutions representing optimal trade-offs.

Returns

• Java, C#, C++, Python: Returns true on success, false on failure. Error details can be retrieved using GetLastError().
• C: Returns a non-zero value on success, zero on failure. Error details can be retrieved using OQGetLastError().

Notes

• The name must be unique across all model components and free of whitespace.
• In C, both name and expression strings must be null-terminated.

Set Multi-Objective Goal

Description

Applicable only in multi-objective optimization (ignored in single-objective cases), this function sets a target range for the objective identified by name, directing OptQuest to prioritize solutions on the Pareto frontier where the objective’s value lies between min and max (inclusive). The objective must already exist in the model. If multiple objectives have goals, OptQuest focuses the search on frontier regions satisfying all goals. If the frontier cannot satisfy all goals simultaneously, OptQuest randomly selects a subset of goals to prioritize in each iteration.

Returns

• Java, C#, C++, Python: Returns true on success, false on failure. Error details can be retrieved using GetLastError().
• C: Returns a non-zero value on success, zero on failure. Error details can be retrieved using OQGetLastError().

Notes

• The name must match an existing objective.
• In C, the name string must be null-terminated.

Set Objective Statistic Parameters

Description

Configures the statistical aggregation method for the objective identified by name when performing multiple replications in stochastic simulations. This setting is ignored for single-replication optimizations. The options for the statistic value are shown in the table below. The statisticValue is only used for selecting the percentile, it is ignored for the other statistic choices

Returns

• Java, C#, C++, Python: Returns true on success, false on failure. Error details can be retrieved using GetLastError().
• C: Returns a non-zero value on success, zero on failure. Error details can be retrieved using OQGetLastError().

Notes

• The objective must exist before calling this function.
• In C, the name string must be null-terminated.

Set Objective Confidence Parameters

Description

Applicable only for variable-replication optimizations (ignored in single- or fixed-replication cases), this function sets early-stopping confidence parameters for the objective identified by name. Parameters include:

• ctype: Specifies the statistic type for early stopping (e.g., mean).
• clevel: Defines the confidence level (e.g., 95 for 95% confidence).
• epct: Sets the acceptable error percentage for the confidence interval.

This enables OptQuest to halt replications early when the objective’s statistic meets the specified confidence criteria, optimizing computational efficiency.

The options for the ctype value are shown in the table below. The “Type 1” option performs all of the requested replications, the “Type 2” option allows early stopping if OptQuest determines that it is impossible to meet the confidence settings on a particular solution.

The options for the clevel value are shown in the table below. OptQuest will stop early if the percent error in the objective is less than epct with the confidence width defined by the options below.

Returns

• Java, C#, C++, Python: Returns true on success, false on failure. Error details can be retrieved using GetLastError().
• C: Returns a non-zero value on success, zero on failure. Error details can be retrieved using OQGetLastError().

Notes

• The objective must exist before calling this function.
• In C, the name string must be null-terminated.

Add Sampling Metric

Description

Adds a sampling metric identified by name for use in adaptive sampling within the OptQuestModel. The expression is a mathematical formula referencing input and/or output variables by their names, representing the response value monitored during adaptive sampling. The errorExpression is a mathematical expression that evaluates to the uncertainty or error associated with the response value; it can be set to "0" if the response has no uncertainty. Supported mathematical functions for both expressions are detailed in the Supported Mathematical Functions section. The name must be unique across all model components (inputs, outputs, constraints, objectives, metrics) and must not contain whitespace. OptQuest will create two named objectives with the _response and _error suffix that can be used in expressions.

model.AddSampleMetric('metric', metricExpression, errorExpression)

Will create metric_response and metric_error which may be retrieved by from a solution.

Returns

• Java, C#, C++, Python: Returns true on success, false on failure. Error details can be retrieved using GetLastError().
• C: Returns a non-zero value on success, zero on failure. Error details can be retrieved using OQGetLastError().

Notes

• In C, the name, expression, and errorExpression strings must be null-terminated.
• The metric is only used during adaptive sampling and is ignored in optimization workflows.

Add Constraint

Description

Adds a constraint identified by name to the OptQuestModel. The expression is a mathematical formula that can reference input variables, output variables, or objectives by their names, defining a feasible region for optimization or sampling. Supported mathematical functions for the expression are detailed in the Supported Mathematical Functions section. The name must be unique across all model components (inputs, outputs, constraints, objectives) and must not contain whitespace.

Returns

• Java, C#, C++, Python: Returns true on success, false on failure. Error details can be retrieved using GetLastError().
• C: Returns a non-zero value on success, zero on failure. Error details can be retrieved using OQGetLastError().

Notes

• In C, the name and expression strings must be null-terminated.
• Constraints limit the solution space to feasible regions, supporting both linear and non-linear expressions.

Set Replications

Description

Configures the number of replications for stochastic simulations in the OptQuestModel. The function can:

• Set a fixed number of replications (reps) for each solution evaluation. (Note: in C, set a fixed number of replications by setting min and max to the same desired number of replications.)
• Define a variable replication range with min and max bounds, allowing OptQuest to adjust the number of replications dynamically based on convergence criteria (e.g., confidence intervals).

Returns

• Java, C#, C++, Python: Returns true on success, false on failure. Error details can be retrieved using GetLastError().
• C: Returns a non-zero value on success, zero on failure. Error details can be retrieved using OQGetLastError().

Notes

• Variable replication settings are only applicable when convergence monitoring is enabled (e.g., via SetObjectiveConfidence or SetOutputStatistic).

Set Serial Replications

Description

Enables “serial replication” mode for the OptQuestModel, altering the behavior of replication handling during parallel solution evaluations. By default, when multiple solutions are evaluated concurrently, OptQuest completes all replications for one solution before generating a new one. In serial replication mode, OptQuest generates and evaluates a new solution after receiving the first replication result, ensuring that replications for different solutions are interleaved during parallel processing.

Returns

• Java, C#, C++, Python: Returns true on success, false on failure. Error details can be retrieved using GetLastError().
• C: Returns a non-zero value on success, zero on failure. Error details can be retrieved using OQGetLastError().

Notes

• This setting is relevant only when multiple solutions are evaluated in parallel (e.g., via concurrent optimization).

Set Sampling Method

Description

Configures the sampling method(s) for adaptive sampling in the OptQuestModel. The method parameter is a bitwise OR combination of supported sampling method flags, which determine how the adaptive sampling engine selects and evaluates solutions. For a detailed explanation of adaptive sampling, refer to the Adaptive Sampling section.

Sampling Method Categories

The sampling methods are divided into two groups: model-building methods (Stochastic, Dynamic, Async) and feedback methods (Uniform, Variance, Zero, Gradient, Min, Max). These control how the adaptive sampling engine constructs its internal model and selects sample points, respectively.

Model-Building Methods

• Stochastic Sampling: When disabled (default), the engine searches for the optimal next sample point, which may focus too narrowly or be computationally intensive. When enabled, it randomly selects the next point from the domain, weighted by predicted quality, promoting broader exploration and faster point generation.
• Dynamic Sampling: For fast simulations, building the internal model may be slower than evaluating simulations. When enabled, OptQuest monitors evaluation times and generates multiple sample points simultaneously to keep simulations active, sacrificing some model accuracy for efficiency.
• Async Sampling: When enabled, the internal model is built in a background thread, allowing concurrent model construction and simulation evaluation. If a new point is requested before the model is updated, the previous model is used, prioritizing efficiency for fast simulations.

Feedback Methods

These methods define the criteria for selecting the next sample point based on the sampling metric’s estimated value and uncertainty. Multiple feedback methods can be combined using bitwise OR, resulting in one sample per enabled method per request.

• Uniform: Uses a space-filling sequence to distribute samples evenly across the domain, ignoring metric values. This is the fastest method for uniform domain coverage.
• Variance: Targets regions with the highest variance (least-known areas), minimizing global variance and building a uniformly accurate response surface.
• Zero: Selects points closest to a zero metric value, ideal for mapping boundary conditions or transition zones in the response surface.
• Gradient: Targets regions with the steepest response changes, identifying areas of rapid variation.
• Min: Focuses on regions with the smallest metric values, increasing sample density in low-response areas for detailed characterization.
• Max: Focuses on regions with the largest metric values, increasing sample density in high-response areas for detailed characterization.

Returns

• Java, C#, C++, Python: Returns true on success, false on failure. Error details can be retrieved using GetLastError().
• C: Returns a non-zero value on success, zero on failure. Error details can be retrieved using OQGetLastError().

Model Optimization API

After defining a model using the model definition functions, the following API functions facilitate running optimization or adaptive sampling on the OptQuestModel. Once any of these functions are invoked, the model becomes immutable, preventing modifications to variables, objectives, or constraints.

Create Solution

Description

Requests the OptQuestModel to generate a new trial solution for evaluation. OptQuest populates the solution with values for each input variable. The caller can then provide output variable values and submit the solution for processing by the optimization or sampling engine. In C, the client is responsible for freeing the HOptQuestSolution handle using the appropriate cleanup function (e.g., OQDeleteSolution).

Returns

• Java, C#, C++, Python: Returns an OptQuestSolution object associated with the model. If OptQuestSolution.IsValid() returns false, no new solutions could be generated (e.g., due to domain exhaustion or an interrupted optimization).
• C: Returns an HOptQuestSolution handle. Check validity using OQIsValid.

Notes

• In C, ensure proper resource cleanup to avoid memory leaks.

Interrupt Optimization

Description

Signals the OptQuestModel to stop generating new solutions during manual optimization loops. This function is relevant only for manual optimization workflows, as managed optimization handles termination internally. In multi-threaded manual optimization scenarios, calling this function notifies all threads that no further solutions will be provided. Affected threads can gracefully exit when their next call to CreateSolution() returns an invalid OptQuestSolution.

Returns

• This function does not return a value.

Notes

• Ensure all threads check the validity of solutions returned by CreateSolution() to handle the interruption gracefully.

Continue Optimization

Description

If an optimization is interrupted with a call to Interrupt(), no new solutions will be generated unless Continue() is called. Use this to restart an interrupted optimization. This function is relevant only for manual optimization workflows, as managed optimization handles continuing internally.

Returns

• This function does not return a value.

Create Empty Solution

Description

Creates an empty OptQuestSolution object associated with the OptQuestModel, allowing the caller to manually populate input and output values. This is typically used with the OptQuestSolution.Suggest() function to propose solutions for evaluation. The caller can submit the solution as either a “Suggested” solution (input values only) or an “Evaluated” solution (both input and output values) for processing by the OptQuest engine. In C, the client must free the HOptQuestSolution handle using the appropriate cleanup function (e.g., OQDeleteSolution).

Returns

• Java, C#, C++, Python: Returns an empty OptQuestSolution object tied to the model.
• C: Returns an HOptQuestSolution handle.

Notes

• In C, ensure proper resource cleanup to avoid memory leaks.

Copy Solution

Description

Creates a new OptQuestSolution object with input and output values copied from the source solution (src) into the destination OptQuestModel. This is useful for transferring a solution from one model to another, such as when continuing optimization with modified parameters. Values from src matching variable names in the destination model are copied; unmatched values in src are ignored, and missing values in the destination model are set to NaN. The copied solution can be submitted as a “Suggested” (input values only) or “Evaluated” (input and output values) solution for processing. In C, the client must free the HOptQuestSolution handle after submission using the appropriate cleanup function.

Returns

• Java, C#, C++, Python: Returns an OptQuestSolution object tied to the destination model, pre-filled with values from src.
• C: Returns an HOptQuestSolution handle.

Notes

• In C, ensure proper resource cleanup to avoid memory leaks.

Add All Solutions

Description

Transfers all evaluated solutions from the source OptQuestModel (src) to the destination OptQuestModel. This is typically used to resume optimization after modifying model parameters, such as constraints or objectives. Transferred solutions are reprocessed in the context of the destination model to compute new objective values. If constraints in the destination model are stricter, infeasible solutions are mapped to the feasible space and marked for re-evaluation.

Returns

• Java, C#, C++, Python: Returns true on success, false on failure. Error details can be retrieved using GetLastError().
• C: Returns a non-zero value on success, zero on failure. Error details can be retrieved using OQGetLastError().

Notes

• Ensure variable names and types align between source and destination models for accurate solution transfer.

Mangaged Optimization

Description

Executes a managed optimization on the OptQuestModel, evaluating nsol solutions generated by the optimization engine. Three variants are available:

• Optimize(int nsol): Use when objectives and constraints depend only on input variables, requiring no external evaluation. No callback is needed.
• Optimize(int nsol, IOptQuestEvaluator eval): Use when output variables require evaluation via a custom callback function.
• Optimize(int nsol, IOptQuestEvaluator eval, IOptQuestMonitor monitor): Extends the previous variant by adding a monitor callback to post-process evaluated solutions, typically for updating a UI.

In C, callbacks are function pointers and may be NULL if not required. The context parameter allows passing user-defined data to callbacks.

In Python, callbacks are functions that take a single OptQuestSolution parameter and may be None if not required.

Returns

• Java, C#, C++, Python: Returns true on success, false on failure. Error details can be retrieved using GetLastError().
• C: Returns a non-zero value on success, zero on failure. Error details can be retrieved using OQGetLastError().

Concurrent Managed Optimization

Description

Runs a concurrent managed optimization, evaluating nsol solutions across npar parallel threads. This function behaves like Managed Optimization but processes npar solutions simultaneously. OptQuest ensures thread-safe handling of the model and solutions, but the IOptQuestEvaluator and IOptQuestMonitor callbacks must implement proper synchronization to avoid race conditions on shared, non-OptQuest-managed state. The function blocks until all solutions are evaluated.

In C, callbacks are function pointers and may be NULL if not required. The context parameter allows passing user-defined data to callbacks.

In Python, callbacks are functions that take a single OptQuestSolution parameter and may be None if not required.

Returns

• Java, C#, C++, Python: Returns true on success, false on failure. Error details can be retrieved using GetLastError().
• C: Returns a non-zero value on success, zero on failure. Error details can be retrieved using OQGetLastError().

Notes

• Use appropriate synchronization in callbacks to manage shared resources safely.

Create Asynchronous Model Channel

Description

Creates an OptQuestModelChannel for inter-thread communication, enabling coordination between the main application and a concurrent optimization running in a background thread with npar parallel evaluations. In C, the client must free the HOptQuestModelChannel handle using OQDeleteAsyncChannel.

Returns

• Java, C#, C++: Returns an OptQuestModelChannel object tied to the model.
• C: Returns an HOptQuestModelChannel handle. Returns NULL on failure, with error details available via OQGetLastError().

Notes

• In C, ensure proper cleanup of the channel to avoid resource leaks.

Asynchronous Optimization

Description

Runs a managed optimization in a background thread, using an OptQuestModelChannel (ipc) to communicate with the main thread. The optimization evaluates nsol solutions, with variants mirroring those of Managed Optimization. The main thread can call OptQuestModelChannel.Interrupt() to request early termination, which halts new solution generation and evaluation but allows ongoing evaluations to complete. This function blocks until the optimization completes or is interrupted.

Returns

• Java, C#, C++: Returns true on success, false on failure. Error details can be retrieved using GetLastError().
• C: Returns a non-zero value on success, zero on failure. Error details can be retrieved using OQGetLastError().

Example

// Create a channel for 5 concurrent solution evaluations
OptQuestModelChannel oqChannel = oqModel.CreateAsyncChannel(5);

// Start asynchronous optimization in a background thread
Thread background = new Thread(() -> {
    oqModel.AsyncOptimize(oqChannel, nsol);
}).start();

// Interrupt optimization on user event
oqChannel.Interrupt();

// Wait for graceful shutdown
background.join();

Managed Adaptive Sampling

Description

Executes managed adaptive sampling on the OptQuestModel, evaluating nsol solutions generated by the adaptive sampling engine. Three variants are available:

• Sample(int nsol): Use when metrics and constraints depend only on input variables, requiring no external evaluation. No callback is needed.
• Sample(int nsol, IOptQuestEvaluator eval): Use when output variables require evaluation via a custom callback function.
• Sample(int nsol, IOptQuestEvaluator eval, IOptQuestMonitor monitor): Extends the previous variant by adding a monitor callback to post-process evaluated solutions, typically for updating a UI.

In C, callbacks are function pointers and may be NULL if not required. The context parameter allows passing user-defined data to callbacks.

In Python, callbacks are functions that take a single OptQuestSolution parameter and may be None if not required.

Returns

• Java, C#, C++, Python: Returns true on success, false on failure. Error details can be retrieved using GetLastError().
• C: Returns a non-zero value on success, zero on failure. Error details can be retrieved using OQGetLastError().

Concurrent Managed Adaptive Sampling

Description

Runs concurrent managed adaptive sampling, evaluating nsol solutions across npar parallel threads. This function behaves like managed adaptive sampling but processes npar solutions simultaneously. OptQuest ensures thread-safe handling of the model and solutions, but the IOptQuestEvaluator and IOptQuestMonitor callbacks must implement proper synchronization to avoid race conditions on shared, non-OptQuest-managed state. The function blocks until all solutions are evaluated.

In C, callbacks are function pointers and may be NULL if not required. The context parameter allows passing user-defined data to callbacks.

In Python, callbacks are functions that take a single OptQuestSolution parameter and may be None if not required.

Returns

• Java, C#, C++, Python: Returns true on success, false on failure. Error details can be retrieved using GetLastError().
• C: Returns a non-zero value on success, zero on failure. Error details can be retrieved using OQGetLastError().

Notes

• Use appropriate synchronization in callbacks to manage shared resources safely.

Asynchronous Managed Adaptive Sampling

Description

Runs managed adaptive sampling in a background thread, using an OptQuestModelChannel (ipc) to communicate with the main thread. The sampling evaluates nsol solutions, with variants mirroring those of managed adaptive sampling. The main thread can call OptQuestModelChannel.Interrupt() to request early termination, which halts new solution generation and evaluation but allows ongoing evaluations to complete. This function blocks until the sampling completes or is interrupted.

Returns

• Java, C#, C++: Returns true on success, false on failure. Error details can be retrieved using GetLastError().
• C: Returns a non-zero value on success, zero on failure. Error details can be retrieved using OQGetLastError().

Get Best Solutions

Description

Retrieves the best solutions identified during optimization from the OptQuestModel. The function returns a collection (List in Java, C#, and Python) or count in C++ and C of OptQuestSolution objects, even if only one solution is available.

• GetBestSolutions(): For single-objective optimizations, returns a collection containing the single best solution. For multi-objective optimizations, returns all solutions on the Pareto frontier.
• GetBestSolutions(int limit): For single-objective optimizations, returns up to limit best solutions. For multi-objective optimizations, returns all Pareto frontier solutions, ignoring the limit parameter.

In C and C++, GetBestSolutions returns the number of solutions, and individual solutions are accessed via GetBestSolutionsAt(int i). These functions share global state and are not reentrant; a subsequent call to GetBestSolutions invalidates the previous list.

Returns

• Java, C#, Python: A List of OptQuestSolution objects.
• C++, C: GetBestSolutions returns the number of solutions; GetBestSolutionsAt returns the solution at index i.

Get All Solutions

Description

Retrieves the all evaluated solution during optimization from the OptQuestModel. The function returns a collection (List in Java, C#, and Python) or count in C++ and C of OptQuestSolution objects, even if only one solution is available.

In C and C++, GetAllSolutions returns the number of solutions, and individual solutions are accessed via GetAllSolutionsAt(int i). These functions share global state and are not reentrant; a subsequent call to GetAllSolutions invalidates the previous list.

Returns

• Java, C#, Python: A List of OptQuestSolution objects.
• C++, C: GetBestSolutions returns the number of solutions; GetBestSolutionsAt returns the solution at index i.

Get Termination Reason

Description

Returns an integer indicating why an optimization stopped.

Returns

Get Last Error

Description

Retrieves error information for the OptQuestModel when a function returns false or fails. This is useful for debugging model configurations or runtime issues.

Returns

• A string containing the last error message and relevant call stack.

Solution API

The OptQuestModel manages OptQuestSolution objects, which are passed between the client and the optimization or sampling engine to represent trial solutions.

Delete Solution

Description

Releases resources associated with an OptQuestSolution object. Solutions are never created directly; they are instantiated by the OptQuestModel via CreateSolution(), CreateEmptySolution(), or CopySolution(). In Java and C#, memory is managed by the garbage collector. In C++ and Python, the destructor handles cleanup when the object goes out of scope. In C, the client must explicitly call OQDeleteSolution to free the HOptQuestSolution handle.

Returns

• This function does not return a value.

Is Valid

Description

Checks if an OptQuestSolution is valid. An invalid solution is returned when the optimization engine cannot generate a new solution, e.g., due to an exhausted feasible space or a too-restrictive domain. In C# and C++, the operator bool pattern allows implicit conversion to a boolean for validity checks.

Returns

• Java, C#, C++, Python: Returns true if the solution is valid, false otherwise.
• C: Returns a non-zero value if valid, zero if invalid.

Get Iteration

Description

Retrieves the unique iteration number assigned to the OptQuestSolution when it is created and sent for evaluation. Multiple replications of the same solution share the same iteration number.

Returns

• An int representing the iteration number of the solution.

Notes

• Use this to track the sequence of solutions generated during optimization or sampling.

Get Replication

Description

Retrieves the unique replication number assigned to the OptQuestSolution for a specific evaluation instance. Each replication of a solution has a distinct replication number.

Returns

• An int representing the replication number of the solution.

Notes

• Useful for distinguishing between multiple evaluations of the same solution in stochastic simulations.

Get Number Of Completed Replications

Description

Returns the total number of replications evaluated for the OptQuestSolution.

Returns

• An int representing the number of completed replications.

Is Complete

Description

Checks if all required replications for the OptQuestSolution have been evaluated, indicating that no further evaluations are needed.

Returns

• Java, C#, C++, Python: Returns true if all replications are complete, false otherwise.
• C: Returns a non-zero value if complete, zero if more replications are needed.

Notes

• Use this to determine if a solution’s evaluation cycle is finished, especially in variable replication modes.

Is Feasible

Description

Verifies if the OptQuestSolution satisfies all constraints defined in the OptQuestModel, indicating it lies within the feasible region.

Returns

• Java, C#, C++, Python: Returns true if the solution is feasible, false if it violates any constraints.
• C: Returns a non-zero value if feasible, zero if infeasible.

Has Met Confidence

Description

Checks if the OptQuestSolution has met the confidence requirements for all objectives in variable replication mode, ensuring sufficient statistical reliability for stochastic simulations.

Returns

• Java, C#, C++, Python: Returns true if confidence requirements are met for all objectives, false otherwise.
• C: Returns a non-zero value if confidence is met, zero if any objective’s confidence is unmet.

Notes

• Only relevant for variable replication optimizations with confidence settings (e.g., via SetObjectiveConfidence).

Get Value

Description

Retrieves the value associated with a named variable (input or output), objective, or constraint in an OptQuestSolution. If the requested value is unavailable (e.g., the name is invalid or the value is undefined), NaN is returned. The name parameter can include suffixes to access specific information, particularly for replications, confidence intervals, or constraint components.

Name Parameter Formats

• Basic Usage: Use the name of the variable, objective, or constraint (e.g., "input1", "objective1", "constraint1").

• Outputs with Replications: For solutions with multiple replications, the aggregated output value is returned by default. To access a specific replication, append ";#" where # is the replication number (e.g., "output;2" for replication #2).

• Objectives with Replications: Similar to outputs, the aggregated objective value is returned by default. Use ";#" for a specific replication (e.g., "objective;3" for replication #3). For variable replication mode, append ";cw" to retrieve the confidence interval width (e.g., "objective;cw").

• Constraints: By default, the constraint name returns feasibility (1.0 for feasible, 0.0 for infeasible). To access specific parts of a constraint expression, use:

  • “;LHS;#”: Left-hand side of the constraint’s #th clause (e.g., “constraint1;LHS;1”).
  • “;RHS;#”: Right-hand side of the constraint’s #th clause (e.g., “constraint1;RHS;1”).
  • Clause numbers are typically 1 unless the constraint includes OR conditions (e.g., input1 - input2 < 3 OR input2 + input3 > 5 - input2).

Example

For a constraint named constraint1 defined as input1 - input2 < 3 OR input2 + input3 > 5 - input2:

• GetValue("constraint1"): Returns 1.0 if feasible, 0.0 if infeasible.
• GetValue("constraint1;LHS;1"): Returns the value of input1 - input2.
• GetValue("constraint1;RHS;1"): Returns 3.
• GetValue("constraint1;LHS;2"): Returns the value of input2 + input3.
• GetValue("constraint1;RHS;2"): Returns the value of 5 - input2.

Returns

• A double value representing the requested information, or NaN if the information is unavailable.

Notes

• In C, the name string must be null-terminated.

Set Value

Description

Sets the value of a named input or output variable in an OptQuestSolution. This is primarily used to assign values to output variables during solution evaluation. However, clients can also override input variable values if needed. Objective and constraint values cannot be set directly, as they are computed from input and output variables.

Returns

• Java, C#, C++, Python: Returns true on success, false on failure. Error details can be retrieved using GetLastError().
• C: Returns a non-zero value on success, zero on failure. Error details can be retrieved using OQGetLastSolutionError().

Notes

• In C, the name string must be null-terminated.

Submit Solution

Description

Submits an evaluated OptQuestSolution back to the optimization engine for processing. This function is used exclusively in manual optimization loops; managed optimization handles submission automatically. The solution must have all required output values set (via SetValue) before submission.

Returns

• An the total number of evaluated solutions that have been evaluated by OptQuest, including this one. This can be useful to track how many solutions have been processed (even including other concurrent threads).

Notes

• Ensure all necessary output values are set before calling.
• In manual loops, call Update after submission to refresh the solution’s state if further modifications are needed.

Reject Solution

Description

Rejects an OptQuestSolution, signaling to the optimization engine that it could not be evaluated (e.g., due to external constraints or simulation failures). The rejected solution is returned to the engine and not used to guide future solution generation. This function is used only in manual optimization loops; managed optimization handles rejections internally.

Returns

• An the total number of evaluated solutions that have been evaluated by OptQuest (not including this one, because it was rejected). This can be useful to track how many solutions have been processed (even including other concurrent threads).

Notes

• Use this to inform the engine of unevaluable solutions without penalizing the optimization process.
• In manual loops, call Update after rejection if the solution’s state needs refreshing.

Update Solution

Description

Updates the internal state of an OptQuestSolution after it has been submitted or rejected to the optimization engine. This ensures the solution reflects the latest engine processing, such as updated constraint feasibility or objective values. This function is used only in manual optimization loops; managed optimization handles updates automatically.

Returns

• Java, C#, C++, Python: Returns true on success, false on failure. Error details can be retrieved using GetLastError().
• C: Returns a non-zero value on success, zero on failure. Error details can be retrieved using OQGetLastSolutionError().

Notes

• Call this after Submit or Reject in manual loops to ensure the solution’s state is consistent with the engine.

Add Suggested

Description

Submits an OptQuestSolution as a “warm start” to the optimization engine, providing known or promising input variable values to accelerate convergence. The client must set input variable values (via SetValue) before calling this function. OptQuest evaluates these suggested solutions before generating new ones. This is typically used before starting an optimization to leverage prior knowledge.

Returns

• Java, C#, C++, Python: Returns true on success, false on failure. Error details can be retrieved using GetLastError().
• C: Returns a non-zero value on success, zero on failure. Error details can be retrieved using OQGetLastSolutionError().

Notes

• Ensure all required input variables are set before calling.
• Use with solutions created via CreateEmptySolution() or CopySolution() for manual input specification.

Add Evaluated

Description

Submits an OptQuestSolution with pre-computed input and output variable values to the optimization engine. This is useful for incorporating results from prior simulations, saving computational effort. The client must set both input and output variable values (via SetValue) before calling. OptQuest processes these evaluated solutions before generating new ones, integrating them into the optimization process.

Returns

• Java, C#, C++, Python: Returns true on success, false on failure. Error details can be retrieved using GetLastError().
• C: Returns a non-zero value on success, zero on failure. Error details can be retrieved using OQGetLastSolutionError().

Notes

• Ensure all required input and output variables are set before calling.
• Use with solutions created via CreateEmptySolution() or CopySolution() for manual input specification.

Get Last Error

Description

Retrieves error information for an OptQuestSolution when a function returns false or fails. This is useful for debugging issues related to solution manipulation or submission.

Returns

• A string containing the last error message and relevant call stack.

Notes

• Call this after any failed OptQuestSolution operation to diagnose the issue.

Managed Optimization API

The Managed Optimization API in OptQuest simplifies common optimization workflows by handling the optimization loop, including solution creation, evaluation, post-processing, and status updates. This can optionally run in parallel. Two optional callback functions can be provided to the Optimize() function: one for custom solution evaluation (required when computing output variables) and one for status monitoring (e.g., updating a UI during optimization).

Evaluate (Solution Evaluator)

Description

The solution evaluator callback is implemented by providing an IOptQuestEvaluator interface in Java, C#, or C++, a function that accepts a solution in Python, or a function pointer of type OQEvaluator in C. It is called by OptQuest to evaluate an OptQuestSolution during managed optimization.

• Input: OptQuest provides the solution (sol) with pre-populated input variable values, accessible via GetValue().
• Evaluate: The callback performs custom evaluation (e.g., running a simulation) to compute output variable values, which are set using SetValue().
• Output: If the callback returns true, the solution is submitted to OptQuest for post-processing (equivalent to OptQuestSolution.Submit()). If false, the solution is rejected and excluded from post-processing (equivalent to OptQuestSolution.Reject()).

In C, the context parameter allows passing user-defined state to the callback. In concurrent optimization (e.g., ConcurrentOptimize or AsyncOptimize), this function may be called simultaneously across multiple threads, so proper synchronization is required for any shared state not managed by OptQuest.

Returns

• Java, C#, C++, Python: Returns true to submit the solution, false to reject it.
• C: Returns a non-zero value to submit, zero to reject.

Notes

• Ensure thread-safe handling of shared resources in concurrent scenarios.
• Verify input values and set all required output variables before returning true.

Monitor (Solution Monitor)

Description

The solution monitor callback is implemented by providing an IOptQuestMonitor interface in Java, C#, or C++, a function that accepts a solution in Python, or a function pointer of type OQMonitor in C. It is called by OptQuest after post-processing an evaluated solution during managed optimization.

• Input: OptQuest provides the solution (sol) with values for input variables, output variables, constraints, and objectives, accessible via GetValue().
• Examine: The callback updates application state, such as a UI, or evaluates early stopping conditions based on the solution’s results.
• Output: If the callback returns true, OptQuest continues generating new solutions. If false, solution generation stops, and the optimization loop exits early. In concurrent optimization, ongoing evaluations complete, but no new solutions are generated.

In C, the context parameter allows passing user-defined state. In concurrent optimization, this function may be called simultaneously across multiple threads, requiring proper synchronization for shared, non-OptQuest-managed state.

Returns

• Java, C#, C++, Python: Returns true to continue optimization, false to stop generating new solutions.
• C: Returns a non-zero value to continue, zero to stop.

Notes

• Use this callback for real-time monitoring or to implement complex early-stopping logic.
• Ensure thread-safe handling of shared resources in concurrent scenarios.
• Access solution details (e.g., feasibility, objective values) to inform monitoring decisions.

Functions Available In Expressions

These functions are available when defining expressions for Objectives and Constraints.

Linking OptQuest To Your Project

We provide the OptQuest Engine with language bindings for Java, C#, C++, C, and Python. This section describes how to integrate OptQuest with your project.

Java

OptQuest is delivered as a single OptQuest.jar file to be included in your Java project. Adding a reference to the file as a library in your build system of choice should be sufficient to link to the both the “old” OptQuest 9 API as well as the “new” OptQuest 10 API.

C

OptQuest is delivered as OptQuestEngine.dll which contains the optimization engine and OptQuestNet.dll which contains the C# language bindings. In your C# application, you’ll import OptQuestNet.dll and at run time, both OptQuestNet.dll and OptQuestEngine.dll need to be in the same directory. An Visual Studio solution file is provided with working examples of linking a C# application to OptQuest.

C++

OptQuest is delivered as OptQuestEngine.dll and OptQuestLib.dll which contain the optimization engine and OptQuest.h and OptQuestLib.lib which contains the C++ language bindings. In your C++ application, OptQuestLib.dll and at run time OptQuestEnginge.dll needs to be in the same directory as your application. An Visual Studio solution file is provided with working examples of linking a C++ application to OptQuest.

C

OptQuest is delivered as OptQuestEngine.dll and OptQuestLib.dll which contain the optimization engine and OptQuest.h and OptQuestLib.lib which contains the C language bindings. In your C application, OptQuestLib.dll and at run time OptQuestEnginge.dll needs to be in the same directory as your application. An Visual Studio solution file is provided with working examples of linking a C application to OptQuest.

Python

OptQuest is delivered as OptQuestEngine.dll and OptQuestLib.dll which contain the optimization engine and OptQuest.py which contains the Python language bindings. By default, OptQuest.py will look for OptQuestLib.dll in the current working directory. After importing optquest.py the variable dll_path can be set to the location of OptQuestLib.dll. OptQuestEngine.dll needs to be in the same directory as OptQuestLib.dll. A working example is provided.

Standard I/O Interface

For expert use only. The OptQuest engine can be accessed as a standalone application using a standard input/output (STDIO) interface, enabling communication with your application via STDIN and STDOUT. This interface is intended as a last-resort method for integrating optimization capabilities when direct linking to OptQuest libraries (Java, C#, C++, or C) is not feasible. Only manual optimization is supported; managed optimization is not available.

Setup

• Windows: The OptQuest.exe executable, included with the example Visual Studio solution, starts an OptQuest server that listens for commands on STDIN and writes results to STDOUT.
• Java: The OptQuest.jar file includes a Main() function with identical behavior. Run java -jar OptQuest.jar to start the server, which listens on STDIN and writes to STDOUT.

Interface Characteristics

• Command Format:
  • Most commands are single-line, terminated with an end-of-line character (e.g., \n), with parameters separated by spaces.
  • Some commands are multi-line, with options specified line by line and terminated by a single line containing END.
• Response Format:
  • Responses are typically single-line, terminated with an end-of-line character.
  • Error messages begin with ERROR and may span multiple lines. Continue reading until the input buffer is empty.
• Error Handling:
  • No error checking or warning messages are provided; commands must be well-formed.
  • Malformed commands may result in undefined behavior or server crashes.
• Limitations:
  • Only manual optimization loops are supported, requiring the client to manage solution creation, evaluation, and submission.
  • This interface is less robust and harder to debug compared to library-based integration.

Usage

1. Start the Server:
   • Run OptQuest.exe (Windows) or java -jar OptQuest.jar (Java) from the command line.
   • The server initializes and waits for commands on STDIN.
2. Send Commands:
   • Write commands to STDIN, ensuring proper formatting (space-delimited parameters, correct termination).
   • For multi-line commands, terminate the input with a single line containing END.
3. Read Responses:
   • Read STDOUT for single-line responses or multi-line error messages starting with ERROR.
   • Parse responses to extract solution data, status, or error details.
4. Error Management:
   • Monitor for ERROR prefixes and read subsequent lines until the buffer is empty.
   • Ensure commands are correctly formatted to avoid server instability.

Supported Commands

The OptQuest STDIO interface supports a subset of functionality for manual optimization workflows, allowing interaction with the optimization engine via STDIN commands and STDOUT responses. Commands facilitate model creation, variable and constraint definition, solution generation, and result retrieval. Below is a detailed list of supported commands, their descriptions, and their equivalents in the OptQuest API.

Command List

Create Model

Command Format

The CREATEMODEL command is a multi-line command that defines a new OptQuest model. It begins with CREATEMODEL, followed by model definition commands, and ends with a single line containing END. Each model definition command is a single line with space-delimited parameters.

CREATEMODEL
...model definition commands...
END

Model Definition Commands

Each model definition command starts with a string identifier followed by one or more parameters, separated by spaces unless otherwise noted. The table below lists supported commands and their equivalent OptQuest API functions.

¹ Tuple and Geolocation Format: Tuples and geolocations are specified as a single string with comma-separated values for each tuple or coordinate pair, and semicolon-separated groups. For example, four tuples (a,b,c), (d,e,f), (g,h,i), (j,k,l) are written as a,b,c;d,e,f;g,h,i;j,k,l. Similarly, geolocations are formatted as lat1,lon1;lat2,lon2.

² Metric Expressions: The responseExpression and errorExpression in the METRIC command are delimited by a semicolon (;) to allow spaces within the expressions.

Return

A single integer representing the unique identifier for the newly created model.

If there is an error, the return will begin with ERROR followed by description of what went wrong.

<modelIdentifier>

Create Solution

Command Format

A single-line command that takes one parameter: the integer identifier of the model to which the solution belongs.

CREATESOLUTION <modelIdentifier>

Return

A multi-line response defining the created solution:

• First Line: Two integers: (model ID) and (unique solution ID).
• Second Line: Seven integers:
  • : Iteration number assigned to the solution.
  • : Replication number for this solution instance.
  • : Total number of replications for the solution.
  • : 1 if all replications are complete, 0 otherwise.
  • : 1 if the solution is feasible (satisfies constraints), 0 otherwise.
  • : 1 if confidence requirements are met (in variable replication mode), 0 otherwise.
  • : 1 if the solution has been evaluated, 0 otherwise (typically 0 for new solutions).
• Subsequent Lines: Space-delimited pairs of (string) and (double) for each input variable.

If there is an error, the return will begin with ERROR followed by description of what went wrong.

<modelIdentifier> <solutionIdentifier>
<iteration> <replication> <numberOfReplications> <isComplete> <isFeasible> <hasMetConfidence> <isEvaluated>
<inputName1> <inputValue1>
...
<inputNameN> <inputValueN>

Submit Solution

Command Format

A multi-line command to submit an evaluated solution:

• First Line: SUBMITSOLUTION followed by two integers: <modelIdentifier> (model ID) and <solutionIdentifier> (solution ID).
• Subsequent Lines: Space-delimited pairs of <variableName> (string) and <variableValue> (double) for output variables and, optionally, input variables if they were modified during evaluation.
• Final Line: END to terminate the command.

SUBMITSOLUTION
<modelIdentifier> <solutionIdentifier>
<variableName1> <variableValue1>
...
<variableNameN> <variableValueN>
END

Return

A single integer representing the total number of evaluated solutions in the model.

If an error occurs (e.g., invalid solution ID), the response begins with ERROR followed by a description.

<numberCompleted>

Reject Solution

Command Format

A single-line command that takes two integer parameters: <modelIdentifier> (model ID) and <solutionIdentifier> (solution ID) to reject a solution that could not be evaluated.

REJECTSOLUTION <modelIdentifier> <solutionIdentifier>

Return

A single integer representing the total number of evaluated solutions in the model.

If an error occurs (e.g., invalid solution ID), the response begins with ERROR followed by a description.

<numberCompleted>

Add Solution

Command Format

A multi-line command to add a suggested or evaluated solution to a model:

• First Line: ADDSOLUTION followed by two integers: <modelIdentifier> (model ID) and <isEvaluated> (flag: 0 for suggested solution with only input values, 1 for evaluated solution with both input and output values).
• Subsequent Lines: Space-delimited pairs of <variableName> (string) and <variableValue> (double) for all input variables, and, if <isEvaluated> is 1, all output variables.
• Final Line: END to terminate the command.

ADDSOLUTION
<modelIdentifier> <isEvaluated>
<variableName1> <variableValue1>
...
<variableNameN> <variableValueN>
END

Return

A single line with OK on success.

If an error occurs (e.g., invalid model ID or missing required values), the response begins with ERROR followed by a description.

OK

Get Solution

Command Format

A single-line command that takes two integer parameters: <modelIdentifier> (model ID) and <solutionIdentifier> (solution ID) to retrieve all information about a specific solution.

GETSOLUTION <modelIdentifier> <solutionIdentifier>

Return

A multi-line response containing comprehensive details about the solution, including all evaluated replications:

• First Line: Two integers: <modelIdentifier> (model ID) and <solutionIdentifier> (solution ID).

• Second Line: Seven integers:

  • <iteration>: Iteration number assigned to the solution.
  • <replication>: Replication number for this solution instance.
  • <numberOfReplications>: Total number of replications for the solution.
  • <isComplete>: 1 if all replications are complete, 0 otherwise.
  • <isFeasible>: 1 if the solution satisfies all constraints, 0 otherwise.
  • <hasMetConfidence>: 1 if confidence requirements are met (in variable replication mode), 0 otherwise.
  • <isEvaluated>: 1 if the solution has been evaluated, 0 otherwise.

• Subsequent Lines: Space-delimited pairs of keys (string) and values (double) for:

  • Input Variables: <inputName> and <inputValue>.
  • Output Variables: Aggregated <outputName> and <outputValue>, plus per-replication values as <outputName;R> for replication R.
  • Objectives: Aggregated <objectiveName> and <objectiveValue>, confidence width as <objectiveName;cw>, and per-replication values as <objectiveName;R> for replication R.
  • Constraints: Feasibility as <constraintName> (1.0 for feasible, 0.0 for infeasible), and per-clause left-hand side (<constraintName;LHS;C>) and right-hand side (<constraintName;RHS;C>) for clause C.

If an error occurs (e.g., invalid solution ID), the response begins with ERROR followed by a description.

<modelIdentifier> <solutionIdentifier>
<iteration> <replication> <numberOfReplications> <isComplete> <isFeasible> <hasMetConfidence> <isEvaluated>
<inputName1> <inputValue1>
...
<inputNameN> <inputValueN>
<outputName1> <outputValue1>
<outputName1;1> <outputValue1Replication1>
...
<outputName1;R> <outputValue1ReplicationR>
...
<outputNameN> <outputValueN>
<outputNameN;1> <outputValueNReplication1>
...
<outputNameN;R> <outputValueNReplicationR>
<objectiveName1> <objectiveValue1>
<objectiveName1;cw> <objectiveConfidenceWidth1>
<objectiveName1;1> <objectiveValue1Replication1>
...
<objectiveName1;R> <objectiveValue1ReplicationR>
...
<objectiveNameN> <objectiveValueN>
<objectiveNameN;cw> <objectiveConfidenceWidthN>
<objectiveNameN;1> <objectiveValueNReplication1>
...
<objectiveNameN;R> <objectiveValueNReplicationR>
<constraintName1> <constraintFeasibility1>
<constraintName1;LHS;1> <constraintLeftHandSideValue1Clause1>
<constraintName1;RHS;1> <constraintRightHandSideValue1Clause1>
...
<constraintName1;LHS;C> <constraintLeftHandSideValue1ClauseC>
<constraintName1;RHS;C> <constraintRightHandSideValue1ClauseC>
...
<constraintNameN> <constraintFeasibilityN>
<constraintNameN;LHS;1> <constraintLeftHandSideValueNClause1>
<constraintNameN;RHS;1> <constraintRightHandSideValueNClause1>
...
<constraintNameN;LHS;C> <constraintLeftHandSideValueNClauseC>
<constraintNameN;RHS;C> <constraintRightHandSideValueNClauseC>

Get Best Solutions

Command Format

A single-line command that takes two integer parameters: <modelIdentifier> (model ID) and <limit> (number of best solutions to return; ignored for multi-objective optimizations, where the entire Pareto frontier is returned).

GETBESTSOLUTIONS <modelIdentifier> <limit>

Return

A multi-line response containing a concatenated list of the best solutions in the format of GETSOLUTION. Each solution, including the first, is preceded by a line with three dashes and a 0-based counter value.

If an error occurs (e.g., invalid model ID), the response begins with ERROR followed by a description.

--- 0
<solution 1 output>
--- 1
<solution 2 output>
...
--- <n-1>
<solution N output>

Get All Solutions

Command Format

A single-line command that takes one parameter: <modelIdentifier> (model ID).

GETALLSOLUTIONS <modelIdentifier>

Return

A multi-line response containing a concatenated list of all evaluated solutions in the format of GETSOLUTION. Each solution, including the first, is preceded by a line with three dashes and a 0-based counter value.

If an error occurs (e.g., invalid model ID), the response begins with ERROR followed by a description.

--- 0
<solution 1 output>
--- 1
<solution 2 output>
...
--- <n-1>
<solution N output>

Add All Solutions

Command Format

A single-line command that takes two integer parameters: <destinationModelIdentifier> (destination model ID) and <sourceModelIdentifier> (source model ID).

ADDALLSOLUTIONS <destinationModelIdentifier> <sourceModelIdentifier>

Return

A single line with OK on success.

If an error occurs (e.g., invalid model IDs), the response begins with ERROR followed by a description.

OK

Delete Model

Command Format

A single-line command that takes one parameter: <modelIdentifier> (model ID).

DELETEMODEL <modelIdentifier>

Return

A single line with OK, regardless of whether the model existed.

OK

Quit

Command Format

A single-line command with no parameters.

QUIT

Example

Here’s an example of how to define a model, request a few solutions, evaluate them, and print out the best. Lines beginning with > are inputs from STDIN from the client, and lines beginning with < are responses that are sent to STDOUT by the server.

> CREATEMODEL
> CONTINUOUS X -10 10
> CONTINUOUS Y -15 15
> OUTPUT Z
> CONSTRAINT C1 X<Y
> CONSTRAINT C2 X+Y>1
> CONSTRAINT C3 X+Y<10
> OBJECTIVE O1 MAX X+Y-Z
> END
< 0
> CREATESOLUTION 0
< 0 0
< 1 1 1 0 0 1 0
< X -2.5
< Y 7.75
> SUBMITSOLUTION
> 0 0
> Z 66
> END
< 1
> CREATESOLUTION 0
< 0 1
< 2 1 1 0 0 1 0
< X 0.5
< Y 0.5
> SUBMITSOLUTION
> 0 1
> Z .5
> END
< 2
> CREATESOLUTION 0
< 0 2
< 3 1 1 0 0 1 0
< X -5.0
< Y 15.0
> SUBMITSOLUTION
> 0 2
> Z 250
> END
< 3
> GETBESTSOLUTIONS 0 1
< --- 0
< 2 1 1 1 1 1 0
< X 0.5
< Y 0.5
< Z 0.5
< O1 0.5
< C3 1.0
< C3;LHS;1 1.0
< C3;RHS;1 10.0
< C1 1.0
< C1;LHS;1 0.5
< C1;RHS;1 0.5
< C2 1.0
< C2;LHS;1 1.0
< C2;RHS;1 1.0
> GETALLSOLUTIONS 0
< --- 0
< 2 1 1 1 1 1 0
< X 0.5
< Y 0.5
< Z 0.5
< O1 0.5
< C3 1.0
< C3;LHS;1 1.0
< C3;RHS;1 10.0
< C1 1.0
< C1;LHS;1 0.5
< C1;RHS;1 0.5
< C2 1.0
< C2;LHS;1 1.0
< C2;RHS;1 1.0
< --- 1
< 1 1 1 1 1 1 0
< X -2.5
< Y 7.75
< Z 66.0
< O1 -60.75
< C3 1.0
< C3;LHS;1 5.25
< C3;RHS;1 10.0
< C1 1.0
< C1;LHS;1 -2.5
< C1;RHS;1 7.75
< C2 1.0
< C2;LHS;1 5.25
< C2;RHS;1 1.0
< --- 2
< 3 1 1 1 1 1 0
< X -5.0
< Y 15.0
< Z 250.0
< O1 -240.0
< C3 1.0
< C3;LHS;1 10.0
< C3;RHS;1 10.0
< C1 1.0
< C1;LHS;1 -5.0
< C1;RHS;1 15.0
< C2 1.0
< C2;LHS;1 10.0
< C2;RHS;1 1.0
> DELETEMODEL 0
< OK
> QUIT