PecanProject · ANAMASGARD · May 27, 2026 · May 30, 2026 · Jun 10, 2026 · Jun 19, 2026
@@ -37,6 +37,7 @@ sections to include in release notes:
 ### Changed
 
 - Renamed the CLI option `--file-name` to `--file-prefix` for clarity while keeping `--file-name` as a backward-compatible alias (#320)
+- Renamed `plantWoodCStorageDelta` to `plantWoodCAccountingDelta` (internal/restart state) and output debug column `nppStorage` to `cnDelta` to reflect that the field is an accounting term for carbon not coupled to nitrogen, not a storage pool (#339).
 
 ### Removed
 

@@ -70,6 +70,8 @@ Event files must be segmented to the same time boundaries as climate segments.
 
 ## When Saved State Changes
 
+If you rename a serialized restart key without changing struct layout (for example `envi.plantWoodCStorageDelta` → `envi.plantWoodCAccountingDelta`), update the key in `src/sipnet/restart.c` and restart tests; checkpoints written by older builds with the previous key name will fail to load.
+
 If you add saved state or change an existing saved payload:
 
 1. Update the serialized payload type and restart read/write logic in `src/sipnet/restart.c`.

@@ -163,26 +163,27 @@ litter, $f_{\text{harvest,transfer,}i}$ set to 1.
 ### Wood Carbon
 
 As stated above, SIPNET uses a five-day averaged NPP when allocating gained carbon to plant growth. To implement this,
-the current timestep's net primary production (adjusted GPP - autotrophic respiration) is added to the wood carbon pool
-where it acts as a storage pool, and all allocations from the averaged NPP are deducted from that pool.
+the current timestep's net primary production (adjusted GPP - autotrophic respiration) is accumulated in an accounting
+term, and all allocations from the averaged NPP are deducted from that term.
 
-Starting in SIPNET v2.1, to support mass balance tracking, this storage is explicitly tracked as a separate pool called
-$C_{\text{wood,storage}}$, which is initialized to zero. We can represent this storage of carbon as:
+Starting in SIPNET v2.1, to support mass balance tracking, this term is explicitly tracked as
+$C_{\text{wood,accounting}}$, which is initialized to zero. We can represent this
+accounting delta as:
 
 \begin{equation}
-\frac{dC_{\text{wood,storage}}}{dt} = (GPP - R_a) - \overline{\text{NPP}}_\text{alloc}
-\label{eq:wood_c_storage}
+\frac{dC_{\text{wood,accounting}}}{dt} = (GPP - R_a) - \overline{\text{NPP}}_\text{alloc}
+\label{eq:wood_c_accounting}
 \end{equation}
 
-where $\overline{NPP}_\text{alloc}$ is the sum of the carbon allocated to the biomass pools as growth. This storage term
-represents the lag between NPP input and allocation output due to the five-day averaging. Tracking the storage term
-explicitly enables checking nitrogen mass balance, as the storage changes do not involve nitrogen changes, whereas
-growth allocation does.
+where $\overline{NPP}_\text{alloc}$ is the sum of the carbon allocated to the biomass pools as growth. This accounting
+term represents the lag between NPP input and allocation output due to the five-day averaging. Tracking it explicitly
+enables checking nitrogen mass balance, as these carbon changes do not involve nitrogen changes, whereas growth
+allocation does.
 
-The total wood carbon is the sum of the structural wood carbon and the storage pool:
+The total wood carbon is the sum of the structural wood carbon and the accounting delta:
 
 \begin{equation}
-C_{\text{wood,total}} = C_{\text{wood}} + C_{\text{wood,storage}}
+C_{\text{wood,total}} = C_{\text{wood}} + C_{\text{wood,accounting}}
 \end{equation}
 
 Thus, changes to (non-storage) wood carbon over time are determined by:
@@ -709,8 +710,8 @@ Nitrogen limitation occurs when plant nitrogen demand exceeds the supply of plan
 demand is diagnosed from potential biomass growth derived from five-day averaged NPP.
 
 If plant nitrogen demand exceeds plant-available nitrogen, allocation of carbon to new growth is reduced to the level
-that available nitrogen can support. Carbon not allocated to growth remains in the wood storage pool 
-(\eqref{eq:wood_c_storage}). Thus, nitrogen limitation does not directly affect carbon uptake; it reduces future 
+that available nitrogen can support. Carbon not allocated to growth remains in the wood carbon accounting term
+(\eqref{eq:wood_c_accounting}). Thus, nitrogen limitation does not directly affect carbon uptake; it reduces future
 photosynthesis by constraining increases in photosynthetically active leaf area \eqref{eq:lai_calculation}.
 
 Nitrogen limitation is applied during the flux calculation stage of the model update sequence. N limitation is 
@@ -723,7 +724,7 @@ implemented as follows:
 - Reduce biomass growth accordingly by scaling carbon allocation to plant biomass pools.
 - Calculate the amount by which plant N demand exceeds available supply [^*].
 - Calculate the fraction by which biomass growth must be reduced so that N demand equals supply.
-- Reduce biomass growth accordingly by scaling carbon allocation to plant biomass pools. Unallocated carbon remains in the wood storage pool \eqref{eq:wood_c_storage}.
+- Reduce biomass growth accordingly by scaling carbon allocation to plant biomass pools. Unallocated carbon remains in the wood carbon accounting term \eqref{eq:wood_c_accounting}.
 - Calculate nitrogen uptake as the amount of N required to support the realized plant growth, based on fixed stoichiometry.
 
 [^*]: Nitrogen limitation is evaluated after accounting for biological nitrogen fixation and before mineral nitrogen

@@ -99,7 +99,7 @@ Run-time parameters can change from one run to the next, or when the model is st
 | Symbol                            | Parameter Name | Definition                                                               | Units                                                               | Notes                                                                                    |
 |-----------------------------------|----------------|--------------------------------------------------------------------------|---------------------------------------------------------------------|------------------------------------------------------------------------------------------|
 | $C_{\text{wood},0}$               | plantWoodInit  | Initial wood carbon                                                      | $\text{g C} \cdot \text{m}^{-2} \text{ ground area}$                | Above-ground + roots                                                                     |
-| $C_{\text{wood,storage}}$         |                | Wood carbon storage pool (delta), initialized internally to 0            | $\text{g C} \cdot \text{m}^{-2} \text{ ground area}$                | Not a runtime param; $C_{\text{wood,total}} = C_{\text{wood}} + C_{\text{wood,storage}}$ |
+| $C_{\text{wood,accounting}}$       | plantWoodCAccountingDelta | Wood carbon accounting delta (N-lag term), initialized internally to 0 | $\text{g C} \cdot \text{m}^{-2} \text{ ground area}$                | Not a runtime param; $C_{\text{wood,total}} = C_{\text{wood}} + C_{\text{wood,accounting}}$ |
 | $LAI_0$                           | laiInit        | Initial leaf area                                                        | $\text{m}^2 \text{ leaves} \cdot \text{m}^{-2} \text{ ground area}$ | Multiply by SLW to get initial plant leaf C: $C_{\text{leaf},0} = LAI_0 \cdot SLW$       |
 | $C_{\text{litter},0}$             | litterInit     | Initial litter carbon                                                    | $\text{g C} \cdot \text{m}^{-2} \text{ ground area}$                |                                                                                          |
 | $C_{\text{soil},0}$               | soilInit       | Initial soil carbon                                                      | $\text{g C} \cdot \text{m}^{-2} \text{ ground area}$                |                                                                                          |

@@ -14,7 +14,7 @@ The `sipnet.out` file contains a time series of state variables and fluxes from
 | 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}$  |
+| 4  |                             | plantWoodC          | Total wood carbon ($C_{\text{wood}} + C_{\text{wood,accounting}}$) [^2]   | 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}$  |
@@ -48,6 +48,8 @@ The `sipnet.out` file contains a time series of state variables and fluxes from
 [^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.
 
+[^2]: `plantWoodC` reports structural wood carbon plus the N-lag accounting term ($C_{\text{wood,accounting}}$). The N-coupled structural pool alone is not written as a separate output column.
+
 An example output file can be found in [tests/smoke/sipnet.out](https://github.com/PecanProject/sipnet/blob/master/tests/smoke/niwot/sipnet.out).
 
 ```

@@ -11,15 +11,16 @@
 BalanceTracker balanceTracker;
 
 void getMassTotals(double *carbon, double *nitrogen) {
-  *carbon = (envi.plantWoodC + envi.plantWoodCStorageDelta) + envi.plantLeafC +
-            envi.fineRootC + envi.coarseRootC + envi.soilC;
+  *carbon = (envi.plantWoodC + envi.plantWoodCAccountingDelta) +
+            envi.plantLeafC + envi.fineRootC + envi.coarseRootC + envi.soilC;
   if (ctx.litterPool) {
     *carbon += envi.litterC;
   }
 
   if (ctx.nitrogenCycle) {
     // Note: this is the one place where we use plantWoodC by itself; it's the
-    // reason plantWoodCStorageDelta was created, so that we can ignore it here.
+    // reason plantWoodCAccountingDelta was created, so that we can ignore it
+    // here.
     *nitrogen =
         envi.plantWoodC / params.woodCN + envi.plantLeafC / params.leafCN +
         envi.fineRootC / params.fineRootCN + envi.coarseRootC / params.woodCN +

@@ -531,7 +531,7 @@ void processEvents(void) {
         const double fracRB = harvParams->fractionRemovedBelow;
         const double fracTB = harvParams->fractionTransferredBelow;
 
-        const double woodC = envi.plantWoodC + envi.plantWoodCStorageDelta;
+        const double woodC = envi.plantWoodC + envi.plantWoodCAccountingDelta;
         // Litter increase
         double litterAdd = fracTA * (envi.plantLeafC + woodC);
         double soilAdd = fracTB * (envi.fineRootC + envi.coarseRootC);

@@ -189,7 +189,7 @@ void initResetState(RestartState *state, MeanTracker *npp) {
   state->enviPF[9] = (StateField){"envi.soilOrgN",                FT_DOUBLE, &envi.soilOrgN,               0};
   state->enviPF[10] = (StateField){"envi.litterN",                FT_DOUBLE, &envi.litterN,                0};
   state->enviPF[11] = (StateField){"envi.plantStorageN",          FT_DOUBLE, &envi.plantStorageN, 0};
-  state->enviPF[12] = (StateField){"envi.plantWoodCStorageDelta", FT_DOUBLE, &envi.plantWoodCStorageDelta, 0};
+  state->enviPF[12] = (StateField){"envi.plantWoodCAccountingDelta", FT_DOUBLE, &envi.plantWoodCAccountingDelta, 0};
   state->enviPF[13] = (StateField){"envi.invalid",                FT_INVALID, NULL, FIELD_INVALID};
 
   state->trackersPF[0] = (StateField){"trackers.gpp",                 FT_DOUBLE, &trackers.gpp,                0};

@@ -439,8 +439,8 @@ void outputHeader(FILE *out) {
                "rRoot       ra       rh     rtot evapotranspiration ");
   fprintf(out,
           "fluxestranspiration     minN  soilOrgN    litterN  "
-          "plantStorageN       n2o nLeaching  nFixation  nUptake      ch4  "
-          "nppStorage\n");
+          "plantStorageN       n2o nLeaching  nFixation  nUptake      ch4   "
+          "cnDelta\n");
 }
 
 /*!
@@ -453,7 +453,7 @@ void outputHeader(FILE *out) {
 void outputState(FILE *out, int year, int day, double time) {
 
   fprintf(out, "%4d %3d %5.2f %10.2f %10.2f %12.2f ", year, day, time,
-          (envi.plantWoodC + envi.plantWoodCStorageDelta), envi.plantLeafC,
+          (envi.plantWoodC + envi.plantWoodCAccountingDelta), envi.plantLeafC,
           trackers.woodCreation);
   fprintf(out, "%8.2f ", envi.soilC);
   fprintf(out, "%11.2f %9.2f ", envi.coarseRootC, envi.fineRootC);
@@ -467,10 +467,10 @@ void outputState(FILE *out, int year, int day, double time) {
       trackers.rh, trackers.rtot, trackers.evapotranspiration);
   fprintf(out, "%19.4f %8.4f %9.4f %10.4f %14.4f ", fluxes.transpiration,
           envi.minN, envi.soilOrgN, envi.litterN, envi.plantStorageN);
-  fprintf(out, "%9.6f %9.4f %10.4f %8.4f %8.4f", trackers.n2o,
+  fprintf(out, "%9.6f %9.4f %10.4f %8.4f %8.4f ", trackers.n2o,
           trackers.nLeaching, trackers.nFixation, trackers.nUptake,
           trackers.methane);
-  fprintf(out, "%12.4f\n", envi.plantWoodCStorageDelta);
+  fprintf(out, "%9.4f\n", envi.plantWoodCAccountingDelta);
 }
 
 // de-allocate space used for climate linked list
@@ -1075,7 +1075,7 @@ void vegResp(double *folResp, double *woodResp, double baseFolResp) {
 
   // :: from [1], eq (A19)
   *woodResp = params.baseVegResp *
-              (envi.plantWoodC + envi.plantWoodCStorageDelta) *
+              (envi.plantWoodC + envi.plantWoodCAccountingDelta) *
               pow(params.vegRespQ10, climate->tair / 10.0);
 }
 
@@ -1103,7 +1103,7 @@ void vegResp2(double *folResp, double *woodResp, double *growthResp,
                                            // by a given fraction in winter
   }
   *woodResp = params.baseVegResp *
-              (envi.plantWoodC + envi.plantWoodCStorageDelta) *
+              (envi.plantWoodC + envi.plantWoodCAccountingDelta) *
               pow(params.vegRespQ10, climate->tair / 10.0);
 
   // Rg is a fraction of the recent mean NPP
@@ -1206,8 +1206,8 @@ void calcRootAndWoodFluxes(void) {
 
   // Wood litter, in g C * m^-2 ground area * day^-1
   // turnover rate is fraction lost per day
-  fluxes.woodLitter =
-      (envi.plantWoodC + envi.plantWoodCStorageDelta) * params.woodTurnoverRate;
+  fluxes.woodLitter = (envi.plantWoodC + envi.plantWoodCAccountingDelta) *
+                      params.woodTurnoverRate;
 
   // :: from [3], root model description
   calcRootResp(&fluxes.rCoarseRoot, params.coarseRootQ10,
@@ -1611,7 +1611,7 @@ void updateMainPools(void) {
   double r_a = fluxes.rVeg + fluxes.rFineRoot + fluxes.rCoarseRoot;
   double nppAllocations = fluxes.leafCreation + fluxes.woodCreation +
                           fluxes.fineRootCreation + fluxes.coarseRootCreation;
-  envi.plantWoodCStorageDelta +=
+  envi.plantWoodCAccountingDelta +=
       ((fluxes.photosynthesis - r_a) - nppAllocations) * climate->length;
   envi.plantWoodC += (fluxes.woodCreation - fluxes.woodLitter -
                       fluxes.leafOnCreationFromWood) *
@@ -1806,7 +1806,7 @@ void setupModel(void) {
 
   envi.plantWoodC =
       (1 - params.coarseRootFrac - params.fineRootFrac) * params.plantWoodInit;
-  envi.plantWoodCStorageDelta = 0.0;
+  envi.plantWoodCAccountingDelta = 0.0;
   envi.plantLeafC = params.laiInit * params.leafCSpWt;
 
   if (ctx.litterPool) {

@@ -455,11 +455,12 @@ typedef struct Environment {
   // Carbon gains from photosynthesis and losses to respiration don't affect the
   // total nitrogen in the system. Since SIPNET uses a five-day time-averaged
   // NPP value for allocating plant growth, there is a lag from input to output
-  // here that must be tracked. So, we split the wood pool into plantWoodC
-  // (above) and a new pool to track non-nitrogen-affecting changes over time.
-  // As this is a delta, it can be negative. Note that the actual "wood carbon"
-  // is the sum of these two pools.
-  double plantWoodCStorageDelta;
+  // here that must be tracked. plantWoodC (above) holds N-coupled structural
+  // wood; plantWoodCAccountingDelta tracks carbon changes with no associated
+  // nitrogen (an accounting term, not a storage pool). As this is a delta, it
+  // can be negative. Total wood carbon is plantWoodC +
+  // plantWoodCAccountingDelta.
+  double plantWoodCAccountingDelta;
 } Envi;
 
 // Global var

@@ -69,7 +69,7 @@ void initEnv(void) {
   }
 
   // not used here, but accessed
-  envi.plantWoodCStorageDelta = 0.0;
+  envi.plantWoodCAccountingDelta = 0.0;
   envi.soilWater = 10.0;
   envi.minN = 10.0;
 }

@@ -14,8 +14,8 @@ int main(void) {
 
   // Missed envi update
   copyFile(STATE_FILE, BAD_STATE);
-  replaceFirstOccurrence(BAD_STATE, "double plantWoodCStorageDelta;",
-                         "double plantWoodCStorageDelta;double dummyPool;");
+  replaceFirstOccurrence(BAD_STATE, "double plantWoodCAccountingDelta;",
+                         "double plantWoodCAccountingDelta;double dummyPool;");
 
   // Missed context update
   copyFile(CONTEXT_FILE, BAD_CTX);

@@ -2,6 +2,7 @@
 #include <stdlib.h>
 #include <string.h>
 
+#include "common/exitCodes.h"
 #include "common/logging.h"
 #include "utils/tUtils.h"
 
@@ -168,6 +169,46 @@ static int hasManagedEventOnDay(const char *eventFile, int year, int day) {
   return found;
 }
 
+static int testObsoletePlantWoodCStorageDeltaKeyFails(void) {
+  int status = 0;
+  int stepStatus = 0;
+  int rc;
+
+  logTest("Starting testObsoletePlantWoodCStorageDeltaKeyFails\n");
+
+  runShell("rm -f run.out events.out run.restart *.log");
+
+  stepStatus = prepRunFiles("restart_segment1.clim", "events_segment1.in");
+  if (stepStatus) {
+    logTest(
+        "Failed to prepare files for obsolete restart key test segment 1\n");
+    return stepStatus;
+  }
+
+  status |= (runModel("restart_seg1.in", "obsolete_key_seg1.log") != 0);
+  status |= !fileContains(CHECKPOINT_FILE, "envi.plantWoodCAccountingDelta ");
+  status |=
+      replaceFirstOccurrence(CHECKPOINT_FILE, "envi.plantWoodCAccountingDelta ",
+                             "envi.plantWoodCStorageDelta ");
+
+  stepStatus = prepRunFiles("restart_segment2.clim", "events_segment2.in");
+  if (stepStatus) {
+    logTest(
+        "Failed to prepare files for obsolete restart key test segment 2\n");
+    return status | stepStatus;
+  }
+
+  rc = runModel("restart_seg2.in", "obsolete_key_seg2.log");
+  status |= (rc != EXIT_CODE_BAD_RESTART_PARAMETER);
+  status |= !fileContains("obsolete_key_seg2.log", "unknown key");
+
+  if (status) {
+    logTest("testObsoletePlantWoodCStorageDeltaKeyFails failed (rc=%d)\n", rc);
+  }
+
+  return status;
+}
+
 static int testDefaultEventsFileUsedWhenUnset(void) {
   int status = 0;
   int stepStatus = 0;
@@ -723,6 +764,7 @@ int run(void) {
   status |= testEventsPrefixCliOverrideUsed();
   status |= testConfigDumpIncludesRestartAndEventsKeys();
   status |= testSegmentedEquivalence();
+  status |= testObsoletePlantWoodCStorageDeltaKeyFails();
   status |= testStrictClimateMismatchFails();
   status |= testCheckpointFarFromMidnightWarnsAndWrites();
   status |= testRestartNotNearMidnightWarns();