/**
The `Management` object is used to for operations that remove trees from the simulation environment.
The iLand management is accessible using the global object `management`, which is available
when script code is invoked from the iLand management subsystem.

Main functions
--------------

+ Loading trees from iLand: use {{#crossLink "Management/load:method"}}{{/crossLink}} and {{#crossLink "Management/loadFromMap:method"}}{{/crossLink}} to load a list of trees
+ manipulating lists of trees: use {{#crossLink "Management/filter:method"}}{{/crossLink}} to select a sub set based on some criterion,
 or {{#crossLink "Management/sort:method"}}{{/crossLink}} to bring the list in a specific order; you can calculate {{#crossLink "Management/sum:method"}}{{/crossLink}}
 or {{#crossLink "Management/mean:method"}}{{/crossLink}} values from all trees in the list
+ removing trees: {{#crossLink "Management/manage:method"}}{{/crossLink}} and {{#crossLink "Management/kill:method"}}{{/crossLink}}
+ other functions such as....

Note that by default only living trees are processed.
Several special functions exists, e.g. a function to filter based on a predefined list of tree-ids (filter()), of methods
that select trees based on some rastered GIS data.

There are several distinct tree removal modes in iLand, namely by harvesting a tree, or by killing a tree, or due to a disturbance.
In general, harvesting removes all (aboveground) biomass from the system, while a killed trees' biomass is moved to the soil pools.
Disturbed trees behave similar to killed trees. Note, that there are further subtle differences between removal modes: for instance, resprouting
is only possible from harvested trees; or, trees killed by disturbance might be treated differently by management.

The management functions typically affect only individual trees in iLand with a height >4m. However, there are some functions available
to alter the state of the saplings (tree cohorts < 4m height).



Expressions and tree variables
------------------------------
Many function of the `management` object allow to specify a filter ([Expression](https://iland-model.org/Expression)). In the context of
management, tree variables can be used within filter expressions: see https://iland-model.org/tree+variables

Tree species can be included in Expressions by using the short name as is; internally, the species (identity) is
a integer index of the species, and species short names (such as 'piab', 'fasy', or 'pico') are used as placeholders.


Examples
--------
The wiki contains a small collection of useful management scripts.

@module iLand
@class Management
*/

/**
The number of trees that are currently in the internal list.

See also: {{#crossLink "SpatialAnalysis/load:method"}}{{/crossLink}}

@property count
@type integer
*/
/**
The removal fraction for foliage [0..1]. 0: 0% will be removed, 1: 100% will be removed from the forest by management operations (i.e. calls to manage())

The default value is 0 (all foliage remains in the forest)

See also: {{#crossLink "SpatialAnalysis/removeBranch:method"}}{{/crossLink}}, {{#crossLink "SpatialAnalysis/removeStem:method"}}{{/crossLink}}

@property removeFoliage
@type double
@Example
    // full tree extraction
    management.removeFoliage = 1; management.removeBranch=1; management.removeStem = 1;
    management.manageAll();

*/
/**
The removal fraction for branches [0..1]. 0: 0% will be removed, 1: 100% will be removed from the forest by management operations (i.e. calls to manage())

The default value is 0 (all branches remain in the forest)

See also: {{#crossLink "SpatialAnalysis/removeFoliage:method"}}{{/crossLink}}, {{#crossLink "SpatialAnalysis/removeStem:method"}}{{/crossLink}}

@property removeBranch
@type double
*/
/**
The removal fraction for the stem biomass [0..1]. 0: 0% will be removed, 1: 100% will be removed from the forest by management operations (i.e. calls to manage())

The default value is 1 (100% of the stem is removed in case of management). Note that root biomass is never extracted.

See also: {{#crossLink "SpatialAnalysis/removeFoliage:method"}}{{/crossLink}}, {{#crossLink "SpatialAnalysis/removeBranch:method"}}{{/crossLink}}

@property removeStem
@type double
*/

/**
Load all trees into the internal list and return the number of trees.

@method loadAll
@return {integer} the number of trees that were loaded.
*/
/**
Load all trees passing the filter criterion specified in `filter` and return number of trees in the list.
`filter` can be any tree-related Expression.

@method load
@param {string} filter A valid filter Expression that is applied during the loading of the list.
@return {integer} the number of trees that were loaded.
@Example
    // load all trees with a dbh >30 cm
    management.load('dbh>30');
*/
/**
Load all trees of a resource unit with the index `ruindex` and return the number of loaded trees.

@method loadResourceUnit
@param {int} ruindex The index (0-based) of the resource unit that should be loaded
@return {integer} the number of trees that were loaded.
@Example
    for (var i=0; i<Globals.resourceUnitCount; ++) {
        management.loadResourceUnit(i);
        // further processing....
    }
*/

/**
Load all trees that are located on grid pixels with the value `standID` on the grid `map`.

@method loadFromMap
@param {Map} map a GIS grid that defines stand IDs.
@param {integer} standID the ID of the stand that should be loaded.
@param {boolean} do_append if `true`, the list is not cleared and trees are added to the existing list. Default is `false`.
@return {integer} the number of trees that were loaded.
@Example
    // Access to the global stand grid (required only once)
    var stand_grid = new Map();
    // load all trees of the forest stand with ID=1
    management.loadFromMap(stand_grid, 1);
*/

/**
Clears the list without affecting any trees.

@method clear
*/
/**
Sort the trees in the internal list in ascending order according to a criterion given
by `expression` (a valid [iLand Expression](https://iland-model.org/Expression)).

See also: {{#crossLink "Management/percentile:method"}}{{/crossLink}}

@method sort
@param {string} expression Expression used for sorting
@Example
    management.sort('dbh'); // sort by diameter, largest tree are now in the end of the list
    management.sort('-dbh'); // to sort in descending order, reverse the sign of the expression
*/
/**
Apply a filter `expression` on the list of trees (`expression`is a valid [iLand Expression](https://iland-model.org/Expression))
and return the number of trees remaining in the lists. After calling this function, the list of
trees is typically reduced and contains only those trees, who meet the condition in `expression`.

See the example how to filter by species, and how to combine multiple criteria.

See also: {{#crossLink "Management/sort:method"}}{{/crossLink}}, {{#crossLink "Management/load:method"}}{{/crossLink}}

@method filter
@param {string} expression Expression used for filtering
@return {integer} the number of trees in the list after filtering.
@Example
    management.loadAll();
    management.filter('dbh>10');
    // is the same as:
    management.load('dbh>10');
    // using tree species names: note, that no "'" or '"" signs
    // are used with species IDs; note also the boolean 'and' operator
    management.filter('species=piab and dbh>20');
    management.loadAll(); // all trees
    management.filter('dbh>10 and species=piab'); // reduce list
    // ... some processing....
    management.filter('dbh>20'); // now only spruce trees > 20cm are still in the list
    management.filter('stress>0'); // now only spruce trees >20cm, that have a non-zero stress rating are in the list
    // ...

*/
/**
Apply a filter in form of a `list` of ids, return number of remaining trees. This can be useful
to pre-define a management on individual trees.


See the example below.


See also: {{#crossLink "Management/filter:method"}}{{/crossLink}}, https://iland-model.org/initialize+trees

@method filterIdList
@param {array} list A list of unique tree IDs.
@return {integer} the number of trees in the list after filtering.
@Example
    // array of tree IDs
    var treelist = [10,20,40,43]; // can be loaded form file...
    management.load(); // load all trees
    management.filter(treelist); // filter trees using the tree list
    management.kill(); // remove all trees remaining, i.e. the trees in the tree list.

*/
/**
Shuffle all trees in the list randomly.

@method randomize
*/

/**
Retrieve the value associated with the `pct` percentile [0..100] of the currently loaded trees. A call
to {{#crossLink "Management/sort:method"}}{{/crossLink}}() is required in order to prepare valid
data.

See also: {{#crossLink "Management/sort:method"}}{{/crossLink}}

@method percentile
@param {integer} pct the percentile [0..100] for which to return the value
@return {dobule} the value associated with the `pct` percentile
*/

/**
Calculate the mean value for all trees in the internal list for `expression` (optionally filtered by the `filter` criterion).

See also: {{#crossLink "Management/sum:method"}}{{/crossLink}}

@method mean
@param {string} expression The expression used for calculating the mean value
@param {string} filter If not empty, the mean is calculated only from those trees that meet the criterion in the expression
@return {dobule} the mean value of `expression`
@Example
    var mean_dbh = management.mean('dbh');

*/
/**
Calculate the sum of `expression` for all trees in the internal list (optionally filtered by the `filter` criterion).

See also: {{#crossLink "Management/sum:method"}}{{/crossLink}}

@method sum
@param {string} expression The expression used for calculating the mean value
@param {string} filter If not empty, the mean is calculated only from those trees that meet the criterion in the expression
@return {dobule} the mean value of `expression`
@Example
    // select trees that represent 50% of the total basal area
    management.loadAll();
    var total_ba = management.sum('basalarea');
    management.randomize();
    management.filter('incsum(basalarea)<' + total_ba * 0.5 );
    console.log(management.sum('basalarea'));
*/


/**
Use `killPct` to remove `n` trees sampled randomly from a given percentile range (given by `from` and `to`). All
trees are removed, if `n` is higher than the number of trees in that range.

The tree list needs to be sorted, before percentile based selection makes sense.

See also: {{#crossLink "Management/sort:method"}}{{/crossLink}}, {{#crossLink "Management/percentile:method"}}{{/crossLink}}

@method killPct
@param {integer} from lower percentile of the current tree distribution (0..100)
@param {integer} to higher percentile of the current tree distribution (0..100)
@param {integer} n the number of trees to kill in the given percentile
@return {integer} the number of killed trees
@Example
    var n = management.loadAll();
    management.sort('dbh');
    var n_killed = management.killPct(0,50, n*0.25);
    console.log('killed ' + n_killed + ' below median: ' + management.percentile(50) );
    // kill 33% of the trees between the 80th and the 100th percentile.
    management.killPct(80,100, n*0.2 * 0.33);
*/
/**
Kill all trees which are currently in the tree list.

See also: {{#crossLink "Management/kill:method"}}{{/crossLink}}, {{#crossLink "Management/manageAll:method"}}{{/crossLink}}
@method killAll
@return {integer} the number of killed trees.
*/
/**
Kill all and cut down all trees in the list. The biomass of cut down trees bypasses the standing dead wood pool, and
such trees can act as trap trees with regard to bark beetles.

See also: {{#crossLink "Management/kill:method"}}{{/crossLink}}, {{#crossLink "Management/manageAll:method"}}{{/crossLink}}
@method cutAndDrop
*/
/**
Remove all selected trees with with the _disturbance_ flag set. Disturbed trees are treated
differently with regard to carbon flows and {{#crossLinkModule "ABE"}}{{/crossLinkModule}}. Biomass of the stem and
the branches is routed to the soil and snag pools as indicated by the parameters of the function. The rest of the biomass
is removed from the system (e.g., consumed by fire). For example, if `stem_to_soil_fraction`=0.2, `stem_to_snag_fraction`=0.3, then
50% of the biomass leaves the system, 20% are added to the soil, 30% to the snag pools.

The `agent` parameter is the reason of death (i.e. the process that should be mimicked). Recognized values are 'fire', 'wind', 'barkbeetle', and 'cutdown'. For instance,
tree that are removed with the `agent` set to 'wind' act as a breeding material for bark beetles. If the `agent` parameter is `'fire'`, then serotinous trees produce extra seeds.

See also: {{#crossLink "Management/killAll:method"}}{{/crossLink}}, {{#crossLink "Management/manageAll:method"}}{{/crossLink}}
@method disturbanceKill
@param {double} stem_to_soil_fraction (0..1) of stem biomass that is routed to the soil
@param {double} stem_to_snag_fraction (0..1) of the stem biomass continues as standing dead
@param {double} branch_to_soil_fraction (0..1) of branch biomass that is routed to the soil
@param {double} branch_to_snag_fraction (0..1) of the branch biomass continues as standing dead
@param {string} agent the disturbance agent that is mimicked ('fire' 'wind', 'barkbeetle', 'cutdown' ...)
@return {integer} the number of killed trees.
*/
/**
Kill `fraction` (0..1) of all trees for which the Expression `filter` is _true_.

See also: {{#crossLink "Management/killAll:method"}}{{/crossLink}}, {{#crossLink "Management/manage:method"}}{{/crossLink}}
@method kill
@param {string} filter A expression to select a subset of the trees.
@param {double} fraction give the fraction (0..1) of trees that should be killed.
@return {integer} the number of killed trees.
@Example
    management.loadAll();
    // kill 30% of larch trees, and 60% of pine
    management.kill('species = lade', 0.3);
    management.kill('species = pisy', 0.6);
*/


/**
Use `managePct` to remove `n` trees sampled randomly from a given percentile range (given by `from` and `to`). All
trees are removed, if `n` is higher than the number of trees in that range.

The tree list needs to be sorted, before percentile based selection makes sense.

See also: {{#crossLink "Management/sort:method"}}{{/crossLink}}, {{#crossLink "Management/percentile:method"}}{{/crossLink}}

@method managePct
@param {integer} from lower percentile of the current tree distribution (0..100)
@param {integer} to higher percentile of the current tree distribution (0..100)
@param {integer} n the number of trees to harvest in the given percentile
@return {integer} the number of harvested trees
@Example
    var n = management.loadAll();
    management.sort('dbh');
    var n_rem = management.managePct(0,50, n*0.25);
    console.log('removed ' + n_rem + ' below median: ' + management.percentile(50) );
    // harvest 33% of the trees between the 80th and the 100th percentile.
    management.managePct(80,100, n*0.2 * 0.33);
*/
/**
Harvest all trees which are currently in the tree list.

See also: {{#crossLink "Management/manage:method"}}{{/crossLink}}, {{#crossLink "Management/killAll:method"}}{{/crossLink}}
@method manageAll
@return {integer} the number of harvested trees.
*/

/**
Remove a `fraction` (0..1) of all trees for which the Expression `filter` is _true_.

See also: {{#crossLink "Management/manageAll:method"}}{{/crossLink}}, {{#crossLink "Management/kill:method"}}{{/crossLink}}
@method manage
@param {string} filter A expression to select a subset of the trees.
@param {double} fraction give the fraction (0..1) of trees that should be harvested.
@return {integer} the number of harvested trees.
@Example
    management.loadAll();
    // kill 30% of larch trees, and 60% of pine
    management.manage('species = lade', 0.3);
    management.manage('species = pisy', 0.6);
*/


/**
Kill all saplings (i.e. trees <4m) which are located on grid pixels with the value `standID` on the grid `map`.

@method killSaplings
@param {Map} map A Map object with a stand grid.
@param {integer} standID the ID of the stand to process.
*/

/**
Kill all saplings (i.e. trees <4m) which are located on the resource unit identified by `ruindex`.

@method killSaplingsResourceUnit
@param {integer} ruindex the index of the resource unit to process.
*/

/**
(Hacky) function to modify the carbon content of the snag/soil pools of resource units covered by pixels with `standID` on the `map`.
If the resource unit is only partially covered, the factors are scaled accordingly.
The parameters are remove-fractions, i.e. values of 0 mean no change, values of 1 mean removal of 100% of the carbon of the respective pool.

@method removeSoilCarbon
@param {Map} map A Map object with a stand grid.
@param {integer} standID the ID of the stand to process.
@param {double} SWDfrac fraction of standing woody debris to remove.
@param {double} DWDfrac  fraction of downed woody debris to remove.
@param {double} litterFrac fraction of litter (yL) to remove.
@param {double} soilFrac fraction of SOM to remove..
*/


/**
`tree(index)` returns the tree with index `index` (index is 0-based) from the current list. The returned Javascript object
is a reference to the represented tree in iLand. See {{#crossLink "Tree"}}{{/crossLink}} for more details.

See also: {{#crossLink "TreeList/treeObject:method"}}{{/crossLink}}

@method tree
@return {Tree}  a reference to the tree with index `index` (see above). If the index is out of range, the `valid` property of the returned object is `false`.
@Example
    management.loadAll(); // fill the tree list
    // loop over all trees
    for (var i=0;i<management.count;++i)
       console.log( management.tree(i).dbh );

**/

/**
`treeObject(index)` returns the tree with index `index` (index is 0-based) from the current list. A new Javascript object
is created for the tree. See {{#crossLink "Tree"}}{{/crossLink}} for more details.

See also: {{#crossLink "TreeList/tree:method"}}{{/crossLink}}

@method treeObject
@return {Tree}  a object representing the tree with index `index` (see above), or an invalid Tree object (if index is out of range).
@Example
    management.loadAll(); // fill the tree list
    var x = management.treeObject(7); // 8th tree in the list
    // access the tree
    if (x.valid == true)
       console.log(x.dbh);

**/




Management = {}