The ABE-library The ABE-library

  • API Docs for Version: 1.0

    • APIs

    Show:

    helper Class

    Defined in: lib_helper.js:3
    Module: abe-lib

    ABE Library

    The library provides a number of helper functions.

    Building STPs

    The library provides functions to simplify the construction of Stand treatment programs.

    • lib.createSTP: takes one or several activites and creates a STP with a given name

    Introspection

    • use formattedLog() and formattedSTP() for a detailed look into past and plant activitites

    Miscallaneous

    • Logging: use log() and dbg() functions and lib.logevel to control the amount of log information
    • Activity log: use activityLog() (internally) to add to the stand-level log data

    Internals

    • lib.mergeOptions: help with global / local settings
    • lib.selectOptimalPatches: compare patches and select the best based on a criterion

    Useful activites

    • changeSTP: set follow-up STP when the current STP ends
    • repeater: simple activity to repeatedly run a single JS function / activity

    Methods

    activityLog

    (
    • actName
    • extraValues
    )

    Defined in lib_helper.js:310

    Stands store a activity log, also used for DNN training. activityLog is the internal function to populate the management history. The extraValues is any value that can be defined by the activity itself.

    See also: TODO: write management history, activityLog()

    Parameters:

    • actName String

      the activity name to log

    • extraValues String

      extra values (activity specific)

    buildProgram

    (
    • concepts
    )

    Defined in lib_helper.js:218

    Library function to build a full iLand STP from a collection of elements.

    The function takes one or multiple elements that are typically Javascript objects to define iLand activities. These Javascript objects typically are returnd by library functions; for example, the library function lib.thinning.tending() returns (one or more) definitions of iLand activities. buildProgram combines multiple elements to a single Javascript object. Note that this function does not intitalize iLand activities - it merely operates on Javascript objects. Use createSTP to actually create a stand treatment program in iLand!

    Parameters:

    • concepts Object

      one or multiple concepts, typically the result of calls to library function

    Returns:

    object a definitions of multiple activities combined in a single object

    Example:

    //
                     const StructureThinning = lib.thinning.selectiveThinning({mode = 'dynamic'});
                     const StructureHarvest = lib.harvest.targetDBH({dbhList = {"fasy":65,   //source: 'Waldbau auf ökologischer Grundlage', p.452
                          "frex":60, "piab":45, "quro":75, "pisy":45, "lade":65,
                          "qupe":75, "psme":65, "abal":45, "acps":60, "pini":45}});
                    
                      const stp = lib.buildProgram(StructureThinning, StructureHarvest);
                      // you can still modify the program, e.g, by adding activities!
                      stp['a_new_activity'] = { type: 'general', schedule: .... };

    buildRareSpeciesFilter

    (
    • speciesList
    • threshold
    )
    String

    Defined in lib_helper.js:700

    Constructs a iLand expression for filtering trees based on the proportion of target species in the stand. When the relative basal area of all target species combined is below threshold, then trees of these species are filtered out. The chance of being filtered out declines linearly up to 2x threshold, above no trees are filtered. The species list can be provided in multiple formats.

    Parameters:

    • speciesList String | string | object

      The list of species. Can be: - A single species ID string (e.g., "quro"). - An array of species ID strings (e.g., ["quro", "qupe"]). - An object where keys are species IDs (e.g., 'quro') and values are ignored. - A function

    • threshold Number

      The relative basal area threshold (0..1) for filtering.

    Returns:

    String:

    The filter string.

    changeSTP

    (
    • options
    )
    Object

    Defined in lib_helper.js:564

    Switches the active Stand Treatment Program (STP) for a stand.

    This function allows you to dynamically change the STP that is being applied to a stand during a simulation. It's particularly useful for implementing adaptive management strategies or scenarios where different management regimes should be applied based on specific conditions or triggers.

    Parameters:

    • options Object

      Options for configuring the STP change.

      • STP String

        The name of the STP to switch to. This STP must already be defined in the iLand project.

      • schedule Object

        Schedule object for triggering the STP change (default: { signal: 'end' }).

      • id String

        A unique identifier for the activity (default: 'change_stp').

    Returns:

    Object:

    act - An object describing the STP change activity.

    Example:

    // Switch to the 'harvest_STP' when the 'start' signal is received. lib.changeSTP({ STP: 'harvest_STP', schedule: { signal: 'start' } });

    // Switch to 'passive_STP' after 100 years. lib.changeSTP({ STP: 'passive_STP', schedule: { absolute: true, opt: 100} });

    CheckManagementOfStands

    ()

    Defined in lib_helper.js:100

    Sanity check for all stands, if they have a STP.

    createSTP

    (
    • stp_name
    • concepts
    )

    Defined in lib_helper.js:263

    Main library function to create stand treatment programs in iLand.

    The function takes one or multiple elements that are typically Javascript objects to define iLand activities, combines them, and creates a STP in iLand. If the STP already exists, it updates the existing STP (using fmengine.updateManagement), and creates a new stp otherwise (using fmengine.addManagement).

    See also: lib.helper/buildProgram:method,FMEngine/updateManagement:method

    Parameters:

    • stp_name String

      name of the stand treatment program

    • concepts Object

      one or multiple concepts, typically the result of calls to library function

    Example:

    //
                     const StructureThinning = lib.thinning.selectiveThinning({mode = 'dynamic'});
                     const StructureHarvest = lib.harvest.targetDBH({dbhList = {"fasy":65,   //source: 'Waldbau auf ökologischer Grundlage', p.452
                          "frex":60, "piab":45, "quro":75, "pisy":45, "lade":65,
                          "qupe":75, "psme":65, "abal":45, "acps":60, "pini":45}});
                    
                      lib.createSTP('my_structure_stp',StructureThinning, StructureHarvest);

    dbg

    (
    • str
    )

    Defined in lib_helper.js:151

    Internal debug function to log a string str to the iLand logfile. You can control the amount of log messages by setting lib.loglevel to the following values:

    • 0: None - no messages from abe-library
    • 1: Normal - limited amount of messages from the library, usually only high level
    • 2: Debug - high number of log messages. Use for debugging and not in productive model applications.

    See also: lib.dbg()

    Parameters:

    • str String

      string to log

    formattedLog

    ()

    Defined in lib_helper.js:334

    returns the activity log for the currently active stand as formatted HTML.

    Example:

    // show the log for stand 13 in a popup window
                    fmengine.standId = 13;
                    Globals.alert( lib.formattedLog() );

    formattedSTP

    ()

    Defined in lib_helper.js:375

    returns a readable description of the current STP as formatted HTML.

    The description is a list of activites of the STP that is assigned the currently active stand. Items are greyed out if they have already been run in the current rotation, provide the planned year and a detailed descriptions (as provdied by the library functions)

    Example:

    // show the log for stand 13 in a popup window
                    fmengine.standId = 13;
                    Globals.alert( lib.formattedSTP() );

    getAllStandGridIds

    ()

    Defined in lib_helper.js:71

    Helper function to get a list of all unique stand ids from the standGrid.

    initAllStands

    ()

    Defined in lib_helper.js:54

    Initializes all stands of the current simulation (initStandObj()).

    initStandObj

    ()

    Defined in lib_helper.js:39

    Initializes the stand.obj Javascript object for the current stand (stand.id).

    log

    (
    • str
    )

    Defined in lib_helper.js:127

    Internal function to log a string str to the iLand logfile. You can control the amount of log messages by setting lib.loglevel to the following values:

    • 0: None - no messages from abe-library
    • 1: Normal - limited amount of messages from the library, usually only high level
    • 2: Debug - high number of log messages. Use for debugging and not in productive model applications.

    See also: lib.dbg()

    Parameters:

    • str String

      string to log

    Example:

    // set log level (e.g. in iLand Javascript console or in your code) after loading the library
                    lib.loglevel = 2; //debug!
                    ...
                    // somewhere in library code: running the function now produces log messages
                    lib.dbg(selectiveThinning: repeat ${stand.obj.lib.selective_thinning_counter}, removed ${harvested} trees.);

    mergeOptions

    (
    • defaults
    • options
    )

    Defined in lib_helper.js:179

    Helper function to combine deafult options and user-provided options for activities.

    The function throws an error when options include values not defined in defaults. You should therefore define all potential keys that can be used by the user with value undefined!

    Parameters:

    • defaults Object

      object containing default values

    • options Object

      object user-defined options

    Returns:

    object that contains default values updated with user-provided options

    Example:

    // pattern
                    const default_options = { schedule: undefined, intensity: 10 };
                    // create an object with combined options (even if not provided)
                    const opts = lib.mergeOptions(defaultOptions, options || {});
                    // ...

    repeater

    (
    • options
    )
    Object

    Defined in lib_helper.js:616

    Creates a repeater activity that repeatedly triggers a specified signal.

    This function is useful for creating activities that need to be executed multiple times at regular intervals, such as repeated thinnings or harvests. The repeater can be configured to trigger based on a schedule or a signal, and it can optionally block other activities until it has finished.

    Parameters:

    • options Object

      Options for configuring the repeater.

      • schedule Object

        Schedule object for starting the repeater.

      • id String

        A unique identifier for the repeater activity (default: 'repeater').

      • count Number

        Number of times to repeat the signal (default: undefined).

      • interval Number

        Interval (in years) between repetitions (default: 1).

      • signal String

        Name of the signal to emit at each repetition.

      • block Boolean

        Whether the repeater should block other activities until it finishes (default: true).

      • parameter Function | Undefined

        Function to provide the signal parameter when the signal is emitted (default: undefined).

    Returns:

    Object:

    act - An object describing the repeater activity.

    Example:

    // Repeat the 'thinning' signal 5 times every 10 years, starting in year 50. lib.repeater({ schedule: { start: 50 }, count: 5, interval: 10, signal: 'thinning' });

    // Repeat the 'harvest' signal 3 times every 2 years, triggered by the 'ready_for_harvest' signal, // and provide a custom parameter to the signal. lib.repeater({ schedule: { signal: 'ready_for_harvest' }, count: 3, interval: 2, signal: 'harvest', parameter: function() { // Example: Return the current stand's basal area as the parameter. return stand.basalArea(); } });

    selectOptimalPatches

    (
    • options
    )
    Object

    Defined in lib_helper.js:414

    Selects optimal patches based on a given criterion.

    This function helps with selecting the best patches in a stand based on a specified criterion (e.g., light availability, basal area) or a custom function. It's useful for setting up spatially explicit management activities like creating gaps or targeting specific areas within a stand for treatments.

    Parameters:

    • options Object

      Options for configuring the patch selection.

      • id String

        A unique identifier for the activity (default: 'selectOptimalPatches').

      • N Number

        Number of patches to select per hectare (default: 4).

      • patchsize Number

        Size of the patches (in cells, assuming a square shape, e.g., 2 for 2x2 cells, which is 20x20m or 400m2) (default: 2).

      • spacing Number

        Space (in 10m cells) between candidate patches (default: 0).

      • criterium String

        Criterion for selecting patches ('max_light', 'min_light', or 'min_basalarea') (default: 'max_light').

      • customFun Function | Undefined

        Custom function for evaluating patches. This function should take a patch object as input and return a score (default: undefined).

      • patchId Number

        ID to assign to the selected patches (default: 1).

      • sendSignal String

        Optional: Signal that should be send after selecting patches (default: undefined).

      • schedule Object

        Schedule object for triggering the patch selection (default: { signal: 'start' }).

    Returns:

    Object:

    act - An object describing the patch selection activity.

    Example:

    // Select 5 patches per hectare based on maximum light availability, using 3x3 patches.
                    lib.selectOptimalPatches({
                        N: 5,
                        patchsize: 3,
                        criterium: 'max_light'
                    });
                    
                    // Select 2 patches per hectare based on a custom evaluation function.
                    lib.selectOptimalPatches({
                        N: 2,
                        customFun: function(patch) {
                            // Example: Score based on proximity to a specific location
                            const targetX = 50;
                            const targetY = 50;
                            const distance = Math.sqrt(Math.pow(patch.x - targetX, 2) + Math.pow(patch.y - targetY, 2));
                            return 1 / distance; // Higher score for closer patches
                        }
                    });