Loading...
 

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.

List of available activities


Javascript API documentation for 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.

PropertyDescription
typeThe name of the activity type. This selects the activity from the library of activities.
scheduleSchedule-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.
constraintConstraint-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.
enabledIfExpression 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.

EventDescription
onCreateFires 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.
onSetupFires separately for each stand. This is the place to specify properties that are specific to a given stand.
onEnterFires, 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.
onEvaluateThis 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.
onExecutedThe onExecuted event is fired after an activity was successfully executed.
onCancelSimilar to “onExecuted”, but this event is fired when the activity was either not executed at all (e.g., expired) or cancelled by user code.
onExitFires 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$).

PropertyDescription
minMinimum stand age for activity.
maxMaximum stand age for activity.
optOptimal point in time for execution of the activity.
minRelEarliest point in time relative to rotation length (e.g. 0.2)
maxRelLatest point in time relative to rotation length (e.g. 0.4)
optRelOptimal execution time (relative to rotation length).
repeatIntervalWhen “repeat” is true, the repeatInterval provides the lag between two executions of the activity.
forceBoolean. If true, then the activity will be triggered, if it has not been executed at the defined maximum age (max or maxRel).
repeatBoolean. If true, the activity will be automatically repeated every “repeatInterval” years. Default is false. First start: between min and max???
absoluteBoolean. 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.