Isotope-enabled implementation of the LWF-BROOK90 hydrological model in Julia
User info:
Developer info:
The model LWF-BROOK90 is a 1D Soil-Vegetation-Atmosphere Transfer (SVAT) model, calculating the soil water balance in forest soil on the scale of forest stands. 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. LWFBrook90.jl is developed with the following objectives in mind:
- support for stable isotopes (δ¹⁸O and δ²H) by including transport equation
and fractionation processes - efficient parameter estimation (optimizing computational costs)
- model flexibility for alternative processes parametrizations
(possibly resulting in a flexible model framework)
Figure 1: Summary of processes and state variables used in LWFBrook90.jl
You can start by reading the documentation and to get started have a look at Example-01.
An example data set BEA2016* was generated using the R package LWFBrook90R and is located in the folder examples/. See outputs in the next section.
To run this example simulation simply call LWFBrook90.run_example(). Note, that the first time might take some time to load and compile the package. Another possibility is to follow the script main.jl, which sets up a simulation and shows some simple plotting commands. See documentation section Example.
Further documentation for LWFBrook90.jl is available here and for BROOK90 here.
To get started with Julia: see the section Installation in the documentation.
If you're new to scientific computing in Julia. There are many useful tutorials around. For a quick start you can check out:
- Getting Started With Julia, targeted at epidemiologists, by C.Arnold-Leps: https://juliaepibook.callumarnold.com/install-julia and https://juliaepibook.callumarnold.com/julia-basics
- Noteworthy Differences from other Languages: https://docs.julialang.org/en/v1/manual/noteworthy-differences/
- Getting Started with Julia (for Experienced Programmers), by C.Rackauckas, 35min: https://www.youtube.com/watch?v=-lJK92bEKow
Following plots illustrate results of the provided data set. The scalar state variables and depth-depenedent (vector) state variables can be plotted:
Figure 2: Example simulation: scalar results
Figure 3: Example simulation: vector results soil water
Tests are run to assert agreement with results from LWFBrook90R. Visualizations are reported below. Note that minor discrepancies are still present linked to the adaptive time stepping and intermediate updates of state variables.
Figure 4: Comparing daily outputs of LWFBrook90R and LWFBrook90.jl for example data set over a year
Figure 5: Comparing daily outputs of LWFBrook90R and LWFBrook90.jl for example data set over 2 months
- Preprocessing steps to define a convenient format of input data sets are not yet designed. Currently, LWFBrook90.jl makes use of an input data set that is best prepared using the preprocessing steps provded in the the R package LWFBrook90R.
- Newest developments of BROOK90 are not included. LWFBrook90R is based on LWF-BROOK90, which was itself forked from an older vresion of BROOK90 (v3.1F). Developments in BROOK90 up to v4.8 (such as
KKMEANthe intercell averages of hydraulic conductivity) are partially included, but not activated by default in LWFBrook90.jl. - Currently a part of LWFBrook90R activated when
Reset==1, is not implemented in LWFBrook90.jl. (A test implementation of this is available in the branch005-simplify-time-step-control.)
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.
LWFBrook90.jl is licensed under GPL-3.0 (for details see the file LICENSE).
Development of LWFBrook90.jl builds on the following works:
- BROOK90 (v4.8) by C. Anthony Federer, Licensed under CC0 1.0, http://www.ecoshift.net/brook/brook90.htm
- LWFBrook90R (v0.4.3) by Paul Schmidt-Walter, Volodymyr Trotsiuk, Klaus Hammel, Martin Kennel, Anthony Federer, Robert Nuske, Licensed under GPL-3.0, https://github.com/pschmidtwalter/LWFBrook90R
Note that LWFBrook90R itself uses LWF-BROOK90 by Hammel and Kennel, 2001 (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)
All literature references are reported in the section References in the documentation.
The Swiss National Science Foundation is acknowledged for funding the development of this package through the project "Give and take: How much water does soil retain for trees?" (project number 185093, https://p3.snf.ch/project-185093).
Matthias Häni, Katrin Meusburger, Peter Waldner, Lorenz Walthert, Stephan Zimmermann of WSL and its Long-term Forest Ecosystem Research (LWF) project are gratefully acknowledged for providing example data files located in examples/BEA2016*.
Any help in form of discussions, pull requests, example data sets, or otherwise is very welcome. Please don't hesitate to contact us.
For implementation details: see documentation section Implementation.
If you're new to scientific computing in Julia. For more in depth treatments of topics related to scientific computing and machine learning in Julia be sure to check out the course MIT 18.337J by C. Rackauckas at https://github.com/mitmath/18337. This course lists further introduction material under lecture 1.1.