Installing CWatM

Contents

• Installing CWatM

  • Installing Python

    • Virtual environment setup (optional)

      • What is virtual environment

      • How to install virtual environment

    • External libraries

  • Installing CWatM

    • C++ libraries

      • Compiling a version

    • Installing CwatM on Mac

  • Running the model for the first time

    • Run with a settingsfile

  • Using Flags

Installing Python

CWatM requires having Python.

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

Running the model for the first time

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: ...
Arguments list:
settings.ini     settings file
-q --quiet       output progression given as .
-v --veryquiet   no output progression is given
-l --loud        output progression given as time st
-c --check       input maps and stack maps are check
-h --noheader    .tss file have no header and start
-t --printtime   the computation time for hydrologic
-w --warranty    copyright and warranty information

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 with a settingsfile

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