From 8b56816cec163d50834324157e040d61f2f30976 Mon Sep 17 00:00:00 2001 From: Takuya Iwanaga Date: Sun, 15 Dec 2024 23:10:52 +1100 Subject: [PATCH] Standardize docstrings More docstring changes --- examples/calibration/alt_calibration.jl | 2 +- src/Nodes/DamNode.jl | 75 ++++++++++++------- src/calibration.jl | 98 +++++++++++++++---------- 3 files changed, 110 insertions(+), 65 deletions(-) diff --git a/examples/calibration/alt_calibration.jl b/examples/calibration/alt_calibration.jl index d8247c0..930f439 100644 --- a/examples/calibration/alt_calibration.jl +++ b/examples/calibration/alt_calibration.jl @@ -38,7 +38,7 @@ function calibrate(sn, v_id, climate, calib_data) TraceInterval=30.0, PopulationSize=75, ) - + res = bboptimize(opt) bs = best_candidate(res) diff --git a/src/Nodes/DamNode.jl b/src/Nodes/DamNode.jl index c70a3e4..8711b3e 100644 --- a/src/Nodes/DamNode.jl +++ b/src/Nodes/DamNode.jl @@ -210,21 +210,25 @@ end """ - run_node!(node::DamNode, climate::Climate, timestep::Int; - inflow=nothing, extraction=nothing, exchange=nothing) + run_node!( + node::DamNode, climate::Climate, timestep::Int; + inflow=nothing, extraction=nothing, exchange=nothing + )::Nothing Run a specific node for a specified time step. # Arguments -- `node::DamNode` : -- `climate::Climate` : -- `timestep::Int` : current time step -- `inflow::DataFrame` : Time series of inflows from any upstream node. -- `extraction::DataFrame` : Time series of water orders (expects column of `_releases`) -- `exchange::DataFrame` : Time series of groundwater flux +- `node` : DamNode +- `climate` : Climate dataset +- `timestep` : Current time step +- `inflow` : Time series of inflows from any upstream node. +- `extraction` : Time series of water orders (expects column of `_releases`) +- `exchange` : Time series of groundwater flux """ -function run_node!(node::DamNode, climate::Climate, timestep::Int; - inflow=nothing, extraction=nothing, exchange=nothing)::Nothing +function run_node!( + node::DamNode, climate::Climate, timestep::Int; + inflow=nothing, extraction=nothing, exchange=nothing +)::Nothing ts = timestep # if checkbounds(Bool, node.outflow, ts) # if node.outflow[ts] != undef @@ -247,27 +251,40 @@ end """ + run_node!( + node::DamNode, + ts::Int64, + rain::Float64, + et::Float64, + volume::Float64, + inflow::Float64, + extractions::Float64, + gw_flux::Float64 + ) + Calculate outflow for the dam node for a single time step. -# Parameters -- node : DamNode -- rain : rainfall in mm -- et : evapotranspiration data in mm -- irrig_ext : irrigation extractions -- extractions : extraction data in ML -- gw_flux : groundwater interaction +# Arguments +- `node` : DamNode +- `rain` : rainfall in mm +- `et` : evapotranspiration data in mm +- `irrig_ext` : irrigation extractions +- `extractions` : extraction data in ML +- `gw_flux` : groundwater interaction # Returns -- outflow from dam +Outflow from dam """ -function run_node!(node::DamNode, - ts::Int64, - rain::Float64, - et::Float64, - volume::Float64, - inflow::Float64, - extractions::Float64, - gw_flux::Float64) +function run_node!( + node::DamNode, + ts::Int64, + rain::Float64, + et::Float64, + volume::Float64, + inflow::Float64, + extractions::Float64, + gw_flux::Float64 +) dam_area = node.calc_dam_area(volume) discharge = node.calc_dam_discharge(volume, node.max_storage) @@ -297,6 +314,12 @@ end """ update_params!(node::DamNode, storage_coef::Float64)::Nothing + +Method to update `DamNode` specific parameters. + +# Arguments +- `node` : DamNode +- `storage_coef` : Storage coefficient value """ function update_params!(node::DamNode, storage_coef::Float64)::Nothing node.storage_coef = Param(storage_coef, bounds=node.storage_coef.bounds) diff --git a/src/calibration.jl b/src/calibration.jl index 85cc599..9efeb66 100644 --- a/src/calibration.jl +++ b/src/calibration.jl @@ -39,7 +39,6 @@ Objective function which considers performance of next node and current node. The weighting factor places equal emphasis on both nodes by default (0.5). The weighting value places a \$x\$ weight on the current node, and \$1 - x\$ on the next node. - """ function dependent_obj_func( params, climate::Climate, this_node::NetworkNode, next_node::NetworkNode, calib_data::DataFrame; @@ -106,9 +105,10 @@ end """ - calibrate!(sn, v_id, climate, calib_data, - metric::Function=Streamfall.RMSE; - kwargs...) + calibrate!( + sn::StreamfallNetwork, v_id::Int64, climate::Climate, calib_data::DataFrame; + metric::Function=Streamfall.RMSE, kwargs... + ) Calibrate a given node, recursing upstream, using the BlackBoxOptim package. @@ -116,33 +116,39 @@ Calibrate a given node, recursing upstream, using the BlackBoxOptim package. - `sn::StreamfallNetwork` : Network - `v_id::Int` : node identifier - `climate::Climate` : Climate data -- `calib_data::Array` : calibration data for target node by its id +- `calib_data::Array` : Calibration data for target node by its name. - `metric::Function` : Optimization function to use. Defaults to RMSE. +- `kwargs` : Additional arguments to use. """ -function calibrate!(sn::StreamfallNetwork, v_id::Int64, climate::Climate, calib_data::DataFrame; - metric::Function=Streamfall.RMSE, - kwargs...) +function calibrate!( + sn::StreamfallNetwork, v_id::Int64, climate::Climate, calib_data::DataFrame; + metric::Function=Streamfall.RMSE, kwargs... +) calibrate!(sn, v_id, climate, calib_data; metric=metric, kwargs...) end """ - calibrate!(sn, v_id, climate, calib_data, - metric::Function=Streamfall.RMSE; - kwargs...) + calibrate!( + sn::StreamfallNetwork, v_id::Int64, climate::Climate, calib_data::DataFrame; + metric::Function=Streamfall.RMSE, kwargs... + ) Calibrate a given node, recursing upstream, using the BlackBoxOptim package. # Arguments -- `sn::StreamfallNetwork` : Network -- `v_id::Int` : node identifier -- `climate::Climate` : Climate data -- `calib_data::DataFrame` : calibration data for target node by its id -- `metric::Function` : Optimization function to use. Defaults to RMSE. +- `sn` : Streamfall Network +- `v_id` : node identifier +- `climate` : Climate data +- `calib_data` : Calibration data for target node by its name. +- `metric` : Optimization function to use. Defaults to RMSE. +- `kwargs` : Additional calibration arguments. + BlackBoxOptim arguments will be passed through. """ -function calibrate!(sn::StreamfallNetwork, v_id::Int64, climate::Climate, calib_data::DataFrame; - metric::Function=Streamfall.RMSE, - kwargs...) +function calibrate!( + sn::StreamfallNetwork, v_id::Int64, climate::Climate, calib_data::DataFrame; + metric::Function=Streamfall.RMSE, kwargs... +) # Set defaults as necessary defaults = (; MaxTime=900, @@ -161,7 +167,15 @@ function calibrate!(sn::StreamfallNetwork, v_id::Int64, climate::Climate, calib_ end this_node = sn[v_id] - next_node = sn[first(outlets(sn, this_node.name))] + next_node = try + sn[first(outlets(sn, this_node.name))] + catch err + if !(err isa BoundsError) + throw(err) + end + + nothing + end extraction = get(kwargs, :extraction, nothing) exchange = get(kwargs, :exchange, nothing) @@ -207,9 +221,11 @@ end # TODO : Clean the next two methods up as they are rough duplicates. """ - calibrate!(node, climate::Climate, calib_data::Array; - metric::Function=Streamfall.RMSE, - kwargs...) + calibrate!( + node::NetworkNode, climate::Climate, calib_data::Array; + metric::Function=Streamfall.RMSE, + kwargs... + ) Calibrate a given node using the BlackBoxOptim package. @@ -220,9 +236,11 @@ Calibrate a given node using the BlackBoxOptim package. - `extractor::Function` : Calibration extraction method, define a custom one to change behavior - `metric::Function` : Optimization function to use. Defaults to RMSE. """ -function calibrate!(node::NetworkNode, climate::Climate, calib_data::Array; - metric::Function=Streamfall.RMSE, - kwargs...) +function calibrate!( + node::NetworkNode, climate::Climate, calib_data::Array; + metric::Function=Streamfall.RMSE, + kwargs... +) # Set defaults as necessary defaults = (; MaxTime=900, @@ -268,9 +286,10 @@ end """ - calibrate!(node, climate::Climate, calib_data::DataFrame; - metric::Function=Streamfall.RMSE, - kwargs...) + calibrate!( + node::NetworkNode, climate::Climate, calib_data::DataFrame; + metric::Function=Streamfall.RMSE, kwargs... + ) Calibrate a given node using the BlackBoxOptim package. @@ -281,9 +300,10 @@ Calibrate a given node using the BlackBoxOptim package. - `extractor::Function` : Calibration extraction method, define a custom one to change behavior - `metric::Function` : Optimization function to use. Defaults to RMSE. """ -function calibrate!(node::NetworkNode, climate::Climate, calib_data::DataFrame; - metric::Function=Streamfall.RMSE, - kwargs...) +function calibrate!( + node::NetworkNode, climate::Climate, calib_data::DataFrame; + metric::Function=Streamfall.RMSE, kwargs... +) # Set defaults as necessary defaults = (; MaxTime=900, @@ -315,15 +335,17 @@ end """ - calibrate!(sn::StreamfallNetwork, climate::Climate, calib_data::DataFrame; - metric::Function=Streamfall.RMSE, - kwargs...) + calibrate!( + sn::StreamfallNetwork, climate::Climate, calib_data::DataFrame; + metric::Function=Streamfall.RMSE, kwargs... + ) Calibrate a stream network. """ -function calibrate!(sn::StreamfallNetwork, climate::Climate, calib_data::DataFrame; - metric::Function=Streamfall.RMSE, - kwargs...) +function calibrate!( + sn::StreamfallNetwork, climate::Climate, calib_data::DataFrame; + metric::Function=Streamfall.RMSE, kwargs... +) _, outlets = find_inlets_and_outlets(sn) calib_states = Dict() for out in outlets