Initial conditions
The initialization of vegetation structure in the ED-2.2 model requires that the user define, for each polygon, the attributes of the hierarchy of sites, patches, and cohorts. It is usually relatively easy to convert plot census information into vegetation files by assuming each plot corresponds to a patch and each tree in a patch corresponds to a cohort. It may be necessary to break large plots or mapped stands into subplots. The following sections explain the structure on how to build these files. In order to use these files to initialize the model, the user must set NL%IED_INIT_MODE to 6. This option does not allow representing multiple sites. There is a legacy option with multiple sites for running with TOPMODEL (NL%IED_INIT_MODE=3), but TOPMODEL is no longer supported and may require code development and debugging to successfully run.
In case you would like to retrieve the forest structure from a previous ED-2.1 or ED-2.2 simulation, the user may set NL%IED_INIT_MODE=5 in ED2IN. Important: this will only set the forest structure from the previous simulation, but otherwise it will start a new simulation (e.g. soil moisture, vegetation temperature will use the typical initial conditions).
In case you would like to resume a previous simulation, use NL%RUNTYPE='HISTORY' in ED2IN. This will read every variable in the history file, and continue the simulation. Important: this option is intended to be used within the same version of the code (i.e. same Github commit): for example, you may want to use this option to resume a simulation interrupted due to a power outage. We strongly discourage setting NL%RUNTYPE='HISTORY' with a new commit and providing history files from an older commit.
Files types and formats for NL%IED_INIT_MODE=6
Below is the list of variables that must be provided in the pss file. The first line contains the header, and it is ignored.
Important. The columns must be given in the same order as below. The code will not check the header.
| Variable | Unit | Description |
|---|---|---|
| time | years | Year (dummy variable) |
| patch | string | Unique patch identifier (arbitrary, but it must be consistent with the css file) |
| trk | integer | Disturbance type. Allowed classes are
|
| age | years | Patch age since last disturbance |
| area | fraction | Fractional area represented by patch. The sum of the areas of all patches within the same site must add 1. |
| water | m3 m-3 | Soil moisture (dummy variable) |
| fsc | KgC m-2 | Fast soil carbon (below and above ground) |
| stsc | KgC m-2 | Structural soil carbon (below and above ground) |
| stsl | KgL m-2 | Structural soil lignin (below and above ground) |
| ssc | KgC m-2 | Slow soil carbon. If NL%DECOMP_SCHEME = 5, this will be partitioned amongst microbial, humified (slow) and passive pools |
| lai | mLeaf2 mGround-2 | Leaf area index (dummy variable) |
| msn | KgN m-2 | Mineralized soil nitrogen |
| fsn | KgN m-2 | Fast soil nitrogen (below and above ground) |
| nep | kgC m-2 yr-1 | Net ecosystem productivity (dummy variable) |
| gpp | kgC m-2 yr-1 | Gross primary productivity (dummy variable) |
| rh | kgC m-2 yr-1 | Heterotrophic respiration (dummy variable) |
Dummy variables are legacy variables that are no longer needed by ED-2. You can set them to zero, for example.
Below is the list of variables that must be provided in the css file. The first line contains the header, and it is ignored.
Important. The columns must be given in the same order as below. The code will not check the header.
| Variable | Unit | Description |
|---|---|---|
| time | years | Year (dummy variable) |
| patch | string | Patch identifier (arbitrary, but it must be consistent with the pss file) |
| cohort | string | Cohort identifier (arbitrary, it must be unique within the same patch) |
| dbh | cm | Stem diameter at breast height |
| hite | m | Tree height (dummy variable) |
| pft | integer | Plant Functional Type, consistent with the default numbers or the XML-defined PFTs |
| n | plant (stem) m-2 | Local (within-patch) stem density. |
| bdead | KgC plant-1 | Biomass of structural carbon (dummy variable) |
| balive | KgC plant-1 | Biomass of living tissues - leaf, fine root, sapwood, bark (dummy variable) |
| lai | mLeaf2 mGround-2 | Leaf area index (dummy variable) |
Dummy variables are legacy variables that are no longer needed by ED-2. You may want to include the values to keep things consistent, but otherwise, you may set them to zero.
Files types and formats for NL%IED_INIT_MODE=3 (Currently not supported)
This file comes in two formats and file format is specified in the file header:
nsites <num> file_format <ff>
Both file formats then contain a site attribute header line and then the following site attributes.
Important. The columns must be given in the same order as below. The code will not check the header.
| Attribute | Unit | Description |
|---|---|---|
| sitenum | Integer | Site number |
| area | Dimensionless | Site fractional area |
| TCI | Dimensionless | Topography convergence index (Bevin and Kirkby, 1979)) |
| elev | m | Elevation |
| slope | degrees | Slope |
| aspect | degrees | Aspect |
| soil | 1-17 | Soil class (see NL%NSLCON in ED2IN) |
For file format #2 there is then an N x (N+1) adjacency matrix that is used in the runoff calculation. For file format 1 the adjacency matrix is approximated based on the proportional abundance of each site and assuming a random distribution of sites. File format #3 is like #1 but a soil class is specified for each soil layer rather than one class for all layers. The adjacency matrix has N+1 columns because the last column is the transition to the water patch.
The patch file is a space delimited ASCII file, that describe patch-level properties such are the are and the soil carbon and nitrogen stocks. The first line contains the header, and it is ignored. Important. The columns must be given in the same order as below. The code will not check the header.
| Variable | Units | Description |
|---|---|---|
| time | years | Year (dummy variable) |
| Site | integer | Site number (arbitrary, but it must be consistent with the site file) |
| patch | string | Unique patch identifier (arbitrary, but it must be consistent with the css file) |
| trk | integer | Disturbance type. Allowed classes are
|
| age | years | Patch age since last disturbance |
| area | fraction | Fractional area represented by patch. The sum of the areas of all patches within the same site must add 1. |
| water | m3 m-3 | Soil moisture (dummy variable) |
| fsc | KgC m-2 | Fast soil carbon (below and above ground) |
| stsc | KgC m-2 | Structural soil carbon (below and above ground) |
| stsl | KgL m-2 | Structural soil lignin (below and above ground) |
| ssc | KgC m-2 | Slow soil carbon. If NL%DECOMP_SCHEME = 5, this will be partitioned amongst microbial, humified (slow) and passive pools |
| psc | dimensionless | Dummy variable, for back-compatibility with ED-1 |
| msn | KgN m-2 | Mineralized soil nitrogen |
| fsn | KgN m-2 | Fast soil nitrogen (below and above ground) |
Dummy variables are legacy variables that are no longer needed by ED-2. You can set them to zero, for example.
Below is the list of variables that must be provided in the css file. The first line contains the header, and it is ignored.
Important. The columns must be given in the same order as below. The code will not check the header.
| Variable | Unit | Description |
|---|---|---|
| time | years | Year (dummy variable) |
| patch | string | Patch identifier (arbitrary, but it must be consistent with the pss file) |
| cohort | string | Cohort identifier (arbitrary, it must be unique within the same patch) |
| dbh | cm | Stem diameter at breast height |
| hite | m | Tree height (dummy variable) |
| pft | integer | Plant Functional Type, consistent with the default numbers or the XML-defined PFTs |
| n | plant (stem) m-2 | Local (within-patch) stem density. |
| bdead | KgC plant-1 | Biomass of structural carbon (dummy variable) |
| balive | KgC plant-1 | Biomass of living tissues - leaf, fine root, sapwood, bark (dummy variable) |
| lai | mLeaf2 mGround-2 | Leaf area index (dummy variable) |
Dummy variables are legacy variables that are no longer needed by ED-2. You may want to include the values to keep things consistent, but otherwise, you may set them to zero.
A sample set of scripts to convert forest inventory plots to pss/css files (NL%IED_INIT_MODE=6) is available here. Currently this script works only for tropical forest PFTs.
To use it, you must download all the three files, and place them in the same directory.
-
allometry.r. This subroutine computes the dummy variables in the css files, so they are consistent. -
pft_allom_table.csv. List of default parameters by allometry (consistent as of Jan 2019). -
make_bioinit.r. The main script, which calls/reads the other files.
You must also provide a standardised forest inventory plot file in CSV format. The script expects the following variables (names are case sensitive and must appear in the first line of the CSV file, the order does not matter).
| Variable | Description. |
|---|---|
| plots | Unique plot identification. Refrain from using very large plots. The definition of "gap" in ED-2 is typically associated with the crown area of a large tree (about 175 m2 in the tropics). In case the plot is much larger than this, split the original plots and provide the smaller plots in the CSV file. |
| tag | Unique ID for tree. Do not repeat tags for trees in the same plot. |
| scientific | Scientific name. Currently not used by the script, but it could be useful for non-tropical PFTs. |
| wood.dens | Wood density (g cm-3). In case the wood density is not known, use some wood density data base (e.g. Chave et al.,2009) and the scientific names to provide estimates. |
| dbh | Stem diameter at breast height (cm). |
You must also edit the first few lines of the make_bioinit.r script, specifically, set the following variables:
| Variable | Description |
|---|---|
| place | Name of the site, for output directory. |
| census.csv | Name of the CSV file with the forest inventory data (no paths). |
| iata | Short code used to identify the site. |
| identity | Tag for forest inventory data (it may be useful for multiple data sets in the same site). |
| lon | Site longitude. Longitude goes from -180 to 180. Make sure to use the correct coordinates, because ED-2 reads this information. |
| lat | Site latitude. Make sure to use the correct coordinates, because ED-2 reads this information. |
| year | Year of measurements, used to populate dummy variable year. |
| subplot.area | Area of sub-plots (m2), in case of differential sampling efforts. Put the full size in case all trees the same sampling effort was used for all measured trees. |
| allplot.area | Total plot area (m2). |
| nplots | Number of plots. |
| min.dbh.subplot | Minimum DBH (cm) for trees to be measured in the sub-plot. In case the same sampling effort was used for all measured trees, set this to the minimum DBH measured in the plot. |
| min.dbh.allplot | Minimum DBH (cm) for trees to be measured in the entire plot. |
| fast.soil.c | Carbon stocks in the fast (metabolic litter + microbial) soil carbon (kgC m-2). Currently the same value is used for all plots. |
| struct.soil.c | Carbon stocks in the structural (woody debris) soil carbon (kgC m-2). Currently the same value is used for all plots. |
| struct.soil.l | Lignin stocks in the structural (woody debris) soil carbon (kgL m-2). Currently the same value is used for all plots. |
| fast.soil.c | Carbon stocks in the slow (humified + passive) soil carbon (kgC m-2). Currently the same value is used for all plots. |
| min.soil.n | Nitrogen stocks in the mineralised pool (kgN m-2). Currently the same value is used for all plots. |
| fast.soil.c | Nitrogen stocks in the fast (metabolic litter + microbial) soil pool (kgN m-2). Currently the same value is used for all plots. |
| iallom | Allometric setting to fill in the dummy variables in the css files. This is consistent with NL%IALLOM in ED2IN. |
| pft.idx | List of PFTs to use. Currently the script works only for tropical forest PFTs (2,3,4). |
Soil texture is used to determine various hydraulic and thermal parameters in ED2. The canonical soil texture types in ED2 represent the entire range of silt, clay, and sand fractions, and closely follows the USDA texture classification but with further division of clayey soils that are frequently found in tropical regions.
| Soil class | NL%SLCON | Sand (%) | Silt (%) | Clay (%) |
|---|---|---|---|---|
| Sand (Sa) | 1 | 92.0 | 5.0 | 3.0 |
| Loamy sand (LSa) | 2 | 82.5 | 11.5 | 06.0 |
| Sandy loam (SaL) | 3 | 66.0 | 23.0 | 11.0 |
| Silt loam (SiL) | 4 | 20.0 | 64.0 | 16.0 |
| Loam (L) | 5 | 41.0 | 42.0 | 17.0 |
| Sandy clay loam (SaCL) | 6 | 59.0 | 14.0 | 27.0 |
| Silty clay loam (SiCL) | 7 | 10.0 | 56.0 | 34.0 |
| Clay loam (CL) | 8 | 32.0 | 34.0 | 34.0 |
| Sandy clay (SaC) | 9 | 52.0 | 6.0 | 42.0 |
| Silty clay (SiC) | 10 | 6.0 | 47.0 | 47.0 |
| Clay (C) | 11 | 20.0 | 20.0 | 60.0 |
| Peat (P) | 12 | -- | -- | -- |
| Bedrock (BR) | 13 | -- | -- | -- |
| Silt (Si) | 14 | 7.5 | 87.5 | 5.0 |
| Heavy clay (CC) | 15 | 10.0 | 10.0 | 80.0 |
| Clayey sand (CSa) | 16 | 37.5 | 10.0 | 52.5 |
| Clayey silt (CSi) | 17 | 12.5 | 35.0 | 52.5 |
The peat and bedrock hydraulic and thermal properties are not determined through texture fraction.
Soil texture can be initialised in a few different ways in ED2:
- Read from existing soil texture data bases. To do this, you must set NL%ISOILFLG=1 and provide the path to the collection of gridded texture files (in HDF5 format) in NL%SOIL_DATABASE. In case you have gridded sand, silt, and clay data (e.g., from SoilGrids) and would like to convert the data to HDF5, consider the R scripts available here.
- Specify the soil texture class for all polygons. To do this, set NL%ISOILFLG=2, and set NL%NSLCON to the preferred texture. Make sure variables NL%SLXSAND and NL%SLXCLAY are outside the range [0-1].
- Specify the sand and clay fractions for all polygons. To do this, set NL%ISOILFLG=2, and set variables NL%SLXSAND and NL%SLXCLAY are set bounded between 0 and 1, and that their sum is also bounded between 0 and 1.
Currently the three approaches assume constant soil texture classes across all layers. There is ongoing efforts to allow heterogeneous textures and this may change in the future. Also, note that if you use the van Genuchten (1980) based parametrisation (NL%SOIL_HYDRO_SCHEME=2), you must specify additional properties, namely: soil organic content (NL%SLSOC), soil pH (NL%SLPH), soil cation exchange capacity ((NL%SLCEC)), and dry bulk density ((NL%SLDBD)). If unsure, you can obtain estimates from SoilGrids, but currently the model cannot read gridded data for these properties.
Soil depth to bedrock controls the maximum rooting depth of plants and can be an important abiotic constraint. In ED2, there are a few different ways to specify the depth:
- For single polygon runs, it is possible to specify the soil layers in ED2IN (variable NL%SLZ) down to the depth to bedrock or the maximum rooting depth in the case of very deep soils. In both cases, it is advisable to also set the bottom soil boundary conditions accordingly (variables NL%ISOILBC and NL%SLDRAIN in ED2IN).
- For regional simulations, or to avoid adjusting the soil layers for each polygon of interest, it is possible to read soil depth through gridded data bases. In this case, set NL%ISOILDEPTHFLG=2 and provide the path and prefix of gridded data in NL%SOILDEPTH_DB=2 in ED2IN. The gridded data set must be provided in HDF5 format; in case you have gridded soil depth data (e.g., from SoilGrids) and would like to convert the data to HDF5, consider using the R scripts available here.
There are a number of ways for the user to prescribe the initial soil temperature, and soil moisture content. These are controlled by the ED2IN setting ISTWFLG:
- 0 – Interpolate from the coarser nested grid
- 1 – Read values from file (ISTWFLN)
- 2 – Set values prescribed values
For case 1, refer to the function “ecmwf_soil” for the exact file format. For case 2, soil moisture is set based on the values given in the ED2IN setting SLMSTR. Soil temperature, on the other hand, is based on subtracting the values in STGOFF from the air temperature. In all cases, soil heat is set based on soil temperature and moisture.
Land cover setting is specified by the ED2IN setting IVEGTFLG. This setting is used only for regional runs, and the idea is to eliminate polygons that would fall over a water body (ocean, lakes, rivers). In case of regional run, the first grid should always have IVEGTFLG set to 1. The standard land cover setting comes from the Olson Global Ecosystem data with roughly 1 km resolution. Even though the data itself contains information on which type of vegetation (or water) exists at each point, all that ED2 uses is the information on whether the point has land or water.
The subroutines that control the land cover mapping are adaptations of the ones available at RAMS and BRAMS.