User Guide

Installation and usage

Installation

First, download and install Julia: https://julialang.org/downloads/. If you like you can also install julia-vscode.org to get a complete IDE. Both these steps are nicely summarized by https://techytok.com/julia-vscode/. ALternatively, you can also follow the official documentation of the VS Code Julia: https://www.julia-vscode.org/docs/dev/gettingstarted/#Installation-and-Configuration-1.

To install LWFBrook90.jl open a Julia REPL, enter the Pkg REPL by pressing ] and add the package:

(@v1.7) pkg> add LWFBrook90
(@v1.7) pkg> status

Dependencies of LWFBrook90.jl should automatically be installed. After that hit Ctrl-C to quit the Pkg REPL and return to the default Julia REPL. Now the installation can be tested with a single line using LWFBrook90; run_example().

Usage

Check out a step-by-step guide for a simulation in section Example Script 01

The steps in a typical simulation script are:

• load the package using LWFBrook90
• read input data model = loadSPAC()
  • optional arguments in loadSPAC() can be used to define model parameters (-> type ?loadSPAC to see documentation)
• pre-process model for simulation simulation = setup(model)
• compute simulation simulate!(simulation)
• post-process and plot simulation results

LWFBrook90.jl outputs quantities in daily resolution. Monthly or yearly quantities can be derived in the post processing. ~~For performance reasons, e.g. for Bayesian parameter estimation, computation of these additional quantities can also be deactivated during simulation, and they could be calculated in a post-processing step from the state vector.~~

Input data

Overview of input data

To run a simulation following input files are expected in a single folder

• soil_horizons.csv - containing the hydraulic parameters of the different soil horizons
• param.csv - containing scalar model parameters
• meteoveg.csv - containing daily values of meteorologic variables [and stand properties]
• meteoiso.csv - containing isotopic signatures of aggregate precipitation samples
• initial_conditions.csv - containing initial conditions of scalar state variables
• soil_discretization.csv - containing the initial conditions of the soil water status in the form of the soil matric potential (kPa) and the initial isotopic signatures (vector state variables); parameters of relative root density distributions defined for the soil domain; as well as the definition of the numerical discretization of the soil domain (nodes with upper and lower limits).
• meteo_storm_durations.csv - containing parameters of sub-daily storm/precipitation event patterns for each month

Of these only the CSV files for the parameters soil_horizons.csv and param.csv and the forcings meteoveg.csv, meteoiso.csv are absolutely needed. The remaing can be provided by the user as arguments to loadSPAC() in the Julia script:

• soil_discretizations.csv: not needed if Δz_thickness_m, root_distribution, and IC_soil provided.
• initial_conditions.csv: not needed if IC_scalar provided.
• meteo_storm_durations.csv: not needed if storm_durations_h provided.
• meteoveg.csv: columns with vegetation parameters are not needed if loadSPAC(canopy_evolution = ...) is provided.

The structure of the input CSV's is illustrated by the example input data sets isoBEA2010-18-* or DAV2020-bare-minimum or DAV2020-full located in the folder examples/, as well as below in this documentation. Please follow these examples closely when generating your own input files, including the exact column names and header lines containing the units.

For convenience, input CSV files can be generated from a script that sets up a simulation with the R package LWFBrook90R (v0.4.3). Instead of running the simulation with run_LWFB90(), the same arguments can be used to generate the input files for LWFBrook90.jl using the R function provided in the file generate_LWFBrook90jl_Input.R. Note that the input file meteoiso.csv needs to be generated separately and the files containing the initial conditions (initial_conditions.csv and soil_discretization.csv) also need to be extended manually with the isotope values (see structure of these input files below).

To load input data and prepare a simulation follow the instructions in section Example Script 01 or alternatively use the sample script main_with_isotopes.jl. NOTE: these will be replaced with Jupyter-notebooks generated with Literate.jl.

In case you're unfamiliar with Julia, there are various ways to run a script such as main.jl: One possibility is to open the Julia REPL and run the script using include(“main.jl”). Alternatively, the editor VS Code in combination with the Julia extension (julia-vscode.org), provides a complete IDE for programming in Julia.

Structure of input data

soil_horizons.csv: (when using Mualem-VanGenuchten parametrization of the soil retention curve):

meteoveg.csv: contains time dependent parameters (meterologic variables and vegetation parameters):

If meteoveg.csv does not contain columns for DENSEF, HEIGHT, LAI, SAI, the parametrization of these should be provided to the function loadSPAC().

meteoiso.csv: contains time dependent isotopic signatures of precipiation. (Note that the dates contain the end dates of the collection interval of cumulative isotope samples. The values are backward interpolated with piecewise constants. The first row containng the NA is assumed to be the start date of the first collection interval.):

meteo_storm_durations.csv:

initial_conditions.csv:

soil_discretization.csv contains the initial conditions of the soil water status, root density distributions, and the definition of the numerical discretization of the soil domain (nodes with upper and lower limits):

param.csv contains scalar model parameters:

Calibration data (calibration not yet implemented)

Roadmap to include calibration data intends include of:

• Throughfall amounts (for parametrisation of interception)
• Soil moisture (volumetric water content, θ)
• Soil matric potential (ψ)

as well as

• Isotopic composition of soil water (δ_soil)
• Isotopic composition of xylem water (δ_xylem)

Below the example structure of data sets for psi.csv contains the soil matric potential (ψ) of different sensor series or as site average:

theta.csv contains the soil moisture (volumetric water content, θ):

delta_soil.csv contains the isotopic signature of soil water:

delta_xylem.csv contains the isotopic signature of xylem water: