Update documentation (#8)

* Update documentation

* Fix some typos

* Fix further typos

* Increment version number

Project.toml

@@ -1,7 +1,7 @@
 name = "LWFBrook90"
 uuid = "100deb6c-4418-4b77-ad5c-a1fadb580743"
 authors = ["Fabian Bernhard"]
-version = "0.1.2"
+version = "0.1.3"
 
 [deps]
 CSV = "336ed68f-0bac-5ca0-87d4-7b16caf5d00b"

README.md

@@ -16,7 +16,7 @@ Implementation of the LWF-BROOK90 hydrological model in Julia
 </p>
 
 ## What is LWFBrook90.jl?
-The model LWF-BROOK90 is a 1D Soil Vegetation Atmosphere Transport (SVAT) model, calculating the soil water balance in forest soil. Modelled processes include vertical soil water movement, soil and plant evapotranspiration and temporary storages in snowpack or interception layer.
+The model LWF-BROOK90 is a 1D Soil-Vegetation-Atmosphere Transfer (SVAT) model, calculating the soil water balance in forest soil. Modelled processes include vertical soil water movement, soil and plant evapotranspiration and temporary storages in snowpack or interception layer.
 LWFBrook90.jl is an implementation of the existing LWF-BROOK90 rewritten entirely in the Julia programming language.
 
 Processes and state variables of the model in LWF-BROOK90 are summarised visually in Figure 1 below.
@@ -41,7 +41,7 @@ Development of LWFBrook90.jl builds on the following works:
 
 Furthermore, Matthias Häni, Katrin Meusburger, Peter Waldner, Lorenz Walthert, Stephan Zimmermann of [WSL](http://www.wsl.ch) and its Long-term Forest Ecosystem Research (LWF) project gratefully acknowledged for providing example data files located in `example/BEA2016*`.
 
-LWFBrook90.jl is licensed under GPL-3.0 (see the file `LICENSE`).
+LWFBrook90.jl is licensed under GPL-3.0 (for details see the file `LICENSE`).
 
 
 
@@ -76,7 +76,7 @@ Tests are run to assert agreement with results from LWFBrook90R. Visualizations
 - Currently a part of LWFBrook90R activated when `Reset==1`, is not implemented in LWFBrook90.jl. (A test implementation of this is available in the branch `005-simplify-time-step-control`.)
 
 ### Improve agreement with LWFBrook90R
-Note that some features of LWFBrook90R are not implemented in the main version of LWFBrook90.jl. The time step adaptivity and `Reset==1` of LWFBrook90R would require code refactoring, which goes slightly against the intended use of the library for ODEs DiffEqeuations.jl. Because of this, implementation of these features is left aways from the main version. However, an attempt at their implementation resides currently in a feature branch `005`. Below are some of the results of that branch:
+Note that some features of LWFBrook90R are not implemented in the main version of LWFBrook90.jl. The time step adaptivity and `Reset==1` of LWFBrook90R would require code refactoring, which goes slightly against the intended use of the library for ODEs DifferentialEquations.jl. Because of this, implementation of these features is left away from the main version. However, an attempt at their implementation resides currently in a feature branch `005`. Below are some of the results generated with that branch:
 
 <p align="center"><img src="https://github.com/fabern/LWFBrook90.jl/blob/develop/docs/src/assets/git-hash-2-55ca42d-feature005/2021-02-24_19h10_R-vs-Julia_comparison_DailyRawValues.png?raw=true" width="400"><p>
 <p align="center">Figure 6: Comparing daily outputs of LWFBrook90R and experimental LWFBrook90.jl:feature-005 for example data set over a year<p>

docs/src/index.md

@@ -14,7 +14,7 @@ Depth = 2
 
 
 ## About LWFBrook90.jl
-LWFBrook90.jl implements a 1D soil vegetation atmosphere transport model.
+LWFBrook90.jl implements a 1D soil-vegetation-atmosphere transfer model.
 Intended use cases of this impelemntation are:
 - support of stable isotopes (δ¹⁸O and δ²H)
 - efficient model calibration for data analysis
@@ -28,7 +28,7 @@ For further details read through the section [User Guide](@ref) or refer to sect
 
 ## Citing LWFBrook90.jl
 When using LWFBrook90.jl please cite <!-- [TODO.et.al (2021)](TODO) -->
->TODO: generate citation: (Journal of Open Source Software? Zenodo? Journal of Open Research Software (DiffEq.jl)? Alternatives?)
+>TODO: generate citation: (Journal of Open Source Software? Zenodo? Journal of Open Research Software (DifferentialEquations.jl)? Alternatives?)
 
 
 
@@ -46,6 +46,4 @@ Federer, C. A. (2002). BROOK 90: A simulation model output for evaporation, soil
 
 Hammel, K., & Kennel, M. (2001). Charakterisierung und Analyse der Wasserverfügbarkeit und des Wasserhaushalts von Waldstandorten in Bayern mit dem Simulationsmodell BROOK90 (No. 185; *Forstliche Forschungsberichte München*, p. 135). Technische Uni München Wissenschaftszentrum Weihenstephan. ISBN 3-933506-16-6
 
-Hammel, K., & Kennel, M. (2001). Charakterisierung und Analyse der Wasserverfügbarkeit und des Wasserhaushalts von Waldstandorten in Bayern mit dem Simulationsmodell BROOK90 (No. 185; *Forstliche Forschungsberichte München*, p. 135). Technische Uni München Wissenschaftszentrum Weihenstephan. ISBN 3-933506-16-6
-
 Schmidt-Walter, P., Trotsiuk, V., Meusburger, K., Zacios, M., & Meesenburg, H. (2020). Advancing simulations of water fluxes, soil moisture and drought stress by using the LWF-Brook90 hydrological model in R. *Agricultural and Forest Meteorology*, 291, 108023. https://doi.org/10.1016/j.agrformet.2020.108023

docs/src/model.md

@@ -1,7 +1,7 @@
 # SVAT Model
 
 ## Description
-LWFBrook90.jl is a 1D Soil Vegetation Atmosphere Transport (SVAT) model, calculating the soil water balance in forest soil. Modelled processes include vertical soil water movement, soil and plant evapotranspiration and temporary storages in snowpack or interception layer.
+LWFBrook90.jl is a 1D Soil-Vegetation-Atmosphere Transfer (SVAT) model, calculating the soil water balance in forest soil. Modelled processes include vertical soil water movement, soil and plant evapotranspiration and temporary storages in snowpack or interception layer.
 
 Vertical soil water movement is modelled using the Richards equations and preferential flow.
 Mass loss through evaporation from temporary storages (snowpack or interception by vegetation) is included.
@@ -14,7 +14,6 @@ Processes and state variables in LWF-BROOK90 are summarised visually in Figure 1
 <p>
 ```
 
-
 ## Implementation
 The model is implemented based code from the R package LWFBrook90R and its Fortran source code as well as the original implementation of BROOK90 (v4.8) (www.ecoshift.net/brook/b90doc.html).
 

docs/src/user-guide.md

@@ -11,11 +11,6 @@ To install LWFBrook90.jl open a Julia REPL, enter the Pkg REPL by pressing `]` a
 ```
 (@v1.5) pkg> add LWFBrook90
 ```
-If the you want to use the develop version not in the package registry you can install directly from github using the command:
-```
-(@v1.5) pkg> add https://github.com/fabern/LWFBrook90.jl
-```
-
 Dependencies of LWFBrookJulia.jl should automatically be installed.
 
 ### Usage

src/func_DiffEq_definition_cb.jl

@@ -1,8 +1,11 @@
-""" define_LWFB90_cb()\n
-    Generates callback function cb needed for ODE() probelm in DiffEq.jl package.
-    LWFBrook90 updates states INTS, INTR, SNOW, CC, SNOWLQ not continuously but only
-    once per day. This operator splitting (daily vs continuous update of ODEs) is
-    implemented by using this callback function which is called once per day.
+"""
+    define_LWFB90_cb()
+
+Generate callback function cb needed for ODE() problem in DiffEq.jl package.
+
+LWFBrook90 updates states INTS, INTR, SNOW, CC, SNOWLQ not continuously but only
+once per day. This operator splitting (daily vs continuous update of ODEs) is
+implemented by using this callback function which is called once per day.
 """
 function define_LWFB90_cb()
     # A) Define updating function
@@ -271,18 +274,4 @@ function define_LWFB90_cb()
     cb_func = PeriodicCallback(LWFBrook90R_update_INTS_INTR_SNOW_CC_SNOWLQ!,  1.0;
                                initial_affect = true);
     return cb_func
-end
-
-""" define_LWFB90_ODE()\n
-    Generates an ODEProblem from DiffEq.jl.\n\n
-    # An ODE problem which consists of
-    #   - definition of right-hand-side (RHS) function f
-    #   - definition of callback function cb
-    #   - initial condition of states
-    #   - definition of simulation time span
-    #   - parameters\n
-    Seperate updating of different states (INTS, INTR, SNOW, CC, SNOWLQ are updated once per
-    day while GWAT and SWATI are updated continuously) is implemented by means of operator
-    splitting using a callback function for the daily updates and a ODE RHS (right hand
-    side) for the continuous update.
-"""
+end

src/func_DiffEq_definition_f.jl

@@ -1,5 +1,7 @@
-""" define_LWFB90_f()\n
-    Generates function f (right-hand-side of ODEs) needed for ODE() probelm in DiffEq.jl package.
+"""
+    define_LWFB90_f()
+
+Generate function f (right-hand-side of ODEs) needed for ODE() problem in DiffEq.jl package.
 """
 # function define_LWFB90_f()
     function f_LWFBrook90R(du,u,p,t)

src/func_DiffEq_definition_ode.jl

@@ -1,3 +1,20 @@
+"""
+    define_LWFB90_ODE()
+
+Generates an ODEProblem from DiffEq.jl
+
+An ODE problem which consists of
+  - definition of right-hand-side (RHS) function f
+  - definition of callback function cb
+  - initial condition of states
+  - definition of simulation time span
+  - parameters
+
+Seperate updating of different states (INTS, INTR, SNOW, CC, SNOWLQ are updated once per
+day while GWAT and SWATI are updated continuously) is implemented by means of operator
+splitting using a callback function for the daily updates and a ODE RHS (right hand
+side) for the continuous update.
+"""
 function define_LWFB90_ODE(u0, tspan, p)
 
     # Define callback functions

src/func_DiffEq_definition_p.jl

@@ -1,6 +1,21 @@
-""" define_diff_eq_parameters(NLAYER, IMODEL, constant_dt_solver, NOOUTF, Reset, compute_intermediate_quantities,
-    pfile_meteo, pfile_siteparam, pfile_param, pfile_soil, pfile_pdur)\n
-    Generates vector p needed for ODE() problem in DiffEq.jl package."""
+"""
+    define_diff_eq_parameters()
+
+Generate vector p needed for ODE() problem in DiffEq.jl package.
+
+# Arguments
+- `NLAYER::...`: TODO argument description.
+- `IMODEL::...`: TODO argument description.
+- `constant_dt_solver::...`: TODO argument description.
+- `NOOUTF::...`: TODO argument description.
+- `Reset::...`: TODO argument description.
+- `compute_intermediate_quantities::...`: TODO argument description.
+- `pfile_meteo::...`: TODO argument description.
+- `pfile_siteparam::...`: TODO argument description.
+- `pfile_param::...`: TODO argument description.
+- `pfile_soil::...`: TODO argument description.
+- `pfile_pdur::...`: TODO argument description.
+"""
 function define_LWFB90_p(NLAYER, IMODEL, constant_dt_solver, NOOUTF, Reset, compute_intermediate_quantities,
     pfile_meteo, pfile_siteparam, pfile_param, pfile_soil, pfile_pdur)
 

src/func_DiffEq_definition_u0.jl

@@ -1,5 +1,8 @@
-""" define_LWFB90_u0()\n
-    Generates vector u0 needed for ODE() problem in DiffEq.jl package."""
+"""
+    define_LWFB90_u0()
+
+Generate vector u0 needed for ODE() problem in DiffEq.jl package.
+"""
 function define_LWFB90_u0(u_GWAT_init,
                             u_INTS_init,
                             u_INTR_init,

src/func_MSB_functions.jl

@@ -1,6 +1,12 @@
 # TODO(bernhard): think about where to put function definition of MSBSETVARS(), MSBDAYNIGHT()
-"""MSBSETVARS() function that computes state dependent parameters for
-updating states INTS, INTR, SNOW, CC, SNOWLQ in callback function
+"""
+    MSBSETVARS()
+
+Compute state dependent parameters for updating states INTS, INTR, SNOW, CC, SNOWLQ in
+callback function.
+
+# Arguments
+- many
 """
 function MSBSETVARS(IDAY, #TODO(bernhard) just for debug... remove again!
                     # arguments

src/func_input_definition.jl

@@ -6,17 +6,18 @@ using DataFramesMeta#: @linq, transform, DataFramesMeta
 using Dates: DateTime, Millisecond, Second, Day, month, value, dayofyear
 
 """
-read_LWFBrook90R_inputData(folder::String, prefix::String)\n
-Intent: load different input files for LWFBrook90\n
+    read_LWFBrook90R_inputData(folder::String, prefix::String)
+
+Load different input files for LWFBrook90:
 - climveg
 - param
 - siteparam
 - pdur
 - soil_materials.csv
 - soil_nodes.csv
-\n\n
+
 These files were created with an R script `generate_LWFBrook90Julia_Input.R` that
-takes the same arguements as the R funciton LWFBrook90R::run_LWFB90() and generates
+takes the same arguements as the R funciton `LWFBrook90R::run_LWFB90()` and generates
 the corresponding Julia input functions.
 """
 function read_LWFBrook90R_inputData(folder::String, prefix::String)
@@ -117,31 +118,48 @@ end
 
 ######################
 # Define functions to handle DateTimes and convert into Days as Floats
-""" DateTime2RelativeDaysFloat(x,
-        reference_DateTime)\n Transforms DateTimes `x` to simulation time """
+"""
+    DateTime2RelativeDaysFloat(x,reference_DateTime)
+
+Transforms DateTimes `x` to simulation time
+"""
 function DateTime2RelativeDaysFloat(x::DateTime, reference::DateTime)
     ms2days = 1.0/(24.0*3600.0*1000.0) # to convert milliseconds to days
     ms2days*value(convert(Millisecond, x-reference))
 end
-""" RelativeDaysFloat2DateTime(t,
-        reference_DateTime)\n Transforms simulation time t to DateTimes `dt` """
+"""
+    RelativeDaysFloat2DateTime(t, reference_DateTime)
+
+Transforms simulation time `t` to DateTimes
+"""
 function RelativeDaysFloat2DateTime(t::Float64, reference::DateTime)
     # reference + Day(floor(t))
     t_sec = 60*60*24*t # t is in days, t_sec in seconds
     reference + Second(floor(t_sec))
 end
-""" p_DOY(t::Float64, reference::DateTime)\n Get DOY (Day Of Year) from simulation time"""
+"""
+    p_DOY(t::Float64, reference::DateTime)
+
+Get DOY (Day Of Year) from simulation time
+"""
 function p_DOY(t::Float64, reference::DateTime)
     dayofyear(reference + Day(floor(t)))
 end
-""" p_MONTHN(t::Float64, reference::DateTime)\n Get Month from simulation time"""
+"""
+    p_MONTHN(t::Float64, reference::DateTime)
+
+Get Month from simulation time
+"""
 function p_MONTHN(t::Float64, reference::DateTime)
     month(reference + Day(floor(t)))
 end
 
 # Subset input data and transform dates into floats relative to reference_date
-# """ subset_standardize(data::DataFrame, start::DateTime, stop::DateTime, reference::DateTime)\n
-# Returns DataFrame `data` that is subset between `start` and `stop` and colum `dates` transformed to simulation time."""
+# """
+#    subset_standardize(data::DataFrame, start::DateTime, stop::DateTime, reference::DateTime)
+#
+# Returns DataFrame `data` that is subset between `start` and `stop` and colum `dates` transformed to simulation time.
+# """
 # function subset_standardize(data::DataFrame, start::DateTime, stop::DateTime, reference::DateTime)
 #     @linq data |>
 #     # Subset