Index: /anuga_work/publications/linuxconf_2006/paper_ole_nielsen.tex
===================================================================
--- /anuga_work/publications/linuxconf_2006/paper_ole_nielsen.tex	(revision 4115)
+++ /anuga_work/publications/linuxconf_2006/paper_ole_nielsen.tex	(revision 4115)
@@ -0,0 +1,463 @@
+% Use the standard \LaTeXe\ article style in 12pt Computer Modern font
+% on A4 paper by
+\documentclass[12pt,a4paper]{article}
+% Do \emph{not} change the width nor the height of the text from the
+% defaults set by this document class.
+%
+% The alternative which is closer to what we actually use is
+% \documentclass[11pt,a5paper]{article}
+% \usepackage[a5paper]{geometry}
+% Because it is a great size for on screen reading
+% and prints nicely on a4paper either 2up or booklet.
+
+% The preamble is to contain your own \LaTeX\ commands and to say
+% what packages to use.  Three useful packages are the following:
+\usepackage{graphicx} % avoid epsfig or earlier such packages
+\usepackage{url}      % for URLs and DOIs
+\newcommand{\doi}[1]{\url{http://dx.doi.org/#1}}
+\usepackage{amsmath}  % many want amsmath extensions
+\usepackage{amsfonts}
+\usepackage{underscore}
+% Avoid loading unused packages (as done by some \LaTeX\ editors).
+
+% Create title and authors using \verb|\maketitle|.  Separate authors by
+% \verb|\and| and put addresses in \verb|\thanks| command with
+% \verb|\url| command \verb|\protect|ed.
+\title{Open Source Software for Computational Modelling of Fluid Flow}
+
+\author{
+O.~M.~Nielsen\thanks{Risk Assessment Methods Project, Geospatial and
+Earth Monitoring Division, Geoscience Australia, Symonston,
+\textsc{Australia}. \protect\url{mailto:Ole.Nielsen@ga.gov.au}} 
+\and
+S.~G.~Roberts\thanks{Dept. of Maths, Australian National University,
+Canberra, \textsc{Australia}. \protect\url{mailto:stephen.roberts}}}
+
+\date{30 December 2006}
+
+\newcommand{\AnuGA}{\textsc{Anuga}}
+\newcommand{\Python}{\textsc{Python}}
+\newcommand{\VPython}{\textsc{VPython}}
+\newcommand{\pypar}{\textsc{mpi}}
+\newcommand{\Metis}{\textsc{Metis}}
+\newcommand{\mpi}{\textsc{mpi}}
+
+\newcommand{\UU}{\mathbf{U}}
+\newcommand{\VV}{\mathbf{V}}
+\newcommand{\EE}{\mathbf{E}}
+\newcommand{\GG}{\mathbf{G}}
+\newcommand{\FF}{\mathbf{F}}
+\newcommand{\HH}{\mathbf{H}}
+\newcommand{\SSS}{\mathbf{S}}
+\newcommand{\nn}{\mathbf{n}}
+
+\newcommand{\code}[1]{\texttt{#1}}
+
+
+%\graphicspath{{../Figures/}}
+
+\begin{document}
+
+% Use default \verb|\maketitle|.
+\maketitle
+
+% Use the \verb|abstract| environment.
+\begin{abstract}
+Geoscience Australia and the Australian National University are
+developing a hydrodynamic inundation modelling tool called \AnuGA{}
+to help simulate the impact of natural inundation hazards such as
+riverine flooding, storm surges and tsunami. The core of \AnuGA{} is
+a \Python{} implementation of a finite-volume method for solving the
+conservative form of the Shallow Water Wave equation.  In this paper
+we describe the parallelisation of the code using a domain
+decomposition strategy. We describe the use of the the \Metis{}
+graph partitioning library to decompose our finite volume meshes.
+The parallel efficiency of our code is tested using a number of mesh
+partitions, and we verify that the \Metis{} graph partition is
+particularly efficient.
+\end{abstract}
+
+% By default we include a table of contents in each paper.
+\tableofcontents
+
+% Use \verb|\section|, \verb|\subsection|, \verb|\subsubsection| and
+% possibly \verb|\paragraph| to structure your document.  Make sure
+% you \verb|\label| them for cross-referencing with \verb|\ref|\,.
+\section{Introduction}
+\label{sec:intro}
+
+%Floods are the single greatest cause of death due to natural hazards
+%in Australia, causing almost 40{\%} of the fatalities recorded
+%between 1788 and 2003~\cite{Blong-2005}. Analysis of buildings
+%damaged between 1900 and 2003 suggests that 93.6{\%} of damage is
+%the result of meteorological hazards, of which almost 25{\%} is
+%directly attributable to flooding~\cite{Blong-2005}.
+
+Flooding of coastal communities may result from surges of near-shore
+waters caused by severe storms. The extent of inundation is
+critically linked to tidal conditions, bathymetry and topography; as
+recently exemplified in the United States by Hurricane Katrina.
+While the scale of the impact from such events is not common, the
+preferential development of Australian coastal corridors means that
+storm-surge inundation of even a few hundred metres beyond the
+shoreline has increased potential to cause significant disruption
+and loss.
+
+Coastal communities also face the small but real risk of tsunami.
+Fortunately, catastrophic tsunami of the scale of the 26 December
+2004 event are exceedingly rare. However, smaller-scale tsunami are
+more common and regularly threaten coastal communities around the
+world. Earthquakes which occur in the Java Trench near Indonesia
+(e.g.~\cite{TsuMIS1995}) and along the Puysegur Ridge to the south
+of New Zealand (e.g.~\cite{LebKC1998}) have potential to generate
+tsunami that may threaten Australia's northwestern and southeastern
+coastlines.
+
+Hydrodynamic modelling allows flooding, storm-surge and tsunami
+hazards to be better understood, their impacts to be anticipated
+and, with appropriate planning, their effects to be mitigated.
+Geoscience Australia in collaboration with the Mathematical Sciences
+Institute, Australian National University, is developing a software
+application called \AnuGA{} to model the hydrodynamics of floods,
+storm surges and tsunami. These hazards are modelled using the
+conservative shallow water equations which are described in
+section~\ref{sec:model}. In \AnuGA{} these equations are solved
+using a finite volume method as described in section~\ref{sec:fvm}.
+A more complete discussion of the method can be found in
+\cite{modsim2005} where the model and solution technique is
+validated on a standard tsunami benchmark data set.
+
+In this paper we will provide a description of the parallelisation
+of the code using a domain decomposition strategy and provide the
+preliminary timing results which verify the scalability of the
+parallel code.
+
+
+
+\section{Model}
+\label{sec:model}
+
+The shallow water wave equations are a system of differential
+conservation equations which describe the flow of a thin layer of
+fluid over terrain. The form of the equations are:
+\[
+\frac{\partial \UU}{\partial t}+\frac{\partial \EE}{\partial
+x}+\frac{\partial \GG}{\partial y}=\SSS
+\]
+where $\UU=\left[ {{\begin{array}{*{20}c}
+ h & {uh} & {vh} \\
+\end{array} }} \right]^T$ is the vector of conserved quantities; water depth
+$h$, $x$ momentum $uh$ and $y$ momentum $vh$. Other quantities
+entering the system are bed elevation $z$ and stage (absolute water
+level) $w$, where the relation $w = z + h$ holds true at all times.
+The fluxes in the $x$ and $y$ directions, $\EE$ and $\GG$ are given
+by
+\[
+\EE=\left[ {{\begin{array}{*{20}c}
+ {uh} \hfill \\
+ {u^2h+gh^2/2} \hfill \\
+ {uvh} \hfill \\
+\end{array} }} \right]\mbox{ and }\GG=\left[ {{\begin{array}{*{20}c}
+ {vh} \hfill \\
+ {vuh} \hfill \\
+ {v^2h+gh^2/2} \hfill \\
+\end{array} }} \right]
+\]
+and the source term (which includes gravity and friction) is given
+by
+\[
+\SSS=\left[ {{\begin{array}{*{20}c}
+ 0 \hfill \\
+ -{gh(z_{x} + S_{fx} )} \hfill \\
+ -{gh(z_{y} + S_{fy} )} \hfill \\
+\end{array} }} \right]
+\]
+where $S_f$ is the bed friction. The friction term is modelled using
+Manning's resistance law
+\[
+S_{fx} =\frac{u\eta ^2\sqrt {u^2+v^2} }{h^{4/3}}\mbox{ and }S_{fy}
+=\frac{v\eta ^2\sqrt {u^2+v^2} }{h^{4/3}}
+\]
+in which $\eta$ is the Manning resistance coefficient.
+
+As demonstrated in our papers, \cite{modsim2005,Rob99l} these
+equations provide an excellent model of flows associated with
+inundation such as dam breaks and tsunamis.
+
+\section{Finite Volume Method}
+\label{sec:fvm}
+
+We use a finite-volume method for solving the shallow water wave
+equations \cite{Rob99l}. The study area is represented by a mesh of
+triangular cells as in Figure~\ref{fig:mesh} in which the conserved
+quantities of  water depth $h$, and horizontal momentum $(uh, vh)$,
+in each volume are to be determined. The size of the triangles may
+be varied within the mesh to allow greater resolution in regions of
+particular interest.
+
+\begin{figure}
+\begin{center}
+\includegraphics[width=5.0cm,keepaspectratio=true]{step-five}
+\caption{Triangular mesh used in our finite volume method. Conserved
+quantities $h$, $uh$ and $vh$ are associated with the centroid of
+each triangular cell.} \label{fig:mesh}
+\end{center}
+\end{figure}
+
+The equations constituting the finite-volume method are obtained by
+integrating the differential conservation equations over each
+triangular cell of the mesh. Introducing some notation we use $i$ to
+refer to the $i$th triangular cell $T_i$, and ${\cal N}(i)$ to the
+set of indices referring to the cells neighbouring the $i$th cell.
+Then $A_i$ is the area of the $i$th triangular cell and $l_{ij}$ is
+the length of the edge between the $i$th and $j$th cells.
+
+By applying the divergence theorem we obtain for each volume an
+equation which describes the rate of change of the average of the
+conserved quantities within each cell, in terms of the fluxes across
+the edges of the cells and the effect of the source terms. In
+particular, rate equations associated with each cell have the form
+$$
+ \frac{d\UU_i }{dt}+ \frac1{A_i}\sum\limits_{j\in{\cal N}(i)} \HH_{ij} l_{ij} = \SSS_i
+$$
+where
+\begin{itemize}
+\item $\UU_i$ the vector of conserved quantities averaged over the $i$th cell,
+\item $\SSS_i$ is the source term associated with the $i$th cell,
+and
+\item $\HH_{ij}$ is the outward normal flux of
+material across the \textit{ij}th edge.
+\end{itemize}
+
+
+%\item $l_{ij}$ is the length of the edge between the $i$th and $j$th
+%cells
+%\item $m_{ij}$ is the midpoint of
+%the \textit{ij}th edge,
+%\item
+%$\mathbf{n}_{ij} = (n_{ij,1} , n_{ij,2})$is the outward pointing
+%normal along the \textit{ij}th edge, and The
+
+The flux $\HH_{ij}$ is evaluated using a numerical flux function
+$\HH(\cdot, \cdot ; \ \cdot)$ which is consistent with the shallow
+water flux in the sense that for all vectors $\UU$ and $\nn$
+$$
+H(\UU,\UU;\ \nn) = \EE(\UU) n_1 + \GG(\UU) n_2 .
+$$
+
+Then
+$$
+\HH_{ij}  = \HH(\overline{\UU}_i(m_{ij})),
+\overline{\UU}_i(m_{ij})), \mathbf{n}_{ij})
+$$
+where $m_{ij}$ is the midpoint of the \textit{ij}th edge and
+$\mathbf{n}_{ij}$ is the outward pointing normal on the
+\textit{ij}th edge. The function $\overline{\UU}_i(x)$ for $x \in
+T_i$ is obtained from the average values, $\UU_i$, of the $i$th and
+neighbouring  cells.
+
+We use a second order reconstruction to produce a piece-wise linear
+function construction of the conserved quantities for  all $x \in
+T_i$ for each cell (see Figure~\ref{fig:mesh:reconstruct}. This
+function is allowed to be discontinuous across the edges of the
+cells, but the slope of this function is limited to avoid
+artificially introduced oscillations.
+
+Godunov's method (see \cite{Toro-92}) involves calculating the
+numerical flux function $\HH(\cdot, \cdot ; \ \cdot)$ by exactly
+solving the corresponding one dimensional Riemann problem normal to
+the edge. We use the central-upwind scheme of \cite{KurNP2001} to
+calculate an approximation of the flux across each edge.
+
+\begin{figure}
+\begin{center}
+\includegraphics[width=5.0cm,keepaspectratio=true]{step-reconstruct}
+\caption{From the values of the conserved quantities at the centroid
+of the cell and its neighbouring cells, a discontinuous piecewise
+linear reconstruction of the conserved quantities is obtained.}
+\label{fig:mesh:reconstruct}
+\end{center}
+\end{figure}
+
+
+
+
+
+In the computations presented in this paper we use an explicit Euler
+time stepping method with variable timestepping adapted to the
+observed CFL condition.
+
+
+
+
+
+
+
+\section{Validation}
+\label{sec:validation} The process of validating the \AnuGA{}
+application is in its early stages, however initial indications are
+encouraging.
+
+As part of the Third International Workshop on Long-wave Runup
+Models in 2004 (\url{http://www.cee.cornell.edu/longwave}), four
+benchmark problems were specified to allow the comparison of
+numerical, analytical and physical models with laboratory and field
+data. One of these problems describes a wave tank simulation of the
+1993 Okushiri Island tsunami off Hokkaido, Japan \cite{MatH2001}. A
+significant feature of this tsunami was a maximum run-up of 32~m
+observed at the head of the Monai Valley. This run-up was not
+uniform along the coast and is thought to have resulted from a
+particular topographic effect. Among other features, simulations of
+the Hokkaido tsunami should capture this run-up phenomenon.
+
+\begin{figure}[htbp]
+\centerline{\includegraphics[width=4in]{tsunami-fig-3.eps}}
+\caption{Comparison of wave tank and \AnuGA{} water stages at gauge
+5.}\label{fig:val}
+\end{figure}
+
+
+\begin{figure}[htbp]
+\centerline{\includegraphics[width=4in]{tsunami-fig-4.eps}}
+\caption{Complex reflection patterns and run-up into Monai Valley
+simulated by \AnuGA{} and visualised using our netcdf OSG
+viewer.}\label{fig:run}
+\end{figure}
+
+
+The wave tank simulation of the Hokkaido tsunami was used as the
+first scenario for validating \AnuGA{}. The dataset provided
+bathymetry and topography along with initial water depth and the
+wave specifications. The dataset also contained water depth time
+series from three wave gauges situated offshore from the simulated
+inundation area.
+
+Figure~\ref{fig:val} compares the observed wave tank and modelled
+\AnuGA{} water depth (stage height) at one of the gauges. The plots
+show good agreement between the two time series, with \AnuGA{}
+closely modelling the initial draw down, the wave shoulder and the
+subsequent reflections. The discrepancy between modelled and
+simulated data in the first 10 seconds is due to the initial
+condition in the physical tank not being uniformly zero. Similarly
+good comparisons are evident with data from the other two gauges.
+Additionally, \AnuGA{} replicates exceptionally well the 32~m Monai
+Valley run-up, and demonstrates its occurrence to be due to the
+interaction of the tsunami wave with two juxtaposed valleys above
+the coastline. The run-up is depicted in Figure~\ref{fig:run}.
+
+This successful replication of the tsunami wave tank simulation on a
+complex 3D beach is a positive first step in validating the \AnuGA{}
+modelling capability. Subsequent validation will be conducted as
+additional datasets become available.
+
+
+
+\section{Parallel Implementation}\label{sec:parallel}
+
+To parallelize our algorithm we use a simple domain decomposition
+strategy. We suppose we have a global mesh which defines the domain
+of our problem. We must first subdivide the global mesh into a set
+of non-overlapping submeshes. This partitioning is done using the
+\Metis{} partitioning library. We will demonstrate the efficiency of
+this library in the following subsections. Once this partitioning
+has been done, and the proper communication patterns set, we can
+start to evolve our solution. Each timestep consists of
+independently and then communicate the appropriate ``ghost'' cell
+information once each timestep.
+
+%\begin{figure}[hbtp]
+%  \centerline{ \includegraphics[scale = 0.6]{domain.eps}}
+%  \caption{The first step of the parallel algorithm is to divide
+%  the mesh over the processors.}
+%  \label{fig:subpart}
+%\end{figure}
+
+
+
+\begin{figure}[h!]
+  \centerline{ \includegraphics[width=6.5cm]{mermesh.eps}}
+  \caption{The global Merimbula mesh}
+ \label{fig:mergrid}
+\end{figure}
+
+\begin{figure}[h!]
+  \centerline{ \includegraphics[width=6.5cm]{mermesh4c.eps}
+  \includegraphics[width=6.5cm]{mermesh4a.eps}}
+
+  \centerline{ \includegraphics[width=6.5cm]{mermesh4d.eps}
+  \includegraphics[width=6.5cm]{mermesh4b.eps}}
+  \caption{The global Merimbula mesh partitioned into 4 submeshes using \Metis.}
+ \label{fig:mergrid4}
+\end{figure}
+
+
+
+
+\begin{table}[h!]
+\caption{4-way and 8-way partition tests of Merimbula mesh showing
+the percentage distribution of cells between the
+submeshes.}\label{tbl:mer}
+\begin{center}
+\begin{tabular}{|c|c c c c|}
+\hline
+CPU & 0 & 1 & 2 & 3\\
+\hline
+Cells & 2757 & 2713 & 2761 & 2554\\
+\% & 25.6\% & 25.2\% & 25.6\% & 23.7\%\ \\
+\hline
+\end{tabular}
+
+\medskip
+
+\begin{tabular}{|c|c c c c c c c c|}
+\hline
+CPU & 0 & 1 & 2 & 3 & 4 & 5 & 6 & 7\\
+\hline
+Cells & 1229 & 1293 & 1352 & 1341 & 1349 & 1401 & 1413 & 1407\\
+\% & 11.4\% & 12.0\% & 12.5\% & 12.4\% & 12.5\% & 13.0\% & 13.1\% & 13.1\%\\
+\hline
+\end{tabular}
+\end{center}
+\end{table}
+
+
+\section{Conclusions}
+\label{sec:6} \AnuGA{} is a flexible and robust modelling system
+that simulates hydrodynamics by solving the shallow water wave
+equation in a triangular mesh. It can model the process of wetting
+and drying as water enters and leaves an area and is capable of
+capturing hydraulic shocks due to the ability of the finite-volume
+method to accommodate discontinuities in the solution.
+
+\AnuGA{} can take as input bathymetric and topographic datasets and
+simulate the behaviour of riverine flooding, storm surge and
+tsunami. Initial validation using wave tank data supports AnuGA's
+ability to model complex scenarios. Further validation will be
+pursued as additional datasets become available.
+
+\AnuGA{} is already being used to model the behaviour of
+hydrodynamic natural hazards. This modelling capability is part of
+Geoscience Australia's ongoing research effort to model and
+understand the potential impact from natural hazards in order to
+reduce their impact on Australian communities.
+
+
+\paragraph{Acknowledgements:}
+The authors are grateful to Belinda Barnes, National Centre for
+Epidemiology and Population Health, Australian National University,
+and Matt Hayne and Augusto Sanabria, Risk Research Group, Geoscience
+Australia, for helpful reviews of a previous version of this paper.
+Author Nielsen publish with the permission of the CEO, Geoscience
+Australia.
+
+% Preferably provide your bibliography as a separate .bbl file.
+% Include URLs, DOIs, Math Review numbers or Zentralblatt numbers in your bibliography
+% so we help connect the web of science and ensure maximum visibility
+% for your article.
+\bibliographystyle{plain}
+\bibliography{database1}
+
+
+
+
+\end{document}
Index: /anuga_work/publications/linuxconf_2006/step-five.fig
===================================================================
--- /anuga_work/publications/linuxconf_2006/step-five.fig	(revision 4115)
+++ /anuga_work/publications/linuxconf_2006/step-five.fig	(revision 4115)
@@ -0,0 +1,36 @@
+#FIG 3.2
+Landscape
+Center
+Metric
+A4      
+100.00
+Single
+-2
+1200 2
+1 3 0 1 0 1 50 -1 20 0.000 1 0.0000 2655 2520 45 45 2655 2520 2700 2520
+1 3 0 1 0 1 50 -1 20 0.000 1 0.0000 3330 2700 45 45 3330 2700 3375 2700
+1 3 0 1 0 1 50 -1 20 0.000 1 0.0000 3960 2250 45 45 3960 2250 4005 2250
+1 3 0 1 0 1 50 -1 20 0.000 1 0.0000 2160 2790 45 45 2160 2790 2205 2790
+1 3 0 1 0 1 50 -1 20 0.000 1 0.0000 2295 3330 45 45 2295 3330 2340 3330
+1 3 0 1 0 1 50 -1 20 0.000 1 0.0000 2835 3600 45 45 2835 3600 2880 3600
+1 3 0 1 0 1 50 -1 20 0.000 1 0.0000 3375 3330 45 45 3375 3330 3420 3330
+1 3 0 1 0 1 50 -1 20 0.000 1 0.0000 3960 3600 45 45 3960 3600 4005 3600
+1 3 0 1 0 1 50 -1 20 0.000 1 0.0000 4365 2880 45 45 4365 2880 4410 2880
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 3
+	 1980 2340 3150 2115 2880 3060
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 3
+	 2880 3060 3285 4095 3960 2835
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 3
+	 3150 2115 4725 1845 3960 2835
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 3
+	 3960 2835 4545 4095 4725 1845
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
+	 3285 4095 4545 4095
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 3
+	 1620 3060 2340 3870 2880 3060
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 4
+	 1980 2340 2880 3060 1620 3060 1980 2340
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 3
+	 3150 2115 3960 2835 2880 3060
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
+	 2340 3870 3285 4095
Index: /anuga_work/publications/linuxconf_2006/step-reconstruct.fig
===================================================================
--- /anuga_work/publications/linuxconf_2006/step-reconstruct.fig	(revision 4115)
+++ /anuga_work/publications/linuxconf_2006/step-reconstruct.fig	(revision 4115)
@@ -0,0 +1,50 @@
+#FIG 3.2
+Landscape
+Center
+Metric
+A4      
+100.00
+Single
+-2
+1200 2
+1 3 0 1 0 2 50 -1 20 0.000 1 0.0000 2655 2520 45 45 2655 2520 2700 2520
+1 3 0 1 0 2 45 -1 20 0.000 1 0.0000 3330 2700 45 45 3330 2700 3375 2700
+1 3 0 1 0 2 50 -1 20 0.000 1 0.0000 3960 2250 45 45 3960 2250 4005 2250
+1 3 0 1 0 1 50 -1 -1 0.000 1 0.0000 2160 2790 45 45 2160 2790 2205 2790
+1 3 0 1 0 1 50 -1 -1 0.000 1 0.0000 2295 3330 45 45 2295 3330 2340 3330
+1 3 0 1 0 1 50 -1 -1 0.000 1 0.0000 2835 3600 45 45 2835 3600 2880 3600
+1 3 0 1 0 2 50 -1 20 0.000 1 0.0000 3375 3330 45 45 3375 3330 3420 3330
+1 3 0 1 0 1 50 -1 -1 0.000 1 0.0000 3960 3600 45 45 3960 3600 4005 3600
+1 3 0 1 0 1 50 -1 -1 0.000 1 0.0000 4365 2880 45 45 4365 2880 4410 2880
+1 3 0 1 0 1 50 -1 20 0.000 1 0.0000 3376 2903 45 45 3376 2903 3421 2903
+1 3 0 1 0 1 50 -1 20 0.000 1 0.0000 3062 2640 45 45 3062 2640 3107 2640
+1 3 0 1 0 1 50 -1 20 0.000 1 0.0000 3514 2503 45 45 3514 2503 3559 2503
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 3
+	 1980 2340 3150 2115 2880 3060
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 3
+	 2880 3060 3285 4095 3960 2835
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 3
+	 3150 2115 4725 1845 3960 2835
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 3
+	 3960 2835 4545 4095 4725 1845
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
+	 3285 4095 4545 4095
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 3
+	 1620 3060 2340 3870 2880 3060
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 4
+	 1980 2340 2880 3060 1620 3060 1980 2340
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 3
+	 3150 2115 3960 2835 2880 3060
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
+	 2340 3870 3285 4095
+2 1 1 1 0 7 50 -1 -1 4.000 0 0 -1 0 0 4
+	 2665 2519 3962 2241 3369 3334 2654 2519
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 1 0 2
+	1 1 1.00 30.00 60.00
+	 3328 2707 3065 2637
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 1 0 2
+	1 1 1.00 30.00 60.00
+	 3339 2700 3517 2500
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 1 0 2
+	1 1 1.00 30.00 60.00
+	 3336 2703 3380 2915
Index: /anuga_work/publications/linuxconf_2006/underscore.sty
===================================================================
--- /anuga_work/publications/linuxconf_2006/underscore.sty	(revision 4115)
+++ /anuga_work/publications/linuxconf_2006/underscore.sty	(revision 4115)
@@ -0,0 +1,232 @@
+% underscore.sty     12-Oct-2001   Donald Arseneau   asnd@triumf.ca
+% Make the "_" character print as "\textunderscore" in text.
+% Copyright 1998,2001 Donald Arseneau;  Distribute freely if unchanged.
+% Instructions follow after the definitions.
+
+\ProvidesPackage{underscore}[2001/10/12]
+
+\begingroup
+ \catcode`\_=\active
+ \gdef_{% \relax % No relax gives a small vulnerability in alignments
+   \ifx\if@safe@actives\iftrue % must be outermost test!
+      \string_%
+   \else
+      \ifx\protect\@typeset@protect
+         \ifmmode \sb \else \BreakableUnderscore \fi
+      \else
+         \ifx\protect\@unexpandable@protect \noexpand_%
+         \else \protect_%
+      \fi\fi
+    \fi}
+\endgroup
+
+% At begin: set catcode; fix \long \ttdefault so I can use it in comparisons; 
+\AtBeginDocument{%
+  {\immediate\write\@auxout{\catcode\number\string`\_ \string\active}}%
+  \catcode\string`\_\string=\active
+  \edef\ttdefault{\ttdefault}%
+}
+
+\newcommand{\BreakableUnderscore}{\leavevmode\nobreak\hskip\z@skip
+ \ifx\f@family\ttdefault \string_\else \textunderscore\fi
+ \usc@dischyph\nobreak\hskip\z@skip}
+
+\DeclareRobustCommand{\_}{%
+  \ifmmode \nfss@text{\textunderscore}\else \BreakableUnderscore \fi}
+
+\let\usc@dischyph\@dischyph
+\DeclareOption{nohyphen}{\def\usc@dischyph{\discretionary{}{}{}}}
+\DeclareOption{strings}{\catcode`\_=\active}
+
+\ProcessOptions
+\ifnum\catcode`\_=\active\else \endinput \fi
+
+%%%%%%%%   Redefine commands that use character strings   %%%%%%%%
+
+\@ifundefined{UnderscoreCommands}{\let\UnderscoreCommands\@empty}{}
+\expandafter\def\expandafter\UnderscoreCommands\expandafter{%
+  \UnderscoreCommands
+  \do\include \do\includeonly
+  \do\@input \do\@iinput \do\InputIfFileExists
+  \do\ref \do\pageref \do\newlabel
+  \do\bibitem \do\@bibitem \do\cite \do\nocite \do\bibcite
+}
+
+% Macro to redefine a macro to pre-process its string argument
+% with \protect -> \string.
+\def\do#1{% Avoid double processing if user includes command twice!
+ \@ifundefined{US\string_\expandafter\@gobble\string#1}{%
+   \edef\@tempb{\meaning#1}% Check if macro is just a protection shell...
+   \def\@tempc{\protect}%
+   \edef\@tempc{\meaning\@tempc\string#1\space\space}%
+   \ifx\@tempb\@tempc % just a shell: hook into the protected inner command
+     \expandafter\do
+       \csname \expandafter\@gobble\string#1 \expandafter\endcsname
+   \else % Check if macro takes an optional argument
+     \def\@tempc{\@ifnextchar[}%
+     \edef\@tempa{\def\noexpand\@tempa####1\meaning\@tempc}%
+     \@tempa##2##3\@tempa{##2\relax}%
+     \edef\@tempb{\meaning#1\meaning\@tempc}%
+     \edef\@tempc{\noexpand\@tempd \csname
+        US\string_\expandafter\@gobble\string#1\endcsname}%
+     \if \expandafter\@tempa\@tempb \relax 12\@tempa % then no optional arg
+       \@tempc #1\US@prot
+     \else  % There is optional arg
+       \@tempc #1\US@protopt
+     \fi
+   \fi
+ }{}}
+
+\def\@tempd#1#2#3{\let#1#2\def#2{#3#1}}
+
+\def\US@prot#1#2{\let\@@protect\protect \let\protect\string
+  \edef\US@temp##1{##1{#2}}\restore@protect\US@temp#1}
+\def\US@protopt#1{\@ifnextchar[{\US@protarg#1}{\US@prot#1}}
+\def\US@protarg #1[#2]{\US@prot{{#1[#2]}}}
+
+\UnderscoreCommands
+\let\do\relax \let\@tempd\relax  % un-do
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\endinput
+
+underscore.sty    12-Oct-2001  Donald Arseneau
+
+Features:
+~~~~~~~~~
+\_ prints an underscore so that the hyphenation of constituent words
+is not affected and hyphenation is permitted after the underscore.
+For example, "compound\_fracture" hyphenates as com- pound_- frac- ture.
+If you prefer the underscore to break without a hyphen (but still with 
+the same rules for explicit hyphen-breaks) then use the [nohyphen]
+package option.
+
+A simple _  acts just like \_ in text mode, but makes a subscript in 
+math mode: activation_energy $E_a$
+
+Both forms use an underscore character if the font encoding contains
+one (e.g., "\usepackage[T1]{fontenc}" or typewriter fonts in any encoding),
+but they use a rule if the there is no proper character.
+
+Deficiencies:
+~~~~~~~~~~~~~
+The skips and penalties ruin any kerning with the underscore character
+(when a character is used).  However, there doesn't seem to be much, if
+any, such kerning in the ec fonts, and there is never any kerning with
+a rule.
+
+You must avoid "_" in file names and in cite or ref tags, or you must use 
+the babel package, with its active-character controls, or you must give 
+the [strings] option, which attempts to redefine several commands (and 
+may not work perfectly).  Even without the [strings] option or babel, you 
+can use occasional underscores like: "\include{file\string_name}".
+
+Option: [strings]
+~~~~~~~~~~~~~~~~~
+The default operation is quite simple and needs no customization; but
+you must avoid using "_" in any place where LaTeX uses an argument as
+a string of characters for some control function or as a name.  These
+include the tags for \cite and \ref, file names for \input, \include,
+and \includegraphics, environment names, counter names, and placement
+parameters (like "[t]").  The problem with these contexts is that they
+are `moving arguments' but LaTeX does not `switch on' the \protect
+mechanism for them.
+
+If you need to use the underscore character in these places, the package
+option [strings] is provided to redefine commands taking a string argument
+so that the argument is protected (with \protect -> \string).  The list
+of commands is given in "\UnderscoreCommands", with "\do" before each,
+covering \cite, \ref, \input, and their variants.  Not included are many
+commands regarding font names, everything with counter names, environment
+names, page styles, and versions of \ref and \cite defined by external
+packages (e.g. \vref and \citeyear).
+
+You can add to the list of supported commands by defining \UnderscoreCommands
+before loading this package; e.g.
+
+   \usepackage{chicago}
+   \newcommand{\UnderscoreCommands}{%   (\cite already done)
+     \do\citeNP \do\citeA \do\citeANP \do\citeN \do\shortcite
+     \do\shortciteNP \do\shortciteA \do\shortciteANP \do\shortciteN
+     \do\citeyear \do\citeyearNP
+   }
+   \usepackage[strings]{underscore}
+
+Not all commands can be supported this way!  Only commands that take a
+string argument *first* can be protected.  One optional argument before
+the string argument is also permitted, as exemplified by \cite: both
+\cite{tags} and \cite[text]{tags} are allowed.  A command like
+\@addtoreset which takes two counter names as arguments could not
+be protected by adding it to \UnderscoreCommands.
+
+!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+!! When you use the [strings] option, you must load this package !!
+!! last (or nearly last).                                        !!
+!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+There are two reasons: 1) The redefinitions done for protection must come
+after other packages define their customized versions of those commands.
+2) The [strings] option requires the _ character to be activated immediately
+in order for the cite and ref tags to be read properly from the .aux file
+as plain strings, and this catcode setting might disrupt other packages.
+
+The babel package implements a protection mechanism for many commands,
+and will be a complete fix for most documents without the [strings] option.
+Many add-on packages are compatible with babel, so they will get the
+strings protection also.  However, there are several commands that are 
+not covered by babel, but can easily be supported by the [strings] and 
+\UnderscoreCommands mechanism.  Beware that using both [strings] and babel 
+may lead to conflicts, but does appear to work (load babel last).
+
+Implementation Notes:
+~~~~~~~~~~~~~~~~~~~~~
+The first setting of "_" to be an active character is performed in a local
+group so as to not interfere with other packages.  The catcode setting
+is repeated with \AtBeginDocument so the definition is in effect for the
+text.  However, the catcode setting is repeated immediately when the
+[strings] option is detected.
+
+The definition of the active "_" is essentially:
+       \ifmmode \sb \else \BreakableUnderscore \fi
+where "\sb" retains the normal subscript meaning of "_" and where
+"\BreakableUnderscore" is essentially "\_".  The rest of the definition
+handles the "\protect"ion without causing \relax to be inserted before
+the character.
+
+\BreakableUnderscore uses "\nobreak\hskip\z@skip" to separate the
+underscore from surrounding words, thus allowing TeX to hyphenate them,
+but preventing free breaks around the underscore. Next, it checks the
+current font family, and uses the underscore character from tt fonts or
+otherwise \textunderscore (which is a character or rule depending on
+the font encoding).  After the underscore, it inserts a discretionary
+hyphenation point as "\usc@dischyph", which is usually just "\-"
+except that it still works in the tabbing environment, although it
+will give "\discretionary{}{}{}" under the [nohyphen] option.  After
+that, another piece of non-breaking interword glue is inserted. 
+Ordinarily, the comparison "\ifx\f@family\ttdefault" will always fail 
+because \ttdefault is `long' where \f@family is not (boooo hisss), but 
+\ttdefault is redefined to be non-long by "\AtBeginDocument".
+
+The "\_" command is then defined to use "\BreakableUnderscore".
+
+If the [strings] option is not given, then that is all!
+
+Under the [strings] option, the list of special commands is processed to:
+- retain the original command as \US_command (\US_ref)
+- redefine the command as \US@prot\US_command for ordinary commands
+  (\ref -> \US@prot\US_ref) or as \US@protopt\US_command when an optional
+  argument is possible (\bibitem -> \US@protopt\US_bibitem).
+- self-protecting commands (\cite) retain their self-protection.
+Diagnosing the state of the pre-existing command is done by painful
+contortions involving \meaning.
+
+\US@prot and \US@protopt read the argument, process it with \protect
+enabled, then invoke the saved \US_command.
+
+Modifications:
+~~~~~~~~~~~~~~
+12-Oct-2001  Babel (safe@actives) compatibility and [nohyphen] option.
+
+Test file integrity:  ASCII 32-57, 58-126:  !"#$%&'()*+,-./0123456789
+:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefghijklmnopqrstuvwxyz{|}~
