Skip to content

Add user-facing descriptions of model parameters #37

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.

Sign up for GitHub

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
merged 3 commits into from
Apr 27, 2025
Merged

Add user-facing descriptions of model parameters #37

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
d39e62c
Parameter descriptions and more flexible parameter update
ConnectedSystems Apr 27, 2025
f8f7c06
Update example
ConnectedSystems Apr 27, 2025
69dff81
Expand acronym
ConnectedSystems Apr 27, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 12 additions & 12 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -172,18 +172,18 @@ To display an overview of a node or network:
julia> node
Name: 406219 [IHACRESBilinearNode]
Area: 1985.73
┌──────────────┬───────────┬─────────────┬─────────────┐
│ Parameter │ Value │ Lower Bound │ Upper Bound │
├──────────────┼───────────┼─────────────┼─────────────┤
│ d │ 84.2802 │ 10.0 │ 550.0 │
│ d2 │ 2.42241 │ 0.0001 │ 10.0 │
│ e │ 0.812959 │ 0.1 │ 1.5 │
│ f │ 2.57928 │ 0.01 │ 3.0 │
│ a │ 5.92338 │ 0.1 │ 10.0 │
│ b │ 0.0989926 │ 0.001 │ 0.1 │
│ storage_coef │ 1.86134 │ 1.0e-10 │ 10.0 │
│ alpha │ 0.727905 │ 1.0e-5 │ 1.0 │
└──────────────┴───────────┴─────────────┴─────────────┘
┌──────────────┬───────────┬─────────────┬─────────────┬──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ Parameter │ Value │ Lower Bound │ Upper Bound │ Description │
├──────────────┼───────────┼─────────────┼─────────────┼──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ d │ 84.2802 │ 10.0 │ 550.0 │ Catchment moisture deficit threshold, higher values indicate the catchment can hold more water before generating runoff. │
│ d2 │ 2.42241 │ 0.0001 │ 10.0 │ Scaling factor (d*d2) which creates a second threshold, changing the shape of effective rainfall response. │
│ e │ 0.812959 │ 0.1 │ 1.5 │ PET conversion factor, controls the rate of evapotranspiration losses, converts temperature to PET. │
│ f │ 2.57928 │ 0.01 │ 3.0 │ Plant stress threshold, controls at what moisture deficit plants begin to experience stress. │
│ a │ 5.92338 │ 0.1 │ 10.0 │ Quickflow storage coefficient, where higher values lead to faster quickflow response. │
│ b │ 0.0989926 │ 0.001 │ 0.1 │ Slowflow storage coefficient, lower values lead to slower baseflow recession. │
│ storage_coef │ 1.86134 │ 1.0e-10 │ 10.0 │ Groundwater interaction factor, controling how water is exchanged with deeper groundwater. │
│ alpha │ 0.727905 │ 1.0e-5 │ 1.0 │ Effective rainfall scaling factor, partitions rainfall into runoff. │
└──────────────┴───────────┴─────────────┴─────────────┴──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
```

### Network specification
Expand Down
35 changes: 30 additions & 5 deletions docs/src/examples/node_creation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,14 +7,39 @@ user-defined values.
using Streamfall

hymod_node = create_node(SimpleHyModNode, "410730", 129.2)
# Name: 410730 [SimpleHyModNode]
# Area: 129.2
# ┌───────────┬───────┬─────────────┬─────────────┬──────────────────────────────────────────────────────────────────────────────────────────────────────┐
# │ Parameter │ Value │ Lower Bound │ Upper Bound │ Description │
# ├───────────┼───────┼─────────────┼─────────────┼──────────────────────────────────────────────────────────────────────────────────────────────────────┤
# │ Sm_max │ 250.0 │ 1.0 │ 500.0 │ Maximum soil storage capacity. │
# │ B │ 1.0 │ 0.0 │ 2.0 │ Controls how quickly the catchment becomes saturated as rainfall accumulates. │
# │ alpha │ 0.2 │ 0.0 │ 1.0 │ The split between quick and slow flow components. Higher values direct more water through quickflow. │
# │ Kf │ 0.5 │ 0.1 │ 0.9999 │ Quickflow recession. │
# │ Ks │ 0.05 │ 0.001 │ 0.1 │ Slowflow recession. │
# └───────────┴───────┴─────────────┴─────────────┴──────────────────────────────────────────────────────────────────────────────────────────────────────┘

# Hymod parameters ("hy_" prefix is simply to avoid any variable name conflicts)
hy_Sm_max = 250.0
hy_B = 1.0
hy_alpha = 0.2
hy_Kf = 0.5
hy_Ks = 0.05
hy_Sm_max = 370.0
hy_B = 0.5
hy_alpha = 0.3
hy_Kf = 0.25
hy_Ks = 0.25

# Update parameters
update_params!(hymod_node, hy_Sm_max, hy_B, hy_alpha, hy_Kf, hy_Ks)

# The "Value" column indicates model parameters have been updated.
print(hymod_node)
# Name: 410730 [SimpleHyModNode]
# Area: 129.2
# ┌───────────┬───────┬─────────────┬─────────────┬──────────────────────────────────────────────────────────────────────────────────────────────────────┐
# │ Parameter │ Value │ Lower Bound │ Upper Bound │ Description │
# ├───────────┼───────┼─────────────┼─────────────┼──────────────────────────────────────────────────────────────────────────────────────────────────────┤
# │ Sm_max │ 370.0 │ 1.0 │ 500.0 │ Maximum soil storage capacity. │
# │ B │ 0.5 │ 0.0 │ 2.0 │ Controls how quickly the catchment becomes saturated as rainfall accumulates. │
# │ alpha │ 0.3 │ 0.0 │ 1.0 │ The split between quick and slow flow components. Higher values direct more water through quickflow. │
# │ Kf │ 0.25 │ 0.1 │ 0.9999 │ Quickflow recession. │
# │ Ks │ 0.25 │ 0.001 │ 0.1 │ Slowflow recession. │
# └───────────┴───────┴─────────────┴─────────────┴──────────────────────────────────────────────────────────────────────────────────────────────────────┘
```
26 changes: 13 additions & 13 deletions docs/src/primer.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ The spec takes the following form:
# The node type which defines which model is used for this node
# In this case, it is the IHACRES with the bilinear formulation of the CMD module
node_type: IHACRESBilinearNode
area: 130.0 # subcatchment area in km^2 (from BoM)
area: 130.0 # subcatchment area in km^2 (from the Australian Bureau of Meteorology)

# This spec defines a single node system
# so it has no nodes upstream (inlets) or downstream (outlets)
Expand Down Expand Up @@ -76,18 +76,18 @@ Node 1
--------
Name: 410730 [IHACRESBilinearNode]
Area: 130.0
┌──────────────┬───────┬─────────────┬─────────────┐
│ Parameter │ Value │ Lower Bound │ Upper Bound │
├──────────────┼───────┼─────────────┼─────────────┤
│ d │ 200.0 │ 10.0 │ 550.0 │
│ d2 │ 2.0 │ 0.0001 │ 10.0 │
│ e │ 1.0 │ 0.1 │ 1.5 │
│ f │ 0.8 │ 0.01 │ 3.0 │
│ a │ 0.9 │ 0.1 │ 10.0 │
│ b │ 0.1 │ 0.001 │ 0.1 │
│ storage_coef │ 2.9 │ 1.0e-10 │ 10.0 │
│ alpha │ 0.95 │ 1.0e-5 │ 1.0 │
└──────────────┴───────┴─────────────┴─────────────┘
┌──────────────┬───────┬─────────────┬─────────────┬──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ Parameter │ Value │ Lower Bound │ Upper Bound │ Description │
├──────────────┼───────┼─────────────┼─────────────┼──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ d │ 200.0 │ 10.0 │ 550.0 │ Catchment moisture deficit threshold, higher values indicate the catchment can hold more water before generating runoff. │
│ d2 │ 2.0 │ 0.0001 │ 10.0 │ Scaling factor (d*d2) which creates a second threshold, changing the shape of effective rainfall response. │
│ e │ 1.0 │ 0.1 │ 1.5 │ PET conversion factor, controls the rate of evapotranspiration losses, converts temperature to PET. │
│ f │ 0.8 │ 0.01 │ 3.0 │ Plant stress threshold, controls at what moisture deficit plants begin to experience stress. │
│ a │ 0.9 │ 0.1 │ 10.0 │ Quickflow storage coefficient, where higher values lead to faster quickflow response. │
│ b │ 0.1 │ 0.001 │ 0.1 │ Slowflow storage coefficient, lower values lead to slower baseflow recession. │
│ storage_coef │ 2.9 │ 1.0e-10 │ 10.0 │ Groundwater interaction factor, controling how water is exchanged with deeper groundwater. │
│ alpha │ 0.95 │ 1.0e-5 │ 1.0 │ Effective rainfall scaling factor, partitions rainfall into runoff. │
└──────────────┴───────┴─────────────┴─────────────┴──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
```


Expand Down
2 changes: 1 addition & 1 deletion src/Nodes/DamNode.jl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ Base.@kwdef mutable struct DamNode{P,A<:AbstractFloat} <: NetworkNode
area::A

max_storage::A
storage_coef::P = Param(0.5, bounds=(0.00001, 10.0))
storage_coef::P = Param(0.5, bounds=(0.00001, 10.0), desc="Storage coefficient.")

# Dam storage volume to level
calc_dam_level::Function = c_dam_level
Expand Down
23 changes: 11 additions & 12 deletions src/Nodes/GR4J/GR4JNode.jl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -71,14 +71,10 @@ Base.@kwdef mutable struct GR4JNode{P,A<:AbstractFloat} <: GRNJNode
const area::A

# Parameters
# x1 : maximum capacity of the production store (mm) (> 0)
# x2 : groundwater exchange coefficient (mm) (value < and > 0 possible)
# x3 : one day ahead maximum capacity of the routing store (mm, > 0)
# x4 : time base of unit hydrograph UH1 (days, > 0.5)
X1::P = Param(350.0, bounds=(1.0, 1500.0))
X2::P = Param(0.0, bounds=(-10.0, 5.0))
X3::P = Param(40.0, bounds=(1.0, 500.0))
X4::P = Param(0.5, bounds=(0.5, 10.0))
X1::P = Param(350.0, bounds=(1.0, 1500.0), desc="Maximum soil water storage capacity.")
X2::P = Param(0.0, bounds=(-10.0, 5.0), desc="Water exchange with deeper groundwater and adjacent catchments.")
X3::P = Param(40.0, bounds=(1.0, 500.0), desc="Maximum capacity of one day ahead of routing store, controls the baseflow component.")
X4::P = Param(0.5, bounds=(0.5, 10.0), desc="Time base of quickflow controlling the timing and shape of hydrograph.")

# stores
p_store::Vector{A} = [0.0]
Expand Down Expand Up @@ -226,10 +222,13 @@ end
Update parameters for GR4J.
"""
function update_params!(node::GR4JNode, X1::Float64, X2::Float64, X3::Float64, X4::Float64)::Nothing
node.X1 = Param(X1, bounds=node.X1.bounds)
node.X2 = Param(X2, bounds=node.X2.bounds)
node.X3 = Param(X3, bounds=node.X3.bounds)
node.X4 = Param(X4, bounds=node.X4.bounds)
param_pairs = zip([:X1, :X2, :X3, :X4], [X1, X2, X3, X4])

# First item will always be the set value, so it can be skipped
for (p, v) in param_pairs
param = getfield(node, p)
setfield!(node, p, Param(v; (keys(param)[2:end] .=> values(param)[2:end])...))
end

return nothing
end
Expand Down
22 changes: 12 additions & 10 deletions src/Nodes/HyMod/HyModNode.jl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,11 +25,11 @@ Base.@kwdef mutable struct SimpleHyModNode{P,A<:AbstractFloat} <: HyModNode
const area::A

# parameters
Sm_max::P = Param(250.0, bounds=(1.0, 500.0))
B::P = Param(1.0, bounds=(0.0, 2.0))
alpha::P = Param(0.2, bounds=(0.0, 1.0))
Kf::P = Param(0.5, bounds=(0.1, 0.9999))
Ks::P = Param(0.05, bounds=(0.001, 0.1))
Sm_max::P = Param(250.0, bounds=(1.0, 500.0), desc="Maximum soil storage capacity.")
B::P = Param(1.0, bounds=(0.0, 2.0), desc="Controls how quickly the catchment becomes saturated as rainfall accumulates.")
alpha::P = Param(0.2, bounds=(0.0, 1.0), desc="The split between quick and slow flow components. Higher values direct more water through quickflow.")
Kf::P = Param(0.5, bounds=(0.1, 0.9999), desc="Quickflow recession.")
Ks::P = Param(0.05, bounds=(0.001, 0.1), desc="Slowflow recession.")

# stores
Sm::Array{A} = [0.0]
Expand Down Expand Up @@ -173,11 +173,13 @@ end
Update parameters for HyMod.
"""
function update_params!(node::HyModNode, Sm_max::F, B::F, alpha::F, Kf::F, Ks::F) where {F<:Float64}
node.Sm_max = Param(Sm_max, bounds=node.Sm_max.bounds::Tuple)
node.B = Param(B, bounds=node.B.bounds::Tuple)
node.alpha = Param(alpha, bounds=node.alpha.bounds::Tuple)
node.Kf = Param(Kf, bounds=node.Kf.bounds::Tuple)
node.Ks = Param(Ks, bounds=node.Ks.bounds::Tuple)
param_pairs = zip([:Sm_max, :B, :alpha, :Kf, :Ks], [Sm_max, B, alpha, Kf, Ks])

# First item will always be the set value, so it can be skipped
for (p, v) in param_pairs
param = getfield(node, p)
setfield!(node, p, Param(v; (keys(param)[2:end] .=> values(param)[2:end])...))
end
end

function update_state!(
Expand Down
Loading
Loading