Difference between revisions of "REW"

From SourceWiki
Jump to navigation Jump to search
 
Line 28: Line 28:
 
* 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.
 
* 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:
+
* 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
 
     ./configure
Line 38: Line 38:
 
     cp src/nvec_ser/.libs/libsundials_nvecserial.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.
+
* 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:
+
* 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 \
 
     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
 
     -L. -lsundials_cvode -lsundials_nvecserial -I../include
  
 +
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 time at which output is shown on the screen while the model is running, and may cover many hydrological time steps. ''w'' is a vector of results at this timestep.
 +
 +
TODO: where is ''tout'' defined, and we may want to check the above is correct by altering ''tout''. This should only have an impact on what is shown on the screen, but not on the final model results
 +
 +
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 ===
 +
 +
todo
  
 
== Developers and applications ==
 
== Developers and applications ==

Revision as of 19:48, 2 February 2009


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:

  • 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
  • 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

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 time at which output is shown on the screen while the model is running, and may cover many hydrological time steps. w is a vector of results at this timestep.

TODO: where is tout defined, and we may want to check the above is correct by altering tout. This should only have an impact on what is shown on the screen, but not on the final model results

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

todo

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