Show:
Module: ABE

The global variable fmengine (of type FMEngine) variable lets you access the ABE core engine.

Use fmengine to register agents and stand treatment programmes. fmengine also provides some additional functionalities, such as logging (log) or executing functions/activities in the ABE context.

Methods

abort

(
  • message
)

Calling abort stops the execution of ABE and prints the error message message to the console (and shows the error). Note that abort does not interrupt execution of JavaScript code immediately. However, the ABE core engine cancels all further activities, when the abort method has been called.

      if (some_error_condition) {
                              fmengine.abort('This is really not expected!!');
                              return; // required; otherwise do_some_stuff() would be executed.
                          }
                          do_some_stuff();

Parameters:

  • message String

    The error message.

addAgent

(
  • program
  • name
)
Boolean

add an agent definition (Javascript) and gives the agent the name name.

Parameters:

  • program Object

    The javascript object that defines the Agent.

  • name String

    The name that ABE should be use for this Agent.

Returns:

Boolean:

true on success.

Example:

  // define a simple agent
                      var fire_agent = {
                          // scheduler options:
                          scheduler: { enabled: false },
                          // stp is a list of STPs available for the agent
                          stp: {  'fire': 'fire', 'timber':'timber', 'default': 'fire'},
                      };
                    
                      fmengine.addAgent(fire_agent, 'fire'); // add the agent
                    

addAgent

(
  • agent_type_name
  • name
)
Boolean

add an agent by specifying the name of an agent type and gives the agent the name name.

See also: AddAgentType:method

Parameters:

  • agent_type_name String

    The name of the agent type Agent.

  • name String

    The name that ABE should be use for this AddAgentType:method.

Returns:

Boolean:

true on success.

addAgentType

(
  • program
  • name
)
Boolean

add an agent type (and not a specific agent!) by specifying the name of an agent type. The agent type will get the name name. Using an agent type (instead of single agents) allow the creation of multiple agents programmatically (e.g. small landowners). Properties of the generated agents can be refined using the newAgent() handler function of the agent.

Parameters:

  • program Object

    The javascript object that defines the Agent.

  • name String

    The name that ABE should be use for this agent type

Returns:

Boolean:

true on success.

Example:

See also: AddAgentType:method

  // define a agent type template
                      var fire_template = {
                          // scheduler options:
                          scheduler: { enabled: true,
                                       harvestIntensity: 1},
                          // stp is a list of STPs available for the agent
                          stp: {  'fire': 'fire', 'timber':'timber', 'default': 'fire'},
                          newAgent: function() {
                              // this is called whenever a new agent is generated
                              var new_ag = {
                              scheduler: this.scheduler };
                              new_ag.harvestIntensity = 1 + Math.random()*0.5; // sample between 1 and 1.5
                              return new_ag;
                          }
                      };

addManagement

(
  • program
  • name
)
Boolean

adds a management program (STP) whose definition is provided by the Javascript object program. The name of the program is used internally.

See also: Activity

Parameters:

  • program Object

    The javascript object that defines the STP.

  • name String

    The name that ABE should be use for this STP.

Returns:

Boolean:

true on success.

isValidStand

(
  • stand_id
)
Boolean

checks if a given stand_id is valid (i.e., part of the currently simulated area).

Parameters:

  • stand_id Int

    The id of the stand to check.

Returns:

Boolean:

true, if 'stand_id' is a valid stand in the current setup.

log

(
  • message
)

log writes a log message. Each message is prefixed with a code for identifying the current stand and the current year of the simulation. The format of the prefix is: 'S_standid_Y_year_:'.

  fmengine.log('log message for stand ' + stand.id);
                      // produces (in year 0 and for stand 7)
                      abe: "S7Y0:" log message for stand 7

Parameters:

  • message String

    The message to be printed.

runActivity

(
  • standId
  • activity
)
Boolean

runActivity executes an Activity for stand given by standId. This bypasses the normal scheduling (useful for debugging/testing). This function calls the main execution function of the activity.

Parameters:

  • standId Int

    the (integer) id of the stand in which context the activity should be executed.

  • activity String

    the name of the activity that should be executed.

Returns:

Boolean:

returns false if the stand or activity were not found.

runActivity

(
  • standId
  • activity
)
Boolean

runActivityEvaluate executes an Activity for stand given by standId. This bypasses the normal scheduling (useful for debugging/testing). 'runActivityEvaluate' invokes the evaluation code of scheduled activites (e.g., ActThinning, ActScheduled).

Parameters:

  • standId Int

    the (integer) id of the stand in which context the activity should be executed.

  • activity String

    the name of the activity that should be executed.

Returns:

Boolean:

returns false if the stand or activity were not found.

runPlanting

(
  • standId
  • planting
)

Runs a planting activity (without the context of stand treatment programmes). This is especially useful for setting up initial stand conditions. The planting defines the activity according to the syntax of the planting activity.

  // global 'onInit' function is called during startup
                      function onInit() {
                        // run a planting activity for the stand 235 (30cm spruce trees on 90% of the pixels)
                        fmengine.runPlanting( 235, { species: "piab", fraction: 0.9, height: 0.3 });
                      }

Parameters:

  • standId Int

    (integer) of the stand for which a planting activity should be executed.

  • planting Object

    A javascript object with the definition of the planting activity (see ABE documentation).

setUIShortcuts

(
  • A
)

This function adds quicklinks that trigger Javascript functions to the user interface of iLand. Each name-value pair defines one function call (name) and its description (value).

  // call this anywhere (e.g. in the body of the main javascript)
                      Globals.setUIShortcuts( { 'Globals.reloadABE()': 'full reload of ABE', 'test()': 'my dearest test function' } );

Parameters:

  • A Object

    object containt name/value pairs that are used in the iLand UI to create quicklinks for calling javascript functions.

standIds

() Array

returns a list of valid stand-ids within the model. See also: StandId:property

  for (var s of fmengine.standIds) {
                         fmengine.standId = s; // set s to the current stand
                         console.log('Stand ' + s + ': ' + stand.flag('wui')); // print value of the attribute wui for all stands
                      }

Returns:

Array:

Array of valid stand-ids.

updateManagement

(
  • program
  • stp_name
)
Boolean

updates the definition of a STP, i.e. replace the STP stp_name with a new Javascript object program.

If the stp_name is not found, an error is thrown.

See also: Activity

Parameters:

  • program Object

    The javascript object that defines the STP.

  • stp_name String

    The name that ABE should be use for this STP.

Returns:

Boolean:

true on success.

Properties

enabled

Boolean

The enabled property can be used to enable/disable ABE. When false then all management activties are paused.

  // switch management off at a certain simulation year
                      function run() {
                         // run is called by ABE every year
                         if (Globals.year==10)
                            fmengine.enabled = false;
                      }
                      // run() is called from ABE (only if ABE is running). In order to enable ABE use e.g.:
                      function onNewYear() {
                          // is called by iLand at the beginning of every simulation year
                          if (Globals.year==30)
                              fmengine.enabled = true;
                      }

Default: true

standId

Int

standId is the numeric Id of the stand that is set as the current execution context, i.e. the stand, site, etc. variables that are available in the current context refer to the stand with this Id. The property is set automatically by ABE during the execution of forest management. It can, however, be changed by Javascript for debugging/testing purposes. Note that changing the standId might lead to unexpected behavior.

See also: id

Default: -1

verbose

Boolean

ABE generates much more detailed log messages, if verbose is true. This is generally useful for debugging and should be turned off for productive use. Note, that verbose mode can switched on for specfic code sections:

  ....
                      fmengine.verbose = true;
                      ... // do some complicated stuff
                      fmengine.verbose = false; // switch off verbose mode
                    

See also: trace

Default: false