SIP325 document proposed C and N limited leaf-on events

[dlebauer]

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 leafGrowth parameter, available C and available N.

  • Available C is limited to a percent of woody + coarse root biomass
  • Available N is augmented by a storage pool, and the storage pool is fed by translocation of some N from leaves to storage at leaf off.

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

• These 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

• All of the issues related to clamping, death,
• especially Insufficient carbon for growth should cause mortality, and fix C balance #325, ensureNonNegativeStocks clamps plantWoodC but not plantWoodCStorageDelta , sum can go negative and break downstream fluxes #324

Checklist

• Related issues are listed above. PRs without an approved, related issue may not get reviewed.
• PR title has the issue number in it ("[#] <concise description of proposed change>")
• Tests added/updated for new features (if applicable)
• Documentation updated (if applicable)
• docs/CHANGELOG.md updated with noteworthy changes
• Code formatted with clang-format (run git clang-format if needed)

[Copilot]

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.md with 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.md related 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.

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 8 comments.

[Alomir]

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.

[dlebauer]

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]?

[Alomir]

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.

[Alomir]

That's not to say I don't favor renaming it (apologies for the double negative, it's a real failing of mine 😂)

[dlebauer]

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!

[dlebauer]

updating docs per https://github.com/PecanProject/sipnet/pull/332/changes/BASE..fe5cf2354322021e46b341d50c6d2576082d29fe#diff-48280cdb24047c693a4e16f288979b44b0ef078ce4dfeb3bba5e1293f7f4ce74L1184

[dlebauer]

Suggested change

	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}}$:

[Alomir]

Isn't F*C_{demand,leaf,on} the same as the Delta_C param? I can't find where we define that F term.

[dlebauer]

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.

[Alomir]

One side of this should be the negative of the other; perhaps:

Suggested change

	\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}

[dlebauer]

I'll defer to you, but to clarify the rationale behind stating:

$$ \text{inputs}=\text{outputs} $$

Is that by convention in this document, fluxes are > 0, and +/- signs are used in state updates:

$$ \frac{dX}{dt}=\text{inputs}-\text{outputs} $$

At one point I considered of indicating direction like:

$$F^C_{\text{source}\rightarrow\text{sink}}$$

But I was already spending too much time on notation and I don't know if it would clarify this case 🤯.

[Alomir]

I'm fine either way, really. Your current form does seem to be in keeping with the rest of the doc.

[Alomir]

Suggested change

	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.

[Alomir]

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.

[Alomir]

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.

[Alomir]

Actually, that last line in this section:
"Total plant N demand $F^N_{\text{demand,}total}$ is then partitioned between fixation and soil N uptake"

could perhaps be:
"Total plant N demand $F^N_{\text{demand,}total}$ is reduced by the N storage pool, and then any remaining demand is partitioned between fixation and soil N uptake"
or some such.

[dlebauer]

Based on conversation with @Alomir today, considering the actual implementation of this feature and the potential circularity, we came up with the following scheme. Docs will need to be updated accordingly.

• Leaf-off transfers fraction of leaf N to plant N storage at leafOff.
• Plant N storage is only used for leafOn and growth; growth does not occur between leafOff and leafOn
• Leaf-on N is only limited by plant N storage, not mineral uptake or fixation.
• Leaf-on draws from plant N storage¹.
• Any storage N remaining after leaf-on is available for subsequent plant growth.
• Growth uses storage N before soil mineral N uptake².
• N fixation remains a fixed fraction of total plant N demand, even so, we expect this fraction = 0 (or very small to represent free-living n fixers) for tree crops.

Explicit decisions:

Option	Tradeoff	Decision
Leaf-on N uses all N sources	More complete, but creates circular dependency with uptake	No
Leaf-on N uses storage only	Simple and avoids circularity	Yes
Storage only for leaf-on	Simple, but can accumulate	No
Storage for leaf-on + later growth	Prevents accumulation	Yes
Use storage before soil N	Simple, defensible	Yes
Split storage/soil 50-50 or by size	Viable, but not clearly more defensible	Maybe later
Add storage flag	More control, more complexity	No
Track full plant N pools	Cleaner long-term, much bigger refactor	Maybe later

Footnotes

1. N storage pool is expected to meet leafOn N demand b/c realized leafOn should be << leaf N at preceding leafOff, and initial leaf N can be set to satisfy initial demand. ↩

2. drawing down storage first is the simplest scheme; we considered other ways of partitioning the N sources to meet N demand for plant growth. ↩