| | 157 | The model ORCHIDEE can run in offline mode. Different predefined experiment set ups can be found in folder ORCHIDEE_OL, see section [wiki:Documentation/TrunkFunctionality4#Experiments Experiments] further below. |
| | 158 | |
| | 159 | The model can also be coupled to an atomspheric model and be run in coupled mode. For example in the coupled model IPSL-CM, ORCHIDEE is coupled to the atmospheric model LMDZ and the ocean model NEMO. |
| | 160 | === Consistency checks === |
| | 161 | Describes r6947. The code distinguishes between three options to check for mass and surface conservation. These options are controlled by the parameter '''err_act'''. Always use err_act = 3 when developing and testing the code. Note that in addition to checking for mass balance closure ORCHIDEE trunk will also check for the conservation of veget_max and frac_nobio. This is useful to make sure no surface area is lost when moving biomass from one PFT to another following natural disturbances, forest management, land cover changes and when using age classes. In some parts of the code, for example, modules that deal with disturbances, it is assumed that the tallest trees are stored in the last diameter class. When the difference in diameter between diameter classes becomes very small, this assumption could be violated. Therefore, the diameter classes are sorted to enforce the assumed order and where needed the order is checked. |
| | 162 | * err_act = 1 is recommended when running global long-term simulations. Under this option, mass balance closure is checked for all biogeochemical processes but only at the highest level thus stomate.f90 and stomate_lpj.f90. Although the mass balance checks are not very expensive in terms of computer time, skipping the numerous lower level checks is expected to save some time. Under this option the total mass balance error is only written to the history file. No information is provided in which subroutine the problem occurred. |
| | 163 | * err_act = 2 is recommended when developing and testing the model. Now the mass balance is explicitly checked in stomate.f90, stomate_lpj.f90 and all its subroutines. Under this option the mass balance error is written to the history file and if the mass balance is not closed, the warning message will indicate in which subroutine the problem likely originated. |
| | 164 | * arr_act = 3 is recommended when having a problem with mass balance closure. The mass balance is explicitly checked in stomate.f90, stomate_lpj.f90 and all its subroutines. If a mass balance error occurs, the model is stopped. It is expected that within the time step of the subroutine a precision of 1e-8 is achieved. If not the model will crash. Additionally consistency between flux-based and pool-based NBP is checked. This check represent an integrated check which give confidence for the technical implementation of the C and N cycles. Comparing the flux and pool based nbp estimates is an instantaneous check that covers just a single day in the model (thus 48 time steps for the soil and litter calcuations which are called from stomate.f90). The cross-consistency check for the flux and pool based NBP requires mass balance closure and area preservation from all all subroutines being called from stomate.f90 including stomate_lpj.f90. This check should always be satisfied, if not there is a bug somewhere! The mass balance of individual subroutines teaches us about the calculations performed within that subroutine. The flux and pool based NBP consistency check teaches us of how these fluxes and pools should be accounted for, passing this check requires additional understanding of the flow of the code (i.e., bm_to_litter) and how the different time steps come together. |
| | 165 | |
| | 166 | As an additional consistency check the time integral of the NBP (from 0 -> t) should equal the C and N stock at time step t. Comparing the time integral of NEP vs the all pools includes all the accumulated precision errors. If those errors would be random there would be no problem but they are more likely biases. Hence, when the fluxes and pools increase several order of magnitudes (e.g toward 1e4) and a small bias (1e-12) is integrated over 10,000 days (1e4) the divergence between the time integral of NEP and the pools will approach/exceed 1-8 and woukd stop the model. This is a fundamental problem related to machine precision and the way we do the calculations (think of the so called catastrophic rounding errors that may occur with floating numbers). For this reason this check is written to the history files but does not make the model crash. The user will have to decide whether (s)he is facing a precision error or a real bug. Fixing precision errors will require to improve the precision of the calculations in one or several subroutines. |
| | 167 | |
| | 168 | The variable MBC_NBP3_c was added to enable monitoring whether the NBP send to LMDZ in intersurf.f90 is identical to the NBP calculated in stomate_lpj.f90. If ERR_ACT=3 is used, the model will crash if the NBP send in intersurf differs from the NBP calculated in stomate_lpj.f90. Irrespective of the value of ERR_ACT, the mismatch between both NBPs will be send to MBC_NBP3_c. |
| | 169 | |
| | 170 | |
| | 171 | === Croplands === |
| | 172 | Describes r7767. Makes use of sapiens_planting and sapiens_harvest. Planting and harvest is determined by temperature and soil moisture using the moigdd phenology type. At senescence, 50% of the aboveground biomass is placed into the harvest_pool (just like wood) and its decomposition is accounted for in the fluxes from the product use pool. The remaining 50% of aboveground biomass enters the litter pool, along with all of the roots. |
| | 173 | |
| | 174 | |
| | 175 | === CWRR vs Choinel === |
| | 176 | Describes r6614. Following ORCHIDEE trunk 3, the Choinel code is no longer available in ORCHIDEE trunk. The hydrological schemes were not touched during the development of ORCHIDEE trunk. The hydraulic architecture in ORCHIDEE trunk relies on CWRR. |
| | 177 | |
| | 178 | |
| | 179 | === Diameter classes === |
| | 180 | Describes r6614. Diameter classes were introduced to better simulate the canopy structure, they are a tool to simulate heterogeneity within a single PFT. Given that the canopy is the interface between the land and the atmosphere this feature has effects well beyond forest management. Stand structure was observed to affect albedo, transpiration, photosynthesis, soil temperature, roughness length, and recruitment. Using diameter classes adds very little complexity to setting-up the simulations as well as to the output files. The complexity is mostly within the code. |
| | 181 | |
| | 182 | The computational cost of using diameter classes is negligible and when a reasonable low number of diameter classes is used, the memory cost remains very small as the dimensions of only two variables are increased. The number of diameter classes is the same for all PFTs and is set by the parameter '''NCIRC'''. ORCHIDEE-CN, and ORCHIDEE-CNP are coded and used for NCIRC = 1. ORCHIDEE trunk was coded and tested for NCIRC = 3. Until further testing, three diameter classes are considered sufficient although for some specific application, i.e., simulating tree ring width NCIRC = 5 resulted in slightly better model performance. The branch ORCHIDEE-CN-CAN that preceded this trunk version has been run with one diameter class as well (this should be confirmed for ORCHIDEE trunk). |
| | 183 | |
| | 184 | Given earlier choices in the ORCHIDEE model, we either need to define the boundaries of each diameter class or the diameter distribution. While developing the code, we considered the second approach the most flexible. To allow maximal flexibility, each diameter class needs to be defined separately by the variable '''CIRC_CLASS_DIST_0000X''', where X is the number of the diameter class. The smallest number presents the smallest diameter class. From literature it is known that a truncated exponential distribution is a good first guess: |
| | 185 | {{{ |
| | 186 | CIRC_CLASS_DIST_00001=9 |
| | 187 | CIRC_CLASS_DIST_00002=5 |
| | 188 | CIRC_CLASS_DIST_00003=1 |
| | 189 | }}} |
| | 190 | The above declaration implies that 9/15th of the trees will always be in the smallest diameter class, 5/15th will be in the medium class and 1 tree out of 15 will be in the largest diameter class. These ratios are kept throughout the simulations and the boundaries of the diameter classes are adjusted to respect this constraint. Consequently, an even-aged stand will be simulated with three diameter classes where the diameter of the first class may be, for example, 20.3 cm, the diameter of the second class 20.4 cm and the diameter of the third class 20.5 cm. The same code and set-up allows to simulate, in the same simulation, an uneven-aged stand for the same PFT but in a different pixel with, for example, the smallest diameter 7 cm, the medium diameter 25 cm and the largest diameter 45 cm. |
| | 191 | |
| | 192 | === Experiments === |
| 175 | | |
| 176 | | === Consistency checks === |
| 177 | | Describes r6947. The code distinguishes between three options to check for mass and surface conservation. These options are controlled by the parameter '''err_act'''. Always use err_act = 3 when developing and testing the code. Note that in addition to checking for mass balance closure ORCHIDEE trunk will also check for the conservation of veget_max and frac_nobio. This is useful to make sure no surface area is lost when moving biomass from one PFT to another following natural disturbances, forest management, land cover changes and when using age classes. In some parts of the code, for example, modules that deal with disturbances, it is assumed that the tallest trees are stored in the last diameter class. When the difference in diameter between diameter classes becomes very small, this assumption could be violated. Therefore, the diameter classes are sorted to enforce the assumed order and where needed the order is checked. |
| 178 | | * err_act = 1 is recommended when running global long-term simulations. Under this option, mass balance closure is checked for all biogeochemical processes but only at the highest level thus stomate.f90 and stomate_lpj.f90. Although the mass balance checks are not very expensive in terms of computer time, skipping the numerous lower level checks is expected to save some time. Under this option the total mass balance error is only written to the history file. No information is provided in which subroutine the problem occurred. |
| 179 | | * err_act = 2 is recommended when developing and testing the model. Now the mass balance is explicitly checked in stomate.f90, stomate_lpj.f90 and all its subroutines. Under this option the mass balance error is written to the history file and if the mass balance is not closed, the warning message will indicate in which subroutine the problem likely originated. |
| 180 | | * arr_act = 3 is recommended when having a problem with mass balance closure. The mass balance is explicitly checked in stomate.f90, stomate_lpj.f90 and all its subroutines. If a mass balance error occurs, the model is stopped. It is expected that within the time step of the subroutine a precision of 1e-8 is achieved. If not the model will crash. Additionally consistency between flux-based and pool-based NBP is checked. This check represent an integrated check which give confidence for the technical implementation of the C and N cycles. Comparing the flux and pool based nbp estimates is an instantaneous check that covers just a single day in the model (thus 48 time steps for the soil and litter calcuations which are called from stomate.f90). The cross-consistency check for the flux and pool based NBP requires mass balance closure and area preservation from all all subroutines being called from stomate.f90 including stomate_lpj.f90. This check should always be satisfied, if not there is a bug somewhere! The mass balance of individual subroutines teaches us about the calculations performed within that subroutine. The flux and pool based NBP consistency check teaches us of how these fluxes and pools should be accounted for, passing this check requires additional understanding of the flow of the code (i.e., bm_to_litter) and how the different time steps come together. |
| 181 | | |
| 182 | | As an additional consistency check the time integral of the NBP (from 0 -> t) should equal the C and N stock at time step t. Comparing the time integral of NEP vs the all pools includes all the accumulated precision errors. If those errors would be random there would be no problem but they are more likely biases. Hence, when the fluxes and pools increase several order of magnitudes (e.g toward 1e4) and a small bias (1e-12) is integrated over 10,000 days (1e4) the divergence between the time integral of NEP and the pools will approach/exceed 1-8 and woukd stop the model. This is a fundamental problem related to machine precision and the way we do the calculations (think of the so called catastrophic rounding errors that may occur with floating numbers). For this reason this check is written to the history files but does not make the model crash. The user will have to decide whether (s)he is facing a precision error or a real bug. Fixing precision errors will require to improve the precision of the calculations in one or several subroutines. |
| 183 | | |
| 184 | | The variable MBC_NBP3_c was added to enable monitoring whether the NBP send to LMDZ in intersurf.f90 is identical to the NBP calculated in stomate_lpj.f90. If ERR_ACT=3 is used, the model will crash if the NBP send in intersurf differs from the NBP calculated in stomate_lpj.f90. Irrespective of the value of ERR_ACT, the mismatch between both NBPs will be send to MBC_NBP3_c. |
| 185 | | |
| 186 | | |
| 187 | | === Croplands === |
| 188 | | Describes r7767. Makes use of sapiens_planting and sapiens_harvest. Planting and harvest is determined by temperature and soil moisture using the moigdd phenology type. At senescence, 50% of the aboveground biomass is placed into the harvest_pool (just like wood) and its decomposition is accounted for in the fluxes from the product use pool. The remaining 50% of aboveground biomass enters the litter pool, along with all of the roots. |
| 189 | | |
| 190 | | |
| 191 | | === CWRR vs Choinel === |
| 192 | | Describes r6614. Following ORCHIDEE trunk 3, the Choinel code is no longer available in ORCHIDEE trunk. The hydrological schemes were not touched during the development of ORCHIDEE trunk. The hydraulic architecture in ORCHIDEE trunk relies on CWRR. |
| 193 | | |
| 194 | | |
| 195 | | === Diameter classes === |
| 196 | | Describes r6614. Diameter classes were introduced to better simulate the canopy structure, they are a tool to simulate heterogeneity within a single PFT. Given that the canopy is the interface between the land and the atmosphere this feature has effects well beyond forest management. Stand structure was observed to affect albedo, transpiration, photosynthesis, soil temperature, roughness length, and recruitment. Using diameter classes adds very little complexity to setting-up the simulations as well as to the output files. The complexity is mostly within the code. |
| 197 | | |
| 198 | | The computational cost of using diameter classes is negligible and when a reasonable low number of diameter classes is used, the memory cost remains very small as the dimensions of only two variables are increased. The number of diameter classes is the same for all PFTs and is set by the parameter '''NCIRC'''. ORCHIDEE-CN, and ORCHIDEE-CNP are coded and used for NCIRC = 1. ORCHIDEE trunk was coded and tested for NCIRC = 3. Until further testing, three diameter classes are considered sufficient although for some specific application, i.e., simulating tree ring width NCIRC = 5 resulted in slightly better model performance. The branch ORCHIDEE-CN-CAN that preceded this trunk version has been run with one diameter class as well (this should be confirmed for ORCHIDEE trunk). |
| 199 | | |
| 200 | | Given earlier choices in the ORCHIDEE model, we either need to define the boundaries of each diameter class or the diameter distribution. While developing the code, we considered the second approach the most flexible. To allow maximal flexibility, each diameter class needs to be defined separately by the variable '''CIRC_CLASS_DIST_0000X''', where X is the number of the diameter class. The smallest number presents the smallest diameter class. From literature it is known that a truncated exponential distribution is a good first guess: |
| 201 | | {{{ |
| 202 | | CIRC_CLASS_DIST_00001=9 |
| 203 | | CIRC_CLASS_DIST_00002=5 |
| 204 | | CIRC_CLASS_DIST_00003=1 |
| 205 | | }}} |
| 206 | | The above declaration implies that 9/15th of the trees will always be in the smallest diameter class, 5/15th will be in the medium class and 1 tree out of 15 will be in the largest diameter class. These ratios are kept throughout the simulations and the boundaries of the diameter classes are adjusted to respect this constraint. Consequently, an even-aged stand will be simulated with three diameter classes where the diameter of the first class may be, for example, 20.3 cm, the diameter of the second class 20.4 cm and the diameter of the third class 20.5 cm. The same code and set-up allows to simulate, in the same simulation, an uneven-aged stand for the same PFT but in a different pixel with, for example, the smallest diameter 7 cm, the medium diameter 25 cm and the largest diameter 45 cm. |
