About the Script Strategy Mode

You can add a script to your Custom strategy to drive the design plan.

The script is similar to the Script component (see Script Component). The global variables table in the Custom strategy script editor contains all the component’s parameters plus the standard runtime objects, allowing you to insert references to these items into your script. As a result, your Custom strategy scripts can do most anything that the Script component scripts do. In addition, the global variable table contains several items that you can use to specifically perform design searches and process the results of these searches.

Design Plan

This global variable type represents an object that encapsulates an exploration technique instance. Each instance in the currently defined set of exploration technique instances appears as a variable of this type in the global variable table. The name of each variable is the same as the technique instance name, except that all the spaces in each name are replaced with underscores. Objects of this type can be used to interact with the technique instance via the following methods:

  • public void run(); This method runs the encapsulated technique instance in the environment of the latest design point. Clicking the button inverts a reference to the global variable for the currently selected technique instance into the script, with the variable’s run() method already invoked upon that variable.
  • public DesignPlan getPlan(); This method returns the internal object representing the encapsulated technique instance. You can invoke methods on this object to reconfigure the technique instance before running it. The available methods depend on the technique type. The APIs for design plans are the same as the APIs for the components:

Single Run

This global variable type represents an object that encapsulates the Single Run pseudo-technique. Similar to the Design Plan type it implements a run() method. One global variable of this type, named Single_Run, is always present in the global variables table. Clicking the button when Single Run is selected inserts a reference to this global variable into the script, with the variable’s run() method already invoked upon that variable.

DesignPointAPI

This global variable type represents an object that provides a suite of methods that can be used to inspect and manipulate design points during execution of the strategy script. One global variable of this type, named DesignPointAPI, is always present in the global variables table. A reference to this object must be inserted into the script for each method that you want to invoke.

Each design plan imposes search criteria on some of the component’s variables. Some of these criteria can be used to grade each design point as being better, indifferent, or worse, according to your explorations goals. The component itself also imposes search criteria on some of the component’s variables. These criteria are shown on the Formulation tab in the Design Gateway. After execution, the Runtime GatewayHistory tab shows the design plans’ grading as the values of special variables (e.g., objective, feasibility, etc.), and it shows the formulation’s grading as the coloration applied to the rows of the design points.

For most plan-based component types (e.g., DOE, Optimization, etc.), there is only one design plan, and Isight forces the two sets of search criteria to be identical (so both forms of display give the same information). For the Exploration component, there can be various numbers of design plans, each with its own search criteria. Therefore, those criteria and the component formulation must remain distinct, and the information on the History tab must be interpreted carefully. If your script runs more than one design plan, or runs a design plan more than once, the values of the special variables (e.g., objective, feasibility, etc.) will show only how each plan has graded its own run (additional special variables are added by the Custom strategy to record which plans have evaluated which runs). The row coloration on the History tab will show how the runs are graded according to the component’s overall search criteria. You can use these API methods to specify what these overall search criteria are:

  • public void gradeRunsByComponentFormulation(); This method configures the custom strategy run grader to use the formulation (design variables, objectives, etc.) as configured on this strategy’s Exploration component. After this call is made, all evaluated design points are graded by those criteria. If a request is made to grade a stored run, it will be graded by those criteria. This will continue unless and until an API call is made to use another formulation.

    Note: The Custom strategy is configured to grade according to the component formulation before it begins execution by default.

  • public void gradeRunsByPlanFormulation(DesignPlan plan); This method configures the custom strategy run grader to use the formulation (design variables, objectives, etc.) as configured on the given design plan. After this call is made, all evaluated design points are graded by those criteria. If a request is made to grade a stored run, it will be graded by those criteria. This will continue unless and until an API call is made to use another formulation. If no plan is given, the last chosen formulation will continue to be applied.
  • public void gradeRunsByRunningPlanFormulation(); This method configures the custom strategy run grader to use the formulation (design variables, objectives, etc.) as configured on each design plan just before that plan begins execution. After this call is made, all evaluated design points continue to be graded according to the last chosen formulation unless and until a design plan is run. From then on, each time a design plan is to be run, the run grader is reconfigured to grade according to that plan’s formulation, then the plan is run. This will continue unless and until an API call is made to use a fixed formulation.

After the design plan has finished executing, the “best” point evaluated by the design plan can be inspected and manipulated using the following API methods:

  • public Variable getBestRunVariable(String parmName); This method returns the named variable from the Context of the best run found since execution began or since the latest call to discardBestRun(). If there is no current best run, null is returned.

    Note: If the value of any variable returned by this method is changed, the recorded best run grade will not be the grade of the altered design point.

  • public int getBestRunGrade(); This method returns the run grade (one of the GradeableRun.GRADE_XXX constant values) of the best run found since execution began or since the latest call to discardBestRun().
  • public boolean isBestRunFeasible(); This method checks the run grade of the best run found since execution began or since the latest call to discardBestRun(). It returns true if that grade is feasible (i.e., one of the GradeableRun.GRADE_FEASIBLE_XXX constant values).
  • public double getBestRunObjective(); This method returns the objective value of the best run found since execution began or since the latest call to discardBestRun(). If the best run is infeasible, this will be the penalized objective. If no design point has yet been evaluated, Double.POSITIVE_INFINITY is returned.
  • public void discardBestRun(); This method discards the best run found since execution began or since the latest call to discardBestRun(). The next run will be graded as if it were the first run. If this method is not called between technique instances, the first run made by the second technique is compared to the best run made by the first. This may be acceptable if the two technique instances impose sufficiently compatible grading criteria.
  • public void setToBestRun(); This method takes the best run found since execution began or since the latest call to discardBestRun() and resets the values of the current runtime Context to the values of that run. Any subsequent technique instances impose sufficiently compatible grading criteria.

You may find it useful to save arbitrary design points encountered during strategy execution, inspect them, manipulate them, and use them as starting points for further exploration.

The following APIs allows you to record and retrieve arbitrary runs:

  • public boolean hasStoredRun(String key); This method checks if there is a Context stored in the runtime environment’s blackboard under the given key.
  • public Variable getStoredRunVariable(String key, String parmName); This method returns the named variable from the Context stored in the runtime environment’s blackboard under the given key. If there is no Context stored under that key, null is returned. If the Context has no variable of that name, null is returned.
  • public int getStoredRunGrade(String key, boolean compareToRuns); This method returns the run grade (one of the GradeableRun.GRADE_XXX constant values) of the Context stored in the runtime environment’s blackboard under the given key. This run grade is calculated using the grading criteria of the most recently run technique instance. If the argument compareToRuns is true, the Context is graded relative to the current best run (therefore, it could be “better”). If the argument compareToRuns is false, it is graded in isolation (therefore, it can be only “feasible” or “infeasible”).
  • public boolean isStoredRunFeasible(String key); This method checks the run grade of the Context stored in the runtime environment’s blackboard under the given key. This run grade is calculated using the grading criteria of the most recently run technique instance. It returns true if that grade is feasible (i.e., one of the GradeableRun.GRADE_FEASIBLE_XXX constant values).
  • public double getStoredRunObjective(String key); This method returns the objective value of the Context stored in the runtime environment’s blackboard under the given key. This objective is calculated using the grading criteria of the most recently run technique instance.
  • public void makeStoredRun(String key, Context run); This method takes the given Context and stores it in the runtime environment’s blackboard under the given key.
  • public void discardStoredRun(String key); This method removes the Context, if any, stored in the runtime environment’s blackboard under the given key.
  • public void setToStoredRun(String key); This method takes the Context stored in the runtime environment’s blackboard under the given key and resets the values of the current runtime Context to the values of that Context. If there is no Context stored under that key, the current runtime Context remains unaltered. Any subsequent technique instance executions will begin with that design point.

Note: The blackboard is also accessible at runtime in the Subflow Prologue and Subflow Epilogue (see Defining Prologue/Epilogue Information for more information).