SIP325 document proposed C and N limited leaf-on events#332
SIP325 document proposed C and N limited leaf-on events#332
Conversation
There was a problem hiding this comment.
Pull request overview
This PR updates SIPNET documentation to describe a proposed model structure for leaf-on/leaf-off that limits leaf-on growth by available carbon and nitrogen (including an explicit plant N storage concept), and records some alternate mortality ideas related to storage exhaustion.
Changes:
- Extend
docs/model-structure.mdwith a proposed leaf-on/leaf-off formulation (C reallocation limits, N resorption/storage, and updated N-demand discussion). - Add new (proposed) parameters and state/pool symbols to
docs/parameters.mdrelated to plant N storage, leaf-on C reallocation, and leaf N resorption. - Add an alternate mortality-from-storage-exhaustion concept to
docs/.alternate-model-structure-ideas.md.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 6 comments.
| File | Description |
|---|---|
| docs/parameters.md | Documents new proposed N storage / leaf-on reallocation / leaf N resorption parameters and symbols. |
| docs/model-structure.md | Replaces the previous leaf-on/off description with a more detailed proposed, limiter-based formulation and related N-demand equations. |
| docs/.alternate-model-structure-ideas.md | Adds an alternate mortality concept tied to persistent storage depletion (documentation only). |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Co-authored-by: David LeBauer <dlebauer@gmail.com>
Mostly revisions for clarity and consistency Co-authored-by: David LeBauer <dlebauer@gmail.com> Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
| Symbols in blackboard bold, e.g. $\mathbb{X}$, indicate proposed model quantities that are documented here but | ||
| not yet implemented. |
There was a problem hiding this comment.
I'm not sure this is worth it at this point? Leave it in if you feel strongly, of course.
There was a problem hiding this comment.
I do appreciate the opportunity to use some of the cool fonts, but what I feel strongly about is making sure that the docs reflect the actual implementation.
I would be okay with the alternative of adding implementation to this PR or otherwise leaving this PR open until the feature is implemented.
There was a problem hiding this comment.
Would it work to write like [\mathrm{planned}] F^C_{\text{mort},j,t} = ...? Then nobody has to remember any extra notations
There was a problem hiding this comment.
@infotroph unless there is objection, lets go with 'wait to merge docs until implemented'
| \end{equation} | ||
|
|
||
| where $0 \le \mathbb{f}^C_{\text{realloc}} \le 1$. Leaf-on reallocation uses structural perennial biomass only. It does not draw | ||
| from $C_{\text{wood,storage}}$, because the storage pool is a bookkeeping buffer for recent carbon allocation lag rather than a carbon pool available for reallocation. |
There was a problem hiding this comment.
Yeah, I like this.
Note that this is making me feel more strongly about resolving whether the storage pool should be included for calcs of wood resp, wood turnover, and harvest.
There was a problem hiding this comment.
Actually, how about renaming the "storage" pool to something to indicate that it is an accounting tool rather than a biological representation, like [NPP|Wood]Allocation[Lag|Buffer]?
There was a problem hiding this comment.
Thinking about this more, I'm actually not sure I totally agree. The storage pool is a buffer used to track carbon entering and leaving the system without any associated nitrogen. We need it to balance nitrogen, since we have fixed C:N ratios.
Thinking of it as just a allocation lag tracker doesn't feel right when that pool is negative.
When it's positive, I think I agree with your wording - it's basically a lag buffer. When it's negative, though, some carbon pool somewhere is taking a hit, we just don't reduce any pools because we are also using those pool sizes to track nitrogen, which hasn't changed.
There was a problem hiding this comment.
That's not to say I don't favor renaming it (apologies for the double negative, it's a real failing of mine 😂)
There was a problem hiding this comment.
Yeah, the key point was
renaming the "storage" pool to something to indicate that it is an accounting tool rather than a biological representation
I'll leave naming to those more qualified!
| Leaf-on events define the timing of leaf emergence. Leaf-on requests a transfer of carbon to the leaf pool, and the | ||
| amount transferred is limited by available carbon and nitrogen: |
There was a problem hiding this comment.
| Leaf-on events define the timing of leaf emergence. Leaf-on requests a transfer of carbon to the leaf pool, and the | |
| amount transferred is limited by available carbon and nitrogen: | |
| Leaf-on events define the timing of leaf emergence. | |
| Leaf-on requests a transfer of carbon to the leaf pool, and the | |
| amount transferred is limited by available carbon and nitrogen. | |
| The requested leaf-on carbon demand $F^C_{\text{demand,leaf,on}}$ is bounded by the seasonal leaf-growth amount parameter, $\Delta C_{\text{leaf}}$: |
There was a problem hiding this comment.
Isn't F*C_{demand,leaf,on} the same as the Delta_C param? I can't find where we define that F term.
There was a problem hiding this comment.
Yeah this is pretty confusing and should be re-written.
Goal is:
- F^C_leaf is realized flux of carbon to leaf.
- Delta_C_leaf (misleading because it is not realized) is the parameter that defines how much leaf biomass is added if not limited by C or N availability.
| \begin{equation} | ||
| \sum_j F^C_{\text{source,}j} = F^C_{\text{leaf,on}} | ||
| \label{eq:leaf_on_source_c_sum} | ||
| \end{equation} |
There was a problem hiding this comment.
One side of this should be the negative of the other; perhaps:
| \begin{equation} | |
| \sum_j F^C_{\text{source,}j} = F^C_{\text{leaf,on}} | |
| \label{eq:leaf_on_source_c_sum} | |
| \end{equation} | |
| \begin{equation} | |
| \sum_j F^C_{\text{source,}j} + F^C_{\text{leaf,on}} = 0 | |
| \label{eq:leaf_on_source_c_sum} | |
| \end{equation} |
There was a problem hiding this comment.
I'll defer to you, but to clarify the rationale behind stating:
Is that by convention in this document, fluxes are > 0, and +/- signs are used in state updates:
At one point I considered of indicating direction like:
But I was already spending too much time on notation and I don't know if it would clarify this case 🤯.
| \label{eq:plant_n_storage} | ||
| \end{equation} | ||
|
|
||
| Stored nitrogen contributes to satisfying plant growth nitrogen demand, including leaf-on demand. |
There was a problem hiding this comment.
| Stored nitrogen contributes to satisfying plant growth nitrogen demand, including leaf-on demand. | |
| Stored nitrogen contributes to satisfying plant growth nitrogen demand, including leaf-on demand (indicated as $F^N_{\text{storage,use}}$). |
Or some other way to explicitly mention that F term.
There was a problem hiding this comment.
Also, should we explicitly say "can be used for any plant N demand, not just leaf on", or is that obvious? (Maybe just an "all" before "plant growth nitrogen demand"?)
Feel free to not do anything here, I think this is just me.
| Plant N demand is the amount of N required to support plant growth. This is calculated as the sum of carbon creation fluxes divided by their respective C:N ratios: | ||
| Plant N demand is the amount of N required to support plant growth. This is calculated as the sum of carbon creation fluxes divided by their respective C:N ratios. | ||
|
|
||
| For leaf-on reallocation, source-pool nitrogen contributes according to the source-pool C:N ratio. Net leaf-on N demand |
There was a problem hiding this comment.
This is true for all N demand, correct? (That is, source-pool N contributes...) We don't actually refer to the N storage in the equations below, so I don't think we need this. Or, perhaps, a more general statement (at the end?) stating that this demand can be met with the source-pool N.
There was a problem hiding this comment.
Actually, that last line in this section:
"Total plant N demand
could perhaps be:
"Total plant N demand
or some such.
Co-authored-by: David LeBauer <dlebauer@gmail.com>
Co-authored-by: Mike Longfritz <Mike.Longfritz@gmail.com>
Note: marked as SIP325, though this isn't the complete solution.
Summary
What: Documentation of proposed scheme for having sufficient N and C for leaf-on without going into carbon debt.
Leaf growth is realized as minimum of
leafGrowthparameter, available C and available N.defer mortality (Insufficient carbon for growth should cause mortality, and fix C balance #325), hope is that this will solve the immediate problem of leaf on not having enough resources; but some ideas written to
docs/.alternate-model-structure-ideas.mdThese docs do not cover implementation, or resolution of phantomC introduced by clipping (ensureNonNegativeStocks clamps plantWoodC but not plantWoodCStorageDelta , sum can go negative and break downstream fluxes #324), it focuses on documentation of proposed model structure.
PR tries to be unopinionated about implementation.
Motivation: Why is this change needed?
At present, leaf-on induced carbon demand creates unrealistically high demand for C and N, and wood accounting allowed negative biomass, negative fluxes, and abuse of storage accounting. This doesn't solve the negative pools and fluxes and other complications encountered, but it should go a long way toward avoiding them.
How was this change tested?
make document 💻<--👀Reproduction steps
NA
Related issues
Checklist
docs/CHANGELOG.mdupdated with noteworthy changesclang-format(rungit clang-formatif needed)