Name

objective — The methods in this file are useful for setting up scenario automation using ScenarioSets.

Overview

The methods in this file are useful for setting up scenario automation using ScenarioSets.

The objective function will help to create a TargetDescription object and associated metadata. TargetDescription objects can be provided to the ScenarioSet addScenario method to specify the targets to activate.

The annualObjective and periodicObjective methods are used to specify accounts and target values, and these objects are passed as parameters to the objective method.

Here is an example of the declaration and use of objectives and how they can be added to a ScenarioSet:

 // Maximum harvest
 objs = new Object[] {
    annualObjective("SPF", 120000, 1, null, null).linear(true),
    annualObjective("Birch", 100000, 1, null, null).linear(true),
    annualObjective("Aspen", 30000, 1, null, null).linear(true)
 };
 primaryHarvest = objective("Harvest by species groups", 
 			   objs, "product.Spg.", "Harvest_Level");
 
 // Evenflow harvest, using ArrayList to collect objectives
 objs = new ArrayList();
 objs.add(annualObjective("SPF", 0, 5000, 0, 5000));
 objs.add(annualObjective("Birch", 0, 5000, 0, 5000));
 objs.add(annualObjective("Aspen", 0, 5000, 0, 5000));
 primaryFlow = objective("Primary even flow harvest", 
 			objs.toArray(), "flow.even.product.Spg.", 
 			"Harvest_Flow");
  
 // Create a ScenarioSet
 s = new ScenarioSet(0.05, 400000,
                     2000000, false,
 	             null, null, null);
 
 s.addScenario("scenarios/Base_maxEven", "Base model max even flow",
               new TargetDescription[] {
 		   primaryHarvest,
 		   primaryFlow
               });
 
 // Conditionally run the scenario
 if (s.showMenu())
     s.run();

In addition to the parameters that can be used to create the annualObjective and periodicObjective objects, there are several methods that can modify target behaviour:

MethodPurpose
linear(boolean)Set linear or non-linear scaling. The default value is false (non-linear scaling).
discount(float)Set a discount rate. The default value is 1 (no discounting).
premultiply(boolean)Pre-multiply the penalty weight before applying non-linear scaling to the deviation. The default value is false (do not premultiply weights before applying non-linear scaling to deviations).

These methods return the object, and so may be chained together in a compact fluent coding style. For example

    annualObjective("Aspen", 30000, 1, null, null).linear(true).discount(1.02)

Syntax

objective ( String title , Object [ ] specs , String prefix , String category ) 

The command has the following arguments:

title

A title to describe the purpose of these targets.

specs

A list of annualObjective and periodicObjective objects that specify the accounts and targets levels that should be activated for this TargetDescription.

prefix

The account name prefix that should be prepended to each target in the list of annualObjective and periodicObjectives.

category

A label that specifies the category of this TargetDescription. The ScenarioSet object will prevent duplicate categories from being added to a scenario.

Description

Create a TargetDescription object and associated metadata. This object can be passed to the addScenario method of a ScenarioSet object. The target names and setting will be neatly formatted and added to the TargetDescription metatdata.

The TargetDescription object will implement the apply(), activate() and deactivate() methods. apply() will set and activate the targets according to the specifications. activate() and deactivate() will turn the targets on and off.

Return value

A TargetDescription object, suitable to use as a parameter to ScenarioSet addScenario method.

Syntax

annualObjective ( String label , Double minTarget , Double minWeight , Double maxTarget , Double maxWeight ) 

The command has the following arguments:

label

The account label. This label is prepended with the prefix value specified in the objective method to construct a unique account name.

minTarget

The minimum annual target value to apply. Specify 'null' if the minmum target should not be active.

minWeight

The penalty value to apply to the minimum target value.

maxTarget

The maximum annual target value to apply. Specify 'null' if the maxmum target should not be active.

maxWeight

The penalty value to apply to the maximum target value.

Description

The annualObjective method creates a specification consisting of the name of an account, and the target settings and weight values that are to be applied. The target values are set for all periods.

Syntax

annualObjective ( String label , Double minTarget , Double minWeight , Double maxTarget , Double maxWeight , int start , int end ) 

The command has the following arguments:

label

The account label. This label is prepended with the prefix value specified in the objective method to construct a unique account name.

minTarget

The minimum annual target value to apply. Specify 'null' if the minmum target should not be active.

minWeight

The penalty value to apply to the minimum target value.

maxTarget

The maximum annual target value to apply. Specify 'null' if the maximum target should not be active.

maxWeight

The penalty value to apply to the maximum target value.

start

The starting period to use for the range of periods that the target should be applied to.

end

The ending period to use for the range of periods that the target should be applied to.

Description

The annualObjective method creates a specification consisting of the name of an account, and the target settings and weight values that are to be applied. The target values are set for the specified periods.

Syntax

periodicObjective ( String label , Double minTarget , Double minWeight , Double maxTarget , Double maxWeight ) 

The command has the following arguments:

label

The account label. This label is prepended with the prefix value specified in the objective method to construct a unique account name.

minTarget

The minimum periodic target value to apply. Specify 'null' if the minmum target should not be active.

minWeight

The penalty value to apply to the minimum target value.

maxTarget

The maximum periodic target value to apply. Specify 'null' if the maxmum target should not be active.

maxWeight

The penalty value to apply to the maximum target value.

Description

The periodicObjective method creates a specification consisting of the name of an account, and the target settings and weight values that are to be applied. The target values are set for all periods.

Syntax

periodicObjective ( String label , Double minTarget , Double minWeight , Double maxTarget , Double maxWeight , int start , int end ) 

The command has the following arguments:

label

The account label. This label is prepended with the prefix value specified in the objective method to construct a unique account name.

minTarget

The minimum periodic target value to apply. Specify 'null' if the minmum target should not be active.

minWeight

The penalty value to apply to the minimum target value.

maxTarget

The maximum periodic target value to apply. Specify 'null' if the maxmum target should not be active.

maxWeight

The penalty value to apply to the maximum target value.

start

The starting period to use for the range of periods that the target shoud be applied to.

end

The ending period to use for the range of periods that the target shoud be applied to.

Description

The periodicObjective method creates a specification consisting of the name of an account, and the target settings and weight values that are to be applied. The target values are set for the specified periods.

Syntax

void objective ( ) 

Description

Print objective function value to the console. This is a legacy function that has been preserved for backwards compatibility.