doc: Add theory chapter.

* doc/fullswof-utils.texi (Theory): New chapter.

1 files changed, 69 insertions, 0 deletions

diff --git a/doc/fullswof-utils.texi b/doc/fullswof-utils.texi
index 8145934..03e5e9d 100644
--- a/doc/fullswof-utils.texi
+++ b/doc/fullswof-utils.texi
@@ -46,6 +46,7 @@ Utility scripts for the FullSWOF shallow flow solver
 @menu
 * Installation::                Installing FullSWOF-utils.
 * Usage::
+* Theory::
 * Demos::
 * GNU Free Documentation License::  The license of this manual.
 * Index::                       Complete Index.
@@ -368,6 +369,74 @@ format.
 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 curve the conveyance and
+discharge are calculated for a set of water levels within the minimum to
+maximum range.  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.
+
 @node Demos, GNU Free Documentation License, Boundary Definition File, Top
 @comment  node-name,  next,  previous,  up
 @chapter Demos