LWFBrook90.jl

Implementation of the LWF-BROOK90 hydrological model in Julia

User info:

Developer info: Git branch model

What is LWFBrook90.jl?

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

Further model description can be found in the documentation.

License

LWFBrook90.jl is licensed under GPL-3.0 (for details see the file LICENSE).

Acknowledgements

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*.

For Users: getting started

To get started with Julia: see the section Installation in the documentation.

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.

Example data set:

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

Limitations of LWFBrook90.jl

• 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 KKMEAN the 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 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 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.

For Developers:

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. There are many useful tutorials around. For a quick start you can check out:

• Getting Started with Julia (for Experienced Programmers), by C.Rackauckas, 35min: https://www.youtube.com/watch?v=-lJK92bEKow
• Noteworthy Differences from other Languages: https://docs.julialang.org/en/v1/manual/noteworthy-differences/

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.