Index: /documentation/planning/issues_pre_trac.txt
===================================================================
--- /documentation/planning/issues_pre_trac.txt	(revision 3468)
+++ /documentation/planning/issues_pre_trac.txt	(revision 3468)
@@ -0,0 +1,208 @@
+
+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: /documentation/user_manual/old_pyvolution_documentation/limiting.tex
===================================================================
--- /documentation/user_manual/old_pyvolution_documentation/limiting.tex	(revision 3468)
+++ /documentation/user_manual/old_pyvolution_documentation/limiting.tex	(revision 3468)
@@ -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: /documentation/user_manual/old_pyvolution_documentation/ls.tex
===================================================================
--- /documentation/user_manual/old_pyvolution_documentation/ls.tex	(revision 3468)
+++ /documentation/user_manual/old_pyvolution_documentation/ls.tex	(revision 3468)
@@ -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: /documentation/user_manual/old_pyvolution_documentation/mesh.fig
===================================================================
--- /documentation/user_manual/old_pyvolution_documentation/mesh.fig	(revision 3468)
+++ /documentation/user_manual/old_pyvolution_documentation/mesh.fig	(revision 3468)
@@ -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: /documentation/user_manual/old_pyvolution_documentation/mesh_example.fig
===================================================================
--- /documentation/user_manual/old_pyvolution_documentation/mesh_example.fig	(revision 3468)
+++ /documentation/user_manual/old_pyvolution_documentation/mesh_example.fig	(revision 3468)
@@ -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: /documentation/user_manual/old_pyvolution_documentation/pyvolution_structure.tex
===================================================================
--- /documentation/user_manual/old_pyvolution_documentation/pyvolution_structure.tex	(revision 3468)
+++ /documentation/user_manual/old_pyvolution_documentation/pyvolution_structure.tex	(revision 3468)
@@ -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: /documentation/user_manual/old_pyvolution_documentation/triangle.fig
===================================================================
--- /documentation/user_manual/old_pyvolution_documentation/triangle.fig	(revision 3468)
+++ /documentation/user_manual/old_pyvolution_documentation/triangle.fig	(revision 3468)
@@ -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: undation/pyvolution/wiki/issues_pre_trac.txt
===================================================================
--- /inundation/pyvolution/wiki/issues_pre_trac.txt	(revision 3467)
+++ 	(revision )
@@ -1,208 +1,0 @@
-
-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
-
