This document describes FullSWOF-utils, a set of utility scripts to be used with the FullSWOF shallow flow solver.

Copyright © 2019, 2020, 2021, 2022 Paul Garlick.

     Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts.  A copy of the license is included in the section entitled ``GNU Free Documentation License''.

FullSWOF-utils
**************

Utility scripts for the FullSWOF shallow flow solver

Installation
************

The fullSWOF-utils package comprises a single top-level directory and several sub-directories.  The package may be installed in the same location as FullSWOF itself or any other convenient location.

The package contains the following utility scripts:

 1. boundaryProfile.py: for visualising the topography at the domain boundaries.

 2. makeBoundary: for generating boundary condition files.

 3. slope.py: for measuring bed slope.

 4. specificPoints.py: for monitoring the solution process.

Instructions for managing a software environment for the utility scripts are given in the following sub-sections:

Requirements
============

To install fullSWOF-utils the following packages are required:

  * Git (https://git-scm.com/), the version control system.

  * Texinfo (https://www.gnu.org/software/texinfo/), the GNU documentation system.

Cloning
=======

FullSWOF-utils is maintained using git, the version control system.  A simple way to install the package is to clone the git repository.  To do so, first open a terminal window on a system that has git installed.  Then, from within a suitable working directory, execute the command:

     git clone https://cgit.tourbillion-technology.com/fullSWOF-utils

A directory named fullSWOF-utils will be created.  To complete the installation first change directory to the new fullSWOF-utils directory.  Then execute the command:

     make

This command will create the documentation for the package.  The documentation is available in two formats; GNU Info format and html. The info file is located in the doc directory.  The html files are located in the manual directory.  There are two versions. fullswof-utils.html contains the complete documentation set out on one page.  The subdirectory html_node contains a top-level index.html file and a separate page for each node.

The info file may be read using the info program.  The html files may be read using any web browser.

Uninstalling
============

All the files in the fullSWOF-utils package are installed under a single directory.  To uninstall the package it is sufficient to remove that directory.  For example, to remove a clone of the repository, first navigate to the directory on the system where the clone is located. Then execute the command:

     rm -rf fullSWOF-utils

Usage
*****

The programs provided in the fullSWOF-utils package are written in the python programming language.  Python version 3.0 or above is recommended.  See Runtime Dependencies for the python packages that are required by each program.

To run an individual program it is convenient to create a symbolic link to the corresponding file in the installation directory.  For example, from a suitable working directory, execute the following command to create a link to the makeBoundary program:

     ln -s /path/to/installation/directory/fullswof-utils/makeBoundary

Runtime Dependencies
====================

The fullSWOF-utils programs utilise functions provided by the Python Standard Library.  FullSWOF-utils will be able to access these functions on systems that have the python package installed.  In addition extra packages are required by the individual programs as follows:

boundaryProfile.py, makeBoundary, slope.py and specificPoints.py:

      1. Matplotlib (https://matplotlib.org/), a library for creating plots and visualisations in Python.

      2. NumPy (https://numpy.org/), a Python package for scientific computation.

Invoking makeBoundary
=====================

The makeBoundary program creates boundary condition files for the FullSWOF solver.  The command-line syntax is:

     ./makeBoundary boundary

where boundary is one of top, bottom, left and right.

There are five types of boundary condition that are recognised by the solver:

case 1
     imposed height condition

case 2
     wall condition

case 3
     Neumann condition

case 4
     periodic condition

case 5
     imposed discharge condition

Cases 1 and 5 are implemented in makeBoundary.  A height value and a discharge value are calculated for each cell along the boundary. At grid cells where the calculated values are zero the wall boundary condition, case 2, is applied.

Each time makeBoundary runs it reads two input files and produces one output file.  The first input file, named topography.txt, provides the height data.  This file is also used by FullSWOF to define the domain topography.  The file may be saved in the current working directory or, alternatively, a symbolic link to a file in an external directory may be created.  To create such a link use a command of the form:

     ln -s /path/to/topography/file topography.txt

The second input file is the boundary definition file.  This file specifies the boundary type, the global discharge across the boundary and the local gradient. Extra control parameters allow the global discharge to be split across separate regions.  Surface roughness may be defined for the each region individually.  See Boundary Definition File for details of the input parameters and the file format.

makeBoundary generates an output file in the format required by the FullSWOF solver.  Depending on the value of the boundary command-line option, the filename of the output file is one of BCTop.txt, BCBottom.txt, BCLeft.txt or BCRight.txt.

Boundary Definition File
------------------------

The boundary definition file contains a list of parameters that control the operation of the makeBoundary program.  The parameters are defined in the file as a sequence of ``key-value'' pairs. The key is the name of the variable.  Each key has an associated value. Each value is either a boolean (``True'' or ``False'') signifier, an integer or floating point number, or a list of integers or floating point numbers.  Keys and values are defined on the same line, separated by a colon.

The keys are defined as follows:

type
     boundary type (1=imposed height, 2=wall, 3=Neumann, 4=periodic, 5=imposed discharge).  For cases 1 and 5, the height and imposed discharge are both specified for each cell along the boundary.  For sub-critical inflow the type value (1 or 5) determines which of the specified values are used.  For super-critical inflow both values are used.  For super-critical outflow neither value is used.

plotting
     enable plotting (True or False).  The program can display plots of hydraulic radius, conveyance and discharge versus water level for each active panel.  To cycle through the plots press the q key.

printing
     enable printing (True or False).  The program can write output files containing data for the rating curve for each active panel. Rating curves express the relation between water level and discharge.

slope
     local gradient.  This is the value normal to the boundary, derived from survey data or from running the slope.py program.

target_flow
     imposed discharge (/m3/s).  This is the total flow crossing the boundary.

markers
     panel marker co-ordinates (/m).  This is a comma-separated list of distances.  The distances indicate the measurement from the left-hand edge of the domain to the internal marker points.  Markers at the corner points are automatically generated to complete the list.

panel
     fill order.  The fill order is a comma-separated list of panel indices.  The list specifies the manner in which the wetted area changes as the flow increases.

ztol
     channel overtopping tolerance (/m).  For the main channel, the overtopping tolerance sets the difference between the minimum ground elevation at the channel banks and the maximum water level.  When the flow is sufficiently high for the water level to reach this level the next panel, specified by the fill order, is activated.  This panel can then fill to the same maximum water level.  The panels are filled in sequence until one panel is part-filled so that the total flow across the boundary matches the target flow.

n_co
     Manning's n coefficients.  This is a comma-separated list, ordered by panel index.  Each panel is allocated a coefficient representing the roughness value for that section of the boundary.

numH
     number of height intervals.  The relation between water level and discharge is calculated at the specified number of points, for each active panel.

Comment lines are allowed in the boundary definition file.  Lines that start with the # character are treated as comments.

Invoking slope.py
=================

slope.py is an interactive program that is able to derive local gradient information from elevation data and user input.  The program reads the elevation data from the file topography.txt, which must be located in the working directory.  To start the program the command is:

     ./slope.py

The program responds with a request for user input:

     Locate markers (m), plot channel profile (p), save profile (s) or exit (q):

The derivation of the local gradient is a two-stage process.  Firstly, a series of markers are placed on opposite sides of the feature of interest.  For example, for a channel feature, markers are placed along the channel on either side.  Secondly, a best-fit curve is fitted to the data.  A plot is displayed and the gradient printed to standard output. Optionally, the one-dimensional elevation data may be saved to an output file.

A detailed description of the options follows:

m
     Locate markers.  slope.py opens a window that displays a contour plot of the elevation data on the left hand side and a contour plot of the derived slope on the right hand side.  The axes are labeled by cell index number.  A legend to the side of each plot shows the range of contour values.

     The user is required to identify marker locations by positioning the mouse pointer within the elevation plot and pressing the SPACE key.  The markers are entered in pairs, one on either side of the feature of interest.  To finish the sequence of marker pairs, the user is required to move the mouse pointer to a position outside the elevation plot and press the q key.

p
     Plot channel profile.  slope.py constructs a straight line between each pair of markers and calculates the location of the minimum elevation value along each line.  These locations form a channel ``centre-line''.  slope.py then uses a best-fit procedure to plot a straight line through the centre-line elevation data.  A new window opens to show the centre-line data and the best-fit line.  The gradient and intercept of the best-fit line are printed to standard output.

s
     Save profile.  The channel centre-line data is written to the file 1D.txt.  The file is formatted in the FullSWOF xyz format.

q
     Quit slope.py.

Theory
******

The values of discharge and height calculated by the makeBoundary program are based on a one-dimensional analysis of friction loss in channels.  The formulae applied are Manning's equation and the continuity equation.  A summary of the background theory is given in the Fluvial Design Guide (See Section 7.4 Fundamental hydraulic principles (http://evidence.environment-agency.gov.uk/FCERM/en/FluvialDesignGuide/Chapter7.aspx?pagenum=4).) published by the Environment Agency.

In makeBoundary the one-dimensional analysis is implemented in a series of steps.  The first step identifies the number of regions, or ''panels'', that make up the boundary.  The markers at the start and end of each panel are listed in the boundary definition file (see Boundary Definition File).  In the next step the minimum and maximum heights are established for each panel.  The minimum height is the height at the bottom of the channel.  The maximum height is the height at which overtopping starts to occur.

The next step is to generate a rating curve for each panel.  The rating curve relates the discharge Q to surface elevation h for the steady flow condition.  The discharge is defined by the continuity equation:

     Q = A V

where A is the cross-sectional area of the flow and V is the flow velocity.  For the case of channel flow, V is given by Manning's equation:

     V = (1/n) R2/3 S1/2

where n is the Manning coefficient of roughness, R is the hydraulic radius and S is the friction slope.  The hydraulic radius is the ratio of the cross-sectional area A to the wetted perimeter of the channel P.  The friction slope is taken to be equal to the slope of the channel bed for the case of steady flow.

It is convenient to introduce the term conveyance to directly relate the discharge to the slope.  The conveyance K is given by the expression

     K = A (1/n) R2/3.

Discharge and slope are then related by the expression

     Q = K S1/2.

In order to generate data for the rating curves the conveyance and discharge are calculated for a set of water levels for each panel.  The set of levels spans the range between the minimum height and the maximum height.  At each level the wetted perimeter and the cross-sectional area are calculated.  From these values the hydraulic radius is calculated, allowing the conveyance to be determined.  Finally, the discharge is calculated from the conveyance.

Figure: Rating curve for the right hand panel of the top boundary.

An example rating curve is shown in ratingCurve.  The data for this curve was generated from the topography and boundary definition file provided in the demo directory.

Together, the rating curves establish the connection between water level and discharge at the boundary.  The makeBoundary program identifies the panels that are filled and the panel that is part-filled. The discharge in the part-filled panel is set so that the sum of the discharge values is equal to the target flow.  The last step is to interpolate the water level from the rating curve of the part-filled panel.

Demos
*****

Examples of input files that demonstrate how to use FullSWOF-utils programs are included in the demo directory.  Sample height data, in the file topography.txt, is also provided.

To run the demos directly, first change the current working directory to the demo directory.  Then execute the individual program (see Usage for the command line syntax).

The input files for makeBoundary may be viewed with a text editor.  To experiment with the control parameters, first back up the distributed input files and then edit the parameter values as desired. Note that the makeBoundary program will overwrite its output file if it already exists.

Running slope.py provides an opportunity to test the effect of marker positioning.  Contour plots of elevation and slope are displayed when the m key is pressed.  The elevation contour plot allows the feature of interest to be identified.  Markers are placed in pairs on either side of the channel feature.  An example of a set of marker pairs is shown in markers.

Figure: Contour plots of elevation (left) and slope (right).  Feature markers are shown as red disks.

slope.py draws a straight line between each pair of markers. A search procedure reveals the position along each line at which the elevation is a minimum.  The set of minumum positions identifies the centre-line of the channel.  The profile of the channel is plotted and displayed when the p key is pressed.  The profile calculated from the example set of marker pairs is shown in profile.

Figure: Elevation plotted against distance from bottom boundary.

The blue line in profile shows the height variation of the channel centre-line.  The best-fit line is shown by the dashed red line. The gradient of the best-fit line and the intercept on the y-axis are printed to standard output.  The data points that define the blue line are written to the file 1D.txt when the s key is pressed. The file is overwritten if it already exists.

GNU Free Documentation License
******************************

     [file fdl-1.3.texi not included]