Set the level of internal error checking

Author: S. Luyssaert
Last major revision: S. Luyssaert (2020/03/19)
Last check: D. Goll(2020/04/20)

Objective

Background of this item: ORCHIDEE has build in error and consistency checking (i.e. mass conservation checks). Setting the correct level of these checks can help you to more quickly find the reason of a crash or a suspicious result. These setting should work for both the land-only and the land-atmosphere configurations. Currently, carbon and water mass checks are available which are described in the following.

Carbon and nitrogen mass conservation

The code distinguishes between three options to check for mass conservation. These options are controlled by the parameter err_act. Always use err_act = 3 when developing and testing the code. 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.

• 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.
• 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.
• err_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.

Surface conservation

Note that in addition to checking for mass balance closure ORCHIDEE trunk 4 (r6614 and higher) 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. Mass and surface conservation cannot be separated from each other and were therefore merged into a single parameter (see above).

NaN checking

err_act also checks the presence of NaN. This is especially useful when running the model in PROD mode because such a compilation will not crash on a divide by zero but will write NaN values instead. Note that the default setting of xios (prec=4 in the field definition file in src_xml) cannot write NaN to the history files. Mass conservation, surface conservation and NaNs cannot be separated from each other and were therefore merged into a single parameter (see above).

Water conservation

hydrol.f90

Since ​r2720, water budget closure is checked in hydrol.f90 for the related water stores (soil, snowpack and canopy) owing to the diagnostic variable TWBR (total water budget residu). This variable can be seen in the MONITORING tool when running with libIGCM.

It is calculated at each time step as the difference between the total water storage change and the net fluxes, and should be close to zero if water is conserved. Acceptable values are in the order of 10-13 kg/m2/s (~ less than 10^{-8 kg/m2/d).}

Another useful check variable is undermcr, which is defined per soiltile, and holds the number of orchidee time steps per output time step in which at least one soil layer has a moisture content mc below the residual value mcr. These situations are pathological, since they are close to negative moisture contents, which make no physical sense and cannot be tracted correctly by the code.

Additionnal variables can be output to check water conservation in hydrol at several stages of hydrol_soil, which can be useful if you develop hydrol.f90. To export them, activate check_cwrr (default is no). The following variables will then be exported: check_infilt, check_tr, check_over, and check_under. See the ​hydrol.f90 code for further explanations.

routing.f90

Note that TWBR does not tell anything about water conservation in the routing scheme. Instead, specific water budget residues are calculated for the 4 main reservoirs of the routing scheme: wbr_stream, wbr_fast, wbr_slow, and wbr_lake. The standard output unit is also in kg/m2/s, and these values must also be as close to zero as possible.

In the trunk (2.0), the output level for these variables is 8, so they are not exported by default (SECHIBA_HISTLEVEL = 5), and you need change the the output level to get them. Explanations are ​here.

Energy conservation

No check is done for the energy conservation in ORCHIDEE.