Class: FMEngine

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.

Properties Overview

Name Type Description
active boolean The active property indicates whether an activity can still be executed during this rotation. After an activity is executed,
enabled boolean The enabled property can be used to enable/disable ABE. When false then all management activties are paused.
enabled boolean An activity can only be executed, if the enabled property is true. Activities can be switched on/ off using this flag.
finalHarvest boolean An activity with finalHarvest=true ends a rotation when (successfully) executed. This resets the [age](stand.qmd#age)
name string (read-only) The name of the activity as provided in the definition of the activity.
name string (read-only) The name of the stand treatment program as provided when called the respecitve ‘fmengine’ functions.
obj Javascript The obj is a general purpose javascript entity that is stored for an activity.
options object The ‘options’ property provides a link to the ‘options’ property of the STP definition, i.e., this is a mechanism
scheduled boolean This flag indicates whether the Scheduler is used when this activity is run, i.e. if the
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
verbose boolean ABE generates much more detailed log messages, if verbose is true. This is generally useful for debugging and

Methods Overview

Method Return Type Description
abort(message) void 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
addAgent(program) boolean add an agent definition (Javascript) and gives the agent the name name.
addAgent(agent_type_name) boolean add an agent by specifying the name of an agent type and gives the agent the name name.
addAgentType(program) boolean add an agent type (and not a specific agent!) by specifying the name of an agent type. The agent type
addManagement(program) boolean adds a management program (STP) whose definition is provided by the Javascript object program. The name of the program is used internally.
isValidStand(stand_id) boolean checks if a given stand_id is valid (i.e., part of the currently simulated area).
log(message) void log writes a log message. Each message is prefixed with a code for identifying the current stand and the current year of the simulation.
runActivity(standId) boolean runActivity executes an Activity for stand given by standId. This bypasses the normal scheduling (useful for debugging/testing).
runActivityEvaluate(standId) boolean runActivityEvaluate executes an Activity for stand given by standId. This bypasses the normal scheduling (useful for debugging/testing).
runPlanting(standId) void Runs a planting activity (without the context of stand treatment programmes). This is especially useful for
setUIShortcuts(A) void This function adds quicklinks that trigger Javascript functions to the user interface of iLand. Each name-value pair
standIds() array returns a list of valid stand-ids within the model.
updateManagement(program) boolean updates the definition of a STP, i.e. replace the STP stp_name with a new Javascript object program.

Properties Details

active

boolean

The active property indicates whether an activity can still be executed during this rotation. After an activity is executed, the active flag is set to false, and the next active (and enabled) activity is selected. At the end of a rotation, the active flag of all activities of the programme are set back to true. By changing the value of active, activities can be either removed from the current rotation, or re-enabled.

    //re-enable the 'todo' activity.
    stand.activity("todo").active = true;

See also: enabled

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;
    }

enabled

boolean

An activity can only be executed, if the enabled property is true. Activities can be switched on/ off using this flag.

Note that an activity needs also to be [active](activity.qmd#active) in order to get executed.

    // switch off a repeating activity, when a height threshold is surpassed.
    if (stand.hmean>12)
        stand.activity('repeater').enabled = false;

See also: active

finalHarvest

boolean

An activity with finalHarvest=true ends a rotation when (successfully) executed. This resets the [age](stand.qmd#age) counter and sets all activites [active](activity.qmd#active).

name

string ReadOnly

The name of the activity as provided in the definition of the activity.

See also: fmengine.addManagement

name

string ReadOnly

The name of the stand treatment program as provided when called the respecitve ‘fmengine’ functions.

  See also: [fmengine.addManagement](fmengine.qmd#addmanagement)

obj

Javascript

The obj is a general purpose javascript entity that is stored for an activity.

Note that obj can hold arbitrary Javascript objects, including data structures and functions.

See also: obj.

options

object

The ‘options’ property provides a link to the ‘options’ property of the STP definition, i.e., this is a mechanism that can be used to pass purely javascript options/values to other javascript code (e.g., when an activity within the stand context is executed). Note that the C++ part of ABE does not interfere with these options.

            // definition of the STP
            var stp: { U: [110, 130, 150], // define the rotation period
                clearcut: a_clearcut, // some activities
                options: { dbh: 5, someOtherParameter: 50}
            }

            // definition of activities… here the ‘dbh’ options is used
            // in the Javascript code to select trees to harvest.
            var a_clearcut: {
               type: "scheduled", … ,
               onEvaluate: function() {
                        trees.loadAll();
                        trees.harvest("dbh>" + stp.options.dbh );}
                     }
            };

scheduled

boolean

This flag indicates whether the Scheduler is used when this activity is run, i.e. if the exact date of execution is selected by the scheduling algorithm of ABE. The default value depends on the type of the activity, e.g., default is false for activities of type general, but true for scheduled activities.

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

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

Methods Details

abort(message)

Returns: void

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)

Returns: boolean

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

Parameters:

  • program (object): The javascript object that defines the Agent. @param {string} name The name that ABE should be use for this Agent. @return {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

Return Value Description: 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

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)

Returns: boolean

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

See also: [addAgentType:method](addagenttype:method.qmd)

Parameters:

  • agent_type_name (string): The name of the agent type Agent. @param {string} name The name that ABE should be use for this addAgentType:method. @return {boolean} true on success.

Return Value Description: true on success.

addAgentType(program)

Returns: 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. @param {string} name The name that ABE should be use for this agent type @return {boolean} true on success.

@example

    // 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;
        }
    };

Return Value Description: true on success.

@example

    // 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;
        }
    };

Example:

See also: {{#crossLink "addAgentType:method"}}{{/crossLink}}

  @method addAgentType
  @param {object} program The javascript object that defines the {{#crossLink "Agent"}}{{/crossLink}}.
  @param {string} name The name that ABE should be use for this agent type
  @return {boolean} true on success.


  @example

        // 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)

Returns: 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. @param {string} name The name that ABE should be use for this STP. @return {boolean} true on success.

Return Value Description: true on success.

isValidStand(stand_id)

Returns: 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. @return {boolean} true, if ‘stand_id’ is a valid stand in the current setup.

Return Value Description: true, if ‘stand_id’ is a valid stand in the current setup.

log(message)

Returns: void

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)

Returns: 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. @param {string} activity the name of the activity that should be executed. @return {boolean} returns false if the stand or activity were not found.

Return Value Description: returns false if the stand or activity were not found.

runActivityEvaluate(standId)

Returns: 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. @param {string} activity the name of the activity that should be executed. @return {boolean} returns false if the stand or activity were not found.

Return Value Description: returns false if the stand or activity were not found.

runPlanting(standId)

Returns: void

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. @param {object} planting A javascript object with the definition of the planting activity (see ABE documentation).

setUIShortcuts(A)

Returns: void

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()

Returns: 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
    }

Return Value Description: Array of valid stand-ids.

updateManagement(program)

Returns: 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. @param {string} stp_name The name that ABE should be use for this STP. @return {boolean} true on success.

Return Value Description: true on success.