Class ScenarioSet

java.lang.Object
ca.spatial.patchworks.ScenarioSet

public class ScenarioSet extends Object
This class provides a framework to automate the processing of scenarios.

A ScenarioSet is a container for descriptions of how to run scenarios. In addition the class contains parameters that describe the simulation environment. When the class is instantiated you must specify

  • The rate of improvement to be used to determine when to end the simulation
  • The number of iterations to wait between calculations of the rate of improvement
  • The frequency of 'checkpoints' that will save the simulation state during long running simulations.
  • A flag that specifies if the scenario reports should be zipped up into a zip file after the simulation has completed.

Scenario definitions can be added to the set using the addScenario(java.lang.String, java.lang.String, ca.spatial.patchworks.TargetDescription[]) method. This method requires a folder name, a textual description and a list of target settings. The description string can include HTML formatting tags, and can be composed of lists or tables. The target settings are specified as an array of TargetDescription objects. See the TargetDescription documentation for more details.

Once a ScenarioSet has been created and populated, use the run() method to immediately run the selected scenarios in sequence. Prior to executing the run() method, the showMenu() can be used to verify and alter the scenarios that are selected to be run.

The steps involved in the execution of a scenario depend on the activity mode that has been set for that scenario. The default activity mode is ScenarioDescription.Activity.SOLVE, and when executed the following steps will take place:

  • If the cancelTreatments flag is set, all currently applied mangement treatments are canceled (see ScenarioDescription.setCancelBefore(boolean)).
  • All targets are turned off.
  • The apply() method of each TargetDescription added for this scenario is called in sequence, causing the simulation environment to be adjusted accordingly. The descriptive string for the scenario and all descriptive strings from the targets are inserted into the main index report for the scenario.
  • The simulation is run until the convergence requirements are met. Checkpoints of scenario state may be taken periodically depending on the checkpoint interval.
  • When the convergence criteria has been met the scheduler is paused and the scenario reports are saved.
  • If the makeZip flag is set, all scenario reports are saved into a zip archive file. (see ScenarioDescription.setMakeZipFile(boolean)).
The execution sequence appropriate for the activity mode is carried out for each selected scenario. See the ScenarioDescription.Activity documentation for more information about activity modes.

If an error occurs while initializing a scenario then that scenario will be skipped. In this case a dialog will be presented that asks if the remaining scenarios should be skipped as well.

Here is a sample usage of the ScenarioSet class:

 setHarvestLow = new TargetDescription("Set harvest low", "HarvestLevel") {
    public void apply() {
      setMinimum("product.Yield.conifer", 100000);
      setActive("product.Yield.conifer", true, true, false);
    }
   };
   
 s = new ScenarioSet(false, 0.05, 400000, 5000000, true);
 s.addScenario("Basic", "Basic scenario with only low harvest target",
               new TargetDescription[] {setHarvestLow});

 if (s.showMenu())
     s.run();
 
This code snippet defines a target, creates a ScenarioSet, adds one scenario that uses the target, presents a menu of options for review, and if the scenario is selected and the 'Ok' button is been pressed it will execute the scenario.

ScenarioSet scripts may start off simple, but as the analysis project progresses many scenario alternatives may be added, including complex user defined meta-heuristic (see ScenarioChangeListener). It is a good practise to modularize the script files by putting the TargetDescription definitions in one file, and the ScenarioSet definition in another.

See Also:
ScenarioDescription, TargetDescription, ScenarioChangeListener
  • Constructor Details

    • ScenarioSet

      public ScenarioSet(double improvement, int iterations, int checkPointCount, boolean makeZipFile, ConvergenceSpec[] specs, ChangeListenerFactory factory)
      Create a ScenarioSet container that will manage the list of what to run.

      The ScenarioSet accepts the following arguments:

      Parameters:
      improvement - A double value that specifies the convergance criteria. The value will be tested against the percent decrease in the objective function. If the amount of decrease is less than the convergence criteria then the simulation will stop.
      iterations - An integer that specifies the number of iterations to run before checking the convergence criteria.
      checkPointCount - An integer that specifies the number of iterations to pass before saving the scenario data files. This will periodically save out the files so that the program may be restarted from a partial solution. This can guard against catastrohic loss from a power failure or network outage during very long running simulations. The checkpoint count is only checked when the convergence criteria is tested, so this value should be a mutiple of the iterations parameter.
      makeZipFile - A boolean that specifies if the reports should automatically be saved together into a ZIP file.
      specs - An array of sub-target criteria.
      factory - An object reference to a factory object that can create a default change listener for all scenarios.
    • ScenarioSet

      public ScenarioSet(double improvement, int iterations, int checkPointCount, boolean makeZipFile, String[] patterns, double[] values, ChangeListenerFactory factory)
      Create a ScenarioSet container that will manage the list of what to run.

      The ScenarioSet accepts the following arguments:

      Parameters:
      improvement - A double value that specifies the convergance criteria. The value will be tested against the percent decrease in the objective function. If the amount of decrease is less than the convergence criteria then the simulation will stop.
      iterations - An integer that specifies the number of iterations to run before checking the convergence criteria.
      checkPointCount - An integer that specifies the number of iterations to pass before saving the scenario data files. This will periodically save out the files so that the program may be restarted from a partial solution. This can guard against catastrohic loss from a power failure or network outage during very long running simulations. The checkpoint count is only checked when the convergence criteria is tested, so this value should be a mutiple of the iterations parameter.
      makeZipFile - A boolean that specifies if the reports should automatically be saved together into a ZIP file.
      factory - An object reference to a factory object that can create a default change listener for all scenarios.
    • ScenarioSet

      public ScenarioSet(double improvement, int iterations, int checkPointCount, boolean makeZipFile)
      This is a convenience constructor that does not specify the sub-target convergence criteria or listener factory. It is equivalent to
        new ScenarioSet(improvement, iterations, checkPointCount, 
                        makeZipFile, null, null);
       
    • ScenarioSet

      public ScenarioSet()
      This is a convenience constructor that uses default parameters. It is equivalent to
        new ScenarioSet(0.05, 400000, 5000000, true, null, null);
       
  • Method Details

    • getActivity

      public ScenarioDescription.Activity getActivity()
      Get the default activity for the scenarios in this ScenarioSet.
    • setActivity

      public ScenarioSet setActivity(ScenarioDescription.Activity activity)
      Set the default activity to be applied to Scenarios added to this ScenarioSet.
    • getImprovement

      public double getImprovement()
      Get the value of the convergence criteria.
    • setImprovement

      public ScenarioSet setImprovement(double improve)
      Set the value of the convergence criteria. This will determine when the simulation will stop running. See the Control.waitForProgress(int, double) method for a description of this parameter.
    • getIterations

      public int getIterations()
      Get the value of the number of iterations to wait between testing the convergence criteria.
    • setIterations

      public ScenarioSet setIterations(int count)
      Set the value of the number of iterations to wait between testing the convergence criteria. Every time this count is reached the scenario manager will test convergence and call the scenario life cycle methods ScenarioChangeListener.evaluateBefore() and ScenarioChangeListener.evaluateAfter(boolean, ca.spatial.patchworks.ScenarioMonitor).

      See the Control.waitForProgress(int, double) method for a description of this parameter.

    • getCheckPointCount

      public int getCheckPointCount()
      Get the number of iterations between saving the core scenario files.
    • setCheckPointCount

      public ScenarioSet setCheckPointCount(int count)
      Set the number of iterations to pass before saving the core scenario files. This routine is useful when conducting a long-running simulation. The scripts will periodically save the core files, and in the case of a power failure or other interuption the simulation can be restarted from the last save point.
      Parameters:
      count - The number of iterations between checkpoints. If this value is zero or less then checkpointing will not occur. The checkpoint count is only checked when the convergence criteria is tested, so this value should be a mutiple of the iterations parameter.
    • getMakeZipFile

      public boolean getMakeZipFile()
      Return a flag that indicates if the scenario output should be copied into a zip archive file.
    • setMakeZipFile

      public ScenarioSet setMakeZipFile(boolean mode)
      Specify if all scenario reports should be copied into a zip file after the scenario has completed. The zip file will have the same name as the scenario folder.
    • getAllowDuplicates

      public boolean getAllowDuplicates()
      Returns a flag indicating if duplicate categories are allowed in sets of targets.
    • setAllowDuplicates

      public ScenarioSet setAllowDuplicates(boolean mode)
      Specify if duplicate categories are allowed in sets of targets. If false, then an exception will occur when more than one target in a scenario specifies the same category name.
    • getChangeListenerFactory

      public ChangeListenerFactory getChangeListenerFactory()
      Return the default ChangeListenerFactory.
    • setChangeListenerFactory

      public ScenarioSet setChangeListenerFactory(ChangeListenerFactory factory)
      Set the default ChangeListenerFactory.
    • setCriteria

      public ScenarioSet setCriteria(String[] patterns, double[] values)
    • getCriteria

      public ConvergenceSpec[] getCriteria()
    • getScenarioCount

      public int getScenarioCount()
      Get a count of the number of defined scenarios
    • getScenario

      public ScenarioDescription getScenario(String key)
      Get a scenario for the specified label
    • getScenarios

      public ScenarioDescription[] getScenarios()
      Return a list of scenarios
    • getScenarioNames

      public Set<String> getScenarioNames()
      Return the scenario names
    • clearTargets

      public static void clearTargets()
      Clear all targets. This will deactivate all targets.
    • addScenario

      public ScenarioDescription addScenario(String label, String description, TargetDescription[] targets)
      Add a scenario to the set.
      Parameters:
      label - The name to be used when saving the scenario.
      description - Descriptive text that will be added to the main report table of contents.
      targets - The list of TargetDescriptions that will be applied before starting the scenario.
    • addScenario

      public ScenarioDescription addScenario(String label, String description, TargetDescription[] targets, ScenarioDescription.Activity activity, double improve, int iterations, int checkpointCount, boolean makeZipfile, ConvergenceSpec[] specs, ChangeListenerFactory factory)
    • addScenario

      public ScenarioDescription addScenario(String label, String description, TargetDescription[] targets, ScenarioDescription.Activity activity, double improve, int iterations, int checkpointCount, boolean makeZipfile, String[] patterns, double[] values, ChangeListenerFactory factory)
    • addScenario

      public ScenarioDescription addScenario(ScenarioDescription description)
    • setSelected

      public void setSelected(String label, boolean mode)
      Set the selected status of a pre-defined scenario.
      Parameters:
      label - The name of the scenario.
      mode - The selected status to apply.
    • showMenu

      public boolean showMenu()
      Show a menu containing the simulation parameters.
      Returns:
      Returns a true value if the Ok button is pressed, or false if the cancel button is pressed.
    • run

      public void run()
      Run the selected simulations.
    • getScenarioSummary

      public String getScenarioSummary(ScenarioDescription sd)
      Get an HTML formated list of the targets that have been set for the specified scenario.
      Returns:
      An HTML formated string that describes the targets that are set in the requested scenario.