REW

Introduction

This page collects information about the application of the Representative Elementary Watershed model.

Versions

THREW

C version maintained by Fuqiang Tian (University of Illinois)

CREW

FORTRAN version maintained by Haksu Lee

Installation

THREW

Macintosh / linux

An easy way to install on mac and linux is by creating first static libraries for the solver and then linking those in the application. The advantage of this is that you don't need to recompile the solver each time you make changes to the model, which is quicker. Compiling it this way involves the following steps:

• download the cvode solver from the cvode/sundials website At the time of writing that is cvode-2.5.0.tar.gz

• decompress cvode-2.5.0.tar.gz, and add the directory /include/threw/ from the threw model to cvode-2.5.0/include. Replace the file cvode-2.5.0/src/cvode/cvode.c with the one included in the THREW model.

• Compile the solver with the changes we just made. This can be done with the following commands from within the cvode-2.5.0 directory. Note: we do not need to install the library (make install) since we will just copy the static libraries for use in threw.

    ./configure
    make

NOTE: to build static libraries for inclusion in R on AMD86 you need to do: ./configure CFLAGS=-fPIC

• copy the static libraries, which reside in a hidden directory

    cp src/cvode/.libs/libsundials_cvode.a ./
    cp src/nvec_ser/.libs/libsundials_nvecserial.a ./

• then copy both files (libsundials_cvode.a and libsundials_nvecserial.a) into the src directory of the THREW model. You may now throw away the cvode-2.5.0/ folder since both files (which are static libraries) contain all the functionality we need.

• Now you should be able to compile the threw model with the following command:

    gcc -pipe threw_closure.c threw_error.c threw_f.c threw_init.c threw_io.c threw_utility.c threw2.c -o threw2 \
    -L. -lsundials_cvode -lsundials_nvecserial -I../include -lm

Why do we need to patch the solver? Only one thing changes: after each hydrological time step the function W2Flux() is executed. This is necessary to add external fluxes, such as rain. In its original form, the solver solves a differential equation from a certain initial state without further external intervention. In a hydrological model however, we may need to update the internal states after each timestep, for instance by adding rain, or taking away evapotranspiration. This is what W2Flux() does.

the solver

Get your head around the solver in threw takes a bit of time. Here is a little explanation of what actually happens.

The core of the solver is the following line in threw2.c:

    CVode(cvode_mem, tout, w, &t, CV_NORMAL)

This function solves the differential equations up to time tout. tout is the current time in seconds. w is a vector of results at each timestep.

QUESTION: Does the fact that tout is defined in seconds mean that the internal time step of the solver is seconds? Any way of making this more flexible?

QUESTION: why do we need to patch the solver? Can't we execute W2Flux() after each call to CVode()? Likely answer: no, because the frequency of the input data may be higher than the requested output.

All the data for running the model are stored in the structure cvode_mem. This is a very complex structure that is understood by the solver. It contains everything from model state variables, parameters, as well as the 'right hand side function'. It is this function that is solved by the solver. It is basically the entire hydrological model, represented as a set of differential equations. In the threw code, the function is constructed in threw_f.c. It contains all the closure relations, which, individually, are defined in threw_closure.c.

Structure of the RHS function

todo

Structure of cvode_mem

The structure of cvode_mem is internal to the solver and we do not really need to know this. cvode_mem is created with:

    cvode_mem = CVodeCreate(CV_BDF, CV_NEWTON)

and then initialised with:

    CVodeSetFdata(cvode_mem, MData)
    CVodeMalloc(cvode_mem, f, CData.T0, w, CV_SS, CData.RTOL, &CData.ATOL)

where:

• MData = pointer to model data structure
• cvode_mem is the structure to be initialised
• f is the right hand side function
• CData.T0: starting time (dimensions?)
• w: state vector
• CV_SS
• CData.RTOL = Relative Tolerance
• CData.ATOL = Absolute Tolerance

Developers and applications

afaik, the following institutes / persons use a version of the REW model

• University of Illinois at Urbana Champaign
• University of Bristol (Wouter Buytaert)
• T U Munchen