Dear TEMIR developers and users
After consultation with many of you, I’ve taken the liberty to make substantial changes to TEMIR to fix a few issues and also (initiated by David) to implement a couple of potentially useful capabilities. Please see them below, download the latest code here into your main TEMIR directory:
Please test them and report any issues. I strongly encourage you to start any new development or incorporate your recent development into this version. Please also read my notes below carefully. I marked most of my changes with “(Tai, Feb 2019)” in the code.
#0: Reorganization of TEMIR structure
Affected modules: execution_*.R, input_TEMIR_*.R, initialize_TEMIR_*.R
Thanks to David, the execution structure of TEMIR has been dramatically reorganized. Now all necessary inputs and options are specified in input_TEMIR_*.R. A new script, initialize_TEMIR_*.R within “/code_v1.1” can be used to check out TEMIR and create a simulation directory that contains the execution_*.R and input_TEMIR_*.R scripts, as well as the “hist_data” and “temp_data” directories. Please read the instruction guide, TEMIR_manual_v1.1.docx, in “/code_v1.1” to familiarize yourself with the new steps to run TEMIR. The new structure would require a new directory, “/TEMIR_inputs” in parallel to “/code_v1.1”:
Alternatively (and anyhow), you may clearly specify the required directories in execution_*.R within “/code_v1.1”, which will be copied to the execution_*.R in the simulation directory automatically when you run initialize_TEMIR_*.R.
#1: Fixing a canopy scaling issue to avoid scaling by stem areas
Affected modules: Farquhar_Ball_Berry.R, radiative_transfer.R, simulate_ij.R
This is likely the most dramatic fix that may affect everyone’s previous results, and may substantially alleviate the longstanding overestimation problem for GPP and conductance. When I first developed the model, I followed CLM4.5 closely. In CLM, “L_sun” and “L_sha” are sunlit and shaded plant area index, that includes both leaf area index (LAI) and stem area index (SAI), such that:
L_sun + L_sha = LAI + SAI
Therefore, in TEMIR thus far, GPP and canopy conductance are indeed scaled up from the leaf level using both LAI and SAI! But for most woody plants, stems carry out very little photosynthesis and have very few stomata, so that shouldn’t be so. Now I’ve redefined two variables, “LAI_sun” and “LAI_sha”, which really account for leaf areas only when used to scale up photosynthesis and conductance. This is indeed more consistent with many other LSMs (e.g., JULES). SAI is still used to account for light attenuation.
Along with these changes, now “LAI_sun” has to be explicitly provided in f_canopy_photosyn() instead of being calculated within this function, and is now calculated within f_simulate_ij() using one of the two canopy radiative transfer schemes (see #2 below). If for some reason you need to revert to the older way of scaling by LAI + SAI, you only need to modify the definition of “LAI_sun” and “LAI_sha” within f_simulate_ij() when they’re calculated.
Related to these changes, a new capability is also added to calculate leaf-level stomatal conductance weighted by sunlit and shaded leaf areas, named “g_s”, to be outputted by f_canopy_photosyn(). “g_s” is then used within f_simulate_ij() to calculate canopy-integrated stomatal resistance, “R_s”, to be used by f_drydep_Wesely() or f_drydep_Zhang().
#2: Two canopy radiative transfer schemes
Affected modules: simulate_ij.R, input_TEMIR_*.R
Default TEMIR uses CLM’s two-stream approximation for canopy radiative transfer. Zhang et al. (2003)’s scheme uses a simpler radiative transfer scheme that always assumes spherical leaf orientation and considers attenuation by LAI only. GEOS-Chem’s implementation of Wesely (1989) has its own peculiar way of accounting for light. Since dry deposition has been incorporated, all of these schemes are available in TEMIR. With the overarching philosophy that for each simulation the same scheme should be consistently used by all modules that require it, I’ve now implemented a manual switch in input_TEMIR_*.R, “simple_radiation_flag” in the ecosystem menu, so that when it is turned on, the simplified scheme from Zhang et al. (2003) would be used to calculate “phi_sun”, “phi_sha”, “LAI_sun”, “LAI_sha”, “K_b” within f_simulate_ij() to replace the default values calculated by f_PAR_absorb(), which will then be consistently used by all modules (photosynthesis, different stomatal conductance calculations for dry deposition, etc.).
#3: Two aerodynamic conductance schemes
Affected modules: Monin_Obukhov.R, Farquhar_Ball_Berry.R, simulate_ij.R, execution_*.R, input_TEMIR_*.R
Aerodynamic conductance (“g_ah”) is needed for calculation of ozone damage and dry deposition. GEOS-Chem Wesely and Zhang et al. (2003) dry deposition schemes come with a standard way of calculating “g_ah” that differs from default TEMIR’s “g_ah” calculated in f_Monin_Obukhov(). Now both schemes are available, and I’ve implemented a manual switch in input_TEMIR_*.R, “use_TEMIR_ga_flag” in the dry deposition menu, to choose between the two schemes; once chosen, the same scheme will be used consistently across all modules that require it. If “Monin_Obukhov_flag=TRUE”, then “use_TEMIR_ga_flag” will be automatically turned on. I’ve also modified f_Monin_Obukhov() such that now the Obukhov length there, “L_Obuk”, is calculated in exactly the same manner as that in drydep_toolbox.R, instead of a rather ad hoc way that I used before. The only difference between the two schemes now is the formulation of “g_ah” as a function of “L_Obuk”, etc.
Along with these changes, I’ve also modified f_canopy_photosyn() and its nested functions such that “g_ah” has to be explicitly provided instead of being calculated within f_Farquhar_Ball_Berry(), to be used directly in f_ozone_impact() (see #4 below). “g_ah” is now always calculated within f_simulate_ij() using one of the two schemes.
#4: Using aerodynamic conductance for scalars for ozone damage
Affected modules: Farquhar_Ball_Berry.R
Following Lombardozzi’s implementation in CLM, the stomatal ozone flux has always been calculated using the aerodynamic conductance for momentum (“g_am”). However, this is not right; the conductance for scalars (e.g., heat, water) should be used instead. I’ve now modified f_ozone_impact(), and the functions that call upon it, such that “g_ah” is used to calculate ozone flux, and has to be explicitly provided to f_canopy_photosyn() and calculated within f_simulate_ij().
#5: Capability to use interannually varying LAI and ozone data as inputs
Affected modules: PFT_surf_data.R, input_TEMIR_*.R, execution_*.R
We’ve now implemented an exciting capacity to use user-defined, interannually varying LAI and O3 data as inputs to drive TEMIR. This is much better than using only a single, preset year of data (CLM 2000 LAI and GEOS-Chem 2010 O3) that was the case before. All you need to do is to specify, within the LAI data menu and O3 damage menu in input_TEMIR_*.R, the directory paths to the input nc files and the file naming convention. Each input nc file can have any spatial resolution, but has to be for one year only, with a temporal resolution of monthly for LAI and hourly for O3. The monthly LAI data by year that default GEOS-Chem v12.1.1 uses can be downloaded here:
Interannually varying ozone concentrations are now being generated by David.
#6: Small dry deposition fixes
Affected modules: simulate_ij.R, drydep_toolbox.R
I’ve standardized some of the meteorological variables that need to be inputted into f_drydep_Zhang() and f_drydep_Wesely():
rho=rho_atm, T.s=T_2m, H=H_sen, z0=Z_0m, cz=(Z_atm + Z_0m), r_s=R_s, r_a=1/g_ah
I’ve also renamed a few functions and variables and removed some unused variables here and there. However, I haven’t completely checked drydep_toolbox.R yet in terms of the science, which I will do later. I just checked enough to make sure it can run, and mostly just modified the interfacing with dry deposition within f_simulate_ij().
Remaining issues and notes:
1. I have left drydep_toolbox.R mostly intact, and didn’t check its science much. If you’re confident with how it is written now, feel absolutely free to use it.
2. I haven’t checked the new Medlyn scheme yet. Use it with caution. Note that the stomatal conductance scheme to use for photosynthesis is specified in gs_scheme=‘FBB’ or gs_scheme=‘Medlyn’ in the ecosystem menu of input_TEMIR_*.R.
3. I haven’t checked any functionalities related to FLUXNET at all. Use them with caution, and in consultation with David.
4. The capability to calculate stomatal ozone flux with any stomatal conductance scheme and POD3IAM is now being developed by Mehliyar. Stay tuned.
5. TEMIR-Crop will be ready for every one to use after Jacky incorporates the updates above. I will check the interfacing between TEMIR v1.1 ecophysiology mode and crop mode with Jacky in the near future.
6. When you write new functions and variables in your development, please follow these rules:
i. Variable and function names should have at least three letters (this would make it much easier to search for them when debugging!).
ii. Functions should always start with f_*.
iii. Try to use names that clearly tell people what they refer to.
iv. Capitalize letters only if the whole word is an acronym (e.g., PAR), it is intended as a capitalized symbol (e.g., A_n), or when it refers to a proper name (e.g., f_Farquhar_Ball_Berry). Otherwise, use small letters as often as possible (e.g., f_canopy_photosyn instead of f_Canopy_Photosyn).
v. Try to minimize interactions between different modules; rely as much as possible on simulate_ij.R to do the interfacing between modules.
Please take your time to digest the messages above. I will address the above issues together with some of you in the coming weeks; but if you do not need to use dry deposition, Medlyn scheme or FLUXNET site simulation (or if you’re confident with how they are written as of now), the above version v1.1 is all ready to go!
This is the first post to the TEMIR web forum - please feel free to make active use of this forum, and report any problems. Request to add your other email addresses to the forum should you find them more convenient.
Happy coding!
Best,
Amos