SIP279 SIPNET Restart MVP

[dlebauer]

Summary

• What: Adds MVP full-state restart support for segmented SIPNET runs.
  • Introduces ASCII text restart file as restart schema v1.0
  • Stops at end of .clim file and writes a restart file RESTART_OUT
  • Restarts by specifying RESTART_IN file
  • Writes one output file per climate segment (these outputs can be concatenated downstream)
• Motivation:
  1. To support parameter changes to represent planting of a different PFT
  2. To support state data assimilation

How was this change tested?

Ran:

• make sipnet
• make testbuild
• make testrun
• make smoke

Added restart test coverage:

• hop test: continuous vs segmented equivalence
• same-day multi-event boundary non-replay
• climate ordering
• schema mismatch failure
• model/build mismatch failure
• truncated checkpoint failure
• no-restart unchanged behavior

Key Changes

• Runtime restart module:
  • src/sipnet/restart.c
  • src/sipnet/restart.h
• Runtime wiring:
  • src/sipnet/sipnet.c
  • src/common/context.c
  • src/sipnet/cli.c
• Event determinism helpers:
  • src/sipnet/events.c
  • src/sipnet/events.h
• Tests:
  • tests/sipnet/test_restart_infrastructure/testRestartMVP.c
• Docs:
  • docs/user-guide/running-sipnet.md
  • docs/developer-guide/restart-checkpoint.md
  • mkdocs.yml

Related Issues

• discussed in https://github.com/orgs/ccmmf/discussions/188
• requirements in Restart implementation requirements ccmmf/organization#180
• requirements in Investigate full state save for reset support #271
• implementation spec, fixes Implement MVP full-state restart support in SIPNET #279

Checklist

• Related issues are listed above. PRs without an approved, related issue may not get reviewed.
• PR title has the issue number in it ("[#] <concise description of proposed change>")
• Tests added/updated for new features (if applicable)
• Documentation updated (if applicable)
• docs/CHANGELOG.md updated with noteworthy changes
• Code formatted with clang-format (run git clang-format if needed)

Notes

• Restart climate input must begin with a timestamp (year, day, time) that occurs after the last segment.
• Implementation and initial test scaffolding in this PR was generated with OpenAI Codex based on my specifications and review, but my C skills are limited. My specifications were based on issues linked above.

[Copilot]

Pull request overview

Adds strict binary restart checkpointing to SIPNET to support segmented runs with deterministic resume validation (climate boundary, runtime flags, event cursor determinism), plus integration-style unit tests and documentation.

Changes:

• Introduces src/sipnet/restart.c/.h to write/load full-state checkpoints with strict compatibility checks.
• Wires restart options through CLI + Context and integrates checkpoint load/write into the main run loop.
• Adds event determinism helpers (event cursor + hashing) and new restart-focused tests/docs.

Reviewed changes

Copilot reviewed 29 out of 29 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
Makefile	Adds restart.c to SIPNET build.
src/sipnet/sipnet.c	Loads checkpoint at run start, records processed climate steps, writes checkpoint at run end.
src/sipnet/state.h	Adds Trackers.lastYear so yearly rollover state can be checkpointed/restored.
src/sipnet/restart.c	Implements schema v1 restart header/payload read/write + strict validations.
src/sipnet/restart.h	Declares restart module APIs used by runtime.
src/sipnet/events.c	Adds event cursor indexing and deterministic hashing helpers.
src/sipnet/events.h	Exposes new event cursor/hash APIs for restart determinism checks.
src/sipnet/cli.c	Adds --restart-in/--restart-out and --restart-strict; fixes --file-name to require an argument.
src/sipnet/cli.h	Updates flag-option count for CLI/context mapping.
src/common/context.c	Adds restart config keys, enforces strict mode when restart is used, hides restart keys from config dump.
src/common/context.h	Adds restartStrict, restartIn, restartOut fields to Context.
tests/sipnet/test_restart_infrastructure/Makefile	Builds/runs the new restart MVP test binary in the unit test harness.
tests/sipnet/test_restart_infrastructure/testRestartMVP.c	Adds restart MVP integration test coverage (equivalence, mismatch failures, truncation, etc.).
tests/sipnet/test_restart_infrastructure/restart.param	Parameter fixture for deterministic restart tests.
tests/sipnet/test_restart_infrastructure/events_base.in	Event fixture used to validate deterministic event resume.
tests/sipnet/test_restart_infrastructure/restart_cont.in	Continuous-run input fixture.
tests/sipnet/test_restart_infrastructure/restart_seg1.in	Segment 1 input fixture (writes checkpoint).
tests/sipnet/test_restart_infrastructure/restart_seg2.in	Segment 2 input fixture (loads checkpoint).
tests/sipnet/test_restart_infrastructure/restart_seg2_bad.in	Segment 2 input fixture for mismatch failure.
tests/sipnet/test_restart_infrastructure/restart_full.clim	Climate fixture for continuous run.
tests/sipnet/test_restart_infrastructure/restart_segment1.clim	Climate fixture for segment 1.
tests/sipnet/test_restart_infrastructure/restart_segment2.clim	Climate fixture for segment 2 (valid boundary row).
tests/sipnet/test_restart_infrastructure/restart_segment2_bad.clim	Climate fixture for segment 2 mismatch failure.
docs/user-guide/running-sipnet.md	Documents restart options and strict constraints for users.
docs/user-guide/model-inputs.md	Adds restart options/flag to the run-time options documentation.
docs/developer-guide/restart-checkpoint.md	Adds developer-facing checkpoint schema/validation contract.
mkdocs.yml	Adds restart checkpoint spec page to MkDocs navigation.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 29 out of 29 changed files in this pull request and generated 4 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[dlebauer]

Bump version before merging

[Copilot]

Pull request overview

Copilot reviewed 59 out of 60 changed files in this pull request and generated 12 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Alomir]

Looks good to me (and to copilot, which is good given how much I reworked)