Show:
Module: iLand

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

Methods

addSaplings

(
  • standId
  • x
  • y
  • width
  • height
  • species
  • treeheight
  • age
)
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

Parameters:

  • standId Integer

    id of the stand (0 or -1 for no stand provided)

  • x Double

    id x-coordinate of the rectangle

  • y Double

    id y-coordinate of the rectangle

  • width Double

    width (m) of the rectangle

  • height Double

    height (m) of the rectangle

  • species String

    species code of the species to plant saplings

  • treeheight Double

    height (m) of saplings

  • age Integer

    age of the saplings that are planted

Returns:

Integer:

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

(
  • map
  • mapId
  • species
  • px_per_hectare
  • treeheight
  • age
)
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

Parameters:

  • map Map

    Map object

  • mapId Integer

    identifier for the stand / polygon on the given map for which to add saplings

  • species String

    species code of the species to plant saplings

  • px_per_hectare Double

    proportion to plant saplings from the 2x2m cells within the given stand (0..1)

  • treeheight Double

    height (m) of saplings

  • age Integer

    age of the saplings that are planted

Returns:

Integer:

the number of saplings trees

addSingleTrees

(
  • resourceIndex
  • content
)
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.

Parameters:

  • resourceIndex Integer

    0-based resource unit index

  • content String

    line (or lines) of an init-file to initialize

Returns:

Integer:

the number of added trees.

addTrees

(
  • resourceIndex
  • content
)
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.

Parameters:

  • resourceIndex Integer

    0-based resource unit index

  • content String

    line (or lines) of an init-file to initialize

Returns:

Integer:

the number of added trees.

addTreesOnMap

(
  • standID
  • content
)
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.

Parameters:

  • standID Integer

    ID of the stand in the stand grid

  • content String

    line (or lines) of an init-file to initialize

Returns:

Integer:

the number of added trees.

alert

(
  • message
)

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

(
  • RUs
)

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

See also: saveDebugOutputs

Parameters:

  • RUs Array

    array of resource unit indices

Example:

// limit output to a sample of the resource units
                    Globals.debugOutputFilter([106,235,414,543]);

defaultDirectory

(
  • category
)
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.

See also: currentDir

Parameters:

  • category String

    folder category

Returns:

String:

The requested file path (without a trailing slash)

fileExists

(
  • file_name
)
Boolean

Check if the file file_name already exists.

Parameters:

  • file_name String

    file to check

Returns:

Boolean:

true if the file already exists

grid

(
  • type
)
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:

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)

See also: gridToFile

Parameters:

  • type String

    select the type of grid to return

Returns:

Grid:

a Javascript object encapsulating the Grid

gridToFile

(
  • grid_type
  • file_name
  • height_level
)
Boolean

Creates a ESRI style grid file from an iLand grid. 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

See also: grid

Parameters:

  • grid_type String

    select the type of grid to export

  • file_name String

    target file path (relative to the home directory)

  • height_level Numeric

    gives the reference height level for the height-corrected LIF lifc (see also the competition for light wiki page)

Returns:

Boolean:

true on success.

Example:

Globals.gridToFile('height', 'temp/heightgrid.txt'); // store in project_folder/temp

include

(
  • name
)

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

(
  • file_name
)
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.

See also: saveModelSnapshot

Parameters:

  • file_name String

    filename of the input database.

Returns:

Boolean:

true on succes.

loadTextFile

(
  • file_name
)
String

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

Parameters:

  • file_name String

    filename to load

Returns:

String:

the content of the file or an empty text if file does not exist/is empty.

path

(
  • filename
)
String

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

Example (Project-file: "c:\iland\test\test.xml"): Globals.path('temp/filexy.txt') -> "c:\iland\test\temp.filexy.txt"

See also: defaultDirectory, currentDirectory

Parameters:

  • filename String

    filename that should be extended

Returns:

String:

fully qualified file path

print

(
  • message
)

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

(
  • from
  • to
)
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)

Parameters:

  • from Double

    lower bound (inclusive), default=0

  • to Double

    upper bound (inclusive), default=1

Returns:

Double:

the random number

reloadABE

()

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

()

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

Returns:

Grid:

a Javascript Grid

saveDebugOutputs

(
  • do_clear
)

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

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

Parameters:

  • do_clear Boolean

    if true, debug output buffer is cleared

saveModelSnapshot

(
  • file_name
)
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.

See also: loadModelSnapshot

Parameters:

  • file_name String

    filename of the output database.

Returns:

Boolean:

true on succes.

saveTextFile

(
  • file_name
  • content
)
Boolean

Save the content of a string content to a file.

Parameters:

  • file_name String

    filename to save to

  • content String

    content that should be written

Returns:

Boolean:

true on success.

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. The image type depends on the extension provided with file_name. Default path is the home directory.

Parameters:

  • file_name String

    file name that

Returns:

Boolean:

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

Returns:

Boolean:

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
  • value
)
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.

See also: setting

Parameters:

  • key String

    fully qualified key within the project file

  • value Object

    new value of the setting key.

Returns:

Boolean:

true on success.

setting

(
  • key
)

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

See also: set

Parameters:

  • key String

    fully qualified key within the project file

Returns:

The value of the setting, or undefined if the setting is not present

Example:

// global 'onInit' function is called during startup
                    var width = Globals.setting('model.world.width'); // the horizontal extent of the project area
                    var filename = Globals.setting('user.targetdir') + "my_file.txt"; // a user-defined key in the project file

setUIshortcuts

(
  • shortcuts
)

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

speciesShareGrid

(
  • species
)
Grid

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

See also: grid

Parameters:

  • species String

    species code (e.g., 'piab') of the species

Returns:

Grid:

a Javascript Grid

startOutput

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

See also: stopOutput

Parameters:

  • table_name String

    Output that should be started

Returns:

Boolean:

true on succes, an error message is printed in case of failure.

Example:

Globals.startOutput("debug_performance");

stopOutput

(
  • table_name
)
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.

See also: startOutput

Parameters:

  • table_name String

    Output that should be stopped

Returns:

Boolean:

true on succes, an error message is printed in case of failure.

systemCmd

(
  • command
)
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.

Parameters:

  • command String

    command to execute

Returns:

String:

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
)

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

See also: repaint

Parameters:

  • milliseconds Integer

    time to wait in milliseconds

Properties

currentDir

String

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

Example (Project-file: "c:\iland\test\test.xml"): Globals.path('temp/filexy.txt') -> "c:\iland\test\temp.filexy.txt"

See also: path

Example:

Globals.currentDir="c:/temp";
                    Globals.loadTextFile("i_am_in_temp.txt"); // accesses c:/temp

msec

Integer

The milliseconds since the start of the day.

Example:

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

The number of resource units in the current simulation.

Default: 1

viewOptions

Object

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.

Example:

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

worldX

Integer

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

See also: worldY

worldY

Integer

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

See also: worldX

year

Integer

The current year of the simulation.