Description of the project XML file

# project file

## The project file

The project file is the main spot to control iLand. The file contains settings that define which world to create (i.e. the spatial configuration, climate data, etc), but also how iLand should operate - this includes switches defining the behaviour of the model, but also which kind of output data should be created (and where it should be stored).
For the project file we choose a XML based structure which gives great flexibility and adaptability. For the time being, no GUI is provided to make these settings - but this may change in future.

### Example files

Example files are provided here: Example for a project file

## Main sections

The project file consists of five main sections:

• system: settings like file path, database locations, or logging
• model:main settings of the models: extent (world), site specific setting, used climate, model initialization and management
• modules: settings related to the disturbance modules of iLand
• output: definition of which outputs should be created by the model
• user: this section can be used for user-defined settings (which may be used in Javascript)

Each valid XML project file starts with a fixed header, and all sections are below the top node project:

<?xml version="1.0" encoding="utf-8"?>
<project>
<system> ... </system>
<model> ... </model>
<modules> ... </modules>
<output> ... </output>
<user> ... </user>
</project>

## System settings

### path

This section defines the default directories for different types of files. More details can be found here.

### database

iLand uses primarily the SQLite database system, which stores all tables of a database within a single database file. This database files are considered to be located in the database location defined in the path section.

 key datatype description in database file defines the input database. Stored in this database are e.g. species parameter. out database file result (see Outputs) are written to this database. climate database file the SQLite database containing the climate data

### settings

 key datatype description multithreading boolean if true, iLand will use several threads to perform its calculations (if more than 10 [[RessourceUnits]] are defined) responsive boolean if true iLand is more responsive during lengthy calculations (i.e. the user interface freezes less frequently) randomSeed integer Non-zero values are used as the seed for the random number generator. This results in a reproducible series of (pseudo)-random numbers. Empty or 0 causes different random numbers for each run and therefore stochastic variation between runs. Note: this does not work when multi threading is enabled (more). Default value is 0. logLevel string This setting defines the logging intensity. Possible values are Debug, Info, Warning and Error. When running on the Debug logging level, the log output contains many details that may slow down the application. Default is Debug. expressionLinearizationEnabled boolean if true, specific expressions (user defined formulas, e.g. for light response) use a interpolation approach to increase the calculation performance debugOutput integer defined the active debug outputs. Each output is coded by a single bit. Find a list of currently available outputs under the debug data menu of the iLand application. e.g: a value of 17 (=16+1) would enable the water output (16) and the Tree NPP output (1). debugOutputAutoSave boolean if true, csv-output files are created for each active debug output and saved to the temp directory (see Path-section).

### logging

 key datatype description logTarget string either console or file. If file the log output is stored in a file (see logFile). If console the log output is printed in the log window of the iLand main application. default=console logFile string Log-output is stored in this file. If the filename contains the string $date$, it is replaced by a timestamp (yyyymmdd__hrmiss). The default location is the log-path. A new file is created whenever the model created (e.g. after clicking "Create Model" or "Reload"). flush boolean log information is immediately written to the logfile when flush is true. This can be useful for debugging purposes (but might slow down execution). (default: false)

### javascript

This section deals with Javascript-script files that are loaded into the models' script engine at startup. Note that you can load multiple files by using the Globals.include() javascript function.

 key datatype description fileName string the filename of a javascript file to load. Default location is the "scripts"-directory.

## Model settings

### site

Site variables define the project site in a non spatially explicit manner.

 key datatype description availableNitrogen numeric plant available nitrogen kg/ha/year soil properties - water cycle soilDepth numeric Depth of root accessible soil in cm pctSand numeric Percentange of sand (0..100) in soil. See water cycle. pctSilt numeric Percentange of silt (0..100) in soil. See water cycle. pctClay numeric Percentange of clay (0..100) in soil. See water cycle soil properties - carbon and nitrogen cycling youngLabileC numeric (initial) carbon content of ylC (i.e. litter) soil pool (kg/ha) youngLabileN numeric (initial) nitrogen content of ylC soil pool (kg/ha) youngLabileDecompRate numeric (initial) decomposition rate of yl pool youngLabileAbovegroundFraction numeric (initial) fraction of aboveground C in the litter (yL) layer (foliage) youngRefractoryC numeric (initial) carbon content of yrC (woody) soil pool (kg/ha) youngRefractoryN numeric (initial) nitrogen content of yrC (woody) soil pool (kg/ha) youngRefractoryDecompRate numeric (initial) decomposition rate of yr pool somC numeric (initial) carbon content of oC (soil organic matter) soil pool (kg/ha) somN numeric (initial) nitrogen content of oN (soil organic matter) soil pool (kg/ha) somDecompRate numeric decomposition rate for soil organic matter (i.e. the "old" pool sensu ICBM) youngRefractoryAbovegroundFraction numeric fraction (0..1) of C in the yR pool from aboveground sources (branches, stems) soilHumificationRate numeric humification rate

### settings

This section is about global model settings.

 key datatype description General switches growthEnabled boolean if false, trees will apply/read light patterns, but do not grow mortalityEnabled boolean if false, tree mortaliy (intrinsic and stress related) will not be executed. Management works. regenerationEnabled boolean if true, the regeneration submodule is enabled (seed production, seed dispersal, establishment, sapling growth, recruitment) carbonCycleEnabled boolean if true, the snag dynamics and soil CN cycling sub-modules are enabled. Light calculations lightExtinctionCoefficient numeric "k" parameter (beer lambert) used for calc. of absorbed light on resourceUnit level lightExtinctionCoefficientOpacity numeric "k" for beer lambert used for opacity of single trees temperatureTau numeric "tau"-value for delayed temperature calculation acc. to Mäkela 2008 Production epsilon numeric 3PG's maximum efficiency in GPP production (default value: 1.8). usePARFractionBelowGroundAllocation bool changes the behavior of belowground allocation. If true, the ratio of utilized total radiation is used, otherwise this ratio is considered to be 1. (default=true) Water cycle airDensity numeric density of air (kg / m3) laiThresholdForClosedStands numeric For the calculation of the maximum canopy conductance a ramp is assumed for LAI values below this threshold. Default: 3 boundaryLayerConductance numeric boundary layer conductance for the evaporation calculation. Default value: 0.2 m/s waterUseSoilSaturation bool if true, plants can access the water up to the saturation point (0kPa). If false, the accessible water is limited with the field capacity (-15kPa). Default is false. interceptionStorageNeedle numeric asymptotic crown storage capacity for intercepted rain water of confiers. (default: 4). interceptionStorageBroadleaf numeric asymptotic crown storage capacity for intercepted rain water of deciduous trees. (default: 2). snowMeltTemperature numeric threshold temperature for snow (degree Celsius). Precipitation on days with mean temperature below this threshold is modeled as snow; snow melts at mean temperatures above the threshold. default: 0°C. groundVegetationLAI numeric the minimum leaf area index of a resource unit for the water cycle. See transpiration and conductance in saplings. groundVegetationPsiMin numeric the assumed $\Psi_{min}$ of ground vegetation. See transpiration and conductance in saplings. heatCapacityAir deprecated Specific heat capacity of air (J /(kg °C)) airPressure deprecated atmospheric average pressure (mbar)

Seed Dispersal
settings for external seed input and high-detailed outputs during seed dispersal are configured in a sub-section seedDispersal of the "model.settings" section. See also external seeds.

 key datatype description dumpSeedMapsEnabled boolean if "true", seed-kernels are stored per species as .CSV file, and seedmaps are dumped per species and year as a pair of images (one image before actual dispersal, indicating seed availability, and one after seed dispersal) dumpSeedMapsPath string target directory for seed maps / seed kernel dumps externalSeedEnabled boolean if "true" external seeds are produced by species listed under externalSeedSpecies. If external seeds are enabled, the buffer-area of the simulation area is considered as a source of seeds. externalSeedSpecies string list of species (case sensitive!) with external seed input (e.g., "Psme, Abmi"). externalSeedSource string cardinal directions of external seed input. Specify as list of N,E,S,W (i.e.. north, east, south, west). If empty or missing, seeds enter from all directions. e.g.: "E,S" -> seed from east and south direction. externalSeedBuffer string This specifies a species-specific special "buffer", i.e. it defines the distance between the external seed input and the edge of the simulation area. Unit is "seed pixels", i.e. currently 20m. Specify as a ',' separated list of alternately species name and buffer-width (e.g. "Psme, 2, Abmi, 1" -> 40m for Psme, 20m for Abmi). No special buffer is used for species not in the list. Note: the remaining seed source must be >1px due to an implementation detail of the dispersal routine. externalSeedBackgroundInput string specifies a list of species together with a probability for each species. If a species is in the list, then a global background seed input is assumed (see external seeds). recruitmentDimensionVariation double defines the range of variation (r) for recruited trees compared to the dimensions of the cohrt. tree_dbh = cohort_dbh * rnd(1-r, 1+r), tree_h = cohort_h * rnd(1-r, 1+r) (e.g: r=0.2 -> random number from 0.8 to 1.2)

Seed Dispersal - Seed Belt
Settings for the specifying an seed belt. The section is a sub section of model.settings.seedDispersal.

 key datatype description enabled boolean the submodule is only active if enabled is true. width numeric the width of the seed belt (in pixels of the seed maps, currently 20m). E.g., a value of 10 would lead to a seed belt with a width of 200m. sizeX numeric the number of sectors in x-direction. Sectors are used to specify fine grained species distribution within the belt. sizeY numeric the number of sectors in y-direction. Sectors are used to specify fine grained species distribution within the belt. species__ string specifies species and proportion of a given sector. The x and y in the key specify the coordinates of the sector. x and y are between 0 and sizeX and sizeY, respectively. 0/0 is the lower left corner (south west), sizeX-1 / sizeY-1 the upper right (north east) corner. The string is a list of species code and the fraction of pixels that should act as a seed source for that species. The information is specified as a space-delimited list: ... Example: a value for the key species_0_0 of "Psme 0.7 Abmi 0.2" means: in the sector (0/0), 70% of the seed pixels in the belt should be populated with Psme, 20% with Abmi. Note that the sum of fractions need not to be 1.

Seed Dispersal - Long Distance Dispersal
These settings affect the size of the area that is handled by long distance dispersal. See seed kernel and seed distribution. The section is a sub-section of model.settings.seedDispersal.

 key datatype description thresholdArea double The threshold defines the density of potential seedlings per m² up to which a full kernel is used (default: 0.0001) thresholdLDD double The threshold (again, seedlings per m²) defines the maximum distance of long-distance-dispersal (default: 0.0000001) LDDSeedlings double For LDD, the parameter defines $p$, the number of seedlings that is dispersed per discrete LDD-package. (default: 0.5) rings integer ‘rings’ defines the number of rings for which LDD dispersal is calculated.(default: 5)

### settings.soil

This section contains parameters for the ICBM/2N carbon and nitrogen cycling sub model. Find more details on the model and the parameters on the pages soil C and N cycling and soil parametrization and initialization.

 key datatype description soil dynamics settings useDynamicAvailableNitrogen bool if true, iLand utilizes the plant available N from the soil model to calculate species responses. If false, the static value world.site.availableNitrogen will be used. nitrogenDeposition double To account for external nitrogen input, a nitrogen deposition (kgN/ha*yr) is added to the available nitrogen which is derived by the dynamic soil module calculations. Default: 0. Note that nitrogen deposition is *not* added if the static world.site.availableNitrogen value is used. qb double C/N ratio of soil microbes qh double C/N ratio of SOM leaching double how many percent of the mineralized nitrogen in O is not available for plants but is leached (0..1) el double microbal efficiency in the labile pool, auxiliary parameter (see parameterization example) er double microbal efficiency in the refractory pool, auxiliary parameter (see parameterization example) snag settings (click for more details) swdDBHClass12 double class break between classes 1 and 2 for standing snags (dbh, cm) swdDBHClass23 double class break between classes 2 and 3 for standing snags (dbh, cm)

### settings.grass

This section contains settings related to the ground vegetation (grass and herbs) and its effect on regeneration success. See also XXX.

 key datatype description enabled boolean enable/disable the submodule. Default is false. grassPotential string function defining the potential grass cover 0..1 as a function of the light level of each 2x2m pixel value. The parameter is the light influence field (LIF), i.e. it is close to 1 for unobstructed conditions, and reach almost 0 within dense forests. See competition for light. Default value: polygon(lif, 0.1,0, 0.7,1) maxTimeLag numeric number of years needed by the grass/herb layer to grow from 0 to full cover. This settings defines the growth speed, i.e. how fast new openings are occupied by ground vegetation. grassEffect string formula describing the probability of prohibiting regeneration as a function of grass level. Parameter: the current grass level on the pixel 0..1.

### settings.browsing

This section contains settings related to the browsing effect by ungulate game species. See also browsing.

 key datatype description enabled boolean if false the browsing module is disabled, i.e. no effect is calculated. browsingPressure numeric scaling factor modifying the base probability (see above).

### species

This section identifies the source of the (many) species parameters, and some general parameters on this level.

 key datatype description source database table Defines the table in the input database that contains the species parameters (see species parameter for a detailed description) reader LIP file link to a binary LIP file containing the "reader"-matrices, i.e. a matrix for each crown radius class used to calculate theLightResourceIndex. nitrogenResponseClasses structure contains detailed parameters of the parameterization of nitrogen response classes. For syntax and expected key names see table below. CO2Response structure detailed parameters for the calculation of CO2 response. For expected variable names see table below. lightResponse structure define the shade tolerant and shade intolerant expressions for light responses as f(LRI). See table below. phenology structure definition of the available phenology types (e.g. broadleaved). See table below.

Nitrogen classes
Each of the three classes is defined by two coefficients (a and b):

<nitrogenResponseClasses>
<class_1_a>-0.045</class_1_a>
<class_1_b>2.5</class_1_b>
<class_2_a>-0.055</class_2_a>
<class_2_b>25</class_2_b>
<class_3_a>-0.065</class_3_a>
<class_3_b>40</class_3_b>
</nitrogenResponseClasses>

CO2 Response
The calculation of the CO2 response is based on the following parameters:

<CO2Response>
<p0>1</p0>
<baseConcentration>340</baseConcentration>
<compensationPoint>80</compensationPoint>
<beta0>0.3</beta0>
</CO2Response>

where:

• baseConcentration = base CO2 conceptration (for which the base RUE is derived- maybe average over 1961-1990, as most RUE observations/ studies relate to this period?) in ppm
• compensationPoint = compensation point of CO2 concentration (no production below) in ppm
• beta0 = relative productivity increase when doubling CO2 concentration (base beta (cf. Norby et al. 2005, Berthelot et al. 2005)) (unitless)
• p0 = relative starting point for multiplication (e.g. GPP) (unitless)

lightResponse
Tree species have a specific light response class in the range from 1 to 5. In the project file functions are defined for classes 1 and 5 respectively. Values between are linearly interpolated.

<lightResponse>
</lightResponse>

Phenology
In this section, the available phenology groups are defined. Each tree species is linked to one of these groups due to a species parameter. The number of available group is not limited. A group is identified by a numeric "id" which is also used to link species to phenology groups. The special id 0 is reserved for evergreen species. The Ids of the following groups start with 1.
Each group is identified by the following parameters used in the Jolly (Jolly et al 2005) model:

 Parameter description vpdMin VPD minimum kPa. vpdMax VPD maximum kPa. dayLengthMin minimum day length in hours. dayLengthMax maximum day length in hours. tempMin minimum temperature in °. tempMax maximum temperature in °.

The id of a group is an attribute of the type-tag. An XML-example looks like:

<phenology>
<type id="1">
<vpdMin>0.9</vpdMin>
<vpdMax>4.1</vpdMax>
<dayLengthMin>10</dayLengthMin>
<dayLengthMax>11</dayLengthMax>
<tempMin>2</tempMin>
<tempMax>9</tempMax>
</type>
<type id="2">
...
</type>
</phenology>

Sprouting
The section sprouting defines options for species that resprout.

 key datatype description adultSproutProbability numeric annual probability that one adjacent 2x2m pixel is colonized by lateral sprouts of adults (>4m)

### initialization

 key datatype description mode string describes the general mode. Following options: 'copy': initalize 1 resource unit, then copy to all others, 'unit': separate initailization for each resource unit, 'single': one initialization for the full area, 'map': init-files for each stand (defined by a map), 'snapshot': load from a database snapshot. See initialize trees for details. type string describes the type of the expected initialization file. Possible values: distribution or single (see also: initialize trees ). mapFileName string when using the map mode, the matching of stands and init files is defined in this file (see also: landscape setup ). randomFunction string defines the function (as an expression) used when estimating positions for individual trees (for init files of type distribution). file string path of the initialization file to be loaded. In mode unit this key needs to be overwritten by the environment file. If blank, no trees are loaded. saplingFile string path of the initialization file for saplings (see initialize trees). If blank, no saplings are loaded. subsection: snags (i.e.: model.initialization.snags) swdC double initial carbon content in (standing) snags (kg/ha) swdCN double CN ratio of snags swdCount double number of snags otherC double initial carbon content in the pools for other wood (i.e. branches and coarse roots). (kg/ha.). This content is split up into the five parts. otherCN double CN ratio of 'otherC' (branches, coarse roots). otherAbovegroundFraction double initial fraction (0..1) of C in the other pool from aboveground (branches) swdDecompRate double decay rate of standing snags (i.e. ksw) swdHalfLife double halflife attached to initial snags (years) subsection: heightGrid (i.e.: model.initialization.heightGrid) enabled boolean if true the top height grid is used fileName string the ESRI ASCII file that holds the tree top heights (default path is system.path.init). See also: here maxTries numeric The maximum number of attempts to find a suitable cell for a tree (default: 10) fitFormula string Equation that estimates the suitability of a target 10m cell based on the relative height of the tree compared to the top canopy height. default: polygon(x, 0,0, 0.8,1, 1.1, 1, 1.25,0)

### management

The management section controls the Javascript based management subsytem of iLand. See also management. Note that, the Javascript interface can be 'misused' for other (i.e., not management related) tasks as well.

 key datatype description enabled bool Management is disabled if the value is false. This switch relates to the "base" management subsystem. file string filename of the Javascript file to load (default path is the script path provided in the paths section). abeEnabled bool Switch for turning the agent based management engine on/off. ABE details are specified in the sub section abe.

### management.abe

This section contains settings related to the agent based management module of iLand.

 key datatype description file string Filename of the main Javascript file of ABE (relative paths are relative to the project root). agentDataFile string filename of the data file for the spatial setup of ABE (relative paths are relative to the project root).

### parameter

This section contains various switches and settings and provide fine grained control over iLand.

 key datatype description torus boolean if true, the simulation space is treated as a torus, where any influence (e.g. a light influence pattern) leaving on one side again enters at the opposite site. This is especially useful for small simulated areas to provide a continuous environment without edge effects. debug_tree expression a filter expression executed for trees during initialization. Textual debug output is generated only for those trees passing the filter. (e.g.: "ruindex=2 and dbh>30"). Providing an empty string is the fastest option when the debug data is not used. To enable debug output for all trees, set the value to '1' or 'true'. debug_clear boolean if true, text debug will be cleared after each simulation year. If set to false, the debug info is kept to provide time series information. gpp_per_year numeric if set, the production module is short-cut and this amound of NPP (kg/ha) is available for growth. debugDumpStamps boolean if true, the content of the LIP-files is dumped to the console. This feature is provided for debugging purposes.

## Module settings

This section of the XML file consists of module specific settings. A specific module has a dedicated node in the project file below the project top node. The general layout for a module named 'module_name' is as follows:

<project>
<system>...</system>
<model>...</model>
<module_name>
<enabled>true</enabled>
... module specific settings....
</module_name>
...
</modules>
...
</project>

See the module specific documentation for details of the parameters and the disturbance modules page for an overview.

## Output settings

### output

The output section defines which types of outputs should be created during model runs. Additionally, the behaviour of some of the outputs can be further fine-tuned.
Generally, this section contains for each type of output a section. This list holds only general settings applicable to all outputs. Details to output specific settings are provided elsewhere.

 key datatype description enabled boolean true for active outputs. mode string set to 'file' to create a text file (file name is the same as the table name), any other value creates a database table condition string provides a way to constrain the output to selected years (not available for all outputs, see Outputs for details).
Created by werner. Last Modification: Monday 29 of April, 2019 13:33:14 CEST by werner.