Package com.opttek.optquest

Class OptQuestModel

java.lang.Object

com.opttek.optquest.OptQuestModel

public class OptQuestModel
extends Object

The main class that defines an OptQuest optimization model. This class is used to configure decision variables (inputs), output variables, constraints, and objectives. It supports a wide range of variable types including continuous, integer, discrete, binary, design, permutation, tuple, geolocation, selection, mixture, low-rank matrices, time series, sequence, DAG, tree, topological sequence, path, choice, multi-choice, and random variables for simulation optimization.

OptQuest is a black-box metaheuristic optimizer suitable for complex, simulation-based, or non-linear problems where derivative information is unavailable. It handles single and multi-objective optimization, variable replications for stochastic responses, confidence testing, adaptive sampling, and surrogate modeling.

Use AddContinuousVariable(String, double, double) (and the many other Add*Variable methods) to define the model, SetReplications(int, int) for stochastic simulations, then call one of the Optimize(...) methods with a custom IOptQuestEvaluator to evaluate solutions.

Solutions are managed via OptQuestSolution instances. Best solutions or frontier points can be retrieved with GetBestSolutions().

Names: OptQuest matches names without regard to case. Flow and flow are the same name, in the API and in expressions. So a model cannot have both Flow and flow: the second Add call returns false because the name already exists. OptQuestSolution.GetInputNames() and OptQuestSolution.GetOutputNames() return each name as you wrote it when you added it.

A variable name must not be the name of a function or a constant of the expression language, such as rate, max, pi or e. In Java the Add call throws COptQuestException with the message "The variable name is a reserved function name."

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

• the selected tuple of a tuple variable and the selected location of a geolocation variable;
• the option of a design or choice variable;
• the bin of an assignment variable and the group of a partition variable;
• the rank of a sequence, multi-stage sequence or topological sequence variable, and the position of an element of a permutation variable;
• the position of a node on a path variable;
• the element numbers in generated names, such as v@1 for the first element of a vector;
• the iteration number (OptQuestSolution.GetIteration()) and the replication number (OptQuestSolution.GetReplication()).

Java arrays start at 0. To use a reported value k as an index into your own array, read element k - 1. A value of 0 has its own meaning: an assignment bin of 0 means that the item is in no bin, and a path position of 0 means that the node is not on the path.

Author:

OptTek Systems, Inc.

See Also:

• COptQuestUserControlledOptimization
• OptQuestSolution
• IOptQuestEvaluator
• IOptQuestMonitor

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	OptQuestModel.Confidence	Constants used for confidence-interval based replication stopping rules.
static class	OptQuestModel.SampleMethod	Constants for sampling methods used with adaptive sampling and surrogate modeling.
static class	OptQuestModel.SampleVariogram	Names of variogram models used when building the surrogate (Kriging) model for adaptive sampling.
static class	OptQuestModel.Statistic	Constants for statistics that can be computed over replications of an output or objective in stochastic simulations.
static class	OptQuestModel.TerminationReason	Possible reasons why an optimization terminated.

Field Summary

Fields

Modifier and Type	Field	Description
final Map<String,com.opttek.optquest.COptQuestStringConstraint>	constraints	Map of all constraints by name.
final Map<String,com.opttek.optquest.COptQuestVariable>	inputs	Map of all input (decision) variables by name.
final Map<String,com.opttek.optquest.COptQuestStringObjective>	objectives	Map of all objectives by name (single- or multi-objective).
final Map<String,com.opttek.optquest.COptQuestUserControlledVariable>	outputs	Map of all output (user-controlled) variables by name.
final Map<com.opttek.optquest.COptQuestSingleObjective,double[]>	RDSBins	Internal map used only when Response Distribution Sampling (RDS) is enabled.
List<OptQuestSolution>	solutions

Constructor Summary

Constructors

Constructor	Description
OptQuestModel()

Method Summary

Modifier and Type	Method	Description
boolean	AddAllSolutions(OptQuestModel src)	Copies every evaluated solution of the source model src into this model.
boolean	AddAngleVariable(String name, double minDeg, double maxDeg)	Adds an angle variable.
boolean	AddAssignmentVariable(String name, int m, int n)	Adds an assignment variable.
boolean	AddAssignmentVariable(String name, int m, int n, boolean[] mustAssign, int[] binCapacitiesMin, int[] binCapacitiesMax)	Adds an assignment variable with separate rules for each item and each bin.
boolean	AddAssignmentVariable(String name, int m, int n, boolean mustAssign, int binCapacityMin, int binCapacityMax)	Adds an assignment variable with the same rules for every item and every bin.
boolean	AddBetaRandomVariable(String name, double alpha, double beta)	Adds a Beta-distributed random variable (used as a random input drawn each replication).
boolean	AddBinaryMatrixVariable(String name, int m, int n)	Adds a binary matrix variable: an m by n matrix of binary variables.
boolean	AddBinaryNDVariable(String name, int[] dims)	Adds a binary N-dimensional variable: an array of binary variables with the shape dims.
boolean	AddBinaryVariable(String name)	Adds a binary variable with the given name.
boolean	AddBinaryVectorVariable(String name, int k)	Adds a binary vector variable: k binary variables.
boolean	AddBSplineCorrectionMatrixVariable(String name, double[][] initial, int knotRows, int knotCols, double min, double max)	Adds a B-spline correction matrix variable.
boolean	AddBSplineCorrectionVectorVariable(String name, double[] initial, int numKnots, double min, double max)	Adds a B-spline correction vector variable.
boolean	AddBSplineMatrixVariable(String name, int rows, int cols, int knotRows, int knotCols, double min, double max)	Adds a B-spline matrix variable.
boolean	AddBSplineVectorVariable(String name, int length, int numKnots, double min, double max)	Adds a B-spline vector variable.
boolean	AddBudgetedSelectionVariable(String name, int n, double[] costs, double budgetMax)	Adds a budgeted selection variable that selects candidates whose total cost is at most budgetMax.
boolean	AddBudgetedSelectionVariable(String name, int n, double[] costs, double budgetMin, double budgetMax, int kMin, int kMax)	Adds a budgeted selection variable with a budget range and a range for the number of selected candidates.
boolean	AddCauchyRandomVariable(String name, double location, double scale)	Adds a Cauchy-distributed random variable.
boolean	AddChiSquareRandomVariable(String name, int df)	Adds a Chi-square-distributed random variable.
boolean	AddChoiceVariable(String name, int k)	Adds a choice variable.
boolean	AddConstraint(String name, String expression)	Defines a linear or non-linear constraint where the expression may include variables and outputs.
boolean	AddContinuousVariable(String name, double min, double max)	Adds a continuous variable with the given name, minimum value and maximum value.
boolean	AddDAGVariable(String name, String[] nodeNames)	Adds a DAG variable.
boolean	AddDAGVariable(String name, String[] nodeNames, String startNode, String endNode, boolean connected, Map<String,List<String>> predecessors)	Adds a DAG variable with an optional start node, an optional end node, the connected option and optional precedences.
boolean	AddDesignVariable(String name, int num)	Deprecated. Use a choice variable instead.
boolean	AddDiscreteMatrixVariable(String name, int m, int n, double min, double max, double step)	Adds a discrete matrix variable: an m by n matrix of discrete variables.
boolean	AddDiscreteNDVariable(String name, int[] dims, double min, double max, double step)	Adds a discrete N-dimensional variable: an array of discrete variables with the shape dims.
boolean	AddDiscreteVariable(String name, double min, double max, double step)	Adds a discrete variable with the given name, minimum value, maximum value and step size.
boolean	AddDiscreteVectorVariable(String name, int n, double min, double max, double step)	Adds a discrete vector variable: n discrete variables.
boolean	AddEnumerationVariable(String name, double[] items)	Adds an enumeration variable: a decision variable that has an enumerated set of values such as 5,7 and 25.
boolean	AddExchangeableGroup(String name, String[] variables)	Declares a group of identical items, one variable for each item, whose values you can exchange without a change to the result.
boolean	AddExchangeableGroup(String name, String[][] variables)	Declares a group of identical items, each described by a row of variables, whose values you can exchange row for row without a change to the result.
boolean	AddExponentialRandomVariable(String name, double scale)	Adds an exponentially distributed random variable.
boolean	AddExpressionVariable(String name, String expression)	Defines a variable that is evaluated as an expression of other variables in the model.
boolean	AddFixGroup(String name, String[] variables)	Declares a fix group: a set of decision variables that the optimizer holds at the values of the best solution found so far while it searches the other variables.
boolean	AddFloatGroup(String name, String[] variables)	Declares a float group: a set of decision variables that the optimizer searches while it holds all the other variables at the values of the best solution found so far.
boolean	AddFourierCorrectionMatrixVariable(String name, double[][] initial, int freqRows, int freqCols, double min, double max)	Adds a Fourier correction matrix variable.
boolean	AddFourierCorrectionVectorVariable(String name, double[] initial, int numFreq, double min, double max)	Adds a Fourier correction vector variable.
boolean	AddFourierMatrixVariable(String name, int rows, int cols, int freqRows, int freqCols, double min, double max)	Adds a Fourier matrix variable.
boolean	AddFourierVectorVariable(String name, int length, int numFreq, double min, double max)	Adds a Fourier vector variable.
boolean	AddGammaRandomVariable(String name, double shape, double scale)	Adds a Gamma-distributed random variable.
boolean	AddGeolocationVariable(String name, double[][] locations)	Adds a geolocation variable: a decision variable whose values are lists of latitude and longitude.
boolean	AddIncrementalLowRankCorrectionMatrixVariable(String name, double[][] initial, int rank, double min, double max)	Adds an incremental low-rank correction matrix variable.
boolean	AddIncrementalTimeSeriesCorrectionVectorVariable(String name, double[] initial, int longScale, int shortScale, int rank, double min, double max)	Adds an incremental time-series correction vector variable.
boolean	AddIntegerMatrixVariable(String name, int m, int n, double min, double max)	Adds an integer matrix variable: an m by n matrix of integer variables.
boolean	AddIntegerNDVariable(String name, int[] dims, double min, double max)	Adds an integer N-dimensional variable: an array of integer variables with the shape dims.
boolean	AddIntegerVariable(String name, double min, double max)	Adds an integer variable with the given name, minimum value and maximum value.
boolean	AddIntegerVectorVariable(String name, int n, double min, double max)	Adds an integer vector variable: n integer variables.
boolean	AddItemSelectionVariable(String name, int n, int k)	Adds an item selection variable that selects exactly k of n candidates.
boolean	AddItemSelectionVariable(String name, int n, int kMin, int kMax)	Adds an item selection variable that selects from kMin to kMax of n candidates.
boolean	AddLogNormalRandomVariable(String name, double shape, double scale)	Adds a log-normal distributed random variable.
boolean	AddLowRankCorrectionMatrixVariable(String name, double[][] initial, int rank, double min, double max)	Adds a low-rank correction matrix variable.
boolean	AddLowRankMatrixVariable(String name, int rows, int cols, int rank, double min, double max)	Adds a low-rank matrix variable.
boolean	AddMatrixVariable(String name, int m, int n, double min, double max)	Adds a matrix variable: an m by n matrix of continuous variables.
boolean	AddMaximizeObjective(String name, String expression)	Defines an objective whose value the optimizer maximizes.
boolean	AddMinimizeObjective(String name, String expression)	Defines an objective whose value the optimizer minimizes.
boolean	AddMixtureVariable(String name, String[] components, double[] lowerBounds, double[] upperBounds, double sumTo)	Adds a mixture variable.
boolean	AddMultiChoiceVariable(String name, String[] choices, int minSelect, int maxSelect)	Adds a multi-choice variable.
boolean	AddMultiStageSequenceVariable(String name, String[][] stageGroups)	Adds a multi-stage sequence variable.
boolean	AddNDVariable(String name, int[] dims, double min, double max)	Adds a N-dimensional variable: an array of continuous variables with the shape dims.
boolean	AddNormalRandomVariable(String name, double mean, double sigma)	Adds a normally distributed random variable.
boolean	AddObjective(String name, String dir, String expression)	Defines an objective whose value the optimizer minimizes or maximizes.
boolean	AddOutputMatrixVariable(String name, int rows, int cols)	Adds an output matrix variable: a rows by cols matrix of output variables.
boolean	AddOutputNDVariable(String name, int[] dims)	Adds an output N-dimensional variable: an array of output variables with the shape dims.
boolean	AddOutputVariable(String name)	Adds an output variable.
boolean	AddOutputVectorVariable(String name, int n)	Adds an output vector variable: n output variables.
boolean	AddParetoRandomVariable(String name, double gamma, double loc, double scale)	Adds a Pareto-distributed random variable.
boolean	AddPartitionVariable(String name, int m, int k)	Adds a partition variable.
boolean	AddPathVariable(String name, String[] nodeNames, String startNode, String endNode, String[] requiredNodes)	Adds a path variable.
boolean	AddPermutationVariable(String group, String[] names)	Deprecated. Use a sequence variable instead.
boolean	AddPoissonRandomVariable(String name, double lambda)	Adds a Poisson-distributed random variable.
boolean	AddPolicySequenceVariable(String name, double[][] featureMatrix, String[] itemNames, String[] featureNames)	Adds a policy sequence variable.
boolean	AddPowerRandomVariable(String name, double rmin, double rmax, double power)	Adds a random variable whose value is from rmin to rmax.
boolean	AddRegionVariable(String name, double[][] polygon)	Adds a region variable.
boolean	AddSampleMetric(String name, String responseExpression, String errorExpression)	Defines a response metric and an error metric that the engine tracks for adaptive sampling.
boolean	AddSelectionVariable(String name, String[] selVars)	Selection variables are used to add or remove other variables from the optimization.
boolean	AddSequenceVariable(String name, String[] components, Integer topK)	Adds a sequence variable.
boolean	AddSphericalAngleVariable(String name, double minThetaDeg, double maxThetaDeg, double minPhiDeg, double maxPhiDeg)	Adds a spherical angle variable.
boolean	AddSphericalElevationRandomVariable(String name, double min, double max)	Adds a spherical elevation random variable.
boolean	AddSphericalRegionVariable(String name, double[][] polygon)	Adds a spherical region variable.
boolean	AddSplineCorrectionMatrixVariable(String name, double[][] initial, int knotRows, int knotCols, double min, double max)	Adds a spline correction matrix variable.
boolean	AddSplineCorrectionVectorVariable(String name, double[] initial, int numKnots, double min, double max)	Adds a spline correction vector variable.
boolean	AddSplineMatrixVariable(String name, int rows, int cols, int knotRows, int knotCols, double min, double max)	Adds a spline matrix variable.
boolean	AddSplineVectorVariable(String name, int length, int numKnots, double min, double max)	Adds a spline vector variable.
boolean	AddStudentTRandomVariable(String name, int df)	Adds a Student's t-distributed random variable.
boolean	AddTimeSeriesCorrectionVectorVariable(String name, double[] initial, int longScale, int shortScale, int rank, double min, double max)	Adds a time-series correction vector variable.
boolean	AddTimeSeriesVectorVariable(String name, int longScale, int shortScale, int rank, double min, double max)	Adds a time-series vector variable.
boolean	AddTopologicalSequenceVariable(String name, String[] tasks, Map<String,List<String>> predecessors)	Adds a topological sequence variable.
boolean	AddTreeVariable(String name, String[] nodeNames)	Adds a tree variable.
boolean	AddTreeVariable(String name, String[] nodeNames, String rootNode, Map<String,List<String>> predecessors)	Adds a tree variable with an optional fixed root and optional precedences.
boolean	AddTupleVariable(String name, double[][] tuples)	Adds a tuple variable: a decision variable whose values are lists of tuples.
boolean	AddUniformRandomVariable(String name, double min, double max)	Adds a uniform random variable.
boolean	AddVariableExclusiveRange(String name, double min, double max)	Defines a range of values that will be excluded as possible solutions for the variable identified by the name.
boolean	AddVectorVariable(String name, int n, double min, double max)	Adds a vector variable: n continuous variables.
boolean	AddWeibullRandomVariable(String name, double shape, double scale)	Adds a Weibull-distributed random variable.
void	CleanUp()	Closes the log files opened by LogSetup(String) and LogSolutions(String).
void	Continue()	Restarts an optimization that was interrupted with a call to Interrupt().
OptQuestSolution	CopySolution(OptQuestSolution src)	Make a copy of the input OptQuestSolution.
OptQuestModelChannel	CreateAsyncChannel(int npar)	Creates an asynchronous communication channel to send signals to the model during an optimization
OptQuestSolution	CreateSolution()	Requests the OptQuestModel to generate a new trial solution for evaluation.
String	Describe()	Generates a string describing the model parameters.
List<OptQuestSolution>	GetAllSolutions()	Returns all evaluated solutions.
List<OptQuestSolution>	GetBestSolutions()	If the OptQuestModel has a single objective, this method returns the best solution.
List<OptQuestSolution>	GetBestSolutions(int limit)	If the OptQuestModel has a single objective, this method returns the best n solutions where n is the limit parameter.
OptQuestSolution	GetEmptySolution()	Creates an empty OptQuestSolution.
int	GetMaxReplications()	Returns the maximum number of replications set by SetReplications(int, int), or 0 before the model has initialized successfully.
int	GetNumberOfCompletedIterations()	Returns the number of solutions that have been evaluated.
int	GetTerminationReason()	Returns why the last run stopped, as one of the OptQuestModel.TerminationReason constants.
boolean	Initialize()	Prepares the model to run and moves it from the definition stage to the execution stage, after which the model is immutable.
void	Interrupt()	Signals the OptQuestModel to stop generating new solutions during manual optimization loops.
boolean	LogSetup(String filespec)	LogSetup() logs the OptQuestModel setup in an xml formatted file.
boolean	LogSolutions(String filespec)	LogSolutions() logs all solutions in a csv formatted file.
boolean	Optimize(int nsol)	Starts the optimization and stops when nsol solutions have been evaluated.
boolean	Optimize(int npar, int nsol)	Starts the optimization and stops when nsol solutions have been evaluated.
boolean	Optimize(int npar, int nsol, IOptQuestEvaluator eval)	Starts the optimization and stops when nsol solutions have been evaluated.
boolean	Optimize(int npar, int nsol, IOptQuestEvaluator eval, IOptQuestMonitor monitor)	Starts the optimization and stops when nsol solutions have been evaluated.
boolean	Optimize(int nsol, IOptQuestEvaluator eval)	Starts the optimization and stops when nsol solutions have been evaluated.
boolean	Optimize(int nsol, IOptQuestEvaluator eval, IOptQuestMonitor monitor)	Starts the optimization and stops when nsol solutions have been evaluated.
boolean	Optimize(OptQuestModelChannel ipc, int nsol)	Starts the optimization and stops when nsol solutions have been evaluated.
boolean	Optimize(OptQuestModelChannel ipc, int nsol, IOptQuestEvaluator eval)	Starts the optimization and stops when nsol solutions have been evaluated.
boolean	Optimize(OptQuestModelChannel ipc, int nsol, IOptQuestEvaluator eval, IOptQuestMonitor monitor)	Starts the optimization and stops when nsol solutions have been evaluated.
boolean	Sample(int nsol)	Starts an adaptive sampling run and stops when nsol solutions have been evaluated.
boolean	Sample(int npar, int nsol)	Starts a concurrent adaptive sampling run using npar parallel evaluators and stops when nsol solutions have been evaluated.
boolean	Sample(int npar, int nsol, IOptQuestEvaluator eval)	Starts a concurrent adaptive sampling run using npar parallel evaluators.
boolean	Sample(int npar, int nsol, IOptQuestEvaluator eval, IOptQuestMonitor monitor)	Starts a concurrent adaptive sampling run using npar parallel evaluators.
boolean	Sample(int nsol, IOptQuestEvaluator eval)	Starts an adaptive sampling run and stops when nsol solutions have been evaluated.
boolean	Sample(int nsol, IOptQuestEvaluator eval, IOptQuestMonitor monitor)	Starts an adaptive sampling run and stops when nsol solutions have been evaluated.
boolean	Sample(OptQuestModelChannel ipc, int nsol)	Starts an asynchronous adaptive sampling run.
boolean	Sample(OptQuestModelChannel ipc, int nsol, IOptQuestEvaluator eval)	Starts an asynchronous adaptive sampling run with a custom evaluator.
boolean	Sample(OptQuestModelChannel ipc, int nsol, IOptQuestEvaluator eval, IOptQuestMonitor monitor)	Starts an asynchronous adaptive sampling run with a custom evaluator and monitor.
boolean	SetLicense(String license)	Sets the license ID that OptTek Systems, Inc.
boolean	SetObjectiveConfidence(String name, int ctype, int clevel, double epct)	Sets the values used for replication confidence testing on the specified objective.
boolean	SetObjectiveGoal(String name, double min, double max)	Sets a target range, from min to max inclusive, for an objective in a model with two or more objectives.
boolean	SetObjectiveStatistic(String name, int statistic)	Defines the statistic for the replications of an objective.
boolean	SetObjectiveStatistic(String name, int statistic, double statisticValue)	Defines the percentile statistic for the replications of an objective.
boolean	SetOutputStatistic(String name, int statistic)	Defines the statistic for the replications of an output variable.
boolean	SetOutputStatistic(String name, int statistic, double statisticValue)	Defines the percentile statistic for the replications of an output variable.
boolean	SetParallelHint(int npar)	Sets a hint for the number of parallel evaluations that are expected to happen.
boolean	SetRandomSeed(int seed)	Sets the random seed.
boolean	SetReplications(int reps)	Sets the number of fixed replications to be run for each solution.
boolean	SetReplications(int min, int max)	Sets the number of variable replications to be run for each solution.
boolean	SetSampleMethod(int method)	Sets the sample method to be used when using sample metrics.
boolean	SetSampleRDSBeta(String name, int nBins, double alpha, double beta)	Sets the bins to use if response distribution sampling is enabled, from a Beta distribution.
boolean	SetSampleRDSCauchy(String name, int nBins, double location, double scale)	Sets the bins to use if response distribution sampling is enabled, from a Cauchy distribution.
boolean	SetSampleRDSChiSquare(String name, int nBins, double nu)	Sets the bins to use if response distribution sampling is enabled, from a Chi-square distribution.
boolean	SetSampleRDSDiscrete(String name, double[] binEdges)	Sets the bins to use if response distribution sampling is enabled, from a list of bin edges.
boolean	SetSampleRDSExponential(String name, int nBins, double scale)	Sets the bins to use if response distribution sampling is enabled, from an exponential distribution.
boolean	SetSampleRDSGamma(String name, int nBins, double a, double scale)	Sets the bins to use if response distribution sampling is enabled, from a Gamma distribution.
boolean	SetSampleRDSLogNormal(String name, int nBins, double s, double scale)	Sets the bins to use if response distribution sampling is enabled, from a log-normal distribution.
boolean	SetSampleRDSNormal(String name, int nBins, double mu, double sigma)	Sets the bins to use if response distribution sampling is enabled, from a normal distribution.
boolean	SetSampleRDSParams(String name, String distribution, double[] params)	Sets the bins to use if response distribution sampling is enabled, from a named distribution.
boolean	SetSampleRDSPareto(String name, int nBins, double gamma, double loc, double scale)	Sets the bins to use if response distribution sampling is enabled, from a Pareto distribution.
boolean	SetSampleRDSPoisson(String name, int nBins, double lambda)	Sets the bins to use if response distribution sampling is enabled, from a Poisson distribution.
boolean	SetSampleRDST(String name, int nBins, double nu)	Sets the bins to use if response distribution sampling is enabled, from a Student's t distribution.
boolean	SetSampleRDSUniform(String name, int nBins, double a, double b)	Sets the bins to use if response distribution sampling is enabled, from a uniform distribution.
boolean	SetSampleRDSWeibull(String name, int nBins, double c, double scale)	Sets the bins to use if response distribution sampling is enabled, from a Weibull distribution.
boolean	SetSampleVariogram(String variogram)	Sets the sample variogram to be used when building the surrogate model.
boolean	SetSerialReplications()	Runs the replications of each solution serially.
boolean	SetStopCycles(int cycles)	Stops the optimization after cycles search cycles.
boolean	SetStopImprovement(double improvement, int iterations)	Stops the optimization when iterations consecutive iterations pass without a cumulative improvement of more than the fraction improvement.
boolean	SetStopTime(int seconds)	Sets the number of seconds the optimization should run before stopping.
void	SetTerminationReason(int reason)	Sets the termination reason.
boolean	StopOnSuccessfulMILP()	Sets a flag so that the optimization stops as soon as it finds an optimal solution in the case that the optimization is a mixed integer linear program (MILP).
boolean	SuggestedSolutionsOnly()	Restricts the model to the solutions you supply.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

inputs

public final Map<String,com.opttek.optquest.COptQuestVariable> inputs

Map of all input (decision) variables by name. Populated automatically when any Add*Variable method is called. LinkedHashMap preserves insertion order.

outputs

public final Map<String,com.opttek.optquest.COptQuestUserControlledVariable> outputs

Map of all output (user-controlled) variables by name. Includes expression variables and variables added via AddOutputVariable(String). LinkedHashMap preserves insertion order, matching inputs.

constraints

public final Map<String,com.opttek.optquest.COptQuestStringConstraint> constraints

Map of all constraints by name. LinkedHashMap preserves insertion order.

objectives

public final Map<String,com.opttek.optquest.COptQuestStringObjective> objectives

Map of all objectives by name (single- or multi-objective). LinkedHashMap preserves insertion order.

RDSBins

public final Map<com.opttek.optquest.COptQuestSingleObjective,double[]> RDSBins

Internal map used only when Response Distribution Sampling (RDS) is enabled.

solutions

public List<OptQuestSolution> solutions

Constructor Details

OptQuestModel

public OptQuestModel()

Method Details

SetLicense

public boolean SetLicense(String license)

Sets the license ID that OptTek Systems, Inc. assigned to you. If no license is set, the demo license is used, which limits the number of iterations to 50.

Parameters:

license - - license ID

Returns:

true if the method was successful.

LogSetup

public boolean LogSetup(String filespec)

LogSetup() logs the OptQuestModel setup in an xml formatted file. This is used for debugging optimization setup problems.

Parameters:

filespec - path to a file that will contain the logging info

Returns:

true if the method was successful.

LogSolutions

public boolean LogSolutions(String filespec)

LogSolutions() logs all solutions in a csv formatted file.

Parameters:

filespec - path to a file that will contain the solution log

Returns:

true if the method was successful.

AddContinuousVariable

public boolean AddContinuousVariable(String name,
 double min,
 double max)
                              throws com.opttek.optquest.COptQuestException

Adds a continuous variable with the given name, minimum value and maximum value. A continuous variable can have any value between the minimum bound and the maximum bound.

Parameters:

name - - name of the variable. The name must be unique to the model and must not contain whitespace or semicolons.

min - - minimum value for the continuous variable

max - - maximum value for the continuous variable

Returns:

true if the variable was added; false if the name is not valid, for example if it is already in use or contains whitespace or a semicolon

Throws:

com.opttek.optquest.COptQuestException - - An exception is thrown if an error occurred adding the variable.

AddIntegerVariable

public boolean AddIntegerVariable(String name,
 double min,
 double max)
                           throws com.opttek.optquest.COptQuestException

Adds an integer variable with the given name, minimum value and maximum value. The variable takes the values min, min + 1, min + 2, and so on, up to max. Give whole-number bounds to get whole-number values.

Parameters:

name - - name of the variable. The name must be unique to the model and must not contain whitespace or semicolons.

min - - minimum value for the integer variable

max - - maximum value for the integer variable

Returns:

true if the variable was added; false if the name is not valid, for example if it is already in use or contains whitespace or a semicolon

Throws:

com.opttek.optquest.COptQuestException - - An exception is thrown if an error occurred adding the variable.

AddDiscreteVariable

public boolean AddDiscreteVariable(String name,
 double min,
 double max,
 double step)
                            throws com.opttek.optquest.COptQuestException

Adds a discrete variable with the given name, minimum value, maximum value and step size. The variable takes the values min, min + step, min + 2 × step, and so on. The largest value is the one nearest to max, so it can differ from max when max - min is not a whole multiple of step.

Parameters:

name - - name of the variable. The name must be unique to the model and must not contain whitespace or semicolons.

min - - minimum value for the variable

max - - maximum value for the variable

step - - step between values; must be greater than 0

Returns:

true if the variable was added; false if the name is not valid, for example if it is already in use or contains whitespace or a semicolon

Throws:

com.opttek.optquest.COptQuestException - - An exception is thrown if an error occurred adding the variable.

AddBinaryVariable

public boolean AddBinaryVariable(String name)
                          throws com.opttek.optquest.COptQuestException

Adds a binary variable with the given name.

Parameters:

name - - name of the variable. The name must be unique to the model and must not contain whitespace or semicolons.

Returns:

true if the variable was added; false if the name is not valid, for example if it is already in use or contains whitespace or a semicolon

Throws:

com.opttek.optquest.COptQuestException - - An exception is thrown if an error occurred adding the variable.

AddDesignVariable

@Deprecated
public boolean AddDesignVariable(String name,
 int num)
                          throws com.opttek.optquest.COptQuestException

Deprecated.

Use a choice variable instead. Add it with AddChoiceVariable(String, int). A choice variable gives the number of the selected option, from 1 to the number of options.

Design variables are used when the value of the decision variable represents an alternative, and not a quantity. For example, the variable may take on the values red, green or blue. Design variables are useful in optimization problems where the decision variables consist of choosing the best alternative from a catalog, and a larger number may not imply the commitment of more resources. Therefore, choice #10 may not be a more costly or a better choice than choice #1. Adds a design variable with the given name and the number of possible choices.

Parameters:

name - - name of the variable. The name must be unique to the model and must not contain whitespace or semicolons.

num - - number of possible choices.

Returns:

true if the variable was added; false if the name is not valid, for example if it is already in use or contains whitespace or a semicolon

Throws:

com.opttek.optquest.COptQuestException - - An exception is thrown if an error occurred adding the variable.

AddEnumerationVariable

public boolean AddEnumerationVariable(String name,
 double[] items)
                               throws com.opttek.optquest.COptQuestException

Adds an enumeration variable: a decision variable that has an enumerated set of values such as 5,7 and 25.

Parameters:

name - - name of the variable. The name must be unique to the model and must not contain whitespace or semicolons.

items - - the array of valid values

Returns:

true if the variable was added; false if the name is not valid, for example if it is already in use or contains whitespace or a semicolon

Throws:

com.opttek.optquest.COptQuestException - - An exception is thrown if an error occurred adding the variable.

AddPermutationVariable

@Deprecated
public boolean AddPermutationVariable(String group,
 String[] names)
                               throws com.opttek.optquest.COptQuestException

Deprecated.

Use a sequence variable instead. Add it with AddSequenceVariable(String, String[], Integer). A sequence variable gives the same ranks, from 1 to n, and it also has a top-k mode.

Permutation variables are used to solve sequencing problems. For example, you could use permutation variables to determine the order in which paint should be mixed to minimize cleanup time between color changes. The value of a permutation variable represents its position within the sequence. A decision variable will be created for each entry in the names[] array. They will be named with the prefix group@ signifying their membership in the group.

Parameters:

group - - Group identifier.

names - - the list of the names in the sequence.

Returns:

true if the variables were added; false if the group name or a member name is not valid, for example if it is already in use or contains whitespace or a semicolon, or if two member names are the same

Throws:

com.opttek.optquest.COptQuestException - - An exception is thrown if an error occurred adding the variable.

AddTupleVariable

public boolean AddTupleVariable(String name,
 double[][] tuples)
                         throws com.opttek.optquest.COptQuestException

Adds a tuple variable: a decision variable whose values are lists of tuples. Tuple variables are used for discrete choices in multiple dimensions, and are intended to be used when a Euclidean distance between values is meaningful. For example, consider three options (a1,b1), (a2,b2), and (a3,b3). The 2D Euclidean distance between the options will be used to determine closeness when searching for good solutions.

Parameters:

name - - name of the variable. The name must be unique to the model and must not contain whitespace or semicolons.

tuples - - the list of discrete choices

Returns:

true if the variable was added; false if the name is not valid, for example if it is already in use or contains whitespace or a semicolon

Throws:

com.opttek.optquest.COptQuestException - - An exception is thrown if an error occurred adding the variable.

AddGeolocationVariable

public boolean AddGeolocationVariable(String name,
 double[][] locations)
                               throws com.opttek.optquest.COptQuestException

Adds a geolocation variable: a decision variable whose values are lists of latitude and longitude. This is a specialization of the tuple with extra restrictions on the size of the tuple (2) and distance is on a sphere rather than Euclidean distance.

Parameters:

name - - name of the variable. The name must be unique to the model and must not contain whitespace or semicolons.

locations - - list of latitude and longitude for the geolocation.

Returns:

true if the variable was added; false if the name is not valid, for example if it is already in use or contains whitespace or a semicolon

Throws:

com.opttek.optquest.COptQuestException - - An exception is thrown if an error occurred adding the variable.

AddSelectionVariable

public boolean AddSelectionVariable(String name,
 String[] selVars)
                             throws com.opttek.optquest.COptQuestException

Selection variables are used to add or remove other variables from the optimization. With a COptQuestSelectionGroup, the user has a binary variable whose value indicates an on/off state, where the off state indicates that other variables are not used in the evaluation. The OptQuest Engine maps the dependent variables to their lower bounds when the variable indicating the state is set to the off state.

Parameters:

name - - The name of the newly created binary variable to signify selection.

selVars - - the list of the names of other variables to be included when the name binary variable is true.

Returns:

true if the variable was added; false if the name is not valid, for example if it is already in use or contains whitespace or a semicolon

Throws:

com.opttek.optquest.COptQuestException - - An exception is thrown if an error occurred adding the variable.

AddExchangeableGroup

public boolean AddExchangeableGroup(String name,
 String[] variables)
                             throws com.opttek.optquest.COptQuestException

Declares a group of identical items, one variable for each item, whose values you can exchange without a change to the result. An example is the capacities of three identical chillers. In each trial solution that the optimizer generates, it puts the values of the members in ascending order, in the order of variables: the first member has the smallest value. Thus the optimizer does not evaluate two solutions that differ only by an exchange of values. The optimizer evaluates a solution that you suggest with the values that you give.

Use an exchangeable group only for items that have the same type, the same bounds and the same role in your evaluation. If the items differ, for example machines with different capacities, a solution and the same solution with two values exchanged are different solutions, and the optimizer evaluates only one of them. If the bounds differ, the optimizer searches only values that fit the bounds of the members in ascending order. Put a variable in no more than one exchangeable group. If a variable is in two groups, the order of the second group can break the order of the first group.

Each member must be a decision variable that is already in the model: a continuous, integer, discrete, binary, design, enumeration, tuple, geolocation or selection variable, or an element of a vector, matrix, N-dimensional, item-selection or budgeted-selection variable under its generated name, such as v@1. The values of a manifold variable, such as dir@theta, are not accepted. Names are matched without regard to case.

Parameters:

name - - group name; must be unique in the model and free of whitespace and semicolons. This call adds no variable.

variables - - names of the members, one for each item.

Returns:

- true if the group was added; false if the model is already initialized, if the name is not valid or is already in use, or if a member is not a decision variable of the model.

Throws:

com.opttek.optquest.COptQuestException - - if the engine cannot add the group.

AddExchangeableGroup

public boolean AddExchangeableGroup(String name,
 String[][] variables)
                             throws com.opttek.optquest.COptQuestException

Declares a group of identical items, each described by a row of variables, whose values you can exchange row for row without a change to the result. An example is three identical machines, each with an x and a y position. In each trial solution that the optimizer generates, it puts the rows in ascending order, in the order of variables: by the value of the first variable of each row, then by the second variable when the first values are equal, and so on. Thus the optimizer does not evaluate two solutions that differ only by an exchange of rows. The optimizer evaluates a solution that you suggest with the values that you give.

Every row must have the same number of variables, in the same order: in the machine example, x first and y second in each row. Use an exchangeable group only for items that have the same type, the same bounds and the same role in your evaluation. If the items differ, a solution and the same solution with two rows exchanged are different solutions, and the optimizer evaluates only one of them. If the bounds differ, the optimizer searches only values that fit the bounds of the members in ascending order. Put a variable in no more than one exchangeable group. If a variable is in two groups, the order of the second group can break the order of the first group.

Each member must be a decision variable that is already in the model: a continuous, integer, discrete, binary, design, enumeration, tuple, geolocation or selection variable, or an element of a vector, matrix, N-dimensional, item-selection or budgeted-selection variable under its generated name, such as v@1. The values of a manifold variable, such as dir@theta, are not accepted. Names are matched without regard to case.

Parameters:

name - - group name; must be unique in the model and free of whitespace and semicolons. This call adds no variable.

variables - - one row for each item, each row holding the names of the variables of that item.

Returns:

- true if the group was added; false if the model is already initialized, if the name is not valid or is already in use, or if a member is not a decision variable of the model.

Throws:

com.opttek.optquest.COptQuestException - - EXCEPT_BADVARIABLEDIMENSIONS, "Variable definitions are of unequal length.", if the rows do not all have the same number of variables.

AddFixGroup

public boolean AddFixGroup(String name,
 String[] variables)
                    throws com.opttek.optquest.COptQuestException

Declares a fix group: a set of decision variables that the optimizer holds at the values of the best solution found so far while it searches the other variables. After an initial part of the search, the optimizer makes one more trial solution from each new trial solution. In that trial solution, the members of the group have the values of the best solution, and all the other variables keep the values of the new trial solution. The optimizer also evaluates the new trial solution. The length of the initial part increases with the number of variables. The optimizer counts these trial solutions in the iteration budget, and it does not evaluate one that duplicates a solution it already has.

Use a fix group when you want more of the search to change the other variables near the best solution. With a fix group of a set of variables, the optimizer makes the same trial solutions as with a float group (AddFloatGroup(String, String[])) of all the other decision variables, so declare the smaller set. For each group that you add, the optimizer makes its own trial solutions. For a group with no members and for a group that holds every decision variable, the optimizer makes no extra trial solutions.

Each member must be a decision variable that is already in the model: a continuous, integer, discrete, binary, design, enumeration, tuple, geolocation or selection variable, or an element of a vector, matrix, N-dimensional, item-selection or budgeted-selection variable under its generated name, such as v@1. The values of a manifold variable, such as dir@theta, are not accepted. Names are matched without regard to case.

Parameters:

name - group name; must be unique in the model and free of whitespace and semicolons. This call adds no variable.

variables - names of the members

Returns:

true if the group was added; false if the model is already initialized, if the name is not valid or is already in use, or if a member is not a decision variable of the model

Throws:

com.opttek.optquest.COptQuestException - if the engine cannot add the group

AddFloatGroup

public boolean AddFloatGroup(String name,
 String[] variables)
                      throws com.opttek.optquest.COptQuestException

Declares a float group: a set of decision variables that the optimizer searches while it holds all the other variables at the values of the best solution found so far. After an initial part of the search, the optimizer makes one more trial solution from each new trial solution. In that trial solution, the members of the group keep the values of the new trial solution, and all the other variables have the values of the best solution. The optimizer also evaluates the new trial solution. The length of the initial part increases with the number of variables. The optimizer counts these trial solutions in the iteration budget, and it does not evaluate one that duplicates a solution it already has.

Use a float group when you want more of the search to change a small set of variables near the best solution. With a float group of a set of variables, the optimizer makes the same trial solutions as with a fix group (AddFixGroup(String, String[])) of all the other decision variables, so declare the smaller set. For each group that you add, the optimizer makes its own trial solutions. For a group with no members and for a group that holds every decision variable, the optimizer makes no extra trial solutions.

Each member must be a decision variable that is already in the model: a continuous, integer, discrete, binary, design, enumeration, tuple, geolocation or selection variable, or an element of a vector, matrix, N-dimensional, item-selection or budgeted-selection variable under its generated name, such as v@1. The values of a manifold variable, such as dir@theta, are not accepted. Names are matched without regard to case.

Parameters:

name - group name; must be unique in the model and free of whitespace and semicolons. This call adds no variable.

variables - names of the members

Returns:

true if the group was added; false if the model is already initialized, if the name is not valid or is already in use, or if a member is not a decision variable of the model

Throws:

com.opttek.optquest.COptQuestException - if the engine cannot add the group

AddVariableExclusiveRange

public boolean AddVariableExclusiveRange(String name,
 double min,
 double max)
                                  throws com.opttek.optquest.COptQuestException

Defines a range of values that will be excluded as possible solutions for the variable identified by the name. Any value > min and < max will be excluded. Multiple ranges can be defined on one variable.

Parameters:

name - - name of the variable that will have the exclusive range.

min - - any value > min will be excluded

max - - any value < max will be excluded

Returns:

- true if the variable was added successfully; false if an input with the name does not exist.

Throws:

com.opttek.optquest.COptQuestException - - An exception is thrown if an error occurred adding the variable.

AddVectorVariable

public boolean AddVectorVariable(String name,
 int n,
 double min,
 double max)
                          throws com.opttek.optquest.COptQuestException

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

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

The value of each element is a continuous value from min to max.

Parameters:

name - base name of the variable; it must be unique and must not contain whitespace or a semicolon

n - number of elements; must be at least 1

min - lower bound of each element

max - upper bound of each element

Returns:

true if the variable was added; false if the name is not valid, for example if it is already in use or contains whitespace or a semicolon

Throws:

com.opttek.optquest.COptQuestException - if n is less than 1

AddMatrixVariable

public boolean AddMatrixVariable(String name,
 int m,
 int n,
 double min,
 double max)
                          throws com.opttek.optquest.COptQuestException

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

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

The value of each element is a continuous value from min to max.

Parameters:

name - base name of the variable; it must be unique and must not contain whitespace or a semicolon

m - number of rows; must be at least 1

n - number of columns; must be at least 1

min - lower bound of each element

max - upper bound of each element

Returns:

true if the variable was added; false if the name is not valid, for example if it is already in use or contains whitespace or a semicolon

Throws:

com.opttek.optquest.COptQuestException - if m or n is less than 1

AddBinaryVectorVariable

public boolean AddBinaryVectorVariable(String name,
 int k)
                                throws com.opttek.optquest.COptQuestException

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

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

The value of each element is 0 or 1.

Parameters:

name - base name of the variable; it must be unique and must not contain whitespace or a semicolon

k - number of elements; must be at least 1

Returns:

true if the variable was added; false if the name is not valid, for example if it is already in use or contains whitespace or a semicolon

Throws:

com.opttek.optquest.COptQuestException - if k is less than 1

AddBinaryMatrixVariable

public boolean AddBinaryMatrixVariable(String name,
 int m,
 int n)
                                throws com.opttek.optquest.COptQuestException

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

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

The value of each element is 0 or 1.

Parameters:

name - base name of the variable; it must be unique and must not contain whitespace or a semicolon

m - number of rows; must be at least 1

n - number of columns; must be at least 1

Returns:

true if the variable was added; false if the name is not valid, for example if it is already in use or contains whitespace or a semicolon

Throws:

com.opttek.optquest.COptQuestException - if m or n is less than 1

AddIntegerVectorVariable

public boolean AddIntegerVectorVariable(String name,
 int n,
 double min,
 double max)
                                 throws com.opttek.optquest.COptQuestException

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

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

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

Parameters:

name - base name of the variable; it must be unique and must not contain whitespace or a semicolon

n - number of elements; must be at least 1

min - lower bound of each element

max - upper bound of each element

Returns:

true if the variable was added; false if the name is not valid, for example if it is already in use or contains whitespace or a semicolon

Throws:

com.opttek.optquest.COptQuestException - if n is less than 1

AddIntegerMatrixVariable

public boolean AddIntegerMatrixVariable(String name,
 int m,
 int n,
 double min,
 double max)
                                 throws com.opttek.optquest.COptQuestException

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

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

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

Parameters:

name - base name of the variable; it must be unique and must not contain whitespace or a semicolon

m - number of rows; must be at least 1

n - number of columns; must be at least 1

min - lower bound of each element

max - upper bound of each element

Returns:

true if the variable was added; false if the name is not valid, for example if it is already in use or contains whitespace or a semicolon

Throws:

com.opttek.optquest.COptQuestException - if m or n is less than 1

AddDiscreteVectorVariable

public boolean AddDiscreteVectorVariable(String name,
 int n,
 double min,
 double max,
 double step)
                                  throws com.opttek.optquest.COptQuestException

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

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

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

Parameters:

name - base name of the variable; it must be unique and must not contain whitespace or a semicolon

n - number of elements; must be at least 1

min - lower bound of each element

max - upper bound of each element

step - step between values; must be greater than 0

Returns:

true if the variable was added; false if the name is not valid, for example if it is already in use or contains whitespace or a semicolon

Throws:

com.opttek.optquest.COptQuestException - if n is less than 1

AddDiscreteMatrixVariable

public boolean AddDiscreteMatrixVariable(String name,
 int m,
 int n,
 double min,
 double max,
 double step)
                                  throws com.opttek.optquest.COptQuestException

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

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

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

Parameters:

name - base name of the variable; it must be unique and must not contain whitespace or a semicolon

m - number of rows; must be at least 1

n - number of columns; must be at least 1

min - lower bound of each element

max - upper bound of each element

step - step between values; must be greater than 0

Returns:

true if the variable was added; false if the name is not valid, for example if it is already in use or contains whitespace or a semicolon

Throws:

com.opttek.optquest.COptQuestException - if m or n is less than 1

AddNDVariable

public boolean AddNDVariable(String name,
 int[] dims,
 double min,
 double max)
                      throws com.opttek.optquest.COptQuestException

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

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

The value of each element is a continuous value from min to max.

Parameters:

name - base name of the variable; it must be unique and must not contain whitespace or a semicolon

dims - size of each dimension; there must be at least one dimension, and each size must be at least 1

min - lower bound of each element

max - upper bound of each element

Returns:

true if the variable was added; false if the name is not valid, for example if it is already in use or contains whitespace or a semicolon

Throws:

com.opttek.optquest.COptQuestException - if dims is null or empty, or if a size is less than 1

AddIntegerNDVariable

public boolean AddIntegerNDVariable(String name,
 int[] dims,
 double min,
 double max)
                             throws com.opttek.optquest.COptQuestException

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

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

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

Parameters:

name - base name of the variable; it must be unique and must not contain whitespace or a semicolon

dims - size of each dimension; there must be at least one dimension, and each size must be at least 1

min - lower bound of each element

max - upper bound of each element

Returns:

true if the variable was added; false if the name is not valid, for example if it is already in use or contains whitespace or a semicolon

Throws:

com.opttek.optquest.COptQuestException - if dims is null or empty, or if a size is less than 1

AddDiscreteNDVariable

public boolean AddDiscreteNDVariable(String name,
 int[] dims,
 double min,
 double max,
 double step)
                              throws com.opttek.optquest.COptQuestException

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

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

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

Parameters:

name - base name of the variable; it must be unique and must not contain whitespace or a semicolon

dims - size of each dimension; there must be at least one dimension, and each size must be at least 1

min - lower bound of each element

max - upper bound of each element

step - step between values; must be greater than 0

Returns:

true if the variable was added; false if the name is not valid, for example if it is already in use or contains whitespace or a semicolon

Throws:

com.opttek.optquest.COptQuestException - if dims is null or empty, or if a size is less than 1

AddBinaryNDVariable

public boolean AddBinaryNDVariable(String name,
 int[] dims)
                            throws com.opttek.optquest.COptQuestException

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

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

The value of each element is 0 or 1.

Parameters:

name - base name of the variable; it must be unique and must not contain whitespace or a semicolon

dims - size of each dimension; there must be at least one dimension, and each size must be at least 1

Returns:

true if the variable was added; false if the name is not valid, for example if it is already in use or contains whitespace or a semicolon

Throws:

com.opttek.optquest.COptQuestException - if dims is null or empty, or if a size is less than 1

AddOutputNDVariable

public boolean AddOutputNDVariable(String name,
 int[] dims)
                            throws com.opttek.optquest.COptQuestException

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

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

Your evaluator writes a value to each element before it submits the solution.

Parameters:

name - base name of the variable; it must be unique and must not contain whitespace or a semicolon

dims - size of each dimension; there must be at least one dimension, and each size must be at least 1

Returns:

true if the variable was added; false if the name is not valid, for example if it is already in use or contains whitespace or a semicolon

Throws:

com.opttek.optquest.COptQuestException - if dims is null or empty, or if a size is less than 1

AddAngleVariable

public boolean AddAngleVariable(String name,
 double minDeg,
 double maxDeg)
                         throws com.opttek.optquest.COptQuestException

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

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

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

The engine reports the angle as its equivalent from 0 up to, but not including, 360, not in the range that you declare. For example, for an arc declared from -45 to 45, the engine reports -45 as 315. To compare the value with the declared bounds, add or subtract 360 until the value is at least minDeg and less than minDeg + 360. The value is then from minDeg to maxDeg. When minDeg is greater than maxDeg, compare the value with maxDeg + 360 instead of maxDeg. For example, on the arc from 320 to 40, a reported 10 becomes 370, which is from 320 to 400.

Parameters:

name - base name of the variable; it must be unique and must not contain whitespace or a semicolon

minDeg - start of the arc, in degrees

maxDeg - end of the arc, in degrees

Returns:

true if the variable was added; false if the name is not valid, for example if it is already in use or contains whitespace or a semicolon

Throws:

com.opttek.optquest.COptQuestException - if minDeg or maxDeg is NaN

AddSphericalAngleVariable

public boolean AddSphericalAngleVariable(String name,
 double minThetaDeg,
 double maxThetaDeg,
 double minPhiDeg,
 double maxPhiDeg)
                                  throws com.opttek.optquest.COptQuestException

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

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

Variable names:

• <name>@theta: the elevation in degrees, from -90 (straight down) through 0 (the horizon) to 90 (straight up).
• <name>@phi: the azimuth in degrees, where 0 is north and 90 is east.

The engine reports the azimuth as its equivalent from 0 up to, but not including, 360, not in the range that you declare. For example, for an azimuth declared from -60 to 60, the engine reports -60 as 300. To compare the azimuth with the declared bounds, use the rule for an angle variable, with minPhiDeg and maxPhiDeg. The engine reports the elevation as it is, within the declared range.

Parameters:

name - base name of the variable; it must be unique and must not contain whitespace or a semicolon

minThetaDeg - smallest elevation, in degrees; must be from -90 to 90

maxThetaDeg - largest elevation, in degrees; must be from minThetaDeg to 90

minPhiDeg - start of the azimuth arc, in degrees

maxPhiDeg - end of the azimuth arc, in degrees

Returns:

true if the variable was added; false if the name is not valid, for example if it is already in use or contains whitespace or a semicolon

Throws:

com.opttek.optquest.COptQuestException - if a bound is NaN, if an elevation bound is outside [-90, 90], or if minThetaDeg is greater than maxThetaDeg

AddMixtureVariable

public boolean AddMixtureVariable(String name,
 String[] components,
 double[] lowerBounds,
 double[] upperBounds,
 double sumTo)
                           throws com.opttek.optquest.COptQuestException

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

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

Variable names: <name>@<component> for each component, in the order of components. The value of each name is the weight of that component.

With a negative lower bound, a weight can be below zero, down to that bound.

Supply both bound arrays or neither.

Parameters:

name - base name of the variable; it must be unique and must not contain whitespace or a semicolon

components - names of the components; each must be unique and must not contain whitespace, a semicolon, a comma or @

lowerBounds - lower bound of each component, or null for a lower bound of 0 on every component

upperBounds - upper bound of each component, or null for no upper bounds

sumTo - sum of the weights; must be greater than 0

Returns:

true if the variable was added; false if the name is not valid, for example if it is already in use or contains whitespace or a semicolon, or if only one of lowerBounds and upperBounds is null

Throws:

com.opttek.optquest.COptQuestException - if components is empty or holds a name that is not valid, if sumTo is not greater than 0, if a bound array does not have one entry for each component, if a lower bound is greater than its upper bound, or if no set of weights within the bounds sums to sumTo

AddLowRankMatrixVariable

public boolean AddLowRankMatrixVariable(String name,
 int rows,
 int cols,
 int rank,
 double min,
 double max)
                                 throws com.opttek.optquest.COptQuestException

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

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

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

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

Parameters:

name - base name of the variable; it must be unique and must not contain whitespace or a semicolon

rows - number of rows; must be at least 1

cols - number of columns; must be at least 1

rank - largest rank of the correction. A value greater than the number of rows or columns is reduced to it, and a value of 0 or less gives a constant matrix.

min - lower bound of every entry

max - upper bound of every entry

Returns:

true if the variable was added; false if the name is not valid, for example if it is already in use or contains whitespace or a semicolon

Throws:

com.opttek.optquest.COptQuestException - if min or max is NaN, or if min is greater than max

AddLowRankCorrectionMatrixVariable

public boolean AddLowRankCorrectionMatrixVariable(String name,
 double[][] initial,
 int rank,
 double min,
 double max)
                                           throws com.opttek.optquest.COptQuestException

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

In every solution that the engine generates, every entry is from min to max, and the matrix is initial plus a correction of rank at most rank. The engine first moves each entry of initial into [min, max].

The value of rank is the number of row patterns that the engine can combine in the correction. With rank 1, each row of the correction is one row pattern, multiplied by an amount that can differ from row to row. Each extra unit of rank adds one more row pattern. With rank 0, the value is initial with no correction.

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

Parameters:

name - base name of the variable; it must be unique and must not contain whitespace or a semicolon

initial - the baseline matrix; the variable has as many rows and columns as initial

rank - largest rank of the correction. A value greater than the number of rows or columns is reduced to it, and a value of 0 or less gives initial with no correction.

min - lower bound of every entry

max - upper bound of every entry

Returns:

true if the variable was added; false if the name is not valid, for example if it is already in use or contains whitespace or a semicolon

Throws:

com.opttek.optquest.COptQuestException - if min or max is NaN, or if min is greater than max

AddIncrementalLowRankCorrectionMatrixVariable

public boolean AddIncrementalLowRankCorrectionMatrixVariable(String name,
 double[][] initial,
 int rank,
 double min,
 double max)
                                                      throws com.opttek.optquest.COptQuestException

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

In every solution that the engine generates, every entry is from min to max, and the matrix is initial plus a correction of rank at most 1. The engine first moves each entry of initial into [min, max].

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

Parameters:

name - base name of the variable; it must be unique and must not contain whitespace or a semicolon

initial - the baseline matrix; the variable has as many rows and columns as initial

rank - the number of this variable in the sequence. Pass 1 for the first variable in the sequence, 2 for the next, and so on. The value must be at least 1. It does not change the values of this variable.

min - lower bound of every entry

max - upper bound of every entry

Returns:

true if the variable was added; false if the name is not valid, for example if it is already in use or contains whitespace or a semicolon

Throws:

com.opttek.optquest.COptQuestException - if min or max is NaN, if min is greater than max, or if rank is less than 1

AddTimeSeriesVectorVariable

public boolean AddTimeSeriesVectorVariable(String name,
 int longScale,
 int shortScale,
 int rank,
 double min,
 double max)
                                    throws com.opttek.optquest.COptQuestException

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

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

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

Variable names: <name>@1 to <name>@n, where n is longScale × shortScale. The names go row by row. With days as rows and hours as columns, the first shortScale names are the hours of day 1, the next shortScale names are the hours of day 2, and so on. Hour h of day d is <name>@k, where k is (d - 1) × shortScale + h, with d and h counted from 1.

Parameters:

name - base name of the variable; it must be unique and must not contain whitespace or a semicolon

longScale - number of rows of the matrix, for example the number of days; must be at least 1

shortScale - number of columns of the matrix, for example the number of hours in a day; must be at least 1

rank - largest rank of the correction. A value greater than the number of rows or columns is reduced to it, and a value of 0 or less gives a constant matrix.

min - lower bound of every element

max - upper bound of every element

Returns:

true if the variable was added; false if the name is not valid, for example if it is already in use or contains whitespace or a semicolon

Throws:

com.opttek.optquest.COptQuestException - if min or max is NaN, or if min is greater than max

AddTimeSeriesCorrectionVectorVariable

public boolean AddTimeSeriesCorrectionVectorVariable(String name,
 double[] initial,
 int longScale,
 int shortScale,
 int rank,
 double min,
 double max)
                                              throws com.opttek.optquest.COptQuestException

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

In every solution that the engine generates, every value is from min to max, and the matrix is initial plus a correction of rank at most rank. The engine first moves each entry of initial into [min, max].

The value of rank is the number of patterns that the engine can combine in the correction. With days as rows and hours as columns and rank 1, the correction to each day is one pattern over the hours, multiplied by an amount that can differ from day to day. Each extra unit of rank adds one more pattern. With rank 0, the value is initial with no correction.

Variable names: <name>@1 to <name>@n, where n is longScale × shortScale. The names go row by row. With days as rows and hours as columns, the first shortScale names are the hours of day 1, the next shortScale names are the hours of day 2, and so on. Hour h of day d is <name>@k, where k is (d - 1) × shortScale + h, with d and h counted from 1.

Parameters:

name - base name of the variable; it must be unique and must not contain whitespace or a semicolon

initial - the baseline vector; it must have longScale × shortScale values

longScale - number of rows of the matrix, for example the number of days; must be at least 1

shortScale - number of columns of the matrix, for example the number of hours in a day; must be at least 1

rank - largest rank of the correction. A value greater than the number of rows or columns is reduced to it, and a value of 0 or less gives initial with no correction.

min - lower bound of every element

max - upper bound of every element

Returns:

true if the variable was added; false if the name is not valid, for example if it is already in use or contains whitespace or a semicolon

Throws:

com.opttek.optquest.COptQuestException - if min or max is NaN, or if min is greater than max

AddIncrementalTimeSeriesCorrectionVectorVariable

public boolean AddIncrementalTimeSeriesCorrectionVectorVariable(String name,
 double[] initial,
 int longScale,
 int shortScale,
 int rank,
 double min,
 double max)
                                                         throws com.opttek.optquest.COptQuestException

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

In every solution that the engine generates, every value is from min to max, and the matrix is initial plus a correction of rank at most 1. The engine first moves each entry of initial into [min, max].

Variable names: <name>@1 to <name>@n, where n is longScale × shortScale. The names go row by row. With days as rows and hours as columns, the first shortScale names are the hours of day 1, the next shortScale names are the hours of day 2, and so on. Hour h of day d is <name>@k, where k is (d - 1) × shortScale + h, with d and h counted from 1.

Parameters:

name - base name of the variable; it must be unique and must not contain whitespace or a semicolon

initial - the baseline vector; it must have longScale × shortScale values

longScale - number of rows of the matrix, for example the number of days; must be at least 1

shortScale - number of columns of the matrix, for example the number of hours in a day; must be at least 1

rank - the number of this variable in the sequence. Pass 1 for the first variable in the sequence, 2 for the next, and so on. The value must be at least 1. It does not change the values of this variable.

min - lower bound of every element

max - upper bound of every element

Returns:

true if the variable was added; false if the name is not valid, for example if it is already in use or contains whitespace or a semicolon

Throws:

com.opttek.optquest.COptQuestException - if min or max is NaN, if min is greater than max, or if rank is less than 1

AddBSplineVectorVariable

public boolean AddBSplineVectorVariable(String name,
 int length,
 int numKnots,
 double min,
 double max)
                                 throws com.opttek.optquest.COptQuestException

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

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

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

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

Parameters:

name - base name of the variable; it must be unique and must not contain whitespace or a semicolon

length - number of elements; must be at least 1

numKnots - number of knots; fewer knots give a smoother curve. A value less than 2 is used as 2, and a value greater than the number of elements is used as that number.

min - lower bound of every element

max - upper bound of every element

Returns:

true if the variable was added; false if the name is not valid, for example if it is already in use or contains whitespace or a semicolon

Throws:

com.opttek.optquest.COptQuestException - if an error occurs while the variable is added

AddSplineVectorVariable

public boolean AddSplineVectorVariable(String name,
 int length,
 int numKnots,
 double min,
 double max)
                                throws com.opttek.optquest.COptQuestException

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

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

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

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

Parameters:

name - base name of the variable; it must be unique and must not contain whitespace or a semicolon

length - number of elements; must be at least 1

numKnots - number of knots; fewer knots give a smoother curve. A value less than 2 is used as 2, and a value greater than the number of elements is used as that number.

min - lower bound of every element

max - upper bound of every element

Returns:

true if the variable was added; false if the name is not valid, for example if it is already in use or contains whitespace or a semicolon

Throws:

com.opttek.optquest.COptQuestException - if an error occurs while the variable is added

AddBSplineCorrectionVectorVariable

public boolean AddBSplineCorrectionVectorVariable(String name,
 double[] initial,
 int numKnots,
 double min,
 double max)
                                           throws com.opttek.optquest.COptQuestException

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

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

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

Variable names: <name>@1 to <name>@length, one for each element. The number of elements is the length of initial.

Parameters:

name - base name of the variable; it must be unique and must not contain whitespace or a semicolon

initial - the baseline vector; the variable has as many elements as initial

numKnots - number of knots; fewer knots give a smoother curve. A value less than 2 is used as 2, and a value greater than the number of elements is used as that number.

min - lower bound of every element

max - upper bound of every element

Returns:

true if the variable was added; false if the name is not valid, for example if it is already in use or contains whitespace or a semicolon

Throws:

com.opttek.optquest.COptQuestException - if an error occurs while the variable is added

AddSplineCorrectionVectorVariable

public boolean AddSplineCorrectionVectorVariable(String name,
 double[] initial,
 int numKnots,
 double min,
 double max)
                                          throws com.opttek.optquest.COptQuestException

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

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

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

Variable names: <name>@1 to <name>@length, one for each element. The number of elements is the length of initial.

Parameters:

name - base name of the variable; it must be unique and must not contain whitespace or a semicolon

initial - the baseline vector; the variable has as many elements as initial

numKnots - number of knots; fewer knots give a smoother curve. A value less than 2 is used as 2, and a value greater than the number of elements is used as that number.

min - lower bound of every element

max - upper bound of every element

Returns:

true if the variable was added; false if the name is not valid, for example if it is already in use or contains whitespace or a semicolon

Throws:

com.opttek.optquest.COptQuestException - if an error occurs while the variable is added

AddBSplineMatrixVariable

public boolean AddBSplineMatrixVariable(String name,
 int rows,
 int cols,
 int knotRows,
 int knotCols,
 double min,
 double max)
                                 throws com.opttek.optquest.COptQuestException

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

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

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

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

Parameters:

name - base name of the variable; it must be unique and must not contain whitespace or a semicolon

rows - number of rows; must be at least 1

cols - number of columns; must be at least 1

knotRows - number of knot rows; fewer give a smoother surface down the columns. A value less than 2 is used as 2, and a value greater than the number of rows is used as that number.

knotCols - number of knot columns; fewer give a smoother surface along the rows. A value less than 2 is used as 2, and a value greater than the number of columns is used as that number.

min - lower bound of every entry

max - upper bound of every entry

Returns:

true if the variable was added; false if the name is not valid, for example if it is already in use or contains whitespace or a semicolon

Throws:

com.opttek.optquest.COptQuestException - if an error occurs while the variable is added

AddSplineMatrixVariable

public boolean AddSplineMatrixVariable(String name,
 int rows,
 int cols,
 int knotRows,
 int knotCols,
 double min,
 double max)
                                throws com.opttek.optquest.COptQuestException

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

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

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

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

Parameters:

name - base name of the variable; it must be unique and must not contain whitespace or a semicolon

rows - number of rows; must be at least 1

cols - number of columns; must be at least 1

knotRows - number of knot rows; fewer give a smoother surface down the columns. A value less than 2 is used as 2, and a value greater than the number of rows is used as that number.

knotCols - number of knot columns; fewer give a smoother surface along the rows. A value less than 2 is used as 2, and a value greater than the number of columns is used as that number.

min - lower bound of every entry

max - upper bound of every entry

Returns:

true if the variable was added; false if the name is not valid, for example if it is already in use or contains whitespace or a semicolon

Throws:

com.opttek.optquest.COptQuestException - if an error occurs while the variable is added

AddBSplineCorrectionMatrixVariable

public boolean AddBSplineCorrectionMatrixVariable(String name,
 double[][] initial,
 int knotRows,
 int knotCols,
 double min,
 double max)
                                           throws com.opttek.optquest.COptQuestException

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

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

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

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

Parameters:

name - base name of the variable; it must be unique and must not contain whitespace or a semicolon

initial - the baseline matrix; the variable has as many rows and columns as initial

knotRows - number of knot rows; fewer give a smoother surface down the columns. A value less than 2 is used as 2, and a value greater than the number of rows is used as that number.

knotCols - number of knot columns; fewer give a smoother surface along the rows. A value less than 2 is used as 2, and a value greater than the number of columns is used as that number.

min - lower bound of every entry

max - upper bound of every entry

Returns:

true if the variable was added; false if the name is not valid, for example if it is already in use or contains whitespace or a semicolon

Throws:

com.opttek.optquest.COptQuestException - if an error occurs while the variable is added

AddSplineCorrectionMatrixVariable

public boolean AddSplineCorrectionMatrixVariable(String name,
 double[][] initial,
 int knotRows,
 int knotCols,
 double min,
 double max)
                                          throws com.opttek.optquest.COptQuestException

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

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

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

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

Parameters:

name - base name of the variable; it must be unique and must not contain whitespace or a semicolon

initial - the baseline matrix; the variable has as many rows and columns as initial

knotRows - number of knot rows; fewer give a smoother surface down the columns. A value less than 2 is used as 2, and a value greater than the number of rows is used as that number.

knotCols - number of knot columns; fewer give a smoother surface along the rows. A value less than 2 is used as 2, and a value greater than the number of columns is used as that number.

min - lower bound of every entry

max - upper bound of every entry

Returns:

true if the variable was added; false if the name is not valid, for example if it is already in use or contains whitespace or a semicolon

Throws:

com.opttek.optquest.COptQuestException - if an error occurs while the variable is added

AddFourierVectorVariable

public boolean AddFourierVectorVariable(String name,
 int length,
 int numFreq,
 double min,
 double max)
                                 throws com.opttek.optquest.COptQuestException

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

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

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

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

Parameters:

name - base name of the variable; it must be unique and must not contain whitespace or a semicolon

length - number of elements; must be at least 1

numFreq - number of cosine terms, including the constant term; fewer give a smoother vector. A value less than 1 is used as 1, and a value greater than the number of elements is used as that number.

min - lower bound of every element

max - upper bound of every element

Returns:

true if the variable was added; false if the name is not valid, for example if it is already in use or contains whitespace or a semicolon

Throws:

com.opttek.optquest.COptQuestException - if an error occurs while the variable is added

AddFourierMatrixVariable

public boolean AddFourierMatrixVariable(String name,
 int rows,
 int cols,
 int freqRows,
 int freqCols,
 double min,
 double max)
                                 throws com.opttek.optquest.COptQuestException

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

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

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

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

Parameters:

name - base name of the variable; it must be unique and must not contain whitespace or a semicolon

rows - number of rows; must be at least 1

cols - number of columns; must be at least 1

freqRows - number of cosine terms down each column; fewer make the rows more alike. A value less than 1 is used as 1, and a value greater than the number of rows is used as that number.

freqCols - number of cosine terms along each row; fewer make the columns more alike. A value less than 1 is used as 1, and a value greater than the number of columns is used as that number.

min - lower bound of every entry

max - upper bound of every entry

Returns:

true if the variable was added; false if the name is not valid, for example if it is already in use or contains whitespace or a semicolon

Throws:

com.opttek.optquest.COptQuestException - if an error occurs while the variable is added

AddFourierCorrectionVectorVariable

public boolean AddFourierCorrectionVectorVariable(String name,
 double[] initial,
 int numFreq,
 double min,
 double max)
                                           throws com.opttek.optquest.COptQuestException

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

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

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

Variable names: <name>@1 to <name>@length, one for each element. The number of elements is the length of initial.

Parameters:

name - base name of the variable; it must be unique and must not contain whitespace or a semicolon

initial - the baseline vector; the variable has as many elements as initial

numFreq - number of cosine terms, including the constant term; fewer give a smoother vector. A value less than 1 is used as 1, and a value greater than the number of elements is used as that number.

min - lower bound of every element

max - upper bound of every element

Returns:

true if the variable was added; false if the name is not valid, for example if it is already in use or contains whitespace or a semicolon

Throws:

com.opttek.optquest.COptQuestException - if an error occurs while the variable is added

AddFourierCorrectionMatrixVariable

public boolean AddFourierCorrectionMatrixVariable(String name,
 double[][] initial,
 int freqRows,
 int freqCols,
 double min,
 double max)
                                           throws com.opttek.optquest.COptQuestException

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

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

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

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

Parameters:

name - base name of the variable; it must be unique and must not contain whitespace or a semicolon

initial - the baseline matrix; the variable has as many rows and columns as initial

freqRows - number of cosine terms down each column; fewer make the rows more alike. A value less than 1 is used as 1, and a value greater than the number of rows is used as that number.

freqCols - number of cosine terms along each row; fewer make the columns more alike. A value less than 1 is used as 1, and a value greater than the number of columns is used as that number.

min - lower bound of every entry

max - upper bound of every entry

Returns:

true if the variable was added; false if the name is not valid, for example if it is already in use or contains whitespace or a semicolon

Throws:

com.opttek.optquest.COptQuestException - if an error occurs while the variable is added

AddRegionVariable

public boolean AddRegionVariable(String name,
 double[][] polygon)
                          throws com.opttek.optquest.COptQuestException

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

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

Variable names: <name>@x and <name>@y, the coordinates of the point, in the units of the polygon.

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

Parameters:

name - base name of the variable; it must be unique and must not contain whitespace or a semicolon

polygon - the vertices, one row {x, y} for each vertex; there must be at least three

Returns:

true if the variable was added; false if the name is not valid, for example if it is already in use or contains whitespace or a semicolon

Throws:

com.opttek.optquest.COptQuestException - if polygon is null, has fewer than three vertices or has a vertex with fewer than two coordinates, or if the polygon has no area

AddSphericalRegionVariable

public boolean AddSphericalRegionVariable(String name,
 double[][] polygon)
                                   throws com.opttek.optquest.COptQuestException

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

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

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

Variable names:

• <name>@theta: the latitude of the point, in degrees.
• <name>@phi: the longitude of the point, in degrees, from -180 to 180.

Parameters:

name - base name of the variable; it must be unique and must not contain whitespace or a semicolon

polygon - the vertices, one row {latitude, longitude} in degrees for each vertex, with the latitude first; there must be at least three

Returns:

true if the variable was added; false if the name is not valid, for example if it is already in use or contains whitespace or a semicolon

Throws:

com.opttek.optquest.COptQuestException - if polygon is null or has a vertex with fewer than two coordinates, a coordinate that is not finite or a latitude outside [-90, 90]; if it has fewer than three different vertices or two consecutive antipodal vertices; or if the boundary doubles back on itself or encloses no area

AddSequenceVariable

public boolean AddSequenceVariable(String name,
 String[] components,
 Integer topK)
                            throws com.opttek.optquest.COptQuestException

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

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

Variable names: <name>@<component> for each component, in the order of components. The value of each name is the integer rank of that component.

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

Parameters:

name - base name of the variable; it must be unique and must not contain whitespace or a semicolon

components - names of the components; each must be unique and must not contain whitespace, a semicolon, a comma or @

topK - null for a full ranking, or the number of components to rank. A value of n or more gives a full ranking, and a value less than 1 is used as 1. With topK = 1, the most important component gets rank 1, and every other component gets rank 2.

Returns:

true if the variable was added; false if the name is not valid, for example if it is already in use or contains whitespace or a semicolon

Throws:

com.opttek.optquest.COptQuestException - if components is empty or holds a name that is not valid

AddMultiStageSequenceVariable

public boolean AddMultiStageSequenceVariable(String name,
 String[][] stageGroups)
                                      throws com.opttek.optquest.COptQuestException

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

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

Variable names: <name>@<component> for every component, stage by stage, in the order of stageGroups. The value of each name is the integer rank of that component within its stage.

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

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

Parameters:

name - base name of the variable; it must be unique and must not contain whitespace or a semicolon

stageGroups - one array of component names for each stage. Each stage must have at least one component. Each name must be unique across all stages and must not contain whitespace, a semicolon, a comma or @.

Returns:

true if the variable was added; false if the name is not valid, for example if it is already in use or contains whitespace or a semicolon

Throws:

com.opttek.optquest.COptQuestException - if stageGroups is empty, if a stage is empty, or if a component name is not valid or appears more than once

AddPolicySequenceVariable

public boolean AddPolicySequenceVariable(String name,
 double[][] featureMatrix,
 String[] itemNames,
 String[] featureNames)
                                  throws com.opttek.optquest.COptQuestException

Adds a policy sequence variable. Its value is a priority score for each item of a set, and one weight for each feature of the items. The score of an item is a weighted sum of its features, and the engine chooses the weights. Use a policy sequence variable when a good order depends on a few item attributes, and the weights themselves are a useful result, for example dispatch order by urgency and setup family.

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

Variable names:

• <name>@<itemName> for each item, an input: the priority score of that item.
• <name>@<featureName> for each feature, an output: the coefficient of that feature, which is the change in score for one unit of the feature. Multiply each raw feature value of an item by its coefficient and add the products to score a new item. That sum can differ from the reported score by a constant that is the same for every item, so it gives the same order.
• <name>@<featureName>@contribution for each feature, an output: the signed share of that feature in the rule, in [-1, 1]. The absolute values of all the contributions sum to 1.
• <name>@<featureName>@confidence for each feature, an output: a confidence in [0, 1] for the weight of that feature. A feature whose values are all equal gets 0.
• <name>@<itemName>@confidence for each item, an output: a confidence in [0, 1] that the item is in the right place relative to its neighbors in the order. With one item, the value is 1.

The engine computes every value of a policy sequence variable. The item scores are inputs. The coefficients, the contributions and the confidences are outputs. Your evaluator can read these outputs, and must not write them. Item names and feature names share one set of names, so every item name and feature name must be different from all the others.

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

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

Parameters:

name - base name of the variable; it must be unique and must not contain whitespace or a semicolon

featureMatrix - feature values, one row for each item and one column for each feature

itemNames - names of the items, one for each row of featureMatrix

featureNames - names of the features, one for each column of featureMatrix

Returns:

true if the variable was added; false if the name is not valid, for example if it is already in use or contains whitespace or a semicolon

Throws:

com.opttek.optquest.COptQuestException - if featureMatrix is empty, if the number of item names is not the number of rows, if the number of feature names is not the number of columns, or if an item name or feature name is not valid or is used more than once

AddChoiceVariable

public boolean AddChoiceVariable(String name,
 int k)
                          throws com.opttek.optquest.COptQuestException

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

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

Variable names: <name>@choice, the 1-based index of the selected option, a whole number from 1 to k.

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

Parameters:

name - base name of the variable; it must be unique and must not contain whitespace or a semicolon

k - number of options; must be at least 1

Returns:

true if the variable was added; false if the name is not valid, for example if it is already in use or contains whitespace or a semicolon

Throws:

com.opttek.optquest.COptQuestException - if k is less than 1

AddMultiChoiceVariable

public boolean AddMultiChoiceVariable(String name,
 String[] choices,
 int minSelect,
 int maxSelect)
                               throws com.opttek.optquest.COptQuestException

Adds a multi-choice variable. Its value is a subset of the choices that has from minSelect to maxSelect members. Use a multi-choice variable when the decision is an unordered selection of several items, such as which sensors to turn on or which assets to include.

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

Variable names: <name>@<choice> for each choice, in the order of choices. The value of each name is 1 if the choice is selected and 0 if it is not.

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

Parameters:

name - base name of the variable; it must be unique and must not contain whitespace or a semicolon

choices - names of the choices; each must be unique and must not contain whitespace, a semicolon, a comma or @

minSelect - smallest number of selected choices; must be at least 0

maxSelect - largest number of selected choices; must be at least minSelect and at most the number of choices

Returns:

true if the variable was added; false if the name is not valid, for example if it is already in use or contains whitespace or a semicolon

Throws:

com.opttek.optquest.COptQuestException - if choices is empty or holds a name that is not valid, or if minSelect and maxSelect are not valid

AddDAGVariable

public boolean AddDAGVariable(String name,
 String[] nodeNames)
                       throws com.opttek.optquest.COptQuestException

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

In every solution that the engine generates, the edges form no cycle. Any DAG over the nodes can occur, including the graph with no edges.

Variable names: <name>@<nodeFrom>,<nodeTo> for every ordered pair of nodes, including a node paired with itself: the full n by n adjacency matrix, row by row in the order of nodeNames. The value of each name is 1 if the edge from nodeFrom to nodeTo is present and 0 if it is not. The diagonal is always 0. Each name contains a comma, so write it in brackets in an expression: [<name>@A,B].

In a suggested solution, a value greater than 0.5 is an edge. The engine keeps a suggested DAG as it is. If the suggested edges form a cycle, the engine removes edges until no cycle remains.

Parameters:

name - base name of the variable; it must be unique and must not contain whitespace or a semicolon

nodeNames - names of the nodes; there must be at least one, and each must be unique and must not contain whitespace, a semicolon, a comma or @

Returns:

true if the variable was added; false if the name is not valid, for example if it is already in use or contains whitespace or a semicolon

Throws:

com.opttek.optquest.COptQuestException - if nodeNames is empty or holds a name that is not valid

AddDAGVariable

public boolean AddDAGVariable(String name,
 String[] nodeNames,
 String startNode,
 String endNode,
 boolean connected,
 Map<String,List<String>> predecessors)
                       throws com.opttek.optquest.COptQuestException

Adds a DAG variable with an optional start node, an optional end node, the connected option and optional precedences. Its value is a directed acyclic graph (DAG) over the given nodes: a set of directed edges with no cycle.

In every solution that the engine generates, the edges form no cycle, and:

• the start node, when given, has no incoming edge;
• the end node, when given, has no outgoing edge;
• with connected, every node can be reached from the start node when there is one, and every node can reach the end node when there is one;
• no directed path runs from a node to one of its predecessors.

The variable names and the rules for a suggested solution are the same as for AddDAGVariable(String, String[]). In a suggested solution, the engine also removes edges that break the start node, the end node or a precedence, and with connected it adds edges until the graph is connected.

Parameters:

name - base name of the variable; it must be unique and must not contain whitespace or a semicolon

nodeNames - names of the nodes; there must be at least one, and each must be unique and must not contain whitespace, a semicolon, a comma or @

startNode - the node with no incoming edge, or null or empty

endNode - the node with no outgoing edge, or null or empty

connected - true to connect every node to the start node and the end node; it needs a start node, an end node or both

predecessors - map from a node to the nodes that must come before it, or null. Names that are not nodes are ignored.

Returns:

true if the variable was added; false if the name is not valid, for example if it is already in use or contains whitespace or a semicolon

Throws:

com.opttek.optquest.COptQuestException - if nodeNames is empty or holds a name that is not valid, if the start or end node is not one of the nodes, if the start node and the end node are the same node, if connected is true with no start node and no end node, if the start node has a predecessor, if the end node is a predecessor, if a node lists itself as a predecessor, or if the precedences form a cycle

AddTreeVariable

public boolean AddTreeVariable(String name,
 String[] nodeNames)
                        throws com.opttek.optquest.COptQuestException

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

In every solution that the engine generates, the edges form a spanning tree. The tree has exactly n - 1 edges and no cycle. Any node can be the root.

Variable names: <name>@<nodeFrom>,<nodeTo> for every ordered pair of nodes, including a node paired with itself: the full n by n adjacency matrix, row by row in the order of nodeNames. The value of each name is 1 if the edge from nodeFrom to nodeTo is present and 0 if it is not. The diagonal is always 0. Each name contains a comma, so write it in brackets in an expression: [<name>@A,B].

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

Parameters:

name - base name of the variable; it must be unique and must not contain whitespace or a semicolon

nodeNames - names of the nodes; there must be at least one, and each must be unique and must not contain whitespace, a semicolon, a comma or @

Returns:

true if the variable was added; false if the name is not valid, for example if it is already in use or contains whitespace or a semicolon

Throws:

com.opttek.optquest.COptQuestException - if nodeNames is empty or holds a name that is not valid

AddTreeVariable

public boolean AddTreeVariable(String name,
 String[] nodeNames,
 String rootNode,
 Map<String,List<String>> predecessors)
                        throws com.opttek.optquest.COptQuestException

Adds a tree variable with an optional fixed root and optional precedences. Its value is a directed spanning tree over the given nodes: one node is the root, every other node has exactly one incoming edge, and every node can be reached from the root.

In every solution that the engine generates, the edges form a spanning tree with exactly n - 1 edges and no cycle. When rootNode is given, it is the root of every tree. Otherwise any node can be the root. A node never comes above one of its predecessors: no path from the root to a predecessor passes through the node.

The variable names and the rules for a suggested solution are the same as for AddTreeVariable(String, String[]). In a suggested solution, the engine also changes a tree whose root is not rootNode or that puts a node above one of its predecessors.

Parameters:

name - base name of the variable; it must be unique and must not contain whitespace or a semicolon

nodeNames - names of the nodes; there must be at least one, and each must be unique and must not contain whitespace, a semicolon, a comma or @

rootNode - the root of every tree, or null or empty to let any node be the root

predecessors - map from a node to the nodes that must come before it, or null. Names that are not nodes are ignored.

Returns:

true if the variable was added; false if the name is not valid, for example if it is already in use or contains whitespace or a semicolon

Throws:

com.opttek.optquest.COptQuestException - if nodeNames is empty or holds a name that is not valid, if rootNode is not one of the nodes, if the root node has a predecessor, if a node lists itself as a predecessor, or if the precedences form a cycle

AddTopologicalSequenceVariable

public boolean AddTopologicalSequenceVariable(String name,
 String[] tasks,
 Map<String,List<String>> predecessors)
                                       throws com.opttek.optquest.COptQuestException

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

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

Variable names: <name>@<task> for each task, in the order of tasks. The value of each name is the integer rank of that task in the order, where 1 is first and n is last. The ranks are a permutation of 1 to n.

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

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

Parameters:

name - base name of the variable; it must be unique and must not contain whitespace or a semicolon

tasks - names of the tasks; there must be at least one, and each must be unique and must not contain whitespace, a semicolon, a comma or @

predecessors - for each task that has predecessors, the tasks that must come before it; null for no precedences

Returns:

true if the variable was added; false if the name is not valid, for example if it is already in use or contains whitespace or a semicolon

Throws:

com.opttek.optquest.COptQuestException - if tasks is empty or holds a name that is not valid, if a task lists itself as a predecessor, or if the precedences form a cycle

AddPathVariable

public boolean AddPathVariable(String name,
 String[] nodeNames,
 String startNode,
 String endNode,
 String[] requiredNodes)
                        throws com.opttek.optquest.COptQuestException

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

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

Variable names: <name>@<node> for each node, in the order of nodeNames. The value of each name is the 1-based position of that node on the path, or 0 if the node is not on the path.

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

Parameters:

name - base name of the variable; it must be unique and must not contain whitespace or a semicolon

nodeNames - names of the candidate nodes; there must be at least two, and each must be unique and must not contain whitespace, a semicolon, a comma or @

startNode - the node at position 1, or null for any start node

endNode - the node at the last position, or null for any end node

requiredNodes - nodes that must be on the path, or null for none

Returns:

true if the variable was added; false if the name is not valid, for example if it is already in use or contains whitespace or a semicolon

Throws:

com.opttek.optquest.COptQuestException - if nodeNames has fewer than two nodes or holds a name that is not valid, or if startNode, endNode or a required node is not in nodeNames

AddAssignmentVariable

public boolean AddAssignmentVariable(String name,
 int m,
 int n)
                              throws com.opttek.optquest.COptQuestException

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

The engine adds the assignment rules to the model as constraints, so a solution that breaks a rule is infeasible. With this method, every item is in exactly one bin, and a bin can hold any number of items.

Variable names: <name>@1 to <name>@m, one for each item. The value of each name is the number of the bin that the item is in, counted from 1.

In a suggested solution, the engine rounds each value to the nearest bin index. The engine can then change the assignment so that it meets the rules.

Parameters:

name - base name of the variable; it must be unique and must not contain whitespace or a semicolon

m - number of items; must be at least 1

n - number of bins; must be at least 1

Returns:

true if the variable was added; false if the name is not valid, for example if it is already in use or contains whitespace or a semicolon

Throws:

com.opttek.optquest.COptQuestException - if m or n is less than 1

AddAssignmentVariable

public boolean AddAssignmentVariable(String name,
 int m,
 int n,
 boolean mustAssign,
 int binCapacityMin,
 int binCapacityMax)
                              throws com.opttek.optquest.COptQuestException

Adds an assignment variable with the same rules for every item and every bin. Its value is an assignment of each of m items to one of n bins. Use an assignment variable when the decision is an assignment of items to bins, such as jobs to machines or tasks to workers.

The engine adds the assignment rules to the model as constraints, so a solution that breaks a rule is infeasible. When mustAssign is true, every item is in exactly one bin. When it is false, every item is in at most one bin. Every bin holds from binCapacityMin to binCapacityMax items.

Variable names: <name>@1 to <name>@m, one for each item. The value of each name is the number of the bin that the item is in, counted from 1, or 0 when the item is in no bin.

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

Parameters:

name - base name of the variable; it must be unique and must not contain whitespace or a semicolon

m - number of items; must be at least 1

n - number of bins; must be at least 1

mustAssign - true if every item must be in a bin, false if an item can be in no bin

binCapacityMin - smallest number of items in each bin

binCapacityMax - largest number of items in each bin

Returns:

true if the variable was added; false if the name is not valid, for example if it is already in use or contains whitespace or a semicolon

Throws:

com.opttek.optquest.COptQuestException - if m or n is less than 1, if binCapacityMax is negative or less than binCapacityMin, if the bin minimums add up to more than m items, or if mustAssign is true and the bins cannot hold every item

AddAssignmentVariable

public boolean AddAssignmentVariable(String name,
 int m,
 int n,
 boolean[] mustAssign,
 int[] binCapacitiesMin,
 int[] binCapacitiesMax)
                              throws com.opttek.optquest.COptQuestException

Adds an assignment variable with separate rules for each item and each bin. Its value is an assignment of each of m items to one of n bins. Use an assignment variable when the decision is an assignment of items to bins, such as jobs to machines or tasks to workers.

The engine adds the assignment rules to the model as constraints, so a solution that breaks a rule is infeasible. Item i is in exactly one bin when mustAssign[i] is true, and in at most one bin when it is false. Bin j holds from binCapacitiesMin[j] to binCapacitiesMax[j] items.

Variable names: <name>@1 to <name>@m, one for each item. The value of each name is the number of the bin that the item is in, counted from 1, or 0 when the item is in no bin.

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

Parameters:

name - base name of the variable; it must be unique and must not contain whitespace or a semicolon

m - number of items; must be at least 1

n - number of bins; must be at least 1

mustAssign - one entry for each item: true if the item must be in a bin, false if it can be in no bin

binCapacitiesMin - one entry for each bin: the smallest number of items in the bin

binCapacitiesMax - one entry for each bin: the largest number of items in the bin

Returns:

true if the variable was added; false if the name is not valid, for example if it is already in use or contains whitespace or a semicolon

Throws:

com.opttek.optquest.COptQuestException - if m or n is less than 1, if an array is null or does not have one entry for each item or bin, if a bin maximum is negative or less than its minimum, if the bin minimums add up to more than m items, or if the bins cannot hold every item that must be assigned

AddItemSelectionVariable

public boolean AddItemSelectionVariable(String name,
 int n,
 int k)
                                 throws com.opttek.optquest.COptQuestException

Adds an item selection variable that selects exactly k of n candidates. Use an item selection variable when the decision is which candidates to include, such as which sites to open. This variable is not the same as AddSelectionVariable(String, String[]), which turns a group of variables on or off.

The engine adds the selection rule to the model as a constraint, so a solution that selects a different number of candidates is infeasible.

Variable names: <name>@1 to <name>@n, one for each candidate. These are ordinary binary inputs. The value of each name is 1 if the candidate is selected and 0 if it is not.

Parameters:

name - base name of the variable; it must be unique and must not contain whitespace or a semicolon

n - number of candidates; must be at least 1

k - number of candidates to select; must be from 0 to n

Returns:

true if the variable was added; false if the name is not valid, for example if it is already in use or contains whitespace or a semicolon

Throws:

com.opttek.optquest.COptQuestException - if n is less than 1, or if k is less than 0 or greater than n

AddItemSelectionVariable

public boolean AddItemSelectionVariable(String name,
 int n,
 int kMin,
 int kMax)
                                 throws com.opttek.optquest.COptQuestException

Adds an item selection variable that selects from kMin to kMax of n candidates. Use an item selection variable when the decision is which candidates to include, such as which sites to open. This variable is not the same as AddSelectionVariable(String, String[]), which turns a group of variables on or off.

The engine adds the selection rule to the model as a constraint, so a solution that selects fewer than kMin or more than kMax candidates is infeasible.

Variable names: <name>@1 to <name>@n, one for each candidate. These are ordinary binary inputs. The value of each name is 1 if the candidate is selected and 0 if it is not.

Parameters:

name - base name of the variable; it must be unique and must not contain whitespace or a semicolon

n - number of candidates; must be at least 1

kMin - smallest number of candidates to select; must be at least 0

kMax - largest number of candidates to select; must be from kMin to n

Returns:

true if the variable was added; false if the name is not valid, for example if it is already in use or contains whitespace or a semicolon

Throws:

com.opttek.optquest.COptQuestException - if n is less than 1, or if no selection has from kMin to kMax candidates

AddBudgetedSelectionVariable

public boolean AddBudgetedSelectionVariable(String name,
 int n,
 double[] costs,
 double budgetMax)
                                     throws com.opttek.optquest.COptQuestException

Adds a budgeted selection variable that selects candidates whose total cost is at most budgetMax. Use a budgeted selection variable when the decision is which candidates to include within a budget, such as which projects to fund.

The engine adds the budget rule to the model as a constraint, so a solution whose selected candidates cost more than budgetMax is infeasible.

Variable names: <name>@1 to <name>@n, one for each candidate. These are ordinary binary inputs. The value of each name is 1 if the candidate is selected and 0 if it is not.

Parameters:

name - base name of the variable; it must be unique and must not contain whitespace or a semicolon

n - number of candidates; must be at least 1

costs - cost of each candidate, one entry for each candidate

budgetMax - largest total cost of the selected candidates

Returns:

true if the variable was added; false if the name is not valid, for example if it is already in use or contains whitespace or a semicolon

Throws:

com.opttek.optquest.COptQuestException - if n is less than 1, if costs is null or does not have n entries, or if budgetMax is less than the lowest possible total cost

AddBudgetedSelectionVariable

public boolean AddBudgetedSelectionVariable(String name,
 int n,
 double[] costs,
 double budgetMin,
 double budgetMax,
 int kMin,
 int kMax)
                                     throws com.opttek.optquest.COptQuestException

Adds a budgeted selection variable with a budget range and a range for the number of selected candidates. Use a budgeted selection variable when the decision is which candidates to include within a budget, such as which projects to fund.

The engine adds the budget and count rules to the model as constraints, so a solution that breaks a rule is infeasible. The total cost of the selected candidates is from budgetMin to budgetMax, and the number of selected candidates is from kMin to kMax.

Variable names: <name>@1 to <name>@n, one for each candidate. These are ordinary binary inputs. The value of each name is 1 if the candidate is selected and 0 if it is not.

Parameters:

name - base name of the variable; it must be unique and must not contain whitespace or a semicolon

n - number of candidates; must be at least 1

costs - cost of each candidate, one entry for each candidate

budgetMin - smallest total cost of the selected candidates; 0 or less for no smallest total

budgetMax - largest total cost of the selected candidates

kMin - smallest number of candidates to select; 0 for no smallest number

kMax - largest number of candidates to select; n for no largest number

Returns:

true if the variable was added; false if the name is not valid, for example if it is already in use or contains whitespace or a semicolon

Throws:

com.opttek.optquest.COptQuestException - if n is less than 1, if costs is null or does not have n entries, if no selection has from kMin to kMax candidates, if budgetMax is less than the lowest possible total cost, or if budgetMin is positive and greater than budgetMax or than the highest possible total cost

AddPartitionVariable

public boolean AddPartitionVariable(String name,
 int m,
 int k)
                             throws com.opttek.optquest.COptQuestException

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

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

Variable names: <name>@1 to <name>@m, one for each item. The value of each name is the number of the group that the item is in, counted from 1. Item 1 is always in group 1. For each later item, the group number is at most one more than the largest group number among the items before it.

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

Parameters:

name - base name of the variable; it must be unique and must not contain whitespace or a semicolon

m - number of items; must be at least k

k - number of groups; must be at least 1

Returns:

true if the variable was added; false if the name is not valid, for example if it is already in use or contains whitespace or a semicolon

Throws:

com.opttek.optquest.COptQuestException - if k is less than 1 or m is less than k

AddBetaRandomVariable

public boolean AddBetaRandomVariable(String name,
 double alpha,
 double beta)
                              throws com.opttek.optquest.COptQuestException

Adds a Beta-distributed random variable (used as a random input drawn each replication).

The engine draws a new value at the start of every replication. Without SetReplications(int), each trial solution has one replication, so it gets one draw, and its result depends on that one draw. To compare trial solutions by the combined result of several draws, call SetReplications with more than one replication.

Parameters:

name - name of the variable (must be unique, no whitespace or ;)

alpha - shape parameter

beta - shape parameter

Returns:

true if the variable was added; false if the name is not valid, for example if it is already in use or contains whitespace or a semicolon

Throws:

com.opttek.optquest.COptQuestException - if an error occurred adding the variable

AddCauchyRandomVariable

public boolean AddCauchyRandomVariable(String name,
 double location,
 double scale)
                                throws com.opttek.optquest.COptQuestException

Adds a Cauchy-distributed random variable.

The engine draws a new value at the start of every replication. Without SetReplications(int), each trial solution has one replication, so it gets one draw, and its result depends on that one draw. To compare trial solutions by the combined result of several draws, call SetReplications with more than one replication.

Parameters:

name - name of the variable (must be unique, no whitespace or ;)

location - location parameter

scale - scale parameter

Returns:

true if the variable was added; false if the name is not valid, for example if it is already in use or contains whitespace or a semicolon

Throws:

com.opttek.optquest.COptQuestException - if an error occurred adding the variable

AddChiSquareRandomVariable

public boolean AddChiSquareRandomVariable(String name,
 int df)
                                   throws com.opttek.optquest.COptQuestException

Adds a Chi-square-distributed random variable.

The engine draws a new value at the start of every replication. Without SetReplications(int), each trial solution has one replication, so it gets one draw, and its result depends on that one draw. To compare trial solutions by the combined result of several draws, call SetReplications with more than one replication.

Parameters:

name - name of the variable (must be unique, no whitespace or ;)

df - degrees of freedom

Returns:

true if the variable was added; false if the name is not valid, for example if it is already in use or contains whitespace or a semicolon

Throws:

com.opttek.optquest.COptQuestException - if an error occurred adding the variable

AddExponentialRandomVariable

public boolean AddExponentialRandomVariable(String name,
 double scale)
                                     throws com.opttek.optquest.COptQuestException

Adds an exponentially distributed random variable.

The engine draws a new value at the start of every replication. Without SetReplications(int), each trial solution has one replication, so it gets one draw, and its result depends on that one draw. To compare trial solutions by the combined result of several draws, call SetReplications with more than one replication.

Parameters:

name - name of the variable (must be unique, no whitespace or ;)

scale - scale parameter

Returns:

true if the variable was added; false if the name is not valid, for example if it is already in use or contains whitespace or a semicolon

Throws:

com.opttek.optquest.COptQuestException - if an error occurred adding the variable

AddGammaRandomVariable

public boolean AddGammaRandomVariable(String name,
 double shape,
 double scale)
                               throws com.opttek.optquest.COptQuestException

Adds a Gamma-distributed random variable.

The engine draws a new value at the start of every replication. Without SetReplications(int), each trial solution has one replication, so it gets one draw, and its result depends on that one draw. To compare trial solutions by the combined result of several draws, call SetReplications with more than one replication.

Parameters:

name - name of the variable (must be unique, no whitespace or ;)

shape - shape parameter

scale - scale parameter

Returns:

true if the variable was added; false if the name is not valid, for example if it is already in use or contains whitespace or a semicolon

Throws:

com.opttek.optquest.COptQuestException - if an error occurred adding the variable

AddLogNormalRandomVariable

public boolean AddLogNormalRandomVariable(String name,
 double shape,
 double scale)
                                   throws com.opttek.optquest.COptQuestException

Adds a log-normal distributed random variable.

The engine draws a new value at the start of every replication. Without SetReplications(int), each trial solution has one replication, so it gets one draw, and its result depends on that one draw. To compare trial solutions by the combined result of several draws, call SetReplications with more than one replication.

Parameters:

name - name of the variable (must be unique, no whitespace or ;)

shape - shape parameter

scale - scale parameter

Returns:

true if the variable was added; false if the name is not valid, for example if it is already in use or contains whitespace or a semicolon

Throws:

com.opttek.optquest.COptQuestException - if an error occurred adding the variable

AddNormalRandomVariable

public boolean AddNormalRandomVariable(String name,
 double mean,
 double sigma)
                                throws com.opttek.optquest.COptQuestException

Adds a normally distributed random variable.

The engine draws a new value at the start of every replication. Without SetReplications(int), each trial solution has one replication, so it gets one draw, and its result depends on that one draw. To compare trial solutions by the combined result of several draws, call SetReplications with more than one replication.

Parameters:

name - name of the variable (must be unique, no whitespace or ;)

mean - mean

sigma - standard deviation

Returns:

true if the variable was added; false if the name is not valid, for example if it is already in use or contains whitespace or a semicolon

Throws:

com.opttek.optquest.COptQuestException - if an error occurred adding the variable

AddParetoRandomVariable

public boolean AddParetoRandomVariable(String name,
 double gamma,
 double loc,
 double scale)
                                throws com.opttek.optquest.COptQuestException

Adds a Pareto-distributed random variable.

The engine draws a new value at the start of every replication. Without SetReplications(int), each trial solution has one replication, so it gets one draw, and its result depends on that one draw. To compare trial solutions by the combined result of several draws, call SetReplications with more than one replication.

Parameters:

name - name of the variable (must be unique, no whitespace or ;)

gamma - shape parameter

loc - location parameter

scale - scale parameter

Returns:

true if the variable was added; false if the name is not valid, for example if it is already in use or contains whitespace or a semicolon

Throws:

com.opttek.optquest.COptQuestException - if an error occurred adding the variable

AddPoissonRandomVariable

public boolean AddPoissonRandomVariable(String name,
 double lambda)
                                 throws com.opttek.optquest.COptQuestException

Adds a Poisson-distributed random variable.

The engine draws a new value at the start of every replication. Without SetReplications(int), each trial solution has one replication, so it gets one draw, and its result depends on that one draw. To compare trial solutions by the combined result of several draws, call SetReplications with more than one replication.

Parameters:

name - name of the variable (must be unique, no whitespace or ;)

lambda - rate parameter

Returns:

true if the variable was added; false if the name is not valid, for example if it is already in use or contains whitespace or a semicolon

Throws:

com.opttek.optquest.COptQuestException - if an error occurred adding the variable

AddPowerRandomVariable

public boolean AddPowerRandomVariable(String name,
 double rmin,
 double rmax,
 double power)
                               throws com.opttek.optquest.COptQuestException

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

The probability density is proportional to x^(power - 1): pdf(x) = power * x^(power - 1) / (rmax^power - rmin^power) for rmin <= x <= rmax. With power = 1, the density is the constant 1 / (rmax - rmin).

The engine draws a new value at the start of every replication. Without SetReplications(int), each trial solution has one replication, so it gets one draw, and its result depends on that one draw. To compare trial solutions by the combined result of several draws, call SetReplications with more than one replication.

Parameters:

name - name of the variable (must be unique, no whitespace or ;)

rmin - inner radius; must be non-negative

rmax - outer radius; must be greater than rmin

power - sets where the values are most frequent, as described above; must be greater than 0. Zero is not the uniform case (uniform is power = 1), and the engine refuses zero and any negative value

Returns:

true if the variable was added; false if the name is not valid, for example if it is already in use or contains whitespace or a semicolon

Throws:

com.opttek.optquest.COptQuestException - if an error occurred adding the variable

AddSphericalElevationRandomVariable

public boolean AddSphericalElevationRandomVariable(String name,
 double min,
 double max)
                                            throws com.opttek.optquest.COptQuestException

Adds a spherical elevation random variable.

The engine draws a new value at the start of every replication. Without SetReplications(int), each trial solution has one replication, so it gets one draw, and its result depends on that one draw. To compare trial solutions by the combined result of several draws, call SetReplications with more than one replication.

Parameters:

name - name of the variable (must be unique, no whitespace or ;)

min - minimum elevation

max - maximum elevation

Returns:

true if the variable was added; false if the name is not valid, for example if it is already in use or contains whitespace or a semicolon

Throws:

com.opttek.optquest.COptQuestException - if an error occurred adding the variable

AddStudentTRandomVariable

public boolean AddStudentTRandomVariable(String name,
 int df)
                                  throws com.opttek.optquest.COptQuestException

Adds a Student's t-distributed random variable.

The engine draws a new value at the start of every replication. Without SetReplications(int), each trial solution has one replication, so it gets one draw, and its result depends on that one draw. To compare trial solutions by the combined result of several draws, call SetReplications with more than one replication.

Parameters:

name - name of the variable (must be unique, no whitespace or ;)

df - degrees of freedom

Returns:

true if the variable was added; false if the name is not valid, for example if it is already in use or contains whitespace or a semicolon

Throws:

com.opttek.optquest.COptQuestException - if an error occurred adding the variable

AddUniformRandomVariable

public boolean AddUniformRandomVariable(String name,
 double min,
 double max)
                                 throws com.opttek.optquest.COptQuestException

Adds a uniform random variable.

The engine draws a new value at the start of every replication. Without SetReplications(int), each trial solution has one replication, so it gets one draw, and its result depends on that one draw. To compare trial solutions by the combined result of several draws, call SetReplications with more than one replication.

Parameters:

name - name of the variable (must be unique, no whitespace or ;)

min - minimum value

max - maximum value

Returns:

true if the variable was added; false if the name is not valid, for example if it is already in use or contains whitespace or a semicolon

Throws:

com.opttek.optquest.COptQuestException - if an error occurred adding the variable

AddWeibullRandomVariable

public boolean AddWeibullRandomVariable(String name,
 double shape,
 double scale)
                                 throws com.opttek.optquest.COptQuestException

Adds a Weibull-distributed random variable.

The engine draws a new value at the start of every replication. Without SetReplications(int), each trial solution has one replication, so it gets one draw, and its result depends on that one draw. To compare trial solutions by the combined result of several draws, call SetReplications with more than one replication.

Parameters:

name - name of the variable (must be unique, no whitespace or ;)

shape - shape parameter

scale - scale parameter

Returns:

true if the variable was added; false if the name is not valid, for example if it is already in use or contains whitespace or a semicolon

Throws:

com.opttek.optquest.COptQuestException - if an error occurred adding the variable

AddOutputVariable

public boolean AddOutputVariable(String name)
                          throws com.opttek.optquest.COptQuestException

Adds an output variable. You set the value of an output variable. It can be an output of a simulation or a value calculated from the values of decision variables. Output variables can be used in the mathematical expression of constraints and objectives.

Parameters:

name - - name of the variable. The name must be unique to the model and must not contain whitespace or semicolons.

Returns:

true if the variable was added; false if the name is not valid, for example if it is already in use or contains whitespace or a semicolon

Throws:

com.opttek.optquest.COptQuestException - - An exception is thrown if an error occurred adding the variable.

SetOutputStatistic

public boolean SetOutputStatistic(String name,
 int statistic)
                           throws com.opttek.optquest.COptQuestException

Defines the statistic for the replications of an output variable. Available statistics include:

• Statistic.None = 0
• Statistic.Mean = 1
• Statistic.Median = 2
• Statistic.StdDev = 4
• Statistic.Variance = 6
• Statistic.CoeffOfVar = 8
• Statistic.Min = 14
• Statistic.Max = 15
• Statistic.Sum = 16

With Statistic.None, the result is the same as with no call: the engine uses the mean of the replications. The exception is an output that is used by an objective with its own statistic. The engine does not combine that output, so GetValue on it returns the value of the replication that completed last.

Parameters:

name - - name of the output variable

statistic - - the statistic to be applied to the output

Returns:

- true if the statistic was added successfully; false if an output with the name does not exist.

Throws:

com.opttek.optquest.COptQuestException - - An exception is thrown if an error occurred adding the variable.

SetOutputStatistic

public boolean SetOutputStatistic(String name,
 int statistic,
 double statisticValue)
                           throws com.opttek.optquest.COptQuestException

Defines the percentile statistic for the replications of an output variable.

Parameters:

name - - name of the output variable.

statistic - - Statistic.Percentile

statisticValue - - target value

Returns:

- true if the statistic was added successfully; false if an output with the name does not exist.

Throws:

com.opttek.optquest.COptQuestException - - An exception is thrown if an error occurred adding the variable.

AddOutputVectorVariable

public boolean AddOutputVectorVariable(String name,
 int n)
                                throws com.opttek.optquest.COptQuestException

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

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

Your evaluator writes a value to each element before it submits the solution.

Parameters:

name - base name of the variable; it must be unique and must not contain whitespace or a semicolon

n - number of elements; must be at least 1

Returns:

true if the variable was added; false if the name is not valid, for example if it is already in use or contains whitespace or a semicolon

Throws:

com.opttek.optquest.COptQuestException - if n is less than 1

AddOutputMatrixVariable

public boolean AddOutputMatrixVariable(String name,
 int rows,
 int cols)
                                throws com.opttek.optquest.COptQuestException

Adds an output matrix variable: a rows by cols matrix of output variables. The elements are ordinary output variables.

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

Your evaluator writes a value to each element before it submits the solution.

Parameters:

name - base name of the variable; it must be unique and must not contain whitespace or a semicolon

rows - number of rows; must be at least 1

cols - number of columns; must be at least 1

Returns:

true if the variable was added; false if the name is not valid, for example if it is already in use or contains whitespace or a semicolon

Throws:

com.opttek.optquest.COptQuestException - if rows or cols is less than 1

AddExpressionVariable

public boolean AddExpressionVariable(String name,
 String expression)
                              throws com.opttek.optquest.COptQuestException

Defines a variable that is evaluated as an expression of other variables in the model. The expression may include variables and outputs. For example, the objective may be to minimize "2*Var1 + 3*Var2 + 1.5*Var3". "Var1", "Var2" and "Var3" must be names that were assigned to variables. A list of the supported mathematical functions can be found in the "Functions Available In Expressions" section in the Help.

Parameters:

name - - name of the variable. The name must be unique to the model and must not contain whitespace or semicolons.

expression - - the string expression.

Returns:

true if the variable was added; false if the name is not valid, for example if it is already in use or contains whitespace or a semicolon

Throws:

com.opttek.optquest.COptQuestException - - An exception is thrown if an error occurred adding the expression variable.

AddConstraint

public boolean AddConstraint(String name,
 String expression)
                      throws com.opttek.optquest.COptQuestException

Defines a linear or non-linear constraint where the expression may include variables and outputs. "2*Var1 + 3*Var2 + 1.5*Var3 ≤ 100" could be used to define a budget constraint. "Var1", "Var2" and "Var3" must be names that were assigned to variables. A list of the supported mathematical functions can be found in the "Functions Available In Expressions" section in the Help.

The engine checks a constraint that uses only ordinary input variables before the evaluation. In every solution that the engine generates, the inputs meet the constraint. The engine checks a constraint that uses an output, or an expression that depends on an output, after the evaluation. A solution that breaks it is infeasible.

A constraint that uses a value of a manifold variable is checked after the evaluation, like a constraint on an output. These values have names with '@', such as mix@compA or dir@theta, and COptQuestManifoldVariable.getProjectedInputVariables() returns them. The same applies to a constraint that uses a random variable. Your evaluator can receive values that break such a constraint, and the solution is then infeasible. The values of an item selection variable and a budgeted selection variable are ordinary inputs.

Parameters:

name - - name of the constraint. The name must be unique to the model and must not contain whitespace or semicolons.

expression - - the string expression.

Returns:

- true if the constraint was added successfully; false if the name was not unique to the model or contained whitespace or semicolons.

Throws:

com.opttek.optquest.COptQuestException - - An exception is thrown if an error occurred adding the constraint.

AddObjective

public boolean AddObjective(String name,
 String dir,
 String expression)

Defines an objective whose value the optimizer minimizes or maximizes. The expression may include variables and outputs. For example, the objective may be to minimize "2*Var1 + 3*Var2 + 1.5*Var3". "Var1", "Var2" and "Var3" must be names that were assigned to variables. A list of the supported mathematical functions can be found in the "Functions Available In Expressions" section in the Help.

Parameters:

name - - name of the objective. The name must be unique to the model and must not contain whitespace or semicolons.

dir - - "MIN" or "MAX"

expression - - the string expression.

Returns:

- true if the objective was added successfully; false if objective name is not unique or contains whitespace or semicolons.

AddMinimizeObjective

public boolean AddMinimizeObjective(String name,
 String expression)

Defines an objective whose value the optimizer minimizes. The expression may include variables and outputs. For example, the objective may be to minimize "2*Var1 + 3*Var2 + 1.5*Var3". "Var1", "Var2" and "Var3" must be names that were assigned to variables. A list of the supported mathematical functions can be found in the "Functions Available In Expressions" section in the Help.

Parameters:

name - - name of the objective. The name must be unique to the model and must not contain whitespace or semicolons.

expression - - the string expression.

Returns:

- true if the objective was added successfully; false if objective name is not unique or contains whitespace or semicolons.

AddMaximizeObjective

public boolean AddMaximizeObjective(String name,
 String expression)

Defines an objective whose value the optimizer maximizes. The expression may include variables and outputs. For example, the objective may be to maximize "2*Var1 + 3*Var2 + 1.5*Var3". "Var1", "Var2" and "Var3" must be names that were assigned to variables. A list of the supported mathematical functions can be found in the "Functions Available In Expressions" section in the Help.

Parameters:

name - - name of the objective. The name must be unique to the model and must not contain whitespace or semicolons.

expression - - the string expression.

Returns:

- true if the objective was added successfully; false if the objective name is not unique to the model or contains whitespace or semicolons.

SetObjectiveGoal

public boolean SetObjectiveGoal(String name,
 double min,
 double max)

Sets a target range, from min to max inclusive, for an objective in a model with two or more objectives. It is ignored if the model has a single objective.

OptQuest uses the goal to decide where to search. After its first cycle of search phases, OptQuest uses the rest of the run to fill gaps between neighboring solutions on the Pareto frontier, while the frontier has at least two solutions. It fills first the largest gap next to a frontier solution whose objective values are inside the most goal ranges. OptQuest does not use the goal to decide feasibility, and it does not remove the solutions outside the range from the frontier: GetBestSolutions() can return them.

Parameters:

name - - name of the objective

min - - minimum value of the goal range.

max - - maximum value of the goal range.

Returns:

- true if the goal range was successfully added; false if an objective with the specified name does not exist in the model.

SetObjectiveConfidence

public boolean SetObjectiveConfidence(String name,
 int ctype,
 int clevel,
 double epct)

Sets the values used for replication confidence testing on the specified objective. Confidence testing is only available when the replication statistic is the mean value, OptQuestModel.Statistic.Mean

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

Parameters:

name - - name of the objective

ctype -

OptQuestModel.Confidence.Type1 = indicates the replications should stop after the minimum replications have been run and when the confidence level is reached or the maximum number of replications is run.

OptQuestModel.Confidence.Type2 = indicates the replications should stop after the minimum replications are run and the confidence level is reached, or the maximum number of replications is run, or when the best solution does not fall within current solutions confidence level. Type 2 is not available for COptQuestMultiObjective.

clevel -

• OptQuestModel.Confidence.Level80 = 80%
• OptQuestModel.Confidence.Level90 = 90%
• OptQuestModel.Confidence.Level95 - 95%
• OptQuestModel.Confidence.Level98 = 98%
• OptQuestModel.Confidence.Level99 = 99%
• OptQuestModel.Confidence.Level999 = 99.9%

epct - - the acceptable error, as a fraction of the mean of the replications. It must be greater than 0 and less than 1. For 5 percent, pass 0.05. The engine checks the value when the model initializes, not at this call. With a value outside that range, the run fails with the message "Bad value for the replication confidence error percent."

Returns:

- true if the objective confidence was set successfully. false if it failed.

SetObjectiveStatistic

public boolean SetObjectiveStatistic(String name,
 int statistic)
                              throws com.opttek.optquest.COptQuestException

Defines the statistic for the replications of an objective. Available statistics include:

• Statistic.None = 0
• Statistic.Mean = 1
• Statistic.Median = 2
• Statistic.StdDev = 4
• Statistic.Variance = 6
• Statistic.CoeffOfVar = 8
• Statistic.Min = 14
• Statistic.Max = 15
• Statistic.Sum = 16

With Statistic.None, or with no call, the engine combines each output that the objective uses, with the statistic of that output (the mean unless SetOutputStatistic(String, int) sets another), and computes the objective expression once from those values. With any other statistic, the engine computes the expression in each replication and applies the statistic to those values. For an objective y*y and two replications with y = 1 and y = 3, no statistic gives 4.0, Statistic.Mean gives 5.0 and Statistic.Max gives 9.0. When the model initializes, the engine refuses a statistic on the objective together with a statistic other than None on an output that the objective uses.

Parameters:

name - - name of the objective variable

statistic - - the statistic to be applied to the objective

Returns:

- true if the statistic was added successfully; false if the add failed.

Throws:

com.opttek.optquest.COptQuestException - - An exception is thrown if an error occurred setting the statistic

SetObjectiveStatistic

public boolean SetObjectiveStatistic(String name,
 int statistic,
 double statisticValue)
                              throws com.opttek.optquest.COptQuestException

Defines the percentile statistic for the replications of an objective.

Parameters:

name - - name of the objective variable.

statistic - - Statistic.Percentile

statisticValue - - target value

Returns:

- true if the statistic was added successfully; false if the add failed.

Throws:

com.opttek.optquest.COptQuestException - - An exception is thrown if an error occurred adding the variable.

SetReplications

public boolean SetReplications(int reps)

Sets the number of fixed replications to be run for each solution. A value of 1 runs without replications.

Parameters:

reps - - number of replications to be run on each solution.

Returns:

- true if replications were set successfully.

SetReplications

public boolean SetReplications(int min,
 int max)

Sets the number of variable replications to be run for each solution. Variable replications are used with confidence settings to control when replication processing is complete. min must be at least 1 and max at least min; max of 1 runs without replications. A confidence interval needs two replications, so a min of 1 runs at least 2 when max is greater than 1.

The replications stop early when the objective meets the confidence set with SetObjectiveConfidence(String, int, int, double). Without SetObjectiveConfidence, the engine runs max replications for every trial solution. SetObjectiveStatistic(String, int) and SetOutputStatistic(String, int) set how the engine combines the replications into one value. They do not stop the replications early.

Parameters:

min - - minimum number of replications to be run on each solution.

max - - maximum number of replications to be run on each solution.

Returns:

- true if replications were set successfully.

SetSerialReplications

public boolean SetSerialReplications()

Runs the replications of each solution serially. If you are running replications and using multiple evaluators, the replication solutions can be run in parallel, or they can be run serially. If they are run in parallel, solution n, replication 1 can be evaluated at the same time as solution n, replication 2. If you run the replications serially, solution n, replication 1 must finish before solution n, replication 2 can be run, and they could both run on the same evaluator. Running serially may be beneficial if your simulation requires a warm-up period.

Most users do not need this method. It has an effect only on a model with replications whose solutions are evaluated in parallel.

Returns:

true if the serial replication management was set successfully.

SetParallelHint

public boolean SetParallelHint(int npar)

Sets a hint for the number of parallel evaluations that are expected to happen. This should correspond to the number of processors/computer available for evaluation. OptQuest defaults to a single evaluator, so this method is only needed if more than one evaluator is desired. This value is a hint to how many solutions are expected to be evaluated in parallel. It is used to configure the internal metaheuristics. During evaluation any number (up to 5000) solutions may be evaluated in parallel. Optimization will be most efficient when the number matches this hint.

Most users do not need this method. It has an effect only in a manual loop with several solutions out at once. The parallel Optimize(npar, ...) methods set the hint to their own npar.

Parameters:

npar - number of parallel evaluators

Returns:

true if the hint was set successfully.

SetRandomSeed

public boolean SetRandomSeed(int seed)

Sets the random seed. The engine uses the random seed in solution generation, so a change to the seed can change the set of solutions.

Use it to find out how much a result depends on the random choices of the search: run the same model with several seeds and compare the best objective values. By default the engine always uses the same seed, so an optimization is repeatable.

Parameters:

seed - value to be used as the random seed; it must be greater than 0. A seed of 0 or less is accepted but ignored, and the default seed is used.

Returns:

true if the random seed was set.

StopOnSuccessfulMILP

public boolean StopOnSuccessfulMILP()

Sets a flag so that the optimization stops as soon as it finds an optimal solution in the case that the optimization is a mixed integer linear program (MILP).

Returns:

true if the flag was set.

SuggestedSolutionsOnly

public boolean SuggestedSolutionsOnly()

Restricts the model to the solutions you supply. OptQuest evaluates the solutions added with AddSuggested(), AddEvaluated() and AddRequired(), and generates none of its own.

Suggested solutions are still mapped to the feasible space and still checked for duplicates, so you can use the model as a batch mapper: supply a set of points and CreateSolution() returns the ones that map to distinct feasible solutions. When the supplied solutions run out, CreateSolution() returns an invalid solution and GetTerminationReason() reports FactoriesDone, so the caller reads back however many solutions remain without knowing the count in advance.

Only AddSuggested() points are mapped. The solutions from all three supply methods are evaluated and deduplicated, but the engine maps to the feasible space only the solutions from AddSuggested(). A solution from AddEvaluated() holds a response that was already measured for its input values, and a solution from AddRequired() is evaluated exactly as supplied. So the engine deliberately does not map either kind, and they come back with the caller's raw values.

The model still requires an objective, and each solution returned by CreateSolution() must be returned to the engine with Submit() or Reject(). The engine checks for duplicates across the whole run rather than in a single batch, and a model cannot be refilled after its supplied solutions are used up. Once CreateSolution() reports the queue empty, solutions added afterwards are accepted but never evaluated. So use a separate model for each set of points that should be mapped independently.

Use this mode with the manual CreateSolution() loop, not with Optimize(n, ...). Running out of supplied solutions is the normal end of a mapping run, but the serial Optimize(nsol, ...) overload reports it as a failure: it returns false once the supplied solutions are exhausted before nsol is reached, without throwing and with no error message, so a successful mapping run returns the same value as a real failure. The parallel overload returns true in the same situation. In this mode the caller does not know in advance how many solutions remain, so nsol is almost always larger than that number.

Must be called before the model is initialized.

Returns:

true if the flag was set.

SetStopCycles

public boolean SetStopCycles(int cycles)

Stops the optimization after cycles search cycles. The run then ends with the termination reason AutoStop (4). A search cycle is one pass of the engine's search methods, and the number of iterations in a cycle depends on the problem. An improvement of the best solution does not reset the count of cycles.

Parameters:

cycles - - the number of cycles to try before stopping.

Returns:

true if the cycles were set successfully.

SetStopImprovement

public boolean SetStopImprovement(double improvement,
 int iterations)

Stops the optimization when iterations consecutive iterations pass without a cumulative improvement of more than the fraction improvement. The improvement is relative, measured against the best and worst feasible objective values found so far. For example, SetStopImprovement(0.01, 100) stops the run when, over the last 100 iterations, the best objective changed by 1 percent or less of the difference between the best and the worst feasible objective values. The run then ends with the termination reason AutoStop (4).

The rule applies only to a model with one objective. The engine ignores it when the model has two or more objectives.

Parameters:

improvement - - the fraction; use a value from 0.0 to 0.2

iterations - - number of consecutive iterations

Returns:

true if the stopping rule was set successfully.

SetStopTime

public boolean SetStopTime(int seconds)

Sets the number of seconds the optimization should run before stopping. The current iteration will complete before the optimization stops. If the evaluation is long (such as running a simulation) the actual time the optimization runs may be longer than specified.

Parameters:

seconds - maximum number of seconds

Returns:

true if the stop time was set successfully.

AddSampleMetric

public boolean AddSampleMetric(String name,
 String responseExpression,
 String errorExpression)

Defines a response metric and an error metric that the engine tracks for adaptive sampling. The expressions may include variables and outputs. For example, the objective may be to minimize "2*Var1 + 3*Var2 + 1.5*Var3". "Var1", "Var2" and "Var3" must be names that were assigned to variables. A list of the supported mathematical functions can be found in the "Functions Available In Expressions" section in the Help.

Parameters:

name - - name of the objective. The name must be unique to the model.

responseExpression - - the string expression for the response value to track.

errorExpression - - the string expression for the error in the response value.

Returns:

- true if the objective was added successfully; false if the add failed.

SetSampleMethod

public boolean SetSampleMethod(int method)

Sets the sample method to be used when using sample metrics. Available sampling methods include:

• SampleMethod.Stochastic
• SampleMethod.Dynamic
• SampleMethod.Async
• SampleMethod.Variance
• SampleMethod.Uniform
• SampleMethod.Zero
• SampleMethod.Gradient
• SampleMethod.Min
• SampleMethod.Max

Parameters:

method - - bitwise or'd values to turn on one or more of the sampling methods

Returns:

true if the sampling method was set successfully.

SetSampleVariogram

public boolean SetSampleVariogram(String variogram)

Sets the sample variogram to be used when building the surrogate model. By default the engine chooses a variogram with a heuristic. Most users do not need this method: use the default unless OptTek support advises a different variogram. Available variograms include:

• SampleVariogram.Spherical
• SampleVariogram.Pow
• SampleVariogram.Exp
• SampleVariogram.Gaussian
• SampleVariogram.Tanh
• SampleVariogram.Sech
• SampleVariogram.Linear
• SampleVariogram.Quadratic
• SampleVariogram.Partition
• SampleVariogram.Matern

Parameters:

variogram - - name of the variogram to use

Returns:

true if the sampling variogram was set successfully.

SetSampleRDSParams

public boolean SetSampleRDSParams(String name,
 String distribution,
 double[] params)

Sets the bins to use if response distribution sampling is enabled, from a named distribution.

Parameters:

name - - metric name

distribution - - name of the distribution

params - - parameters for the distribution

Returns:

true if the sampling method was set successfully.

SetSampleRDSUniform

public boolean SetSampleRDSUniform(String name,
 int nBins,
 double a,
 double b)

Sets the bins to use if response distribution sampling is enabled, from a uniform distribution.

Parameters:

name - - metric name

nBins - - number of bins

a - Lower bound

b - Upper bound

Returns:

true if the sampling method was set successfully.

SetSampleRDSNormal

public boolean SetSampleRDSNormal(String name,
 int nBins,
 double mu,
 double sigma)

Sets the bins to use if response distribution sampling is enabled, from a normal distribution.

Parameters:

name - - metric name

nBins - - number of bins

mu - Mean

sigma - Standard deviation

Returns:

true if the sampling method was set successfully.

SetSampleRDSLogNormal

public boolean SetSampleRDSLogNormal(String name,
 int nBins,
 double s,
 double scale)

Sets the bins to use if response distribution sampling is enabled, from a log-normal distribution.

Parameters:

name - - metric name

nBins - - number of bins

s - Shape parameter

scale - Scale parameter

Returns:

true if the sampling method was set successfully.

SetSampleRDSBeta

public boolean SetSampleRDSBeta(String name,
 int nBins,
 double alpha,
 double beta)

Sets the bins to use if response distribution sampling is enabled, from a Beta distribution.

Parameters:

name - - metric name

nBins - - number of bins

alpha - Shape parameter

beta - : Shape parameter

Returns:

true if the sampling method was set successfully.

SetSampleRDSPoisson

public boolean SetSampleRDSPoisson(String name,
 int nBins,
 double lambda)

Sets the bins to use if response distribution sampling is enabled, from a Poisson distribution.

Parameters:

name - - metric name

nBins - - number of bins

lambda - Rate parameter

Returns:

true if the sampling method was set successfully.

SetSampleRDSExponential

public boolean SetSampleRDSExponential(String name,
 int nBins,
 double scale)

Sets the bins to use if response distribution sampling is enabled, from an exponential distribution.

Parameters:

name - - metric name

nBins - - number of bins

scale - Scale parameter.

Returns:

true if the sampling method was set successfully.

SetSampleRDSCauchy

public boolean SetSampleRDSCauchy(String name,
 int nBins,
 double location,
 double scale)

Sets the bins to use if response distribution sampling is enabled, from a Cauchy distribution.

Parameters:

name - - metric name

nBins - - number of bins

location - Location parameter.

scale - Scale parameter.

Returns:

true if the sampling method was set successfully.

SetSampleRDSGamma

public boolean SetSampleRDSGamma(String name,
 int nBins,
 double a,
 double scale)

Sets the bins to use if response distribution sampling is enabled, from a Gamma distribution.

Parameters:

name - - metric name

nBins - - number of bins

a - Shape parameter

scale - Scale parameter.

Returns:

true if the sampling method was set successfully.

SetSampleRDSChiSquare

public boolean SetSampleRDSChiSquare(String name,
 int nBins,
 double nu)

Sets the bins to use if response distribution sampling is enabled, from a Chi-square distribution.

Parameters:

name - - metric name

nBins - - number of bins

nu - Degrees of freedom

Returns:

true if the sampling method was set successfully.

SetSampleRDSPareto

public boolean SetSampleRDSPareto(String name,
 int nBins,
 double gamma,
 double loc,
 double scale)

Sets the bins to use if response distribution sampling is enabled, from a Pareto distribution.

Parameters:

name - - metric name

nBins - - number of bins

gamma - Shape parameter.

loc - Location parameter.

scale - Scale parameter.

Returns:

true if the sampling method was set successfully.

SetSampleRDST

public boolean SetSampleRDST(String name,
 int nBins,
 double nu)

Sets the bins to use if response distribution sampling is enabled, from a Student's t distribution.

Parameters:

name - - metric name

nBins - - number of bins

nu - Degrees of freedom

Returns:

true if the sampling method was set successfully.

SetSampleRDSWeibull

public boolean SetSampleRDSWeibull(String name,
 int nBins,
 double c,
 double scale)

Sets the bins to use if response distribution sampling is enabled, from a Weibull distribution.

Parameters:

name - - metric name

nBins - - number of bins

c - Shape parameter

scale - Scale parameter

Returns:

true if the sampling method was set successfully.

SetSampleRDSDiscrete

public boolean SetSampleRDSDiscrete(String name,
 double[] binEdges)

Sets the bins to use if response distribution sampling is enabled, from a list of bin edges.

Parameters:

name - - metric name

binEdges - list of binEdges to use for an arbitrary response distribution

Returns:

true if the sampling method was set successfully.

Describe

public String Describe()

Generates a string describing the model parameters.

Returns:

string that describes the model setup

Initialize

public boolean Initialize()
                   throws com.opttek.optquest.COptQuestException

Prepares the model to run and moves it from the definition stage to the execution stage, after which the model is immutable.

Calling this is optional: every method that needs an initialized model calls it first. Call it explicitly only to find out whether the model is well formed before generating any solutions.

Returns:

true if the model initialized successfully.

Throws:

com.opttek.optquest.COptQuestException - - An exception is thrown if there was an error building the model.

Interrupt

public void Interrupt()

Signals the OptQuestModel to stop generating new solutions during manual optimization loops. Only used for manual optimizations.

Continue

public void Continue()

Restarts an optimization that was interrupted with a call to Interrupt(). Only used for manual optimizations. After Interrupt(), no new solutions will be generated unless Continue() is called.

CleanUp

public void CleanUp()

Closes the log files opened by LogSetup(String) and LogSolutions(String).

The setup log is XML and is only well formed once its closing elements are written, so a model that logged its setup must be cleaned up before the file is read. Calling this more than once is harmless. It is called for you when the model is deleted through the C API or a language binding; a caller holding the Java object directly has no other way to release the files, which stay locked on Windows until the process exits.

CreateSolution

public OptQuestSolution CreateSolution()
                                throws com.opttek.optquest.COptQuestException

Requests the OptQuestModel to generate a new trial solution for evaluation. Only used for manual optimizations. OptQuest populates the solution with values for each input variable. Each output that your evaluator writes (an output variable, or an element of an output vector, matrix or N-dimensional variable) is NaN until you set it. If you submit the solution with an output that is not set, each objective and constraint that uses the output is NaN, and the solution is infeasible.

Returns:

- Returns an OptQuestSolution, never null. Test IsValid() on it: false means the engine had no further solution to offer, or the model failed to initialize. Call GetTerminationReason() to tell those apart.

Throws:

com.opttek.optquest.COptQuestException - if an error occurred

GetEmptySolution

public OptQuestSolution GetEmptySolution()
                                  throws com.opttek.optquest.COptQuestException

Creates an empty OptQuestSolution. This method can be used to create a suggested solution by setting values for each of the variables in the model. Call OptQuestSolution.AddSuggested() to add the solution to the model.

Use the solution with AddSuggested(), AddEvaluated() or AddRequired(). Do not call Submit() or Reject() on it: the engine did not issue it, and Java does not refuse the call.

Returns:

- returns an empty OptQuestSolution

Throws:

com.opttek.optquest.COptQuestException - An exception is thrown if an error occurred creating an empty solution.

CopySolution

public OptQuestSolution CopySolution(OptQuestSolution src)
                              throws com.opttek.optquest.COptQuestException

Make a copy of the input OptQuestSolution. This can be used to populate a new OptQuestModel instance with solutions from a previously run OptQuestModel. After calling CopySolution(), call AddEvaluated() for the copied solution.

The copy contains the input values, the output values, and the per-replication values of each output. Each manifold variable in the copy has the same values as in src.

Use the copy with AddSuggested(), AddEvaluated() or AddRequired(). Do not call Submit() or Reject() on it: the engine did not issue it, and Java does not refuse the call.

Parameters:

src - - the solution to be copied

Returns:

- the copy of src. If the model cannot initialize, the method returns a solution for which OptQuestSolution.IsValid() returns false.

Throws:

com.opttek.optquest.COptQuestException - - An exception is thrown if an error occurred copying the solution.

AddAllSolutions

public boolean AddAllSolutions(OptQuestModel src)
                        throws com.opttek.optquest.COptQuestException

Copies every evaluated solution of the source model src into this model. Use it to continue an optimization after you change the model, for example its constraints or objectives. Each copy is added in the same way as with AddEvaluated(): the engine does not evaluate it again, and it uses its input and output values as given. The engine computes the objectives and constraints of each copy with the definitions of this model, so a copy that breaks a constraint of this model is infeasible.

The two models must declare the same input names and the same output names, compared without regard to case. The variable types are not compared. If the names are different, the call returns false and copies nothing.

Parameters:

src - - OptQuestModel with evaluated solutions.

Returns:

- true if every solution was copied; false if the names are different or a copy failed

Throws:

com.opttek.optquest.COptQuestException - - An exception is thrown if an error occurred adding the solutions.

CreateAsyncChannel

public OptQuestModelChannel CreateAsyncChannel(int npar)

Creates an asynchronous communication channel to send signals to the model during an optimization

Parameters:

npar - - number of concurrent threads to support in Optimize call().

Returns:

- OptQuestModelChannel object tied to this model.

Optimize

public boolean Optimize(int nsol)
                 throws com.opttek.optquest.COptQuestException

Starts the optimization and stops when nsol solutions have been evaluated.

Parameters:

nsol - - number of solutions to generate before stopping.

Returns:

- true if the optimization completed successfully. Return false if there were any errors.

Throws:

com.opttek.optquest.COptQuestException - - An exception is thrown if there were any errors in the model setup or during the optimization.

Optimize

public boolean Optimize(int nsol,
 IOptQuestEvaluator eval)
                 throws com.opttek.optquest.COptQuestException

Starts the optimization and stops when nsol solutions have been evaluated. The custom evaluator eval will be called to evaluate each solution.

Parameters:

nsol - - number of solutions to generate

eval - - custom evaluator used to evaluate each solution.

Returns:

- true if the optimization completed successfully. Return false if there were any errors.

Throws:

com.opttek.optquest.COptQuestException - - An exception is thrown if there were any errors in the model setup or during the optimization.

Optimize

public boolean Optimize(int nsol,
 IOptQuestEvaluator eval,
 IOptQuestMonitor monitor)
                 throws com.opttek.optquest.COptQuestException

Starts the optimization and stops when nsol solutions have been evaluated. The custom evaluator eval.Evaluate() will be called to evaluate each solution. When a solution has completed evaluation and OptQuest has updated the best solution or frontier solutions, the custom monitor.Monitor() is called.

Parameters:

nsol - - number of solutions to generate

eval - - custom class used to evaluate each solution.

monitor - - custom class to monitor optimization progress.

Returns:

- true if the optimization completed successfully. Return false if there were any errors.

Throws:

com.opttek.optquest.COptQuestException - - An exception is thrown if there were any errors in the model setup or during the optimization.

Optimize

public boolean Optimize(int npar,
 int nsol)
                 throws com.opttek.optquest.COptQuestException

Starts the optimization and stops when nsol solutions have been evaluated. The optimization is run with npar number of parallel evaluators meaning npar evaluations will be done in parallel.

Parameters:

npar - - number of parallel evaluators to use

nsol - - number of solutions to generate

Returns:

- true if the optimization completed successfully. Return false if there were any errors.

Throws:

com.opttek.optquest.COptQuestException - - An exception is thrown if there were any errors in the model setup or during the optimization.

Optimize

public boolean Optimize(int npar,
 int nsol,
 IOptQuestEvaluator eval)
                 throws com.opttek.optquest.COptQuestException

Starts the optimization and stops when nsol solutions have been evaluated. The optimization is run with npar number of parallel evaluators meaning npar evaluations will be done in parallel. The custom evaluator eval.Evaluate() will be called to evaluate each solution.

Parameters:

npar - - number of parallel evaluators to use

nsol - - number of solutions to generate

eval - - custom class used to evaluate each solution.

Returns:

- true if the optimization completed successfully. Return false if there were any errors.

Throws:

com.opttek.optquest.COptQuestException - - An exception is thrown if there were any errors in the model setup or during the optimization.

Optimize

public boolean Optimize(int npar,
 int nsol,
 IOptQuestEvaluator eval,
 IOptQuestMonitor monitor)
                 throws com.opttek.optquest.COptQuestException

Starts the optimization and stops when nsol solutions have been evaluated. The optimization is run with npar number of parallel evaluators meaning npar evaluations will be done in parallel. The custom evaluator eval.Evaluate() will be called to evaluate each solution. When a solution has completed evaluation and OptQuest has updated the best solution or frontier solutions, the custom monitor.Monitor() is called.

Parameters:

npar - - number of parallel evaluators to use

nsol - - number of solutions to generate

eval - - custom evaluator used to evaluate each solution.

monitor - - custom class to monitor optimization progress.

Returns:

- true if the optimization completed successfully. Return false if there were any errors.

Throws:

com.opttek.optquest.COptQuestException - throws a COptQuestException if an error occurred during the optimization.

Optimize

public boolean Optimize(OptQuestModelChannel ipc,
 int nsol)
                 throws com.opttek.optquest.COptQuestException

Starts the optimization and stops when nsol solutions have been evaluated. Signals are sent to the OptQuestModelChannel as the optimization progresses.

Parameters:

ipc - - an asynchronous communication channel.

nsol - - number of solutions to generate

Returns:

- true if the optimization completed successfully. Return false if there were any errors.

Throws:

com.opttek.optquest.COptQuestException - throws a COptQuestException if an error occurred during the optimization.

Optimize

public boolean Optimize(OptQuestModelChannel ipc,
 int nsol,
 IOptQuestEvaluator eval)
                 throws com.opttek.optquest.COptQuestException

Starts the optimization and stops when nsol solutions have been evaluated. Signals are sent to the OptQuestModelChannel as the optimization progresses. The custom evaluator eval.Evaluate() will be called to evaluate each solution.

Parameters:

ipc - - an asynchronous communication channel.

nsol - - number of solutions to generate

eval - - custom evaluator used to evaluate each solution.

Returns:

- true if the optimization completed successfully. Return false if there were any errors.

Throws:

com.opttek.optquest.COptQuestException - throws a COptQuestException if an error occurred during the optimization.

Optimize

public boolean Optimize(OptQuestModelChannel ipc,
 int nsol,
 IOptQuestEvaluator eval,
 IOptQuestMonitor monitor)
                 throws com.opttek.optquest.COptQuestException

Starts the optimization and stops when nsol solutions have been evaluated. Signals are sent to the OptQuestModelChannel as the optimization progresses. The custom evaluator eval.Evaluate() will be called to evaluate each solution. When a solution has completed evaluation and OptQuest has updated the best solution or frontier solutions, the custom monitor.Monitor() is called.

Parameters:

ipc - - an asynchronous communication channel.

nsol - - number of solutions to generate

eval - - custom evaluator used to evaluate each solution.

monitor - - custom class to monitor optimization progress.

Returns:

- true if the optimization completed successfully. Return false if there were any errors.

Throws:

com.opttek.optquest.COptQuestException - throws a COptQuestException if an error occurred during the optimization.

Sample

public boolean Sample(int nsol)
               throws com.opttek.optquest.COptQuestException

Starts an adaptive sampling run and stops when nsol solutions have been evaluated. In a sampling run, the engine explores the response surface described by the metrics registered with AddSampleMetric(com.opttek.optquest.COptQuestStringObjective, com.opttek.optquest.COptQuestStringObjective) rather than searching for an optimum.

Parameters:

nsol - - number of solutions to generate

Returns:

- true if the sampling run completed successfully. Return false if there were any errors.

Throws:

com.opttek.optquest.COptQuestException - - An exception is thrown if there were any errors in the model setup or during sampling.

Sample

public boolean Sample(int nsol,
 IOptQuestEvaluator eval)
               throws com.opttek.optquest.COptQuestException

Starts an adaptive sampling run and stops when nsol solutions have been evaluated. The custom evaluator eval will be called to evaluate each solution.

Parameters:

nsol - - number of solutions to generate

eval - - custom evaluator used to evaluate each solution.

Returns:

- true if the sampling run completed successfully. Return false if there were any errors.

Throws:

com.opttek.optquest.COptQuestException - - An exception is thrown if there were any errors in the model setup or during sampling.

Sample

public boolean Sample(int nsol,
 IOptQuestEvaluator eval,
 IOptQuestMonitor monitor)
               throws com.opttek.optquest.COptQuestException

Starts an adaptive sampling run and stops when nsol solutions have been evaluated. The custom evaluator eval.Evaluate() will be called to evaluate each solution, and monitor.Monitor() is called once each solution has been processed.

Parameters:

nsol - - number of solutions to generate

eval - - custom class used to evaluate each solution.

monitor - - custom class to monitor sampling progress.

Returns:

- true if the sampling run completed successfully. Return false if there were any errors.

Throws:

com.opttek.optquest.COptQuestException - - An exception is thrown if there were any errors in the model setup or during sampling.

Sample

public boolean Sample(int npar,
 int nsol)
               throws com.opttek.optquest.COptQuestException

Starts a concurrent adaptive sampling run using npar parallel evaluators and stops when nsol solutions have been evaluated.

Parameters:

npar - - number of solutions to evaluate concurrently

nsol - - number of solutions to generate

Returns:

- true if the sampling run completed successfully. Return false if there were any errors.

Throws:

com.opttek.optquest.COptQuestException - - An exception is thrown if there were any errors in the model setup or during sampling.

Sample

public boolean Sample(int npar,
 int nsol,
 IOptQuestEvaluator eval)
               throws com.opttek.optquest.COptQuestException

Starts a concurrent adaptive sampling run using npar parallel evaluators. The custom evaluator eval will be called to evaluate each solution.

Parameters:

npar - - number of solutions to evaluate concurrently

nsol - - number of solutions to generate

eval - - custom evaluator used to evaluate each solution.

Returns:

- true if the sampling run completed successfully. Return false if there were any errors.

Throws:

com.opttek.optquest.COptQuestException - - An exception is thrown if there were any errors in the model setup or during sampling.

Sample

public boolean Sample(int npar,
 int nsol,
 IOptQuestEvaluator eval,
 IOptQuestMonitor monitor)
               throws com.opttek.optquest.COptQuestException

Starts a concurrent adaptive sampling run using npar parallel evaluators. The custom evaluator eval.Evaluate() will be called to evaluate each solution, and monitor.Monitor() is called once each solution has been processed.

Parameters:

npar - - number of solutions to evaluate concurrently

nsol - - number of solutions to generate

eval - - custom class used to evaluate each solution.

monitor - - custom class to monitor sampling progress.

Returns:

- true if the sampling run completed successfully. Return false if there were any errors.

Throws:

com.opttek.optquest.COptQuestException - - An exception is thrown if there were any errors in the model setup or during sampling.

Sample

public boolean Sample(OptQuestModelChannel ipc,
 int nsol)
               throws com.opttek.optquest.COptQuestException

Starts an asynchronous adaptive sampling run. Solutions are delivered through the supplied channel rather than through an evaluator callback.

Parameters:

ipc - - channel created by CreateAsyncChannel(int)

nsol - - number of solutions to generate

Returns:

- true if the sampling run completed successfully. Return false if there were any errors.

Throws:

com.opttek.optquest.COptQuestException - - An exception is thrown if there were any errors in the model setup or during sampling.

Sample

public boolean Sample(OptQuestModelChannel ipc,
 int nsol,
 IOptQuestEvaluator eval)
               throws com.opttek.optquest.COptQuestException

Starts an asynchronous adaptive sampling run with a custom evaluator.

Parameters:

ipc - - channel created by CreateAsyncChannel(int)

nsol - - number of solutions to generate

eval - - custom evaluator used to evaluate each solution.

Returns:

- true if the sampling run completed successfully. Return false if there were any errors.

Throws:

com.opttek.optquest.COptQuestException - - An exception is thrown if there were any errors in the model setup or during sampling.

Sample

public boolean Sample(OptQuestModelChannel ipc,
 int nsol,
 IOptQuestEvaluator eval,
 IOptQuestMonitor monitor)
               throws com.opttek.optquest.COptQuestException

Starts an asynchronous adaptive sampling run with a custom evaluator and monitor.

Parameters:

ipc - - channel created by CreateAsyncChannel(int)

nsol - - number of solutions to generate

eval - - custom class used to evaluate each solution.

monitor - - custom class to monitor sampling progress.

Returns:

- true if the sampling run completed successfully. Return false if there were any errors.

Throws:

com.opttek.optquest.COptQuestException - - An exception is thrown if there were any errors in the model setup or during sampling.

GetBestSolutions

public List<OptQuestSolution> GetBestSolutions()

If the OptQuestModel has a single objective, this method returns the best solution. If the model has multiple objectives, this method returns the points on the frontier.

The list is empty when the model has no completed iterations, for example before the first run or after a failed initialization, so test its length before you read the first entry. The first entry can be infeasible when the run found no feasible solution, so test OptQuestSolution.IsFeasible() on it.

For a single objective, the feasible solutions come first, then the infeasible solutions, then the solutions that the evaluator rejected, whose objective is NaN. Each group is in objective order, and equal values are in iteration order. The order does not depend on the size of a constraint violation, so when no solution is feasible, the first entry is the infeasible solution with the best objective value. For several objectives, the frontier is in no particular order.

Returns:

- The best solution for a single objective model. The points on the frontier for a multi-objective model.

GetBestSolutions

public List<OptQuestSolution> GetBestSolutions(int limit)

If the OptQuestModel has a single objective, this method returns the best n solutions where n is the limit parameter. If limit equals 0, all solutions are returned, ordered from best to worst. If limit is less than 0, the worst |limit| solutions are returned, worst first. If the model has multiple objectives, this method returns the points on the frontier.

The list is empty when the model has no completed iterations, for example before the first run or after a failed initialization, so test its length before you read the first entry. The first entry can be infeasible when the run found no feasible solution, so test OptQuestSolution.IsFeasible() on it.

For a single objective, the feasible solutions come first, then the infeasible solutions, then the solutions that the evaluator rejected, whose objective is NaN. Each group is in objective order, and equal values are in iteration order. The order does not depend on the size of a constraint violation, so when no solution is feasible, the first entry is the infeasible solution with the best objective value. An infeasible solution whose objective is NaN, for example because the evaluator did not set an output that the objective uses, comes after the infeasible solutions whose objective is a number, for a minimized and for a maximized objective. For several objectives, the frontier is in no particular order.

Parameters:

limit - - for a single objective OptQuestModel, the top n solutions are returned where n = limit.

Returns:

- the points on the frontier for a multi objective model. For a single objective model, the top n solutions.

GetAllSolutions

public List<OptQuestSolution> GetAllSolutions()
                                       throws com.opttek.optquest.COptQuestException

Returns all evaluated solutions.

Returns:

list of evaluated solutions.

Throws:

com.opttek.optquest.COptQuestException - if an error occurred

GetNumberOfCompletedIterations

public int GetNumberOfCompletedIterations()

Returns the number of solutions that have been evaluated. The count includes feasible solutions, infeasible solutions and rejected solutions.

Returns:

- the number of solutions.

GetMaxReplications

public int GetMaxReplications()

Returns the maximum number of replications set by SetReplications(int, int), or 0 before the model has initialized successfully.

Returns:

the maximum replication count, or 0 if the model is not yet initialized

GetTerminationReason

public int GetTerminationReason()

Returns why the last run stopped, as one of the OptQuestModel.TerminationReason constants.

NotStarted = 0

No run has started.

Running = 1

A run is in progress, or Continue() cleared an interrupt.

LP = 3

The objective and every constraint are linear, and the engine solved the problem exactly.

AutoStop = 4

The engine stopped the run because of a stop rule set with SetStopCycles(int) or SetStopImprovement(double, int).

OptimalFound = 5

The engine has no other candidate to try, for example because it evaluated every combination of values or because the constraints fix the values.

MaxIterations = 6

The run completed the number of iterations that you asked for.

MaxTime = 7

The engine stopped the run because it reached the time set with SetStopTime(int).

UserStopped = 8

The run was stopped, for example by Interrupt() or by a monitor that returned false.

BestFound = 9

Not used. The engine does not set this reason.

Exception = 10

The run stopped because of an error.

FactoriesDone = 11

The engine has no more solutions to generate. With SuggestedSolutionsOnly(), the supplied solutions are used up.

Infeasible = 12

No input values satisfy the constraints.

CannotGenerate = 13

The engine cannot generate a solution that is different from the solutions it already has.

MaxDemoIterations = 14

No license is set, and the run stopped at 50 iterations. Call SetLicense(String).

Returns:

termination reason

SetTerminationReason

public void SetTerminationReason(int reason)

Sets the termination reason. Internal OptTek use only.