Quick start

Installation

Wflow is a Julia package, that can be installed using Julia's built-in package manager, Pkg. The rest of this section provides more detailed instructions, such that new Julia users can also install Wflow. If you already know this, you can go ahead to the next section.

First download and install the current stable release of Julia. Please see platform specific instructions for further installation instructions and if you have trouble installing Julia.

If you are new to Julia, it may be a good idea to check out the Getting Started section of the Julia Manual. Links to other learning resources can be found at julialang.org/learning.

Start an interactive session (also known as a read-eval-print loop or "REPL") by double-clicking the Julia executable or running julia from the command line, in case you have chosen to add it to your path. The default prompt will appear, in which Julia code can be entered and run.

julia> 1 + 2
3

Enter the Pkg REPL by pressing ] from the Julia REPL. To get back to the Julia REPL, press backspace or ^C. Just like in the Julia REPL, you can type ? to get a help message, this will list the available commands. To get more information on a specific command type ? followed by the command.

pkg> ?

pkg> ?add

If you go back to the Julia REPL, note that the same works, and is a convenient way to consult documentation for specific functions or types, or other objects.

help?> cos

Now go back to the Pkg REPL and install Wflow using:

pkg> add Wflow

This can take a while, especially the first time, since compatible dependencies are also automatically looked up and installed from the Pkg General registry. It is also possible to install Wflow from the master branch as follows:

pkg> add https://github.com/Deltares/Wflow.jl

This command will track the master branch, and will update to the latest commit on that branch when you run update, or simply up, in the Pkg REPL. The use of add will install Wflow in you home directory under .julia/packages/Wflow. Note that packages installed under packages by add are supposed to never be altered in that location, for Pkg and it's automatic dependency handling to work well. If you want to make any changes to any of the files in the Wflow directory, you need to do a development install. This can be done using:

pkg> dev https://github.com/Deltares/Wflow.jl

This will clone the git repository, put it under your home directory in .julia/dev/Wflow, and add the Wflow package to your project environment. Note that to receive updates, you have to pull in the latest changes yourself using git pull.

Finally, go back the Julia REPL and try to load Wflow:

julia> using Wflow

The first time this will take longer as any package that is new or changed needs to be precompiled first, to allow faster loading on subsequent uses.

You have now successfully installed Julia and Wflow. Before ending this section, we still want to recommend a few tools that can make using and developing Julia code easier.

The first is Revise.jl. This package allows you to modify code and use the changes without restarting Julia. Install it with add Revise from the Pkg REPL. Then create a file called .julia/config/startup.jl, and put using Revise there. This will load Revise every time you start a Julia session.

There is a section on editors and IDEs for Julia on https://julialang.org/, scroll down to see it. We use and recommend Microsoft's free and open source Visual Studio Code. When combined with the Julia extension it provides a powerful and interactive development experience.

Usage

To run a simulation, first the required static and dynamic input data should be prepared in NetCDF files. Next, we use a TOML configuration file, to fully specify a model simulation. This includes the model type, the start- and endtime, the path to the forcing NetCDF files, as well as the mapping of parameters in the model to names in the NetCDF file. See the section Config and TOML for more details.

As an example, we will run the Moselle example SBM model, of which the configuration file can be seen here: sbm_simple.toml. First we share some code that will download the required files to your current working directory:

# urls to TOML and NetCDF of the Moselle example model
staticmaps = "https://github.com/visr/wflow-artifacts/releases/download/v0.2.1/staticmaps.nc"
forcing = "https://github.com/visr/wflow-artifacts/releases/download/v0.2.0/forcing-2000.nc"
toml_url = "https://raw.githubusercontent.com/Deltares/Wflow.jl/master/test/sbm_simple.toml"

# create a "data" directory in the current directory
datadir = joinpath(@__DIR__, "data")
mkpath(datadir)
toml_path = joinpath(@__DIR__, "sbm_simple.toml")

# download resources to current and data dirs
download(staticmaps, joinpath(datadir, "staticmaps-moselle.nc"))
download(forcing, joinpath(datadir, "forcing-moselle.nc"))
download(toml_url, toml_path)

Now that we have our files in place, running a simulation is as simple as calling this function:

Wflow.run — Function

run(tomlpath::String)
run(config::Config)
run(model::Model)
run()

Run an entire simulation starting either from a path to a TOML settings file, a prepared Config object, or an initialized Model object. This allows more flexibility if you want to for example modify a Config before initializing the Model.

The 0 argument version expects ARGS to contain a single entry, pointing to the TOML path. This makes it easier to start a run from the command line without having to escape quotes:

julia -e "using Wflow; Wflow.run()" "path/to/config.toml"

source

As you can see, there are three different methods for this function. We will first make use of the first one, where a path to a TOML file is passed as a String.

using Wflow
Wflow.run(toml_path)

This will parse the TOML file to create a Wflow.Config, use that to initialize a Wflow.Model, and finally run the Wflow.Model for the specified duration.

Wflow.Config — Type

Config(path::AbstractString)
Config(dict::AbstractDict)
Config(dict::Dict{String,Any}, path::Union{String,Nothing})

Struct that contains the parsed TOML configuration, as well as a reference to the TOML path, if it exists. It behaves largely like a distionary, but it overloads getproperty and setproperty to support syntax like config.model.reinit = false.

source

Wflow.Model — Type

Model{N,L,V,R,W}

Composite type that represents all different aspects of a Wflow Model, such as the network, parameters, clock, configuration and input and output.

source

If you want to try out several different settings, without having to modify the TOML file every time, you can create a Wflow.Config first, modify some settings, and then start the simulation:

using Dates
config = Wflow.Config(toml_path)
config.endtime = DateTime("2000-01-03T00:00:00")
Wflow.run(config)

For even more control, you can initialize the model object yourself, and modify it directly, or run a custom simulation loop. See the Wflow.run source for some inspiration.