path: root/doc/fullswof-utils.texi

\input texinfo

@comment %**start of header
@settitle FullSWOF-utils Reference Manual
@syncodeindex pg cp
@comment %**end of header

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

Copyright @copyright{} 2019, 2020, 2021, 2022 Paul Garlick.

@quotation
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''.
@end quotation
@end copying

@dircategory Science
@direntry
* FullSWOF-utils: (FullSWOF-utils). Utility programs for the FullSWOF solver.
@end direntry

@titlepage
@title FullSWOF-utils Reference Manual
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@contents

@ifnottex
@node Top
@top FullSWOF-utils

Utility scripts for the FullSWOF shallow flow solver
@end ifnottex


@menu
* Installation::                Installing FullSWOF-utils.
* Usage::
* Theory::
* Demos::
* GNU Free Documentation License::  The license of this manual.
* Index::                       Complete Index.
@end menu

@node Installation, Usage, Top, Top
@comment  node-name,  next,  previous,  up
@chapter Installation

@cindex chapter, installation

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

The package contains the following utility scripts:

@enumerate
@item
@strong{boundaryProfile.py:} for visualising the topography at the
domain boundaries.

@item
@strong{makeBoundary:} for generating boundary condition files.

@item
@strong{slope.py:} for measuring bed slope.

@item
@strong{specificPoints.py:} for monitoring the solution process.
@end enumerate

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

@menu
* Requirements::
* Cloning::
* Uninstalling::
@end menu

@node Requirements, Cloning, Installation, Installation
@comment  node-name,  next,  previous,  up
@section Requirements

To install @emph{fullSWOF-utils} the following packages are required:

@itemize
@item
@url{https://git-scm.com/, Git}, the version control system.

@item
@url{https://www.gnu.org/software/texinfo/, Texinfo}, the GNU
documentation system.
@end itemize


@node Cloning, Uninstalling, Requirements, Installation
@comment  node-name,  next,  previous,  up
@section 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:

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

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

@example
make
@end example

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.
@emph{fullswof-utils.html} contains the complete documentation set out
on one page.  The subdirectory @emph{html_node} contains a top-level
@emph{index.html} file and a separate page for each node.

The info file may be read using the @command{info} program.  The html
files may be read using any web browser.

@node Uninstalling,  , Cloning, Installation
@comment  node-name,  next,  previous,  up
@section Uninstalling

All the files in the @emph{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:

@example
rm -rf fullSWOF-utils
@end example

@node Usage, GNU Free Documentation License, Installation, Top
@comment  node-name,  next,  previous,  up
@chapter Usage

The programs provided in the @emph{fullSWOF-utils} package are written
in the @emph{python} programming language.  Python version 3.0 or above
is recommended.  @xref{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 @emph{makeBoundary} program:

@example
ln -s /path/to/installation/directory/fullswof-utils/makeBoundary
@end example

@menu
* Runtime Dependencies::
* Invoking boundaryProfile.py::
* Invoking makeBoundary::
* Invoking slope.py::
* Invoking specificPoints.py::
@end menu


@node Runtime Dependencies,  , Usage, Usage
@comment  node-name,  next,  previous,  up
@section Runtime Dependencies

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

@table @command
@item boundaryProfile.py, makeBoundary, slope.py and specificPoints.py:
@enumerate
@item
@url{https://matplotlib.org/, Matplotlib}, a library for
creating plots and visualisations in Python.

@item
@url{https://numpy.org/, NumPy}, a Python package for scientific
computation.
@end enumerate

@end table

@node Invoking boundaryProfile.py, Invoking makeBoundary, Runtime Dependencies, Usage
@comment  node-name,  next,  previous,  up
@section Invoking @command{boundaryProfile.py}
The @command{boundaryProfile.py} program plots a cross-section through
the topography at the specified boundary.  The command-line syntax is:

@example
./boundaryProfile.py @option{boundary}
@end example

where @option{boundary} is one of @code{top}, @code{bottom}, @code{left}
and @code{right}.

The program reads an input file that contains the local height data.  As
a pre-requisite step the input file must be extracted from the global
@code{xyz} file.  A standard utility such as @command{awk} may be used.
The input filename must be one of
@code{(top|bottom|left|right)_boundary.txt}.

Elevation at the specified boundary is plotted against distance.  The
colour of the curve denotes the boundary; the @code{top} boundary is
blue, the @code{bottom} boundary is green, the @code{left} boundary is
red and the @code{right} boundary is orange.


@node Invoking makeBoundary,  , Runtime Dependencies, Usage
@comment  node-name,  next,  previous,  up
@section Invoking @command{makeBoundary}

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

@example
./makeBoundary @option{boundary}
@end example

where @option{boundary} is one of @code{top}, @code{bottom}, @code{left}
and @code{right}.  

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

@table @asis
@item case 1
imposed height condition

@item case 2
wall condition

@item case 3
Neumann condition

@item case 4
periodic condition

@item case 5
imposed discharge condition
@end table

Cases 1 and 5 are implemented in @emph{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 @command{makeBoundary} runs it reads two input files and
produces one output file.  The first input file, named
@file{topography.txt}, provides the height data.  This file is also used
by @emph{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:

@example
ln -s /path/to/topography/file topography.txt
@end example

The second input file is the @emph{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.  @xref{Boundary Definition
File} for details of the input parameters and the file format.

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

@menu
* Boundary Definition File::
@end menu

@node Boundary Definition File, GNU Free Documentation License, Invoking makeBoundary, Invoking makeBoundary
@comment  node-name,  next,  previous,  up
@subsection Boundary Definition File

The @emph{boundary definition file} contains a list of parameters that
control the operation of the @emph{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:

@table @asis
@item 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.

@item 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 @samp{q} key.

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

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

@item target_flow
imposed discharge (/@math{m@sup{3}/s}).  This is the total flow
crossing the boundary.

@item 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.

@item 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.

@item 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.

@item n_co
Manning's @samp{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.

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

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

@node Invoking slope.py, Demos, Boundary Definition File, Usage
@comment  node-name,  next,  previous,  up
@section Invoking @command{slope.py}

@command{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 @file{topography.txt},
which must be located in the working directory.  To start the program
the command is:

@example
./slope.py
@end example

The program responds with a request for user input:

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

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:

@table @samp
@item m
Locate markers.  @command{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 @key{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 @kbd{q} key.

@item p
Plot channel profile.  @command{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''.  @command{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.

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

@item q
Quit @command{slope.py}.
@end table

@node Invoking specificPoints.py, Theory, Invoking slope.py, Usage
@comment  node-name,  next,  previous,  up
@section Invoking @command{specificPoints.py}

After the solution procedure has finished the
@command{specificPoints.py} script may be used to display the
convergence history.  The script may also be used to monitor the
computation while it is underway.

The script reads the @file{hu_specific_points.dat} file.  This file
contains the solution variables sampled at the monitoring point.  The
location of the monitoring point is specified in the
@file{Inputs/parameters.txt} file.

The script is executed from the @file{Outputs} directory.  The
command-line syntax is:

@example
./specificPoints.py
@end example

Water elevation at the monitoring point is plotted against simulated
time.  In order to re-read the file and update the plot press the
@kbd{x} key.

@node Theory, Demos, Invoking slope.py, Top
@comment  node-name,  next,  previous,  up
@chapter Theory

The values of discharge and height calculated by the @emph{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
@cite{Fluvial Design Guide}@footnote{See
@url{http://evidence.environment-agency.gov.uk/FCERM/en/FluvialDesignGuide/Chapter7.aspx?pagenum=4,
Section 7.4 Fundamental hydraulic principles}.} published by the
Environment Agency.

In @emph{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
(@pxref{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 @emph{rating curve} for each panel.  The
rating curve relates the discharge @emph{Q} to surface elevation
@emph{h} for the steady flow condition.  The discharge is defined by the
continuity equation:

@indentedblock
  @math{Q = A V}
@end indentedblock

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

@indentedblock
  @math{V = (1/n) R@sup{2/3} S@sup{1/2}}
@end indentedblock

@noindent
where @emph{n} is the Manning coefficient of roughness, @emph{R} is the
hydraulic radius and @emph{S} is the friction slope.  The hydraulic
radius is the ratio of the cross-sectional area @emph{A} to the wetted
perimeter of the channel @emph{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 @emph{conveyance} to directly
relate the discharge to the slope.  The conveyance @emph{K} is given by
the expression

@indentedblock
  @math{K = A (1/n) R@sup{2/3}}.
@end indentedblock

Discharge and slope are then related by the expression

@indentedblock
  @math{Q = K S@sup{1/2}}.
@end indentedblock

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.

@float Figure,ratingCurve
  @image{./images/rating_curve}
  @caption{Rating curve for the right hand panel of the top boundary.}
@end float

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

Together, the rating curves establish the connection between water level
and discharge at the boundary.  The @emph{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.

@node Demos, GNU Free Documentation License, Boundary Definition File, Top
@comment  node-name,  next,  previous,  up
@chapter Demos

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

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

The input files for @command{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 @command{makeBoundary} program will overwrite its output
file if it already exists.

Running @command{slope.py} provides an opportunity to test the effect of
marker positioning.  Contour plots of elevation and slope are displayed
when the @kbd{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 @ref{markers}.

@float Figure,markers
  @image{./images/markers}
  @caption{Contour plots of elevation (left) and slope (right).  Feature markers are shown as red disks.}
@end float

@command{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 @kbd{p} key is pressed.  The profile calculated from
the example set of marker pairs is shown in @ref{profile}.

@float Figure,profile
  @image{./images/profile}
  @caption{Elevation plotted against distance from bottom boundary.}
@end float

The blue line in @ref{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 @file{1D.txt} when the @kbd{s} key is pressed.
The file is overwritten if it already exists.

@node GNU Free Documentation License, Index, Usage, Top
@appendix GNU Free Documentation License
@include fdl-1.3.texi

@node Index,  , GNU Free Documentation License, Top
@unnumbered Index
@printindex cp

@bye

Local Variables:
mode: texinfo
eval: (outline-minor-mode)
TeX-master: t
End: