Programming for hydrologists, engineers and
water resources specialists: Python
Rwasoka, Donald T
Gumindoga, Webster
August, 2020
1|Page
1.0 INTRODUCTION AND MOTIVATION 4
LEARNING OBJECTIVES 5
WHICH LANGUAGE? 5
WHAT IS PYTHON? 6
LEARNING STRATEGY 7
ASSIGNMENTS 8
2.0 DOWNLOAD AND INSTALLATION 8
DOWNLOAD ANACONDA PYTHON 8
INSTALLATION OF GDAL 14
3.0 PYTHON BASICS 16
4.0 READING IN TIME-SERIES DATA AND PLOTTING 17
5.0 PERFORMANCE EVALUATION METRICS IN HYDROLOGY 18
6.0 PRECIPITATION 18
GAP FILLING FOR AN EVENT: RWANDOGA CATCHMENT 18
DOUBLE MASS CURVES 18
AREAL RAINFALL 18
7.0 EVAPOTRANSPIRATION 18
8.0 INTERCEPTION 18
9.0 INFILTRATION 19
FROM DARCY’S LAW TO RICHARD’S EQUATION 19
SORPTIVITY 19
DIFFUSIVITY 19
INFILTRATION AT A POINT: PHILLP EQUATION 19
INFILTRATION AT A POINT: HORTON’S EQUATION 19
STREAMFLOW MEASUREMENT AND GAUGING 19
RATING CURVES 19
SALT DILUTION GAUGING 19
HYDROGRAPH ANALYSIS 20
BASEFLOW SEPARATION 20
BASEFLOW INDEX 20
RECESSION ANALYSIS 20
2|Page
STATISTICS IN HYDROLOGY AND ENGINEERING 20
LINEAR ALGEBRA/SYSTEMS 20
NUMERICAL INTEGRATION AND DIFFERENTIATION 20
NUMERICAL SCHEMES 21
FINITE DIFFERENCE 21
FINITE ELEMENT 21
FINITE VOLUME 21
STREAMFLOW ROUTING 21
OVERLAND FLOW GENERATION AND ROUTING 21
SOIL WATER 22
DARCY’S LAW AND MASS CONSERVATION 22
SOIL WATER CONSTITUTIVE EQUATIONS 22
SOIL WATER MOVEMENT: TANK-APPROACH 22
SOIL WATER MOVEMENT: RICHARD’S EQUATION 22
STREAM-BED MORPHODYNAMICS 24
GROUNDWATER FLOW 24
BOUSSINESQ FLOW 24
GROUNDWATER FLOW TO WELLS 24
STREAMFLOW DEPLETION 24
GROUNDWATER FLOW MODELLING 25
BUILDING A FINITE-DIFFERENCE GROUNDWATER MODELLING IN PYTHON 25
3|Page
1.0 INTRODUCTION AND MOTIVATION
Greetings and Welcome
Running computations is at the core of scientific and engineering work. Ideas and
concepts are defined and expressed in terms of equations and computational results.
Equations can be solved on paper but this is not effective and efficient. You can
imagine trying to run iterations or numerical approximations on paper. At some point it
becomes tedious and cumbersome. Paper work is good when you are learning the
concept but repetitive paper work of the same calculation or operation is definitely not
an efficient and effective to work. Or, imagine if you have to do the same calculation or
operation over and over again with files in a folder or columns in spreadsheets. You
can do it manually and spend the next n hours clicking repetitively. Surely, that’s neither
effective nor efficient, especially in these times of the information age and on the cusp
of the fourth industrial revolution. What if you can tell the machine to do it for you?
What if you tell the machine to produce exactly what you envision without being limited
by, is the function available in the software? What you could solve the equations
yourself anyway you like with having to say I need x software because it uses finite
element analysis but I also need y software because the problem is naturally solved in
a finite difference or finite volume framework. What if you could write new software that
will do all that at no extra cost to you or your organization? What if you could improve
the graphs you present? These what if questions and more can be addressed by
learning programming. You can tell the computer what to do. It can do the manual and
repetitive work for you. Gone are the days when programming was viewed as a
preserve of those doing computer scientists. Everyone needs to learn and use
programming. The start-ups of this world are built on programming.
Furthermore, you should learn programming for the following reasons:
Programming will teach how to think. Steve Jobs once said everybody “should
learn how to program a computer, because it teaches you how to think. I view
computer science as a liberal art.” Programming, also teaches you to think
through your actions before you make a move.
It’s a better way to store your work, and you can even revisit and re-use your
code at any time. You don't have to run to a textbook to find the formula and run
the derivations again. As long as you keep your codes safely, you can re-use
them at any time. Thus you can work 10 to 100 times faster
From the above, programming will increase your productivity
It allows you to automate design workflows and changes.
It enables you to come up with more creative solutions
Programming will enhance your communication and collaboration skills
4|Page
As long as you understand the basic ideas or building blocks, you have the
flexibility of switching from one programming language to another. Maybe until
quantum computing makes a commercial entry.
With the world moving to data science and automation on the horizon, you have
to know how to program.
You will discover that your laptop or computer can do more than watching
videos, playing games, and writing letters!
Given the above the reasons, the evolving information age that we are, the fourth
industrial revolution and global trends in terms of science and engineering, we were
convinced that it is criminal to produce a modern-day engineering, environmental and
hydrologic graduate and/or professional who is not comfortable in programming. As
we used to say, it can’t. It’s criminal. We will not be complicit. We were thus motivated
to develop this material for use in the Civil Engineering Department at the University of
Zimbabwe.
Learning Objectives
The overall learning objective of the programming is not to teach you programming per
se. Our aim is to teach hydrology, hydraulics and modelling concepts and computations
through programming. There is a subtle but significant difference. In essence, the ideas
and concepts in hydrology, hydraulics and modelling are explored and taught through
programming. So you have to bring your hydrology, hydraulics and modelling concepts
and mathematical skills, it's just that the ideas will be expressed in code. It is hands-
on and mind-on!
Specifically, we expect that at the end, you will:
1. Be able to translate ideas and solve problems in computer language
2. Be able to read, analyze, optimise, and debug code
3. Computational understand equations and algorithms
4. Solve hydrologic and engineering problems.
5. Effectively visualize and present computation output.
6. Use programming to improve your thesis computational work and graphs.
Which Language?
That is the million-dollar question we had to grapple with : which language?
There are many programming languages out there. Some are recent and some are
old. Sum are fast and some are not as fast. Some are interpreted and some need to
be compiled. However, the building blocks, ideas and logic are more or less the same.
The difference is in the syntax, which is, how do you write a statement but the idea is
more or less the same.
5|Page
One of the conditions that we used to select which language to teach is that the
coding language should be easily accessible and free. This therefore meant that
commercial packages such as MATLAB were not in this subset that we were looking
at. Furthermore, since we are introducing coding in an applied sense and so we also
wanted a language that was more intuitive; a language that you can easily read and
understand even though it might not be the fastest cat in town. It can be argued that
the fastest languages are the old legends in the names of: C, C++ and Fortran.
Actually, most of the modern-day intuitive languages actually use fortran and c++ in
the background. However, we still wanted something that was modern, in wide-use
and interpreted - touch and go. We ultimately decided that Python and R are the best
candidates for now from a computational, data science, spatial science and statistical
perspective. In this text we will deal with Python. Yes, I know, in an African context the
name Python may not be ideal but you'll get to appreciate what it does.
The Tiobe ranking Index ([Link] as at August 2020 shows
the rankings of programming languages in terms of popularity. Have a look at ranking
of Python and R.
What is Python?
We cannot say it any better than the python guys themselves, so here is the blurb from
here, [Link]
6|Page
Python is an interpreted, object-oriented, high-level programming language with
dynamic semantics. Its high-level built in data structures, combined with dynamic
typing and dynamic binding, make it very attractive for Rapid Application Development,
as well as for use as a scripting or glue language to connect existing components
together. Python's simple, easy to learn syntax emphasizes readability and therefore
reduces the cost of program maintenance. Python supports modules and packages,
which encourages program modularity and code reuse. The Python interpreter and the
extensive standard library are available in source or binary form without charge for all
major platforms, and can be freely distributed.
Often, programmers fall in love with Python because of the increased productivity it
provides. Since there is no compilation step, the edit-test-debug cycle is incredibly fast.
Debugging Python programs is easy: a bug or bad input will never cause a
segmentation fault. Instead, when the interpreter discovers an error, it raises an
exception. When the program doesn't catch the exception, the interpreter prints a stack
trace. A source level debugger allows inspection of local and global variables,
evaluation of arbitrary expressions, setting breakpoints, stepping through the code a
line at a time, and so on. The debugger is written in Python itself, testifying to Python's
introspective power. On the other hand, often the quickest way to debug a program is
to add a few print statements to the source: the fast edit-test-debug cycle makes this
simple approach very effective.
Python has two main version that are in use, Python 2 and Python 3, generally
abbreviated py2 and py3. We will use py3 here.
Learning Strategy
As indicated in the overall learning objective above, the aim is not that we hard-core
teach programming and all its fore and background issues. Most of the programming
will be learnt through exercises. The following will be the execution strategy:
1. We will start with a short introduction on python and general programming
concepts e.g. “hello world”, data types, control flow, indexing etc.
2. We will then move onto reading in time-series data. Spatial data will be dealt
with during the GIS module. Most of the learning for now will be based on time-
series data. Being able to read in data is crucial
3. We will then explore plotting time series data and data wrangling
4. Then we get into hydrology and engineering aspects
The learning is going to be interactive in the following ways:
In some instances all the code will be provided.
In other instances the provided codes will be half done and you will have to add
the missing lines.
7|Page
In some instances the final output will be provided and student is then expected
write code to produce the final output
In some cases the student will have to derive the equations and implement.
This is not meant to replace the need for attending lectures but this builds on the
lectures. The lectures will deal with the theoretical aspects and the programming will
deal the practical computational aspects. So bring what you learnt in class to python
class.
Assignments
There will a number of short coding assignments. These will include quiz’s, short
scripting task, read and correcting codes and ultimately developing your own codes.
2.0 Download and Installation
As indicated earlier we will use py3. You can download python from the python
webpage and then build it up to your taste but for beginners its better to use a pre-
packaged python distribution which you can get from anaconda, enthought and others.
The assumption is that most users use windows platforms. Ans so the instructions will
be structured for windows.
We use the anaconda python distribution here.
Download Anaconda Python
1. Go to [Link]
2. Scroll down to the bottom of the page and download the ‘bit version’ that is suitable for your
computer/laptop
8|Page
For older packages of anaconda, you can download them here:
[Link]
and scroll down for 3.7
3. After downloading anaconda, you can go ahead and install it by running or
double clicking the installer you downloaded
a. Its better to choose default settings and suggestions.
9|Page
b. At the Advanced Installation Options screen below, I recommend that
you do not check "Add Anaconda to my PATH environment variable"
If you will have 3.8, instead of 3.7.
4. After the installation process finishes successfully, you should now have the
anaconda python distribution installed on your machine. Included in the
installation are:
a. Spyder , anaconda’s IDE
b. Jupyter notebook
c. Python and packages
d. Anaconda command line
10 | P a g e
5. Open that anaconda command prompt (black screen) by searching for “anaconda prompt” in
your search window
11 | P a g e
6. Strat by doing an update of anaconda, so start by doing typing in “conda
update conda” on the anaconda conda prompt window
7. When the update is completed, you can have look at the modules that are
installed by running
conda list.
12 | P a g e
The names of the packages installed iby the anaconda package will then be printed to the screen:
Check if you can see numpy, pandas and matplotlib!!
Hoooraaay!!! Installation is done!
13 | P a g e
Installation of GDAL
GDAL (Geospatial Data Abstraction Library) is a computer software library for reading
and writing raster and vector geospatial data formats. It’s found if most, if not all GIS
systems. It runs in the background but in python for spatial operations we will need to
interact withit directly.
Getting it to work is a bit tricky. Fortunately, there is someone in world who spends his
time coming up a solution and shares the solutions with the world in the form of .whl
files.
Proceed as follows:
1. Navigate to this page: [Link]
2. Click and download .whl file that matches the version of python you installed
and the ‘bit’ of your machine. It’s easier to save the file on your c drive because
we will have to navigate using the command line
3. Using your anaconda command prompt (not the windows command prompt!!)
navigate to where the gdal .whl file is.
14 | P a g e
In my case, I put it on C:\Users\MyName because this is where my installation
of anaconda prompt starts at, if not all of them. If your file is in a different place,
switch to that folder using “cd: “commands
In my case I am on C: so I will just list all the directories and files, and we should
see the gdal .whl file
4. Now pip install the .whl file by calling the internal python installer called pip and
the name of the file to be installed on the anaconda command prompt/line. Type
in:
pip install GDAL-3.1.2-cp37-cp37m-win_amd64.whl
If you don’t get an error, as you should not, Installation is done. Hooray!!!
15 | P a g e
3.0 PYTHON BASICS
We will use Jupyter notebook to run python code in this class. You are free to use the python Spyder
IDE as well.
What is a Jupyter notebook ?
As explained by the jupyter guys themselves:
“Notebook documents (or “notebooks”, all lower case) are documents produced by the Jupyter
Notebook App, which contain both computer code (e.g. python) and rich text elements (paragraph,
equations, figures, links, etc…). Notebook documents are both human-readable documents
containing the analysis description and the results (figures, tables, etc..) as well as executable
documents which can be run to perform data analysis. ”
[Link]
We will explain more in class. See you then!
16 | P a g e