SIP279 SIPNET Restart MVP #276

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.

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

Merged

dlebauer merged 67 commits into master from codex/restart-mvp-master

Mar 16, 2026

.github/workflows/cpp-linter.yaml

-Original file line number
+Diff line change
@@ Expand Up / @@ -26,5 +26,5 @@ jobs: @@
           - name: analysis
             if: steps.linter.outputs.checks-failed > 0
             run: |
-                echo "${{ steps.linter.outputs.checks-failed }} linter checks failed" |
+                echo "${{ steps.linter.outputs.checks-failed }} linter checks failed"
+                exit 1

.gitignore

-Original file line number
+Diff line change
@@ -1,29 +1,28 @@
     # build artifacts and executables
     # /sipnet instead of just sipnet to NOT ignore test dirs
-    *.o
-    *.a
+    **/*.o
+    **/*.a
     /sipnet
-    subsetData
-    transpose
     .doxygen.stamp
     .mkdocs.stamp
-    site/*
-    site_preview/*
     _codeql_build_dir/
     _codeql_detected_source_root
     # documentation
     docs/api
     docs/latex
+    docs/html
     # Test files
     tests/sipnet/*/*
+    !tests/sipnet/*/*/
     !tests/sipnet/*/*.c
     !tests/sipnet/*/*.h
     !tests/sipnet/*/*.in
     !tests/sipnet/*/*.out
     !tests/sipnet/*/*.clim
     !tests/sipnet/*/*.param
+    !**/.clang-tidy
     # But exclude generated test outputs
     tests/sipnet/*/events.out
     tests/sipnet/*/sipnet.out
@@ Expand All / @@ -34,8 +33,11 @@ tests/sipnet/*/sipnet.config @@
     .Rproj.user
     .Rhistory
     src/sipnet/.vscode/*
+    cmake-build-debug-gcc/
+    .vscode/
     # Temporary and backup files
     *.bak
     *~
-    *.tmp
+    *.tmp
+    /tmp/

CMakeLists.txt

-Original file line number
+Diff line change
@@ Expand Up / @@ -30,14 +30,15 @@ add_library(commonlib @@
     )
     add_library(sipnetlib
+            src/sipnet/balance.c
             src/sipnet/cli.c
             src/sipnet/events.c
             src/sipnet/frontend.c
             src/sipnet/outputItems.c
+            src/sipnet/restart.c
             src/sipnet/runmean.c
             src/sipnet/sipnet.c
             src/sipnet/state.c
-            src/sipnet/balance.c
     )
     add_library(tests
@@ Expand All / @@ -55,4 +56,10 @@ add_library(tests @@
             tests/sipnet/test_modeling/testNitrogenCycle.c
             tests/sipnet/test_modeling/testDependencyFunctions.c
             tests/sipnet/test_modeling/testBalance.c
+            tests/sipnet/test_restart_infrastructure/testRestartMVP.c
+            tests/sipnet/test_restart_infrastructure/testRestartMissedEnvi.c
+            tests/sipnet/test_restart_infrastructure/testRestartMissedCtx.c
+            tests/sipnet/test_restart_infrastructure/mock_state.c
+            tests/sipnet/test_restart_infrastructure/bad_code/ctx_fail.c
+            tests/sipnet/test_restart_infrastructure/bad_code/envi_fail.c
     )

Makefile

-Original file line number
+Diff line change
@@ Expand Up / @@ -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 events.c frontend.c outputItems.c runmean.c state.c balance.c
+    SIPNET_CFILES:=sipnet.c cli.c events.c frontend.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
@@ Expand Down @@

docs/CHANGELOG.md

-Original file line number
+Diff line change
@@ Expand Up / @@ -29,6 +29,8 @@ sections to include in release notes: @@
     ### Added
     - Build and release binaries for MacOS and Windows on release (in addition to existing Linux builds)
+    - MVP restart checkpoints for segmented runs (`RESTART_IN` / `RESTART_OUT`) (#279)
+    - Configurable events prefix for `<prefix>.in` / `<prefix>.out`
     - Support for tillage events (#158)
     - `woodCreation` as output (#161)
     - Soil mineral pool (#170)
@@ Expand Down @@

docs/developer-guide/restart-checkpoint.md

-Original file line number
+Diff line change
@@ -0,0 +1,94 @@
+    # Restart Checkpoint Spec
+    This page documents SIPNET's restart checkpoint implementation.
+    ## Scope and Intent
+    SIPNET restart is designed for segmented orchestration:
+    - stop at end of one climate segment
+    - write full runtime state at segment end (`RESTART_OUT`)
+    - restore full runtime state at next segment start (`RESTART_IN`)
+    - fail fast on incompatible restart/configuration inputs
+    SIPNET itself does not stitch outputs across segments.
+    ## Runtime Sequence
+    On resume, SIPNET executes:
+. Normal setup (`setupModel`, `setupEvents`)
+. Load checkpoint and overwrite runtime state
+. Validate compatibility checks and restart boundary checks
+. Continue run from resumed climate input
+    ## Restart Schema v1.0 Overview
+    Checkpoint format is ASCII text with one key/value per line:
+    - header: `SIPNET_RESTART 1.0`
+    - metadata: `meta_info.model_version`, `meta_info.build_info`, `meta_info.checkpoint_utc_epoch`, `meta_info.processed_steps`
+    - schema layout guard metadata: `schema_layout.envi_size`, `schema_layout.trackers_size`, `schema_layout.phenology_trackers_size`, `schema_layout.event_trackers_size`
+    - mode flags: `flags.*`
+    - boundary metadata: `boundary.year`, `boundary.day`, `boundary.time`, `boundary.length`
+    - mean tracker metadata: `mean.npp.*`
+    - full runtime state: `envi.*`, `trackers.*`, `phenology.*`, `event_trackers.*`
+    - mean ring buffers: `mean.npp.values.<idx>`, `mean.npp.weights.<idx>`
+    - end marker: `end_restart 1`
+    Example checkpoint content is exercised in
+    `tests/sipnet/test_restart_infrastructure/testRestartMVP.c`.
+    ## Validation Contract
+    On load, SIPNET enforces the following. Lines that start with (warning) log a warning and do not error.
+    - magic header match
+    - schema version match
+    - model numeric version match
+    - `schema_layout.*` values exactly match the expected struct sizes for the running build
+    - (warning) build info mismatch
+    - context flag compatibility
+    - first-row climate timestamp strictly after checkpoint boundary (`year`, `day`, `time`)
+    - (warning) resumed segment starts on the midnight-following day and within one timestep after midnight
+    - mean tracker shape/cursor validity
+    - All lines appearing after `end_restart` are ignored
+    - integer values must fit in signed 32-bit range
+    - floating-point values must be finite (`nan`/`inf` are rejected)
+    All mismatches above are hard errors except as indicated.
+    ## Climate and Event Boundaries
+    Restart writes always emit a checkpoint. If the last processed climate step is
+    more than one timestep before midnight, SIPNET logs a warning, as there will be a time gap in any resumption from that
+    file.
+    Resumed climate segments must begin on the day after the checkpoint boundary. If they start more than one timestep
+    after midnight (using the first resumed climate row's timestep length) SIPNET logs a warning.
+    Event files must be segmented to the same time boundaries as climate segments.
+    ## When Saved State Changes
+    If you add saved state or change an existing saved payload:
+. Update the serialized payload type and restart read/write logic in `src/sipnet/restart.c`.
+. Update the `RESTART_SCHEMA_LAYOUT_*` constants, static asserts, and runtime schema-layout validation.
+. Update restart docs/tests and bump `RESTART_SCHEMA_VERSION`.
+    ## Struct Drift Guards
+    Restart schema v1.0 includes compile-time and runtime drift guards so struct layout changes cannot silently pass:
+    - Compile-time guards: `_Static_assert` checks in `src/sipnet/restart.c` for `Envi`, `Trackers`, `PhenologyTrackers`, `EventTrackers`, and expected number of model flags in `Context`.
+    - Runtime guards: `schema_layout.*` fields in each checkpoint are validated on load.
+    - Test guardrails: `tests/sipnet/test_restart_infrastructure/testRestartMVP.c` verifies schema layout keys are present and rejects tampered values.
+    ## Schema Bump Checklist
+    When intentionally changing the restart schema version:
+. Update `src/sipnet/restart.c` in all schema touchpoints: `RESTART_SCHEMA_VERSION`, `RESTART_SCHEMA_LAYOUT_*`, `_Static_assert` layout guards, and checkpoint read/write + required-key validation logic.
+. Update restart examples/fixtures to the new header and key set, including the restart fixtures in `tests/sipnet/test_restart_infrastructure/testRestartMVP.c`.
+. Update docs that name schema version or key expectations: `docs/developer-guide/restart-checkpoint.md` and `docs/user-guide/running-sipnet.md`.

docs/user-guide/model-inputs.md

            
                      Original file line number
                      Diff line number
                      Diff line change
                  
    @@ -95,7 +95,9 @@ loc	year day  time length tair tsoil par    precip vpd   vpdSoil vPress wspd
  
    ## Agronomic Events

    Agronomic (management) events are read from an `events.in` file. This file specifies one event per line:

    Agronomic (management) events are read from `events.in` by default, or from

    `<EVENTS_PREFIX>.in` when `EVENTS_PREFIX` / `--events-prefix` is set. This

    file specifies one event per line:

    | col | parameter   | description                          | units  | notes                                            |

    | --- | ----------- | ------------------------------------ | ------ | ------------------------------------------------ |

    @@ -207,21 +209,25 @@ 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-name`  | sipnet    | Prefix of climate and parameter files |

    | Option          | Default   | Description                                        |

    | --------------- | --------- | -------------------------------------------------- |

    | `input-file`    | sipnet.in | Name of input config file                          |

    | `file-name`     | sipnet    | Prefix of climate and parameter files              |

    | `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                |

    ### Output Flags

    | Option              | Default | Description                                                    |

    |---------------------|---------|----------------------------------------------------------------|

    | `do-main-output`    | on      | Print time series of all output variables to `<file-name>.out` |

    | `do-single-outputs` | off     | Print outputs one variable per file (e.g. `<file-name>.NEE`)   |

    | `dump-config`       | on      | Print final config to `<file-name>.config`                     |

    | `do-single-outputs` | off     | Print selected outputs only (`NEE`, `NEE_cum`, `GPP`, `GPP_cum`) one variable per file (e.g. `<file-name>.NEE`) |

    | `dump-config`       | off     | Print final config to `<file-name>.config`                     |

    | `print-header`      | on      | Whether to print header row in output files                    |

    | `quiet`             | off     | Suppress info and warning message                              |

    ### Model Flags

    | Option           | Default | Description                                                                             |

    @@ -260,24 +266,24 @@ See `sipnet --help` for a full list of available command-line options.
  
    SIPNET reads a configuration file that specifies run-time options without using command-line arguments. By default, SIPNET looks for a file named `sipnet.in` in the current directory. These will be overwritten by command-line arguments if specified.

    The configuration file uses a simple key-value format, `option = value`, 

    with one option per line; comments follow `#`. Flags are specified as 0 for off and 1 for on.

    with one option per line; comments follow `!`. Flags are specified as 0 for off and 1 for on.

    #### Example Configuration File

    Note that case is ignored for parameter names, as well as dashes and underscores.

    ```

    # Base filename (used for derived filenames)

    ! Base filename (used for derived filenames)

    FILE_NAME = mysite

    # Output options

    ! Output options

    DO_MAIN_OUTPUT = 1

    DO_SINGLE_OUTPUTS = 0

    DUMP_CONFIG = 1

    PRINT_HEADER = 1

    QUIET = 0

    # Model options

    ! Model options

    EVENTS = 1

    GDD = 1

    GROWTH_RESP = 0

docs/user-guide/model-outputs.md

            
                      Original file line number
                      Diff line number
                      Diff line change
                  
    @@ -3,7 +3,7 @@
  
    There are two main output files generated by SIPNET:

    1. `sipnet.out`: Model state variables and fluxes at each timestep.

    2. `events.out`: Contains a record of agronomic events processed during the simulation (if event handling is enabled).

    2. `events.out` (name configurable): Contains a record of events processed during the simulation if event handling is enabled.

    ## Model Outputs

    @@ -59,18 +59,21 @@ year day  time plantWoodC plantLeafC woodCreation      soil coarseRootC fineRoot
  
    ## Events output

    When event handling is enabled, SIPNET will create a file named `events.out`. 

    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. 

    The name/value pairs represent the state variables that are directly changed by an event, recording the change (delta) applied to each.

    Information in `events.out` can, in principle, be reconstructed or inferred from `events.in` and `sipnet.out` though this may be confounded if simultaneous events affect the same variable.

    Information in the events output file can, in principle, be reconstructed or

    inferred from the corresponding events input file and `sipnet.out` though this

    may be confounded if simultaneous events affect the same variable.

    Still, _`sipnet.out` is the authoritative source_ for information about system state and evolution in time, including responses to events.

    Below is an example `events.out`, with header enabled for clarity. 

    Below is an example events output file, with header enabled for clarity.

    Note the delimiters: spaces separate columns, commas separate name/value pairs, and `=` map names with their values (deltas).

    ```

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

SIP279 SIPNET Restart MVP #276

Uh oh!

Diff view

Diff view

There are no files selected for viewing

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!