Skip to content

[#345] Update model outputs documentation #347

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
Rahmankhan3 wants to merge 1 commit into
base: master
Choose a base branch
from
Draft

[#345] Update model outputs documentation #347

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
88 changes: 45 additions & 43 deletions docs/user-guide/model-outputs.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,52 +1,51 @@

# Outputs

There are two main output files generated by SIPNET:

1. `sipnet.out`: Model state variables and fluxes at each timestep.
2. `events.out` (name configurable): Contains a record of events processed during the simulation if event handling is enabled.

## Model Outputs

The `sipnet.out` file contains a time series of state variables and fluxes from the simulation.

| # | Symbol | Output Name | Definition / Notes | Units |
|----|-----------------------------|---------------------|----------------------------------------------------------------------------|---------------|
| 1 | | year | Year of start of timestep | (integer) |
| 2 | | day | Day-of-year of start of timestep | (integer) |
| 3 | | time | Hour-of-day (fractional) at start of timestep | hours |
| 4 | | plantWoodC | Woody plant carbon | g C m$^{-2}$ |
| 5 | | plantLeafC | Leaf carbon | g C m$^{-2}$ |
| 6 | | woodCreation | Carbon allocated to wood during timestep | g C m$^{-2}$ |
| 7 | | soil | (Single) soil organic carbon (or mineral soil C pool) | g C m$^{-2}$ |
| 8 | | coarseRootC | Coarse root carbon | g C m$^{-2}$ |
| 9 | | fineRootC | Fine root carbon | g C m$^{-2}$ |
| 10 | | litter | Litter carbon (0 if litter pool disabled) | g C m$^{-2}$ |
| 11 | | soilWater | Soil water content | cm |
| 12 | $\overline{f}_{\text{WHC}}$ | soilWetnessFrac | Mean soil wetness as fraction of water holding capacity over timestep [^1] | unitless |
| 13 | | snow | Snow water equivalent | cm |
| 14 | | npp | Net primary production for timestep | g C m$^{-2}$ |
| 15 | | nee | Net ecosystem exchange (sign convention per code: - (NPP - RH)) | g C m$^{-2}$ |
| 16 | | cumNEE | Cumulative NEE since simulation start | g C m$^{-2}$ |
| 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}$ |
| 20 | | rRoot | Root (autotrophic) respiration | g C m$^{-2}$ |
| 21 | | ra | Total autotrophic respiration (rAboveground + rRoot) | g C m$^{-2}$ |
| 22 | | rh | Total heterotrophic respiration (litter + soil components) | g C m$^{-2}$ |
| 23 | $R$ | rtot | Total ecosystem respiration (ra + rh) | g C m$^{-2}$ |
| 24 | | evapotranspiration | ET (transpiration + immedEvap + evaporation + sublimation) for timestep | cm |
| 25 | | fluxestranspiration | Transpiration component only (as a flux) | cm day$^{-1}$ |
| 27 | $N_\textrm{min}$ | minN | Soil mineral nitrogen | g N m$^{-2}$ |
| | | soilOrgN | Soil organic nitrogen | g N m$^{-2}$ |
| | | litterN | Litter nitrogen | g N m$^{-2}$ |
| | | n2o | Nitrous oxide production | g N m$^{-2}$ |
| | | nLeaching | Nitrogen lost to leaching | g N m$^{-2}$ |
| | | nFixation | Nitrogen demand met by fixation | g N m$^{-2}$ |
| | | nUptake | Nitrogen demand met by uptake from soil | g N m$^{-2}$ |
| | | ch4 | Methane production | g C m$^{-2}$ |
The `sipnet.out` file contains a time series of state variables and fluxes from the simulation.

[^1]: Mean soilWetnessFrac (ratio of soil water / water holding capacity) calculated as average between previous and current time step. Reported for diagnostics only.
Internal moisture dependency functions use instantaneous $W_{soil}/W_{WHC}$ (not this average), and clip that ratio to [0,1] where those dependency functions are defined.
| # | Symbol | Output Name | Definition / Notes | Units |
| -- | ----------------------------- | ------------------- | ------------------------------------------------------------------------- | --------------- |
| 1 | | year | Year of start of timestep | (integer) |
| 2 | | day | Day-of-year of start of timestep | (integer) |
| 3 | | time | Hour-of-day (fractional) at start of timestep | hours |
| 4 | | plantWoodC | Woody plant carbon | g C m$^{-2}$ |
| 5 | | plantLeafC | Leaf carbon | g C m$^{-2}$ |
| 6 | | woodCreation | Carbon allocated to wood during timestep | g C m$^{-2}$ |
| 7 | | soil | (Single) soil organic carbon (or mineral soil C pool) | g C m$^{-2}$ |
| 8 | | coarseRootC | Coarse root carbon | g C m$^{-2}$ |
| 9 | | fineRootC | Fine root carbon | g C m$^{-2}$ |
| 10 | | litter | Litter carbon (0 if litter pool disabled) | g C m$^{-2}$ |
| 11 | | soilWater | Soil water content | cm |
| 12 | $\overline{f}_{\text{WHC}}$ | soilWetnessFrac | Mean soil wetness as fraction of water holding capacity over timestep[^1] | unitless |
| 13 | | snow | Snow water equivalent | cm |
| 14 | | npp | Net primary production for timestep | g C m$^{-2}$ |
| 15 | | nee | Net ecosystem exchange (sign convention per code: - (NPP - RH)) | g C m$^{-2}$ |
| 16 | | cumNEE | Cumulative NEE since simulation start | g C m$^{-2}$ |
| 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}$ |
| 20 | | rRoot | Root (autotrophic) respiration | g C m$^{-2}$ |
| 21 | | ra | Total autotrophic respiration (rAboveground + rRoot) | g C m$^{-2}$ |
| 22 | | rh | Total heterotrophic respiration (litter + soil components) | g C m$^{-2}$ |
| 23 | $R$ | rtot | Total ecosystem respiration (ra + rh) | g C m$^{-2}$ |
| 24 | | evapotranspiration | ET (transpiration + immedEvap + evaporation + sublimation) for timestep | cm |
| 25 | | fluxestranspiration | Transpiration component only (as a flux) | cm day$^{-1}$ |
| 26 | $N_\textrm{min}$ | minN | Soil mineral nitrogen | g N m$^{-2}$ |
| 27 | | soilOrgN | Soil organic nitrogen | g N m$^{-2}$ |
| 28 | | litterN | Litter nitrogen | g N m$^{-2}$ |
| 29 | | plantStorageN | Plant nitrogen storage pool | g N m$^{-2}$ |
| 30 | | n2o | Nitrous oxide production | g N m$^{-2}$ |
| 31 | | nLeaching | Nitrogen lost to leaching | g N m$^{-2}$ |
| 32 | | nFixation | Nitrogen demand met by fixation | g N m$^{-2}$ |
| 33 | | nUptake | Nitrogen demand met by uptake from soil | g N m$^{-2}$ |
| 34 | | ch4 | Methane production | g C m$^{-2}$ |
| 35 | | nppStorage | Net primary production allocated to storage | g C m$^{-2}$ |

An example output file can be found in [tests/smoke/sipnet.out](https://github.com/PecanProject/sipnet/blob/master/tests/smoke/niwot/sipnet.out).

Expand All @@ -62,9 +61,9 @@ year day time plantWoodC plantLeafC woodCreation soil coarseRootC fineRoot
When event handling is enabled, SIPNET will create `events.out` by default, or
`<EVENTS_PREFIX>.out` when a custom events prefix is configured.

This file is designed primarily for _testing and debugging_.
It contains one row for each agronomic event that is processed.
Each row lists the year, day, event type, and parameter name/value pairs.
This file is designed primarily for _testing and debugging_.
It contains one row for each agronomic event that is processed.
Each row lists the year, day, event type, and parameter name/value pairs.
The name/value pairs represent the state variables that are directly changed by an event, recording the change (delta) applied to each.

Information in the events output file can, in principle, be reconstructed or
Expand All @@ -85,3 +84,6 @@ year day type param_name=delta[,param_name=delta,...]
2024 70 irrig fluxes.immedEvap=2.50,envi.soilWater=2.50
2024 200 harv env.litter=4.25,envi.plantLeafC=-1.39,envi.plantWoodC=-1.63,envi.fineRootC=-2.52,envi.coarseRootC=-2.97
```

[^1]: Mean soilWetnessFrac (ratio of soil water / water holding capacity) calculated as average between previous and current time step. Reported for diagnostics only.
Internal moisture dependency functions use instantaneous $W_{soil}/W_{WHC}$ (not this average), and clip that ratio to [0,1] where those dependency functions are defined.
Loading