Class: Globals

The Globals object exposes a series of auxiliary functions to the scripting context. An instance of “Globals” is always available in the global context, so no explicit creation is necessary. The provided function cover inter alia:

handling of directories and simple text files
access to XML settings
access and control over Outputs
miscellaneous functions (e.g., for making screeshots)

Global functions

In addition to the functions provided by the Globals object, there are a number of (truly) global helper functions available. They are:

print(x): prints x (see Globals.print() and console.log())
include(source_file): loads a Javascript code file source_file and runs the code. Can be useful to load “libraries”. (See Globals.include()).
alert(message): shows a message box with the text message and stops until user clicks Ok. (See Globals.alert())
printObj(obj): helper function to pretty print an object to the console.

Handling of exceptions

Some functions throughout the iLand API “throw errors”. Unhandled, a message box shows the error and iLand stops running. You can, however, also handle these errors programmatically, i.e. “catch” them and continue with the execution of the model. Here is an example:

// not handled: this throws an error that the setting key is not valid.
let x = Globals.setting("mr.james.bond");

// handled using a try/catch block
try {
let x = Globals.setting("mr.james.bond");
} catch (error) {
    console.log(error);
}

Properties Overview

Name	Type	Description
`currentDir`	`any`	gets or sets the current directory of iLand. Relative paths are resolved relative to the `currentDir`.
`msec`	`any`	The milliseconds since the start of the day.
`resourceUnitCount`	`integer` (read-only)	The number of resource units in the current simulation.
`viewOptions`	`any`	`viewOptions` allow some control over the visualization of the landscape in the iLand GUI. The `viewOptions` is an object with the following elements:
`worldX`	`any`	extent of the world (without buffer) in meters (x-direction).
`worldY`	`any`	extent of the world (without buffer) in meters (y-direction).
`year`	`any` (read-only)	The current year of the simulation.

Methods Overview

Method	Return Type	Description
`addSaplings()`	`integer`	add sapling on a metric rectangle given with `width` and `height` at x/y.
`addSaplingsOnMap()`	`integer`	add sapling on a stand defined by a (spatial) map
`addSingleTrees()`	`integer`	Add single trees on a specific resource unit with the 0-based index `resourceIndex`.
`addTrees()`	`integer`	Add trees distribution on a specific resource unit with the 0-based index `resourceIndex`.
`addTreesOnMap()`	`integer`	Add trees distribution on a specific stand described by the `standID`.
`alert(message)`	`void`	shows a message box to the user (only available with iLand GUI) and halts execution until the user clicks OK.
`debugOutputFilter()`	`void`	can be used to limit the amount of debug output that is generated on resource unit level. If the
`defaultDirectory()`	`string`	Get directory with of the given category `category`. See filenames and paths for available categories.
`fileExists()`	`boolean`	Check if the file `file_name` already exists.
`grid(type)`	`Grid`	extract a grid of type `type` from iLand. The extracted grid is a floating point grid (double precision) and
`gridToFile(grid_type, file_name, height_level)`	`boolean`	Creates a grid file from an iLand grid either as ESRI style or
`include(name)`	`void`	Includes / runs a Javascript file. The file is loaded and evaluated in the current Javascript context. `include` is useful for loading additional
`loadModelSnapshot()`	`boolean`	loads a snapshot database (created with a previous call to saveModelSnapshot()).
`loadTextFile()`	`string`	Load the content of a text file into a string. Throws an error if the file does not exist.
`path()`	`string`	Use `path()` to construct a path relative to the project directory. Useful for avoiding absolute file paths in Javascript.
`print(message)`	`void`	print the contents of the message to the log. In iLand GUI the message is also printed to the screen even if a logfile is specified.
`random()`	`double`	Return a random number between `from` and `to`. This function uses the iLand internal random number generation process
`reloadABE()`	`void`	Completely reloads the ABE (agent based management engine) sub module. This includes loading of the (static) stand description file,
`repaint()`	`void`	force a repaint of the GUI main visualization area.
`resourceUnitGrid(expression)`	`Grid`	Return a grid (resolution of resource units) with the result of an `expression`
`saveDebugOutputs()`	`void`	forces writing of debug outputs from the internal buffer of iLand to disk.
`saveModelSnapshot()`	`boolean`	creates a snapshot from the current state of the model. `file_name` is the path to the target database, which is created if the database file does not exist
`saveTextFile()`	`boolean`	Save the content of a string `content` to a file.
`screenshot(file_name)`	`boolean`	make a screenshot from the central viewing widget (as if pressing Ctrl+P in the iLand viewer) and stores the image to the provided file `file_name`.
`seedMapToFile(species, file_name)`	`boolean`	Creates a ESRI style grid file from the seed map for a given species.
`set(key)`	`boolean`	Set a setting in the project file with the key `key` to a value of `value`.
`setUIshortcuts(shortcuts)`	`void`	This is a helper function that allows to add shortcut links to the ‘Scripting’ panel in the iLand Viewer user interface.
`setting(key)`	`void`	Read a value from the project file. The `key` is the full path to the
`speciesShareGrid(species)`	`Grid`	Return a grid with the basal area of the given `species` (resource unit resolution, i.e. 100m).
`startOutput()`	`boolean`	starts the output `table_name`. The table name for each output can be found on the output wiki page.
`stopOutput()`	`boolean`	stops the output `table_name`. The table name for each output can be found on the output wiki page.
`systemCmd()`	`string`	Execute a system command (e.g., for copying files). Commands are operating system dependent; For windows,
`wait(milliseconds)`	`void`	Pause model execution for `milliseconds` ms. This can be useful to slow down animations.

Properties Details

`currentDir`

any

gets or sets the current directory of iLand. Relative paths are resolved relative to the currentDir.

Example (Project-file: “c:.xml”): Globals.path(‘temp/filexy.txt’) -> “c:.filexy.txt”

`msec`

any

The milliseconds since the start of the day.

// simple timer functions:
    var _elapsed=-1;
    function start_timer() { _elapsed = Globals.msec; }
    function elapsed(thingi)
    {
        var elapsed=Globals.msec - _elapsed;
        _elapsed = Globals.msec;
        console.log("Time: " + thingi + ": " + elapsed + "ms");
    }

    // use timers:
    start_timer();
    // do some lengthy operation x
    elapsed("x"); // prints time elapsed since start_timer()
    // some other lenghty operation y
    elapsed("y"); // print duration of 'y' in ms

`resourceUnitCount`

integer ReadOnly

The number of resource units in the current simulation.

`viewOptions`

any

viewOptions allow some control over the visualization of the landscape in the iLand GUI. The viewOptions is an object with the following elements:

minValue and maxValue: the value range of the visualization; if not present, the value range of the ruler is automatically scaled
type: defines the type of visualization, and is one of the following:
- lif: the ‘Light Influence Field’ (2m)
- dom: the dominant height (10m)
- regeneratation: saplings/regeneration (2m)
- seed: seed availability (20m)
- trees: individual trees
- ru: resource units (1ha)
clip: boolean ; if true, grids are clipped to the height grid (i.e. white for out-of-project-areas) (not supported for all visualizations)
transparent: boolean; if true, trees are drawn semi-transparent
species
- boolean value in single tree mode: if true, draw trees using species colors (true)
- a species short name (e.g. ‘piab’): select this species, e.g. for seed availability per species, or species shares
grid: draw one of the dynamic grids layers from active sub modules (check the possible names either in iLand or in the wiki)
expression: provides a expression that can be evaluated for trees or for resource unit (depending on the type)
filter: expression that is used to filter trees (useful for showing only a subset of trees)

This option is not available in the iLand console version.

Globals.viewOptions = { type: 'trees', species: true };
        var vo = Globals.viewOptions;
        vo.filter = 'dbh<10';
        Globals.viewOptions = vo;
        Globals.repaint();

`worldX`

any

extent of the world (without buffer) in meters (x-direction).

`worldY`

any

extent of the world (without buffer) in meters (y-direction).

`year`

any ReadOnly

The current year of the simulation.

Methods Details

`addSaplings()`

Returns: integer

add sapling on a metric rectangle given with width and height at x/y. if a standId is provided (-1 or 0: no stand), x/y is relative to the lower left edge of the stand rectangle. If no stand is provided, x/y are absolute (relative to the project area). returns the number of successfully added sapling cells

Return Value Description: the number of saplings trees

Example:

// this function creates gaps of fixed sizes on a fixed location relative to a position given by dx/dy
    function createPattern4x4(id, dx, dy) {
        var beech = true;
        // (1) remove saplings...
        Globals.removeSaplings(-1,dx-20,dy-20,40,40);
        // (2) ... and trees
        trees.loadAll();
        trees.simulate = false;
        console.log('createPattern4x4: stand ' + id + ', N=' + trees.count);
        trees.filter("mod(x,100)>29 and mod(x,100)<71 and mod(y,100)>29 and mod(y,100)<71");
        console.log('createPattern4x4: stand ' + id + ', Nafter=' + trees.count);
        trees.kill();
        // (3) plant saplings into the created gaps; actually, create alternating 10x10m cells with Silver fir and beech.
        for (var ix=0;ix<4;++ix) {
            for (var iy=0;iy<4;++iy) {
                Globals.addSaplings(-1, dx-20 + 10*ix, dy-20 + 10*iy, 8,8, (beech?"abal":"fasy"), 0.25, 4);
                beech = !beech; // flip between beech and silver fir
                //console.log('createPattern4x4: ' + id + ', x: ' + dx +  ', y: ' + dy );
            }
        }
    }

`addSaplingsOnMap()`

Returns: integer

add sapling on a stand defined by a (spatial) map if a standId is provided (-1 or 0: no stand), x/y is relative to the lower left edge of the stand rectangle. If no stand is provided, x/y are absolute (relative to the project area). returns the number of successfully added sapling cells

Return Value Description: the number of saplings trees

`addSingleTrees()`

Returns: integer

Add single trees on a specific resource unit with the 0-based index resourceIndex. The tree list is in the string content and follows the single-tree syntax described in the wiki.

Return Value Description: the number of added trees.

`addTrees()`

Returns: integer

Add trees distribution on a specific resource unit with the 0-based index resourceIndex. The tree list is in the string content and follows the distribution-tree syntax described in the wiki.

Return Value Description: the number of added trees.

`addTreesOnMap()`

Returns: integer

Add trees distribution on a specific stand described by the standID. The stand is defined in the global stand grid. The tree list is in the string content and follows the distribution-tree syntax described in the wiki.

Return Value Description: the number of added trees.

`alert(message)`

Returns: void

shows a message box to the user (only available with iLand GUI) and halts execution until the user clicks OK.

Note: The global function alert() is a short-cut to Globals.alert().

Parameters:

message (string): message to show as a string

`debugOutputFilter()`

Returns: void

can be used to limit the amount of debug output that is generated on resource unit level. If the function is called with a list of resource unit indices, then only RUs within the list produce debug output. Output is deactivated for all other resource units (a call with an empty list effectively disables the output).

Effective for debug outputs on resource unit level and partiucularly useful for outputs with daily resolution (e.g., daiyle water cycle, daily species response).

`defaultDirectory()`

Returns: string

Get directory with of the given category category. See filenames and paths for available categories. Using this defaultDirectory() avoids absolute file paths in scripts.

`fileExists()`

Returns: boolean

Check if the file file_name already exists.

Return Value Description: true if the file already exists

`grid(type)`

Returns: Grid

extract a grid of type type from iLand. The extracted grid is a floating point grid (double precision) and a copy of the current state in iLand (memory is freed automatically during Javascript garbage collection).

The grid has a cell size of 10m or 100m (depending on the type) and covers the full extent of the model.

The available grid types with 10m resolution are: + height: dominant tree height (m) + count: number of living trees (>4m height) on each pixel + standgrid the internal standgrid of iLand (see https://iland-model.org/landscape+setup#Setting_up_the_stand_grid) + valid: pixels inside the project area get a value of 1, pixels non within the project area 0 (see wiki page) + forestoutside: 1 if a pixel is out of project area and is considered to be forested (see wiki page)

The available grid types with 100m resolution are: + smallsaplingcover: the fraction of the area which is covered by small saplings (<=1.3m) OR grass cover (0..1). (Note: RUs with non-stockable area have always a value <1). + saplingcover: the fraction of the area which is covered by saplings (with a height >1.3m) (0..1). (Note: RUs with non-stockable area have always a value <1). + swc: mean annual water content (mm) over the full year + swc_gs: mean annual water content (mm) during the growing season (fixed month April - September) + swc_pot: field water capacity (mm) of the resource unit (potential water content)

`gridToFile(grid_type, file_name, height_level)`

Returns: boolean

Creates a grid file from an iLand grid either as ESRI style or GeoTIF (when the file ends with .tif or .TIF).

Specify the target file name with file_name and the type of the source grid with the string grid_type.

The avaialable grid_types are: lif: the basic LIF grid of iLand (2m resolution) height: the height grid (10m resolution) of iLand (top tree heights) lifc: a height-corrected LIF with 10m resolution. Calculated as mean LIF value over 10m, and height corre

`include(name)`

Returns: void

Includes / runs a Javascript file. The file is loaded and evaluated in the current Javascript context. include is useful for loading additional code (e.g., library style scripts), or several management programs in ABE, or several agents in BITE.

Note: The global function include() is a short-cut to Globals.include().

Parameters:

name (string): of the Javascript file to include (path relative to the project root)

Example:

// File 1
    include('scripts/file2.js');
    print(a); // prints "defined in file2"

    // file2.js:
    var a = "defined in file2";
    // some other stuff

`loadModelSnapshot()`

Returns: boolean

loads a snapshot database (created with a previous call to saveModelSnapshot()). The model must be already created (i.e. resource units, …); exisiting trees are removed and replaced by the trees from the database.

`loadTextFile()`

Returns: string

Load the content of a text file into a string. Throws an error if the file does not exist.

Return Value Description: the content of the file or an empty text if file does not exist/is empty.

`path()`

Returns: string

Use path() to construct a path relative to the project directory. Useful for avoiding absolute file paths in Javascript.

Example (Project-file: “c:.xml”): Globals.path(‘temp/filexy.txt’) -> “c:.filexy.txt”

See also: defaultDirectory, currentDirectory

Return Value Description: fully qualified file path

`print(message)`

Returns: void

print the contents of the message to the log. In iLand GUI the message is also printed to the screen even if a logfile is specified. In addition to the iLand print() function also the built-in Javascript object console can be used (e.g. console.log(); see https://developer.mozilla.org/de/docs/Web/API/Console).

Note: The global function print() is a short-cut to Globals.print().

Parameters:

message (string): message to print as a string

`random()`

Returns: double

Return a random number between from and to. This function uses the iLand internal random number generation process and respects a global random seed. With other words: Using the Javascript Math.random() does not guarantee the same sequence of numbers, even when a global random seed is set (and multithreading is disabled)

Return Value Description: the random number

`reloadABE()`

Returns: void

Completely reloads the ABE (agent based management engine) sub module. This includes loading of the (static) stand description file, and the javascript source code of ABE.

`repaint()`

Returns: void

force a repaint of the GUI main visualization area.

`resourceUnitGrid(expression)`

Returns: Grid

Return a grid (resolution of resource units) with the result of an expression (Expression) evaluated in the context of the resource unit (see the wiki for a list of available variables).

Parameters:

expression (string): Expression to evaluate for each resource unit

Return Value Description: a Javascript Grid

`saveDebugOutputs()`

Returns: void

forces writing of debug outputs from the internal buffer of iLand to disk.

See also: startOutput(), https://iland-model.org/Debug+Outputs

`saveModelSnapshot()`

Returns: boolean

creates a snapshot from the current state of the model. file_name is the path to the target database, which is created if the database file does not exist (paths relative to the home directory). The wiki provides details about snapshots.

`saveTextFile()`

Returns: boolean

Save the content of a string content to a file.

Return Value Description: true on success.

`screenshot(file_name)`

Returns: boolean

make a screenshot from the central viewing widget (as if pressing Ctrl+P in the iLand viewer) and stores the image to the provided file file_name. The image type depends on the extension provided with file_name. Default path is the home directory.

Parameters:

file_name (string): file name that

Return Value Description: true on success.

Example:

// make a screenshot every 5 years
    function screenshot() {
       if (Globals.year % 5 == 0)
          Globals.screenshot( Globals.defaultDirectory('temp') + 'image_' + Globals.year + '.png' );
    }

`seedMapToFile(species, file_name)`

Returns: boolean

Creates a ESRI style grid file from the seed map for a given species. The functions causes the creation of a raster file for ‘species’ the next time seed dispersal is calculated. species is the species-id (e.g., ‘piab’, ‘fasy’), and file_name the destination location of the grid file ESRI ASCII raster. The saved seed map contains the seed distribution on 20m resolution. Seed maps are only saved once, i.e. if a time series of seed maps is needed, seedMapToFile() need to be called periodically.

Parameters:

species (string): species code to export (e.g., ‘piab’)
file_name (string): target file path (relative to the home directory)

Return Value Description: true on success.

Example:

// save maps for scots pine and beech
    Globals.seedMapToFile('pisy', 'temp/map_pisy.asc');
    Globals.seedMapToFile('fasy', 'temp/map_fasy.asc');
    // now run the model, at least for one year
    // files are created during model execution

`set(key)`

Returns: boolean

Set a setting in the project file with the key key to a value of value. The key is the full path to the requested node using a ‘.’-notation.

`setUIshortcuts(shortcuts)`

Returns: void

This is a helper function that allows to add shortcut links to the ‘Scripting’ panel in the iLand Viewer user interface. shortcuts is a object with name/value pairs, where the value is the string displayed in iLand, and name the Javascript function call (as a string).

Parameters:

shortcuts (object): Javascript object that defines named Javascript calls

Example:

Globals.setUIshortcuts({ 'kyrill()': 'run the kyrill storm',
                     'emma_paula()': 'run the emma/paula storms' }) ;

`setting(key)`

Returns: void

Read a value from the project file. The key is the full path to the requested node using a ‘.’-notation.

`speciesShareGrid(species)`

Returns: Grid

Return a grid with the basal area of the given species (resource unit resolution, i.e. 100m).

`startOutput()`

Returns: boolean

starts the output table_name. The table name for each output can be found on the output wiki page. Starting debug outputs is also possible - the table_name has to have the format debug_XXX, with XXX one of the following:

treeNPP
treePartition
treeGrowth
waterCycle
dailyResponse
establishment
carbonCycle
performance

`stopOutput()`

Returns: boolean

stops the output table_name. The table name for each output can be found on the output wiki page. Starting (debug outputs) is also possible - see startOutput().

`systemCmd()`

Returns: string

Execute a system command (e.g., for copying files). Commands are operating system dependent; For windows, cmd.exe /C executes a command without a separate command window (see example below). Output of the executed command is redirected to the iLand log (stdout, stderr), the stdout output is returned as a string.

Return Value Description: the output of the command (std-out)

Example:

// helper function for windows: fix slashes and add 'cmd.exe /C'
    function winnify(s) {
         // replace forward with backward slashes
         s = s.replace(/\//g, '\\');
         s = "cmd.exe /C " + s;
         return s;
    }

    // onYearEnd: is called automtically from iLand at the end of a year
    function onYearEnd()
    {
        v = Globals.setting('user.v'); // 'version' is a user defined variable in the project file
        // create a folder for the simulation using 'v' at the end of the first simulation year
        if (Globals.year==1)
            Globals.systemCmd(winnify('mkdir ' + Globals.path('output/v' + v)));
    }

`wait(milliseconds)`

Returns: void

Pause model execution for milliseconds ms. This can be useful to slow down animations.