Allow TimeStepper's StopTime to be optional

[andrewdnolan]

This PR enables StopTime to be optional for TimeStepper's. In coupled E3SM simulations components do not know the stop time (coupler is responsible for calling finalize).

The optional StopTime was enabled by reordering the arguments to TimeStepper::create so that StopTime was the last argument, which is a requirement of std::optional.

An overload to TimeStepper::init1 is added that accepts a structure (TimeInitParams), which will be how the coupler will provides the StartTime instead of it being read from the config file.

I've also added an overload to initOmegaModules which accepts this TimeInitParams structure, which will be used in the coupled version of ocnInit. In refactoring initOmegaModules to be suitable for both standalone and coupled configuration, I moved a bunch of code not related to init'ing modules from initOmegaModules into ocnInit. This code was primarily related to reading the restart and initial condition IOStreams, which will need different handling in coupled mode.

While this PR adds an overload to initOmegaModules that accepts TimeInitParams, I have intentionally not added an analogous overload to ocnInit. Exactly what we pass ocnInit in a coupled simulation is still being scoped out and how to pass that (e.g. all as separate arguments or as struct(s)) is yet to be determined. A follow on PR that adds coupled overloads for ocnInit, ocnRun, and ocnFinalize will come later. Given that the work enclosed in this PR is self contained, I figured it would make sense to get reviewed and merged while we figure out more details for the coupled driver.

---

Checklist

• Documentation:
  • User's Guide has been updated
  • Developer's Guide has been updated
  • Documentation has been built locally and changes look as expected
• Linting
  • Pre-commit run locally
• Building
  • CMake build does not produce any new warnings from changes in this PR
• Testing
  • Add a comment to the PR titled Testing with the following:
    • Which machines CTest unit tests
      have been run on and indicate that are all passing.
    • The Polaris omega_pr test suite
      has passed, using the Polaris e3sm_submodules/Omega baseline
    • Document machine(s), compiler(s), and the build path(s) used for -p for both the baseline (Polaris e3sm_submodules/Omega) and the PR build
    • Indicate "All tests passed" or document failing tests
    • Document testing used to verify the changes including any tests that are added/modified/impacted.
  • New tests:
    • CTest unit tests for new features have been added per the approved design.

[andrewdnolan]

Documentation:

Updated the developers guide to reflect the new argument order and detail the TimeStepper::init1(TimeParams); overload.

Local build of the documentation can be found here:

https://portal.nersc.gov/cfs/e3sm/anolan/omega_PR400/_build/html/

[andrewdnolan]

Testing:

CTest unit tests

• Machine: pm-cpu
• Compiler: gnu
• Build type: Release
• Result: All tests passed

Polaris omega_pr suite

• Baseline workdir: /pscratch/sd/a/anolan/omega_PR400//baseline_omega_pr
• Baseline build: /pscratch/sd/a/anolan/omega_PR400/build/baseline
• PR build: /pscratch/sd/a/anolan/omega_PR400/build/optional-stoptime
• PR workdir: /pscratch/sd/a/anolan/omega_PR400/my_branch_omega_pr
• Machine: pm-cpu
• Compiler: gnu
• Build type: Release
• Log: /pscratch/sd/a/anolan/omega_PR400/my_branch_omega_pr/polaris_omega_pr.o52491023
• Result: All tests passed

Tests added/modified/impacted

• CTest:TimeStepperTest.cpp added testOptionalStopTime— ensures doStep method works without StopTime or EndAlarm

[xylar]

Suggested change

	coupler, overriding the value defined in the configuration file.
	the coupler, overriding the value defined in the configuration file.

[xylar]

I don't feel super expert in Omega time stepping but this approach looks clean to me. I'm approving mostly on the basis of it seeming like a sensible and extensible design.