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

@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 http://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/python/makeBoundary
@end example

@menu
* Runtime Dependencies::
* Invoking makeBoundary::
* Invoking slope.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 makeBoundary:
@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

@item slope.py:
@enumerate
@item
Matplotlib.

@item
NumPy.
@end enumerate

@end table

@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)

@item plotting
enable plotting (True or False)

@item printing
enable printing (True or False)

@item slope
local gradient

@item target_flow
imposed discharge (flow across boundary /@math{m@sup{3}/s})

@item markers
panel marker co-ordinates (comma-separated list of distances /m)

@item panel
fill order (comma-separated list of panel indices)

@item ztol
channel overtopping tolerance (/m)

@item n_co
Manning's n coefficients (comma-separated list, ordered by panel index)

@item numH
number of height intervals
@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 slope.py

@command{slope.py} is an interactive program that is able to derive
local gradient information from elevation data and user input.  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 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: