Documentation errors in the phenology section of the CLM technical note

[jyoti1singh]

2.26.2.3.4. section (Harvest) of CLM technical note says that GDDmin is the lowest (for planting) 20-year running mean growing degree-days based on the base temperature threshold in the 7th row, tracked from April to September (NH). GDDmat is a crop’s 20-year running mean growing degree-days needed for vegetative and physiological maturity. These values are given in Table 2.26.2 that lists crop phenology and morphology parameters for the active crop plant functional types in CLM5BGCCROP.

However, GDDmin and GDDmat are variables defined in parameter file as gddmin and hybgdd respectively. These values vary with crop plant functional type. If this is the case, the description of these variables needs to be changed in CLM technical note.

[olyson]

@danicalombardozzi if you can confirm what changes are needed here for the technical note, I can make the changes as I am currently making changes to the technical note to resolve some other issues.

[wwieder]

Are these values also changing with @samsrabin 's PR? If so, how?

[samsrabin]

I'm not changing these variables' names or definitions in my work, so no worries there.

Jyoti, let me know if my read is correct here:

• I don't see anything technically wrong with the text about $GDD_{min}$, although it could be ambiguous. I might suggest editing the sentence about it to "$GDD_{min}$ is the lowest allowed (for planting) 20-year…"
• Also, the next sentence should be edited: "$GDD_{mat}$ is a crop's 20-year running mean growing degree-days needed for …"

Everything else seems correct. Is that right?

Other suggestions

• In the table, I would also suggest changing "Harvest: days past planting" to "Maximum growing season length ($mxmat$)" and deleting the ≤ symbols. Then in the paragraph after the table, "the number in the 11th row" can be replaced with $mxmat$.
• The values in the "% $GDD_{mat}$" rows should be 3%, 5%, etc. instead of 0.03, 0.05, etc.
• "fcur is the fraction of allocation that goes to currently displayed growth" is unclear.

I think the paragraph after the table could be more completely reworked for organization and clarity. It would also be best to avoid duplicating information that's already given elsewhere. A suggestion:

Notes:

• $Date_{planting}^{min}$ and $Date_{planting}^{max}$ are the minimum and maximum planting dates in the Northern Hemisphere; the corresponding dates in the Southern Hemisphere are shifted by 6 months. (See Sect. 2.26.2.3.1.)
• $T_{p}$ and $T_{p}^{ min }$ are crop-specific average and coldest planting temperatures, respectively. (See Sect. 2.26.2.3.1.)
• $GDD_{min}$ is a threshold describing the coolest historical climate a patch can have had in order for a crop to be sown there; see Sect. 2.26.2.3.1 for details.
• $GDD_{mat}$ is the heat unit index, in units of accumulated growing degree-days, a crop needs to reach maturity. Heat unit index can be "boosted" to the Phase 3 (grain fill) threshold value if it is below that threshold but maximum leaf area index has been reached; see Sect. 2.26.2.3.3.
• $mxmat$ is the maximum growing season length (days past planting), at which harvest occurs even if heat unit index has not reached $GDD_{mat}$.
• Crop growth phases are described in Sects. 2.26.2.1–4.
• $z_{top}^{\max }$ is the maximum top-of-canopy height of a crop (see Sect. 2.2.1.3).
• SLA is specific leaf area (see Sect. 2.10).
• $\chi _{L}$ is the leaf orientation index: equals -1 for vertical, 0 for random, and 1 for horizontal leaf orientation. [This appears to not be explained anywhere in the docs.]
• grperc is the growth respiration factor (see Sect. 2.17.1.2).
• flnr is the fraction of leaf N in the Rubisco enzyme. [See Sect 2.10? Is this the same as $N_{cb}$ in Table 2.10.1?]
• fcur is the fraction of allocation that goes to currently displayed growth. [Rework; add section reference.]

Finally, a note that should probably just be a different issue: It's a bit confusing and inaccurate to refer so much to GDDs when talking about thresholds for crop phase transitions, because it's not purely GDD accumulation that is considered—it's heat unit index. These two variables are the same unless a crop reaches maximum LAI before reaching the degree-day value for grain fill threshold (phase 3), in which case HUI is "boosted" to the value derived from multiplying $GDD_{mat}$ by the "Phase 3 % $GDD_{mat}$" value given in the table (as described in Sect. 2.26.2.3.3, although that section should mention that HUI is actually increased). This distinction actually tripped me up for a few hours at one point. It would be more accurate if $GDD_{mat}$ were renamed $HUI_{mat}$, but that'd be a much bigger undertaking.

[jyoti1singh]

I agree with your following points @samsrabin :
• In the table, I would also suggest changing "Harvest: days past planting" to "Maximum growing season length (mxmat)" and deleting the ≤ symbols. Then in the paragraph after the table, "the number in the 11th row" can be replaced with mxmat.
• The values in the "% GDD_mat" rows should be 3%, 5%, etc. instead of 0.03, 0.05, etc.
• "fcur is the fraction of allocation that goes to currently displayed growth" is unclear.

I think GDD_min has confusing definitions in the technical note. Section 2.26.2.3.1. (Planting) says GDD_min is the minimum growing degree day requirement (Table 2.26.2) and section 2.26.2.3.4. (Harvest) says GDD_min is the lowest (for planting) 20-year running mean growing degree-days based on the base temperature threshold in the 7th row, tracked from April to September (NH). In the harvest section, the description of GDD_min is confused with the minimum GDD required for the crop to be planted. For example for winter wheat (Tbase = ⁰C)
(gdd020(p) /= spval .and. &
gdd020(p) >= gddmin(ivt(p)))) then

Secondly, In my view, saying GDD_mat is a crop's 20-year running mean growing degree-days needed for vegetative and physiological maturity is incorrect because the value of GDD_mat is user-defined in the parameter file (as variable hybgdd) as can be seen below in CNPhenology.F90.

gddmaturity(p) = hybgdd(ivt(p))

I don't understand your comment regarding GDD and HUI completely. As far as I know, the following are the variables related to HUI in the CNPhenology module.
hui: gdd since planting (gddplant)
huileaf: heat unit index needed from planting to leaf emergence
huigrain: heat unit index required to reach vegetative maturity
gddmaturity: gdd needed to harvest (GDD_mat )

Here, Heat units are reported in growing degree-days (GDD) units and the heat unit index of each phenological phase is a given fraction of the gddmaturity. As far as I understand, hui and gddmaturity are two different variables, and hui may become equal to gddmaturity at the time of harvest if mxmat is not the only criteria that is being satisfied in the case of crop harvest.

[samsrabin]

@jyoti1singh:

I still think the two mentions of $GDD_{min}$ are correct, although potentially confusing. But maybe I'm missing something. To help clarify, what do you think of what I wrote in my major rewrite:

$GDD_{min}$ is a threshold describing the coolest historical climate a patch can have had in order for a crop to be sown there; see Sect. 2.26.2.3.1 for details.

Is that correct? If so, how does what's written in 2.26.2.3.1 conflict with that?

Re: $GDD_{mat}$: Yes, that's what I meant by striking "20-year running mean growing degree-days" in my suggested edit (second bullet point in my post). But see also what I have in my major rewrite, which I think is clearer:

$GDD_{mat}$ is the heat unit index, in units of accumulated growing degree-days, a crop needs to reach maturity. Heat unit index can be "boosted" to the Phase 3 (grain fill) threshold value if it is below that threshold but maximum leaf area index has been reached; see Sect. 2.26.2.3.3.

Does that look right?

[jyoti1singh]

Maybe the ideal definition GDD_min is what you mention, especially if it is the recommendation for deciding the value of GDD_min in the parameter file. My only confusion is when users set the value of GDD_min in the parameter file, do they follow the criteria of checking that it is the lowest (for planting) 20-year running mean growing degree-days based on the base temperature (of the particular )?

Again I have the same doubt regarding GDD_mat , as It also depends upon the cultivar so that the user can change its values in the parameter file depending on the availability of experimental data. I think GDD_mat should be simply defined as "the heat unit index, in units of accumulated growing degree-days, a crop needs to reach maturity" from your description, rest of the text might be a bit confusing.

[samsrabin]

Re: $GDD_{min}$: Sure, the users can try to parameterize it based on the real-life distribution of the crop/cultivar. But it's also kind of a weird parameter, if you think about it. We're using input maps of the distribution of crops/cultivars; if we know it's planted in real life (or we want it to be planted based on a LU scenario), why do we let the model override that? This feels very much like a DGVM thing (bioclimatic envelopes of biomes) that doesn't make as much sense in a LU context. For that reason, I think it doesn't matter too much exactly how the user goes about parameterizing $GDD_{min}$. Indeed, now I kinda think $GDD_{min}$ should be removed from the model entirely! @danicalombardozzi am I off my rocker?

Re: $GDD_{mat}$, I think your suggestion to just keep the first sentence of my definition is smart. It should minimize confusion for users just looking for a definition rather than a process explanation, and it also avoids repeating information that's given elsewhere in the docs.

[samsrabin]

@danicalombardozzi sorry, meant to tag you above, and adding you in an edit isn't working. Sorry if this spawned multiple notifications.

[jyoti1singh]

As I understand GDD_min was required to decide if planting criteria are satisfied for a crop to be planted as planting is not prescribed in CLM5. With the introduction of the prescribed planting date, GDD_min will become irrelevant unless it is used in some other module of crop growth.

[samsrabin]

Right, but $GDD_{min}$ is only one of the planting criteria; the rest have to do with current conditions, which I think it makes sense to keep. They are also kept in my prescribed calendars implementation, for use when not using prescribed calendars.

[jyoti1singh]

Got your point!