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"?>   ...    ...    ...    ...    ...

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.

keydatatypedescription
indatabase filedefines the input database. Stored in this database are e.g. species parameter.
outdatabase fileresult (see Outputs) are written to this database.
climatedatabase filethe SQLite database containing the climate data

 

settings

keydatatypedescription
multithreadingbooleanif true, iLand will use several threads to perform its calculations (if more than 10 [[[[RessourceUnits]] are defined)
threadCountintegernumber of used threads if multithreading is enabled. -1 uses all available CPU cores.
responsivebooleanif true iLand is more responsive during lengthy calculations (i.e. the user interface freezes less frequently)
randomSeedintegerNon-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.
logLevelstringThis 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.
expressionLinearizationEnabledbooleanif true, specific expressions (user defined formulas, e.g. for light response) use a interpolation approach to increase the calculation performance
debugOutputintegerdefined 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).
debugOutputAutoSavebooleanif true, csv-output files are created for each active debug output and saved to the temp directory (see Path-section).

 

logging

keydatatypedescription
logTargetstringeither 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
logFilestringLog-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").
flushbooleanlog 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.

keydatatypedescription
fileNamestringthe filename of a javascript file to load. Default location is the "scripts"-directory.

 

Model settings

world

keydatatypedescription
cellSizenumericThe size of pixels of the light grid (m). The default is 2m
widthnumerichorizontal (east-west) extent of the simulation area (m)
heightnumericvertical (north-south) extent (meter)
buffernumerica buffer zone with the given width is attached to the rectangle of the simulation area (defined by width and height).
resourceUnitsAsGridbooleanif true, each resource unit is a 100x100m pixel.
latitudenumericLatitude of project area (in degree). Used for day of length calculation.
environmentEnabledbooleanif true, the spatial distribution of several model parameters is loaded from an environment file. See keys below and the pages initialization and simulation extent for details.
environmentFilestringfilename of the environment file. Default path is the project path. See for more details.
environmentModestringThis settings determines how the environment file is interpreted. Possible values are grid and matrix. In grid-mode a GIS grid defines the spatial pattern, in matrix mode resource units are addressed using the resource unit index. See for details.
environmentGridstringFilename of the GIS grid which is used in grid-mode. The grid contains integer IDs which are used to map the parameter values in the environment file to resource units within the landscape.
timeEventsEnabledboolif true, the time event mechanism is enabled. Similar to the spatial parameter distribution (see above), project settings can be linked to specific year to change.
timeEventsFilestringfilename of the "time events" file. This is a simple CSV-style file with a fixed column year and user-defined columns with column names of valid project file keys.
DEMstringif not empty, a digital elevation model is read from a file (ESRI ASCII raster, relative to the project root). See also simulation extent.
subsection: areaMask (i.e. model.world.areaMask)
enabledboolif true, the mask of valid project area is retrieved from an image (located at imageFile). See for more.
imageFilestringfilename of the image file used for the overlay.
subsection: location (i.e. model.world.location)
xnumericThe following keys (x, y, z, rotation) specify the location of the 0/0 point of the local iLand coordinate in the (metric) coordinate system of GIS-based input data. See landscape setup for details. x is the offset in x-direction.
ynumericSee above. y is the offset in y-direction.
znumericSee above. z is the offset in z-direction (height). Usually 0.
rotationnumericSee above. A value for rotation rotates the GIS-based input data. Note that this can have side-effects with e.g. the orientation of LIP-patterns. rotation is given in degrees.
subsection: standGrid (i.e. model.world.standGrid)
enabledbooleanIf true, the stand grid is loaded and used.
fileNamestringpath to the stand grid file (ESRI ASCII format, relative to the project root). See also the section location, and landscape setup.

 

site

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

keydatatypedescription
availableNitrogennumericplant available nitrogen kg/ha/year
soil properties - water cycle
soilDepthnumericDepth of root accessible soil in cm
pctSandnumericPercentange of sand (0..100) in soil. See water cycle.
pctSiltnumericPercentange of silt (0..100) in soil. See water cycle.
pctClaynumericPercentange of clay (0..100) in soil. See water cycle
soil properties - carbon and nitrogen cycling
youngLabileCnumeric(initial) carbon content of ylC (i.e. litter) soil pool (kg/ha)
youngLabileNnumeric(initial) nitrogen content of ylC soil pool (kg/ha)
youngLabileDecompRatenumeric(initial) decomposition rate of yl pool
youngLabileAbovegroundFractionnumeric(initial) fraction of aboveground C in the litter (yL) layer (foliage)
youngRefractoryCnumeric(initial) carbon content of yrC (woody) soil pool (kg/ha)
youngRefractoryNnumeric(initial) nitrogen content of yrC (woody) soil pool (kg/ha)
youngRefractoryDecompRatenumeric(initial) decomposition rate of yr pool
somCnumeric(initial) carbon content of oC (soil organic matter) soil pool (kg/ha)
somNnumeric(initial) nitrogen content of oN (soil organic matter) soil pool (kg/ha)
somDecompRatenumericdecomposition rate for soil organic matter (i.e. the "old" pool sensu ICBM)
youngRefractoryAbovegroundFractionnumericfraction (0..1) of C in the yR pool from aboveground sources (branches, stems)
soilHumificationRatenumerichumification rate

 

climate

Source and properties of the used climate (see also ClimateData).

keydatatypedescription
tableNamestringName of the SQLite table within the defined climate database to load (system.database.climate).
filterstringan optional filter criterion that is added to the where clause of the SQL for reading the climate data. This can be useful e.g. for skipping parts of the climate records. Example: 'year>2000 and year<2010' limits used climate data to the years 2001 to 2009. See also randomSamplingEnabled.
co2concentrationnumericcurrent value of the atmospheric CO2 concentration. Default value is 380ppm. A time series may be implementing using the Time-Event feature. See also section world.species.CO2Response
co2pathwaystringselects a pre-defined CO2 concentration pathway, one of 'RCP2.6', 'RCP4.5', 'RCP6.0', 'RCP8.5', and 'No' (for no change, is the default). See also ClimateData
co2startYearnumericif a co2pathway is used, then co2startYear defines the starting point of CO2 concentration within the simulation. See also ClimateData
batchYearsintegerfor performance reasons the access to the climate database accesses is performed bulked. This setting specifies how many years are loaded at once.
temperatureShiftdoublesimple option to modify the climate. The value is added to each daily temperature (default = 0)
precipitationShiftdoublesimple option to modify the climate. The daily precipitation is multiplied for each day with this value. (default = 1).
randomSamplingEnabledbooleanif true, only the first batchYears of the climate file are loaded (but see filter). The actual climate for each year is the sampled from this climate data. See also randomSamplingList. (default=false)
randomSamplingListstringif this key contains a list of 0-based indices (e.g. "3, 12, 14, 0, 3, 14", the random sampling (if enabled) uses this sequence of years. Note: the index is 0-based (in the example the 4th year would be used first). Use any non-word characters as delimiters. The list will be recycled if more years are simulated than present in the list. The index values are to be between 0 and batchYears-1. If invalid indices are in the list, an error is reported. If the key is empty or not present, each year a climate year is selected randomly from the list of loaded years. default=empty

 

settings

This section is about global model settings.

keydatatypedescription
General switches
growthEnabledbooleanif false, trees will apply/read light patterns, but do not grow
mortalityEnabledbooleanif false, tree mortaliy (intrinsic and stress related) will not be executed. Management works.
regenerationEnabledbooleanif true, the regeneration submodule is enabled (seed production, seed dispersal, establishment, sapling growth, recruitment)
carbonCycleEnabledbooleanif true, the snag dynamics and soil CN cycling sub-modules are enabled.
Light calculations
lightExtinctionCoefficientnumeric"k" parameter (beer lambert) used for calc. of absorbed light on resourceUnit level
lightExtinctionCoefficientOpacitynumeric"k" for beer lambert used for opacity of single trees
temperatureTaunumeric"tau"-value for delayed temperature calculation acc. to Mäkela 2008
Production
epsilonnumeric3PG's maximum efficiency in GPP production (default value: 1.8).
usePARFractionBelowGroundAllocationboolchanges 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
airDensitynumericdensity of air (kg / m3)
laiThresholdForClosedStandsnumericFor the calculation of the maximum canopy conductance a ramp is assumed for LAI values below this threshold. Default: 3
boundaryLayerConductancenumericboundary layer conductance for the evaporation calculation. Default value: 0.2 m/s
waterUseSoilSaturationboolif 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.
interceptionStorageNeedlenumericasymptotic crown storage capacity for intercepted rain water of confiers. (default: 4).
interceptionStorageBroadleafnumericasymptotic crown storage capacity for intercepted rain water of deciduous trees. (default: 2).
snowMeltTemperaturenumericthreshold 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.
groundVegetationLAInumericthe minimum leaf area index of a resource unit for the water cycle. See transpiration and conductance in saplings.
groundVegetationPsiMinnumericthe assumed $\Psi_{min}$ of ground vegetation. See transpiration and conductance in saplings.
heatCapacityAirdeprecatedSpecific heat capacity of air (J /(kg °C))
airPressuredeprecatedatmospheric 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.

keydatatypedescription
dumpSeedMapsEnabledbooleanif "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)
dumpSeedMapsPathstringtarget directory for seed maps / seed kernel dumps
externalSeedEnabledbooleanif "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.
externalSeedSpeciesstringlist of species (case sensitive!) with external seed input (e.g., "Psme, Abmi").
externalSeedSourcestringcardinal 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.
externalSeedBufferstringThis 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.
externalSeedBackgroundInputstringspecifies 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).
recruitmentDimensionVariationdoubledefines 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.

keydatatypedescription
enabledbooleanthe submodule is only active if enabled is true.
widthnumericthe 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.
sizeXnumericthe number of sectors in x-direction. Sectors are used to specify fine grained species distribution within the belt.
sizeYnumericthe number of sectors in y-direction. Sectors are used to specify fine grained species distribution within the belt.
species__stringspecifies 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.

keydatatypedescription
thresholdAreadoubleThe threshold defines the density of potential seedlings per m² up to which a full kernel is used (default: 0.0001)
thresholdLDDdoubleThe threshold (again, seedlings per m²) defines the maximum distance of long-distance-dispersal (default: 0.0000001)
LDDSeedlingsdoubleFor LDD, the parameter defines $p$, the number of seedlings that is dispersed per discrete LDD-package. (default: 0.5)
ringsinteger‘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.

keydatatypedescription
soil dynamics settings
useDynamicAvailableNitrogenboolif 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.
nitrogenDepositiondoubleTo 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.
qbdoubleC/N ratio of soil microbes
qhdoubleC/N ratio of SOM
leachingdoublehow many percent of the mineralized nitrogen in O is not available for plants but is leached (0..1)
eldoublemicrobal efficiency in the labile pool, auxiliary parameter (see parameterization example)
erdoublemicrobal efficiency in the refractory pool, auxiliary parameter (see parameterization example)
snag settings (click for more details)
swdDBHClass12doubleclass break between classes 1 and 2 for standing snags (dbh, cm)
swdDBHClass23doubleclass 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.

keydatatypedescription
enabledbooleanenable/disable the submodule. Default is false.
grassPotentialstringfunction 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)
maxTimeLagnumericnumber 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.
grassEffectstringformula 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.

keydatatypedescription
enabledbooleanif false the browsing module is disabled, i.e. no effect is calculated.
browsingPressurenumericscaling 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.

keydatatypedescription
sourcedatabase tableDefines the table in the input database that contains the species parameters (see species parameter for a detailed description)
readerLIP filelink to a binary LIP file containing the "reader"-matrices, i.e. a matrix for each crown radius class used to calculate theLightResourceIndex.
nitrogenResponseClassesstructurecontains detailed parameters of the parameterization of nitrogen response classes. For syntax and expected key names see table below.
CO2Responsestructuredetailed parameters for the calculation of CO2 response. For expected variable names see table below.
lightResponsestructuredefine the shade tolerant and shade intolerant expressions for light responses as f(LRI). See table below.
phenologystructuredefinition 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):

-0.045  2.5  -0.055  25  -0.065  40

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

1  340  80  0.3

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.

1-exp(-6*(lri-0.05))  1-exp(-3*(lri-0.01))

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:

Parameterdescription
vpdMinVPD minimum kPa.
vpdMaxVPD maximum kPa.
dayLengthMinminimum day length in hours.
dayLengthMaxmaximum day length in hours.
tempMinminimum temperature in °.
tempMaxmaximum temperature in °.

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

0.9  4.1  10  11  2  9     ...

Sprouting The section sprouting defines options for species that resprout.

keydatatypedescription
adultSproutProbabilitynumericannual probability that one adjacent 2x2m pixel is colonized by lateral sprouts of adults (>4m)

 

initialization

 

keydatatypedescription
modestringdescribes 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.
typestringdescribes the type of the expected initialization file. Possible values: distribution or single (see also: initialize trees ).
mapFileNamestringwhen using the map mode, the matching of stands and init files is defined in this file (see also: landscape setup ).
randomFunctionstringdefines the function (as an expression) used when estimating positions for individual trees (for init files of type distribution).
filestringpath 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.
saplingFilestringpath of the initialization file for saplings (see initialize trees). If blank, no saplings are loaded.
subsection: snags (i.e.: model.initialization.snags)
swdCdoubleinitial carbon content in (standing) snags (kg/ha)
swdCNdoubleCN ratio of snags
swdCountdoublenumber of snags
otherCdoubleinitial 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.
otherCNdoubleCN ratio of 'otherC' (branches, coarse roots).
otherAbovegroundFractiondoubleinitial fraction (0..1) of C in the other pool from aboveground (branches)
swdDecompRatedoubledecay rate of standing snags (i.e. ksw)
swdHalfLifedoublehalflife attached to initial snags (years)
subsection: heightGrid (i.e.: model.initialization.heightGrid)
enabledbooleanif true the top height grid is used
fileNamestringthe ESRI ASCII file that holds the tree top heights (default path is system.path.init). See also: here
maxTriesnumericThe maximum number of attempts to find a suitable cell for a tree (default: 10)
fitFormulastringEquation 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.

keydatatypedescription
enabledboolManagement is disabled if the value is false. This switch relates to the "base" management subsystem.
filestringfilename of the Javascript file to load (default path is the script path provided in the paths section).
abeEnabledboolSwitch 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.

keydatatypedescription
filestringFilename of the main Javascript file of ABE (relative paths are relative to the project root).
agentDataFilestringfilename 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.

keydatatypedescription
torusbooleanif 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_treeexpressiona 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_clearbooleanif 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_yearnumericif set, the production module is short-cut and this amound of NPP (kg/ha) is available for growth.
debugDumpStampsbooleanif 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:

......  true  ... module specific settings..........

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.

keydatatypedescription
enabledbooleantrue for active outputs.
modestringset to 'file' to create a text file (file name is the same as the table name), any other value creates a database table
conditionstringprovides a way to constrain the output to selected years (not available for all outputs, see Outputs for details).