Control (Patchworks v1.0 API Specification)

java.lang.Object
- ca.spatial.patchworks.Control

```
public class Control
extends Object
```
This class provides most of the user-visible controls into the Patchworks model. Some of the main functions that can be performed with this class include:
- Adding account to the model
- Getting references to modeling objects, such as Targets and AttributeStores
- Getting instances of specialized report objects
- Starting and pausing the solver
- Reloading results from previously saved scenarios
- Invoking specialized graphical user interfaces, such as the account or group explorers.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`void`	`addAccount(String group, String attribute, boolean sum, String account)` Deprecated.
`void`	`addAccount(String group, String attribute, String account)` Add a summary account to the model.
`void`	`addAccount(String group, String attribute, String account, double factor)` Add a summary account to the model.
`void`	`addAccount(String group, String attribute, String account, double[] factors)` Add a summary account to the model.
`void`	`addEdgeElement(String account, String attribute1, String attribute2, double factor)` Add an edge contrast specification to an edge target.
`void`	`addEdgeTarget(String account, Topology topology)` Create an edge target, using the specified topology to determine stand adjacency.
`void`	`addExclusiveAccount(String match, String account)` Add an exclusive account to the model.
`void`	`addExclusiveDependent(String exclusive, String choice, String source, String sink, double factor)` Add an exclusive dependent account to the model.
`void`	`addExclusiveDependent(String exclusive, String choice, String source, String sink, double[] factors)` Add an exclusive dependent account to the model.
`void`	`addFlowRatioAccount(String account, String input, FlowSpec flowPeriods, double ratioScale)` Add a flow ratio account to the model.
`void`	`addFlowRatioAccount(String account, String input, FlowSpec flowPeriods, double ratioScale, boolean annual)` Add a flow ratio account to the model.
`void`	`addFlowRatioAccount(String account, String input, int[] flowPeriods, double ratioScale)` Add a flow ratio account to the model.
`void`	`addFlowRatioAccount(String account, String input, int[] flowPeriods, double ratioScale, boolean annual)` Add a flow ratio account to the model.
`void`	`addFlowRatioAccount(String account, String input, int flowPeriod, boolean skipFirst)` Add a flow ratio account to the model.
`void`	`addFlowValueAccount(String account, String input, FlowSpec flowPeriods)` Add a flow value account to the model.
`void`	`addFlowValueAccount(String account, String input, int[] flowPeriods)` Add a flow value account to the model.
`void`	`addFlowValueAccount(String account, String input, int flowPeriod, boolean skipFirst)` Add a flow value account to the model.
`void`	`addGroupDistributionAccount(String account, String[] groupNames, double[] groupTotals)` Create a new GroupDistibutionAccount.
`void`	`addGroupDistributionSubAccount(String groupAccount, String subAccount, double min, double max)` Create a sub-account within a GroupDistributionAccount.
`void`	`addMetaAccount(String account, String[] components, double[] factors)` Add a meta account to the model.
`void`	`addMetaAccount(String account, String[] components, double[][] factors)` Add a meta account to the model.
`void`	`addNote(String details)` Add a note to the log file.
`void`	`addNote(String category, String details)` Add a note to the log file.
`void`	`addPatchTarget(String criteria, String label, double min, double max)` Add a patch target account to the model.
`void`	`addProgressListener(ObjectiveProgressReport listener)`
`void`	`addRatioAccount(String account, String numerator, String denominator)` Add a ratio account to the model.
`void`	`addRatioAccount(String account, String numerator, String denominator, double ratioScale)` Add a ratio account to the model.
`void`	`addRouteBuildAccount(String route, String account)` Add a route construction account to the model.
`void`	`addRouteBuildAccount(String route, String account, boolean sum)` Deprecated. Use `addRouteBuildAccount(String, String, double)` instead.
`void`	`addRouteBuildAccount(String route, String account, double factor)` Add a route construction account to the model.
`void`	`addRouteBuildAccount(String route, String account, double[] factors)` Add a route construction account to the model.
`void`	`addRouteHaulAccount(String route, String account)` Add a route hauling account to the model.
`void`	`addRouteHaulAccount(String route, String account, boolean sum)` Deprecated. Use `addRouteHaulAccount(String, String, double)` instead.
`void`	`addRouteHaulAccount(String route, String account, double factor)` Add a route hauling account to the model.
`void`	`addRouteHaulAccount(String route, String account, double[] factors)` Add a route hauling account to the model.
`void`	`addRouteProductAccount(String route, String account)` Add a route flow account to the model.
`void`	`addRouteProductAccount(String route, String account, boolean sum)` Deprecated. Use `addRouteProductAccount(String, String, double)` instead.
`void`	`addRouteProductAccount(String route, String account, double factor)` Add a route flow account to the model.
`void`	`addRouteProductAccount(String route, String account, double[] factors)` Add a route flow account to the model.
`void`	`addRouteRebuildAccount(String route, String account, double factor)` Add a route reactivation account to the model.
`void`	`addRouteRebuildAccount(String route, String account, double[] factors)` Add a route reactivation account to the model.
`void`	`addRouteRepairAccount(String route, String account)` Add a route maintenance account to the model.
`void`	`addRouteRepairAccount(String route, String account, boolean sum)` Deprecated. Use `addRouteRepairAccount(String, String, double)` instead.
`void`	`addRouteRepairAccount(String route, String account, double factor)` Add a route maintenance account to the model.
`void`	`addRouteRepairAccount(String route, String account, double[] factors)` Add a route maintenance account to the model.
`void`	`addTabulateAccount(String account, String input, int[] tabulatePeriods)` Add a tabulate value account to the model.
`void`	`calculateGroups(String expression)` Assign groups as determined by evaluating an expression.
`void`	`cancelTreatments()` Cancel all of the treatments for all blocks in the forest.
`void`	`cancelTreatments(String label)` Cancel all of the treatments for the block with the given label.
`void`	`cbmExport()` Display a wizard to collect parameters and run the CBM-CFS3 export tool.
`void`	`cbmExport(String[] classifiers, String histDist, String lastDist, String[] conSppList, String[] hwdSppList, String sppRegex, int evalYear, String output)` Export files that can be imported in to the CBM-CFS3 model.
`void`	`cbmExport(String[] classifiers, String histDist, String lastDist, String conYield, String hwdYield, String conLeadSpp, String hwdLeadSpp, int evalYear, String output)` Export files that can be imported in to the CBM-CFS3 model.
`void`	`close()` Release the structures that have been allocated for the simulation.
`void`	`duplicateAccount(String master, String child, double factor)` Dupliate the value of an account into another account.
`void`	`duplicateAccount(String master, String child, double[] factors)` Dupliate the value of an account into another account.
`AccessTableModel`	`getAccessTable()` Get a reference to the timing constraints table object.
`Actions`	`getActions()` Get a map containing actions that are known to the model.
`Set`	`getAttributeLabels()` Get a set object containing all of the attribute labels that have been loaded into the Patchworks model.
`GeoRelationalStore`	`getBlockTable()` Get a reference to the block table object.
`Object`	`getClientObject()`
`ComparisonWriter`	`getComparisonWriter()`
`ConversionFactors`	`getConversionFactors()` Get an object that contains the conversion factors used in this model.
`Vector<String>`	`getDestinationNames()` Get a sorted list of route destination names
`ArrayList<EventRecord>`	`getEvents(String id, String treatedManAreaExpr, String treatedUnmanAreaExpr)` Return a list of event records for the given row.
`Exclusive`	`getExclusiveAccount(String name)` Get an exclusive account by name.
`Vector<String>`	`getExclusiveAccountNames()` Get a sorted list of exclusive account names
`Report`	`getExclusiveAssignmentReport(String filename, String title, String exclusive)` Get an exclusive assignment report.
`Report`	`getExclusiveLockReport(String filename, String title, String exclusive)` Get an exclusive lock report.
`Set<String>`	`getGroups()` Return a set of all of the defined groups labels.
`long`	`getIteration()`
`static int`	`getMaximumEntries()` Get the maximum number of management entries within a stand.
`Report`	`getNetworkCostReport(String filename, String title)` Get a network cost report.
`GeoRelationalStore`	`getNetworkTable()` Get the network table containing the route shapes as well as cost and utilization data for every segment for every destination.
`double`	`getObjectiveValue(boolean details)` Compute the current objective value.
`Component`	`getPerformanceChart()` Get a performance strip chart viewer.
`ReportWriter`	`getReportWriter()`
`Report`	`getRouteCostReport(String filename, String title, String destination)` Get a route cost report.
`Report`	`getRouteReport(String filename, String title, String destination)` Get a route report.
`GeoRelationalStore`	`getRouteTable(String label)` Get a route table for a specified route.
`static Control`	`getSharedInstance()` Get a reference to the Control object.
`StandEventReport`	`getStandEventReport(String filename, String title, String treatedManAreaExpr, String treatedUnmanAreaExpr)` Create a Stand Dynamics report.
`String[]`	`getStrataColumns()` Get the names of the stratification columns
`Target`	`getTarget(String label)` Get a target by name.
`Set<String>`	`getTargetLabels()` Get a set of all target labels.
`Collection<Target>`	`getTargets()` Get all targets.
`AttributeStore`	`getTargetTable()` Get a reference to the target table.
`Component`	`getTargetView(String label)` Get a target viewer for a specified target.
`Report`	`getTimingConstraintsReport(String filename, String title)` Get a timing constraints report.
`ArrayList<String>`	`getTreatmentNames()`
`Component`	`getTreatmentView(String label)` Get a treatment viewer for a specified block.
`static void`	`identifyPatches(GeoRelationalStore store, Topology topology, String label, String reselect, int period, String output)` This method will identify patches within a spatial dataset.
`void`	`initialize(Task task)` Initialize the account values
`void`	`inputGroups(File file)` Load a group definition file.
`void`	`inputGroups(String filename)` Load a group definition file.
`void`	`inputRoute(String label, String filename)` Input a saved route file.
`Topology`	`inputTopology(File file, double distance)` Input a topology dataset related to the block dataset.
`Topology`	`inputTopology(String filename, double distance)`
`void`	`interrupt()` Send a signal to interrupt the scheduler.
`boolean`	`isSuspended()` Determine if the scheduler is suspended
`void`	`loadAvailable(String filename)` Load a saved file in to initialize block availability data.
`void`	`loadExclusive(String exclusive, String filename)` Load a saved file in to initialize exclusive account assignments.
`void`	`loadExclusiveLocks(String exclusive, String filename)` Load a saved file in to initialize exclusive account locks.
`void`	`loadSchedule(String filename)` Load a saved file in to initialize the schedule of treatments.
`void`	`loadSchedule(String filename, boolean cancelPrevious)` Load a saved file in to initialize the schedule of treatments.
`void`	`loadTargetStatus(String filename)` Load a saved file in to initialize target status data.
`void`	`loadTargetSummary(String filename)` Load a saved file in to initialize target summary data.
`void`	`makeDotFile(String filename)`
`void`	`makeDotFile(String filename, int width, int height, boolean simplify)`
`void`	`outputRoute(String label, String filename)` Save a route definition to a file.
`void`	`removeAccount(String group, String account)` Remove a summary account from the model.
`void`	`removeProgressListener(ObjectiveProgressReport listener)`
`void`	`resume()` Resume the scheduler from a suspended state.
`Topology`	`reuseOrLoadTopology(String filename, double distance, GeoRelationalStore store, String label)` Access a previously loaded topology file, or if not already loaded then input a topology dataset for an arbitrary spatial dataset.
`boolean`	`setBlockAvailable(int row, boolean[] values)` Set the available timings for all periods.
`void`	`setConversionFactors(String linearMapUnits, String linearReportUnits, double linearReportToMap, String areaMapUnits, String areaBlockUnits, double areaBlockToMap)` Set up the conversion factors that describe the spatial units.
`void`	`setInitialValue(String label, double value, int period)` Set an initial value for an account.
`static void`	`setMaximumEntries(int entries)` Set the maximum number of consecutive treatments that are allowed on any polygon.
`void`	`setPatchThreshold(String patch, double threshold)` Set a threshold on the criteria used to allow blocks to become a member of a patch.
`void`	`setRandomSeed(long seed)` Set the seed used by the random number generator within the scheduler.
`boolean`	`setTargetDiscountRate(String label, double rate)` Deprecated.
`boolean`	`setTargetLinear(String label, boolean value)` Deprecated.
`boolean`	`setTreatment(int index, String treatment, int year, boolean managed)` Apply a treatment to a block in a specific year
`void`	`setTreatmentAffinity(TreatmentAffinity[][] affinities)` Set the list of treatments that are allowed to be scheduled in the same planning period within the same bunch.
`void`	`showAccountExplorer()` Display the AccountExplorer viewer.
`void`	`showGroupExplorer()` Display the GroupExplorer viewer.
`void`	`suspend()` Suspend the sheduler.
`void`	`waitForIterations(int attempts)` This method will wait for a number of scheduling attempts to pass before returning to the caller.
`void`	`waitForProgress(int attempts, double percent)` This method will wait for the objective function to converge before returning to the caller.
`void`	`waitForProgress(int attempts, double percent, ConvergenceSpec[] specs, ScenarioChangeListener asd)` This method will wait for the objective function to converge before returning to the caller.
`void`	`waitForProgress(int attempts, double percent, String[] patterns, double[] values, ScenarioChangeListener asd)` Deprecated. It is recommended that scenario life cycle management should be handled using the `ScenarioSet`, `ScenarioDescription` and `ScenarioChangeListener` mechanism. These methods provide self-documentation and fine-grained customizable control over how scenarios are run, including the ability to monitor progress and alter simulation values.
`void`	`waitUntilInitialized()` Wait until the model is initialized.

Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

setConversionFactors

public void setConversionFactors(String linearMapUnits,
                                 String linearReportUnits,
                                 double linearReportToMap,
                                 String areaMapUnits,
                                 String areaBlockUnits,
                                 double areaBlockToMap)

Set up the conversion factors that describe the spatial units. Spatial units are used for linear measures (road lengths and distance to mill) and area measures (polygon area, patch sizes). The spatial units used in data sets are typically metres or feet, but in reporting these are typically kilometres or miles. Similarly, area units are typically reported in hectares or acres rather than square metres or square feet.

This method allows the specification of the unit labels to be used in reports, and the conversion factors that should be applied between mapping units and reporting units.

More importantly, this class specifies the relationship between the map units used in the block shape file, which would be used to compute topological relationships in map units, and the polygon areas loaded from the input matrix, which are commonly represented in hectares or acres. This conversion is required to properly support calculation of perimeter-to-area ratios.

The default conversion values are

Conversion factors
Factor	Meaning	Default value
linearMapUnits	The label to describe the map distance measure in the units of the spatial data set	"m"
linearReportUnits	The label to describe distance units as preferred for reporting	"Km"
linearReportToMap	A numeric factor that converts from linear reporting units to linear map units (e.g. kilometres to metres, or miles to feet)	1,000
areaMapUnits	The label to describe the map area measures in the units of the spatial data set	"m2"
areaBlockUnits	The label to describe area units as described in the input matrix	"ha"
areaBlockToMap	A numeric factor that converts from input matrix area units to area map units (e.g. hectares to m2, or acres to ft2)	10,000

The default values are equivalent to the following command:

 control.setConversionFactors("m"", "Km", 1000, "m2, "ha", 10000);

The values to use for typical American measures would be:

 control.setConversionFactors("ft", "miles", 5280, "ft2", "acres", 43560);

This method may only be executed in the context of the target initialization section of the PIN file. An error will occur if this command is encountered after the model has initialized.

getConversionFactors
```
public ConversionFactors getConversionFactors()
```
Get an object that contains the conversion factors used in this model.

setMaximumEntries
```
public static void setMaximumEntries(int entries)
```
Set the maximum number of consecutive treatments that are allowed on any polygon. The default value is 7. Increase this limit in case of long planning horizons or silvicultural treatments that have many mid-rotation treatments (selection or shelterwood).

Parameters:

entries - the maximum number of management entries within a stand over the management planning horizon.

getMaximumEntries
```
public static int getMaximumEntries()
```
Get the maximum number of management entries within a stand. This value will limit the number of treatments that may be allocated to any stand.

inputGroups
```
public void inputGroups(File file)
```
Load a group definition file. This method is invoked immediately. This method is only valid when called during the account resolution phase (usually in the Patchworks_TargetInit method in the PIN file).

inputGroups
```
public void inputGroups(String filename)
```
Load a group definition file. This method is invoked immediately. This method is only valid when called during the account resolution phase (usually in the Patchworks_TargetInit method in the PIN file).

calculateGroups
```
public void calculateGroups(String expression)
```
Assign groups as determined by evaluating an expression. The expression is evaluated for each record in the block shape file. If the result of the expression is not null or an empty string, then the resulting string value is used to assign the block to a group.

getGroups
```
public Set<String> getGroups()
```
Return a set of all of the defined groups labels.

inputTopology
```
public Topology inputTopology(File file,
                              double distance)
```
Input a topology dataset related to the block dataset.
This method may only be executed in the context of the target initialization section of the PIN file. The topology file is loaded as soon as the command is encountered.
The method will open the named file, load the topological relationships, and return a reference to the Topology structure. The topology that was just loaded becomes the default topology that is used to create patch accounts, and within the MapViewer to select neighbour polygons.
Multiple topology datasets may be loaded within a single Patchworks session. The most recently loaded topology file becomes the default topology.

Parameters:

file - The file containing the topological relationships.

distance - A value that is used to filter records from the topology file. Only neighbours that are within the filter distance are loaded from the topology file.

inputTopology

public Topology inputTopology(String filename,
                              double distance)

reuseOrLoadTopology
```
public Topology reuseOrLoadTopology(String filename,
                                    double distance,
                                    GeoRelationalStore store,
                                    String label)
```
Access a previously loaded topology file, or if not already loaded then input a topology dataset for an arbitrary spatial dataset.
This routine will return a topology dataset. This routine will not change the default block topology. You may call this routine at any time.

Parameters:

filename - The file containing the topological relationships.

distance - A value that is used to filter records from the topology file. Only neighbours that are within the filter distance are loaded from the topology file.

store - A reference to the spatial coverage that the topology file describes.

label - The name of the field in the spatial dataset that uniquely identifies each row.

addAccount
```
public void addAccount(String group,
                       String attribute,
                       String account)
```
Add a summary account to the model. This method is only valid when called during the account resolution phase (usually in the Patchworks_TargetInit method in the PIN file).

Parameters:

group - The group of blocks that the account is applied to

attribute - The attribute to be summed into the account

account - The name of the account

addAccount
```
public void addAccount(String group,
                       String attribute,
                       String account,
                       double[] factors)
```
Add a summary account to the model. This method is only valid when called during the account resolution phase (usually in the Patchworks_TargetInit method in the PIN file).

Parameters:

group - The group of blocks that the account is applied to

attribute - The attribute to be summed into the account

account - The name of the account

factors - An array of scaling factors that will be used to multiply the values from the attribute, with one value per period. If the array is shorter than the number of periods the last value will be repeated.

addAccount
```
public void addAccount(String group,
                       String attribute,
                       String account,
                       double factor)
```
Add a summary account to the model. This method is only valid when called during the account resolution phase (usually in the Patchworks_TargetInit method in the PIN file).

Parameters:

group - The group of blocks that the account is applied to

attribute - The attribute to be summed into the account

account - The name of the account

factor - A scaling factor that will be used to multiply the values from attribute.

addAccount
```
public void addAccount(String group,
                       String attribute,
                       boolean sum,
                       String account)
```
Deprecated.

Add a summary account to the model.
This method is only valid when called during the account resolution phase (usually in the Patchworks_TargetInit method in the PIN file).

Parameters:

group - The group of blocks that the account is applied to

attribute - The attribute to be summed into the account

sum - A flag to indicate if the attribute value should be added or subtracted from the account

account - The name of the account

removeAccount
```
public void removeAccount(String group,
                          String account)
```
Remove a summary account from the model. This will remove an account name that was automatically added via the accounts.csv file from being defined in the model. Be careful that the account name has not been used anywhere else in the model definition phase prior to being deleted.
This method is only valid when called during the account resolution phase (usually in the Patchworks_TargetInit method in the PIN file).

Parameters:

group - The group of blocks that the account is applied to

account - The name of the account. If the account is not found in the group then an exception will be thrown.

duplicateAccount
```
public void duplicateAccount(String master,
                             String child,
                             double[] factors)
```
Dupliate the value of an account into another account.

Parameters:

master - The name of the account that holds the values to be copied.

child - The name of the account that is to receive the duplicated values.

factors - An array of scaling factors that will be used to multiply the values from the attribute, with one value per period. If the array is shorter than the number of periods the last value will be repeated.

duplicateAccount
```
public void duplicateAccount(String master,
                             String child,
                             double factor)
```
Dupliate the value of an account into another account.

Parameters:

master - The name of the account that holds the values to be copied.

child - The name of the account that is to receive the duplicated values.

factor - A scaling factor to be applied to the duplicated account.

addExclusiveAccount
```
public void addExclusiveAccount(String match,
                                String account)
```
Add an exclusive account to the model.

Parameters:

match - The name of the exclusive account

account - The output account that is one of the options for this exclusive account.

addExclusiveDependent
```
public void addExclusiveDependent(String exclusive,
                                  String choice,
                                  String source,
                                  String sink,
                                  double[] factors)
```
Add an exclusive dependent account to the model. These accounts shadow what is happening in the Exclusive accounts, and will forward other attribute values to other accounts, depending on what happened with the exclusive.

Parameters:

exclusive - The name of the exclusive account

choice - The output account that was selected by the exclusive account

source - The account that contains the values to be added for this exclusive account.

sink - The account to add the values into, if the choice was selected in the exclusive account.

factors - An array of scaling factors that will be used to multiply the values from the attribute, with one value per period. If the array is shorter than the number of periods the last value will be repeated.

addExclusiveDependent
```
public void addExclusiveDependent(String exclusive,
                                  String choice,
                                  String source,
                                  String sink,
                                  double factor)
```
Add an exclusive dependent account to the model. These accounts shadow what is happening in the Exclusive accounts, and will forward other attribute values to other accounts, depending on what happened with the exclusive.

Parameters:

exclusive - The name of the exclusive account

choice - The output account that was selected by the exclusive account

source - The account that contains the values to be added for this exclusive account.

sink - The account to add the values into, if the choice was selected in the exclusive account.

factor - A scaling factor to be applied to the source values.

addPatchTarget
```
public void addPatchTarget(String criteria,
                           String label,
                           double min,
                           double max)
```
Add a patch target account to the model. This method is only valid when called during the account resolution phase (usually in the Patchworks_TargetInit method in the PIN file).

Parameters:

criteria - The name of the patch criteria account. The first time the criteria account is referenced a Patcher account will be created using the current default topology. Any subsequent patch targets with the same criteria name will be associated with this Patcher, regardless if the default topology changes.

label - The name to be given to this patch account

min - The minimum size of patches in this account

max - The maximum size of patches in this account

setPatchThreshold
```
public void setPatchThreshold(String patch,
                              double threshold)
```
Set a threshold on the criteria used to allow blocks to become a member of a patch. If the block has a criteria value larger than the threshold, then it is eligible to join the patch.
This method will only work after the patch target has been defined (after calling the addPatchTarget(java.lang.String, java.lang.String, double, double) method).

Parameters:

patch - The name of the patch criteria account.

threshold - The threshold criteria value. The criteria must be greater (on a per unit basis) than this value for the block to join in a patch. The default value is 0.

addRouteHaulAccount
```
public void addRouteHaulAccount(String route,
                                String account)
```
Add a route hauling account to the model. This will sum hauling costs into a summary account. This method is only valid when called during the account resolution phase (usually in the Patchworks_TargetInit method in the PIN file).

Parameters:

route - The name of the route of interest

account - The name to be given to this account

addRouteHaulAccount
```
public void addRouteHaulAccount(String route,
                                String account,
                                double factor)
```
Add a route hauling account to the model. This will sum hauling costs into a summary account. This method is only valid when called during the account resolution phase (usually in the Patchworks_TargetInit method in the PIN file).

Parameters:

route - The name of the route of interest

account - The name to be given to this account

factor - A factor used to multiply haul values.

addRouteHaulAccount
```
public void addRouteHaulAccount(String route,
                                String account,
                                double[] factors)
```
Add a route hauling account to the model. This will sum hauling costs into a summary account. This method is only valid when called during the account resolution phase (usually in the Patchworks_TargetInit method in the PIN file).

Parameters:

route - The name of the route of interest

account - The name to be given to this account

factors - An array of scaling factors that will be used to multiply the values from the attribute, with one value per period. If the array is shorter than the number of periods the last value will be repeated.

addRouteHaulAccount
```
@Deprecated
public void addRouteHaulAccount(String route,
                                             String account,
                                             boolean sum)
```
Deprecated. Use addRouteHaulAccount(String, String, double) instead.

Add a route hauling account to the model. This will sum hauling costs into a summary account. This method is only valid when called during the account resolution phase (usually in the Patchworks_TargetInit method in the PIN file).

Parameters:

route - The name of the route of interest

account - The name to be given to this account

sum - A flag to indicate if the attribute value should be added or subtracted from the account

addRouteBuildAccount
```
public void addRouteBuildAccount(String route,
                                 String account)
```
Add a route construction account to the model. This will sum construction costs into a summary account. This method is only valid when called during the account resolution phase (usually in the Patchworks_TargetInit method in the PIN file).

Parameters:

route - The name of the route of interest

account - The name to be given to this account

addRouteBuildAccount
```
public void addRouteBuildAccount(String route,
                                 String account,
                                 double factor)
```
Add a route construction account to the model. This will sum construction costs into a summary account. This method is only valid when called during the account resolution phase (usually in the Patchworks_TargetInit method in the PIN file).

Parameters:

route - The name of the route of interest

account - The name to be given to this account

factor - A factor used to multiply haul values.

addRouteBuildAccount
```
public void addRouteBuildAccount(String route,
                                 String account,
                                 double[] factors)
```
Add a route construction account to the model. This will sum construction costs into a summary account. This method is only valid when called during the account resolution phase (usually in the Patchworks_TargetInit method in the PIN file).

Parameters:

route - The name of the route of interest

account - The name to be given to this account

factors - An array of scaling factors that will be used to multiply the values from the attribute, with one value per period. If the array is shorter than the number of periods the last value will be repeated.

addRouteBuildAccount
```
@Deprecated
public void addRouteBuildAccount(String route,
                                              String account,
                                              boolean sum)
```
Deprecated. Use addRouteBuildAccount(String, String, double) instead.

Add a route construction account to the model. This will sum construction costs into a summary account. This method is only valid when called during the account resolution phase (usually in the Patchworks_TargetInit method in the PIN file).

Parameters:

route - The name of the route of interest

account - The name to be given to this account

sum - A flag to indicate if the attribute value should be added or subtracted from the account

addRouteRebuildAccount
```
public void addRouteRebuildAccount(String route,
                                   String account,
                                   double factor)
```
Add a route reactivation account to the model. This will sum reactivation costs into a summary account. This method is only valid when called during the account resolution phase (usually in the Patchworks_TargetInit method in the PIN file).

Parameters:

route - The name of the route of interest

account - The name to be given to this account

factor - A factor used to multiply haul values.

addRouteRebuildAccount
```
public void addRouteRebuildAccount(String route,
                                   String account,
                                   double[] factors)
```
Add a route reactivation account to the model. This will sum reactivation costs into a summary account. This method is only valid when called during the account resolution phase (usually in the Patchworks_TargetInit method in the PIN file).

Parameters:

route - The name of the route of interest

account - The name to be given to this account

factors - An array of scaling factors that will be used to multiply the values from the attribute, with one value per period. If the array is shorter than the number of periods the last value will be repeated.

addRouteRepairAccount
```
public void addRouteRepairAccount(String route,
                                  String account)
```
Add a route maintenance account to the model. This will sum maintenance costs into a summary account. This method is only valid when called during the account resolution phase (usually in the Patchworks_TargetInit method in the PIN file).

Parameters:

route - The name of the route of interest

account - The name to be given to this account

addRouteRepairAccount
```
public void addRouteRepairAccount(String route,
                                  String account,
                                  double factor)
```
Add a route maintenance account to the model. This will sum maintenance costs into a summary account. This method is only valid when called during the account resolution phase (usually in the Patchworks_TargetInit method in the PIN file).

Parameters:

route - The name of the route of interest

account - The name to be given to this account

factor - A factor used to multiply haul values.

addRouteRepairAccount
```
public void addRouteRepairAccount(String route,
                                  String account,
                                  double[] factors)
```
Add a route maintenance account to the model. This will sum maintenance costs into a summary account. This method is only valid when called during the account resolution phase (usually in the Patchworks_TargetInit method in the PIN file).

Parameters:

route - The name of the route of interest

account - The name to be given to this account

factors - An array of scaling factors that will be used to multiply the values from the attribute, with one value per period. If the array is shorter than the number of periods the last value will be repeated.

addRouteRepairAccount
```
@Deprecated
public void addRouteRepairAccount(String route,
                                               String account,
                                               boolean sum)
```
Deprecated. Use addRouteRepairAccount(String, String, double) instead.

Add a route maintenance account to the model. This will sum maintenance costs into a summary account. This method is only valid when called during the account resolution phase (usually in the Patchworks_TargetInit method in the PIN file).

Parameters:

route - The name of the route of interest

account - The name to be given to this account

sum - A flag to indicate if the attribute value should be added or subtracted from the account

addRouteProductAccount
```
public void addRouteProductAccount(String route,
                                   String account)
```
Add a route flow account to the model. This will sum product values (the amount of product being hauled) into a summary account. This method is only valid when called during the account resolution phase (usually in the Patchworks_TargetInit method in the PIN file).

Parameters:

route - The name of the route of interest

account - The name to be given to this account

addRouteProductAccount
```
public void addRouteProductAccount(String route,
                                   String account,
                                   double factor)
```
Add a route flow account to the model. This will sum product values (the amount of product being hauled) into a summary account. This method is only valid when called during the account resolution phase (usually in the Patchworks_TargetInit method in the PIN file).

Parameters:

route - The name of the route of interest

account - The name to be given to this account

factor - A factor used to multiply haul values.

addRouteProductAccount
```
public void addRouteProductAccount(String route,
                                   String account,
                                   double[] factors)
```
Add a route flow account to the model. This will sum product values (the amount of product being hauled) into a summary account. This method is only valid when called during the account resolution phase (usually in the Patchworks_TargetInit method in the PIN file).

Parameters:

route - The name of the route of interest

account - The name to be given to this account

factors - An array of scaling factors that will be used to multiply the values from the attribute, with one value per period. If the array is shorter than the number of periods the last value will be repeated.

addRouteProductAccount
```
@Deprecated
public void addRouteProductAccount(String route,
                                                String account,
                                                boolean sum)
```
Deprecated. Use addRouteProductAccount(String, String, double) instead.

Add a route flow account to the model. This will sum product values (the amount of product being hauled) into a summary account. This method is only valid when called during the account resolution phase (usually in the Patchworks_TargetInit method in the PIN file).

Parameters:

route - The name of the route of interest

account - The name to be given to this account

sum - A flag to indicate if the attribute value should be added or subtracted from the account

addMetaAccount
```
public void addMetaAccount(String account,
                           String[] components,
                           double[] factors)
```
Add a meta account to the model. A meta account creates a summary account that tracks the results of other accounts. Other account values can be multiplied by a scaling factor and summed. This is useful for establishing targets on values that are not represented by stand indicators, such as patch frequency.
This method is only valid when called during the account resolution phase (usually in the Patchworks_TargetInit method in the PIN file).

Parameters:

account - The name to be given to this account

components - The names of the accounts that will be summed.

factors - The factors that will be applied to each account.

addMetaAccount
```
public void addMetaAccount(String account,
                           String[] components,
                           double[][] factors)
```
Add a meta account to the model. A meta account creates a summary account that tracks the results of other accounts. Other account values can be multiplied by a scaling factor and summed. This is useful for establishing targets on values that are not represented by stand indicators, such as patch frequency.
This method is only valid when called during the account resolution phase (usually in the Patchworks_TargetInit method in the PIN file).

Parameters:

account - The name to be given to this account

components - The names of the accounts that will be summed.

factors - Arrays of scaling factors that will be used to multiply the values from the attribute, with one value per period. If the array is shorter than the number of periods the last value will be repeated.

addFlowRatioAccount
```
public void addFlowRatioAccount(String account,
                                String input,
                                int flowPeriod,
                                boolean skipFirst)
```
Add a flow ratio account to the model. A flow ratio account tracks the relative change in an account between periods. This can be used to implement flow policies such as non-declining yield.
This method is only valid when called during the account resolution phase (usually in the Patchworks_TargetInit method in the PIN file).

Parameters:

account - The name to be given to this account

input - The names of the account that the flow policy will apply to.

flowPeriod - An offest value to specified the relative period that the flow will be compared to.

skipFirst - If true then do not compare flows between initial conditions and the first period.

See Also:

FlowRatioTarget

addFlowRatioAccount
```
public void addFlowRatioAccount(String account,
                                String input,
                                int[] flowPeriods,
                                double ratioScale)
```
Add a flow ratio account to the model. A flow ratio account tracks the relative change in an account between periods. This can be used to implement flow policies such as non-declining yield.
This method is only valid when called during the account resolution phase (usually in the Patchworks_TargetInit method in the PIN file).
The flow ratios are based on the comparison of periodic values. This is appropriate if the planning periods are the same width, or if comparing extant inventory values (e.g. features). If comparing product values between periods of different widths then use the form addFlowRatioAccount(String, String, int[], double, boolean).

Parameters:

account - The name to be given to this account

input - The names of the account that the flow policy will apply to.

flowPeriods - An array of offest values to specified the period that the flow in each period will be compared to. Specify an offset value the same as the period to skip calculation for that period.

ratioScale - A value used to scale the resulting ratio. The default value is 100, which will display the values as a percent.

See Also:

FlowRatioTarget

addFlowRatioAccount
```
public void addFlowRatioAccount(String account,
                                String input,
                                FlowSpec flowPeriods,
                                double ratioScale)
```
Add a flow ratio account to the model. A flow ratio account tracks the relative change in an account between periods. This can be used to implement flow policies such as non-declining yield.
This method is only valid when called during the account resolution phase (usually in the Patchworks_TargetInit method in the PIN file).
The flow ratios are based on the comparison of periodic values. This is appropriate if the planning periods are the same width, or if comparing extant inventory values (e.g. features). If comparing product values between periods of different widths then use the form addFlowRatioAccount(String, String, int[], double, boolean).

Parameters:

account - The name to be given to this account

input - The names of the account that the flow policy will apply to.

flowPeriods - A FlowSpec object that describes how periods should be compared.

ratioScale - A value used to scale the resulting ratio. The default value is 100, which will display the values as a percent.

See Also:

FlowRatioTarget

addFlowRatioAccount
```
public void addFlowRatioAccount(String account,
                                String input,
                                int[] flowPeriods,
                                double ratioScale,
                                boolean annual)
```
Add a flow ratio account to the model. A flow ratio account tracks the relative change in an account between periods. This can be used to implement flow policies such as non-declining yield.
This method is only valid when called during the account resolution phase (usually in the Patchworks_TargetInit method in the PIN file).
Using the annual flag you may choose between periodic and annualize values for comparison.

Parameters:

account - The name to be given to this account

input - The names of the account that the flow policy will apply to.

flowPeriods - An array of offest values to specified the period that the flow in each period will be compared to. Specify an offset value the same as the period to skip calculation for that period.

ratioScale - A value used to scale the resulting ratio. The default value is 100, which will display the values as a percent.

annual - A flag that indicates if the flow ratios should be based on annualized values (true) or periodic values.

See Also:

FlowRatioTarget

addFlowRatioAccount
```
public void addFlowRatioAccount(String account,
                                String input,
                                FlowSpec flowPeriods,
                                double ratioScale,
                                boolean annual)
```
Add a flow ratio account to the model. A flow ratio account tracks the relative change in an account between periods. This can be used to implement flow policies such as non-declining yield.
This method is only valid when called during the account resolution phase (usually in the Patchworks_TargetInit method in the PIN file).
Using the annual flag you may choose between periodic and annualize values for comparison.

Parameters:

account - The name to be given to this account

input - The names of the account that the flow policy will apply to.

flowPeriods - A FlowSpec object that describes how periods should be compared.

ratioScale - A value used to scale the resulting ratio. The default value is 100, which will display the values as a percent.

annual - A flag that indicates if the flow ratios should be based on annualized values (true) or periodic values.

See Also:

FlowRatioTarget

addFlowValueAccount
```
public void addFlowValueAccount(String account,
                                String input,
                                int flowPeriod,
                                boolean skipFirst)
```
Add a flow value account to the model. A flow value account tracks the absolute change in an account between periods. This can be used to implement flow policies such as non-declining yield.
This method is only valid when called during the account resolution phase (usually in the Patchworks_TargetInit method in the PIN file).

Parameters:

account - The name to be given to this account

input - The names of the account that the flow policy will apply to.

flowPeriod - An offest value to specified the relative period that the flow will be compared to.

skipFirst - If true then do not compare flows between initial conditions and the first period.

See Also:

FlowValueTarget

addFlowValueAccount
```
public void addFlowValueAccount(String account,
                                String input,
                                int[] flowPeriods)
```
Add a flow value account to the model. A flow value account tracks the absolute change in an account between periods. This can be used to implement flow policies such as non-declining yield.
This method is only valid when called during the account resolution phase (usually in the Patchworks_TargetInit method in the PIN file).

Parameters:

account - The name to be given to this account

input - The names of the account that the flow policy will apply to.

flowPeriods - An array of offest values to specified the period that the flow in each period will be compared to. Specify an offset value the same as the period to skip calculation for that period.

See Also:

FlowValueTarget

addFlowValueAccount
```
public void addFlowValueAccount(String account,
                                String input,
                                FlowSpec flowPeriods)
```
Add a flow value account to the model. A flow value account tracks the absolute change in an account between periods. This can be used to implement flow policies such as non-declining yield.
This method is only valid when called during the account resolution phase (usually in the Patchworks_TargetInit method in the PIN file).

Parameters:

account - The name to be given to this account

input - The names of the account that the flow policy will apply to.

flowPeriods - A FlowSpec object that describes how periods should be compared.

See Also:

FlowValueTarget

addTabulateAccount
```
public void addTabulateAccount(String account,
                               String input,
                               int[] tabulatePeriods)
```
Add a tabulate value account to the model. A tabulate account adds the values from one set of periods in the input accounts to another set of periods in the output account. This can be used to track total values across multiple periods.
This method is only valid when called during the account resolution phase (usually in the Patchworks_TargetInit method in the PIN file).

Parameters:

account - The name to be given to this account

input - The name of the account that provides the values to sum up.

tabulatePeriods - An array of period values that indicate the periods in the output account that should receive the values from the input account. The array has one cell for each planning period. These cells correspond to the periods in the input account. The values in the cells identify which output period the value should be written in to. If the value is negative then the input value will not be used.

See Also:

TabulateTarget

addRatioAccount
```
public void addRatioAccount(String account,
                            String numerator,
                            String denominator,
                            double ratioScale)
```
Add a ratio account to the model. A ratio account creates a summary account that tracks the result of dividing one account by another. This is useful for establishing targets on the percent composition of a type, such as the amount of late seral stage area as a percent of a strata.
This method is only valid when called during the account resolution phase (usually in the Patchworks_TargetInit method in the PIN file).

Parameters:

account - The name to be given to this account

numerator - The name of the account to be used as the numerator

denominator - The name of the account to be used as the denominator

ratioScale - A value used to scale the resulting ratio. The default value is 100, which will display the values as a percent.

See Also:

RatioTarget

addRatioAccount
```
public void addRatioAccount(String account,
                            String numerator,
                            String denominator)
```
Add a ratio account to the model. A ratio account creates a summary account that tracks the result of dividing one account by another. This is useful for establishing targets on the percent composition of a type, such as the amount of late seral stage area as a percent of a strata.
This method is equivalent to
```
  addRatioAccount(account, numerator, denominator, 100);
 
```
This method is only valid when called during the account resolution phase (usually in the Patchworks_TargetInit method in the PIN file).
Parameters:

account - The name to be given to this account

numerator - The name of the account to be used as the numerator

denominator - The name of the account to be used as the denominator

See Also:

RatioTarget

addEdgeTarget
```
public void addEdgeTarget(String account,
                          Topology topology)
```
Create an edge target, using the specified topology to determine stand adjacency. After creating the target, use the addEdgeElement(java.lang.String, java.lang.String, java.lang.String, double) method to define the edge contrast matrix.
This target type computes edge metric targets. Edge metrics describe the juxtaposition of one forest type beside another. This metric works by computing the absolute difference in value between edge attributes between two adjacent stands (on a per unit area basis), and multiplying this by the length of shared edge. Polygons that do not touch have no shared edge, and do not count towards this metric.
A scale factor is also allowed in order to more heavily contrast some edge types.
When adding an element, specify the names of the attributes that define the edge, and provide a scaling factor that will be applied to the difference between the two edges. For example:
```
 topology = control.intputTopology("../blocks/blocks_topo.csv", 10);
 control.addEdgeTarget("feature.Edge.OldYoung", topology);
 control.addEdgeElement("feature.Edge.OldYoung", "feature.Seral.Old", "feature.Seral.Young", 1);
 
```

addEdgeElement

public void addEdgeElement(String account,
                           String attribute1,
                           String attribute2,
                           double factor)

Add an edge contrast specification to an edge target.

addGroupDistributionAccount
```
public void addGroupDistributionAccount(String account,
                                        String[] groupNames,
                                        double[] groupTotals)
```
Create a new GroupDistibutionAccount. A group distribution account will compute the percent composition of the input account value compared with the total area of of a set of groups. The total area of each group will be added in to a sub-account based on the percent composition range assigned to the sub-account.

Parameters:

account - The name of the new account.

groupNames - A list of names of the groups that will participate in the account. These names must be defined as groups in the Patchworks model.

groupTotals - A list of area totals for each group. These values will be used as the denominator in the calculation of the percent composition of each group, and will be added to the group sub account that represents the proper proporional sub-account.

addGroupDistributionSubAccount
```
public void addGroupDistributionSubAccount(String groupAccount,
                                           String subAccount,
                                           double min,
                                           double max)
```
Create a sub-account within a GroupDistributionAccount. The sub-account will track the amount of area that is composed of groups having a percent composition between the limits of the min and max values.

Parameters:

groupAccount - The name of the GroupDistributionAccount that this sub-account should be attached to.

subAccount - The name that should be given to this sub-account.

min - The minimum percent composition value used to limit group area to be added to this sub-account. The percent composition value must be greater than this value.

max - The maximum percent composition value used to limit group area to be added to this sub-account. The percent composition value must be less than or equal to this value.

setTreatmentAffinity
```
public void setTreatmentAffinity(TreatmentAffinity[][] affinities)
```
Set the list of treatments that are allowed to be scheduled in the same planning period within the same bunch. By default any mix of treatments are allowed within a bunch. When an affintiy list is set then only the treatments within the same list are allowed to be scheduled within a bunch during the same period. This method may only be called during target inititialization.

getTreatmentNames

public ArrayList<String> getTreatmentNames()

initialize
```
public void initialize(Task task)
```
Initialize the account values

waitUntilInitialized
```
public void waitUntilInitialized()
                          throws InterruptedException
```
Wait until the model is initialized. If it is already initialized then return immediately. Note that if errors occur when loading the model then this method will wait indefinitely.

Throws:

InterruptedException

setInitialValue
```
public void setInitialValue(String label,
                            double value,
                            int period)
```
Set an initial value for an account. This value will be present at initialization before any attributes are added in to the account. This value can be used to represent a baseline that is known but not represented by block attributes.

Parameters:

label - the account label

value - the value to set as the baseline

period - the period to set

interrupt
```
public void interrupt()
```
Send a signal to interrupt the scheduler.

getAttributeLabels
```
public Set getAttributeLabels()
```
Get a set object containing all of the attribute labels that have been loaded into the Patchworks model.

makeDotFile

public void makeDotFile(String filename)

makeDotFile

public void makeDotFile(String filename,
                        int width,
                        int height,
                        boolean simplify)

close
```
public void close()
```
Release the structures that have been allocated for the simulation. Note that after this method has been called the simulation environment is closed and none of the other methods can be used.

getTargetLabels
```
public Set<String> getTargetLabels()
```
Get a set of all target labels.

setTargetLinear
```
public boolean setTargetLinear(String label,
                               boolean value)
```
Deprecated.
This method set the linear scaling mode on a target value. The use of this method is deprecated. Instead, use something similar to the following:
```
  control.getTarget("name").setLinear(true);
 
```

setTargetDiscountRate
```
public boolean setTargetDiscountRate(String label,
                                     double rate)
```
Deprecated.
This method set the discount on a target value. The use of this method is deprecated. Instead, use something similar to the following:
```
  control.getTarget("name").setDiscountRate(1.03);
 
```

getIteration
```
public long getIteration()
```

getPerformanceChart
```
public Component getPerformanceChart()
```
Get a performance strip chart viewer.

waitForIterations
```
public void waitForIterations(int attempts)
                       throws InterruptedException
```
This method will wait for a number of scheduling attempts to pass before returning to the caller. If is useful to include this method in scripts that perform batch execution.
The following example shows typical BeanShell usage:
```
   print("Run simulation and then save");
   gui.click("start");
   control.waitForIterations(4000000);
   gui.click("pause");
   reportWriter.saveStage("scenario1");
 
```
An invocation of this convenience method of the form
```
   control.waitForIterations(4000000);
 
```
behaves in exactly the same way as the expression
```
   control.waitForProgress(4000000, -1, null, null, null);
 
```
Parameters:

attempts - The number of attempts that must pass before execution continues. An attempt is a trial of a change to the schedule. The number of attempts is usually less than the number of iterations, because many iterations are discarded as infeasible before being tested by the scheduling algorithm.

Throws:

InterruptedException

waitForProgress
```
public void waitForProgress(int attempts,
                            double percent)
                     throws InterruptedException
```
This method will wait for the objective function to converge before returning to the caller. If is useful to include this method in scripts that perform batch execution.
The following example shows typical BeanShell usage:
```
   print("Run simulation and then save");
   gui.click("start");
   control.waitForProgress(100000, 0.1);
   gui.click("pause");
   reportWriter.saveStage("scenario2");
 
```
An invocation of this convenience method of the form
```
   control.waitForIterations(100000, 0.1);
 
```
behaves in exactly the same way as the expression
```
   control.waitForIterations(100000, 0.1, null, null, null);
 
```
Parameters:

attempts - The number of attempts that must pass between tests for the convergence of the objective value. An attempt is a trial of a change to the schedule. The number of attempts is usually less than the number of iterations, because many iterations are discarded as infeasible before being tested by the scheduling algorithm.

percent - The threshold for performance improvement that must be achieved before the method returns. The change in objective function value is measured between sampling intervals specified by the attempts parameter. If the percent improvement over the interval is less than the percent parameter the method will return. If the percent value is less than zero, then return as soon as the number of attempts has been completed.

Throws:

InterruptedException

waitForProgress
```
public void waitForProgress(int attempts,
                            double percent,
                            ConvergenceSpec[] specs,
                            ScenarioChangeListener asd)
                     throws InterruptedException
```
This method will wait for the objective function to converge before returning to the caller. If is useful to include this method in scripts that perform batch execution.
The following example shows typical BeanShell usage:
```
   print("Run simulation and then save");
   gui.click("start");
   String[] patterns = {"product.Yield.*", "route.*", "*"};
   double[] values = {0.01, 0.5, 0.1};
   control.waitForProgress(100000, 0.1, patterns, values, null);
   gui.click("pause");
   reportWriter.saveStage("scenario2");
 
```
This example will start the silumation, and then call the wait method. The method will wait until 100,000 attemtps have passed, and then test the change in the objective function value against the percent parameter. If the change is less than the percent value, then the method will then test specific target values for change since the last test. If all the specified targets have change less than the specified values, the method will return and the script will continue to pause the simulator and save the scenario. Otherwise the method will wait for another set of attempts to occur before testing again.
Parameters:

attempts - The number of attempts that must pass between tests for the convergence of the objective value. An attempt is a trial of a change to the schedule. The number of attempts is usually less than the number of iterations, because many iterations are discarded as infeasible before being tested by the scheduling algorithm.

percent - The threshold for performance improvement that must be achieved before the method returns. The change in objective function value is measured between sampling intervals specified by the attempts parameter. If the percent improvement over the interval is less than the percent parameter the method will then test the specific target values specified in patterns and values parameters. If the percent value is less than zero, then return as soon as the number of attempts has been completed.

specs - An array of sub-target convergence criteria

asd - A reference to an ScenarioChangeListener object. The scheduler will call the ScenarioChangeListener.init() method when the listener is registered, and then the ScenarioChangeListener.evaluateBefore() and ScenarioChangeListener.evaluateAfter(boolean, ca.spatial.patchworks.ScenarioMonitor) methods before and after it evaluates the convergence criteria. The changeListener may alter the criteria to terminate or extend the simulation.

Throws:

InterruptedException

waitForProgress
```
public void waitForProgress(int attempts,
                            double percent,
                            String[] patterns,
                            double[] values,
                            ScenarioChangeListener asd)
                     throws InterruptedException
```
Deprecated. It is recommended that scenario life cycle management should be handled using the ScenarioSet, ScenarioDescription and ScenarioChangeListener mechanism. These methods provide self-documentation and fine-grained customizable control over how scenarios are run, including the ability to monitor progress and alter simulation values.
This method will wait for the objective function to converge before returning to the caller. If is useful to include this method in scripts that perform batch execution.
The following example shows typical BeanShell usage:
```
   print("Run simulation and then save");
   gui.click("start");
   String[] patterns = {"product.Yield.*", "route.*", "*"};
   double[] values = {0.01, 0.5, 0.1};
   control.waitForProgress(100000, 0.1, patterns, values, null);
   gui.click("pause");
   reportWriter.saveStage("scenario2");
 
```
This example will start the simulation, and then call the wait method. The method will wait until 100,000 attemtps have passed, and then test the change in the objective function value against the percent parameter. If the change is less than the percent value, then the method will then test specific target values for change since the last test. If all the specified targets have change less than the specified values, the method will return and the script will continue to pause the simulator and save the scenario. Otherwise the method will wait for another set of attempts to occur before testing again.
Parameters:

attempts - The number of attempts that must pass between tests for the convergence of the objective value. An attempt is a trial of a change to the schedule. The number of attempts is usually less than the number of iterations, because many iterations are discarded as infeasible before being tested by the scheduling algorithm.

percent - The threshold for performance improvement that must be achieved before the method returns. The change in objective function value is measured between sampling intervals specified by the attempts parameter. If the percent improvement over the interval is less than the percent parameter the method will then test the specific target values specified in patterns and values parameters. If the percent value is less than zero, then return as soon as the number of attempts has been completed.

patterns - A list of glob-style patterns that describe the targets to be tested.

values - A list of percentages to be compared against the targets that match the corresponding patterns.

asd - A reference to an ScenarioChangeListener object that will receive scenario life cycle events and potentially alter the course of the simulation. This value may be null, in which case life cycle events will be ignored.

Throws:

InterruptedException

addProgressListener

public void addProgressListener(ObjectiveProgressReport listener)

removeProgressListener

public void removeProgressListener(ObjectiveProgressReport listener)

inputRoute
```
public void inputRoute(String label,
                       String filename)
```
Input a saved route file. This method will read the route definition file into the model.

Parameters:

label - The name of the route to load

filename - The name of the file that contains the saved route information.

outputRoute
```
public void outputRoute(String label,
                        String filename)
```
Save a route definition to a file. This method will save the current routing information into an output file.

Parameters:

label - The name of the route to save

filename - The name of the file to contain the saved route information.

resume
```
public void resume()
```
Resume the scheduler from a suspended state. After calling this method the scheduler will become active.

suspend
```
public void suspend()
```
Suspend the sheduler. The scheduler is paused and may be resumed using the resume() method.

isSuspended
```
public boolean isSuspended()
```
Determine if the scheduler is suspended

getSharedInstance
```
public static Control getSharedInstance()
```
Get a reference to the Control object. Control objects cannot be instantiated directly. Instead you must call this method to get access to the object.

setTreatment
```
public boolean setTreatment(int index,
                            String treatment,
                            int year,
                            boolean managed)
```
Apply a treatment to a block in a specific year

Parameters:

index - the block index

treatment - the name of the treatment to apply

year - the year to apply the treatment

managed - apply to the managed (true) or unmanaged (false) protion of the block

Returns:

true if the treatment was applied successfully, or false if not

setBlockAvailable
```
public boolean setBlockAvailable(int row,
                                 boolean[] values)
```
Set the available timings for all periods. This is a performance optimization over setting timings by separate calls period-by-period.

Parameters:

row - The row number for the block

values - The array of timing values.

Returns:

Returns true if the block has managed area, false if no managed area.

setRandomSeed
```
public void setRandomSeed(long seed)
```
Set the seed used by the random number generator within the scheduler. This routine is provided so that a repeatable sequence of numbers is returned from the stream.
The Patchworks scheduling hueristic uses the random number stream to guide the allocation process. Pseudo random numbers are generated by an algorithm where the value of the first pseudorandomm number is used to help generate the value of the next, and so on. If you set the value of the first number to a known quantity, the the rest of the number stream is predictable and repeatable.
By default the random number stream is initialized with a seed that is highly likely to be different from any other Patchworks run. Normally you would not want to manually set the seed to the random number stream.

cancelTreatments
```
public void cancelTreatments(String label)
```
Cancel all of the treatments for the block with the given label.

cancelTreatments
```
public void cancelTreatments()
```
Cancel all of the treatments for all blocks in the forest.

getClientObject
```
public Object getClientObject()
```

getTargetView
```
public Component getTargetView(String label)
```
Get a target viewer for a specified target.
The object that is returned is a component, and must be placed inside of a windowing container such as a JFrame in order to be made visible on the screen.

getTreatmentView
```
public Component getTreatmentView(String label)
```
Get a treatment viewer for a specified block.
The object that is returned is a component, and must be placed inside of a windowing container such as a JFrame in order to be made visible on the screen.

getTargetTable
```
public AttributeStore getTargetTable()
```
Get a reference to the target table.
The object that is returned is a model (one part of a model-view-controller paradigm). You can manipulate the data programatically using this model. If you want to view the table then instead call the AttributeStore.showCube(boolean) method.

getTarget

public Target getTarget(String label)

Get a target by name.

getTargets

public Collection<Target> getTargets()

Get all targets.

getObjectiveValue
```
public double getObjectiveValue(boolean details)
```
Compute the current objective value.

Parameters:

details - This parameter is historic and is ignored.

Returns:

The current objective function value

getBlockTable
```
public GeoRelationalStore getBlockTable()
```
Get a reference to the block table object. The block table includes most of the block level internal simulation data, as well as the shape data that describes each block.
The object that is returned is a model (one part of a model-view-controller paradigm). You can manipulate the data programatically using this model. If you want to view the table then instead call the AttributeStore.showCube(boolean) method.

See Also:

BlockStore

getStandEventReport
```
public StandEventReport getStandEventReport(String filename,
                                            String title,
                                            String treatedManAreaExpr,
                                            String treatedUnmanAreaExpr)
```
Create a Stand Dynamics report.

Parameters:

filename - the name to be given to the output file, having a .csv extension

title - the title to be shown in the report writer

treatedManAreaExpr - an expression that yields the area of the managed portion of the stand that has been treated. May be null in which case the entire area is affected by the event.

treatedUnmanAreaExpr - an expression that yields the area of the unmanaged portion of the stand that has been treated. May be null in which case the entire area is affected by the event.

getEvents
```
public ArrayList<EventRecord> getEvents(String id,
                                        String treatedManAreaExpr,
                                        String treatedUnmanAreaExpr)
```
Return a list of event records for the given row.

Parameters:

id - the row of interest

treatedManAreaExpr - an expression to use to determine the area of the managed part of the block that received treatments

treatedUnmanAreaExpr - an expression to use to determine the area of the unmanaged part of the block that received treatments

cbmExport
```
public void cbmExport()
```
Display a wizard to collect parameters and run the CBM-CFS3 export tool.

cbmExport
```
public void cbmExport(String[] classifiers,
                      String histDist,
                      String lastDist,
                      String[] conSppList,
                      String[] hwdSppList,
                      String sppRegex,
                      int evalYear,
                      String output)
               throws Exception
```
Export files that can be imported in to the CBM-CFS3 model.

Parameters:

classifiers - a list of strata names to be included in the model

histDist - an expression that evaluates to the historic disturbance condition of the polygon

lastDist - an expression that evaluates to the last disturbance condition of the polygon

conSppList - a list of stand attributes that define the conifer volume in the stand

hwdSppList - a list of stand attributes that define the hardwood volume in the stand

sppRegex - a regular expression pattern that can be used to extract the species codes from the yield attributes

evalYear - the year to be used to calculate leading species

output - the name of the output zip file. If a zip extension is not present it will be added.

Throws:

Exception

cbmExport
```
public void cbmExport(String[] classifiers,
                      String histDist,
                      String lastDist,
                      String conYield,
                      String hwdYield,
                      String conLeadSpp,
                      String hwdLeadSpp,
                      int evalYear,
                      String output)
               throws Exception
```
Export files that can be imported in to the CBM-CFS3 model.

Parameters:

classifiers - a list of strata names to be included in the model

histDist - an expression that evaluates to the historic disturbance condition of the polygon

lastDist - an expression that evaluates to the last disturbance condition of the polygon

conYield - an expression to calculate the conifer yield component of the stand

hwdYield - an expression to calculate the hardwood yield component of the stand

conLeadSpp - an expression to calculate the conifer leading species

hwdLeadSpp - an expression to calculate the hardwood leading species

evalYear - the year to be used to calculate leading species

output - the name of the output zip file. If a zip extension is not present it will be added.

Throws:

Exception

getStrataColumns
```
public String[] getStrataColumns()
```
Get the names of the stratification columns

getAccessTable
```
public AccessTableModel getAccessTable()
```
Get a reference to the timing constraints table object.
The object that is returned is a model (one part of a model-view-controller paradigm). You can manipulate the data programatically using this model. If you want to view and edit the table then call the action to open the timing constraints editor:
```
   control.getActions().get("editAccess").perform();
 
```
See Also:

getActions(), Actions

getRouteTable
```
public GeoRelationalStore getRouteTable(String label)
```
Get a route table for a specified route. The route table will contain the route shapes as well as cost and utilization data for every segment.

getNetworkTable
```
public GeoRelationalStore getNetworkTable()
```
Get the network table containing the route shapes as well as cost and utilization data for every segment for every destination.

getDestinationNames
```
public Vector<String> getDestinationNames()
```
Get a sorted list of route destination names

getExclusiveAccountNames
```
public Vector<String> getExclusiveAccountNames()
```
Get a sorted list of exclusive account names

getRouteReport
```
public Report getRouteReport(String filename,
                             String title,
                             String destination)
```
Get a route report. This report creates a CSV file containing order of road segments in a route. The file can be used to reload a scenario back to the current condition.

Parameters:

filename - The filename used for output. This name must be unique within the ReportWriter where this report will be cataloged.

title - The report title

destination - The name of the destination for this route report

getRouteCostReport
```
public Report getRouteCostReport(String filename,
                                 String title,
                                 String destination)
```
Get a route cost report. This report creates html, gif and csv files that describe the costs associated with a route.

Parameters:

filename - The filename used for output. This name must be unique within the ReportWriter where this report will be cataloged.

title - The report title

destination - The name of the destination for this route report

getNetworkCostReport
```
public Report getNetworkCostReport(String filename,
                                   String title)
```
Get a network cost report. This report creates html, gif and csv files that describe the costs associated with tne entire.

Parameters:

filename - The filename used for output. This name must be unique within the ReportWriter where this report will be cataloged.

title - The report title

getTimingConstraintsReport
```
public Report getTimingConstraintsReport(String filename,
                                         String title)
```
Get a timing constraints report. This report creates html and csv files that describe the timing constraints associated with each block. The timing constraints are saved in a format that can be load back in to the Timing Constraints Editor.
Timing constraints are specified by 'ZONES', which are simply polygons that have the same values for a classification field. The constraints specify if a stand is eligible to be scheduled for treatments.
This file represents one of the input data sets used by the Patchworks model. This file is usually not saved by the model as a 'scenario' data set. This report can be used to optionally save this data.

Parameters:

filename - The filename used for output. This name must be unique within the ReportWriter where this report will be cataloged.

title - The report title

addNote
```
public void addNote(String details)
```
Add a note to the log file. The note will be printed out in the ScenarioEventReport. You can use this method to add your own annotations and document the scenario.

Parameters:

details - The detailed message string to be added to the log file.

addNote
```
public void addNote(String category,
                    String details)
```
Add a note to the log file. The note will be printed out in the ScenarioEventReport. You can use this method to add your own annotations and document the scenario. T

Parameters:

category - The category name of the message.

details - The detailed message string to be added to the log file.

getExclusiveAccount
```
public Exclusive getExclusiveAccount(String name)
```
Get an exclusive account by name. Exclusive accounts are part of the 'multiple-destination' plumbing.

getExclusiveAssignmentReport
```
public Report getExclusiveAssignmentReport(String filename,
                                           String title,
                                           String exclusive)
```
Get an exclusive assignment report. This report creates a CSV file containing the assignments to exclusive accounts (such as in a multiple-destination route formulation). The file can be used to reload a scenario back to the current condition.

Parameters:

filename - The filename used for output. This name must be unique within the ReportWriter where this report will be cataloged.

title - The report title

exclusive - The name of the exclusive account to be saved

getExclusiveLockReport
```
public Report getExclusiveLockReport(String filename,
                                     String title,
                                     String exclusive)
```
Get an exclusive lock report. This report creates a CSV file containing the locks to exclusive accounts (such as in a multiple-destination route formulation). The file can be used to reload a scenario back to the current condition.

Parameters:

filename - The filename used for output. This name must be unique within the ReportWriter where this report will be cataloged.

title - The report title

exclusive - The name of the exclusive account to be saved

loadExclusive
```
public void loadExclusive(String exclusive,
                          String filename)
```
Load a saved file in to initialize exclusive account assignments. This method will load a previously saved file and restore the simulation to a previous condition.

Parameters:

exclusive - The name of the exclusive account to be saved

filename - The filename to be read for input.

loadExclusiveLocks
```
public void loadExclusiveLocks(String exclusive,
                               String filename)
```
Load a saved file in to initialize exclusive account locks. Locks will cause the exclusive account to be ineligible to change in the given time period. This method will load a previously saved file and restore the simulation to a previous condition.

Parameters:

exclusive - The name of the exclusive account to be saved

filename - The filename to be read for input.

loadSchedule
```
public void loadSchedule(String filename)
```
Load a saved file in to initialize the schedule of treatments. This method will load a previously saved file and restore the simulation to a previous condition. Any previous treatments will be cancelled before the treatment file is loaded.

Parameters:

filename - The filename to be read for input.

loadSchedule
```
public void loadSchedule(String filename,
                         boolean cancelPrevious)
```
Load a saved file in to initialize the schedule of treatments. This method will load a previously saved file and restore the simulation to a previous condition. Any previous treatments will be cancelled if the cancelPrevious parameter is set to true.

Parameters:

filename - The filename to be read for input.

cancelPrevious - Flag to indicate to cancel all previously scheduled preatments before loading the specified treatment file.

loadTargetSummary
```
public void loadTargetSummary(String filename)
```
Load a saved file in to initialize target summary data. This method will load a previously saved file and restore the simulation to a previous condition.

Parameters:

filename - The filename to be read for input.

loadTargetStatus
```
public void loadTargetStatus(String filename)
```
Load a saved file in to initialize target status data. This method will load a previously saved file and restore the simulation to a previous condition.

Parameters:

filename - The filename to be read for input.

loadAvailable
```
public void loadAvailable(String filename)
```
Load a saved file in to initialize block availability data. This method will load a previously saved file and restore the simulation to a previous condition.

Parameters:

filename - The filename to be read for input.

showAccountExplorer
```
public void showAccountExplorer()
```
Display the AccountExplorer viewer.

showGroupExplorer
```
public void showGroupExplorer()
```
Display the GroupExplorer viewer.

getActions
```
public Actions getActions()
```
Get a map containing actions that are known to the model. These generally used in GUI components but can also be used in scripts.

getReportWriter
```
public ReportWriter getReportWriter()
```

getComparisonWriter

public ComparisonWriter getComparisonWriter()

identifyPatches
```
public static void identifyPatches(GeoRelationalStore store,
                                   Topology topology,
                                   String label,
                                   String reselect,
                                   int period,
                                   String output)
```
This method will identify patches within a spatial dataset. The will analyze all selected polygons (according to the reselection criteria). Selected polygons that are neighbours according to the topology will be assigned the same patch id. The method will create an output file with a row for each polygon containing the unique id and patch number. Polygons that do not belong to patches will be given a patch id of '-1'.

Parameters:

store - The spatial dataset to classify

topology - The topological relationships

label - A column in the spatial dataset that uniquely identifies each polygon

reselect - An expression used to select the polygons that are candidates for patching.

period - The period of interest. For simple spatial datasets such as shapefiles or coverages this should be 0.

output - The name of the output file that will contain the patch numbers.

Class Control

Method Summary

Methods inherited from class java.lang.Object

Method Detail

setConversionFactors

getConversionFactors

setMaximumEntries

getMaximumEntries

inputGroups

inputGroups

calculateGroups

getGroups

inputTopology

inputTopology

reuseOrLoadTopology

addAccount

addAccount

addAccount

addAccount

removeAccount

duplicateAccount

duplicateAccount

addExclusiveAccount

addExclusiveDependent

addExclusiveDependent

addPatchTarget

setPatchThreshold

addRouteHaulAccount

addRouteHaulAccount

addRouteHaulAccount

addRouteHaulAccount

addRouteBuildAccount

addRouteBuildAccount

addRouteBuildAccount

addRouteBuildAccount

addRouteRebuildAccount

addRouteRebuildAccount

addRouteRepairAccount

addRouteRepairAccount

addRouteRepairAccount

addRouteRepairAccount

addRouteProductAccount

addRouteProductAccount

addRouteProductAccount

addRouteProductAccount

addMetaAccount

addMetaAccount

addFlowRatioAccount

addFlowRatioAccount

addFlowRatioAccount

addFlowRatioAccount

addFlowRatioAccount

addFlowValueAccount

addFlowValueAccount

addFlowValueAccount

addTabulateAccount

addRatioAccount

addRatioAccount

addEdgeTarget

addEdgeElement

addGroupDistributionAccount

addGroupDistributionSubAccount

setTreatmentAffinity

getTreatmentNames

initialize

waitUntilInitialized

setInitialValue

interrupt

getAttributeLabels

makeDotFile

makeDotFile

close

getTargetLabels

setTargetLinear

setTargetDiscountRate

getIteration

getPerformanceChart

waitForIterations

waitForProgress

waitForProgress