Add --debug-log logs for internal model state

CMakeLists.txt

@@ -32,6 +32,7 @@ add_library(commonlib
 add_library(sipnetlib
         src/sipnet/balance.c
         src/sipnet/cli.c
+        src/sipnet/debug_log.c
         src/sipnet/depeffects.c
         src/sipnet/events.c
         src/sipnet/frontend.c
@@ -66,6 +67,7 @@ add_library(tests
         tests/sipnet/test_restart_infrastructure/testRestartMissedCtx.c
         tests/sipnet/test_restart_infrastructure/testRestartMissedEnvi.c
         tests/sipnet/test_sipnet_infrastructure/testClimInput.c
+        tests/sipnet/test_sipnet_infrastructure/testDebugLogFiles.c
         tests/sipnet/test_sipnet_infrastructure/testOutputHeader.c
         tests/sipnet/test_sipnet_infrastructure/testParamInput.c
         tests/utils/helpers.c

Makefile

@@ -11,7 +11,7 @@ COMMON_CFILES:=context.c logging.c modelParams.c util.c
 COMMON_CFILES:=$(addprefix src/common/, $(COMMON_CFILES))
 COMMON_OFILES=$(COMMON_CFILES:.c=.o)
 
-SIPNET_CFILES:=sipnet.c cli.c depeffects.c events.c frontend.c limitations.c nitrogen.c outputItems.c restart.c runmean.c state.c balance.c
+SIPNET_CFILES:=sipnet.c cli.c debug_log.c depeffects.c events.c frontend.c limitations.c nitrogen.c outputItems.c restart.c runmean.c state.c balance.c
 SIPNET_CFILES:=$(addprefix src/sipnet/, $(SIPNET_CFILES))
 SIPNET_OFILES=$(SIPNET_CFILES:.c=.o)
 SIPNET_LIBS=-lsipnet_common

docs/user-guide/model-inputs.md

@@ -209,13 +209,14 @@ Thus, command-line arguments override settings in the configuration file, and co
 
 ### Input / Output Options
 
-| Option          | Default   | Description                                        |
-| --------------- | --------- | -------------------------------------------------- |
-| `input-file`    | sipnet.in | Name of input config file                          |
-| `file-prefix`   | sipnet    | Prefix of climate and parameter files (alias: `file-name` for backwards compatibility) |
-| `events-prefix` | events    | Prefix for events input/output files (`<name>.in`, `<name>.out`) |
-| `restart-in`    | unset     | Path to restart checkpoint to load                 |
-| `restart-out`   | unset     | Path to restart checkpoint to write                |
+| Option          | Default   | Description                                                                                      |
+|-----------------|-----------|--------------------------------------------------------------------------------------------------|
+| `input-file`    | sipnet.in | Name of input config file                                                                        |
+| `file-prefix`   | sipnet    | Prefix of climate and parameter files (alias: `file-name` for backwards compatibility)           |
+| `events-prefix` | events    | Prefix for events input/output files (`<name>.in`, `<name>.out`)                                 |
+| `restart-in`    | unset     | Path to restart checkpoint to load                                                               |
+| `restart-out`   | unset     | Path to restart checkpoint to write                                                              |
+| `debug-log`     | unset     | Prefix for debug log files (`<prefix>_envi.log`, `<prefix>_fluxes.log`, `<prefix>_trackers.log`) |
 
 ### Output Flags
 

docs/user-guide/running-sipnet.md

@@ -24,13 +24,14 @@ When the same option is specified in both places, **command-line arguments take
 
 ### Input/Output Options
 
-| Option             | Short | Argument   | Default     | Description                                                                                |
-|--------------------|-------|------------|-------------|--------------------------------------------------------------------------------------------|
-| `--input-file`     | `-i`  | `<name>`   | `sipnet.in` | Name of input configuration file                                                           |
-| `--file-prefix`    | `-f`  | `<name>`   | `sipnet`    | Prefix for climate and parameter input files (looks for `<name>.clim` and `<name>.param`)  |
-| `--events-prefix`  |  `-e` | `<name>`   | `events`    | Prefix for events input and output files (SIPNET uses `<name>.in` and `<name>.out`)        |
-| `--restart-in`     |       | `<path>`   | unset       | Read a restart checkpoint (schema `1.0`)                                                   |
-| `--restart-out`    |       | `<path>`   | unset       | Write a restart checkpoint at end of run                                                   |
+| Option            | Short | Argument   | Default     | Description                                                                                 |
+|-------------------|-------|------------|-------------|---------------------------------------------------------------------------------------------|
+| `--input-file`    | `-i`  | `<name>`   | `sipnet.in` | Name of input configuration file                                                            |
+| `--file-prefix`   | `-f`  | `<name>`   | `sipnet`    | Prefix for climate and parameter input files (looks for `<name>.clim` and `<name>.param`)   |
+| `--events-prefix` | `-e`  | `<name>`   | `events`    | Prefix for events input and output files (SIPNET uses `<name>.in` and `<name>.out`)         |
+| `--debug-log`     |       | `<prefix>` | unset       | Write debug logs to `<prefix>_envi.log`, `<prefix>_fluxes.log`, and `<prefix>_trackers.log` |
+| `--restart-in`    |       | `<path>`   | unset       | Read a restart checkpoint (schema `1.0`)                                                    |
+| `--restart-out`   |       | `<path>`   | unset       | Write a restart checkpoint at end of run                                                    |
 
 ### Model Feature Flags
 
@@ -104,17 +105,18 @@ Keys are case-insensitive and can use hyphens or underscores (e.g., `EVENTS`, `e
 
 #### Input/Output Keys
 
-| 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                     |
-| `RESTART_IN`      | string     | Path to checkpoint to resume from                                         |
-| `RESTART_OUT`     | string     | Path to checkpoint to write at end of run                                 |
+| 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                                                           |
+| `RESTART_IN`       | string     | Path to checkpoint to resume from                                                                                 |
+| `RESTART_OUT`      | string     | Path to checkpoint to write at end of run                                                                         |
+| `DEBUG_LOG_PREFIX` | string     | Prefix for debug log files (optional; writes `<prefix>_envi.log`, `<prefix>_fluxes.log`, `<prefix>_trackers.log`) |
 
 #### Model Feature Keys
 
@@ -319,6 +321,16 @@ CLIM_FILE my_site.clim
 ...
 ```
 
+### Debug Log Files
+
+**Filename pattern**: `<prefix>_envi.log`, `<prefix>_fluxes.log`, `<prefix>_trackers.log` (if `--debug-log <prefix>` is provided)
+
+These files contain one row per time step. Each row starts with `year`, `day`, and `time`.
+
+- `<prefix>_envi.log` contains one column for each field in the global `envi` struct
+- `<prefix>_fluxes.log` contains one column for each field in the global `fluxes` struct
+- `<prefix>_trackers.log` contains one column for each field in `trackers` (prefixed `t.`) and `phenologyTrackers` (prefixed `pt.`)
+
 ## Input Files Reference
 
 For details on the format and contents of input files, see:

src/common/context.c

@@ -61,6 +61,7 @@ void initContext(void) {
   CREATE_CHAR_CONTEXT(inputFile,      "INPUT_FILE",       DEFAULT_INPUT_FILE);
   CREATE_CHAR_CONTEXT(restartIn,      "RESTART_IN",       NO_DEFAULT_FILE);
   CREATE_CHAR_CONTEXT(restartOut,     "RESTART_OUT",      NO_DEFAULT_FILE);
+  CREATE_CHAR_CONTEXT(debugLogPrefix, "DEBUG_LOG_PREFIX", NO_DEFAULT_FILE);
   // clang-format on
 
   // Other

src/common/context.h

@@ -75,6 +75,7 @@ struct Context {
   char inputFile[CONTEXT_CHAR_MAXLEN];
   char restartIn[CONTEXT_CHAR_MAXLEN];
   char restartOut[CONTEXT_CHAR_MAXLEN];
+  char debugLogPrefix[CONTEXT_CHAR_MAXLEN];
 
   // Other
   // File prefix for climate and param files

src/sipnet/cli.c

@@ -12,6 +12,7 @@
 #define DECLARE_ARG_FOR_MAP(x) #x, #x
 #define CLI_RESTART_IN 1001
 #define CLI_RESTART_OUT 1002
+#define CLI_DEBUG_LOG 1003
 
 // The struct 'option' is defined in getopt.h, and is expected by getopt_long()
 // See docs/developer-guide/cli-options.md for details on how to add a new
@@ -50,6 +51,7 @@ static struct option long_options[] = {  // NOLINT
     {"events-prefix", required_argument, 0, 'e'},
     {"restart-in", required_argument, 0, CLI_RESTART_IN},
     {"restart-out", required_argument, 0, CLI_RESTART_OUT},
+    {"debug-log", required_argument, 0, CLI_DEBUG_LOG},
     {"help", no_argument, 0, 'h'},
     {"version", no_argument, 0, 'v'},
     {0, 0, 0, 0}};
@@ -102,6 +104,7 @@ void usage(char *progName) {
   printf("  --carbon-saturation  Enable maximum storage limit of soil organic carbon (0)\n");
   printf("\n");
   printf("Output flags: (prepend flag with 'no-' to force off, eg '--no-print-header')\n");
+  printf("  --debug-log <prefix> Write debug state logs to <prefix>_{envi,fluxes,trackers}.log\n");
   printf("  --do-main-output     Print time series of all output variables to <file-prefix>.out (1)\n");
   printf("  --do-single-outputs  Print selection* of outputs one variable per file (e.g. <file-prefix>.NEE)\n");
   printf("  --dump-config        Print final config to <file-prefix>.config (0)\n");
@@ -193,6 +196,17 @@ void parseCommandLineArgs(int argc, char *argv[]) {
         }
         updateCharContext("restartOut", optarg, CTX_COMMAND_LINE);
         break;
+      case CLI_DEBUG_LOG: {
+        const size_t maxDebugPrefixLen =
+            FILENAME_MAXLEN - strlen("_trackers.log") - 1;
+        requireCLIArg("--debug-log");
+        if (strlen(optarg) > maxDebugPrefixLen) {
+          logError("debug-log prefix %s is too long; max length is %zu\n",
+                   optarg, maxDebugPrefixLen);
+          exit(EXIT_CODE_BAD_CLI_ARGUMENT);
+        }
+        updateCharContext("debugLogPrefix", optarg, CTX_COMMAND_LINE);
+      } break;
       case 'i':
         requireCLIArg("--input-file");
         if (strlen(optarg) >= FILENAME_MAXLEN) {