Add state output and input control to realization

[KJafarzadegan]

Warm states restart are essential

In many applications of hydrologic models, there's a need to restart the model at a specific time. In order to be able to do that the model should provide the state variables at every time step as output and at the same time it must be able to accept the state variables as inputs. Otherwise, when you restart the model, all the state variables will be assumed to have their default values (usually zeros) which will significantly affect the calculated runoff.

To provide an example, assume you run the model from 1979 to 12/31/2016. Now if you want to get the streamflow for the year 2017, one option is to run the model all over again from 1979 till 12/31/2017. The other option is to simply run it from where you stopped (12/31/2016) but using the state variables calculated at the end of 12/31/2016. Otherwise, the result for the year 2017 will be significantly different for these two scenarios.

Noah-MP and WRF-hydro models do this by providing a 2nd output file called the RESTART file (one file for each timestep). You can also provide this RESTART file as input by providing the path to it in the "name list.hrldas" file in WRF-hydro.

The same thing is needed for NextGen to be able to perform sequential procedures such as data assimilation.

Building from advice issued in (NOAA-OWP/cfe#73), we started to try to address this in (NOAA-OWP/cfe#86) and we will be happy to give help if we can.

[mattw-nws]

This is definitely something on our radar, as far as supporting. Technically, much of what is needed in ngen is already there--the model_params feature (this needs better documentation) allows for the passing of variables via BMI methods at the beginning of the simulation (after Initialize but not at every timestep), and this could be used to pass state variables into any BMI module that supports it. Of course, for this to be useful, the module has to support the setup of state variables using this mechanism--and that's a per-module need.

What is more directly on our roadmap is some way of detecting the proper variable names to retrieve and set--and then a mechanism that can retrieve the state (e.g. at the end of a run, in your scenario). This may happen in various ways--@peckhams has proposed a feature for a future version of BMI that will have more categories of variables than just "input" and "output" (to include state variables) directly in the spec, and we've also considered the use of MCM files extended with an additional namespace to capture state (and calibration parameters) variable names for this purpose.

In summary, yes, essential, and yes we plan to add it. No ETA yet though, that's for sure.