Package com.opttek.optquest

Class OptQuestSolution

java.lang.Object
com.opttek.optquest.OptQuestSolution
public class OptQuestSolution extends Object
A solution of an OptQuestModel. It holds a value for every input, output and expression variable of the model. From it you can also read the iteration number, the replication number, whether the solution is feasible, and whether it met its confidence requirement.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    final int
    id
     

  • Constructor Summary

    Constructors
    Constructor
    Description
    OptQuestSolution()
    Internal OptTek use only.
    OptQuestSolution(OptQuestModel opt, int id, com.opttek.optquest.COptQuestSolution csol)
    Internal OptTek use only.
    OptQuestSolution(OptQuestModel opt, com.opttek.optquest.COptQuestSolution csol)
    Internal OptTek use only.

  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    AddEvaluated()
    Supplies a solution to the engine whose outputs have already been calculated.
    boolean
    AddRequired()
    Adds a solution that the engine evaluates with the exact values that you give.
    boolean
    AddSuggested()
    Supplies a "warm start" solution to the engine.
    boolean
    Evaluate()
    Computes the expression variables, the constraint feasibility and the objective values of a solution whose input and output values you have set.
    List<String>
    GetInputNames()
    Returns the names of the model's input variables, in the order they were declared.
    int
    GetIteration()
    Returns the iteration number that OptQuest assigned to the solution.
    int
    GetNumberOfCompletedReplications()
    Returns the number of evaluated replications of a solution.
    List<String>
    GetOutputNames()
    Returns the names of the model's output variables, in the order they were declared.
    int
    GetReplication()
    Returns the replication number for this solution.
    double
    GetValue(String name)
    Returns the value associated with the named Variable, Objective, or Constraint.
    boolean
    HasMetConfidence()
    Returns true if the solution has met confidence requirements when being evaluated in variable replication mode.
    boolean
    IsComplete()
    Returns true if all of the replications for a solution have been completed.
    boolean
    IsEvaluated()
    Returns true if the solution is a suggested solution with input values and output values.
    boolean
    IsFeasible()
    Returns true if the solution satisfies all constraints.
    boolean
    IsValid()
    Call this method when using the Manual Optimization pattern to verify CreateSolution() has returned a valid solution.
    boolean
    Predict()
    Requests that the outputs of a solution be predicted using an internally built proxy model.
    int
    Reject()
    Rejects an OptQuestSolution, signaling to the optimization engine that it could not be evaluated due to external constraints or simulation failures.
    boolean
    SetValue(String name, double value)
    Sets the value of a named input or output variable in an OptQuestSolution.
    int
    Submit()
    Submits an evaluated solution back to the Optimization Engine.
    boolean
    Update()
    Updates the internal state of a solution after it has been returned (Submitted or Rejected) to the Optimization engine.

    Methods inherited from class java.lang.Object

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

  • Field Details

    • id

      public final int id

  • Constructor Details

    • OptQuestSolution

      public OptQuestSolution()
      Internal OptTek use only.

    • OptQuestSolution

      public OptQuestSolution(OptQuestModel opt, com.opttek.optquest.COptQuestSolution csol)
      Internal OptTek use only.

    • OptQuestSolution

      public OptQuestSolution(OptQuestModel opt, int id, com.opttek.optquest.COptQuestSolution csol)
      Internal OptTek use only.

  • Method Details

    • IsValid

      public boolean IsValid()
      Call this method when using the Manual Optimization pattern to verify CreateSolution() has returned a valid solution. If the optimization engine cannot generate a new solution (e.g., the feasible space is too small or has been exhaustively searched), it will return an empty solution with no valid values.
      Returns:
      true if the solution has been successfully created, false if the model could not create a solution.

    • GetIteration

      public int GetIteration()
      Returns the iteration number that OptQuest assigned to the solution.
      Returns:
      - returns the iteration number OptQuest assigned to the solution. This is the unique number assigned to a solution when it is first created and sent out for evaluation. Multiple replications can have the same iteration number.

    • GetReplication

      public int GetReplication()
      Returns the replication number for this solution. This is the unique number assigned to a replication of a solution when it is first created and sent out for evaluation. The replication number will be between 1 and the maximum number of replications.
      Returns:
      Returns the replication number OptQuest assigned to the solution.

    • GetNumberOfCompletedReplications

      public int GetNumberOfCompletedReplications()
      Returns the number of evaluated replications of a solution.

      For a solution that OptQuestModel.CreateSolution() issued and that you did not yet submit or reject, the count is the number of replications of the same iteration that are complete: GetReplication() minus 1. Without replications, it is 0.

      Returns:
      - number of evaluated replications.

    • IsEvaluated

      public boolean IsEvaluated()
      Returns true if the solution is a suggested solution with input values and output values. The solution was added using the AddEvaluated() method which is used to supply solutions to the engine where the outputs have already been calculated.
      Returns:
      true if the suggested solution was evaluated.

    • IsComplete

      public boolean IsComplete()
      Returns true if all of the replications for a solution have been completed.

      With replications, the engine calls a monitor once for each replication. In the monitor, GetValue(String) on an output or an objective returns the combined value of the replications that are complete so far. To stop on the combined value of all the replications of a trial solution, test IsComplete() before you compare the value, for example return !sol.IsComplete() || profit < 1000;.

      For a solution that OptQuestModel.CreateSolution() issued and that you did not yet submit or reject, IsComplete() returns false.

      Returns:
      true if the solution has completed evaluation.

    • IsFeasible

      public boolean IsFeasible()
      Returns true if the solution satisfies all constraints.
      Returns:
      true if the solution satisfies all constraints.

    • HasMetConfidence

      public boolean HasMetConfidence()
      Returns true if the solution has met confidence requirements when being evaluated in variable replication mode. If confidence was set on multiple objectives, the method will return true if all objectives met the confidence criteria.
      Returns:
      true if the solution met the replication confidence testing criteria

    • GetValue

      public double GetValue(String name) throws com.opttek.optquest.COptQuestException
      Returns the value associated with the named Variable, Objective, or Constraint. If the requested value is not available in the solution, NaN is returned.

      Additional parameters may be passed in as part of the name to retrieve specific information:

      Outputs: if a solution has multiple replications, requesting the output by its name returns the aggregated value. To retrieve the value of a specific replication, add a ";#" to the name. For example, sol.GetValue("output") will retrieve the aggregated value of the variable named "output", sol.GetValue("output;2") will retrieve the value of the variable named "output" for replication #2.

      Objectives: if a solution has multiple replications, requesting the objective by its name returns the aggregated value. To retrieve the value of a specific replication, add a ";#" to the name. For example, sol.GetValue("objective") will retrieve the aggregated value of the variable named "objective", sol.GetValue("objective;3") will retrieve the value of the objective named "objective" for replication #3.

      Objectives: if variable replications are being used, OptQuest tracks the width of the confidence interval for each objective. To retrieve that width, append ";cw". For example sol.GetValue("objective;cw") will return the confidence width of the objective named "objective".

      Constraints: If only the constraint name is requested, the feasibility of the constraint is returned. Additionally, constraints have two sides to the expression, the left and right, and may have multiple clauses. Each side of the constraint expression may be retrieved using a ";LHS;#" or ";RHS;#" suffix, where LHS is for the left side of the equation, and RHS is for the right side, and the number is the clause number, which is usually 1 except for complex constraints with "or" conditions.

      For example, consider this constraint named constraint1, input1-input2 < 3 or input2+input3 > 5-input2 sol.GetValue("constraint1") will return 1.0 if that constraint is feasible in the solution, 0.0 if it is infeasible sol.GetValue("constraint1;LHS;1") will return the value of input1-input2 sol.GetValue("constraint1;RHS;1") will return 3 sol.GetValue("constraint1;LHS;2") will return the value of input2+input3 sol.GetValue("constraint1;RHS;2") will return 5-input2

      Parameters:
      name - - name of the object
      Returns:
      - A double value representing the requested information, NaN if the information is not available.
      Throws:
      com.opttek.optquest.COptQuestException - - An exception is thrown if there was an error retrieving the value.

    • SetValue

      public boolean SetValue(String name, double value) throws com.opttek.optquest.COptQuestException
      Sets the value of a named input or output variable in an OptQuestSolution. This is primarily used to assign values to output variables during solution evaluation. However, clients can also override input variable values if needed. This method is also used to set input values for suggested solutions.
      Parameters:
      name - - name of the input or output variable
      value - - value assigned to the input or output
      Returns:
      true if the call was successful, false if there was an error such as a variable with the input name does not exist.
      Throws:
      com.opttek.optquest.COptQuestException - - An exception is thrown if there was an error setting the value.

    • Submit

      public int Submit() throws com.opttek.optquest.COptQuestException
      Submits an evaluated solution back to the Optimization Engine. Only used for Manual Optimization loops.

      Call it only on a solution that OptQuestModel.CreateSolution() returned. Java does not refuse a solution that the engine did not issue, such as a solution from OptQuestModel.GetEmptySolution() or OptQuestModel.CopySolution(OptQuestSolution), so never call Submit() on such a solution. In the other languages, the call fails with ERROR BAD SOLUTION ID.

      Returns:
      - Returns the total number of evaluated solutions, including this one, or -1 if the solution was not taken. Zero is one of those counts, so test for a negative answer rather than a false one. The count can be useful to track how many solutions have been processed including other concurrent threads.
      Throws:
      com.opttek.optquest.COptQuestException - - An exception is thrown if there was an error.

    • Reject

      public int Reject() throws com.opttek.optquest.COptQuestException
      Rejects an OptQuestSolution, signaling to the optimization engine that it could not be evaluated due to external constraints or simulation failures. Only used for Manual Optimization loops. It indicates the solution has no valid output values. The engine marks the solution infeasible and does not compute its objectives, so GetValue() returns NaN for an objective. An expression variable that depends on an output or on the variable names of a manifold variable is not computed, and GetValue() returns 0 for it. The input values, and any output values that you set, stay as they were.

      Call it only on a solution that OptQuestModel.CreateSolution() returned. Java does not refuse a solution that the engine did not issue, such as a solution from OptQuestModel.GetEmptySolution() or OptQuestModel.CopySolution(OptQuestSolution), so never call Reject() on such a solution. In the other languages, the call fails with ERROR BAD SOLUTION ID.

      Returns:
      - Returns the total number of evaluated solutions, including this one, or -1 if the solution was not taken, read the same way as Submit()'s answer. The count can be useful to track how many solutions have been processed including other concurrent threads.
      Throws:
      com.opttek.optquest.COptQuestException - - An exception is thrown if there was an error.

    • Predict

      public boolean Predict() throws com.opttek.optquest.COptQuestException
      Requests that the outputs of a solution be predicted using an internally built proxy model.

      The prediction uses every solution the model holds when the call is made, so a solution may be predicted, more solutions collected, and another prediction made that accounts for them. This may be called while a run is in progress, including from inside an evaluator. The proxy model is only rebuilt when the set of solutions has changed, so predicting many points against an unchanged set is inexpensive. Solutions added after the model has reached its stopping criteria are not taken up, because the run is finished.

      Returns:
      -true if the call was successful, false if there was an error.
      Throws:
      com.opttek.optquest.COptQuestException - - An exception is thrown if there was an error.

    • Evaluate

      public boolean Evaluate() throws com.opttek.optquest.COptQuestException
      Computes the expression variables, the constraint feasibility and the objective values of a solution whose input and output values you have set. For the callback that runs your simulation in a managed run, see IOptQuestEvaluator.Evaluate(OptQuestSolution).

      The solution is not given to the engine: it does not become an iteration, and it does not change the search. Use it with a solution from OptQuestModel.GetEmptySolution() or OptQuestModel.CopySolution(OptQuestSolution).

      Returns:
      -true if the call was successful, false if there was an error.
      Throws:
      com.opttek.optquest.COptQuestException - - An exception is thrown if there was an error.

    • Update

      public boolean Update()
      Updates the internal state of a solution after it has been returned (Submitted or Rejected) to the Optimization engine. Only used for Manual Optimization loops.
      Returns:
      -true if the call was successful, false if there was an error.

    • AddSuggested

      public boolean AddSuggested() throws com.opttek.optquest.COptQuestException
      Supplies a "warm start" solution to the engine. If certain solutions are known to be good, before starting an optimization, suggesting them as starting points can speed convergence. The caller supplies values for the Input Variables. OptQuest will evaluate suggested solutions before generating new solutions. A suggested solution will be mapped to the feasible space if the inputs supplied are infeasible. The engine can also change the values of a manifold variable, so that they are inside the set of the variable.
      Returns:
      - true if the call was successful, false if there was an error.
      Throws:
      com.opttek.optquest.COptQuestException - - An exception is thrown if there was an error.

    • AddEvaluated

      public boolean AddEvaluated() throws com.opttek.optquest.COptQuestException
      Supplies a solution to the engine whose outputs have already been calculated. If previous simulations have been run and the output values have been computed for specific inputs, sending them in as evaluated solutions can save computational effort. The caller supplies values for the input and output variables. OptQuest will process evaluated solutions before generating new solutions. The engine uses the values of a manifold variable in an evaluated solution as given.
      Returns:
      - true if the call was successful, false if there was an error.
      Throws:
      com.opttek.optquest.COptQuestException - - An exception is thrown if there was an error.

    • AddRequired

      public boolean AddRequired() throws com.opttek.optquest.COptQuestException
      Adds a solution that the engine evaluates with the exact values that you give. Use it when the engine must evaluate a specific point, for example your current operating plan. The caller supplies values for the Input Variables. OptQuest will evaluate required solutions before generating new solutions. A required solution will not be mapped to the feasible space if the inputs supplied are infeasible. The engine uses the values of a manifold variable in a required solution as given, and your evaluator receives them unchanged.
      Returns:
      - true if the call was successful, false if there was an error.
      Throws:
      com.opttek.optquest.COptQuestException - - An exception is thrown if there was an error.

    • GetInputNames

      public List<String> GetInputNames()
      Returns the names of the model's input variables, in the order they were declared. Every name returned resolves through GetValue(String), so you can use the pair to read every value of a solution without keeping your own list of names: 
       for (String name : sol.GetInputNames()) {
     System.out.println(name + " = " + sol.GetValue(name));
 }

      Most variables appear under the name they were added with. For a permutation and the structured variable types, the engine generates element names joined by '@': AddPermutationVariable("g", {"a","b"}) adds g@a and g@b; AddVectorVariable("v", 3, 0, 1) adds v@1 through v@3; AddAngleVariable("dir", 0, 360) adds dir@theta. The base name itself is not an addressable value and is not returned.

      Random variables (AddNormalRandomVariable and the other random variable methods) are reported here too. The engine writes them, and draws each one again for every replication. The caller never supplies one, so they are inputs to the caller's evaluation. Read them like any other input; do not write them back with SetValue(String, double) when seeding a suggested solution. Unlike the rest of this list, a random variable name also accepts the ";<replication>" suffix described on GetOutputNames(), because the engine stores a value per replication for it.

      Variables added with AddOutputVariable, expression variables, the elements of AddOutputVectorVariable and its matrix and n-dimensional counterparts, and the coefficient, contribution and confidence values of a policy sequence variable are reported by GetOutputNames() instead. The two lists never overlap.

      Objectives and constraints also resolve through GetValue(String), but neither this method nor GetOutputNames() returns them. Read them with the names that you gave to OptQuestModel.AddObjective(String, String, String) and OptQuestModel.AddConstraint(String, String).

      Returns:
      a fresh list of input names, empty if this solution is not valid

    • GetOutputNames

      public List<String> GetOutputNames()
      Returns the names of the model's output variables, in the order they were declared. Every name returned resolves through GetValue(String), and may be suffixed with ";<replication>" to read a single replication.

      The list contains two kinds of name:

      • Names that your evaluator must write: the variables added with AddOutputVariable, and the elements of AddOutputVectorVariable, AddOutputMatrixVariable and AddOutputNDVariable.
      • Names that the engine computes: expression variables, and the coefficient, contribution and confidence names of a policy sequence variable (<name>@<featureName>, <name>@<featureName>@contribution, <name>@<featureName>@confidence and <name>@<itemName>@confidence). Do not write these names.

      The engine does not mark which kind a name is. To get the names that your evaluator must write, remove from this list the names of your expression variables and every name that starts with the base name of a policy sequence variable and '@'.

      The values of the decision variables, and the random variables that the engine draws again for each replication, are reported by GetInputNames() instead. Objectives and constraints also resolve through GetValue(String), but neither this method nor GetInputNames() returns them. Read them with the names that you gave to AddObjective and AddConstraint.

      Returns:
      a fresh list of output names, empty if this solution is not valid