O2.4.1 Refactored Mizuroute source code, with unit tests, docstrings

[odunbar]

To refactor the source code of mizuroute from https://github.com/limamau/Rivers.
Based off meeting with Andrew/Kat

Tasks

Beta Give feedback

1. Add source functionality for models and calculate_streamflow functions to run Mizuroute in structure below. #9
   +0
2. Add unit tests for all functions
3. Add docstrings
4. Add in Environmental and Dynamics structs #11
   +0
5. Change from "instant" to "evolutionary" style model #10
   +0

Implementation idea

objects in src/

Follow the Julian style:

• abstract types

abstract type AbstractHillslopeModel end
abstract type AbtstractChannelModel end

• structs for the models

struct MizurouteHillslopeV1 <: AbstractHillslopeModel 
    ...params...
end
struct MizurouteChannelV1 <: AbstractChannelModel 
    ...params...
end

struct HillslopeChannelRiverModel{HS <: HillslopeModel, CH <: ChannelModel}
    hillslope_model::HS
    channel_model::CH
end 

• struct for the state

struct RiverState{AM <: AbstractMatrix}
    hillslope::AM # instantaneous
    channel::AM # instantaneous
    graph::Dict # river graph copy?
end 
# initialize method
# initialize_state(river_model::HCRM) where {HCRM <: HillslopChannelRiverModel} end

• struct for the environments

struct StaticEnvironment 
    # static data objects
end
struct DynamicEnvironment 
    # timeseries objects
    # date/time - index map
end
struct Environment{SE <: StaticEnvironment, DE <: DynamicEnvironment}
    static_env::SE
    dyn_env::DE
    graph::Dict # river graph?
end
# get_static(env, :name)
# get_dynamic(env, :name, time=date/time)

• generic methods for river routing environment -> streamflow

function calculate_streamflow(river_model, river_state, static_environment, dyamic_environment) end
# this function contains:
function calculate_hillslope(hillslope_model, hillslope_state, static_environment, dyamic_environment) end
function calculate_streamflow_from_channel(channel_model, channel_state, static_environment, dyamic_environment) end

User interface in examples/

We wish to move towards the "model_type==evolutionary" paradigm

using ClimaRivers
# build model
hillslope = MizurouteHillslopeV1(params) 
channel = MizurouteChannelV1(params)
river_model = HillslopeChannelRiverModel(hillslope, channel)

# build data
graph = ...
static_env = StaticEnvironment(...)
dynamic_env = DynamicEnvironment(...)
env = Environment(static_env, dynamic_env, graph)

# get exp conditions
start_date = ...
end_date = ...

## evolutionary model, evolving a state over time
model_types = ["evolutionary", "instant"]
model_type = model_types[1]

streamflow = zeros(dates,basins)
if model_type == "evolutionary"
    ## intialize river state
    river_state = zeros(dates,basins)
    river_state_instant = set_state(river_model, env, start_date)
    for date in [start_date,end_date]
        river_state[date,:] = evolve_state!(river_state_instant, river_model, env, date)
        streamflow[date,...] = compute_streamflow(river_state_instant)
     end
elseif model_type == "instant"
    ## full-timeseries model, predicts all states at once
    river_state = compute_state(river_model, env, start_date, end_date)
    streamflow = compute_streamflow(river_state)
end