source: documentation/simple_example.tex @ 2264

\documentclass{article}

\title{A Simple Example}
%\author{Howard Silcock}

% Can we get rid of indenting and put a blank line before each para?
% Find out how to change date format
% Relabel sections, subsections

\setlength{\parindent}{0mm} %\setlength{\parskip}{3pt}
\setlength{\oddsidemargin}{0.6in}\setlength{\evensidemargin}{0.6in}
\addtolength{\textheight}{1in} \addtolength{\textwidth}{0.5in}
\setlength{\marginparwidth}{0in}
\setlength{\topmargin}{0mm}\setlength{\headheight}{0in}

\begin{document}

\maketitle

%\section*{Discussion of a Simple Example}

This is a discussion of the structure and operation of the file
\texttt{bedslope.py}, with just enough detail to allow the reader
to appreciate what's involved in setting up a scenario like the
one it depicts.


\subsection*{Overview}

This example carries out the solution of the shallow-water wave
equation in the simple case of a configuration comprising a flat
bed, sloping at a fixed angle in one direction and having a
constant depth across each line in the perpendicular direction.

The quantities involved in the problem are:
\begin{itemize}
   \item elevation
   \item friction
   \item depth
   \item stage
\end{itemize}

\emph{[More details of the problem background]}

\subsection*{Outline of the Program}

In outline, \texttt{bedslope.py} performs the following steps:

\begin{enumerate}

   \item Sets up a
triangular mesh.

   \item Sets certain parameters governing the mode of
operation of the model-specifying, for instance, whether the
output is to be `smoothed'.

   \item Inputs various quantities describing physical measurements, such
as the elevation, to be specified at each mesh point.

   \item Sets up the boundary conditions.

   \item Carries out the evolution of the model through a series of time
steps and outputs the results, providing a results file that can
be visualised.

\end{enumerate}


\subsection*{Establishing the Mesh}

The first task is to set up the triangular mesh to be used for the
scenario. This is carried out through the statement:

\begin{verbatim}
    points, vertices, boundary = rectangular(10, 10) .
\end{verbatim}

The function \texttt{rectangular} is imported from a module
\texttt{mesh\_factory} defined elsewhere. (AnuGA also contains
several other schemes that can be used for setting up meshes, but
we shall not discuss these now.) The above assignment sets up a
$10 \times 10$ rectangular mesh, triangulated in a specific way.
In general, the assignment

\begin{verbatim}
    points, vertices, boundary = rectangular(m, n)
\end{verbatim}

returns:

\begin{itemize}

   \item a list \texttt{points} of length $N$, where $N = (m + 1)(n + 1)$,
comprising the coordinates $(x, y)$ of each of the $N$ mesh
points,

   \item a list \texttt{vertices} of length $2mn$ (each entry specifies the three
vertices of one of the triangles used in the triangulation) , and

   \item a dictionary \texttt{boundary}, used to tag the triangle edges on
the boundaries. Each key corresponds to a triangle edge on one of
the four boundaries and its value is one of \texttt{`left'},
\texttt{`right'}, \texttt{`top'} and \texttt{`bottom'}, indicating
which boundary the edge in question belongs to.

\end{itemize}


\subsection*{Initialising the domain}

These variables are then used to set up a data structure domain,
through the assignment:

\begin{verbatim}
    domain = Domain(points, vertices, boundary)
\end{verbatim}

This uses a Python class \texttt{Domain}, imported from
\texttt{shallow\_water}, which is an extension of a more generic
class of the same name in the module \texttt{domain}, and inherits
some methods from the generic class but has others specific to the
shallow-water scenarios in which it is used. The following lines
set certain key options governing the domain: \emph{[more details
of what these do]}

\begin{verbatim}
    domain.smooth = False
    domain.visualise = False
    domain.store = True
    domain.filename = 'bedslope'
    domain.default_order = 2
\end{verbatim}


\subsection*{Specifying the Quantities}

The next task is to specify a number of quantities that we wish to
set for each mesh point. The class \texttt{Domain} has a method
\texttt{set\_quantity}, used to specify these quantities. It is a
particularly flexible method that allows the user to set
quantities in a variety of ways---using constants, functions,
numeric arrays or expressions involving other quantities, all of
which can be passed as arguments. The code in the present example
demonstrates a number of forms in which we can invoke
\texttt{set\_quantity}.


\subsubsection*{Elevation}

The elevation is set using a function, defined through the
statements below, which is specific to this example and specifies
a particularly simple initial configuration for demonstration
purposes:

\begin{verbatim}
    \# Initial conditions
    def f(x,y):
        return -x/2
\end{verbatim}

This simply associates an elevation with each point $(x, y)$ of
the plane.  It specifies that the bed slopes linearly in the $x$
direction, with slope $-\frac{1}{2}$,  and is constant in the $y$
direction. %[screen shot?]\\
\\
Once the function $f$ is specified, the quantity is assigned
through the simple statement:

\begin{verbatim}
    domain.set_quantity('elevation', f)
\end{verbatim}


\subsubsection*{Friction}

The assignment of the friction quantity demonstrates another way
we can use \texttt{set\_quantity} to set quantities---namely,
assign them to a constant numerical value:

\begin{verbatim}
    domain.set_quantity('friction', 0.1)
\end{verbatim}

This just specifies that the Manning friction coefficient is set
to 0.1 at every mesh point.

\subsubsection*{Depth}

Assigning depth illustrates a more complex way to use
\texttt{set\_quantity}, introducing an expression involving other
quantities:

\begin{verbatim}
    h = 0.05 \# Constant depth
    domain.set_quantity('stage', expression = 'elevation + %f' %h)
\end{verbatim}

Here the quantity \texttt{stage} is defined by taking the quantity
elevation already defined and adding a constant value $h = 0.05$
to it everywhere. This expresses the fact that the water depth is
everywhere constant, so the surface is a constant height above the
elevation of the bed.

\subsubsection*{Boundary Conditions}

The boundary conditions are specified as follows:

\begin{verbatim}
    Br = Reflective_boundary(domain)

    Bt = Transmissive_boundary(domain)

    Bd = Dirichlet_boundary([0.2,0.,0.])

    Bw = Time_boundary(domain=domain,
                f=lambda t: [(0.1*sin(t*2*pi)), 0.0, 0.0])
\end{verbatim}

The effect of these statements is to set up four alternative
boundary conditions and store them in variables that can be
assigned as needed. Each boundary condition specifies the
behaviour at a boundary in terms of the behaviour in neighbouring
elements. The boundary conditions may be briefly described as
follows:

\begin{description}
    \item[Reflective boundary]Returns same conserved
quantities as those present in its neighbour volume but reflected.
Specific to the shallow water equation as it works with the
momentum quantities assumed to be the second and third conserved
quantities.
    \item[Transmissive boundary]\emph{[Need to add some suitable text
here]}
    \item[Dirichlet boundary]Specifies a fixed value at the
boundary.
    \item[Time boundary.]A Dirichlet boundary whose behaviour varies with time.
\end{description}

Once the four boundary types have been specified through the
statements above, they can be applied through a statement of the
form

\begin{verbatim}
    domain.set_boundary({'left': Bd, 'right': Br, 'top': Br, 'bottom':
Br})
\end{verbatim}

This statement stipulates that, in the current example, the left
boundary is fixed, with an elevation of 0.2, while the other
boundaries are all reflective.


\subsection*{Evolution}

The final statement
\nopagebreak[3]
\begin{verbatim}
    for t in domain.evolve(yieldstep = 0.1, finaltime = 4.0):
        domain.write_time()
\end{verbatim}

is the key step that causes the configuration of the domain to
`evolve' in accordance with the model embodied in the code, over a
series of steps indicated by the values of \texttt{yieldstep} and
\texttt{finaltime}, which can be altered as required.


\subsection*{Output}

%Give details here of the form of the output and explain how it can
%be used with swollen. Include screen shots.//

The output is a NetCDF file with the extension \texttt{.sww}. It
contains stage and momentum information and can be used with the
\texttt{swollen} package to generate a visual display.


\subsection*{How to Run the Code}

The code can be run in various ways:

\begin{itemize}
\item{from a Windows command line}

\item{within the Python IDLE environment}

\item{within emacs}

\item{from a Linux command line}
\end{itemize}

\end{document}