Package com.opttek.optquest

Class COptQuestUserControlledOptimization

java.lang.Object
com.opttek.optquest.COptQuestUserControlledOptimization
public class COptQuestUserControlledOptimization extends Object
The COptQuestUserControlledOptimization class searches for solutions to problems using a 'black box' approach. It incorporates metaheuristics to guide its search algorithms toward better solutions. This approach remembers which solutions worked well and recombines them into new, better solutions. The simplest optimization problem contains decision variables, an objective function and the goal of the optimization (to either minimize or maximize)

  • Constructor Details

    • COptQuestUserControlledOptimization

      public COptQuestUserControlledOptimization()
      The default constructor. The license ID must be set by calling SetLicenseID(int).

    • COptQuestUserControlledOptimization

      public COptQuestUserControlledOptimization(String license)
      Constructor that accepts the license ID as input.
      Parameters:
      license - - the license ID assigned by OptTek Systems, Inc.

    • COptQuestUserControlledOptimization

      public COptQuestUserControlledOptimization(COptQuestSearchParameters search)
      Constructor that uses your customized search parameters. Users should not modify the search parameters unless they have been directed to make changes by OptTek Systems, Inc.

  • Method Details

    • SetCustomMetadata

      public void SetCustomMetadata(String key, Object value)
      For advanced users only. Contact OptTek Systems, Inc.

    • BeginOptimization

      public void BeginOptimization() throws COptQuestException
      Call BeginOptimization() defining variables, constraints and an objective. OptQuest will validate the model and begin solution generation. If there is an error in the model, a COptQuestException will be thrown.
      Throws:
      COptQuestException - if a problem is encountered

    • GetNextSolution

      public COptQuestSolution GetNextSolution() throws COptQuestException
      Call this method to get the next solution for evaluation. If solutions cannot be generated, null is returned. This may happen if all solutions can be enumerated and they have all been returned, or if the model is tightly constrained and OptQuest cannot generate new solutions.
      Returns:
      - a solution to be evaluated or null if no solutions can be created.
      Throws:
      COptQuestException - if a problem is encountered

    • ReturnEvaluatedSolution

      public COptQuestSolution ReturnEvaluatedSolution(COptQuestSolution solution) throws COptQuestException
      Call when a COptQuestSolution has completed evaluation. All COptQuestUserControlledVariables and COptQuestSingleObjectives should have values set.
      Parameters:
      solution - completed solution
      Throws:
      COptQuestException - if a problem is encountered

    • EndOptimization

      public void EndOptimization()
      Call this method when you no longer want to get solutions for evaluation.

    • EvaluateMetamodel

      public void EvaluateMetamodel(COptQuestSolution sol) throws COptQuestException
      Evaluates a solution at an arbitrary location in the domain based on the metamodel construcsted with BuildMetaModel()
      Parameters:
      sol - A COptQuestSolution with the inputs set. The metamodel will be used to estimate the value of the metrics and will be returned in-place in the solution that was passed in.
      Throws:
      COptQuestException - if a problem is encountered

    • GetCompletedSolutions

      public List<COptQuestSolution> GetCompletedSolutions()
      Use this method to update UI components of your application. It will return a list of solutions that have completed evaluation since the last time this method was called.
      Returns:
      - list of solutions that have completed evaluation.

    • GetAllSolutions

      public List<COptQuestSolution> GetAllSolutions()
      Returns:
      - list of solutions that have completed evaluation.

    • GetVersion

      public static String GetVersion()
      Returns the version number of the OptQuest Engine.
      Returns:
      the version number as a string.

    • RunSerialReplications

      public void RunSerialReplications(boolean onOff)
      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.
      Parameters:
      onOff - - if true, replications of a solution are run serially. If false, replications of a solution are run in parallel. The default value is to run replications in parallel.

    • RunRepeatableEvaluations

      public void RunRepeatableEvaluations(boolean onOff)
      If you are running OptQuest with multiple evaluators (you have called SetEvaluate()) the optimization results may vary across multiple runs of the same optimization. The generation of new solutions is dependent on the solutions available to OptQuest. In the default case, OptQuest generates new solutions as evaluations complete. If you require repeatable results, OptQuest will wait for all evaluators to complete and then process the solutions in iteration order. If the number of solutions is not a multiple of the number of evaluators, the last solutions may not be repeatable. For example, if the number of evaluators is 7 and you run 55 iterations, iterations 1 - 49 will be repeatable. Solutions 50 - 55 may not be. By default, OptQuest does not guarantee repeatable results with multiple evaluators.
      Parameters:
      onOff - - true if you want OptQuest to produce repeatable results across each run of the optimization, false if it is OK for results to vary across each run.

    • SetEvaluate

      public void SetEvaluate(int numberOfParallelEvaluators) throws COptQuestException
      The input parameter identifies the number of parallel evaluations that will be performed by the user. This should correspond to the number of processors/computer available for evaluation. During optimization, OptQuest will provide this many COptQuestSolutions at a time.
      OptQuest defaults to a single evaluator, so this method is only needed if more than one evaluator is desired. In most cases with parallel evaluators, this method is called once. In an environment with a dynamic number of available evaluators, the SetEvaluate(int) method may be called more than once during the optimization process to add additional evaluators. Evaluators cannot be removed once they have been added.
      Parameters:
      numberOfParallelEvaluators - number of parallel evaluators
      Throws:
      COptQuestException - if you call this method with less than one or greater than 5000 evaluators or if you attempt to remove evaluators

    • SetRandomSeed

      public void SetRandomSeed(int seed)
      Allows the random seed to be modified. The random seed is used in solution generation so modifying the seed can change the set of solutions.
      Parameters:
      seed - value to be used as the random seed.

    • StopOnSuccessfulMILP

      public void StopOnSuccessfulMILP(boolean stop)
      When this is set to true, the optimization stops as soon as it finds an optimal solution in the case that the optimization is a mixed integer linear program (MILP).

    • SetAutoStopByCycles

      public void SetAutoStopByCycles(boolean stop)
      Sets the auto stop by optimization cycles option. If the input parameter is true, auto stop by optimization cycles is turned on. The default is auto stop by optimization cycles is turned off. Auto stop is not available if running additional optimizations. AUTOSTOPCYCLES - defaults to 2 When automatic stop by optimization cycles is set, the optimization will stop when the number of specified auto stop cycles is reached. OptQuest works through a combination of techniques at finer levels of numerical precision to find the best solution. It will cycle through these techniques repeatedly as the search continues. This parameter limits the number of times OptQuest cycles through these techniques.
      Parameters:
      stop - true if auto stop by optimization cycles is to be used. False if it is not to be used.

    • SetAutoStopByPercentImprovement

      public void SetAutoStopByPercentImprovement(boolean stop)
      Sets the auto stop by percent improvement option. If the input parameter is true, auto stop by percent improvement is turned on. The default is auto stop by percent improvement is turned off. This auto stop option is only applicable to single objective problems. Auto stop is not available if running additional optimizations. AUTOSTOPNUMSOLUTIONS - defaults to 500 AUTOSTOPPERCENTIMPROVE - defaults to 0.01 When automatic stop by percent improvement is set, the optimization will stop when AUTOSTOPNUMSOLUTIONS are explored without a cumulative improvement of AUTOSTOPPERCENTIMPROVE during that time. Improvement is relative percent improvement based on the best and worst feasible objective values encountered.
      Parameters:
      stop - true if auto stop by percent improvement is to be used. False if it is not to be used.

    • SetAutoStopCycles

      public void SetAutoStopCycles(int frequency)
      Sets the autoStopFrequency - defaults to 2, OptQuest works through a combination of techniques at finer levels of numerical precision to find the best solution. It will cycle through these techniques repeatedly as the search continues. This parameter limits the number of times OptQuest cycles through these techniques if autoStop is turned on.
      Parameters:
      frequency - the number of times OptQuest cycles through its search techniques

    • SetAutoStopNumberSolutions

      public void SetAutoStopNumberSolutions(int numberSolutions)
      Sets the autoStopNumberSolutions - defaults to 500 If autoStop is turned on, autoStopNumberSolutions and autoStopPercentImprovement work together to stop the OptQuest search if autoStopNumberSolutions are explored without a cumulative improvement of autoStopPercentImprovement during that time.
      Parameters:
      numberSolutions - stop if this number of solutions is explored without making the specified improvement

    • SetAutoStopPercentImprove

      public void SetAutoStopPercentImprove(double percentImprove)
      Sets the autoStopPercentImprovement - defaults to 0.01 If autoStop is turned on, autoStopNumberSolutions and autoStopPercentImprovement work together to stop the OptQuest search if autoStopNumberSolutions are explored without a cumulative improvement of greater than autoStopPercentImprovement during that time.
      Parameters:
      percentImprove - stop if the autoStopNumberSolutions is explored without making more than this amount of improvement, allowed values are 0.0 through 0.2

    • SetMaximumTime

      public void SetMaximumTime(int NumberOfSeconds)
      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 NumberOfSeconds.
      Parameters:
      NumberOfSeconds - maximum number of seconds

    • SetName

      public void SetName(String name)
      Assigns a name to the optimization problem.

    • GetName

      public String GetName()
      Returns the name assigned to the optimization object

    • GetNumberOfCompletedIterations

      public int GetNumberOfCompletedIterations()
      Returns the number of solutions that have been evaluated. The count includes feasible solutions, infeasible solutions and rejected solutions.

    • AddVariable

      public void AddVariable(COptQuestVariable variable) throws COptQuestException
      Adds the variable defined by the input parameter to the optimization. If the user is naming variables, the name must be unique, and it cannot be an OptQuest keyword such as a math function name.
      Throws:
      COptQuestException - if a problem is encountered

    • AddSelectionGroup

      public void AddSelectionGroup(COptQuestSelectionGroup group)
      Adds a Selection Group to the optimization. Selection groups allow a variable that can be turned "off" which indicates that other variables will not be used in the evaluation.
      Parameters:
      group - the selection group to add

    • AddExchangeableGroup

      public void AddExchangeableGroup(COptQuestExchangeableGroup group)
      Adds a Exchangeable Group to the optimization. Variables in the group are identical if they have the same value and can be swapped.
      Parameters:
      group - the selection group to add

    • AddObjective

      public void AddObjective(COptQuestObjective objective) throws COptQuestException
      Adds the objective defined by the input parameter to the optimization problem.
      Parameters:
      objective - the objective to add
      Throws:
      COptQuestException - if an objective has already been defined

    • GetObjective

      public COptQuestObjective GetObjective()
      Returns the COptQuestObjective object added by the AddObjective() method

    • AddConstraint

      public void AddConstraint(COptQuestStringConstraint constraint) throws COptQuestException
      Adds the string constraint defined by the input parameter to the optimization. If an optimization problem contains multiple constraints, the constraints are ANDed together. If a solution is feasible, it satisfies every constraint in the optimization.
      Parameters:
      constraint - the constraint to add
      Throws:
      COptQuestException - if the string expression is empty.

    • AddSuggestedSolution

      public void AddSuggestedSolution(COptQuestSolution suggSol)
      The input solution is added to the set of suggested solutions. If the optimization has not started, the suggested solution will be evaluated first If the optimization is running, the suggested solution will be one of the next solutions to be evaluated. To create a suggested solution, call CreateSolution(). Use the SetVariableValue(COptQuestVariable, double) method to set a value for each decision variable. Note: All decision variables must be added to the optimization problem before adding a suggested solution. Note: If multiple suggested solutions are added they will be returned for evaluation in reverse order (last in, first out). Note: If multiple suggested solutions are added, OptQuest may return additional solutions for evaluation between the suggested solutions specified.
      Parameters:
      suggSol - the suggested solution to add

    • AddEvaluatedSolution

      public void AddEvaluatedSolution(COptQuestSolution evalSol)

    • AddRequiredSolution

      public void AddRequiredSolution(COptQuestSolution reqSol)

    • GetEmptySolution

      public COptQuestSolution GetEmptySolution() throws COptQuestException
      Throws:
      COptQuestException

    • AddPermutationGroup

      public void AddPermutationGroup(COptQuestPermutationGroup group)
      Adds the permutation group defined by the input parameter to the optimization problem.
      Parameters:
      group - the permutation group to add

    • SetGenerateNewSolutions

      public void SetGenerateNewSolutions(boolean onOff)
      If you only want OptQuest to call Evaluate() with suggested solutions, call SetGenerateNewSolutions(false). The default condition is to call Evaluate() with all suggested solutions and then with OptQuest generated solutions.

    • CheckOptimization

      public void CheckOptimization() throws COptQuestException
      Use this method to check an optimization for errors. A COptQuestException is thrown if an error is found. The exception identifies the type of error.
      Throws:
      COptQuestException - if a problem is encountered

    • SetLicenseID

      public void SetLicenseID(String license)
      Used to set the license ID. License IDs are assigned by OptTek Systems, Inc.
      Parameters:
      license - - license id

    • SetUseReplications

      public void SetUseReplications(boolean Value)
      Use to turn on the general replication algorithm. Your Evaluate() method will be called to evaluate each replication of a solution.

    • GetUseReplications

      public boolean GetUseReplications()
      Returns true if general replication processing is turned on. Returns false if it is not.
      Returns:
      true if general replication processing is turned on.

    • SetMinimumReplications

      public void SetMinimumReplications(int minimum) throws COptQuestException
      Sets the minimum number of replications to be run when running general replication. The default is 2 replication and the minimum value allowed is 2.
      Parameters:
      minimum - the minimum number of replications to be run before stopping replication processing.
      Throws:
      COptQuestException - if replication value is less than 2

    • GetMinimumReplications

      public int GetMinimumReplications()
      Returns the minimum number of replications set by the call to SetMinimumReplications().
      Returns:
      the minimum number of replications to be run before stopping.

    • SetMaximumReplications

      public void SetMaximumReplications(int maximum)
      Sets the maximum number of replications to be run when running general replication. If you are running with confidence type 1 or 2, you can set the maximum to -1 which means we will run replications until the confidence criteria is met.
      Parameters:
      maximum - the maximum number of replications to be run before stopping replication processing.

    • GetMaximumReplications

      public int GetMaximumReplications()
      Returns the maximum number of replications set by the call to SetMaximumReplications().
      Returns:
      the maximum number of replications to be run

    • SetHeatMapMinimumReplications

      public void SetHeatMapMinimumReplications(int minimum) throws COptQuestException
      Sets the minimum number of replications to be run when running a HeatMap optimization. The default is 1.
      Parameters:
      minimum - the minimum number of replications to be run before stopping replication processing in HeatMap mode
      Throws:
      COptQuestException - if value provided is less than 1

    • GetHeatMapMinimumReplications

      public int GetHeatMapMinimumReplications()
      Returns the minimum number of replications set by the call to SetHeatMapMinimumReplications().
      Returns:
      the minimum number of replications to be run before stopping.

    • SetHeatMapMaximumReplications

      public void SetHeatMapMaximumReplications(int maximum) throws COptQuestException
      Sets the maximum number of replications to be run when running a HeatMap optimization. The default is 1.
      Parameters:
      maximum - the maximum number of replications to be run before stopping replication processing.
      Throws:
      COptQuestException - if value provided is less than 1

    • GetHeatMapMaximumReplications

      public int GetHeatMapMaximumReplications()
      Returns the maximum number of replications set by the call to SetMaximumReplications().
      Returns:
      the maximum number of replications to be run

    • LogSetup

      public void LogSetup(String logFilePath) throws IOException
      LogSetup() logs calls to the COptQuestOptimization class in an xml formatted file. This is used for debugging optimization setup problems.
      Parameters:
      logFilePath - path to a file that will contain the logging info
      Throws:
      IOException - if there is a problem with the file path

    • CloseLogSetupFile

      public void CloseLogSetupFile()
      Closes the xml nodes in the log setup file and then closes the file. Use in conjunction with LogSetup() to have a properly formatted XML file.

    • LogSolutions

      public void LogSolutions(String logFilePath) throws IOException
      LogSolutions() logs all solutions in a csv formatted file. This is used for debugging solution generation.
      Parameters:
      logFilePath - path to a file that will contain the solution log
      Throws:
      IOException - if there is a problem with the file path

    • CloseSolutionLog

      public void CloseSolutionLog()

    • GetVariable

      public COptQuestVariable GetVariable(String Name)
      Given a variable name, return the COptQuestVariable object.
      Parameters:
      Name - variable name
      Returns:
      COptQuestVariable object with that name

    • GetVariables

      public ArrayList<COptQuestVariable> GetVariables()
      Returns an array of all variables that have been added to the optimization using the AddVariable()method.
      Returns:
      array of COptQuestVariable objects

    • GetNumberOfStringConstraints

      public int GetNumberOfStringConstraints()
      Returns the number of COptQuestStringConstraint objects added to the optimization.
      Returns:
      number of COptQuestStringConstraint objects

    • GetStringConstraint

      public COptQuestStringConstraint GetStringConstraint(int index)
      Returns the string constraint at the index specified by the input parameter.
      Parameters:
      index - index of the constraint
      Returns:
      the string constraint at the specified index

    • GetBestSolution

      public COptQuestSolution GetBestSolution()
      Returns the solution that has the best objective value. Returns null if no best solution exists.
      Returns:
      the best solution

    • GetNthBestSolution

      public COptQuestSolution GetNthBestSolution(int nth)
      Returns the nth best solution where solutions are ordered from best to worst based on the objective value. If the input parameter is 1, the best solution is returned, If the input parameter is 2, the second-best solution etc. If the nth best solution doesn't exist, null is returned.
      Parameters:
      nth - - 1 based number of the solution to return
      Returns:
      the solution that produced the Nth best objective value

    • GetIterationSolution

      public COptQuestSolution GetIterationSolution(int iteration)
      Returns the solution that was generated at the iteration specified by the input parameter. Returns null if the solution doesn't exist.

    • GetNumberOfFeasibleSolutions

      public int GetNumberOfFeasibleSolutions()
      Returns the number of solutions that satisfied all linear and non-linear constraints.

    • GetNumberOfInfeasibleSolutions

      public int GetNumberOfInfeasibleSolutions()
      Returns the number of solutions that violated a non-linear constraint.

    • GetNumberOfRejectedSolutions

      public int GetNumberOfRejectedSolutions()
      Returns the number of solutions that were rejected by calling COptQuestSolution.RejectSolution();

    • IsEnumerable

      public boolean IsEnumerable()
      Returns true if all variables in the optimization problem can be enumerated. Note that if the combination of the variables results in a large solution space, OptQuest will not enumerate all possible solutions.
      Returns:
      true if all the variables in the problem can be enumerated.

    • CreateSolution

      public COptQuestSolution CreateSolution() throws COptQuestException
      Creates a new solution that can be used to create a suggested solution. The variable values are initialized to the last suggested value or the midpoint of the lower and upper bound if no solution has been suggested.
      Returns:
      a new solution
      Throws:
      COptQuestException - if a problem is encountered

    • GetPatternFrontier

      public ArrayList<COptQuestSolution> GetPatternFrontier()
      Provides all solutions in the current pattern frontier in no particular order.
      Returns:
      An unsorted ArrayList<COptQuestSolution> of solutions on the pattern frontier.

    • GetPatternFrontier

      public ArrayList<COptQuestSolution> GetPatternFrontier(COptQuestSingleObjective obj) throws COptQuestException
      Provides all solutions in the current pattern frontier sorted by the specified objective.
      Parameters:
      obj - the objective to sort by
      Returns:
      A sorted ArrayList<COptQuestSolution> of solutions on the pattern frontier.
      Throws:
      COptQuestException - if the objective is not found

    • GetTerminationReason

      public int GetTerminationReason()
      Returns the reason the optimization terminated.
      TERM_NOTSTARTED=0
      The optimization has not been started.
      TERM_RUNNING=1
      The optimization is still running.
      TERM_LP=3
      The optimization was solved using an Linear/Integer/Mixed Integer Program.
      TERM_AUTOSTOP=4
      The optimization stopped due to the Auto Stop feature
      TERM_OPTIMALFOUND=5
      The optimal solution was found.
      TERM_MAXITERATIONS=6
      The optimization stopped when the maximum number of iterations was reached.
      TERM_MAXTIME=7
      The optimization stopped when the maximum time was reached.
      TERM_USERSTOPPED=8
      The optimization was stopped by the user.
      TERM_EXCEPTION=10
      The optimization stopped due to an exception.
      TERM_INFEASIBLE=12
      There are no solutions that satisfy the constraints.
      TERM_CANNOTGENERATE=13
      New (different) solutions cannot be generated.
      Returns:
      termination reason

    • SetTerminationReason

      public void SetTerminationReason(int reason)