SIP287 Add C Saturation by mswilburn · Pull Request #301 · PecanProject/sipnet

mswilburn · 2026-03-27T00:38:42Z

Summary

Implementing soil carbon saturation by creating a flag, adding a new parameter, modifying fluxes into soil organic carbon pool, adding new flux from soil organic carbon pool to litter pool, and updating documentation. Motivation for this change includes evaluating model soil carbon dynamics with and without an explicit maximum limit for long-term storage.

How was this change tested?

List steps taken to test this change, with appropriate outputs if applicable

If changes are needed for any sipnet.out files in the test/smoke subdirectories, then include output from
tools/smoke_check.py by running the commands below and pasting the output at the end of this PR. Note that
this must be run BEFORE submitting changes to any sipnet.out files.

make smoke
python tools/smoke_check.py run verbose <list tests/smoke subdirectories with changed outputs>

Run python tools/smoke_check.py help for more info.

Related issues

Fixes Implement Carbon Saturation in SIPNET #287

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)

Note: See CONTRIBUTING.md for additional guidance. This repository uses automated formatting checks; if the pre-commit hook blocks your commit, run git clang-format to format staged changes.

Alomir

New flag option looks good! (Other than the one issue in restart.c)

Merging from master

mswilburn · 2026-05-22T12:43:28Z

Smoke and Unit test output.

PR301 Smoke Test Output.txt
PR301 Unit Test Output.txt

Copilot

Pull request overview

Implements optional soil carbon saturation (issue #287) by adding a new carbonSaturation model flag, a soilCSaturation parameter, and a saturation-fraction-based rerouting of root-loss and litter-to-soil carbon back into the litter pool in updatePoolsForSoil(). The flag is wired through Context, CLI, restart serialization, and validation (it requires litterPool), and is exercised by a new unit test and existing smoke runs.

Changes:

Adds carbon-saturation CLI/model flag (Context, CLI map, restart schema, validation) and registers a new optional soilCSaturation parameter.
Modifies updatePoolsForSoil() to partition soil-bound carbon inputs by envi.soilC / params.soilCSaturation between soil and litter pools when the flag is on.
Adds testCarbonSaturation.c unit test plus smoke-test config/param updates.

Reviewed changes

Copilot reviewed 17 out of 17 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
src/sipnet/sipnet.c	New saturation branch in `updatePoolsForSoil()` and parameter registration.
src/sipnet/state.h	Adds `soilCSaturation` param field (and a stray blank line in `FluxVars`).
src/sipnet/cli.c, cli.h	Adds `--carbon-saturation` flag, arg map entry, usage text, bumps `NUM_FLAG_OPTIONS`.
src/common/context.h, context.c	Adds `carbonSaturation` Context field, initializer, and `validateContext()` dependency on `litterPool`.
src/sipnet/restart.c	Adds the flag to restart schema, serialization, and compatibility check.
tests/sipnet/test_modeling/testCarbonSaturation.c, Makefile	New unit test covering four input/saturation combinations.
tests/smoke/{niwot,russell_*}/sipnet.config, sipnet.param	Adds default-off `CARBON_SATURATION` line and `soilCSaturation 1.0` param entry.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Alomir · 2026-05-27T18:46:27Z

+      double saturationFraction = envi.soilC / params.soilCSaturation;
+      double soilInputs =
+          fluxes.coarseRootLoss + fluxes.fineRootLoss + fluxes.litterToSoil;
+
+      envi.litterC += (fluxes.woodLitter + fluxes.leafLitter +
+                       (soilInputs * saturationFraction) - fluxes.litterToSoil -
+                       fluxes.rLitter - fluxes.litterMethane) *
+                      climate->length;
+
+      envi.soilC += (soilInputs * (1 - saturationFraction) - fluxes.rSoil -
+                     fluxes.soilMethane) *
+                    climate->length;


This sounds like something to address

Addressed, saturationFraction has been clamped to 0-1

mswilburn · 2026-05-30T00:04:02Z

+  soilInputs =
+      fluxes.coarseRootLoss + fluxes.fineRootLoss + fluxes.litterToSoil;
+  saturationFraction = expSoilC / params.soilCSaturation;
+
+  expLitterC += (fluxes.woodLitter + fluxes.leafLitter +
+                 (soilInputs * saturationFraction) - fluxes.litterToSoil -
+                 fluxes.rLitter - fluxes.litterMethane) *
+                climate->length;
+
+  expSoilC += (soilInputs * (1 - saturationFraction) - fluxes.rSoil -
+               fluxes.soilMethane) *
+              climate->length;
+
+  updatePoolsForSoil();
+  status |= checkSoil(expSoilC);
+  status |= checkLitter(expLitterC);


Revised and included test for envi.soilC > params.soilCSaturation scenario

dlebauer

This looks great, glad to have this feature and look forward to seeing whether and when it improves model performance.

I'm about to start a code review but before merging, could you please update the documentation?

dlebauer

Thanks for adding the docs. I made a few comments related to improving clarity.

Adding the clamp to the code as requested by Mike and Copilot will make code consistent with docs, and avoid negative fluxes.

dlebauer · 2026-05-29T06:07:27Z

 | $Q_{10s}$             | soilRespQ10         | Soil respiration Q10                                                                | unitless                                                                            | scalar determining effect of temp on soil respiration          |
 | $D_{\text{moisture}}$ | soilRespMoistEffect | scalar determining effect of moisture on soil resp.                                 | unitless                                                                            |                                                                |
 | $f_{\text{till}}$     | tillageEff          | Effect of tillage on decomposition that exponentially decays over time              | fraction                                                                            | Documented in model structure; event-level term in `events.in` |
+| $f_{\text{C,soil,saturation}}$ | soilCSaturation | Maximum amount of carbon that can be stabilized in the soil determined by soil texture        | $\text{g C} \cdot \text{m}^{-2} \text{ ground area}$                                                                                   |                                                                |


f is reserved for unitless "fraction" parameters.

Something like C_soil,sat, or C^*_soil

Revised to C_soil,saturation

dlebauer · 2026-05-29T06:12:43Z

+If soil carbon saturation is enabled, only a fraction of the total carbon input will be added to the soil. The amount added to the soil carbon pool is a function of the proximity of the pool to the soil carbon saturation limit. As the soil carbon pool aqcuires more carbon and approaches its saturation limit, the amount of carbon stored in the pool decreases. This represents the physical and chemical constraints of the mineralogical surfaces of soil to stabilize carbon for long-term storage. The remaining carbon that is not stabilized in the soil carbon pool due to saturation constraints will be returned to the litter carbon pool to act as fast-turnover carbon \eqref{eq:soil_carbon_to_litter}.
+
+\begin{equation}
+\frac{dC_\text{soil}}{dt} = F^C_{\text{soil}} \cdot (1 - \frac{C_{\text{soil}}}{f_{\text{C,soil,saturation}}}) - R_{\text{soil}} - F^C_{\text{CH}_4\text{,soil}}


F^C_{\text{soil}} it is used earlier to represent “total carbon input to soil pool,” not as an unstabilized return flux, please confirm that it is the correct quantity to use here.

Yes, this is the correct term. The inputs did not change, they are just getting multiplied by (1-saturationFraction). Therefore, F^C_{\text{soil}} remains the same. The term is also correct in the envi.litterC calculation because it is the remainder of the fraction that gets redirected to the litter pool. If F^C_{\text{soil}} * (1-saturationFraction) C goes to the soil pool, then F^C_{\text{soil}} * (saturationFraction) C goes to the litter pool.

mswilburn · 2026-05-30T01:10:47Z

All comments have been addressed, ready for another review.

…turation Merge from master

Add restriction for 'carbon-saturation' requiring 'litter-pool'.

dlebauer

Thanks, this looks great. I reviewed the documentation and made a few suggestions.

Alomir

Looks great - only a couple of minor doc comments.

@dlebauer - this is good to go from the code perspective, I'll leave the doc approval to you

…om/PecanProject/sipnet into SIP287-Implement-Carbon-Saturation

Alomir · 2026-06-12T16:10:16Z

As @dlebauer is away for several weeks, I'm going to merge this in. I believe all of the doc comments have been addressed; any remaining tweaks can be done in a separate PR

Alomir · 2026-07-06T17:09:19Z

This PR is not showing up in the closed PRs list - hoping this comment forces a reindex.

Adding C saturation flag

b6463c9

Alomir reviewed Mar 27, 2026

View reviewed changes

Comment thread src/sipnet/restart.c Outdated

mswilburn added 10 commits March 27, 2026 10:32

Fix flag numbering error

54c071a

Merging from master

ebcffcb

Soil carbon pool calculation and fluxes

8e174fc

Updating flag count

baae4f2

Updating flux state variable calculation

443ccb0

Create unit test

cf727e2

clang-format

68b472c

Merge branch 'master' into SIP287-Implement-Carbon-Saturation

3630bc7

Merging from master

Updating unit testing and config files

43d72a0

Update to unit test

243c275

mswilburn marked this pull request as ready for review May 22, 2026 12:43

mswilburn requested review from dlebauer and mdietze as code owners May 22, 2026 12:43

Alomir requested a review from Copilot May 27, 2026 16:34

Copilot started reviewing on behalf of Alomir May 27, 2026 16:34 View session

Copilot AI reviewed May 27, 2026

View reviewed changes

dlebauer requested changes May 27, 2026

View reviewed changes

mswilburn added 3 commits May 28, 2026 11:37

Updating documentation and changelog

7ff3732

Merging from master

0d77da0

Updating more documentation

3055e64

dlebauer requested changes May 29, 2026

View reviewed changes

mswilburn mentioned this pull request May 29, 2026

Add range constraints to model inputs and throw error for out of range inputs #278

Open

mswilburn added 2 commits May 29, 2026 19:00

Revised documentation

8acb7c6

Capping satFrac and limiting org N

2ba7714

mswilburn and others added 2 commits June 3, 2026 14:03

Merge remote-tracking branch 'origin' into SIP287-Implement-Carbon-Sa…

5a3d5f1

…turation Merge from master

Update model inputs restrictions (#346)

d42d410

Add restriction for 'carbon-saturation' requiring 'litter-pool'.

dlebauer requested changes Jun 4, 2026

View reviewed changes

Comment thread docs/parameters.md Outdated

Comment thread docs/model-structure.md

Comment thread docs/model-structure.md

Comment thread docs/model-structure.md Outdated

Comment thread docs/user-guide/running-sipnet.md

Alomir approved these changes Jun 5, 2026

View reviewed changes

Comment thread docs/user-guide/running-sipnet.md

Comment thread docs/CHANGELOG.md Outdated

Comment thread src/sipnet/state.h Outdated

mswilburn and others added 8 commits June 10, 2026 09:19

Updating documentation

60a5073

Merge branch 'SIP287-Implement-Carbon-Saturation' of https://github.c…

24a48f0

…om/PecanProject/sipnet into SIP287-Implement-Carbon-Saturation

Updating documentation

076999c

Merge branch 'master' into SIP287-Implement-Carbon-Saturation

2b42f20

Add testCarbontSaturation

49ac7d0

Add unitClip function

761c4ad

Update to use unitClip

b0b1c7b

Extern fix for unitClip

6440439

Alomir merged commit af5f3b8 into master Jun 12, 2026
12 checks passed

Alomir deleted the SIP287-Implement-Carbon-Saturation branch June 12, 2026 16:10

Uh oh!

Conversation

mswilburn commented Mar 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

How was this change tested?

Related issues

Checklist

Uh oh!

Alomir left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

mswilburn commented May 22, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Alomir May 27, 2026

Choose a reason for hiding this comment

Uh oh!

mswilburn May 30, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

mswilburn May 30, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

dlebauer left a comment

Choose a reason for hiding this comment

Uh oh!

dlebauer left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

dlebauer May 29, 2026

Choose a reason for hiding this comment

Uh oh!

mswilburn May 30, 2026

Choose a reason for hiding this comment

Uh oh!

dlebauer May 29, 2026

Choose a reason for hiding this comment

Uh oh!

mswilburn May 29, 2026

Choose a reason for hiding this comment

Uh oh!

mswilburn commented May 30, 2026

Uh oh!

dlebauer left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Alomir left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Alomir commented Jun 12, 2026

Uh oh!

Uh oh!

Alomir commented Jul 6, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

mswilburn commented Mar 27, 2026 •

edited

Loading