FMEngine Class
ABE\abe_context_doc.js:2
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.
Item Index
Methods
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
StringThe error message.
addAgent
-
program
-
name
add an agent definition (Javascript) and gives the agent the name name
.
Parameters:
Returns:
true on success.
addManagement
-
program
-
name
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
ObjectThe javascript object that defines the STP.
-
name
StringThe name that ABE should be use for this STP.
Returns:
true on success.
isValidStand
-
stand_id
checks if a given stand_id
is valid (i.e., part of the currently simulated area).
Parameters:
-
stand_id
IntThe id of the stand to check.
Returns:
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
StringThe message to be printed.
runActivity
-
standId
-
activity
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
Intthe (integer) id of the stand in which context the activity should be executed.
-
activity
Stringthe name of the activity that should be executed.
Returns:
returns false if the stand or activity were not found.
runActivity
-
standId
-
activity
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
Intthe (integer) id of the stand in which context the activity should be executed.
-
activity
Stringthe name of the activity that should be executed.
Returns:
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
ObjectA 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
Objectobject 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
Returns:
Array of valid stand-ids.
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