Index: /anuga_core/documentation/coding_standards/Docstring Conventions, GA version.htm
===================================================================
--- /anuga_core/documentation/coding_standards/Docstring Conventions, GA version.htm	(revision 3574)
+++ /anuga_core/documentation/coding_standards/Docstring Conventions, GA version.htm	(revision 3574)
@@ -0,0 +1,377 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"><head><!--
+This HTML is auto-generated.  DO NOT EDIT THIS FILE!  If you are writing a new
+PEP, see http://www.python.org/peps/pep-0001.html for instructions and links
+to templates.  DO NOT USE THIS HTML FILE AS YOUR TEMPLATE!
+-->
+  <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+  <meta name="generator" content="Docutils 0.2.8: http://docutils.sourceforge.net/"><title>PEP 257 -- Docstring Conventions</title>
+  
+  <link rel="stylesheet" href="Docstring%20Conventions,%20GA%20version_files/pep.css" type="text/css"></head>
+
+
+
+<body bgcolor="white">
+<table class="navigation" border="0" cellpadding="0" cellspacing="0" width="100%">
+<tbody><tr><td class="navicon" height="35" width="150">
+<a href="http://www.python.org/" title="Python Home Page">
+<img src="Docstring%20Conventions,%20GA%20version_files/PyBanner012.gif" alt="[Python]" border="0" height="35" width="150"></a></td>
+<td class="textlinks" align="left">
+[<b><a href="http://www.python.org/">Python Home</a></b>]
+[<b><a href="http://www.python.org/peps/">PEP Index</a></b>]
+[<b><a href="http://www.python.org/peps/pep-0257.txt">PEP Source</a></b>]
+</td></tr></tbody></table>
+<div class="document">
+<table class="rfc2822 field-list" frame="void" rules="none">
+<col class="field-name">
+<col class="field-body">
+<tbody valign="top">
+<tr class="field"><th class="field-name">PEP:</th><td class="field-body">257</td>
+</tr>
+<tr class="field"><th class="field-name">Title:</th><td class="field-body">Docstring Conventions</td>
+</tr>
+<tr class="field"><th class="field-name">Version:</th><td class="field-body">1.8</td>
+</tr>
+<tr class="field"><th class="field-name">Last-Modified:</th><td class="field-body"><a class="reference" href="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/python/python/nondist/peps/pep-0257.txt">2002/11/30 01:49:37</a></td>
+</tr>
+<tr class="field"><th class="field-name">Author:</th><td class="field-body">David Goodger &lt;goodger at users.sourceforge.net&gt;,
+Guido van Rossum &lt;guido at python.org&gt;</td>
+</tr>
+<tr class="field"><th class="field-name">Discussions-To:</th><td class="field-body"><a class="reference" href="mailto:doc-sig@python.org?subject=PEP%20257">doc-sig at python.org</a></td>
+</tr>
+<tr class="field"><th class="field-name">Status:</th><td class="field-body">Active</td>
+</tr>
+<tr class="field"><th class="field-name">Type:</th><td class="field-body">Informational</td>
+</tr>
+<tr class="field"><th class="field-name">Content-Type:</th><td class="field-body"><a class="reference" href="http://www.python.org/peps/pep-0012.html">text/x-rst</a></td>
+</tr>
+<tr class="field"><th class="field-name">Created:</th><td class="field-body">29-May-2001</td>
+</tr>
+<tr class="field"><th class="field-name">Post-History:</th><td class="field-body">13-Jun-2001</td>
+</tr>
+</tbody>
+</table>
+<hr>
+<div class="contents topic" id="contents">
+<p class="topic-title"><a name="contents">Contents</a></p>
+<ul class="simple">
+<li><a class="reference" href="#abstract" id="id14" name="id14">Abstract</a></li>
+<li><a class="reference" href="#rationale" id="id15" name="id15">Rationale</a></li>
+<li><a class="reference" href="#specification" id="id16" name="id16">Specification</a><ul>
+<li><a class="reference" href="#what-is-a-docstring" id="id17" name="id17">What is a Docstring?</a></li>
+<li><a class="reference" href="#one-line-docstrings" id="id18" name="id18">One-line Docstrings</a></li>
+<li><a class="reference" href="#multi-line-docstrings" id="id19" name="id19">Multi-line Docstrings</a></li>
+<li><a class="reference" href="#handling-docstring-indentation" id="id20" name="id20">Handling Docstring Indentation</a></li>
+</ul>
+</li>
+<li><a class="reference" href="#references-and-footnotes" id="id21" name="id21">References and Footnotes</a></li>
+<li><a class="reference" href="#copyright" id="id22" name="id22">Copyright</a></li>
+<li><a class="reference" href="#acknowledgements" id="id23" name="id23">Acknowledgements</a></li>
+</ul>
+</div>
+<div class="section" id="abstract">
+<h1><a class="toc-backref" href="#id14" name="abstract">Abstract</a></h1>
+<p>This PEP documents the semantics and conventions associated with
+Python docstrings.</p>
+</div>
+<div class="section" id="rationale">
+<h1><a class="toc-backref" href="#id15" name="rationale">Rationale</a></h1>
+<p>The aim of this PEP is to standardize the high-level structure of
+docstrings: what they should contain, and how to say it (without
+touching on any markup syntax within docstrings).  The PEP contains
+conventions, not laws or syntax.</p>
+<blockquote>
+<p>"A universal convention supplies all of maintainability, clarity,
+consistency, and a foundation for good programming habits too.
+What it doesn't do is insist that you follow it against your will.
+That's Python!"</p>
+<p>-- Tim Peters on comp.lang.python, 2001-06-16</p>
+</blockquote>
+<p>If you violate these conventions, the worst you'll get is some dirty
+looks.  But some software (such as the <a class="reference" href="http://docutils.sourceforge.net/">Docutils</a> <a class="footnote-reference" href="#id8" id="id9" name="id9">[4]</a> docstring processing
+system <a class="footnote-reference" href="#id5" id="id1" name="id1">[1]</a> <a class="footnote-reference" href="#id6" id="id2" name="id2">[2]</a>) will be aware of the conventions, so following them
+will get you the best results.</p>
+</div>
+<div class="section" id="specification">
+<h1><a class="toc-backref" href="#id16" name="specification">Specification</a></h1>
+<div class="section" id="what-is-a-docstring">
+<h2><a class="toc-backref" href="#id17" name="what-is-a-docstring">What is a Docstring?</a></h2>
+<p>A docstring is a string literal that occurs as the first statement in
+a module, function, class, or method definition.  Such a docstring
+becomes the <tt class="literal"><span class="pre">__doc__</span></tt> special attribute of that object.</p>
+<p>All modules should normally have docstrings, and all functions and
+classes exported by a module should also have docstrings.  Public
+methods (including the <tt class="literal"><span class="pre">__init__</span></tt> constructor) should also have
+docstrings.  A package may be documented in the module docstring of
+the <tt class="literal"><span class="pre">__init__.py</span></tt> file in the package directory.</p>
+<p>String literals occurring elsewhere in Python code may also act as
+documentation.  They are not recognized by the Python bytecode
+compiler and are not accessible as runtime object attributes (i.e. not
+assigned to <tt class="literal"><span class="pre">__doc__</span></tt>), but two types of extra docstrings may be
+extracted by software tools:</p>
+<ol class="arabic simple">
+<li>String literals occurring immediately after a simple assignment at
+the top level of a module, class, or <tt class="literal"><span class="pre">__init__</span></tt> method are called
+"attribute docstrings".</li>
+<li>String literals occurring immediately after another docstring are
+called "additional docstrings".</li>
+</ol>
+<p>Please see <a class="reference" href="http://www.python.org/peps/pep-0258.html">PEP 258</a>, "Docutils Design Specification" <a class="footnote-reference" href="#id6" id="id3" name="id3">[2]</a>, for a
+detailed description of attribute and additional docstrings.</p>
+<p>XXX Mention docstrings of 2.2 properties.</p>
+<p>For consistency, always use <tt class="literal"><span class="pre">"""triple</span> <span class="pre">double</span> <span class="pre">quotes"""</span></tt> around
+docstrings.  Use <tt class="literal"><span class="pre">r"""raw</span> <span class="pre">triple</span> <span class="pre">double</span> <span class="pre">quotes"""</span></tt> if you use any
+backslashes in your docstrings.  For Unicode docstrings, use
+<tt class="literal"><span class="pre">u"""Unicode</span> <span class="pre">triple-quoted</span> <span class="pre">strings"""</span></tt>.</p>
+<p>There are two forms of docstrings: one-liners and multi-line
+docstrings.</p>
+</div>
+<div class="section" id="one-line-docstrings">
+<h2><a class="toc-backref" href="#id18" name="one-line-docstrings">One-line Docstrings</a></h2>
+<p>One-liners are for really obvious cases.  They should really fit on
+one line.  For example:</p>
+<pre class="literal-block">def kos_root():
+    """Return the pathname of the KOS root directory."""
+    global _kos_root
+    if _kos_root: return _kos_root
+    ...
+</pre>
+<p>Notes:</p>
+<ul>
+<li><p class="first">Triple quotes are used even though the string fits on one line.
+This makes it easy to later expand it.</p>
+</li>
+<li><p class="first">The closing quotes are on the same line as the opening quotes.  This
+looks better for one-liners.</p>
+</li>
+<li><p class="first">There's no blank line either before or after the docstring.</p>
+</li>
+<li><p class="first">The docstring is a phrase ending in a period.  It prescribes the
+function or method's effect as a command ("Do this", "Return that"),
+not as a description; e.g. don't write "Returns the pathname ...".</p>
+</li>
+<li><p class="first">The one-line docstring should NOT be a "signature" reiterating the
+function/method parameters (which can be obtained by introspection).
+Don't do:</p>
+<pre class="literal-block">def function(a, b):
+    """function(a, b) -&gt; list"""
+</pre>
+<p>This type of docstring is only appropriate for C functions (such as
+built-ins), where introspection is not possible.  However, the
+nature of the <em>return value</em> cannot be determined by introspection,
+so it should be mentioned.  The preferred form for such a docstring
+would be something like:</p>
+<pre class="literal-block">def function(a, b):
+    """Do X and return a list."""
+</pre>
+<p>(Of course "Do X" should be replaced by a useful description!)</p>
+</li>
+</ul>
+</div>
+<div class="section" id="multi-line-docstrings">
+<h2><a class="toc-backref" href="#id19" name="multi-line-docstrings">Multi-line Docstrings</a></h2>
+<p>Multi-line docstrings consist of a summary line just like a one-line
+docstring, followed by a blank line, followed by a more elaborate
+description.  The summary line may be used by automatic indexing
+tools; it is important that it fits on one line and is separated from
+the rest of the docstring by a blank line.  The summary line may be on
+the same line as the opening quotes or on the next line.  The entire
+docstring is indented the same as the quotes at its first line (see
+example below).</p>
+<p>Insert a blank line before and after all docstrings (one-line or
+multi-line) that document a class -- generally speaking, the class's
+methods are separated from each other by a single blank line, and the
+docstring needs to be offset from the first method by a blank line;
+for symmetry, put a blank line between the class header and the
+docstring.  Docstrings documenting functions or methods generally
+don't have this requirement, unless the function or method's body is
+written as a number of blank-line separated sections -- in this case,
+treat the docstring as another section, and precede it with a blank
+line.</p>
+<p>The docstring of a script (a stand-alone program) should be usable as
+its "usage" message, printed when the script is invoked with incorrect
+or missing arguments (or perhaps with a "-h" option, for "help").
+Such a docstring should document the script's function and command
+line syntax, environment variables, and files.  Usage messages can be
+fairly elaborate (several screens full) and should be sufficient for a
+new user to use the command properly, as well as a complete quick
+reference to all options and arguments for the sophisticated user.</p>
+<p>The docstring for a module should generally list the classes,
+exceptions and functions (and any other objects) that are exported by
+the module, with a one-line summary of each.  (These summaries
+generally give less detail than the summary line in the object's
+docstring.)  The docstring for a package (i.e., the docstring of the
+package's <tt class="literal"><span class="pre">__init__.py</span></tt> module) should also list the modules and
+subpackages exported by the package.</p>
+<p>The docstring for a function or method should summarize its behavior
+and document its arguments, return value(s), side effects, exceptions
+raised, and restrictions on when it can be called (all if applicable).
+Optional arguments should be indicated.  It should be documented
+whether keyword arguments are part of the interface.</p>
+<p>The docstring for a class should summarize its behavior and list the
+public methods and instance variables.  If the class is intended to be
+subclassed, and has an additional interface for subclasses, this
+interface should be listed separately (in the docstring).  The class
+constructor should be documented in the docstring for its <tt class="literal"><span class="pre">__init__</span></tt>
+method.  Individual methods should be documented by their own
+docstring.</p>
+<p>If a class subclasses another class and its behavior is mostly
+inherited from that class, its docstring should mention this and
+summarize the differences.  Use the verb "override" to indicate that a
+subclass method replaces a superclass method and does not call the
+superclass method; use the verb "extend" to indicate that a subclass
+method calls the superclass method (in addition to its own behavior).</p>
+<p><em>Do not</em> use the Emacs convention of mentioning the arguments of
+functions or methods in upper case in running text.  Python is case
+sensitive and the argument names can be used for keyword arguments, so
+the docstring should document the correct argument names.  It is best
+to list each argument on a separate line.  For example:</p>
+<pre class="literal-block">def complex(real=0.0, imag=0.0):
+    """Form a complex number.
+
+    Keyword arguments:
+    real -- the real part (default 0.0)
+    imag -- the imaginary part (default 0.0)
+
+    """
+    if imag == 0.0 and real == 0.0: return complex_zero
+    ...
+</pre>
+<p>The BDFL <a class="footnote-reference" href="#id7" id="id4" name="id4">[3]</a> recommends inserting a blank line between the last
+paragraph in a multi-line docstring and its closing quotes, placing
+the closing quotes on a line by themselves.  This way, Emacs'
+<tt class="literal"><span class="pre">fill-paragraph</span></tt> command can be used on it.</p>
+</div>
+<div class="section" id="handling-docstring-indentation">
+<h2><a class="toc-backref" href="#id20" name="handling-docstring-indentation">Handling Docstring Indentation</a></h2>
+<p>Docstring processing tools will strip a uniform amount of indentation
+from the second and further lines of the docstring, equal to the
+minimum indentation of all non-blank lines after the first line.  Any
+indentation in the first line of the docstring (i.e., up to the first
+newline) is insignificant and removed.  Relative indentation of later
+lines in the docstring is retained.  Blank lines should be removed
+from the beginning and end of the docstring.</p>
+<p>Since code is much more precise than words, here is an implementation
+of the algorithm:</p>
+<pre class="literal-block">def trim(docstring):
+    if not docstring:
+        return ''
+    # Convert tabs to spaces (following the normal Python rules)
+    # and split into a list of lines:
+    lines = docstring.expandtabs().splitlines()
+    # Determine minimum indentation (first line doesn't count):
+    indent = sys.maxint
+    for line in lines[1:]:
+        stripped = line.lstrip()
+        if stripped:
+            indent = min(indent, len(line) - len(stripped))
+    # Remove indentation (first line is special):
+    trimmed = [lines[0].strip()]
+    if indent &lt; sys.maxint:
+        for line in lines[1:]:
+            trimmed.append(line[indent:].rstrip())
+    # Strip off trailing and leading blank lines:
+    while trimmed and not trimmed[-1]:
+        trimmed.pop()
+    while trimmed and not trimmed[0]:
+        trimmed.pop(0)
+    # Return a single string:
+    return '\n'.join(trimmed)
+</pre>
+<p>The docstring in this example contains two newline characters and is
+therefore 3 lines long.  The first and last lines are blank:</p>
+<pre class="literal-block">def foo():
+    """
+    This is the second line of the docstring.
+    """
+</pre>
+<p>To illustrate:</p>
+<pre class="literal-block">&gt;&gt;&gt; print repr(foo.__doc__)
+'\n    This is the second line of the docstring.\n    '
+&gt;&gt;&gt; foo.__doc__.splitlines()
+['', '    This is the second line of the docstring.', '    ']
+&gt;&gt;&gt; trim(foo.__doc__)
+'This is the second line of the docstring.'
+</pre>
+<p>Once trimmed, these docstrings are equivalent:</p>
+<pre class="literal-block">def foo():
+    """A multi-line
+    docstring.
+    """
+
+def bar():
+    """
+    A multi-line
+    docstring.
+    """
+</pre>
+</div>
+</div>
+<div class="section" id="references-and-footnotes">
+<h1><a class="toc-backref" href="#id21" name="references-and-footnotes">References and Footnotes</a></h1>
+<table class="footnote" id="id5" frame="void" rules="none">
+<colgroup><col class="label"><col></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id1" name="id5">[1]</a></td><td><a class="reference" href="http://www.python.org/peps/pep-0256.html">PEP 256</a>, Docstring Processing System Framework, Goodger
+(<a class="reference" href="http://www.python.org/peps/pep-0256.html">http://www.python.org/peps/pep-0256.html</a>)</td></tr>
+</tbody>
+</table>
+<table class="footnote" id="id6" frame="void" rules="none">
+<colgroup><col class="label"><col></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a name="id6">[2]</a></td><td><em>(<a class="fn-backref" href="#id2">1</a>, <a class="fn-backref" href="#id3">2</a>)</em> <a class="reference" href="http://www.python.org/peps/pep-0258.html">PEP 258</a>, Docutils Design Specification, Goodger
+(<a class="reference" href="http://www.python.org/peps/pep-0258.html">http://www.python.org/peps/pep-0258.html</a>)</td></tr>
+</tbody>
+</table>
+<table class="footnote" id="id7" frame="void" rules="none">
+<colgroup><col class="label"><col></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id4" name="id7">[3]</a></td><td>Guido van Rossum, Python's creator and Benevolent Dictator For
+Life.</td></tr>
+</tbody>
+</table>
+<table class="footnote" id="id8" frame="void" rules="none">
+<colgroup><col class="label"><col></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id9" name="id8">[4]</a></td><td><a class="reference" href="http://docutils.sourceforge.net/">http://docutils.sourceforge.net/</a></td></tr>
+</tbody>
+</table>
+<table class="footnote" id="id10" frame="void" rules="none">
+<colgroup><col class="label"><col></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id11" name="id10">[5]</a></td><td><a class="reference" href="http://www.python.org/doc/essays/styleguide.html">http://www.python.org/doc/essays/styleguide.html</a></td></tr>
+</tbody>
+</table>
+<table class="footnote" id="id12" frame="void" rules="none">
+<colgroup><col class="label"><col></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id13" name="id12">[6]</a></td><td><a class="reference" href="http://www.python.org/sigs/doc-sig/">http://www.python.org/sigs/doc-sig/</a></td></tr>
+</tbody>
+</table>
+</div>
+<div class="section" id="copyright">
+<h1><a class="toc-backref" href="#id22" name="copyright">Copyright</a></h1>
+<p>This document has been placed in the public domain.</p>
+</div>
+<div class="section" id="acknowledgements">
+<h1><a class="toc-backref" href="#id23" name="acknowledgements">Acknowledgements</a></h1>
+<p>The "Specification" text comes mostly verbatim from the <a class="reference" href="http://www.python.org/doc/essays/styleguide.html">Python Style
+Guide</a> <a class="footnote-reference" href="#id10" id="id11" name="id11">[5]</a> essay by Guido van Rossum.</p>
+<p>This document borrows ideas from the archives of the Python <a class="reference" href="http://www.python.org/sigs/doc-sig/">Doc-SIG</a> <a class="footnote-reference" href="#id12" id="id13" name="id13">[6]</a>.
+Thanks to all members past and present.</p>
+<!-- Local Variables:
+mode: indented-text
+indent-tabs-mode: nil
+fill-column: 70
+sentence-end-double-space: t
+End: -->
+</div>
+</div>
+
+<hr class="footer">
+<div class="footer">
+<a class="reference" href="http://www.python.org/peps/pep-0257.txt">View document source</a>.
+Generated on: 2005-10-26 02:30 UTC.
+Generated by <a class="reference" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
+</div>
+</body></html>
Index: /anuga_core/documentation/coding_standards/Docstring Conventions, GA version_files/pep.css
===================================================================
--- /anuga_core/documentation/coding_standards/Docstring Conventions, GA version_files/pep.css	(revision 3574)
+++ /anuga_core/documentation/coding_standards/Docstring Conventions, GA version_files/pep.css	(revision 3574)
@@ -0,0 +1,349 @@
+/*
+:Author: David Goodger
+:Contact: goodger@users.sourceforge.net
+:date: $Date: 2005/09/18 15:11:03 $
+:version: $Revision: 1.6 $
+:copyright: This stylesheet has been placed in the public domain.
+
+Default cascading style sheet for the PEP HTML output of Docutils.
+*/
+
+/* "! important" is used here to override other ``margin-top`` and
+   ``margin-bottom`` styles that are later in the stylesheet or 
+   more specific.  See http://www.w3.org/TR/CSS1#the-cascade */
+.first {
+  margin-top: 0 ! important }
+
+.last, .with-subtitle {
+  margin-bottom: 0 ! important }
+
+.hidden {
+  display: none }
+
+.navigation {
+  width: 100% ;
+  background: #99ccff ;
+  margin-top: 0px ;
+  margin-bottom: 0px }
+
+.navigation .navicon {
+  width: 150px ;
+  height: 35px }
+
+.navigation .textlinks {
+  padding-left: 1em ;
+  text-align: left }
+
+.navigation td, .navigation th {
+  padding-left: 0em ;
+  padding-right: 0em ;
+  vertical-align: middle }
+
+.rfc2822 {
+  margin-top: 0.5em ;
+  margin-left: 0.5em ;
+  margin-right: 0.5em ;
+  margin-bottom: 0em }
+
+.rfc2822 td {
+  text-align: left }
+
+.rfc2822 th.field-name {
+  text-align: right ;
+  font-family: sans-serif ;
+  padding-right: 0.5em ;
+  font-weight: bold ;
+  margin-bottom: 0em }
+
+a.toc-backref {
+  text-decoration: none ;
+  color: black }
+
+blockquote.epigraph {
+  margin: 2em 5em ; }
+
+body {
+  margin: 0px ;
+  margin-bottom: 1em ;
+  padding: 0px }
+
+dl.docutils dd {
+  margin-bottom: 0.5em }
+
+div.section {
+  margin-left: 1em ;
+  margin-right: 1em ;
+  margin-bottom: 1.5em }
+
+div.section div.section {
+  margin-left: 0em ;
+  margin-right: 0em ;
+  margin-top: 1.5em }
+
+div.abstract {
+  margin: 2em 5em }
+
+div.abstract p.topic-title {
+  font-weight: bold ;
+  text-align: center }
+
+div.admonition, div.attention, div.caution, div.danger, div.error,
+div.hint, div.important, div.note, div.tip, div.warning {
+  margin: 2em ;
+  border: medium outset ;
+  padding: 1em }
+
+div.admonition p.admonition-title, div.hint p.admonition-title,
+div.important p.admonition-title, div.note p.admonition-title,
+div.tip p.admonition-title {
+  font-weight: bold ;
+  font-family: sans-serif }
+
+div.attention p.admonition-title, div.caution p.admonition-title,
+div.danger p.admonition-title, div.error p.admonition-title,
+div.warning p.admonition-title {
+  color: red ;
+  font-weight: bold ;
+  font-family: sans-serif }
+
+/* Uncomment (and remove this text!) to get reduced vertical space in
+   compound paragraphs.
+div.compound .compound-first, div.compound .compound-middle {
+  margin-bottom: 0.5em }
+
+div.compound .compound-last, div.compound .compound-middle {
+  margin-top: 0.5em }
+*/
+
+div.dedication {
+  margin: 2em 5em ;
+  text-align: center ;
+  font-style: italic }
+
+div.dedication p.topic-title {
+  font-weight: bold ;
+  font-style: normal }
+
+div.figure {
+  margin-left: 2em }
+
+div.footer, div.header {
+  clear: both;
+  font-size: smaller }
+
+div.footer {
+  margin-left: 1em ;
+  margin-right: 1em }
+
+div.line-block {
+  display: block ;
+  margin-top: 1em ;
+  margin-bottom: 1em }
+
+div.line-block div.line-block {
+  margin-top: 0 ;
+  margin-bottom: 0 ;
+  margin-left: 1.5em }
+
+div.sidebar {
+  margin-left: 1em ;
+  border: medium outset ;
+  padding: 1em ;
+  background-color: #ffffee ;
+  width: 40% ;
+  float: right ;
+  clear: right }
+
+div.sidebar p.rubric {
+  font-family: sans-serif ;
+  font-size: medium }
+
+div.system-messages {
+  margin: 5em }
+
+div.system-messages h1 {
+  color: red }
+
+div.system-message {
+  border: medium outset ;
+  padding: 1em }
+
+div.system-message p.system-message-title {
+  color: red ;
+  font-weight: bold }
+
+div.topic {
+  margin: 2em }
+
+h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
+h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
+  margin-top: 0.4em }
+
+h1 {
+  font-family: sans-serif ;
+  font-size: large }
+
+h2 {
+  font-family: sans-serif ;
+  font-size: medium }
+
+h3 {
+  font-family: sans-serif ;
+  font-size: small }
+
+h4 {
+  font-family: sans-serif ;
+  font-style: italic ;
+  font-size: small }
+
+h5 {
+  font-family: sans-serif;
+  font-size: x-small }
+
+h6 {
+  font-family: sans-serif;
+  font-style: italic ;
+  font-size: x-small }
+
+hr.docutils {
+  width: 75% }
+
+img.align-left {
+  clear: left }
+
+img.align-right {
+  clear: right }
+
+img.borderless {
+  border: 0 }
+
+ol.simple, ul.simple {
+  margin-bottom: 1em }
+
+ol.arabic {
+  list-style: decimal }
+
+ol.loweralpha {
+  list-style: lower-alpha }
+
+ol.upperalpha {
+  list-style: upper-alpha }
+
+ol.lowerroman {
+  list-style: lower-roman }
+
+ol.upperroman {
+  list-style: upper-roman }
+
+p.attribution {
+  text-align: right ;
+  margin-left: 50% }
+
+p.caption {
+  font-style: italic }
+
+p.credits {
+  font-style: italic ;
+  font-size: smaller }
+
+p.label {
+  white-space: nowrap }
+
+p.rubric {
+  font-weight: bold ;
+  font-size: larger ;
+  color: maroon ;
+  text-align: center }
+
+p.sidebar-title {
+  font-family: sans-serif ;
+  font-weight: bold ;
+  font-size: larger }
+
+p.sidebar-subtitle {
+  font-family: sans-serif ;
+  font-weight: bold }
+
+p.topic-title {
+  font-family: sans-serif ;
+  font-weight: bold }
+
+pre.address {
+  margin-bottom: 0 ;
+  margin-top: 0 ;
+  font-family: serif ;
+  font-size: 100% }
+
+pre.line-block {
+  font-family: serif ;
+  font-size: 100% }
+
+pre.literal-block, pre.doctest-block {
+  margin-left: 2em ;
+  margin-right: 2em ;
+  background-color: #eeeeee }
+
+span.classifier {
+  font-family: sans-serif ;
+  font-style: oblique }
+
+span.classifier-delimiter {
+  font-family: sans-serif ;
+  font-weight: bold }
+
+span.interpreted {
+  font-family: sans-serif }
+
+span.option {
+  white-space: nowrap }
+
+span.option-argument {
+  font-style: italic }
+
+span.pre {
+  white-space: pre }
+
+span.problematic {
+  color: red }
+
+span.section-subtitle {
+  /* font-size relative to parent (h1..h6 element) */
+  font-size: 80% }
+
+table.citation {
+  border-left: solid thin gray }
+
+table.docinfo {
+  margin: 2em 4em }
+
+table.docutils {
+  margin-top: 0.5em ;
+  margin-bottom: 0.5em }
+
+table.footnote {
+  border-left: solid thin black }
+
+table.docutils td, table.docutils th,
+table.docinfo td, table.docinfo th {
+  padding-left: 0.5em ;
+  padding-right: 0.5em ;
+  vertical-align: top }
+
+td.num {
+  text-align: right }
+
+th.field-name {
+  font-weight: bold ;
+  text-align: left ;
+  white-space: nowrap ;
+  padding-left: 0 }
+
+h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
+h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
+  font-size: 100% }
+
+tt.docutils {
+  background-color: #eeeeee }
+
+ul.auto-toc {
+  list-style-type: none }
Index: /anuga_core/documentation/coding_standards/Style Guide for Python Code, GA version.htm
===================================================================
--- /anuga_core/documentation/coding_standards/Style Guide for Python Code, GA version.htm	(revision 3574)
+++ /anuga_core/documentation/coding_standards/Style Guide for Python Code, GA version.htm	(revision 3574)
@@ -0,0 +1,892 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3c.org/TR/1999/REC-html401-19991224/loose.dtd">
+<!-- saved from url=(0110)file://V:\1\cit\risk_assessment_methods_project\inundation\sandpits\onielsen\anuga\documentation\pep-0008.html -->
+<html xmlns:v="urn:schemas-microsoft-com:vml"
+xmlns:o="urn:schemas-microsoft-com:office:office"
+xmlns:w="urn:schemas-microsoft-com:office:word"
+xmlns:st1="urn:schemas-microsoft-com:office:smarttags"
+xmlns="http://www.w3.org/TR/REC-html40">
+
+<head>
+<meta http-equiv=Content-Type content="text/html; charset=windows-1252">
+<meta name=ProgId content=Word.Document>
+<meta name=Generator content="Microsoft Word 10">
+<meta name=Originator content="Microsoft Word 10">
+<link rel=File-List
+href="Style%20Guide%20for%20Python%20Code,%20GA%20version_files/filelist.xml">
+<link rel=Edit-Time-Data
+href="Style%20Guide%20for%20Python%20Code,%20GA%20version_files/editdata.mso">
+<!--[if !mso]>
+<style>
+v\:* {behavior:url(#default#VML);}
+o\:* {behavior:url(#default#VML);}
+w\:* {behavior:url(#default#VML);}
+.shape {behavior:url(#default#VML);}
+</style>
+<![endif]-->
+<title>PEP 8 -- Style Guide for Python Code</title>
+<o:SmartTagType namespaceuri="urn:schemas-microsoft-com:office:smarttags"
+ name="date"/>
+<o:SmartTagType namespaceuri="urn:schemas-microsoft-com:office:smarttags"
+ name="country-region"/>
+<o:SmartTagType namespaceuri="urn:schemas-microsoft-com:office:smarttags"
+ name="place"/>
+<!--[if gte mso 9]><xml>
+ <o:DocumentProperties>
+  <o:Author>nielsen ole</o:Author>
+  <o:LastAuthor>gray duncan</o:LastAuthor>
+  <o:Revision>6</o:Revision>
+  <o:TotalTime>51</o:TotalTime>
+  <o:Created>2006-02-16T06:00:00Z</o:Created>
+  <o:LastSaved>2006-08-04T01:38:00Z</o:LastSaved>
+  <o:Pages>2</o:Pages>
+  <o:Words>4017</o:Words>
+  <o:Characters>22898</o:Characters>
+  <o:Company>Geoscience Australia</o:Company>
+  <o:Lines>190</o:Lines>
+  <o:Paragraphs>53</o:Paragraphs>
+  <o:CharactersWithSpaces>26862</o:CharactersWithSpaces>
+  <o:Version>10.6626</o:Version>
+ </o:DocumentProperties>
+</xml><![endif]--><!--[if gte mso 9]><xml>
+ <w:WordDocument>
+  <w:SpellingState>Clean</w:SpellingState>
+  <w:GrammarState>Clean</w:GrammarState>
+  <w:Compatibility>
+   <w:UseFELayout/>
+  </w:Compatibility>
+  <w:BrowserLevel>MicrosoftInternetExplorer4</w:BrowserLevel>
+ </w:WordDocument>
+</xml><![endif]--><!--[if !mso]><object
+ classid="clsid:38481807-CA0E-42D2-BF39-B33AF135CC4D" id=ieooui></object>
+<style>
+st1\:*{behavior:url(#ieooui) }
+</style>
+<![endif]-->
+<link rel=Stylesheet type="text/css" media=all
+href="Style%20Guide%20for%20Python%20Code,%20GA%20version_files/style.css">
+<style>
+<!--
+ /* Font Definitions */
+ @font-face
+	{font-family:"MS Mincho";
+	panose-1:2 2 6 9 4 2 5 8 3 4;
+	mso-font-alt:"\FF2D\FF33 \660E\671D";
+	mso-font-charset:128;
+	mso-generic-font-family:modern;
+	mso-font-pitch:fixed;
+	mso-font-signature:-1610612033 1757936891 16 0 131231 0;}
+@font-face
+	{font-family:"\@MS Mincho";
+	panose-1:2 2 6 9 4 2 5 8 3 4;
+	mso-font-charset:128;
+	mso-generic-font-family:modern;
+	mso-font-pitch:fixed;
+	mso-font-signature:-1610612033 1757936891 16 0 131231 0;}
+ /* Style Definitions */
+ p.MsoNormal, li.MsoNormal, div.MsoNormal
+	{mso-style-parent:"";
+	margin:0cm;
+	margin-bottom:.0001pt;
+	mso-pagination:widow-orphan;
+	font-size:12.0pt;
+	font-family:"Times New Roman";
+	mso-fareast-font-family:"Times New Roman";
+	mso-bidi-font-family:"Times New Roman";}
+h3
+	{mso-margin-top-alt:auto;
+	margin-right:0cm;
+	mso-margin-bottom-alt:auto;
+	margin-left:0cm;
+	mso-pagination:widow-orphan;
+	mso-outline-level:3;
+	font-size:13.5pt;}
+a:link, span.MsoHyperlink
+	{color:blue;
+	text-decoration:underline;
+	text-underline:single;}
+a:visited, span.MsoHyperlinkFollowed
+	{color:blue;
+	text-decoration:underline;
+	text-underline:single;}
+pre
+	{margin:0cm;
+	margin-bottom:.0001pt;
+	mso-pagination:widow-orphan;
+	font-size:10.0pt;
+	font-family:"Courier New";
+	mso-fareast-font-family:"Times New Roman";
+	mso-bidi-font-family:"Courier New";}
+p.navigation, li.navigation, div.navigation
+	{mso-style-name:navigation;
+	mso-margin-top-alt:auto;
+	margin-right:0cm;
+	mso-margin-bottom-alt:auto;
+	margin-left:0cm;
+	mso-pagination:widow-orphan;
+	font-size:12.0pt;
+	font-family:"Times New Roman";
+	mso-fareast-font-family:"Times New Roman";
+	mso-bidi-font-family:"Times New Roman";}
+p.header, li.header, div.header
+	{mso-style-name:header;
+	mso-margin-bottom-alt:auto;
+	mso-pagination:widow-orphan;
+	font-size:12.0pt;
+	font-family:"Times New Roman";
+	mso-fareast-font-family:"Times New Roman";
+	mso-bidi-font-family:"Times New Roman";}
+p.content, li.content, div.content
+	{mso-style-name:content;
+	mso-margin-top-alt:auto;
+	mso-margin-bottom-alt:auto;
+	mso-pagination:widow-orphan;
+	font-size:12.0pt;
+	font-family:"Times New Roman";
+	mso-fareast-font-family:"Times New Roman";
+	mso-bidi-font-family:"Times New Roman";}
+p.navicon, li.navicon, div.navicon
+	{mso-style-name:navicon;
+	mso-margin-top-alt:auto;
+	margin-right:0cm;
+	mso-margin-bottom-alt:auto;
+	margin-left:0cm;
+	mso-pagination:widow-orphan;
+	background:#99CCFF;
+	font-size:12.0pt;
+	font-family:"Times New Roman";
+	mso-fareast-font-family:"Times New Roman";
+	mso-bidi-font-family:"Times New Roman";}
+p.textlinks, li.textlinks, div.textlinks
+	{mso-style-name:textlinks;
+	mso-margin-top-alt:auto;
+	margin-right:0cm;
+	mso-margin-bottom-alt:auto;
+	margin-left:0cm;
+	mso-pagination:widow-orphan;
+	background:#99CCFF;
+	font-size:12.0pt;
+	font-family:"Times New Roman";
+	mso-fareast-font-family:"Times New Roman";
+	mso-bidi-font-family:"Times New Roman";}
+p.navicon1, li.navicon1, div.navicon1
+	{mso-style-name:navicon1;
+	mso-margin-top-alt:auto;
+	margin-right:0cm;
+	mso-margin-bottom-alt:auto;
+	margin-left:0cm;
+	mso-pagination:widow-orphan;
+	background:#99CCFF;
+	font-size:12.0pt;
+	font-family:"Times New Roman";
+	mso-fareast-font-family:"Times New Roman";
+	mso-bidi-font-family:"Times New Roman";}
+p.textlinks1, li.textlinks1, div.textlinks1
+	{mso-style-name:textlinks1;
+	mso-margin-top-alt:auto;
+	margin-right:0cm;
+	mso-margin-bottom-alt:auto;
+	margin-left:0cm;
+	mso-pagination:widow-orphan;
+	background:#99CCFF;
+	font-size:12.0pt;
+	font-family:"Times New Roman";
+	mso-fareast-font-family:"Times New Roman";
+	mso-bidi-font-family:"Times New Roman";}
+span.SpellE
+	{mso-style-name:"";
+	mso-spl-e:yes;}
+span.GramE
+	{mso-style-name:"";
+	mso-gram-e:yes;}
+@page Section1
+	{size:595.3pt 841.9pt;
+	margin:72.0pt 90.0pt 72.0pt 90.0pt;
+	mso-header-margin:35.4pt;
+	mso-footer-margin:35.4pt;
+	mso-paper-source:0;}
+div.Section1
+	{page:Section1;}
+ /* List Definitions */
+ @list l0
+	{mso-list-id:1153451165;
+	mso-list-type:hybrid;
+	mso-list-template-ids:214334516 -1253416102 201916419 201916421 201916417 201916419 201916421 201916417 201916419 201916421;}
+@list l0:level1
+	{mso-level-start-at:5;
+	mso-level-number-format:bullet;
+	mso-level-text:-;
+	mso-level-tab-stop:42.0pt;
+	mso-level-number-position:left;
+	margin-left:42.0pt;
+	text-indent:-18.0pt;
+	font-family:"Courier New";
+	mso-fareast-font-family:"Times New Roman";
+	color:windowtext;
+	mso-ansi-font-style:normal;}
+@list l0:level2
+	{mso-level-tab-stop:72.0pt;
+	mso-level-number-position:left;
+	text-indent:-18.0pt;}
+@list l0:level3
+	{mso-level-tab-stop:108.0pt;
+	mso-level-number-position:left;
+	text-indent:-18.0pt;}
+@list l0:level4
+	{mso-level-tab-stop:144.0pt;
+	mso-level-number-position:left;
+	text-indent:-18.0pt;}
+@list l0:level5
+	{mso-level-tab-stop:180.0pt;
+	mso-level-number-position:left;
+	text-indent:-18.0pt;}
+@list l0:level6
+	{mso-level-tab-stop:216.0pt;
+	mso-level-number-position:left;
+	text-indent:-18.0pt;}
+@list l0:level7
+	{mso-level-tab-stop:252.0pt;
+	mso-level-number-position:left;
+	text-indent:-18.0pt;}
+@list l0:level8
+	{mso-level-tab-stop:288.0pt;
+	mso-level-number-position:left;
+	text-indent:-18.0pt;}
+@list l0:level9
+	{mso-level-tab-stop:324.0pt;
+	mso-level-number-position:left;
+	text-indent:-18.0pt;}
+ol
+	{margin-bottom:0cm;}
+ul
+	{margin-bottom:0cm;}
+-->
+</style>
+<!--[if gte mso 10]>
+<style>
+ /* Style Definitions */
+ table.MsoNormalTable
+	{mso-style-name:"Table Normal";
+	mso-tstyle-rowband-size:0;
+	mso-tstyle-colband-size:0;
+	mso-style-noshow:yes;
+	mso-style-parent:"";
+	mso-padding-alt:0cm 5.4pt 0cm 5.4pt;
+	mso-para-margin:0cm;
+	mso-para-margin-bottom:.0001pt;
+	mso-pagination:widow-orphan;
+	font-size:10.0pt;
+	font-family:"Times New Roman";}
+</style>
+<![endif]--><!--
+This HTML is auto-generated.  DO NOT EDIT THIS FILE!  If you are writing a new
+PEP, see http://www.python.org/peps/pep-0001.html for instructions and links
+to templates.  DO NOT USE THIS HTML FILE AS YOUR TEMPLATE!
+--><!--[if gte mso 9]><xml>
+ <o:shapedefaults v:ext="edit" spidmax="9218"/>
+</xml><![endif]--><!--[if gte mso 9]><xml>
+ <o:shapelayout v:ext="edit">
+  <o:idmap v:ext="edit" data="1"/>
+ </o:shapelayout></xml><![endif]-->
+</head>
+
+<body bgcolor=white lang=EN-AU link=blue vlink=blue style='tab-interval:36.0pt'>
+
+<div class=Section1>
+
+<table class=MsoNormalTable border=0 cellspacing=0 cellpadding=0 width="100%"
+ style='width:100.0%;mso-cellspacing:0cm;background:#99CCFF;mso-padding-alt:
+ 0cm 0cm 0cm 0cm'>
+ <tr style='mso-yfti-irow:0;mso-yfti-lastrow:yes;height:26.25pt'>
+  <td width="100%" style='width:100.0%;padding:0cm 0cm 0cm 0cm;height:26.25pt'>
+  <p class=MsoNormal><a href="http://www.python.org/" title="Python Home Page"><span
+  style='text-decoration:none;text-underline:none'><img border=0 width=150
+  height=35 id="_x0000_i1025"
+  src="Style%20Guide%20for%20Python%20Code,%20GA%20version_files/PyBanner040.gif"
+  alt="[Python]"></span></a></p>
+  </td>
+  <td width="100%" style='width:100.0%;padding:0cm 0cm 0cm 12.0pt;height:26.25pt'>
+  <p class=MsoNormal>[<b><a href="http://www.python.org/">Python Home</a></b>]
+  [<b><a href="http://www.python.org/peps/">PEP Index</a></b>] [<b><a
+  href="http://www.python.org/peps/pep-0008.txt">PEP Source</a></b>] </p>
+  </td>
+ </tr>
+</table>
+
+<div style='margin-left:12.0pt;margin-top:6.0pt;margin-right:12.0pt'>
+
+<p class=MsoNormal><span style='display:none;mso-hide:all'><o:p>&nbsp;</o:p></span></p>
+
+<table class=MsoNormalTable border=0 cellpadding=0 style='mso-cellspacing:1.5pt;
+ mso-padding-alt:0cm 5.4pt 0cm 5.4pt'>
+ <tr style='mso-yfti-irow:0'>
+  <td style='padding:.75pt 6.0pt .75pt .75pt'>
+  <p class=MsoNormal align=right style='text-align:right'><b><span
+  style='font-family:Arial'>PEP:&nbsp;<o:p></o:p></span></b></p>
+  </td>
+  <td style='padding:.75pt .75pt .75pt .75pt'>
+  <p class=MsoNormal>8</p>
+  </td>
+ </tr>
+ <tr style='mso-yfti-irow:1'>
+  <td style='padding:.75pt 6.0pt .75pt .75pt'>
+  <p class=MsoNormal align=right style='text-align:right'><b><span
+  style='font-family:Arial'>Title:&nbsp;<o:p></o:p></span></b></p>
+  </td>
+  <td style='padding:.75pt .75pt .75pt .75pt'>
+  <p class=MsoNormal>Style Guide for Python Code</p>
+  </td>
+ </tr>
+ <tr style='mso-yfti-irow:2'>
+  <td style='padding:.75pt 6.0pt .75pt .75pt'>
+  <p class=MsoNormal align=right style='text-align:right'><b><span
+  style='font-family:Arial'>Version:&nbsp;<o:p></o:p></span></b></p>
+  </td>
+  <td style='padding:.75pt .75pt .75pt .75pt'>
+  <p class=MsoNormal>$Revision: 1.27$ (Modified by Geoscience <st1:country-region><st1:place>Australia</st1:place></st1:country-region>)</p>
+  </td>
+ </tr>
+ <tr style='mso-yfti-irow:3'>
+  <td style='padding:.75pt 6.0pt .75pt .75pt'>
+  <p class=MsoNormal align=right style='text-align:right'><b><span
+  style='font-family:Arial'>Author:&nbsp;<o:p></o:p></span></b></p>
+  </td>
+  <td style='padding:.75pt .75pt .75pt .75pt'>
+  <p class=MsoNormal>Guido van <span class=SpellE>Rossum</span> &lt;<span
+  class=SpellE>guido</span> at python.org&gt;, Barry Warsaw &lt;<span
+  class=SpellE>barry</span> at python.org&gt;</p>
+  </td>
+ </tr>
+ <tr style='mso-yfti-irow:4'>
+  <td style='padding:.75pt 6.0pt .75pt .75pt'>
+  <p class=MsoNormal align=right style='text-align:right'><b><span
+  style='font-family:Arial'>Status:&nbsp;<o:p></o:p></span></b></p>
+  </td>
+  <td style='padding:.75pt .75pt .75pt .75pt'>
+  <p class=MsoNormal>Active</p>
+  </td>
+ </tr>
+ <tr style='mso-yfti-irow:5'>
+  <td style='padding:.75pt 6.0pt .75pt .75pt'>
+  <p class=MsoNormal align=right style='text-align:right'><b><span
+  style='font-family:Arial'>Type:&nbsp;<o:p></o:p></span></b></p>
+  </td>
+  <td style='padding:.75pt .75pt .75pt .75pt'>
+  <p class=MsoNormal>Informational</p>
+  </td>
+ </tr>
+ <tr style='mso-yfti-irow:6'>
+  <td style='padding:.75pt 6.0pt .75pt .75pt'>
+  <p class=MsoNormal align=right style='text-align:right'><b><span
+  style='font-family:Arial'>Created:&nbsp;<o:p></o:p></span></b></p>
+  </td>
+  <td style='padding:.75pt .75pt .75pt .75pt'>
+  <p class=MsoNormal><st1:date Month="7" Day="5" Year="2001">05-Jul-2001</st1:date></p>
+  </td>
+ </tr>
+ <tr style='mso-yfti-irow:7;mso-yfti-lastrow:yes'>
+  <td style='padding:.75pt 6.0pt .75pt .75pt'>
+  <p class=MsoNormal align=right style='text-align:right'><b><span
+  style='font-family:Arial'>Post-History:&nbsp;<o:p></o:p></span></b></p>
+  </td>
+  <td style='padding:.75pt .75pt .75pt .75pt'>
+  <p class=MsoNormal>Modified slightly by Ole Nielsen &lt;<span class=SpellE>Ole.Nielsen</span>
+  at ga.gov.au&gt; and Duncan Gray &lt;<span class=SpellE>Duncan.gray</span> at
+  ga.gov.au&gt;</p>
+  <p class=MsoNormal>Geoscience Australia 2005. </p>
+  <p class=MsoNormal>The GA modifications are clearly flagged using blue
+  italics and reasons outlined.</p>
+  </td>
+ </tr>
+</table>
+
+</div>
+
+<div class=MsoNormal align=center style='text-align:center'>
+
+<hr size=2 width="100%" align=center>
+
+</div>
+
+<div style='margin-left:12.0pt;margin-right:12.0pt'>
+
+<h3>Introduction</h3>
+
+<pre><span style='mso-spacerun:yes'>    </span>This document gives coding conventions for the Python code</pre><pre><span style='mso-spacerun:yes'>    </span><span
+class=GramE>comprising</span> the standard library for the main Python distribution.</pre><pre><span style='mso-spacerun:yes'>    </span>Please see the companion informational PEP describing style</pre><pre><span style='mso-spacerun:yes'>    </span><span
+class=GramE>guidelines</span> for the C code in the C implementation of Python[1].</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>This document was adapted from Guido's original Python Style</pre><pre><span style='mso-spacerun:yes'>    </span>Guide <span
+class=GramE>essay[</span>2], with some additions from Barry's style guide[5].</pre><pre><span style='mso-spacerun:yes'>    </span>Where there's conflict, Guido's style rules for the purposes of</pre><pre><span style='mso-spacerun:yes'>    </span><span
+class=GramE>this</span> PEP.<span style='mso-spacerun:yes'>  </span>This PEP may still be incomplete (in fact, it may never</pre><pre><span style='mso-spacerun:yes'>    </span><span
+class=GramE>be</span> finished &lt;wink&gt;).</pre><pre><o:p>&nbsp;</o:p></pre><pre><o:p>&nbsp;</o:p></pre>
+
+<h3>A Foolish Consistency is the Hobgoblin of Little Minds</h3>
+
+<pre><span style='mso-spacerun:yes'>    </span>A style guide is about consistency.<span style='mso-spacerun:yes'>  </span>Consistency with this style</pre><pre><span style='mso-spacerun:yes'>    </span><span
+class=GramE>guide</span> is important.<span style='mso-spacerun:yes'>  </span>Consistency within a project is more</pre><pre><span style='mso-spacerun:yes'>    </span><span
+class=GramE>important</span>. Consistency within one module or function is most</pre><pre><span style='mso-spacerun:yes'>    </span><span
+class=GramE>important</span>.</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>But most importantly: know when to be inconsistent -- sometimes</pre><pre><span style='mso-spacerun:yes'>    </span><span
+class=GramE>the</span> style guide just doesn't apply.<span style='mso-spacerun:yes'>  </span>When in doubt, use your best</pre><pre><span style='mso-spacerun:yes'>    </span><span
+class=GramE>judgement</span>.<span style='mso-spacerun:yes'>  </span>Look at other examples and decide what looks best.</pre><pre><span style='mso-spacerun:yes'>    </span>And don't hesitate to ask!</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>Two good reasons to break a particular rule:</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>(1) When applying the rule would make the code less readable, even</pre><pre><span style='mso-spacerun:yes'>        </span><span
+class=GramE>for</span> someone who is used to reading code that follows the rules.</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>(2) To be consistent with surrounding code that also breaks it</pre><pre><span style='mso-spacerun:yes'>        </span>(<span
+class=GramE>maybe</span> for historic reasons) -- <span class=GramE>although</span> this is also an</pre><pre><span style='mso-spacerun:yes'>        </span><span
+class=GramE>opportunity</span> to clean up someone else's mess (in true XP style).</pre><pre><o:p>&nbsp;</o:p></pre><pre><o:p>&nbsp;</o:p></pre>
+
+<h3>Code lay-out</h3>
+
+<pre><span style='mso-spacerun:yes'>  </span>Indentation</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>Use the default of Emacs' Python-mode: 4 spaces for one</pre><pre><span style='mso-spacerun:yes'>    </span><span
+class=GramE>indentation</span> level.<span style='mso-spacerun:yes'>  </span>For really old code that you don't want to</pre><pre><span style='mso-spacerun:yes'>    </span><span
+class=GramE>mess</span> up, you can continue to use 8-space tabs.<span style='mso-spacerun:yes'>  </span>Emacs Python-mode</pre><pre><span style='mso-spacerun:yes'>    </span><span
+class=GramE>auto-</span>detects the prevailing indentation level used in a file and</pre><pre><span style='mso-spacerun:yes'>    </span><span
+class=GramE>sets</span> its indentation parameters accordingly.</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>  </span><span
+class=GramE>Tabs or Spaces?</span></pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>Never mix tabs and spaces.<span style='mso-spacerun:yes'>  </span>The most popular way of indenting</pre><pre><span style='mso-spacerun:yes'>    </span>Python is with spaces only.<span style='mso-spacerun:yes'>  </span>The second-most popular way is with</pre><pre><span style='mso-spacerun:yes'>    </span><span
+class=GramE>tabs</span> only.<span style='mso-spacerun:yes'>  </span>Code indented with a mixture of tabs and spaces should</pre><pre><span style='mso-spacerun:yes'>    </span><span
+class=GramE>be</span> converted to using spaces exclusively.<span style='mso-spacerun:yes'>  </span>(In Emacs, select the</pre><pre><span style='mso-spacerun:yes'>    </span><span
+class=GramE>whole</span> buffer and hit ESC-x <span class=SpellE>untabify</span>.)<span style='mso-spacerun:yes'>  </span>When invoking the python</pre><pre><span style='mso-spacerun:yes'>    </span><span
+class=GramE>command</span> line interpreter with the -t option, it issues warnings</pre><pre><span style='mso-spacerun:yes'>    </span><span
+class=GramE>about</span> code that illegally mixes tabs and spaces.<span style='mso-spacerun:yes'>  </span>When using -<span
+class=SpellE>tt</span></pre><pre><span style='mso-spacerun:yes'>    </span><span
+class=GramE>these</span> warnings become errors.<span style='mso-spacerun:yes'>  </span>These options are highly</pre><pre><span style='mso-spacerun:yes'>    </span><span
+class=GramE>recommended</span>!</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>For new projects, spaces-only are strongly recommended over tabs.</pre><pre><span style='mso-spacerun:yes'>    </span>Most editors have features that make this easy to do.<span style='mso-spacerun:yes'>  </span>(In Emacs,</pre><pre><span style='mso-spacerun:yes'>    </span><span
+class=GramE>make</span> sure indent-tabs-mode is nil).</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>  </span>Maximum Line Length</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>There are still many devices around that are limited to 80</pre><pre><span style='mso-spacerun:yes'>    </span><span
+class=GramE>character</span> lines; plus, limiting windows to 80 characters makes it</pre><pre><span style='mso-spacerun:yes'>    </span><span
+class=GramE>possible</span> to have several windows side-by-side.<span style='mso-spacerun:yes'>  </span>The default</pre><pre><span style='mso-spacerun:yes'>    </span><span
+class=GramE>wrapping</span> on such devices looks ugly.<span style='mso-spacerun:yes'>  </span>Therefore, please limit all</pre><pre><span style='mso-spacerun:yes'>    </span><span
+class=GramE>lines</span> to a maximum of 79 characters (Emacs wraps lines that are</pre><pre><span style='mso-spacerun:yes'>    </span><span
+class=GramE>exactly</span> 80 characters long).<span style='mso-spacerun:yes'>  </span>For flowing long blocks of text</pre><pre><span style='mso-spacerun:yes'>    </span>(<span
+class=SpellE>docstrings</span> or comments), limiting the length to 72 characters is</pre><pre><span style='mso-spacerun:yes'>    </span><span
+class=GramE>recommended</span>.</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>The preferred way of wrapping long lines is by using Python's</pre><pre><span style='mso-spacerun:yes'>    </span><span
+class=GramE>implied</span> line continuation inside parentheses, brackets and braces.</pre><pre><span style='mso-spacerun:yes'>    </span>If necessary, you can add an extra pair of parentheses around an</pre><pre><span style='mso-spacerun:yes'>    </span><span
+class=GramE>expression</span>, but sometimes using a backslash looks better.<span style='mso-spacerun:yes'>  </span>Make</pre><pre><span style='mso-spacerun:yes'>    </span><span
+class=GramE>sure</span> to indent the continued line appropriately.<span style='mso-spacerun:yes'>  </span>Emacs</pre><pre><span style='mso-spacerun:yes'>    </span>Python-mode does this right.<span style='mso-spacerun:yes'>  </span>Some examples:</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span><span
+class=GramE>class</span> Rectangle(Blob):</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>        </span><span
+class=GramE>def</span> __init__(self, width, height,</pre><pre><span style='mso-spacerun:yes'>                     </span><span
+class=SpellE>color</span>='black', emphasis=None, highlight=0):</pre><pre><span style='mso-spacerun:yes'>            </span><span
+class=GramE>if</span> width == 0 and height == 0 and \</pre><pre><span style='mso-spacerun:yes'>               </span><span
+class=SpellE>color</span> == 'red' and emphasis == 'strong' or \</pre><pre><span style='mso-spacerun:yes'>               </span><span
+class=GramE>highlight</span> &gt; 100:</pre><pre><span style='mso-spacerun:yes'>                </span><span
+class=GramE>raise</span> <span class=SpellE>ValueError</span>(&quot;sorry, you lose&quot;)</pre><pre><span style='mso-spacerun:yes'>            </span><span
+class=GramE>if</span> width == 0 and height == 0 and (<span class=SpellE>color</span> == 'red' or</pre><pre><span style='mso-spacerun:yes'>                          </span><span style='mso-spacerun:yes'>                     </span><span
+class=GramE>emphasis</span> is None):</pre><pre><span style='mso-spacerun:yes'>                </span><span
+class=GramE>raise</span> <span class=SpellE>ValueError</span>(&quot;I don't think so&quot;)</pre><pre><span style='mso-spacerun:yes'>            </span><span
+class=SpellE>Blob.__init</span>_<span class=GramE>_(</span>self, width, height,</pre><pre><span style='mso-spacerun:yes'>                          </span><span
+class=SpellE>color</span>, emphasis, highlight)</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>  </span>Blank Lines</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>Separate top-level function and class definitions with two blank</pre><pre><span style='mso-spacerun:yes'>    </span><span
+class=GramE>lines</span>.<span style='mso-spacerun:yes'>  </span>Method definitions inside a class are separated by a</pre><pre><span style='mso-spacerun:yes'>    </span><span
+class=GramE>single</span> blank line.<span style='mso-spacerun:yes'>  </span>Extra blank lines may be used (<s>sparingly</s> <i
+style='mso-bidi-font-style:normal'><span style='color:blue'>liberally</span></i>) to</pre><pre><span style='mso-spacerun:yes'>    </span><span
+class=GramE>separate</span> groups of related functions.<span style='mso-spacerun:yes'>  </span>Blank lines may be omitted</pre><pre><span style='mso-spacerun:yes'>    </span><span
+class=GramE>between</span> a bunch of related one-liners (e.g. a set of dummy</pre><pre><span style='mso-spacerun:yes'>    </span><span
+class=GramE>implementations</span>).</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>When blank lines are used to separate method definitions, there is</pre><pre><span style='mso-spacerun:yes'>    </span><span
+class=GramE>also</span> a blank line between the `class' line and the first method</pre><pre><span style='mso-spacerun:yes'>    </span><span
+class=GramE>definition</span>.</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>Use blank lines in functions, <s>sparingly</s> <i
+style='mso-bidi-font-style:normal'><span style='color:blue'>liberally</span></i>, to indicate logical</pre><pre><span style='mso-spacerun:yes'>    </span><span
+class=GramE>sections</span>.</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>Python accepts the control-L (i.e. ^L) form feed character as</pre><pre><span style='mso-spacerun:yes'>    </span><span
+class=SpellE>whitespace</span>; Emacs (and some printing tools) treat these</pre><pre><span style='mso-spacerun:yes'>    </span><span
+class=GramE>characters</span> as page separators, so you may use them to separate</pre><pre><span style='mso-spacerun:yes'>    </span><span
+class=GramE>pages</span> of related sections of your file.</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>  </span>Encodings (<a
+href="http://www.python.org/peps/pep-0263.html">PEP 263</a>)</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>Code in the core Python distribution should <span
+class=SpellE>aways</span> use the ASCII or</pre><pre><span style='mso-spacerun:yes'>    </span><span
+class=GramE>Latin-1 encoding (a.k.a. ISO-8859-1).</span><span style='mso-spacerun:yes'>  </span>Files using ASCII should</pre><pre><span style='mso-spacerun:yes'>    </span><span
+class=GramE>not</span> have a coding cookie.<span style='mso-spacerun:yes'>  </span>Latin-1 should only be used when a</pre><pre><span style='mso-spacerun:yes'>    </span><span
+class=GramE>comment</span> or <span class=SpellE>docstring</span> needs to mention an author name that requires</pre><pre><span style='mso-spacerun:yes'>    </span>Latin-1; otherwise, using \x escapes is the preferred way to</pre><pre><span style='mso-spacerun:yes'>    </span><span
+class=GramE>include</span> non-ASCII data in string literals.<span style='mso-spacerun:yes'>  </span>An exception is made</pre><pre><span style='mso-spacerun:yes'>    </span><span
+class=GramE>for</span> those files that are part of the test suite for the code</pre><pre><span style='mso-spacerun:yes'>    </span><span
+class=GramE>implementing</span> <a
+href="http://www.python.org/peps/pep-0263.html">PEP 263</a>.</pre><pre><o:p>&nbsp;</o:p></pre><pre><o:p>&nbsp;</o:p></pre>
+
+<h3>Imports</h3>
+
+<pre><span style='mso-spacerun:yes'>    </span>- Imports should usually be on separate lines, e.g.:</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>        </span>No:<span style='mso-spacerun:yes'>  </span>import sys, <span
+class=SpellE>os</span></pre><pre><span style='mso-spacerun:yes'>        </span>Yes: import sys</pre><pre><span style='mso-spacerun:yes'>             </span><span
+class=GramE>import</span> <span class=SpellE>os</span></pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>it's</span> okay to say this though:</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>        </span><span
+class=GramE>from</span> types import <span class=SpellE>StringType</span>, <span
+class=SpellE>ListType</span></pre><pre><o:p>&nbsp;</o:p></pre><pre
+style='margin-left:42.0pt;text-indent:-18.0pt;mso-list:l0 level1 lfo2'><![if !supportLists]><span
+style='mso-fareast-font-family:"Courier New"'><span style='mso-list:Ignore'>-<span
+style='font:7.0pt "Times New Roman"'>&nbsp;&nbsp; </span></span></span><![endif]><span style='mso-spacerun:yes'> </span>Imports are always put at the top of the file (<i
+style='mso-bidi-font-style:normal'><span style='color:blue'>or top of <o:p></o:p></span></i></pre><pre
+style='margin-left:24.0pt'><i style='mso-bidi-font-style:normal'><span
+style='color:blue'><span style='mso-spacerun:yes'>  </span><span class=GramE>the</span> function/method/class in cases where the import is optional <o:p></o:p></span></i></pre><pre
+style='margin-left:24.0pt'><i style='mso-bidi-font-style:normal'><span
+style='color:blue'><span style='mso-spacerun:yes'>  </span><span class=GramE>or</span> very slow to load</span></i>), just after any module comments and <span
+class=SpellE>docstrings</span>, </pre><pre style='margin-left:24.0pt'><i
+style='mso-bidi-font-style:normal'><span style='color:blue'><span style='mso-spacerun:yes'>  </span></span></i><span
+class=GramE>and</span> before module <span class=SpellE>globals</span> and constants.<span style='mso-spacerun:yes'>  </span>Imports should be grouped, </pre><pre
+style='margin-left:24.0pt'><span style='mso-spacerun:yes'>  </span><span
+class=GramE>with</span> the order being</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>  </span><span style='mso-spacerun:yes'>    </span>1. <span
+class=GramE>standard</span> library imports</pre><pre><span style='mso-spacerun:yes'>      </span>2. <span
+class=GramE>related</span> major package imports (i.e. all email package imports next)</pre><pre><span style='mso-spacerun:yes'>      </span>3. <span
+class=GramE>application</span> specific imports</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>      </span>You should put a blank line between each group of imports.</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>- Relative imports for intra-package imports are highly</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>discouraged</span>.<span style='mso-spacerun:yes'>  </span>Always use the absolute package path for all</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>imports</span>. <i style='mso-bidi-font-style:normal'><span
+style='color:blue'>Package imports should be relative to a directory on the PYTHONPATH.</span></i> </pre><pre><o:p>&nbsp;</o:p></pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>- When importing a class from a class-containing module, it's usually</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>okay</span> to spell this</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>        </span><span
+class=GramE>from</span> <span class=SpellE>MyClass</span> import <span
+class=SpellE>MyClass</span></pre><pre><span style='mso-spacerun:yes'>        </span><span
+class=GramE>from</span> <span class=SpellE>foo.bar.YourClass</span> import <span
+class=SpellE>YourClass</span></pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>      </span>If this spelling causes local name clashes, then spell them</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>        </span><span
+class=GramE>import</span> <span class=SpellE>MyClass</span></pre><pre><span style='mso-spacerun:yes'>        </span><span
+class=GramE>import</span> <span class=SpellE>foo.bar.YourClass</span></pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>and</span> use &quot;<span class=SpellE>MyClass.MyClass</span>&quot; and &quot;<span
+class=SpellE>foo.bar.YourClass.YourClass</span>&quot;</pre><pre><span
+style='mso-tab-count:1'>      </span></pre><pre style='margin-left:24.0pt'><span
+style='mso-tab-count:1'>  </span><i style='mso-bidi-font-style:normal'><span
+style='color:blue'>Using import * is discouraged except for special cases like <o:p></o:p></span></i></pre><pre
+style='margin-left:24.0pt'><i style='mso-bidi-font-style:normal'><span
+style='color:blue'><span style='mso-spacerun:yes'>  </span><span class=GramE>unit</span> testing where only one module is imported. The reason <o:p></o:p></span></i></pre><pre
+style='margin-left:24.0pt'><i style='mso-bidi-font-style:normal'><span
+style='color:blue'><span style='mso-spacerun:yes'>  </span><span class=GramE>being</span> that multiple * imports obscures the origin of individual <o:p></o:p></span></i></pre><pre
+style='margin-left:24.0pt'><i style='mso-bidi-font-style:normal'><span
+style='color:blue'><span style='mso-spacerun:yes'>  </span><span class=GramE>objects</span> making debugging much harder.<span style='mso-spacerun:yes'>  </span><o:p></o:p></span></i></pre><pre><o:p>&nbsp;</o:p></pre><pre><o:p>&nbsp;</o:p></pre><pre><o:p>&nbsp;</o:p></pre><pre><o:p>&nbsp;</o:p></pre>
+
+<h3 style='tab-stops:45.8pt list 54.0pt left 91.6pt 137.4pt 183.2pt 229.0pt 274.8pt 320.6pt 366.4pt 412.2pt 458.0pt 503.8pt 549.6pt 595.4pt 641.2pt 687.0pt 732.8pt'><span
+class=SpellE>Whitespace</span> in Expressions and Statements</h3>
+
+<pre><span style='mso-spacerun:yes'>  </span>Pet Peeves</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>Guido hates <span
+class=SpellE>whitespace</span> in the following places:</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>- Immediately inside parentheses, brackets or braces, as in:</pre><pre><span style='mso-spacerun:yes'>      </span>&quot;<span
+class=GramE>spam(</span> ham[ 1 ], { eggs: 2 } )&quot;.<span style='mso-spacerun:yes'>  </span>Always write this as</pre><pre><span style='mso-spacerun:yes'>      </span>&quot;<span
+class=GramE>spam(</span>ham[1], {eggs: 2})&quot;.</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>- Immediately before a comma, semicolon, or colon, as in:</pre><pre><span style='mso-spacerun:yes'>      </span><span
+lang=ES style='mso-ansi-language:ES'>&quot;<span class=SpellE>if</span> x == <span
+class=GramE>4 :</span> <span class=SpellE>print</span> x , y ; x , y = y , x&quot;.<span style='mso-spacerun:yes'>  </span></span>Always write this as</pre><pre><span style='mso-spacerun:yes'>      </span><span
+lang=ES style='mso-ansi-language:ES'>&quot;<span class=SpellE>if</span> x == 4: <span
+class=SpellE>print</span> x, y; x, y = y, x&quot;.<o:p></o:p></span></pre><pre><span
+lang=ES style='mso-ansi-language:ES'><o:p>&nbsp;</o:p></span></pre><pre><span
+lang=ES style='mso-ansi-language:ES'><span style='mso-spacerun:yes'>    </span></span>- Immediately before the open parenthesis that starts the argument</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>list</span> of a function call, as in &quot;spam (1)&quot;.<span style='mso-spacerun:yes'>  </span>Always write</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>this</span> as &quot;spam(1)&quot;.</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>- Immediately before the open parenthesis that starts an indexing or</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>slicing</span>, as in: &quot;<span class=SpellE>dict</span> ['key'] = list [index]&quot;.<span style='mso-spacerun:yes'>  </span>Always</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>write</span> this as &quot;<span class=SpellE>dict</span>['key'] = list[index]&quot;.</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>- More than one space around an assignment (or other) operator to</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>align</span> it with another, as in:</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>          </span>x<span style='mso-spacerun:yes'>             </span>= 1</pre><pre><span style='mso-spacerun:yes'>          </span>y<span style='mso-spacerun:yes'>             </span>= 2</pre><pre> <span style='mso-spacerun:yes'>         </span><span
+class=SpellE>long_variable</span> = 3</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>      </span>Always write this as</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>          </span>x = 1</pre><pre><span style='mso-spacerun:yes'>          </span>y = 2</pre><pre><span style='mso-spacerun:yes'>          </span><span
+class=SpellE>long_variable</span> = 3</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>(Don't bother to argue with him on any of the above -- Guido's</pre><pre><span style='mso-spacerun:yes'>    </span><span
+class=GramE>grown</span> accustomed to this style over 20 years.)</pre><pre><o:p>&nbsp;</o:p></pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>  </span>Other Recommendations</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>- Always surround these binary operators with a single space on</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>either</span> side: assignment (=), comparisons (==, &lt;, &gt;, !=, &lt;&gt;, &lt;=,</pre><pre><span style='mso-spacerun:yes'>      </span>&gt;=, in, not in, is, is not), Booleans (and, or, not).</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>- Use your better judgment for the insertion of spaces around</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>arithmetic</span> operators.<span style='mso-spacerun:yes'>  </span>Always be consistent about <span
+class=SpellE>whitespace</span> on</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>either</span> side of a binary operator.<span style='mso-spacerun:yes'>  </span>Some examples:</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>          </span><span
+class=SpellE>i</span> = i+1</pre><pre><span style='mso-spacerun:yes'>          </span><span
+class=GramE>submitted</span> = submitted + 1</pre><pre><span style='mso-spacerun:yes'>          </span>x = x*2 - 1</pre><pre><span style='mso-spacerun:yes'>          </span><span
+lang=ES style='mso-ansi-language:ES'>hypot2 = <span class=SpellE>x*x</span> + <span
+class=SpellE>y*y</span><o:p></o:p></span></pre><pre><span lang=ES
+style='mso-ansi-language:ES'><span style='mso-spacerun:yes'>          </span>c = (<span
+class=SpellE>a+b</span>) * (a-b)<o:p></o:p></span></pre><pre><span lang=ES
+style='mso-ansi-language:ES'><span style='mso-spacerun:yes'>          </span></span>c = (a + b) * (a - b)</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>- Don't use spaces around the '=' sign when used to indicate a</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>keyword</span> argument or a default parameter value.<span style='mso-spacerun:yes'>  </span>For instance:</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>          </span><span
+class=GramE>def</span> complex(real, <span class=SpellE>imag</span>=0.0):</pre><pre><span style='mso-spacerun:yes'>            </span><span style='mso-spacerun:yes'>  </span><span
+class=GramE>return</span> magic(r=real, <span class=SpellE>i</span>=<span
+class=SpellE>imag</span>)</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>- Compound statements (multiple statements on the same line) are</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>generally</span> discouraged.</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>          </span>No:<span style='mso-spacerun:yes'>  </span>if <span
+class=SpellE>foo</span> == 'blah': <span class=SpellE>do_blah_<span
+class=GramE>thing</span></span><span class=GramE>()</span></pre><pre><span style='mso-spacerun:yes'>          </span>Yes: if <span
+class=SpellE>foo</span> == 'blah':</pre><pre><span style='mso-spacerun:yes'>                   </span><span
+class=SpellE>do_blah_<span class=GramE>thing</span></span><span class=GramE>()</span></pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>       </span><span style='mso-spacerun:yes'>   </span>No:<span style='mso-spacerun:yes'>  </span><span
+class=SpellE>do_<span class=GramE>one</span></span><span class=GramE>(</span>); <span
+class=SpellE>do_two</span>(); <span class=SpellE>do_three</span>()</pre><pre><span style='mso-spacerun:yes'>          </span>Yes: <span
+class=SpellE>do_<span class=GramE>one</span></span><span class=GramE>()</span></pre><pre><span style='mso-spacerun:yes'>               </span><span
+class=SpellE>do_<span class=GramE>two</span></span><span class=GramE>()</span></pre><pre><span style='mso-spacerun:yes'>               </span><span
+class=SpellE>do_<span class=GramE>three</span></span><span class=GramE>()</span></pre><pre><o:p>&nbsp;</o:p></pre>
+
+<h3 style='tab-stops:45.8pt list 54.0pt left 91.6pt 137.4pt 183.2pt 229.0pt 274.8pt 320.6pt 366.4pt 412.2pt 458.0pt 503.8pt 549.6pt 595.4pt 641.2pt 687.0pt 732.8pt'>Comments</h3>
+
+<pre><span style='mso-spacerun:yes'>    </span>Comments that contradict the code are worse than no comments.</pre><pre><span style='mso-spacerun:yes'>    </span>Always make a priority of keeping the comments up-to-date when the</pre><pre><span style='mso-spacerun:yes'>    </span><span
+class=GramE>code</span> changes!</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>Comments should be complete sentences.<span style='mso-spacerun:yes'>  </span>If a comment is a phrase</pre><pre><span style='mso-spacerun:yes'>    </span><span
+class=GramE>or</span> sentence, its first word should be capitalized, unless it is an</pre><pre><span style='mso-spacerun:yes'>    </span><span
+class=GramE>identifier</span> that begins with a lower case letter (never alter the</pre><pre><span style='mso-spacerun:yes'>    </span><span
+class=GramE>case</span> of identifiers!).</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>If a comment is short, the period at the end is best omitted.</pre><pre><span style='mso-spacerun:yes'>    </span>Block comments generally consist of one or more paragraphs built</pre><pre><span style='mso-spacerun:yes'>    </span><span
+class=GramE>out</span> of complete sentences, and each sentence should end in a</pre><pre><span style='mso-spacerun:yes'>    </span><span
+class=GramE>period</span>.</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>You should use two spaces after a sentence-ending period, since it</pre><pre><span style='mso-spacerun:yes'>    </span><span
+class=GramE>makes</span> Emacs wrapping and filling work <span class=SpellE>consistenty</span>.</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>When writing English, <span
+class=SpellE>Strunk</span> and White apply.</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>Python coders from non-English speaking countries: please write</pre><pre><span style='mso-spacerun:yes'>    </span><span
+class=GramE>your</span> comments in English, unless you are 120% sure that the code</pre><pre><span style='mso-spacerun:yes'>    </span><span
+class=GramE>will</span> never be read by people who don't speak your language.</pre><pre><o:p>&nbsp;</o:p></pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>  </span>Block Comments</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>Block comments generally apply to some (or all) code that follows</pre><pre><span style='mso-spacerun:yes'>    </span><span
+class=GramE>them</span>, and are indented to the same level as that code.<span style='mso-spacerun:yes'>  </span>Each line</pre><pre><span style='mso-spacerun:yes'>    </span><span
+class=GramE>of</span> a block comment starts with a # and a single space (unless it</pre><pre><span style='mso-spacerun:yes'>    </span><span
+class=GramE>is</span> indented text inside the comment).<span style='mso-spacerun:yes'>  </span>Paragraphs inside a block</pre><pre><span style='mso-spacerun:yes'>    </span><span
+class=GramE>comment</span> are separated by a line containing a single #.<span style='mso-spacerun:yes'>  </span>Block</pre><pre><span style='mso-spacerun:yes'>    </span><span
+class=GramE>comments</span> are best surrounded by a blank line above and below them</pre><pre><span style='mso-spacerun:yes'>    </span>(<span
+class=GramE>or</span> two lines above and a single line below for a block comment at</pre><pre><span style='mso-spacerun:yes'>    </span><span
+class=GramE>the</span> start of a <span class=SpellE>a</span> new section of function definitions <i
+style='mso-bidi-font-style:normal'><span style='color:blue'>or to delimit <o:p></o:p></span></i></pre><pre><i
+style='mso-bidi-font-style:normal'><span style='color:blue'><span style='mso-spacerun:yes'>    </span><span
+class=GramE>logical</span> sections</span></i>).</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>  </span>Inline Comments</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>An inline comment is a comment on the same line as a statement.</pre><pre><span style='mso-spacerun:yes'>    </span>Inline comments should be used sparingly.<span style='mso-spacerun:yes'>  </span>Inline comments should</pre><pre><span style='mso-spacerun:yes'>    </span><span
+class=GramE>be</span> separated by at least two spaces from the statement.<span style='mso-spacerun:yes'>  </span>They</pre><pre><span style='mso-spacerun:yes'>    </span><span
+class=GramE>should</span> start with a # and a single space.</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>Inline comments are unnecessary and in fact distracting if they state</pre><pre><span style='mso-spacerun:yes'>    </span><span
+class=GramE>the</span> obvious.<span style='mso-spacerun:yes'>  </span>Don't do this:</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>        </span>x = x+1<span style='mso-spacerun:yes'>                 </span># Increment x</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>But sometimes, this is useful:</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>        </span>x = x+1<span style='mso-spacerun:yes'>                 </span># Compensate for border</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>  </span>Developer Comments</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>If software is being created in a multi-developer environment, it is often</pre><pre><span style='mso-spacerun:yes'>    </span><span
+class=GramE>useful</span> to comment the code to indicate those sections which require updating </pre><pre><span style='mso-spacerun:yes'>    </span><span
+class=GramE>or</span> refining. They should start with #FIXME followed by the name of the </pre><pre><span style='mso-spacerun:yes'>    </span><span
+class=GramE>developer</span> in standard brackets. The name should be consistent amongst the</pre><pre><span style='mso-spacerun:yes'>    </span><span
+class=GramE>group</span>; either full initials, first name or surname. For example, if </pre><pre><span style='mso-spacerun:yes'>    </span>Duncan S Gray found an issue, he could insert in the code:</pre><pre><o:p>&nbsp;</o:p></pre><pre
+style='margin-top:0cm;margin-right:12.0pt;margin-bottom:0cm;margin-left:12.0pt;
+margin-bottom:.0001pt'><span style='mso-spacerun:yes'>    </span>#FIXME (DSG): Should check that function returns something sensible and</pre><pre><span style='mso-spacerun:yes'>      </span>#<span
+class=GramE>raise</span> a meaningful exception if it returns None for example</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>This allows other developers to identify areas which require attention with </pre><pre><span style='mso-spacerun:yes'>    </span><span
+class=GramE>the</span> added bonus of knowing who logged the issue.</pre><pre><o:p>&nbsp;</o:p></pre>
+
+<h3 style='tab-stops:45.8pt list 54.0pt left 91.6pt 137.4pt 183.2pt 229.0pt 274.8pt 320.6pt 366.4pt 412.2pt 458.0pt 503.8pt 549.6pt 595.4pt 641.2pt 687.0pt 732.8pt'>Documentation
+Strings</h3>
+
+<pre><span style='mso-spacerun:yes'>    </span>Conventions for writing good documentation strings</pre><pre><span style='mso-spacerun:yes'>    </span>(a.k.a. &quot;<span
+class=SpellE>docstrings</span>&quot;) are immortalized in <a
+href="http://www.python.org/peps/pep-0257.html">PEP 257</a> [3].</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>- Write <span
+class=SpellE>docstrings</span> for all public modules, functions, classes, and</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>methods</span>.<span style='mso-spacerun:yes'>  </span><span
+class=SpellE>Docstrings</span> are not necessary for non-public methods,</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>but</span> you should have a comment that describes what the method</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>does</span>.<span style='mso-spacerun:yes'>  </span>This comment should appear after the &quot;def&quot; line.</pre><pre><span
+style='mso-tab-count:1'>      </span><i style='mso-bidi-font-style:normal'><span
+style='color:blue'>Ideally, all modules, functions, classes, and methods should have <o:p></o:p></span></i></pre><pre><i
+style='mso-bidi-font-style:normal'><span style='color:blue'><span style='mso-spacerun:yes'>      </span><span
+class=GramE>a</span> <span class=SpellE>docstring</span>.<o:p></o:p></span></i></pre><pre><i
+style='mso-bidi-font-style:normal'><span style='color:blue'> <span style='mso-spacerun:yes'>   </span>- For test methods #s are preferred, over <span
+class=SpellE>docstrings</span>.<span style='mso-spacerun:yes'>  </span><span
+class=SpellE>Docstrings</span> dont <o:p></o:p></span></i></pre><pre><i
+style='mso-bidi-font-style:normal'><span style='color:blue'><span
+style='mso-tab-count:1'>      </span>work well with verbose=2. <o:p></o:p></span></i></pre><pre><i
+style='mso-bidi-font-style:normal'><span style='color:blue'><o:p>&nbsp;</o:p></span></i></pre><pre><i
+style='mso-bidi-font-style:normal'><span style='color:blue'><o:p>&nbsp;</o:p></span></i></pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>- <a
+href="http://www.python.org/peps/pep-0257.html">PEP 257</a> describes good <span
+class=SpellE>docstring</span> conventions.<span style='mso-spacerun:yes'>  </span>Note that most</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>importantly</span>, the &quot;&quot;&quot; that ends a <span
+class=SpellE>multiline</span> <span class=SpellE>docstring</span> should be</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>on</span> a line by itself, e.g.:</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>      </span>&quot;&quot;&quot;Return a <span
+class=SpellE>foobang</span></pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>      </span>Optional <span
+class=SpellE>plotz</span> says to <span class=SpellE>frobnicate</span> the <span
+class=SpellE>bizbaz</span> first.</pre><pre><span style='mso-spacerun:yes'>      </span>&quot;&quot;&quot;</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>- For one liner <span
+class=SpellE>docstrings</span>, it's okay to keep the closing &quot;&quot;&quot; on</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>the</span> same line.</pre><pre><o:p>&nbsp;</o:p></pre><pre><o:p>&nbsp;</o:p></pre>
+
+<h3 style='tab-stops:45.8pt list 54.0pt left 91.6pt 137.4pt 183.2pt 229.0pt 274.8pt 320.6pt 366.4pt 412.2pt 458.0pt 503.8pt 549.6pt 595.4pt 641.2pt 687.0pt 732.8pt'>Version
+Bookkeeping</h3>
+
+<pre><span style='mso-spacerun:yes'>    </span>If you have to have RCS or CVS crud in your source file, do it as</pre><pre><span style='mso-spacerun:yes'>    </span><span
+class=GramE>follows</span>.</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>        </span>__version__ = &quot;$Revision: 1.27 $&quot;</pre><pre><span style='mso-spacerun:yes'>        </span># $Source: /cvsroot/python/python/nondist/peps/pep-0008.txt,v $</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>These lines should be included after the module's <span
+class=SpellE>docstring</span>,</pre><pre><span style='mso-spacerun:yes'>    </span><span
+class=GramE>before</span> any other code, separated by a blank line above and</pre><pre><span style='mso-spacerun:yes'>    </span><span
+class=GramE>below</span>.</pre><pre><o:p>&nbsp;</o:p></pre><pre><o:p>&nbsp;</o:p></pre>
+
+<h3 style='tab-stops:45.8pt list 54.0pt left 91.6pt 137.4pt 183.2pt 229.0pt 274.8pt 320.6pt 366.4pt 412.2pt 458.0pt 503.8pt 549.6pt 595.4pt 641.2pt 687.0pt 732.8pt'>Naming
+Conventions</h3>
+
+<pre><span style='mso-spacerun:yes'>    </span>The naming conventions of Python's library are a bit of a mess, so we'll</pre><pre><span style='mso-spacerun:yes'>    </span><span
+class=GramE>never</span> get this completely consistent -- nevertheless, here are the</pre><pre><span style='mso-spacerun:yes'>    </span><span
+class=GramE>currently</span> recommended naming standards.<span style='mso-spacerun:yes'>  </span>New modules and packages</pre><pre><span style='mso-spacerun:yes'>    </span>(<span
+class=GramE>including</span> 3rd party frameworks) should be written to these standards, but</pre><pre><span style='mso-spacerun:yes'>    </span><span
+class=GramE>where</span> an existing library has a different style, internal consistency is</pre><pre><span style='mso-spacerun:yes'>    </span><span
+class=GramE>preferred</span>.</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>  </span>Descriptive: Naming Styles</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>There are a lot of different naming styles.<span style='mso-spacerun:yes'>  </span>It helps to be able</pre><pre><span style='mso-spacerun:yes'>    </span><span
+class=GramE>to</span> recognize what naming style is being used, independently from</pre><pre><span style='mso-spacerun:yes'>    </span><span
+class=GramE>what</span> they are used for.</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>The following naming styles are commonly distinguished:</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>- <span
+class=GramE>b</span> (single lowercase letter)</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>- B (single uppercase letter)</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>- <span
+class=GramE>lowercase</span></pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>- <span
+class=SpellE>lower_case_with_underscores</span></pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>- UPPERCASE</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>- UPPER_CASE_WITH_UNDERSCORES</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>- <span
+class=SpellE>CapitalizedWords</span> (or <span class=SpellE>CapWords</span>, or <span
+class=SpellE>CamelCase</span> -- so named because</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>of</span> the bumpy look of its letters[4]).<span style='mso-spacerun:yes'>  </span>This is also sometimes known as</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=SpellE><span class=GramE>StudlyCaps</span></span><span class=GramE>.</span></pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>- <span
+class=SpellE>mixedCase</span> (differs from <span class=SpellE>CapitalizedWords</span> by initial lowercase</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>character</span>!)</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>- <span
+class=SpellE>Capitalized_Words_With_Underscores</span> (ugly!)</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>There's also the style of using a short unique prefix to group</pre><pre><span style='mso-spacerun:yes'>    </span><span
+class=GramE>related</span> names together.<span style='mso-spacerun:yes'>  </span>This is not used much in Python, but it</pre><pre><span style='mso-spacerun:yes'>    </span><span
+class=GramE>is</span> mentioned for completeness.<span style='mso-spacerun:yes'>  </span>For example, the <span
+class=SpellE><span class=GramE>os.stat</span></span><span class=GramE>()</span></pre><pre><span style='mso-spacerun:yes'>    </span><span
+class=GramE>function</span> returns a <span class=SpellE>tuple</span> whose items traditionally have names like</pre><pre><span style='mso-spacerun:yes'>    </span><span
+class=SpellE><span class=GramE>st_mode</span></span><span class=GramE>, <span
+class=SpellE>st_size</span>, <span class=SpellE>st_mtime</span> and so on.</span><span style='mso-spacerun:yes'>  </span>The X11 library uses a</pre><pre><span style='mso-spacerun:yes'>    </span><span
+class=GramE>leading</span> X for all its public functions.<span style='mso-spacerun:yes'>  </span>(In Python, this style is</pre><pre><span style='mso-spacerun:yes'>    </span><span
+class=GramE>generally</span> deemed unnecessary because attribute and method names</pre><pre><span style='mso-spacerun:yes'>    </span><span
+class=GramE>are</span> prefixed with an object, and function names are prefixed with</pre><pre><span style='mso-spacerun:yes'>    </span><span
+class=GramE>a</span> module name.)</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>In addition, the following special forms using leading or trailing</pre><pre><span style='mso-spacerun:yes'>    </span><span
+class=GramE>underscores</span> are recognized (these can generally be combined with any</pre><pre><span style='mso-spacerun:yes'>    </span><span
+class=GramE>case</span> convention):</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>- _<span
+class=SpellE>single_leading_underscore</span>: weak &quot;internal use&quot; indicator</pre><pre><span style='mso-spacerun:yes'>      </span>(e.g. &quot;from M import *&quot; does not import objects whose name</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>starts</span> with an underscore).</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>- <span
+class=SpellE>single_trailing_underscore</span>_: used by convention to avoid</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>conflicts</span> with Python keyword, e.g.</pre><pre><span style='mso-spacerun:yes'>      </span>&quot;<span
+class=SpellE><span class=GramE>Tkinter.Toplevel</span></span><span class=GramE>(</span>master, class_='<span
+class=SpellE>ClassName</span>')&quot;.</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span><span
+class=GramE>- __<span class=SpellE>double_leading_underscore</span>: class-private names as of Python 1.4.</span></pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>- __<span
+class=SpellE>double_leading_and_trailing_underscore</span>__: &quot;magic&quot; objects or</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>attributes</span> that live in user-controlled namespaces,</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>e.g. __init__, __import__ or __file__.</span><span style='mso-spacerun:yes'>  </span>Sometimes these are</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>defined</span> by the user to trigger certain magic <span
+class=SpellE>behavior</span></pre><pre><span style='mso-spacerun:yes'>      </span>(<span
+class=GramE>e.g</span>. operator overloading); sometimes these are inserted by the</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>infrastructure</span> for its own use or for debugging purposes.<span style='mso-spacerun:yes'>  </span>Since</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>the</span> infrastructure (loosely defined as the Python interpreter</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>and</span> the standard library) may decide to grow its list of magic</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>attributes</span> in future versions, user code should generally</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>refrain</span> from using this convention for its own use.<span style='mso-spacerun:yes'>  </span>User code</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>that</span> aspires to become part of the infrastructure could combine</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>this</span> with a short prefix inside the underscores,</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>e.g. __<span class=SpellE>bobo_magic_attr</span>__.</span></pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>  </span>Prescriptive: Naming Conventions</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>Names to Avoid</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>      </span>Never use the characters `l' (lowercase letter el), `O'</pre><pre><span style='mso-spacerun:yes'>      </span>(<span
+class=GramE>uppercase</span> letter oh), or `I' (uppercase letter eye) as single</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>character</span> variable names.<span style='mso-spacerun:yes'>  </span>In some fonts, these characters are</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=SpellE>indistinguisable</span> from the numerals one and zero.<span style='mso-spacerun:yes'>  </span>When tempted</pre><pre
+style='margin-left:12.0pt'><span style='mso-spacerun:yes'>    </span><span
+class=GramE>to</span> use `l' use `L' instead, <i style='mso-bidi-font-style:
+normal'><span style='color:blue'>unless the mathematical formula <o:p></o:p></span></i></pre><pre
+style='margin-left:12.0pt'><i style='mso-bidi-font-style:normal'><span
+style='color:blue'><span style='mso-spacerun:yes'>    </span><span class=GramE>using</span> l would become harder to understand</span></i>.</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>Module Names</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>      </span>Modules should have short, lowercase names, <s>without</s> <i
+style='mso-bidi-font-style:normal'><span style='color:blue'>possibly with</span></i> </pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>underscores</span>.</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>      </span>Since module names are mapped to file names, and some file systems</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>are</span> case insensitive and truncate long names, it is important that</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>module</span> names be chosen to be fairly short -- this won't be a</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>problem</span> on Unix, but it may be a problem when the code is</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>transported</span> to Mac or Windows.</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>      </span>When an extension module written in C or C++ has an accompanying</pre><pre><span style='mso-spacerun:yes'>      </span>Python module that provides a higher level (e.g. more object</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>oriented</span>) interface, the C/C++ module has a leading underscore</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>(e.g. _socket).</span></pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>      </span>Python packages should have short, all-lowercase names, <s>without</s> </pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE><i style='mso-bidi-font-style:normal'><span style='color:blue'>possibly</span></i></span><i
+style='mso-bidi-font-style:normal'><span style='color:blue'> with</span></i> underscores.</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>Class Names</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>      </span>Almost without exception, class names use the <span
+class=SpellE>CapWords</span> convention.</pre><pre><span style='mso-spacerun:yes'>      </span>Classes for internal use have a leading underscore in addition.</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>Exception Names</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>      </span>If a module defines a single exception raised for all sorts of</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>conditions</span>, it is generally called &quot;error&quot; or &quot;Error&quot;.<span style='mso-spacerun:yes'>  </span>It seems</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>that</span> built-in (extension) modules use &quot;error&quot; (e.g. <span
+class=SpellE>os.error</span>),</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>while</span> Python modules generally use &quot;Error&quot; (e.g. <span
+class=SpellE>xdrlib.Error</span>).</pre><pre><span style='mso-spacerun:yes'>      </span>The trend seems to be toward <span
+class=SpellE>CapWords</span> exception names.</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>Global Variable Names</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>      </span>(Let's hope that these variables are meant for use inside one</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>module</span> only.)<span style='mso-spacerun:yes'>  </span>The conventions are about the same as those for</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>functions</span>.<span style='mso-spacerun:yes'>  </span>Modules that are designed for use via &quot;from M import *&quot;</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>should</span> prefix their <span class=SpellE>globals</span> (and internal functions and classes)</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>with</span> an underscore to prevent exporting them.</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>Function Names</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>      </span>Function names should be lowercase, possibly with words separated by</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>underscores</span> to improve readability.<span style='mso-spacerun:yes'>  </span><span
+class=SpellE>mixedCase</span> is allowed only in</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>contexts</span> where that's already the prevailing style (e.g. <span
+class=SpellE>threading.py</span>),</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>to</span> retain backwards compatibility.</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>Method Names and Instance Variables</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>      </span>The story is largely the same as with functions: in general, use</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>lowercase</span> with words separated by underscores as necessary to improve</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>readability</span>.</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>      </span>Use one leading underscore only for internal methods and instance</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>variables</span> which are not intended to be part of the class's public</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>interface</span>.<span style='mso-spacerun:yes'>  </span>Python does not enforce this; it is up to programmers to</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>respect</span> the convention.</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>      </span>Use two leading underscores to denote class-private names.<span style='mso-spacerun:yes'>  </span>Python</pre><pre><span style='mso-spacerun:yes'>      </span>&quot;<span
+class=GramE>mangles</span>&quot; these names with the class name: if class <span
+class=SpellE>Foo</span> has an</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>attribute</span> named __a, it cannot be accessed by <span
+class=SpellE>Foo.__a</span>.<span style='mso-spacerun:yes'>  </span>(An insistent</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>user</span> could still gain access by calling <span class=SpellE>Foo._Foo__a</span>.)<span style='mso-spacerun:yes'>  </span>Generally,</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>double</span> leading underscores should be used only to avoid name conflicts</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>with</span> attributes in classes designed to be subclassed.</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>Designing for inheritance</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>      </span>Always decide whether a class's methods and instance variables</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>should</span> be public or non-public.<span style='mso-spacerun:yes'>  </span>In general, never make data</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>variables</span> public unless you're implementing essentially a</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>record</span>.<span style='mso-spacerun:yes'>  </span>It's almost always <span
+class=SpellE>preferrable</span> to give a functional</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>interface</span> to your class instead (and some Python 2.2</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>developments</span> will make this much nicer). <i
+style='mso-bidi-font-style:normal'><span style='color:blue'>Consider using Pythons <o:p></o:p></span></i></pre><pre><i
+style='mso-bidi-font-style:normal'><span style='color:blue'><span style='mso-spacerun:yes'>      </span><span
+class=GramE>properties</span>.<o:p></o:p></span></i></pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>      </span>Also decide whether your attributes should be private or not.</pre><pre><span style='mso-spacerun:yes'>      </span>The difference between private and non-public is that the former</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>will</span> never be useful for a derived class, while the latter might</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>be</span>.<span style='mso-spacerun:yes'>  </span>Yes, you should design your classes with inheritance in</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>mind</span>!</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>      </span>Private attributes should have two leading underscores, no</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>trailing</span> underscores.</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>      </span>Non-public attributes should have a single leading underscore,</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>no</span> trailing underscores.</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>      </span>Public attributes should have no leading or trailing</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>underscores</span>, unless they conflict with reserved words, in which</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>case</span>, a single trailing underscore is preferable to a leading</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>one</span>, or a corrupted spelling, e.g. class_ rather than <span
+class=SpellE>klass</span>.</pre><pre><span style='mso-spacerun:yes'>      </span>(This last point is a bit controversial; if you prefer <span
+class=SpellE>klass</span></pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>over</span> class_ then just be consistent. :).</pre><pre><o:p>&nbsp;</o:p></pre><pre><o:p>&nbsp;</o:p></pre>
+
+<h3 style='tab-stops:45.8pt list 54.0pt left 91.6pt 137.4pt 183.2pt 229.0pt 274.8pt 320.6pt 366.4pt 412.2pt 458.0pt 503.8pt 549.6pt 595.4pt 641.2pt 687.0pt 732.8pt'>Programming
+Recommendations</h3>
+
+<pre><span style='mso-spacerun:yes'>    </span>- Code should be written in a way that does not disadvantage other</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>implementations</span> of Python (<span class=SpellE>PyPy</span>, <span
+class=SpellE>Jython</span>, <span class=SpellE>IronPython</span>, Pyrex, <span
+class=SpellE>Psyco</span>,</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>and</span> such).<span style='mso-spacerun:yes'>  </span>For example, do not rely on <span
+class=SpellE>CPython's</span> efficient</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>implementation</span> of in-place string concatenation for statements in</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>the</span> form a+=b or a=<span class=SpellE>a+b</span>.<span style='mso-spacerun:yes'>  </span>Those statements run more slowly in</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=SpellE><span class=GramE>Jython</span></span><span class=GramE>.</span><span style='mso-spacerun:yes'>  </span>In performance sensitive parts of the library, the</pre><pre><span style='mso-spacerun:yes'>      </span>''.<span
+class=GramE>join(</span>) form should be used instead.<span style='mso-spacerun:yes'>  </span>This will assure that</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>concatenation</span> occurs in linear time across various implementations.</pre><pre><span
+style='mso-tab-count:1'>      </span><i style='mso-bidi-font-style:normal'><span
+style='color:blue'>In performance insensitive part it is OK to use the more readable <o:p></o:p></span></i></pre><pre><i
+style='mso-bidi-font-style:normal'><span style='color:blue'><span style='mso-spacerun:yes'>      </span><span
+class=GramE>a</span>+=b and a=<span class=SpellE>a+b</span>. <o:p></o:p></span></i></pre><pre><o:p>&nbsp;</o:p></pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>- Comparisons to singletons like <span
+class=GramE>None</span> should always be done with</pre><pre><span style='mso-spacerun:yes'>      </span>'<span
+class=GramE>is</span>' or 'is not'.<span style='mso-spacerun:yes'>  </span>Also, beware of writing &quot;if x&quot; when you</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>really</span> mean &quot;if x is not None&quot; -- e.g. when testing whether a</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>variable</span> or argument that defaults to None was set to some other</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>value</span>.<span style='mso-spacerun:yes'>  </span>The other value might be a value that's false in a</pre><pre><span style='mso-spacerun:yes'>      </span>Boolean context!</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>- Class-based exceptions are always preferred over string-based</pre><pre> <span style='mso-spacerun:yes'>     </span><span
+class=GramE>exceptions</span>.<span style='mso-spacerun:yes'>  </span>Modules or packages should define their own</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>domain-specific</span> base exception class, which should be subclassed</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>from</span> the built-in Exception class.<span style='mso-spacerun:yes'>  </span>Always include a class</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=SpellE>docstring</span>.<span style='mso-spacerun:yes'>  </span>E.g.:</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>        </span><span
+class=GramE>class</span> <span class=SpellE>MessageError</span>(Exception):</pre><pre><span style='mso-spacerun:yes'>            </span><span
+class=GramE>&quot;&quot;&quot;Base class for errors in the email package.&quot;&quot;&quot;</span></pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>      </span>When raising an exception, use &quot;raise <span
+class=SpellE><span class=GramE>ValueError</span></span><span class=GramE>(</span>'message')&quot;</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>instead</span> of the older form &quot;raise <span class=SpellE>ValueError</span>, 'message'&quot;.<span style='mso-spacerun:yes'>  </span>The</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=SpellE><span class=GramE>paren</span></span><span class=GramE>-using</span> form is preferred because when the exception</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>arguments</span> are long or include string formatting, you don't need</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>to</span> use line continuation characters thanks to the containing</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>parentheses</span>.<span style='mso-spacerun:yes'>  </span>The older form will be removed in Python 3000.</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>- Use string methods instead of the string module unless</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>backward-compatibility</span> with versions earlier than Python 2.0 is</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>important</span>.<span style='mso-spacerun:yes'>  </span>String methods are always much faster and share the</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>same</span> API with <span class=SpellE>unicode</span> strings.</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>- Avoid slicing strings when checking for prefixes or suffixes.</pre><pre><span style='mso-spacerun:yes'>      </span>Use <span
+class=SpellE><span class=GramE>startswith</span></span><span class=GramE>(</span>) and <span
+class=SpellE>endswith</span>() instead, since they are</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>cleaner</span> and less error prone.<span style='mso-spacerun:yes'>  </span>For example:</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>        </span>No:<span style='mso-spacerun:yes'>  </span>if <span
+class=SpellE><span class=GramE>foo</span></span><span class=GramE>[</span>:3] == 'bar':</pre><pre><span style='mso-spacerun:yes'>        </span>Yes: if <span
+class=SpellE><span class=GramE>foo.startswith</span></span><span class=GramE>(</span>'bar'):</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>      </span>The exception is if your code must work with Python 1.5.2 (but</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>let's</span> hope not!).</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>- Object type comparisons should always use <span
+class=SpellE><span class=GramE>isinstance</span></span><span class=GramE>(</span>) instead</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>of</span> comparing types directly.<span style='mso-spacerun:yes'>  </span><span
+class=GramE>E.g.</span></pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>        </span>No:<span style='mso-spacerun:yes'>  </span>if <span
+class=GramE>type(</span>obj) is type(1):</pre><pre><span style='mso-spacerun:yes'>        </span>Yes: if <span
+class=SpellE><span class=GramE>isinstance</span></span><span class=GramE>(</span>obj, <span
+class=SpellE>int</span>):</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>      </span>When checking if an object is a string, keep in mind that it</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>might</span> be a <span class=SpellE>unicode</span> string too!<span style='mso-spacerun:yes'>  </span>In Python 2.3, <span
+class=SpellE>str</span> and <span class=SpellE>unicode</span></pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>have</span> a common base class, <span class=SpellE>basestring</span>, so you can do:</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>        </span><span
+class=GramE>if</span> <span class=SpellE>isinstance</span>(obj, <span
+class=SpellE>basestring</span>):</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>      </span>In Python 2.2, the <span
+class=GramE>types</span> module has the <span class=SpellE>StringTypes</span> type defined</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>for</span> that purpose, e.g.:</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>        </span><span
+class=GramE>from</span> types import <span class=SpellE>StringTypes</span></pre><pre><span style='mso-spacerun:yes'>        </span><span
+class=GramE>if</span> <span class=SpellE>isinstance</span>(obj, <span
+class=SpellE>StringTypes</span>):</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>      </span>In Python 2.0 and 2.1, you should do:</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>        </span><span
+class=GramE>from</span> types import <span class=SpellE>StringType</span>, <span
+class=SpellE>UnicodeType</span></pre><pre><span style='mso-spacerun:yes'>        </span><span
+class=GramE>if</span> <span class=SpellE>isinstance</span>(obj, <span
+class=SpellE>StringType</span>) or \</pre><pre><span style='mso-spacerun:yes'>           </span><span
+class=SpellE><span class=GramE>isinstance</span></span><span class=GramE>(</span>obj, <span
+class=SpellE>UnicodeType</span>) :</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>- For sequences, (strings, lists, <span
+class=SpellE>tuples</span>), use the fact that empty</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>sequences</span> are false, so &quot;if not <span class=SpellE>seq</span>&quot; or &quot;if <span
+class=SpellE>seq</span>&quot; is preferable</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>to</span> &quot;if <span class=SpellE>len</span>(<span
+class=SpellE>seq</span>)&quot; or &quot;if not <span class=SpellE>len</span>(<span
+class=SpellE>seq</span>)&quot;.</pre><pre><span style='mso-spacerun:yes'>      </span><i
+style='mso-bidi-font-style:normal'><span style='color:blue'>We prefer using if <span
+class=SpellE><span class=GramE>len</span></span><span class=GramE>(</span><span
+class=SpellE>seq</span>) == 0 to check for emptiness.<o:p></o:p></span></i></pre><pre><o:p>&nbsp;</o:p></pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>- Don't write string literals that rely on significant trailing</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=SpellE>whitespace</span>.<span style='mso-spacerun:yes'>  </span>Such trailing <span
+class=SpellE>whitespace</span> is visually</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>indistinguishable</span> and some editors (or more recently,</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=SpellE>reindent.py</span>) will trim them.</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>- Don't compare <span
+class=SpellE>boolean</span> values to True or False using == (<span
+class=SpellE>bool</span></pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>types</span> are new in Python 2.3):</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>        </span>No:<span style='mso-spacerun:yes'>  </span>if greeting == True:</pre><pre><span style='mso-spacerun:yes'>        </span>Yes: if greeting:</pre><pre><span
+style='mso-tab-count:1'>      </span><span style='mso-spacerun:yes'>  </span><i
+style='mso-bidi-font-style:normal'><span style='color:blue'>Yes:<span
+style='mso-tab-count:1'>  </span>if greeting is True:<o:p></o:p></span></i></pre><pre><o:p>&nbsp;</o:p></pre><pre><o:p>&nbsp;</o:p></pre>
+
+<h3 style='tab-stops:45.8pt list 54.0pt left 91.6pt 137.4pt 183.2pt 229.0pt 274.8pt 320.6pt 366.4pt 412.2pt 458.0pt 503.8pt 549.6pt 595.4pt 641.2pt 687.0pt 732.8pt'>References</h3>
+
+<pre><span style='mso-spacerun:yes'>    </span>[1] <a
+href="http://www.python.org/peps/pep-0007.html">PEP 7</a>, Style Guide for C Code, van <span
+class=SpellE>Rossum</span></pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>[2] <a
+href="http://www.python.org/doc/essays/styleguide.html">http://www.python.org/doc/essays/styleguide.html</a></pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>[3] <a
+href="http://www.python.org/peps/pep-0257.html">PEP 257</a>, <span
+class=SpellE>Docstring</span> Conventions, <span class=SpellE>Goodger</span>, <span
+class=GramE>van</span> <span class=SpellE>Rossum</span></pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>[4] <a
+href="http://www.wikipedia.com/wiki/CamelCase">http://www.wikipedia.com/wiki/CamelCase</a></pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>[5] Barry's GNU Mailman style guide</pre><pre><span style='mso-spacerun:yes'>      </span><span style='mso-spacerun:yes'>  </span><a
+href="http://barry.warsaw.us/software/STYLEGUIDE.txt">http://barry.warsaw.us/software/STYLEGUIDE.txt</a></pre><pre><o:p>&nbsp;</o:p></pre><pre><o:p>&nbsp;</o:p></pre>
+
+<h3 style='tab-stops:45.8pt list 54.0pt left 91.6pt 137.4pt 183.2pt 229.0pt 274.8pt 320.6pt 366.4pt 412.2pt 458.0pt 503.8pt 549.6pt 595.4pt 641.2pt 687.0pt 732.8pt'>Copyright</h3>
+
+<pre><span style='mso-spacerun:yes'>    </span>This document has been placed in the public domain.</pre><pre><o:p>&nbsp;</o:p></pre><pre><o:p>&nbsp;</o:p></pre></div>
+
+</div>
+
+</body>
+
+</html>
Index: /anuga_core/documentation/coding_standards/Style Guide for Python Code, GA version_files/style.css
===================================================================
--- /anuga_core/documentation/coding_standards/Style Guide for Python Code, GA version_files/style.css	(revision 3574)
+++ /anuga_core/documentation/coding_standards/Style Guide for Python Code, GA version_files/style.css	(revision 3574)
@@ -0,0 +1,30 @@
+BODY {
+	PADDING-RIGHT: 0px; PADDING-LEFT: 0px; PADDING-BOTTOM: 0px; MARGIN: 0px; PADDING-TOP: 0px
+}
+.navigation {
+	BACKGROUND: #99ccff; WIDTH: 100%
+}
+.navigation .navicon {
+	WIDTH: 150px
+}
+.navigation .textlinks {
+	PADDING-LEFT: 1em; TEXT-ALIGN: left
+}
+.header {
+	MARGIN-TOP: 0.5em
+}
+.header {
+	MARGIN-LEFT: 1em; MARGIN-RIGHT: 1em
+}
+.content {
+	MARGIN-LEFT: 1em; MARGIN-RIGHT: 1em
+}
+.header TABLE TD {
+	TEXT-ALIGN: left
+}
+.header TABLE TH {
+	PADDING-RIGHT: 0.5em; FONT-FAMILY: sans-serif; TEXT-ALIGN: right
+}
+H3 {
+	FONT-FAMILY: sans-serif
+}
Index: /anuga_core/documentation/experimentation/boundary_ANUGA_MOST/report/50100MOSTcomparison_onslow.tex
===================================================================
--- /anuga_core/documentation/experimentation/boundary_ANUGA_MOST/report/50100MOSTcomparison_onslow.tex	(revision 3574)
+++ /anuga_core/documentation/experimentation/boundary_ANUGA_MOST/report/50100MOSTcomparison_onslow.tex	(revision 3574)
@@ -0,0 +1,27 @@
+\begin{table} \label{table:locationsonslow} 
+\caption{Defined point locations for comparison study for Onslow region.}
+\begin{center}
+\begin{tabular}{|l|l|l|l|}\hline
+\bf{Point Name} & \bf{Easting} & \bf{Northing} & \bf{Elevation (m)}\\ \hline
+Region polygon1 & 305000.00 & 7601000.00 & 6.55 \\ \hline 
+Onshore Centre & 305000.00 & 7605000.00 & 1.42 \\ \hline 
+Ocean polygon 2 & 305000.00 & 7646000.00 & -30.83 \\ \hline 
+Ocean polygon 1 & 305000.00 & 7624000.00 & -3.18 \\ \hline 
+Boundary 1 & 305000.00 & 7670000.00 & -49.04 \\ \hline 
+Western region & 292000.00 & 7611000.00 & -9.03 \\ \hline 
+Boundary 2 & 280000.00 & 7624000.00 & -11.34 \\ \hline 
+Western corner & 265000.00 & 7620000.00 & -31.18 \\ \hline 
+Centre & 292000.00 & 7630000.00 & -9.48 \\ \hline 
+Region polygon2 & 293000.00 & 7602500.00 & -9.69 \\ \hline 
+\end{tabular} 
+  \end{center} 
+ \end{table} 
+ 
+\begin{figure}[hbt] 
+ \centerline{ \includegraphics[width=150mm, height=100mm]{../report_figures/onslow_boundary_gauges.png}}
+\caption{Point locations used for comparison between boundary at 50m and 100m contour for Onslow region.}  
+\label{fig:points}
+\end{figure}
+\input{latexoutput_compare50_100_MOST} 
+ \clearpage 
+ 
Index: /anuga_core/documentation/experimentation/boundary_ANUGA_MOST/report/MOST_ANUGA.tex
===================================================================
--- /anuga_core/documentation/experimentation/boundary_ANUGA_MOST/report/MOST_ANUGA.tex	(revision 3574)
+++ /anuga_core/documentation/experimentation/boundary_ANUGA_MOST/report/MOST_ANUGA.tex	(revision 3574)
@@ -0,0 +1,308 @@
+\documentclass[reqno]{article}
+\usepackage{ae} % or {zefonts}
+\usepackage[T1]{fontenc}
+\usepackage[ansinew]{inputenc}
+\usepackage{amsmath}
+\usepackage{amssymb}
+\usepackage{graphicx}
+\usepackage{color}
+\usepackage[colorlinks]{hyperref}
+\usepackage{setspace}
+% \Add{} and \Del{} Corrections and \Mark{}
+%\usepackage[active,new,noold,marker]{xrcs}
+\usepackage{eurosym}
+\DeclareInputText{128}{\euro} % ANSI code for euro:  \usepackage{eurosym}
+\DeclareInputText{165}{\yen}  % ANSI code for yen:  ¥ \usepackage{amssymb}
+
+\usepackage{lscape} %landcape pages support
+%\input{definitions}
+\topmargin 0pt
+\oddsidemargin 10pt
+\evensidemargin 10pt
+\marginparwidth 0.5pt
+\textwidth \paperwidth 
+\advance\textwidth -2.5in
+%\setstretch{1.5}
+%\parindent 0pt
+%\parskip 2pt
+
+\title{Inundation Modelling from an Earthquake Source}
+\date{}
+
+\begin{document}
+
+\maketitle
+ \begin{abstract}
+The Risk Research Group at Geoscience Australia is playing a role in building 
+the capability for the Australian Tsunami Warning System (ATWS). 
+The ATWS aims to detect and warn the community
+of tsunami-genic events as well as develop community education programs for
+preparation of the event. Risk mitigation involves understanding the relative 
+risk
+of tsunamis to communities so that appropropriate evacuation plans can be 
+put in place. 
+To develop an understanding of the risk, the Risk Research Group is developing 
+decision support tools to assist emergency managers. These tools consist 
+of inundation
+maps and damage modelling overlaid on aerial photography of the region 
+detailing critical
+infrastructure. This report deals with the tsunami inundation modelling
+and the interaction with the event propagation model, Method of 
+Splitting Tsunami (MOST).
+
+  \end{abstract}
+  
+  \tableofcontents
+
+\section{Introduction}
+\label{intro}
+
+To determine tsunami risk, we follow the risk methodology of 
+determining the hazard, consequence and
+exposure. The tsunami hazard can be generated by
+submarine earthquakes and mass failures, as well as volcanoes and asteroid
+impacts. Here, we concentrate on submarine earthquakes only. The
+Method of Splitting Tsunami (MOST) models the earthquake event and 
+propagates the tsunami wave in deep water, \cite{titov:most}. 
+GA has used this model to develop 
+a preliminary hazard map for Australia which is based
+on generating a series of earthquakes along the relevant subduction
+zones surrounding Australia. The map details the average wave height
+at the 50m contour line and has been used in nominating areas of
+detailed inundation modelling by the Fire and Emergency Services Authority
+in Western Australia. MOST uses a finite difference technique and is
+based on a fixed grid structure. Inputs include bathymetric data, typically
+on the order of 100m grid spacing, and details regarding the source, such
+as location, size, slip angle, for example.
+
+In determining the 
+consequence of the tsunami wave once is reaches the coastline,
+we use the software tool ANUGA which solves the shallow water 
+wave equation to 
+calculate the maximum inundation depth ashore. ANUGA uses the
+finite volume technique, \cite{ON:modsim} with the
+advantage being that the cell resolution can be changed
+according to areas of interest and that wetting and drying
+is treated robustly as part of the numerical scheme. 
+ANUGA requires a number
+of inputs including on and offshore data, 
+an initial condition (such as the tidal height), forcing
+terms (such as wind) and the boundary condition (such as the form of
+the tsunami wave). This report discusses the details of the latter point, 
+i.e the interaction between ANUGA and MOST 
+focussing on the location at which information is ``best'' 
+passed from one model
+to the next. 
+
+Drivers for this study surround computational processing time
+to develop both {\it tactical} and {\it strategic} decision support tools.
+Tactical tools support ``real time'' consequence prediction for 
+emergency manager use 
+to obtain assessments of tsunami impact and expected 
+consequences to guide initial resource deployment. Strategic tools are based
+on using estimated recurrence rates of tsunamigenic events (the hazard), 
+the modelled 
+inundation and associated damage (exposure) 
+to present a national tsunami risk map.
+On another strategic level,
+the precomputed simulations 
+and risk maps will comprise a library of scenarios for the Australian Tsunami 
+Warning System to assist in mitigation, warning, response and community 
+recovery in the event of a tsunami disaster.
+
+\section{The modelling environment}
+\label{models}
+
+The purpose of this section is to briefly describe the process of how
+ANUGA and MOST interact through the boundary condition. MOST is 
+based on a fixed grid and outputs water depth and momentum at
+each grid point. For the preliminary hazard map, a 250m (?) grid was used.
+By contrast, ANUGA uses an unstructured triangular mesh which therefore
+calls for interpolation from the MOST output to the defined boundary. As
+MOST is modelling the tsunami wave from its source and is often made
+up of a series of waves,
+ANUGA needs to account for its time varying nature.
+ANUGA deals with a time varying boundary in the following way.
+
+
+\section{Comparisons}
+\label{compare}
+
+This section details a range of comparisons at 
+virtual ``gauge'' points located
+within the study area, including the boundary. Note, these gauges are 
+constructed for computational purposes only and are not physical tide
+gauges. The purpose is to ascertain
+any relationships between the bathymetric topography and the ``matching'' 
+of the ANUGA and MOST outputs. The difficult question is to 
+how to define this matching. In this report, we will investigate
+the comparison between MOST and ANUGA to determine the point of divergence.
+Secondly, we are also interested in the difference in impact ashore
+when the boundary is placed at 100m and 50m contour lines.
+Section \ref{sec:mostanugaonslow} deals with the first
+issue with Section \ref{sec:compare50100onslow} dealing with the second.
+
+
+Firstly, at what water depth should we place the ANUGA boundary? Where
+is the transition from deep water to shallow water? Some have
+suggested this can be determined 
+by the ratio of the water's depth to the wavelength of the wave. 
+In particular,
+when the depth of the water, 
+$d$, becomes less than one half of the wavelength of the wave, 
+$\lambda$
+\footnote{http://electron4.phys.utk.edu/141/dec8/December\%208.htm}. 
+Wavelengths can often be of the order of 100km which would place the 
+transition at 50km! This then aligns with the following NOAA statement, 
+"[t]sunami waves are shallow-water waves with long periods and wave lengths."
+\footnote{http://www.pmel.noaa.gov/tsunami-hazard/tsunami\_faqs.htm}
+
+Unfortunately, this doesn't help the modelling effort as the study area
+is constrained by UTM zones and the computational load. However, the 
+former issue
+is planned for investigation and the latter is underway through the 
+parallelisation of ANUGA.
+
+need some words here about why 100m has been chosen
+
+need some words about the choice of gauge locations. Nick, do they line up
+to the grid points used in MOST? 
+
+\subsection{Onslow case study}
+
+\subsubsection{MOST and ANUGA comparison - 100m contour}
+\label{sec:mostanugaonslow}
+
+Before considering any comparison, we will investigate how the maximum
+amplitude varies as the tsunami wave reaches the shore. The theory
+says that the amplitude will grow and the velocity decrease to zero.
+
+have a plot here that has the bed elevation on the x-axis and the 
+maximum amplitude on the y-axis
+
+have a plot here that has the bed elevation on the x-axis and the 
+maximum amplitude on the y-axis
+
+We want to compare MOST and ANUGA all the way to the shore - as
+close as practical anyway. It is important to note here
+that MOST and ANUGA are using different bathymetry data sets, with MOST
+typically using a much coarser grid than ANUGA. We interpolate
+both MOST and ANUGA output onto the defined point locations. Due to the
+fact that ANUGA is utilising a finer resolution bathymetry set, 
+we will expect to see richer detail in the ANUGA output. 
+
+\input{comparison_onslow}
+
+The table should show us where it is appropriate to place
+the boundary.
+
+\begin{table}
+\label{table:mostanugacomparisononslow}
+\caption{Comparison in output between ANUGA boundary at 100m 
+MOST output.}
+\centering
+\begin{tabular}{|l|l|l|}\hline
+Point location & MOST & ANUGA \\ \hline
+& some sort of measure of fit - eg max/min amplitude&   \\ \hline
+\end{tabular}
+\end{table}
+
+or perhaps ditch the table and repeat the graphs above
+with both ANUGA and MOST
+
+\subsubsection{ANUGA comparison - 50m and 100m contour}
+\label{sec:compare50100onslow}
+
+The following shows the time series for the point locations
+described in Table \ref{table:locationsonslow}.
+It is evident from the model output when the boundary is placed 
+at the 50m contour does not pick up the
+detail which is evident in the output for the 100m contour. This 
+is due to the fact that the output
+for the 100m contour has been propagated by ANUGA which is more effective
+in modelling the propagation in shallow water. 
+It seems that the maximum amplitudes are
+effectively matched for most of the locations chosen; 
+see for example the output for the Ocean polygon 1 and 2 locations.
+
+\input{50100MOSTcomparison_onslow}
+
+It is more instructive in this case to compare differences in
+inundation depths and extent ashore as the boundary location is changed.
+Table \ref{table:anugacomparisononslow} lists inundation depths
+for locations within the internal polygon with the finest resolution.
+
+\begin{table}
+\label{table:anugacomparisononslow}
+\caption{Comparison in inundation depth at select locations when ANUGA boundary 
+is at the 50m and 100m contour.}
+\centering
+\begin{tabular}{|l|l|l|}\hline
+Point location & Boundary at 50m contour & Boundary at 100m contour \\ \hline
+&  &   \\ \hline
+\end{tabular}
+\end{table}
+
+\begin{figure}
+\caption{Map showing inundation extent for 50m and 100m contour line.}
+\label{fig:extentcomparisononslow}
+\end{figure}
+
+\subsection{Pt Hedland case study}
+
+\subsubsection{MOST and ANUGA comparison - 100m contour}
+\label{mostanugapthedland}
+
+\begin{table}
+\label{table:mostanugacomparisonpthedland}
+\caption{Comparison in output between ANUGA boundary at 100m 
+MOST output.}
+\centering
+\begin{tabular}{|l|l|l|}\hline
+Point location & MOST & ANUGA \\ \hline
+& some sort of measure of fit &   \\ \hline
+\end{tabular}
+\end{table}
+
+\subsubsection{ANUGA comparison - 50m and 100m contour}
+\label{compare50100pthedland}
+
+%\input{comparison_pt_hedland}
+
+\begin{table}
+\label{table:anugacomparisonpthedland}
+\caption{Comparison in inundation depth at select location when ANUGA boundary 
+is at the 50m and 100m contour.}
+\centering
+\begin{tabular}{|l|l|l|}\hline
+Point location & Boundary at 50m contour & Boundary at 100m contour \\ \hline
+&  &   \\ \hline
+\end{tabular}
+\end{table}
+
+\begin{figure}
+\caption{Map showing inundation extent for 50m and 100m contour line.}
+\label{fig:extentcomparisonpthedland}
+\end{figure}
+
+\section{Summary}
+\label{summary}
+
+\begin{thebibliography}{99}
+
+\bibitem{titov:most} Titov, V.V., and F.I. Gonzalez (1997), Implementation 
+and testing of
+the Method of Splitting Tsunami (MOST) model, NOAA Technical Memorandum
+ERL PMEL-112.
+
+\bibitem{ON:modsim} Nielsen, O., S. Robers, D. Gray, A. McPherson, and 
+A. Hitchman (2005)
+Hydrodynamic modelling of coastal inundation, MODSIM 2005 International
+Congress on Modelling and Simulation. Modelling and Simulation Society 
+of Australian and New Zealand, 518-523, \newline URL: 
+http://www.mssanz.org.au/modsim05/papers/nielsen.pdf
+
+
+\end{thebibliography}
+
+\end{document}
Index: /anuga_core/documentation/experimentation/boundary_ANUGA_MOST/report/comparison_onslow.tex
===================================================================
--- /anuga_core/documentation/experimentation/boundary_ANUGA_MOST/report/comparison_onslow.tex	(revision 3574)
+++ /anuga_core/documentation/experimentation/boundary_ANUGA_MOST/report/comparison_onslow.tex	(revision 3574)
@@ -0,0 +1,8 @@
+\begin{figure}[hbt] 
+ \centerline{ \includegraphics[width=150mm, height=100mm]{../report_figures/boundarycomparison.png}}
+\caption{Point locations used to compare MOST and ANUGA for Onslow region.}  
+\label{fig:comparisonpoints}
+\end{figure}
+\input{latexoutput_MOST_ANUGA_comparison} 
+ \clearpage 
+ 
Index: /anuga_core/documentation/experimentation/boundary_ANUGA_MOST/report/latexoutput_MOST_ANUGA_comparison.tex
===================================================================
--- /anuga_core/documentation/experimentation/boundary_ANUGA_MOST/report/latexoutput_MOST_ANUGA_comparison.tex	(revision 3574)
+++ /anuga_core/documentation/experimentation/boundary_ANUGA_MOST/report/latexoutput_MOST_ANUGA_comparison.tex	(revision 3574)
@@ -0,0 +1,100 @@
+\begin{figure}[hbt] 
+ \centering 
+ \begin{tabular}{cc} 
+\includegraphics[width=0.49\linewidth, height=50mm]{../report_figures/gaugePoint0stage.png}& 
+\includegraphics[width=0.49\linewidth, height=50mm]{../report_figures/gaugePoint0speed.png}\\ 
+\end{tabular} 
+ \caption{Time series for stage and speed at Point0 gauge location (elevation -24.89m)} 
+ \label{fig:gaugePoint0} 
+ \end{figure} 
+ 
+\begin{figure}[hbt] 
+ \centering 
+ \begin{tabular}{cc} 
+\includegraphics[width=0.49\linewidth, height=50mm]{../report_figures/gaugePoint1stage.png}& 
+\includegraphics[width=0.49\linewidth, height=50mm]{../report_figures/gaugePoint1speed.png}\\ 
+\end{tabular} 
+ \caption{Time series for stage and speed at Point1 gauge location (elevation -41.48m)} 
+ \label{fig:gaugePoint1} 
+ \end{figure} 
+ 
+\begin{figure}[hbt] 
+ \centering 
+ \begin{tabular}{cc} 
+\includegraphics[width=0.49\linewidth, height=50mm]{../report_figures/gaugePoint2stage.png}& 
+\includegraphics[width=0.49\linewidth, height=50mm]{../report_figures/gaugePoint2speed.png}\\ 
+\end{tabular} 
+ \caption{Time series for stage and speed at Point2 gauge location (elevation -48.06m)} 
+ \label{fig:gaugePoint2} 
+ \end{figure} 
+ 
+\begin{figure}[hbt] 
+ \centering 
+ \begin{tabular}{cc} 
+\includegraphics[width=0.49\linewidth, height=50mm]{../report_figures/gaugePoint3stage.png}& 
+\includegraphics[width=0.49\linewidth, height=50mm]{../report_figures/gaugePoint3speed.png}\\ 
+\end{tabular} 
+ \caption{Time series for stage and speed at Point3 gauge location (elevation -95.93m)} 
+ \label{fig:gaugePoint3} 
+ \end{figure} 
+ 
+\begin{figure}[hbt] 
+ \centering 
+ \begin{tabular}{cc} 
+\includegraphics[width=0.49\linewidth, height=50mm]{../report_figures/gaugePoint4stage.png}& 
+\includegraphics[width=0.49\linewidth, height=50mm]{../report_figures/gaugePoint4speed.png}\\ 
+\end{tabular} 
+ \caption{Time series for stage and speed at Point4 gauge location (elevation -72.01m)} 
+ \label{fig:gaugePoint4} 
+ \end{figure} 
+ 
+\begin{figure}[hbt] 
+ \centering 
+ \begin{tabular}{cc} 
+\includegraphics[width=0.49\linewidth, height=50mm]{../report_figures/gaugePoint5stage.png}& 
+\includegraphics[width=0.49\linewidth, height=50mm]{../report_figures/gaugePoint5speed.png}\\ 
+\end{tabular} 
+ \caption{Time series for stage and speed at Point5 gauge location (elevation -40.61m)} 
+ \label{fig:gaugePoint5} 
+ \end{figure} 
+ 
+\begin{figure}[hbt] 
+ \centering 
+ \begin{tabular}{cc} 
+\includegraphics[width=0.49\linewidth, height=50mm]{../report_figures/gaugePoint6stage.png}& 
+\includegraphics[width=0.49\linewidth, height=50mm]{../report_figures/gaugePoint6speed.png}\\ 
+\end{tabular} 
+ \caption{Time series for stage and speed at Point6 gauge location (elevation -8.67m)} 
+ \label{fig:gaugePoint6} 
+ \end{figure} 
+ 
+\begin{figure}[hbt] 
+ \centering 
+ \begin{tabular}{cc} 
+\includegraphics[width=0.49\linewidth, height=50mm]{../report_figures/gaugePoint7stage.png}& 
+\includegraphics[width=0.49\linewidth, height=50mm]{../report_figures/gaugePoint7speed.png}\\ 
+\end{tabular} 
+ \caption{Time series for stage and speed at Point7 gauge location (elevation -72.47m)} 
+ \label{fig:gaugePoint7} 
+ \end{figure} 
+ 
+\begin{figure}[hbt] 
+ \centering 
+ \begin{tabular}{cc} 
+\includegraphics[width=0.49\linewidth, height=50mm]{../report_figures/gaugePoint8stage.png}& 
+\includegraphics[width=0.49\linewidth, height=50mm]{../report_figures/gaugePoint8speed.png}\\ 
+\end{tabular} 
+ \caption{Time series for stage and speed at Point8 gauge location (elevation -50.26m)} 
+ \label{fig:gaugePoint8} 
+ \end{figure} 
+ 
+\begin{figure}[hbt] 
+ \centering 
+ \begin{tabular}{cc} 
+\includegraphics[width=0.49\linewidth, height=50mm]{../report_figures/gaugePoint9stage.png}& 
+\includegraphics[width=0.49\linewidth, height=50mm]{../report_figures/gaugePoint9speed.png}\\ 
+\end{tabular} 
+ \caption{Time series for stage and speed at Point9 gauge location (elevation -6.72m)} 
+ \label{fig:gaugePoint9} 
+ \end{figure} 
+ 
Index: /anuga_core/documentation/experimentation/boundary_ANUGA_MOST/report/latexoutput_compare.tex
===================================================================
--- /anuga_core/documentation/experimentation/boundary_ANUGA_MOST/report/latexoutput_compare.tex	(revision 3574)
+++ /anuga_core/documentation/experimentation/boundary_ANUGA_MOST/report/latexoutput_compare.tex	(revision 3574)
@@ -0,0 +1,100 @@
+\begin{figure}[hbt] 
+ \centering 
+ \begin{tabular}{cc} 
+\includegraphics[width=0.49\linewidth, height=50mm]{../report_figures/gaugeRegionpolygon1stage.png}& 
+\includegraphics[width=0.49\linewidth, height=50mm]{../report_figures/gaugeRegionpolygon1speed.png}\\ 
+\end{tabular} 
+ \caption{Time series for stage and speed at Region polygon1 gauge location (elevation 3.00m)} 
+ \label{fig:gaugeRegionpolygon1} 
+ \end{figure} 
+ 
+\begin{figure}[hbt] 
+ \centering 
+ \begin{tabular}{cc} 
+\includegraphics[width=0.49\linewidth, height=50mm]{../report_figures/gaugeOnshoreCentrestage.png}& 
+\includegraphics[width=0.49\linewidth, height=50mm]{../report_figures/gaugeOnshoreCentrespeed.png}\\ 
+\end{tabular} 
+ \caption{Time series for stage and speed at Onshore Centre gauge location (elevation 11.87m)} 
+ \label{fig:gaugeOnshoreCentre} 
+ \end{figure} 
+ 
+\begin{figure}[hbt] 
+ \centering 
+ \begin{tabular}{cc} 
+\includegraphics[width=0.49\linewidth, height=50mm]{../report_figures/gaugeOceanpolygon2stage.png}& 
+\includegraphics[width=0.49\linewidth, height=50mm]{../report_figures/gaugeOceanpolygon2speed.png}\\ 
+\end{tabular} 
+ \caption{Time series for stage and speed at Ocean polygon 2 gauge location (elevation -18.48m)} 
+ \label{fig:gaugeOceanpolygon2} 
+ \end{figure} 
+ 
+\begin{figure}[hbt] 
+ \centering 
+ \begin{tabular}{cc} 
+\includegraphics[width=0.49\linewidth, height=50mm]{../report_figures/gaugeOceanpolygon1stage.png}& 
+\includegraphics[width=0.49\linewidth, height=50mm]{../report_figures/gaugeOceanpolygon1speed.png}\\ 
+\end{tabular} 
+ \caption{Time series for stage and speed at Ocean polygon 1 gauge location (elevation -15.61m)} 
+ \label{fig:gaugeOceanpolygon1} 
+ \end{figure} 
+ 
+\begin{figure}[hbt] 
+ \centering 
+ \begin{tabular}{cc} 
+\includegraphics[width=0.49\linewidth, height=50mm]{../report_figures/gaugeBoundary1stage.png}& 
+\includegraphics[width=0.49\linewidth, height=50mm]{../report_figures/gaugeBoundary1speed.png}\\ 
+\end{tabular} 
+ \caption{Time series for stage and speed at Boundary 1 gauge location (elevation -45.94m)} 
+ \label{fig:gaugeBoundary1} 
+ \end{figure} 
+ 
+\begin{figure}[hbt] 
+ \centering 
+ \begin{tabular}{cc} 
+\includegraphics[width=0.49\linewidth, height=50mm]{../report_figures/gaugeWesternregionstage.png}& 
+\includegraphics[width=0.49\linewidth, height=50mm]{../report_figures/gaugeWesternregionspeed.png}\\ 
+\end{tabular} 
+ \caption{Time series for stage and speed at Western region gauge location (elevation -10.49m)} 
+ \label{fig:gaugeWesternregion} 
+ \end{figure} 
+ 
+\begin{figure}[hbt] 
+ \centering 
+ \begin{tabular}{cc} 
+\includegraphics[width=0.49\linewidth, height=50mm]{../report_figures/gaugeBoundary2stage.png}& 
+\includegraphics[width=0.49\linewidth, height=50mm]{../report_figures/gaugeBoundary2speed.png}\\ 
+\end{tabular} 
+ \caption{Time series for stage and speed at Boundary 2 gauge location (elevation -12.25m)} 
+ \label{fig:gaugeBoundary2} 
+ \end{figure} 
+ 
+\begin{figure}[hbt] 
+ \centering 
+ \begin{tabular}{cc} 
+\includegraphics[width=0.49\linewidth, height=50mm]{../report_figures/gaugeWesterncornerstage.png}& 
+\includegraphics[width=0.49\linewidth, height=50mm]{../report_figures/gaugeWesterncornerspeed.png}\\ 
+\end{tabular} 
+ \caption{Time series for stage and speed at Western corner gauge location (elevation -36.07m)} 
+ \label{fig:gaugeWesterncorner} 
+ \end{figure} 
+ 
+\begin{figure}[hbt] 
+ \centering 
+ \begin{tabular}{cc} 
+\includegraphics[width=0.49\linewidth, height=50mm]{../report_figures/gaugeCentrestage.png}& 
+\includegraphics[width=0.49\linewidth, height=50mm]{../report_figures/gaugeCentrespeed.png}\\ 
+\end{tabular} 
+ \caption{Time series for stage and speed at Centre gauge location (elevation -13.04m)} 
+ \label{fig:gaugeCentre} 
+ \end{figure} 
+ 
+\begin{figure}[hbt] 
+ \centering 
+ \begin{tabular}{cc} 
+\includegraphics[width=0.49\linewidth, height=50mm]{../report_figures/gaugeRegionpolygon2stage.png}& 
+\includegraphics[width=0.49\linewidth, height=50mm]{../report_figures/gaugeRegionpolygon2speed.png}\\ 
+\end{tabular} 
+ \caption{Time series for stage and speed at Region polygon2 gauge location (elevation -5.43m)} 
+ \label{fig:gaugeRegionpolygon2} 
+ \end{figure} 
+ 
Index: /anuga_core/documentation/experimentation/boundary_ANUGA_MOST/report/latexoutput_compare50_100_MOST.tex
===================================================================
--- /anuga_core/documentation/experimentation/boundary_ANUGA_MOST/report/latexoutput_compare50_100_MOST.tex	(revision 3574)
+++ /anuga_core/documentation/experimentation/boundary_ANUGA_MOST/report/latexoutput_compare50_100_MOST.tex	(revision 3574)
@@ -0,0 +1,100 @@
+\begin{figure}[hbt] 
+ \centering 
+ \begin{tabular}{cc} 
+\includegraphics[width=0.49\linewidth, height=50mm]{../report_figures/gaugeRegionpolygon1stage.png}& 
+\includegraphics[width=0.49\linewidth, height=50mm]{../report_figures/gaugeRegionpolygon1speed.png}\\ 
+\end{tabular} 
+ \caption{Time series for stage and speed at Region polygon1 gauge location (elevation 6.55m)} 
+ \label{fig:gaugeRegionpolygon1} 
+ \end{figure} 
+ 
+\begin{figure}[hbt] 
+ \centering 
+ \begin{tabular}{cc} 
+\includegraphics[width=0.49\linewidth, height=50mm]{../report_figures/gaugeOnshoreCentrestage.png}& 
+\includegraphics[width=0.49\linewidth, height=50mm]{../report_figures/gaugeOnshoreCentrespeed.png}\\ 
+\end{tabular} 
+ \caption{Time series for stage and speed at Onshore Centre gauge location (elevation 1.42m)} 
+ \label{fig:gaugeOnshoreCentre} 
+ \end{figure} 
+ 
+\begin{figure}[hbt] 
+ \centering 
+ \begin{tabular}{cc} 
+\includegraphics[width=0.49\linewidth, height=50mm]{../report_figures/gaugeOceanpolygon2stage.png}& 
+\includegraphics[width=0.49\linewidth, height=50mm]{../report_figures/gaugeOceanpolygon2speed.png}\\ 
+\end{tabular} 
+ \caption{Time series for stage and speed at Ocean polygon 2 gauge location (elevation -30.83m)} 
+ \label{fig:gaugeOceanpolygon2} 
+ \end{figure} 
+ 
+\begin{figure}[hbt] 
+ \centering 
+ \begin{tabular}{cc} 
+\includegraphics[width=0.49\linewidth, height=50mm]{../report_figures/gaugeOceanpolygon1stage.png}& 
+\includegraphics[width=0.49\linewidth, height=50mm]{../report_figures/gaugeOceanpolygon1speed.png}\\ 
+\end{tabular} 
+ \caption{Time series for stage and speed at Ocean polygon 1 gauge location (elevation -3.18m)} 
+ \label{fig:gaugeOceanpolygon1} 
+ \end{figure} 
+ 
+\begin{figure}[hbt] 
+ \centering 
+ \begin{tabular}{cc} 
+\includegraphics[width=0.49\linewidth, height=50mm]{../report_figures/gaugeBoundary1stage.png}& 
+\includegraphics[width=0.49\linewidth, height=50mm]{../report_figures/gaugeBoundary1speed.png}\\ 
+\end{tabular} 
+ \caption{Time series for stage and speed at Boundary 1 gauge location (elevation -49.04m)} 
+ \label{fig:gaugeBoundary1} 
+ \end{figure} 
+ 
+\begin{figure}[hbt] 
+ \centering 
+ \begin{tabular}{cc} 
+\includegraphics[width=0.49\linewidth, height=50mm]{../report_figures/gaugeWesternregionstage.png}& 
+\includegraphics[width=0.49\linewidth, height=50mm]{../report_figures/gaugeWesternregionspeed.png}\\ 
+\end{tabular} 
+ \caption{Time series for stage and speed at Western region gauge location (elevation -9.03m)} 
+ \label{fig:gaugeWesternregion} 
+ \end{figure} 
+ 
+\begin{figure}[hbt] 
+ \centering 
+ \begin{tabular}{cc} 
+\includegraphics[width=0.49\linewidth, height=50mm]{../report_figures/gaugeBoundary2stage.png}& 
+\includegraphics[width=0.49\linewidth, height=50mm]{../report_figures/gaugeBoundary2speed.png}\\ 
+\end{tabular} 
+ \caption{Time series for stage and speed at Boundary 2 gauge location (elevation -11.34m)} 
+ \label{fig:gaugeBoundary2} 
+ \end{figure} 
+ 
+\begin{figure}[hbt] 
+ \centering 
+ \begin{tabular}{cc} 
+\includegraphics[width=0.49\linewidth, height=50mm]{../report_figures/gaugeWesterncornerstage.png}& 
+\includegraphics[width=0.49\linewidth, height=50mm]{../report_figures/gaugeWesterncornerspeed.png}\\ 
+\end{tabular} 
+ \caption{Time series for stage and speed at Western corner gauge location (elevation -31.18m)} 
+ \label{fig:gaugeWesterncorner} 
+ \end{figure} 
+ 
+\begin{figure}[hbt] 
+ \centering 
+ \begin{tabular}{cc} 
+\includegraphics[width=0.49\linewidth, height=50mm]{../report_figures/gaugeCentrestage.png}& 
+\includegraphics[width=0.49\linewidth, height=50mm]{../report_figures/gaugeCentrespeed.png}\\ 
+\end{tabular} 
+ \caption{Time series for stage and speed at Centre gauge location (elevation -9.48m)} 
+ \label{fig:gaugeCentre} 
+ \end{figure} 
+ 
+\begin{figure}[hbt] 
+ \centering 
+ \begin{tabular}{cc} 
+\includegraphics[width=0.49\linewidth, height=50mm]{../report_figures/gaugeRegionpolygon2stage.png}& 
+\includegraphics[width=0.49\linewidth, height=50mm]{../report_figures/gaugeRegionpolygon2speed.png}\\ 
+\end{tabular} 
+ \caption{Time series for stage and speed at Region polygon2 gauge location (elevation -9.69m)} 
+ \label{fig:gaugeRegionpolygon2} 
+ \end{figure} 
+ 
Index: /anuga_core/documentation/experimentation/smf.tex
===================================================================
--- /anuga_core/documentation/experimentation/smf.tex	(revision 3574)
+++ /anuga_core/documentation/experimentation/smf.tex	(revision 3574)
@@ -0,0 +1,211 @@
+\documentclass[reqno]{article}
+%\documentstyle{letter}
+\usepackage{ae} % or {zefonts}
+\usepackage[T1]{fontenc}
+\usepackage[ansinew]{inputenc}
+\usepackage{amsmath}
+\usepackage{amssymb}
+\usepackage{graphicx}
+\usepackage{color}
+\usepackage[colorlinks]{hyperref}
+\usepackage{setspace}
+% \Add{} and \Del{} Corrections and \Mark{}
+%\usepackage[active,new,noold,marker]{xrcs}
+\usepackage{eurosym}
+\DeclareInputText{128}{\euro} % ANSI code for euro:  \usepackage{eurosym}
+\DeclareInputText{165}{\yen}  % ANSI code for yen:  ¥ \usepackage{amssymb}
+
+\usepackage{lscape} %landcape pages support
+%\input{definitions}
+\topmargin 0pt
+\oddsidemargin 10pt
+\evensidemargin 10pt
+\marginparwidth 0.5pt
+\textwidth \paperwidth 
+\advance\textwidth -2.5in
+\setstretch{1.5}
+\parindent 0pt
+\parskip 2pt
+
+%\title{Application of SMF surface elevation function in inundation modelling}
+\date{}
+
+\begin{document}
+
+%\maketitle
+
+May 2006
+
+Dr Phil Watts
+
+Applied Fluids Engineering
+
+Long Beach California
+
+USA
+
+phil.watts@appliedfluids.com
+
+Dear Phil,
+\parindent 15pt
+
+{\bf Ref: Application of sediment mass failure surface elevation function
+in inundation modelling}
+
+We work at Geoscience Australia (GA) in the Risk Research Group 
+researching risks posed by a range of natural hazards 
+(http://www.ga.gov.au/urban/projects/risk/index.jsp). 
+Due to recent
+events and Australia's apparent vulnerabiliy to tsunami hazards, 
+we are investigating the tsunami risk to Australia. To understand
+impact ashore, we have developed in conjunction
+with the Australian National University, a hydrodynamic model called
+ANUGA which uses the finite volume technique, [1].
+
+A recent tsunami inundation study called for the tsunami source to
+be a slump and as such, we implemented the surface elevation
+function as described in Watts et al 2005, [2]. We found this a very useful
+way to incorporate another tsunami-genic event to our understanding
+of tsunami risk. In trying
+to implement this function however, we had some questions;
+
+\begin{itemize}
+\item
+Is there a physical explanation to why the total volume
+of the surface elevation function should not be zero?
+\item
+Should $\eta_{\rm min}$ used in the surface elevation function
+be | ${\eta_{\rm min}}$ | instead?
+\item
+Is the substitution of $x_g$ into the elevation 
+function realistic?
+\end{itemize}
+
+Investigating the long term behaviour of the
+system, we found that water was being lost from the system when
+the slump was added to the system. Further investigation showed that
+the depressed volume was greater than the volume displaced above the
+water surface with approximately 2-3 \% loss. You can see from
+Figure 2 of [2] that the
+surface elevation function $\eta(x,y)$ indicates that
+the total volume is not conserved.
+
+However, we can alleviate this issue by finding the appropriate set of 
+parameters which
+will conserve volume. Setting the integral of the elevation function to zero 
+and solving for $\kappa'$ yields the result,
+$$\kappa' = [
+{\rm erf} ( \frac{x - x_0 } {\sqrt \lambda_0 } ) / 
+{\rm erf} ( \frac{x - \Delta x - x_0}{\sqrt \lambda_0 }) 
+]_{x_{\rm min}}^{x_{\rm max}} \ .$$
+
+\noindent The relationship between $\kappa'$ and $\Delta x$ is shown in
+Figure \ref{fig:vol_cons}. It must be noted, that whilst 
+$\kappa'$ is technically less than 1 for $\Delta x < 5.93$ it is
+effectively equal to 1 for those values. From this calculation, it would
+seem then that there is no appropriate $\Delta x$ for $\kappa'$ = 0.83 
+(a parameter used in [2]) satisfying conservation of volume.
+
+We've reproduced Figure 2 in [2]
+for appropriate values of $\kappa'$ and $\Delta x$ to
+ensure volume conservation within the system. Using the above
+formulation, the values of interest shown in Figure 2 in [2] would
+be ($\kappa', \Delta x) = (1,2), (1,4), (1.2, 13.48)$ and shown in
+Figure \ref{fig:eta_vary}. Note, this has not been scaled by $\eta_{\rm min}$.
+
+
+\begin{figure}
+
+  \centerline{ \includegraphics[width=75mm, height=50mm]{volume_conservation.png}}
+
+  \caption{Relationship between $\kappa'$ and $\Delta x$ to ensure volume conservation.}
+  \label{fig:vol_cons}
+\end{figure}
+
+\begin{figure}[hbt]
+
+  \centerline{ \includegraphics[width=75mm, height=50mm]{redo_figure.png}}
+
+  \caption{Surface elevation functions for
+($\kappa', \Delta x) = (1,2), (1,4), (1.2, 13.48)$.}
+  \label{fig:eta_vary}
+\end{figure}
+
+For our particular test case, changing the surface elevation function 
+in this way increases the inundation depth ashore by a factor greater than
+the initial water loss of 2-3 \%. 
+
+Turning to our question regarding the scaling of the surface elevation 
+function formulation, we see that $\eta_{\rm min}$ is always negative
+and hence
+$- \eta_{O,3D} / \eta_{\rm min}$ would be always positive. This
+would change the form of $\eta(x,y)$ and place the depressed volume behind
+the submarine mass failure. Should then $\eta_{\rm min}$ be replaced
+by |$\eta_{\rm min}$|?
+
+Our final question is whether it is appropriate to substitute
+the formulation for $x_g$ into the surface elevation function using
+$x_0 - \Delta x \approx x_g$. 
+($x_g$ is formulated
+as $x_g = d/\tan \theta + T/ \sin \theta$ which is described as a gauge
+located above the submarine mass failure
+initial submergence location in [3].) In this
+way, $\kappa'$ as described above would not 
+be dependent on $\Delta x$, nor the subsequent surface elevation function.
+
+
+We are continuing to seek out validation data sets to improve the
+accuracy of our model. We recently had success in validating
+the model against the Benchmark Problem $\#$2 Tsunami Run-up 
+onto a complex 3-dimensional beach, as provided to the 3rd 
+International Workshop on Long Wave Run-up in 2004, see [1].
+We note in [4] your proposal for others to employ the benchmark
+cases described there for experimental or numerical work.
+Your model has been compared with the laboratory experiments in 2003 [5] and 
+again in 2005 [3] with fairly good agreement. Given
+the numerical model you implemented was the boundary element method, we would
+be very interested in comparing our finite volume model using the
+approximated surface elevation function with your 
+experimental results. Would it therefore be possible for you to provide the 
+experimental time series for comparison with ANUGA?
+
+\parindent 0pt
+
+Thanks for your time and we look forward to your response.
+
+Yours sincerely,
+
+Jane Sexton, Ole Nielsen, Adrian Hitchman and Trevor Dhu.
+
+Risk Research Group, Geoscience Australia.
+
+\newpage
+{\bf References}
+
+[1] Nielsen, O., S. Robers, D. Gray, A. McPherson, and A. Hitchman (2005)
+Hydrodynamic modelling of coastal inundation, MODSIM 2005 International
+Congress on Modelling and Simulation. Modelling and Simulation Society 
+of Australian and New Zealand, 518-523, \newline URL: 
+http://www.mssanz.org.au/modsim05/papers/nielsen.pdf
+
+[2] Watts, P., Grilli, S.T., Tappin, D.R. and Fryer, G.J. (2005),
+Tsunami generation by submarine mass failure Part II: Predictive
+equations and case studies, Journal of Waterway, Port, Coastal, and
+Ocean Engineering, 131, 298 - 310.
+
+[3] Grilli, S.T. and Watts, P. (2005), Tsunami generation by
+submarine mass failure Part I: Modeling, experimental validation,
+and sensitivity analyses, Journal of Waterway, Port, Coastal, and
+Ocean Engineering, 131, 283 - 297.
+
+[4] Watts, P., Imamura, F. and Grilli, S. (2000)
+Comparing Model Simulations of Three Benchmark Tsunami Generation,
+Science of Tsunami Hazards, 18, 2, 107-123.
+
+[5] Enet, F., Grilli, S.T. and Watts, P. (2003), Laboratory Experiments for 
+Tsunamis Generated by Underwater Landslides: 
+Comparison with Numerical Modeling,
+Proceedings of the Thirteenth (2003) International Offshore and
+Polar Engineering Conference. The International Society of Offshore and
+Polar Engineers.
+\end{document}
Index: /anuga_core/documentation/planning/issues_pre_trac.txt
===================================================================
--- /anuga_core/documentation/planning/issues_pre_trac.txt	(revision 3574)
+++ /anuga_core/documentation/planning/issues_pre_trac.txt	(revision 3574)
@@ -0,0 +1,247 @@
+From TODO list (HUSK.txt)
+
+Have the quantity label e.g. elevation, associated with the data in sww files.
+
+Do data manager for non-smooth data + tests. Smooth is OK (7/9)
+		
+	
+Perhaps control old/new style with minimum_allowed height
+In any case get rid of old style.
+Then optimise protect_against.....
+	
+
+	
+Create a pyvolution_interfaces.py module with all getters/setters
+converts etc.
+
+
+gradient should not require qs to be numeric arrays anymore.!!
+
+
+Let rectangular mesh and others 
+like it to generat the three lists for use when instantiating
+Mesh and DOmain objects.
+
+
+Don't use default conserved qs - hardwire into shallow_water.py
+Even hardwire pertinent arrays from cons quan into shallow_water and use directly with flux etc
+
+
+Interface
+
+ set_quantity should be ablt take either a function or an array.
+ 
+
+Design:  
+explicit and implicit updates should be stored in each quantity. 
+
+Create repr of a domain such that it lists all its parameters e.g. order
+	
+	
+OPEN ISSUES:
+------------
+
+
+Try to use properties with getters and setters
+E.g. as in
+class Contact(object):
+
+    def __init__(self, first_name=None, last_name=None, 
+                 display_name=None, email=None):
+        self.first_name = first_name
+        self.last_name = last_name
+        self.display_name = display_name
+        self.email = email
+
+    def print_info(self):
+        print self.display_name, "<" + self.email + ">"            
+
+    def set_email(self, value):
+        if '@' not in value:
+            raise Exception("This doesn't look like an email address.")
+        self._email = value
+
+    def get_email(self):
+        return self._email
+
+    email = property(get_email, set_email)
+----------------------------------------------------
+
+Issue:  File function (e.g. boundary) should give an error message (or set a defoult) if underlying netcdf has missing values. Make a unit test.
+Maybe the underlying code should detect NaNs.
+
+
+Issue: finaltime should be renamed 'duration'
+
+Issue (interpolate_sww (new functionality): Give a warning if points
+ are outside the mesh.
+Importance: Mid
+Comment (Ole): If points and triangles are listed as discontinuous e.g. vertex coordinates replicated for each triangle, then the bounding polygon gets mangled and some points appear to be outside.
+Who: DSG
+
+Issue (interpolate_sww (new functionality)): Be able to specify at
+what times data is needed e.g. input a start, finish and period.
+Importance: low
+
+Issue (least_squares): Do a bug report to sci py
+Importance: low to don't do
+Who: Stephen
+
+Issue (least_squares): Runs out of memory with e.g 6 million points and 
+300,000 basis functions.
+Importance: Mid 
+Suggested Action: Look at blocking strategies
+
+Issue (least_squares): Code to not product D matrix (if it isn't
+needed) isn't working.
+Importance: Mid - low
+Suggested Action: Fix
+
+Issue: Parameters specified in config.py must be tranferred to C code 
+and it should be possible to override them when setting up a domain.
+Background: N/A
+Importance: Mid
+Suggested Action: 
+	  1: Let domain read the config file to provide default values.
+	  2: Write getters and setters to override them.
+	  3: Pass pertinent values from domain into the c-extensions.
+Status: Largely resolved. action 2 ongoing
+
+
+Issue: Checkpointing - needs to respect changes in script.
+Importance: Low
+
+
+Issue: Adding unknown quantities cause a KeyError.  Known quantities
+are given in the list other_quantities, in shallow_water.  Do we want
+unknown quantities attached to domain in the future?  If so, it
+shouldn't cause a key error.
+Importance: low
+Suggested Action: 
+Who: OLE
+
+
+Issue: The water level can not be less than the bed elevation, as an
+assert.  
+Importance: Medium
+Suggested Action: How about having the functionality that water levels are set
+to == the bed elevation, if level < bed elevation.  This will make
+setting things up easier.  A following suggestion is don't initialise
+quantities without values, eg in quantity __init__. 
+Status: resolved.  Needs unit test though
+
+Issue: Transmissive boundary condition can cause unphysical momentums if
+material is not moving out of the domain.
+Importance: Med
+Suggested Action: Comment in transmissive boundary code.  look into
+sponge boundary.
+
+
+
+	
+CLOSED ISSUES:
+--------------
+
+Issue (least_squares): The current is-a-point-in-a-triangle algorithm
+is slow if a point is outside of the mesh.  It will check each
+triangle 3 times to see if the point is in that triangle.
+Importance: low
+Suggested Action: Form a polygon of the mesh boundary (by constructing
+the neigbour structure) and throw out points not in the polygon (this
+algorithm is there).
+Who: DSG
+Comment (OLE): I have done this (I think)
+
+
+Issue: Get the reservoir example working for the 'new' pyvolution
+Issue: Mid
+Who: DSG
+Status: Done  
+
+Issue (least_squares): datapoints outside the mesh are not used in
+least squares.
+Importance: Mid - low
+Suggested Action: Talk to Steve about including them
+Status: Talked to Steve, it was dicided not to use them
+
+Issue (least_squares): Do a test that the number of attribute titles and number
+of attributes match
+Importance: Mid
+Who: DSG
+Status: closed, this is checked when loading points files now
+
+Issue (Malpasset example):
+Pmesh no longer takes care of attributes but still accepts xya with attributes.
+
+Background:
+Chris imported xya file into pmesh. It contained x, y, bed elevation
+The tsh thus generated did add bed elevation, but didn't produce the proper 
+tsh file.
+
+Importance: mid
+Suggested actions: Either spit out an error message or generate a proper 
+tsh-header.
+Status:  The story of this is wrong.  Pmesh does produce a proper tsh file
+
+Issue: Second order limiters may cause numerical problems 
+manifesting themselves as QNAN (Quiet NANs_ or INF)
+Background: The second order gradient limiter is not robust enough - 
+especially with shallow water depths. Heighs and momentum are 
+limited independently and high speeds may result.
+Importance: Mid
+Suggested Action: 
+	  1: Try to incorporate a weighted averaging process between 
+	  shallow depths and large depths as in the first order scheme.
+	  2: Look at limiting height and momentum together, by keeping 
+	  an eye on the speeds 
+	  (e.g make speed constant across a volume and recompute momentum)
+	  3: Catch errors resulting from these instabilities as early 
+	  as possibly and produce and throw an appropriate exception
+	  4: Make small example that reveals this bug.
+Status: 1 succesfully implemented by Ole and Stephen 12/5/4.
+	2 Didn't work but using the weighted average for momentums seemed 
+	to work well.
+	3 and 4 not done.
+	June 2004: With the new limiter (item 1 and 2) 3 and 4 are probably 
+	not necessary now.
+
+
+
+Issue: Tags for specifying boundary conditions should be arbitrary
+Background: Domain has the functionality for using arbitrary keys
+when associating boundary objects to boundary values.
+Triangle, which pmesh is based on, uses integers only.
+It would be nice to have mnemonic names for boundaries throughout.
+Importance: Mid
+Status: Duncan resolved this in early June.
+
+
+
+
+
+Issue: Checkpointing - needs to always back one timestep up in 
+       case output wasn't written
+Background:
+       Data at latest checkpoint may be incomplete or even corrupted 
+       depending on when and how program was stopped.
+Importance: Mid
+Suggested Action: Always try second latest checkpoint first.
+Status: Done (Ole 14/5/4)
+              
+
+		
+Issue: interpolated_conserved_quantities in shallow_water.py
+Background: Was computed by flux functions and used by bed_slope.
+It turns out to be unneccessary as conserved quantities at centroid works just as well.
+Importance: Mid
+Suggested Action: Get rid of it everywhere
+Status: Was done when whole things was refactored in April 2004 by OMN
+
+
+Issue: Exceptions thrown by Python functions called from C don't get caughts
+Background: Have a look at gravity in shallow_water. It calls a C function, gradient, which may throw an exception if arguments are scalars.
+However, it doesn't get caught becuase gravity itself is called from within C
+Importance: Low
+Suggested Action: Have a look at the calling convention from C (David Beasley)
+Status: Unresolved - but no longer relevant as we don't call Python from C
+
Index: /anuga_core/documentation/planning/pmesh_pre_trac_issues.txt
===================================================================
--- /anuga_core/documentation/planning/pmesh_pre_trac_issues.txt	(revision 3574)
+++ /anuga_core/documentation/planning/pmesh_pre_trac_issues.txt	(revision 3574)
@@ -0,0 +1,311 @@
+CURRENT PMESH ISSUES
+
+OPEN - issues that have not beeen resolved
+ 
+Issue: On the cluster, if storm_surge/pmesh is in the pythonpath (and
+not storm_surge?), pmesh.mesh fails by trying to load pmesh
+visualisation stuff.  Pmesh shouldn't be trying to load anyhow.
+
+Issue: crash if file>filter alpha boundary if there is no alpha
+boundary.
+
+Issue: Add export seg outline file back into pmesh
+
+Issue: triangles_to_polySet (outlining the current set) sometimes
+duplicates vertices.  Now that is fixed, but segments that overlap (ie
+one big line that gets little ones drawn on it) break triangle.
+
+Suggested action: make a dictionary of Hough transforms (parametric
+lines i.e. angle, x-intercept) of the segments. Check any that take up
+the same space. Fix overlapping lines.
+
+Issue: Red mesh selected for refinement seems to be 'behind' the green
+mesh after selecting all then clearing the selection.
+Importance: low
+Suggested Action: Fixed BUT now it draws the greens behind the reds.
+It is much less obvious now though.
+The only way to fix it for good is to colour in the triangles - that
+is the only way to guarantee you know what each triangle is.
+
+
+Issue:  Ole thought that the regional mesh max areas were incorrect
+when a .tsh file was loaded.  Maybe it was that the overall max area
+is not saved.  It's hard coded in MeshGenDialog.
+Importance: Medium
+Suggested Action: Fix when .tsh goes NETCDF
+
+Issue: Catch error if .tsh file is a bad format.
+suggestion: quick and dirty try - except
+Importance: Medium
+
+Issue (new feature): Have visualisation of verts be turned on and
+off.  This will speed things up.
+Importance: low
+
+Issue (new feature): Hve .tsh as a netscf fie, instead of an ascii
+file.
+Importance: Medium
+
+Issue: When a file is saved as and then saved later, sometimes the
+file name is not known.   Is it that 'clear' is removing the name
+(which it should). 
+
+Issue:A .tsh file loaded into pmesh after smoothing will not have the
+outline info, since this is removed when smoothing.  If this is a
+problem, refactor loadASCII so it can write the outline as well.
+Suggested Action: Document use
+
+Issue:vertices at the bottom of the canvas can be hard to visualise,
+since you don't know if all vertices are on the screen.  
+Suggested Action: have a 5% border
+Importance: low to not do
+
+Issue: The mesh produced by triangle isn't of high quality near a low
+angle formed by two user segments.
+Reason:triangle
+Tried:  Tried the triangle flags L,i,V (for info).  Using box.poly on
+nautilus.  Couldn't get a better quality mesh.
+
+Issue: Get the naming right for mesh/triangulation/user/generated.
+How about "outline + triangulation = mesh"
+Importance: Medium -low
+
+Issue: S/W - too many methods with the same name on differnent classes
+eg editWindow.  Makes things confusing. 
+Importance: low
+
+Issue: Normalise seems broken - what is it doing to the attributes?.  
+Suggested Action: remove!
+
+Bug: Calling 'Generate Mesh' on empty document or If there are no
+enclosed regions will cause trianglulation to crash pmesh.
+Importance: low - not do, but document
+Suggested Action: Catch them (with try) and do nothing
+notes:   Fixing the 'Generate Mesh' crash is a P3 requirement.
+
+The zoom in/out is jittery
+
+The initial mesh window coordinates are in the fourth quadrant.
+
+Deleting a selected object is done with the scroll bar, not the 
+delete key. 
+
+Issue: triangle calculates incorrect attribute values, some of the time.
+Importance: Medium
+Suggested Action: Preprocess data to smoth it out.
+
+Issue: pmesh can not be automatically installed in windows and linux,
+triangle doesn't compile easily.
+Installs best in Linux.  
+Importance: Low
+Suggested Action: delve into setup more so it works with a variety of
+compilers.
+
+Issue: two vertices can be ontop of one another
+Importance: Low
+Suggested Action: See how it goes when used.  The cost of checking
+probably doesn't outwiegh the benifit.
+action taken: When loading an xya file duplicate vertices are removed. 
+
+
+Issue: When calculating mesh, have the pointer turn into an hour glass
+Importance: Low
+
+****************
+CLOSED - issues that have  beeen resolved
+************
+Issue: If some triangles have tags and others don't then the data
+structure (a list of lists) is dificult to use in Numeric.
+Solution -  use a list structure, instead of list of lists 
+Closed -  used a list structure, instead of list of lists 
+ 
+Issue (Ole): I couldn't get pmesh to write mesh in the .msh format
+Importance: Mid
+Suggested action: Either 
+    1:  Equip scripted mesh generation with functionality for tagging
+    2:  Allow pmesh to store as msh
+    3:  Have a tsh2msh converter
+Closed: Couldn't be reproduced. suggested action 2 has already been
+implemented.  More investigation required before calling an issue an issue..
+
+Issue: After selecting all for refinement then clearing the selection
+segments (blue lines) can not be selected.
+Importance: High
+Suggested Action:Fixed
+Reason: 
+
+Issue: Refined triangles don't have the correct region information.
+Importance: High
+Suggested Action: Fixed
+Reason: I don't think 'refine' fixes triangle attributes
+
+
+Issue: Pmesh won't save a refined mesh.
+Importance: High
+Reason: Refine_triangle.getNewVertex was not appending to mesh.meshVertices,
+        nor was it assigning an index to the vertex.
+
+Issue When starting generate mesh, the cursor doesn't start in the
+first box.
+Importance: Low
+Action: fixed
+
+Issue: Why is triangle att's set as a list and returned as a list of
+lists, when loading from a .tsh file?  Note: a change of this might
+also affect the 'triangle' glue code.
+Note: This also happens to triangle atts! (?)
+action: triangle att's set as a list of lists
+
+Issue:Implememt the following with mesh gen minimum angle, 0 - 32
+nothing;32-40 warning message, may not converge; 40 - error message 
+Importance: Low
+Action: done
+
+Issue: Middle magnifying glass icon does not describe what it will do.
+Importance: Low Low
+action: too unimportant to do
+
+Issue:  Maybe triangle doesn't normalise meshes away from the origin,
+resulting in round-off error.
+Importance: Low Low
+Suggested Action: closed since this didn;t seem to be a problem.
+
+Issue:hull.exe generates files that it doesn't clean up eg called
+s1f8, se4, etc. These seem to turn up in a root directory
+Importance: Low
+
+Issue: Hull.exe (alpha shape) - gives an assertion error if points are
+too close together?.  
+Importance: Low
+Suggested Action: when using the results from hull.exe, check if it
+has given any results and throw a friendly message if there are no results.
+
+Issue: When adding segments, vertices are hard to select (with the mouse).
+
+Issue: Calling autoSegment when not in the pmesh directory will not
+work, since it calls the hull.exe, assuming it's in the current dir 
+Importance: medium
+Suggested Action: Have the current dir change to the pmesh dir , run
+hull, then change back
+action: contractor is making alpha shape in python
+
+Issue: In the shallow_water functions for pmesh, make the
+volume.interpolate_cons_quantitie call more automatic
+
+Issue: Need tests for pmesh functions in  shallow_water.py
+
+Issue: If there is a large scale grid, how many triangles can be
+generated?  with a normalised grid there's a limit of 22674.
+Using a 100 * 100 domain, a max triangle area of 0.01 produced
+1,048,576 triangles.
+
+Issue: Internal boudaries get an empty string as tag (per default?)
+Background: The notion of defaiults values for internal boundaries was removed, but this one seems to have taken its place. The following hack will 
+remove the tag: 
+  #for b in domain.boundary.keys():
+  #    if domain.boundary[b] == '':
+  #        del domain.boundary[b]
+  #
+  #domain = Domain(domain.coordinates, domain.triangles, domain.boundary)
+Importance: high
+
+
+Issue: The default region button cannot be selected after loading a file.
+Reason: Unknown.  
+Importance: Low
+
+Issue: The vertices were being sorted when loading .xya files
+Time to complete : 5hrs
+Issue: In load ascii all text reading of lines using find must ltrim
+beforehand
+
+Issue: pmesh -when loading/saving the dir should be the dir where the
+file lives.  Not always the current dir. 
+
+Issue: Tags for specifying boundary conditions should be arbitrary
+Background: Domain has the functionality for using arbitrary keys
+when associating boundary objects to boundary values.
+Triangle, which pmesh is based on, uses integers only.
+It would be nice to have mnemonic names for boundaries throughout.
+Importance: Mid
+Status: Unresolved
+
+Issue: Calling save the first time seemingly does nothing
+Importance: Low
+Suggested Action: Call save_as when save is clicked the first time.
+
+
+Bug: Calling Zoom functions on empty document 
+causes an AttributeError Exceptions.
+Importance: Medium
+Suggested Action: Catch them (with try) and do nothing
+notes: the zoom crash is not reproducable.  Fixing the 'Generate Mesh' crash
+is a P3 requirement.
+
+When doing mesh generation, no default values (min angle, max area)
+are shown. - Low priority for Chris
+
+
+Cursor shape changes when it shouldn't.
+
+Issue: Help message and status message are the same.  Remove one
+Importance: Low
+Suggested Action: Remove the status info
+
+
+Issue: Selecting nodes require that boundary is selected precisely.
+Importance: High
+Suggested Action: Allow click in interior of square.
+
+Bug: Entering negative value for area is allowed.
+Importance: Medium
+Suggested Action: Check input and return error message
+
+
+Issue: Minimum angle needs a specification of what interval is allowed.
+It seems to pick a default value if angle is out of bounds.
+Action: angles <0.0, >90.0 not allowed 
+
+Bug: Entering zero for area causes crash.
+Importance: Medium
+Suggested Action: Check input and return normal error message
+
+
+Issue: Re-generating grids goes slower and slower when repeated.
+Importance: Low
+Suggested Action: Check that old grid gets removed from memory.
+Action taken: cleaned up how visualised objects are handled
+
+
+Issue: nothing says what mode(seg or vertex) pmesh is in
+Importance: Low
+Action taken: Have the buttons stay 'down', to depict mode.
+
+  
+
+Issue: Meaning of 1 x zoom is not intuitive. 
+Related issue: Absolute scale should be reported in status bar
+Importance: Medium
+ Action taken : Zoom x 1  gives a zoom corresponding 
+to the opening screen.
+
+Vertices and segments that have a triangle on top of them are hard to 
+select/see.  Ole suggested that there be the capability to view/hide the mesh.
+ Action taken :put segs/vertices on top
+
+
+NOTES
+The arrow and postscript bottons currently do nothing.
+
+
+-----------------------------------------------
+NEW REQUIREMENTS
+
+Introduce 'eraser tool'. When selected left clicking any object will remove it.
+
+Allow generated grid to be cleared (or hidden).
+
+
+
+CVS INFORMATION FOR THIS FILE
+$Source: /var/lib/cvs/pmesh/documentation/issues.txt,v $
Index: /anuga_core/documentation/planning/priorities.tex
===================================================================
--- /anuga_core/documentation/planning/priorities.tex	(revision 3574)
+++ /anuga_core/documentation/planning/priorities.tex	(revision 3574)
@@ -0,0 +1,425 @@
+%FIXME: Take stuff from future_directions.txt and wiki
+	
+\documentclass[11pt]{report}
+\usepackage{graphicx}
+
+\title{AnuGA Inundation Modelling Project - Planning and Priorities - Draft}
+\author{Ole Nielsen, Duncan Gray, Jane Sexton, Nick Bartzis,\\ Trevor Dhu, Neil Corby, Stephen Roberts, ...}
+
+
+\date{\today}	  	  % update before release!
+				% Use an explicit date so that reformatting
+				% doesn't cause a new date to be used.  Setting
+				% the date to \today can be used during draft
+				% stages to make it easier to handle versions.
+
+%\release{1.0}			% release version; this is used to define the
+				% \version macro
+
+\makeindex			% tell \index to actually write the .idx file
+
+\begin{document}
+\maketitle
+
+\section*{Overview}
+
+The ANUGA inundation modelling project is a collaborative effort between
+ Geoscience Australia (GA) and the Australian National University
+ (ANU). GA is largely responsible for the software development,
+ applications to scenario and risk modelling projects as well as
+ contributions to the Australian National Research Priorities.  
+ ANU is mainly responsible for the mathematical and numerical modelling approach and the continued development of the model. 
+ 
+ 
+ This
+ document outlines the agreed priorities for the inundation modelling
+ project predominantly seen from the GA perspective, but including the ANU where appropriate. 
+ Priorities are organised into three separate streams focusing at the following objectives: 
+ \begin{enumerate}  
+   \item Deliverables of specific case studies. These are typically
+   tasks that are requested by GA's clients.
+   \item Research topics that have emerged and would advance the
+   understanding of the science of hydrodynamic inundation
+   \item Development and maintenance issues that are necessary for the
+   continued health of the software itself.
+\end{enumerate} 
+where the first is primarily resourced by Jane Sexton and Nick Bartzis, the second by Stephen Roberts and Ole Nielsen, while the third is the responsibility of Ole Nielsen and Duncan Gray. Significant overlaps are expected and names assigned to tasks are tentative only. 
+
+Overarching these three streams is a fourth stream, management, which covers coordination of the FESA project and management of the inundation modelling team.
+
+\section*{Specific case studies (production)}
+
+
+
+The list in order of importance but subject to availability of
+topographic data and URS/MOST input is
+
+\begin{enumerate} 
+  \item Onslow, WA - end of June 06. This study mainly supports the
+    FESA funded WA study, but has synergies with projects in other
+    lists as well (Nick)
+  \item Complete Sydney (Benfield) project (Jane). Refinements have
+    included addressing water loss through the form of the surface
+    elevation function, boundary conditions, friction creep and issues
+    with ill-conditioned system as a result of a complex internal
+    polygon. Whilst a protection has been put in place for friction
+    creep, the issue is still outstanding. Final results will be
+    delivered to Benfield by Fri 28 April noting the friction issue
+    is still outstanding.  This project has synergies with the ANUGA
+    Demo initiative (Everyone)
+  \item Port Hedland - end of June 06. Also part of the WA project. (Nick)
+  \item Broome
+  \item Perth
+  \item Busselton
+  \item Shark Bay using survey from 17th July 2006.
+  \item Xmas & Cocos islands tide gauge validation.
+  \item Rerun Wollongong with slump (pending better defition of slump sizes) (Nick, Adrian), 2-3 weeks
+  \item NSW state study  (deferred until 2007 - Matt)
+  \item SE Qld study
+  \item Hobart (2007). Trevor Dhu has arranged for TAFI to provide bathymetric data to a 50m contour plus a 25m DEM. Apparently, even better DEM data is available. 
+  \item Other study areas may be identified when the national hazard map has been completed (expected
+within the next 12 months) and consultation has occurred with stakeholders.
+\end{enumerate}
+Given that the production line is in a start-up phase and the needs
+outlined in the research and development streams, only priority 1 to 3
+are guaranteed to complete before 30 June 2006. However, once
+streamlined, we expect a production rate of about one scenario per
+month (subject to availability of computational resources and data).
+A number of these studies may not be conducted by the team, however,
+our assistance will certainly be required.
+
+
+
+\section*{Research topics}
+
+The list is
+
+\begin{enumerate} 
+  \item Sensitivity study using Onslow project (Nick, Jane, Ole)
+  The sensitivity to mesh resolution to be investigated. There are two aspects:
+  \begin{enumerate}
+    \item Resolution of triangles containing individual gauges. ANUGA
+    keeps track of the volume of water under each triangle. Pointwise
+    measurements away from triangle centroids may deviate
+    significantly from the true values due to the linear
+    reconstruction of triangle near steep bedslopes. One study would
+    provide an error estimate of the pointwise readings as a function
+    of resolution and slope.
+    \item How does resolution affect propagation of tsunami waves. One
+    could fix the resolution near gauges at selected points near and
+    on shore and vary resolution of bathymetry affecting the
+    approaching waves. Results reported as deviation at gauges as
+    function of bathymetric resolution upstream.
+  \end{enumerate}     
+  \begin{itemize}
+    \item Nick to do the runs  
+    \item Team to help setup the study and write document
+  \end{itemize}   
+  
+  \item Validation: 
+  \begin{itemize}
+    \item Onslow tide gauges (Ole with David Burbidge)
+      \begin{itemize}
+      \item Ole to get data and terms of reference
+      \item Nick to do the runs  
+      \item Team to help setup the study and write document    
+    \end{itemize} 
+    \item Boxing day event (ANU contract 2006/2007 with Asavanant and Grilli)
+    \item Friction validation (Duncan with Tom Baldock UQ)
+    Duncan to get a sense of scope on this by June 2006. 
+    Work to be done in 2006/2007.
+    \item PDC (Ole)
+    Ole to visit Pacifit Disaster Center in 6/7
+    \item 1953 Suva data from Tariq (someone)
+    Date is available. Ole to arrange for unpacking with GIS and scope project.
+    Could form a graduate project.
+    \item Comparison to tsunami study in NZ where Mike 21 is used for inundation. Contact: Rick Liefting, Coastal Scientist, Tonkin and Taylor Limited, www.tonkin.co.nz, Hamilton. Email: RLiefting@tonkin.co.nz    
+  \end{itemize} 
+  \item Comparison of MOST and ANUGA over a stretch of deep water. Also, where to pick up boundary condition (Nick).
+  \item Momentum sink study (Duncan with Nick Dando)
+  Report and talk by end of June 2006. Paper later.
+  \item Submarine landslide modelling paper with Dr Mueller or Russell Blong (Ask him), Sydney (Jane, Ole, Adrian/Monica, Matt). 
+        Perhaps use Wollongong as the study area.  
+  \item Probabilistic integration with URS model, pending URS data (Ole, Trevor). Duncan to write urs2sww for boundary conditions. Ole to ask PDC.  
+  \item Effect of the GBR based on new LADS data (which we need to get from Phil O'brien). 
+        This could become a graduate program, an ANU contract or a job for an ANU summer scholar
+        (see graduate\_proposal\_GBR.doc).
+  \item Comparing calculated run-up height with Synolakis' approximation 
+        ($R = A^\frac{4}{5} h^ \frac{1}{5}$ where $A$ is the amplitude at some offshore location
+         and $h$ is the depth at the same offshore location). Calculate the maximum elevation 
+         at which there is water. Need to confirm definition of run-up height.
+  \item Incorporate asteroid model (parabolic cavity) as an initial condition into ANUGA. 
+        Compare calculated extent with the approximation of
+        run-in (or maximum extent) from Chesley and Ward 2006 where the run-in distance is approximated
+        by $X \approx 10 \sqrt{g R} D^\frac{3}{8}$ where $R$ is the run-up height and $D$ is the 
+        asteroid diameter. Allows another event to be added to the overall
+        tsunami risk assessment. This could become a graduate or student project (see graduate\_proposal\_asteroid.doc).
+  \item Investigate the topographic effect on water flow and the impact on hydrological hazard (as part of the CRA
+        with NSW DNR and SES in contributing to the vulnerability assessment). This could become a graduate
+        or student project (see graduate\_proposal\_topography.doc).
+  
+  \item Scenario database (future); this could complement the ATWS
+    operational centre. (how often would it need to be updated, i.e how
+    long will the results remain valid?  eg, effect of sediment transport
+    affecting local bathymetry, change in sea levels due to climate
+    change). This is a product for the ATWS, states and EMA. AGO may need
+    scenarios under climate change scenarios.
+  \item Automatic definition of mesh-resolution based on data (e.g. depth or gradients). Perhaps use wavelet transforms. Stephen has a link to a researcher at Imperial College, London.
+  \item Investigate behaviour near steep and shallow bathymetries, where artifitial fluxes may be generated. Now evolved into 'friction creep'. 
+    Stephen to look into that with input from Ole.
+  \item Effect of debris on flow and damage (Under way at JCU - shawn)
+  \item Write ANUGA in term of latitudes and longitudes
+  \item Incorporate coriolis effect for large study areas
+  \item Revive storm surge model (Rosh DNR)
+  \item Riverine flooding (Rosh DNR)
+  \item Collaboration with Hans Peter ?? (Stephen Roberts)
+  \item Solution uncertainty (interaction with Hugh Durrant-Whyte and
+  Suresh Kumar from USyd)
+\end{enumerate}
+No more than priority 1-4 are expected to complete before 30 June 2006.
+
+
+\section*{Development and maintenance issues.}
+
+The list is
+
+\begin{enumerate} 
+  \item Bug fixing (see tickets in TRAC) - ongoing (Duncan \& Ole)
+  \item Integrated damage modelling (Duncan)
+  \begin{itemize}
+    \item Calculation of inundation extent. Determine "wet" cells and 
+    create the "extent$\_$polygon".
+        This polygon could then be used in damage modelling (rather than 
+getting the building information
+        from the NBED and the GIS team to determine the set of those buildings 
+which suffer inundation).
+        Script determine which buildings in extent by 
+        inside$\_$polygon(building$\_$i,extent$\_$polygon) == True.
+   \end{itemize}
+  \item Streamlined end-to-end process including production management of files (Nick + Hamish, Neil, Ole, Jane, Duncan)
+  In addition to Nick's automatic log of scripts generating the data, also log username and ANUGA version if possible.
+ 
+  \item Map2PDF vs ArcReader (Neil, Lisa)
+  \item Easy interface to building regions of variable resolution (Duncan)
+  \item Sydney demo (Jane, Duncan, Ole) - Ask 
+  \item Deploy parallel version (Ole, Nick)
+  \item Userguide, technical documentation and installation process (Everyone)
+  \item OSS License (Ole)
+  \item Visualisation (Nick, Ole)
+  \begin{itemize}
+    \item Hand crafted using Houdini
+    \item Take Swollen-viewer further, e.g.\ by colour coding quantitios or applying contour plots
+    \item ANU work on new visualisation techniques
+  \end{itemize}
+  \item Automatic coastline buffering. 
+    \item Improve memory efficiency of mesh generator.
+\end{enumerate}
+It is the hope that most of these priorities will be adressed before 30 June 2006.
+
+
+\section*{Roles and responsibilities}
+
+
+This is a first cut only. Please comment!
+
+
+\subsection*{Inundation modelling team (IMP)}
+\begin{enumerate} 
+  \item \textbf{Duncan}: Take responsibility for the code development
+  and maintenance. Represent the inundation modelling project in the
+  corporate IM context. Other responsibilities include
+  \begin{itemize}
+  \item IM
+  \item TRIM
+  \end{itemize}
+  Take responsibility for one or more research projects, and contribute to production on a needs basis.  
+  % Suggested work
+  % Production of one FESA study
+  % Boundary condition URS2SWW
+  % Damage modelling
+  \item \textbf{Jane}: Coordinate FESA production project, take responsibility for one or 
+  more research projects and contribute to production and code development on a needs basis. In the longer term, maintenance of other stakeholder relationships (?).
+  \item \textbf{Nick}: Take responsibility for the production stream, develop visualisation techniques, 
+  and contribute to code development on a needs basis. Other responsibilities include
+  \begin{itemize}
+  \item TRIM
+  \end{itemize}
+  \item \textbf{Ole}: Coordinate the inundation modelling project. 
+  Manage the balance and requirements between the research, development and production stream. 
+  Take responsibility for the code development and maintenance as well as one or more research projects. 
+  Contribute to production on a needs basis. Other responsibilities include
+  \begin{itemize}
+  \item Programmers User Group and High Performance Computing issues.
+  \end{itemize} 
+\end{enumerate}
+
+
+\subsection*{Digital Elevation Modelling Team (DEM)}
+\begin{enumerate} 
+  \item \textbf{Hamish Anderson}: Coordinate collection and supply of 
+  topographic and bathymetric data.    
+  \item \textbf{Mike Sexton}: Bathymetric data specialist.        
+  \item \textbf{Kathryn Tobyn}: Bathymetric data specialist.      
+\end{enumerate}   
+
+\subsection*{Earthquake and Tsunami Hazards (ETH)}
+\begin{enumerate} 
+  \item \textbf{David Burbidge}: Link to URS data; developing probabilistic hazard map
+  \item \textbf{Phil Cummins}: Team leader
+\end{enumerate}   
+
+\subsection*{GIS team}
+\begin{enumerate} 
+  \item \textbf{Neil Corby}: Coordinate development of GIS decision tool. 
+    Assist with collection and supply of topographic data.  
+  \item \textbf{Ingo Hartig}: Development of GIS decision tool. 
+    Assist with collection, supply and validation of topographic data.    
+    Assist IMP with genaral GIS visualisation.  
+  \item \textbf{Lisa Cornish}: Arcview exposure database with Neil
+\end{enumerate}   
+
+
+\begin{figure}
+
+  \centerline{ \includegraphics[width=75mm, height=75mm]{information_flow.eps}}
+
+
+\caption{Diagram showing information flow among the teams comprising the FESA project.}
+\label{fig:information flow}
+\end{figure}
+
+
+\subsection*{Other stakeholders}
+\begin{enumerate} 
+  \item \textbf{Stephen Roberts (ANU)}: Contribute to research and further development of 
+  ANUGA.   
+  \item \textbf{Linda Stals (ANU)}: Develop parallel version of ANUGA.     
+  \item \textbf{Adrian Hitchman and Monica Osuchowski}: Provide input to submarine landslide research.
+  \item \textbf{Trevor Dhu}: Develop new engagements with external
+  stakeholders such as state governments. Assist with development of probabilistic modelling.
+  \item Others?
+\end{enumerate}
+
+
+    
+\subsection*{Potential contacts}
+
+\begin{itemize} 
+  \item Lex Nielsen from SMEC in order to explore
+    how they can get involved
+  \item Lutz Grosz from ACcESS
+  \item Tom Baldock UQ
+  \item Tariq Rahiman (tir14@student.canterbury.ac.nz, tariq@mrd.gov.fj) (Suva scenario)
+  \item Allen L. Clark PDC (aclark@pdc.org)
+  \item Roy Walters, NIWA (tsunami modelling)
+  \item Russell Blong, Benfield (landslide modelling)
+  \item Ray Steedman, WA oceanography (By way of Norm Schramm)
+  \item Rosh Ranasinghe (DPNR)
+  \item Suresh Kumar (ACFR)
+\end{itemize}     
+
+    
+\subsection*{Resources}    
+    
+The allocation to the different streams from the core inundation modelling team in terms of 
+4 full time equivalents (FTE) are
+
+\begin{itemize} 
+\item \textbf{Production}: 1.25 FTE  (Mainly Nick)
+\item \textbf{Research}: 1 FTE
+\item \textbf{Code development and maintenance}: 1 FTE
+\item \textbf{Management}: 0.75 FTE (0.5 WA-FESA Project coordination, 0.25 TEAM)
+\end{itemize}
+
+
+\chapter{Personnel availability}
+
+\begin{itemize}
+  \item \textbf{Duncan}: 4 days/week
+  \item \textbf{Jane}: Three weeks leave in the period 15 June 2006 to 15 July 2006
+    Ole to cover Jane's commitments.
+  \item \textbf{Nick}: Leave from 21 August 2006 to 13 October 2006
+    Duncan to cover off on the production line.
+  \item \textbf{Ole}: Leave for six weeks around August or September. 
+    Jane to be acting team leader with Duncan responsible for
+    software and maintenance issues. 
+\end{itemize}
+
+
+
+\chapter{Detailed planning}
+
+Needs updating
+
+\section{Validation of ANUGA}
+
+\subsection{Laboratory Data}
+25 July 2005: Benchmark data from wave tank experiments 
+were deemed suitable for
+initial validation exercises and we should proceed with these
+immediately using the existing acquired datasets.  In addition, data
+from vertical wall run-ups will be relevant.  Andrew's letter to key
+players regarding other existing laboratory datasets is deemed
+extremely valuable and should go ahead.
+This has now completed in the form of the Okushiri island validation
+
+7 April 2006: Next exercise along these lines seems to be wavetank
+data from UQ as conducted by Tom Baldock et al. These experiments
+include friction. Duncan will visit Tom in May and possibly conduct a
+validation project depending on his findings.
+
+
+
+\subsection{Historical Data}
+Andrew McPherson has contacted relevant organisations regarding sources and
+availability of existing post-tsunami field survey data.  We agreed
+that a scenario from e.g. Banda Aceh or Thailand (Phuket)
+demonstrating the detailed effect of bathymetric variations would be
+an ideal study and could form the basis of a scientific paper. Matt is
+considering whether this would fit into his research priorities.
+
+Promising leads are
+\begin{itemize}
+  \item Suva data (Tariq)
+  \item Boxing day event conducted by the Grilli and Asavanant (Stephen Roberts). This has been flagged as a \$15K ANU project in FY 6/7
+  \item The Connection to Sri Lanka (John Schneider)
+\end{itemize}
+
+  
+\subsection{Other}
+Validation against analytical solutions is well under way and 
+is considered an integral component of the validation process.
+The same is true for the Lake Merimbula tidal validation project.
+Stephen, John Jakeman and Chris are looking after these.
+
+
+    
+
+\section{Potential joint PhD projects (GA and ANU)}
+Ole to investigate if GA would fund a PhD student: Project could be
+"Algorithms for augmentation of unstructured grids" or "Algorithms for
+unification of geodesic systems in unstructured grids" the latter
+capturing the notion of being able to model the synoptic, deep water
+wave propagation in latitudes and longitudes with a seemless connection 
+to detailed modelling using UTM projections.
+A PhD scholarship is worth about \$20K per annum. 
+
+7 April 2006: We are putting \$10K in the 06-07 budget.
+
+\section{Other projects}
+LADS (laser airborne depth sounder) data is available from the Hydrographer's Officer
+for the Great Barrier Reef. A project investigating whether or not a tsunami wave
+is attentuated by the reef would be a real benefit to the ATWS (to inform whether
+North Queensland is vulnerable).
+
+\section{Long term aim}
+
+We agreed that having a detailed, reproducible and validated 
+inundation scenario from the Boxing Day Tsunami running in parallel
+(and being faster than the sequential code) would be a worthwhile goal.   
+    
+    
+\end{document}
+
+
+
Index: /anuga_core/documentation/planning/update_anuga_planning.py
===================================================================
--- /anuga_core/documentation/planning/update_anuga_planning.py	(revision 3574)
+++ /anuga_core/documentation/planning/update_anuga_planning.py	(revision 3574)
@@ -0,0 +1,48 @@
+#!/usr/bin/env python
+
+"""Update, compile and create PDF and HTML from LaTeX file
+
+This can for example be run from a cronjob:
+
+  crontab -e
+
+with content 
+
+SHELL=/bin/sh
+PATH=/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin:~/bin
+
+# m h dom mon dow command
+  42 *  *   *   *  ~/anuga/documentation/user_manual/update_anuga_user_manual.py > ~/anuga/documentation/user_manual/update_anuga.log
+#
+
+
+Note UNIX only
+ 
+"""
+
+
+import os
+
+
+anugapath = os.path.expanduser('~/anuga/documentation/planning')
+texfiles = ['priorities']
+
+os.chdir(anugapath) # Move to location of LaTeX files 
+os.system('svn up') # Update from svn
+
+
+for texfile in texfiles:
+    print 'Processing %s' %texfile
+    # Compile with LaTeX, makeindex etc
+    for i in range(3):
+        os.system('latex --interaction=nonstopmode %s.tex' %texfile)
+        os.system('makeindex %s.idx' %texfile)
+        os.system('bibtex %s' %texfile)    
+
+    # Create pdf file
+    os.system('dvips %s -o %s.ps' %((texfile,)*2))    
+    os.system('ps2pdf %s.ps' %texfile)    
+     
+    # Create html pages     
+    os.system('latex2html %s' %texfile)
+
Index: /anuga_core/documentation/requirements/anuga_API_requirements.tex
===================================================================
--- /anuga_core/documentation/requirements/anuga_API_requirements.tex	(revision 3574)
+++ /anuga_core/documentation/requirements/anuga_API_requirements.tex	(revision 3574)
@@ -0,0 +1,279 @@
+\documentclass{manual}
+
+
+\title{ANUGA requirements for the Application Programmers Interface (API)}
+
+\author{Ole Nielsen, Duncan Gray, Jane Sexton, Nick Bartzis}
+
+% Please at least include a long-lived email address;
+% the rest is at your discretion.
+\authoraddress{Geoscience Australia \\
+  Email: \email{ole.nielsen@ga.gov.au}
+}
+
+%Draft date
+\date{\today}                   % update before release!
+				% Use an explicit date so that reformatting
+				% doesn't cause a new date to be used.  Setting
+				% the date to \today can be used during draft
+				% stages to make it easier to handle versions.
+
+\release{1.0}			% release version; this is used to define the
+				% \version macro
+
+\makeindex			% tell \index to actually write the .idx file
+%\makemodindex			% If this contains a lot of module sections.
+
+
+
+\begin{document}
+\maketitle
+
+
+
+% This makes the contents more accessible from the front page of the HTML.
+\ifhtml
+\chapter*{Front Matter\label{front}}
+\fi
+
+
+
+
+\chapter{Introduction}
+
+This document outlines the agreed requirements for the ANUGA API.
+
+	
+
+\chapter{Public API}		
+\section{General principles}	
+
+ The ANUGA API must be simple to use.  Operations that are
+conceptually simple should be easy to do. An example would be setting
+up a small test problem on a unit square without any geographic
+orientation.  Complex operations should be manageable and not require
+the user to enter information that isn't strictly part of the problem
+description. Examples are entering UTM coordinates (or geographic
+coordinates) as read from a map should not require any reference to a
+particular origin.  Nor should the same information have to be entered
+more than once per scenario.
+
+
+
+\section{Georeferencing}
+
+Currently ANUGA is limited to UTM coordinates assumed to belong to one zone.
+ANUGA shall throw an exception if this assumption is violated.
+
+It must be possible in general to enter data points as 
+	
+\begin{itemize}
+  \item A list of 2-tuples of coordinates in which case the points are 
+    assumed to be in absolute UTM coordinates in an undefined zone
+  \item An N by 2 Numeric array of coordinates. Points are assumed to 
+    be in absolute UTM coordinates in an undefined zone  
+  \item A geospatial dataset object that contains properly 
+    georeferenced points 
+\end{itemize} 	
+
+
+General
+\begin{itemize} 
+  \item The undefined zone must be a symbol or number that does 
+    not exist geographically.
+
+  \item Any component that needs coordinates to be relative to a
+  particular point shall be responsible for deriving that
+  origin. Examples are meshes where absolute coordinates may cause
+  numerical problems. An example of a derived origin would be using
+  the South-West most point on the boundary.
+
+  \item Coordinates must be passed around as either geospatial objects
+  or absolute UTM unless there is a compelling reason to use relative
+  coordinates on grounds of efficiency or numerical stability.
+  
+  \item Passing Geo_reference's as a keyword should not be done  Where
+  it is currently done, it doesn't have to be
+  changed as a matter of priority, but don't document this 'feature'
+  in the user manual.  If you are refactoring this API, then please
+  remove geo_reference as a keyword.
+  
+\end{itemize}   
+ 
+ 
+ 
+\chapter{Internal API}
+
+
+\section{Pmesh - ideas}
+If we were to automatically define regions of variable resolution it
+would be good to automatically tag regions defined by an alpha
+shape. - For this to be useful pmesh would also have to add mesh
+files.  A story would be load a file of points representing 5 and -5
+contour lines.  Use alpha shape to add segments, and define this
+region.  Add an overall outline and generate the mesh.   
+
+\section{Point files - ideas}
+
+Currently title information must be given for points files.  The api
+could be changed so the titles are an input.  These titles could be
+used if the file does not have titles.  This should reduce the amount
+of file pre-processing.
+
+Remove the ability of points files to have geo-refferencing
+information.  The values be absolute. Cons - zone information is lost.
+Pros - text files will be a csv format. 
+
+
+\section{Damage Model - Requirements}
+Generally, damage model determines a percentage damage to a set of
+structures and their content.
+The dollar loss for each structure and its contents due to this damage
+is then determined.
+
+The damage model used in ANUGA is expected to change. The requirements
+for this damage model is based on three algorithms.
+
+ 
+\begin{itemize} 
+  \item Probability of structural collapse.  Given the distance from
+  the coast and the maximum inundation height above ground floor, the
+  percentage probability of collapse is calculated.  The distance from
+  the coast is
+  'binned' into one of 4 distance ranges.  The height in binned into
+  one of 5 ranges.  The percentage result is therefore represented by
+  a 4 by 5 array. 
+  \item Structural damage curve.  Given the type of building (X or Y)
+  and the maximum inundation height above ground floor, the
+  percentage damage loss to the structure is determined.  The curve is
+  based on a set of [height, percentage damage] points.  
+  \item Content damage curve.  Given the maximum inundation height above
+  ground floor, the 
+  percentage damage loss to the content of each structure is
+  determined.  The curve is based on a set of [height, percentage
+  damage] points.  
+\end{itemize}  
+Interpolate between points when using the damage curves.
+
+
+The national building exposure database (NBED) gives the following relevant
+information for each structure;
+\begin{itemize} 
+  \item Location, Latitude and Longitude.
+  \item The total cost of the structure.
+  \item The total cost of the structures contents.
+  \item The building type  (Have to check how this is given).
+\end{itemize}  
+This information is given in a csv file. Each row is a structure.
+  
+So how will these dry algorithms (look-up tables) be used?  
+Given NBED, an sww and an assumed ground floor height the percent
+structure and content loss and probability of collapse can be determined.
+  
+The probability of collapse will be used in a way to have each
+structure either collapsed, or not not collapsed.  There will not be
+any 20\% probablity of collapse structures when calculating the damage
+loss.
+
+This is we will get either collapsed, or not not collapsed from a
+probability of collapse;
+\begin{itemize} 
+  \item Count the number of houses (sample size) with each unique
+ probability of collapse (excluding 0).
+  \item probability of collapse * sample size = Number of collapsed
+  buildings (NCB).
+  \item Round the number of collapsed buildings.
+  \item Randomly 'collapse' NCB buildings, from the sample structures.
+  This is done by setting the \% damage loss to structures and content
+  to 100.  This overrides losses calculated from the curves.   
+\end{itemize}  
+  
+What is the final output?
+Add these columns to the NBED file. 
+\begin{itemize} 
+  \item \% content damage
+  \item \% structure damage
+  \item damage cost to content
+  \item damage cost to structure
+  \item inundation above ground height
+\end{itemize}   
+
+How will the ground floor height be given?
+Have it passed as a keyword argument, defaulting to .3.
+
+\section{Damage Model - Design}
+It has to be modular.  In the future the three algorithms will be
+combined to give a cumulative probability distribution, so this part
+doesn't have to be designed to be too flexible.  This change will
+occur before the shape of the damage curves change, Ken believes.  
+
+Have one file that has general damage functions/classes, such as
+interrogating nbed csv files and calculating maximum inundation above
+ground hight. 
+
+\chapter{Efficiency and optimisation}
+
+
+\section{Parallelisation of pyvolution}
+
+
+(From ANU meeting 27/7/5)
+ 
+Remaining loose ends and ideas are
+\begin{itemize} 
+  \item fluxes in ghostcells should not affect timestep computation.
+  \item a function for re-assembling model output should be made available
+  \item scoping of methodologies for automatic domain decomposition
+  \item implementation of automatic domain decomposition (using C
+    extensions for maximal sequential performance in order to minimise
+    performance penalties due to Amdahl's law)
+  \item in depth testing and tuning of parallel performance. This may require 
+    adding wrappers for non-blocking MPI communication to pypar if needed.   
+  \item ability to read in precomputed sub-domains. Perhaps using caching.py  
+
+\end{itemize}   
+
+
+\chapter{Old stuff from pyvolution/wiki}
+
+
+\begin{itemize} 
+  \item Make origins instances of a georeference class 
+        (like class point from GPScape).
+         It would conatin multiple representation, projections and code for adding itself to e.g. NetCDF files.
+  \item Tagged regions, edges etc should be done in terms of set-theory,
+so that each tag maps e.g. to a list of indices.
+
+
+  \item The information from a .tsh file shall be converted to a data
+structure that pyvolution understands.
+  \item The vertex attribute information will be converted to field values
+ and they shall be accessable using the attribute tag.
+  \item Volumes will have a region tag. This shall be implemented using the
+  principals of set theory.
+  \item For a given region and a given field value/conserved quantity apply
+  a supplied function with parameters (x,y and the old value
+  of the field value/conserved quantity).  
+  \item Also need a flag specifying if the vertex or centroid values are
+  being set.(Rational - will can be used to avoid discontinuites/ or
+  create them, depending on what is required.)
+  Example calls: domain.set_field_values('bed_elevation', 
+		   			 f, location='vertices')
+					 
+  Example calls: domain.set_conserved_quantities('stage', f, 
+					         location='centroid')
+					 				 
+					
+					
+  where f has the form
+  def f(x, y, old_value):
+      ...
+      return z										 
+\end{itemize} 
+
+
+\end{document}
+
+
+
+
Index: /anuga_core/documentation/requirements/fancyhdr.sty
===================================================================
--- /anuga_core/documentation/requirements/fancyhdr.sty	(revision 3574)
+++ /anuga_core/documentation/requirements/fancyhdr.sty	(revision 3574)
@@ -0,0 +1,329 @@
+% fancyhdr.sty version 1.99d
+% Fancy headers and footers for LaTeX.
+% Piet van Oostrum, Dept of Computer Science, University of Utrecht
+% Padualaan 14, P.O. Box 80.089, 3508 TB Utrecht, The Netherlands
+% Telephone: +31 30 2532180. Email: piet@cs.ruu.nl
+% ========================================================================
+% LICENCE: This is free software. You are allowed to use and distribute
+% this software in any way you like. You are also allowed to make modified
+% versions of it, but you can distribute a modified version only if you
+% clearly indicate that it is a modified version and the person(s) who
+% modified it. This indication should be in a prominent place, e.g. in the
+% top of the file. If possible a contact address, preferably by email,
+% should be given for these persons. If that is feasible the modifications
+% should be indicated in the source code.
+% ========================================================================
+% MODIFICATION HISTORY:
+% Sep 16, 1994
+% version 1.4: Correction for use with \reversemargin
+% Sep 29, 1994:
+% version 1.5: Added the \iftopfloat, \ifbotfloat and \iffloatpage commands
+% Oct 4, 1994:
+% version 1.6: Reset single spacing in headers/footers for use with
+% setspace.sty or doublespace.sty
+% Oct 4, 1994:
+% version 1.7: changed \let\@mkboth\markboth to
+% \def\@mkboth{\protect\markboth} to make it more robust
+% Dec 5, 1994:
+% version 1.8: corrections for amsbook/amsart: define \@chapapp and (more
+% importantly) use the \chapter/sectionmark definitions from ps@headings if
+% they exist (which should be true for all standard classes).
+% May 31, 1995:
+% version 1.9: The proposed \renewcommand{\headrulewidth}{\iffloatpage...
+% construction in the doc did not work properly with the fancyplain style. 
+% June 1, 1995:
+% version 1.91: The definition of \@mkboth wasn't restored on subsequent
+% \pagestyle{fancy}'s.
+% June 1, 1995:
+% version 1.92: The sequence \pagestyle{fancyplain} \pagestyle{plain}
+% \pagestyle{fancy} would erroneously select the plain version.
+% June 1, 1995:
+% version 1.93: \fancypagestyle command added.
+% Dec 11, 1995:
+% version 1.94: suggested by Conrad Hughes <chughes@maths.tcd.ie>
+% CJCH, Dec 11, 1995: added \footruleskip to allow control over footrule
+% position (old hardcoded value of .3\normalbaselineskip is far too high
+% when used with very small footer fonts).
+% Jan 31, 1996:
+% version 1.95: call \@normalsize in the reset code if that is defined,
+% otherwise \normalsize.
+% this is to solve a problem with ucthesis.cls, as this doesn't
+% define \@currsize. Unfortunately for latex209 calling \normalsize doesn't
+% work as this is optimized to do very little, so there \@normalsize should
+% be called. Hopefully this code works for all versions of LaTeX known to
+% mankind.  
+% April 25, 1996:
+% version 1.96: initialize \headwidth to a magic (negative) value to catch
+% most common cases that people change it before calling \pagestyle{fancy}.
+% Note it can't be initialized when reading in this file, because
+% \textwidth could be changed afterwards. This is quite probable.
+% We also switch to \MakeUppercase rather than \uppercase and introduce a
+% \nouppercase command for use in headers. and footers.
+% May 3, 1996:
+% version 1.97: Two changes:
+% 1. Undo the change in version 1.8 (using the pagestyle{headings} defaults
+% for the chapter and section marks. The current version of amsbook and
+% amsart classes don't seem to need them anymore. Moreover the standard
+% latex classes don't use \markboth if twoside isn't selected, and this is
+% confusing as \leftmark doesn't work as expected.
+% 2. include a call to \ps@empty in ps@@fancy. This is to solve a problem
+% in the amsbook and amsart classes, that make global changes to \topskip,
+% which are reset in \ps@empty. Hopefully this doesn't break other things.
+% May 7, 1996:
+% version 1.98:
+% Added % after the line  \def\nouppercase
+% May 7, 1996:
+% version 1.99: This is the alpha version of fancyhdr 2.0
+% Introduced the new commands \fancyhead, \fancyfoot, and \fancyhf.
+% Changed \headrulewidth, \footrulewidth, \footruleskip to
+% macros rather than length parameters, In this way they can be
+% conditionalized and they don't consume length registers. There is no need
+% to have them as length registers unless you want to do calculations with
+% them, which is unlikely. Note that this may make some uses of them
+% incompatible (i.e. if you have a file that uses \setlength or \xxxx=)
+% May 10, 1996:
+% version 1.99a:
+% Added a few more % signs
+% May 10, 1996:
+% version 1.99b:
+% Changed the syntax of \f@nfor to be resistent to catcode changes of :=
+% Removed the [1] from the defs of \lhead etc. because the parameter is
+% consumed by the \@[xy]lhead etc. macros.
+% June 24, 1997:
+% version 1.99c:
+% corrected \nouppercase to also include the protected form of \MakeUppercase
+% \global added to manipulation of \headwidth.
+% \iffootnote command added.
+% Some comments added about \@fancyhead and \@fancyfoot.
+% Aug 24, 1998
+% version 1.99d
+% Changed the default \ps@empty to \ps@@empty in order to allow
+% \fancypagestyle{empty} redefinition.
+
+\let\fancy@def\gdef
+
+\def\if@mpty#1#2#3{\def\temp@ty{#1}\ifx\@empty\temp@ty #2\else#3\fi}
+
+% Usage: \@forc \var{charstring}{command to be executed for each char}
+% This is similar to LaTeX's \@tfor, but expands the charstring.
+
+\def\@forc#1#2#3{\expandafter\f@rc\expandafter#1\expandafter{#2}{#3}}
+\def\f@rc#1#2#3{\def\temp@ty{#2}\ifx\@empty\temp@ty\else
+                                    \f@@rc#1#2\f@@rc{#3}\fi}
+\def\f@@rc#1#2#3\f@@rc#4{\def#1{#2}#4\f@rc#1{#3}{#4}}
+
+% Usage: \f@nfor\name:=list\do{body}
+% Like LaTeX's \@for but an empty list is treated as a list with an empty
+% element
+
+\newcommand{\f@nfor}[3]{\edef\@fortmp{#2}%
+    \expandafter\@forloop#2,\@nil,\@nil\@@#1{#3}}
+
+% Usage: \def@ult \cs{defaults}{argument}
+% sets \cs to the characters from defaults appearing in argument
+% or defaults if it would be empty. All characters are lowercased.
+
+\newcommand\def@ult[3]{%
+    \edef\temp@a{\lowercase{\edef\noexpand\temp@a{#3}}}\temp@a
+    \def#1{}%
+    \@forc\tmpf@ra{#2}%
+        {\expandafter\if@in\tmpf@ra\temp@a{\edef#1{#1\tmpf@ra}}{}}%
+    \ifx\@empty#1\def#1{#2}\fi}
+% 
+% \if@in <char><set><truecase><falsecase>
+%
+\newcommand{\if@in}[4]{%
+    \edef\temp@a{#2}\def\temp@b##1#1##2\temp@b{\def\temp@b{##1}}%
+    \expandafter\temp@b#2#1\temp@b\ifx\temp@a\temp@b #4\else #3\fi}
+
+\newcommand{\fancyhead}{\@ifnextchar[{\f@ncyhf h}{\f@ncyhf h[]}}
+\newcommand{\fancyfoot}{\@ifnextchar[{\f@ncyhf f}{\f@ncyhf f[]}}
+\newcommand{\fancyhf}{\@ifnextchar[{\f@ncyhf {}}{\f@ncyhf {}[]}}
+
+% The header and footer fields are stored in command sequences with
+% names of the form: \f@ncy<x><y><z> with <x> for [eo], <y> form [lcr]
+% and <z> from [hf].
+
+\def\f@ncyhf#1[#2]#3{%
+    \def\temp@c{}%
+    \@forc\tmpf@ra{#2}%
+        {\expandafter\if@in\tmpf@ra{eolcrhf,EOLCRHF}%
+            {}{\edef\temp@c{\temp@c\tmpf@ra}}}%
+    \ifx\@empty\temp@c\else
+        \ifx\PackageError\undefined
+        \errmessage{Illegal char `\temp@c' in fancyhdr argument:
+          [#2]}\else
+        \PackageError{Fancyhdr}{Illegal char `\temp@c' in fancyhdr argument:
+          [#2]}{}\fi
+    \fi
+    \f@nfor\temp@c{#2}%
+        {\def@ult\f@@@eo{eo}\temp@c
+         \def@ult\f@@@lcr{lcr}\temp@c
+         \def@ult\f@@@hf{hf}{#1\temp@c}%
+         \@forc\f@@eo\f@@@eo
+             {\@forc\f@@lcr\f@@@lcr
+                 {\@forc\f@@hf\f@@@hf
+                     {\expandafter\fancy@def\csname
+                      f@ncy\f@@eo\f@@lcr\f@@hf\endcsname
+                      {#3}}}}}}
+
+% Fancyheadings version 1 commands. These are more or less deprecated,
+% but they continue to work.
+
+\newcommand{\lhead}{\@ifnextchar[{\@xlhead}{\@ylhead}}
+\def\@xlhead[#1]#2{\fancy@def\f@ncyelh{#1}\fancy@def\f@ncyolh{#2}}
+\def\@ylhead#1{\fancy@def\f@ncyelh{#1}\fancy@def\f@ncyolh{#1}}
+
+\newcommand{\chead}{\@ifnextchar[{\@xchead}{\@ychead}}
+\def\@xchead[#1]#2{\fancy@def\f@ncyech{#1}\fancy@def\f@ncyoch{#2}}
+\def\@ychead#1{\fancy@def\f@ncyech{#1}\fancy@def\f@ncyoch{#1}}
+
+\newcommand{\rhead}{\@ifnextchar[{\@xrhead}{\@yrhead}}
+\def\@xrhead[#1]#2{\fancy@def\f@ncyerh{#1}\fancy@def\f@ncyorh{#2}}
+\def\@yrhead#1{\fancy@def\f@ncyerh{#1}\fancy@def\f@ncyorh{#1}}
+
+\newcommand{\lfoot}{\@ifnextchar[{\@xlfoot}{\@ylfoot}}
+\def\@xlfoot[#1]#2{\fancy@def\f@ncyelf{#1}\fancy@def\f@ncyolf{#2}}
+\def\@ylfoot#1{\fancy@def\f@ncyelf{#1}\fancy@def\f@ncyolf{#1}}
+
+\newcommand{\cfoot}{\@ifnextchar[{\@xcfoot}{\@ycfoot}}
+\def\@xcfoot[#1]#2{\fancy@def\f@ncyecf{#1}\fancy@def\f@ncyocf{#2}}
+\def\@ycfoot#1{\fancy@def\f@ncyecf{#1}\fancy@def\f@ncyocf{#1}}
+
+\newcommand{\rfoot}{\@ifnextchar[{\@xrfoot}{\@yrfoot}}
+\def\@xrfoot[#1]#2{\fancy@def\f@ncyerf{#1}\fancy@def\f@ncyorf{#2}}
+\def\@yrfoot#1{\fancy@def\f@ncyerf{#1}\fancy@def\f@ncyorf{#1}}
+
+\newdimen\headwidth
+\newcommand{\headrulewidth}{0.4pt}
+\newcommand{\footrulewidth}{\z@skip}
+\newcommand{\footruleskip}{.3\normalbaselineskip}
+
+% Fancyplain stuff shouldn't be used anymore (rather
+% \fancypagestyle{plain} should be used), but it must be present for
+% compatibility reasons.
+
+\newcommand{\plainheadrulewidth}{\z@skip}
+\newcommand{\plainfootrulewidth}{\z@skip}
+\newif\if@fancyplain \@fancyplainfalse
+\def\fancyplain#1#2{\if@fancyplain#1\else#2\fi}
+
+\headwidth=-123456789sp %magic constant
+
+% Command to reset various things in the headers:
+% a.o.  single spacing (taken from setspace.sty)
+% and the catcode of ^^M (so that epsf files in the header work if a
+% verbatim crosses a page boundary)
+% It also defines a \nouppercase command that disables \uppercase and
+% \Makeuppercase. It can only be used in the headers and footers.
+\def\fancy@reset{\restorecr
+ \def\baselinestretch{1}%
+ \def\nouppercase##1{{\let\uppercase\relax\let\MakeUppercase\relax
+     \expandafter\let\csname MakeUppercase \endcsname\relax##1}}%
+ \ifx\undefined\@newbaseline% NFSS not present; 2.09 or 2e
+   \ifx\@normalsize\undefined \normalsize % for ucthesis.cls
+   \else \@normalsize \fi
+ \else% NFSS (2.09) present
+  \@newbaseline%
+ \fi}
+
+% Initialization of the head and foot text.
+
+% The default values still contain \fancyplain for compatibility.
+\fancyhf{} % clear all
+% lefthead empty on ``plain'' pages, \rightmark on even, \leftmark on odd pages
+% evenhead empty on ``plain'' pages, \leftmark on even, \rightmark on odd pages
+\fancyhead[el,or]{\fancyplain{}{\sl\rightmark}}
+\fancyhead[er,ol]{\fancyplain{}{\sl\leftmark}}
+\fancyfoot[c]{\rm\thepage} % page number
+
+% Put together a header or footer given the left, center and
+% right text, fillers at left and right and a rule.
+% The \lap commands put the text into an hbox of zero size,
+% so overlapping text does not generate an errormessage.
+% These macros have 5 parameters:
+% 1. \@lodd or \@rodd % This determines at which side the header will stick
+%    out.
+% 2. \f@ncyolh, \f@ncyelh, \f@ncyolf or \f@ncyelf. This is the left component.
+% 3. \f@ncyoch, \f@ncyech, \f@ncyocf or \f@ncyecf. This is the middle comp.
+% 4. \f@ncyorh, \f@ncyerh, \f@ncyorf or \f@ncyerf. This is the right component.
+% 5. \@lodd or \@rodd % This determines at which side the header will stick
+%    out. This is the reverse of parameter nr. 1. One of them is always
+%    \relax and the other one is \hss (after expansion).
+
+\def\@fancyhead#1#2#3#4#5{#1\hbox to\headwidth{\fancy@reset\vbox{\hbox
+{\rlap{\parbox[b]{\headwidth}{\raggedright#2\strut}}\hfill
+\parbox[b]{\headwidth}{\centering#3\strut}\hfill
+\llap{\parbox[b]{\headwidth}{\raggedleft#4\strut}}}\headrule}}#5}
+
+\def\@fancyfoot#1#2#3#4#5{#1\hbox to\headwidth{\fancy@reset\vbox{\footrule
+\hbox{\rlap{\parbox[t]{\headwidth}{\raggedright#2\strut}}\hfill
+\parbox[t]{\headwidth}{\centering#3\strut}\hfill
+\llap{\parbox[t]{\headwidth}{\raggedleft#4\strut}}}}}#5}
+
+\def\headrule{{\if@fancyplain\let\headrulewidth\plainheadrulewidth\fi
+\hrule\@height\headrulewidth\@width\headwidth \vskip-\headrulewidth}}
+
+\def\footrule{{\if@fancyplain\let\footrulewidth\plainfootrulewidth\fi
+\vskip-\footruleskip\vskip-\footrulewidth
+\hrule\@width\headwidth\@height\footrulewidth\vskip\footruleskip}}
+
+\def\ps@fancy{%
+\@ifundefined{@chapapp}{\let\@chapapp\chaptername}{}%for amsbook
+%
+% Define \MakeUppercase for old LaTeXen.
+% Note: we used \def rather than \let, so that \let\uppercase\relax (from
+% the version 1 documentation) will still work.
+%
+\@ifundefined{MakeUppercase}{\def\MakeUppercase{\uppercase}}{}%
+\@ifundefined{chapter}{\def\sectionmark##1{\markboth
+{\MakeUppercase{\ifnum \c@secnumdepth>\z@
+ \thesection\hskip 1em\relax \fi ##1}}{}}%
+\def\subsectionmark##1{\markright {\ifnum \c@secnumdepth >\@ne
+ \thesubsection\hskip 1em\relax \fi ##1}}}%
+{\def\chaptermark##1{\markboth {\MakeUppercase{\ifnum \c@secnumdepth>\m@ne
+ \@chapapp\ \thechapter. \ \fi ##1}}{}}%
+\def\sectionmark##1{\markright{\MakeUppercase{\ifnum \c@secnumdepth >\z@
+ \thesection. \ \fi ##1}}}}%
+%\csname ps@headings\endcsname % use \ps@headings defaults if they exist
+\ps@@fancy
+\gdef\ps@fancy{\@fancyplainfalse\ps@@fancy}%
+% Initialize \headwidth if the user didn't
+%
+\ifdim\headwidth<0sp
+%
+% This catches the case that \headwidth hasn't been initialized and the
+% case that the user added something to \headwidth in the expectation that
+% it was initialized to \textwidth. We compensate this now. This loses if
+% the user intended to multiply it by a factor. But that case is more
+% likely done by saying something like \headwidth=1.2\textwidth. 
+% The doc says you have to change \headwidth after the first call to
+% \pagestyle{fancy}. This code is just to catch the most common cases were
+% that requirement is violated.
+%
+    \global\advance\headwidth123456789sp\global\advance\headwidth\textwidth
+\fi}
+\def\ps@fancyplain{\ps@fancy \let\ps@plain\ps@plain@fancy}
+\def\ps@plain@fancy{\@fancyplaintrue\ps@@fancy}
+\let\ps@@empty\ps@empty
+\def\ps@@fancy{%
+\ps@@empty % This is for amsbook/amsart, which do strange things with \topskip
+\def\@mkboth{\protect\markboth}%
+\def\@oddhead{\@fancyhead\@lodd\f@ncyolh\f@ncyoch\f@ncyorh\@rodd}%
+\def\@oddfoot{\@fancyfoot\@lodd\f@ncyolf\f@ncyocf\f@ncyorf\@rodd}%
+\def\@evenhead{\@fancyhead\@rodd\f@ncyelh\f@ncyech\f@ncyerh\@lodd}%
+\def\@evenfoot{\@fancyfoot\@rodd\f@ncyelf\f@ncyecf\f@ncyerf\@lodd}%
+}
+\def\@lodd{\if@reversemargin\hss\else\relax\fi}
+\def\@rodd{\if@reversemargin\relax\else\hss\fi}
+
+\newif\iffootnote
+\let\latex@makecol\@makecol
+\def\@makecol{\ifvoid\footins\footnotetrue\else\footnotefalse\fi
+\let\topfloat\@toplist\let\botfloat\@botlist\latex@makecol}
+\def\iftopfloat#1#2{\ifx\topfloat\empty #2\else #1\fi}
+\def\ifbotfloat#1#2{\ifx\botfloat\empty #2\else #1\fi}
+\def\iffloatpage#1#2{\if@fcolmade #1\else #2\fi}
+
+\newcommand{\fancypagestyle}[2]{%
+  \@namedef{ps@#1}{\let\fancy@def\def#2\relax\ps@fancy}}
Index: /anuga_core/documentation/requirements/fncychap.sty
===================================================================
--- /anuga_core/documentation/requirements/fncychap.sty	(revision 3574)
+++ /anuga_core/documentation/requirements/fncychap.sty	(revision 3574)
@@ -0,0 +1,433 @@
+%%% Derived from the original fncychap.sty,
+%%% but changed ``TWELV'' to ``TWELVE''.
+
+%%% Copyright   Ulf A. Lindgren
+%%%             Department of Applied Electronics
+%%%             Chalmers University of Technology
+%%%             S-412 96 Gothenburg, Sweden
+%%%             E-mail lindgren@ae.chalmers.se
+%%%
+%%% Note        Permission is granted to modify this file under
+%%%             the condition that it is saved using another
+%%%             file and package name.
+%%%
+%%% Revision    1.1
+%%%
+%%%             Jan. 8th Modified package name base date option
+%%%             Jan. 22th Modified FmN and FmTi for error in book.cls
+%%%                  \MakeUppercase{#}->{\MakeUppercase#}
+%%%             Apr. 6th Modified Lenny option to prevent undesired 
+%%%                  skip of line.
+%%%             Nov. 8th Fixed \@chapapp for AMS
+%%%             Feb. 11th Fixed appendix problem related to Bjarne
+%%% Last modified    Feb. 11th 1998
+
+\NeedsTeXFormat{LaTeX2e}[1995/12/01]
+\ProvidesPackage{fncychap}
+             [1997/04/06 v1.11
+                 LaTeX package (Revised chapters)]
+
+%%%% DEFINITION OF Chapapp variables
+\newcommand{\CNV}{\huge\bfseries}
+\newcommand{\ChNameVar}[1]{\renewcommand{\CNV}{#1}}
+
+
+%%%% DEFINITION OF TheChapter variables
+\newcommand{\CNoV}{\huge\bfseries}
+\newcommand{\ChNumVar}[1]{\renewcommand{\CNoV}{#1}}
+
+\newif\ifUCN
+\UCNfalse
+\newif\ifLCN
+\LCNfalse
+\def\ChNameLowerCase{\LCNtrue\UCNfalse}
+\def\ChNameUpperCase{\UCNtrue\LCNfalse}
+\def\ChNameAsIs{\UCNfalse\LCNfalse}
+
+%%%%% Fix for AMSBook 971008
+
+\@ifundefined{@chapapp}{\let\@chapapp\chaptername}{}
+
+
+%%%%% Fix for Bjarne and appendix 980211
+
+\newif\ifinapp
+\inappfalse
+\renewcommand\appendix{\par
+  \setcounter{chapter}{0}%
+  \setcounter{section}{0}%
+  \inapptrue%
+  \renewcommand\@chapapp{\appendixname}%
+  \renewcommand\thechapter{\@Alph\c@chapter}}
+
+%%%%%
+
+\newcommand{\FmN}[1]{%
+\ifUCN
+   {\MakeUppercase#1}\LCNfalse
+\else
+   \ifLCN
+      {\MakeLowercase#1}\UCNfalse
+   \else #1
+   \fi
+\fi}
+
+
+%%%% DEFINITION OF Title variables
+\newcommand{\CTV}{\Huge\bfseries}
+\newcommand{\ChTitleVar}[1]{\renewcommand{\CTV}{#1}}
+
+%%%% DEFINITION OF the basic rule width
+\newlength{\RW}
+\setlength{\RW}{1pt}
+\newcommand{\ChRuleWidth}[1]{\setlength{\RW}{#1}}
+
+\newif\ifUCT
+\UCTfalse
+\newif\ifLCT
+\LCTfalse
+\def\ChTitleLowerCase{\LCTtrue\UCTfalse}
+\def\ChTitleUpperCase{\UCTtrue\LCTfalse}
+\def\ChTitleAsIs{\UCTfalse\LCTfalse}
+\newcommand{\FmTi}[1]{%
+\ifUCT
+
+   {\MakeUppercase#1}\LCTfalse
+\else
+   \ifLCT
+      {\MakeLowercase#1}\UCTfalse
+   \else #1
+   \fi
+\fi}
+
+
+
+\newlength{\mylen}
+\newlength{\myhi}
+\newlength{\px}
+\newlength{\py}
+\newlength{\pyy}
+\newlength{\pxx}
+
+
+\def\mghrulefill#1{\leavevmode\leaders\hrule\@height #1\hfill\kern\z@}
+
+\newcommand{\DOCH}{%
+  \CNV\FmN{\@chapapp}\space \CNoV\thechapter
+  \par\nobreak
+  \vskip 20\p@
+  }
+\newcommand{\DOTI}[1]{%
+    \CTV\FmTi{#1}\par\nobreak
+    \vskip 40\p@
+    }
+\newcommand{\DOTIS}[1]{%
+    \CTV\FmTi{#1}\par\nobreak
+    \vskip 40\p@
+    }
+
+%%%%%% SONNY DEF
+
+\DeclareOption{Sonny}{%
+  \ChNameVar{\Large\sf}
+  \ChNumVar{\Huge}
+  \ChTitleVar{\Large\sf}
+  \ChRuleWidth{0.5pt}
+  \ChNameUpperCase
+  \renewcommand{\DOCH}{%
+    \raggedleft
+    \CNV\FmN{\@chapapp}\space \CNoV\thechapter
+    \par\nobreak
+    \vskip 40\p@}
+  \renewcommand{\DOTI}[1]{%
+    \CTV\raggedleft\mghrulefill{\RW}\par\nobreak
+    \vskip 5\p@
+    \CTV\FmTi{#1}\par\nobreak
+    \mghrulefill{\RW}\par\nobreak
+    \vskip 40\p@}
+  \renewcommand{\DOTIS}[1]{%
+    \CTV\raggedleft\mghrulefill{\RW}\par\nobreak
+    \vskip 5\p@
+    \CTV\FmTi{#1}\par\nobreak
+    \mghrulefill{\RW}\par\nobreak
+    \vskip 40\p@}
+}
+
+%%%%%% LENNY DEF
+
+\DeclareOption{Lenny}{%
+
+  \ChNameVar{\fontsize{14}{16}\usefont{OT1}{phv}{m}{n}\selectfont}
+  \ChNumVar{\fontsize{60}{62}\usefont{OT1}{ptm}{m}{n}\selectfont}
+  \ChTitleVar{\Huge\bfseries\rm}
+  \ChRuleWidth{1pt}
+  \renewcommand{\DOCH}{%
+    \settowidth{\px}{\CNV\FmN{\@chapapp}}
+    \addtolength{\px}{2pt}
+    \settoheight{\py}{\CNV\FmN{\@chapapp}}
+    \addtolength{\py}{1pt}
+
+    \settowidth{\mylen}{\CNV\FmN{\@chapapp}\space\CNoV\thechapter}
+    \addtolength{\mylen}{1pt}
+    \settowidth{\pxx}{\CNoV\thechapter}
+    \addtolength{\pxx}{-1pt}
+
+    \settoheight{\pyy}{\CNoV\thechapter}
+    \addtolength{\pyy}{-2pt}
+    \setlength{\myhi}{\pyy}
+    \addtolength{\myhi}{-1\py}
+    \par
+    \parbox[b]{\textwidth}{%
+    \rule[\py]{\RW}{\myhi}%
+    \hskip -\RW%
+    \rule[\pyy]{\px}{\RW}%
+    \hskip -\px%
+    \raggedright%
+    \CNV\FmN{\@chapapp}\space\CNoV\thechapter%
+    \hskip1pt%
+    \mghrulefill{\RW}%
+    \rule{\RW}{\pyy}\par\nobreak%
+    \vskip -\baselineskip%
+    \vskip -\pyy%
+    \hskip \mylen%
+    \mghrulefill{\RW}\par\nobreak%
+    \vskip \pyy}%
+    \vskip 20\p@}
+ 
+
+  \renewcommand{\DOTI}[1]{%
+    \raggedright
+    \CTV\FmTi{#1}\par\nobreak
+    \vskip 40\p@}
+
+  \renewcommand{\DOTIS}[1]{%
+    \raggedright
+    \CTV\FmTi{#1}\par\nobreak
+    \vskip 40\p@}
+ }
+
+
+%%%%%%% GLENN DEF
+
+
+\DeclareOption{Glenn}{%
+  \ChNameVar{\bfseries\Large\sf}
+  \ChNumVar{\Huge}
+  \ChTitleVar{\bfseries\Large\rm}
+  \ChRuleWidth{1pt}
+  \ChNameUpperCase
+  \ChTitleUpperCase
+  \renewcommand{\DOCH}{%
+    \settoheight{\myhi}{\CTV\FmTi{Test}}
+    \setlength{\py}{\baselineskip}
+    \addtolength{\py}{\RW}
+    \addtolength{\py}{\myhi}
+    \setlength{\pyy}{\py}
+    \addtolength{\pyy}{-1\RW}
+     
+    \raggedright
+    \CNV\FmN{\@chapapp}\space\CNoV\thechapter
+    \hskip 3pt\mghrulefill{\RW}\rule[-1\pyy]{2\RW}{\py}\par\nobreak}
+
+  \renewcommand{\DOTI}[1]{%
+    \addtolength{\pyy}{-4pt}
+    \settoheight{\myhi}{\CTV\FmTi{#1}}
+    \addtolength{\myhi}{\py}
+    \addtolength{\myhi}{-1\RW}
+    \vskip -1\pyy
+    \rule{2\RW}{\myhi}\mghrulefill{\RW}\hskip 2pt
+    \raggedleft\CTV\FmTi{#1}\par\nobreak
+    \vskip 80\p@}
+
+  \renewcommand{\DOTIS}[1]{%
+    \setlength{\py}{10pt}
+    \setlength{\pyy}{\py}
+    \addtolength{\pyy}{\RW}
+    \setlength{\myhi}{\baselineskip}
+    \addtolength{\myhi}{\pyy}
+    \mghrulefill{\RW}\rule[-1\py]{2\RW}{\pyy}\par\nobreak
+%    \addtolength{}{}
+\vskip -1\baselineskip
+    \rule{2\RW}{\myhi}\mghrulefill{\RW}\hskip 2pt
+    \raggedleft\CTV\FmTi{#1}\par\nobreak
+    \vskip 60\p@}
+  }
+
+%%%%%%% CONNY DEF
+
+\DeclareOption{Conny}{%
+  \ChNameUpperCase
+  \ChTitleUpperCase  
+  \ChNameVar{\centering\Huge\rm\bfseries}
+  \ChNumVar{\Huge}
+  \ChTitleVar{\centering\Huge\rm}
+  \ChRuleWidth{2pt}
+
+  \renewcommand{\DOCH}{%
+    \mghrulefill{3\RW}\par\nobreak
+    \vskip -0.5\baselineskip
+    \mghrulefill{\RW}\par\nobreak
+    \CNV\FmN{\@chapapp}\space \CNoV\thechapter
+    \par\nobreak
+    \vskip -0.5\baselineskip
+   }
+  \renewcommand{\DOTI}[1]{%
+    \mghrulefill{\RW}\par\nobreak
+    \CTV\FmTi{#1}\par\nobreak
+    \vskip 60\p@
+    }
+  \renewcommand{\DOTIS}[1]{%
+    \mghrulefill{\RW}\par\nobreak
+    \CTV\FmTi{#1}\par\nobreak
+    \vskip 60\p@
+    }
+  }
+
+%%%%%%% REJNE DEF
+
+\DeclareOption{Rejne}{%
+
+  \ChNameUpperCase
+  \ChTitleUpperCase  
+  \ChNameVar{\centering\Large\rm}
+  \ChNumVar{\Huge}
+  \ChTitleVar{\centering\Huge\rm}
+  \ChRuleWidth{1pt}
+  \renewcommand{\DOCH}{%
+    \settoheight{\py}{\CNoV\thechapter}
+    \addtolength{\py}{-1pt}
+    \CNV\FmN{\@chapapp}\par\nobreak
+    \vskip 20\p@
+    \setlength{\myhi}{2\baselineskip}
+    \setlength{\px}{\myhi}
+    \addtolength{\px}{-1\RW}
+    \rule[-1\px]{\RW}{\myhi}\mghrulefill{\RW}\hskip
+    10pt\raisebox{-0.5\py}{\CNoV\thechapter}\hskip
+10pt\mghrulefill{\RW}\rule[-1\px]{\RW}{\myhi}\par\nobreak
+     \vskip -1\p@
+    }
+  \renewcommand{\DOTI}[1]{%
+    \setlength{\mylen}{\textwidth}
+    \addtolength{\mylen}{-2\RW}
+    {\vrule width\RW}\parbox{\mylen}{\CTV\FmTi{#1}}{\vrule
+width\RW}\par\nobreak
+    \vskip
+-1pt\rule{\RW}{2\baselineskip}\mghrulefill{\RW}\rule{\RW}{2\baselineskip}
+    \vskip 60\p@
+    }
+  \renewcommand{\DOTIS}[1]{%
+    \setlength{\py}{\fboxrule}
+    \setlength{\fboxrule}{\RW}
+    \setlength{\mylen}{\textwidth}
+    \addtolength{\mylen}{-2\RW}
+    \fbox{\parbox{\mylen}{\vskip
+2\baselineskip\CTV\FmTi{#1}\par\nobreak\vskip \baselineskip}} 
+    \setlength{\fboxrule}{\py}
+    \vskip 60\p@
+    }
+  }
+
+
+%%%%%%% BJARNE DEF
+
+\DeclareOption{Bjarne}{%
+  \ChNameUpperCase
+  \ChTitleUpperCase  
+  \ChNameVar{\raggedleft\normalsize\rm}
+  \ChNumVar{\raggedleft \bfseries\Large}
+  \ChTitleVar{\raggedleft \Large\rm}
+  \ChRuleWidth{1pt}
+
+
+%% Note thechapter -> c@chapter fix appendix bug
+
+  \newcounter{AlphaCnt}
+  \newcounter{AlphaDecCnt}
+  \newcommand{\AlphaNo}{%
+    \ifcase\number\theAlphaCnt
+      \ifnum\c@chapter=0
+        ZERO\else{}\fi
+    \or ONE\or TWO\or THREE\or FOUR\or FIVE
+    \or SIX\or SEVEN\or EIGHT\or NINE\or TEN
+    \or ELEVEN\or TWELVE\or THIRTEEN\or FOURTEEN\or FIFTEEN
+    \or SIXTEEN\or SEVENTEEN\or EIGHTEEN\or NINETEEN\fi
+}
+
+  \newcommand{\AlphaDecNo}{%
+    \setcounter{AlphaDecCnt}{0}
+    \@whilenum\number\theAlphaCnt>0\do
+      {\addtocounter{AlphaCnt}{-10}
+       \addtocounter{AlphaDecCnt}{1}}
+     \ifnum\number\theAlphaCnt=0
+     \else
+       \addtocounter{AlphaDecCnt}{-1}
+       \addtocounter{AlphaCnt}{10}
+     \fi
+     
+     
+    \ifcase\number\theAlphaDecCnt\or TEN\or TWENTY\or THIRTY\or
+    FORTY\or FIFTY\or SIXTY\or SEVENTY\or EIGHTY\or NINETY\fi
+    }
+  \newcommand{\TheAlphaChapter}{%
+    
+    \ifinapp 
+      \thechapter
+    \else
+      \setcounter{AlphaCnt}{\c@chapter}
+      \ifnum\c@chapter<20
+        \AlphaNo
+      \else
+        \AlphaDecNo\AlphaNo
+      \fi
+    \fi
+    }  
+  \renewcommand{\DOCH}{%
+    \mghrulefill{\RW}\par\nobreak
+    \CNV\FmN{\@chapapp}\par\nobreak 
+    \CNoV\TheAlphaChapter\par\nobreak
+    \vskip -1\baselineskip\vskip 5pt\mghrulefill{\RW}\par\nobreak
+    \vskip 20\p@
+    }
+  \renewcommand{\DOTI}[1]{%
+    \CTV\FmTi{#1}\par\nobreak
+    \vskip 40\p@
+    }
+  \renewcommand{\DOTIS}[1]{%
+    \CTV\FmTi{#1}\par\nobreak
+    \vskip 40\p@
+    }
+}
+
+\DeclareOption*{%
+  \PackageWarning{fancychapter}{unknown style option}
+  }
+
+\ProcessOptions* \relax
+
+\def\@makechapterhead#1{%
+  \vspace*{50\p@}%
+  {\parindent \z@ \raggedright \normalfont
+    \ifnum \c@secnumdepth >\m@ne
+      \DOCH
+    \fi
+    \interlinepenalty\@M
+    \DOTI{#1}
+  }}
+\def\@schapter#1{\if@twocolumn
+                   \@topnewpage[\@makeschapterhead{#1}]%
+                 \else
+                   \@makeschapterhead{#1}%
+                   \@afterheading
+                 \fi}
+\def\@makeschapterhead#1{%
+  \vspace*{50\p@}%
+  {\parindent \z@ \raggedright
+    \normalfont
+    \interlinepenalty\@M
+    \DOTIS{#1}
+    \vskip 40\p@
+  }}
+
+\endinput
+
+
Index: /anuga_core/documentation/requirements/least_squares_redesign.txt
===================================================================
--- /anuga_core/documentation/requirements/least_squares_redesign.txt	(revision 3574)
+++ /anuga_core/documentation/requirements/least_squares_redesign.txt	(revision 3574)
@@ -0,0 +1,193 @@
+Project Plan
+
+By Duncan Gray
+
+INTRODUCTION
+
+ Software, called least squares, has been developed to implement a
+penalised least-squares fit and associated interpolations. It is
+currently in least_squares.py.  Steven Roberts outlined the least
+squares algorithm used. The code is currently not meeting user
+requirements with regards to speed and memory use.  Additional
+functionality is also needed.
+
+
+SCOPE
+
+This is looking at redesigning the least_squares module, excluding
+interpolate_function and pts2rectangle.  Other modules will
+be modified, based on these changes, e.g.  geospatial_data.py.
+
+
+LIFE-CYCLE
+
+Use a staged delivery life-cycle (see rapid development), with the
+proviso that additional functionality to supporting objects, such as
+build_quadtree in quad.py can be worked on after requirements have
+been determined.  Also, the current least squares may be tinkered with
+to check the feasibility of concepts and general maintanance.  The
+main thrust will be refactoring though. 
+
+
+______________________________________________________________________
+Least Squares Refactoring Software Requirements Specification
+
+By Duncan Gray
+
+
+INTRODUCTION
+
+This document specifies the requirements of the redesign of least squares.
+
+DEFINITIONS
+
+  
+REQUIREMENT SECTION
+
+Introduction
+
+Assume that all the requirements of the current least squares code will
+stay the same, unless stated.  Note implementation and names used are
+not regarded as requirements.  
+
+
+Requirements - Fitting
+
+When in verbose mode display how many points are in the
+mesh and how many are outside its boundary. Also display the max # of
+points/ triangle and the minimum number of points.  If this operation
+takes a lot of time, let it be optional.
+
+Raise an exception if no points are inside the mesh.
+
+Per build cycle, fitting 2 million points to a 600,000 triangles mesh
+will not cause a memory error.
+
+Remove least_squares commandline.  This means it will be called using
+python files, which should increase accountability.
+
+Points do not have to be supplied all at once.  They can be supplied
+as blocks. (This will improve memory use)
+
+Requirements - Interpolation
+
+Return information on which points were outside the mesh (in such a
+way that it can not be interpreted as real data).  If attribute
+information for points outside the mesh is returned, that can only be
+a float, let the user set the default value that is returned for
+points outside the mesh. if the value can be set to NAN, then set it
+to NAN. 
+
+
+Reduce the time spent building matrix A. (not a testable requirement)
+
+Points do not have to be supplied all at once.  They can be supplied
+as blocks. (This will improve memory use)
+
+A target to aim for
+Algorithmic complexity of build equations should be linear in number
+of data points and logorithmic in the number of vertices.
+
+Constraint
+Memory consumption of least squares equations must be indepenent on
+the number of datapoints. (Except for the memory used to store the points.) 
+___________________________________________________________________________
+Least Squares System Design Specification
+
+By Duncan Gray - lots of good ideas by Ole
+
+
+INTRODUCTION
+
+This specifies design choices for the least squares code.
+
+DESIGN IDEAS, to meet requirements
+*To save memory;
+When interpolating, don't build AtA, B and D. (This has been implemented)
+When fitting, don't build A. - Work with AtA and Atz. Build Atz
+directly, rather than through At*z - use code similar to AtA.
+
+
+* To save memory
+
+This is for the layer interpolation and fitting with IO: Use blocking
+when interpolating/fitting a large number of points (how large?  Can the
+program check the available memory and work out a good block size?
+Maybe have it user specified.  Do have the option for user specified)
+
+The code has to be refactored so fitting can handle blocked point
+info.  Need a building phase and a solve phase.  
+
+*Returning information on points outside the mesh.
+Do not find that these points are outside the mesh by searching the
+binary tree.  Do it by using polygon.  (data_manager.sww2dem does not
+use the expanded search, since it needs points outside the mesh, and
+setting precrop to True means these points are not returned.  Using a
+precrop of true and expand search true grinds the system to a halt.)
+___________________
+Heres the snippet (from data_manager.py) that will identify points outside the mesh, in case you can use it for the interpolate methodology:
+ 
+    P = interp.mesh.get_boundary_polygon()
+    outside_indices = outside_polygon(grid_points, P, closed=True)
+    for i in outside_indices:
+        grid_values[i] = NODATA_value        
+Cheers, O
+__________________
+
+*To reduce the time spent building matrix A.
+
+Change the expansion algorithm, when determining what triangle a point
+ is in, when none of the vertices are in the cell the point is in.
+
+Options (still thinking about this one)
+*  It should look in the cell of the point and then all adjacent
+cells. If it isn't there then ... expand more. 
+- Building the structure to keep this info could be prohibitive.
+
+*A feature that could work for the current implementation is to keep a
+ list of triangles that have been checked, so each incorrect triangle
+ isn't checked three times, if all three verts are in the cell being checked. 
+
+Another speed up option is to write the bottlenecks in C. Do it if necessary.
+
+* To give warnings.
+Use warnings module?  Check this out.
+
+DESIGN IDEAS, refactoring
+
+Remove georeferencing from build_interpolation_matrix_A. Change the
+point co-ords to conform to the mesh co-ords early in the code.
+
+Currently there is one class, called Interpolation, that holds the
+matrix data and methods for fitting and interpolation.  Break this
+into two classes, one for fittting, the other for interpolation. Have
+processes common to both classes in functions.     
+
+Have least squares as two stand alone packages.  One that has the guts
+of LS (e.g. the two new classes).  One that has the IO API's
+(functions that load and write files and do the blocking).  The guts
+package will be dependent of the general mesh package.  The IO API
+will rely on an IO module.
+
+HOW WILL IMPLEMENTATION OCCUR?
+Code a new least squares module in a seperate directory.  Heavily cut
+and paste from the old least squares. Implement memory and time tests
+on the old least squares (and new LS) before doing any changes.  
+
+For the speed up, discuss/ get go ahead from Ole before implementing
+any major changes, since there is no obvious way forward.
+
+EXTRA IDEAS
+- Reading in multiple sww files.  If data is broken into multiple sww
+files, eg 0 - 30 sec 30 - 60 sec, how do we take this into account?
+In the old version it's in Interpolate_sww, when 
+x, y, volumes, time, quantity = self.read_sww(...) occurs
+
+The time vector is incresed and the quantity matrix is increased.
+
+If the sww files are being split up to keep them below 2 GB in size
+the quantity matrix could be huge.
+
+How about a 'near enough' method? where you give a list of points, it
+determines which triangles the points are in and returns the time
+series vert info for those points.       
Index: /anuga_core/documentation/requirements/manual.cls
===================================================================
--- /anuga_core/documentation/requirements/manual.cls	(revision 3574)
+++ /anuga_core/documentation/requirements/manual.cls	(revision 3574)
@@ -0,0 +1,155 @@
+%
+% manual.cls for the Python documentation
+%
+
+\NeedsTeXFormat{LaTeX2e}[1995/12/01]
+\ProvidesClass{manual}
+             [1998/03/03 Document class (Python manual)]
+
+\RequirePackage{pypaper}
+\RequirePackage{fancybox}
+
+% Change the options here to get a different set of basic options, but only
+% if you have to.  Paper and font size should be adjusted in pypaper.sty.
+%
+\LoadClass[\py@paper,\py@ptsize,twoside,openright]{report}
+
+\setcounter{secnumdepth}{2}
+
+% Optional packages:
+%
+% If processing of these documents fails at your TeX installation,
+% these may be commented out (independently) to make things work.
+% These are both supplied with the current version of the teTeX
+% distribution.
+%
+% The "fancyhdr" package makes nicer page footers reasonable to
+% implement, and is used to put the chapter and section information in 
+% the footers.
+%
+\RequirePackage{fancyhdr}\typeout{Using fancier footers than usual.}
+
+
+% Required packages:
+%
+% The "fncychap" package is used to get the nice chapter headers.  The
+% .sty file is distributed with Python, so you should not need to disable
+% it.  You'd also end up with a mixed page style; uglier than stock LaTeX!
+%
+\RequirePackage[Bjarne]{fncychap}\typeout{Using fancy chapter headings.}
+% Do horizontal rules it this way to match:
+\newcommand{\py@doHorizontalRule}{\mghrulefill{\RW}}
+%
+%
+% This gives us all the Python-specific markup that we really want.
+% This should come last.  Do not change this.
+%
+\RequirePackage{python}
+
+% support for module synopsis sections:
+\newcommand{\py@ModSynopsisFilename}{\jobname\thechapter.syn}
+\let\py@OldChapter=\chapter
+\renewcommand{\chapter}{
+  \py@ProcessModSynopsis
+  \py@closeModSynopsisFile
+  \py@OldChapter
+}
+
+
+% Change the title page to look a bit better, and fit in with the
+% fncychap ``Bjarne'' style a bit better.
+%
+\renewcommand{\maketitle}{%
+  \begin{titlepage}%
+    \let\footnotesize\small
+    \let\footnoterule\relax
+    \py@doHorizontalRule%
+    \ifpdf
+      \begingroup
+      % This \def is required to deal with multi-line authors; it
+      % changes \\ to ', ' (comma-space), making it pass muster for
+      % generating document info in the PDF file.
+      \def\\{, }
+      \pdfinfo{
+        /Author (\@author)
+        /Title (\@title)
+      }
+      \endgroup
+    \fi
+    \begin{flushright}%
+      {\rm\Huge\py@HeaderFamily \@title \par}%
+      {\em\LARGE\py@HeaderFamily \py@release\releaseinfo \par}
+      \vfill
+      {\LARGE\py@HeaderFamily \@author \par}
+      \vfill\vfill
+      {\large
+       \@date \par
+       \vfill
+       \py@authoraddress \par
+      }%
+    \end{flushright}%\par
+    \@thanks
+  \end{titlepage}%
+  \setcounter{footnote}{0}%
+  \let\thanks\relax\let\maketitle\relax
+  \gdef\@thanks{}\gdef\@author{}\gdef\@title{}
+}
+
+
+% Catch the end of the {abstract} environment, but here make sure the
+% abstract is followed by a blank page if the 'openright' option is used.
+%
+\let\py@OldEndAbstract=\endabstract
+\renewcommand{\endabstract}{
+  \if@openright
+    \ifodd\value{page}
+      \typeout{Adding blank page after the abstract.}
+      \vfil\pagebreak
+    \fi
+  \fi
+  \py@OldEndAbstract
+}
+
+% This wraps the \tableofcontents macro with all the magic to get the
+% spacing right and have the right number of pages if the 'openright'
+% option has been used.  This eliminates a fair amount of crud in the
+% individual document files.
+%
+\let\py@OldTableofcontents=\tableofcontents
+\renewcommand{\tableofcontents}{%
+  \setcounter{page}{1}%
+  \pagebreak%
+  \pagestyle{plain}%
+  {%
+    \parskip = 0mm%
+    \py@OldTableofcontents%
+    \if@openright%
+      \ifodd\value{page}%
+        \typeout{Adding blank page after the table of contents.}%
+        \pagebreak\hspace{0pt}%
+      \fi%
+    \fi%
+    \cleardoublepage%
+  }%
+  \pagenumbering{arabic}%
+  \@ifundefined{fancyhf}{}{\pagestyle{normal}}%
+  \py@doing@page@targetstrue%
+}
+% This is needed to get the width of the section # area wide enough in the
+% library reference.  Doing it here keeps it the same for all the manuals.
+%
+\renewcommand*\l@section{\@dottedtocline{1}{1.5em}{2.6em}}
+\renewcommand*\l@subsection{\@dottedtocline{2}{4.1em}{3.5em}}
+\setcounter{tocdepth}{1}
+
+
+% Fix the theindex environment to add an entry to the Table of
+% Contents; this is much nicer than just having to jump to the end of
+% the book and flip around, especially with multiple indexes.
+%
+\let\py@OldTheindex=\theindex
+\renewcommand{\theindex}{
+  \cleardoublepage
+  \py@OldTheindex
+  \addcontentsline{toc}{chapter}{\indexname}
+}
Index: /anuga_core/documentation/requirements/plotting_module_requirements.txt
===================================================================
--- /anuga_core/documentation/requirements/plotting_module_requirements.txt	(revision 3574)
+++ /anuga_core/documentation/requirements/plotting_module_requirements.txt	(revision 3574)
@@ -0,0 +1,60 @@
+Requirements for module to plot time series data after simulation run.
+
+31 March 2006
+
+
+
+1.	The module shall read a SWW file and plot the time series for the prescribed quantities at defined gauge locations.
+
+1.1	The prescribed quantities must be a name of an existing quantity or an expression involving existing quantities.
+1.1.1	The default quantity will be 'depth'.
+1.1.2	The user can define a list of quantities. The possibilities are the conserved quantitues of the shallow water wave equation and other quantities which can be derived from those, i.e. ['stage', 'depth', 'xmomentum', 'ymomentum', 'momentum', 'velocity', 'bearing'].
+1.1.3	Absolute momentum ('momentum') will be calculated as sqrt(xmomentum^2 + ymomentum^2).
+1.1.4	Velocity should be calculated as absolute momentum divided (pointwise) by depth.
+1.1.5	Bearing should return the angle of the momentum vector (xmomentum, ymomentum) from the North direction.
+
+1.2	The gauge locations should either be defined in a separate file in which case the plotting function is 
+        invoked with the name of the file, or they should be provided as an argument in the form of a Numeric array 
+	or a structure that can be converted to a Numeric array.
+1.2.1	The gauges file should contain the gauge name and location defined in eastings and northings.
+1.2.2	The gauge file should be a comma separated file.
+
+1.3	The module should be contained in data_manager.py (I think it should be a new module (Ole))
+1.3.1	The output should be available both as data and graphics.
+1.3.2	The default output shall be graphics.
+1.3.3	The output should optionally be computed for a prescribed time range.
+1.3.4 	The default time range is the complete time series.
+1.3.5	The output should be stored in the same directory as the SWW file.
+    
+1.4	A latex document should be automatically generated which contains the output graphics.
+1.4.1	The caption of the output graphics should contain the gauge name and other simulation parameters.
+
+The outline of the module is as follows:
+
+def sww2timeseries(swwfile,
+                   gauge_filename,   (or a structure that contains that info, e.g. based on Geospatial_data)
+                   gauge_data_outname,
+                   quantity = None,
+                   time_min = None,
+                   time_max = None,
+                   verbose = False):
+
+    # extract gauge locations from gauge file
+    
+    # extract all quantities from sww file
+    
+    # loop through appropriate range of time
+    
+    # plot prescribed quantities and export data if requested
+    
+
+    return
+
+
+where
+
+swwfile defines the input sww file
+gauge_filename defines the gauge (name, easting, northing)
+gauge_data_outname defined the name of the output data file (if required)
+time_min defines the beginning of the time range 
+time_max defines the end of the time range
Index: /anuga_core/documentation/requirements/pmesh_requirements_documentation.txt
===================================================================
--- /anuga_core/documentation/requirements/pmesh_requirements_documentation.txt	(revision 3574)
+++ /anuga_core/documentation/requirements/pmesh_requirements_documentation.txt	(revision 3574)
@@ -0,0 +1,331 @@
+Pmesh Software Requirements Specification
+By Duncan Gray
+
+$Revision: 1.29 $
+$Date: 2004/08/13 08:31:15 $
+
+INTRODUCTION
+
+The software, called pmesh, will produce a triangulation based on
+initial vertices and boundaries.  The produced triangulation can be
+used by an evolution code to solve storm surge problems using the Finite
+Volume Method.
+
+
+The requirements in this document describe the software features
+needed to produce triangulations useful for Geohazards.
+
+OVERALL DESCRIPTION 
+
+Pmesh is a graphical user interface (GUI) for triangle (a mesh
+generating program developed by J. R. Shewchuk) which is a mesh
+generation program. It will allow vertices (points) and segments
+(straight lines between the vertices) to be added to a canvas.
+
+
+
+Pmesh will let the user select various modes. The initial
+allowable modes will be vertex or segment.  The mode describes what sort
+of object is added or selected in response to mouse clicks.  When
+changing modes any prior selected objects become deselected.
+ 
+In general the left mouse button will add an object and the right mouse
+button will select an object.  A selected object can de deleted by
+pressing the delete key.  Additionaly, by pressing the middle mouse
+button (scroll bar) the attributes of a selected object can be edited.
+
+The graphical objects are of two types; user or generated.  User
+objects are vertices and segments inputted by the user.  These are
+used by triangle when generating a mesh.
+
+ The generated objects are vertices, segments and triangles of the
+triangulation.  Only the triangles are graphically displayed.
+Generated objects can not be modified by the user. To modify the
+generated triangulation edit the user objects and generate a new
+trianglulation.
+
+
+DEFINITIONS
+
+Segments are edges whose presence in the triangulation is constraints.
+Segments can be used to define the boundaries of a problem.
+
+A triangulation is the triangles, vertices and segments generated by
+triangle.
+
+A mesh is all the triangle elements .e.g. the vertices, segments and
+triangulation.
+
+A Planar Straight Line Graph (PSLG) is a set of vertices and segments.
+Segments are simply edges, whose endpoints are vertices in the PSLG.
+Segments may join each other only at their endpoints and must not intersect.
+
+
+REQUIREMENT SECTION
+
+Introduction
+
+Each requirement has a priority (e.g. P1), with 1 being the highest
+and 10 the lowest.  The priority number is given at the end of each
+requirement.
+
+IMPLIMENTED
+
+Requirements
+
+- When a mesh is loaded  all of the mesh will fit in the application
+  window - P1 DONE
+  
+- If some of the mesh is not visible scroll bars are used to make
+  the canvas visible - P1 DONE
+
+- Have ability to zoom in by *2 on the mesh and zoom out, by
+  *0.5. -P1 DONE 
+ 
+- add user vertices, positioning by mouse - P1 DONE
+		     , positioning by entering x,y values - P1 DONE
+
+- add user segments, vertices selection by mouse - P1 DONE
+
+- be able to select a user vertex. -P2 DONE
+
+- be able to select a user segment. -P2 DONE
+
+- to be able to delete selected user objects. -P2 DONE
+
+- be able to delete an entire mesh. - P2 DONE
+  
+- To be able to load and save meshes as a python pickled object. -P2 DONE
+
+- access to triangle mesh generator,
+	  user can select min angle, max area - P1 DONE
+	  user can select rough number of triangles to generate - P3
+	  DONE
+	  
+- The screen should reflect the current generated triangulation -P2 DONE
+
+- Have 'Zoom' button that positions all of the mesh in the viewing
+  window - P3 DONE  
+
+- Be able to automatically generate segments that bound all of the
+user vertices, but not a convex hull bound.  Specifically, be able to
+apply an alpha shape around a set of vertices. - P3 - DONE
+ 
+- specify a region by selecting a point bounded by segments. - P30 - DONE
+
+- specify an attribute to a region. - P30 - DONE
+
+- specify a hole in the mesh by selecting a point bounded by
+  segments. - P30 - DONE
+
+
+- write an ascii file that outputs - P30 - DONE
+# of vertices
+[x,y]
+# of triangles
+[vert1 #, vert2 #, vert3 #, adjoining triangle 1, adjoining triangle
+2, adjoining triangle 3, attributes of region ]
+if there is no adjoining triangle, give -1 as the adjoining triangle.
+
+
+- specify how much vertex attribute information can be added to the mesh. -P40
+  - eg one attribute per vertex, two attributes per vertex
+- specify the default attribute vertex value - P40
+
+- edit segment attribute.  Can only select integers -P40 - DONE
+
+
+- load the following user vertex file layout 
+  - First row {"Lat", "Long", "Depth"}
+  - Subsiquent rows x y positions with 1 attribute
+  - Initially, load the file type, ditching the attribute info - P3 DONE
+  - Use the attribute info - P60 - DONE
+
+- Have an ascii export/import file format, that fully specifies a mesh 
+  - Add more output to the current export, so a mesh is fully specified
+  - Add an import of the exported format   - P60 - Done
+  
+- Print out the triangulation as a postscript file - P80 - DONE
+
+- Be able to tag boundaries with strings. - DONE
+ 
+- Have a warning prompt when saving a mesh where the generated mesh is
+  different from the user mesh - eg boundary tags that aren't carried
+  thru. Warning ~"Mesh not generated after changes.  Generate mesh?  "
+  - cancel, don't gen, don't save.  Yes - generate mesh, go to save
+  screen.  No - goto save screen.  To implement this need to know when
+  the user has done a change, and the mesh hasn't been generated.  If
+  there is no generated mesh do not prompt. - DONE
+
+access to triangle mesh generator,
+	  user can select  max area in region - P80 - DONE
+ 
+- .xya file, which has vertex information, will have headers naming
+the attributes in the first row.  The headers will be strings
+representing a label for the attribute information.  This information
+will be space deliminated.  There will be no ordering imposed.  The
+name, column index mapping will be in the .tsh file.
+      - x and y headings are manitory. - not done, requirements changed
+      - Missing fields will cause an error during loading of the xya file.
+
+ 
+ NOT IMPLIMENTED
+- show file name in title bar
+ 
+- Have a divide all max areas by value x function. - P80
+
+- triang.genMesh - get triangle compiled automatically. 
+
+- able to specify a 'circular' region by specifying center, radius and
+  number of number of segments. (The functionality is there as a hack.
+   need to add gui etc.) - P100
+   
+- Display mouse point position [x,y] - P60
+
+- Calculate total area enclosed (maybe a buton?) -P80
+	  (this requirement GUI aspect needs to be fleshed out with Chris)
+	  
+- Load in a segment attribute to boundary mapping.  ie segment
+  attribute is 'seen' as a boundary, such as a 0 flux boundary and
+  this is interanally represented as an interger, as defined by the
+  mapping. - P100 
+  
+- Select segment attribute from an enumerated list of boundaries. - P100
+  
+- Select segment attribute from an enumerated list of boundaries and
+  can also input values of constants described in the boundary. - P100
+
+- Select objects  - Be able to select multiple objects.  Eg select
+  many segments and mark with one attribute -P100
+
+- Be able to select objects by "mouse dragging" a rectangle. (A
+  rectangle whos size and position is controlled by the mouse)
+  Everything within the rectangle is selected.
+  
+- Move user vertices  - can initially be  done by
+  adding/deleting vertices and segments. -P100 [should we have this feature?]
+
+- specify a maximum area for each triangle, based on current mesh
+  (this is refinement of the current mesh) - P100
+
+- able to specify a 'circular' region by specifying center, radius and
+  number of number of segments. - P100
+  
+-Log window.  Have a separate window that displays log information.
+This window can be turned on or off. - P100
+
+- Log information of the generation mesh process.  - P100
+  - max area
+  - minimum angle
+  [Other information to be determined ] 
+
+- reduce mesh generation crashing by only mesh generating if all of the
+vertices are bounded by segments. - P100
+
+- Set the initial mesh co-ordinate to origin (0,0) at canvas bottom left and
+  (100,100)at canvas top right.
+
+- Have info with the mesh, such as #of triangles, min angle, max area
+	  (this requirement GUI aspect needs to be fleshed out with Chris)
+	  
+- Put postscript/clear/close buttons as a menu, not at the bottom of
+  pmesh
+  
+- assume the scale is metres, important for the programs using the
+mesh.  Maybe in add vertex have the scale?
+
+- be able to add two .tsh files together.
+
+- run triangle as a seperate thread, so if it's not converging it can
+be stopped. - P100
+ 
+-  
+__________________
+ 
+The information below describe the various colours for drawn objects,
+given the objects state.
+User Vertex, not selected  - small black rectangle (to represent a point)
+	     selected      - small red rectangle
+	     selected when adding a segment - small orange rectangle
+User Segment, not selected  - blue line
+	     selected      - red line
+	     
+Computer Vertices and Segments will not be drawn
+Computer Triangle,  not selected  - green triangle 
+	     selected      - red triangle (can be selected to add max
+	     area value when refining triangulations)
+_________________________
+
+
+DEVELOPMENT
+
+The pmesh software will be developed using an iterative approach, with
+it being "released" several times and each release having increased
+functionality. The first iteration will be a minimal system.
+Requirements to be delivered in each iteration are described below.
+
+Currently four iterations are planned.
+Each requirement is associated with an iteration, via the requirement's
+priority, represented by a P number. P1, P2, P3 etc.
+
+ 
+1st iteration P1 & P2 - basic framework, loading and saving of meshes
+2nd iteration P3      - specifying  # of triangles in mesh
+3rd iteration P30     - specify holes, regions and having attributes
+			for regions  
+4rd iteration P40     - attribute and boundary manipulation
+			 
+5th iteration P60     - increased GUI functionality
+
+6th iteration P80     - region selection, selection of different max
+			 triangle areas based on region, segments
+			automatically added
+Future iterations P100    
+__________________________
+
+NOTES
+
+How to speed things up.
+Use numericpy to build the data structures and then pass them straight
+to the triangle.o (This is assuming the numericpy data structures are
+in a c format.) - Don't lose the OO structure though. 
+
+preallocate lists, instead of calling c repeditively
+_______
+Questions
+What format will the initial data in? Chris is going to find an inital
+format, from previous work.
+
+How will data be taken in future? ie do we have datasets that we will
+convert or will we hand generate initial data sets?
+ 
+What s/w package takes care of the boundary conditions?
+[this seems to be an open issue still.]
+
+Things to work out with Chris and Steve: 
+How can the quality of the meshes be tested? Chris believes triangle
+diagnostices should provide this information.
+
+Will we need this?
+  -L  Do not use diametral lenses to determine whether subsegments are
+        encroached; use diametral circles instead (as in Ruppert's
+        algorithm).  Use this switch if you want all triangles in the mesh
+        to be Delaunay, and not just constrained Delaunay; or if you want
+        to ensure that all Voronoi vertices lie within the triangulation.
+        (Applications such as some finite volume methods may have this
+        requirement.)  This switch may increase the number of vertices in
+        the mesh to meet these constraints.
+ ________________________________________________________________
+
+REQUIREMENT ISSUES
+
+ - if a vertex with attribute info is moved, the attribute info does
+ not change.  This will not reflect the actual environment. Option
+ 1)The user can enter correct attribute data
+  
+ 2) the s/w can interpolate, based on the original vertex data.
+ 
+ Currently suggesting option 1 - Duncan and Chris.
+ 
+CVS INFORMATION FOR THIS FILE
+$Source: /var/lib/cvs/pmesh/documentation/mesh_gen_SRS.txt,v $
Index: /anuga_core/documentation/requirements/pypaper.sty
===================================================================
--- /anuga_core/documentation/requirements/pypaper.sty	(revision 3574)
+++ /anuga_core/documentation/requirements/pypaper.sty	(revision 3574)
@@ -0,0 +1,18 @@
+%
+%  Change this to say a4paper instead of letterpaper if you want A4.  These
+%  are the latex defaults.
+%
+\newcommand{\py@paper}{letterpaper}
+\newcommand{\py@ptsize}{10pt}
+
+%  These set up the fonts for the documents.
+%
+%  The "times" package makes the default font the PostScript Times
+%  font, which makes for smaller PostScript and a font that more people 
+%  like.
+%
+%  The "avant" package causes the AvantGarde font to be used for
+%  sans-serif text, instead of the uglier Helvetica set up by the "times"
+%  package.
+%
+\RequirePackage{times}\typeout{Using Times instead of Computer Modern.}
Index: /anuga_core/documentation/requirements/python.ist
===================================================================
--- /anuga_core/documentation/requirements/python.ist	(revision 3574)
+++ /anuga_core/documentation/requirements/python.ist	(revision 3574)
@@ -0,0 +1,11 @@
+line_max 100
+headings_flag 1
+heading_prefix "  \\bigletter "
+
+preamble "\\begin{theindex}
+\\def\\bigletter#1{{\\Large\\sffamily#1}\\nopagebreak\\vspace{1mm}}
+
+"
+
+symhead_positive "{Symbols}"
+numhead_positive "{Numbers}"
Index: /anuga_core/documentation/requirements/python.sty
===================================================================
--- /anuga_core/documentation/requirements/python.sty	(revision 3574)
+++ /anuga_core/documentation/requirements/python.sty	(revision 3574)
@@ -0,0 +1,1309 @@
+%
+% python.sty for the Python docummentation  [works only with Latex2e]
+%
+
+\NeedsTeXFormat{LaTeX2e}[1995/12/01]
+\ProvidesPackage{python}
+             [1998/01/11 LaTeX package (Python markup)]
+
+\RequirePackage{longtable}
+\RequirePackage{underscore}
+
+% Uncomment these two lines to ignore the paper size and make the page 
+% size more like a typical published manual.
+%\renewcommand{\paperheight}{9in}
+%\renewcommand{\paperwidth}{8.5in}   % typical squarish manual
+%\renewcommand{\paperwidth}{7in}     % O'Reilly ``Programmming Python''
+
+% These packages can be used to add marginal annotations which indicate
+% index entries and labels; useful for reviewing this messy documentation!
+%
+%\RequirePackage{showkeys}
+%\RequirePackage{showidx}
+
+% If we ever want to indent paragraphs, this needs to be changed.
+% This is used inside the macros defined here instead of coding
+% \noindent directly.
+\let\py@parindent=\noindent
+
+% for PDF output, use maximal compression & a lot of other stuff
+% (test for PDF recommended by Tanmoy Bhattacharya <tanmoy@qcd.lanl.gov>)
+%
+\newif\ifpy@doing@page@targets
+\py@doing@page@targetsfalse
+
+\newif\ifpdf\pdffalse
+\ifx\pdfoutput\undefined\else\ifcase\pdfoutput
+\else
+  \pdftrue
+  \input{pdfcolor}
+  \let\py@LinkColor=\NavyBlue
+  \let\py@NormalColor=\Black
+  \pdfcompresslevel=9
+  \pdfpagewidth=\paperwidth    % page width of PDF output
+  \pdfpageheight=\paperheight  % page height of PDF output
+  %
+  % Pad the number with '0' to 3 digits wide so no page name is a prefix
+  % of any other.
+  %
+  \newcommand{\py@targetno}[1]{\ifnum#1<100 0\fi\ifnum#1<10 0\fi#1}
+  \newcommand{\py@pageno}{\py@targetno\thepage}
+  %
+  % This definition allows the entries in the page-view of the ToC to be
+  % active links.  Some work, some don't.
+  %
+  \let\py@OldContentsline=\contentsline
+  %
+  % Backward compatibility hack: pdfTeX 0.13 defined \pdfannotlink,
+  % but it changed to \pdfstartlink in 0.14.  This let's us use either
+  % version and still get useful behavior.
+  %
+  \@ifundefined{pdfstartlink}{
+    \let\pdfstartlink=\pdfannotlink
+  }{}
+  %
+  % The \py@parindent here is a hack -- we're forcing pdfTeX into
+  % horizontal mode since \pdfstartlink requires that.
+  \def\py@pdfstartlink{%
+    \ifvmode\py@parindent\fi%
+    \pdfstartlink%
+  }
+  %
+  % Macro that takes two args: the name to link to and the content of
+  % the link.  This takes care of the PDF magic, getting the colors
+  % the same for each link, and avoids having lots of garbage all over 
+  % this style file.
+  \newcommand{\py@linkToName}[2]{%
+    \py@pdfstartlink attr{/Border [0 0 0]} goto name{#1}%
+      \py@LinkColor#2\py@NormalColor%
+    \pdfendlink%
+  }
+  % Compute the padded page number separately since we end up with a pair of
+  % \relax tokens; this gets the right string computed and works.
+  \renewcommand{\contentsline}[3]{%
+    \def\my@pageno{\py@targetno{#3}}%
+    \py@OldContentsline{#1}{\py@linkToName{page\my@pageno}{#2}}{#3}%
+  }
+  \AtEndDocument{
+    \def\_{\string_}
+    \InputIfFileExists{\jobname.bkm}{\pdfcatalog{/PageMode /UseOutlines}}{}
+  }
+  \newcommand{\py@target}[1]{%
+    \ifpy@doing@page@targets%
+      {\pdfdest name{#1} xyz}%
+    \fi%
+  }
+  \let\py@OldLabel=\label
+  \renewcommand{\label}[1]{%
+    \py@OldLabel{#1}%
+    \py@target{label-#1}%
+  }
+  % This stuff adds a page# destination to every PDF page, where # is three
+  % digits wide, padded with leading zeros.  This doesn't really help with
+  % the frontmatter, but does fine with the body.
+  %
+  % This is *heavily* based on the hyperref package.
+  %
+  \def\@begindvi{%
+    \unvbox \@begindvibox
+    \@hyperfixhead
+  }
+  \def\@hyperfixhead{%
+   \let\H@old@thehead\@thehead
+       \global\def\@foo{\py@target{page\py@pageno}}%
+     \expandafter\ifx\expandafter\@empty\H@old@thehead
+       \def\H@old@thehead{\hfil}\fi
+    \def\@thehead{\@foo\relax\H@old@thehead}%
+  }
+\fi\fi
+
+% Increase printable page size (copied from fullpage.sty)
+\topmargin 0pt
+\advance \topmargin by -\headheight
+\advance \topmargin by -\headsep
+
+% attempt to work a little better for A4 users
+\textheight \paperheight
+\advance\textheight by -2in
+
+\oddsidemargin 0pt
+\evensidemargin 0pt
+%\evensidemargin -.25in  % for ``manual size'' documents
+\marginparwidth 0.5in
+
+\textwidth \paperwidth
+\advance\textwidth by -2in
+
+
+% Style parameters and macros used by most documents here
+\raggedbottom
+\sloppy
+\parindent = 0mm
+\parskip = 2mm
+\hbadness = 5000                % don't print trivial gripes
+
+\pagestyle{empty}               % start this way; change for
+\pagenumbering{roman}           % ToC & chapters
+
+% Use this to set the font family for headers and other decor:
+\newcommand{\py@HeaderFamily}{\sffamily}
+
+% Set up abstract ways to get the normal and smaller font sizes that
+% work even in footnote context.
+\newif\ifpy@infootnote \py@infootnotefalse
+\let\py@oldmakefntext\@makefntext
+\def\@makefntext#1{%
+  \bgroup%
+    \py@infootnotetrue
+    \py@oldmakefntext{#1}%
+  \egroup%
+}
+\def\py@defaultsize{%
+  \ifpy@infootnote\footnotesize\else\normalsize\fi%
+}
+\def\py@smallsize{%
+  \ifpy@infootnote\scriptsize\else\small\fi%
+}
+
+% Redefine the 'normal' header/footer style when using "fancyhdr" package:
+\@ifundefined{fancyhf}{}{
+  % Use \pagestyle{normal} as the primary pagestyle for text.
+  \fancypagestyle{normal}{
+    \fancyhf{}
+    \fancyfoot[LE,RO]{{\py@HeaderFamily\thepage}}
+    \fancyfoot[LO]{{\py@HeaderFamily\nouppercase{\rightmark}}}
+    \fancyfoot[RE]{{\py@HeaderFamily\nouppercase{\leftmark}}}
+    \renewcommand{\headrulewidth}{0pt}
+    \renewcommand{\footrulewidth}{0.4pt}
+  }
+  % Update the plain style so we get the page number & footer line,
+  % but not a chapter or section title.  This is to keep the first
+  % page of a chapter and the blank page between chapters `clean.'
+  \fancypagestyle{plain}{
+    \fancyhf{}
+    \fancyfoot[LE,RO]{{\py@HeaderFamily\thepage}}
+    \renewcommand{\headrulewidth}{0pt}
+    \renewcommand{\footrulewidth}{0.4pt}
+  }
+  % Redefine \cleardoublepage so that the blank page between chapters
+  % gets the plain style and not the fancy style.  This is described
+  % in the documentation for the fancyhdr package by Piet von Oostrum.
+  \@ifundefined{chapter}{}{
+    \renewcommand{\cleardoublepage}{
+      \clearpage\if@openright \ifodd\c@page\else
+      \hbox{}
+      \thispagestyle{plain}
+      \newpage
+      \if@twocolumn\hbox{}\newpage\fi\fi\fi
+    }
+  }
+}
+
+% This sets up the {verbatim} environment to be indented and a minipage,
+% and to have all the other mostly nice properties that we want for
+% code samples.
+
+\let\py@OldVerbatim=\verbatim
+\let\py@OldEndVerbatim=\endverbatim
+\RequirePackage{verbatim}
+\let\py@OldVerbatimInput=\verbatiminput
+
+% Variable used by begin code command
+\newlength{\py@codewidth}
+
+\renewcommand{\verbatim}{%
+  \setlength{\parindent}{1cm}%
+  % Calculate the text width for the minipage:
+  \setlength{\py@codewidth}{\linewidth}%
+  \addtolength{\py@codewidth}{-\parindent}%
+  %
+  \par\indent%
+  \begin{minipage}[t]{\py@codewidth}%
+    \small%
+    \py@OldVerbatim%
+}
+\renewcommand{\endverbatim}{%
+    \py@OldEndVerbatim%
+  \end{minipage}%
+}
+\renewcommand{\verbatiminput}[1]{%
+  {\setlength{\parindent}{1cm}%
+   % Calculate the text width for the minipage:
+   \setlength{\py@codewidth}{\linewidth}%
+   \addtolength{\py@codewidth}{-\parindent}%
+   %
+   \small%
+   \begin{list}{}{\setlength{\leftmargin}{1cm}}
+     \item%
+     \py@OldVerbatimInput{#1}%
+   \end{list}
+  }%
+}
+
+% This does a similar thing for the {alltt} environment:
+\RequirePackage{alltt}
+\let\py@OldAllTT=\alltt
+\let\py@OldEndAllTT=\endalltt
+
+\renewcommand{\alltt}{%
+  \setlength{\parindent}{1cm}%
+  % Calculate the text width for the minipage:
+  \setlength{\py@codewidth}{\linewidth}%
+  \addtolength{\py@codewidth}{-\parindent}%
+  \let\e=\textbackslash%
+  %
+  \par\indent%
+  \begin{minipage}[t]{\py@codewidth}%
+    \small%
+    \py@OldAllTT%
+}
+\renewcommand{\endalltt}{%
+    \py@OldEndAllTT%
+  \end{minipage}%
+}
+
+
+\newcommand{\py@modulebadkey}{{--just-some-junk--}}
+
+
+%%  Lots of index-entry generation support.
+
+% Command to wrap around stuff that refers to function / module /
+% attribute names  in the index.  Default behavior: like \code{}.  To
+% just keep the index entries in the roman font, uncomment the second
+% definition; it matches O'Reilly style more.
+%
+\newcommand{\py@idxcode}[1]{\texttt{#1}}
+%\renewcommand{\py@idxcode}[1]{#1}
+
+% Command to generate two index entries (using subentries)
+\newcommand{\indexii}[2]{\index{#1!#2}\index{#2!#1}}
+
+% And three entries (using only one level of subentries)
+\newcommand{\indexiii}[3]{\index{#1!#2 #3}\index{#2!#3, #1}\index{#3!#1 #2}}
+
+% And four (again, using only one level of subentries)
+\newcommand{\indexiv}[4]{
+\index{#1!#2 #3 #4}
+\index{#2!#3 #4, #1}
+\index{#3!#4, #1 #2}
+\index{#4!#1 #2 #3}
+}
+
+% Command to generate a reference to a function, statement, keyword,
+% operator.
+\newcommand{\kwindex}[1]{\indexii{keyword}{#1@{\py@idxcode{#1}}}}
+\newcommand{\stindex}[1]{\indexii{statement}{#1@{\py@idxcode{#1}}}}
+\newcommand{\opindex}[1]{\indexii{operator}{#1@{\py@idxcode{#1}}}}
+\newcommand{\exindex}[1]{\indexii{exception}{#1@{\py@idxcode{#1}}}}
+\newcommand{\obindex}[1]{\indexii{object}{#1}}
+\newcommand{\bifuncindex}[1]{%
+  \index{#1@{\py@idxcode{#1()}} (built-in function)}}
+
+% Add an index entry for a module
+\newcommand{\py@refmodule}[2]{\index{#1@{\py@idxcode{#1}} (#2module)}}
+\newcommand{\refmodindex}[1]{\py@refmodule{#1}{}}
+\newcommand{\refbimodindex}[1]{\py@refmodule{#1}{built-in }}
+\newcommand{\refexmodindex}[1]{\py@refmodule{#1}{extension }}
+\newcommand{\refstmodindex}[1]{\py@refmodule{#1}{standard }}
+
+% Refer to a module's documentation using a hyperlink of the module's
+% name, at least if we're building PDF:
+\ifpdf
+  \newcommand{\refmodule}[2][\py@modulebadkey]{%
+    \ifx\py@modulebadkey#1\def\py@modulekey{#2}\else\def\py@modulekey{#1}\fi%
+    \py@linkToName{label-module-\py@modulekey}{\module{#2}}%
+  }
+\else
+  \newcommand{\refmodule}[2][\py@modulebadkey]{\module{#2}}
+\fi
+
+% support for the module index
+\newif\ifpy@UseModuleIndex
+\py@UseModuleIndexfalse
+
+\newcommand{\makemodindex}{
+  \newwrite\modindexfile
+  \openout\modindexfile=mod\jobname.idx
+  \py@UseModuleIndextrue
+}
+
+% Add the defining entry for a module
+\newcommand{\py@modindex}[2]{%
+  \renewcommand{\py@thismodule}{#1}
+  \setindexsubitem{(in module #1)}%
+  \index{#1@{\py@idxcode{#1}} (#2module)|textbf}%
+  \ifpy@UseModuleIndex%
+    \@ifundefined{py@modplat@\py@thismodulekey}{
+      \write\modindexfile{\protect\indexentry{#1@{\texttt{#1}}}{\thepage}}%
+    }{\write\modindexfile{\protect\indexentry{#1@{\texttt{#1} %
+        \emph{(\py@platformof[\py@thismodulekey]{})}}}{\thepage}}%
+    }
+  \fi%
+}
+
+% *** XXX *** THE NEXT FOUR MACROS ARE NOW OBSOLETE !!! ***
+
+% built-in & Python modules in the main distribution
+\newcommand{\bimodindex}[1]{\py@modindex{#1}{built-in }%
+  \typeout{*** MACRO bimodindex IS OBSOLETE -- USE declaremodule INSTEAD!}}
+\newcommand{\stmodindex}[1]{\py@modindex{#1}{standard }%
+  \typeout{*** MACRO stmodindex IS OBSOLETE -- USE declaremodule INSTEAD!}}
+
+% Python & extension modules outside the main distribution
+\newcommand{\modindex}[1]{\py@modindex{#1}{}%
+  \typeout{*** MACRO modindex IS OBSOLETE -- USE declaremodule INSTEAD!}}
+\newcommand{\exmodindex}[1]{\py@modindex{#1}{extension }%
+  \typeout{*** MACRO exmodindex IS OBSOLETE -- USE declaremodule INSTEAD!}}
+
+% Additional string for an index entry
+\newif\ifpy@usingsubitem\py@usingsubitemfalse
+\newcommand{\py@indexsubitem}{}
+\newcommand{\setindexsubitem}[1]{\renewcommand{\py@indexsubitem}{ #1}%
+                                 \py@usingsubitemtrue}
+\newcommand{\ttindex}[1]{%
+  \ifpy@usingsubitem
+    \index{#1@{\py@idxcode{#1}}\py@indexsubitem}%
+  \else%
+    \index{#1@{\py@idxcode{#1}}}%
+  \fi%
+}
+\newcommand{\withsubitem}[2]{%
+  \begingroup%
+    \def\ttindex##1{\index{##1@{\py@idxcode{##1}} #1}}%
+    #2%
+  \endgroup%
+}
+
+
+% Module synopsis processing -----------------------------------------------
+%
+\newcommand{\py@thisclass}{}
+\newcommand{\py@thismodule}{}
+\newcommand{\py@thismodulekey}{}
+\newcommand{\py@thismoduletype}{}
+
+\newcommand{\py@standardIndexModule}[1]{\py@modindex{#1}{standard }}
+\newcommand{\py@builtinIndexModule}[1]{\py@modindex{#1}{built-in }}
+\newcommand{\py@extensionIndexModule}[1]{\py@modindex{#1}{extension }}
+\newcommand{\py@IndexModule}[1]{\py@modindex{#1}{}}
+
+\newif\ifpy@HaveModSynopsis       \py@HaveModSynopsisfalse
+\newif\ifpy@ModSynopsisFileIsOpen \py@ModSynopsisFileIsOpenfalse
+\newif\ifpy@HaveModPlatform       \py@HaveModPlatformfalse
+
+% \declaremodule[key]{type}{name}
+\newcommand{\declaremodule}[3][\py@modulebadkey]{
+  \py@openModSynopsisFile
+  \renewcommand{\py@thismoduletype}{#2}
+  \ifx\py@modulebadkey#1
+    \renewcommand{\py@thismodulekey}{#3}
+  \else
+    \renewcommand{\py@thismodulekey}{#1}
+  \fi
+  \@ifundefined{py@#2IndexModule}{%
+    \typeout{*** MACRO declaremodule called with unknown module type: `#2'}
+    \py@IndexModule{#3}%
+  }{%
+    \csname py@#2IndexModule\endcsname{#3}%
+  }
+  \label{module-\py@thismodulekey}
+}
+\newif\ifpy@ModPlatformFileIsOpen \py@ModPlatformFileIsOpenfalse
+\newcommand{\py@ModPlatformFilename}{\jobname.pla}
+\newcommand{\platform}[1]{
+  \ifpy@ModPlatformFileIsOpen\else
+    \newwrite\py@ModPlatformFile
+    \openout\py@ModPlatformFile=\py@ModPlatformFilename
+    \py@ModPlatformFileIsOpentrue
+  \fi
+}
+\InputIfFileExists{\jobname.pla}{}{}
+\newcommand{\py@platformof}[2][\py@modulebadkey]{%
+  \ifx\py@modulebadkey#1 \def\py@key{#2}%
+  \else \def\py@key{#1}%
+  \fi%
+  \csname py@modplat@\py@key\endcsname%
+}
+\newcommand{\ignorePlatformAnnotation}[1]{}
+
+% \moduleauthor{name}{email}
+\newcommand{\moduleauthor}[2]{}
+
+% \sectionauthor{name}{email}
+\newcommand{\sectionauthor}[2]{}
+
+
+\newcommand{\py@defsynopsis}{Module has no synopsis.}
+\newcommand{\py@modulesynopsis}{\py@defsynopsis}
+\newcommand{\modulesynopsis}[1]{
+  \py@HaveModSynopsistrue
+  \renewcommand{\py@modulesynopsis}{#1}
+}
+
+% define the file
+\newwrite\py@ModSynopsisFile
+
+% hacked from \addtocontents from latex.ltx:
+\long\def\py@writeModSynopsisFile#1{%
+  \protected@write\py@ModSynopsisFile%
+      {\let\label\@gobble \let\index\@gobble \let\glossary\@gobble}%
+      {\string#1}%
+}
+\newcommand{\py@closeModSynopsisFile}{
+  \ifpy@ModSynopsisFileIsOpen
+    \closeout\py@ModSynopsisFile
+    \py@ModSynopsisFileIsOpenfalse
+  \fi
+}
+\newcommand{\py@openModSynopsisFile}{
+  \ifpy@ModSynopsisFileIsOpen\else
+    \openout\py@ModSynopsisFile=\py@ModSynopsisFilename
+    \py@ModSynopsisFileIsOpentrue
+  \fi
+}
+
+\newcommand{\py@ProcessModSynopsis}{
+  \ifpy@HaveModSynopsis
+    \py@writeModSynopsisFile{\modulesynopsis%
+      {\py@thismodulekey}{\py@thismodule}%
+      {\py@thismoduletype}{\py@modulesynopsis}}%
+    \py@HaveModSynopsisfalse
+  \fi
+  \renewcommand{\py@modulesynopsis}{\py@defsynopsis}
+}
+\AtEndDocument{\py@ProcessModSynopsis\py@closeModSynopsisFile}
+
+
+\long\def\py@writeModPlatformFile#1{%
+  \protected@write\py@ModPlatformFile%
+    {\let\label\@gobble \let\index\@gobble \let\glossary\@gobble}%
+    {\string#1}%
+}
+
+
+\newcommand{\localmoduletable}{
+  \IfFileExists{\py@ModSynopsisFilename}{
+    \begin{synopsistable}
+      \input{\py@ModSynopsisFilename}
+    \end{synopsistable}
+  }{}
+}
+
+\ifpdf
+  \newcommand{\py@ModSynopsisSummary}[4]{%
+    \py@linkToName{label-module-#1}{\bfcode{#2}} & #4\\
+  }
+\else
+  \newcommand{\py@ModSynopsisSummary}[4]{\bfcode{#2} & #4\\}
+\fi
+\newenvironment{synopsistable}{
+  % key, name, type, synopsis
+  \let\modulesynopsis=\py@ModSynopsisSummary
+  \begin{tabular}{ll}
+}{
+  \end{tabular}
+}
+%
+% --------------------------------------------------------------------------
+
+
+\newcommand{\py@reset}{
+  \py@usingsubitemfalse
+  \py@ProcessModSynopsis
+  \renewcommand{\py@thisclass}{}
+  \renewcommand{\py@thismodule}{}
+  \renewcommand{\py@thismodulekey}{}
+  \renewcommand{\py@thismoduletype}{}
+}
+
+% Augment the sectioning commands used to get our own font family in place,
+% and reset some internal data items:
+\renewcommand{\section}{\py@reset%
+                        \@startsection{section}{1}{\z@}%
+                                    {-3.5ex \@plus -1ex \@minus -.2ex}%
+                                    {2.3ex \@plus.2ex}%
+                                    {\reset@font\Large\py@HeaderFamily}}
+\renewcommand{\subsection}{\@startsection{subsection}{2}{\z@}%
+                                    {-3.25ex\@plus -1ex \@minus -.2ex}%
+                                    {1.5ex \@plus .2ex}%
+                                    {\reset@font\large\py@HeaderFamily}}
+\renewcommand{\subsubsection}{\@startsection{subsubsection}{3}{\z@}%
+                                    {-3.25ex\@plus -1ex \@minus -.2ex}%
+                                    {1.5ex \@plus .2ex}%
+                                    {\reset@font\normalsize\py@HeaderFamily}}
+\renewcommand{\paragraph}{\@startsection{paragraph}{4}{\z@}%
+                                    {3.25ex \@plus1ex \@minus.2ex}%
+                                    {-1em}%
+                                    {\reset@font\normalsize\py@HeaderFamily}}
+\renewcommand{\subparagraph}{\@startsection{subparagraph}{5}{\parindent}%
+                                    {3.25ex \@plus1ex \@minus .2ex}%
+                                    {-1em}%
+                                    {\reset@font\normalsize\py@HeaderFamily}}
+
+
+% Now for a lot of semantically-loaded environments that do a ton of magical
+% things to get the right formatting and index entries for the stuff in
+% Python modules and C API.
+
+
+% {fulllineitems} is used in one place in libregex.tex, but is really for
+% internal use in this file.
+%
+\newcommand{\py@itemnewline}[1]{%
+  \@tempdima\linewidth%
+  \advance\@tempdima \leftmargin\makebox[\@tempdima][l]{#1}%
+}
+
+\newenvironment{fulllineitems}{
+  \begin{list}{}{\labelwidth \leftmargin \labelsep 0pt
+                 \rightmargin 0pt \topsep -\parskip \partopsep \parskip
+                 \itemsep -\parsep
+                 \let\makelabel=\py@itemnewline}
+}{\end{list}}
+
+% \optional is mostly for use in the arguments parameters to the various
+% {*desc} environments defined below, but may be used elsewhere.  Known to
+% be used in the debugger chapter.
+%
+% Typical usage:
+%
+%     \begin{funcdesc}{myfunc}{reqparm\optional{, optparm}}
+%                                    ^^^       ^^^
+%                          No space here       No space here
+%
+% When a function has multiple optional parameters, \optional should be
+% nested, not chained.  This is right:
+%
+%     \begin{funcdesc}{myfunc}{\optional{parm1\optional{, parm2}}}
+%
+\let\py@badkey=\@undefined
+
+\newcommand{\optional}[1]{%
+  {\textnormal{\Large[}}{#1}\hspace{0.5mm}{\textnormal{\Large]}}}
+
+% This can be used when a function or method accepts an varying number 
+% of arguments, such as by using the *args syntax in the parameter list.
+\newcommand{\py@moreargs}{...}
+
+% This can be used when you don't want to document the parameters to a 
+% function or method, but simply state that it's an alias for
+% something else.
+\newcommand{\py@unspecified}{...}
+
+
+\newlength{\py@argswidth}
+\newcommand{\py@sigparams}[1]{%
+  \parbox[t]{\py@argswidth}{\py@varvars{#1}\code{)}}}
+\newcommand{\py@sigline}[2]{%
+  \settowidth{\py@argswidth}{#1\code{(}}%
+  \addtolength{\py@argswidth}{-2\py@argswidth}%
+  \addtolength{\py@argswidth}{\textwidth}%
+  \item[#1\code{(}\py@sigparams{#2}]}
+
+% C functions ------------------------------------------------------------
+% \begin{cfuncdesc}[refcount]{type}{name}{arglist}
+% Note that the [refcount] slot should only be filled in by
+% tools/anno-api.py; it pulls the value from the refcounts database.
+\newcommand{\cfuncline}[3]{
+  \py@sigline{\code{#1 \bfcode{#2}}}{#3}%
+  \index{#2@{\py@idxcode{#2()}}}
+}
+\newenvironment{cfuncdesc}[4][\py@badkey]{
+  \begin{fulllineitems}
+    \cfuncline{#2}{#3}{#4}
+    \ifx#1\@undefined\else%
+      \emph{Return value: \textbf{#1}.}\\
+    \fi
+}{\end{fulllineitems}}
+
+% C variables ------------------------------------------------------------
+% \begin{cvardesc}{type}{name}
+\newenvironment{cvardesc}[2]{
+  \begin{fulllineitems}
+    \item[\code{#1 \bfcode{#2}}\index{#2@{\py@idxcode{#2}}}]
+}{\end{fulllineitems}}
+
+% C data types -----------------------------------------------------------
+% \begin{ctypedesc}[index name]{typedef name}
+\newenvironment{ctypedesc}[2][\py@badkey]{
+  \begin{fulllineitems}
+    \item[\bfcode{#2}%
+    \ifx#1\@undefined%
+      \index{#2@{\py@idxcode{#2}} (C type)}
+    \else%
+      \index{#2@{\py@idxcode{#1}} (C type)}
+    \fi]
+}{\end{fulllineitems}}
+
+% C type fields ----------------------------------------------------------
+% \begin{cmemberdesc}{container type}{ctype}{membername}
+\newcommand{\cmemberline}[3]{
+  \item[\code{#2 \bfcode{#3}}]
+  \index{#3@{\py@idxcode{#3}} (#1 member)}
+}
+\newenvironment{cmemberdesc}[3]{
+  \begin{fulllineitems}
+    \cmemberline{#1}{#2}{#3}
+}{\end{fulllineitems}}
+
+% Funky macros -----------------------------------------------------------
+% \begin{csimplemacrodesc}{name}
+% -- "simple" because it has no args; NOT for constant definitions!
+\newenvironment{csimplemacrodesc}[1]{
+  \begin{fulllineitems}
+    \item[\bfcode{#1}\index{#1@{\py@idxcode{#1}} (macro)}]
+}{\end{fulllineitems}}
+
+% simple functions (not methods) -----------------------------------------
+% \begin{funcdesc}{name}{args}
+\newcommand{\funcline}[2]{%
+  \funclineni{#1}{#2}%
+  \index{#1@{\py@idxcode{#1()}} (in module \py@thismodule)}}
+\newenvironment{funcdesc}[2]{
+  \begin{fulllineitems}
+    \funcline{#1}{#2}
+}{\end{fulllineitems}}
+
+% similar to {funcdesc}, but doesn't add to the index
+\newcommand{\funclineni}[2]{%
+  \py@sigline{\bfcode{#1}}{#2}}
+\newenvironment{funcdescni}[2]{
+  \begin{fulllineitems}
+    \funclineni{#1}{#2}
+}{\end{fulllineitems}}
+
+% classes ----------------------------------------------------------------
+% \begin{classdesc}{name}{constructor args}
+\newenvironment{classdesc}[2]{
+  % Using \renewcommand doesn't work for this, for unknown reasons:
+  \global\def\py@thisclass{#1}
+  \begin{fulllineitems}
+    \py@sigline{\strong{class }\bfcode{#1}}{#2}%
+    \index{#1@{\py@idxcode{#1}} (class in \py@thismodule)}
+}{\end{fulllineitems}}
+
+% \begin{classdesc*}{name}
+\newenvironment{classdesc*}[1]{
+  % Using \renewcommand doesn't work for this, for unknown reasons:
+  \global\def\py@thisclass{#1}
+  \begin{fulllineitems}
+    \item[\strong{class }\code{\bfcode{#1}}%
+      \index{#1@{\py@idxcode{#1}} (class in \py@thismodule)}]
+}{\end{fulllineitems}}
+
+% \begin{excclassdesc}{name}{constructor args}
+% but indexes as an exception
+\newenvironment{excclassdesc}[2]{
+  % Using \renewcommand doesn't work for this, for unknown reasons:
+  \global\def\py@thisclass{#1}
+  \begin{fulllineitems}
+    \py@sigline{\strong{exception }\bfcode{#1}}{#2}%
+    \index{#1@{\py@idxcode{#1}} (exception in \py@thismodule)}
+}{\end{fulllineitems}}
+
+% There is no corresponding {excclassdesc*} environment.  To describe
+% a class exception without parameters, use the {excdesc} environment.
+
+
+\let\py@classbadkey=\@undefined
+
+% object method ----------------------------------------------------------
+% \begin{methoddesc}[classname]{methodname}{args}
+\newcommand{\methodline}[3][\@undefined]{
+  \methodlineni{#2}{#3}
+  \ifx#1\@undefined
+    \index{#2@{\py@idxcode{#2()}} (\py@thisclass\ method)}
+  \else
+    \index{#2@{\py@idxcode{#2()}} (#1 method)}
+  \fi
+}
+\newenvironment{methoddesc}[3][\@undefined]{
+  \begin{fulllineitems}
+    \ifx#1\@undefined
+      \methodline{#2}{#3}
+    \else
+      \def\py@thisclass{#1}
+      \methodline{#2}{#3}
+    \fi
+}{\end{fulllineitems}}
+
+% similar to {methoddesc}, but doesn't add to the index
+% (never actually uses the optional argument)
+\newcommand{\methodlineni}[3][\py@classbadkey]{%
+  \py@sigline{\bfcode{#2}}{#3}}
+\newenvironment{methoddescni}[3][\py@classbadkey]{
+  \begin{fulllineitems}
+    \methodlineni{#2}{#3}
+}{\end{fulllineitems}}
+
+% object data attribute --------------------------------------------------
+% \begin{memberdesc}[classname]{membername}
+\newcommand{\memberline}[2][\py@classbadkey]{%
+  \ifx#1\@undefined
+    \memberlineni{#2}
+    \index{#2@{\py@idxcode{#2}} (\py@thisclass\ attribute)}
+  \else
+    \memberlineni{#2}
+    \index{#2@{\py@idxcode{#2}} (#1 attribute)}
+  \fi
+}
+\newenvironment{memberdesc}[2][\py@classbadkey]{
+  \begin{fulllineitems}
+    \ifx#1\@undefined
+      \memberline{#2}
+    \else
+      \def\py@thisclass{#1}
+      \memberline{#2}
+    \fi
+}{\end{fulllineitems}}
+
+% similar to {memberdesc}, but doesn't add to the index
+% (never actually uses the optional argument)
+\newcommand{\memberlineni}[2][\py@classbadkey]{\item[\bfcode{#2}]}
+\newenvironment{memberdescni}[2][\py@classbadkey]{
+  \begin{fulllineitems}
+    \memberlineni{#2}
+}{\end{fulllineitems}}
+
+% For exceptions: --------------------------------------------------------
+% \begin{excdesc}{name}
+%  -- for constructor information, use excclassdesc instead
+\newenvironment{excdesc}[1]{
+  \begin{fulllineitems}
+    \item[\strong{exception }\bfcode{#1}%
+          \index{#1@{\py@idxcode{#1}} (exception in \py@thismodule)}]
+}{\end{fulllineitems}}
+
+% Module data or constants: ----------------------------------------------
+% \begin{datadesc}{name}
+\newcommand{\dataline}[1]{%
+  \datalineni{#1}\index{#1@{\py@idxcode{#1}} (data in \py@thismodule)}}
+\newenvironment{datadesc}[1]{
+  \begin{fulllineitems}
+    \dataline{#1}
+}{\end{fulllineitems}}
+
+% similar to {datadesc}, but doesn't add to the index
+\newcommand{\datalineni}[1]{\item[\bfcode{#1}]\nopagebreak}
+\newenvironment{datadescni}[1]{
+  \begin{fulllineitems}
+    \datalineni{#1}
+}{\end{fulllineitems}}
+
+% bytecode instruction ---------------------------------------------------
+% \begin{opcodedesc}{name}{var}
+% -- {var} may be {}
+\newenvironment{opcodedesc}[2]{
+  \begin{fulllineitems}
+    \item[\bfcode{#1}\quad\var{#2}]
+}{\end{fulllineitems}}
+
+
+\newcommand{\nodename}[1]{\label{#1}}
+
+% For these commands, use \command{} to get the typography right, not 
+% {\command}.  This works better with the texinfo translation.
+\newcommand{\ABC}{{\sc abc}}
+\newcommand{\UNIX}{{\sc Unix}}
+\newcommand{\POSIX}{POSIX}
+\newcommand{\ASCII}{{\sc ascii}}
+\newcommand{\Cpp}{C\protect\raisebox{.18ex}{++}}
+\newcommand{\C}{C}
+\newcommand{\EOF}{{\sc eof}}
+\newcommand{\NULL}{\constant{NULL}}
+\newcommand{\infinity}{\ensuremath{\infty}}
+\newcommand{\plusminus}{\ensuremath{\pm}}
+
+% \guilabel{Start}
+\newcommand{\guilabel}[1]{\textsf{#1}}
+% \menuselection{Start \sub Programs \sub Python}
+\newcommand{\menuselection}[1]{\guilabel{{\def\sub{ \ensuremath{>} }#1}}}
+
+% Also for consistency: spell Python "Python", not "python"!
+
+% code is the most difficult one...
+\newcommand{\code}[1]{\textrm{\@vobeyspaces\@noligs\def\{{\char`\{}\def\}{\char`\}}\def\~{\char`\~}\def\^{\char`\^}\def\e{\char`\\}\def\${\char`\$}\def\#{\char`\#}\def\&{\char`\&}\def\%{\char`\%}%
+\texttt{#1}}}
+
+\newcommand{\bfcode}[1]{\code{\bfseries#1}} % bold-faced code font
+\newcommand{\csimplemacro}[1]{\code{#1}}
+\newcommand{\kbd}[1]{\code{#1}}
+\newcommand{\samp}[1]{`\code{#1}'}
+\newcommand{\var}[1]{%
+  \ifmmode%
+    \hbox{\py@defaultsize\textrm{\textit{#1\/}}}%
+  \else%
+    \py@defaultsize\textrm{\textit{#1\/}}%
+  \fi%
+}
+\renewcommand{\emph}[1]{{\em #1}}
+\newcommand{\dfn}[1]{\emph{#1}}
+\newcommand{\strong}[1]{{\bf #1}}
+% let's experiment with a new font:
+\newcommand{\file}[1]{`\filenq{#1}'}
+\newcommand{\filenq}[1]{{\py@smallsize\textsf{\let\e=\textbackslash#1}}}
+
+% Use this def/redef approach for \url{} since hyperref defined this already,
+% but only if we actually used hyperref:
+\ifpdf
+  \newcommand{\url}[1]{{%
+    \py@pdfstartlink attr{/Border [0 0 0]} user{/S /URI /URI (#1)}%
+    \py@LinkColor%                              color of the link text
+    \py@smallsize\sf #1%
+    \py@NormalColor%                    Turn it back off; these are declarative
+    \pdfendlink}%                       and don't appear bound to the current
+  }%                                    formatting "box".
+\else
+  \newcommand{\url}[1]{\mbox{\py@smallsize\textsf{#1}}}
+\fi
+\newcommand{\email}[1]{{\py@smallsize\textsf{#1}}}
+\newcommand{\newsgroup}[1]{{\py@smallsize\textsf{#1}}}
+
+\newcommand{\py@varvars}[1]{{%
+  {\let\unspecified=\py@unspecified%
+   \let\moreargs=\py@moreargs%
+   \var{#1}}}}
+
+% I'd really like to get rid of this!
+\newif\iftexi\texifalse
+
+% This is used to get l2h to put the copyright and abstract on
+% a separate HTML page.
+\newif\ifhtml\htmlfalse
+
+
+% These should be used for all references to identifiers which are
+% used to refer to instances of specific language constructs.  See the
+% names for specific semantic assignments.
+%
+% For now, don't do anything really fancy with them; just use them as
+% logical markup.  This might change in the future.
+%
+\newcommand{\module}[1]{\texttt{#1}}
+\newcommand{\keyword}[1]{\texttt{#1}}
+\newcommand{\exception}[1]{\texttt{#1}}
+\newcommand{\class}[1]{\texttt{#1}}
+\newcommand{\function}[1]{\texttt{#1}}
+\newcommand{\member}[1]{\texttt{#1}}
+\newcommand{\method}[1]{\texttt{#1}}
+
+\newcommand{\pytype}[1]{#1}             % built-in Python type
+
+\newcommand{\cfunction}[1]{\texttt{#1}}
+\newcommand{\ctype}[1]{\texttt{#1}}     % C struct or typedef name
+\newcommand{\cdata}[1]{\texttt{#1}}     % C variable, typically global
+
+\newcommand{\mailheader}[1]{{\py@smallsize\textsf{#1:}}}
+\newcommand{\mimetype}[1]{{\py@smallsize\textsf{#1}}}
+% The \! is a "negative thin space" in math mode.
+\newcommand{\regexp}[1]{%
+  {\tiny$^{^\lceil}\!\!$%
+   {\py@defaultsize\code{#1}}%
+   $\!\rfloor\!$%
+  }}
+\newcommand{\envvar}[1]{%
+  #1%
+  \index{#1}%
+  \index{environment variables!{#1}}%
+}
+\newcommand{\makevar}[1]{#1}            % variable in a Makefile
+\newcommand{\character}[1]{\samp{#1}}
+
+% constants defined in Python modules or C headers, not language constants:
+\newcommand{\constant}[1]{\code{#1}}    % manifest constant, not syntactic
+
+\newcommand{\manpage}[2]{{\emph{#1}(#2)}}
+\newcommand{\pep}[1]{PEP #1\index{Python Enhancement Proposals!PEP #1}}
+\newcommand{\rfc}[1]{RFC #1\index{RFC!RFC #1}}
+\newcommand{\program}[1]{\strong{#1}}
+\newcommand{\programopt}[1]{\strong{#1}}
+% Note that \longprogramopt provides the '--'!
+\newcommand{\longprogramopt}[1]{\strong{-{}-#1}}
+
+% \ulink{link text}{URL}
+\ifpdf
+  \newcommand{\ulink}[2]{{%
+    % For PDF, we *should* only generate a link when the URL is absolute.
+    \py@pdfstartlink attr{/Border [0 0 0]} user{/S /URI /URI (#2)}%
+    \py@LinkColor%                              color of the link text
+    #1%
+    \py@NormalColor%                    Turn it back off; these are declarative
+    \pdfendlink}%                       and don't appear bound to the current
+  }%                                    formatting "box".
+\else
+  \newcommand{\ulink}[2]{#1}
+\fi
+
+% cited titles:  \citetitle{Title of Work}
+%       online:  \citetitle[url-to-resource]{Title of Work}
+\ifpdf
+  \newcommand{\citetitle}[2][\py@modulebadkey]{%
+    \ifx\py@modulebadkey#1\emph{#2}\else\ulink{\emph{#2}}{#1}\fi%
+  }
+\else
+  \newcommand{\citetitle}[2][URL]{\emph{#2}}
+\fi
+
+
+
+% This version is being checked in for the historical record; it shows
+% how I've managed to get some aspects of this to work.  It will not
+% be used in practice, so a subsequent revision will change things
+% again.  This version has problems, but shows how to do something
+% that proved more tedious than I'd expected, so I don't want to lose
+% the example completely.
+%
+\newcommand{\grammartoken}[1]{\texttt{#1}}
+\newenvironment{productionlist}[1][\py@badkey]{
+  \def\optional##1{{\Large[}##1{\Large]}}
+  \def\production##1##2{\code{##1}&::=&\code{##2}\\}
+  \def\productioncont##1{& &\code{##1}\\}
+  \def\token##1{##1}
+  \let\grammartoken=\token
+  \parindent=2em
+  \indent
+  \begin{tabular}{lcl}
+}{%
+  \end{tabular}
+}
+
+\newlength{\py@noticelength}
+
+\newcommand{\py@heavybox}{
+  \setlength{\fboxrule}{2pt}
+  \setlength{\fboxsep}{7pt}
+  \setlength{\py@noticelength}{\linewidth}
+  \addtolength{\py@noticelength}{-2\fboxsep}
+  \addtolength{\py@noticelength}{-2\fboxrule}
+  \setlength{\shadowsize}{3pt}
+  \Sbox
+  \minipage{\py@noticelength}
+}
+\newcommand{\py@endheavybox}{
+  \endminipage
+  \endSbox
+  \fbox{\TheSbox}
+}
+
+% a 'note' is as plain as it gets:
+\newcommand{\py@noticelabel@note}{Note:}
+\newcommand{\py@noticestart@note}{}
+\newcommand{\py@noticeend@note}{}
+
+% a 'warning' gets more visible distinction:
+\newcommand{\py@noticelabel@warning}{Warning:}
+\newcommand{\py@noticestart@warning}{\py@heavybox}
+\newcommand{\py@noticeend@warning}{\py@endheavybox}
+
+\newenvironment{notice}[1][note]{
+  \def\py@noticetype{#1}
+  \csname py@noticestart@#1\endcsname
+  \par\strong{\csname py@noticelabel@#1\endcsname}
+}{\csname py@noticeend@\py@noticetype\endcsname}
+\newcommand{\note}[1]{\strong{\py@noticelabel@note} #1}
+\newcommand{\warning}[1]{\strong{\py@noticelabel@warning} #1}
+
+% Deprecation stuff.
+% Should be extended to allow an index / list of deprecated stuff.  But
+% there's a lot of stuff that needs to be done to make that automatable.
+%
+% First parameter is the release number that deprecates the feature, the
+% second is the action the should be taken by users of the feature.
+%
+% Example:
+%  \deprecated{1.5.1}{Use \method{frobnicate()} instead.}
+%
+\newcommand{\deprecated}[2]{%
+  \strong{Deprecated since release #1.}  #2\par}
+
+% New stuff.
+% This should be used to mark things which have been added to the
+% development tree but that aren't in the release, but are documented.
+% This allows release of documentation that already includes updated
+% descriptions.  Place at end of descriptor environment.
+%
+% Example:
+%  \versionadded{1.5.2}
+%  \versionchanged[short explanation]{2.0}
+%
+\newcommand{\versionadded}[2][\py@badkey]{%
+  \ifx#1\@undefined%
+    {  New in version #2.  }%
+  \else%
+    {  New in version #2:\ #1.  }%
+  \fi%
+}
+\newcommand{\versionchanged}[2][\py@badkey]{%
+  \ifx#1\@undefined%
+    {  Changed in version #2.  }%
+  \else%
+    {  Changed in version #2:\ #1.  }%
+  \fi%
+}
+
+
+% Tables.
+%
+\newenvironment{tableii}[4]{%
+  \begin{center}%
+    \def\lineii##1##2{\csname#2\endcsname{##1}&##2\\}%
+    \begin{tabular}{#1}\strong{#3}&\strong{#4} \\* \hline%
+}{%
+    \end{tabular}%
+  \end{center}%
+}
+
+\newenvironment{longtableii}[4]{%
+  \begin{center}%
+    \def\lineii##1##2{\csname#2\endcsname{##1}&##2\\}%
+    \begin{longtable}[c]{#1}\strong{#3}&\strong{#4} \\* \hline\endhead%
+}{%
+    \end{longtable}%
+  \end{center}%
+}
+
+\newenvironment{tableiii}[5]{%
+  \begin{center}%
+    \def\lineiii##1##2##3{\csname#2\endcsname{##1}&##2&##3\\}%
+    \begin{tabular}{#1}\strong{#3}&\strong{#4}&\strong{#5} \\%
+      \hline%
+}{%
+    \end{tabular}%
+  \end{center}%
+}
+
+\newenvironment{longtableiii}[5]{%
+  \begin{center}%
+    \def\lineiii##1##2##3{\csname#2\endcsname{##1}&##2&##3\\}%
+    \begin{longtable}[c]{#1}\strong{#3}&\strong{#4}&\strong{#5} \\%
+      \hline\endhead%
+}{%
+    \end{longtable}%
+  \end{center}%
+}
+
+\newenvironment{tableiv}[6]{%
+  \begin{center}%
+    \def\lineiv##1##2##3##4{\csname#2\endcsname{##1}&##2&##3&##4\\}%
+    \begin{tabular}{#1}\strong{#3}&\strong{#4}&\strong{#5}&\strong{#6} \\%
+      \hline%
+}{%
+    \end{tabular}%
+  \end{center}%
+}
+
+\newenvironment{longtableiv}[6]{%
+  \begin{center}%
+    \def\lineiv##1##2##3##4{\csname#2\endcsname{##1}&##2&##3&##4\\}%
+    \begin{longtable}[c]{#1}\strong{#3}&\strong{#4}&\strong{#5}&\strong{#6}%
+      \\%
+      \hline\endhead%
+}{%
+    \end{longtable}%
+  \end{center}%
+}
+
+\newenvironment{tablev}[7]{%
+  \begin{center}%
+    \def\linev##1##2##3##4##5{\csname#2\endcsname{##1}&##2&##3&##4&##5\\}%
+    \begin{tabular}{#1}\strong{#3}&\strong{#4}&\strong{#5}&\strong{#6}&\strong{#7} \\%
+      \hline%
+}{%
+    \end{tabular}%
+  \end{center}%
+}
+
+\newenvironment{longtablev}[7]{%
+  \begin{center}%
+    \def\linev##1##2##3##4##5{\csname#2\endcsname{##1}&##2&##3&##4&##5\\}%
+    \begin{longtable}[c]{#1}\strong{#3}&\strong{#4}&\strong{#5}&\strong{#6}&\strong{#7}%
+      \\%
+      \hline\endhead%
+}{%
+    \end{longtable}%
+  \end{center}%
+}
+
+% XXX Don't think we can use this yet, though it cleans up some
+% tedious markup.  There's no equivalent for the HTML transform yet,
+% and that needs to exist.  I don't know how to write it.
+%
+% This should really have something that makes it easier to bind a
+% table's ``Notes'' column and an associated tablenotes environment,
+% and generates the right magic for getting the numbers right in the
+% table.
+%
+% So this is quite incomplete.
+%
+\newcounter{py@tablenotescounter}
+\newenvironment{tablenotes}{%
+  \noindent Notes:
+  \par
+  \setcounter{py@tablenotescounter}{0}
+  \begin{list}{(\arabic{py@tablenotescounter})}%
+              {\usecounter{py@tablenotescounter}}
+}{\end{list}}
+
+
+% Cross-referencing (AMK, new impl. FLD)
+% Sample usage:
+%  \begin{seealso}
+%    \seemodule{rand}{Uniform random number generator.}; % Module xref
+%    \seetext{\emph{Encyclopedia Britannica}}.           % Ref to a book
+% 
+%    % A funky case: module name contains '_'; have to supply an optional key
+%    \seemodule[copyreg]{copy_reg}{Interface constructor registration for
+%                                  \module{pickle}.}
+%  \end{seealso}
+%
+% Note that the last parameter for \seemodule and \seetext should be complete
+% sentences and be terminated with the proper punctuation.
+
+\ifpdf
+  \newcommand{\py@seemodule}[3][\py@modulebadkey]{%
+    \par%
+    \ifx\py@modulebadkey#1\def\py@modulekey{#2}\else\def\py@modulekey{#1}\fi%
+    \begin{fulllineitems}
+      \item[\py@linkToName{label-module-\py@modulekey}{Module \module{#2}}
+            (section \ref{module-\py@modulekey}):]
+      #3
+    \end{fulllineitems}
+  }
+\else
+  \newcommand{\py@seemodule}[3][\py@modulebadkey]{%
+    \par%
+    \ifx\py@modulebadkey#1\def\py@modulekey{#2}\else\def\py@modulekey{#1}\fi%
+    \begin{fulllineitems}
+      \item[Module \module{#2} (section \ref{module-\py@modulekey}):]
+      #3
+    \end{fulllineitems}
+  }
+\fi
+
+% \seelink{url}{link text}{why it's interesting}
+\newcommand{\py@seelink}[3]{%
+  \par
+  \begin{fulllineitems}
+    \item[\ulink{#2}{#1}]
+    #3
+  \end{fulllineitems}
+}
+% \seetitle[url]{title}{why it's interesting}
+\newcommand{\py@seetitle}[3][\py@modulebadkey]{%
+  \par
+  \begin{fulllineitems}
+    \item[\citetitle{#2}]
+    \ifx\py@modulebadkey#1\else
+      \item[{\small{(\url{#1})}}]
+    \fi
+    #3
+  \end{fulllineitems}
+}
+% \seepep{number}{title}{why it's interesting}
+\newcommand{\py@seepep}[3]{%
+  \par%
+  \begin{fulllineitems}
+    \item[\pep{#1}, ``\emph{#2}'']
+    #3
+  \end{fulllineitems}
+}
+% \seerfc{number}{title}{why it's interesting}
+\newcommand{\py@seerfc}[3]{%
+  \par%
+  \begin{fulllineitems}
+    \item[\rfc{#1}, ``\emph{#2}'']
+    #3
+  \end{fulllineitems}
+}
+% \seeurl{url}{why it's interesting}
+\newcommand{\py@seeurl}[2]{%
+  \par%
+  \begin{fulllineitems}
+    \item[\url{#1}]
+    #2
+  \end{fulllineitems}
+}
+
+\newenvironment{seealso*}{
+  \par
+  \def\seetext##1{\par{##1}}
+  \let\seemodule=\py@seemodule
+  \let\seepep=\py@seepep
+  \let\seerfc=\py@seerfc
+  \let\seetitle=\py@seetitle
+  \let\seeurl=\py@seeurl
+  \let\seelink=\py@seelink
+}{\par}
+\newenvironment{seealso}{
+  \par
+  \strong{See Also:}
+  \par
+  \def\seetext##1{\par{##1}}
+  \let\seemodule=\py@seemodule
+  \let\seepep=\py@seepep
+  \let\seerfc=\py@seerfc
+  \let\seetitle=\py@seetitle
+  \let\seeurl=\py@seeurl
+  \let\seelink=\py@seelink
+}{\par}
+
+% Allow the Python release number to be specified independently of the
+% \date{}.  This allows the date to reflect the document's date and
+% release to specify the Python release that is documented.
+%
+\newcommand{\py@release}{}
+\newcommand{\version}{}
+\newcommand{\shortversion}{}
+\newcommand{\releaseinfo}{}
+\newcommand{\releasename}{Release}
+\newcommand{\release}[1]{%
+  \renewcommand{\py@release}{\releasename\space\version}%
+  \renewcommand{\version}{#1}}
+\newcommand{\setshortversion}[1]{%
+  \renewcommand{\shortversion}{#1}}
+\newcommand{\setreleaseinfo}[1]{%
+  \renewcommand{\releaseinfo}{#1}}
+
+% Allow specification of the author's address separately from the
+% author's name.  This can be used to format them differently, which
+% is a good thing.
+%
+\newcommand{\py@authoraddress}{}
+\newcommand{\authoraddress}[1]{\renewcommand{\py@authoraddress}{#1}}
+\let\developersaddress=\authoraddress
+\let\developer=\author
+\let\developers=\author
+
+% This sets up the fancy chapter headings that make the documents look
+% at least a little better than the usual LaTeX output.
+%
+\@ifundefined{ChTitleVar}{}{
+  \ChNameVar{\raggedleft\normalsize\py@HeaderFamily}
+  \ChNumVar{\raggedleft \bfseries\Large\py@HeaderFamily}
+  \ChTitleVar{\raggedleft \rm\Huge\py@HeaderFamily}
+  % This creates chapter heads without the leading \vspace*{}:
+  \def\@makechapterhead#1{%
+    {\parindent \z@ \raggedright \normalfont
+      \ifnum \c@secnumdepth >\m@ne
+        \DOCH
+      \fi
+      \interlinepenalty\@M
+      \DOTI{#1}
+    }
+  }
+}
+
+
+% Definition lists; requested by AMK for HOWTO documents.  Probably useful
+% elsewhere as well, so keep in in the general style support.
+%
+\newenvironment{definitions}{%
+  \begin{description}%
+  \def\term##1{\item[##1]\mbox{}\\*[0mm]}
+}{%
+  \end{description}%
+}
+
+% Tell TeX about pathological hyphenation cases:
+\hyphenation{Base-HTTP-Re-quest-Hand-ler}
Index: /anuga_core/documentation/requirements/requirements.txt
===================================================================
--- /anuga_core/documentation/requirements/requirements.txt	(revision 3574)
+++ /anuga_core/documentation/requirements/requirements.txt	(revision 3574)
@@ -0,0 +1,97 @@
+Requirements for the Storm Surge Model:
+-------------------------------------
+
+
+(So far these are merely questions, that should crystallise into a
+common view and a proper list of requirements).
+
+GENERAL:
+
+We are required to deliver a Single processor version of the Storm
+Surge hazard model, integrating the Storm Surge model, animation,
+pMesh, examples and a case study. This will be delivered on April 2005.
+
+How do we want users to be able to interact with this model?  What are
+the requirements of the user interface?  
+
+We have a current interface the consists of pmesh and its graphical 
+user interface as well as the pyvolution library (domain, 
+shallow_water and pmesh.mesh) - with each scenario 
+currently controlled by a short scripts.  
+What additional functionality do we need/want/desire in the 
+April deliverable?  Also, how do we want to change the current interfaces?
+
+If we gather these requirements and prioritise them it will clarify
+what should be implemented.
+
+
+REQUIREMENT QUESTIONS (Storm Surge):
+------------------------------------
+
+Scenarios:
+Please think up some scenarios a la
+1  "The software shall allow the user to run a simulation using a coarse grid,
+   then perform some local refinement of specific regions and then run again
+   iteratively until a suitable mesh has been developed."
+
+2  "The software shall then allow the user to increase the resolution
+   of the adapted mesh by a common factor such that the ratio between 
+   fine and course parts remains constant. 
+
+   
+How to set up a simulation:
+    The following components are required:
+	A triangular mesh (e.g. domain) detailing
+	  - location of vertices
+	Bed elevation, friction, stage and x, y momentum at vertices
+    or described by function inputting x and y.
+	Specific boundary conditions applied to various segments
+	Forcing terms
+	Various control parameters such as order
+
+   What else?
+   And how do we want to manage these components?
+
+   Should pmesh have the option of supplying the stage, bed
+   elevation and/or friction values?  How user friendly should this
+   be?  Currently there is a function which assumes the first
+   attribute is bed elevation, 2nd is stage and third is friction.
+   
+   Should the parameters of a boundary condition be able to be set in
+   pmesh?
+   
+   Should regional attributes from pmesh be able to change field
+   conditions and conserved quantities? How user friendly should this
+   be?
+   
+   Should pmesh show segment tag names to which a boundary object has
+   been attached?  I.e. should pmesh load a dictionary of boundary
+   objects indexed by tags, and show/let the user select the known
+   tags?  The tags would be words, rather than integers.
+   
+
+Data flow
+     How should data flow from initial datasets, 
+
+     E.g. 
+     Data -> cleaning -> preprocessing -> mesh generation -> 
+     application of boundary, initial conditions and forcing terms ->
+     Simulation (check pointing, parallelism) ->
+     Actions at every yield (e.g. save data, apply building impacts, viz) ->
+     
+     Visualise and post-process model data.
+
+     
+Other:
+     What is the need for casting boundary conditions and initial conditions 
+     in terms of height (h) as well as stage (w=z+h) -
+     stage being the conserved quantitity which can be set directly.
+
+     What is the need for setting initial conditions and boundary conditions 
+     as functions in terms of x and y?            
+
+Specifics:
+    
+    Output statistics about #volumes, min/max area/edgelengts, specified 
+    max_speed and derived minimal timestep.           
+     
Index: /anuga_core/documentation/requirements/thoughts.txt
===================================================================
--- /anuga_core/documentation/requirements/thoughts.txt	(revision 3574)
+++ /anuga_core/documentation/requirements/thoughts.txt	(revision 3574)
@@ -0,0 +1,76 @@
+QA: Have SMEC (and the likes) try the software for one of their projects 
+and ask them to comment on:
+
+  quality
+  performance (size and speed)
+  ease of installation
+  documentation
+  
+
+  NAME:  How about naming the whole thing  GANU or ANUGA  ?
+  
+  
+PROJECTS:  
+  
+One way of implementing parallelism would be through domain decomposition (DD).
+Perhaps we can work with someone with experience in DD of PDEs and once that 
+works, parallelise the code by having several sub-domains on each processor.
+
+
+Uncertainty modelling and MC simluations.
+
+Running a large simulation (Stress test): {Peter Row?) DONE (tsunamies)
+
+Momentum sink study. Scale, extent, 
+ map various copmpositions of structures to friction terms     
+  
+  
+Stephen: Look at domain decomposition algorithms with a view of 
+parallelising pyvolution
+
+
+Stephen: Timestepping to be controlled by error estimator.
+
+
+
+DESIGN PRINCIPLES (17/3/5) -  as agreed to by Duncan and Ole
+
+Objects shared across project should not precompute 
+structures upon initialisation unless they are used by all clients.
+Rather precompute on demand or split using inheritance.
+Pro: Good separation of concepts
+Con: It may be harder to find the right file
+
+Also, modules shared across project should not generally depend on other modules.
+
+
+
+Idea (ON 28/4/5):
+Allow set_quantity to take a .pts file as argument. That should use least_squares to populate the quantity.
+Furthermore use caching.py to assert whether this should be computed or read from cache.
+
+
+Use logger module as suggested by steve
+
+See also HUSK.txt in pyvolution
+
+
+Have the option of changing boundaries and forcing functions on the fly depnding on e.g. time or value of conserved quantities.
+
+
+PROJECT IDEAS (NOV 2005)
+
+GBR Effect on tsunami (Stephen may get student)
+Convection (Grad proposal 2005/2006, Ole)
+Momentum sink (Grad proposal 2005/2006, Duncan)
+Convergence study (Ole)
+VRML export (David Beard, Malcolm Nicoll)
+Proper installer
+Overcome 2GB NetCDF limit
+IO (data_manager) needs some TLC
+
+See also work program ideas 2005-2006
+
+How to get the same amount of smoothly from a large mesh to a small
+mesh. How does the alpha value get scaled?
+
Index: /anuga_core/documentation/requirements/underscore.sty
===================================================================
--- /anuga_core/documentation/requirements/underscore.sty	(revision 3574)
+++ /anuga_core/documentation/requirements/underscore.sty	(revision 3574)
@@ -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{|}~
Index: /anuga_core/documentation/requirements/update_anuga_requirements.py
===================================================================
--- /anuga_core/documentation/requirements/update_anuga_requirements.py	(revision 3574)
+++ /anuga_core/documentation/requirements/update_anuga_requirements.py	(revision 3574)
@@ -0,0 +1,48 @@
+#!/usr/bin/env python
+
+"""Update, compile and create PDF and HTML from LaTeX file
+
+This can for example be run from a cronjob:
+
+  crontab -e
+
+with content 
+
+SHELL=/bin/sh
+PATH=/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin:~/bin
+
+# m h dom mon dow command
+  42 *  *   *   *  ~/anuga/documentation/user_manual/update_anuga_user_manual.py > ~/anuga/documentation/user_manual/update_anuga.log
+#
+
+
+Note UNIX only
+ 
+"""
+
+
+import os
+
+
+anugapath = os.path.expanduser('~/anuga/documentation/requirements')
+texfiles = ['anuga_API_requirements']
+
+os.chdir(anugapath) # Move to location of LaTeX files 
+os.system('svn up') # Update from svn
+
+
+for texfile in texfiles:
+    print 'Processing %s' %texfile
+    # Compile with LaTeX, makeindex etc
+    for i in range(3):
+        os.system('latex --interaction=nonstopmode %s.tex' %texfile)
+        os.system('makeindex %s.idx' %texfile)
+        os.system('bibtex %s' %texfile)    
+
+    # Create pdf file
+    os.system('dvips %s -o %s.ps' %((texfile,)*2))    
+    os.system('ps2pdf %s.ps' %texfile)    
+     
+    # Create html pages     
+    os.system('latex2html %s' %texfile)
+
Index: /anuga_core/documentation/user_manual/anuga_installation_guide.tex
===================================================================
--- /anuga_core/documentation/user_manual/anuga_installation_guide.tex	(revision 3574)
+++ /anuga_core/documentation/user_manual/anuga_installation_guide.tex	(revision 3574)
@@ -0,0 +1,135 @@
+\documentclass{manual}
+
+
+\title{ANUGA Installation Guide}
+
+\author{Howard Silcock, Ole Nielsen, Duncan Gray, Jane Sexton}
+
+% Please at least include a long-lived email address;
+% the rest is at your discretion.
+\authoraddress{Geoscience Australia \\
+  Email: \email{ole.nielsen@ga.gov.au}
+}
+
+%Draft date
+\date{\today}                   % update before release!
+                % Use an explicit date so that reformatting
+                % doesn't cause a new date to be used.  Setting
+                % the date to \today can be used during draft
+                % stages to make it easier to handle versions.
+
+\release{1.0}           % release version; this is used to define the
+                % \version macro
+
+\makeindex          % tell \index to actually write the .idx file
+%\makemodindex          % If this contains a lot of module sections.
+
+
+
+\begin{document}
+\maketitle
+
+
+
+% This makes the contents more accessible from the front page of the HTML.
+\ifhtml
+\chapter*{Front Matter\label{front}}
+\fi
+
+
+
+
+\chapter{Introduction}
+
+This document outlines the required software for installing the Anuga toolbox.
+All components are licensed as open source and readily available from the net.
+
+
+\section{Pre-requisites}
+
+The Anuga software core (pyvolution, pmesh, least\_squares, ...) depends on the following:
+
+\begin{itemize}
+  \item python 2.3 or later \url{http://www.python.org}
+  \item python-numeric for Linux.  It's called Numeric in Windows.  
+  \item python-dev (Interestingly, numeric seems to be installed as
+  well) for Linux.  This is not necessary for Windows.
+  \item python-scientific (to provide python-netcdf) for Linux.  It's
+    called ScientificPython in Windows.
+  \item NETCDF.  Extract the file netcdf.dll, and put in C://Windows//System32// (Windows XP) or C://WINNT//System32 (Windows NT or 2000). 
+
+  \item A C compiler such as gcc (from GNU in case of Linux and MinGW
+  in case of Windows)
+  \item scons for automatically compiling the distribution.
+\end{itemize}
+
+
+\section{Recommended software}
+
+\begin{itemize}
+  \item psyco \url{http://psyco.sourceforge.net/index.html}
+  \item visual python \url{http://vpython.org}
+  \item matplotlib (pylab) for quality 2d plotting (moving towards mandatory requirement)
+  \item VTK \url{http://mayavi.sourceforge.net/dwnld/vtk/win32/}
+\end{itemize}
+
+
+
+\section{System configuration}
+
+
+The system path on Win32 architectures must contain the directories
+\begin{verbatim}
+  PATH=C:\Python23;C:\MinGW\bin;C:\Program Files\swollen
+\end{verbatim}
+(similar for Linux....)
+
+In addition the root directory for all anuga/inundation modules must be on
+the pythonpath, e.g.\
+\begin{verbatim}
+PYTHONPATH=C:\anuga\inundation
+\end{verbatim}
+
+
+
+
+
+\section{Installation}
+
+(Explain how to check out from svn or obtain from elsewhere)
+
+
+In the ANUGA root directory, run the compilation script:
+{\small \begin{verbatim}
+  scons
+\end{verbatim}}
+
+
+
+\subsection{Testing}
+
+In the ANUGA root directory, run the test suite:
+{\small \begin{verbatim}
+  python test_all.py
+\end{verbatim}}
+
+
+
+
+\section{Other stuff to be included}
+
+\begin{verbatim}
+Install tortoise from downloads (ITs didn't integrate wih explorer).
+In settings set proxy to proxy.agso.gov.au  8080
+
+
+Install swollen from latest distro (in subversion)
+
+
+\end{verbatim}
+
+
+
+
+
+\end{document}
Index: /anuga_core/documentation/user_manual/anuga_user_manual.tex
===================================================================
--- /anuga_core/documentation/user_manual/anuga_user_manual.tex	(revision 3574)
+++ /anuga_core/documentation/user_manual/anuga_user_manual.tex	(revision 3574)
@@ -0,0 +1,3009 @@
+% Complete documentation on the extended LaTeX markup used for Python
+% documentation is available in ``Documenting Python'', which is part
+% of the standard documentation for Python.  It may be found online
+% at:
+%
+%     http://www.python.org/doc/current/doc/doc.html
+
+
+%labels
+%Sections and subsections \label{sec: }
+%Chapters \label{ch: }
+%Equations \label{eq: }
+%Figures \label{fig: }
+
+% Is latex failing with;
+% `modanuga_user_manual.ind' not found?
+% try this command-line
+%   makeindex modanuga_user_manual.idx
+% To produce the modanuga_user_manual.ind file.
+
+
+\documentclass{manual}
+
+\usepackage{graphicx}
+\usepackage{datetime}
+
+\input{definitions}
+
+\title{\anuga User Manual}
+\author{Geoscience Australia and the Australian National University}
+
+% Please at least include a long-lived email address;
+% the rest is at your discretion.
+\authoraddress{Geoscience Australia \\
+  Email: \email{ole.nielsen@ga.gov.au}
+}
+
+%Draft date
+
+% update before release!
+% Use an explicit date so that reformatting
+% doesn't cause a new date to be used.  Setting
+% the date to \today can be used during draft
+% stages to make it easier to handle versions.
+
+
+\longdate       % Make date format long using datetime.sty
+%\settimeformat{xxivtime} % 24 hour Format
+\settimeformat{oclock} % Verbose
+\date{\today, \ \currenttime}
+%\hyphenation{set\_datadir}
+
+\ifhtml
+\date{\today} % latex2html does not know about datetime
+\fi
+
+
+
+
+
+\release{1.0}   % release version; this is used to define the
+                % \version macro
+
+\makeindex          % tell \index to actually write the .idx file
+\makemodindex       % If this contains a lot of module sections.
+
+\setcounter{tocdepth}{3}
+\setcounter{secnumdepth}{3}
+
+
+\begin{document}
+\maketitle
+
+
+% This makes the contents more accessible from the front page of the HTML.
+\ifhtml
+\chapter*{Front Matter\label{front}}
+\fi
+
+%Subversion keywords:
+%
+%$LastChangedDate$
+%$LastChangedRevision$
+%$LastChangedBy$
+
+\input{copyright}
+
+
+\begin{abstract}
+\label{def:anuga}
+
+\noindent \anuga\index{\anuga} is a hydrodynamic modelling tool that
+allows users to model realistic flow problems in complex geometries.
+Examples include dam breaks or the effects of natural hazards such
+as riverine flooding, storm surges and tsunami.
+
+The user must specify a study area represented by a mesh of triangular
+cells, the topography and bathymetry, frictional resistance, initial
+values for water level (called \emph{stage}\index{stage} within \anuga),
+boundary
+conditions and forces such as windstress or pressure gradients if
+applicable.
+
+\anuga tracks the evolution of water depth and horizontal momentum
+within each cell over time by solving the shallow water wave equation
+governing equation using a finite-volume method.
+
+\anuga cannot model details of breaking waves, flow under ceilings such
+as pipes, turbulence and vortices, vertical convection or viscous
+flows.
+
+\anuga also incorporates a mesh generator, called \code{pmesh}, that
+allows the user to set up the geometry of the problem interactively as
+well as tools for interpolation and surface fitting, and a number of
+auxiliary tools for visualising and interrogating the model output.
+
+Most \anuga components are written in the object-oriented programming
+language Python and most users will interact with \anuga by writing
+small Python programs based on the \anuga library
+functions. Computationally intensive components are written for
+efficiency in C routines working directly with the Numerical Python
+structures.
+
+
+\end{abstract}
+
+\tableofcontents
+
+
+\chapter{Introduction}
+
+
+\section{Purpose}
+
+The purpose of this user manual is to introduce the new user to the
+inundation software, describe what it can do and give step-by-step
+instructions for setting up and running hydrodynamic simulations.
+
+\section{Scope}
+
+This manual covers only what is needed to operate the software after
+installation and configuration. It does not includes instructions
+for installing the software or detailed API documentation, both of
+which will be covered in separate publications and by documentation
+in the source code.
+
+\section{Audience}
+
+Readers are assumed to be familiar with the operating environment
+and have a general understanding of the subject matter, as well as
+enough programming experience to adapt the code to different
+requirements and to understand the basic terminology of
+object-oriented programming.
+
+\pagebreak
+\chapter{Background}
+
+
+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 are developing a hydrodynamic inundation modelling tool
+called \anuga to help simulate the impact of these hazards.
+
+The core of \anuga is the fluid dynamics module, called pyvolution,
+which is based on a finite-volume method for solving the shallow water
+wave equation.  The study area is represented by a mesh of triangular
+cells.  By solving the governing equation within each cell, water
+depth and horizontal momentum are tracked over time.
+
+A major capability of pyvolution is that it can 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.  Pyvolution is also capable
+of modelling hydraulic jumps due to the ability of the finite-volume
+method to accommodate discontinuities in the solution.
+
+To set up a particular scenario the user specifies the geometry
+(bathymetry and topography), the initial water level (stage),
+boundary conditions such as tide, and any forcing terms that may
+drive the system such as wind stress or atmospheric pressure
+gradients. Gravity and frictional resistance from the different
+terrains in the model are represented by predefined forcing terms.
+
+A mesh generator, called pmesh, allows the user to set up the geometry
+of the problem interactively and to identify boundary segments and
+regions using symbolic tags.  These tags may then be used to set the
+actual boundary conditions and attributes for different regions
+(e.g. the Manning friction coefficient) for each simulation.
+
+Most \anuga components are written in the object-oriented programming
+language Python.  Software written in Python can be produced quickly
+and can be readily adapted to changing requirements throughout its
+lifetime.  Computationally intensive components are written for
+efficiency in C routines working directly with the Numerical Python
+structures.  The animation tool developed for \anuga is based on
+OpenSceneGraph, an Open Source Software (OSS) component allowing high
+level interaction with sophisticated graphics primitives.
+See \cite{nielsen2005} for more background on \anuga.
+
+\chapter{Restrictions and limitations on \anuga}
+
+Although a powerful and flexible tool for hydrodynamic modelling, \anuga has a
+number of limitations that any potential user need to be aware of. They are
+
+\begin{itemize}
+  \item The mathematical model is the 2D shallow water wave equation. 
+  As such it cannot resolve vertical convection and consequently not breaking 
+  waves or 3D turbulence (e.g.\ vorticity).
+  \item The finite volume is a very robust and flexible numerical technique, 
+  but it is not the fastest method around. If the geometry is sufficiently 
+  simple and if there is no need for wetting or drying, a finite-difference 
+  method may be able to solve the problem faster than \anuga.
+  %\item Mesh resolutions near coastlines with steep gradients need to be...   
+  \item Frictional resistance is implemented using Manning's formula, but 
+  \anuga has not yet been validated in regard to bottom roughness
+\end{itemize}
+
+
+
+\chapter{Getting Started}
+\label{ch:getstarted}
+
+This section is designed to assist the reader to get started with
+\anuga by working through some examples. Two examples are discussed;
+the first is a simple example to illustrate many of the ideas, and
+the second is a more realistic example.
+
+\section{A Simple Example}
+\label{sec:simpleexample}
+
+\subsection{Overview}
+
+What follows is a discussion of the structure and operation of a
+script called \file{runup.py}.
+
+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 example demonstrates the basic ideas involved in setting up a
+complex scenario. In general the user specifies the geometry
+(bathymetry and topography), the initial water level, boundary
+conditions such as tide, and any forcing terms that may drive the
+system such as wind stress or atmospheric pressure gradients.
+Frictional resistance from the different terrains in the model is
+represented by predefined forcing terms. In this example, the
+boundary is reflective on three sides and a time dependent wave on
+one side.
+
+The present example represents a simple scenario and does not
+include any forcing terms, nor is the data taken from a file as it
+would typically be.
+
+The conserved quantities involved in the
+problem are stage (absolute height of water surface),
+$x$-momentum and $y$-momentum. Other quantities
+involved in the computation are the friction and elevation.
+
+Water depth can be obtained through the equation
+
+\begin{tabular}{rcrcl}
+  \code{depth} &=& \code{stage} &$-$& \code{elevation}
+\end{tabular}
+
+
+\subsection{Outline of the Program}
+
+In outline, \file{runup.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, where to store the model output.
+
+   \item Inputs various quantities describing physical measurements, such
+as the elevation, to be specified at each mesh point (vertex).
+
+   \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{The Code}
+
+%FIXME: we are using the \code function here.
+%This should be used wherever possible
+For reference we include below the complete code listing for
+\file{runup.py}. Subsequent paragraphs provide a
+`commentary' that describes each step of the program and explains it
+significance.
+
+\verbatiminput{examples/runup.py}
+%\verbatiminput{examples/bedslope.py}
+
+\subsection{Establishing the Mesh}\index{mesh, establishing}
+
+The first task is to set up the triangular mesh to be used for the
+scenario. This is carried out through the statement:
+
+{\small \begin{verbatim}
+    points, vertices, boundary = rectangular(10, 10)
+\end{verbatim}}
+
+The function \function{rectangular} is imported from a module
+\module{mesh\_factory} defined elsewhere. (\anuga also contains
+several other schemes that can be used for setting up meshes, but we
+shall not discuss these.) The above assignment sets up a $10 \times
+10$ rectangular mesh, triangulated in a regular way. The assignment
+
+{\small \begin{verbatim}
+    points, vertices, boundary = rectangular(m, n)
+\end{verbatim}}
+
+returns:
+
+\begin{itemize}
+
+   \item a list \code{points} giving the coordinates of each mesh point,
+
+   \item a list \code{vertices} specifying the three vertices of each triangle, and
+
+   \item a dictionary \code{boundary} that stores the edges on
+   the boundary and associates each with one of the symbolic tags \code{`left'}, \code{`right'},
+   \code{`top'} or \code{`bottom'}.
+
+\end{itemize}
+
+(For more details on symbolic tags, see page
+\pageref{ref:tagdescription}.)
+
+An example of a general unstructured mesh and the associated data
+structures \code{points}, \code{vertices} and \code{boundary} is
+given in Section \ref{sec:meshexample}.
+
+
+
+
+\subsection{Initialising the Domain}
+
+These variables are then used to set up a data structure
+\code{domain}, through the assignment:
+
+{\small \begin{verbatim}
+    domain = Domain(points, vertices, boundary)
+\end{verbatim}}
+
+This creates an instance of the \class{Domain} class, which
+represents the domain of the simulation. Specific options are set at
+this point, including the basename for the output file and the
+directory to be used for data:
+
+{\small \begin{verbatim}
+    domain.set_name('bedslope')
+\end{verbatim}}
+
+{\small \begin{verbatim}
+    domain.set_datadir('.')
+\end{verbatim}}
+
+In addition, the following statement now specifies that the
+quantities \code{stage}, \code{xmomentum} and \code{ymomentum} are
+to be stored:
+
+{\small \begin{verbatim}
+    domain.set_quantities_to_be_stored(['stage', 'xmomentum',
+    'ymomentum'])
+\end{verbatim}}
+
+
+\subsection{Initial Conditions}
+
+The next task is to specify a number of quantities that we wish to
+set for each mesh point. The class \class{Domain} has a method
+\method{set\_quantity}, used to specify these quantities. It is a
+flexible method that allows the user to set quantities in a variety
+of ways---using constants, functions, numeric arrays, expressions
+involving other quantities, or arbitrary data points with associated
+values, all of which can be passed as arguments. All quantities can
+be initialised using \method{set\_quantity}. For a conserved
+quantity (such as \code{stage, xmomentum, ymomentum}) this is called
+an \emph{initial condition}. However, other quantities that aren't
+updated by the equation are also assigned values using the same
+interface. The code in the present example demonstrates a number of
+forms in which we can invoke \method{set\_quantity}.
+
+
+\subsubsection{Elevation}
+
+The elevation, or height of the bed, 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:
+
+{\small \begin{verbatim}
+    def f(x,y):
+        return -x/2
+\end{verbatim}}
+
+This simply associates an elevation with each point \code{(x, y)} of
+the plane.  It specifies that the bed slopes linearly in the
+\code{x} direction, with slope $-\frac{1}{2}$,  and is constant in
+the \code{y} direction.
+
+Once the function \function{f} is specified, the quantity
+\code{elevation} is assigned through the simple statement:
+
+{\small \begin{verbatim}
+    domain.set_quantity('elevation', f)
+\end{verbatim}}
+
+
+\subsubsection{Friction}
+
+The assignment of the friction quantity (a forcing term)
+demonstrates another way we can use \method{set\_quantity} to set
+quantities---namely, assign them to a constant numerical value:
+
+{\small \begin{verbatim}
+    domain.set_quantity('friction', 0.1)
+\end{verbatim}}
+
+This specifies that the Manning friction coefficient is set to 0.1
+at every mesh point.
+
+\subsubsection{Stage}
+
+The stage (the height of the water surface) is related to the
+elevation and the depth at any time by the equation
+
+{\small \begin{verbatim}
+    stage = elevation + depth
+\end{verbatim}}
+
+
+For this example, we simply assign a constant value to \code{stage},
+using the statement
+
+{\small \begin{verbatim}
+    domain.set_quantity('stage', -.4)
+\end{verbatim}}
+
+which specifies that the surface level is set to a height of $-0.4$,
+i.e. 0.4 units (m) below the zero level.
+
+Although it is not necessary for this example, it may be useful to
+digress here and mention a variant to this requirement, which allows
+us to illustrate another way to use \method{set\_quantity}---namely,
+incorporating an expression involving other quantities. Suppose,
+instead of setting a constant value for the stage, we wished to
+specify a constant value for the \emph{depth}. For such a case we
+need to specify that \code{stage} is everywhere obtained by adding
+that value to the value already specified for \code{elevation}. We
+would do this by means of the statements:
+
+{\small \begin{verbatim}
+    h = 0.05 # Constant depth
+    domain.set_quantity('stage', expression = 'elevation + %f' %h)
+\end{verbatim}}
+
+That is, the value of \code{stage} is set to $\code{h} = 0.05$ plus
+the value of \code{elevation} already defined.
+
+The reader will probably appreciate that this capability to
+incorporate expressions into statements using \method{set\_quantity}
+greatly expands its power.) See Section \ref{sec:Initial Conditions} for more
+details.
+
+\subsection{Boundary Conditions}\index{boundary conditions}
+
+The boundary conditions are specified as follows:
+
+{\small \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.3), 0.0, 0.0])
+\end{verbatim}}
+
+The effect of these statements is to set up a selection of different
+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 introduced here may be briefly described as
+follows:
+
+\begin{itemize}
+    \item \textbf{Reflective boundary}\label{def:reflective boundary} Returns same \code{stage} as
+      as present in its neighbour volume but momentum vector
+      reversed 180 degrees (reflected).
+      Specific to the shallow water equation as it works with the
+      momentum quantities assumed to be the second and third conserved
+      quantities. A reflective boundary condition models a solid wall.
+    \item \textbf{Transmissive boundary}\label{def:transmissive boundary} Returns same conserved quantities as
+      those present in its neighbour volume. This is one way of modelling
+      outflow from a domain, but it should be used with caution if flow is
+      not steady state as replication of momentum at the boundary
+      may cause occasional spurious effects. If this occurs,
+      consider using e.g. a Dirichlet boundary condition.
+    \item \textbf{Dirichlet boundary}\label{def:dirichlet boundary} Specifies
+      constant values for stage, $x$-momentum and $y$-momentum at the boundary.
+    \item \textbf{Time boundary}\label{def:time boundary} Like a Dirichlet
+      boundary but with behaviour varying with time.
+\end{itemize}
+
+\label{ref:tagdescription}Before describing how these boundary
+conditions are assigned, we recall that a mesh is specified using
+three variables \code{points}, \code{vertices} and \code{boundary}.
+In the code we are discussing, these three variables are returned by
+the function \code{rectangular}; however, the example given in
+Section \ref{sec:realdataexample} illustrates another way of
+assigning the values, by means of the function
+\code{create\_mesh\_from\_regions}.
+
+These variables store the data determining the mesh as follows. (You
+may find that the example given in Section \ref{sec:meshexample}
+helps to clarify the following discussion, even though that example
+is a \emph{non-rectangular} mesh.)
+
+\begin{itemize}
+\item The variable \code{points} stores a list of 2-tuples giving the
+coordinates of the mesh points.
+
+\item The variable \code{vertices} stores a list of 3-tuples of
+numbers, representing vertices of triangles in the mesh. In this
+list, the triangle whose vertices are \code{points[i]},
+\code{points[j]}, \code{points[k]} is represented by the 3-tuple
+\code{(i, j, k)}.
+
+\item The variable \code{boundary} is a Python dictionary that
+not only stores the edges that make up the boundary but also assigns
+symbolic tags to these edges to distinguish different parts of the
+boundary. An edge with endpoints \code{points[i]} and
+\code{points[j]} is represented by the 2-tuple \code{(i, j)}. The
+keys for the dictionary are the 2-tuples \code{(i, j)} corresponding
+to boundary edges in the mesh, and the values are the tags are used
+to label them. In the present example, the value \code{boundary[(i,
+j)]} assigned to \code{(i, j)]} is one of the four tags
+\code{`left'}, \code{`right'}, \code{`top'} or \code{`bottom'},
+depending on whether the boundary edge represented by \code{(i, j)}
+occurs at the left, right, top or bottom of the rectangle bounding
+the mesh. The function \code{rectangular} automatically assigns
+these tags to the boundary edges when it generates the mesh.
+\end{itemize}
+
+The tags provide the means to assign different boundary conditions
+to an edge depending on which part of the boundary it belongs to.
+(In Section \ref{sec:realdataexample} we describe an example that
+uses different boundary tags---in general, the possible tags are not
+limited to `left', `right', `top' and `bottom', but can be specified
+by the user.)
+
+Using the boundary objects described above, we assign a boundary
+condition to each part of the boundary by means of a statement like
+
+{\small \begin{verbatim}
+    domain.set_boundary({'left': Br, 'right': Bw, 'top': Br, 'bottom': Br})
+\end{verbatim}}
+
+This statement stipulates that, in the current example, the right
+boundary varies with time, as defined by the lambda function, while the other
+boundaries are all reflective.
+
+The reader may wish to experiment by varying the choice of boundary
+types for one or more of the boundaries. (In the case of \code{Bd}
+and \code{Bw}, the three arguments in each case represent the
+\code{stage}, $x$-momentum and $y$-momentum, respectively.)
+
+{\small \begin{verbatim}
+    Bw = Time_boundary(domain=domain,
+                       f=lambda t: [(0.1*sin(t*2*pi)-0.3), 0.0, 0.0])
+\end{verbatim}}
+
+
+
+\subsection{Evolution}\index{evolution}
+
+The final statement \nopagebreak[3]
+{\small \begin{verbatim}
+    for t in domain.evolve(yieldstep = 0.1, duration = 4.0):
+        print domain.timestepping_statistics()
+\end{verbatim}}
+
+causes the configuration of the domain to `evolve', over a series of
+steps indicated by the values of \code{yieldstep} and
+\code{duration}, which can be altered as required.  The value of
+\code{yieldstep} controls the time interval between successive model
+outputs.  Behind the scenes more time steps are generally taken.
+
+
+\subsection{Output}
+
+The output is a NetCDF file with the extension \code{.sww}. It
+contains stage and momentum information and can be used with the
+\code{swollen} (see Section \ref{sec:swollen}) visualisation package
+to generate a visual display. See Section \ref{sec:file formats}
+(page \pageref{sec:file formats}) for more on NetCDF and other file
+formats.
+
+The following is a listing of the screen output seen by the user
+when this example is run:
+
+\verbatiminput{examples/runupoutput.txt}
+
+
+\section{How to Run the Code}
+
+The code can be run in various ways:
+
+\begin{itemize}
+  \item{from a Windows or Unix command line} as in\ \code{python runup.py}
+  \item{within the Python IDLE environment}
+  \item{within emacs}
+  \item{within Windows, by double-clicking the \code{runup.py}
+  file.}
+\end{itemize}
+
+
+\section{Exploring the Model Output}
+
+The following figures are screenshots from the \anuga visualisation
+tool \code{swollen}. Figure \ref{fig:runupstart} shows the domain
+with water surface as specified by the initial condition, $t=0$.
+Figure \ref{fig:bedslope2} shows later snapshots for $t=2.3$ and
+$t=4$ where the system has been evolved and the wave is encroaching
+on the previously dry bed.  All figures are screenshots from an
+interactive animation tool called Swollen which is part of \anuga.
+Swollen is described in more detail is Section \ref{sec:swollen}.
+
+\begin{figure}[hbt]
+
+  \centerline{\includegraphics[width=75mm, height=75mm]
+    {examples/runupstart.eps}}
+
+  \caption{Bedslope example viewed with Swollen}
+  \label{fig:runupstart}
+\end{figure}
+
+
+\begin{figure}[hbt]
+
+  \centerline{
+    \includegraphics[width=75mm, height=75mm]{examples/runupduring.eps}
+    \includegraphics[width=75mm, height=75mm]{examples/runupend.eps}
+   }
+
+  \caption{Bedslope example viewed with Swollen}
+  \label{fig:bedslope2}
+\end{figure}
+
+
+
+
+\clearpage
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\section{An Example with Real Data}
+\label{sec:realdataexample} The following discussion builds on the
+concepts introduced through the \file{runup.py} example and
+introduces a second example, \file{run\_sydney.py}.  This refers to
+a real-life scenario, in which the domain of interest surrounds the
+Sydney region, and predominantly covers Sydney Harbour. A
+hypothetical tsunami wave is generated by a submarine mass failure
+situated on the edge of the continental shelf.
+
+\subsection{Overview}
+As in the case of \file{runup.py}, the actions carried
+out by the program can be organised according to this outline:
+
+\begin{enumerate}
+
+   \item Set up a triangular mesh.
+
+   \item Set certain parameters governing the mode of
+operation of the model---specifying, for instance, where to store the
+model output.
+
+   \item Input various quantities describing physical measurements, such
+as the elevation, to be specified at each mesh point (vertex).
+
+   \item Set up the boundary conditions.
+
+   \item Carry out the evolution of the model through a series of time
+steps and output the results, providing a results file that can be
+visualised.
+
+\end{enumerate}
+
+
+
+\subsection{The Code}
+
+Here is the code for \file{run\_sydney\_smf.py}:
+
+\verbatiminput{examples/runsydney.py}
+
+In discussing the details of this example, we follow the outline
+given above, discussing each major step of the code in turn.
+
+\subsection{Establishing the Mesh}\index{mesh, establishing}
+
+One obvious way that the present example differs from
+\file{runup.py} is in the use of a more complex method to
+create the mesh. Instead of imposing a mesh structure on a
+rectangular grid, the technique used for this example involves
+building mesh structures inside polygons specified by the user,
+using a mesh-generator referred to as \code{pmesh}.
+
+In its simplest form, \code{pmesh} creates the mesh within a single
+polygon whose vertices are at geographical locations specified by
+the user. The user specifies the \emph{resolution}---that is, the
+maximal area of a triangle used for triangulation---and a triangular
+mesh is created inside the polygon using a mesh generation engine.
+On any given platform, the same mesh will be returned. Figure
+\ref{fig:pentagon} shows a simple example of this, in which the
+triangulation is carried out within a pentagon.
+
+
+\begin{figure}[hbt]
+
+  \caption{Mesh points are created inside the polygon}
+  \label{fig:pentagon}
+\end{figure}
+
+Boundary tags are not restricted to \code{`left'}, \code{`right'},
+\code{`bottom'} and \code{`top'}, as in the case of
+\file{runup.py}. Instead the user specifies a list of
+tags appropriate to the configuration being modelled.
+
+In addition, \code{pmesh} provides a way to adapt to geographic or
+other features in the landscape, whose presence may require an
+increase in resolution. This is done by allowing the user to specify
+a number of \emph{interior polygons}, each with a specified
+resolution, see Figure \ref{fig:interior meshes}. It is also
+possible to specify one or more `holes'---that is, areas bounded by
+polygons in which no triangulation is required.
+
+\begin{figure}[hbt]
+
+
+
+  \caption{Interior meshes with individual resolution}
+  \label{fig:interior meshes}
+\end{figure}
+
+In its general form, \code{pmesh} takes for its input a bounding
+polygon and (optionally) a list of interior polygons. The user
+specifies resolutions, both for the bounding polygon and for each of
+the interior polygons. Given this data, \code{pmesh} first creates a
+triangular mesh with varying resolution.
+
+The function used to implement this process is
+\function{create\_mesh\_from\_regions}. Its arguments include the
+bounding polygon and its resolution, a list of boundary tags, and a
+list of pairs \code{[polygon, resolution]}, specifying the interior
+polygons and their resolutions.
+
+In practice, the details of the polygons used are read from a
+separate file \file{project.py}. Here is a complete listing of
+\file{project.py}:
+
+\verbatiminput{examples/project.py}
+
+The resulting mesh is output to a \emph{mesh file}\index{mesh
+file}\label{def:mesh file}. This term is used to describe a file of
+a specific format used to store the data specifying a mesh. (There
+are in fact two possible formats for such a file: it can either be a
+binary file, with extension \code{.msh}, or an ASCII file, with
+extension \code{.tsh}. In the present case, the binary file format
+\code{.msh} is used. See Section \ref{sec:file formats} (page
+\pageref{sec:file formats}) for more on file formats.)
+
+The statements
+
+{\small \begin{verbatim}
+    interior_res = 5000
+    interior_regions = [[project.northern_polygon, interior_res],
+                        [project.harbour_polygon, interior_res],
+                        [project.southern_polygon, interior_res],
+                        [project.manly_polygon, interior_res],
+                        [project.top_polygon, interior_res]]
+\end{verbatim}}
+
+are used to read in the specific polygons \code{project.harbour\_polygon\_2} and
+\code{botanybay\_polygon\_2} from \file{project.py} and assign a
+common resolution of to each. The statement
+
+{\small \begin{verbatim}
+create_mesh_from_regions(project.demopoly,
+                         boundary_tags= {'oceannorth': [0], 
+                                         'onshorenorth1': [1],
+                                         'onshorenorthwest1': [2],
+                                         'onshorenorthwest2': [3],
+                                         'onshorenorth2': [4],
+                                         'onshorewest': [5],
+                                         'onshoresouth': [6],
+                                         'oceansouth': [7],
+                                         'oceaneast': [8]},
+                         maximum_triangle_area=100000,
+                         filename=meshname,           
+                         interior_regions=interior_regions)    
+\end{verbatim}}
+
+is then used to create the mesh, taking the bounding polygon to be
+the polygon \code{diffpolygonall} specified in \file{project.py}.
+The argument \code{boundary\_tags} assigns a dictionary, whose keys
+are the names of the boundary tags used for the bounding
+polygon---\code{`bottom'}, \code{`right0'}, \code{`right1'},
+\code{`right2'}, \code{`top'}, \code{`left1'}, \code{`left2'} and
+\code{`left3'}--- and whose values identify the indices of the
+segments associated with each of these tags. (The value associated
+with each boundary tag is a one-element list.)
+
+
+\subsection{Initialising the Domain}
+
+As with \file{runup.py}, once we have created the mesh, the next
+step is to create the data structure \code{domain}. We did this for
+\file{runup.py} by inputting lists of points and triangles and
+specifying the boundary tags directly. However, in the present case,
+we use a method that works directly with the mesh file
+\code{meshname}, as follows:
+
+
+{\small \begin{verbatim}
+    domain = Domain(meshname, use_cache=True, verbose=True)
+\end{verbatim}}
+
+Providing a filename instead of the lists used in \file{runup.py}
+above causes \code{Domain} to convert a mesh file \code{meshname}
+into an instance of \code{Domain}, allowing us to use methods like
+\method{set\_quantity} to set quantities and to apply other
+operations.
+
+%(In principle, the
+%second argument of \function{pmesh\_to\_domain\_instance} can be any
+%subclass of \class{Domain}, but for applications involving the
+%shallow-water wave equation, the second argument of
+%\function{pmesh\_to\_domain\_instance} can always be set simply to
+%\class{Domain}.)
+
+The following statements specify a basename and data directory, and
+identify quantities to be stored. For the first two, values are
+taken from \file{project.py}.
+
+{\small \begin{verbatim}
+    domain.set_name(project.basename)
+    domain.set_datadir(project.outputdir)
+    domain.set_quantities_to_be_stored(['stage', 'xmomentum',
+        'ymomentum'])
+\end{verbatim}}
+
+
+\subsection{Initial Conditions}
+Quantities for \file{runsydney.py} are set
+using similar methods to those in \file{runup.py}. However,
+in this case, many of the values are read from the auxiliary file
+\file{project.py} or, in the case of \code{elevation}, from an
+ancillary points file.
+
+
+
+\subsubsection{Stage}
+
+For the scenario we are modelling in this case, we use a callable
+object \code{tsunami\_source}, assigned by means of a function
+\function{slump\_tsunami}. This is similar to how we set elevation in
+\file{runup.py} using a function---however, in this case the
+function is both more complex and more interesting.
+
+The function returns the water displacement for all \code{x} and
+\code{y} in the domain. The water displacement is a double Gaussian
+function that depends on the characteristics of the slump (length,
+thickness, slope, etc), its location (origin) and the depth at that
+location.
+
+
+\subsubsection{Friction}
+
+We assign the friction exactly as we did for \file{runup.py}:
+
+{\small \begin{verbatim}
+    domain.set_quantity('friction', 0.0)
+\end{verbatim}}
+
+
+\subsubsection{Elevation}
+
+The elevation is specified by reading data from a file:
+
+{\small \begin{verbatim}
+    domain.set_quantity('elevation',
+                        filename = project.combineddemname + '.pts',
+                        use_cache = True,
+                        verbose = True)
+\end{verbatim}}
+
+However, before this step can be executed, some preliminary steps
+are needed to prepare the file from which the data is taken. Two
+source files are used for this data---their names are specified in
+the file \file{project.py}, in the variables \code{coarsedemname}
+and \code{finedemname}. They contain `coarse' and `fine' data,
+respectively---that is, data sampled at widely spaced points over a
+large region and data sampled at closely spaced points over a
+smaller subregion. The data in these files is combined through the
+statement
+
+{\small \begin{verbatim}
+combine_rectangular_points_files(project.finedemname + '.pts',
+                                 project.coarsedemname + '.pts',
+                                 project.combineddemname + '.pts')
+\end{verbatim}}
+
+The effect of this is simply to combine the datasets by eliminating
+any coarse data associated with points inside the smaller region
+common to both datasets. The name to be assigned to the resulting
+dataset is also derived from the name stored in the variable
+\code{combinedname} in the file \file{project.py}.
+
+\subsection{Boundary Conditions}\index{boundary conditions}
+
+Setting boundaries follows a similar pattern to the one used for
+\file{runup.py}, except that in this case we need to associate a
+boundary type with each of the
+boundary tag names introduced when we established the mesh. In place of the four
+boundary types introduced for \file{runup.py}, we use the reflective
+boundary for each of the
+eight tagged segments defined by \code{create_mesh_from_regions}:
+
+{\small \begin{verbatim}
+Bd = Dirichlet_boundary([0.0,0.0,0.0])
+domain.set_boundary( {'oceannorth': Bd,
+                      'onshorenorth1': Bd,
+                      'onshorenorthwest1': Bd,
+                      'onshorenorthwest2': Bd,
+                      'onshorenorth2': Bd,
+                      'onshorewest': Bd,
+                      'onshoresouth': Bd,
+                      'oceansouth': Bd,
+                      'oceaneast': Bd} )
+\end{verbatim}}
+
+\subsection{Evolution}
+
+With the basics established, the running of the `evolve' step is
+very similar to the corresponding step in \file{runup.py}. Here,
+the simulation is run for five hours (18000 seconds) with
+the output stored every two minutes (120 seconds).
+
+{\small \begin{verbatim}
+    import time t0 = time.time()
+
+    for t in domain.evolve(yieldstep = 120, duration = 18000):
+        print domain.timestepping_statistics()
+        print domain.boundary_statistics(tags = 'bottom')
+
+    print 'That took %.2f seconds' %(time.time()
+\end{verbatim}}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\chapter{\anuga Public Interface}
+\label{ch:interface}
+
+This chapter gives an overview of the features of \anuga available
+to the user at the public interface. These are grouped under the
+following headings, which correspond to the outline of the examples
+described in Chapter \ref{ch:getstarted}:
+
+\begin{itemize}
+    \item Establishing the Mesh
+    \item Initialising the Domain
+    \item Specifying the Quantities
+    \item Initial Conditions
+    \item Boundary Conditions
+    \item Forcing Functions
+    \item Evolution
+\end{itemize}
+
+The listings are intended merely to give the reader an idea of what
+each feature is, where to find it and how it can be used---they do
+not give full specifications; for these the reader
+may consult the code. The code for every function or class contains
+a documentation string, or `docstring', that specifies the precise
+syntax for its use. This appears immediately after the line
+introducing the code, between two sets of triple quotes.
+
+Each listing also describes the location of the module in which
+the code for the feature being described can be found. All modules
+are in the folder \file{inundation} or one of its subfolders, and the
+location of each module is described relative to \file{inundation}. Rather
+than using pathnames, whose syntax depends on the operating system,
+we use the format adopted for importing the function or class for
+use in Python code. For example, suppose we wish to specify that the
+function \function{create\_mesh\_from\_regions} is in a module called
+\module{mesh\_interface} in a subfolder of \module{inundation} called
+\code{pmesh}. In Linux or Unix syntax, the pathname of the file
+containing the function, relative to \file{inundation}, would be
+
+\begin{center}
+%    \code{pmesh/mesh\_interface.py}
+    \code{pmesh}$\slash$\code{mesh\_interface.py}
+\end{center}
+
+while in Windows syntax it would be
+
+\begin{center}
+    \code{pmesh}$\backslash$\code{mesh\_interface.py}
+\end{center}
+
+Rather than using either of these forms, in this chapter we specify
+the location simply as \code{pmesh.mesh\_interface}, in keeping with
+the usage in the Python statement for importing the function,
+namely:
+\begin{center}
+    \code{from pmesh.mesh\_interface import create\_mesh\_from\_regions}
+\end{center}
+
+Each listing details the full set of parameters for the class or
+function; however, the description is generally limited to the most
+important parameters and the reader is again referred to the code
+for more details.
+
+The following parameters are common to many functions and classes
+and are omitted from the descriptions given below:
+
+%\begin{center}
+\begin{tabular}{ll}  %\hline
+%\textbf{Name } & \textbf{Description}\\
+%\hline
+\emph{use\_cache} & Specifies whether caching is to be used for improved performance. See Section \ref{sec:caching} for details on the underlying caching functionality\\
+\emph{verbose} & If \code{True}, provides detailed terminal output
+to the user\\  % \hline
+\end{tabular}
+%\end{center}
+
+\section{Mesh Generation}
+
+Before discussing the part of the interface relating to mesh
+generation, we begin with a description of a simple example of a
+mesh and use it to describe how mesh data is stored.
+
+\label{sec:meshexample} Figure \ref{fig:simplemesh} represents a
+very simple mesh comprising just 11 points and 10 triangles.
+
+
+\begin{figure}[h]
+  \begin{center}
+    \includegraphics[width=90mm, height=90mm]{triangularmesh.eps}
+  \end{center}
+
+  \caption{A simple mesh}
+  \label{fig:simplemesh}
+\end{figure}
+
+
+The variables \code{points}, \code{vertices} and \code{boundary}
+represent the data displayed in Figure \ref{fig:simplemesh} as
+follows. The list \code{points} stores the coordinates of the
+points, and may be displayed schematically as in Table
+\ref{tab:points}.
+
+
+\begin{table}
+  \begin{center}
+    \begin{tabular}[t]{|c|cc|} \hline
+      index & \code{x} & \code{y}\\  \hline
+      0 & 1 & 1\\
+      1 & 4 & 2\\
+      2 & 8 & 1\\
+      3 & 1 & 3\\
+      4 & 5 & 5\\
+      5 & 8 & 6\\
+      6 & 11 & 5\\
+      7 & 3 & 6\\
+      8 & 1 & 8\\
+      9 & 4 & 9\\
+      10 & 10 & 7\\  \hline
+    \end{tabular}
+  \end{center}
+
+  \caption{Point coordinates for mesh in
+    Figure \protect \ref{fig:simplemesh}}
+  \label{tab:points}
+\end{table}
+
+The list \code{vertices} specifies the triangles that make up the
+mesh. It does this by specifying, for each triangle, the indices
+(the numbers shown in the first column above) that correspond to the
+three points at its vertices, taken in an anti-clockwise order
+around the triangle. Thus, in the example shown in Figure
+\ref{fig:simplemesh}, the variable \code{vertices} contains the
+entries shown in Table \ref{tab:vertices}. The starting point is
+arbitrary so triangle $(0,1,3)$ is considered the same as $(1,3,0)$
+and $(3,0,1)$.
+
+
+\begin{table}
+  \begin{center}
+    \begin{tabular}{|c|ccc|} \hline
+      index & \multicolumn{3}{c|}{\code{vertices}}\\ \hline
+      0 & 0 & 1 & 3\\
+      1 & 1 & 2 & 4\\
+      2 & 2 & 5 & 4\\
+      3 & 2 & 6 & 5\\
+      4 & 4 & 5 & 9\\
+      5 & 4 & 9 & 7\\
+      6 & 3 & 4 & 7\\
+      7 & 7 & 9 & 8\\
+      8 & 1 & 4 & 3\\
+      9 & 5 & 10 & 9\\  \hline
+    \end{tabular}
+  \end{center}
+
+  \caption{Vertices for mesh in Figure \protect \ref{fig:simplemesh}}
+  \label{tab:vertices}
+\end{table}
+
+Finally, the variable \code{boundary} identifies the boundary
+triangles and associates a tag with each.
+
+\refmodindex[pmesh.meshinterface]{pmesh.mesh\_interface}\label{sec:meshgeneration}
+
+\begin{funcdesc}  {create\_mesh\_from\_regions}{bounding_polygon,
+                             boundary_tags,
+                             maximum_triangle_area,
+                             filename=None,
+                             interior_regions=None,
+                             poly_geo_reference=None,
+                             mesh_geo_reference=None,
+                             minimum_triangle_angle=28.0}
+Module: \module{pmesh.mesh\_interface}
+
+This function allows a user to initiate the automatic creation of a
+mesh inside a specified polygon (input \code{bounding_polygon}).
+Among the parameters that can be set are the \emph{resolution}
+(maximal area for any triangle in the mesh) and the minimal angle
+allowable in any triangle. The user can specify a number of internal
+polygons within each of which a separate mesh is to be created,
+generally with a smaller resolution. \code{interior_regions} is a
+paired list containing the interior polygon and its resolution.
+Additionally, the user specifies a list of boundary tags, one for
+each edge of the bounding polygon.
+
+\textbf{WARNING}. Note that the dictionary structure used for the
+parameter \code{boundary\_tags} is different from that used for the
+variable \code{boundary} that occurs in the specification of a mesh.
+In the case of \code{boundary}, the tags are the \emph{values} of
+the dictionary, whereas in the case of \code{boundary_tags}, the
+tags are the \emph{keys} and the \emph{value} corresponding to a
+particular tag is a list of numbers identifying boundary edges
+labelled with that tag. Because of this, it is theoretically
+possible to assign the same edge to more than one tag. However, an
+attempt to do this will cause an error.
+\end{funcdesc}
+
+
+
+
+\begin{classdesc}  {Mesh}{userSegments=None,
+                 userVertices=None,
+                 holes=None,
+                 regions=None,
+                 geo_reference=None}
+Module: \module{pmesh.mesh}
+
+A class used to build a mesh outline and generate a two-dimensional
+triangular mesh. The mesh outline is used to describe features on the
+mesh, such as the mesh boundary. Many of this classes methods are used
+to build a mesh outline, such as \code{add\_vertices} and
+\code{add\_region\_from\_polygon}.
+
+\end{classdesc}
+
+
+\subsection{Key Methods of Class Mesh}
+
+
+\begin{methoddesc} {add\_hole}{x,y, geo_reference=None}
+Module: \module{pmesh.mesh},  Class: \class{Mesh}
+
+This method is used to build the mesh outline.  It defines a hole,
+when the boundary of the hole has already been defined, by selecting a
+point within the boundary. 
+
+\end{methoddesc}
+
+
+\begin{methoddesc}  {add\_hole\_from\_polygon}{self, polygon, tags=None,
+    geo_reference=None}
+Module: \module{pmesh.mesh},  Class: \class{Mesh}
+
+This method is used to add a `hole' within a region ---that is, to
+define a interior region where the triangular mesh will not be
+generated---to a \class{Mesh} instance. The region boundary is described by
+the polygon passed in.  Additionally, the user specifies a list of
+boundary tags, one for each edge of the bounding polygon.
+\end{methoddesc}
+
+
+\begin{methoddesc}  {add\_points_and_segments}{self, points, segments,
+    segment\_tags=None}
+Module: \module{pmesh.mesh},  Class: \class{Mesh}
+
+This method is used to build the mesh outline. It adds some points and
+segments connecting some points.  A tag for each point can optionally
+be added.
+
+\end{methoddesc}
+
+\begin{methoddesc} {add\_region}{x,y, geo_reference=None}
+Module: \module{pmesh.mesh},  Class: \class{Mesh}
+
+This method is used to build the mesh outline.  It defines a region,
+when the boundary of the region has already been defined, by selecting
+a point within the boundary.  A region instance is returned.  This can
+be used to set the resolution.
+
+\end{methoddesc}
+
+\begin{methoddesc}  {add\_region\_from\_polygon}{self, polygon, tags=None,
+                                max_triangle_area=None, geo_reference=None}
+Module: \module{pmesh.mesh},  Class: \class{Mesh}
+
+This method is used to build the mesh outline.  It adds a region to a
+\class{Mesh} instance.  Regions are commonly used to describe an area
+with an increased density of triangles, by setting
+\code{max_triangle_area}.  The
+region boundary is described by the input \code{polygon}.  Additionally, the
+user specifies a list of boundary tags, one for each edge of the
+bounding polygon.
+
+\end{methoddesc}
+
+
+
+
+
+\begin{methoddesc} {add\_vertices}{point_data}
+Module: \module{pmesh.mesh},  Class: \class{Mesh}
+Add user vertices. The point_data can be a list of (x,y) values, a numeric
+array or a geospatial_data instance.	
+\end{methoddesc}
+
+\begin{methoddesc} {auto\_segment}{raw_boundary=raw_boundary,
+                    remove_holes=remove_holes,
+                    smooth_indents=smooth_indents,
+                    expand_pinch=expand_pinch}
+Module: \module{pmesh.mesh},  Class: \class{Mesh}
+Add segments between the user vertices to give the vertices an
+outline.  The outline is an alpha shape. This method is
+useful since a set of user vertices need to be outlined by segments
+before generate_mesh is called.
+	
+\end{methoddesc}
+
+\begin{methoddesc}  {export\_mesh_file}{self,ofile}
+Module: \module{pmesh.mesh},  Class: \class{Mesh}
+
+This method is used to save the mesh to a file. \code{ofile} is the
+name of the mesh file to be written, including the extension.  Use
+the extension \code{.msh} for the file to be in NetCDF format and
+\code{.tsh} for the file to be ASCII format.
+\end{methoddesc}
+
+\begin{methoddesc}  {generate\_mesh}{self,
+                      maximum_triangle_area=None,
+                      minimum_triangle_angle=28.0,
+                      verbose=False}
+Module: \module{pmesh.mesh},  Class: \class{Mesh}
+
+This method is used to generate the triangular mesh.  The  maximal
+area of any triangle in the mesh can be specified, which is used to
+control the triangle density, along with the
+minimum angle in any triangle.
+\end{methoddesc}
+
+
+
+\begin{methoddesc}  {import_ungenerate_file}{self,ofile, tag=None}
+Module: \module{pmesh.mesh},  Class: \class{Mesh}
+
+This method is used to import a polygon file in the ungenerate
+format, which is used by arcGIS. The polygons from the file are converted to
+vertices and segments. \code{ofile} is the name of the polygon file.
+\code{tag} is the tag given to all the polygon's segments.
+
+This function can be used to import building footprints.
+\end{methoddesc}
+
+%%%%%%
+\section{Initialising the Domain}
+
+%Include description of the class Domain and the module domain.
+
+%FIXME (Ole): This is also defined in a later chapter
+%\declaremodule{standard}{pyvolution.domain}
+
+\begin{classdesc} {Domain} {source=None,
+                 triangles=None,
+                 boundary=None,
+                 conserved_quantities=None,
+                 other_quantities=None,
+                 tagged_elements=None,
+                 geo_reference=None,
+                 use_inscribed_circle=False,
+                 mesh_filename=None,
+                 use_cache=False,
+                 verbose=False,
+                 full_send_dict=None,
+                 ghost_recv_dict=None,
+                 processor=0,
+                 numproc=1}
+Module: \refmodule{pyvolution.domain}
+
+This class is used to create an instance of a data structure used to
+store and manipulate data associated with a mesh. The mesh is
+specified either by assigning the name of a mesh file to
+\code{source} or by
+\end{classdesc}
+
+\begin{funcdesc}  {pmesh\_to\_domain\_instance}{file_name, DomainClass, use_cache = False, verbose = False}
+Module: \module{pyvolution.pmesh2domain}
+
+Once the initial mesh file has been created, this function is
+applied to convert it to a domain object---that is, to a member of
+the special Python class \class{Domain} (or a subclass of
+\class{Domain}), which provides access to properties and methods
+that allow quantities to be set and other operations to be carried
+out.
+
+\code{file\_name} is the name of the mesh file to be converted,
+including the extension. \code{DomainClass} is the class to be
+returned, which must be a subclass of \class{Domain} having the same
+interface as \class{Domain}---in practice, it can usually be set
+simply to \class{Domain}.
+
+This is now superseded by Domain(mesh_filename).
+\end{funcdesc}
+
+
+\subsection{Key Methods of Domain}
+
+\begin{methoddesc} {set\_name}{name}
+    Module: \refmodule{pyvolution.domain}, page \pageref{mod:pyvolution.domain}  %\code{pyvolution.domain}
+
+    Assigns the name \code{name} to the domain.
+\end{methoddesc}
+
+\begin{methoddesc} {get\_name}{}
+    Module: \module{pyvolution.domain}
+
+    Returns the name assigned to the domain by \code{set\_name}. If no name has been
+    assigned, returns \code{`domain'}.
+\end{methoddesc}
+
+\begin{methoddesc} {set\_datadir}{name}
+    Module: \module{pyvolution.domain}
+
+    Specifies the directory used for SWW files, assigning it to the pathname \code{name}. The default value, before
+    \code{set\_datadir} has been run, is the value \code{default\_datadir}
+    specified in \code{config.py}.
+
+    Since different operating systems use different formats for specifying pathnames,
+    it is necessary to specify path separators using the Python code \code{os.sep}, rather than
+    the operating-specific ones such as `$\slash$' or `$\backslash$'.
+    For this to work you will need to include the statement \code{import os}
+    in your code, before the first appearance of \code{set\_datadir}.
+
+    For example, to set the data directory to a subdirectory
+    \code{data} of the directory \code{project}, you could use
+    the statements:
+
+    {\small \begin{verbatim}
+        import os
+        domain.set_datadir{'project' + os.sep + 'data'}
+    \end{verbatim}}
+\end{methoddesc}
+
+\begin{methoddesc} {get\_datadir}{}
+    Module: \module{pyvolution.domain}
+
+    Returns the data directory set by \code{set\_datadir} or,
+    if \code{set\_datadir} has not
+    been run, returns the value \code{default\_datadir} specified in
+    \code{config.py}.
+\end{methoddesc}
+
+\begin{methoddesc} {set\_minimum_sww_depth}{time=0.0}
+    Module: \module{pyvolution.domain}
+
+    Sets the minimum depth that will be recognised when writing
+        to an sww file. This is useful for removing thin water layers
+        that seems to be caused by friction creep.
+\end{methoddesc}
+
+\begin{methoddesc} {set\_time}{time=0.0}
+    Module: \module{pyvolution.domain}
+
+    Sets the initial time, in seconds, for the simulation. The
+    default is 0.0.
+\end{methoddesc}
+
+\begin{methoddesc} {set\_default\_order}{n}
+    Sets the default (spatial) order to the value specified by
+    \code{n}, which must be either 1 or 2. (Assigning any other value
+    to \code{n} will cause an error.)
+\end{methoddesc}
+
+
+%%%%%%
+\section{Initial Conditions}
+\label{sec:Initial Conditions}
+In standard usage of partial differential equations, initial conditions
+refers to the values associated to the system variables (the conserved
+quantities here) for \code{time = 0}. In setting up a scenario script
+as described in Sections \ref{sec:simpleexample} and \ref{sec:realdataexample},
+\code{set_quantity} is used to define the initial conditions of variables
+other than the conserved quantities, such as friction. Here, we use the terminology
+of initial conditions to refer to initial values for variables which need
+prescription to solve the shallow water wave equation. Further, it must be noted
+that \code{set_quantity} does not necessarily have to be used in the initial
+condition setting; it can be used at any time throughout the simulation.
+
+\begin{methoddesc}{set\_quantity}{name,
+    numeric = None,
+    quantity = None,
+    function = None,
+    geospatial_data = None,
+    filename = None,
+    attribute_name = None,
+    alpha = None,
+    location = 'vertices',
+    indices = None,
+    verbose = False,
+    use_cache = False}
+  Module: \module{pyvolution.domain}
+  (see also \module{pyvolution.quantity.set\_values})
+
+This function is used to assign values to individual quantities for a
+domain. It is very flexible and can be used with many data types: a
+statement of the form \code{domain.set\_quantity(name, x)} can be used
+to define a quantity having the name \code{name}, where the other
+argument \code{x} can be any of the following:
+
+\begin{itemize}
+\item a number, in which case all vertices in the mesh gets that for
+the quantity in question.
+\item a list of numbers or a Numeric array ordered the same way as the mesh vertices.
+\item a function (e.g.\ see the samples introduced in Chapter 2)
+\item an expression composed of other quantities and numbers, arrays, lists (for
+example, a linear combination of quantities, such as
+\code{domain.set\_quantity('stage','elevation'+x))}
+\item the name of a file from which the data can be read. In this case, the optional argument attribute\_name will select which attribute to use from the file. If left out, set\_quantity will pick one. This is useful in cases where there is only one attribute.
+\item a geospatial dataset (See ?????). Optional argument attribute\_name applies here as with files.
+\end{itemize}
+
+
+Exactly one of the arguments
+  numeric, quantity, function, points, filename
+must be present.
+
+
+Set quantity will look at the type of the second argument (\code{numeric}) and
+determine what action to take.
+
+Values can also be set using the appropriate keyword arguments.
+If x is a function, for example, \code{domain.set\_quantity(name, x)}, \code{domain.set\_quantity(name, numeric=x)}, and \code{domain.set\_quantity(name, function=x)}
+are all equivalent.
+
+
+Other optional arguments are
+\begin{itemize}
+\item \code{indices} which is a list of ids of triangles to which set\_quantity should apply its assignment of values.
+\item \code{location} determines which part of the triangles to assign
+  to. Options are 'vertices' (default), 'edges', 'unique vertices', and 'centroids'.
+\end{itemize}
+
+%%%
+\anuga provides a number of predefined initial conditions to be used
+with \code{set\_quantity}.
+
+\end{methoddesc}
+
+
+
+
+\begin{funcdesc}{set_region}{tag, quantity, X, location='vertices'}
+  Module: \module{pyvolution.domain}
+  
+  (see also \module{pyvolution.quantity.set\_values})
+  
+This function is used to assign values to individual quantities given
+a regional tag.   It is similar to \code{set\_quantity}. 
+For example, if in pmesh a regional tag of 'ditch' was
+used, set\_region can be used to set elevation of this region to
+-10m. X is the constant or function to be applied to the quantity,
+over the tagged region.  Location describes how the values will be
+applied.  Options are 'vertices' (default), 'edges', 'unique
+vertices', and 'centroids'.
+
+This method can also be called with a list of region objects.  This is
+useful for adding quantities in regions, and having one quantity
+value based on another quantity. See  \module{pyvolution.region} for
+more details.
+\end{funcdesc}
+
+
+
+
+\begin{funcdesc}{slump_tsunami}{length, depth, slope, width=None, thickness=None,
+                x0=0.0, y0=0.0, alpha=0.0,
+                gravity=9.8, gamma=1.85,
+                massco=1, dragco=1, frictionco=0, psi=0,
+                dx=None, kappa=3.0, kappad=0.8, zsmall=0.01,
+                domain=None,
+                verbose=False}
+Module: \module{pyvolution.smf}
+
+This function returns a callable object representing an initial water
+displacement generated by a submarine sediment failure. These failures can take the form of
+a submarine slump or slide. In the case of a slide, use \code{slide_tsunami} instead.
+
+The arguments include as a minimum, the slump or slide length, the water depth to the centre of sediment
+mass, and the bathymetric slope. Other slump or slide parameters can be included if they are known.
+\end{funcdesc}
+
+
+%%%
+\begin{funcdesc}{file\_function}{filename,
+    domain = None,
+    quantities = None,
+    interpolation_points = None,
+    verbose = False,
+    use_cache = False}
+Module: \module{pyvolution.util}
+
+Reads the time history of spatial data for
+specified interpolation points from a NetCDF file (\code{filename})
+and returns
+a callable object. \code{filename} could be a \code{sww} file.
+Returns interpolated values based on the input
+file using the underlying \code{interpolation\_function}.
+
+\code{quantities} is either the name of a single quantity to be
+interpolated or a list of such quantity names. In the second case, the resulting
+function will return a tuple of values---one for each quantity.
+
+\code{interpolation\_points} is a list of absolute UTM coordinates
+for points at which values are sought.
+
+The model time stored within the file function can be accessed using
+the method \code{f.get\_time()}
+\end{funcdesc}
+
+%%%
+\begin{classdesc}{Interpolation\_function}{self,
+    time,
+    quantities,
+    quantity_names = None,
+    vertex_coordinates = None,
+    triangles = None,
+    interpolation_points = None,
+    verbose = False}
+Module: \module{pyvolution.least\_squares}
+
+Given a time series (i.e. a series of values associated with
+different times), whose values are either just numbers or a set of
+numbers defined at the vertices of a triangular mesh (such as those
+stored in SWW files), \code{Interpolation\_function} is used to
+create a callable object that interpolates a value for an arbitrary
+time \code{t} within the model limits and possibly a point \code{(x,
+y)} within a mesh region.
+
+The actual time series at which data is available is specified by
+means of an array \code{time} of monotonically increasing times. The
+quantities containing the values to be interpolated are specified in
+an array---or dictionary of arrays (used in conjunction with the
+optional argument \code{quantity\_names}) --- called
+\code{quantities}. The optional arguments \code{vertex\_coordinates}
+and \code{triangles} represent the spatial mesh associated with the
+quantity arrays. If omitted the function created by
+\code{Interpolation\_function} will be a function of \code{t} only.
+
+Since, in practice, values need to be computed at specified points,
+the syntax allows the user to specify, once and for all, a list
+\code{interpolation\_points} of points at which values are required.
+In this case, the function may be called using the form \code{f(t,
+id)}, where \code{id} is an index for the list
+\code{interpolation\_points}.
+
+\end{classdesc}
+
+%%%
+%\begin{funcdesc}{set\_region}{functions}
+%[Low priority. Will be merged into set\_quantity]
+
+%Module:\module{pyvolution.domain}
+%\end{funcdesc}
+
+
+
+%%%%%%
+\section{Boundary Conditions}\index{boundary conditions}
+
+\anuga provides a large number of predefined boundary conditions,
+represented by objects such as \code{Reflective\_boundary(domain)} and
+\code{Dirichlet\_boundary([0.2, 0.0, 0.0])}, described in the examples
+in Chapter 2. Alternatively, you may prefer to ``roll your own'',
+following the method explained in Section \ref{sec:roll your own}.
+
+These boundary objects may be used with the function \code{set\_boundary} described below
+to assign boundary conditions according to the tags used to label boundary segments.
+
+\begin{methoddesc}{set\_boundary}{boundary_map}
+Module: \module{pyvolution.domain}
+
+This function allows you to assign a boundary object (corresponding to a
+pre-defined or user-specified boundary condition) to every boundary segment that
+has been assigned a particular tag.
+
+This is done by specifying a dictionary \code{boundary\_map}, whose values are the boundary objects
+and whose keys are the symbolic tags.
+
+\end{methoddesc}
+
+\begin{methoddesc} {get\_boundary\_tags}{}
+Module: \module{pyvolution.mesh}
+
+Returns a list of the available boundary tags.
+\end{methoddesc}
+
+%%%
+\subsection{Predefined boundary conditions}
+
+\begin{classdesc}{Reflective\_boundary}{Boundary}
+Module: \module{pyvolution.shallow\_water}
+
+Reflective boundary returns same conserved quantities as those present in
+the neighbouring volume but reflected.
+
+This class is specific to the shallow water equation as it works with the
+momentum quantities assumed to be the second and third conserved quantities.
+\end{classdesc}
+
+%%%
+\begin{classdesc}{Transmissive\_boundary}{domain = None}
+Module: \module{pyvolution.generic\_boundary\_conditions}
+
+A transmissive boundary returns the same conserved quantities as
+those present in the neighbouring volume.
+
+The underlying domain must be specified when the boundary is instantiated.
+\end{classdesc}
+
+%%%
+\begin{classdesc}{Dirichlet\_boundary}{conserved_quantities=None}
+Module: \module{pyvolution.generic\_boundary\_conditions}
+
+A Dirichlet boundary returns constant values for each of conserved
+quantities. In the example of \code{Dirichlet\_boundary([0.2, 0.0, 0.0])},
+the \code{stage} value at the boundary is 0.2 and the \code{xmomentum} and
+\code{ymomentum} at the boundary are set to 0.0. The list must contain
+a value for each conserved quantity.
+\end{classdesc}
+
+%%%
+\begin{classdesc}{Time\_boundary}{domain = None, f = None}
+Module: \module{pyvolution.generic\_boundary\_conditions}
+
+A time-dependent boundary returns values for the conserved
+quantities as a function \code{f(t)} of time. The user must specify
+the domain to get access to the model time.
+\end{classdesc}
+
+%%%
+\begin{classdesc}{File\_boundary}{Boundary}
+Module: \module{pyvolution.generic\_boundary\_conditions}
+
+This method may be used if the user wishes to apply a SWW file or
+a time series file to a boundary segment or segments.
+The boundary values are obtained from a file and interpolated to the
+appropriate segments for each conserved quantity.
+\end{classdesc}
+
+
+
+%%%
+\begin{classdesc}{Transmissive\_Momentum\_Set\_Stage\_boundary}{Boundary}
+Module: \module{pyvolution.shallow\_water}
+
+This boundary returns same momentum conserved quantities as
+those present in its neighbour volume but sets stage as in a Time\_boundary.
+The underlying domain must be specified when boundary is instantiated
+
+This type of boundary is useful when stage is known at the boundary as a
+function of time, but momenta (or speeds) aren't.
+
+This class is specific to the shallow water equation as it works with the
+momentum quantities assumed to be the second and third conserved quantities.
+\end{classdesc}
+
+
+
+\subsection{User-defined boundary conditions}
+\label{sec:roll your own}
+[How to roll your own] TBA
+
+
+
+
+
+\section{Forcing Functions}
+
+\anuga provides a number of predefined forcing functions to be used with .....
+
+%\begin{itemize}
+
+
+%  \item \indexedcode{}
+%  [function, arguments]
+
+%  \item \indexedcode{}
+
+%\end{itemize}
+
+
+
+\section{Evolution}\index{evolution}
+
+  \begin{methoddesc}{evolve}{yieldstep = None, finaltime = None, duration = None, skip_initial_step = False}
+
+  Module: \module{pyvolution.domain}
+
+  This function (a method of \class{domain}) is invoked once all the
+  preliminaries have been completed, and causes the model to progress
+  through successive steps in its evolution, storing results and
+  outputting statistics whenever a user-specified period
+  \code{yieldstep} is completed (generally during this period the
+  model will evolve through several steps internally
+  as the method forces the water speed to be calculated
+  on successive new cells). The user
+  specifies the total time period over which the evolution is to take
+  place, by specifying values (in seconds) for either \code{duration}
+  or \code{finaltime}, as well as the interval in seconds after which
+  results are to be stored and statistics output.
+
+  You can include \method{evolve} in a statement of the type:
+
+  {\small \begin{verbatim}
+      for t in domain.evolve(yieldstep, finaltime):
+          <Do something with domain and t>
+  \end{verbatim}}
+
+  \end{methoddesc}
+
+
+
+\subsection{Diagnostics}
+
+
+  \begin{funcdesc}{statistics}{}
+  Module: \module{pyvolution.domain}
+
+  \end{funcdesc}
+
+  \begin{funcdesc}{timestepping\_statistics}{}
+  Module: \module{pyvolution.domain}
+
+  Returns a string of the following type for each
+  timestep:
+
+  \code{Time = 0.9000, delta t in [0.00598964, 0.01177388], steps=12
+  (12)}
+
+  Here the numbers in \code{steps=12 (12)} indicate the number of steps taken and
+  the number of first-order steps, respectively.
+  \end{funcdesc}
+
+
+  \begin{funcdesc}{boundary\_statistics}{quantities = None, tags = None}
+  Module: \module{pyvolution.domain}
+
+  Returns a string of the following type when \code{quantities = 'stage'} and \code{tags = ['top', 'bottom']}:
+
+  {\small \begin{verbatim}
+ Boundary values at time 0.5000:
+    top:
+        stage in [ -0.25821218,  -0.02499998]
+    bottom:
+        stage in [ -0.27098821,  -0.02499974]
+  \end{verbatim}}
+
+  \end{funcdesc}
+
+
+  \begin{funcdesc}{get\_quantity}{name, location='vertices', indices = None}
+  Module: \module{pyvolution.domain}
+  Allow access to individual quantities and their methods
+
+  \end{funcdesc}
+
+
+  \begin{funcdesc}{get\_values}{location='vertices', indices = None}
+  Module: \module{pyvolution.quantity}
+
+  Extract values for quantity as an array
+
+  \end{funcdesc}
+
+
+  \begin{funcdesc}{get\_integral}{}
+  Module: \module{pyvolution.quantity}
+
+  Return computed integral over entire domain for this quantity
+
+  \end{funcdesc}
+
+
+\section{Other}
+
+  \begin{funcdesc}{domain.create\_quantity\_from\_expression}{???}
+
+  Handy for creating derived quantities on-the-fly.
+  See \file{Analytical\_solution\_circular\_hydraulic\_jump.py} for an example of use.
+  \end{funcdesc}
+
+
+
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\chapter{\anuga System Architecture}
+
+From pyvolution/documentation
+
+\section{File Formats}
+\label{sec:file formats}
+
+\anuga makes use of a number of different file formats. The
+following table lists all these formats, which are described in more
+detail in the paragraphs below.
+
+\bigskip
+
+\begin{center}
+
+\begin{tabular}{|ll|}  \hline
+
+\textbf{Extension} & \textbf{Description} \\
+\hline\hline
+
+\code{.sww} & NetCDF format for storing model output
+\code{f(t,x,y)}\\
+
+\code{.tms} & NetCDF format for storing time series \code{f(t)}\\
+
+\code{.xya} & ASCII format for storing arbitrary points and
+associated attributes\\
+
+\code{.pts} & NetCDF format for storing arbitrary points and
+associated attributes\\
+
+\code{.asc} & ASCII format of regular DEMs as output from ArcView\\
+
+\code{.prj} & Associated ArcView file giving more metadata for
+\code{.asc} format\\
+
+\code{.ers} & ERMapper header format of regular DEMs for ArcView\\
+
+\code{.dem} & NetCDF representation of regular DEM data\\
+
+\code{.tsh} & ASCII format for storing meshes and associated
+boundary and region info\\
+
+\code{.msh} & NetCDF format for storing meshes and associated
+boundary and region info\\
+
+\code{.nc} & Native ferret NetCDF format\\
+
+\code{.geo} & Houdinis ASCII geometry format (?) \\  \par \hline
+%\caption{File formats used by \anuga}
+\end{tabular}
+
+
+\end{center}
+
+The above table shows the file extensions used to identify the
+formats of files. However, typically, in referring to a format we
+capitalise the extension and omit the initial full stop---thus, we
+refer, for example, to `SWW files' or `PRJ files'.
+
+\bigskip
+
+A typical dataflow can be described as follows:
+
+\subsection{Manually Created Files}
+
+\begin{tabular}{ll}
+ASC, PRJ & Digital elevation models (gridded)\\
+NC & Model outputs for use as boundary conditions (e.g. from MOST)
+\end{tabular}
+
+\subsection{Automatically Created Files}
+
+\begin{tabular}{ll}
+ASC, PRJ  $\rightarrow$  DEM  $\rightarrow$  PTS & Convert
+DEMs to native \code{.pts} file\\
+
+NC $\rightarrow$ SWW & Convert MOST boundary files to
+boundary \code{.sww}\\
+
+PTS + TSH $\rightarrow$ TSH with elevation & Least squares fit\\
+
+TSH $\rightarrow$ SWW & Convert TSH to \code{.sww}-viewable using
+Swollen\\
+
+TSH + Boundary SWW $\rightarrow$ SWW & Simulation using
+\code{pyvolution}\\
+
+Polygonal mesh outline $\rightarrow$ & TSH or MSH
+\end{tabular}
+
+
+
+
+\bigskip
+
+\subsection{SWW and TMS Formats}
+
+The SWW and TMS formats are both NetCDF formats, and are of key
+importance for \anuga.
+
+An SWW file is used for storing \anuga output and therefore pertains
+to a set of points and a set of times at which a model is evaluated.
+It contains, in addition to dimension information, the following
+variables:
+
+\begin{itemize}
+    \item \code{x} and \code{y}: coordinates of the points, represented as Numeric arrays
+    \item \code{elevation}, a Numeric array storing bed-elevations
+    \item \code{volumes}, a list specifying the points at the vertices of each of the
+    triangles
+    % Refer here to the example to be provided in describing the simple example
+    \item \code{time}, a Numeric array containing times for model
+    evaluation
+\end{itemize}
+
+
+The contents of an SWW file may be viewed using the visualisation
+tool \code{swollen}, which creates an on-screen geometric
+representation. See section \ref{sec:swollen} (page
+\pageref{sec:swollen}) in Appendix \ref{ch:supportingtools} for more
+on \code{swollen}.
+
+Alternatively, there are tools, such as \code{ncdump}, that allow
+you to convert an NetCDF file into a readable format such as the
+Class Definition Language (CDL). The following is an excerpt from a
+CDL representation of the output file \file{bedslope.sww} generated
+from running the simple example \file{runup.py} of
+Chapter \ref{ch:getstarted}:
+
+\verbatiminput{examples/bedslopeexcerpt.cdl}
+
+The SWW format is used not only for output but also serves as input
+for functions such as \function{file\_boundary} and
+\function{file\_function}, described in Chapter \ref{ch:interface}.
+
+A TMS file is used to store time series data that is independent of
+position.
+
+
+\subsection{Mesh File Formats}
+
+A mesh file is a file that has a specific format suited to
+triangular meshes and their outlines. A mesh file can have one of
+two formats: it can be either a TSH file, which is an ASCII file, or
+an MSH file, which is a NetCDF file. A mesh file can be generated
+from the function \function{create\_mesh\_from\_regions} (see
+Section \ref{sec:meshgeneration}) and used to initialise a domain.
+
+A mesh file can define the outline of the mesh---the vertices and
+line segments that enclose the region in which the mesh is
+created---and the triangular mesh itself, which is specified by
+listing the triangles and their vertices, and the segments, which
+are those sides of the triangles that are associated with boundary
+conditions.
+
+In addition, a mesh file may contain `holes' and/or `regions'. A
+hole represents an area where no mesh is to be created, while a
+region is a labelled area used for defining properties of a mesh,
+such as friction values.  A hole or region is specified by a point
+and bounded by a number of segments that enclose that point.
+
+A mesh file can also contain a georeference, which describes an
+offset to be applied to $x$ and $y$ values---eg to the vertices.
+
+
+\subsection{Formats for Storing Arbitrary Points and Attributes}
+
+An XYA file is used to store data representing arbitrary numerical
+attributes associated with a set of points.
+
+The format for an XYA file is:\\
+%\begin{verbatim}
+
+            first line:     \code{[attribute names]}\\
+            other lines:  \code{x y [attributes]}\\
+
+            for example:\\
+            \code{elevation, friction}\\
+            \code{0.6, 0.7, 4.9, 0.3}\\
+            \code{1.9, 2.8, 5, 0.3}\\
+            \code{2.7, 2.4, 5.2, 0.3}
+
+        The first two columns are always implicitly assumed to be $x$, $y$ coordinates.
+        Use the same delimiter for the attribute names and the data.
+
+        An XYA file can optionally end with a description of the georeference:
+
+            \code{\#geo reference}\\
+            \code{56}\\
+            \code{466600.0}\\
+            \code{8644444.0}
+
+        Here the first number specifies the UTM zone (in this case zone 56)  and other numbers specify the
+        easting and northing
+        coordinates (in this case (466600.0, 8644444.0)) of the lower left corner.
+
+A PTS file is a NetCDF representation of the data held in an XYA
+file. If the data is associated with a set of $N$ points, then the
+data is stored using an $N \times 2$ Numeric array of float
+variables for the points and an $N \times 1$ Numeric array for each
+attribute.
+
+%\end{verbatim}
+
+\subsection{ArcView Formats}
+
+Files of the three formats ASC, PRJ and ERS are all associated with
+data from ArcView.
+
+An ASC file is an ASCII representation of DEM output from ArcView.
+It contains a header with the following format:
+
+\begin{tabular}{l l}
+\code{ncols}      &   \code{753}\\
+\code{nrows}      &   \code{766}\\
+\code{xllcorner}  &   \code{314036.58727982}\\
+\code{yllcorner}  & \code{6224951.2960092}\\
+\code{cellsize}   & \code{100}\\
+\code{NODATA_value} & \code{-9999}
+\end{tabular}
+
+The remainder of the file contains the elevation data for each grid point
+in the grid defined by the above information.
+
+A PRJ file is an ArcView file used in conjunction with an ASC file
+to represent metadata for a DEM.
+
+
+\subsection{DEM Format}
+
+A DEM file is a NetCDF representation of regular DEM data.
+
+
+\subsection{Other Formats}
+
+
+
+
+\subsection{Basic File Conversions}
+
+  \begin{funcdesc}{sww2dem}{basename_in, basename_out = None,
+            quantity = None,
+            timestep = None,
+            reduction = None,
+            cellsize = 10,
+            NODATA_value = -9999,
+            easting_min = None,
+            easting_max = None,
+            northing_min = None,
+            northing_max = None,
+            expand_search = False,
+            verbose = False,
+            origin = None,
+            datum = 'WGS84',
+            format = 'ers'}
+  Module: \module{pyvolution.data\_manager}
+
+  Takes data from an SWW file \code{basename_in} and converts it to DEM format (ASC or
+  ERS) of a desired grid size \code{cellsize} in metres.
+  The easting and northing values are used if the user wished to clip the output
+  file to a specified rectangular area. The \code{reduction} input refers to a function
+  to reduce the quantities over all time step of the SWW file, example, maximum.
+  \end{funcdesc}
+
+
+  \begin{funcdesc}{dem2pts}{basename_in, basename_out=None,
+            easting_min=None, easting_max=None,
+            northing_min=None, northing_max=None,
+            use_cache=False, verbose=False}
+  Module: \module{pyvolution.data\_manager}
+
+  Takes DEM data (a NetCDF file representation of data from a regular Digital
+  Elevation Model) and converts it to PTS format.
+  \end{funcdesc}
+
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\chapter{Basic \anuga Assumptions}
+
+(From pyvolution/documentation)
+
+
+Physical model time cannot be earlier than 1 Jan 1970 00:00:00.
+If one wished to recreate scenarios prior to that date it must be done
+using some relative time (e.g. 0).
+
+
+All spatial data relates to the WGS84 datum (or GDA94) and has been
+projected into UTM with false easting of 500000 and false northing of
+1000000 on the southern hemisphere (0 on the northern).
+
+It is assumed that all computations take place within one UTM zone.
+
+DEMs, meshes and boundary conditions can have different origins within
+one UTM zone. However, the computation will use that of the mesh for
+numerical stability.
+
+When generating a mesh it is assumed that polygons do not cross.
+Having polygons tht cross can cause the mesh generation to fail or bad
+meshes being produced.
+
+
+%OLD
+%The dataflow is: (See data_manager.py and from scenarios)
+%
+%
+%Simulation scenarios
+%--------------------%
+%%
+%
+%Sub directories contain scrips and derived files for each simulation.
+%The directory ../source_data contains large source files such as
+%DEMs provided externally as well as MOST tsunami simulations to be used
+%as boundary conditions.
+%
+%Manual steps are:
+%  Creation of DEMs from argcview (.asc + .prj)
+%  Creation of mesh from pmesh (.tsh)
+%  Creation of tsunami simulations from MOST (.nc)
+%%
+%
+%Typical scripted steps are%
+%
+%  prepare_dem.py:  Convert asc and prj files supplied by arcview to
+%                   native dem and pts formats%
+%
+%  prepare_pts.py: Convert netcdf output from MOST to an sww file suitable
+%                  as boundary condition%
+%
+%  prepare_mesh.py: Merge DEM (pts) and mesh (tsh) using least squares
+%                   smoothing. The outputs are tsh files with elevation data.%
+%
+%  run_simulation.py: Use the above together with various parameters to
+%                     run inundation simulation.
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\appendix
+
+\chapter{Supporting Tools}
+\label{ch:supportingtools}
+
+This section describes a number of supporting tools, supplied with \anuga, that offer a
+variety of types of functionality and enhance the basic capabilities of \anuga.
+
+\section{caching}
+\label{sec:caching}
+
+The \code{cache} function is used to provide supervised caching of function 
+results. A Python function call of the form
+
+      {\small \begin{verbatim}
+      result = func(arg1,...,argn)
+      \end{verbatim}}
+
+  can be replaced by
+
+      {\small \begin{verbatim}
+      from caching import cache
+      result = cache(func,(arg1,...,argn))
+      \end{verbatim}}
+
+  which returns the same output but reuses cached
+  results if the function has been computed previously in the same context.
+  \code{result} and the arguments can be simple types, tuples, list, dictionaries or
+  objects, but not unhashable types such as functions or open file objects.
+  The function \code{func} may be a member function of an object or a module.
+
+  This type of caching is particularly useful for computationally intensive
+  functions with few frequently used combinations of input arguments. Note that
+  if the inputs or output are very large caching may not save time because
+  disc access may dominate the execution time.
+
+  If the function definition changes after a result has been cached, this will be
+  detected by examining the functions \code{bytecode (co\_code, co\_consts,
+  func\_defaults, co\_argcount)} and the function will be recomputed.
+  However, caching will not detect changes in modules used by \code{func}.
+  In this case cache must be cleared manually.
+
+  Options are set by means of the function \code{set\_option(key, value)},
+  where \code{key} is a key associated with a
+  Python dictionary \code{options}. This dictionary stores settings such as the name of
+  the directory used, the maximum
+  number of cached files allowed, and so on.
+
+  The \code{cache} function allows the user also to specify a list of dependent files. If any of these
+  have been changed, the function is recomputed and the results stored again.
+
+  %Other features include support for compression and a capability to \ldots
+
+
+   \textbf{USAGE:} \nopagebreak
+
+    {\small \begin{verbatim}
+    result = cache(func, args, kwargs, dependencies, cachedir, verbose,
+                   compression, evaluate, test, return_filename)
+    \end{verbatim}}
+
+
+\section{swollen}
+\label{sec:swollen}
+ The output generated by \anuga may be viewed by
+means of the visualisation tool \code{swollen}, which takes the
+\code{SWW} file output by \anuga and creates a visual representation
+of the data. Examples may be seen in Figures \ref{fig:runupstart}
+and \ref{fig:bedslope2}. To view an \code{SWW} file with
+\code{swollen} in the Windows environment, you can simply drag the
+icon representing the file over an icon on the desktop for the
+\code{swollen} executable file (or a shortcut to it), or set up a
+file association to make files with the extension \code{.sww} open
+with \code{swollen}. Alternatively, you can operate \code{swollen}
+from the command line, in both Windows and Linux environments.
+
+On successful operation, you will see an interactive moving-picture
+display. You can use keys and the mouse to slow down, speed up or
+stop the display, change the viewing position or carry out a number
+of other simple operations. Help is also displayed when you press
+the \code{h} key.
+
+The main keys operating the interactive screen are:\\
+
+\begin{center}
+\begin{tabular}{|ll|}   \hline
+
+\code{w} & toggle wireframe \\
+
+space bar & start/stop\\
+
+up/down arrows & increase/decrease speed\\
+
+left/right arrows & direction in time \emph{(when running)}\\
+& step through simulation \emph{(when stopped)}\\
+
+left mouse button & rotate\\
+
+middle mouse button & pan\\
+
+right mouse button & zoom\\  \hline
+
+\end{tabular}
+\end{center}
+
+\vfill
+
+The following table describes how to operate swollen from the command line:
+
+Usage: \code{swollen [options] swwfile \ldots}\\  \nopagebreak
+Options:\\  \nopagebreak
+\begin{tabular}{ll}
+  \code{--display <type>} & \code{MONITOR | POWERWALL | REALITY\_CENTER |}\\
+                                    & \code{HEAD\_MOUNTED\_DISPLAY}\\
+  \code{--rgba} & Request a RGBA colour buffer visual\\
+  \code{--stencil} & Request a stencil buffer visual\\
+  \code{--stereo} & Use default stereo mode which is \code{ANAGLYPHIC} if not \\
+                                    & overridden by environmental variable\\
+  \code{--stereo <mode>} & \code{ANAGLYPHIC | QUAD\_BUFFER | HORIZONTAL\_SPLIT |}\\
+                                    & \code{VERTICAL\_SPLIT | LEFT\_EYE | RIGHT\_EYE |}\\
+                                     & \code{ON | OFF} \\
+  \code{-alphamax <float 0-1>} & Maximum transparency clamp value\\
+  \code{-alphamin <float 0-1>} & Transparency value at \code{hmin}\\
+\end{tabular}
+
+\begin{tabular}{ll}
+  \code{-cullangle <float angle 0-90>} & Cull triangles steeper than this value\\
+  \code{-help} & Display this information\\
+  \code{-hmax <float>} & Height above which transparency is set to
+                                     \code{alphamax}\\
+\end{tabular}
+
+\begin{tabular}{ll}
+
+  \code{-hmin <float>} & Height below which transparency is set to
+                                     zero\\
+\end{tabular}
+
+\begin{tabular}{ll}
+  \code{-lightpos <float>,<float>,<float>} & $x,y,z$ of bedslope directional light ($z$ is
+                                     up, default is overhead)\\
+\end{tabular}
+
+\begin{tabular}{ll}
+  \code{-loop}  & Repeated (looped) playback of \code{.swm} files\\
+
+\end{tabular}
+
+\begin{tabular}{ll}
+  \code{-movie <dirname>} & Save numbered images to named directory and
+                                     quit\\
+
+  \code{-nosky} & Omit background sky\\
+
+
+  \code{-scale <float>} & Vertical scale factor\\
+  \code{-texture <file>} & Image to use for bedslope topography\\
+  \code{-tps <rate>} & Timesteps per second\\
+  \code{-version} & Revision number and creation (not compile)
+                                     date\\
+\end{tabular}
+
+\section{utilities/polygons}
+
+  \declaremodule{standard}{utilities.polygon}
+  \refmodindex{utilities.polygon}
+
+  \begin{classdesc}{Polygon\_function}{regions, default = 0.0, geo_reference = None}
+  Module: \code{utilities.polygon}
+
+  Creates a callable object that returns one of a specified list of values when
+  evaluated at a point \code{x, y}, depending on which polygon, from a specified list of polygons, the
+  point belongs to. The parameter \code{regions} is a list of pairs
+  \code{(P, v)}, where each \code{P} is a polygon and each \code{v}
+  is either a constant value or a function of coordinates \code{x}
+  and \code{y}, specifying the return value for a point inside \code{P}. The
+  optional parameter \code{default} may be used to specify a value
+  for a point not lying inside any of the specified polygons. When a
+  point lies in more than one polygon, the return value is taken to
+  be the value for whichever of these polygon appears later in the
+  list.
+  %FIXME (Howard): CAN x, y BE VECTORS?
+
+  \end{classdesc}
+
+  \begin{funcdesc}{read\_polygon}{filename}
+  Module: \code{utilities.polygon}
+
+  Reads the specified file and returns a polygon. Each
+  line of the file must contain exactly two numbers, separated by a comma, which are interpreted
+  as coordinates of one vertex of the polygon.
+  \end{funcdesc}
+
+  \begin{funcdesc}{populate\_polygon}{polygon, number_of_points, seed = None, exclude = None}
+  Module: \code{utilities.polygon}
+
+  Populates the interior of the specified polygon with the specified number of points,
+  selected by means of a uniform distribution function.
+  \end{funcdesc}
+
+  \begin{funcdesc}{point\_in\_polygon}{polygon, delta=1e-8}
+  Module: \code{utilities.polygon}
+
+  Returns a point inside the specified polygon and close to the edge. The distance between
+  the returned point and the nearest point of the polygon is less than $\sqrt{2}$ times the
+  second argument \code{delta}, which is taken as $10^{-8}$ by default.
+  \end{funcdesc}
+
+  \begin{funcdesc}{inside\_polygon}{points, polygon, closed = True, verbose = False}
+  Module: \code{utilities.polygon}
+
+  Used to test whether the members of a list of points
+  are inside the specified polygon. Returns a Numeric
+  array comprising the indices of the points in the list that lie inside the polygon.
+  (If none of the points are inside, returns \code{zeros((0,), 'l')}.)
+  Points on the edges of the polygon are regarded as inside if
+  \code{closed} is set to \code{True} or omitted; otherwise they are regarded as outside.
+  \end{funcdesc}
+
+  \begin{funcdesc}{outside\_polygon}{points, polygon, closed = True, verbose = False}
+  Module: \code{utilities.polygon}
+
+  Exactly like \code{inside\_polygon}, but with the words `inside' and `outside' interchanged.
+  \end{funcdesc}
+
+  \begin{funcdesc}{is\_inside\_polygon}{point, polygon, closed=True, verbose=False}
+  Module: \code{utilities.polygon}
+
+  Returns \code{True} if \code{point} is inside \code{polygon} or
+  \code{False} otherwise. Points on the edges of the polygon are regarded as inside if
+  \code{closed} is set to \code{True} or omitted; otherwise they are regarded as outside.
+  \end{funcdesc}
+
+  \begin{funcdesc}{is\_outside\_polygon}{point, polygon, closed=True, verbose=False}
+  Module: \code{utilities.polygon}
+
+  Exactly like \code{is\_outside\_polygon}, but with the words `inside' and `outside' interchanged.
+  \end{funcdesc}
+
+  \begin{funcdesc}{point\_on\_line}{x, y, x0, y0, x1, y1}
+  Module: \code{utilities.polygon}
+
+  Returns \code{True} or \code{False}, depending on whether the point with coordinates
+  \code{x, y} is on the line passing through the points with coordinates \code{x0, y0}
+  and \code{x1, y1} (extended if necessary at either end).
+  \end{funcdesc}
+
+  \begin{funcdesc}{separate\_points\_by\_polygon}{points, polygon, closed = True, verbose = False}
+    \indexedcode{separate\_points\_by\_polygon}
+  Module: \code{utilities.polygon}
+
+  \end{funcdesc}
+
+  \begin{funcdesc}{polygon\_area}{polygon}
+  Module: \code{utilities.polygon}
+
+  Returns area of arbitrary polygon (reference http://mathworld.wolfram.com/PolygonArea.html)
+  \end{funcdesc}
+
+  \begin{funcdesc}{plot\_polygons}{polygons, figname, verbose = False}
+  Module: \code{utilities.polygon}
+
+  Plots each polygon contained in input polygon list, e.g.
+ \code{polygons = [poly1, poly2, poly3]} where \code{poly1 = [[x11,y11],[x12,y12],[x13,y13]]}
+ etc.  Each polygon is closed for plotting purposes and subsequent plot saved to \code{figname}.
+  Returns list containing the minimum and maximum of \code{x} and \code{y},
+  i.e. \code{[x_{min}, x_{max}, y_{min}, y_{max}]}.
+  \end{funcdesc}
+
+\section{coordinate\_transforms}
+
+\section{geospatial\_data}
+
+This describes a class that represents arbitrary point data in UTM
+coordinates along with named attribute values.
+
+%FIXME (Ole): This gives a LaTeX error
+%\declaremodule{standard}{geospatial_data}
+%\refmodindex{geospatial_data}
+
+
+
+\begin{classdesc}{Geospatial\_data}
+  {data_points = None,
+    attributes = None,
+    geo_reference = None,
+    default_attribute_name = None,
+    file_name = None}
+Module: \code{geospatial\_data}
+
+This class is used to store a set of data points and associated
+attributes, allowing these to be manipulated by methods defined for
+the class.
+
+The data points are specified either by reading them from a NetCDF
+or XYA file, identified through the parameter \code{file\_name}, or
+by providing their \code{x}- and \code{y}-coordinates in metres,
+either as a sequence of 2-tuples of floats or as an $M \times 2$
+Numeric array of floats, where $M$ is the number of points.
+Coordinates are interpreted relative to the origin specified by the
+object \code{geo\_reference}, which contains data indicating the UTM
+zone, easting and northing. If \code{geo\_reference} is not
+specified, a default is used.
+
+Attributes are specified through the parameter \code{attributes},
+set either to a list or array of length $M$ or to a dictionary whose
+keys are the attribute names and whose values are lists or arrays of
+length $M$. One of the attributes may be specified as the default
+attribute, by assigning its name to \code{default\_attribute\_name}.
+If no value is specified, the default attribute is taken to be the
+first one.
+\end{classdesc}
+
+
+\begin{methoddesc}{import\_points\_file}{delimiter = None, verbose = False}
+
+\end{methoddesc}
+
+
+\begin{methoddesc}{export\_points\_file}{ofile, absolute=False}
+
+\end{methoddesc}
+
+
+\begin{methoddesc}{get\_data\_points}{absolute = True}
+
+\end{methoddesc}
+
+
+\begin{methoddesc}{set\_attributes}{attributes}
+
+\end{methoddesc}
+
+
+\begin{methoddesc}{get\_attributes}{attribute_name = None}
+
+\end{methoddesc}
+
+
+\begin{methoddesc}{get\_all\_attributes}{}
+
+\end{methoddesc}
+
+
+\begin{methoddesc}{set\_default\_attribute\_name}{default_attribute_name}
+
+\end{methoddesc}
+
+
+\begin{methoddesc}{set\_geo\_reference}{geo_reference}
+
+\end{methoddesc}
+
+
+\begin{methoddesc}{add}{}
+
+\end{methoddesc}
+
+
+\section{pmesh GUI}
+ \emph{Pmesh}
+allows the user to set up the mesh of the problem interactively.
+It can be used to build the outline of a mesh or to visualise a mesh
+automatically generated.
+
+Pmesh will let the user select various modes. The current allowable
+modes are vertex, segment, hole or region.  The mode describes what
+sort of object is added or selected in response to mouse clicks.  When
+changing modes any prior selected objects become deselected.
+
+In general the left mouse button will add an object and the right
+mouse button will select an object.  A selected object can de deleted
+by pressing the the middle mouse button (scroll bar).
+
+\section{alpha\_shape}
+\emph{Alpha shapes} are used to generate close-fitting boundaries
+around sets of points. The alpha shape algorithm produces a shape
+that approximates to the `shape formed by the points'---or the shape
+that would be seen by viewing the points from a coarse enough
+resolution. For the simplest types of point sets, the alpha shape
+reduces to the more precise notion of the convex hull. However, for
+many sets of points the convex hull does not provide a close fit and
+the alpha shape usually fits more closely to the original point set,
+offering a better approximation to the shape being sought.
+
+In \anuga, an alpha shape is used to generate a polygonal boundary
+around a set of points before mesh generation. The algorithm uses a
+parameter $\alpha$ that can be adjusted to make the resultant shape
+resemble the shape suggested by intuition more closely. An alpha
+shape can serve as an initial boundary approximation that the user
+can adjust as needed.
+
+The following paragraphs describe the class used to model an alpha
+shape and some of the important methods and attributes associated
+with instances of this class.
+
+\begin{classdesc}{Alpha\_Shape}{points, alpha = None}
+Module: \code{alpha\_shape}
+
+To instantiate this class the user supplies the points from which
+the alpha shape is to be created (in the form of a list of 2-tuples
+\code{[[x1, y1],[x2, y2]}\ldots\code{]}, assigned to the parameter
+\code{points}) and, optionally, a value for the parameter
+\code{alpha}. The alpha shape is then computed and the user can then
+retrieve details of the boundary through the attributes defined for
+the class.
+\end{classdesc}
+
+
+\begin{funcdesc}{alpha\_shape\_via\_files}{point_file, boundary_file, alpha= None}
+Module: \code{alpha\_shape}
+
+This function reads points from the specified point file
+\code{point\_file}, computes the associated alpha shape (either
+using the specified value for \code{alpha} or, if no value is
+specified, automatically setting it to an optimal value) and outputs
+the boundary to a file named \code{boundary\_file}. This output file
+lists the coordinates \code{x, y} of each point in the boundary,
+using one line per point.
+\end{funcdesc}
+
+
+\begin{methoddesc}{set\_boundary\_type}{self,raw_boundary=True,
+                          remove_holes=False,
+                          smooth_indents=False,
+                          expand_pinch=False,
+                          boundary_points_fraction=0.2}
+Module: \code{alpha\_shape},  Class: \class{Alpha\_Shape}
+
+This function sets flags that govern the operation of the algorithm
+that computes the boundary, as follows:
+
+\code{raw\_boundary = True} returns raw boundary, i.e. the regular edges of the
+                alpha shape.\\
+\code{remove\_holes = True} removes small holes (`small' is defined by
+\code{boundary\_points\_fraction})\\
+\code{smooth\_indents = True} removes sharp triangular indents in
+boundary\\
+\code{expand\_pinch = True} tests for pinch-off and
+corrects---preventing a boundary vertex from having more than two edges.
+\end{methoddesc}
+
+
+\begin{methoddesc}{get\_boundary}{}
+Module: \code{alpha\_shape},  Class: \class{Alpha\_Shape}
+
+Returns a list of tuples representing the boundary of the alpha
+shape. Each tuple represents a segment in the boundary by providing
+the indices of its two endpoints.
+\end{methoddesc}
+
+
+\begin{methoddesc}{write\_boundary}{file_name}
+Module: \code{alpha\_shape},  Class: \class{Alpha\_Shape}
+
+Writes the list of 2-tuples returned by \code{get\_boundary} to the
+file \code{file\_name}, using one line per tuple.
+\end{methoddesc}
+
+\section{Numerical Tools}
+
+The following table describes some useful numerical functions that
+may be found in the module \module{utilities.numerical\_tools}:
+
+\begin{tabular}{|p{8cm} p{8cm}|}  \hline
+\code{angle(v1, v2=None)} & Angle between two-dimensional vectors
+\code{v1} and \code{v2}, or between \code{v1} and the $x$-axis if
+\code{v2} is \code{None}. Value is in range $0$ to $2\pi$. \\
+
+\code{normal\_vector(v)} & Normal vector to \code{v}.\\
+
+\code{mean(x)} & Mean value of a vector \code{x}.\\
+
+\code{cov(x, y=None)} & Covariance of vectors \code{x} and \code{y}.
+If \code{y} is \code{None}, returns \code{cov(x, x)}.\\
+
+\code{err(x, y=0, n=2, relative=True)} & Relative error of
+$\parallel$\code{x}$-$\code{y}$\parallel$ to
+$\parallel$\code{y}$\parallel$ (2-norm if \code{n} = 2 or Max norm
+if \code{n} = \code{None}). If denominator evaluates to zero or if
+\code{y}
+is omitted or if \code{relative = False}, absolute error is returned.\\
+
+\code{norm(x)} & 2-norm of \code{x}.\\
+
+\code{corr(x, y=None)} & Correlation of \code{x} and \code{y}. If
+\code{y} is \code{None} returns autocorrelation of \code{x}.\\
+
+\code{ensure\_numeric(A, typecode = None)} & Returns a Numeric array
+for any sequence \code{A}. If \code{A} is already a Numeric array it
+will be returned unaltered. Otherwise, an attempt is made to convert
+it to a Numeric array. (Needed because \code{array(A)} can
+cause memory overflow.)\\
+
+\code{histogram(a, bins, relative=False)} & Standard histogram. If
+\code{relative} is \code{True}, values will be normalised against
+the total and thus represent frequencies rather than counts.\\
+
+\code{create\_bins(data, number\_of\_bins = None)} & Safely create
+bins for use with histogram. If \code{data} contains only one point
+or is constant, one bin will be created. If \code{number\_of\_bins}
+is omitted, 10 bins will be created.\\  \hline
+
+\end{tabular}
+
+
+\chapter{Modules available in \anuga}
+
+
+\section{\module{pyvolution.general\_mesh} }
+\declaremodule[pyvolution.generalmesh]{}{pyvolution.general\_mesh}
+\label{mod:pyvolution.generalmesh}
+
+\section{\module{pyvolution.neighbour\_mesh} }
+\declaremodule[pyvolution.neighbourmesh]{}{pyvolution.neighbour\_mesh}
+\label{mod:pyvolution.neighbourmesh}
+
+\section{\module{pyvolution.domain} --- Generic module for 2D triangular domains for finite-volume computations of conservation laws}
+\declaremodule{}{pyvolution.domain}
+\label{mod:pyvolution.domain}
+
+
+\section{\module{pyvolution.quantity}}
+\declaremodule{}{pyvolution.quantity}
+\label{mod:pyvolution.quantity}
+
+
+Class Quantity - Implements values at each triangular element
+
+To create:
+
+   Quantity(domain, vertex_values)
+
+   domain: Associated domain structure. Required.
+
+   vertex_values: N x 3 array of values at each vertex for each element.
+                  Default None
+
+   If vertex_values are None Create array of zeros compatible with domain.
+   Otherwise check that it is compatible with dimenions of domain.
+   Otherwise raise an exception
+
+
+
+\section{\module{pyvolution.shallow\_water} --- 2D triangular domains for finite-volume
+computations of the shallow water wave equation. This module contains a specialisation
+of class Domain from module domain.py consisting of methods specific to the Shallow Water
+Wave Equation
+}
+\declaremodule[pyvolution.shallowwater]{}{pyvolution.shallow\_water}
+\label{mod:pyvolution.shallowwater}
+
+
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\chapter{Frequently Asked Questions}
+
+
+\section{General Questions}
+
+\subsubsection{What is \anuga?}
+
+\subsubsection{Why is it called \anuga?}
+
+\subsubsection{How do I obtain a copy of \anuga?}
+
+\subsubsection{What developments are expected for \anuga in the future?}
+
+\subsubsection{Are there any published articles about \anuga that I can reference?}
+
+\section{Modelling Questions}
+
+\subsubsection{Which type of problems are \anuga good for?}
+
+\subsubsection{Which type of problems are beyond the scope of \anuga?}
+
+\subsubsection{Can I start the simulation at an arbitrary time?}
+Yes, using \code{domain.set\_time()} you can specify an arbitrary
+starting time. This is for example useful in conjunction with a
+file\_boundary, which may start hours before anything hits the model
+boundary. By assigning a later time for the model to start,
+computational resources aren't wasted.
+
+\subsubsection{Can I change values for any quantity during the simulation?}
+Yes, using \code{domain.set\_quantity()} inside the domain.evolve
+loop you can change values of any quantity. This is for example
+useful if you wish to let the system settle for a while before
+assigning an initial condition. Another example would be changing
+the values for elevation to model e.g. erosion.
+
+\subsubsection{Can I change boundary conditions during the simulation?}
+Not sure, but it would be nice :-)
+
+\subsubsection{Why does a file\_function return a list of numbers when evaluated?}
+Currently, file\_function works by returning values for the conserved
+quantities \code{stage}, \code{xmomentum} and \code{ymomentum} at a given point in time
+and space as a triplet. To access e.g.\ \code{stage} one must specify element 0 of the
+triplet returned by file\_function.
+
+\subsubsection{Which diagnostics are available to troubleshoot a simulation?}
+
+\subsubsection{How do I use a DEM in my simulation?}
+You use \code{dem2pts} to convert your DEM to the required .pts format. This .pts file is then called
+when setting the elevation data to the mesh in \code{domain.set_quantity}
+
+\subsubsection{What sort of DEM resolution should I use?}
+Try and work with the \emph{best} you have available. Onshore DEMs
+are typically available in 25m, 100m and 250m grids. Note, offshore
+data is often sparse, or non-existent.
+
+\subsubsection{What sort of mesh resolution should I use?}
+The mesh resolution should be commensurate with your DEM - it does not make sense to put in place a mesh which is finer than your DEM. As an example,
+if your DEM is on a 25m grid, then the cell resolution should be of the order of 315$m^2$ (this represents half the area of the square grid). Ideally,
+you need a fine mesh over regions where the DEM changes rapidly, and other areas of significant interest, such as the coast.
+
+
+\subsubsection{How do I tag interior polygons?}
+At the moment create_mesh_from_regions does not allow interior
+polygons with symbolic tags. If tags are needed, the interior
+polygons must be created subsequently. For example, given a filename
+of polygons representing solid walls (in Arc Ungenerate format) can
+be tagged as such using the code snippet:
+\begin{verbatim}
+  # Create mesh outline with tags
+  mesh = create_mesh_from_regions(bounding_polygon,
+                                  boundary_tags=boundary_tags)
+  # Add buildings outlines with tags set to 'wall'. This would typically
+  # bind to a Reflective boundary
+  mesh.import_ungenerate_file(buildings_filename, tag='wall')
+
+  # Generate and write mesh to file
+  mesh.generate_mesh(maximum_triangle_area=max_area)
+  mesh.export_mesh_file(mesh_filename)
+\end{verbatim}
+
+Note that a mesh object is returned from \code{create_mesh_from_regions}
+when file name is omitted.
+
+\subsubsection{How often should I store the output?}
+This will depend on what you are trying to answer with your model and how much memory you have available on your machine. If you need
+to look in detail at the evolution, then you will need to balance your storage requirements and the duration of the simulation.
+If the SWW file exceeds 1Gb, another SWW file will be created until the end of the simulation. As an example, to store all the conserved
+quantities on a mesh with approximately 300000 triangles on a 2 min interval for 5 hours will result in approximately 350Mb SWW file
+(as for the \file{run\_sydney\_smf.py} example).
+
+\subsection{Boundary Conditions}
+
+\subsubsection{How do I create a Dirichlet boundary condition?}
+
+A Dirichlet boundary condition sets a constant value for the
+conserved quantities at the boundaries. A list containing
+the constant values for stage, xmomentum and ymomentum is constructed
+and used in the function call, e.g. \code{Dirichlet_boundary([0.2,0.,0.])}
+
+\subsubsection{How do I know which boundary tags are available?}
+The method \code{domain.get\_boundary\_tags()} will return a list of
+available tags for use with
+\code{domain.set\_boundary\_condition()}.
+
+
+
+
+
+\chapter{Glossary}
+
+\begin{tabular}{|lp{10cm}|c|}  \hline
+%\begin{tabular}{|llll|}  \hline
+    \emph{Term} & \emph{Definition} & \emph{Page}\\  \hline
+
+    \indexedbold{\anuga} & Name of software (joint development between ANU and
+    GA) & \pageref{def:anuga}\\
+
+    \indexedbold{bathymetry} & offshore elevation &\\
+
+    \indexedbold{conserved quantity} & conserved (stage, x and y
+    momentum) & \\
+
+%    \indexedbold{domain} & The domain of a function is the set of all input values to the
+%    function.&\\
+
+    \indexedbold{Digital Elevation Model (DEM)} & DEMs are digital files consisting of points of elevations,
+sampled systematically at equally spaced intervals.& \\
+
+    \indexedbold{Dirichlet boundary} & A boundary condition imposed on a differential equation
+ that specifies the values the solution is to take on the boundary of the
+ domain. & \pageref{def:dirichlet boundary}\\
+
+    \indexedbold{edge} & A triangular cell within the computational mesh can be depicted
+    as a set of vertices joined by lines (the edges). & \\
+
+    \indexedbold{elevation} & refers to bathymetry and topography &\\
+
+    \indexedbold{evolution} & integration of the shallow water wave equations
+    over time &\\
+
+    \indexedbold{finite volume method} & The method evaluates the terms in the shallow water
+    wave equation as fluxes at the surfaces of each finite volume. Because the
+    flux entering a given volume is identical to that leaving the adjacent volume,
+    these methods are conservative. Another advantage of the finite volume method is
+    that it is easily formulated to allow for unstructured meshes. The method is used
+    in many computational fluid dynamics packages. & \\
+
+    \indexedbold{forcing term} & &\\
+
+    \indexedbold{flux} & the amount of flow through the volume per unit
+    time & \\
+
+    \indexedbold{grid} & Evenly spaced mesh & \\
+
+    \indexedbold{latitude} & The angular distance on a mericlear north and south of the
+    equator, expressed in degrees and minutes. & \\
+
+    \indexedbold{longitude} & The angular distance east or west, between the meridian
+    of a particular place on Earth and that of the Prime Meridian (located in Greenwich,
+    England) expressed in degrees or time.& \\
+
+    \indexedbold{Manning friction coefficient} & &\\
+
+    \indexedbold{mesh} & Triangulation of domain &\\
+
+    \indexedbold{mesh file} & A TSH or MSH file & \pageref{def:mesh file}\\
+
+    \indexedbold{NetCDF} & &\\
+
+    \indexedbold{northing} & A rectangular (x,y) coordinate measurement of distance
+    north from a north-south reference line, usually a meridian used as the axis of
+    origin within a map zone or projection. Northing is a UTM (Universal Transverse
+    Mercator) coordinate. & \\
+
+    \indexedbold{points file} & A PTS or XYA file & \\  \hline
+
+    \end{tabular}
+
+    \begin{tabular}{|lp{10cm}|c|}  \hline
+
+    \indexedbold{polygon} & A sequence of points in the plane. \anuga represents a polygon
+    either as a list consisting of Python tuples or lists of length 2 or as an $N \times 2$
+    Numeric array, where $N$ is the number of points.
+
+    The unit square, for example, would be represented either as
+    \code{[ [0,0], [1,0], [1,1], [0,1] ]} or as \code{array( [0,0], [1,0], [1,1],
+    [0,1] )}.
+
+    NOTE: For details refer to the module \module{utilities/polygon.py}. &
+    \\     \indexedbold{resolution} &  The maximal area of a triangular cell in a
+    mesh & \\
+
+
+    \indexedbold{reflective boundary} & Models a solid wall. Returns same conserved
+    quantities as those present in the neighbouring 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. & \pageref{def:reflective boundary}\\
+
+    \indexedbold{stage} & &\\
+
+%    \indexedbold{try this}
+
+    \indexedbold{swollen} & visualisation tool used with \anuga & \pageref{sec:swollen}\\
+
+    \indexedbold{time boundary} & Returns values for the conserved
+quantities as a function of time. The user must specify
+the domain to get access to the model time. & \pageref{def:time boundary}\\
+
+    \indexedbold{topography} & onshore elevation &\\
+
+    \indexedbold{transmissive boundary} & & \pageref{def:transmissive boundary}\\
+
+    \indexedbold{vertex} & A point at which edges meet. & \\
+
+    \indexedbold{xmomentum} & conserved quantity (note, two-dimensional SWW equations say
+    only \code{x} and \code{y} and NOT \code{z}) &\\
+
+    \indexedbold{ymomentum}  & conserved quantity & \\  \hline
+
+    \end{tabular}
+
+
+%The \code{\e appendix} markup need not be repeated for additional
+%appendices.
+
+
+%
+%  The ugly "%begin{latexonly}" pseudo-environments are really just to
+%  keep LaTeX2HTML quiet during the \renewcommand{} macros; they're
+%  not really valuable.
+%
+%  If you don't want the Module Index, you can remove all of this up
+%  until the second \input line.
+%
+
+%begin{latexonly}
+%\renewcommand{\indexname}{Module Index}
+%end{latexonly}
+\input{mod\jobname.ind}        % Module Index
+%
+%begin{latexonly}
+%\renewcommand{\indexname}{Index}
+%end{latexonly}
+\input{\jobname.ind}            % Index
+
+
+
+\begin{thebibliography}{99}
+\bibitem[nielsen2005]{nielsen2005} 
+{\it Hydrodynamic modelling of coastal inundation}.
+Nielsen, O., S. Roberts, D. Gray, A. McPherson and A. Hitchman.
+In Zerger, A. and Argent, R.M. (eds) MODSIM 2005 International Congress on
+Modelling and Simulation. Modelling and Simulation Society of Australia and
+New Zealand, December 2005, pp. 518-523. ISBN: 0-9758400-2-9.\\
+http://www.mssanz.org.au/modsim05/papers/nielsen.pdf
+
+
+
+
+\end{thebibliography}{99}
+
+\end{document}
Index: /anuga_core/documentation/user_manual/copyright.tex
===================================================================
--- /anuga_core/documentation/user_manual/copyright.tex	(revision 3574)
+++ /anuga_core/documentation/user_manual/copyright.tex	(revision 3574)
@@ -0,0 +1,99 @@
+%*************************************************
+%     LaTeX document
+%
+%  This is the ANUGA User Manual
+%
+%  Version 1.0    February, 2006
+%
+%
+%
+%  Copyright 2004, 2005, 2006
+%  Stephen Roberts, Australian National University
+%  Ole Nielsen, Duncan Gray, Jane Sexton, Nick Bartzis, Geoscience Australia
+%
+%  COPYRIGHT PAGE
+%
+%
+%*************************************************
+
+\vspace*{0.5in}
+
+Copyright \copyright 2004, 2005, 2006 Australian National University and Geoscience Australia. All rights reserved.
+
+
+Permission to use, copy, modify, and distribute this software for any
+purpose without fee is hereby granted under the terms of the GNU
+General Public License as published by the Free Software Foundation;
+either version 2 of the License, or (at your option) any later
+version, provided that this entire notice is included in all copies
+of any software which is or includes a copy or modification of this
+software and in all copies of the supporting documentation for such
+software.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License (\url{http://www.gnu.org/copyleft/gpl.html})
+for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program; if not, write to the Free Software
+Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307
+
+
+
+This work was produced at Geoscience Australia and the Australian
+National University funded by the Commonwealth of Australia. Neither
+the Australian Government, the Australian National University,
+Geoscience Australia nor any of their employees, makes any warranty,
+express or implied, or assumes any liability or responsibility for
+the accuracy, completeness, or usefulness of any information,
+apparatus, product, or process disclosed, or represents that its use
+would not infringe privately-owned rights. Reference herein to any
+specific commercial products, process, or service by trade name,
+trademark, manufacturer, or otherwise, does not necessarily
+constitute or imply its endorsement, recommendation, or favoring by
+the Australian Government, Geoscience Australia or the Australian
+National University.  The views and opinions of authors expressed
+herein do not necessarily state or reflect those of the Australian
+Government, Geoscience Australia or the Australian National
+University, and shall not be used for advertising or product
+endorsement purposes.
+
+
+This document does not convey a warranty, express or implied,
+of merchantability or fitness for a particular purpose.
+
+
+\begin{center}
+
+  %\vspace{0.5in}
+   \anuga
+
+   Manual typeset with \LaTeX
+
+\end{center}
+
+  \vspace{0.5in}
+
+\textbf{Credits}:
+\begin{itemize}
+\item \anuga was developed and is maintained by Stephen Roberts,
+  Ole Nielsen, Duncan Gray, Jane Sexton and Nick Bartzis.
+\index{ANUGA!credits|textit}  
+\end{itemize}
+
+
+
+\textbf{License}:
+\begin{itemize}
+\item \anuga is freely available and distributed under the terms of the GNU General Public Licence.\index{ANUGA!licence|textit}
+\end{itemize}
+
+
+
+\textbf{Acknowledgments}:
+\begin{itemize}
+\item Christopher Zoppou, Linda Stals, Matt Hardy, Jack Kelly, John Jakeman, Trevor Dhu, who contributed to this project at various times.
+\item A stand alone visualiser (Swollen viewer) based on Open-scene-graph was developed by Darran Edmundson.
+\end{itemize}
Index: /anuga_core/documentation/user_manual/datetime.sty
===================================================================
--- /anuga_core/documentation/user_manual/datetime.sty	(revision 3574)
+++ /anuga_core/documentation/user_manual/datetime.sty	(revision 3574)
@@ -0,0 +1,568 @@
+%%
+%% This is file `datetime.sty',
+%% generated with the docstrip utility.
+%%
+%% The original source files were:
+%%
+%% datetime.dtx  (with options: `datetime.sty,package')
+%% Copyright (C) 2005 Nicola Talbot, all rights reserved.
+%% If you modify this file, you must change its name first.
+%% You are NOT ALLOWED to distribute this file alone. You are NOT
+%% ALLOWED to take money for the distribution or use of either this
+%% file or a changed version, except for a nominal charge for copying
+%% etc.
+%% \CharacterTable
+%%  {Upper-case    \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
+%%   Lower-case    \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
+%%   Digits        \0\1\2\3\4\5\6\7\8\9
+%%   Exclamation   \!     Double quote  \"     Hash (number) \#
+%%   Dollar        \$     Percent       \%     Ampersand     \&
+%%   Acute accent  \'     Left paren    \(     Right paren   \)
+%%   Asterisk      \*     Plus          \+     Comma         \,
+%%   Minus         \-     Point         \.     Solidus       \/
+%%   Colon         \:     Semicolon     \;     Less than     \<
+%%   Equals        \=     Greater than  \>     Question mark \?
+%%   Commercial at \@     Left bracket  \[     Backslash     \\
+%%   Right bracket \]     Circumflex    \^     Underscore    \_
+%%   Grave accent  \`     Left brace    \{     Vertical bar  \|
+%%   Right brace   \}     Tilde         \~}
+\NeedsTeXFormat{LaTeX2e}
+\ProvidesPackage{datetime}[2005/09/30 v2.46 Date Time Package]
+\RequirePackage{fmtcount}
+\newif\if@dt@nodate
+\@dt@nodatefalse
+\newcommand{\dateseparator}{/}
+\newcommand{\ordinaldateenglish}[1]{\ordinalnum{#1}}
+\let\ordinaldatenohyphenation=\ordinaldateenglish
+
+\newcommand{\ordinaldatewelsh}[1]{%
+#1\ifnum#1=1\/\textsuperscript{a\~n}\fi}
+
+\newcommand{\ordinaldatebreton}[1]{%
+#1\ifnum#1=1\/\textsuperscript{a\~n}\fi}
+
+\newcommand{\ordinaldatefrench}[1]{%
+#1\ifnum#1=1\ier\fi}
+
+\newcommand{\ordinaldate}[1]{%
+\@ifundefined{languagename}{\ordinalnum{#1}}{%
+\@ifundefined{ordinaldate\languagename}{#1}{%
+\csname ordinaldate\languagename\endcsname{#1}}}}
+\newif\ifshowdow % show the day of week if true
+
+\providecommand{\formatdate}[3]{}
+
+\newcount\@day
+\newcount\@month
+\newcount\@year
+
+\DeclareRobustCommand*{\longdate}{%
+\renewcommand{\formatdate}[3]{\ifshowdow\dayofweekname{##1}{##2}{##3} \fi
+\@day=##1\relax\@month=##2\relax\@year=##3\relax
+\ordinaldate{\the\@day}\ \monthname[\@month], \the\@year}}
+
+\DeclareRobustCommand*{\shortdate}{%
+\renewcommand{\formatdate}[3]{\ifshowdow\shortdayofweekname{##1}{##2}{##3} \fi
+\@day=##1\relax\@month=##2\relax\@year=##3\relax
+\ordinaldate{\the\@day}\ \shortmonthname[\@month], \the\@year}}
+
+\providecommand*{\twodigit}[1]{{\@dtctr=#1\relax\ifnum\@dtctr<10 0\fi\the\@dtctr}}
+
+\DeclareRobustCommand*{\ddmmyyyydate}{%
+\renewcommand{\formatdate}[3]{\@day=##1\relax\@month=##2\relax\@year=##3\relax
+\twodigit\@day\dateseparator \twodigit\@month\dateseparator \the\@year}}
+
+\DeclareRobustCommand*{\dmyyyydate}{%
+\renewcommand{\formatdate}[3]{\@day=##1\relax\@month=##2\relax\@year=##3\relax
+\the\@day\dateseparator \the\@month\dateseparator \the\@year}}
+
+\DeclareRobustCommand*{\ddmmyydate}{\renewcommand{\formatdate}[3]{%
+\@day=##1\relax\@month=##2\relax\@year=##3\relax
+\@dtctr=\@year%
+\@modulo{\@dtctr}{100}%
+\twodigit\@day\dateseparator \twodigit\@month\dateseparator \twodigit\@dtctr}}
+
+\DeclareRobustCommand*{\dmyydate}{\renewcommand{\formatdate}[3]{%
+\@day=##1\relax\@month=##2\relax\@year=##3\relax
+\@dtctr=\@year%
+\@modulo{\@dtctr}{100}%
+\the\@day\dateseparator \the\@month\dateseparator \twodigit\@dtctr}}
+
+\DeclareRobustCommand*{\textdate}{%
+\renewcommand{\formatdate}[3]{\ifshowdow\dayofweekname{##1}{##2}{##3} the \fi
+\@day=##1\relax\@month=##2\relax\@year=##3\relax
+\@Ordinalstring\@day\ of \monthname[\@month], \@Numberstring\@year}}
+
+\DeclareRobustCommand*{\usdate}{%
+\renewcommand{\formatdate}[3]{\@day=##1\relax\@month=##2\relax\@year=##3\relax
+\monthname[\@month]\ \the\@day, \the\@year}}
+
+\DeclareRobustCommand*{\mmddyyyydate}{%
+\renewcommand{\formatdate}[3]{\@day=##1\relax\@month=##2\relax\@year=##3\relax
+\twodigit\@month\dateseparator \twodigit\@day\dateseparator \the\@year}}
+
+\DeclareRobustCommand*{\mdyyyydate}{%
+\renewcommand{\formatdate}[3]{\@day=##1\relax\@month=##2\relax\@year=##3\relax
+\the\@month\dateseparator \the\@day\dateseparator \the\@year}}
+
+\DeclareRobustCommand*{\mmddyydate}{\renewcommand{\formatdate}[3]{%
+\@day=##1\relax\@month=##2\relax\@year=##3\relax
+\@dtctr=\@year%
+\@modulo{\@dtctr}{100}%
+\twodigit\@month\dateseparator \twodigit\@day\dateseparator \twodigit\@dtctr}}
+
+\DeclareRobustCommand*{\mdyydate}{\renewcommand{\formatdate}[3]{%
+\@day=##1\relax\@month=##2\relax\@year=##3\relax
+\@dtctr=\@year%
+\@modulo{\@dtctr}{100}%
+\the\@month\dateseparator \the\@day\dateseparator \twodigit\@dtctr}}
+\newcommand{\newdate}[4]{%
+\@ifundefined{date@#1@y}{%
+\@namedef{date@#1@d}{#2}%
+\@namedef{date@#1@m}{#3}%
+\@namedef{date@#1@y}{#4}}{%
+\PackageError{datetime}{Date `#1' already defined}{}}}
+
+\newcommand{\getdateyear}[1]{%
+\@ifundefined{date@#1@y}{%
+\PackageError{datetime}{Date `#1' not defined}{}}{%
+\csname date@#1@y\endcsname}}
+
+\newcommand{\getdatemonth}[1]{%
+\@ifundefined{date@#1@m}{%
+\PackageError{datetime}{Date `#1' not defined}{}}{%
+\csname date@#1@m\endcsname}}
+
+\newcommand{\getdateday}[1]{%
+\@ifundefined{date@#1@d}{%
+\PackageError{datetime}{Date `#1' not defined}{}}{%
+\csname date@#1@d\endcsname}}
+
+\newcommand{\displaydate}[1]{%
+\@ifundefined{date@#1@y}{%
+\PackageError{datetime}{Date `#1' not defined}{}}{%
+\formatdate{\csname date@#1@d\endcsname}{%
+\csname date@#1@m\endcsname}{%
+\csname date@#1@y\endcsname}}}
+\DeclareRobustCommand*{\currenttime}{\xxivtime}
+
+\newcommand{\timeseparator}{:}
+
+\providecommand{\settimeformat}[1]{\DeclareRobustCommand*\currenttime{\csname#1\endcsname}}
+\longdate
+\showdowtrue
+\InputIfFileExists{datetime.cfg}{\typeout{Loading local datetime configurations}}{\typeout{No datetime.cfg file found}}
+\RequirePackage{fmtcount}
+\DeclareOption{long}{\longdate}
+\DeclareOption{short}{\shortdate}
+\DeclareOption{ddmmyyyy}{\ddmmyyyydate}
+\DeclareOption{dmyyyy}{\dmyyyydate}
+\DeclareOption{ddmmyy}{\ddmmyydate}
+\DeclareOption{dmyy}{\dmyydate}
+\DeclareOption{text}{\textdate}
+\DeclareOption{us}{\usdate}
+\DeclareOption{mmddyyyy}{\mmddyyyydate}
+\DeclareOption{mdyyyy}{\mdyyyydate}
+\DeclareOption{mmddyy}{\mmddyydate}
+\DeclareOption{mdyy}{\mdyydate}
+\DeclareOption{level}{\fmtcountsetoptions{fmtord=level}}
+\DeclareOption{raise}{\fmtcountsetoptions{fmtord=raise}}
+\DeclareOption{dayofweek}{\showdowtrue}
+\DeclareOption{nodayofweek}{\showdowfalse}
+\DeclareOption{nodate}{\@dt@nodatetrue}
+\DeclareOption{24hr}{\settimeformat{xxivtime}}
+\DeclareOption{12hr}{\settimeformat{ampmtime}}
+\DeclareOption{oclock}{\settimeformat{oclock}}
+
+
+\DeclareOption{austrian}{\input{dt-austrian.def}}
+\DeclareOption{bahasa}{\input{dt-bahasa.def}}
+\DeclareOption{basque}{\input{dt-basque.def}}
+\DeclareOption{breton}{\input{dt-breton.def}}
+\DeclareOption{bulgarian}{\input{dt-bulgarian.def}}
+\DeclareOption{catalan}{\input{dt-catalan.def}}
+\DeclareOption{croatian}{\input{dt-croatian.def}}
+\DeclareOption{czech}{\input{dt-czech.def}}
+\DeclareOption{danish}{\input{dt-danish.def}}
+\DeclareOption{dutch}{\input{dt-dutch.def}}
+\DeclareOption{esperanto}{\input{dt-esperanto.def}}
+\DeclareOption{estonian}{\input{dt-estonian.def}}
+\DeclareOption{finnish}{\input{dt-finnish.def}}
+\DeclareOption{french}{\input{dt-french.def}}
+\DeclareOption{galician}{\input{dt-galician.def}}
+\DeclareOption{german}{\input{dt-german.def}}
+\DeclareOption{greek}{\input{dt-greek.def}}
+\DeclareOption{hebrew}{\input{dt-hebrew.def}}
+\DeclareOption{icelandic}{\input{dt-icelandic.def}}
+\DeclareOption{irish}{\input{dt-irish.def}}
+\DeclareOption{italian}{\input{dt-italian.def}}
+\DeclareOption{latin}{\input{dt-latin.def}}
+\DeclareOption{lsorbian}{\input{dt-lsorbian.def}}
+\DeclareOption{magyar}{\input{dt-magyar.def}}
+\DeclareOption{naustrian}{\input{dt-naustrian.def}}
+\DeclareOption{ngerman}{\input{dt-ngerman.def}}
+\DeclareOption{norsk}{\input{dt-norsk.def}}
+\DeclareOption{polish}{\input{dt-polish.def}}
+\DeclareOption{portuges}{\input{dt-portuges.def}}
+\DeclareOption{romanian}{\input{dt-romanian.def}}
+\DeclareOption{russian}{\input{dt-russian.def}}
+\DeclareOption{samin}{\input{dt-samin.def}}
+\DeclareOption{scottish}{\input{dt-scottish.def}}
+\DeclareOption{serbian}{\input{dt-serbian.def}}
+\DeclareOption{slovak}{\input{dt-slovak.def}}
+\DeclareOption{slovene}{\input{dt-slovene.def}}
+\DeclareOption{spanish}{\input{dt-spanish.def}}
+\DeclareOption{swedish}{\input{dt-swedish.def}}
+\DeclareOption{turkish}{\input{dt-turkish.def}}
+\DeclareOption{ukraineb}{\input{dt-ukraineb.def}}
+\DeclareOption{usorbian}{\input{dt-usorbian.def}}
+\DeclareOption{welsh}{\input{dt-welsh.def}}
+
+\ProcessOptions
+\RequirePackage{ifthen}
+\if@dt@nodate
+\typeout{datetime package message : option "nodate" used, so not defining \protect\monthname}
+\else
+\providecommand{\monthnameenglish}[1][\month]{%
+\@orgargctr=#1\relax
+\ifcase\@orgargctr
+\PackageError{datetime}{Invalid Month number \the\@orgargctr}{Month numbers should go from 1 (January) to 12 (December)}%
+\or January%
+\or February%
+\or March%
+\or April%
+\or May%
+\or June%
+\or July%
+\or August%
+\or September%
+\or October%
+\or November%
+\or December%
+\else \PackageError{datetime}{Invalid Month number \the\@orgargctr}{Month numbers should go from 1 (January) to 12 (December)}%
+\fi}
+
+ %\let\monthname=\monthnameenglish
+\newcommand{\monthname}{\@ifundefined{languagename}{%
+\monthnameenglish}{\@ifundefined{monthname\languagename}{%
+\monthnameenglish}{\csname monthname\languagename\endcsname}}}
+\fi
+\if@dt@nodate
+\typeout{datetime package message : option "nodate" used, so not defining \protect\shortmonthname}
+\else
+\providecommand{\shortmonthnameenglish}[1][\month]{%
+\@orgargctr=#1\relax
+\ifcase\@orgargctr
+\PackageError{datetime}{Invalid Month number \the\@orgargctr}{Month numbers should go from 1 (jan) to 12 (dec)}%
+\or Jan%
+\or Feb%
+\or Mar%
+\or Apr%
+\or May%
+\or Jun%
+\or Jul%
+\or Aug%
+\or Sept%
+\or Oct%
+\or Nov%
+\or Dec%
+\else%
+\PackageError{datetime}{Invalid Month number \the\@orgargctr}{Month numbers should go from 1 (jan) to 12 (dec)}%
+\fi}
+
+ %\let\shortmonthname=\shortmonthnameenglish
+
+\newcommand{\shortmonthname}{\@ifundefined{languagename}{%
+\shortmonthnameenglish}{\@ifundefined{shortmonthname\languagename}{%
+\shortmonthnameenglish}{\csname shortmonthname\languagename\endcsname}}}
+\fi
+\newif\ifleapyear
+
+\newcount\@dtctr
+
+\if@dt@nodate
+\typeout{datetime package message : option "nodate" used, so not defining \protect\dayofweek \space or \protect\shortdayofweek}
+\else
+
+\providecommand{\testifleapyear}[1]{%
+\leapyearfalse
+\@year=#1\relax
+\@dtctr=\@year
+\@modulo{\@dtctr}{400}%
+\ifnum\@dtctr=0\relax
+\leapyeartrue %         year mod 400 = 0 => leap year
+\else
+\@dtctr=\@year
+\@modulo{\@dtctr}{100}%
+\ifnum\@dtctr=0\relax
+\leapyearfalse %        year mod 100 = 0 && year mod 400 != 0 => not a leap year
+\else
+\@dtctr=\@year
+\@modulo{\@dtctr}{4}%
+\ifnum\@dtctr=0\relax
+\leapyeartrue %         year mod 4 = 0 && year mod 100 != 0 => leap year
+\fi
+\fi
+\fi
+}
+
+\newcount\dayofyear
+
+
+\providecommand{\computedayofyear}[3]{%
+\testifleapyear{#3}%
+\dayofyear=0\relax
+\@day=#1\relax \@month=#2\relax \@year=#3\relax
+\ifcase\@month
+\or
+\or \advance\dayofyear by 31\relax
+\or \advance\dayofyear by 59\relax
+\or \advance\dayofyear by 90\relax
+\or \advance\dayofyear by 120\relax
+\or \advance\dayofyear by 151\relax
+\or \advance\dayofyear by 181\relax
+\or \advance\dayofyear by 212\relax
+\or \advance\dayofyear by 243\relax
+\or \advance\dayofyear by 273\relax
+\or \advance\dayofyear by 304\relax
+\or \advance\dayofyear by 334\relax
+\else
+\PackageError{datetime}{Invalid month number}{The second argument to \protect\computedayofyear
+should lie in the range 1-12}
+\fi
+\ifnum\@month>2\relax
+\ifleapyear\advance\dayofyear by 1\relax\fi
+\fi
+\advance\dayofyear by \@day\relax
+}
+
+\newcount\dayofweek
+
+
+\providecommand{\computedayofweek}[3]{%
+\computedayofyear{#1}{#2}{#3}%
+\@dtctr=#3\relax
+\advance\@dtctr by -1901\relax
+\@modulo{\@dtctr}{28}%
+\dayofweek=\@dtctr
+\divide\dayofweek by 4\relax
+\advance\dayofweek by \@dtctr
+\advance\dayofweek by 2\relax
+\@modulo{\dayofweek}{7}%
+\advance\dayofweek by \dayofyear
+\advance\dayofweek by -1\relax
+\@modulo{\dayofweek}{7}%
+\advance\dayofweek by 1\relax}
+
+\providecommand{\dayofweeknameidenglish}[1]{%
+\ifcase#1\relax
+\or Sunday%
+\or Monday%
+\or Tuesday%
+\or Wednesday%
+\or Thursday%
+\or Friday%
+\or Saturday%
+\fi}
+
+\providecommand{\dayofweeknameid}[1]{%
+\@ifundefined{languagename}{%
+\dayofweeknameidenglish{#1}}{%
+\@ifundefined{dayofweeknameid\languagename}{%
+\dayofweeknameidenglish{#1}}{%
+\csname dayofweeknameid\languagename\endcsname{#1}}}%
+}
+
+\providecommand{\dayofweekname}[3]{%
+\computedayofweek{#1}{#2}{#3}%
+\dayofweeknameid{\dayofweek}%
+}
+
+\providecommand{\thisdayofweekname}{%
+\dayofweekname{\day}{\month}{\year}}
+
+\providecommand{\shortdayofweeknameidenglish}[1]{%
+\ifcase#1\relax
+\or Sun%
+\or Mon%
+\or Tue%
+\or Wed%
+\or Thu%
+\or Fri%
+\or Sat%
+\fi}
+
+\providecommand{\shortdayofweekname}[3]{%
+\computedayofweek{#1}{#2}{#3}%
+\@ifundefined{languagename}{%
+\shortdayofweeknameidenglish{\dayofweek}}{%
+\@ifundefined{shortdayofweeknameid\languagename}{%
+\shortdayofweeknameidenglish{\dayofweek}}{%
+\csname shortdayofweeknameid\languagename\endcsname\dayofweek}}%
+}
+
+\fi
+
+\providecommand{\thisshortdayofweekname}{\dayofweekname{\day}{\month}{\year}}
+\if@dt@nodate
+\else
+\DeclareRobustCommand*{\today}{\formatdate{\day}{\month}{\year}}
+\fi
+\if@dt@nodate
+\else
+\@ifundefined{dateenglish}{}{\let\dateenglish\longdate}
+\@ifundefined{dateaustrian}{}{\input{dt-austrian.def}}
+\@ifundefined{datebahasa}{}{\input{dt-bahasa.def}}
+\@ifundefined{datebasque}{}{\input{dt-basque.def}}
+\@ifundefined{datebreton}{}{\input{dt-breton.def}}
+\@ifundefined{datebulgarian}{}{\input{dt-bulgarian.def}}
+\@ifundefined{datecatalan}{}{\input{dt-catalan.def}}
+\@ifundefined{datecroatian}{}{\input{dt-croatian.def}}
+\@ifundefined{dateczech}{}{\input{dt-czech.def}}
+\@ifundefined{datedanish}{}{\input{dt-danish.def}}
+\@ifundefined{datedutch}{}{\input{dt-dutch.def}}
+\@ifundefined{dateesperanto}{}{\input{dt-esperanto.def}}
+\@ifundefined{dateestonian}{}{\input{dt-estonian.def}}
+\@ifundefined{datefinnish}{}{\input{dt-finnish.def}}
+\@ifundefined{datefrench}{}{\input{dt-french.def}}
+\@ifundefined{dategalician}{}{\input{dt-galician.def}}
+\@ifundefined{dategerman}{}{\input{dt-german.def}}
+\@ifundefined{dategreek}{}{\input{dt-greek.def}}
+\@ifundefined{datehebrew}{}{\input{dt-hebrew.def}}
+\@ifundefined{dateicelandic}{}{\input{dt-icelandic.def}}
+\@ifundefined{dateirish}{}{\input{dt-irish.def}}
+\@ifundefined{dateitalian}{}{\input{dt-italian.def}}
+\@ifundefined{datelatin}{}{\input{dt-latin.def}}
+\@ifundefined{datelsorbian}{}{\input{dt-lsorbian.def}}
+\@ifundefined{datemagyar}{}{\input{dt-magyar.def}}
+\@ifundefined{datenaustrian}{}{\input{dt-naustrian.def}}
+\@ifundefined{datengerman}{}{\input{dt-ngerman.def}}
+\@ifundefined{datenorsk}{}{\input{dt-norsk.def}}
+\@ifundefined{datepolish}{}{\input{dt-polish.def}}
+\@ifundefined{dateportuges}{}{\input{dt-portuges.def}}
+\@ifundefined{dateromanian}{}{\input{dt-romanian.def}}
+\@ifundefined{daterussian}{}{\input{dt-russian.def}}
+\@ifundefined{datesamin}{}{\input{dt-samin.def}}
+\@ifundefined{datescottish}{}{\input{dt-scottish.def}}
+\@ifundefined{dateserbian}{}{\input{dt-serbian.def}}
+\@ifundefined{dateslovak}{}{\input{dt-slovak.def}}
+\@ifundefined{dateslovene}{}{\input{dt-slovene.def}}
+\@ifundefined{datespanish}{}{\input{dt-spanish.def}}
+\@ifundefined{dateswedish}{}{\input{dt-swedish.def}}
+\@ifundefined{dateturkish}{}{\input{dt-turkish.def}}
+\@ifundefined{dateukraineb}{}{\input{dt-ukraineb.def}}
+\@ifundefined{dateusorbian}{}{\input{dt-usorbian.def}}
+\@ifundefined{datewelsh}{}{\input{dt-welsh.def}}
+\fi
+\if@dt@nodate
+\typeout{datetime package message : option "nodate" used, so not defining \protect\newdateformat}
+\else
+
+\providecommand\THEDAY{\the\@day}
+\providecommand\THEMONTH{\the\@month}
+\providecommand\THEYEAR{\the\@year}
+\let\c@DAY=\@day
+\let\c@MONTH=\@month
+\let\c@YEAR=\@year
+
+\providecommand{\dateformat}[4]{\@day=#2\relax\@month=#3\relax\@year=#4\relax#1}
+
+\providecommand{\newdateformat}[2]{%
+\@ifundefined{#1}{\expandafter\DeclareRobustCommand\csname#1\endcsname{\renewcommand{\formatdate}{\dateformat{#2}}}}{%
+\PackageError{datetime}{Can't create new date format, command \textbackslash#1 already defined}{You will need to
+give you new date format a different name}}}
+\fi
+
+\newcount\c@HOUR
+\newcount\c@HOURXII
+\newcount\c@MINUTE
+\newcount\c@TOHOUR
+\newcount\c@TOMINUTE
+\def\THEHOUR{\the\c@HOUR}
+\def\THEHOURXII{\the\c@HOURXII}
+\def\THEMINUTE{\the\c@MINUTE}
+\def\THETOHOUR{\the\c@TOHOUR}
+\def\THETOMINUTE{\the\c@TOMINUTE}
+
+\providecommand{\newtimeformat}[2]{%
+\@ifundefined{#1}{%
+\expandafter\def\csname#1\endcsname{%
+\c@HOUR=\time%
+\divide\c@HOUR by 60\relax
+\c@HOURXII=\c@HOUR
+\ifnum\c@HOURXII>12
+\advance\c@HOURXII by -12\relax
+\fi
+\c@MINUTE=\time%
+\@modulo{\c@MINUTE}{60}%
+\c@TOHOUR=\c@HOURXII
+\advance\c@TOHOUR by 1\relax
+\@modulo{\c@TOHOUR}{12}%
+\c@TOMINUTE=\c@MINUTE
+\advance\c@TOMINUTE by -60\relax
+\multiply\c@TOMINUTE by -1\relax
+#2\relax
+}}{%
+\PackageError{datetime}{Command \textbackslash#1  already defined}{%
+You can't create a new time format called "#1" as the command \textbackslash#1 already exists}}}
+\newtimeformat{xxivtime}{\twodigit\THEHOUR\timeseparator\twodigit\THEMINUTE}
+
+\newtimeformat{ampmtime}{\THEHOURXII\timeseparator\twodigit\THEMINUTE\ifthenelse{\value{HOUR}<12}{\amname}{\ifthenelse{\time=720}{ \noon}{\pmname}}}
+
+\newtimeformat{oclock}{\ifthenelse{\time=0 \or \time=720}{%
+\ifthenelse{\time=0}{\midnight}{\noon}}{%
+\ifthenelse{\value{MINUTE}=0}{%
+\Numberstring{HOUR} \oclockstring}{%
+\ifthenelse{\value{MINUTE}=15}{%
+\quarterpast\ \Numberstring{HOUR}}{%
+\ifthenelse{\value{MINUTE}=30}{%
+\halfpast\ \Numberstring{HOUR}}{%
+\ifthenelse{\value{MINUTE}=45}{%
+\quarterto\ \Numberstring{TOHOUR}}{%
+\ifthenelse{\value{MINUTE}<30}{%
+\Numberstring{MINUTE}\ \ifthenelse{\value{MINUTE}=1}{minute}{minutes} past \Numberstring{HOURXII}}{%
+\Numberstring{TOMINUTE}\ \ifthenelse{\value{TOMINUTE}=1}{minute}{minutes} to \Numberstring{TOHOUR}}}}}}\
+\ifthenelse{\value{HOUR}<12}{%
+\amstring}{%
+\pmstring}}}
+
+\providecommand{\amname}{am}
+\providecommand{\pmname}{pm}
+\providecommand{\amorpmname}{\ifthenelse{\value{HOUR}>12}{\pmname}{\amname}}
+\providecommand{\amstring}{in the morning}
+\providecommand{\pmstring}{in the afternoon}
+\providecommand{\amorpmstring}{\ifthenelse{\value{HOUR}>12}{\pmstring}{\amstring}}
+\providecommand{\halfpast}{Half past}
+\providecommand{\quarterpast}{Quarter past}
+\providecommand{\quarterto}{Quarter to}
+\providecommand{\noon}{Noon}
+\providecommand{\midnight}{Midnight}
+\providecommand{\oclockstring}{O'Clock}
+
+\newcount\pdftimectr
+\newcount\pdfdatectr
+
+\pdftimectr=0\relax
+\@dtctr=\time%
+\divide\@dtctr by 60\relax
+\multiply\@dtctr by 10000\relax
+\pdftimectr=\@dtctr
+\@dtctr=\time%
+\@modulo{\@dtctr}{60}%
+\multiply\@dtctr by 100\relax
+\advance\pdftimectr by \@dtctr
+\pdfdatectr=\day
+\@dtctr=\month
+\multiply\@dtctr by 100\relax
+\advance\pdfdatectr by \@dtctr
+\@dtctr=\year
+\multiply\@dtctr by 10000\relax
+\advance\pdfdatectr by \@dtctr
+\ifnum\pdftimectr<100000
+\edef\pdfdate{\the\pdfdatectr0\the\pdftimectr}
+\else
+\edef\pdfdate{\the\pdfdatectr\the\pdftimectr}
+\fi
+\endinput
+%%
+%% End of file `datetime.sty'.
Index: /anuga_core/documentation/user_manual/definitions.tex
===================================================================
--- /anuga_core/documentation/user_manual/definitions.tex	(revision 3574)
+++ /anuga_core/documentation/user_manual/definitions.tex	(revision 3574)
@@ -0,0 +1,16 @@
+%Common definitions for the ANUGA documentation
+%
+
+\newcommand{\indexedcode}[1]{\code{#1}\indexascode{#1}}
+\newcommand{\indexascode}[1]{\index{#1@{\texttt {#1}}}}
+\newcommand{\indexedcodeheader}[1]{{\bigskip \large \bf \code{#1}}\indexascode{#1}\\}
+\newcommand{\indexedbold}[1]{\textbf{#1}\index{#1}}
+%\newcommand{\anuga}{\textbf{ANUGA}$^{\scriptscriptstyle \copyright}$ v1.0\ }
+\newcommand{\anuga}{\textbf{ANUGA} v1.0\ }
+%\newcommand{\anugav}[1]{\textbf{ANUGA}$^\copyright$ V#1\ }
+
+%Used with \code.
+%
+\newenvironment{displayedcode}
+   {\begin{tabular}{p{0.41cm}l}}
+   {\end{tabular}}  
Index: /anuga_core/documentation/user_manual/demtest.asc
===================================================================
--- /anuga_core/documentation/user_manual/demtest.asc	(revision 3574)
+++ /anuga_core/documentation/user_manual/demtest.asc	(revision 3574)
@@ -0,0 +1,16 @@
+ncols         10
+nrows         10
+xllcorner     2000
+yllcorner     3000
+cellsize      1
+NODATA_value  -9999
+0.000000 1.000000 2.000000 3.000000 4.000000 5.000000 6.000000 7.000000 8.000000 9.000000 
+10.000000 11.000000 12.000000 13.000000 14.000000 15.000000 16.000000 17.000000 18.000000 19.000000 
+20.000000 21.000000 22.000000 23.000000 24.000000 25.000000 26.000000 27.000000 28.000000 29.000000 
+30.000000 31.000000 32.000000 33.000000 34.000000 35.000000 36.000000 37.000000 38.000000 39.000000 
+40.000000 41.000000 42.000000 43.000000 44.000000 45.000000 46.000000 47.000000 48.000000 49.000000 
+50.000000 51.000000 52.000000 53.000000 54.000000 55.000000 56.000000 57.000000 58.000000 59.000000 
+60.000000 61.000000 62.000000 63.000000 64.000000 65.000000 66.000000 67.000000 68.000000 69.000000 
+70.000000 71.000000 72.000000 73.000000 74.000000 75.000000 76.000000 77.000000 78.000000 79.000000 
+80.000000 81.000000 82.000000 83.000000 84.000000 85.000000 86.000000 87.000000 88.000000 89.000000 
+90.000000 91.000000 92.000000 93.000000 94.000000 95.000000 96.000000 97.000000 98.000000 99.000000 
Index: /anuga_core/documentation/user_manual/demtest.prj
===================================================================
--- /anuga_core/documentation/user_manual/demtest.prj	(revision 3574)
+++ /anuga_core/documentation/user_manual/demtest.prj	(revision 3574)
@@ -0,0 +1,9 @@
+Projection UTM
+Zone 56
+Datum WGS84
+Zunits NO
+Units METERS
+Spheroid WGS84
+Xshift 0.0000000000
+Yshift 10000000.0000000000
+Parameters
Index: /anuga_core/documentation/user_manual/distutils.sty
===================================================================
--- /anuga_core/documentation/user_manual/distutils.sty	(revision 3574)
+++ /anuga_core/documentation/user_manual/distutils.sty	(revision 3574)
@@ -0,0 +1,33 @@
+%
+% LaTeX commands and macros needed for the two Distutils manuals,
+% inst.tex and dist.tex.
+%
+% $Id: distutils.sty,v 1.4 2000/04/19 22:40:34 gward Exp $
+%
+
+% My gripe list about the Python style files:
+%  * I want italics in verbatim environments for variable
+%    text (verbatim.sty?)
+%  * I hate escaping underscores (url.sty fixes this)
+
+% '\command' is for Distutils commands which, depending on your
+% perspective, are just arguments to the setup script, or sub-
+% commands of the setup script, or the classes that implement
+% each "command".
+\newcommand{\command}[1]{\code{#1}}
+
+% '\option' is for Distutils options *in* the setup script.  Command-
+% line options *to* the setup script are marked up in the usual
+% way, ie. with '\programopt' or '\longprogramopt'
+\newcommand{\option}[1]{\textsf{\small{#1}}}
+
+% '\filevar' is for variable components of file/path names -- eg.
+% when you put 'prefix' in a pathname, you mark it up with
+% '\filevar' so that it still looks pathname-ish, but is
+% distinguished from the literal part of the path.  Fred says
+% this can be accomplished just fine with '\var', but I violently
+% disagree.  Pistols at dawn will sort this one out.
+\newcommand{\filevar}[1]{{\textsl{\filenq{#1}}}}
+
+% Just while the code and docs are still under development.
+\newcommand{\XXX}[1]{\textbf{**#1**}}
Index: /anuga_core/documentation/user_manual/examples/bedslope.py
===================================================================
--- /anuga_core/documentation/user_manual/examples/bedslope.py	(revision 3574)
+++ /anuga_core/documentation/user_manual/examples/bedslope.py	(revision 3574)
@@ -0,0 +1,58 @@
+"""Simple example of shallow water wave equation using Pyvolution
+
+Water driven by linear slope and Dirichlet boundary
+
+"""
+
+######################
+# Module imports 
+#
+from anuga.pyvolution.mesh_factory import rectangular
+from anuga.pyvolution.shallow_water import Domain, Reflective_boundary,\
+     Dirichlet_boundary, Time_boundary, Transmissive_boundary
+
+#Create basic triangular mesh
+points, vertices, boundary = rectangular(2, 1)
+
+#Create shallow water domain
+domain = Domain(points, vertices, boundary)
+domain.set_name('bedslope')
+domain.set_datadir('.')                      #Use current directory for output
+domain.set_quantities_to_be_stored('stage')  #See shallow_water.py
+
+
+#######################
+# Initial conditions
+def f(x,y):
+    return -x/2
+
+domain.set_quantity('elevation', f)
+domain.set_quantity('friction', 0.1)
+
+h = 0.05  # Constant depth
+domain.set_quantity('stage', expression = 'elevation + %f' %h)
+
+
+######################
+# Boundary conditions
+from math import sin, pi
+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])
+
+
+print 'Tags are ', domain.get_boundary_tags()
+
+domain.set_boundary({'left': Bd, 'right': Br, 'top': Br, 'bottom': Br})
+#domain.set_boundary({'left': Bw, 'right': Br, 'top': Br, 'bottom': Br})
+
+
+######################
+#Evolution
+domain.check_integrity()
+
+for t in domain.evolve(yieldstep = 0.1, finaltime = 0.2):
+    domain.write_time()
+
Index: /anuga_core/documentation/user_manual/examples/bedslopeexcerpt.cdl
===================================================================
--- /anuga_core/documentation/user_manual/examples/bedslopeexcerpt.cdl	(revision 3574)
+++ /anuga_core/documentation/user_manual/examples/bedslopeexcerpt.cdl	(revision 3574)
@@ -0,0 +1,105 @@
+netcdf bedslope {
+dimensions:
+    number_of_volumes = 200 ;
+    number_of_vertices = 3 ;
+    number_of_points = 121 ;
+    number_of_timesteps = UNLIMITED ; // (41 currently)
+variables:
+    float x(number_of_points) ;
+    float y(number_of_points) ;
+    float elevation(number_of_points) ;
+    float z(number_of_points) ;
+    int volumes(number_of_volumes, number_of_vertices) ;
+    float time(number_of_timesteps) ;
+    float stage(number_of_timesteps, number_of_points) ;
+    float xmomentum(number_of_timesteps, number_of_points) ;
+    float ymomentum(number_of_timesteps, number_of_points) ;
+
+// global attributes:
+        :institution = "Geoscience Australia" ;
+        :description = "Output from pyvolution suitable for plotting" ;
+        :smoothing = "Yes" ;
+        :order = 1 ;
+        :starttime = 0 ;
+        :xllcorner = 0. ;
+        :yllcorner = 0. ;
+        :zone = 56 ;
+        :false_easting = 500000 ;
+        :false_northing = 10000000 ;
+        :datum = "wgs84" ;
+        :projection = "UTM" ;
+        :units = "m" ;
+data:
+
+ x = 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 
+    0.1, 0.1, 0.1, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 
+    0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.4, 0.4, 0.4, 
+    0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 
+    0.5, 0.5, 0.5, 0.5, 0.5, 0.6, 0.6, 0.6, 0.6, 0.6, 0.6, 0.6, 0.6, 0.6, 
+    0.6, 0.6, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.8, 
+    0.8, 0.8, 0.8, 0.8, 0.8, 0.8, 0.8, 0.8, 0.8, 0.8, 0.9, 0.9, 0.9, 0.9, 
+    0.9, 0.9, 0.9, 0.9, 0.9, 0.9, 0.9, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1 ;
+
+ y = 0, 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1, 0, 0.1, 0.2, 0.3, 
+    0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1, 0, 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 
+    0.8, 0.9, 1, 0, 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1, 0, 0.1, 
+    0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1, 0, 0.1, 0.2, 0.3, 0.4, 0.5, 
+    0.6, 0.7, 0.8, 0.9, 1, 0, 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1, 
+    0, 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1, 0, 0.1, 0.2, 0.3, 0.4, 
+    0.5, 0.6, 0.7, 0.8, 0.9, 1, 0, 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 
+    0.9, 1, 0, 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1 ;
+
+ elevation = 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, -0.05, -0.05, -0.05, -0.05, 
+    -0.05, -0.05, -0.05, -0.05, -0.05, -0.05, -0.05, -0.1, -0.1, -0.1, -0.1, 
+    -0.1, -0.1, -0.1, -0.1, -0.1, -0.1, -0.1, -0.15, -0.15, -0.15, -0.15, 
+    -0.15, -0.15, -0.15, -0.15, -0.15, -0.15, -0.15, -0.2, -0.2, -0.2, -0.2, 
+    -0.2, -0.2, -0.2, -0.2, -0.2, -0.2, -0.2, -0.25, -0.25, -0.25, -0.25, 
+    -0.25, -0.25, -0.25, -0.25, -0.25, -0.25, -0.25, -0.3, -0.3, -0.3, -0.3, 
+    -0.3, -0.3, -0.3, -0.3, -0.3, -0.3, -0.3, -0.35, -0.35, -0.35, -0.35, 
+    -0.35, -0.35, -0.35, -0.35, -0.35, -0.35, -0.35, -0.4, -0.4, -0.4, -0.4, 
+    -0.4, -0.4, -0.4, -0.4, -0.4, -0.4, -0.4, -0.45, -0.45, -0.45, -0.45, 
+    -0.45, -0.45, -0.45, -0.45, -0.45, -0.45, -0.45, -0.5, -0.5, -0.5, -0.5, 
+    -0.5, -0.5, -0.5, -0.5, -0.5, -0.5, -0.5 ;
+
+ z = 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, -0.05, -0.05, -0.05, -0.05, -0.05, 
+    -0.05, -0.05, -0.05, -0.05, -0.05, -0.05, -0.1, -0.1, -0.1, -0.1, -0.1, 
+    -0.1, -0.1, -0.1, -0.1, -0.1, -0.1, -0.15, -0.15, -0.15, -0.15, -0.15, 
+    -0.15, -0.15, -0.15, -0.15, -0.15, -0.15, -0.2, -0.2, -0.2, -0.2, -0.2, 
+    -0.2, -0.2, -0.2, -0.2, -0.2, -0.2, -0.25, -0.25, -0.25, -0.25, -0.25, 
+    -0.25, -0.25, -0.25, -0.25, -0.25, -0.25, -0.3, -0.3, -0.3, -0.3, -0.3, 
+    -0.3, -0.3, -0.3, -0.3, -0.3, -0.3, -0.35, -0.35, -0.35, -0.35, -0.35, 
+    -0.35, -0.35, -0.35, -0.35, -0.35, -0.35, -0.4, -0.4, -0.4, -0.4, -0.4, 
+    -0.4, -0.4, -0.4, -0.4, -0.4, -0.4, -0.45, -0.45, -0.45, -0.45, -0.45, 
+    -0.45, -0.45, -0.45, -0.45, -0.45, -0.45, -0.5, -0.5, -0.5, -0.5, -0.5, 
+    -0.5, -0.5, -0.5, -0.5, -0.5, -0.5 ;
+
+ volumes =
+  11, 12, 0,
+  1, 0, 12,
+  12, 13, 1,
+  2, 1, 13,
+  13, 14, 2,
+  3, 2, 14,
+  14, 15, 3,
+  4, 3, 15,
+  ...,
+  109, 108, 120 ;
+
+ time = 0, 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1, 1.1, 1.2, 1.3, 
+    1.4, 1.5, 1.6, 1.7, 1.8, 1.9, 2, 2.1, 2.2, 2.3, 2.4, 2.5, 2.6, 2.7, 2.8, 
+    2.9, 3, 3.1, 3.2, 3.3, 3.4, 3.5, 3.6, 3.7, 3.8, 3.9, 4 ;
+
+ stage =
+  0.025, 0.02777778, 0.02777778, 0.02777778, 0.02777778, 0.02777778, 
+    0.02777778, 0.02777778, 0.02777778, 0.02777778, 0.03333334, -0.01111111, 
+    5.782412e-019, 5.782412e-019, 5.782412e-019, 5.782412e-019, 
+    5.782412e-019, 5.782412e-019, 5.782412e-019, 5.782412e-019, 
+    ... 
+    -0.1654055, -0.1558442, -0.1504084 ;
+
+ xmomentum =
+  _, _, _, _, _, ,... _, _ ;
+
+ ymomentum =
+  _, _, _, _, _, ,... _, _ ;
+}
Index: /anuga_core/documentation/user_manual/examples/file_function_example.py
===================================================================
--- /anuga_core/documentation/user_manual/examples/file_function_example.py	(revision 3574)
+++ /anuga_core/documentation/user_manual/examples/file_function_example.py	(revision 3574)
@@ -0,0 +1,49 @@
+
+#Run bedslopephysical.py first then this
+#
+#Notice the statistics output
+
+from anuga.abstract_2d_finite_volumes.util import file_function
+ 
+f = file_function('bedslope.sww',
+                  quantities = ['stage',  #Quantities we want to interpolate
+                                'elevation',
+                                'xmomentum',
+                                'ymomentum'],
+                  interpolation_points = [ [0.0, 0.0], #Predefined points
+                                           [0.5, 0.5],
+                                           [0.8, 0.7]], 
+                  verbose = True)
+
+
+
+
+
+#Now try to call the function f
+
+#This gives all four quantities at time=1.2 and for predefined point
+#indexed 1  (which is 0.5, 0.5)
+print f(1.2, 1)
+
+
+#To get e.g. xmomentum one may index the output with its number (2)
+print f(1.2, 1)[2]   #xmomentum at time=1.2 and for point number 1
+
+
+#To get a timeseries (arbitrary times within the limits) for stage at point
+#[0.8, 0.7]  (index 2)
+
+t = 0.0
+tmax = 4.0  #From file_function statistics!
+
+print
+print 'Table of interpolated values of stage'
+print 't        f(t, 2)[0]'
+while t <= tmax:
+    print '%.4f  %.4f' %(t, f(t, 2)[0])
+    t += 0.1234
+
+    
+
+
+
Index: /anuga_core/documentation/user_manual/examples/harbour.py
===================================================================
--- /anuga_core/documentation/user_manual/examples/harbour.py	(revision 3574)
+++ /anuga_core/documentation/user_manual/examples/harbour.py	(revision 3574)
@@ -0,0 +1,171 @@
+"""Simple water flow example using ANUGA
+
+Water driven towards a continental slope and into a harbour
+environment. Set up as per:
+P.L.-F Liu 
+Effects of the Continental Shelf on Harbor Resonance, in
+Tsunamis - Their Science and Engineering,
+edited by K. Iida and T. Iwasaki, 303-314. 
+1983, Terra Scientific Publishing Company, Tokyo.
+
+"""
+
+#------------------------------------------------------------------------------
+# Import necessary modules
+#------------------------------------------------------------------------------
+
+from anuga.pmesh.mesh_interface import create_mesh_from_regions
+from anuga.shallow_water import Domain
+from anuga.shallow_water import Reflective_boundary
+from anuga.shallow_water import Dirichlet_boundary
+from anuga.shallow_water import Time_boundary
+from anuga.shallow_water import Transmissive_boundary
+
+waveheight = 1.0
+harbour_length = 2000.0 
+shelf_length = 10000.0
+bottom_length = 10000.0
+harbour_width = 250.0
+shelf_depth = -100. 
+harbour_depth = -10.
+if harbour_depth > shelf_depth: print 'WARNING: depths not consistent'
+#------------------------------------------------------------------------------
+# Setup computational domain
+#------------------------------------------------------------------------------
+
+east = 10000.+harbour_length+shelf_length+bottom_length
+west = 0.
+south = 0.
+north = 5000.
+polygon = [[east,north],[west,north],[west,south],[east,south]]
+meshname = 'harbour_test.msh'
+
+create_mesh_from_regions(polygon,
+                         boundary_tags={'top': [0],
+                                        'left': [1],
+                                        'bottom': [2],
+                                        'right': [3]},
+                         maximum_triangle_area=50000,
+                         filename=meshname)
+                         #interior_regions=interior_regions)
+
+domain = Domain(meshname,use_cache=True,verbose = True)
+domain.set_name('harbour')                  # Output to harbour.sww
+domain.set_datadir('.')                     # Use current directory for output
+domain.set_quantities_to_be_stored(['stage',# Store all conserved quantities
+                                    'xmomentum',
+                                    'ymomentum'])   
+
+
+#------------------------------------------------------------------------------
+# Setup initial conditions
+#------------------------------------------------------------------------------
+# if can't do this, then can set up x = arange(west,east,xstep)
+# and y = arange(south,north,ystep) and use Geospatial data to set elevation
+
+def topography(x,y):
+    from Numeric import zeros, Float
+    z = zeros(len(x), Float)
+    
+    xcentre = (west+east)/2.
+    ycentre = (south+north)/2.
+    ycentreup = ycentre+harbour_width/2.
+    ycentredown = ycentre-harbour_width/2.
+    for i, xi in enumerate(x):
+        yi = y[i]
+        if xi >= xcentre: z[i] = shelf_depth
+        if xi > west and xi <= xcentre-harbour_length: 
+            if yi < ycentredown: z[i] = 0.0
+            if yi > ycentreup: z[i] = 0.0
+            if yi > ycentredown and yi < ycentreup: z[i] = harbour_depth
+        if xi > xcentre-harbour_length and xi < xcentre: z[i] = harbour_depth
+        
+    return z
+
+domain.set_quantity('elevation', topography) # Use function for elevation
+domain.set_quantity('friction', 0. )         # Constant friction 
+domain.set_quantity('stage', 0.0)            # Constant initial stage
+
+#------------------------------------------------------------------------------
+# Setup boundary conditions
+#------------------------------------------------------------------------------
+
+from math import sin, pi
+Br = Reflective_boundary(domain)      # Solid reflective wall
+Bt = Transmissive_boundary(domain)    # Continue all values on boundary 
+Bd = Dirichlet_boundary([0.,0.,0.])   # Constant boundary values
+Bw = Time_boundary(domain=domain,     # Time dependent boundary  
+                   f=lambda t: [((10<t<20)*waveheight), 0.0, 0.0])
+
+# Associate boundary tags with boundary objects
+domain.set_boundary({'left': Br, 'right': Bw, 'top': Br, 'bottom': Br})
+
+#------------------------------------------------------------------------------
+# Evolve system through time
+#------------------------------------------------------------------------------
+
+stagestep = []
+for t in domain.evolve(yieldstep = 10, finaltime = 100.0):
+    domain.write_time()
+
+#-----------------------------------------------------------------------------
+# Interrogate solution
+#-----------------------------------------------------------------------------
+
+# Gauge line
+def gauge_line(west,east,north,south):
+    from Numeric import arange
+    gaugex = arange(east,west,-1000.)
+    gauges = []
+    gaugey = []
+    for x in gaugex:
+        y = (north+south)/2.
+        gaugey.append(y)
+        gauges.append([x,y])
+    return gauges, gaugex, gaugey
+
+gauges, gaugex, gaugey = gauge_line(west,east,north,south)
+
+from anuga.abstract_2d_finite_volumes.util import file_function
+
+f = file_function('harbour.sww',
+                  quantities = ['stage', 'elevation', 'xmomentum', 'ymomentum'],
+                  interpolation_points = gauges,
+                  verbose = True,
+                  use_cache = True)
+
+from pylab import plot, xlabel, ylabel, title, ion, close, savefig, figure
+ion()
+
+maxw = []
+minw = []
+maxd = []
+count = 0
+for k, g in enumerate(gauges):
+    stage = []
+    elevation = []
+    depths = []
+    for i, t in enumerate(f.get_time()):
+        w = f(t, point_id = k)[0]
+        elev = f(t, point_id = k)[1]
+        depth = w-elev
+        stage.append(w)
+        elevation.append(elev)
+        depths.append(elev)
+    maxw.append(max(stage))
+    minw.append(min(stage))
+    maxd.append(max(depths))
+
+filename = 'point'+str(waveheight)+'.csv'
+fid = open(filename,'w')    
+s = 'Waveheight,\n'
+fid.write(s)
+
+figure(1)
+plot(gaugex[:loc],maxw[:loc],'g-')
+xlabel('x')
+ylabel('stage')
+title('Maximum stage for gauge line')
+savefig('max_stage')
+
+close('all')
Index: /anuga_core/documentation/user_manual/examples/project.py
===================================================================
--- /anuga_core/documentation/user_manual/examples/project.py	(revision 3574)
+++ /anuga_core/documentation/user_manual/examples/project.py	(revision 3574)
@@ -0,0 +1,65 @@
+"""Common filenames and locations for topographic data, meshes and outputs.
+Also includes origin for slump scenario.
+"""
+
+from os import sep, environ
+from os.path import expanduser
+import sys
+
+# We'll do this for the final thing 
+home = '.'
+
+if sys.platform == 'win32':
+    home = environ['INUNDATIONHOME']     #Sandpit's parent dir
+else:    
+    home = expanduser('~')
+    
+basename = 'Sydney'
+
+#Setting the location of scenario data
+scenario_dir_name = 'sydney_tsunami_example_2006'
+# revised 100m data
+coarsename = 'bathyland100' 
+# revised 25m data
+finename = 'bathy_dem25'
+
+#Derive subdirectories and filenames
+meshdir = home+sep+scenario_dir_name+sep+'meshes'+sep
+datadir = home+sep+scenario_dir_name+sep+'topographies'+sep
+outputdir = home+sep+scenario_dir_name+sep+'output'+sep
+polygondir = home+sep+scenario_dir_name+sep+'polygons'+sep
+
+meshname = meshdir + basename
+coarsedemname = datadir + coarsename
+finedemname = datadir + finename
+combineddemname = datadir + 'sydneytopo'
+
+refzone = 56
+print 'refzone', refzone
+
+# demo poly 
+j0 = [385000, 6280000]
+j1 = [360000, 6272500]
+j2 = [335000, 6272500]
+j3 = [330000, 6265000]
+j31 = [325000, 6260000]
+j4 = [316000, 6260000]
+j5 = [316000, 6247000]
+j6 = [350000, 6247000]
+j7 = [385000, 6238000]
+
+demopoly = [j0, j1, j2, j3, j31, j4, j5, j6, j7]
+
+from utilities.polygon import read_polygon
+polygonptsfile4 = polygondir + 'poly1'
+polygonptsfile0 = polygondir + 'poly2'
+polygonptsfile1 = polygondir + 'poly3'
+polygonptsfile2 = polygondir + 'poly4'
+polygonptsfile3 = polygondir + 'poly5'
+northern_polygon = read_polygon(polygonptsfile0 + '.csv')
+manly_polygon = read_polygon(polygonptsfile1 + '.csv')
+harbour_polygon = read_polygon(polygonptsfile2 + '.csv')
+southern_polygon = read_polygon(polygonptsfile3 + '.csv')
+top_polygon = read_polygon(polygonptsfile4 + '.csv')
+
+slump_origin = [372500.0, 6255000.0] #Absolute UTM
Index: /anuga_core/documentation/user_manual/examples/runsydney.py
===================================================================
--- /anuga_core/documentation/user_manual/examples/runsydney.py	(revision 3574)
+++ /anuga_core/documentation/user_manual/examples/runsydney.py	(revision 3574)
@@ -0,0 +1,149 @@
+"""Script for running a tsunami inundation scenario for Sydney, NSW, Australia.
+
+Source data such as elevation and boundary data is assumed to be available in
+directories specified by project.py
+The output sww file is stored in project.outputdir 
+
+The scenario is defined by a triangular mesh created from project.polygon,
+the elevation data and a simulated submarine landslide.
+
+"""
+
+
+#------------------------------------------------------------------------------
+# Import necessary modules
+#------------------------------------------------------------------------------
+
+# Standard modules
+import os
+import time
+
+# Related major packages
+from anuga.shallow_water import Domain, Dirichlet_boundary
+from anuga.shallow_water.data_manager import convert_dem_from_ascii2netcdf, dem2pts
+from anuga.abstract_2d_finite_volumes.combine_pts import combine_rectangular_points_files 
+from anuga.pmesh.mesh_interface import create_mesh_from_regions
+
+# Application specific imports
+import project                           # Define file names and polygons
+from anuga.shallow_water.smf import slump_tsunami # Function for submarine mudslide 
+
+
+
+#------------------------------------------------------------------------------
+# Prepare bathymetric and topographic data
+#------------------------------------------------------------------------------
+
+# filenames
+coarsedemname = project.coarsedemname + '.pts'
+finedemname = project.finedemname + '.pts'
+combineddemname = project.combineddemname + '.pts'
+meshname = project.meshname+'.msh'
+
+
+# combining the coarse and fine data
+combine_rectangular_points_files(finedemname,
+                                 coarsedemname,
+                                 combineddemname)
+
+
+
+#------------------------------------------------------------------------------
+# Setup computational domain
+#------------------------------------------------------------------------------
+
+# Interior regions and mesh resolutions
+interior_res = 5000
+interior_regions = [[project.northern_polygon, interior_res],
+                    [project.harbour_polygon, interior_res],
+                    [project.southern_polygon, interior_res],
+                    [project.manly_polygon, interior_res],
+                    [project.top_polygon, interior_res]]
+
+
+create_mesh_from_regions(project.demopoly,
+                         boundary_tags= {'oceannorth': [0], 
+                                         'onshorenorth1': [1],
+                                         'onshorenorthwest1': [2],
+                                         'onshorenorthwest2': [3],
+                                         'onshorenorth2': [4],
+                                         'onshorewest': [5],
+                                         'onshoresouth': [6],
+                                         'oceansouth': [7],
+                                         'oceaneast': [8]},
+                         maximum_triangle_area=100000,
+                         filename=meshname,           
+                         interior_regions=interior_regions)
+
+
+#Create shallow water domain
+
+domain = Domain(meshname,
+                use_cache = True,
+                verbose = True)                                  
+
+
+print 'Number of triangles = ', len(domain)
+print 'The extent is ', domain.get_extent()
+
+domain.set_name(project.basename)
+domain.set_datadir(project.outputdir)
+domain.set_quantities_to_be_stored(['stage', 'xmomentum', 'ymomentum'])
+
+
+#------------------------------------------------------------------------------
+# Set up scenario (tsunami_source is a callable object used with set_quantity)
+#------------------------------------------------------------------------------
+
+tsunami_source = slump_tsunami(length=30000.0,
+                               depth=400.0,
+                               slope=6.0,
+                               thickness=176.0, 
+                               radius=3330,
+                               dphi=0.23,
+                               x0=project.slump_origin[0], 
+                               y0=project.slump_origin[1], 
+                               alpha=0.0, 
+                               domain=domain)
+
+
+#------------------------------------------------------------------------------
+# Setup initial conditions
+#------------------------------------------------------------------------------
+
+domain.set_quantity('stage', tsunami_source)
+domain.set_quantity('friction', 0.0) 
+domain.set_quantity('elevation',
+                    filename = combineddemname,
+                    use_cache = True,
+                    verbose = True)
+
+#------------------------------------------------------------------------------
+# Setup boundary conditions (all Dirichlet)
+#------------------------------------------------------------------------------
+
+print 'Available boundary tags', domain.get_boundary_tags()
+
+Bd = Dirichlet_boundary([0.0,0.0,0.0])
+domain.set_boundary( {'oceannorth': Bd,
+                      'onshorenorth1': Bd,
+                      'onshorenorthwest1': Bd,
+                      'onshorenorthwest2': Bd,
+                      'onshorenorth2': Bd,
+                      'onshorewest': Bd,
+                      'onshoresouth': Bd,
+                      'oceansouth': Bd,
+                      'oceaneast': Bd} )
+
+#------------------------------------------------------------------------------
+# Evolve system through time
+#------------------------------------------------------------------------------
+
+import time
+t0 = time.time()
+
+for t in domain.evolve(yieldstep = 60, finaltime = 7200):
+    print domain.timestepping_statistics()
+    print domain.boundary_statistics(tags = 'oceaneast')    
+    
+print 'That took %.2f seconds' %(time.time()-t0)
Index: /anuga_core/documentation/user_manual/examples/runup.py
===================================================================
--- /anuga_core/documentation/user_manual/examples/runup.py	(revision 3574)
+++ /anuga_core/documentation/user_manual/examples/runup.py	(revision 3574)
@@ -0,0 +1,70 @@
+"""Simple water flow example using ANUGA
+
+Water driven up a linear slope and time varying boundary,
+similar to a beach environment
+"""
+
+
+#------------------------------------------------------------------------------
+# Import necessary modules
+#------------------------------------------------------------------------------
+
+from anuga.abstract_2d_finite_volumes.mesh_factory import rectangular_cross
+from anuga.shallow_water import Domain
+from anuga.shallow_water import Reflective_boundary
+from anuga.shallow_water import Dirichlet_boundary
+from anuga.shallow_water import Time_boundary
+from anuga.shallow_water import Transmissive_boundary
+
+
+#------------------------------------------------------------------------------
+# Setup computational domain
+#------------------------------------------------------------------------------
+
+points, vertices, boundary = rectangular_cross(10, 10) # Basic mesh
+
+domain = Domain(points, vertices, boundary) # Create domain
+domain.set_name('runup')                    # Output to bedslope.sww
+domain.set_datadir('.')                     # Use current directory for output
+#domain.set_quantities_to_be_stored(['stage',# Store all conserved quantities
+#                                    'xmomentum',
+#                                    'ymomentum'])   
+
+
+#------------------------------------------------------------------------------
+# Setup initial conditions
+#------------------------------------------------------------------------------
+
+def topography(x,y):
+    return -x/2                             # linear bed slope
+    #return x*(-(2.0-x)*.5)                  # curved bed slope
+
+domain.set_quantity('elevation', topography) # Use function for elevation
+domain.set_quantity('friction', 0.1)         # Constant friction 
+domain.set_quantity('stage', -.4)            # Constant negative initial stage
+
+
+#------------------------------------------------------------------------------
+# Setup boundary conditions
+#------------------------------------------------------------------------------
+
+from math import sin, pi, exp
+Br = Reflective_boundary(domain)      # Solid reflective wall
+Bt = Transmissive_boundary(domain)    # Continue all values on boundary 
+Bd = Dirichlet_boundary([-0.2,0.,0.]) # Constant boundary values
+Bw = Time_boundary(domain=domain,     # Time dependent boundary  
+                   f=lambda t: [(.1*sin(t*2*pi)-0.3) * exp(-t), 0.0, 0.0])
+
+# Associate boundary tags with boundary objects
+domain.set_boundary({'left': Br, 'right': Bw, 'top': Br, 'bottom': Br})
+
+
+#------------------------------------------------------------------------------
+# Evolve system through time
+#------------------------------------------------------------------------------
+
+for t in domain.evolve(yieldstep = 0.1, finaltime = 10.0):
+    domain.write_time()
+    
+
+
Index: /anuga_core/documentation/user_manual/examples/runuptest.py
===================================================================
--- /anuga_core/documentation/user_manual/examples/runuptest.py	(revision 3574)
+++ /anuga_core/documentation/user_manual/examples/runuptest.py	(revision 3574)
@@ -0,0 +1,165 @@
+"""Simple water flow example using ANUGA
+
+Water driven up a linear slope and time varying boundary,
+similar to a beach environment
+"""
+
+
+#------------------------------------------------------------------------------
+# Import necessary modules
+#------------------------------------------------------------------------------
+
+from anuga.pmesh.mesh_interface import create_mesh_from_regions
+from anuga.shallow_water import Domain
+from anuga.shallow_water import Reflective_boundary
+from anuga.shallow_water import Dirichlet_boundary
+from anuga.shallow_water import Time_boundary
+from anuga.shallow_water import Transmissive_boundary
+
+
+#------------------------------------------------------------------------------
+# Setup computational domain
+#------------------------------------------------------------------------------
+
+waveheight = 1800.0
+depth_east_edge = -4000.
+timeend = 1000.0
+west = 0.
+east = 80000.
+south = 0.
+north = 5000.
+polygon = [[east,north],[west,north],[west,south],[east,south]]
+meshname = 'test.msh'
+
+create_mesh_from_regions(polygon,
+                         boundary_tags={'top': [0],
+                                        'left': [1],
+                                        'bottom': [2],
+                                        'right': [3]},
+                         maximum_triangle_area=200000,
+                         filename=meshname)
+                         #interior_regions=interior_regions)
+
+domain = Domain(meshname,use_cache=True,verbose = True)
+domain.set_name('test')                     # Output to test.sww
+domain.set_datadir('.')                     # Use current directory for output
+domain.set_quantities_to_be_stored(['stage',# Store all conserved quantities
+                                    'xmomentum',
+                                    'ymomentum'])   
+
+
+#------------------------------------------------------------------------------
+# Setup initial conditions
+#------------------------------------------------------------------------------
+
+def topography(x,y):
+    slope = depth_east_edge/((east-west)/2.)
+    c = -(west+east)/2.*slope
+    return slope*x+c                         # linear bed slope
+
+domain.set_quantity('elevation', topography) # Use function for elevation
+domain.set_quantity('friction', 0. )         # Constant friction 
+domain.set_quantity('stage', 0.0)            # Constant initial stage
+
+#------------------------------------------------------------------------------
+# Setup boundary conditions
+#------------------------------------------------------------------------------
+
+from math import sin, pi
+Br = Reflective_boundary(domain)      # Solid reflective wall
+Bt = Transmissive_boundary(domain)    # Continue all values on boundary 
+Bd = Dirichlet_boundary([0.,0.,0.])   # Constant boundary values
+Bw = Time_boundary(domain=domain,     # Time dependent boundary  
+                   f=lambda t: [((10<t<20)*waveheight), 0.0, 0.0])
+
+# Associate boundary tags with boundary objects
+domain.set_boundary({'left': Br, 'right': Bw, 'top': Br, 'bottom': Br})
+
+
+#------------------------------------------------------------------------------
+# Evolve system through time
+#------------------------------------------------------------------------------
+
+stagestep = []
+for t in domain.evolve(yieldstep = 10, finaltime = timeend):
+    domain.write_time()
+
+#-----------------------------------------------------------------------------
+# Interrogate solution
+#-----------------------------------------------------------------------------
+
+# Gauge line
+def gauge_line(west,east,north,south):
+    from Numeric import arange
+    gaugex = arange(west,(west+east)/2.,1000.)
+    gauges = []
+    gaugey = []
+    for x in gaugex:
+        y = (north+south)/2.
+        gaugey.append(y)
+        gauges.append([x,y])
+    return gauges, gaugex, gaugey
+
+gauges, gaugex, gaugey = gauge_line(west,east,north,south)
+
+from anuga.abstract_2d_finite_volumes.util import file_function
+
+f = file_function('test.sww',
+                  quantities = ['stage', 'elevation', 'xmomentum', 'ymomentum'],
+                  interpolation_points = gauges,
+                  verbose = True,
+                  use_cache = True)
+
+from pylab import plot, xlabel, ylabel, title, ion, close, savefig, figure, axis
+ion()
+
+maxw = []
+minw = []
+maxd = []
+count = 0
+for k, g in enumerate(gauges):
+    stage = []
+    elevation = []
+    depths = []
+    bed = topography(g[0],g[1])
+    for i, t in enumerate(f.get_time()):
+        w = f(t, point_id = k)[0]
+        elev = f(t, point_id = k)[1]
+        depth = w-elev
+        stage.append(w)
+        elevation.append(elev)
+        depths.append(elev)
+
+    if max(stage)-bed <= 0.2:
+        count+=1
+        posx=g[0]
+        loc = k  
+    maxw.append(max(stage))
+    minw.append(min(stage))
+    maxd.append(max(depths))
+    
+
+filename = 'maxrunup'+str(waveheight)+str(depth_east_edge)+'.csv'
+fid = open(filename,'w')    
+s = 'Depth at eastern boundary,Waveheight,Runup distance,Runup height\n'
+fid.write(s)
+runup_distance = posx 
+runup_height = topography(runup_distance,(north+south)/2.)
+print 'run up height:   ', runup_height 
+if runup_distance < (east+west)/2.:
+    runup_distance_from_coast = (east+west)/2.-runup_distance
+else:
+    runup_distance_from_coast = runup_distance-(east+west)/2.
+print 'run up distance from coastline: ', runup_distance_from_coast
+s = '%.2f,%.2f,%.2f,%.2f\n' %(depth_east_edge,waveheight,runup_distance_from_coast,runup_height)
+fid.write(s)
+
+figure(1)
+plot(gaugex,maxw,'g+',gaugex,topography(gaugex,(north+south)/2.),'r-')
+xlabel('x')
+ylabel('stage')
+title('Maximum stage for gauge line')
+#axis([33000, 47000, -1000, 3000])
+savefig('max_stage')
+
+close('all')
Index: /anuga_core/documentation/user_manual/fancybox.sty
===================================================================
--- /anuga_core/documentation/user_manual/fancybox.sty	(revision 3574)
+++ /anuga_core/documentation/user_manual/fancybox.sty	(revision 3574)
@@ -0,0 +1,982 @@
+%% BEGIN fancybox.sty
+%%
+%% With corrections and suggestions from:
+%%   - Marcin Wolinski <wolinski@melkor.mimuw.edu.pl>
+%%   - Heiko Oberdiek  <oberdiek@ruf.uni-freiburg.de>
+%%
+\def\fileversion{1.3}
+\def\filedate{2000/09/19}
+% DG/SR modification begin - September 19, 2000
+% (suggested by Heiko Oberdiek <oberdiek@ruf.uni-freiburg.de>)
+\@ifundefined{ProvidesPackage}{}{%
+  \ProvidesPackage{fancybox}[\filedate\space\fileversion]}
+% DG/SR modification end
+% DG/SR modification begin - May 16, 1997
+\providecommand\@begindvi{} % For rather old versions of LaTeX 2e
+% DG/SR modification end
+% DG/SR modification begin - Feb. 27, 1997
+% Now defined only in latex209.def
+\def\@lquote{\leavevmode{\kern\z@}`}
+% DG/SR modification end
+%%
+%% COPYRIGHT 1993, by Timothy Van Zandt, tvz@Princeton.EDU
+%%
+%% DESCRIPTION:
+%%   fancybox.sty is a LaTeX style option, consisting of:
+%%   * Variants of \fbox: \shadowbox, \doublebox, \ovalbox, \Ovalbox.
+%%   * Helpful tools for using box macros.
+%%   * Extensive documentation about how to use box macros.
+%%   * Flexible verbatim macros.
+%%
+%% INSTALLATION:
+%%   Put this file where your TeX looks for inputs.
+%%
+%% DOCUMENTATION:
+%%  See fancybox.doc, which might be appended to this file.
+%%
+%% COPYING:
+%%   The files of this package "fancybox" are released under the Artistic
+%%   License. A copy of that license is included in the file atristic.txt.
+%%   The package consists of the following files:
+%%     fancybox.doc
+%%     fancybox.sty
+%%
+%% CODE:
+\expandafter\ifx\csname fb@framepage\endcsname\relax\else
+  \expandafter\endinput
+\fi
+\typeout{Style option: `fancybox' v\fileversion \space  <\filedate> (tvz)}
+
+\newbox\@fancybox
+\@ifundefined{@tempdimc}{\newdimen\@tempdimc}{}
+
+%% \shadowbox
+
+\newdimen\shadowsize
+\shadowsize 4pt
+
+\def\shadowbox{\VerbBox\@shadowbox}
+\def\@shadowbox#1{%
+  \setbox\@fancybox\hbox{\fbox{#1}}%
+  \leavevmode\vbox{%
+    \offinterlineskip
+    \dimen@=\shadowsize
+    \advance\dimen@ .5\fboxrule
+    \hbox{\copy\@fancybox\kern-.5\fboxrule\lower\shadowsize\hbox{%
+      \vrule \@height\ht\@fancybox \@depth\dp\@fancybox \@width\dimen@}}%
+    \vskip-\dimen@
+    \moveright\shadowsize\vbox{%
+      \hrule \@width\wd\@fancybox \@height\dimen@}}}
+
+% \fancyoval
+
+\def\cornersize{\@ifstar{\@cornersize}{\@@cornersize}}
+\def\@cornersize#1{%
+  \@tempdima=#1\relax
+  \edef\the@cornersize{\number\@tempdima sp}}
+\def\@@cornersize#1{%
+  \edef\the@cornersize{#1\noexpand\@tempdimb}}
+\cornersize{.5}
+
+% This is just a simple change to \oval, making use of the \cornersize
+% parameter instead of making the corner arcs are large as possible.
+
+\def\fancyoval(#1,#2){\@ifnextchar[{\fancy@oval(#1,#2)}{\fancy@oval(#1,#2)[]}}
+
+\def\fancy@oval(#1,#2)[#3]{%
+  \begingroup
+    \fancy@@oval{#1\unitlength}{#2\unitlength}{#3}%
+    \@put{-.5\wd\@tempboxa}{-.5\ht\@tempboxa}{\ht\@tempboxa=\z@\box\@tempboxa}%
+  \endgroup}
+
+\def\fancy@@oval#1#2#3{%
+  \boxmaxdepth \maxdimen
+  \@ovttrue \@ovbtrue \@ovltrue \@ovrtrue
+  \@tfor\@tempa :=#3\do{\csname @ov\@tempa false\endcsname}%
+  \@ovxx#1\relax
+  \advance\@ovxx-\@wholewidth
+  \@ovyy#2\relax
+  \advance\@ovyy-\@wholewidth
+  \@tempdimb \ifdim \@ovyy >\@ovxx \@ovxx\else \@ovyy \fi
+  \advance\@tempdimb-2\p@
+  \ifdim\@tempdimb>\the@cornersize\relax
+    \@tempdimb=\the@cornersize
+  \fi
+  \@getcirc\@tempdimb
+  \@ovro\ht\@tempboxa \@ovri\dp\@tempboxa
+  \@ovdx\@ovxx \advance\@ovdx-\@tempdima \divide\@ovdx \tw@
+  \@ovdy\@ovyy \advance\@ovdy-\@tempdima \divide\@ovdy \tw@
+  \@circlefnt
+  \setbox\@tempboxa\hbox{%
+    \if@ovr \@ovvert32\kern -\@tempdima \fi
+    \if@ovl \kern \@ovxx \@ovvert01\kern -\@tempdima \kern -\@ovxx \fi
+    \if@ovt \@ovhorz \kern -\@ovxx \fi
+    \if@ovb \raise \@ovyy \@ovhorz \fi}%
+  \advance\@ovdx\@ovro
+  \advance\@ovdy\@ovro
+  \advance\@ovxx\@wholewidth
+  \wd\@tempboxa=\@ovxx
+  \dp\@tempboxa=\z@}
+
+% \ovalbox
+
+\def\ovalbox{\VerbBox{\@ovalbox\thinlines}}
+\def\Ovalbox{\VerbBox{\@ovalbox\thicklines}}
+\def\@ovalbox#1#2{%
+  \begingroup
+    #1\relax
+    \setbox\@fancybox\hbox{{#2}}%
+    \@tempdimc\fboxsep \advance\@tempdimc\@wholewidth
+    \@tempdima\ht\@fancybox \advance\@tempdima\dp\@fancybox
+    \advance\@tempdima2\@tempdimc
+    \@tempdimb\wd\@fancybox \advance\@tempdimb2\@tempdimc
+    \fancy@@oval\@tempdimb\@tempdima{}%
+    \@tempdima\dp\@fancybox \advance\@tempdima\@tempdimc
+    \wd\@tempboxa=\z@
+    \leavevmode\hbox{%
+      \lower\@tempdima\box\@tempboxa
+      \kern\@tempdimc\box\@fancybox\kern\@tempdimc}%
+  \endgroup}
+
+% \doublebox
+
+\def\doublebox{\VerbBox\@doublebox}
+\def\@doublebox#1{%
+  \begingroup
+    \setbox\@fancybox\hbox{{#1}}%
+    \fboxrule=.75\fboxrule
+    \setbox\@fancybox\hbox{\fbox{\box\@fancybox}}%
+    \fboxrule=2\fboxrule
+    \fboxsep=\fboxrule
+    \advance\fboxsep .5pt
+    \fbox{\box\@fancybox}%
+  \endgroup}
+
+% Frames for seminar.sty:
+
+\@ifundefined{newslideframe}{}{%
+  \newslideframe{shadow}{\shadowbox{#1}}
+  \newslideframe{double}{\doublebox{#1}}
+  \newslideframe{oval}{\ovalbox{#1}}
+  \newslideframe{Oval}{\Ovalbox{#1}}}
+
+% Sbox environment
+
+\newbox\@Sbox
+
+\def\Sbox{\global\setbox\@Sbox\hbox\bgroup\ignorespaces}
+
+\def\endSbox{%
+  \@testtrue\ifhmode\ifinner\@testfalse\fi\fi
+  \if@test\@latexerr{Misplaced \string\endSbox! Should be in LR mode}\@ehd\fi
+  \egroup}
+
+\def\TheSbox{%
+  \ifvoid\@Sbox
+    \@latexerr{\string\TheSbox\space is empty!}\@ehd
+  \else
+    \box\@Sbox
+  \fi}
+
+\def\beginsbox#1{\setbox#1\hbox\bgroup\ignorespaces}
+
+\def\endsbox{\endSbox}
+
+% \VerbBox
+
+\newtoks\do@VerbBox
+
+\def\VerbBox#1{%
+  \do@VerbBox{#1}%
+  \afterassignment\begin@VerbBox
+  \setbox\@fancybox=\hbox}
+\def\begin@VerbBox{\aftergroup\end@VerbBox}
+\def\end@VerbBox{\the\do@VerbBox{\box\@fancybox}}%
+
+% \Btrivlist
+
+\def\@Blistrestore{%
+  \let\par\relax
+  \let\-\@dischyph \let\'\@acci \let\`\@accii \let\=\@acciii
+  \lineskip\normallineskip \baselineskip\normalbaselineskip}
+
+\def\Btrivlist#1{\@ifnextchar[{\@Btrivlist{#1}}{\@Btrivlist{#1}[]}}
+\def\@Btrivlist#1[#2]{%
+  \@Blistrestore
+  \let\\=\@Btrivlistcr
+  \fb@beginvbox{#2}%
+  \halign\bgroup
+    \if#1l\else\@empty\hfil\fi
+    \ignorespaces##\unskip
+    \if#1r\@empty\else\hfil\fi\cr}
+\def\endBtrivlist{\crcr\egroup\egroup\if@pboxsw$\fi}
+
+\def\fb@beginvbox#1{%
+  \leavevmode
+  \@pboxswfalse
+  \if#1b\@empty\vbox\else\if#1t\@empty\vtop\else
+    \ifmmode\vcenter\else\@pboxswtrue$\vcenter\fi
+  \fi\fi\bgroup}
+
+\def\@Btrivlistcr{\@ifstar
+  {\@ifnextchar[{@@Btrivlistcr}{\cr}}{\@ifnextchar[{\@@Btrivlistcr}{\cr}}}
+\def\@@Btrivlistcr[#1]{\cr\noalign{\vskip #1}}
+
+\def\Bcenter{\Btrivlist{c}}
+\def\endBcenter{\endBtrivlist}
+
+\def\Bflushleft{\Btrivlist{l}}
+\def\endBflushleft{\endBtrivlist}
+
+\def\Bflushright{\Btrivlist{r}}
+\def\endBflushright{\endBtrivlist}
+
+% \Blist
+
+\def\Blist#1#2{\@ifnextchar[{\@Blist{#1}{#2}}{\@Blist{#1}{#2}[]}}
+
+\def\@Blist#1#2[#3]{%
+  \ifnum\@listdepth>5
+    \@toodeep
+  \else
+    \global\advance\@listdepth\@ne
+  \fi
+  \itemindent\z@
+  \csname @list\romannumeral\the\@listdepth\endcsname
+  \def\@itemlabel{#1}%
+  \let\makelabel\@mklab
+  \@nmbrlistfalse
+  \@Blistrestore
+  \let\\=\@Blistcr
+  \let\item\Bitem
+  \@Bitemswfalse
+  #2\relax
+  \fb@beginvbox{#3}%
+  \halign\bgroup
+    \ignorespaces##&\hskip\labelsep\ignorespaces##\unskip\hfil\cr}
+
+\def\endBlist{\endBtrivlist\global\advance\@listdepth\m@ne}
+
+\newif\if@Bitemsw
+
+\def\Bitem{\@ifnextchar({\@Bitemcr\Bitem@skip}{\@Bitemcr\@Bitem}}
+
+\def\@Bitemcr{%
+  \if@Bitemsw
+    \def\next{\cr\noalign{\vskip\itemsep}}%
+  \else
+    \def\next{\global\@Bitemswtrue}%
+  \fi
+  \next}
+
+\def\Bitem@skip(#1){\noalign{\vskip #1}\@Bitem}
+
+\def\@Bitem{\@ifnextchar[{\Bitem@label}{\Bitem@nolabel}}
+
+\def\Bitem@label[#1]{\makelabel{#1}&}
+
+\def\Bitem@nolabel{%
+  \if@nmbrlist
+    \expandafter\advance\csname c@\@listctr\endcsname1 \fi
+  \makelabel{\@itemlabel}%
+  &%
+  \if@nmbrlist\refstepcounter{\@listctr}\fi}
+
+\def\@Blistcr{\@ifstar
+  {\@ifnextchar[{@@Blistcr}{\cr&}}{\@ifnextchar[{\@@Blistcr}{\cr&}}}
+
+\def\@@Blistcr[#1]{\cr\noalign{\vskip #1}&}
+
+% \Bitemize
+
+\def\Bitemize{%
+  \ifnum\@itemdepth>3
+    \@toodeep
+  \else
+    \advance\@itemdepth\@ne
+  \fi
+  \edef\@itemitem{labelitem\romannumeral\the\@itemdepth}%
+  \Blist{\csname\@itemitem\endcsname}{\def\makelabel####1{\hfil####1}}}
+\def\endBitemize{\endBlist}
+
+% \Bdescription
+
+\def\Bdescription{\Blist{}{\def\makelabel####1{\bf####1\hfil}}}
+\def\endBdescription{\endBlist}
+
+% \Benumerate
+
+\def\Benumerate{%
+  \ifnum\@enumdepth>3
+    \@toodeep
+  \else
+    \advance\@enumdepth\@ne
+  \fi
+  \edef\@enumctr{enum\romannumeral\the\@enumdepth}%
+  \Blist{\csname label\@enumctr\endcsname}%
+    {\usecounter{\@enumctr}\def\makelabel####1{\hfil####1}}}
+\def\endBenumerate{\endBlist}
+
+% Beqnarray
+
+\def\Beqnarray{%
+  \stepcounter{equation}%
+  \let\@currentlabel\theequation
+  \def\@eqnnum{{\csname reset@font\endcsname\rm (\theequation)}}%
+  \global\@eqnswtrue\m@th
+  \global\@eqcnt\z@
+  \tabskip\@centering
+  \let\\\@eqncr
+  \vbox\bgroup
+    \halign\bgroup
+      \@eqnsel
+        \hskip\@centering
+        $\displaystyle\tabskip\z@{##}$%
+      &\global\@eqcnt\@ne
+        \hskip 2\arraycolsep
+        \hfil${##}$\hfil
+      &\global\@eqcnt\tw@
+        \hskip 2\arraycolsep
+        $\displaystyle\tabskip\z@{##}$%
+        \hfil
+        \tabskip\@centering
+      &\if@eqnsw\hskip 1em\fi
+        \hfil{##}\tabskip\z@
+      \cr}
+
+\def\endBeqnarray{%
+  \@@eqncr
+  \egroup
+  \global\advance\c@equation\m@ne
+  \egroup
+  \global\@ignoretrue}
+
+\@namedef{Beqnarray*}{\def\@eqncr{\nonumber\@seqncr}\Beqnarray}
+\@namedef{endBeqnarray*}{\nonumber\endBeqnarray}
+
+% \fb@outputage
+
+% Here we insert various hooks for rotating or framing the page.
+% Otherwise, it is the usual \@outputpage
+
+\def\fb@outputpage{%
+  \begingroup
+    \catcode`\ =10
+    \let\-\@dischyph
+    \let\'\@acci
+    \let\`\@accii
+    \let\=\@acciii
+    \if@specialpage
+      \global\@specialpagefalse\@nameuse{ps@\@specialstyle}%
+    \fi
+    \if@twoside
+      \ifodd\count\z@
+        \let\@thehead\@oddhead
+        \let\@thefoot\@oddfoot
+        \let\@themargin\oddsidemargin
+      \else
+        \let\@thehead\@evenhead
+        \let\@thefoot\@evenfoot
+        \let\@themargin\evensidemargin
+      \fi
+    \fi
+    \csname reset@font\endcsname
+    \normalsize
+    \baselineskip\z@
+    \lineskip\z@
+    \let\par\@@par
+    \ifx\this@fancypage\@empty\else
+      \this@fancypage
+      \gdef\this@fancypage{}%
+    \fi
+    \ifx\the@fancypage\@empty\else
+      \setbox\@outputbox\hbox{\the@fancypage{\box\@outputbox}}%
+    \fi
+    \ifx\fb@@rotatepage\@empty\else
+      \setbox\@outputbox\hbox{\fb@@rotatepage{\box\@outputbox}}%
+    \fi
+    \setbox\@outputbox\vbox{%
+      \@tempdima=\wd\@outputbox
+      \setbox\@tempboxa=\hbox to\@tempdima{%
+        \let\label\@gobble
+        \let\index\@gobble
+        \let\glossary\@gobble
+        \@thehead}%
+      \ht\@tempboxa\headheight
+      \dp\@tempboxa\z@
+      \box\@tempboxa
+      \vskip\headsep
+      \box\@outputbox
+      \baselineskip\footskip
+      \hbox to\@tempdima{%
+        \let\label\@gobble
+        \let\index\@gobble
+        \let\glossary\@gobble
+        \@thefoot}}
+    \ifx\the@@fancypage\@empty\else
+      \setbox\@outputbox\hbox{\the@@fancypage{\box\@outputbox}}%
+    \fi
+    \setbox\@outputbox\vbox{%
+      \ifnum\fancyput@flag>-1 \do@fancyput\fi
+      \vskip\topmargin
+      \moveright\@themargin\box\@outputbox}%
+    \ifx\fb@rotatepage\@empty\else
+       \setbox\@outputbox\hbox{\lower\ht\@outputbox\box\@outputbox}%
+       \dp\@outputbox\z@
+       \wd\@outputbox\z@
+       \setbox\@outputbox\hbox{\fb@rotatepage{\box\@outputbox}}%
+       \expandafter\fb@setoffsets\fb@theoffsets
+    \fi
+% DG/SR modification begin - September 19, 2000
+% (suggested by Marcin Wolinski <wolinski@melkor.mimuw.edu.pl> and
+%  Heiko Oberdiek <oberdiek@ruf.uni-freiburg.de>)
+    \let\protect\noexpand
+% DG/SR modification end
+    \shipout\box\@outputbox
+    \global\@colht\textheight
+  \endgroup
+  \stepcounter{page}%
+  \let\firstmark\botmark}
+
+% \fancypage
+
+\def\the@fancypage{}
+\def\the@@fancypage{}
+\def\this@fancypage{}
+
+\def\fancypage#1#2{%
+% DG/SR modification begin - May 16, 1997
+  \@begindvi                    % Need today by LaTeX 2e
+% DG/SR modification end
+  \def\the@fancypage{#1}%
+  \def\the@@fancypage{#2}%
+  \def\@outputpage{\fb@outputpage}}
+
+\def\thisfancypage#1#2{%
+% DG/SR modification begin - May 16, 1997
+  \@begindvi                    % Need today by LaTeX 2e
+% DG/SR modification end
+  \gdef\@outputpage{\fb@outputpage}%
+  \gdef\this@fancypage{\def\the@fancypage{#1}\def\the@@fancypage{#2}}}
+
+% \fancyput
+
+% Token registers used to make it easier to put definitions in argument.
+% Boxes not processed until output so that contents can depend, e.g., on
+% current page or marks or whatever. This makes everything slightly more
+% complicated than one would expect.
+
+\newtoks\the@fancyput
+\newtoks\this@fancyput
+\def\fancyput@flag{-1}%
+
+% \fancyput@flag=-1 if no fancyput, 0 if regular fancyput, 1 if thisfancyput.
+
+\def\fancyput{%
+% DG/SR modification begin - May 16, 1997
+  \@begindvi                    % Need today by LaTeX 2e
+% DG/SR modification end
+  \def\@outputpage{\fb@outputpage}
+  \@ifstar{\@testtrue\@fancyput}{\@testfalse\@fancyput}}
+\def\@fancyput{\@ifnextchar({\@@fancyput}{\@@fancyput(\z@,\z@)}}
+\def\@@fancyput(#1,#2)#3{%
+  \if@test
+    \expandafter\the@fancyput\expandafter{\the\the@fancyput\do{#1}{#2}{#3}}%
+  \else
+    \the@fancyput{\do{#1}{#2}{#3}}%
+  \fi
+  \gdef\fancyput@flag{\z@}}
+
+\def\thisfancyput{%
+% DG/SR modification begin - May 16, 1997
+  \@begindvi                    % Need today by LaTeX 2e
+% DG/SR modification end
+  \gdef\@outputpage{\fb@outputpage}
+  \@ifstar{\@testtrue\@thisfancyput}{\@testfalse\@thisfancyput}}
+\def\@thisfancyput{\@ifnextchar({\@@thisfancyput}{\@@thisfancyput(\z@,\z@)}}
+\def\@@thisfancyput(#1,#2)#3{%
+  \if@test
+    \ifnum\fancyput@flag=\z@
+      \expandafter\global\expandafter\this@fancyput\expandafter{%
+        \the\this@fancyput\do{#1}{#2}{#3}}%
+    \else
+      \expandafter\global\expandafter\this@fancyput\expandafter{%
+        \the\the@fancyput\do{#1}{#2}{#3}}%
+    \fi
+  \else
+    \global\this@fancyput{\do{#1}{#2}{#3}}%
+  \fi
+  \gdef\fancyput@flag{1}}
+
+\def\do@fancyput{%
+  \def\do##1##2##3{\raise##2\hbox to\z@{\kern##1\relax##3\hss}}%
+  \setbox\@tempboxa=\hbox to\z@{%
+    \kern-\hoffset
+    \raise\voffset\hbox{%
+      \ifnum\fancyput@flag=\z@\the\the@fancyput\else\the\this@fancyput\fi}%
+    \hss}%
+  \ht\@tempboxa=\z@ \dp\@tempboxa=\z@
+  \box\@tempboxa
+  \gdef\fancyput@flag{\z@}%
+  \global\this@fancyput{}}
+
+% \Landscape
+
+\def\UsePageParameters{%
+  \clearpage
+  \global\@colht\textheight
+  \onecolumn}
+
+\def\fb@rotatepage{}
+
+
+\def\Landscape{\@ifstar{\@testtrue\@Landscape}{\@testfalse\@Landscape}}
+\def\@Landscape#1#2#3{%
+% DG/SR modification begin - May 16, 1997
+  \@begindvi                    % Need today by LaTeX 2e
+% DG/SR modification end
+  \clearpage
+  \def\fb@rotatepage{#3}%
+  \def\@outputpage{\fb@outputpage}%
+  \@tempdima#1\relax
+  \@tempdimb#2\relax
+  \if@test
+    \edef\fb@theoffsets{{\voffset}{\hoffset}{\number\@tempdima sp}}%
+  \else
+    \edef\fb@theoffsets{{\hoffset}{\voffset}{\number\@tempdimb sp}}%
+  \fi
+  \advance\@tempdimb-\@tempdima
+  \advance\textwidth\@tempdimb
+  \advance\textheight-\@tempdimb
+  \UsePageParameters}
+\def\endLandscape{\clearpage\aftergroup\UsePageParameters}
+
+\def\fb@setoffsets#1#2#3{%
+  \@tempdima#1%
+  \advance#1#2%
+  #2#3
+  \advance#2-2in
+  \advance#2-\@tempdima}
+
+\@namedef{Landscape*}{\@testtrue\@Landscape}
+\@namedef{endLandscape*}{\endLandscape}
+
+% \LandScape
+
+\def\fb@@rotatepage{}
+
+\def\LandScape#1{%
+% DG/SR modification begin - May 16, 1997
+  \@begindvi                    % Need today by LaTeX 2e
+% DG/SR modification end
+  \clearpage
+  \def\fb@@rotatepage{#1}%
+  \def\@outputpage{\fb@outputpage}%
+  \@tempdima\textheight
+  \textheight\textwidth
+  \textwidth\@tempdima
+  \UsePageParameters}
+\def\endLandScape{\clearpage\aftergroup\UsePageParameters}
+
+% \GenericCaption
+
+\def\GenericCaption#1{%
+  \par
+  \begingroup
+    \@parboxrestore
+    \normalsize
+    \vskip 10\p@
+    \setbox\@tempboxa\hbox{#1}%
+    \ifdim\wd\@tempboxa>\hsize
+      #1\par
+    \else
+      \hbox to\hsize{\hfil\box\@tempboxa\hfil}%
+    \fi
+  \endgroup
+  \par}
+
+% \landfloat
+
+\def\landfloat#1#2{%
+  \gdef\curr@landfloat{#1}%
+  \gdef\float@rotation{#2}%
+  \begin{#1}[p]%
+    \setbox\@tempboxa\vbox\bgroup
+      \hsize\@colht
+      \@parboxrestore}
+\def\endlandfloat{%
+      \par\vskip\z@
+    \egroup
+    \setbox\@tempboxa\hbox{\float@rotation{\box\@tempboxa}}%
+    \centerline{\box\@tempboxa}%
+  \expandafter\end\expandafter{\curr@landfloat}}
+
+% \boxput
+
+\def\boxput{\@ifstar{\@testtrue\@boxput}{\@testfalse\@boxput}}
+\def\@boxput{\@ifnextchar({\@@boxput}{\@@boxput(0,0)}}
+\long\def\@@boxput(#1,#2)#3#4{%
+  \setbox\@fancybox\hbox{{#4}}%
+  \setbox\@tempboxa\vbox to\z@{\vss\hbox to\z@{\hss{#3}\hss}\vss}%
+  \@tempdima=#1\wd\@fancybox
+  \advance\@tempdima\wd\@fancybox
+  \divide\@tempdima 2
+  \ifcat a#2\relax
+    \@tempdimb=\z@
+  \else
+    \@tempdimb=.5\ht\@fancybox
+    \advance\@tempdimb.5\dp\@fancybox
+    \@tempdimc=\@tempdimb
+    \advance\@tempdimc-\dp\@fancybox
+    \@tempdimb=#2\@tempdimb
+    \advance\@tempdimb\@tempdimc
+  \fi
+  \setbox\@tempboxa\hbox to \z@{%
+    \if@test\kern-\wd\@fancybox\fi
+    \kern\@tempdima\raise\@tempdimb\box\@tempboxa\hss}%
+  \ht\@tempboxa=\z@ \dp\@tempboxa=\z@
+  \leavevmode
+  \if@test
+    \hbox{\box\@fancybox\box\@tempboxa}%
+  \else
+    \hbox{\box\@tempboxa\box\@fancybox}%
+  \fi}
+
+% \Vfootnotes
+
+\def\VerbatimFootnotes{\let\@footnotetext\V@footnotetext}
+
+\long\def\V@footnotetext{%
+  \afterassignment\V@@footnotetext
+  \let\@tempa}
+\def\V@@footnotetext{%
+  \insert\footins\bgroup
+  \csname reset@font\endcsname
+  \footnotesize
+  \interlinepenalty\interfootnotelinepenalty
+  \splittopskip\footnotesep
+  \splitmaxdepth\dp\strutbox
+  \floatingpenalty \@MM
+  \hsize\columnwidth
+  \@parboxrestore
+  \edef\@currentlabel{\csname p@footnote\endcsname\@thefnmark}%
+  \@makefntext{}%
+  \rule{\z@}{\footnotesep}%
+  \bgroup
+  \aftergroup\V@@@footnotetext
+  \ignorespaces}
+\def\V@@@footnotetext{\strut\egroup}
+
+% Verbatim
+
+% The main idea is to separate the reading and formatting of the
+% verbatim listing. It's pretty simple.
+
+\def\Verbatim@Codes{%
+  \let\do\@makeother
+  \dospecials
+  \Verbatim@ObeyThings
+  \ThisVerbCodes\relax\gdef\ThisVerbCodes{}}
+
+\def\EveryVerbatimCodes{}
+
+% \Verbatim is redefined temporarilly in \Get@Verbatim to scan the
+% verbatim text. \Verbatim is used so that error messages are more
+% enlightening. \next checks whether \Verbatim found its argument,
+% and attempts to recover if not.
+%
+% Heuristically, if current environment is `foo' and argument of
+% \Get@Verbatim is \The@Verbatim, then definition of \Verbatim is
+%
+% \def\Verbatim#1^^M#2^^M\the\EndVerbatimTokens\end{foo}{%
+%  \xdef\The@Verbatim{\noexpand\Every@VerbatimLine#2}%
+%  \endgroup\end{foo}}
+%
+% \The@Verbatim is then equal to the verbatim text, with spaces
+% replaced by \Verbatim@Space, tabs replaced by \Verbatim@Tab,
+% and ` replaced by \@lquote. In addition, each line begins with
+% \Every@VerbatimLine, and each line but the last ends with
+% \Verbatim@Par. It is then possible to redefine these when formatting
+% the verbatim text. To insert each line as an argument to \foo, use
+%   \def\Every@VerbatimLine#1\Verbatim@Par{\foo{#1}}
+%   \The@Verbatim\Verbatim@Par
+%
+\newtoks\EndVerbatimTokens
+\begingroup
+  \catcode`\|=0
+  \catcode`\[=1
+  \catcode`\]=2
+  \catcode`\{=12
+  \catcode`\}=12
+  \catcode`\^^M=13%
+  \catcode`\\=12%
+  |gdef|Get@Verbatim#1[%
+    |begingroup%
+      |Verbatim@Codes|EveryVerbatimCodes%
+      |let|protect|noexpand%
+      |VerbatimEnvironment%
+      |edef|next[|noexpand|def|noexpand|Verbatim####1|noexpand^^M####2%
+        |noexpand^^M|the|EndVerbatimTokens\end{|@VerbEnvir}]%
+      |edef|endVerbatim[|noexpand|endgroup|noexpand|end[|@VerbEnvir]]%
+      |global|let|@VerbEnvir|relax%
+      |next[|@nil|xdef#1[|noexpand|Every@VerbatimLine##2]|endVerbatim]%
+      |def|next[|@ifnextchar|@nil[|@gobble]%     If \@nil is there, then
+        [|gdef#1[]|endVerbatim|end[document]]]%  \Verbatim found its argument.
+      |expandafter|next|Verbatim]%               Otherwise, try to recover.
+  |gdef|AltGet@Verbatim#1[%
+    |begingroup%
+      |Verbatim@Codes|EveryVerbatimCodes%
+      |def^^M##1^^M##2[%
+        |ifx|@nil##2|@empty|else%
+          |noexpand|Verbatim@Par|noexpand|Every@VerbatimLine##1%
+          |expandafter^^M|expandafter##2%
+        |fi]%
+      |let|protect|noexpand%
+      |VerbatimEnvironment%
+      |edef|next[|noexpand|def|noexpand|Verbatim####1|noexpand^^M####2%
+        \end{|@VerbEnvir}]%
+      |edef|endVerbatim[|noexpand|endgroup|noexpand|end[|@VerbEnvir]]%
+      |global|let|@VerbEnvir|relax%
+      |next[|@nil|xdef#1[|noexpand|Every@VerbatimLine##2^^M|@nil]|endVerbatim]%
+      |def|next[|@ifnextchar|@nil[|@gobble]%
+        [|gdef#1[]|endVerbatim|end[document]]]%
+      |expandafter|next|Verbatim]%
+|endgroup
+\def\AltGetVerbatim{\let\Get@Verbatim\AltGet@Verbatim}
+
+% It is enough to not use \begin or \end when defining new verbatim
+% environments, as the default is for \Get@Verbatim to look for the
+% end of the current environment, but using \VerbatimEnvironment
+% is easier to explain to users.
+
+\def\VerbatimEnvironment{%
+  \ifx\@VerbEnvir\relax\xdef\@VerbEnvir{\@currenvir}\fi}
+
+\let\@VerbEnvir\relax
+
+\def\The@VerbatimErr{%
+  \gdef\The@Verbatim{\@latexerr{Misplaced \string\end{Verbatim}}\@ehd}}
+\The@VerbatimErr
+
+\begingroup
+\catcode`\^^M=\active%
+\catcode`\ =\active%
+\catcode`\^^I=\active%
+\gdef\Verbatim@ObeyThings{%
+\catcode`\^^M=\active%
+\catcode`\ =\active%
+\catcode`\^^I=\active%
+\catcode``=\active%
+\def^^M{\noexpand\Verbatim@Par\noexpand\Every@VerbatimLine}%
+\def^^I{\noexpand\Verbatim@Tab}%
+\def {\noexpand\Verbatim@Space}%
+\Verbatim@NoLigs}%
+\gdef\Verbatim@DontObeyLines{\outer\def^^M{}}%
+\endgroup
+
+\def\SaveVerbatim{\@bsphack\Get@Verbatim}
+
+\def\endSaveVerbatim{\@esphack}
+
+{\catcode``13 \gdef\Verbatim@NoLigs{\def`{\noexpand\@lquote}}}
+
+\def\Verbatim@Prep{%
+  \frenchspacing
+  \ThisVerb\relax\gdef\ThisVerb{}%
+  \VerbatimFont
+  \EveryVerbatim
+  \let\Every@VerbatimLine\EveryVerbatimLine
+  \def\Verbatim@Space{\leavevmode\penalty\@M\VerbatimSpace}%
+  \def\Verbatim@Tab{\leavevmode\penalty\@M\VerbatimTab}}%
+
+\def\Verb@Prep{%
+  \frenchspacing
+  \ThisVerb\relax\gdef\ThisVerb{}%
+  \VerbFont
+  \EveryVerb
+  \let\Every@VerbatimLine\EveryVerbatimLine
+  \def\Verbatim@Space{\leavevmode\penalty\@M\VerbSpace}%
+  \def\Verbatim@Tab{\leavevmode\penalty\@M\VerbTab}}%
+
+\def\Verbatim@Par{\leavevmode\null\@@par\penalty\interlinepenalty}
+
+% Parameter initialization:
+
+\def\VerbatimSpace{\ }
+
+{\catcode`\ =12\gdef\ttspace{{\tt }}}
+
+\def\VerbSpace{\ }
+
+\def\VerbatimTab{\ \ \ \ \ \ \ \ }
+
+\def\VerbTab{\ }
+
+\def\EveryVerbatim{}
+
+\def\EveryVerb{}
+
+\def\ThisVerb{}
+
+\def\EveryVerbatimLine{}%
+
+\def\EveryVerbOutLine{}
+
+\def\VerbatimFont{\tt}
+
+\def\VerbFont{\tt}
+
+\def\VerbatimFuzz{2pt}%
+
+\def\EveryVerbatimCodes{}
+
+\def\EveryVerbCodes{}
+
+\def\EveryVerbOutCodes{}
+
+\def\ThisVerbCodes{}
+
+\def\Verbatim@List#1{%
+  \if@minipage\else\vskip\parskip\fi
+  \leftskip\@totalleftmargin
+  \@rightskip\@flushglue \rightskip\@rightskip
+  \parindent\z@
+  \parskip\z@
+  \parfillskip\@flushglue
+  \hfuzz\VerbatimFuzz\relax
+  \@@par
+  \global\@inlabelfalse  %Prevents vspace from being inserted when
+  \Verbatim@Prep         %first line exceeds \hsize.
+  #1%
+  \Verbatim@Par}%
+
+\def\UseVerbatim#1{%
+  \begingroup\trivlist\item[]\Verbatim@List{#1}\endtrivlist\endgroup}
+
+\def\Verbatim{\Get@Verbatim\The@Verbatim}
+\def\endVerbatim{\UseVerbatim\The@Verbatim\The@VerbatimErr}
+
+\def\LUseVerbatim#1{%
+  \begingroup\list{}{}\item[]\Verbatim@List{#1}\endlist\endgroup}
+
+\def\LVerbatim{\Get@Verbatim\The@Verbatim}
+\def\endLVerbatim{\LUseVerbatim\The@Verbatim\The@VerbatimErr}
+
+\def\BUseVerbatim{%
+  \@ifnextchar[{\@BUseVerbatim}{\@BUseVerbatim[]}}
+\def\@BUseVerbatim[#1]#2{%
+  \begingroup
+    \Verbatim@Prep
+    \let\Verbatim@Par\@Btrivlistcr
+    \@Btrivlist{l}[#1]%
+    #2%
+    \endBtrivlist
+  \endgroup}%
+
+\def\BVerbatim{%
+  \catcode`\^^M=13\relax
+  \@ifnextchar[{\@BVerbatim}{\@BVerbatim[]}}
+\def\@BVerbatim[#1]{\def\@tempa{[#1]}\Get@Verbatim\The@Verbatim}
+\def\endBVerbatim{
+  \expandafter\@BUseVerbatim\@tempa\The@Verbatim\The@VerbatimErr}
+
+\newwrite\Verbatim@Outfile
+\def\VerbatimOut#1{%
+  \@bsphack
+  \begingroup
+    \immediate\openout\Verbatim@Outfile #1\relax
+    \def\EveryVerbatimCodes{\EveryVerbOutCodes}%
+    \Get@Verbatim\The@Verbatim}
+\def\endVerbatimOut{%
+    \Verbatim@ObeyThings
+    \def\Verbatim@Par{^^J}%
+    \def\Verbatim@Space{\space}%
+    \def\Verbatim@Tab{\space}%
+    \def\@lquote{\string`}%
+    \ThisVerb\relax\gdef\ThisVerb{}%
+    \let\Every@VerbatimLine\EveryVerbOutLine
+    \immediate\write\Verbatim@Outfile{\The@Verbatim}%
+    \immediate\closeout\Verbatim@Outfile
+  \endgroup
+  \The@VerbatimErr
+  \@esphack}
+
+% This one is a little tricky because:
+% * we want to ignore the ^^M at the end of the last line,
+% * we want to handle files that end with newline and files that don't
+% * we want comment characters to work properly,
+% * we want to expand each line before inserting \Every@VerbatimLine and
+%     \Verbatim@Par,
+%
+% \The@GVerbatim is used as scratch with global redefinition.
+\newread\Verbatim@Infile
+\def\Verbatim@Input#1#2{%
+  \begingroup
+    \Verbatim@Codes\EveryVerbatimCodes
+    \immediate\openin\Verbatim@Infile #1\relax
+    \ifeof\Verbatim@Infile
+      \@latexerr{No verbatim file #1}\@ehd
+    \else
+      \def\The@GVerbatim{}\Verbatim@NextLine
+      \ifeof\Verbatim@Infile
+        \@latexerr{Verbatim file #1 is empty}\@ehd
+      \else
+        \let\The@Verbatim\The@GVerbatim
+        \def\The@GVerbatim{}\Verbatim@NextLine
+        #2{\Verbatim@@Input}%
+      \fi
+    \fi
+    \immediate\closein\Verbatim@Infile
+ \endgroup}
+\def\Verbatim@@Input{%
+  \let\protect\noexpand
+  \edef\The@Verbatim{%
+    \noexpand\Every@VerbatimLine
+    \The@Verbatim
+    \ifeof\Verbatim@Infile\else\noexpand\Verbatim@Par\fi}%
+  \let\protect\relax
+  \The@Verbatim
+  \ifeof\Verbatim@Infile\else
+    \let\The@Verbatim\The@GVerbatim
+    \def\The@GVerbatim{}\Verbatim@NextLine
+    \expandafter\Verbatim@@Input
+  \fi}%
+\begingroup\catcode`\^^M=\active%
+\gdef\Verbatim@NextLine{%
+  \ifeof\Verbatim@Infile\else%
+    \immediate\read\Verbatim@Infile to\@tempa%
+    \expandafter\Verbatim@@NextLine\@tempa^^M\relax^^M\@nil%
+  \fi}%
+% #2 is empty if line ends in ^^M, #2=\relax otherwise.
+\gdef\Verbatim@@NextLine#1^^M#2^^M#3\@nil{%
+  \expandafter\gdef\expandafter\The@GVerbatim\expandafter{\The@GVerbatim#1}%
+  \ifx#2\@empty\@empty\else\expandafter\Verbatim@NextLine\fi}%
+\endgroup%
+
+\def\UseVerb#1{\begingroup\Verb@Prep#1\endgroup}
+
+\def\SaveVerb{\@ifnextchar[{\Save@Verb}{\Save@Verb[]}}
+
+\long\def\Save@Verb[#1]#2{%
+  \begingroup
+    \Verbatim@Codes\Verbatim@DontObeyLines\EveryVerbCodes
+    \Save@@Verb{#1}{#2}}
+
+\long\def\Save@@Verb#1#2#3{%
+  \let\protect\noexpand
+  \def\next{\@ifnextchar\@nil{\@gobble}{\endgroup}}%
+  \long\def\Verb##1#3{\@nil\xdef#2{##1}\endgroup#1}%
+  \expandafter\next\Verb}
+
+\def\Verb{\Save@Verb[\UseVerb{\The@Verbatim}]{\The@Verbatim}}
+
+\def\VerbatimInput#1{\begingroup\Verbatim@Input{#1}\UseVerbatim\endgroup}
+
+\def\LVerbatimInput#1{\begingroup\Verbatim@Input{#1}\LUseVerbatim\endgroup}
+
+\def\BVerbatimInput{\@ifnextchar[{\@BVerbatimInput}{\@BVerbatimInput[]}}
+\def\@BVerbatimInput[#1]#2{%
+  \begingroup\Verbatim@Input{#2}{\@BUseVerbatim[#1]}\endgroup}
+
+\endinput
+%% END fancybox.sty
Index: /anuga_core/documentation/user_manual/fancyhdr.sty
===================================================================
--- /anuga_core/documentation/user_manual/fancyhdr.sty	(revision 3574)
+++ /anuga_core/documentation/user_manual/fancyhdr.sty	(revision 3574)
@@ -0,0 +1,329 @@
+% fancyhdr.sty version 1.99d
+% Fancy headers and footers for LaTeX.
+% Piet van Oostrum, Dept of Computer Science, University of Utrecht
+% Padualaan 14, P.O. Box 80.089, 3508 TB Utrecht, The Netherlands
+% Telephone: +31 30 2532180. Email: piet@cs.ruu.nl
+% ========================================================================
+% LICENCE: This is free software. You are allowed to use and distribute
+% this software in any way you like. You are also allowed to make modified
+% versions of it, but you can distribute a modified version only if you
+% clearly indicate that it is a modified version and the person(s) who
+% modified it. This indication should be in a prominent place, e.g. in the
+% top of the file. If possible a contact address, preferably by email,
+% should be given for these persons. If that is feasible the modifications
+% should be indicated in the source code.
+% ========================================================================
+% MODIFICATION HISTORY:
+% Sep 16, 1994
+% version 1.4: Correction for use with \reversemargin
+% Sep 29, 1994:
+% version 1.5: Added the \iftopfloat, \ifbotfloat and \iffloatpage commands
+% Oct 4, 1994:
+% version 1.6: Reset single spacing in headers/footers for use with
+% setspace.sty or doublespace.sty
+% Oct 4, 1994:
+% version 1.7: changed \let\@mkboth\markboth to
+% \def\@mkboth{\protect\markboth} to make it more robust
+% Dec 5, 1994:
+% version 1.8: corrections for amsbook/amsart: define \@chapapp and (more
+% importantly) use the \chapter/sectionmark definitions from ps@headings if
+% they exist (which should be true for all standard classes).
+% May 31, 1995:
+% version 1.9: The proposed \renewcommand{\headrulewidth}{\iffloatpage...
+% construction in the doc did not work properly with the fancyplain style. 
+% June 1, 1995:
+% version 1.91: The definition of \@mkboth wasn't restored on subsequent
+% \pagestyle{fancy}'s.
+% June 1, 1995:
+% version 1.92: The sequence \pagestyle{fancyplain} \pagestyle{plain}
+% \pagestyle{fancy} would erroneously select the plain version.
+% June 1, 1995:
+% version 1.93: \fancypagestyle command added.
+% Dec 11, 1995:
+% version 1.94: suggested by Conrad Hughes <chughes@maths.tcd.ie>
+% CJCH, Dec 11, 1995: added \footruleskip to allow control over footrule
+% position (old hardcoded value of .3\normalbaselineskip is far too high
+% when used with very small footer fonts).
+% Jan 31, 1996:
+% version 1.95: call \@normalsize in the reset code if that is defined,
+% otherwise \normalsize.
+% this is to solve a problem with ucthesis.cls, as this doesn't
+% define \@currsize. Unfortunately for latex209 calling \normalsize doesn't
+% work as this is optimized to do very little, so there \@normalsize should
+% be called. Hopefully this code works for all versions of LaTeX known to
+% mankind.  
+% April 25, 1996:
+% version 1.96: initialize \headwidth to a magic (negative) value to catch
+% most common cases that people change it before calling \pagestyle{fancy}.
+% Note it can't be initialized when reading in this file, because
+% \textwidth could be changed afterwards. This is quite probable.
+% We also switch to \MakeUppercase rather than \uppercase and introduce a
+% \nouppercase command for use in headers. and footers.
+% May 3, 1996:
+% version 1.97: Two changes:
+% 1. Undo the change in version 1.8 (using the pagestyle{headings} defaults
+% for the chapter and section marks. The current version of amsbook and
+% amsart classes don't seem to need them anymore. Moreover the standard
+% latex classes don't use \markboth if twoside isn't selected, and this is
+% confusing as \leftmark doesn't work as expected.
+% 2. include a call to \ps@empty in ps@@fancy. This is to solve a problem
+% in the amsbook and amsart classes, that make global changes to \topskip,
+% which are reset in \ps@empty. Hopefully this doesn't break other things.
+% May 7, 1996:
+% version 1.98:
+% Added % after the line  \def\nouppercase
+% May 7, 1996:
+% version 1.99: This is the alpha version of fancyhdr 2.0
+% Introduced the new commands \fancyhead, \fancyfoot, and \fancyhf.
+% Changed \headrulewidth, \footrulewidth, \footruleskip to
+% macros rather than length parameters, In this way they can be
+% conditionalized and they don't consume length registers. There is no need
+% to have them as length registers unless you want to do calculations with
+% them, which is unlikely. Note that this may make some uses of them
+% incompatible (i.e. if you have a file that uses \setlength or \xxxx=)
+% May 10, 1996:
+% version 1.99a:
+% Added a few more % signs
+% May 10, 1996:
+% version 1.99b:
+% Changed the syntax of \f@nfor to be resistent to catcode changes of :=
+% Removed the [1] from the defs of \lhead etc. because the parameter is
+% consumed by the \@[xy]lhead etc. macros.
+% June 24, 1997:
+% version 1.99c:
+% corrected \nouppercase to also include the protected form of \MakeUppercase
+% \global added to manipulation of \headwidth.
+% \iffootnote command added.
+% Some comments added about \@fancyhead and \@fancyfoot.
+% Aug 24, 1998
+% version 1.99d
+% Changed the default \ps@empty to \ps@@empty in order to allow
+% \fancypagestyle{empty} redefinition.
+
+\let\fancy@def\gdef
+
+\def\if@mpty#1#2#3{\def\temp@ty{#1}\ifx\@empty\temp@ty #2\else#3\fi}
+
+% Usage: \@forc \var{charstring}{command to be executed for each char}
+% This is similar to LaTeX's \@tfor, but expands the charstring.
+
+\def\@forc#1#2#3{\expandafter\f@rc\expandafter#1\expandafter{#2}{#3}}
+\def\f@rc#1#2#3{\def\temp@ty{#2}\ifx\@empty\temp@ty\else
+                                    \f@@rc#1#2\f@@rc{#3}\fi}
+\def\f@@rc#1#2#3\f@@rc#4{\def#1{#2}#4\f@rc#1{#3}{#4}}
+
+% Usage: \f@nfor\name:=list\do{body}
+% Like LaTeX's \@for but an empty list is treated as a list with an empty
+% element
+
+\newcommand{\f@nfor}[3]{\edef\@fortmp{#2}%
+    \expandafter\@forloop#2,\@nil,\@nil\@@#1{#3}}
+
+% Usage: \def@ult \cs{defaults}{argument}
+% sets \cs to the characters from defaults appearing in argument
+% or defaults if it would be empty. All characters are lowercased.
+
+\newcommand\def@ult[3]{%
+    \edef\temp@a{\lowercase{\edef\noexpand\temp@a{#3}}}\temp@a
+    \def#1{}%
+    \@forc\tmpf@ra{#2}%
+        {\expandafter\if@in\tmpf@ra\temp@a{\edef#1{#1\tmpf@ra}}{}}%
+    \ifx\@empty#1\def#1{#2}\fi}
+% 
+% \if@in <char><set><truecase><falsecase>
+%
+\newcommand{\if@in}[4]{%
+    \edef\temp@a{#2}\def\temp@b##1#1##2\temp@b{\def\temp@b{##1}}%
+    \expandafter\temp@b#2#1\temp@b\ifx\temp@a\temp@b #4\else #3\fi}
+
+\newcommand{\fancyhead}{\@ifnextchar[{\f@ncyhf h}{\f@ncyhf h[]}}
+\newcommand{\fancyfoot}{\@ifnextchar[{\f@ncyhf f}{\f@ncyhf f[]}}
+\newcommand{\fancyhf}{\@ifnextchar[{\f@ncyhf {}}{\f@ncyhf {}[]}}
+
+% The header and footer fields are stored in command sequences with
+% names of the form: \f@ncy<x><y><z> with <x> for [eo], <y> form [lcr]
+% and <z> from [hf].
+
+\def\f@ncyhf#1[#2]#3{%
+    \def\temp@c{}%
+    \@forc\tmpf@ra{#2}%
+        {\expandafter\if@in\tmpf@ra{eolcrhf,EOLCRHF}%
+            {}{\edef\temp@c{\temp@c\tmpf@ra}}}%
+    \ifx\@empty\temp@c\else
+        \ifx\PackageError\undefined
+        \errmessage{Illegal char `\temp@c' in fancyhdr argument:
+          [#2]}\else
+        \PackageError{Fancyhdr}{Illegal char `\temp@c' in fancyhdr argument:
+          [#2]}{}\fi
+    \fi
+    \f@nfor\temp@c{#2}%
+        {\def@ult\f@@@eo{eo}\temp@c
+         \def@ult\f@@@lcr{lcr}\temp@c
+         \def@ult\f@@@hf{hf}{#1\temp@c}%
+         \@forc\f@@eo\f@@@eo
+             {\@forc\f@@lcr\f@@@lcr
+                 {\@forc\f@@hf\f@@@hf
+                     {\expandafter\fancy@def\csname
+                      f@ncy\f@@eo\f@@lcr\f@@hf\endcsname
+                      {#3}}}}}}
+
+% Fancyheadings version 1 commands. These are more or less deprecated,
+% but they continue to work.
+
+\newcommand{\lhead}{\@ifnextchar[{\@xlhead}{\@ylhead}}
+\def\@xlhead[#1]#2{\fancy@def\f@ncyelh{#1}\fancy@def\f@ncyolh{#2}}
+\def\@ylhead#1{\fancy@def\f@ncyelh{#1}\fancy@def\f@ncyolh{#1}}
+
+\newcommand{\chead}{\@ifnextchar[{\@xchead}{\@ychead}}
+\def\@xchead[#1]#2{\fancy@def\f@ncyech{#1}\fancy@def\f@ncyoch{#2}}
+\def\@ychead#1{\fancy@def\f@ncyech{#1}\fancy@def\f@ncyoch{#1}}
+
+\newcommand{\rhead}{\@ifnextchar[{\@xrhead}{\@yrhead}}
+\def\@xrhead[#1]#2{\fancy@def\f@ncyerh{#1}\fancy@def\f@ncyorh{#2}}
+\def\@yrhead#1{\fancy@def\f@ncyerh{#1}\fancy@def\f@ncyorh{#1}}
+
+\newcommand{\lfoot}{\@ifnextchar[{\@xlfoot}{\@ylfoot}}
+\def\@xlfoot[#1]#2{\fancy@def\f@ncyelf{#1}\fancy@def\f@ncyolf{#2}}
+\def\@ylfoot#1{\fancy@def\f@ncyelf{#1}\fancy@def\f@ncyolf{#1}}
+
+\newcommand{\cfoot}{\@ifnextchar[{\@xcfoot}{\@ycfoot}}
+\def\@xcfoot[#1]#2{\fancy@def\f@ncyecf{#1}\fancy@def\f@ncyocf{#2}}
+\def\@ycfoot#1{\fancy@def\f@ncyecf{#1}\fancy@def\f@ncyocf{#1}}
+
+\newcommand{\rfoot}{\@ifnextchar[{\@xrfoot}{\@yrfoot}}
+\def\@xrfoot[#1]#2{\fancy@def\f@ncyerf{#1}\fancy@def\f@ncyorf{#2}}
+\def\@yrfoot#1{\fancy@def\f@ncyerf{#1}\fancy@def\f@ncyorf{#1}}
+
+\newdimen\headwidth
+\newcommand{\headrulewidth}{0.4pt}
+\newcommand{\footrulewidth}{\z@skip}
+\newcommand{\footruleskip}{.3\normalbaselineskip}
+
+% Fancyplain stuff shouldn't be used anymore (rather
+% \fancypagestyle{plain} should be used), but it must be present for
+% compatibility reasons.
+
+\newcommand{\plainheadrulewidth}{\z@skip}
+\newcommand{\plainfootrulewidth}{\z@skip}
+\newif\if@fancyplain \@fancyplainfalse
+\def\fancyplain#1#2{\if@fancyplain#1\else#2\fi}
+
+\headwidth=-123456789sp %magic constant
+
+% Command to reset various things in the headers:
+% a.o.  single spacing (taken from setspace.sty)
+% and the catcode of ^^M (so that epsf files in the header work if a
+% verbatim crosses a page boundary)
+% It also defines a \nouppercase command that disables \uppercase and
+% \Makeuppercase. It can only be used in the headers and footers.
+\def\fancy@reset{\restorecr
+ \def\baselinestretch{1}%
+ \def\nouppercase##1{{\let\uppercase\relax\let\MakeUppercase\relax
+     \expandafter\let\csname MakeUppercase \endcsname\relax##1}}%
+ \ifx\undefined\@newbaseline% NFSS not present; 2.09 or 2e
+   \ifx\@normalsize\undefined \normalsize % for ucthesis.cls
+   \else \@normalsize \fi
+ \else% NFSS (2.09) present
+  \@newbaseline%
+ \fi}
+
+% Initialization of the head and foot text.
+
+% The default values still contain \fancyplain for compatibility.
+\fancyhf{} % clear all
+% lefthead empty on ``plain'' pages, \rightmark on even, \leftmark on odd pages
+% evenhead empty on ``plain'' pages, \leftmark on even, \rightmark on odd pages
+\fancyhead[el,or]{\fancyplain{}{\sl\rightmark}}
+\fancyhead[er,ol]{\fancyplain{}{\sl\leftmark}}
+\fancyfoot[c]{\rm\thepage} % page number
+
+% Put together a header or footer given the left, center and
+% right text, fillers at left and right and a rule.
+% The \lap commands put the text into an hbox of zero size,
+% so overlapping text does not generate an errormessage.
+% These macros have 5 parameters:
+% 1. \@lodd or \@rodd % This determines at which side the header will stick
+%    out.
+% 2. \f@ncyolh, \f@ncyelh, \f@ncyolf or \f@ncyelf. This is the left component.
+% 3. \f@ncyoch, \f@ncyech, \f@ncyocf or \f@ncyecf. This is the middle comp.
+% 4. \f@ncyorh, \f@ncyerh, \f@ncyorf or \f@ncyerf. This is the right component.
+% 5. \@lodd or \@rodd % This determines at which side the header will stick
+%    out. This is the reverse of parameter nr. 1. One of them is always
+%    \relax and the other one is \hss (after expansion).
+
+\def\@fancyhead#1#2#3#4#5{#1\hbox to\headwidth{\fancy@reset\vbox{\hbox
+{\rlap{\parbox[b]{\headwidth}{\raggedright#2\strut}}\hfill
+\parbox[b]{\headwidth}{\centering#3\strut}\hfill
+\llap{\parbox[b]{\headwidth}{\raggedleft#4\strut}}}\headrule}}#5}
+
+\def\@fancyfoot#1#2#3#4#5{#1\hbox to\headwidth{\fancy@reset\vbox{\footrule
+\hbox{\rlap{\parbox[t]{\headwidth}{\raggedright#2\strut}}\hfill
+\parbox[t]{\headwidth}{\centering#3\strut}\hfill
+\llap{\parbox[t]{\headwidth}{\raggedleft#4\strut}}}}}#5}
+
+\def\headrule{{\if@fancyplain\let\headrulewidth\plainheadrulewidth\fi
+\hrule\@height\headrulewidth\@width\headwidth \vskip-\headrulewidth}}
+
+\def\footrule{{\if@fancyplain\let\footrulewidth\plainfootrulewidth\fi
+\vskip-\footruleskip\vskip-\footrulewidth
+\hrule\@width\headwidth\@height\footrulewidth\vskip\footruleskip}}
+
+\def\ps@fancy{%
+\@ifundefined{@chapapp}{\let\@chapapp\chaptername}{}%for amsbook
+%
+% Define \MakeUppercase for old LaTeXen.
+% Note: we used \def rather than \let, so that \let\uppercase\relax (from
+% the version 1 documentation) will still work.
+%
+\@ifundefined{MakeUppercase}{\def\MakeUppercase{\uppercase}}{}%
+\@ifundefined{chapter}{\def\sectionmark##1{\markboth
+{\MakeUppercase{\ifnum \c@secnumdepth>\z@
+ \thesection\hskip 1em\relax \fi ##1}}{}}%
+\def\subsectionmark##1{\markright {\ifnum \c@secnumdepth >\@ne
+ \thesubsection\hskip 1em\relax \fi ##1}}}%
+{\def\chaptermark##1{\markboth {\MakeUppercase{\ifnum \c@secnumdepth>\m@ne
+ \@chapapp\ \thechapter. \ \fi ##1}}{}}%
+\def\sectionmark##1{\markright{\MakeUppercase{\ifnum \c@secnumdepth >\z@
+ \thesection. \ \fi ##1}}}}%
+%\csname ps@headings\endcsname % use \ps@headings defaults if they exist
+\ps@@fancy
+\gdef\ps@fancy{\@fancyplainfalse\ps@@fancy}%
+% Initialize \headwidth if the user didn't
+%
+\ifdim\headwidth<0sp
+%
+% This catches the case that \headwidth hasn't been initialized and the
+% case that the user added something to \headwidth in the expectation that
+% it was initialized to \textwidth. We compensate this now. This loses if
+% the user intended to multiply it by a factor. But that case is more
+% likely done by saying something like \headwidth=1.2\textwidth. 
+% The doc says you have to change \headwidth after the first call to
+% \pagestyle{fancy}. This code is just to catch the most common cases were
+% that requirement is violated.
+%
+    \global\advance\headwidth123456789sp\global\advance\headwidth\textwidth
+\fi}
+\def\ps@fancyplain{\ps@fancy \let\ps@plain\ps@plain@fancy}
+\def\ps@plain@fancy{\@fancyplaintrue\ps@@fancy}
+\let\ps@@empty\ps@empty
+\def\ps@@fancy{%
+\ps@@empty % This is for amsbook/amsart, which do strange things with \topskip
+\def\@mkboth{\protect\markboth}%
+\def\@oddhead{\@fancyhead\@lodd\f@ncyolh\f@ncyoch\f@ncyorh\@rodd}%
+\def\@oddfoot{\@fancyfoot\@lodd\f@ncyolf\f@ncyocf\f@ncyorf\@rodd}%
+\def\@evenhead{\@fancyhead\@rodd\f@ncyelh\f@ncyech\f@ncyerh\@lodd}%
+\def\@evenfoot{\@fancyfoot\@rodd\f@ncyelf\f@ncyecf\f@ncyerf\@lodd}%
+}
+\def\@lodd{\if@reversemargin\hss\else\relax\fi}
+\def\@rodd{\if@reversemargin\relax\else\hss\fi}
+
+\newif\iffootnote
+\let\latex@makecol\@makecol
+\def\@makecol{\ifvoid\footins\footnotetrue\else\footnotefalse\fi
+\let\topfloat\@toplist\let\botfloat\@botlist\latex@makecol}
+\def\iftopfloat#1#2{\ifx\topfloat\empty #2\else #1\fi}
+\def\ifbotfloat#1#2{\ifx\botfloat\empty #2\else #1\fi}
+\def\iffloatpage#1#2{\if@fcolmade #1\else #2\fi}
+
+\newcommand{\fancypagestyle}[2]{%
+  \@namedef{ps@#1}{\let\fancy@def\def#2\relax\ps@fancy}}
Index: /anuga_core/documentation/user_manual/fc-english.def
===================================================================
--- /anuga_core/documentation/user_manual/fc-english.def	(revision 3574)
+++ /anuga_core/documentation/user_manual/fc-english.def	(revision 3574)
@@ -0,0 +1,406 @@
+%%
+%% This is file `fc-english.def',
+%% generated with the docstrip utility.
+%%
+%% The original source files were:
+%%
+%% fmtcount.dtx  (with options: `fc-english.def,package')
+%% Copyright (C) 2005 Nicola Talbot, all rights reserved.
+%% If you modify this file, you must change its name first.
+%% You are NOT ALLOWED to distribute this file alone. You are NOT
+%% ALLOWED to take money for the distribution or use of either this
+%% file or a changed version, except for a nominal charge for copying
+%% etc.
+%% \CharacterTable
+%%  {Upper-case    \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
+%%   Lower-case    \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
+%%   Digits        \0\1\2\3\4\5\6\7\8\9
+%%   Exclamation   \!     Double quote  \"     Hash (number) \#
+%%   Dollar        \$     Percent       \%     Ampersand     \&
+%%   Acute accent  \'     Left paren    \(     Right paren   \)
+%%   Asterisk      \*     Plus          \+     Comma         \,
+%%   Minus         \-     Point         \.     Solidus       \/
+%%   Colon         \:     Semicolon     \;     Less than     \<
+%%   Equals        \=     Greater than  \>     Question mark \?
+%%   Commercial at \@     Left bracket  \[     Backslash     \\
+%%   Right bracket \]     Circumflex    \^     Underscore    \_
+%%   Grave accent  \`     Left brace    \{     Vertical bar  \|
+%%   Right brace   \}     Tilde         \~}
+\ProvidesFile{fc-english}[2005/04/29]
+\newcommand{\@ordinalMenglish}[1]{%
+\@orgargctr=#1\relax
+\@ordinalctr=#1%
+\@modulo{\@ordinalctr}{100}%
+\ifnum\@ordinalctr=11
+\the\@orgargctr\fmtord{th}%
+\else
+\ifnum\@ordinalctr=12
+\the\@orgargctr\fmtord{th}%
+\else
+\ifnum\@ordinalctr=13
+\the\@orgargctr\fmtord{th}%
+\else
+\@modulo{\@ordinalctr}{10}%
+\ifcase\@ordinalctr
+\the\@orgargctr\fmtord{th}%      case 0
+\or \the\@orgargctr\fmtord{st}%  case 1
+\or \the\@orgargctr\fmtord{nd}%  case 2
+\or \the\@orgargctr\fmtord{rd}%  case 3
+\else
+\the\@orgargctr\fmtord{th}%      default case
+\fi
+\fi
+\fi
+\fi
+}
+\let\@ordinalFenglish=\@ordinalMenglish
+\providecommand{\andname}{and}
+
+\newcommand{\@@unitstringenglish}[1]{%
+\ifcase#1\relax
+zero%
+\or one%
+\or two%
+\or three%
+\or four%
+\or five%
+\or six%
+\or seven%
+\or eight%
+\or nine%
+\fi
+}
+
+\newcommand{\@@tenstringenglish}[1]{%
+\ifcase#1\relax
+\or ten%
+\or twenty%
+\or thirty%
+\or forty%
+\or fifty%
+\or sixty%
+\or seventy%
+\or eighty%
+\or ninety%
+\fi
+}
+
+\newcommand{\@@teenstringenglish}[1]{%
+\ifcase#1\relax
+ten%
+\or eleven%
+\or twelve%
+\or thirteen%
+\or fourteen%
+\or fifteen%
+\or sixteen%
+\or seventeen%
+\or eighteen%
+\or nineteen%
+\fi
+}
+
+\newcommand{\@@Unitstringenglish}[1]{%
+\ifcase#1\relax
+Zero%
+\or One%
+\or Two%
+\or Three%
+\or Four%
+\or Five%
+\or Six%
+\or Seven%
+\or Eight%
+\or Nine%
+\fi
+}
+
+\newcommand{\@@Tenstringenglish}[1]{%
+\ifcase#1\relax
+\or Ten%
+\or Twenty%
+\or Thirty%
+\or Forty%
+\or Fifty%
+\or Sixty%
+\or Seventy%
+\or Eighty%
+\or Ninety%
+\fi
+}
+
+\newcommand{\@@Teenstringenglish}[1]{%
+\ifcase#1\relax
+Ten%
+\or Eleven%
+\or Twelve%
+\or Thirteen%
+\or Fourteen%
+\or Fifteen%
+\or Sixteen%
+\or Seventeen%
+\or Eighteen%
+\or Nineteen%
+\fi
+}
+
+\newcommand{\@@numberstringenglish}[1]{%
+\ifnum#1>99999
+\PackageError{fmtcount}{Out of range}%
+{This macro only works for values less than 100000}%
+\else
+\ifnum#1<0
+\PackageError{fmtcount}{Negative numbers not permitted}%
+{This macro does not work for negative numbers, however
+you can try typing "minus" first, and then pass the modulus of
+this number}%
+\fi
+\fi
+\@strctr=#1\relax \divide\@strctr by 1000\relax
+\ifnum\@strctr>9
+\divide\@strctr by 10
+\ifnum\@strctr>1
+\@tenstring{\@strctr}%
+\@strctr=#1 \divide\@strctr by 1000\relax
+\@modulo{\@strctr}{10}%
+\ifnum\@strctr>0 -\@unitstring{\@strctr}\fi
+\else
+\@strctr=#1\relax
+\divide\@strctr by 1000
+\@modulo{\@strctr}{10}%
+\@teenstring{\@strctr}%
+\fi
+\ \@thousand%
+\else
+\ifnum\@strctr>0 \@unitstring{\@strctr}\ \@thousand\fi
+\fi
+\@strctr=#1\relax \@modulo{\@strctr}{1000}%
+\divide\@strctr by 100
+\ifnum\@strctr>0
+\ifnum#1>1000 \ \fi\@unitstring{\@strctr}\ \@hundred%
+\fi
+\@strctr=#1\relax \@modulo{\@strctr}{100}%
+\ifnum#1>100 \ifnum\@strctr>0 \ \andname\ \fi\fi
+\ifnum\@strctr>19
+\divide\@strctr by 10
+\@tenstring{\@strctr}%
+\@strctr=#1\relax \@modulo{\@strctr}{10}%
+\ifnum\@strctr>0
+-\@unitstring{\@strctr}%
+\fi
+\else
+\ifnum\@strctr<10
+\ifnum\@strctr=0
+\ifnum#1<100 \@unitstring{\@strctr}\fi
+\else
+\@unitstring{\@strctr}%
+\fi
+\else
+\@modulo{\@strctr}{10}%
+\@teenstring{\@strctr}%
+\fi
+\fi
+}
+
+\newcommand{\@numberstringMenglish}[1]{%
+\let\@unitstring=\@@unitstringenglish
+\let\@teenstring=\@@teenstringenglish
+\let\@tenstring=\@@tenstringenglish
+\def\@hundred{hundred}\def\@thousand{thousand}%
+\@@numberstringenglish{#1}}
+
+\let\@numberstringFenglish=\@numberstringMenglish
+
+\newcommand{\@NumberstringMenglish}[1]{%
+\let\@unitstring=\@@Unitstringenglish
+\let\@teenstring=\@@Teenstringenglish
+\let\@tenstring=\@@Tenstringenglish
+\def\@hundred{Hundred}\def\@thousand{Thousand}%
+\@@numberstringenglish{#1}}
+
+\let\@NumberstringFenglish=\@NumberstringMenglish
+\newcommand{\@@unitthstringenglish}[1]{%
+\ifcase#1\relax
+zeroth%
+\or first%
+\or second%
+\or third%
+\or fourth%
+\or fifth%
+\or sixth%
+\or seventh%
+\or eighth%
+\or ninth%
+\fi
+}
+
+\newcommand{\@@tenthstringenglish}[1]{%
+\ifcase#1\relax
+\or tenth%
+\or twentieth%
+\or thirtieth%
+\or fortieth%
+\or fiftieth%
+\or sixtieth%
+\or seventieth%
+\or eightieth%
+\or ninetieth%
+\fi
+}
+
+\newcommand{\@@teenthstringenglish}[1]{%
+\ifcase#1\relax
+tenth%
+\or eleventh%
+\or twelfth%
+\or thirteenth%
+\or fourteenth%
+\or fifteenth%
+\or sixteenth%
+\or seventeenth%
+\or eighteenth%
+\or nineteenth%
+\fi
+}
+
+\newcommand{\@@Unitthstringenglish}[1]{%
+\ifcase#1\relax
+Zeroth%
+\or First%
+\or Second%
+\or Third%
+\or Fourth%
+\or Fifth%
+\or Sixth%
+\or Seventh%
+\or Eighth%
+\or Ninth%
+\fi
+}
+
+\newcommand{\@@Tenthstringenglish}[1]{%
+\ifcase#1\relax
+\or Tenth%
+\or Twentieth%
+\or Thirtieth%
+\or Fortieth%
+\or Fiftieth%
+\or Sixtieth%
+\or Seventieth%
+\or Eightieth%
+\or Ninetieth%
+\fi
+}
+
+\newcommand{\@@Teenthstringenglish}[1]{%
+\ifcase#1\relax
+Tenth%
+\or Eleventh%
+\or Twelfth%
+\or Thirteenth%
+\or Fourteenth%
+\or Fifteenth%
+\or Sixteenth%
+\or Seventeenth%
+\or Eighteenth%
+\or Nineteenth%
+\fi
+}
+
+\newcommand{\@@ordinalstringenglish}[1]{%
+\@strctr=#1\relax
+\ifnum#1>99999
+\PackageError{fmtcount}{Out of range}%
+{This macro only works for values less than 100000 (value given: \number\@strctr)}%
+\else
+\ifnum#1<0
+\PackageError{fmtcount}{Negative numbers not permitted}%
+{This macro does not work for negative numbers, however
+you can try typing "minus" first, and then pass the modulus of
+this number}%
+\fi
+\fi
+\@strctr=#1\relax \divide\@strctr by 1000\relax
+\ifnum\@strctr>9
+\divide\@strctr by 10
+\ifnum\@strctr>1\relax
+  \@tenstring{\@strctr}%
+  \@strctr=#1\relax
+  \divide\@strctr by 1000\relax
+  \@modulo{\@strctr}{10}%
+  \ifnum\@strctr>0 -\@unitstring{\@strctr}\fi
+\else
+  \@strctr=#1\relax \divide\@strctr by 1000\relax
+  \@modulo{\@strctr}{10}%
+  \@teenstring{\@strctr}%
+\fi
+\@strctr=#1\relax \@modulo{\@strctr}{1000}%
+\ifnum\@strctr=0\ \@thousandth\else\ \@thousand \fi
+\else
+\ifnum\@strctr>0\relax
+\@unitstring{\@strctr}%
+\@strctr=#1\relax \@modulo{\@strctr}{1000}%
+\ifnum\@strctr=0\ \@thousandth\else\ \@thousand\fi
+\fi
+\fi
+\@strctr=#1\relax \@modulo{\@strctr}{1000}%
+\divide\@strctr by 100
+\ifnum\@strctr>0
+\ifnum#1>1000 \ \fi\@unitstring{\@strctr}%
+\@strctr=#1\relax \@modulo{\@strctr}{100}%
+\ifnum\@strctr=0\ \@hundredth\else\ \@hundred\fi
+\fi
+\@strctr=#1\relax \@modulo{\@strctr}{100}%
+\ifnum#1>100 \ifnum\@strctr>0\ and \fi\fi
+\ifnum\@strctr>19
+\@tmpstrctr=\@strctr
+\divide\@strctr by 10
+\@modulo{\@tmpstrctr}{10}%
+\ifnum\@tmpstrctr=0 \@tenthstring{\@strctr}\else \@tenstring{\@strctr}\fi
+\@strctr=#1\relax \@modulo{\@strctr}{10}%
+\ifnum\@strctr>0
+-\@unitthstring{\@strctr}%
+\fi
+\else
+\ifnum\@strctr<10
+\ifnum\@strctr=0
+\ifnum#1<100 \@unitthstring{\@strctr}\fi
+\else
+\@unitthstring{\@strctr}%
+\fi
+\else
+\@modulo{\@strctr}{10}%
+\@teenthstring{\@strctr}%
+\fi
+\fi
+}
+
+\newcommand{\@ordinalstringMenglish}[1]{%
+\let\@unitthstring=\@@unitthstringenglish
+\let\@teenthstring=\@@teenthstringenglish
+\let\@tenthstring=\@@tenthstringenglish
+\let\@unitstring=\@@unitstringenglish
+\let\@teenstring=\@@teenstringenglish
+\let\@tenstring=\@@tenstringenglish
+\def\@hundred{hundred}\def\@thousand{thousand}%
+\def\@hundredth{hundredth}\def\@thousandth{thousandth}%
+\@@ordinalstringenglish{#1}}
+
+\let\@ordinalstringFenglish=\@ordinalstringMenglish
+
+\newcommand{\@OrdinalstringMenglish}[1]{%
+\let\@unitthstring=\@@Unitthstringenglish
+\let\@teenthstring=\@@Teenthstringenglish
+\let\@tenthstring=\@@Tenthstringenglish
+\let\@unitstring=\@@Unitstringenglish
+\let\@teenstring=\@@Teenstringenglish
+\let\@tenstring=\@@Tenstringenglish
+\def\@hundred{Hundred}\def\@thousand{Thousand}%
+\def\@hundredth{Hundredth}\def\@thousandth{Thousandth}%
+\@@ordinalstringenglish{#1}}
+
+\let\@OrdinalstringFenglish=\@OrdinalstringMenglish
+
+\endinput
+%%
+%% End of file `fc-english.def'.
Index: /anuga_core/documentation/user_manual/fmtcount.sty
===================================================================
--- /anuga_core/documentation/user_manual/fmtcount.sty	(revision 3574)
+++ /anuga_core/documentation/user_manual/fmtcount.sty	(revision 3574)
@@ -0,0 +1,487 @@
+%%
+%% This is file `fmtcount.sty',
+%% generated with the docstrip utility.
+%%
+%% The original source files were:
+%%
+%% fmtcount.dtx  (with options: `fmtcount.sty,package')
+%% Copyright (C) 2005 Nicola Talbot, all rights reserved.
+%% If you modify this file, you must change its name first.
+%% You are NOT ALLOWED to distribute this file alone. You are NOT
+%% ALLOWED to take money for the distribution or use of either this
+%% file or a changed version, except for a nominal charge for copying
+%% etc.
+%% \CharacterTable
+%%  {Upper-case    \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
+%%   Lower-case    \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
+%%   Digits        \0\1\2\3\4\5\6\7\8\9
+%%   Exclamation   \!     Double quote  \"     Hash (number) \#
+%%   Dollar        \$     Percent       \%     Ampersand     \&
+%%   Acute accent  \'     Left paren    \(     Right paren   \)
+%%   Asterisk      \*     Plus          \+     Comma         \,
+%%   Minus         \-     Point         \.     Solidus       \/
+%%   Colon         \:     Semicolon     \;     Less than     \<
+%%   Equals        \=     Greater than  \>     Question mark \?
+%%   Commercial at \@     Left bracket  \[     Backslash     \\
+%%   Right bracket \]     Circumflex    \^     Underscore    \_
+%%   Grave accent  \`     Left brace    \{     Vertical bar  \|
+%%   Right brace   \}     Tilde         \~}
+\NeedsTeXFormat{LaTeX2e}
+\ProvidesPackage{fmtcount}[2005/06/20 v1.03]
+\RequirePackage{ifthen}
+\RequirePackage{keyval}
+\providecommand{\fmtord}[1]{\textsuperscript{#1}}
+
+\newcount\c@padzeroesN
+\c@padzeroesN=1\relax
+\providecommand{\padzeroes}[1][17]{\c@padzeroesN=#1}
+\@ifundefined{dateenglish}{}{\input{fc-english.def}}
+\@ifundefined{datespanish}{}{\input{fc-spanish.def}}
+\@ifundefined{dateportuges}{}{\input{fc-portuges.def}}
+\@ifundefined{datefrench}{}{\input{fc-french.def}}
+\def\fmtcount@french{france}
+\define@key{fmtcount}{french}[france]{%
+\@ifundefined{datefrench}{%
+\PackageError{fmtcount}{Language `french' not defined}{You need
+to load babel before loading fmtcount}}{
+\ifthenelse{\equal{#1}{france}
+         \or\equal{#1}{swiss}
+         \or\equal{#1}{belgian}}{%
+         \def\fmtcount@french{#1}}{%
+\PackageError{fmtcount}{Invalid value `#1' to french key}
+{Option `french' can only take the values `france',
+`belgian' or `swiss'}}
+}}
+
+\define@key{fmtcount}{fmtord}{%
+\ifthenelse{\equal{#1}{level}
+          \or\equal{#1}{raise}
+          \or\equal{#1}{user}}{
+          \def\fmtcount@fmtord{#1}}{%
+\PackageError{fmtcount}{Invalid value `#1' to fmtord key}
+{Option `fmtord' can only take the values `level', `raise'
+or `user'}}}
+
+\newif\iffmtord@abbrv
+\fmtord@abbrvfalse
+\define@key{fmtcount}{abbrv}[true]{%
+\ifthenelse{\equal{#1}{true}\or\equal{#1}{false}}{
+          \csname fmtord@abbrv#1\endcsname}{%
+\PackageError{fmtcount}{Invalid value `#1' to fmtord key}
+{Option `fmtord' can only take the values `true' or
+`false'}}}
+
+\newcommand{\fmtcountsetoptions}[1]{%
+\def\fmtcount@fmtord{}%
+\setkeys{fmtcount}{#1}%
+\@ifundefined{datefrench}{}{%
+\edef\@ordinalstringMfrench{\noexpand\csname @ordinalstringMfrench\fmtcount@french\noexpand\endcsname}%
+\edef\@ordinalstringFfrench{\noexpand\csname @ordinalstringFfrench\fmtcount@french\noexpand\endcsname}%
+\edef\@OrdinalstringMfrench{\noexpand\csname @OrdinalstringMfrench\fmtcount@french\noexpand\endcsname}%
+\edef\@OrdinalstringFfrench{\noexpand\csname @OrdinalstringFfrench\fmtcount@french\noexpand\endcsname}%
+\edef\@numberstringMfrench{\noexpand\csname @numberstringMfrench\fmtcount@french\noexpand\endcsname}%
+\edef\@numberstringFfrench{\noexpand\csname @numberstringFfrench\fmtcount@french\noexpand\endcsname}%
+\edef\@NumberstringMfrench{\noexpand\csname @NumberstringMfrench\fmtcount@french\noexpand\endcsname}%
+\edef\@NumberstringFfrench{\noexpand\csname @NumberstringFfrench\fmtcount@french\noexpand\endcsname}%
+}%
+\ifthenelse{\equal{\fmtcount@fmtord}{level}}{%
+\renewcommand{\fmtord}[1]{##1}}{%
+\ifthenelse{\equal{\fmtcount@fmtord}{raise}}{%
+\renewcommand{\fmtord}[1]{\textsuperscript{##1}}}{%
+}}
+}
+\InputIfFileExists{fmtcount.cfg}{%
+\typeout{Using configuration file fmtcount.cfg}}{%
+\typeout{No configuration file fmtcount.cfg found.}}
+\DeclareOption{level}{\def\fmtcount@fmtord{level}%
+\def\fmtord#1{#1}}
+\DeclareOption{raise}{\def\fmtcount@fmtord{raise}%
+\def\fmtord#1{\textsuperscript{#1}}}
+
+\ProcessOptions
+
+\newcount\@DT@modctr
+\def\@modulo#1#2{%
+\@DT@modctr=#1\relax
+\divide \@DT@modctr by #2\relax
+\multiply \@DT@modctr by #2\relax
+\advance #1 by -\@DT@modctr}
+\newcount\@ordinalctr
+\newcount\@orgargctr
+\newcount\@strctr
+\newcount\@tmpstrctr
+\newif\if@DT@padzeroes
+\newcount\@DT@loopN
+\newcount\@DT@X
+\newcommand{\@binary}[1]{%
+\@DT@padzeroestrue
+\@DT@loopN=17\relax
+\@strctr=\@DT@loopN
+\whiledo{\@strctr<\c@padzeroesN}{0\advance\@strctr by 1}%
+\@strctr=65536\relax
+\@DT@X=#1\relax
+\loop
+\@DT@modctr=\@DT@X
+\divide\@DT@modctr by \@strctr
+\ifthenelse{\boolean{@DT@padzeroes} \and \(\@DT@modctr=0\) \and \(\@DT@loopN>\c@padzeroesN\)}{}{\the\@DT@modctr}%
+\ifnum\@DT@modctr=0\else\@DT@padzeroesfalse\fi
+\multiply\@DT@modctr by \@strctr
+\advance\@DT@X by -\@DT@modctr
+\divide\@strctr by 2\relax
+\advance\@DT@loopN by -1\relax
+\ifnum\@strctr>1
+\repeat
+\the\@DT@X}
+
+\let\binarynum=\@binary
+\newcommand{\@octal}[1]{%
+\ifnum#1>32768
+\PackageError{fmtcount}{Value of counter too large for \protect\@octal}{Maximum value 32768}
+\else
+\@DT@padzeroestrue
+\@DT@loopN=6\relax
+\@strctr=\@DT@loopN
+\whiledo{\@strctr<\c@padzeroesN}{0\advance\@strctr by 1}%
+\@strctr=32768\relax
+\@DT@X=#1\relax
+\loop
+\@DT@modctr=\@DT@X
+\divide\@DT@modctr by \@strctr
+\ifthenelse{\boolean{@DT@padzeroes} \and \(\@DT@modctr=0\) \and \(\@DT@loopN>\c@padzeroesN\)}{}{\the\@DT@modctr}%
+\ifnum\@DT@modctr=0\else\@DT@padzeroesfalse\fi
+\multiply\@DT@modctr by \@strctr
+\advance\@DT@X by -\@DT@modctr
+\divide\@strctr by 8\relax
+\advance\@DT@loopN by -1\relax
+\ifnum\@strctr>1
+\repeat
+\the\@DT@X
+\fi}
+\let\octalnum=\@octal
+\newcommand{\@@hexadecimal}[1]{\ifcase#10\or1\or2\or3\or4\or5\or6\or7\or8\or9\or a\or b\or c\or d\or e\or f\fi}
+
+\newcommand{\@hexadecimal}[1]{%
+\@DT@padzeroestrue
+\@DT@loopN=5\relax
+\@strctr=\@DT@loopN
+\whiledo{\@strctr<\c@padzeroesN}{0\advance\@strctr by 1}%
+\@strctr=65536\relax
+\@DT@X=#1\relax
+\loop
+\@DT@modctr=\@DT@X
+\divide\@DT@modctr by \@strctr
+\ifthenelse{\boolean{@DT@padzeroes} \and \(\@DT@modctr=0\) \and \(\@DT@loopN>\c@padzeroesN\)}{}{\@@hexadecimal\@DT@modctr}%
+\ifnum\@DT@modctr=0\else\@DT@padzeroesfalse\fi
+\multiply\@DT@modctr by \@strctr
+\advance\@DT@X by -\@DT@modctr
+\divide\@strctr by 16\relax
+\advance\@DT@loopN by -1\relax
+\ifnum\@strctr>1
+\repeat
+\@@hexadecimal\@DT@X}
+
+\let\hexadecimalnum=\@hexadecimal
+
+\newcommand{\@@Hexadecimal}[1]{\ifcase#10\or1\or2\or3\or4\or5\or6\or7\or8\or9\or A\or B\or C\or D\or E\or F\fi}
+
+\newcommand{\@Hexadecimal}[1]{%
+\@DT@padzeroestrue
+\@DT@loopN=5\relax
+\@strctr=\@DT@loopN
+\whiledo{\@strctr<\c@padzeroesN}{0\advance\@strctr by 1}%
+\@strctr=65536\relax
+\@DT@X=#1\relax
+\loop
+\@DT@modctr=\@DT@X
+\divide\@DT@modctr by \@strctr
+\ifthenelse{\boolean{@DT@padzeroes} \and \(\@DT@modctr=0\) \and \(\@DT@loopN>\c@padzeroesN\)}{}{\@@Hexadecimal\@DT@modctr}%
+\ifnum\@DT@modctr=0\else\@DT@padzeroesfalse\fi
+\multiply\@DT@modctr by \@strctr
+\advance\@DT@X by -\@DT@modctr
+\divide\@strctr by 16\relax
+\advance\@DT@loopN by -1\relax
+\ifnum\@strctr>1
+\repeat
+\@@Hexadecimal\@DT@X}
+
+\let\Hexadecimalnum=\@Hexadecimal
+\newcommand{\@aaalph}[1]{%
+\@DT@loopN=#1\relax
+\advance\@DT@loopN by -1\relax
+\divide\@DT@loopN by 26\relax
+\@DT@modctr=\@DT@loopN
+\multiply\@DT@modctr by 26\relax
+\@DT@X=#1\relax
+\advance\@DT@X by -1\relax
+\advance\@DT@X by -\@DT@modctr
+\advance\@DT@loopN by 1\relax
+\advance\@DT@X by 1\relax
+\loop
+\@alph\@DT@X
+\advance\@DT@loopN by -1\relax
+\ifnum\@DT@loopN>0
+\repeat
+}
+
+\let\aaalphnum=\@aaalph
+
+\newcommand{\@AAAlph}[1]{%
+\@DT@loopN=#1\relax
+\advance\@DT@loopN by -1\relax
+\divide\@DT@loopN by 26\relax
+\@DT@modctr=\@DT@loopN
+\multiply\@DT@modctr by 26\relax
+\@DT@X=#1\relax
+\advance\@DT@X by -1\relax
+\advance\@DT@X by -\@DT@modctr
+\advance\@DT@loopN by 1\relax
+\advance\@DT@X by 1\relax
+\loop
+\@Alph\@DT@X
+\advance\@DT@loopN by -1\relax
+\ifnum\@DT@loopN>0
+\repeat
+}
+
+\let\AAAlphnum=\@AAAlph
+\newcommand{\@abalph}[1]{%
+\ifnum#1>17576
+\PackageError{fmtcount}{Value of counter too large for \protect\@abalph}{Maximum value 17576}
+\else
+\@DT@padzeroestrue
+\@strctr=17576\relax
+\@DT@X=#1\relax
+\advance\@DT@X by -1\relax
+\loop
+\@DT@modctr=\@DT@X
+\divide\@DT@modctr by \@strctr
+\ifthenelse{\boolean{@DT@padzeroes} \and \(\@DT@modctr=1\)}{}{\@alph\@DT@modctr}%
+\ifnum\@DT@modctr=1\else\@DT@padzeroesfalse\fi
+\multiply\@DT@modctr by \@strctr
+\advance\@DT@X by -\@DT@modctr
+\divide\@strctr by 26\relax
+\ifnum\@strctr>1
+\repeat
+\advance\@DT@X by 1\relax
+\@alph\@DT@X
+\fi}
+
+\let\abalphnum=\@abalph
+
+\newcommand{\@ABAlph}[1]{%
+\ifnum#1>17576
+\PackageError{fmtcount}{Value of counter too large for \protect\@ABAlph}{Maximum value 17576}
+\else
+\@DT@padzeroestrue
+\@strctr=17576\relax
+\@DT@X=#1\relax
+\advance\@DT@X by -1\relax
+\loop
+\@DT@modctr=\@DT@X
+\divide\@DT@modctr by \@strctr
+\ifthenelse{\boolean{@DT@padzeroes} \and \(\@DT@modctr=1\)}{}{\@Alph\@DT@modctr}%
+\ifnum\@DT@modctr=1\else\@DT@padzeroesfalse\fi
+\multiply\@DT@modctr by \@strctr
+\advance\@DT@X by -\@DT@modctr
+\divide\@strctr by 26\relax
+\ifnum\@strctr>1
+\repeat
+\advance\@DT@X by 1\relax
+\@Alph\@DT@X
+\fi}
+
+\let\ABAlphnum=\@ABAlph
+
+\newcommand{\@decimal}[1]{%
+\ifnum#1>10000
+\PackageError{fmtcount}{Value of counter too large for \protect\@decimal}{Maximum value 10000}\number#1\relax
+\else
+\@DT@padzeroestrue
+\@DT@loopN=6\relax
+\@strctr=\@DT@loopN
+\whiledo{\(\@strctr<\c@padzeroesN\) \TE@or \(\@strctr=\c@padzeroesN\)}{0\advance\@strctr by 1}%
+\@strctr=10000\relax
+\@DT@X=#1\relax
+\loop
+\@DT@modctr=\@DT@X
+\divide\@DT@modctr by \@strctr
+\ifthenelse{\boolean{@DT@padzeroes} \and \(\@DT@modctr=0\) \and \(\@DT@loopN>\c@padzeroesN\)}{}{\the\@DT@modctr}%
+\ifnum\@DT@modctr=0\else\@DT@padzeroesfalse\fi
+\multiply\@DT@modctr by \@strctr
+\advance\@DT@X by -\@DT@modctr
+\divide\@strctr by 10\relax
+\advance\@DT@loopN by -1\relax
+\ifnum\@strctr>1
+\repeat
+\the\@DT@X
+\fi}
+
+\let\decimalnum=\@decimal
+\newcommand{\ordinal}[1]{%
+\expandafter\protect\expandafter\ordinalnum{%
+\expandafter\the\csname c@#1\endcsname}}
+
+\newcommand{\ordinalnum}[1]{\@ifnextchar[{\@ordinalnum{#1}}{%
+\@ordinalnum{#1}[m]}}
+
+\def\@ordinalnum#1[#2]{%
+\ifthenelse{\equal{#2}{f}}{%
+\protect\@ordinalF{#1}}{%
+\ifthenelse{\equal{#2}{m}}{}{%
+\PackageError{fmtcount}{Invalid gender option `#2' to
+\string\ordinal}{Available options are m or f}}%
+\protect\@ordinalM{#1}}}
+
+\newcommand{\ordinalstring}[1]{%
+\expandafter\protect\expandafter\ordinalstringnum{%
+\expandafter\the\csname c@#1\endcsname}}
+
+\newcommand{\ordinalstringnum}[1]{%
+\@ifnextchar[{\@ordinal@string{#1}}{\@ordinal@string{#1}[m]}}
+
+\def\@ordinal@string#1[#2]{%
+\ifthenelse{\equal{#2}{f}}{%
+\protect\@ordinalstringF{#1}}{%
+\ifthenelse{\equal{#2}{m}}{}{%
+\PackageError{fmtcount}{Invalid gender option `#2' to
+\string\ordinalstring}{Available options are m or f}}%
+\protect\@ordinalstringM{#1}}}
+
+\newcommand{\Ordinalstring}[1]{%
+\expandafter\protect\expandafter\Ordinalstringnum{%
+\expandafter\the\csname c@#1\endcsname}}
+
+\newcommand{\Ordinalstringnum}[1]{%
+\@ifnextchar[{\@Ordinal@string{#1}}{\@Ordinal@string{#1}[m]}}
+
+\def\@Ordinal@string#1[#2]{%
+\ifthenelse{\equal{#2}{f}}{%
+\protect\@OrdinalstringF{#1}}{%
+\ifthenelse{\equal{#2}{m}}{}{%
+\PackageError{fmtcount}{Invalid gender option `#2' to
+\string\Ordinalstring}{Available options are m or f}}%
+\protect\@OrdinalstringM{#1}}}
+
+\newcommand{\numberstring}[1]{%
+\expandafter\protect\expandafter\numberstringnum{%
+\expandafter\the\csname c@#1\endcsname}}
+
+\newcommand{\numberstringnum}[1]{%
+\@ifnextchar[{\@number@string{#1}}{\@number@string{#1}[m]}}
+
+\def\@number@string#1[#2]{%
+\ifthenelse{\equal{#2}{f}}{%
+\protect\@numberstringF{#1}}{%
+\ifthenelse{\equal{#2}{m}}{}{%
+\PackageError{fmtcount}{Invalid gender option `#2' to
+\string\numberstring}{Available options are m or f}}%
+\protect\@numberstringM{#1}}}
+
+\newcommand{\Numberstring}[1]{%
+\expandafter\protect\expandafter\Numberstringnum{%
+\expandafter\the\csname c@#1\endcsname}}
+
+\newcommand{\Numberstringnum}[1]{%
+\@ifnextchar[{\@Number@string{#1}}{\@Number@string{#1}[m]}}
+
+\def\@Number@string#1[#2]{%
+\ifthenelse{\equal{#2}{f}}{%
+\protect\@NumberstringF{#1}}{%
+\ifthenelse{\equal{#2}{m}}{}{%
+\PackageError{fmtcount}{Invalid gender option `#2' to
+\string\Numberstring}{Available options are m or f}}%
+\protect\@NumberstringM{#1}}}
+
+\providecommand{\binary}[1]{\expandafter\protect\expandafter\@binary{\expandafter\the\csname c@#1\endcsname}}
+\providecommand{\aaalph}[1]{\expandafter\protect\expandafter\@aaalph{\expandafter\the\csname c@#1\endcsname}}
+\providecommand{\AAAlph}[1]{\expandafter\protect\expandafter\@AAAlph{\expandafter\the\csname c@#1\endcsname}}
+\providecommand{\abalph}[1]{\expandafter\protect\expandafter\@abalph{\expandafter\the\csname c@#1\endcsname}}
+\providecommand{\ABAlph}[1]{\expandafter\protect\expandafter\@ABAlph{\expandafter\the\csname c@#1\endcsname}}
+\providecommand{\hexadecimal}[1]{\expandafter\protect\expandafter\@hexadecimal{\expandafter\the\csname c@#1\endcsname}}
+\providecommand{\Hexadecimal}[1]{\expandafter\protect\expandafter\@Hexadecimal{\expandafter\the\csname c@#1\endcsname}}
+\providecommand{\octal}[1]{\expandafter\protect\expandafter\@octal{\expandafter\the\csname c@#1\endcsname}}
+\providecommand{\decimal}[1]{\expandafter\protect\expandafter\@decimal{\expandafter\the\csname c@#1\endcsname}}
+\def\@setdef@ultfmtcount{
+\@ifundefined{@ordinalenglish}{\input{fc-english.def}}{}
+\def\@ordinalstringM{\@ordinalstringMenglish}
+\let\@ordinalstringF=\@ordinalstringMenglish
+\def\@OrdinalstringM{\@OrdinalstringMenglish}
+\let\@OrdinalstringF=\@OrdinalstringMenglish
+\def\@numberstringM{\@numberstringMenglish}
+\let\@numberstringF=\@numberstringMenglish
+\def\@NumberstringM{\@NumberstringMenglish}
+\let\@NumberstringF=\@NumberstringMenglish
+\def\@ordinalM{\@ordinalMenglish}
+\let\@ordinalF=\@ordinalM}
+
+\@ifundefined{languagename}{%
+\@setdef@ultfmtcount}{
+\ifthenelse{\equal{\languagename}{nohyphenation}}{\@setdef@ultfmtcount}{
+\def\@numberstringM{\@ifundefined{@numberstringM\languagename}{%
+\PackageError{fmtcount}{No support for language '\languagename'}{%
+The fmtcount package currently does not support language
+'\languagename' for command \string\@numberstringM}}{%
+\csname @numberstringM\languagename\endcsname}}
+
+\def\@numberstringF{\@ifundefined{@numberstringF\languagename}{%
+\PackageError{fmtcount}{No support for language '\languagename'}{%
+The fmtcount package currently does not support language
+'\languagename' for command \string\@numberstringF}}{%
+\csname @numberstringF\languagename\endcsname}}
+
+\def\@NumberstringM{\@ifundefined{@NumberstringM\languagename}{%
+\PackageError{fmtcount}{No support for language '\languagename'}{%
+The fmtcount package currently does not support language
+'\languagename' for command \string\@NumberstringM}}{%
+\csname @NumberstringM\languagename\endcsname}}
+
+\def\@NumberstringF{\@ifundefined{@NumberstringF\languagename}{%
+\PackageError{fmtcount}{No support for language '\languagename'}{%
+The fmtcount package currently does not support language
+'\languagename' for command \string\@NumberstringF}}{%
+\csname @NumberstringF\languagename\endcsname}}
+
+\def\@ordinalM{\@ifundefined{@ordinalM\languagename}{%
+\PackageError{fmtcount}{No support for language '\languagename'}{%
+The fmtcount package currently does not support language
+'\languagename' for command \string\@ordinalM}}{%
+\csname @ordinalM\languagename\endcsname}}
+
+\def\@ordinalF{\@ifundefined{@ordinalF\languagename}{%
+\PackageError{fmtcount}{No support for language '\languagename'}{%
+The fmtcount package currently does not support language
+'\languagename' for command \string\@ordinalF}}{%
+\csname @ordinalF\languagename\endcsname}}
+
+\def\@ordinalstringM{\@ifundefined{@ordinalstringM\languagename}{%
+\PackageError{fmtcount}{No support for language '\languagename'}{%
+The fmtcount package currently does not support language
+'\languagename' for command \string\@ordinalstringM}}{%
+\csname @ordinalstringM\languagename\endcsname}}
+
+\def\@ordinalstringF{\@ifundefined{@ordinalstringF\languagename}{%
+\PackageError{fmtcount}{No support for language '\languagename'}{%
+The fmtcount package currently does not support language
+'\languagename' for command \string\@ordinalstringF}}{%
+\csname @ordinalstringF\languagename\endcsname}}
+
+\def\@OrdinalstringM{\@ifundefined{@OrdinalstringM\languagename}{%
+\PackageError{fmtcount}{No support for language '\languagename'}{%
+The fmtcount package currently does not support language
+'\languagename' for command \string\@OrdinalstringM}}{%
+\csname @OrdinalstringM\languagename\endcsname}}
+
+\def\@OrdinalstringF{\@ifundefined{@OrdinalstringF\languagename}{%
+\PackageError{fmtcount}{No support for language '\languagename'}{%
+The fmtcount package currently does not support language
+'\languagename' for command \string\@OrdinalstringF}}{%
+\csname @OrdinalstringF\languagename\endcsname}}
+}}
+\let\@ordinal=\@ordinalM
+\let\@ordinalstring=\@ordinalstringM
+\let\@Ordinalstring=\@OrdinalstringM
+\let\@numberstring=\@numberstringM
+\let\@Numberstring=\@NumberstringM
+\endinput
+%%
+%% End of file `fmtcount.sty'.
Index: /anuga_core/documentation/user_manual/fncychap.sty
===================================================================
--- /anuga_core/documentation/user_manual/fncychap.sty	(revision 3574)
+++ /anuga_core/documentation/user_manual/fncychap.sty	(revision 3574)
@@ -0,0 +1,433 @@
+%%% Derived from the original fncychap.sty,
+%%% but changed ``TWELV'' to ``TWELVE''.
+
+%%% Copyright   Ulf A. Lindgren
+%%%             Department of Applied Electronics
+%%%             Chalmers University of Technology
+%%%             S-412 96 Gothenburg, Sweden
+%%%             E-mail lindgren@ae.chalmers.se
+%%%
+%%% Note        Permission is granted to modify this file under
+%%%             the condition that it is saved using another
+%%%             file and package name.
+%%%
+%%% Revision    1.1
+%%%
+%%%             Jan. 8th Modified package name base date option
+%%%             Jan. 22th Modified FmN and FmTi for error in book.cls
+%%%                  \MakeUppercase{#}->{\MakeUppercase#}
+%%%             Apr. 6th Modified Lenny option to prevent undesired 
+%%%                  skip of line.
+%%%             Nov. 8th Fixed \@chapapp for AMS
+%%%             Feb. 11th Fixed appendix problem related to Bjarne
+%%% Last modified    Feb. 11th 1998
+
+\NeedsTeXFormat{LaTeX2e}[1995/12/01]
+\ProvidesPackage{fncychap}
+             [1997/04/06 v1.11
+                 LaTeX package (Revised chapters)]
+
+%%%% DEFINITION OF Chapapp variables
+\newcommand{\CNV}{\huge\bfseries}
+\newcommand{\ChNameVar}[1]{\renewcommand{\CNV}{#1}}
+
+
+%%%% DEFINITION OF TheChapter variables
+\newcommand{\CNoV}{\huge\bfseries}
+\newcommand{\ChNumVar}[1]{\renewcommand{\CNoV}{#1}}
+
+\newif\ifUCN
+\UCNfalse
+\newif\ifLCN
+\LCNfalse
+\def\ChNameLowerCase{\LCNtrue\UCNfalse}
+\def\ChNameUpperCase{\UCNtrue\LCNfalse}
+\def\ChNameAsIs{\UCNfalse\LCNfalse}
+
+%%%%% Fix for AMSBook 971008
+
+\@ifundefined{@chapapp}{\let\@chapapp\chaptername}{}
+
+
+%%%%% Fix for Bjarne and appendix 980211
+
+\newif\ifinapp
+\inappfalse
+\renewcommand\appendix{\par
+  \setcounter{chapter}{0}%
+  \setcounter{section}{0}%
+  \inapptrue%
+  \renewcommand\@chapapp{\appendixname}%
+  \renewcommand\thechapter{\@Alph\c@chapter}}
+
+%%%%%
+
+\newcommand{\FmN}[1]{%
+\ifUCN
+   {\MakeUppercase#1}\LCNfalse
+\else
+   \ifLCN
+      {\MakeLowercase#1}\UCNfalse
+   \else #1
+   \fi
+\fi}
+
+
+%%%% DEFINITION OF Title variables
+\newcommand{\CTV}{\Huge\bfseries}
+\newcommand{\ChTitleVar}[1]{\renewcommand{\CTV}{#1}}
+
+%%%% DEFINITION OF the basic rule width
+\newlength{\RW}
+\setlength{\RW}{1pt}
+\newcommand{\ChRuleWidth}[1]{\setlength{\RW}{#1}}
+
+\newif\ifUCT
+\UCTfalse
+\newif\ifLCT
+\LCTfalse
+\def\ChTitleLowerCase{\LCTtrue\UCTfalse}
+\def\ChTitleUpperCase{\UCTtrue\LCTfalse}
+\def\ChTitleAsIs{\UCTfalse\LCTfalse}
+\newcommand{\FmTi}[1]{%
+\ifUCT
+
+   {\MakeUppercase#1}\LCTfalse
+\else
+   \ifLCT
+      {\MakeLowercase#1}\UCTfalse
+   \else #1
+   \fi
+\fi}
+
+
+
+\newlength{\mylen}
+\newlength{\myhi}
+\newlength{\px}
+\newlength{\py}
+\newlength{\pyy}
+\newlength{\pxx}
+
+
+\def\mghrulefill#1{\leavevmode\leaders\hrule\@height #1\hfill\kern\z@}
+
+\newcommand{\DOCH}{%
+  \CNV\FmN{\@chapapp}\space \CNoV\thechapter
+  \par\nobreak
+  \vskip 20\p@
+  }
+\newcommand{\DOTI}[1]{%
+    \CTV\FmTi{#1}\par\nobreak
+    \vskip 40\p@
+    }
+\newcommand{\DOTIS}[1]{%
+    \CTV\FmTi{#1}\par\nobreak
+    \vskip 40\p@
+    }
+
+%%%%%% SONNY DEF
+
+\DeclareOption{Sonny}{%
+  \ChNameVar{\Large\sf}
+  \ChNumVar{\Huge}
+  \ChTitleVar{\Large\sf}
+  \ChRuleWidth{0.5pt}
+  \ChNameUpperCase
+  \renewcommand{\DOCH}{%
+    \raggedleft
+    \CNV\FmN{\@chapapp}\space \CNoV\thechapter
+    \par\nobreak
+    \vskip 40\p@}
+  \renewcommand{\DOTI}[1]{%
+    \CTV\raggedleft\mghrulefill{\RW}\par\nobreak
+    \vskip 5\p@
+    \CTV\FmTi{#1}\par\nobreak
+    \mghrulefill{\RW}\par\nobreak
+    \vskip 40\p@}
+  \renewcommand{\DOTIS}[1]{%
+    \CTV\raggedleft\mghrulefill{\RW}\par\nobreak
+    \vskip 5\p@
+    \CTV\FmTi{#1}\par\nobreak
+    \mghrulefill{\RW}\par\nobreak
+    \vskip 40\p@}
+}
+
+%%%%%% LENNY DEF
+
+\DeclareOption{Lenny}{%
+
+  \ChNameVar{\fontsize{14}{16}\usefont{OT1}{phv}{m}{n}\selectfont}
+  \ChNumVar{\fontsize{60}{62}\usefont{OT1}{ptm}{m}{n}\selectfont}
+  \ChTitleVar{\Huge\bfseries\rm}
+  \ChRuleWidth{1pt}
+  \renewcommand{\DOCH}{%
+    \settowidth{\px}{\CNV\FmN{\@chapapp}}
+    \addtolength{\px}{2pt}
+    \settoheight{\py}{\CNV\FmN{\@chapapp}}
+    \addtolength{\py}{1pt}
+
+    \settowidth{\mylen}{\CNV\FmN{\@chapapp}\space\CNoV\thechapter}
+    \addtolength{\mylen}{1pt}
+    \settowidth{\pxx}{\CNoV\thechapter}
+    \addtolength{\pxx}{-1pt}
+
+    \settoheight{\pyy}{\CNoV\thechapter}
+    \addtolength{\pyy}{-2pt}
+    \setlength{\myhi}{\pyy}
+    \addtolength{\myhi}{-1\py}
+    \par
+    \parbox[b]{\textwidth}{%
+    \rule[\py]{\RW}{\myhi}%
+    \hskip -\RW%
+    \rule[\pyy]{\px}{\RW}%
+    \hskip -\px%
+    \raggedright%
+    \CNV\FmN{\@chapapp}\space\CNoV\thechapter%
+    \hskip1pt%
+    \mghrulefill{\RW}%
+    \rule{\RW}{\pyy}\par\nobreak%
+    \vskip -\baselineskip%
+    \vskip -\pyy%
+    \hskip \mylen%
+    \mghrulefill{\RW}\par\nobreak%
+    \vskip \pyy}%
+    \vskip 20\p@}
+ 
+
+  \renewcommand{\DOTI}[1]{%
+    \raggedright
+    \CTV\FmTi{#1}\par\nobreak
+    \vskip 40\p@}
+
+  \renewcommand{\DOTIS}[1]{%
+    \raggedright
+    \CTV\FmTi{#1}\par\nobreak
+    \vskip 40\p@}
+ }
+
+
+%%%%%%% GLENN DEF
+
+
+\DeclareOption{Glenn}{%
+  \ChNameVar{\bfseries\Large\sf}
+  \ChNumVar{\Huge}
+  \ChTitleVar{\bfseries\Large\rm}
+  \ChRuleWidth{1pt}
+  \ChNameUpperCase
+  \ChTitleUpperCase
+  \renewcommand{\DOCH}{%
+    \settoheight{\myhi}{\CTV\FmTi{Test}}
+    \setlength{\py}{\baselineskip}
+    \addtolength{\py}{\RW}
+    \addtolength{\py}{\myhi}
+    \setlength{\pyy}{\py}
+    \addtolength{\pyy}{-1\RW}
+     
+    \raggedright
+    \CNV\FmN{\@chapapp}\space\CNoV\thechapter
+    \hskip 3pt\mghrulefill{\RW}\rule[-1\pyy]{2\RW}{\py}\par\nobreak}
+
+  \renewcommand{\DOTI}[1]{%
+    \addtolength{\pyy}{-4pt}
+    \settoheight{\myhi}{\CTV\FmTi{#1}}
+    \addtolength{\myhi}{\py}
+    \addtolength{\myhi}{-1\RW}
+    \vskip -1\pyy
+    \rule{2\RW}{\myhi}\mghrulefill{\RW}\hskip 2pt
+    \raggedleft\CTV\FmTi{#1}\par\nobreak
+    \vskip 80\p@}
+
+  \renewcommand{\DOTIS}[1]{%
+    \setlength{\py}{10pt}
+    \setlength{\pyy}{\py}
+    \addtolength{\pyy}{\RW}
+    \setlength{\myhi}{\baselineskip}
+    \addtolength{\myhi}{\pyy}
+    \mghrulefill{\RW}\rule[-1\py]{2\RW}{\pyy}\par\nobreak
+%    \addtolength{}{}
+\vskip -1\baselineskip
+    \rule{2\RW}{\myhi}\mghrulefill{\RW}\hskip 2pt
+    \raggedleft\CTV\FmTi{#1}\par\nobreak
+    \vskip 60\p@}
+  }
+
+%%%%%%% CONNY DEF
+
+\DeclareOption{Conny}{%
+  \ChNameUpperCase
+  \ChTitleUpperCase  
+  \ChNameVar{\centering\Huge\rm\bfseries}
+  \ChNumVar{\Huge}
+  \ChTitleVar{\centering\Huge\rm}
+  \ChRuleWidth{2pt}
+
+  \renewcommand{\DOCH}{%
+    \mghrulefill{3\RW}\par\nobreak
+    \vskip -0.5\baselineskip
+    \mghrulefill{\RW}\par\nobreak
+    \CNV\FmN{\@chapapp}\space \CNoV\thechapter
+    \par\nobreak
+    \vskip -0.5\baselineskip
+   }
+  \renewcommand{\DOTI}[1]{%
+    \mghrulefill{\RW}\par\nobreak
+    \CTV\FmTi{#1}\par\nobreak
+    \vskip 60\p@
+    }
+  \renewcommand{\DOTIS}[1]{%
+    \mghrulefill{\RW}\par\nobreak
+    \CTV\FmTi{#1}\par\nobreak
+    \vskip 60\p@
+    }
+  }
+
+%%%%%%% REJNE DEF
+
+\DeclareOption{Rejne}{%
+
+  \ChNameUpperCase
+  \ChTitleUpperCase  
+  \ChNameVar{\centering\Large\rm}
+  \ChNumVar{\Huge}
+  \ChTitleVar{\centering\Huge\rm}
+  \ChRuleWidth{1pt}
+  \renewcommand{\DOCH}{%
+    \settoheight{\py}{\CNoV\thechapter}
+    \addtolength{\py}{-1pt}
+    \CNV\FmN{\@chapapp}\par\nobreak
+    \vskip 20\p@
+    \setlength{\myhi}{2\baselineskip}
+    \setlength{\px}{\myhi}
+    \addtolength{\px}{-1\RW}
+    \rule[-1\px]{\RW}{\myhi}\mghrulefill{\RW}\hskip
+    10pt\raisebox{-0.5\py}{\CNoV\thechapter}\hskip
+10pt\mghrulefill{\RW}\rule[-1\px]{\RW}{\myhi}\par\nobreak
+     \vskip -1\p@
+    }
+  \renewcommand{\DOTI}[1]{%
+    \setlength{\mylen}{\textwidth}
+    \addtolength{\mylen}{-2\RW}
+    {\vrule width\RW}\parbox{\mylen}{\CTV\FmTi{#1}}{\vrule
+width\RW}\par\nobreak
+    \vskip
+-1pt\rule{\RW}{2\baselineskip}\mghrulefill{\RW}\rule{\RW}{2\baselineskip}
+    \vskip 60\p@
+    }
+  \renewcommand{\DOTIS}[1]{%
+    \setlength{\py}{\fboxrule}
+    \setlength{\fboxrule}{\RW}
+    \setlength{\mylen}{\textwidth}
+    \addtolength{\mylen}{-2\RW}
+    \fbox{\parbox{\mylen}{\vskip
+2\baselineskip\CTV\FmTi{#1}\par\nobreak\vskip \baselineskip}} 
+    \setlength{\fboxrule}{\py}
+    \vskip 60\p@
+    }
+  }
+
+
+%%%%%%% BJARNE DEF
+
+\DeclareOption{Bjarne}{%
+  \ChNameUpperCase
+  \ChTitleUpperCase  
+  \ChNameVar{\raggedleft\normalsize\rm}
+  \ChNumVar{\raggedleft \bfseries\Large}
+  \ChTitleVar{\raggedleft \Large\rm}
+  \ChRuleWidth{1pt}
+
+
+%% Note thechapter -> c@chapter fix appendix bug
+
+  \newcounter{AlphaCnt}
+  \newcounter{AlphaDecCnt}
+  \newcommand{\AlphaNo}{%
+    \ifcase\number\theAlphaCnt
+      \ifnum\c@chapter=0
+        ZERO\else{}\fi
+    \or ONE\or TWO\or THREE\or FOUR\or FIVE
+    \or SIX\or SEVEN\or EIGHT\or NINE\or TEN
+    \or ELEVEN\or TWELVE\or THIRTEEN\or FOURTEEN\or FIFTEEN
+    \or SIXTEEN\or SEVENTEEN\or EIGHTEEN\or NINETEEN\fi
+}
+
+  \newcommand{\AlphaDecNo}{%
+    \setcounter{AlphaDecCnt}{0}
+    \@whilenum\number\theAlphaCnt>0\do
+      {\addtocounter{AlphaCnt}{-10}
+       \addtocounter{AlphaDecCnt}{1}}
+     \ifnum\number\theAlphaCnt=0
+     \else
+       \addtocounter{AlphaDecCnt}{-1}
+       \addtocounter{AlphaCnt}{10}
+     \fi
+     
+     
+    \ifcase\number\theAlphaDecCnt\or TEN\or TWENTY\or THIRTY\or
+    FORTY\or FIFTY\or SIXTY\or SEVENTY\or EIGHTY\or NINETY\fi
+    }
+  \newcommand{\TheAlphaChapter}{%
+    
+    \ifinapp 
+      \thechapter
+    \else
+      \setcounter{AlphaCnt}{\c@chapter}
+      \ifnum\c@chapter<20
+        \AlphaNo
+      \else
+        \AlphaDecNo\AlphaNo
+      \fi
+    \fi
+    }  
+  \renewcommand{\DOCH}{%
+    \mghrulefill{\RW}\par\nobreak
+    \CNV\FmN{\@chapapp}\par\nobreak 
+    \CNoV\TheAlphaChapter\par\nobreak
+    \vskip -1\baselineskip\vskip 5pt\mghrulefill{\RW}\par\nobreak
+    \vskip 20\p@
+    }
+  \renewcommand{\DOTI}[1]{%
+    \CTV\FmTi{#1}\par\nobreak
+    \vskip 40\p@
+    }
+  \renewcommand{\DOTIS}[1]{%
+    \CTV\FmTi{#1}\par\nobreak
+    \vskip 40\p@
+    }
+}
+
+\DeclareOption*{%
+  \PackageWarning{fancychapter}{unknown style option}
+  }
+
+\ProcessOptions* \relax
+
+\def\@makechapterhead#1{%
+  \vspace*{50\p@}%
+  {\parindent \z@ \raggedright \normalfont
+    \ifnum \c@secnumdepth >\m@ne
+      \DOCH
+    \fi
+    \interlinepenalty\@M
+    \DOTI{#1}
+  }}
+\def\@schapter#1{\if@twocolumn
+                   \@topnewpage[\@makeschapterhead{#1}]%
+                 \else
+                   \@makeschapterhead{#1}%
+                   \@afterheading
+                 \fi}
+\def\@makeschapterhead#1{%
+  \vspace*{50\p@}%
+  {\parindent \z@ \raggedright
+    \normalfont
+    \interlinepenalty\@M
+    \DOTIS{#1}
+    \vskip 40\p@
+  }}
+
+\endinput
+
+
Index: /anuga_core/documentation/user_manual/howto.cls
===================================================================
--- /anuga_core/documentation/user_manual/howto.cls	(revision 3574)
+++ /anuga_core/documentation/user_manual/howto.cls	(revision 3574)
@@ -0,0 +1,109 @@
+%
+% howto.cls for the Python documentation
+%
+
+\NeedsTeXFormat{LaTeX2e}[1995/12/01]
+\ProvidesClass{howto}
+             [1998/02/25 Document class (Python HOWTO)]
+
+\RequirePackage{pypaper}
+\RequirePackage{fancybox}
+
+% Change the options here to get a different set of basic options,  This
+% is where to add things like "a4paper" or "10pt".
+%
+\LoadClass[\py@paper,\py@ptsize,twoside]{article}
+
+\setcounter{secnumdepth}{1}
+
+% Optional packages:
+%
+% If processing of these documents fails at your TeX installation,
+% these may be commented out (independently) to make things work.
+% These are both supplied with the current version of the teTeX
+% distribution.
+%
+% The "fancyhdr" package makes nicer page footers reasonable to
+% implement, and is used to put the chapter and section information in 
+% the footers.
+%
+\RequirePackage{fancyhdr}\typeout{Using fancier footers than usual.}
+
+
+% Required package:
+%
+% This gives us all the Python-specific markup that we really want.
+% This should come last.  Do not change this.
+%
+\RequirePackage{python}
+
+% support for module synopsis sections:
+\newcommand{\py@ModSynopsisFilename}{\jobname.syn}
+
+
+% need to do one of these....
+\newcommand{\py@doHorizontalRule}{\rule{\textwidth}{1pt}}
+
+
+% Change the title page to look a bit better, and fit in with the
+% fncychap ``Bjarne'' style a bit better.
+%
+\renewcommand{\maketitle}{
+  \py@doHorizontalRule
+  \ifpdf
+    \begingroup
+    % This \def is required to deal with multi-line authors; it
+    % changes \\ to ', ' (comma-space), making it pass muster for
+    % generating document info in the PDF file.
+    \def\\{, }
+    \pdfinfo{
+      /Author (\@author)
+      /Title (\@title)
+    }
+    \endgroup
+  \fi
+  \begin{flushright}
+    {\rm\Huge\py@HeaderFamily \@title} \par
+    {\em\large\py@HeaderFamily \py@release\releaseinfo} \par
+    \vspace{25pt}
+    {\Large\py@HeaderFamily \@author} \par
+    \vspace{25pt}
+    \@date \par
+    \py@authoraddress \par
+  \end{flushright}
+  \@thanks
+  \setcounter{footnote}{0}
+  \let\thanks\relax\let\maketitle\relax
+  \gdef\@thanks{}\gdef\@author{}\gdef\@title{}
+}
+
+
+\let\py@OldTableofcontents=\tableofcontents
+\renewcommand{\tableofcontents}{
+  \begingroup
+    \parskip = 0mm
+    \py@OldTableofcontents
+  \endgroup
+  \py@doHorizontalRule
+  \vspace{12pt}
+  \py@doing@page@targetstrue
+}  
+
+% Fix the theindex environment to add an entry to the Table of
+% Contents; this is much nicer than just having to jump to the end of
+% the book and flip around, especially with multiple indexes.
+%
+\let\py@OldTheindex=\theindex
+\renewcommand{\theindex}{
+  \clearpage
+  \py@OldTheindex
+  \addcontentsline{toc}{section}{\indexname}
+}
+
+\@ifundefined{fancyhf}{
+  \pagestyle{plain}}{
+  \pagestyle{normal}}		% start this way; change for
+\pagenumbering{arabic}		% ToC & chapters
+\setcounter{secnumdepth}{2}
+
+\thispagestyle{empty}
Index: /anuga_core/documentation/user_manual/ltxmarkup.sty
===================================================================
--- /anuga_core/documentation/user_manual/ltxmarkup.sty	(revision 3574)
+++ /anuga_core/documentation/user_manual/ltxmarkup.sty	(revision 3574)
@@ -0,0 +1,40 @@
+% Created by Fred L. Drake, Jr. <fdrake@acm.org>, as part of the
+% Python Documentation Project.
+%
+% Define some simple markup for the LaTeX command documentation:
+
+\ProvidesPackage{ltxmarkup}
+\RequirePackage{python}      % fulllineitems environment
+
+% These two macros are used in constructing the last parameter to the
+% envdesc and macrodesc environments.
+
+\newcommand{\py@ltx@optparam}[1]{{[}\var{#1}{]}}
+\newcommand{\py@ltx@param}[1]{\{\var{#1}\}}
+
+\newenvironment{envdesc}[2]{
+  \begin{fulllineitems}
+    \item[\code{\e begin\{{\bfseries #1}\}{%
+      \let\op=\py@ltx@optparam%
+      \let\p=\py@ltx@param%
+      \let\unspecified=\py@unspecified%
+      \let\moreargs=\py@moreargs%
+         #2}}]
+    \item[\code{\e end\{{\bfseries #1}\}}]
+    \index{#1 environment@\py@idxcode{#1} environment}
+    \index{environments!#1@\py@idxcode{#1}}
+}{\end{fulllineitems}}
+
+\newenvironment{macrodesc}[2]{
+  \begin{fulllineitems}
+    \item[\code{{\e\bfseries#1}{%
+      \let\op=\py@ltx@optparam%
+      \let\p=\py@ltx@param%
+      \let\unspecified=\py@unspecified%
+      \let\moreargs=\py@moreargs%
+      #2}}]
+    \index{#1@\py@idxcode{#1}}
+}{\end{fulllineitems}}
+
+\newcommand{\env}[1]{\code{#1}}
+\newcommand{\macro}[1]{\code{\e#1}}
Index: /anuga_core/documentation/user_manual/manual.cls
===================================================================
--- /anuga_core/documentation/user_manual/manual.cls	(revision 3574)
+++ /anuga_core/documentation/user_manual/manual.cls	(revision 3574)
@@ -0,0 +1,155 @@
+%
+% manual.cls for the Python documentation
+%
+
+\NeedsTeXFormat{LaTeX2e}[1995/12/01]
+\ProvidesClass{manual}
+             [1998/03/03 Document class (Python manual)]
+
+\RequirePackage{pypaper}
+\RequirePackage{fancybox}
+
+% Change the options here to get a different set of basic options, but only
+% if you have to.  Paper and font size should be adjusted in pypaper.sty.
+%
+\LoadClass[\py@paper,\py@ptsize,twoside,openright]{report}
+
+\setcounter{secnumdepth}{2}
+
+% Optional packages:
+%
+% If processing of these documents fails at your TeX installation,
+% these may be commented out (independently) to make things work.
+% These are both supplied with the current version of the teTeX
+% distribution.
+%
+% The "fancyhdr" package makes nicer page footers reasonable to
+% implement, and is used to put the chapter and section information in 
+% the footers.
+%
+\RequirePackage{fancyhdr}\typeout{Using fancier footers than usual.}
+
+
+% Required packages:
+%
+% The "fncychap" package is used to get the nice chapter headers.  The
+% .sty file is distributed with Python, so you should not need to disable
+% it.  You'd also end up with a mixed page style; uglier than stock LaTeX!
+%
+\RequirePackage[Bjarne]{fncychap}\typeout{Using fancy chapter headings.}
+% Do horizontal rules it this way to match:
+\newcommand{\py@doHorizontalRule}{\mghrulefill{\RW}}
+%
+%
+% This gives us all the Python-specific markup that we really want.
+% This should come last.  Do not change this.
+%
+\RequirePackage{python}
+
+% support for module synopsis sections:
+\newcommand{\py@ModSynopsisFilename}{\jobname\thechapter.syn}
+\let\py@OldChapter=\chapter
+\renewcommand{\chapter}{
+  \py@ProcessModSynopsis
+  \py@closeModSynopsisFile
+  \py@OldChapter
+}
+
+
+% Change the title page to look a bit better, and fit in with the
+% fncychap ``Bjarne'' style a bit better.
+%
+\renewcommand{\maketitle}{%
+  \begin{titlepage}%
+    \let\footnotesize\small
+    \let\footnoterule\relax
+    \py@doHorizontalRule%
+    \ifpdf
+      \begingroup
+      % This \def is required to deal with multi-line authors; it
+      % changes \\ to ', ' (comma-space), making it pass muster for
+      % generating document info in the PDF file.
+      \def\\{, }
+      \pdfinfo{
+        /Author (\@author)
+        /Title (\@title)
+      }
+      \endgroup
+    \fi
+    \begin{flushright}%
+      {\rm\Huge\py@HeaderFamily \@title \par}%
+      {\em\LARGE\py@HeaderFamily \py@release\releaseinfo \par}
+      \vfill
+      {\LARGE\py@HeaderFamily \@author \par}
+      \vfill\vfill
+      {\large
+       \@date \par
+       \vfill
+       \py@authoraddress \par
+      }%
+    \end{flushright}%\par
+    \@thanks
+  \end{titlepage}%
+  \setcounter{footnote}{0}%
+  \let\thanks\relax\let\maketitle\relax
+  \gdef\@thanks{}\gdef\@author{}\gdef\@title{}
+}
+
+
+% Catch the end of the {abstract} environment, but here make sure the
+% abstract is followed by a blank page if the 'openright' option is used.
+%
+\let\py@OldEndAbstract=\endabstract
+\renewcommand{\endabstract}{
+  \if@openright
+    \ifodd\value{page}
+      \typeout{Adding blank page after the abstract.}
+      \vfil\pagebreak
+    \fi
+  \fi
+  \py@OldEndAbstract
+}
+
+% This wraps the \tableofcontents macro with all the magic to get the
+% spacing right and have the right number of pages if the 'openright'
+% option has been used.  This eliminates a fair amount of crud in the
+% individual document files.
+%
+\let\py@OldTableofcontents=\tableofcontents
+\renewcommand{\tableofcontents}{%
+  \setcounter{page}{1}%
+  \pagebreak%
+  \pagestyle{plain}%
+  {%
+    \parskip = 0mm%
+    \py@OldTableofcontents%
+    \if@openright%
+      \ifodd\value{page}%
+        \typeout{Adding blank page after the table of contents.}%
+        \pagebreak\hspace{0pt}%
+      \fi%
+    \fi%
+    \cleardoublepage%
+  }%
+  \pagenumbering{arabic}%
+  \@ifundefined{fancyhf}{}{\pagestyle{normal}}%
+  \py@doing@page@targetstrue%
+}
+% This is needed to get the width of the section # area wide enough in the
+% library reference.  Doing it here keeps it the same for all the manuals.
+%
+\renewcommand*\l@section{\@dottedtocline{1}{1.5em}{2.6em}}
+\renewcommand*\l@subsection{\@dottedtocline{2}{4.1em}{3.5em}}
+\setcounter{tocdepth}{1}
+
+
+% Fix the theindex environment to add an entry to the Table of
+% Contents; this is much nicer than just having to jump to the end of
+% the book and flip around, especially with multiple indexes.
+%
+\let\py@OldTheindex=\theindex
+\renewcommand{\theindex}{
+  \cleardoublepage
+  \py@OldTheindex
+  \addcontentsline{toc}{chapter}{\indexname}
+}
Index: /anuga_core/documentation/user_manual/manual_example.tex
===================================================================
--- /anuga_core/documentation/user_manual/manual_example.tex	(revision 3574)
+++ /anuga_core/documentation/user_manual/manual_example.tex	(revision 3574)
@@ -0,0 +1,89 @@
+% Complete documentation on the extended LaTeX markup used for Python
+% documentation is available in ``Documenting Python'', which is part
+% of the standard documentation for Python.  It may be found online
+% at:
+%
+%     http://www.python.org/doc/current/doc/doc.html
+
+\documentclass{manual}
+
+\title{Big Python Manual}
+
+\author{Your Name Here}
+
+% Please at least include a long-lived email address;
+% the rest is at your discretion.
+\authoraddress{
+	Organization name, if applicable \\
+	Street address, if you want to use it \\
+	Email: \email{your-email@your.domain}
+}
+
+\date{April 30, 1999}		% update before release!
+				% Use an explicit date so that reformatting
+				% doesn't cause a new date to be used.  Setting
+				% the date to \today can be used during draft
+				% stages to make it easier to handle versions.
+
+\release{x.y}			% release version; this is used to define the
+				% \version macro
+
+\makeindex			% tell \index to actually write the .idx file
+\makemodindex			% If this contains a lot of module sections.
+
+
+\begin{document}
+
+\maketitle
+
+% This makes the contents more accessible from the front page of the HTML.
+\ifhtml
+\chapter*{Front Matter\label{front}}
+\fi
+
+%\input{copyright}
+
+\begin{abstract}
+
+\noindent
+Big Python is a special version of Python for users who require larger 
+keys on their keyboards.  It accommodates their special needs by ...
+
+\end{abstract}
+
+\tableofcontents
+
+
+\chapter{...}
+
+My chapter.
+
+
+\appendix
+\chapter{...}
+
+My appendix.
+
+The \code{\e appendix} markup need not be repeated for additional
+appendices.
+
+
+%
+%  The ugly "%begin{latexonly}" pseudo-environments are really just to
+%  keep LaTeX2HTML quiet during the \renewcommand{} macros; they're
+%  not really valuable.
+%
+%  If you don't want the Module Index, you can remove all of this up
+%  until the second \input line.
+%
+%begin{latexonly}
+\renewcommand{\indexname}{Module Index}
+%end{latexonly}
+\input{mod\jobname.ind}		% Module Index
+
+%begin{latexonly}
+\renewcommand{\indexname}{Index}
+%end{latexonly}
+\input{\jobname.ind}			% Index
+
+\end{document}
Index: /anuga_core/documentation/user_manual/old_pyvolution_documentation/limiting.tex
===================================================================
--- /anuga_core/documentation/user_manual/old_pyvolution_documentation/limiting.tex	(revision 3574)
+++ /anuga_core/documentation/user_manual/old_pyvolution_documentation/limiting.tex	(revision 3574)
@@ -0,0 +1,64 @@
+\documentclass[12pt]{article}
+\usepackage{graphicx}
+
+
+\begin{document}
+
+
+\section{Limiting}
+
+
+
+Let $w, z, h$  be the stage, bed elevation and depth at the centroid and
+let $w_i, z_i, h_i$ be the stage, bed elevation and depth at vertex $i$.
+
+Define the maximal bed elevation range $dz$ as
+
+\[
+  dz = \max_i |z_i - z|
+\]
+
+and the minimal depth $h_{\mbox{\tiny min}}$ as
+
+\[
+  h_{\mbox{\tiny min}} = \min_i h_i
+\]
+
+
+\[
+  \alpha = \left \{
+  \begin{array}{ll} 
+    \max (\min ( 2 h_{\mbox{\tiny min}} / dz )) & dz > 0 \\
+    1 & dz \leq 0     
+  \end{array}
+  \right .  
+\]
+
+
+Let $\tilde{w_i}$ be the stage obtained from a gradient limiter limiting on stage. The corresponding depth is the defined as
+
+\[
+  \tilde{h_i} = \tilde{w_i} - z_i
+\]
+
+Let $\bar{h_i}$ be the depth obtained from a gradient limiter limiting on depth.
+The corresponding stage is the defined as
+
+\[
+  \bar{w_i} = z_i + \bar{h_i}
+\]
+
+
+The balanced stage $w_i$ is then obtained by the linear combination
+
+\[
+  w_i = \alpha \tilde{w_i} + (1-\alpha) \bar{w_i}
+\]
+
+or
+
+\[
+  w_i = z_i + \alpha \tilde{h_i} + (1-\alpha) \bar{h_i}
+\]
+
+\end{document}
Index: /anuga_core/documentation/user_manual/old_pyvolution_documentation/ls.tex
===================================================================
--- /anuga_core/documentation/user_manual/old_pyvolution_documentation/ls.tex	(revision 3574)
+++ /anuga_core/documentation/user_manual/old_pyvolution_documentation/ls.tex	(revision 3574)
@@ -0,0 +1,22 @@
+\documentclass[12pt]{article}
+
+
+\begin{document}
+
+\large
+
+\[
+  f(x,y) = \sum_{j=0}^{M-1} f_j \phi_j(x, y) 
+\]
+
+
+\[
+  \min_f \sum_{i=0}^{N-1} (f(x_i, y_i) - z_i)^2 \ + \ \alpha \int_\Omega (\nabla f)^2 \, dx dy
+\]
+
+
+
+\end{document}
+
+
+
Index: /anuga_core/documentation/user_manual/old_pyvolution_documentation/mesh.fig
===================================================================
--- /anuga_core/documentation/user_manual/old_pyvolution_documentation/mesh.fig	(revision 3574)
+++ /anuga_core/documentation/user_manual/old_pyvolution_documentation/mesh.fig	(revision 3574)
@@ -0,0 +1,130 @@
+#FIG 3.2
+Landscape
+Center
+Metric
+A4      
+100.00
+Single
+-2
+1200 2
+6 450 450 1800 4050
+2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
+	 450 1350 1350 1350 1350 4050 450 4050 450 1350
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
+	 900 1350 900 4050
+4 0 0 50 -1 18 12 0.0000 4 135 1080 450 675 class Points\001
+4 0 0 50 -1 0 12 0.0000 4 180 1350 450 1125 coordinates (x, y)\001
+-6
+6 3915 5400 5265 8100
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
+	 5265 5400 5265 8100
+2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
+	 3915 5400 4815 5400 4815 8100 3915 8100 3915 5400
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
+	 4365 5400 4365 8100
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
+	 4815 5400 5265 5400
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
+	 4815 8100 5265 8100
+-6
+6 5940 5400 7290 8100
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
+	 7290 5400 7290 8100
+2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
+	 5940 5400 6840 5400 6840 8100 5940 8100 5940 5400
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
+	 6390 5400 6390 8100
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
+	 6840 5400 7290 5400
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
+	 6840 8100 7290 8100
+-6
+6 7965 5400 9315 8100
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
+	 9315 5400 9315 8100
+2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
+	 7965 5400 8865 5400 8865 8100 7965 8100 7965 5400
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
+	 8415 5400 8415 8100
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
+	 8865 5400 9315 5400
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
+	 8865 8100 9315 8100
+-6
+6 2295 5040 3015 8100
+2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
+	 2295 5400 2745 5400 2745 8100 2295 8100 2295 5400
+4 0 0 50 -1 0 12 0.0000 4 135 705 2295 5175 centroids\001
+-6
+6 6255 8640 7965 11700
+2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
+	 6255 9000 6705 9000 6705 11700 6255 11700 6255 9000
+4 0 0 50 -1 0 12 0.0000 4 180 1710 6255 8775 number_of_boundaries\001
+-6
+6 495 8685 945 11700
+2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
+	 495 9000 945 9000 945 11700 495 11700 495 9000
+4 0 0 50 -1 0 12 0.0000 4 90 420 495 8775 areas\001
+-6
+6 1620 8685 2070 11700
+2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
+	 1620 9000 2070 9000 2070 11700 1620 11700 1620 9000
+4 0 0 50 -1 0 12 0.0000 4 135 330 1620 8820 radii\001
+-6
+6 2835 8640 4680 11700
+6 2835 9000 4185 11700
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
+	 4185 9000 4185 11700
+2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
+	 2835 9000 3735 9000 3735 11700 2835 11700 2835 9000
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
+	 3285 9000 3285 11700
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
+	 3735 9000 4185 9000
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
+	 3735 11700 4185 11700
+-6
+4 0 0 50 -1 0 12 0.0000 4 180 1830 2835 8775 edgelengths (e0, e1, e2)\001
+-6
+2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
+	 2475 1350 3375 1350 3375 4050 2475 4050 2475 1350
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
+	 2925 1350 2925 4050
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 1 0 2
+	2 1 1.00 60.00 120.00
+	 225 2700 450 2475
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 1 0 2
+	2 1 1.00 60.00 120.00
+	 2250 2700 2475 2475
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 1 0 2
+	2 1 1.00 60.00 120.00
+	 225 6120 450 5895
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
+	 1800 5400 1800 8100
+2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
+	 450 5400 1350 5400 1350 8100 450 8100 450 5400
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
+	 900 5400 900 8100
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
+	 1350 5400 1800 5400
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
+	 1350 8100 1800 8100
+3 0 0 1 0 7 50 -1 -1 0.000 0 0 0 4
+	 675 5625 225 5400 0 2700 450 2475
+	 0.000 1.000 1.000 0.000
+3 0 0 1 0 7 50 -1 -1 0.000 0 0 0 4
+	 4095 5760 2205 4275 1980 2698 2475 2473
+	 0.000 1.000 1.000 0.000
+3 0 0 1 0 7 50 -1 -1 0.000 0 0 0 4
+	 4978 7872 4230 8415 3150 8370 765 8415
+	 0.000 1.000 1.000 0.000
+3 0 0 1 0 7 50 -1 -1 0.000 0 0 0 4
+	 785 8405 135 8460 0 6120 450 5940
+	 0.000 1.000 1.000 0.000
+4 0 0 50 -1 18 12 0.0000 4 180 1950 2475 675 class Vectors(Points)\001
+4 0 0 50 -1 0 12 0.0000 4 180 1350 2475 1125 coordinates (x, y)\001
+4 0 0 50 -1 18 12 0.0000 4 180 1335 450 4725 class Triangles\001
+4 0 0 50 -1 0 12 0.0000 4 180 1530 450 5175 vertices (v0, v1, v2)\001
+4 0 0 50 -1 0 12 0.0000 4 180 1515 3915 5175 normals (n0, n1, n2)\001
+4 0 0 50 -1 0 12 0.0000 4 180 1650 5940 5175 neighbours (t0, t1, t2)\001
+4 0 0 50 -1 0 12 0.0000 4 180 2070 7965 5175 neighbour_faces (f0, f1, f2)\001
Index: /anuga_core/documentation/user_manual/old_pyvolution_documentation/mesh_example.fig
===================================================================
--- /anuga_core/documentation/user_manual/old_pyvolution_documentation/mesh_example.fig	(revision 3574)
+++ /anuga_core/documentation/user_manual/old_pyvolution_documentation/mesh_example.fig	(revision 3574)
@@ -0,0 +1,55 @@
+#FIG 3.2
+Landscape
+Center
+Metric
+A4      
+100.00
+Single
+-2
+1200 2
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 4
+	 3600 4950 5400 3150 6750 5400 3600 4950
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 3
+	 3600 4950 2700 2700 5400 3150
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 3
+	 2700 2700 1800 4050 3600 4950
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 3
+	 1800 4050 1350 5400 3600 4950
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 3
+	 1350 5400 3600 7200 3600 4950
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
+	 3600 7200 6750 5400
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 3
+	 3600 7200 7650 7200 6750 5400
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 3
+	 6750 5400 8550 4950 7650 7200
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 3
+	 6750 5400 8100 3600 8550 4950
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
+	 5400 3150 8100 3600
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 3
+	 5400 3150 7200 1800 8100 3600
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 3
+	 5400 3150 4500 900 7200 1800
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
+	 2700 2700 4500 900
+2 1 0 3 0 7 50 -1 -1 0.000 0 0 -1 0 0 4
+	 3600 4950 5400 3150 6750 5400 3600 4950
+2 1 1 1 0 7 50 -1 -1 4.000 0 0 -1 0 0 4
+	 7200 1800 7470 1575 8460 3510 8100 3600
+2 1 1 1 0 7 50 -1 -1 4.000 0 0 -1 0 0 3
+	 8460 3510 8910 4950 8550 4950
+2 1 1 1 0 7 50 -1 -1 4.000 0 0 -1 0 0 3
+	 8910 4950 7830 7515 7650 7200
+2 1 1 1 0 7 50 -1 -1 4.000 0 0 -1 0 0 3
+	 7830 7515 3105 7470 3600 7200
+2 1 1 1 0 7 50 -1 -1 4.000 0 0 -1 0 0 3
+	 3105 7470 900 5535 1350 5400
+2 1 1 1 0 7 50 -1 -1 4.000 0 0 -1 0 0 3
+	 900 5535 1440 3915 1755 4050
+2 1 1 1 0 7 50 -1 -1 4.000 0 0 -1 0 0 3
+	 1440 3915 2430 2430 2700 2700
+2 1 1 1 0 7 50 -1 -1 4.000 0 0 -1 0 0 3
+	 2475 2430 4365 495 4500 900
+2 1 1 1 0 7 50 -1 -1 4.000 0 0 -1 0 0 2
+	 4365 495 7470 1575
Index: /anuga_core/documentation/user_manual/old_pyvolution_documentation/pyvolution_structure.tex
===================================================================
--- /anuga_core/documentation/user_manual/old_pyvolution_documentation/pyvolution_structure.tex	(revision 3574)
+++ /anuga_core/documentation/user_manual/old_pyvolution_documentation/pyvolution_structure.tex	(revision 3574)
@@ -0,0 +1,155 @@
+\documentclass[12pt]{article}
+\usepackage{graphicx}
+
+
+\begin{document}
+
+
+\section{Abstract view of a basic triangle}
+
+The fundamental geometric structure in the finite-volume 
+or finite-element method is the \textbf{triangle}.
+Several triangles can be joined along their edges to 
+form \textbf{meshes} thus providing the ability to discretise complex and 
+general domains. Figure \ref{fig:mesh_example} shows a mesh composed of a
+number of triangles.
+
+\begin{figure}
+\begin{center} 
+  \includegraphics[width=0.8\textwidth]{mesh_example}  
+\end{center}
+\label{fig:mesh_example}
+\caption{FIXME: Should be replaced by a pmesh generated mesh}
+\end{figure}
+
+
+
+Triangles are fully described by the location of their three \textbf{vertices}
+always required to be given in \emph{counter-clockwise} order and they are
+enumerated as 0, 1, 2.
+Other properties are derived automatically and each triangle is given a 
+unique non-negative integer id. The derived 
+properties are:
+\begin{itemize}
+  \item \textbf{centroid:} location of center of gravity
+  \item \textbf{faces:} Triangle edges are called \emph{faces} in 
+  pyvolution and each is enumerated like the vertex it opposes.       
+  \item \textbf{edgelengths:} Length of each face.  
+  \item \textbf{normals:} Outward pointing normal vectors. 
+  Enumerated as faces. 
+  \item \textbf{midpoints:} Points bisecting each face. 
+  Enumerated as faces.    
+  \item \textbf{area:} The triangle area
+  \item \textbf{radius:} The distance from the centroid to the 
+  nearest midpoint 
+\end{itemize}  
+
+
+In addition, each triangle has information about adjacent triangles 
+(neighbours):
+ 
+\begin{itemize}
+  \item \textbf{neighbours:} Indices of adjacent triangles if present, 
+  otherwise a negative number identifying a boundary 
+  (see Section \ref{sec:boundaries}). Neighbours are enumerated as faces.
+  \item \textbf{neighbour\_faces:} For each face, this is the index of 
+  the closest face in the neighbour. If no neighbour is present this 
+  index is undefined.     
+  \item \textbf{number\_of\_boundaries:} Defined as $3$ less the number of 
+  adjacent triangles.
+\end{itemize}  
+
+The conceptual structure of a triangle and it's relation to edges and 
+adjacent triangles are shown in Figure \ref{fig:triangle}. 
+Some quantities are omitted for simplicity.
+ 
+\begin{figure} 
+  \begin{center}
+    \includegraphics[width=0.8\textwidth]{triangle}
+  \end{center}
+  \caption{Conceptual structure of triangles and their relationships.}
+  \label{fig:triangle}  
+\end{figure} 
+
+
+\section{Mesh Data Structure}
+
+Each triangle, each point and each vector could be implemented 
+as an object containing the above mentioned attributes. 
+However, for performance issues, all information is kept in 
+consecutive memory blocks implemented as standard 2d arrays 
+and each triangle object pertain to all conceptual instances of 
+triangle, point and vector.
+
+In addition, not all information listed above need to be 
+stored permanently. 
+The midpoints, for example, are only needed once when computing the 
+triangle-radii, and are discarded after all other attributes 
+have been computed.
+
+Figure \ref{fig:mesh} shows the objects constituting a mesh, the
+arrays that contain the attributes and their relationships.
+Let $M$ be the total number of triangles and $P$ be the total 
+number of points.
+Class Points contains an $P \times 2$ floating point array 
+representing $x, y$ coordinates of all points entering the 
+structure. These are all vertices and centroids. 
+Derived midpoints need not be stored.
+Class Vectors contains the same kind of data, 
+a $3 M \times 2$ floating point array representing $x,y$ coordinates
+of normal vectors. Class Vectors can be derived from Class Points.
+Class Triangles contains the following arrays
+\begin{itemize}
+  \item \textbf{vertices:} An $M \times 3$ integer array representing 
+  indices into the points array for vertex 0, 1 and 2.
+  \item \textbf{centroids:} An $M \times 1$ integer array representing 
+  indices into the points array for the centroids.
+  \item \textbf{normals:} An $M \times 3$ integer array representing  
+  indices into the Vectors array for normal 0, 1 and 2.    
+  \item \textbf{neighbours:} An $M \times 3$ integer array representing
+  ids of neighbouring triangles. If no neighbouring triangle is present, 
+  the corresponding neighbour index will be negative 
+  representing a boundary object. See Section \ref{sec:boundaries}.     
+  \item \textbf{neighbour\_faces:} An $M \times 3$ integer array representing
+  enumerations (0, 1, or 2) of adjacent faces of neighbouring triangles.
+  \item \textbf{areas:} An $M \times 1$ floating point 
+  array representing the derived geometric property area for each triangle.
+  \item \textbf{radii:} An $M \times 1$ floating point 
+  array representing the derived geometric property radius for each triangle.  
+  \item \textbf{edgelengths:} An $M \times 3$ floating point 
+  array representing the derived geometric edgelenghts 0, 1 and 2.
+  \item \textbf{number\_of\_boundaries:} Number of absent adjacent triangles.
+\end{itemize} 
+(FIXME: A proper diagram with both data and methods 
+should go in somewhere in this document)
+
+
+
+\begin{figure}
+\begin{center} 
+  \includegraphics[width=0.8\textwidth]{mesh}  
+\end{center}
+\label{fig:mesh}
+\caption{The data structure for a basic mesh (without boundary info).}
+\end{figure}
+
+
+\section{Vertex data structure}
+
+It is convenient to keep a mapping from each point in the mesh to
+the triangles and vertex ids occupying them.
+
+.........
+
+Mapping:\\
+  Point id: list of (triangle id, vertex id) 
+
+
+
+
+\section{Boundaries}
+\label{sec:boundaries}
+
+Tags, boundary objects and more
+
+\end{document}
Index: /anuga_core/documentation/user_manual/old_pyvolution_documentation/triangle.fig
===================================================================
--- /anuga_core/documentation/user_manual/old_pyvolution_documentation/triangle.fig	(revision 3574)
+++ /anuga_core/documentation/user_manual/old_pyvolution_documentation/triangle.fig	(revision 3574)
@@ -0,0 +1,44 @@
+#FIG 3.2
+Landscape
+Center
+Metric
+A4      
+100.00
+Single
+-2
+1200 2
+1 3 0 1 0 0 50 -1 20 0.000 1 0.0000 900 3600 90 90 900 3600 990 3600
+1 3 0 1 0 0 50 -1 20 0.000 1 0.0000 4500 3600 90 90 4500 3600 4590 3600
+1 3 0 1 0 0 50 -1 20 0.000 1 0.0000 900 900 90 90 900 900 990 900
+2 1 0 3 0 7 50 -1 -1 0.000 0 0 -1 0 0 4
+	 900 900 900 3600 4500 3600 900 900
+2 1 0 3 0 7 50 -1 -1 0.000 0 0 -1 0 0 4
+	 4500 8775 4500 6075 900 6075 4500 8775
+2 1 0 3 0 7 50 -1 -1 0.000 0 0 -1 1 0 2
+	2 1 3.00 60.00 120.00
+	 2475 3600 2475 4455
+2 1 0 3 0 7 50 -1 -1 0.000 0 0 -1 1 0 2
+	2 1 3.00 60.00 120.00
+	 900 2250 45 2250
+2 1 0 3 0 7 50 -1 -1 0.000 0 0 -1 1 0 2
+	2 1 3.00 60.00 120.00
+	 2565 2115 3170 1510
+4 0 0 50 -1 0 12 0.0000 4 135 615 540 720 vertex 2\001
+4 0 0 50 -1 0 12 0.0000 4 135 615 90 3690 vertex 0\001
+4 0 0 50 -1 0 12 0.0000 4 135 465 3420 2700 face 0\001
+4 0 0 50 -1 0 12 0.0000 4 135 615 4770 3600 vertex 1\001
+4 0 0 50 -1 0 12 0.0000 4 135 465 225 1485 face 1\001
+4 0 0 50 -1 0 12 0.0000 4 135 645 2610 4095 normal 2\001
+4 0 0 50 -1 0 12 0.0000 4 135 645 180 2565 normal 1\001
+4 0 0 50 -1 0 12 0.0000 4 135 645 2970 1980 normal 0\001
+4 0 0 50 -1 0 12 0.0000 4 135 510 1620 2565 id = 17\001
+4 0 0 50 -1 0 12 0.0000 4 135 510 3195 7110 id = 13\001
+4 0 0 50 -1 0 12 0.0000 4 180 1200 1620 3330 neighbour2 = 13\001
+4 0 0 50 -1 0 12 0.0000 4 180 1620 1620 3555 neighbour_faces2 = 2\001
+4 0 0 50 -1 0 12 0.0000 4 135 465 1170 3870 face 2\001
+4 0 0 50 -1 0 12 0.0000 4 135 465 1395 5940 face 2\001
+4 0 0 50 -1 0 12 0.0000 4 135 615 4500 6030 vertex 0\001
+4 0 0 50 -1 0 12 0.0000 4 135 615 270 6030 vertex 1\001
+4 0 0 50 -1 0 12 0.0000 4 135 615 4185 9045 vertex 2\001
+4 0 0 50 -1 0 12 0.0000 4 135 465 1350 7110 face 0\001
+4 0 0 50 -1 0 12 0.0000 4 135 465 4590 7515 face 1\001
Index: /anuga_core/documentation/user_manual/pypaper.sty
===================================================================
--- /anuga_core/documentation/user_manual/pypaper.sty	(revision 3574)
+++ /anuga_core/documentation/user_manual/pypaper.sty	(revision 3574)
@@ -0,0 +1,18 @@
+%
+%  Change this to say a4paper instead of letterpaper if you want A4.  These
+%  are the latex defaults.
+%
+\newcommand{\py@paper}{letterpaper}
+\newcommand{\py@ptsize}{10pt}
+
+%  These set up the fonts for the documents.
+%
+%  The "times" package makes the default font the PostScript Times
+%  font, which makes for smaller PostScript and a font that more people 
+%  like.
+%
+%  The "avant" package causes the AvantGarde font to be used for
+%  sans-serif text, instead of the uglier Helvetica set up by the "times"
+%  package.
+%
+\RequirePackage{times}\typeout{Using Times instead of Computer Modern.}
Index: /anuga_core/documentation/user_manual/python.ist
===================================================================
--- /anuga_core/documentation/user_manual/python.ist	(revision 3574)
+++ /anuga_core/documentation/user_manual/python.ist	(revision 3574)
@@ -0,0 +1,11 @@
+line_max 100
+headings_flag 1
+heading_prefix "  \\bigletter "
+
+preamble "\\begin{theindex}
+\\def\\bigletter#1{{\\Large\\sffamily#1}\\nopagebreak\\vspace{1mm}}
+
+"
+
+symhead_positive "{Symbols}"
+numhead_positive "{Numbers}"
Index: /anuga_core/documentation/user_manual/python.sty
===================================================================
--- /anuga_core/documentation/user_manual/python.sty	(revision 3574)
+++ /anuga_core/documentation/user_manual/python.sty	(revision 3574)
@@ -0,0 +1,1309 @@
+%
+% python.sty for the Python docummentation  [works only with Latex2e]
+%
+
+\NeedsTeXFormat{LaTeX2e}[1995/12/01]
+\ProvidesPackage{python}
+             [1998/01/11 LaTeX package (Python markup)]
+
+\RequirePackage{longtable}
+\RequirePackage{underscore}
+
+% Uncomment these two lines to ignore the paper size and make the page 
+% size more like a typical published manual.
+%\renewcommand{\paperheight}{9in}
+%\renewcommand{\paperwidth}{8.5in}   % typical squarish manual
+%\renewcommand{\paperwidth}{7in}     % O'Reilly ``Programmming Python''
+
+% These packages can be used to add marginal annotations which indicate
+% index entries and labels; useful for reviewing this messy documentation!
+%
+%\RequirePackage{showkeys}
+%\RequirePackage{showidx}
+
+% If we ever want to indent paragraphs, this needs to be changed.
+% This is used inside the macros defined here instead of coding
+% \noindent directly.
+\let\py@parindent=\noindent
+
+% for PDF output, use maximal compression & a lot of other stuff
+% (test for PDF recommended by Tanmoy Bhattacharya <tanmoy@qcd.lanl.gov>)
+%
+\newif\ifpy@doing@page@targets
+\py@doing@page@targetsfalse
+
+\newif\ifpdf\pdffalse
+\ifx\pdfoutput\undefined\else\ifcase\pdfoutput
+\else
+  \pdftrue
+  \input{pdfcolor}
+  \let\py@LinkColor=\NavyBlue
+  \let\py@NormalColor=\Black
+  \pdfcompresslevel=9
+  \pdfpagewidth=\paperwidth    % page width of PDF output
+  \pdfpageheight=\paperheight  % page height of PDF output
+  %
+  % Pad the number with '0' to 3 digits wide so no page name is a prefix
+  % of any other.
+  %
+  \newcommand{\py@targetno}[1]{\ifnum#1<100 0\fi\ifnum#1<10 0\fi#1}
+  \newcommand{\py@pageno}{\py@targetno\thepage}
+  %
+  % This definition allows the entries in the page-view of the ToC to be
+  % active links.  Some work, some don't.
+  %
+  \let\py@OldContentsline=\contentsline
+  %
+  % Backward compatibility hack: pdfTeX 0.13 defined \pdfannotlink,
+  % but it changed to \pdfstartlink in 0.14.  This let's us use either
+  % version and still get useful behavior.
+  %
+  \@ifundefined{pdfstartlink}{
+    \let\pdfstartlink=\pdfannotlink
+  }{}
+  %
+  % The \py@parindent here is a hack -- we're forcing pdfTeX into
+  % horizontal mode since \pdfstartlink requires that.
+  \def\py@pdfstartlink{%
+    \ifvmode\py@parindent\fi%
+    \pdfstartlink%
+  }
+  %
+  % Macro that takes two args: the name to link to and the content of
+  % the link.  This takes care of the PDF magic, getting the colors
+  % the same for each link, and avoids having lots of garbage all over 
+  % this style file.
+  \newcommand{\py@linkToName}[2]{%
+    \py@pdfstartlink attr{/Border [0 0 0]} goto name{#1}%
+      \py@LinkColor#2\py@NormalColor%
+    \pdfendlink%
+  }
+  % Compute the padded page number separately since we end up with a pair of
+  % \relax tokens; this gets the right string computed and works.
+  \renewcommand{\contentsline}[3]{%
+    \def\my@pageno{\py@targetno{#3}}%
+    \py@OldContentsline{#1}{\py@linkToName{page\my@pageno}{#2}}{#3}%
+  }
+  \AtEndDocument{
+    \def\_{\string_}
+    \InputIfFileExists{\jobname.bkm}{\pdfcatalog{/PageMode /UseOutlines}}{}
+  }
+  \newcommand{\py@target}[1]{%
+    \ifpy@doing@page@targets%
+      {\pdfdest name{#1} xyz}%
+    \fi%
+  }
+  \let\py@OldLabel=\label
+  \renewcommand{\label}[1]{%
+    \py@OldLabel{#1}%
+    \py@target{label-#1}%
+  }
+  % This stuff adds a page# destination to every PDF page, where # is three
+  % digits wide, padded with leading zeros.  This doesn't really help with
+  % the frontmatter, but does fine with the body.
+  %
+  % This is *heavily* based on the hyperref package.
+  %
+  \def\@begindvi{%
+    \unvbox \@begindvibox
+    \@hyperfixhead
+  }
+  \def\@hyperfixhead{%
+   \let\H@old@thehead\@thehead
+       \global\def\@foo{\py@target{page\py@pageno}}%
+     \expandafter\ifx\expandafter\@empty\H@old@thehead
+       \def\H@old@thehead{\hfil}\fi
+    \def\@thehead{\@foo\relax\H@old@thehead}%
+  }
+\fi\fi
+
+% Increase printable page size (copied from fullpage.sty)
+\topmargin 0pt
+\advance \topmargin by -\headheight
+\advance \topmargin by -\headsep
+
+% attempt to work a little better for A4 users
+\textheight \paperheight
+\advance\textheight by -2in
+
+\oddsidemargin 0pt
+\evensidemargin 0pt
+%\evensidemargin -.25in  % for ``manual size'' documents
+\marginparwidth 0.5in
+
+\textwidth \paperwidth
+\advance\textwidth by -2in
+
+
+% Style parameters and macros used by most documents here
+\raggedbottom
+\sloppy
+\parindent = 0mm
+\parskip = 2mm
+\hbadness = 5000                % don't print trivial gripes
+
+\pagestyle{empty}               % start this way; change for
+\pagenumbering{roman}           % ToC & chapters
+
+% Use this to set the font family for headers and other decor:
+\newcommand{\py@HeaderFamily}{\sffamily}
+
+% Set up abstract ways to get the normal and smaller font sizes that
+% work even in footnote context.
+\newif\ifpy@infootnote \py@infootnotefalse
+\let\py@oldmakefntext\@makefntext
+\def\@makefntext#1{%
+  \bgroup%
+    \py@infootnotetrue
+    \py@oldmakefntext{#1}%
+  \egroup%
+}
+\def\py@defaultsize{%
+  \ifpy@infootnote\footnotesize\else\normalsize\fi%
+}
+\def\py@smallsize{%
+  \ifpy@infootnote\scriptsize\else\small\fi%
+}
+
+% Redefine the 'normal' header/footer style when using "fancyhdr" package:
+\@ifundefined{fancyhf}{}{
+  % Use \pagestyle{normal} as the primary pagestyle for text.
+  \fancypagestyle{normal}{
+    \fancyhf{}
+    \fancyfoot[LE,RO]{{\py@HeaderFamily\thepage}}
+    \fancyfoot[LO]{{\py@HeaderFamily\nouppercase{\rightmark}}}
+    \fancyfoot[RE]{{\py@HeaderFamily\nouppercase{\leftmark}}}
+    \renewcommand{\headrulewidth}{0pt}
+    \renewcommand{\footrulewidth}{0.4pt}
+  }
+  % Update the plain style so we get the page number & footer line,
+  % but not a chapter or section title.  This is to keep the first
+  % page of a chapter and the blank page between chapters `clean.'
+  \fancypagestyle{plain}{
+    \fancyhf{}
+    \fancyfoot[LE,RO]{{\py@HeaderFamily\thepage}}
+    \renewcommand{\headrulewidth}{0pt}
+    \renewcommand{\footrulewidth}{0.4pt}
+  }
+  % Redefine \cleardoublepage so that the blank page between chapters
+  % gets the plain style and not the fancy style.  This is described
+  % in the documentation for the fancyhdr package by Piet von Oostrum.
+  \@ifundefined{chapter}{}{
+    \renewcommand{\cleardoublepage}{
+      \clearpage\if@openright \ifodd\c@page\else
+      \hbox{}
+      \thispagestyle{plain}
+      \newpage
+      \if@twocolumn\hbox{}\newpage\fi\fi\fi
+    }
+  }
+}
+
+% This sets up the {verbatim} environment to be indented and a minipage,
+% and to have all the other mostly nice properties that we want for
+% code samples.
+
+\let\py@OldVerbatim=\verbatim
+\let\py@OldEndVerbatim=\endverbatim
+\RequirePackage{verbatim}
+\let\py@OldVerbatimInput=\verbatiminput
+
+% Variable used by begin code command
+\newlength{\py@codewidth}
+
+\renewcommand{\verbatim}{%
+  \setlength{\parindent}{1cm}%
+  % Calculate the text width for the minipage:
+  \setlength{\py@codewidth}{\linewidth}%
+  \addtolength{\py@codewidth}{-\parindent}%
+  %
+  \par\indent%
+  \begin{minipage}[t]{\py@codewidth}%
+    \small%
+    \py@OldVerbatim%
+}
+\renewcommand{\endverbatim}{%
+    \py@OldEndVerbatim%
+  \end{minipage}%
+}
+\renewcommand{\verbatiminput}[1]{%
+  {\setlength{\parindent}{1cm}%
+   % Calculate the text width for the minipage:
+   \setlength{\py@codewidth}{\linewidth}%
+   \addtolength{\py@codewidth}{-\parindent}%
+   %
+   \small%
+   \begin{list}{}{\setlength{\leftmargin}{1cm}}
+     \item%
+     \py@OldVerbatimInput{#1}%
+   \end{list}
+  }%
+}
+
+% This does a similar thing for the {alltt} environment:
+\RequirePackage{alltt}
+\let\py@OldAllTT=\alltt
+\let\py@OldEndAllTT=\endalltt
+
+\renewcommand{\alltt}{%
+  \setlength{\parindent}{1cm}%
+  % Calculate the text width for the minipage:
+  \setlength{\py@codewidth}{\linewidth}%
+  \addtolength{\py@codewidth}{-\parindent}%
+  \let\e=\textbackslash%
+  %
+  \par\indent%
+  \begin{minipage}[t]{\py@codewidth}%
+    \small%
+    \py@OldAllTT%
+}
+\renewcommand{\endalltt}{%
+    \py@OldEndAllTT%
+  \end{minipage}%
+}
+
+
+\newcommand{\py@modulebadkey}{{--just-some-junk--}}
+
+
+%%  Lots of index-entry generation support.
+
+% Command to wrap around stuff that refers to function / module /
+% attribute names  in the index.  Default behavior: like \code{}.  To
+% just keep the index entries in the roman font, uncomment the second
+% definition; it matches O'Reilly style more.
+%
+\newcommand{\py@idxcode}[1]{\texttt{#1}}
+%\renewcommand{\py@idxcode}[1]{#1}
+
+% Command to generate two index entries (using subentries)
+\newcommand{\indexii}[2]{\index{#1!#2}\index{#2!#1}}
+
+% And three entries (using only one level of subentries)
+\newcommand{\indexiii}[3]{\index{#1!#2 #3}\index{#2!#3, #1}\index{#3!#1 #2}}
+
+% And four (again, using only one level of subentries)
+\newcommand{\indexiv}[4]{
+\index{#1!#2 #3 #4}
+\index{#2!#3 #4, #1}
+\index{#3!#4, #1 #2}
+\index{#4!#1 #2 #3}
+}
+
+% Command to generate a reference to a function, statement, keyword,
+% operator.
+\newcommand{\kwindex}[1]{\indexii{keyword}{#1@{\py@idxcode{#1}}}}
+\newcommand{\stindex}[1]{\indexii{statement}{#1@{\py@idxcode{#1}}}}
+\newcommand{\opindex}[1]{\indexii{operator}{#1@{\py@idxcode{#1}}}}
+\newcommand{\exindex}[1]{\indexii{exception}{#1@{\py@idxcode{#1}}}}
+\newcommand{\obindex}[1]{\indexii{object}{#1}}
+\newcommand{\bifuncindex}[1]{%
+  \index{#1@{\py@idxcode{#1()}} (built-in function)}}
+
+% Add an index entry for a module
+\newcommand{\py@refmodule}[2]{\index{#1@{\py@idxcode{#1}} (#2module)}}
+\newcommand{\refmodindex}[1]{\py@refmodule{#1}{}}
+\newcommand{\refbimodindex}[1]{\py@refmodule{#1}{built-in }}
+\newcommand{\refexmodindex}[1]{\py@refmodule{#1}{extension }}
+\newcommand{\refstmodindex}[1]{\py@refmodule{#1}{standard }}
+
+% Refer to a module's documentation using a hyperlink of the module's
+% name, at least if we're building PDF:
+\ifpdf
+  \newcommand{\refmodule}[2][\py@modulebadkey]{%
+    \ifx\py@modulebadkey#1\def\py@modulekey{#2}\else\def\py@modulekey{#1}\fi%
+    \py@linkToName{label-module-\py@modulekey}{\module{#2}}%
+  }
+\else
+  \newcommand{\refmodule}[2][\py@modulebadkey]{\module{#2}}
+\fi
+
+% support for the module index
+\newif\ifpy@UseModuleIndex
+\py@UseModuleIndexfalse
+
+\newcommand{\makemodindex}{
+  \newwrite\modindexfile
+  \openout\modindexfile=mod\jobname.idx
+  \py@UseModuleIndextrue
+}
+
+% Add the defining entry for a module
+\newcommand{\py@modindex}[2]{%
+  \renewcommand{\py@thismodule}{#1}
+  \setindexsubitem{(in module #1)}%
+  \index{#1@{\py@idxcode{#1}} (#2module)|textbf}%
+  \ifpy@UseModuleIndex%
+    \@ifundefined{py@modplat@\py@thismodulekey}{
+      \write\modindexfile{\protect\indexentry{#1@{\texttt{#1}}}{\thepage}}%
+    }{\write\modindexfile{\protect\indexentry{#1@{\texttt{#1} %
+        \emph{(\py@platformof[\py@thismodulekey]{})}}}{\thepage}}%
+    }
+  \fi%
+}
+
+% *** XXX *** THE NEXT FOUR MACROS ARE NOW OBSOLETE !!! ***
+
+% built-in & Python modules in the main distribution
+\newcommand{\bimodindex}[1]{\py@modindex{#1}{built-in }%
+  \typeout{*** MACRO bimodindex IS OBSOLETE -- USE declaremodule INSTEAD!}}
+\newcommand{\stmodindex}[1]{\py@modindex{#1}{standard }%
+  \typeout{*** MACRO stmodindex IS OBSOLETE -- USE declaremodule INSTEAD!}}
+
+% Python & extension modules outside the main distribution
+\newcommand{\modindex}[1]{\py@modindex{#1}{}%
+  \typeout{*** MACRO modindex IS OBSOLETE -- USE declaremodule INSTEAD!}}
+\newcommand{\exmodindex}[1]{\py@modindex{#1}{extension }%
+  \typeout{*** MACRO exmodindex IS OBSOLETE -- USE declaremodule INSTEAD!}}
+
+% Additional string for an index entry
+\newif\ifpy@usingsubitem\py@usingsubitemfalse
+\newcommand{\py@indexsubitem}{}
+\newcommand{\setindexsubitem}[1]{\renewcommand{\py@indexsubitem}{ #1}%
+                                 \py@usingsubitemtrue}
+\newcommand{\ttindex}[1]{%
+  \ifpy@usingsubitem
+    \index{#1@{\py@idxcode{#1}}\py@indexsubitem}%
+  \else%
+    \index{#1@{\py@idxcode{#1}}}%
+  \fi%
+}
+\newcommand{\withsubitem}[2]{%
+  \begingroup%
+    \def\ttindex##1{\index{##1@{\py@idxcode{##1}} #1}}%
+    #2%
+  \endgroup%
+}
+
+
+% Module synopsis processing -----------------------------------------------
+%
+\newcommand{\py@thisclass}{}
+\newcommand{\py@thismodule}{}
+\newcommand{\py@thismodulekey}{}
+\newcommand{\py@thismoduletype}{}
+
+\newcommand{\py@standardIndexModule}[1]{\py@modindex{#1}{standard }}
+\newcommand{\py@builtinIndexModule}[1]{\py@modindex{#1}{built-in }}
+\newcommand{\py@extensionIndexModule}[1]{\py@modindex{#1}{extension }}
+\newcommand{\py@IndexModule}[1]{\py@modindex{#1}{}}
+
+\newif\ifpy@HaveModSynopsis       \py@HaveModSynopsisfalse
+\newif\ifpy@ModSynopsisFileIsOpen \py@ModSynopsisFileIsOpenfalse
+\newif\ifpy@HaveModPlatform       \py@HaveModPlatformfalse
+
+% \declaremodule[key]{type}{name}
+\newcommand{\declaremodule}[3][\py@modulebadkey]{
+  \py@openModSynopsisFile
+  \renewcommand{\py@thismoduletype}{#2}
+  \ifx\py@modulebadkey#1
+    \renewcommand{\py@thismodulekey}{#3}
+  \else
+    \renewcommand{\py@thismodulekey}{#1}
+  \fi
+  \@ifundefined{py@#2IndexModule}{%
+    \typeout{*** MACRO declaremodule called with unknown module type: `#2'}
+    \py@IndexModule{#3}%
+  }{%
+    \csname py@#2IndexModule\endcsname{#3}%
+  }
+  \label{module-\py@thismodulekey}
+}
+\newif\ifpy@ModPlatformFileIsOpen \py@ModPlatformFileIsOpenfalse
+\newcommand{\py@ModPlatformFilename}{\jobname.pla}
+\newcommand{\platform}[1]{
+  \ifpy@ModPlatformFileIsOpen\else
+    \newwrite\py@ModPlatformFile
+    \openout\py@ModPlatformFile=\py@ModPlatformFilename
+    \py@ModPlatformFileIsOpentrue
+  \fi
+}
+\InputIfFileExists{\jobname.pla}{}{}
+\newcommand{\py@platformof}[2][\py@modulebadkey]{%
+  \ifx\py@modulebadkey#1 \def\py@key{#2}%
+  \else \def\py@key{#1}%
+  \fi%
+  \csname py@modplat@\py@key\endcsname%
+}
+\newcommand{\ignorePlatformAnnotation}[1]{}
+
+% \moduleauthor{name}{email}
+\newcommand{\moduleauthor}[2]{}
+
+% \sectionauthor{name}{email}
+\newcommand{\sectionauthor}[2]{}
+
+
+\newcommand{\py@defsynopsis}{Module has no synopsis.}
+\newcommand{\py@modulesynopsis}{\py@defsynopsis}
+\newcommand{\modulesynopsis}[1]{
+  \py@HaveModSynopsistrue
+  \renewcommand{\py@modulesynopsis}{#1}
+}
+
+% define the file
+\newwrite\py@ModSynopsisFile
+
+% hacked from \addtocontents from latex.ltx:
+\long\def\py@writeModSynopsisFile#1{%
+  \protected@write\py@ModSynopsisFile%
+      {\let\label\@gobble \let\index\@gobble \let\glossary\@gobble}%
+      {\string#1}%
+}
+\newcommand{\py@closeModSynopsisFile}{
+  \ifpy@ModSynopsisFileIsOpen
+    \closeout\py@ModSynopsisFile
+    \py@ModSynopsisFileIsOpenfalse
+  \fi
+}
+\newcommand{\py@openModSynopsisFile}{
+  \ifpy@ModSynopsisFileIsOpen\else
+    \openout\py@ModSynopsisFile=\py@ModSynopsisFilename
+    \py@ModSynopsisFileIsOpentrue
+  \fi
+}
+
+\newcommand{\py@ProcessModSynopsis}{
+  \ifpy@HaveModSynopsis
+    \py@writeModSynopsisFile{\modulesynopsis%
+      {\py@thismodulekey}{\py@thismodule}%
+      {\py@thismoduletype}{\py@modulesynopsis}}%
+    \py@HaveModSynopsisfalse
+  \fi
+  \renewcommand{\py@modulesynopsis}{\py@defsynopsis}
+}
+\AtEndDocument{\py@ProcessModSynopsis\py@closeModSynopsisFile}
+
+
+\long\def\py@writeModPlatformFile#1{%
+  \protected@write\py@ModPlatformFile%
+    {\let\label\@gobble \let\index\@gobble \let\glossary\@gobble}%
+    {\string#1}%
+}
+
+
+\newcommand{\localmoduletable}{
+  \IfFileExists{\py@ModSynopsisFilename}{
+    \begin{synopsistable}
+      \input{\py@ModSynopsisFilename}
+    \end{synopsistable}
+  }{}
+}
+
+\ifpdf
+  \newcommand{\py@ModSynopsisSummary}[4]{%
+    \py@linkToName{label-module-#1}{\bfcode{#2}} & #4\\
+  }
+\else
+  \newcommand{\py@ModSynopsisSummary}[4]{\bfcode{#2} & #4\\}
+\fi
+\newenvironment{synopsistable}{
+  % key, name, type, synopsis
+  \let\modulesynopsis=\py@ModSynopsisSummary
+  \begin{tabular}{ll}
+}{
+  \end{tabular}
+}
+%
+% --------------------------------------------------------------------------
+
+
+\newcommand{\py@reset}{
+  \py@usingsubitemfalse
+  \py@ProcessModSynopsis
+  \renewcommand{\py@thisclass}{}
+  \renewcommand{\py@thismodule}{}
+  \renewcommand{\py@thismodulekey}{}
+  \renewcommand{\py@thismoduletype}{}
+}
+
+% Augment the sectioning commands used to get our own font family in place,
+% and reset some internal data items:
+\renewcommand{\section}{\py@reset%
+                        \@startsection{section}{1}{\z@}%
+                                    {-3.5ex \@plus -1ex \@minus -.2ex}%
+                                    {2.3ex \@plus.2ex}%
+                                    {\reset@font\Large\py@HeaderFamily}}
+\renewcommand{\subsection}{\@startsection{subsection}{2}{\z@}%
+                                    {-3.25ex\@plus -1ex \@minus -.2ex}%
+                                    {1.5ex \@plus .2ex}%
+                                    {\reset@font\large\py@HeaderFamily}}
+\renewcommand{\subsubsection}{\@startsection{subsubsection}{3}{\z@}%
+                                    {-3.25ex\@plus -1ex \@minus -.2ex}%
+                                    {1.5ex \@plus .2ex}%
+                                    {\reset@font\normalsize\py@HeaderFamily}}
+\renewcommand{\paragraph}{\@startsection{paragraph}{4}{\z@}%
+                                    {3.25ex \@plus1ex \@minus.2ex}%
+                                    {-1em}%
+                                    {\reset@font\normalsize\py@HeaderFamily}}
+\renewcommand{\subparagraph}{\@startsection{subparagraph}{5}{\parindent}%
+                                    {3.25ex \@plus1ex \@minus .2ex}%
+                                    {-1em}%
+                                    {\reset@font\normalsize\py@HeaderFamily}}
+
+
+% Now for a lot of semantically-loaded environments that do a ton of magical
+% things to get the right formatting and index entries for the stuff in
+% Python modules and C API.
+
+
+% {fulllineitems} is used in one place in libregex.tex, but is really for
+% internal use in this file.
+%
+\newcommand{\py@itemnewline}[1]{%
+  \@tempdima\linewidth%
+  \advance\@tempdima \leftmargin\makebox[\@tempdima][l]{#1}%
+}
+
+\newenvironment{fulllineitems}{
+  \begin{list}{}{\labelwidth \leftmargin \labelsep 0pt
+                 \rightmargin 0pt \topsep -\parskip \partopsep \parskip
+                 \itemsep -\parsep
+                 \let\makelabel=\py@itemnewline}
+}{\end{list}}
+
+% \optional is mostly for use in the arguments parameters to the various
+% {*desc} environments defined below, but may be used elsewhere.  Known to
+% be used in the debugger chapter.
+%
+% Typical usage:
+%
+%     \begin{funcdesc}{myfunc}{reqparm\optional{, optparm}}
+%                                    ^^^       ^^^
+%                          No space here       No space here
+%
+% When a function has multiple optional parameters, \optional should be
+% nested, not chained.  This is right:
+%
+%     \begin{funcdesc}{myfunc}{\optional{parm1\optional{, parm2}}}
+%
+\let\py@badkey=\@undefined
+
+\newcommand{\optional}[1]{%
+  {\textnormal{\Large[}}{#1}\hspace{0.5mm}{\textnormal{\Large]}}}
+
+% This can be used when a function or method accepts an varying number 
+% of arguments, such as by using the *args syntax in the parameter list.
+\newcommand{\py@moreargs}{...}
+
+% This can be used when you don't want to document the parameters to a 
+% function or method, but simply state that it's an alias for
+% something else.
+\newcommand{\py@unspecified}{...}
+
+
+\newlength{\py@argswidth}
+\newcommand{\py@sigparams}[1]{%
+  \parbox[t]{\py@argswidth}{\py@varvars{#1}\code{)}}}
+\newcommand{\py@sigline}[2]{%
+  \settowidth{\py@argswidth}{#1\code{(}}%
+  \addtolength{\py@argswidth}{-2\py@argswidth}%
+  \addtolength{\py@argswidth}{\textwidth}%
+  \item[#1\code{(}\py@sigparams{#2}]}
+
+% C functions ------------------------------------------------------------
+% \begin{cfuncdesc}[refcount]{type}{name}{arglist}
+% Note that the [refcount] slot should only be filled in by
+% tools/anno-api.py; it pulls the value from the refcounts database.
+\newcommand{\cfuncline}[3]{
+  \py@sigline{\code{#1 \bfcode{#2}}}{#3}%
+  \index{#2@{\py@idxcode{#2()}}}
+}
+\newenvironment{cfuncdesc}[4][\py@badkey]{
+  \begin{fulllineitems}
+    \cfuncline{#2}{#3}{#4}
+    \ifx#1\@undefined\else%
+      \emph{Return value: \textbf{#1}.}\\
+    \fi
+}{\end{fulllineitems}}
+
+% C variables ------------------------------------------------------------
+% \begin{cvardesc}{type}{name}
+\newenvironment{cvardesc}[2]{
+  \begin{fulllineitems}
+    \item[\code{#1 \bfcode{#2}}\index{#2@{\py@idxcode{#2}}}]
+}{\end{fulllineitems}}
+
+% C data types -----------------------------------------------------------
+% \begin{ctypedesc}[index name]{typedef name}
+\newenvironment{ctypedesc}[2][\py@badkey]{
+  \begin{fulllineitems}
+    \item[\bfcode{#2}%
+    \ifx#1\@undefined%
+      \index{#2@{\py@idxcode{#2}} (C type)}
+    \else%
+      \index{#2@{\py@idxcode{#1}} (C type)}
+    \fi]
+}{\end{fulllineitems}}
+
+% C type fields ----------------------------------------------------------
+% \begin{cmemberdesc}{container type}{ctype}{membername}
+\newcommand{\cmemberline}[3]{
+  \item[\code{#2 \bfcode{#3}}]
+  \index{#3@{\py@idxcode{#3}} (#1 member)}
+}
+\newenvironment{cmemberdesc}[3]{
+  \begin{fulllineitems}
+    \cmemberline{#1}{#2}{#3}
+}{\end{fulllineitems}}
+
+% Funky macros -----------------------------------------------------------
+% \begin{csimplemacrodesc}{name}
+% -- "simple" because it has no args; NOT for constant definitions!
+\newenvironment{csimplemacrodesc}[1]{
+  \begin{fulllineitems}
+    \item[\bfcode{#1}\index{#1@{\py@idxcode{#1}} (macro)}]
+}{\end{fulllineitems}}
+
+% simple functions (not methods) -----------------------------------------
+% \begin{funcdesc}{name}{args}
+\newcommand{\funcline}[2]{%
+  \funclineni{#1}{#2}%
+  \index{#1@{\py@idxcode{#1()}} (in module \py@thismodule)}}
+\newenvironment{funcdesc}[2]{
+  \begin{fulllineitems}
+    \funcline{#1}{#2}
+}{\end{fulllineitems}}
+
+% similar to {funcdesc}, but doesn't add to the index
+\newcommand{\funclineni}[2]{%
+  \py@sigline{\bfcode{#1}}{#2}}
+\newenvironment{funcdescni}[2]{
+  \begin{fulllineitems}
+    \funclineni{#1}{#2}
+}{\end{fulllineitems}}
+
+% classes ----------------------------------------------------------------
+% \begin{classdesc}{name}{constructor args}
+\newenvironment{classdesc}[2]{
+  % Using \renewcommand doesn't work for this, for unknown reasons:
+  \global\def\py@thisclass{#1}
+  \begin{fulllineitems}
+    \py@sigline{\strong{class }\bfcode{#1}}{#2}%
+    \index{#1@{\py@idxcode{#1}} (class in \py@thismodule)}
+}{\end{fulllineitems}}
+
+% \begin{classdesc*}{name}
+\newenvironment{classdesc*}[1]{
+  % Using \renewcommand doesn't work for this, for unknown reasons:
+  \global\def\py@thisclass{#1}
+  \begin{fulllineitems}
+    \item[\strong{class }\code{\bfcode{#1}}%
+      \index{#1@{\py@idxcode{#1}} (class in \py@thismodule)}]
+}{\end{fulllineitems}}
+
+% \begin{excclassdesc}{name}{constructor args}
+% but indexes as an exception
+\newenvironment{excclassdesc}[2]{
+  % Using \renewcommand doesn't work for this, for unknown reasons:
+  \global\def\py@thisclass{#1}
+  \begin{fulllineitems}
+    \py@sigline{\strong{exception }\bfcode{#1}}{#2}%
+    \index{#1@{\py@idxcode{#1}} (exception in \py@thismodule)}
+}{\end{fulllineitems}}
+
+% There is no corresponding {excclassdesc*} environment.  To describe
+% a class exception without parameters, use the {excdesc} environment.
+
+
+\let\py@classbadkey=\@undefined
+
+% object method ----------------------------------------------------------
+% \begin{methoddesc}[classname]{methodname}{args}
+\newcommand{\methodline}[3][\@undefined]{
+  \methodlineni{#2}{#3}
+  \ifx#1\@undefined
+    \index{#2@{\py@idxcode{#2()}} (\py@thisclass\ method)}
+  \else
+    \index{#2@{\py@idxcode{#2()}} (#1 method)}
+  \fi
+}
+\newenvironment{methoddesc}[3][\@undefined]{
+  \begin{fulllineitems}
+    \ifx#1\@undefined
+      \methodline{#2}{#3}
+    \else
+      \def\py@thisclass{#1}
+      \methodline{#2}{#3}
+    \fi
+}{\end{fulllineitems}}
+
+% similar to {methoddesc}, but doesn't add to the index
+% (never actually uses the optional argument)
+\newcommand{\methodlineni}[3][\py@classbadkey]{%
+  \py@sigline{\bfcode{#2}}{#3}}
+\newenvironment{methoddescni}[3][\py@classbadkey]{
+  \begin{fulllineitems}
+    \methodlineni{#2}{#3}
+}{\end{fulllineitems}}
+
+% object data attribute --------------------------------------------------
+% \begin{memberdesc}[classname]{membername}
+\newcommand{\memberline}[2][\py@classbadkey]{%
+  \ifx#1\@undefined
+    \memberlineni{#2}
+    \index{#2@{\py@idxcode{#2}} (\py@thisclass\ attribute)}
+  \else
+    \memberlineni{#2}
+    \index{#2@{\py@idxcode{#2}} (#1 attribute)}
+  \fi
+}
+\newenvironment{memberdesc}[2][\py@classbadkey]{
+  \begin{fulllineitems}
+    \ifx#1\@undefined
+      \memberline{#2}
+    \else
+      \def\py@thisclass{#1}
+      \memberline{#2}
+    \fi
+}{\end{fulllineitems}}
+
+% similar to {memberdesc}, but doesn't add to the index
+% (never actually uses the optional argument)
+\newcommand{\memberlineni}[2][\py@classbadkey]{\item[\bfcode{#2}]}
+\newenvironment{memberdescni}[2][\py@classbadkey]{
+  \begin{fulllineitems}
+    \memberlineni{#2}
+}{\end{fulllineitems}}
+
+% For exceptions: --------------------------------------------------------
+% \begin{excdesc}{name}
+%  -- for constructor information, use excclassdesc instead
+\newenvironment{excdesc}[1]{
+  \begin{fulllineitems}
+    \item[\strong{exception }\bfcode{#1}%
+          \index{#1@{\py@idxcode{#1}} (exception in \py@thismodule)}]
+}{\end{fulllineitems}}
+
+% Module data or constants: ----------------------------------------------
+% \begin{datadesc}{name}
+\newcommand{\dataline}[1]{%
+  \datalineni{#1}\index{#1@{\py@idxcode{#1}} (data in \py@thismodule)}}
+\newenvironment{datadesc}[1]{
+  \begin{fulllineitems}
+    \dataline{#1}
+}{\end{fulllineitems}}
+
+% similar to {datadesc}, but doesn't add to the index
+\newcommand{\datalineni}[1]{\item[\bfcode{#1}]\nopagebreak}
+\newenvironment{datadescni}[1]{
+  \begin{fulllineitems}
+    \datalineni{#1}
+}{\end{fulllineitems}}
+
+% bytecode instruction ---------------------------------------------------
+% \begin{opcodedesc}{name}{var}
+% -- {var} may be {}
+\newenvironment{opcodedesc}[2]{
+  \begin{fulllineitems}
+    \item[\bfcode{#1}\quad\var{#2}]
+}{\end{fulllineitems}}
+
+
+\newcommand{\nodename}[1]{\label{#1}}
+
+% For these commands, use \command{} to get the typography right, not 
+% {\command}.  This works better with the texinfo translation.
+\newcommand{\ABC}{{\sc abc}}
+\newcommand{\UNIX}{{\sc Unix}}
+\newcommand{\POSIX}{POSIX}
+\newcommand{\ASCII}{{\sc ascii}}
+\newcommand{\Cpp}{C\protect\raisebox{.18ex}{++}}
+\newcommand{\C}{C}
+\newcommand{\EOF}{{\sc eof}}
+\newcommand{\NULL}{\constant{NULL}}
+\newcommand{\infinity}{\ensuremath{\infty}}
+\newcommand{\plusminus}{\ensuremath{\pm}}
+
+% \guilabel{Start}
+\newcommand{\guilabel}[1]{\textsf{#1}}
+% \menuselection{Start \sub Programs \sub Python}
+\newcommand{\menuselection}[1]{\guilabel{{\def\sub{ \ensuremath{>} }#1}}}
+
+% Also for consistency: spell Python "Python", not "python"!
+
+% code is the most difficult one...
+\newcommand{\code}[1]{\textrm{\@vobeyspaces\@noligs\def\{{\char`\{}\def\}{\char`\}}\def\~{\char`\~}\def\^{\char`\^}\def\e{\char`\\}\def\${\char`\$}\def\#{\char`\#}\def\&{\char`\&}\def\%{\char`\%}%
+\texttt{#1}}}
+
+\newcommand{\bfcode}[1]{\code{\bfseries#1}} % bold-faced code font
+\newcommand{\csimplemacro}[1]{\code{#1}}
+\newcommand{\kbd}[1]{\code{#1}}
+\newcommand{\samp}[1]{`\code{#1}'}
+\newcommand{\var}[1]{%
+  \ifmmode%
+    \hbox{\py@defaultsize\textrm{\textit{#1\/}}}%
+  \else%
+    \py@defaultsize\textrm{\textit{#1\/}}%
+  \fi%
+}
+\renewcommand{\emph}[1]{{\em #1}}
+\newcommand{\dfn}[1]{\emph{#1}}
+\newcommand{\strong}[1]{{\bf #1}}
+% let's experiment with a new font:
+\newcommand{\file}[1]{`\filenq{#1}'}
+\newcommand{\filenq}[1]{{\py@smallsize\textsf{\let\e=\textbackslash#1}}}
+
+% Use this def/redef approach for \url{} since hyperref defined this already,
+% but only if we actually used hyperref:
+\ifpdf
+  \newcommand{\url}[1]{{%
+    \py@pdfstartlink attr{/Border [0 0 0]} user{/S /URI /URI (#1)}%
+    \py@LinkColor%                              color of the link text
+    \py@smallsize\sf #1%
+    \py@NormalColor%                    Turn it back off; these are declarative
+    \pdfendlink}%                       and don't appear bound to the current
+  }%                                    formatting "box".
+\else
+  \newcommand{\url}[1]{\mbox{\py@smallsize\textsf{#1}}}
+\fi
+\newcommand{\email}[1]{{\py@smallsize\textsf{#1}}}
+\newcommand{\newsgroup}[1]{{\py@smallsize\textsf{#1}}}
+
+\newcommand{\py@varvars}[1]{{%
+  {\let\unspecified=\py@unspecified%
+   \let\moreargs=\py@moreargs%
+   \var{#1}}}}
+
+% I'd really like to get rid of this!
+\newif\iftexi\texifalse
+
+% This is used to get l2h to put the copyright and abstract on
+% a separate HTML page.
+\newif\ifhtml\htmlfalse
+
+
+% These should be used for all references to identifiers which are
+% used to refer to instances of specific language constructs.  See the
+% names for specific semantic assignments.
+%
+% For now, don't do anything really fancy with them; just use them as
+% logical markup.  This might change in the future.
+%
+\newcommand{\module}[1]{\texttt{#1}}
+\newcommand{\keyword}[1]{\texttt{#1}}
+\newcommand{\exception}[1]{\texttt{#1}}
+\newcommand{\class}[1]{\texttt{#1}}
+\newcommand{\function}[1]{\texttt{#1}}
+\newcommand{\member}[1]{\texttt{#1}}
+\newcommand{\method}[1]{\texttt{#1}}
+
+\newcommand{\pytype}[1]{#1}             % built-in Python type
+
+\newcommand{\cfunction}[1]{\texttt{#1}}
+\newcommand{\ctype}[1]{\texttt{#1}}     % C struct or typedef name
+\newcommand{\cdata}[1]{\texttt{#1}}     % C variable, typically global
+
+\newcommand{\mailheader}[1]{{\py@smallsize\textsf{#1:}}}
+\newcommand{\mimetype}[1]{{\py@smallsize\textsf{#1}}}
+% The \! is a "negative thin space" in math mode.
+\newcommand{\regexp}[1]{%
+  {\tiny$^{^\lceil}\!\!$%
+   {\py@defaultsize\code{#1}}%
+   $\!\rfloor\!$%
+  }}
+\newcommand{\envvar}[1]{%
+  #1%
+  \index{#1}%
+  \index{environment variables!{#1}}%
+}
+\newcommand{\makevar}[1]{#1}            % variable in a Makefile
+\newcommand{\character}[1]{\samp{#1}}
+
+% constants defined in Python modules or C headers, not language constants:
+\newcommand{\constant}[1]{\code{#1}}    % manifest constant, not syntactic
+
+\newcommand{\manpage}[2]{{\emph{#1}(#2)}}
+\newcommand{\pep}[1]{PEP #1\index{Python Enhancement Proposals!PEP #1}}
+\newcommand{\rfc}[1]{RFC #1\index{RFC!RFC #1}}
+\newcommand{\program}[1]{\strong{#1}}
+\newcommand{\programopt}[1]{\strong{#1}}
+% Note that \longprogramopt provides the '--'!
+\newcommand{\longprogramopt}[1]{\strong{-{}-#1}}
+
+% \ulink{link text}{URL}
+\ifpdf
+  \newcommand{\ulink}[2]{{%
+    % For PDF, we *should* only generate a link when the URL is absolute.
+    \py@pdfstartlink attr{/Border [0 0 0]} user{/S /URI /URI (#2)}%
+    \py@LinkColor%                              color of the link text
+    #1%
+    \py@NormalColor%                    Turn it back off; these are declarative
+    \pdfendlink}%                       and don't appear bound to the current
+  }%                                    formatting "box".
+\else
+  \newcommand{\ulink}[2]{#1}
+\fi
+
+% cited titles:  \citetitle{Title of Work}
+%       online:  \citetitle[url-to-resource]{Title of Work}
+\ifpdf
+  \newcommand{\citetitle}[2][\py@modulebadkey]{%
+    \ifx\py@modulebadkey#1\emph{#2}\else\ulink{\emph{#2}}{#1}\fi%
+  }
+\else
+  \newcommand{\citetitle}[2][URL]{\emph{#2}}
+\fi
+
+
+
+% This version is being checked in for the historical record; it shows
+% how I've managed to get some aspects of this to work.  It will not
+% be used in practice, so a subsequent revision will change things
+% again.  This version has problems, but shows how to do something
+% that proved more tedious than I'd expected, so I don't want to lose
+% the example completely.
+%
+\newcommand{\grammartoken}[1]{\texttt{#1}}
+\newenvironment{productionlist}[1][\py@badkey]{
+  \def\optional##1{{\Large[}##1{\Large]}}
+  \def\production##1##2{\code{##1}&::=&\code{##2}\\}
+  \def\productioncont##1{& &\code{##1}\\}
+  \def\token##1{##1}
+  \let\grammartoken=\token
+  \parindent=2em
+  \indent
+  \begin{tabular}{lcl}
+}{%
+  \end{tabular}
+}
+
+\newlength{\py@noticelength}
+
+\newcommand{\py@heavybox}{
+  \setlength{\fboxrule}{2pt}
+  \setlength{\fboxsep}{7pt}
+  \setlength{\py@noticelength}{\linewidth}
+  \addtolength{\py@noticelength}{-2\fboxsep}
+  \addtolength{\py@noticelength}{-2\fboxrule}
+  \setlength{\shadowsize}{3pt}
+  \Sbox
+  \minipage{\py@noticelength}
+}
+\newcommand{\py@endheavybox}{
+  \endminipage
+  \endSbox
+  \fbox{\TheSbox}
+}
+
+% a 'note' is as plain as it gets:
+\newcommand{\py@noticelabel@note}{Note:}
+\newcommand{\py@noticestart@note}{}
+\newcommand{\py@noticeend@note}{}
+
+% a 'warning' gets more visible distinction:
+\newcommand{\py@noticelabel@warning}{Warning:}
+\newcommand{\py@noticestart@warning}{\py@heavybox}
+\newcommand{\py@noticeend@warning}{\py@endheavybox}
+
+\newenvironment{notice}[1][note]{
+  \def\py@noticetype{#1}
+  \csname py@noticestart@#1\endcsname
+  \par\strong{\csname py@noticelabel@#1\endcsname}
+}{\csname py@noticeend@\py@noticetype\endcsname}
+\newcommand{\note}[1]{\strong{\py@noticelabel@note} #1}
+\newcommand{\warning}[1]{\strong{\py@noticelabel@warning} #1}
+
+% Deprecation stuff.
+% Should be extended to allow an index / list of deprecated stuff.  But
+% there's a lot of stuff that needs to be done to make that automatable.
+%
+% First parameter is the release number that deprecates the feature, the
+% second is the action the should be taken by users of the feature.
+%
+% Example:
+%  \deprecated{1.5.1}{Use \method{frobnicate()} instead.}
+%
+\newcommand{\deprecated}[2]{%
+  \strong{Deprecated since release #1.}  #2\par}
+
+% New stuff.
+% This should be used to mark things which have been added to the
+% development tree but that aren't in the release, but are documented.
+% This allows release of documentation that already includes updated
+% descriptions.  Place at end of descriptor environment.
+%
+% Example:
+%  \versionadded{1.5.2}
+%  \versionchanged[short explanation]{2.0}
+%
+\newcommand{\versionadded}[2][\py@badkey]{%
+  \ifx#1\@undefined%
+    {  New in version #2.  }%
+  \else%
+    {  New in version #2:\ #1.  }%
+  \fi%
+}
+\newcommand{\versionchanged}[2][\py@badkey]{%
+  \ifx#1\@undefined%
+    {  Changed in version #2.  }%
+  \else%
+    {  Changed in version #2:\ #1.  }%
+  \fi%
+}
+
+
+% Tables.
+%
+\newenvironment{tableii}[4]{%
+  \begin{center}%
+    \def\lineii##1##2{\csname#2\endcsname{##1}&##2\\}%
+    \begin{tabular}{#1}\strong{#3}&\strong{#4} \\* \hline%
+}{%
+    \end{tabular}%
+  \end{center}%
+}
+
+\newenvironment{longtableii}[4]{%
+  \begin{center}%
+    \def\lineii##1##2{\csname#2\endcsname{##1}&##2\\}%
+    \begin{longtable}[c]{#1}\strong{#3}&\strong{#4} \\* \hline\endhead%
+}{%
+    \end{longtable}%
+  \end{center}%
+}
+
+\newenvironment{tableiii}[5]{%
+  \begin{center}%
+    \def\lineiii##1##2##3{\csname#2\endcsname{##1}&##2&##3\\}%
+    \begin{tabular}{#1}\strong{#3}&\strong{#4}&\strong{#5} \\%
+      \hline%
+}{%
+    \end{tabular}%
+  \end{center}%
+}
+
+\newenvironment{longtableiii}[5]{%
+  \begin{center}%
+    \def\lineiii##1##2##3{\csname#2\endcsname{##1}&##2&##3\\}%
+    \begin{longtable}[c]{#1}\strong{#3}&\strong{#4}&\strong{#5} \\%
+      \hline\endhead%
+}{%
+    \end{longtable}%
+  \end{center}%
+}
+
+\newenvironment{tableiv}[6]{%
+  \begin{center}%
+    \def\lineiv##1##2##3##4{\csname#2\endcsname{##1}&##2&##3&##4\\}%
+    \begin{tabular}{#1}\strong{#3}&\strong{#4}&\strong{#5}&\strong{#6} \\%
+      \hline%
+}{%
+    \end{tabular}%
+  \end{center}%
+}
+
+\newenvironment{longtableiv}[6]{%
+  \begin{center}%
+    \def\lineiv##1##2##3##4{\csname#2\endcsname{##1}&##2&##3&##4\\}%
+    \begin{longtable}[c]{#1}\strong{#3}&\strong{#4}&\strong{#5}&\strong{#6}%
+      \\%
+      \hline\endhead%
+}{%
+    \end{longtable}%
+  \end{center}%
+}
+
+\newenvironment{tablev}[7]{%
+  \begin{center}%
+    \def\linev##1##2##3##4##5{\csname#2\endcsname{##1}&##2&##3&##4&##5\\}%
+    \begin{tabular}{#1}\strong{#3}&\strong{#4}&\strong{#5}&\strong{#6}&\strong{#7} \\%
+      \hline%
+}{%
+    \end{tabular}%
+  \end{center}%
+}
+
+\newenvironment{longtablev}[7]{%
+  \begin{center}%
+    \def\linev##1##2##3##4##5{\csname#2\endcsname{##1}&##2&##3&##4&##5\\}%
+    \begin{longtable}[c]{#1}\strong{#3}&\strong{#4}&\strong{#5}&\strong{#6}&\strong{#7}%
+      \\%
+      \hline\endhead%
+}{%
+    \end{longtable}%
+  \end{center}%
+}
+
+% XXX Don't think we can use this yet, though it cleans up some
+% tedious markup.  There's no equivalent for the HTML transform yet,
+% and that needs to exist.  I don't know how to write it.
+%
+% This should really have something that makes it easier to bind a
+% table's ``Notes'' column and an associated tablenotes environment,
+% and generates the right magic for getting the numbers right in the
+% table.
+%
+% So this is quite incomplete.
+%
+\newcounter{py@tablenotescounter}
+\newenvironment{tablenotes}{%
+  \noindent Notes:
+  \par
+  \setcounter{py@tablenotescounter}{0}
+  \begin{list}{(\arabic{py@tablenotescounter})}%
+              {\usecounter{py@tablenotescounter}}
+}{\end{list}}
+
+
+% Cross-referencing (AMK, new impl. FLD)
+% Sample usage:
+%  \begin{seealso}
+%    \seemodule{rand}{Uniform random number generator.}; % Module xref
+%    \seetext{\emph{Encyclopedia Britannica}}.           % Ref to a book
+% 
+%    % A funky case: module name contains '_'; have to supply an optional key
+%    \seemodule[copyreg]{copy_reg}{Interface constructor registration for
+%                                  \module{pickle}.}
+%  \end{seealso}
+%
+% Note that the last parameter for \seemodule and \seetext should be complete
+% sentences and be terminated with the proper punctuation.
+
+\ifpdf
+  \newcommand{\py@seemodule}[3][\py@modulebadkey]{%
+    \par%
+    \ifx\py@modulebadkey#1\def\py@modulekey{#2}\else\def\py@modulekey{#1}\fi%
+    \begin{fulllineitems}
+      \item[\py@linkToName{label-module-\py@modulekey}{Module \module{#2}}
+            (section \ref{module-\py@modulekey}):]
+      #3
+    \end{fulllineitems}
+  }
+\else
+  \newcommand{\py@seemodule}[3][\py@modulebadkey]{%
+    \par%
+    \ifx\py@modulebadkey#1\def\py@modulekey{#2}\else\def\py@modulekey{#1}\fi%
+    \begin{fulllineitems}
+      \item[Module \module{#2} (section \ref{module-\py@modulekey}):]
+      #3
+    \end{fulllineitems}
+  }
+\fi
+
+% \seelink{url}{link text}{why it's interesting}
+\newcommand{\py@seelink}[3]{%
+  \par
+  \begin{fulllineitems}
+    \item[\ulink{#2}{#1}]
+    #3
+  \end{fulllineitems}
+}
+% \seetitle[url]{title}{why it's interesting}
+\newcommand{\py@seetitle}[3][\py@modulebadkey]{%
+  \par
+  \begin{fulllineitems}
+    \item[\citetitle{#2}]
+    \ifx\py@modulebadkey#1\else
+      \item[{\small{(\url{#1})}}]
+    \fi
+    #3
+  \end{fulllineitems}
+}
+% \seepep{number}{title}{why it's interesting}
+\newcommand{\py@seepep}[3]{%
+  \par%
+  \begin{fulllineitems}
+    \item[\pep{#1}, ``\emph{#2}'']
+    #3
+  \end{fulllineitems}
+}
+% \seerfc{number}{title}{why it's interesting}
+\newcommand{\py@seerfc}[3]{%
+  \par%
+  \begin{fulllineitems}
+    \item[\rfc{#1}, ``\emph{#2}'']
+    #3
+  \end{fulllineitems}
+}
+% \seeurl{url}{why it's interesting}
+\newcommand{\py@seeurl}[2]{%
+  \par%
+  \begin{fulllineitems}
+    \item[\url{#1}]
+    #2
+  \end{fulllineitems}
+}
+
+\newenvironment{seealso*}{
+  \par
+  \def\seetext##1{\par{##1}}
+  \let\seemodule=\py@seemodule
+  \let\seepep=\py@seepep
+  \let\seerfc=\py@seerfc
+  \let\seetitle=\py@seetitle
+  \let\seeurl=\py@seeurl
+  \let\seelink=\py@seelink
+}{\par}
+\newenvironment{seealso}{
+  \par
+  \strong{See Also:}
+  \par
+  \def\seetext##1{\par{##1}}
+  \let\seemodule=\py@seemodule
+  \let\seepep=\py@seepep
+  \let\seerfc=\py@seerfc
+  \let\seetitle=\py@seetitle
+  \let\seeurl=\py@seeurl
+  \let\seelink=\py@seelink
+}{\par}
+
+% Allow the Python release number to be specified independently of the
+% \date{}.  This allows the date to reflect the document's date and
+% release to specify the Python release that is documented.
+%
+\newcommand{\py@release}{}
+\newcommand{\version}{}
+\newcommand{\shortversion}{}
+\newcommand{\releaseinfo}{}
+\newcommand{\releasename}{Release}
+\newcommand{\release}[1]{%
+  \renewcommand{\py@release}{\releasename\space\version}%
+  \renewcommand{\version}{#1}}
+\newcommand{\setshortversion}[1]{%
+  \renewcommand{\shortversion}{#1}}
+\newcommand{\setreleaseinfo}[1]{%
+  \renewcommand{\releaseinfo}{#1}}
+
+% Allow specification of the author's address separately from the
+% author's name.  This can be used to format them differently, which
+% is a good thing.
+%
+\newcommand{\py@authoraddress}{}
+\newcommand{\authoraddress}[1]{\renewcommand{\py@authoraddress}{#1}}
+\let\developersaddress=\authoraddress
+\let\developer=\author
+\let\developers=\author
+
+% This sets up the fancy chapter headings that make the documents look
+% at least a little better than the usual LaTeX output.
+%
+\@ifundefined{ChTitleVar}{}{
+  \ChNameVar{\raggedleft\normalsize\py@HeaderFamily}
+  \ChNumVar{\raggedleft \bfseries\Large\py@HeaderFamily}
+  \ChTitleVar{\raggedleft \rm\Huge\py@HeaderFamily}
+  % This creates chapter heads without the leading \vspace*{}:
+  \def\@makechapterhead#1{%
+    {\parindent \z@ \raggedright \normalfont
+      \ifnum \c@secnumdepth >\m@ne
+        \DOCH
+      \fi
+      \interlinepenalty\@M
+      \DOTI{#1}
+    }
+  }
+}
+
+
+% Definition lists; requested by AMK for HOWTO documents.  Probably useful
+% elsewhere as well, so keep in in the general style support.
+%
+\newenvironment{definitions}{%
+  \begin{description}%
+  \def\term##1{\item[##1]\mbox{}\\*[0mm]}
+}{%
+  \end{description}%
+}
+
+% Tell TeX about pathological hyphenation cases:
+\hyphenation{Base-HTTP-Re-quest-Hand-ler}
Index: /anuga_core/documentation/user_manual/triangularmesh.fig
===================================================================
--- /anuga_core/documentation/user_manual/triangularmesh.fig	(revision 3574)
+++ /anuga_core/documentation/user_manual/triangularmesh.fig	(revision 3574)
@@ -0,0 +1,133 @@
+#FIG 3.2  Produced by xfig version 3.2.5-alpha5
+Landscape
+Center
+Metric
+A4      
+100.00
+Single
+-2
+1200 2
+1 3 0 1 0 0 50 -1 20 0.000 1 0.0000 4500 1350 64 64 4500 1350 4564 1350
+1 3 0 1 0 0 50 -1 20 0.000 1 0.0000 4500 3600 64 64 4500 3600 4564 3600
+1 3 0 1 0 0 50 -1 20 0.000 1 0.0000 4500 4500 64 64 4500 4500 4564 4500
+1 3 0 1 0 0 50 -1 20 0.000 1 0.0000 5850 4050 64 64 5850 4050 5914 4050
+1 3 0 1 0 0 50 -1 20 0.000 1 0.0000 5400 2250 64 64 5400 2250 5464 2250
+1 3 0 1 0 0 50 -1 20 0.000 1 0.0000 5850 900 64 64 5850 900 5914 900
+1 3 0 1 0 0 50 -1 20 0.000 1 0.0000 6300 2700 64 64 6300 2700 6364 2700
+1 3 0 1 0 0 50 -1 20 0.000 1 0.0000 7650 4500 64 64 7650 4500 7714 4500
+1 3 0 1 0 0 50 -1 20 0.000 1 0.0000 7650 2250 64 64 7650 2250 7714 2250
+1 3 0 1 0 0 50 -1 20 0.000 1 0.0000 9000 2700 64 64 9000 2700 9064 2700
+1 3 0 1 0 0 50 -1 20 0.000 1 0.0000 8550 1800 64 64 8550 1800 8614 1800
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
+	 4500 4500 5850 4050
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 3
+	 4500 4500 4500 3600 5850 4050
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 3
+	 4500 3600 6300 2700 5850 4050
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 3
+	 5850 4050 7650 4500 6300 2700
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 3
+	 6300 2700 7650 2250 7650 4500
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 3
+	 4500 3600 5400 2250 6300 2700
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 4
+	 5400 2250 4500 1350 5850 900 5400 2250
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
+	 5850 900 6300 2700
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
+	 5850 900 7650 2250
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 3
+	 7650 2250 9000 2700 7650 4500
+2 1 0 2 0 7 50 -1 -1 0.000 0 0 -1 1 0 2
+	2 1 4.00 60.00 120.00
+	 4050 4950 4050 450
+2 1 0 2 0 7 50 -1 -1 0.000 0 0 -1 1 0 2
+	2 1 4.00 60.00 120.00
+	 4050 4950 9450 4950
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
+	 4500 4950 4500 5130
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
+	 4950 4950 4950 5130
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
+	 5400 4950 5400 5130
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
+	 5850 4950 5850 5130
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
+	 6300 4950 6300 5130
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
+	 6750 4950 6750 5130
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
+	 7200 4950 7200 5130
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
+	 7650 4950 7650 5130
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
+	 8100 4950 8100 5130
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
+	 8550 4950 8550 5130
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
+	 9000 4950 9000 5130
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
+	 4050 4500 3960 4500
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
+	 4050 4500 3870 4500
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
+	 4050 4050 3870 4050
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
+	 4050 3600 3870 3600
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
+	 4050 3150 3870 3150
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
+	 4050 2700 3870 2700
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
+	 4050 2250 3870 2250
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
+	 4050 1800 3870 1800
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
+	 4050 1350 3870 1350
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
+	 4050 900 3870 900
+2 1 0 1 0 0 50 -1 -1 0.000 0 0 -1 0 0 3
+	 5850 900 8550 1800 7650 2250
+4 0 0 50 -1 0 12 0.0000 4 150 105 4050 5400 0\001
+4 0 0 50 -1 0 12 0.0000 4 150 105 4500 5400 1\001
+4 0 0 50 -1 0 12 0.0000 4 150 105 4950 5400 2\001
+4 0 0 50 -1 0 12 0.0000 4 150 105 5400 5400 3\001
+4 0 0 50 -1 0 12 0.0000 4 150 105 5850 5400 4\001
+4 0 0 50 -1 0 12 0.0000 4 150 105 6300 5400 5\001
+4 0 0 50 -1 0 12 0.0000 4 150 105 6750 5400 6\001
+4 0 0 50 -1 0 12 0.0000 4 150 105 7200 5400 7\001
+4 0 0 50 -1 0 12 0.0000 4 150 105 7650 5400 8\001
+4 0 0 50 -1 0 12 0.0000 4 150 105 8100 5400 9\001
+4 0 0 50 -1 0 12 0.0000 4 150 210 8550 5400 10\001
+4 0 0 50 -1 0 12 0.0000 4 150 210 9000 5400 11\001
+4 0 0 50 -1 0 12 0.0000 4 150 105 3600 4950 0\001
+4 0 0 50 -1 0 12 0.0000 4 150 105 3600 4500 1\001
+4 0 0 50 -1 0 12 0.0000 4 150 105 3600 4050 2\001
+4 0 0 50 -1 0 12 0.0000 4 150 105 3600 3600 3\001
+4 0 0 50 -1 0 12 0.0000 4 150 105 3600 3150 4\001
+4 0 0 50 -1 0 12 0.0000 4 150 105 3600 2700 5\001
+4 0 0 50 -1 0 12 0.0000 4 150 105 3600 2250 6\001
+4 0 0 50 -1 0 12 0.0000 4 150 105 3600 1800 7\001
+4 0 0 50 -1 0 12 0.0000 4 150 105 3600 1350 8\001
+4 0 0 50 -1 0 12 0.0000 4 150 105 3600 900 9\001
+4 0 0 50 -1 2 12 0.0000 4 150 105 7200 3150 2\001
+4 0 0 50 -1 2 12 0.0000 4 150 105 8100 3150 3\001
+4 0 0 50 -1 2 12 0.0000 4 150 105 6750 2250 4\001
+4 0 0 50 -1 2 12 0.0000 4 150 105 5850 2250 5\001
+4 0 0 50 -1 2 12 0.0000 4 150 105 5220 1710 7\001
+4 0 0 50 -1 2 12 0.0000 4 150 105 5580 3510 8\001
+4 0 0 50 -1 2 12 0.0000 4 150 105 6570 3870 1\001
+4 0 0 50 -1 2 12 0.0000 4 150 105 5400 2880 6\001
+4 0 0 50 -1 0 12 0.0000 4 150 105 5805 4365 1\001
+4 0 0 50 -1 0 12 0.0000 4 150 105 7650 4770 2\001
+4 0 0 50 -1 0 12 0.0000 4 150 105 4500 4770 0\001
+4 0 0 50 -1 0 12 0.0000 4 150 105 4320 3690 3\001
+4 0 0 50 -1 0 12 0.0000 4 150 105 9135 2790 6\001
+4 0 0 50 -1 0 12 0.0000 4 150 105 4455 1170 8\001
+4 0 0 50 -1 0 12 0.0000 4 150 105 5940 765 9\001
+4 0 0 50 -1 2 12 0.0000 4 150 105 4950 4050 0\001
+4 0 0 50 -1 0 12 0.0000 4 150 105 6525 2880 4\001
+4 0 0 50 -1 0 12 0.0000 4 150 105 5175 2340 7\001
+4 0 0 50 -1 2 12 0.0000 4 150 105 7425 1800 9\001
+4 0 0 50 -1 0 12 0.0000 4 150 210 8640 1755 10\001
+4 0 0 50 -1 0 12 0.0000 4 150 105 7740 2565 5\001
Index: /anuga_core/documentation/user_manual/underscore.sty
===================================================================
--- /anuga_core/documentation/user_manual/underscore.sty	(revision 3574)
+++ /anuga_core/documentation/user_manual/underscore.sty	(revision 3574)
@@ -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{|}~
Index: /anuga_core/documentation/user_manual/update_anuga_user_manual.py
===================================================================
--- /anuga_core/documentation/user_manual/update_anuga_user_manual.py	(revision 3574)
+++ /anuga_core/documentation/user_manual/update_anuga_user_manual.py	(revision 3574)
@@ -0,0 +1,49 @@
+#!/usr/bin/env python
+
+"""Update, compile and create PDF and HTML from LaTeX file
+
+This can for example be run from a cronjob:
+
+  crontab -e
+
+with content 
+
+SHELL=/bin/sh
+PATH=/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin:~/bin
+
+# m h dom mon dow command
+  42 *  *   *   *  ~/anuga/documentation/user_manual/update_anuga_user_manual.py > ~/anuga/documentation/user_manual/update_anuga.log
+#
+
+
+Note UNIX only
+ 
+"""
+
+
+import os
+
+
+anugapath = os.path.expanduser('~/anuga/documentation/user_manual')
+texfiles = ['anuga_user_manual', 'anuga_installation_guide']
+
+os.chdir(anugapath) # Move to location of LaTeX files 
+os.system('svn up') # Update from svn
+
+
+for texfile in texfiles:
+    print 'Processing %s' %texfile
+    # Compile with LaTeX, makeindex etc
+    for i in range(3):
+        os.system('latex --interaction=nonstopmode %s.tex' %texfile)
+        os.system('makeindex %s.idx' %texfile)
+        os.system('makeindex mod%s.idx' %texfile)
+        os.system('bibtex %s' %texfile)    
+
+    # Create pdf file
+    os.system('dvips %s -o %s.ps' %((texfile,)*2))    
+    os.system('ps2pdf %s.ps' %texfile)    
+     
+    # Create html pages     
+    os.system('latex2html %s' %texfile)
+
Index: /anuga_core/documentation/workplans_2004_2005/deliverables_Version2004-1.txt
===================================================================
--- /anuga_core/documentation/workplans_2004_2005/deliverables_Version2004-1.txt	(revision 3574)
+++ /anuga_core/documentation/workplans_2004_2005/deliverables_Version2004-1.txt	(revision 3574)
@@ -0,0 +1,76 @@
+Deliverables: Goals to achieve
+------------------------------
+
+Per 4/7/2004:
+-----------
+
+1:Finite volume simulations of water flow in a large (10-20 thousand volumes) 
+  general domain (runtime < 24 hours)
+  Done
+
+2:Suitable visualisation
+
+3:Verification against analytical solutions
+
+4:Parallel capability (later)
+
+5:Incorporation of friction, windfields and tides.
+
+
+Year 4/5:
+---------
+
+0. Maly Vale consultancey and two trips to Merimbula (C) 
+   August 2004     
+
+1. Model Description Report 
+   (Description, mathematics and algorithms behind the storm surge model) 
+   Chris, Stephen (September 2004)
+   
+   Merimbula case study, (November 2004)
+   
+2. Reference Manual (How the programming framework is structured) 
+   Ole, Duncan, Stephen (November 2004)
+
+3. User Manual (How to use the model) 
+   Ole, Duncan, Chris, Stephen (November 2004)
+
+4. Two papers on the comparison of the model with existing 
+   storm surge models and actual data. 
+   Ole, Duncan, Chris, Stephen (December 2004)
+   
+5. Send model to review, (Chris February 2004)
+   
+6. Single processor version of the Storm Surge hazard model 
+   released on CD or on the net integrating the 
+   Storm Surge model, animation, pMesh, examples and case study. 
+   Ole, Duncan, Chris, Stephen (April 2005)
+
+7. Parallel implementation of the Storm Surge model released 
+   Ole, Duncan, Stephen (June 2005)
+
+   
+8. Wave modelling, Stephen (May 2005)
+   
+Bushfire (D+C) July
+Viz (O+D) Oct
+
+Beowulf Ole, Duncan (March 2005)
+ 
+Travel logic:
+--------------
+1 trip to Manly Vale (Sydney) in August
+1 trip to Merimbula in August
+1 Trip to Merimbula when work is being done (August or September)
+1 trip to Manly Vale (Sydney) in September to wrap up
+ 
+ 
+Year 5/6 and beyond
+--------------------
+
+7. Integration of Storm Surge model with iFlood (Dec 2005)
+
+8. Investigation of modelling of surface waves in Storm Surge model Chris, Stephen (June 2005)
+
+
+GUI ?
Index: /anuga_core/documentation/workplans_2004_2005/publications.txt
===================================================================
--- /anuga_core/documentation/workplans_2004_2005/publications.txt	(revision 3574)
+++ /anuga_core/documentation/workplans_2004_2005/publications.txt	(revision 3574)
@@ -0,0 +1,53 @@
+Planned publications 2004
+-------------------------
+
+CTAC 2004 (September): Stephen, Chris, Ole, Duncan
+
+     5-10 pages describing algorithm: Limiters, 
+	  casting of equations in terms of stage 
+	  instead of height as the dependent variable.
+
+	  
+	  
+ASCE Hydraulics Journal: Chris, Stephen, Delis and Sampson 
+     Review of non Riemann solver based schemes; The relaxation and 
+     central schemes and publishing the Sampson analytical solution. 
+     First Draft Completed.
+     
+
+
+Estuarine Coastal and Shelf Science: 
+            1: Chris, Stephen, Ole, Kepert, Duncan 
+	    Describing the Storm Surge model from the finite 
+	    volume to the cyclone model. (Take some from CTAC paper)
+
+            2: Chris, Ole, Stephen, Duncan, Kepert
+	    Application of the Storm Surge model to an actual 
+	    cyclone e.g. cyclone Vance.
+     
+
+ASCE Environmental Engineering or 
+ASCE Ocean and Coastal Engineering: Stephen, Chris, Ole
+     Describing the mathematics of flow over a step and its application to 
+     Merimbula to demonstrate wetting and drying process and 
+     discontinuity in the bed profile. Sampsons 2-D solution and 
+     Greenspans solution used here.
+          
+     
+Python Conference 2005: Ole, Stephen, Duncan 
+     Paper(s) on architecture, use of consecutive data structures, 
+     the modelling framework and pmesh. 1 or 2 papers.
+     
+     
+
+ASCE Hydraulics Journal: Chris, Stephen, Koh, Marchant, Barnes
+      Looking at how to incorporate the Boussinesq terms into the 
+      flux terms of the shallow water wave equation and solving using 
+      the central and generalized Riemann solvers and comparison with 
+      4th order finite difference scheme.
+
+
+Monthly Weather Review: Stephen Chris, Ole, Kepert, Duncan 
+	Describing the Storm Surge model, its efficiency, robustness 
+	and capability with a case study and using the Central scheme, 
+	Generalized Riemann solver and Kinetic theory scheme.
Index: /anuga_core/documentation/workplans_2004_2005/tasks.txt
===================================================================
--- /anuga_core/documentation/workplans_2004_2005/tasks.txt	(revision 3574)
+++ /anuga_core/documentation/workplans_2004_2005/tasks.txt	(revision 3574)
@@ -0,0 +1,90 @@
+TASKS AS OF 20/5/4
+-------------------------
+
+
+Task:		Alpha shapes		
+Who:		Duncan+Chris	
+Priority:	Mid
+Status:
+	Looked at Matlab code.
+	Not immediately usable.
+	Perhaps need assistance from author (17/3)
+	On hold until we know if we can get money to pay author to help (20/5)
+	
+
+Task:		Vertex info - Friction	
+Who:		Duncan
+Priority:	Mid		
+Status:		Done
+
+
+
+Task:		Visualisation		
+Who:		Ole, Darran, Duncan
+Priority:	High
+Status:
+	Contract drafted and sent to Trish (17/3/4)
+	Planned to take place in May  
+	Darran started 3/5/4 and good progress is made (20/5)
+	First version done at 3/4 of the time by 4/6
+  
+
+Task:		Speed    
+Who:		Ole, Steve, Duncan
+Priority	High
+Status:		(24/3) Ole to suggest draft architecture of production code
+		Done by 23/4:
+		Changed underlying datastructure to consecutive arrays,
+		rewrote and implemented flux, distribute and 
+		update_conserved_quantities in C  
+		Problem that took 42s now takes 0.3s (23/4)
+			
+
+
+Task:		Region info in pmesh
+Who:	        Duncan
+Priority:	Low
+Status:		Done (20/5)
+
+
+Task:		Variable resolution in pmesh
+Who:		Duncan
+Priority:	Mid
+Suggestion:     Use region in pmesh to enable variable resolution
+Status:		Unresolved (20/5), Done (?) Early June
+
+
+
+Task: Discontinuous bathymetries
+Who:  Steve, Chris
+Pri: High
+Status: New architecture can represent dixcontinuities, but they are 
+	not yet in use. (20/5) 
+
+
+Task: Windfield (Holland)
+Who:  Ole
+Pri: Mid
+Status: Got fortran code, look at this in June.
+
+
+Task: Tide model
+Who: Chris
+Pri: High
+Status: Verified except issu with datum (20/5)
+
+
+Task: Level at selected points:
+Who: Steve, Ole
+Pri: High
+Status:
+Implemented functional way of setting field values and conserved quantities. 
+(April 2004)
+
+
+Task: verification against analytical solutions 
+Who: Duncan, Chris
+Pri: Mid
+Status: To be looked at in June or July 2004
+
+
