Class ScenarioDescription
- All Implemented Interfaces:
Selectable<ScenarioDescription>
,Comparable<ScenarioDescription>
ScenarioSet
. The scenario description records the scenario
name, a description of its purpose, a list of TargetDescription
objects that characterize the parameters of the scenario, and other
runtime parameters.
ScenarioDescription objects may be used as stand-alone objects, but
most often they are used as components of a ScenarioSet
, and
in most cases ScenarioDescription objects are created by adding values
to an existing ScenarioSet
. For example,
s = new ScenarioSet(improve, iterations, checkPointCount, makeZip, subtargetPrefix, subtargetImprove, factory); s.addScenario("scenarios/C5_Spatial2", "The Spatial2 builds on Spatial1 and adds harvest patches.", new TargetDescription[] {useVQO(1e12, true), ndyGS(10000,0,true), noDisturbancePatch, harvestPatches(0.0001,true), deliveredHarvest(1,true), evenFlowMill(1000, true), roadBudget(1,true), useCompartAccess} );In the above code a ScenarioSet is created with a set of default runtime parameters. A scenario is added specifying a name label, a title, and a set of
TargetDescription
objects that describe
target settings. All other required parameters for the ScenarioDescription
are inherited from the ScenarioSet defaults.
The essential parameters to a ScenarioDescription are the name label and
the array of TargetDescription
objects. The name label is used
as the folder name when the scenario results are saved out. The
TargetDescription objects describe model pre-conditions, the targets
to be activated and the target values to be set. See the
TargetDescription
documentation for more information about
creating and using TargetDescription objects.
Scenarios have several modes of operation.
The default activity is ScenarioDescription.Activity.SOLVE
, but this may be overriden
with the setActivity(ca.spatial.patchworks.ScenarioDescription.Activity)
method.
The ScenarioDescription.Activity.SOLVE
mode which starts from the initial condition,
applies all targets, cues the ScenarioChangeListener
tp deactivate
flow targets for the initial iterations, iterates until convergence, and
saves out results. See the ScenarioDescription.Activity
class for a description of
each available mode.
The ScenarioDescription class uses a fluent interface for customization. Methods may be chained together to modify default values and to set values that are not otherwise available using the convenience methods. For example,
s.addScenario("scenarios/C5_Spatial2", "The Spatial2 builds on Spatial1 and adds harvest patches.", new TargetDescription[] {useVQO(1e12, true), ndyGS(10000,0,true), noDisturbancePatch, harvestPatches(0.0001,true), deliveredHarvest(1,true), evenFlowMill(1000, true), roadBudget(1,true), useCompartAccess} ).setIterations(300000) .setImprovement(0.001) .setActivity(ScenarioDescription.Activity.CONTINUE);will add a scenario to the ScenarioSet, and will override the iteration, improvement values and activity values.
When run under the supervision of a ScenarioSet
a scenario can be
initialized with target values, run until the specified convergence
criteria are met, and the report values are saved out. An optional
ScenarioChangeListener
object can be used to apply more precise
control over the scenario life cycle.
A scenario specific argument may be attached to a ScenarioDescription
using the setUserArg(java.lang.Object)
method. This value may be retrieved
by the ScenarioChangeListener
using the getUserArg()
method.
The value of this argument may be any object reference, such as a
String or an array of other objects.
See the
ScenarioChangeListener documentation for an example of how this may be used.
- See Also:
ScenarioSet
,TargetDescription
,ScenarioChangeListener
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic class
The activity value controls the operations that take place when the scenario is run. -
Constructor Summary
ConstructorsConstructorDescriptionScenarioDescription(String label, String description, TargetDescription[] targets, ScenarioDescription.Activity activity, double improve, int iterations, int checkpointCount, boolean makeZipfile, ConvergenceSpec[] specs, ChangeListenerFactory factory)
Create this scenario with the specified parameters. -
Method Summary
Modifier and TypeMethodDescriptionstatic void
CallTarget.setActive(boolean)
with a value of true for each of the Target objects that are in the targets array.static void
activate(TargetDescription[] targetDescriptions)
CallTargetDescription.activate(java.lang.Object)
with a value of true for each of the TargetDecription objects in the list.static void
activateAccount(String regex)
CallTarget.setActive(boolean)
with a value of true for each of the Target objects that have account names that match to the regular expression string.void
activateCategory(String regex)
CallTargetDescription.activate(java.lang.Object)
with a value of true for each of the TargetDescription objects that have category values that match to the regular expression string.void
analyze(ChangeListenerFactory factory, boolean wait)
Start the scheduler and run until convergence.void
analyzeWithListener(ScenarioChangeListener sdc, boolean wait)
Start the scheduler and run until convergence.Apply the list of targets.boolean
canSave()
Check if the scenario can be saved to the specified locationstatic void
Clear all targets.int
Determine the sorting order of scenario descriptions.static Target[]
deactivateAccount(String regex)
CallTarget.setActive(boolean)
with a value of false for each of the Target objects that have account names that match to the regular expression string and are currently acitve.deactivateCategory(String regex)
CallTargetDescription.deactivate(java.lang.Object)
with a value of false for each of the TargetDescription objects that have category values that match to the regular expression string.Get the default setting of theScenarioDescription.Activity
code for this scenario.boolean
int
Get the number of iterations that should occur between saving the simulation state data.Return the descriptive text for this scenario.double
The value of the objective function convergence criteriaint
A count of the number of iterations that should occur before the objective function is tested against the convergence criteria.getLabel()
The name of the scenarioboolean
A flag to indicate if the simulation results should be archived into a zip file after the simulation has completed.getTargetForCategory(String cat)
Get a list of target description objects that will be applied when this scenario is run.Get the value of the userArg.boolean
A flag that indicates if this scenario is selected for execution.static ConvergenceSpec[]
makeCriteria(String[] patterns, double[] values)
Set the extended convergence criteria to be used for this scenario.void
makeZip()
Pack up a zip file from the reports saved from this scenario.void
printError(String message)
void
printMessage(String message)
void
reloadScenario(boolean ignoreWarnings)
Reload all of the files in a saved scenariovoid
Run this scenario.void
runScenario(ScenarioDescription.Activity activity)
Run this scenario using the operations implied by theScenarioDescription.Activity
code..setActivity(ScenarioDescription.Activity activity)
Set the type of activity that should occur when the simulation is run.setCancelBefore(boolean mode)
Set a flag to indicate if the current set of treatments should be cancelled before the simulation is started.Set aScenarioChangeListener
that will be used to control the simulation environment when therunScenario()
method is called.setCheckpointCount(int count)
Get the number of iterations that should occur between saving the simulation state data.setCriteria(ConvergenceSpec[] specs)
setImprovement(double improve)
Set the value of the objective function convergence criteria.setIterations(int count)
Set the number of iterations that should occur before the objective function is tested against the convergence criteria.setMakeZipFile(boolean mode)
Set a flag to indicate if the simulation results should be archived into a zip file after the simulation has completed.setSelected(boolean mode)
Set a flag to indicate that this scenario is selected for execution.setUserArg(Object userArg)
Set the value of the userArg.toString()
-
Constructor Details
-
ScenarioDescription
public ScenarioDescription(String label, String description, TargetDescription[] targets, ScenarioDescription.Activity activity, double improve, int iterations, int checkpointCount, boolean makeZipfile, ConvergenceSpec[] specs, ChangeListenerFactory factory)Create this scenario with the specified parameters.- Parameters:
label
- The name to be given to this scenario.description
- Text that describes the purpose of the scenario. This text will be recorded as meta-data.targets
- A list of targets that should be applied to this scenario.activity
- AnScenarioDescription.Activity
code to indicate the default treatment for this scenario.improve
- 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 ofConvergenceSpec
factory
- A reference to aChangeListenerFactory
object that will be called when convergence is being tested.
-
-
Method Details
-
runScenario
Run this scenario. The set of operations that take place depend on the value of the activity code (seesetActivity(ca.spatial.patchworks.ScenarioDescription.Activity)
). If the iteration count is set to zero then the scenario will not run, and the reports will be immediately saved.- Throws:
InterruptedException
-
runScenario
Run this scenario using the operations implied by theScenarioDescription.Activity
code..- Throws:
InterruptedException
-
analyzeWithListener
public void analyzeWithListener(ScenarioChangeListener sdc, boolean wait) throws InterruptedExceptionStart the scheduler and run until convergence. Use the provided listener object to react to life cycle events. If theScenarioChangeListener
object is null then life cycle events will not be dispatched.- Parameters:
sdc
- A reference to a ScenarioChangeListener object to handle life cycle events. May be null in which case life cycle events are ignored.wait
- Indicate if the scenario manager should wait and not return until the scenario is complete. If the flag is true, then do not return until the scenario is over. If false, then return immediately.- Throws:
InterruptedException
-
analyze
Start the scheduler and run until convergence. If a factory has been provided then create and set a custom listener object. The custom listener object will be called by theScenarioDescription.DefaultScenarioChangeListener
at the appropriate times.- Parameters:
factory
- A reference to aChangeListenerFactory
object. This object will be used to create a listener to handle life cycle events. May be null in which case no custom life cycle event handler will be added, and only theScenarioDescription.DefaultScenarioChangeListener
processing will occur.wait
- Indicate if the scenario manager should wait and not return until the scenario is complete. If the flag is true, then do not return until the scenario is over. If false, then return immediately.- Throws:
InterruptedException
-
reloadScenario
public void reloadScenario(boolean ignoreWarnings)Reload all of the files in a saved scenario- Parameters:
ignoreWarnings
- to ignore warnings about missing files and continue loading what is available.
-
makeZip
public void makeZip()Pack up a zip file from the reports saved from this scenario. The reports must already be saved for this to work. -
activateCategory
CallTargetDescription.activate(java.lang.Object)
with a value of true for each of the TargetDescription objects that have category values that match to the regular expression string. For example, the following activates TargetDescriptions that contain "Flow" or "Patch" in the category name.sd.activateCategory(".*(Flow|Patch).*");
- Parameters:
regex
- the regular expression string to use to determine the TargetDescription objects to activate.- See Also:
String.matches(java.lang.String)
-
deactivateCategory
CallTargetDescription.deactivate(java.lang.Object)
with a value of false for each of the TargetDescription objects that have category values that match to the regular expression string. For example, the following activates TargetDescriptions that contain "Flow" or "Patch" in the category name.sd.deactivateCategory(".*(Flow|Patch).*");
- Parameters:
regex
- the regular expression string to use to determine the TargetDescription objects to deactivate.- See Also:
String.matches(java.lang.String)
-
activate
CallTargetDescription.activate(java.lang.Object)
with a value of true for each of the TargetDecription objects in the list.- Parameters:
targetDescriptions
- the array of TargetDescription objects to activate.
-
activateAccount
CallTarget.setActive(boolean)
with a value of true for each of the Target objects that have account names that match to the regular expression string. For example, the following activates targets having names that start with "patch" or "ratio".sd.activateAccount("^(patch|ratio).*");
- Parameters:
regex
- the regular expression string to use to determine the Target objects to activate.- See Also:
String.matches(java.lang.String)
-
activate
CallTarget.setActive(boolean)
with a value of true for each of the Target objects that are in the targets array.For example, the following deactivates targets having names that start with "patch" or "ratio" and collects the selected targets int the savedTargets array. After some intermediate processing steps these targets are then reactivated using the activateAccounts method.
savedTargets = sd.deactivateTarget("^(patch|ratio).*"); // other processing steps... // and later on... sd.activate(savedTargets);
- Parameters:
targets
- an array of references for the Targets objects that are to be activated.
-
deactivateAccount
CallTarget.setActive(boolean)
with a value of false for each of the Target objects that have account names that match to the regular expression string and are currently acitve. For example, the following deactivates targets having names that start with "patch" or "ratio".savedTargets = sd.deactivateAccount("^(patch|ratio).*");
This method returns an array of references to the Target objects that have been deactivated. This list will only include targets with matching names that were active when the deactivate command was run.
To reactivate the array of Targets that is returned from this method use the
activate(Target[])
method.- Parameters:
regex
- the regular expression string to use to determine the Target objects to deactivate.- Returns:
- an array of the targets that were deactivated (names matched and were active).
- See Also:
String.matches(java.lang.String)
-
isSelected
public boolean isSelected()A flag that indicates if this scenario is selected for execution.- Specified by:
isSelected
in interfaceSelectable<ScenarioDescription>
-
setSelected
Set a flag to indicate that this scenario is selected for execution.- Specified by:
setSelected
in interfaceSelectable<ScenarioDescription>
-
getLabel
The name of the scenario -
getTargets
Get a list of target description objects that will be applied when this scenario is run. -
getDescription
Return the descriptive text for this scenario. -
getImprovement
public double getImprovement()The value of the objective function convergence criteria -
setImprovement
Set the value of the objective function convergence criteria. If the value is set to a negative number then stop the simulation after the number of viable iterations has met the iteration count. If the improvement count is less than zero then theScenarioChangeListener.evaluateBefore()
andScenarioChangeListener.evaluateAfter(boolean, ca.spatial.patchworks.ScenarioMonitor)
life cycle routines will not be invoked. -
getUserArg
Get the value of the userArg. This is an arbitrary object that can be specified for each description -
setUserArg
Set the value of the userArg. This is an arbitrary object that can be specified for each description.- Parameters:
userArg
- Any arbirary object reference. This value may subsequently be retrieved and used within theScenarioChangeListener
or elsewhere.- Returns:
- A reference to the ScenarioDescription object.
-
printMessage
-
printError
-
getActivity
Get the default setting of theScenarioDescription.Activity
code for this scenario. -
setActivity
Set the type of activity that should occur when the simulation is run. The values can be one ofScenarioDescription.Activity.SOLVE
,ScenarioDescription.Activity.SOLVE_NODEACTIVATE
,ScenarioDescription.Activity.RESUME
,ScenarioDescription.Activity.CONTINUE
ScenarioDescription.Activity.REFRESH
orScenarioDescription.Activity.TARGETS
.- Parameters:
activity
- the activity that should be run
-
getCancelBefore
public boolean getCancelBefore() -
setCancelBefore
Set a flag to indicate if the current set of treatments should be cancelled before the simulation is started.- Parameters:
mode
- If the mode value is true, then all scheduled treatments are cancelled before the simulation is started.
-
getIterations
public int getIterations()A count of the number of iterations that should occur before the objective function is tested against the convergence criteria. -
setIterations
Set the number of iterations that should occur before the objective function is tested against the convergence criteria. -
getCheckpointCount
public int getCheckpointCount()Get the number of iterations that should occur between saving the simulation state data. Checkpoints will save the simulation data so that the model can be restarted from the save point. This can save time if the simulation is interrupted (for example, due to a power failure). -
setCheckpointCount
Get the number of iterations that should occur between saving the simulation state data. -
getMakeZipFile
public boolean getMakeZipFile()A flag to indicate if the simulation results should be archived into a zip file after the simulation has completed. -
setMakeZipFile
Set a flag to indicate if the simulation results should be archived into a zip file after the simulation has completed. -
setChangeListenerFactory
Set aScenarioChangeListener
that will be used to control the simulation environment when therunScenario()
method is called. -
getChangeListenerFactory
-
makeCriteria
Set the extended convergence criteria to be used for this scenario. Each of the strings in the patterns array represent a regular expression that will be matched against target names. If this array is non-null, then the convergence testing mechanism will perform an extended analysis. Each target is matched against the patterns, and the change in value from one sampling point to the next is measured. The sum of change for each pattern is expressed as a percent, and compared to the corresponding number in the values array. If the amount of chage is greater than the value then the convergence criteria is not satisfied.- Parameters:
patterns
- An array of regular expression strings that will be matched against target names.values
- An array of convergence criteria values.
-
setCriteria
-
getCriteria
-
applyTargets
Apply the list of targets. -
getTargetForCategory
-
clearTargets
public static void clearTargets()Clear all targets. -
compareTo
Determine the sorting order of scenario descriptions. The rule is to sort in the order that scenarios are added to the set.- Specified by:
compareTo
in interfaceComparable<ScenarioDescription>
-
canSave
public boolean canSave()Check if the scenario can be saved to the specified location -
toString
-