4. Setup of the model

Contents

• Setup of the model

  • Setup python

    • Python

    • Virtual environment setup (optional)

      • What is virtual environment

      • How to install virtual environment

    • External libraries

  • Installing CWatM

    • C++ libraries

      • Pre-compiled C++ libraries

      • Compiling a version

      • Installing on Mac

    • Test the Python version

    • Run the Python version

      • Using Flags

  • Potential Errors

    • Error because you did not run with Python

    • Error because python is not added to the PATH

    • Error because the path has white spaces included

    • Error because the python libraries are installed incorrectly

    • Error because the settings file is not stored as utf-8 file

    • Error because the references are used wrong

    • Errors Errors Err Er E

  • NetCDF meta data

  • Test the data

  • Settings file

    • Components of the settings file

      • General flags

      • NetCDF meta data

      • Path of data, output

      • Defining the modeling area

      • Defining the time

      • Initial conditions

      • Reading information

    • Sections of information

    • Complete settings file

  • NetCDF meta data

    • Output Meta NetCDF information

    • Name and location of the NetCDF meta data file

  • Initialisation

    • Example of soil moisture

    • Cold start

      • Set up a cold start in the settingsfile

    • Storing initial variables

    • Warm start

      • Set up a cold start in the settingsfile

    • Initial conditions

  • Model Output

    • Time depending and non depending output maps

    • Or time series at specified points

    • Or time series as a catchment sum or average

    • Format of output in the settings file

    • Output variables

    • Daily, monthly - at the end or average

    • Most important output variables - a selection

    • Output variables - starting a list

Setup python

Python

CWatM requires having Python. Downloading Python and the required Python packages is covered in our YouTube tutorial.

Note

CWatM is tested for Python 3.7 - 3.12. We recommend using the most recent stable release .

Warning

a 64-bit version is necessary. This is generally the download default.

Martin Bednář from Brno University of Technology, Czech Republic wrote the following instruction to install Python and the virtual environment:

The following text describes instructions regarding the Windows 10 operating system (OS). However, there might be some differences in case of different OS. The first step is to install the Python language in your machine. You can find the latest version on the official Python Website. As of October 2024, the latest version of Python is 3.13.0. However, it is a relatively new release, thus not all packages might be up to date. So scroll a bit down and download the second latest version which should be 3.12.7.

Select the particular Python version and find a 64-bit version for Windows OS and click its name. Open the file and followrecommended instructions. Be careful during installation of the option to add Python into PATH environmental variable. Figure 2 shows what to look for during the installation. It is not the end of the world if you did not check this checkbox and it is possible to add Python into PATH variable later. However, try to do it now as it will make your life way simpler during using python. After successful installation open the Command Prompt (use i.e. WIN + R shortcut to open Run window and write cmd and hit ENTER.). If you write python -V and hit ENTER. It should return the Python version number you just installed.

Virtual environment setup (optional)

What is virtual environment

The virtual environment enables you to run a clean “separate copy” of Python. Then you are able to install packages into this copied python which do not collide which then “main” Python installed. For example, you install Python on your machine and then install a package named thebestpackage. Lets say it is a new package, thus its version would be 1.0.0. Then you write a code using this package’s functions. After some time you will need to update this package because for example in the version 1.2.0 the creator added a new feature you would like to use. So you update the package. However, the new version changed howsome existing function operated and nowyour former code does notwork properly. However, if you installed the first version of package in the virtual environment the package would remain at version 1.0.0 even if you update the package on the main Python because the virtual environment created a separate copy od Python. Therefore, the virtual environment is very usefull in controling the versions of packages used for your particular peace of code and if you will need and updated version for different code (on main Python version or in different virtual environments) it will remain functional. Nevertheless, the virtual environment is not necessary and is totally optional so if you are not interested you can simply skip this.

How to install virtual environment

There are many ways to setup an virtual environment. Two ways of setup the virtual environment will be described (The second one was presented in the CwatM Level A1 Summer School). The first one is using the venv package that is built-in the Python since version 3.3. The usage of this package is following:

1. Create a folder for your project.

2. Open the Command Prompt inside this folder.

3. Use command: python -m venv .venv

Nowyou have create a virtual environment that is named “.venv” inside your folder. So, how does that command works? Firstly you tell it to use Python (python) then the flag -m tells python to execute a module as script and the module would be venv which follows. The last part is simply the name of your virtual environment. The name of virtual environment can be whatever you like, e. g. “my_project” or you can use a path to any folder you like if you do not want to create a virtual environment in the destination you are currently in. To activate the virtual environment using the venv package you need to open a Command Prompt inside your project folder (where the virtual environment was created) and use following command (“.venv” is the name of your virtual environment):

.venv/Scripts/Activate.bat

This will start the virtual environment and you will see its name in brackets before the next command line (Figure 5). After you activate the virtual environment all the packages you install will be installed specificaly in this activated environment and will not be affected by any changes in the main Python environment. To deactivate the virtual environment simply put in Commant Prompt the deactivate command.

External libraries

These six Python packages are needed:

1. NumPy

2. SciPy

3. netCDF4

4. pandas

5. xmipy

6. openpyxl

These six libraries can be installed with pip, conda

7. GDAL

Note

Troublemaker GDAL

Installing GDAL via pip can be troublesome. We recommend downloading the library from

Christoph Gohkles github page - geospatial-wheels

as GDAL-3.9.2-cp312-cp312m-win_amd64.whl (depending on your Python version)

(You have to click on show all 156 assets, to see GDAL, for older versions e.g. GDAL-3.8.4-cp311-cp311-win_amd64.whl use earlier releases e.g. v2024.2.18)

and installing as:

pip install C:/Users/XXXXX/Downloads/GDAL-3.9.2-cp312-cp312m-win_amd64.whl

Sometimes problems occur if you have installed GDAL separately (or a software did, like QGIS)

We tested GDAL and Numpy on ~40 computers and we could not figure out a version combination (ython, numpy, gdal) which works all the time

- on some computers: Python 3.12, Numpy 2.1 and GDAL 3.9

- on others only pip install numpy==1.26, GDAL 3.8

Note

Numpy version 2.1, 2.2

the branch: develop version work now with Numpy 2.1,2.2. BUT it seems Numpy and GDAL are not good friends.

On some computer we could no work with numpy 2.x

and we had to downscale to: pip install numpy==1.26

These additional packages are used for the post-processing Notebooks (in CWatM/Toolkit)

• Jupyter Notebook

• plotly

• XlsxWriter

These additional package are used for CWatM-MODFLOW

• FloPy

Installing CWatM

CWatM can be cloned through our CWatM GitHub repository.

For those new to GitHub, we recommend using GitHub desktop.

Getting CWatM with GitHub desktop is covered in our YouTube tutorial.

Input data to run CWatM at 30 arcminutes (~50 km x 50km) are available through our CWatM-Earth-30min GitHub repository.

C++ libraries

For the computational time demanding parts e.g. routing, CWatM comes with a C++ library. A pre-compiled version is included for Windows and Linux. Normally, you don’t have to do anything and the pre-compiled version should just work.

Pre-compiled C++ libraries

Windows and CYGWIN_NT-6.1

a compiled version is provided and CWatM is detecting automatically which system is running and which compiled version is needed

Linux

For Cygwin linux a compiled version t5cyg.so is provided in ../cwatm/hydrological_modules/routing_reservoirs/ for version CYGWIN_NT-6.1.

If you use another cygwin version please compile it by yourself and name it t5_linux.so

For Linux Ubuntu a compiled version is provided as t5_linux.so. The file is in ../cwatm/hydrological_modules/routing_reservoirs/

Note

If you use another Linux version or the compiled version is not working or you have a compiler which produce faster executables please compile a version on your own.

Mac

For the new Mac M4 processor we compiled a version t5_mac.so. The old Mac should run with t5_linux.so (we are not using Mac by ourself, therefore no guaranty!)

Compiling a version

C++ sourcecode is in ../cwatm/hydrological_modules/routing_reservoirs/t5.cpp

Note

A compiled version is already provided for Windows and Linux and Apple.

Windows

A compiled version is provided, but maybe you have a faster compiler than the “Minimalist GNU for Windows” or “Microsoft Visual Studio 14.0” we used.

To compile with g++:

..\g++ -c -fPIC -Ofast t5.cpp -o t5.o
..\g++ -shared -Ofast -Wl,-soname,t5.so -o t5.so  t5.o

To compile with Microsoft Visual Studio 14.0:

call "C:\Program Files (x86)\Microsoft Visual Studio 14.0\VC\bin\amd64/vcvars64.bat"
cl /LD /O2 t5.cpp

Note

We used Visual Studio, because it seems to be computational faster

the libray used with Windows is named t5.dll, if you generate a libray t5.so the filename in ../cwatm/management_modules/globals.py has to be changed!

Linux

To compile with g++:

..\g++ -c -fPIC -Ofast t5.cpp -o t5_linux.o
..\g++ -shared -Ofast -Wl,-soname,t5_linux.so -o t5_linux.so  t5_linux.o

    or

    ..\g++ -c -Ofast t5.cpp -o t5_linux.o
..\g++ -shared -Ofast -Wl,-soname,t5_linux.so -o t5_linux.so  t5_linux.o

Warning

Please rename your compiled version to t5_linux.so! At the moment the file t5_linux.so is compiled with Ubuntu Linux

Installing on Mac

We do not run Mac by ourself, therefore this information is from Vlad Amihaesei:

Install Miniconda to run the CWATM model on a Macbook. After that, open a terminal and type conda create—n “cwatm” python=3.12.7 (you have to specify which version of Python you need to use—it took me a while to notice that). Then, type conda activate cwatm.

Install the required libraries:

conda install numpy
conda install netcdf4
conda install scipy
conda install pandas
conda install gdal==3.9.2
conda install openpyxl
conda install xmimpy

Go to the folder of the model, open it in the terminal, then type: conda activate cwatm

Type: python run_cwatm.py

You might have the error of security showing that the t5_mac.so file is not trusted. The location of that file is: …hydrological_modules/routing_reservoirs/t5_mac_so

You have to go to the System Settings on the Mac:

System Settings -> Privacy & Security -> scroll down until you see Allow applications and choose Allow the t5_mac_so

Test the Python version

From a terminal inside the CWatM folder, Run from the command line:

python run_cwatm.py

The output should be:

Running under platform:  Windows  **(or Linux etc)**
CWatM - Community Water Model
Authors: ...
Version: ...
Date: ...

Warning

If python is not set in the environment path, the full path of python has to be used

Warning

We are using run_cwatm.py inside the main repository (CWatM\run_cwatm.py), not one folder deeper (CWatM\cwatm\run_cwatm.py).

Run the Python version

Run from the command line:

python run_cwatm.py settingsfile flags

example (from inside the CWatM folder):

python run_cwatm.py settings.ini

or with more information and an overview of computational runtime:

python run_cwatm.py settings.ini -l -t

Warning

If python is not set in the environment path, the full path of python has to be used

Warning

The model needs a settings file as an argument. See: Settings file

Note

it is also possible to use paths with white spaces or dots. An easy way to avoid this is using relative paths, but is is also possible with absolute paths.

"C:/Python 37/python" "C:/CWatM Hydrologic.modeling/CWatM/run_cwatm.py" "C:/CWatM Hydrologic.modeling/settings .rhine30min.ini" -l

But in the settingsfile do not use apostrophe "" or '':
PathRoot = C:/CWatM Hydrologic.modeling

Using Flags

Flags can be used to change the runtime output on the screen

example:

-q --quiet       output progression given as .
-v --veryquiet   no output progression is given
-l --loud        output progression given as time step, date and discharge
-c --check       input maps and stack maps are checked, output for each input map BUT no model run
-h --noheader    .tss file have no header and start immediately with the time series
-t --printtime   the computation time for hydrological modules are printed
    -w --warranty    copyright and warranty information

Potential Errors

We try to make our program behave properly when encountering unexpected conditions. Therefore we caption a number of possible wrong inputs.

If you get an output with an error number please look at Error handling

Error because you did not run with Python

if the model is causing an error with look like this:

File "run_cwatm.py", line 116
print("%-6s %10s %11s\n" %("Step","Date","Discharge"), end=' ')
SyntaxError: invalid syntax

You run the model without the python command in front. Please use: python cwatm.py (You may have to adjust the path to your python version and to cwatm.py).

Error because python is not added to the PATH

If executing python return an error like this

‘python’ is not recognized as an internal or external command

You need either need to add Python to the PATH Environmental Variable or you need to start Python with full path.

c:/path_to_python/python

Error because the path has white spaces included

It is also possible to use paths with white spaces or dots. An easy way to avoid this is using relative paths, but is is also possible with absolute paths:

"C:/Python 37/python" "C:/CWatM Hydrologic.modeling/CWatM/run_cwatm.py" "C:/CWatM Hydrologic.modeling/settings .rhine30min.ini" -l

But in the settingsfile do not use apostrophe:
PathRoot = C:/CWatM Hydrologic.modeling

Error because the python libraries are installed incorrectly

If the model is causing an error at this stage, please check the python libraries:

python
import numpy
import scipy.ndimage
import gdal
import netCDF4

Error because the settings file is not stored as utf-8 file

If the model causing an error which look like this:

UnicodeDecodeError: 'utf-8' codec can't decode byte 0x83 in position 1504: invalid start byte

It is because the file was not stored as utf-8 (Unicode Transformation Format - 8-bit) file. This can happen if you use the Windows texteditor Wordpad or Notepad. We suggest you use Notepad++ and store the file as utf-8. Might happen too, if your language use strange characters like German Umlaut.

Error because the references are used wrong

In the settingsfile we use references:

[FILE_PATHS]
PathRoot = C:\basin
PathMaps = $(PathRoot)/input

If you use the reference in the next section, you have to put in the section where you defined the reference. Here: FILE_PATHS:

[NETCDF_ATTRIBUTES]
metaNetcdfFile = $(FILE_PATHS:PathRoot)/metaNetcdf.xml

Errors Errors Err Er E

If you type:

python cwatm.py settings.ini -l

You should see something like this:

E:\CWatM_rhine\source>python cwatm.py settings_rhine30min.ini -l
CWatM - Community Water Model  Version: 0.991  Date:  16/09/2017
International Institute of Applied Systems Analysis (IIASA)
Running under platform:  Windows
-----------------------------------------------------------
CWatM Simulation Information and Setting
The simulation output as specified in the settings file: settings_rhine30min.ini
can be found in E:/CWatM_rhine/output
Step         Date   Discharge
1      01/01/1961        4.20
2      02/01/1961        4.23
...

If you don’t see this. Something went wrong and you might see this instead:

E:\CWatM_rhine\source>python cwatm.py settings_rhine30min.ini -l
CWatM - Community Water Model  Version: 0.991  Date:  16/09/2017
International Institute of Applied Systems Analysis (IIASA)
Running under platform:  Windows
-----------------------------------------------------------
ERROR 4: `E:/CWatM_rhine/cwatm_input/routing/ldd.map' does not exist in the file system,
and is not recognised as a supported dataset name.
management_modules.messages.CWatMFileError:
======================== CWatM FILE ERROR ===========================
In  "Ldd"
searching: "E:/CWatM_rhine/cwatm_input/routing/ldd.map"
path: E:/CWatM_rhine/cwatm_input/routing does not exists

The model tries to help you on finding the error.

In this case it is looking for the river network map ldd.map or ldd.nc or ldd.tif

but it cannot find the file and not even the path to the file.

Here you might change:

[FILE_PATHS]
PathRoot = E:/CWatM_rhine
PathMaps = $(PathRoot)/cwatm_input

or:

[TOPOP]
# local drain direction map (1-9)
Ldd = $(FILE_PATHS:PathMaps)/routing/ldd.map

But many other error can occure too! Have fun.

P.s. some error we captured and we give a hint. Please look at Error handling

NetCDF meta data

The format for spatial data for output data is netCDF. In the meta data file information can be added e.g. a description of the parameter

Note

It is not necessary to change this file! This is an option to put additional information into output maps

Test the data

The model is only as good as the data!

To give out a list of data and to check the data the model can run a check.

example:

python run_cwatm settings1.ini -c
or
python run_cwatm settings1.ini -c > checkdata.txt

A list is created with:

Name:      Name of the variable
Filename:  filename or if the value if it is a fixed value
nonMV:     non missing value in 2D map
MV:        missing value in 2D map
lon-lat:   longitude x latitude of 2D map
CompressV: 2D is compressed to 1D?
MV-comp:   missing value in 1D
Zero-comp: Number of 0 in 1D
NonZero:   Number of non 0 in 1D
min:       minimum in 1D (or 2D)
mean:      mean in 1D (or 2D)
max:       maximum in 1D (or 2D)

example:

Name                          File/Value                                    nonMV         MV    lon-lat   Compress    MV-comp  Zero-comp    NonZero        min       mean        max
MaskMap                       put5min_netcdf/areamaps/rhine5min.map          5236          0      68x77      False          0       2404       2832       0.00       0.54       1.00
Ldd                           _5min/input5min_netcdf/routing/ldd.nc          5236          0      68x77      False          0          0       5236       1.00       5.34       9.00
Mask+Ldd                                                                     2832          0      68x77       True          0       2832          0       0.00       0.00       0.00
CellArea                      n_netcdf/landsurface/topo/cellarea.nc          2832          0      68x77       True          0          0       2832   5.31E+07   5.63E+07   5.94E+07
precipitation_coversion       86.4                                              -          -          -          -          -                 86.40
evaporation_coversion         1.00                                              -          -          -          -          -                  1.00
crop_correct                  1.534                                             -          -          -          -          -                  1.53
NumberSnowLayers              7                                                 -          -          -          -          -                  7.00
GlacierTransportZone          3                                                 -          -          -          -          -                  3.00
ElevationStD                  min_netcdf/landsurface/topo/elvstd.nc          2832          0      68x77       True          0          0       2832       0.04      78.67     672.68
...
...

Settings file

The settings file is controlling the CWatM run

######## ##          ##  ####  ######  ##    ##
##       ##          ## ##  ##   ##   ####  ####
##        ##        ##  ##  ##   ##   ## #### ##
##        ##   ##   ## ########  ##  ##   ##   ##
##         ## #### ##  ##    ##  ##  ##        ##
##         ####  #### ##      ## ## ##          ##
##########  ##    ##  ##      ## ## ##          ##

# Community Water Model Version 0.99

Components of the settings file

General flags

General flags are set in the first paragraph For example: If Temperature data are in unit ° Celsius ot Kelvin

[OPTIONS]
#-------------------------------------------------------
# OPTION - to switch on/off
#-------------------------------------------------------

# Data otions
# if temperature is stored in Kelvin instead Celsius
TemperatureInKelvin = True
# if lat/lon the area has to be user defined = precalculated
gridSizeUserDefined = True

#-----------------------------------------------
# Evaporation: calculate pot. evaporation (True) or use precalculated pot.evaporation map stacks (False)
calc_evaporation = False

#-----------------------------------------------
# Irrigation and water demand

# if irrigation is included, otherwise paddy and non paddy is put into 'grassland'
includeIrrigation = True
# if water demand from irrigation, industry and domestic is included
includeWaterDemand = False
# Water allocation
# if water demand and availability is calculated for region to compare demand vs. avail
usingAllocSegments = False
# limit abstraction to available groundwater (True) include fossil groundwater (False)
limitAbstraction = False

# Environmental Flow
calc_environflow = False
use_environflow = False

#-----------------------------------------------
# Soil 
# use preferential flow, that bypasses the soil matrix and drains directly to the groundwater (not for irrPaddy)
preferentialFlow = False
# Capillar rise
CapillarRise = True

#-----------------------------------------------
# Routing

# if runoff concentration to the edge of a cell is included
includeRunoffConcentration = True
# Waterbodies like lakes and reservoirs
includeWaterBodies = True
# kinematic wave routing, if False no routing is calculated
includeRouting = True

#-----------------------------------------------
# Inflow from outside of the modelled area
inflow = False

# --- Reporting & Debugging ------------------- ----------------------------------------------
# Reporting options
writeNetcdfStack = True
reportMap = True
reportTss = True
# Checking water balance (for debugging)
calcWaterBalance = False
sumWaterBalance = False
# use additional PCRaster GIS commands
PCRaster = False






#-------------------------------------------------------
# DEFINITIONS OF PARAMETERS

NetCDF meta data

The format for spatial data for input and output data is netCDF. For output data the basic information are given in the settingsfile

[NETCDF_ATTRIBUTES]
institution = IIASA
title = Global Water Model - WATCH WDFEI
metaNetcdfFile = $(FILE_PATHS:PathRoot)/source/metaNetcdf.xml

For each output file the specific information about units, variable name, displayed variable name is given in the metaNetcdf.xml. See: Output Meta NetCDF information

Path of data, output

Note

Further on the pathes can be used as placeholders

#-------------------------------------------------------
[FILE_PATHS]
#-------------------------------------------------------
PathRoot = E:/CWATM_rhine

PathOut = $(PathRoot)/output
PathMaps = $(PathRoot)/cwatm_input
PathMeteo = $(PathRoot)/climate

Defining the modeling area

In general the input data are stored and used at global scale. The modeling area can be defined by:

• a mask map e.g.: $(FILE_PATHS:PathRoot)/source/rhine30min.tif

• coordinates e.g.: 14 12 0.5 5.0 52.0

• lowest point of a catchment e.g.: 6.25 51.75

Note

The mask map can be a .tif, PCraster or a netCDF format

The coordinates have the format: Number of Cols, Number of rows, cellsize, upper left corner X, upper left corner Y

The point location (lon lat) will be used to create the catchment upstream of this point

Warning

If you use a mask map, make sure you do not use blanks in the file path or name!

# AREA AND OUTLETS
#-------------------------------------------------------
[MASK_OUTLET]

# Area mask
# A pcraster map, tif or netcdf map e.g.  $(FILE_PATHS:PathRoot)/data/areamaps/area_indus.map
# or a retancle: Number of Cols, Number of rows, cellsize, upper left corner X, upper left corner Y 
MaskMap = $(FILE_PATHS:PathRoot)/source/rhine30min.tif
#MaskMap = 14 12 0.5 5.0 52.0


#-------------------------------------------------------
# Station data
# either a map e.g. $(FILE_PATHS:PathRoot)/data/areamaps/area3.map
# or a location coordinates (X,Y) e.g. 5.75 52.25 9.25 49.75 )
# Lobith/Rhine
Gauges = 6.25 51.75

# if .tif file for gauges, this is a flag if the file is global or local
# e.g. Gauges = $(FILE_PATHS:PathRoot)/data/areamaps/gaugesRhine.tif
GaugesLocal = True

Note

If you start with a basin defined by the outlet of a basin e.g. 6.25 51.75

You can generate a new mask map for the following runs by:

savebasinmap = True in [OPTIONS]

a basin.tif is generated in the output folder, which you can copy and use next time as:

MaskMap = your_directory/basin.tif

Defining the time

The start and end time have to be defined. Spin-up time is the time for warming up (results will be stored after the spin-up time)

Note

The time can be given as date: dd/mm/yyyy or as relative date: number (but then CalendarDayStart has to be defined)

Note

Spin-up time can be given as date or number

#-------------------------------------------------------
[TIME-RELATED_CONSTANTS]
#-------------------------------------------------------

# StepStart has to be a date e.g. 01/06/1990
# SpinUp or StepEnd either date or numbers 
# SpinUp: from this date output is generated (up to this day: warm up)

StepStart = 1/1/1990
SpinUp =  1/01/1995
StepEnd =  31/12/2010

Initial conditions

Initial conditions can be stored and be loaded in order to initialise a warm start of the model

Note

Initial conditions are store as one netCDF file with all necessary variables

#-------------------------------------------------------
[INITITIAL CONDITIONS]
#-------------------------------------------------------

# for a warm start initial variables a loaded
# e.g for a start on 01/01/2010 load variable from 31/12/2009
load_initial = False
initLoad = $(FILE_PATHS:PathRoot)/init/Rhine_19891231.nc

# saving variables from this run, to initiate a warm start next run
# StepInit = saving date, can be more than one: 10/01/1973 20/01/1973
save_initial = False
initSave = $(FILE_PATHS:PathRoot)/init/Rhine
StepInit = 31/12/1989 31/12/2010

StepInit indicate the date(s) when initial conditions are saved:

StepInit = 31/12/1989
StepInit = 31/12/1989 31/12/2010
StepInit = 31/12/1989 5y
here: second value in StepInit is indicating a repetition of year(y), month(m) or day(d),
e.g. 2y for every 2 years or 6m for every 6 month

Reading information

Information will be read in from values in the settings file Here the value definitions for [SNOW] is shown:

#-------------------------------------------------------
[SNOW]
#-------------------------------------------------------

# Number of vertical Snow layers
NumberSnowLayers = 7
# up to which layer the ice melt is calculated with the middle temperature
GlacierTransportZone = 3

# Temperature lapse rate with altitude [deg C / m]
TemperatureLapseRate = 0.0065 
# Multiplier applied to precipitation that falls as snow
SnowFactor = 1.0
# Range [m C-1 d-1] of the seasonal variation, SnowMeltCoef is the average value
SnowSeasonAdj = 0.001
# Average temperature at which snow melts
TempMelt =1.0
# Average temperature below which precipitation is snow
TempSnow = 1.0
# Snow melt coefficient: default: 4.0 
# SRM: 0.0045 m/C/day ( = 4.50 mm/C/day), Kwadijk: 18 mm/C/month (= 0.59 mm/C/day)  
# See also Martinec et al., 1998.

# use in CALIBRATION -> copied to CALIBRATION
#SnowMeltCoef = 0.004
IceMeltCoef  = 0.007

#--------------------------------------------------------------
# INITIAL CONDITIONS - Initial snow depth in snow zone 1-7 [mm]  - SnowCoverIni

[FROST]
# Snow water equivalent, (based on snow density of 450 kg/m3) (e.g. Tarboton and Luce, 1996)
SnowWaterEquivalent = 0.45
# Daily decay coefficient, (Handbook of Hydrology, p. 7.28)
Afrost = 0.97
# Snow depth reduction coefficient, [cm-1], (HH, p. 7.28)
Kfrost = 0.57
# Degree Days Frost Threshold (stops infiltration, percolation and capillary rise)
# Molnau and Bissel found a value 56-85 for NW USA.
FrostIndexThreshold = 56

Note

TemperatureLapseRate = 0.0065 | for the variable TemperatureLapseRate the value of 0.0065 is set

Variables can also be defined by spatial maps or map stacks

tanslope = $(PathTopo)\tanslope.map
forest_coverFractionNC   = $(PathForest)\coverFractionInputForest366days.nc

Note

suffix can be .map, but if there is no PCraster map it will look automatically for netCDF .nc

Warning

in most cases values can be replaced by map

Sections of information

• Snow

• Frost

• General information on land cover types

• Soil

• Information for each of the six land cover types

  • Forest

  • Grassland

  • Paddy irrigated area

  • Irrigated area

  • Sealed area

  • Water covered area

• Interflow

• Groundwater

• Water demand

• Runoff concentration

• Routing

• Lakes and reservoirs

• Inflow

Complete settings file

Example of a settings file:

# ------------------------------------------------

######## ##          ##  ####  ######  ##    ##
##       ##          ## ##  ##   ##   ####  ####
##        ##        ##  ##  ##   ##   ## #### ##
##        ##   ##   ## ########  ##  ##   ##   ##
##         ## #### ##  ##    ##  ##  ##        ##
##         ####  #### ##      ## ## ##          ##
##########  ##    ##  ##      ## ## ##          ##

# Community Water Model Version 0.99
# SETTINGS FILE
# ------------------------------------------------


[OPTIONS]
#-------------------------------------------------------
# OPTION - to switch on/off
#-------------------------------------------------------

# Data otions
# if temperature is stored in Kelvin instead Celsius
TemperatureInKelvin = True
# if lat/lon the area has to be user defined = precalculated
gridSizeUserDefined = True

#-----------------------------------------------
# Evaporation: calculate pot. evaporation (True) or use precalculated pot.evaporation map stacks (False)
calc_evaporation = False

#-----------------------------------------------
# Irrigation and water demand

# if irrigation is included, otherwise paddy and non paddy is put into 'grassland'
includeIrrigation = True
# if water demand from irrigation, industry and domestic is included
includeWaterDemand = False
# Water allocation
# if water demand and availability is calculated for region to compare demand vs. avail
usingAllocSegments = False
# limit abstraction to available groundwater (True) include fossil groundwater (False)
limitAbstraction = False

# Environmental Flow
calc_environflow = False
use_environflow = False

#-----------------------------------------------
# Soil 
# use preferential flow, that bypasses the soil matrix and drains directly to the groundwater (not for irrPaddy)
preferentialFlow = False
# Capillar rise
CapillarRise = True

#-----------------------------------------------
# Routing

# if runoff concentration to the edge of a cell is included
includeRunoffConcentration = True
# Waterbodies like lakes and reservoirs
includeWaterBodies = True
# kinematic wave routing, if False no routing is calculated
includeRouting = True

#-----------------------------------------------
# Inflow from outside of the modelled area
inflow = False

# --- Reporting & Debugging ------------------- ----------------------------------------------
# Reporting options
writeNetcdfStack = True
reportMap = True
reportTss = True
# Checking water balance (for debugging)
calcWaterBalance = False
sumWaterBalance = False
# use additional PCRaster GIS commands
PCRaster = False






#-------------------------------------------------------
# DEFINITIONS OF PARAMETERS
#-------------------------------------------------------

#-------------------------------------------------------
[FILE_PATHS]
#-------------------------------------------------------
PathRoot = E:/CWATM_rhine

PathOut = $(PathRoot)/output
PathMaps = $(PathRoot)/cwatm_input
PathMeteo = $(PathRoot)/climate




#-------------------------------------------------------
[NETCDF_ATTRIBUTES]
institution = IIASA
title = Global Water Model - WATCH WDFEI
metaNetcdfFile = $(FILE_PATHS:PathRoot)/source/metaNetcdf.xml

#-------------------------------------------------------
# AREA AND OUTLETS
#-------------------------------------------------------
[MASK_OUTLET]

# Area mask
# A pcraster map, tif or netcdf map e.g.  $(FILE_PATHS:PathRoot)/data/areamaps/area_indus.map
# or a retancle: Number of Cols, Number of rows, cellsize, upper left corner X, upper left corner Y 
MaskMap = $(FILE_PATHS:PathRoot)/source/rhine30min.tif
#MaskMap = 14 12 0.5 5.0 52.0


#-------------------------------------------------------
# Station data
# either a map e.g. $(FILE_PATHS:PathRoot)/data/areamaps/area3.map
# or a location coordinates (X,Y) e.g. 5.75 52.25 9.25 49.75 )
# Lobith/Rhine
Gauges = 6.25 51.75

# if .tif file for gauges, this is a flag if the file is global or local
# e.g. Gauges = $(FILE_PATHS:PathRoot)/data/areamaps/gaugesRhine.tif
GaugesLocal = True

#-------------------------------------------------------
[TIME-RELATED_CONSTANTS]
#-------------------------------------------------------

# StepStart has to be a date e.g. 01/06/1990
# SpinUp or StepEnd either date or numbers 
# SpinUp: from this date output is generated (up to this day: warm up)

StepStart = 1/1/1990
SpinUp =  1/01/1995
StepEnd =  31/12/2010




#-------------------------------------------------------
[INITITIAL CONDITIONS]
#-------------------------------------------------------

# for a warm start initial variables a loaded
# e.g for a start on 01/01/2010 load variable from 31/12/2009
load_initial = False
initLoad = $(FILE_PATHS:PathRoot)/init/Rhine_19891231.nc

# saving variables from this run, to initiate a warm start next run
# StepInit = saving date, can be more than one: 10/01/1973 20/01/1973
save_initial = False
initSave = $(FILE_PATHS:PathRoot)/init/Rhine
StepInit = 31/12/1989 31/12/2010

#-------------------------------------------------------
# CALIBARTION PARAMETERS
#-------------------------------------------------------
[CALIBRATION]

# These are parameter which are used for calibration
# could be any parameter, but for an easier overview, tehey are collected here
# in the calibration template a placeholder (e.g. %arnoBeta) instead of value

# Snow  
SnowMeltCoef = 0.0027
# Cropf factor correction  
crop_correct =  1.11
#Soil
soildepth_factor = 1.28
#Soil preferentialFlowConstant = 4.0, arnoBeta_add = 0.1
preferentialFlowConstant = 4.5
arnoBeta_add = 0.19
# interflow part of recharge factor = 1.0
factor_interflow = 2.8
# groundwater recessionCoeff_factor = 1.0
recessionCoeff_factor = 5.278
# runoff concentration factor runoffConc_factor = 1.0
runoffConc_factor = 0.1
#Routing manningsN Factor to Manning's roughness = 1.0 [0.1-10.]
manningsN = 1.86
# reservoir  normal storage limit (fraction of total storage, [-]) [0.15 - 0.85] default 0.5
normalStorageLimit = 0.44
# lake parameter - factor to alpha: parameter of of channel width and weir coefficient  [0.33 - 3.] dafault 1.
lakeAFactor = 0.33
# lake parameter - factor for wind evaporation
lakeEvaFactor = 1.52
#-------------------------------------------------------
# TOPOGRAPHY MAPS
#-------------------------------------------------------
[TOPOP]
# local drain direction map (1-9)
Ldd = $(FILE_PATHS:PathMaps)/routing/ldd.map

# Elevation standard deviation [m], i.e. altitude difference elevation within pixel.
# Used for sub-pixel modelling of snow accumulation and melt
ElevationStD = $(FILE_PATHS:PathMaps)/landsurface/topo/elvstd.map

# Area of pixel [m2] (for lat/lon every cell has a different area)
CellArea = $(FILE_PATHS:PathMaps)/routing/cellarea.map

#-------------------------------------------------------
# INPUT METEOROLOGICAL TIMESERIES AS MAPS
#-------------------------------------------------------
[METEO]
# precipitation [kg m-2 s-1]
#PrecipitationMaps = $(FILE_PATHS:PathMeteo)/pr*
PrecipitationMaps = $(FILE_PATHS:PathMeteo)/30min/pr_rhine*
# average daily temperature [K]
#TavgMaps = $(FILE_PATHS:PathMeteo)/tavg*
TavgMaps = $(FILE_PATHS:PathMeteo)/30min/tavg_rhine*

# ----------------------------------------
# This is used if calc_evaporation = False

# daily reference evaporation (free water) 
E0Maps = $(FILE_PATHS:PathMeteo)/30min/EWRef_rhine.nc
#E0Maps = $(FILE_PATHS:PathMeteo)/EWRef_daily*
# daily reference evapotranspiration (crop) 
ETMaps = $(FILE_PATHS:PathMeteo)/30min/ETRef_rhine.nc
#ETMaps = $(FILE_PATHS:PathMeteo)/ETRef_daily*

# --------------------------------
# from kg m-2s-1 to m : 86.4
precipitation_coversion = 86.4

# from MM to m : 0.001
#precipitation_coversion = 0.001

evaporation_coversion = 1.00

# OUTPUT maps and timeseries
#OUT_Dir = $(FILE_PATHS:PathOut)
#OUT_MAP_Daily = Precipitation, prec1

#-------------------------------------------------------
# CALCULATE EVAPORATION - PENMAN - MONTEITH
#-------------------------------------------------------
[EVAPORATION]

# This is used if calc_evaporation = True
# use albedo maps
albedo = True
albedoMaps = $(FILE_PATHS:PathMaps)/landsurface/albedo/albedo.nc 

# if not albedo maps use fixed albedo
# Albedo of bare soil surface (Supit et. al.)
AlbedoSoil = 0.15
# Albedo of water surface (Supit et. al.)
AlbedoWater = 0.05
# Albedo of vegetation canopy (FAO,1998)
AlbedoCanopy = 0.23

# use specific humidity (TRUE) QAir,  or relative humidity (FALSE) - rhs
useHuss = False

# map stacks Temperature [K}]
TminMaps = $(FILE_PATHS:PathMeteo)/tmin*
TmaxMaps = $(FILE_PATHS:PathMeteo)/tmax*
# Instantaneous surface pressure[Pa]
PSurfMaps = $(FILE_PATHS:PathMeteo)/ps*
# 2 m istantaneous specific humidity[kg /kg] (QAir) or relative humidity [%] (rhs)
RhsMaps = $(FILE_PATHS:PathMeteo)/hurs*
# wind speed maps at 10m [m/s]
WindMaps = $(FILE_PATHS:PathMeteo)/wind*
# radiation surface downwelling shortwave maps  [W/m2]
RSDSMaps = $(FILE_PATHS:PathMeteo)/rsds*
# radiation surface downwelling longwave maps [W/m2] [W/m2]
RSDLMaps = $(FILE_PATHS:PathMeteo)/rlds*

# OUTPUT maps and timeseries
#OUT_Dir = $(FILE_PATHS:PathOut)
#OUT_MAP_Daily = EWRef, ETRef, temp, prec

#-------------------------------------------------------
[SNOW]
#-------------------------------------------------------

# Number of vertical Snow layers
NumberSnowLayers = 7
# up to which layer the ice melt is calculated with the middle temperature
GlacierTransportZone = 3

# Temperature lapse rate with altitude [deg C / m]
TemperatureLapseRate = 0.0065 
# Multiplier applied to precipitation that falls as snow
SnowFactor = 1.0
# Range [m C-1 d-1] of the seasonal variation, SnowMeltCoef is the average value
SnowSeasonAdj = 0.001
# Average temperature at which snow melts
TempMelt =1.0
# Average temperature below which precipitation is snow
TempSnow = 1.0
# Snow melt coefficient: default: 4.0 
# SRM: 0.0045 m/C/day ( = 4.50 mm/C/day), Kwadijk: 18 mm/C/month (= 0.59 mm/C/day)  
# See also Martinec et al., 1998.

# use in CALIBRATION -> copied to CALIBRATION
#SnowMeltCoef = 0.004
IceMeltCoef  = 0.007

#--------------------------------------------------------------
# INITIAL CONDITIONS - Initial snow depth in snow zone 1-7 [mm]  - SnowCoverIni

[FROST]
# Snow water equivalent, (based on snow density of 450 kg/m3) (e.g. Tarboton and Luce, 1996)
SnowWaterEquivalent = 0.45
# Daily decay coefficient, (Handbook of Hydrology, p. 7.28)
Afrost = 0.97
# Snow depth reduction coefficient, [cm-1], (HH, p. 7.28)
Kfrost = 0.57
# Degree Days Frost Threshold (stops infiltration, percolation and capillary rise)
# Molnau and Bissel found a value 56-85 for NW USA.
FrostIndexThreshold = 56

#--------------------------------------------------------------
# INITIAL CONDITIONS: FrostIndexIni

[VEGETATION]
cropgroupnumber = $(FILE_PATHS:PathMaps)/others/cropgrp.nc
# soil water depletion fraction, Van Diepen et al., 1988: WOFOST 6.0, p.86, Doorenbos et. al 1978

#-------------------------------------------------------
[SOIL]
#-------------------------------------------------------

PathTopo = $(FILE_PATHS:PathMaps)/landsurface/topo
PathSoil = $(FILE_PATHS:PathMaps)/landsurface/soil
PathSoil1 =  $(FILE_PATHS:PathMaps)/others

# Topography - tangent slope, slope length  
tanslope = $(PathTopo)/tanslope.map
slopeLength = $(PathTopo)/slopeLength.map

# maps of relative elevation above flood plains
relativeElevation = $(PathTopo)/dzRel_hydro1k.nc

# Soil hydraulic properties

# soil (Hypres pedotransfer function - http://esdac.jrc.ec.europa.eu/ESDB_Archive/ESDBv2/popup/hy_param.htm)
KSat1 = $(PathSoil1)/ksat1.map
KSat2 = $(PathSoil1)/ksat2.map
KSat3 = $(PathSoil1)/ksat3.map
# Alpha: an Genuchten’s shape parameter
alpha1 = $(PathSoil1)/alpha1.map
alpha2 = $(PathSoil1)/alpha2.map
alpha3 = $(PathSoil1)/alpha3.map
#Lambda: an Genuchten’s shape parameter = n-1-> n = lamda+1, m = 1 - (1/n)
lambda1 = $(PathSoil1)/lambda1.map
lambda2 = $(PathSoil1)/lambda2.map
lambda3 = $(PathSoil1)/lambda3.map
# thetas  is the volumetric water content θ saturated 
thetas1 = $(PathSoil1)/thetas1.map
thetas2 = $(PathSoil1)/thetas2.map
thetas3 = $(PathSoil1)/thetas3.map
# thetar is the volumetric water content θ residual 
thetar1 = $(PathSoil1)/thetar1.map
thetar2 = $(PathSoil1)/thetar2.map
thetar3 = $(PathSoil1)/thetar3.map

percolationImp = $(PathSoil)/percolationImp.map

maxGWCapRise    = 5.0

minCropKC        = 0.2
minTopWaterLayer = 0.0

# Soil depth
StorDepth1 = $(PathSoil)/storageDepth1.map
StorDepth2 = $(PathSoil)/storageDepth2.map

# preferential flow (between 1.0 and 8.0)
# used in CALIBRATION -> copied to CALIBRATION
#preferentialFlowConstant = 4.0

#-------------------------------------------------------
[LANDCOVER]
PathLandcover = $(FILE_PATHS:PathMaps)/landsurface

coverTypes = forest, grassland, irrPaddy, irrNonPaddy, sealed, water
coverTypesShort = f, g, i, n, s, w
fractionLandcover = $(PathLandcover)/fractionLandcover.nc

# Landcover can vary from year to year
dynamicLandcover = True
# if landcover cannot vary, which year should be taken as fixed year
fixLandcoverYear = 1961

#-------------------------------------------------------

[__forest]
PathForest = $(FILE_PATHS:PathMaps)/landcover/forest
PathSoil1 =  $(FILE_PATHS:PathMaps)/others

# Parameters for the Arno's scheme 
# arnoBeta is defined by orographic,+ land cover add + calibration add, the soil water capacity distribution is based on this 
# range [0.01 - 1.2]
forest_arnoBeta = 0.2

#forest_soil
forest_KSat1 = $(PathSoil1)/forest_ksat1.map
forest_KSat2 = $(PathSoil1)/forest_ksat2.map
forest_KSat3 = $(PathSoil1)/ksat3.map
forest_alpha1 = $(PathSoil1)/forest_alpha1.map
forest_alpha2 = $(PathSoil1)/forest_alpha2.map
forest_alpha3 = $(PathSoil1)/alpha3.map
forest_lambda1 = $(PathSoil1)/forest_lambda1.map
forest_lambda2 = $(PathSoil1)/forest_lambda2.map
forest_lambda3 = $(PathSoil1)/lambda3.map
forest_thetas1 = $(PathSoil1)/forest_thetas1.map
forest_thetas2 = $(PathSoil1)/forest_thetas2.map
forest_thetas3 = $(PathSoil1)/thetas3.map
forest_thetar1 = $(PathSoil1)/forest_thetar1.map
forest_thetar2 = $(PathSoil1)/forest_thetar2.map
forest_thetar3 = $(PathSoil1)/thetar3.map

# other paramater values
forest_minInterceptCap  = 0.001
forest_cropDeplFactor   = 0.0

forest_fracVegCover  = $(PathForest)/fracVegCover.map
forest_rootFraction1 = $(PathForest)/rootFraction1.map
forest_rootFraction2 = $(PathForest)/rootFraction2.map
#forest_maxRootDepth  = 2.0
forest_maxRootDepth  = $(PathForest)/maxRootDepth.map
forest_minSoilDepthFrac = $(PathForest)/minSoilDepthFrac.map


forest_cropCoefficientNC = $(PathForest)/CropCoefficientForest_10days.nc
forest_interceptCapNC    = $(PathForest)/interceptCapForest10days.nc

# initial conditions: forest_interceptStor, forest_w1, forest_w2, forest_w3, 


[__grassland]
PathGrassland = $(FILE_PATHS:PathMaps)/landcover/grassland

# Parameters for the Arno's scheme: 
grassland_arnoBeta = 0.0
# arnoBeta is defined by orographic,+ land cover add + calibration add, the soil water capacity distribution is based on this
# range [0.01 - 1.2]

# other paramater values

grassland_minInterceptCap  = 0.001
grassland_cropDeplFactor   = 0.0

grassland_fracVegCover  = $(PathGrassland)/fracVegCover.map
grassland_rootFraction1 = $(PathGrassland)/rootFraction1.map
grassland_rootFraction2 = $(PathGrassland)/rootFraction2.map
grassland_maxRootDepth  = $(PathGrassland)/maxRootDepth.map
grassland_minSoilDepthFrac = $(PathGrassland)/minSoilDepthFrac.map


grassland_cropCoefficientNC = $(PathGrassland)/CropCoefficientGrassland_10days.nc
grassland_interceptCapNC    = $(PathGrassland)/interceptCapGrassland10days.nc

# initial conditions: grassland_interceptSto, grassland_w1, grassland_w2, grassland_w3


[__irrPaddy]
PathIrrPaddy = $(FILE_PATHS:PathMaps)/landcover/irrPaddy

# Parameters for the Arno's scheme:
irrPaddy_arnoBeta = 0.2
# arnoBeta is defined by orographic,+ land cover add + calibration add, the soil water capacity distribution is based on this
# range [0.01 - 1.2]

# other paramater values

irrPaddy_minInterceptCap  = 0.001
irrPaddy_cropDeplFactor   = 0.0

irrPaddy_fracVegCover  = $(PathIrrPaddy)/fracVegCover.map
irrPaddy_rootFraction1 = $(PathIrrPaddy)/rootFraction1.map
irrPaddy_rootFraction2 = $(PathIrrPaddy)/rootFraction2.map
irrPaddy_maxRootDepth  = $(PathIrrPaddy)/maxRootDepth.map
irrPaddy_minSoilDepthFrac = $(PathIrrPaddy)/minSoilDepthFrac.map

irrPaddy_cropCoefficientNC = $(PathIrrPaddy)/CropCoefficientirrPaddy_10days.nc

# maximum flooding depth for paddy
irrPaddy_maxtopwater = 0.05



# initial conditions: irrPaddy_interceptStor, irrPaddy_w1, irrPaddy_w2, irrPaddy_w3



[__irrNonPaddy]
PathIrrNonPaddy = $(FILE_PATHS:PathMaps)/landcover/irrNonPaddy

# Parameters for the Arno's scheme:
irrNonPaddy_arnoBeta = 0.2
# arnoBeta is defined by orographic,+ land cover add + calibration add, the soil water capacity distribution is based on this
# range [0.01 - 1.2]

# other paramater values


irrNonPaddy_minInterceptCap  = 0.001
irrNonPaddy_cropDeplFactor   = 0.0

irrNonPaddy_fracVegCover  = $(PathIrrNonPaddy)/fracVegCover.map
irrNonPaddy_rootFraction1 = $(PathIrrNonPaddy)/rootFraction1.map
irrNonPaddy_rootFraction2 = $(PathIrrNonPaddy)/rootFraction2.map
irrNonPaddy_maxRootDepth  = $(PathIrrNonPaddy)/maxRootDepth.map
irrNonPaddy_minSoilDepthFrac = $(PathIrrNonPaddy)/minSoilDepthFrac.map


irrNonPaddy_cropCoefficientNC = $(PathIrrNonPaddy)/CropCoefficientirrNonPaddy_10days.nc


# initial conditions: irrNonPaddy_interceptStor, irrNonPaddy_w1, irrNonPaddy_w2, irrNonPaddy_w3


[__sealed]
PathSealed = $(FILE_PATHS:PathMaps)/landcover/sealed

sealed_minInterceptCap  = 0.001

# initial conditions: sealed_interceptStor


[__open_water]
PathWater = $(FILE_PATHS:PathMaps)/landcover/water

water_minInterceptCap  = 0.0

#-------------------------------------------------------
[GROUNDWATER]
#-------------------------------------------------------

PathGroundwater = $(FILE_PATHS:PathMaps)/groundwater

recessionCoeff = $(PathGroundwater)/recessionCoeff.map
# baseflow = recessionCoeff * storage groundwater
specificYield = $(PathGroundwater)/specificYield.map
kSatAquifer = $(PathGroundwater)/kSatAquifer.map
# both not used at the moment in groundwater modul, but already loaded

#--------------------------------------------------------------
# INITIAL CONDITIONS: storGroundwater


#-------------------------------------------------------
[WATERDEMAND]
#-------------------------------------------------------

PathWaterdemand = $(FILE_PATHS:PathMaps)/landsurface/waterDemand
# For water demand vs. availability: areas have to be aggregated
# Allocation map
allocSegments = $(PathWaterdemand)/catchx.nc

domesticWaterDemandFile = $(PathWaterdemand)/domesticWaterDemand.nc
industryWaterDemandFile = $(PathWaterdemand)/industryWaterDemand.nc

irrNonPaddy_efficiency = $(FILE_PATHS:PathMaps)/landsurface/waterDemand/efficiency.nc
irrPaddy_efficiency = $(FILE_PATHS:PathMaps)/landsurface/waterDemand/efficiency.nc

#irrNonPaddy_efficiency = 0.8
#irrPaddy_efficiency = 0.8
irrigation_returnfraction = 0.5

# -----------------------------------------------------------
# Estimate of fractions of groundwater and surface water abstractions
# Either a fixed fraction for surface water abstration
# based on fraction of average baseflow and upstream average discharge 
# if swAbstractionFrac < 0: fraction is taken from baseflow / discharge 
# if swAbstractionFrac > 0 this value is taken as a fixed value 
swAbstractionFrac = 0.9
averageDischarge = $(FILE_PATHS:PathOut)/discharge_totalavg_rhine30min.nc
# in [m3/s]
averageBaseflow  = $(FILE_PATHS:PathOut)/baseflow_totalavg_rhine30min.nc
# in [m3/s]
baseflowInM = True
# if baseflow is in [m] instead of [m3/s] it will be converted


#-------------------------------------------------------
# RUNOFF CONCENTRATION
#-------------------------------------------------------
[RUNOFF_CONCENTRATION]

# using triagular weigthning method
# the bigger the factor, more lag time 
forest_runoff_peaktime = 1.0
grassland_runoff_peaktime = 0.5
irrPaddy_runoff_peaktime = 0.5
irrNonPaddy_runoff_peaktime = 0.5
sealed_runoff_peaktime = 0.15 
water_runoff_peaktime = 0.01

interflow_runoff_peaktime =1.0
baseflow_runoff_peaktime = 2.0

# initial conditions:
# here only 1 layer is shown, but there are up to 10: runoff_concIni


#-------------------------------------------------------
# ROUTING MAPS and PARAMETERSD
#-------------------------------------------------------
[ROUTING]

PathRouting = $(FILE_PATHS:PathMaps)/routing

# Number of substep per day
# should be 10 for 0.5 deg but 24 for 0.1 deg

NoRoutingSteps = 10
#kinematic wave parameter: 0.6 is for broad sheet flow
chanBeta = 0.6

# Channel gradient (fraction, dy/dx)
chanGrad = $(PathRouting)/kinematic/changrad.nc
# Minimum channel gradient (for kin. wave: slope cannot be 0)
chanGradMin = 0.0001

#Channel Manning's n
chanMan = $(PathRouting)/kinematic/chanman.nc
#Channel length [meters]
chanLength = $(PathRouting)/kinematic/chanleng.nc
#Channel bottom width [meters]
chanWidth = $(PathRouting)/kinematic/chanbw.nc
#Bankfull channel depth [meters]
chanDepth = $(PathRouting)/kinematic/chanbnkf.nc

# initial conditions: channelStorageIni, riverbedExchangeIni, dischargeIni  

#-------------------------------------------------------
# LAKES AND RESERVOIRS
#-------------------------------------------------------
[LAKES_RESERVOIRS]

PathLakesRes = $(FILE_PATHS:PathMaps)/routing/lakesreservoirs

# Use reservoirs and lakes (otherwise use only lakes Lake ID=1 and 3 => natural conditions)
useResAndLakes = True
# Reservoirs do have a year of implementation
dynamicLakesRes = True
# if Reservoirs does not have a year of implemtation, which year should be taken as fixed year
fixLakesResYear = 1950


#----------------------------
#Big lakes and Reservoirs

# ID of every lake, reservoir from HydroLakes database
waterBodyID = $(PathLakesRes)/lakesResID.nc
# 1 for lake, 2 for reservoir, 3 for lake and reservoir
waterBodyTyp = $(PathLakesRes)/lakesResType.nc
# Avergae discharge from HydroLakes Database
waterBodyDis = $(PathLakesRes)/lakesResDis.nc

# Lakes surface area from HydroLakes Database 
waterBodyArea = $(PathLakesRes)/lakesResArea.nc
# a factor to scale the outlet of a lake
#lakeAFactor = 1.0  -> calibration

#----------------------------
# Small lakes and reservoirs

useSmallLakes = True

smallLakesRes = $(PathLakesRes)/smallLakesRes.nc
smallwaterBodyDis = $(PathLakesRes)/smalllakesresDis.nc

# averageRunoff in [m] (if not given smallwaterBodyDis is taken instead)
#averageRunoff  = $(FILE_PATHS:PathOut)/runoff_totalavg_cali.nc

# for water demand
#min storage in [m3] (if not give it is calculated)
#minStorage  = $(FILE_PATHS:PathOut)/minsmalllakeStorage_cali.nc


# initial conditions: lakeInflowIni, lakeStorageIni, outLakeIni, lakeOutflowIni, reservoirStorageIni 

#------------------
# Reservoirs
# reservoir volume from HydroLakes database
waterBodyVolRes = $(PathLakesRes)/lakesResVolRes.nc
# reservoir starting year from HydroLakes database 
waterBodyYear = $(PathLakesRes)/lakesResYear.nc

#  Conservative, normal and flood storage limit (fraction of total storage, [-])
conservativeStorageLimit = 0.1
#normalStorageLimit = 0.5   # --> put into calibration
floodStorageLimit = 0.9
# adjusting the balance between normal and flood storage
# [0 ..1]  0: NormalstorageLimit      1: (= closer to flood) results in keeping the normal qoutflow longer constant
adjust_Normal_Flood = 0.5

# Minimum, Normal and Non-damaging reservoir outflow  (fraction of average discharge, [-])
MinOutflowQ = 0.2
NormalOutflowQ = 1.0
NonDamagingOutflowQ = 4.0

# initial conditions: lakeInflowIni, lakeStorageIni, outLakeIni, lakeOutflowIni, reservoirStorageIni 


#-------------------------------------------------------
[INFLOW]
#-------------------------------------------------------

# if option inflow = true
# the inflow from outside is added at inflowpoints
In_Dir = $(FILE_PATHS:PathRoot)/in

# nominal map with locations of (measured)inflow hydrographs [cu m / s]
InflowPoints = $(In_Dir)/in.map
#InflowPoints = 8.25 49.75 7.75 50.25

# if InflowPoints is a map, this flag is to identify if it is global (False) or local (True)
# observed or simulated input hydrographs as time series [cu m / s]
# Note: that identifiers in time series have to correspond to InflowPoints
# can be several timeseries in one file or different files e.g. main.tss mosel.tss
#QInTS = main1.tss mosel1.tss
QInTS = mm.tss



#-------------------------------------------------------
[ENVIRONMENTALFLOW]
#-------------------------------------------------------

# Either calculate without run with predone discharge (set calc_ef_after = False)
calc_ef_after = True
# Or calculate after run (set calc_ef_after = False) and defining the file to be used
EFDis = $(FILE_PATHS:PathOut)/discharge_rhine.nc

# if predone discharge, do the maps need to be cut to fit to the mask?
cut_ef_map = False

EnvironmentalFlowFile = $(FILE_PATHS:PathOut)/MQ90_12month.nc

# MAF: Mean, Q90: percentile 90, MMF: monthly average, MQ90: monthly Q90 9averagwed over al Jan, Feb..
# EF_VMF: Environmental flow - variable monthly flow, EF_VMF_LIH - EF- variable monthly flow, high intermediate, low class
OUT_Dir = $(FILE_PATHS:PathOut)
#OUT_MAP_Once = MAF, Q90
#OUT_MAP_12month = MMF, MQ90, EF_VMF, EF_VMF_LIH
#OUT_MAP_12month = MQ90, EF_VMF



#+++++++++++++++++++++++++++++++++++++++++++++++++++++++
#+++++++++++++++++++++++++++++++++++++++++++++++++++++++


[OUTPUT]

# OUTPUT maps and timeseries
OUT_Dir = $(FILE_PATHS:PathOut)

OUT_TSS_Daily = discharge
#OUT_TSS_MonthAvg = discharge
#OUT_TSS_AnnualAvg = discharge

#OUT_Map_Daily = discharge
#OUT_Map_MonthAvg = discharge, precipitation, runoff
#OUT_Map_AnnualAvg = discharge
#OUT_MAP_TotalAvg = discharge, baseflow

NetCDF meta data

Output Meta NetCDF information

The metaNetcdf.xml includes information on the output netCDF files e.g. description of the parameter, unit ..

Example of a metaNetcdf.xml file:

<CWATM>
# METADATA for NETCDF OUTPUT DATA

# varname: name of the variable in the CWAT code
# unit: unit of the varibale
# long name# standard name

# Discharge maps 
<metanetcdf varname="discharge" unit="m3/s"  standard_name="Discharge" long_name="Discharge in cubic meter per second"  title="1st Demo CWATM" author="PB" />

# others
<metanetcdf varname="soilmoisture" unit="mm"  standard_name="soil moisture" long_name="Soil moisture"  title ="1st Demo CWATM" author="PB" />

# Initial condition Files
<metanetcdf varname="initcondition"  purpose ="Initial Conditions CWATM" author="PB" />
<metanetcdf varname="SnowCover1" unit="mm"  standard_name="SnowCover1" long_name="Snow cover top layer"  />
<metanetcdf varname="SnowCover2" unit="mm"  standard_name="SnowCover2" long_name="Snow cover middle layer"  />
<metanetcdf varname="SnowCover3" unit="mm"  standard_name="SnowCover3" long_name="Snow cover lower layer"  />
<metanetcdf varname="FrostIndex" unit="degree/days"  standard_name="FrostIndex" long_name="Frost index based on Molnau, Bissel (1983)"  />
</CWATM>

Name and location of the NetCDF meta data file

In the settings file the name and location of the metadata file is given.

#-------------------------------------------------------
[NETCDF_ATTRIBUTES]
institution = IIASA
title = Global Water Model - WATCH WDFEI
metaNetcdfFile = $(FILE_PATHS:PathRoot)/cwatm/metaNetcdf.xml

Initialisation

CWatM needs to have estimates of the initial state of the internal storage variables, e.g. the amount of water stored in snow, soil, groundwater etc.

There are two possibilities:

1. The initial state of the internal storage variables are unknown and a first guess has to be used e.g. all storage variables are half filled.

2. The initial state is known from a previous run, where the variables are stored at a certain time step. This is called warm start

The warm start is usful for:

• using a long pre-run to find the steady-state storage of the groundwater storage and use it as initial value

• using the stored variables to shorten the warm-up period

• using the stored variables to restart every day with the values from the previous day (forecasting mode)

Example of soil moisture

The next figure shows the impact of different initial condition on the soil moisture of the lower soil. In one of the simulations the soil is initially almost completely saturated. In another simulation the soil is completely dry and the third simulation starts with initial conditions in between the two extremes.

In the beginning the effect of different initial condition can be seen clearly. But after one year the three curves converge. The memory of the lower soil goes back for about one year.

For all the initial condition apart from groundwater, lakes and reservoirs the memory is about 12 month.

Figure: Simulation of soil moisture in the lower soil with different initial conditions

For the groundwater zone a longer warm-up period is needed, because of the slow response of groundwater. Here a rather fast reacting groundwater storage is shown with the three curves coverge after two years. We propose a warm-up of several decades. The longer the better.

Figure: Simulation of groundwater storage with different initial conditions

Cold start

For a cold start the values of the storage variables are unknown and set to a “first” guess. A list of variables and their default value for a cold start is given below in: Initial conditions

Set up a cold start in the settingsfile

In the settings file the option: load_initial has to be set on False

#-------------------------------------------------------
[INITITIAL CONDITIONS]
#-------------------------------------------------------

# for a warm start initial variables a loaded
# e.g for a start on 01/01/2010 load variable from 31/12/2009
load_initial = False
initLoad = $(FILE_PATHS:PathRoot)/init/Rhine_19891231.nc

Note

It is possible to exclude the warming up period of your model run for further analysis of results by setting the SpinUp option

[TIME-RELATED_CONSTANTS]
SpinUp =  01/01/1995

Storing initial variables

In the settings file the option save_initial has to be set to True

The name of the initial netCDF4 file has to be put in initsave

and one or more dates have to be specified in StepInit

# saving variables from this run, to initiate a warm start next run
# StepInit = saving date, can be more than one: 10/01/1973 20/01/1973
save_initial = False
initSave = $(FILE_PATHS:PathRoot)/init/Rhine
StepInit = 31/12/1989 31/12/2010

Warm start

CWatM can write internal variables to a netCDF file for choosen timesteps. These netCDF files can be used as the initial conditions for a suceeding simulation.

This is useful for establishing a steady-state after a long-term run and then using this steady-state for succeding simulations or for an every day run (forecasting mode)

Warning

If the parameters are changed after a run(especially the groundwater, lakes and reservoir parameters) the stored initial values do not represent the conditions of the storage variables. Stored initial conditions should not be used as initial values for a model run with another set of parameters. If you do this during calibration, you will not be able to reproduce the calibration results!

Set up a cold start in the settingsfile

In the settings file the option: load_initial has to be set on True And define the name of the netcdf4 file in initLoad

Note

Use the initial values of the previous day here. E.g. if you run the model from 01/01/2006 use the inital condition from 31/12/2005

#-------------------------------------------------------
[INITITIAL CONDITIONS]
#-------------------------------------------------------

# for a warm start initial variables a loaded
# e.g for a start on 01/01/2010 load variable from 31/12/2009
load_initial = False
initLoad = $(FILE_PATHS:PathRoot)/init/Rhine_19891231.nc

Initial conditions

No.	Variable	Description	Default value	Number of maps
1	SnowCover	Snow cover for up to 7 zones	0	7
2	FrostIndex	Degree days frost threshold	0	1
3	Forest state	Interception storage	0	1
		Top water layer	0	1
		Soil storage for 3 soil layers	0	3
4	Grassland state	Interception storage	0	1
		Top water layer	0	1
		Soil storage for 3 soil layers	0	3
5	Paddy irrigation state	Interception storage	0	1
		Top water layer	0	1
		Soil storage for 3 soil layers	0	3
6	Irrigation state	Interception storage	0	1
		Top water layer	0	1
		Soil storage for 3 soil layers	0	3
7	Sealed area state	Interception storage	0	1
8	Groundwater	Groundwater storage	0	1
9	Runoff concentration	10 layers of runoff concentration	0	10
10	Routing	Channel storage	0.2 * total cross section	1
	Routing	Riverbed exchange	0	1
	Routing	Discharge	depending on ini channel stor.	1
11	Lakes and Reservoirs	Lake inflow	from HydroLakes database	1
		Lake outflow	same as lake inflow	1
		Lake&Res outflow to other lakes&res	same as lake inflow	1
		Lake storage	based on inflow and lake area	1
		Reservoir storage	0.5 * max. reservoir storage	1
		Small lake storage	based on inflow and lake area	1
		Small lake inflow	from HydroLakes database	1
		Small lake outflow	same as small lake inflow	1

Model Output

An advantage of CWatM is the full flexibility of the output variables.

• All parameters and variables can be used for output as maps or time series.

• Even if the model is run at daily timestep, output can be daily, monthly, annual, at the end of a run

• all variables maps are stored as netcdf and the meta data information can be added

Time depending and non depending output maps

Output maps will be produced as spatial maps, stack of spatial maps (over time)

Format: netCDF

The netCDF maps can be read with:

Windows

• Panoply

Linux

• ncview

• cdo

Or time series at specified points

Timeseries are procuded as ASCII .csv files, which can be read with every text editor or Excel

If you need the old version .tss with you can read with PCRaster Aquila

you need to put reportOldTss = True in [Option] (e.g. calibration still need the old version)

The specific point(s) where timeseries are provided are defined in the settings file as Gauges:

Can be several points in the format lon lat lon lat ..

# Station data
# either a map e.g. $(FILE_PATHS:PathRoot)/data/areamaps/area3.map
# or a location coordinates (X,Y) e.g. 5.75 52.25 9.25 49.75 )
# Lobith/Rhine
Gauges = 6.25 51.75 7.75 49.75

# if .tif file for gauges, this is a flag if the file is global or local
# e.g. Gauges = $(FILE_PATHS:PathRoot)/data/areamaps/gaugesRhine.tif
GaugesLocal = True

Or time series as a catchment sum or average

As standard, time series can include values of the specific cell as defined in the settings file as Gauges But time series can also show the area sum or area average of the upstream catchment from the specific cell

for example

[OUTPUT]
# OUTPUT maps and timeseries
# Standard values of a specific cell
OUT_TSS_Daily = discharge
OUT_TSS_AnnualAvg = Precipitation
# Area sum of upstream catchment
OUT_TSS_AreaSum_MonthTot = Precipitation, runoff
# Area sum of upstream catchment
OUT_TSS_AreaAvg_MonthTot = Precipitation

Format of output in the settings file

• per day [Daily]

• total month [MonthTot], average month [MonthAvg], end of month [MonthEnd]

• total year [AnnualTot], average year [AnnualAvg], end of year [AnnualEnd]

• total sum [TotalTot], total average [TotalAvg]

For each of the following sections output can be defined for different variables:

• Meteo

• Snow

• Soil for different land cover (forest, grassland, irrigated land, paddy irrigated)

• Water demand

• Groundwater

• River routing

• Lakes and reservoirs

Or output can be defined in the section [output]

An output directory can be defined and for each sort of output the variable(s) can be set:

OUT_ defines that this variable(s) are output

MAP_ or TSS_ defines if it is a spatial map or a time series of point(s)

AreaSum_ or AreaAvg_ after TSS_ defines if the catchment sum of average upstream of the point is calculated

Daily or MonthAvg or .. is specifying the time

The variable is given after the equal sign e.g. * = discharge*

If more than one variable should be used for output, split with ,

E.g. OUT_MAP_Daily = discharge -> daily spatial map of discharge

As example output for precipitation, temperature and discharge is shown here:

# OUTPUT maps and timeseries
OUT_Dir = $(FILE_PATHS:PathOut)
OUT_MAP_Daily =
OUT_MAP_MonthEnd =
OUT_MAP_MonthTot = Precipitation, Tavg
OUT_MAP_MonthAvg =

OUT_TSS_MonthTot = Precipitation, Tavg   # monthly total precipitation and average temperature
OUT_TSS_Daily = discharge                # daily discharge
OUT_TSS_MonthEnd = discharge
OUT_TSS_AnnualEnd = discharge

OUT_TSS_AreaSum_Daily = Precipitation    # daily sum of precipitation for the upstream catchment
OUT_TSS_AreaAvg_MonthAvg = runoff        # monthly average sum of runoff for the upstream catchment

Note

For each variable the meta data information can be defined in Output Meta NetCDF information

Output variables

Output can be every global defined variable in the model Variable are e.g. Precipitation, runoff, baseflow

but also not so common variables as:

• reservoirStorage (amount of water in the reservoirs in [m3])

• nonIrrReturnFlowFraction (returnflow from domenstic and industrial water use [m3])

• actualET[1] (actual evapotranspiration from grassland [m/day])

• …

Daily, monthly - at the end or average

• per day

• total month, average month, end of month

• total year, average year, end of year

• total average, total at the end

available prefixes are: ‘daily’, ‘monthtot’,’monthavg’, ‘monthend’,’annualtot’,’annualavg’,’annualend’,’totaltot’,’totalavg’

for example

[OUTPUT]
# OUTPUT maps and timeseries
OUT_Dir = $(FILE_PATHS:PathOut)
OUT_MAP_Daily = discharge, runoff, actualET[1]
OUT_MAP_MonthAvg = Precipitation
OUT_MAP_TotalEnd = lakeStorage
OUT_MAP_TotalAvg = Tavg

OUT_TSS_Daily = discharge
OUT_TSS_MonthTot = runoff
OUT_TSS_AnnualAvg = Precipitation
OUT_TSS_AnnualTot = runoff

Note

For each variable the meta data information can be defined in Output Meta NetCDF information

Note

We are not very precise when to use capital letter for some output variables. But we fear now, if we change the variable name, we will forget it somewhere.

Most important output variables - a selection

#Variable name    : Description
discharge         : river discharge
runoff            : runoff
Precipitation     : rainfall + snow
Tavg              : average temperature
ETRef: potential  : evaporation from reference soil
sum_gwRecharge    : total groundwater recharge
totalET           : total actual evapotranspiration
baseflow          : baseflow from groundwater
... (to be continued)

Output variables - starting a list

A list of variables can be produced by using:

grep -d recurse ‘self.var.’ *.py

Every self.var.variable can be used as output variable

For a description of the variable please take a look at the python module itself.

.

As output variable please use without self.var.

We started a list of possible output variables. Please note that this list is under construction. We still need to fill in all descriptions and all units. You find this list at List of output variables