# ABE activities

An activity is the basic silvicultural building block. It describes the “when” and “what” if an activity should be exeecuted. There are several types of activities, but they all share a basic set of properties (which are described here).
Activities are the core element of forest management in ABE, as they are the elements that actually change the forest state in the ecosystem model by removing or planting trees. ABE provides a library of pre-defined activities that cover the most important aspects of forest management. Yet, the activity library can be easily extended by providing user-defined activities. Activities are fetched from the library by specifying the name of the activity type and by further defining the properties of the activity.

## General layout

An activity is a Javascript object, with a number of pre-defined properties, that can be further enriched. The type of activity is selected by setting the $type$ property (see above for available activity types). The $schedule$ sub-object informs ABE about the timing of the activity, and the $constraint$ object defines conditions that prevent activity execution if not met. Each activity type defines further properties that are described on the respective pages.

 Property Description type The name of the activity type. This selects the activity from the library of activities. schedule Schedule-object. The schedule-object defines the planned execution date of an activity. The optimal (as well is minimum and maximum) execution date can be defined, either absolute (e.g., between a stand age of 40 and 50 years, optimally at age 45), or relative to the length of the rotation period (e.g., a final cut at age 1.0*rotation age, no thinning later than 0.5*rotation age). The schedule thus defines a time window within which the scheduler algorithm selects an appropriate execution time. constraint Constraint-object. A constraint-object. Provides a list of constraints, i.e., circumstances that prohibit the execution of the activity. For example, thinnings could be delayed until a specific stand height is reached. enabledIf Expression that can be used to dynamically link the state of an activity to some other property; for instance, an activity can be made only active, if the agent demands a specific thinning intensity.

The block below gives an schematic example of how an activity definition looks like:

var activity  =  {
type: <name of the activity>,
schedule: <object defining the requested execution time>,
constraint: < optional conditions that may inhibit execution >,
enabledIf: < optional activation of activity based on some condition >
…: <activity specific definitions>
…: <events>
}

## Events

The Activities of the iLand management system provide an “Events” mechanism that works much like similar event concepts e.g. in internet browsers. Essentially, it allows to use javascript code for reacting to changes (“events”) in the underlying system, or to modify default behaviour, e.g. during the initialization phase. All activity types share a set of event types that is enriched by specific events for some activity types. The table below gives a list of events that are available for all activities.

 Event Description onCreate Fires when the activity is created without the context of a specific stand. This can be used to change properties of the activity that are valid for all stands. onSetup Fires separately for each stand. This is the place to specify properties that are specific to a given stand. onEnter Fires, when an activity becomes the “current” activity for a stand. The event is also fired, when the activity is assigned as the initial activity during startup. onEvaluate This event is fired immediately before an activity is transferred to the scheduler (only applicable for scheduled activities). The activity can be canceled by returning false from the event. onExecuted The onExecuted event is fired after an activity was successfully executed. onCancel Similar to “onExecuted”, but this event is fired when the activity was either not executed at all (e.g., expired) or cancelled by user code. onExit Fires when the scope of the activity is left, i.e. after execution/expiration of the activity or if the activity is programmatically changed.

Events are added to an activity by simple providing a correctly named Javascript function in the activity definition. Note the syntax for adding Javascript functions to a Javascript object:

function-name: function(<parameters>) { <function defintion> }

Example events
var activity = { type: "general",
...
// the onEnter event is called when the activity becomes active for a stand
onEnter: function() { fmengine.log('entered activity for stand ' + stand.id)},
....
}

## Schedule object

The Schedule object describes the “when” of an activity. The scheduling of an activity can be defined as a specific point in time, or a as “window of opportunity”. Points in time are always given in years and may either be given in “years since stand establishment” (i.e., stand age) or in absolute terms (e.g., in simulation year 20). Furthermore, dates are provided either absolute ($min$, $max$, $opt$) or relative to the rotation length ($minRel$, $maxRel$, $optRel$).

 Property Description min Minimum stand age for activity. max Maximum stand age for activity. opt Optimal point in time for execution of the activity. minRel Earliest point in time relative to rotation length (e.g. 0.2) maxRel Latest point in time relative to rotation length (e.g. 0.4) optRel Optimal execution time (relative to rotation length). repeatInterval When “repeat” is true, the repeatInterval provides the lag between two executions of the activity. force Boolean. If true, then the activity will be triggered, if it has not been executed at the defined maximum age (max or maxRel). repeat Boolean. If true, the activity will be automatically repeated every “repeatInterval” years. Default is false. First start: between min and max??? absolute Boolean. If true, all provided dates are interpreted as absolute (e.g. 2020). If false (the default), all numbers are interpreted as relative to the rotation, e.g. 20 would be 20 years after stand establishment.

Short form:
If the schedule property is only a single number, it is interpreted as the “opt” property.

### Constraint object

Using constraints, the execution of management activities can be restricted. For example, a thinning operation may only be applied if the respective stand reached already a certain minimum timber volume. The constraint property can be either a single constraint or an array of constraints. If an array of constraints is provided, all constraints must “pass” in order to allow the execution of the activity.
Each constraint can either be an expression or a Javascript function, both should return a Boolean value (true or false). Note that expressions must be provided as strings (i.e. enclosed by ‘’ or “”).
“Expressions” make use of the built-in expression engine of iLand and can be used with very little overhead. Javascript functions, on the other hand, execute slower but provide more flexibility. All stand, site and agent variables are available for both cases.

Example code for constraints
// single constraint (expression)
constraint: “stand.volume>100”
// array (list) of constraints, mixing expressions and JS
constraint: [‘stand.hmean > 12 and stand.volume>250', function(){return stand.hmean>10;}]

citation

Rammer, W., Seidl, R., 2015. Coupling human and natural systems: Simulating adaptive management agents in dynamically changing forest landscapes. Global Environmental Change, 35, 475-485.

Created by werner. Last Modification: Tuesday 08 of November, 2016 14:26:54 CET by werner.