Sync SIPNET user/model docs with current implementation by Copilot · Pull Request #380 · PecanProject/sipnet

Copilot · 2026-08-28T14:01:45Z

The documentation had drifted from the current SIPNET behavior, especially around runtime configuration, input formats, event handling, and emitted outputs. This updates the affected user and model docs to reflect the implementation in src/.

Runtime configuration and CLI
- aligned documented flags/options with the current CLI, including flooding
- corrected config-file parsing details: keys are matched case-insensitively, non-alphanumerics are ignored, and separators may be whitespace, =, or :
- clarified which paths are derived from FILE_PREFIX versus directly configured
- corrected the config key for single-output files to DO_SINGLE_OUTPUT
Input file formats
- updated sipnet.param docs to match the current parser: name value per non-comment line, with extra columns tolerated for backward compatibility
- corrected climate examples to use positive timestep lengths and the current 12-column format while retaining note of legacy 14-column support
- refreshed event input docs to reflect supported event types and current irrigation/harvest behavior
Outputs and event records
- updated the main output table and examples to match the current header, including plantStorageN and nppStorage
- clarified soilWetnessFrac behavior under flooding
- documented that events.out may include internally computed events such as leafon, leafoff, and plantdeath, not only user-specified agronomic events
Model structure
- corrected the plant-death description to match the automatic mortality check in the model rather than describing it as an input harvest case
- aligned the event-structure narrative with current computed-event behavior and leaf on/off implementation

Example of the corrected configuration syntax and key naming:

FILE_PREFIX = my_site
EVENTS = 1
FLOODING = 0
DO_MAIN_OUTPUT = 1
DO_SINGLE_OUTPUT = 0
PRINT_HEADER = 1

Fixes Update model documentation to match code implementation #379

dlebauer

@copilot you have done a nice job. I have left some comments, questions, and requests for changes. Please submit all requests for changes as a separate PR, and respond to comments/questions inline. Accept any of my code suggestions that you agree with. if you don't agree, make a counter-suggestion or comment.

dlebauer · 2026-08-28T23:38:45Z

+Leaf on and leaf off events define the timing of leaf emergence and senescence, respectively. These events do not carry
+their own magnitude parameters; instead, the transferred carbon and nitrogen are computed from model state and the


revising for clarity

Suggested change

Leaf on and leaf off events define the timing of leaf emergence and senescence, respectively. These events do not carry

their own magnitude parameters; instead, the transferred carbon and nitrogen are computed from model state and the

Leaf on and leaf off events define the timing of leaf emergence and senescence, respectively. These events only specify the date, not the amount, of leaf biomass C and N added or subtracted; instead, the transferred carbon and nitrogen are computed from model state and the

dlebauer · 2026-08-28T23:45:12Z

-the leaf carbon pool on the leaf off date. 
+Leaf on and leaf off events define the timing of leaf emergence and senescence, respectively. These events do not carry
+their own magnitude parameters; instead, the transferred carbon and nitrogen are computed from model state and the
+parameters `leafGrowth`, `leafOnReallocFrac`, `fracLeafFall`, and `leafNResorptionFrac`.


@copilot Please use mathematical symbols consistently in this section. Before replacing the source code names here, add leafOnReallocFrac and leafNResorptionFrac, with symbols that follow conventions in that file, to docs/parameters.md - they are currently absent. Then use those symbols throughout lines 1214–1235, not only in this paragraph.

Please inform me if there are other places where source code names are used in this file and should be replaced.

Updated in d4566ee. I added leafOnReallocFrac and leafNResorptionFrac to /home/runner/work/sipnet/sipnet/docs/parameters.md and rewrote the leaf-on/leaf-off section to use symbols throughout. The other remaining source-facing names I noticed in this file are the literal event codes (leafon, leafoff, plantdeath) and option names (FLOODING, ANAEROBIC), where the text is referring to file or CLI values rather than equation terms.

dlebauer · 2026-08-29T00:35:27Z

Suggested change

- Nitrogen (when enabled): leaf-on reallocation changes plant N storage by $\Delta N = C_{\text{leafon}}(1/CN_{\text{leaf}} - 1/CN_{\text{wood}})$. Positive $\Delta N$ is drawn from storage and can limit leaf-on; negative $\Delta N$ is returned to storage.

The carbon constraint, and the nitrogen constraint when applicable, scale the transfer down. The scaled amount is applied to the pools and is not subsequently reduced by the general nitrogen limitation (Sec. [Nitrogen Limitation](#nitrogen-limitation)).

dlebauer · 2026-08-29T00:36:58Z

Suggested change

from the leaf carbon pool to the litter pool (or soil pool, if the litter pool is not being used). When `nitrogen-cycle` is enabled, the nitrogen corresponding to the transferred leaf carbon follows it, except for the fraction resorbed to the plant nitrogen storage pool.

Copilot · 2026-08-29T00:41:22Z

@dlebauer I've opened a new pull request, #385, to work on those changes. Once the pull request is ready, I'll request review from you.

dlebauer · 2026-08-29T00:56:15Z

@copilot are you still planning to respond to my comments in this PR?

Copilot · 2026-08-29T01:00:18Z

@copilot are you still planning to respond to my comments in this PR?

Yes. I pushed follow-up changes in d4566ee and replied on the addressed review threads.

it fails too often for reasons unrelated to a PR. It is sufficient to be notified of broken links.

Co-authored-by: Alomir <1099935+Alomir@users.noreply.github.com>

Co-authored-by: dlebauer <464871+dlebauer@users.noreply.github.com>

Co-authored-by: David LeBauer <dlebauer@gmail.com>

dlebauer

This is great, lets merge!

Copilot

🟡 Changes recommended

A few updated doc statements/labels remain inconsistent with the implementation (e.g., config syntax, missing INPUT_FILE in the key table, SOIL_TEMP vs SOIL_PHENOL, and the rSoil symbol).

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This PR updates SIPNET’s user and model documentation to match the current implementation in src/, focusing on configuration/CLI behavior, input formats (params/climate/events), and the emitted outputs (including computed/internal events).

Changes:

Documented current runtime flags/keys (including flooding) and clarified how config values are normalized/merged and reported via --dump-config.
Updated climate, parameter, and events input format docs to reflect current parsers and event handling (including leafon/leafoff).
Updated output field documentation and examples to match the current sipnet.out header and events.out semantics (including internally computed events).

File summaries

File	Description
docs/user-guide/running-sipnet.md	Updates config/CLI docs, config key tables, and troubleshooting guidance.
docs/user-guide/model-outputs.md	Aligns `sipnet.out`/`events.out` field descriptions and examples with current outputs.
docs/user-guide/model-inputs.md	Updates parameter/climate/events input format docs and runtime option notes.
docs/user-guide/getting-started.md	Refreshes smoke-test walkthrough to include merged config output.
docs/parameters.md	Adds/clarifies parameters related to leaf-on reallocation and N resorption.
docs/model-structure.md	Updates model-structure narrative/equations for leaf events, plant death, and N handling.

Review details

Files reviewed: 6/6 changed files
Comments generated: 7
Review effort level: Lite

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.


+Note that it is possible for $\overline{\text{NPP}}$ to be negative, which can occur when autotrophic respiration 
+exceeds GPP. In this case, the plant pools will shrink as carbon is lost to respiration and litter. Also, as this is not
+an instantaneous calculation of NPP, it is possible that a negative allocation may by applied to a pool even if the 


+
+- the growing season start and end dates as specified by the parameters `leafOnDay` and `leafOffDay`, or
+- growing degree days when `GDD = 1`, or
+- soil temperature when `SOIL_TEMP = 1`.



-Both fine and coarse root carbon change in the same way as leaf carbon. Change in carbon for these pools is determined
-as follows, applied separately to fine and coarse roots:
+Change in carbon for the fine root and coarse root pools is determined as follows::


 | 17 | $GPP$                       | gpp                 | Gross primary production                                                   | g C m$^{-2}$  |
 | 18 |                             | rAboveground        | Aboveground autotrophic respiration (leaves + wood)                        | g C m$^{-2}$  |
-| 19 | $R_H$                       | rSoil               | Heterotrophic respiration                                                  | g C m$^{-2}$  |
+| 19 | $R_H$                       | rSoil               | Total belowground respiration (rRoot + rh).                                                  | g C m$^{-2}$  |


 ### Configuration File Format

-Each line in the configuration file contains a key-value pair separated by whitespace:
+Each line in the configuration file uses `KEY = VALUE` syntax; `!` starts a comment line:


 | Key                | Value Type | Description                                                                                                       |
 |--------------------|------------|-------------------------------------------------------------------------------------------------------------------|
-| `INPUT_FILE`       | string     | Name of configuration file to read                                                                                |
 | `FILE_PREFIX`      | string     | Prefix for climate and parameter input files                                                                      |
-| `PARAM_FILE`       | string     | Path to model parameters file (optional; defaults to `<FILE_PREFIX>.param`)                                       |
-| `CLIM_FILE`        | string     | Path to climate file (optional; defaults to `<FILE_PREFIX>.clim`)                                                 |
-| `OUT_FILE`         | string     | Path for main output file (optional; defaults to `<FILE_PREFIX>.out`)                                             |
-| `OUT_CONFIG_FILE`  | string     | Path for config dump file (optional; defaults to `<FILE_PREFIX>.config`)                                          |
 | `EVENTS_PREFIX`    | string     | Prefix used to derive events input and output filenames                                                           |


+
+! Output
+DO_MAIN_OUTPUT = 1
+DO_SINGLE_OUTPUTS = 0


Copilot AI assigned Copilot and Alomir Aug 28, 2026

Copilot started work on behalf of Alomir August 28, 2026 14:01 View session

Copilot AI linked an issue Aug 28, 2026 that may be closed by this pull request

Update model documentation to match code implementation #379

Closed

Copilot AI changed the title ~~[WIP] Update model documentation to match code implementation~~ Sync SIPNET user/model docs with current implementation Aug 28, 2026

Copilot finished work on behalf of Alomir August 28, 2026 14:09

Copilot AI requested a review from Alomir August 28, 2026 14:09

dlebauer requested changes Aug 29, 2026

View reviewed changes

Copilot AI mentioned this pull request Aug 29, 2026

[WIP] [WIP] Address feedback on syncing SIPNET user/model docs with implementation #385

Closed

Copilot started work on behalf of dlebauer August 29, 2026 00:56 View session

Copilot finished work on behalf of dlebauer August 29, 2026 01:01

Copilot AI requested a review from dlebauer August 29, 2026 01:01

This was referenced Aug 29, 2026

SIP325 document proposed C and N limited leaf-on events #332

Closed

[#345] Update model outputs documentation #347

Closed

dlebauer and others added 3 commits August 28, 2026 18:36

Don't require link-check success for PR merge (#387)

0a9c35a

it fails too often for reasons unrelated to a PR. It is sufficient to be notified of broken links.

docs: align user docs with current SIPNET behavior

e7472dc

Co-authored-by: Alomir <1099935+Alomir@users.noreply.github.com>

docs: address review follow-up requests

752c115

Co-authored-by: dlebauer <464871+dlebauer@users.noreply.github.com>

dlebauer force-pushed the copilot/update-model-documentation branch from d4566ee to 752c115 Compare August 29, 2026 01:36

dlebauer and others added 9 commits August 31, 2026 14:58

Merge branch 'master' into copilot/update-model-documentation

d1a50d4

Apply suggestion from @dlebauer

b905586

Co-authored-by: David LeBauer <dlebauer@gmail.com>

Apply suggestion from @dlebauer

8d258ee

Co-authored-by: David LeBauer <dlebauer@gmail.com>

Apply suggestion from @dlebauer

da1cf00

Co-authored-by: David LeBauer <dlebauer@gmail.com>

Apply suggestion from @dlebauer

cfaae1a

Co-authored-by: David LeBauer <dlebauer@gmail.com>

Apply suggestion from @dlebauer

bf612cb

Co-authored-by: David LeBauer <dlebauer@gmail.com>

Apply batched suggestions from code review

ab68dc6

Co-authored-by: David LeBauer <dlebauer@gmail.com>

Reformat tables

0b1fd33

Update plant carbon doc

82bbf8c

Alomir and others added 4 commits September 1, 2026 15:49

Update for soil/litter carbon, N resorp, litter N

09599d2

Update more N mechanics

147256e

Tweak for time step size

dad9698

Apply suggestion from @dlebauer

9343821

dlebauer reviewed Sep 3, 2026

View reviewed changes

Comment thread docs/model-structure.md Outdated

fix wording re NPP

5ec3b67

dlebauer approved these changes Sep 3, 2026

View reviewed changes

Merge branch 'master' into copilot/update-model-documentation

14d2eb6

dlebauer marked this pull request as ready for review September 3, 2026 15:35

dlebauer requested review from mdietze and mswilburn as code owners September 3, 2026 15:35

Copilot AI lite review requested due to automatic review settings September 3, 2026 15:35

dlebauer enabled auto-merge (squash) September 3, 2026 15:35

Copilot started reviewing on behalf of dlebauer September 3, 2026 15:35 View session

dlebauer merged commit 55b0bd1 into master Sep 3, 2026
12 checks passed

dlebauer deleted the copilot/update-model-documentation branch September 3, 2026 15:36

Copilot AI reviewed Sep 3, 2026

View reviewed changes

		Leaf on and leaf off events define the timing of leaf emergence and senescence, respectively. These events do not carry
		their own magnitude parameters; instead, the transferred carbon and nitrogen are computed from model state and the


	- Nitrogen (when enabled): leaf-on reallocation changes plant N storage by $\Delta N = C_{\text{leafon}}(1/CN_{\text{leaf}} - 1/CN_{\text{wood}})$. Positive $\Delta N$ is drawn from storage and can limit leaf-on; negative $\Delta N$ is returned to storage.

	The carbon constraint, and the nitrogen constraint when applicable, scale the transfer down. The scaled amount is applied to the pools and is not subsequently reduced by the general nitrogen limitation (Sec. [Nitrogen Limitation](#nitrogen-limitation)).


	from the leaf carbon pool to the litter pool (or soil pool, if the litter pool is not being used). When `nitrogen-cycle` is enabled, the nitrogen corresponding to the transferred leaf carbon follows it, except for the fraction resorbed to the plant nitrogen storage pool.

Uh oh!

Conversation

Copilot AI commented Aug 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

dlebauer left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

dlebauer Aug 28, 2026

Choose a reason for hiding this comment

Uh oh!

dlebauer Aug 28, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Aug 29, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

dlebauer Aug 29, 2026

Choose a reason for hiding this comment

Uh oh!

dlebauer Aug 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI commented Aug 29, 2026

Uh oh!

dlebauer commented Aug 29, 2026

Uh oh!

Copilot AI commented Aug 29, 2026

Uh oh!

Uh oh!

dlebauer left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Copilot AI commented Aug 28, 2026 •

edited

Loading

dlebauer Aug 29, 2026 •

edited

Loading