Index: /anuga_work/publications/anuga_2007/anuga-bibliography.bib
===================================================================
--- /anuga_work/publications/anuga_2007/anuga-bibliography.bib	(revision 4676)
+++ /anuga_work/publications/anuga_2007/anuga-bibliography.bib	(revision 4676)
@@ -0,0 +1,261 @@
+@INPROCEEDINGS{modsim2005,
+  AUTHOR =       {O. Nielsen and S. Roberts and D. Gray and A. McPherson and A. Hitchman},
+  TITLE =        {Hydrodynamic modelling of coastal inundation},
+  BOOKTITLE =    {MODSIM 2005 International Congress on Modelling and Simulation},
+  YEAR =         {2005},
+  editor =       {A. Zerger and R.M. Argent},
+  pages =        {518--523},
+  month =        {December},
+  organization = {Modelling and Simulation Society of Australia and New Zealand},
+  note =         {\url{http://www.mssanz.org.au/modsim05/papers/nielsen.pdf}},
+  ISBN =         {0-9758400-2-9},
+}
+
+
+
+@ARTICLE{gk:metis,
+  AUTHOR =       {George Karypis and Vipin Kumar},
+  TITLE =        {A fast and high quality multilevel scheme for partitioning irregular graphs},
+  JOURNAL =      {SIAM Journal on Scientific Computing},
+  YEAR =         {1999},
+  volume =       {20},
+  number =       {1},
+  pages =        {359--392},
+  note =         {\url{http://glaros.dtc.umn.edu/gkhome/fetch/papers/mlSIAMSC99.pdf}},
+}
+
+
+
+
+
+@TECHREPORT{TitG1997,
+  AUTHOR =       { V. V. Titov and F. I. Gonzalez},
+  TITLE =        {Imple-mentation and testing of the Method of Splitting Tsunami (MOST) model},
+  INSTITUTION =  {NOAA},
+  YEAR =         {1997},
+  type =         {Technical Memorandum},
+  number =       {ERL PMEL-112},
+}
+
+@ARTICLE{Toro-92,
+  author =       {Toro, E. F.},
+  title =        {Riemann Problems and the WAF Method for
+Solving the Two-Dimensional Shallow Water Equations},
+  journal =      {Philosophical
+Transactions of the Royal Society, Series A},
+  year =         {1992},
+  volume =       {338},
+  pages =        {43-68}
+}
+
+
+@ARTICLE{Baldwin-2006,
+  author =       {Baldwin, S.},
+  title =        {Our Aussie Tsunami Terror},
+  journal =      {Take 5},
+  year =         {2006},
+  month =        {August},
+  date =         {9}, 
+  volume =       {32},
+  pages =        {18-19}
+}
+
+
+@ARTICLE{TsuMIS1995,
+  AUTHOR =       {Y. Tsuji and S. Matsutomi and  F. Imamura and C.E. Synolakis},
+  TITLE =        {Field survey
+of the East Java Earthquake and tsunami},
+  JOURNAL =      {Pure and Applied Geophysics},
+  YEAR =         {1995},
+  volume =       {144},
+  number =       {3/4},
+  pages =        {839--855}
+}
+
+
+@ARTICLE{Nielsen2006,
+  author = {O. Nielsen and J. Sexton and D. Gray and N. Bartzis},
+  title = {Modelling answers tsunami questions},
+  journal = {AusGeo News}, 
+  month = {September},
+  year = {2006},
+  volume = 83,
+  note = {\url{http://www.ga.gov.au/ausgeonews/ausgeonews200609/modelling.jsp}}
+}
+
+
+@ARTICLE{Rob99l,
+  author = {C. Zoppou and S. Roberts},
+  year = 1999,
+  title = {{Catastrophic Collapse of Water Supply Reservoirs in Urban Areas}},
+  journal = {ASCE J. Hydraulic Engineering},
+  volume = 125,
+  number = 7,
+  pages = {686--695}
+}
+
+
+
+
+@TECHREPORT{Blong-2005,
+  AUTHOR =       {R. Blong},
+  TITLE =        {Natural hazards risk assessment: an Australian perspective},
+  INSTITUTION =  {Benfield Hazard Research Centre},
+  YEAR =         {2005},
+  type =         {Issues in Risk Science series},
+  address =      {London},
+}
+
+@ARTICLE{KurNP2001,
+  AUTHOR =       {A. Kurganov and  S. Noelle and G. Petrova},
+  TITLE =        {Semidiscrete central-upwind
+schemes for hyperbolic conservation laws and Hamilton-Jacobi equations},
+  JOURNAL =      {SIAM Journal of Scientific Computing},
+  YEAR =         {2001},
+  volume =       {23},
+  number =       {3},
+  pages =        {707--740}
+}
+
+@ARTICLE{LebKC1998,
+  AUTHOR =       {J.F. Lebrun and  G.D. Karner and J.Y. Collot},
+  TITLE =        {Fracture zone subduction
+and reactivation across the Puysegur ridge/trench system, southern New
+Zealand},
+  JOURNAL =      {Journal of Geophysical Research},
+  YEAR =         {1998},
+  volume =       {103},
+  pages =        {7293--7313},
+}
+
+@INCOLLECTION{MatH2001,
+  AUTHOR =       {M. Matsuyama and H. Tanaka},
+  TITLE =        {An experimental study of the highest
+run-up height in the 1993 Hokkaido Nansei-oki earthquake tsunami},
+  BOOKTITLE =    {National Tsunami Hazard Mitigation Program Review and International Tsunami Symposium (ITS)},
+  PUBLISHER =    {U.S. National Tsunami Hazard Mitigation Program},
+  YEAR =         {2001},
+  pages =        {879--889},
+}
+
+
+
+@article{Zoppou99,
+  AUTHOR = {Christopher Zoppou and Stephen Roberts},
+  TITLE = {Catastrophic collapse of water supply reserviours in urban areas},
+  YEAR = {1999},
+  JOURNAL = {Journal of Hydraulic Engineering},
+    VOLUME = {125},
+    NUMBER = {7},
+    MONTH = {July},
+    PAGES = {686--695}
+}
+
+@ARTICLE{Ole05,
+  AUTHOR = {Ole Nielsen and S.Roberts and D. Gray and A. McPherson and A. Hitchman},
+  TITLE = {Hydrodynamic modelling of coastal indundation},
+  YEAR = {2005},
+  JOURNAL = {MODSIM Conference},
+    VOLUME = {FIX ME},
+    NUMBER = {},
+    MONTH = {},
+    PAGES = {}
+}
+
+@INPROCEEDINGS{Titov01,
+  AUTHOR = {V.V. Titov and F.I. Gonzalez and H.O. Mofjeld and J.C. Newman},
+  TITLE = {Project {SIFT} (Short-term inundation forecasting for tsunamis)},
+  YEAR = {2001},
+  BOOKTITLE = {ITS Proceedings},
+    VOLUME = {},
+    NUMBER = {},
+    MONTH = {},
+    PAGES = {}
+}
+
+@ARTICLE{Titov97,
+AUTHOR = {V.V. Titov and F.I. Gonzalez},
+TITLE = { Implementation and testing of the method of splitting tsunami
+({MOST}) model },
+YEAR = {1997},
+JOURNAL = {NOAA Technical Memorandum},
+}
+
+@INPROCEEDINGS{Watts01,
+AUTHOR = {P. Watts and S.T. Grilli and F. Imamura},
+TITLE = {Coupling of tsunami generation and propagation codes},
+YEAR = {2001},
+BOOKTITLE = {ITS Proccedings},
+}
+
+@INPROCEEDINGS{Avdeev01,
+AUTHOR = {A.V. Avdeev and M.M. Lavrentiev Jr. and A.G. Marchuck and E.V.
+Goryunov and K.V. Simonov and V.A. Okhonin},
+TITLE = {Complex analysis of ocean tsunami observation data for solution
+of the inverse problem},
+YEAR = {2001},
+BOOKTITLE = {ITS Proceedings},
+}
+
+@INPROCEEDINGS{Pelinovsky01,
+AUTHOR = {E. Pelinovsky and C. Kharif and I. Riabov and M. Francius},
+TITLE = {Numerical simulation of tsunami propagation near the {F}rench
+coast of the {M}editerranean},
+YEAR = {2001},
+BOOKTITLE = {ITS Procceedings},
+}
+
+@ARTICLE{Shu88,
+AUTHOR = {C.W. Shu and S. Osher},
+TITLE = {Efficient implementation of essentially non-oscillatory shock
+capturing schemes},
+YEAR = {1988},
+JOURNAL = {Journal of Computational Physics},
+}
+
+@ARTICLE{Toro92,
+AUTHOR = {E.F. Toro},
+TITLE = {Reimann problems and the WAF method for solving the
+two-dimensional shallow water equations},
+YEAR = {1992},
+JOURNAL = {Philospohical Trans Royal Society },
+}
+
+@ARTICLE{Toro89,
+AUTHOR = {E.F. Toro},
+TITLE = {A weighted average flux method for hyperbolic conservation laws},
+YEAR = {1989},
+JOURNAL = {Proc. Royal Soc.},
+}
+
+@ARTICLE{Kurganov01,
+AUTHOR = {A. Kurganov and S. Noelle and G. Petrova},
+TITLE = {Semidiscrete central-upwind schemes for hyperbolic conservation
+laws and {H}amilton-{J}acobi equations},
+YEAR = {2001},
+JOURNAL = {SIAM Journal of Scientific Computing},
+}
+
+@ARTICLE{Synolakis05,
+AUTHOR = {C. Synolakis and E. Okal and E. Bernard},
+TITLE = {The megatsunami of {D}ecember 26 2004},
+YEAR = {2005},
+JOURNAL = {National Academy of Engineering Publications},
+}
+
+@PHDTHESIS{Latham99,
+AUTHOR = {Shane Latham},
+TITLE = {A Free Surface Nonlinearity in the Simplified Steady-State
+Shallow Water Equations},
+SCHOOL = {The Australian National University},
+YEAR = {1999},
+}
+
+@INPROCEEDINGS{Watts05,
+AUTHOR = {P. Watts and M. Ioualalen and S. Grilli and F. Shi and J. Kirby},
+TITLE = {Numerical Simulation of the December 26, 2004 Indian Ocean
+Tsunami using a Higher-order Boussinesq Model},
+BOOKTITLE = {Ocean Waves Measurement and Analysis 5th International
+Symposium},
+YEAR = {2005}
+}
Index: /anuga_work/publications/anuga_2007/anuga_validation.tex
===================================================================
--- /anuga_work/publications/anuga_2007/anuga_validation.tex	(revision 4676)
+++ /anuga_work/publications/anuga_2007/anuga_validation.tex	(revision 4676)
@@ -0,0 +1,517 @@
+% 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{On The Validation of A Hydrodynamic Model}
+
+\author{
+D.~S.~Gray\thanks{Natural Hazard Impacts Project, Geospatial and
+Earth Monitoring Division, Geoscience Australia, Symonston,
+\textsc{Australia}. \protect\url{mailto:Duncan.Gray@ga.gov.au}}\footnotemark[1]
+\and
+T.~Baldock\thanks{University of Queensland, Brisbane, \textsc{Australia}. 
+\protect\url{mailto:tom.baldock@uq.edu.au}}\footnotemark[2]
+\and
+O.~M.~Nielsen\footnotemark[1]
+\and 
+M.~J.~Sexton\footnotemark[1]
+\and
+N.~Bartzis\footnotemark[1]
+\and
+S.~G.~Roberts\thanks{Department of Mathematics, Australian National University,
+Canberra, \textsc{Australia}. \protect\url{mailto:stephen.roberts@anu.edu.au}}}
+
+\date{30 May 2008}
+
+\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}}
+
+
+
+\begin{document}
+
+% Use default \verb|\maketitle|.
+\maketitle
+
+% Use the \verb|abstract| environment.
+\begin{abstract}
+Modelling the effects on the built environment of natural hazards such
+as riverine flooding, storm surges and tsunami is critical for
+understanding their economic and social impact on our urban
+communities.  Geoscience Australia and the Australian National
+University have developed a hydrodynamic inundation modelling tool
+called \ANUGA{} to help simulate the impact of these hazards.
+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 model, the architecture and a range of 
+validations that have been carried out to establish confidence in the model. 
+
+
+\ANUGA{} is availbale as Open Source to enable
+free access to the software and allow the scientific community to
+use, validate and contribute to the software in the future.
+
+%This method allows the study area to be represented by an unstructured
+%mesh with variable resolution to suit the particular problem.  The
+%conserved quantities are water level (stage) and horizontal momentum.
+%An important capability of ANUGA is that it can robustly model the
+%process of wetting and drying as water enters and leaves an area. This
+%means that it is suitable for simulating water flow onto a beach or
+%dry land and around structures such as buildings.
+
+
+\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|\,.
+
+%\clearpage
+\section{Introduction}
+\label{sec:intro}
+
+The Indian Ocean tsunami on 26 December 2004 demonstrated the
+potentially catastrophic consequences of natural hazards.  While the
+scale of the impact from such events is not common, smaller-scale
+tsunami regularly threaten coastal communities
+around the world. Earthquakes which occur in the Java Trench near
+Indonesia (e.g.~\cite{TsuMIS1995} or \cite{Baldwin-2006}) 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. In addition, the
+preferential development of Australian coastal corridors means that
+inundation from hydrological disasters such as tsunami or storm-surge
+of even a few hundred metres beyond the shoreline has increased
+potential to cause significant disruption and loss. The extent of
+inundation is critically linked to the event, tidal conditions,
+bathymetry and topography and it not feasible to make impact
+predictions using heuristics alone.
+
+Hydrodynamic modelling allows impacts from flooding, storm-surge and
+tsunami 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.
+Section~\ref{sec:software} describes the software implementation and
+the API while section~\ref{sec:validation} presents some
+validation results.
+
+
+\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 conservation vectors $\UU$ and normal vectors $\nn$
+$$
+H(\UU,\UU;\ \nn) = \EE(\UU) n_1 + \GG(\UU) n_2 .
+$$
+
+Then
+$$
+\HH_{ij}  = \HH(\UU_i(m_{ij}),
+\UU_j(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, with respect to the $i$th cell, on the
+\textit{ij}th edge. The function $\UU_i(x)$ for $x \in
+T_i$ is obtained from the vector $\UU_k$ of conserved average values for 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{Software Implementation}
+\label{sec:software}
+
+\ANUGA{} is mostly written in the object-oriented programming
+language \Python{} with computationally intensive parts implemented
+as highly optimised shared objects written in C.
+
+\Python{} is known for its clarity, elegance, efficiency and
+reliability. Complex software can be built in \Python{} without undue
+distractions arising from idiosyncrasies of the underlying software
+language syntax. In addition, \Python{}'s automatic memory management,
+dynamic typing, object model and vast number of libraries means that
+software can be produced quickly and can be readily adapted to
+changing requirements throughout its lifetime.
+
+The fundamental object in \ANUGA{} is the \code{Domain} which
+inherits functionality from a hierarchy of increasingly specialised
+classes starting with a basic structural Mesh to classes implementing
+the finite-volume scheme described in section \ref{sec:fvm}. Other classes
+are \code{Quantity} which represents values of one variable across the mesh
+along with their associated operations, \code{Geospatial_data} which
+represents georeferenced elevation data and a collection of \code{Boundary}
+classes which allows for a 'pluggable' way of driving the model.
+The conserved quantities updated automatically by the numerical scheme
+are stage (water level) $w$, $x$-momentum $uh$ and $y$-momentum
+$vh$. The quanitites elevation $z$ and friction $\eta$ are
+quantities that are not updated automatically but can be changed explicitly
+during run-time if the user wishes to do so.
+
+To set up a scenario the user specifies the study area along with any internal
+regions where increased mesh resolution is required. External edges may
+be labelled using symbolic tags which are subsequently used to bind
+boundary condition objects to tagged segments of the mesh boundary.
+The mesh is then generated using \ANUGA{}'s built-in mesh generator and
+converted into the \code{Domain} object which provides all methods used to
+setup and run the flow simulation. Figure \ref{fig:anuga mesh} shows an example of a mesh generated by \ANUGA{}.
+\begin{figure}
+\begin{center}
+\includegraphics[width=4in,keepaspectratio=true]{triangular-mesh}
+\caption{Triangular mesh used in our finite volume method. Conserved
+quantities $h$, $uh$ and $vh$ are associated with each triangular cell.}
+\label{fig:anuga mesh}
+\end{center}
+\end{figure}
+
+
+
+Next step is to setup initial conditions for each \code{Quantity} object. For
+the elevation $z$ this is typically obtained from bathymetric and
+topographic data sets. Setting initial values for quantities is done
+through the method \code{domain.set_quantity(name, X, location,
+region)} where name is the name of the quantity (e.g.\ 'stage',
+'xmomentum', 'ymomentum', 'elevation' or 'friction').  The variable X
+represents the source data for populating the quantity and may take
+one of the following forms:
+
+\begin{itemize}
+\item A constant value as in \code{domain.set_quantity('stage', 1)} which
+will set the initial water level to 1 m everywhere.
+\item Another quantity or a linear combination of quantities.  If \code{q1}
+and \code{q2} are two arbitrary quantities defined within the same domain,
+the expression \code{domain.set_quantity('stage', q1*(3*q2 + 5))} will set the stage
+quantity accordingly.  One common application of this would be to
+assign the stage as a constant depth above the bed elevation.
+\item An arbitrary function (or a callable object), \code{f(x, y)}, where \code{x}
+and \code{y} are assumed to be vectors. The quantity will be assigned values by
+evaluating \code{f} at each location within the mesh.
+\item An arbitrary set of points and associated values (wrapped into a
+Geospatial_data object). The points need not coincide with triangle
+vertices or centroids and a penalised least squares technique is
+employed to populate the quantity in a smooth and stable way.
+Since the least squares technique can be time consuming for large
+problems, \code{set_quantity} employs a caching technique which automatically
+decides whether to perform the computations or retrieve them from a
+cache.  This will typically speed up the build by several orders of
+magnitude after each computation has been performed once.
+\item A filename containing points and attributes.
+\item A Numerical Python array (or a list of numbers) ordered
+according to the internal data structure.
+\end{itemize}
+The parameter \code{location} determines whether the values should be
+assigned to triangle edge, midpoints or vertices and \code{region} allows the
+operation to be restricted to a region specified by a symbolic tag or
+a set of indices.
+
+Boundary conditions are bound to symbolic tags through the method
+\code{domain.set_boundary} which takes as input a lookup table (implemented
+as a Python dictionary) of the form \code{\{tag:~boundary_object\}}.
+The boundary objects are all assumed to be callable functions of vectors x
+and y.  Several predefined standard boundary objects are available and
+it is relatively straightforward to define problem-specific custom
+boundaries if needed.  The predefined boundary conditions include
+Dirichlet, Reflective, Transmissive, Temporal, and Spatio-Temporal
+boundaries.
+
+Forcing terms can be written according to a fixed protocol and added
+to the model using the idiom \code{domain.forcing_terms.append(F)} where \code{F} is
+assumed to be a user-defined callable object.
+
+When the simulation is running, the length of each time step is
+determined from the maximal speeds encountered and the sizes of
+triangles in order not to violate the CFL condition which specifies
+that no information should skip any triangles in one time step.  With
+large speeds and small triangles, time steps can become very small.
+In order to access the state of the simulation at regular time
+intervals, \ANUGA{} uses the method evolve:
+\begin{verbatim}
+For t in domain.evolve(yieldstep, duration):
+    <model interrogation and modification>
+\end{verbatim}
+The parameter \code{duration} specifies the time period over which
+evolve operates, and control is passed to the body of the for-loop at
+each fixed time step called \code{yieldstep}.  The internal workings
+of the numerical scheme and its variable time stepping are thus
+decoupled from the fixed time stepping of the evolve loop.  This means
+that the user of the API may access the model at fixed timesteps to
+e.g.\ store model outputs, interrogate quantities or change the model
+itself at runtime. The evolve method has been implemented using a
+Python generator hence the reference to 'yield' in the parameter name.
+
+Figure \ref{fig:beach runup} shows a simulation of water flowing onto a
+hypothetical beach with obstacles.
+A number of complex patterns are captured in this example including a shock where water reflected off the wall far (at the right hand side) meets the main flow. Other physical features are the standing waves and interference patterns.
+See the \ANUGA{} User Manual at \url{http://sourceforge.net/projects/anuga} for more details and examples.
+\begin{figure}
+\begin{center}
+\includegraphics[width=4in,keepaspectratio=true]{runup}
+\caption{A hypothetical runup scenario.}
+\label{fig:beach runup}
+\end{center}
+\end{figure}
+
+
+
+\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]{okushiri-gauge-5.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]{okushiri-model.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{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,
+tsunami or even dam breaks.
+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 (see \cite{Nielsen2006}).
+The \ANUGA{} source code is available
+at \url{http://sourceforge.net/projects/anuga}.
+
+\bibliographystyle{plain}
+\bibliography{anuga-bibliography}
+
+
+
+
+\end{document}
Index: /anuga_work/publications/anuga_2007/step-five.fig
===================================================================
--- /anuga_work/publications/anuga_2007/step-five.fig	(revision 4676)
+++ /anuga_work/publications/anuga_2007/step-five.fig	(revision 4676)
@@ -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/anuga_2007/step-reconstruct.fig
===================================================================
--- /anuga_work/publications/anuga_2007/step-reconstruct.fig	(revision 4676)
+++ /anuga_work/publications/anuga_2007/step-reconstruct.fig	(revision 4676)
@@ -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/anuga_2007/underscore.sty
===================================================================
--- /anuga_work/publications/anuga_2007/underscore.sty	(revision 4676)
+++ /anuga_work/publications/anuga_2007/underscore.sty	(revision 4676)
@@ -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{|}~
