= Modelling Questions =
== What type of problems is ANUGA good for? ==

General 2D waterflows in complex geometries such as
dam breaks, flows among structures, coastal inundation etc.

== What type of problems are beyond the scope of ANUGA? ==

See the chapter on "Restrictions and Limitations" in the [http://datamining.anu.edu.au/~ole/anuga/user_manual/anuga_user_manual.pdf User Manual].

== Can I start the simulation at an arbitrary time? ==

Yes, using {{{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.

== Can I change values for any quantity during the simulation? ==

Yes, by using {{{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.

== Can I change boundary conditions during the simulation? ==

Yes, see the example in the section "Changing boundary conditions on the fly" in the 
[http://datamining.anu.edu.au/~ole/anuga/user_manual/anuga_user_manual.pdf User Manual].

== How do I access model time during the simulation? ==

The variable {{{t}}} in the evolve for loop is the model time.
For example to change the boundary at a particular time (instead of basing this on the state
of the system as in the "Changing boundary conditions on the fly" section of the manual)
one would write something like
{{{
for t in domain.evolve(yieldstep = 0.2, duration = 40.0):
    if Numeric.allclose(t, 15):
        print 'Changing boundary to outflow'
        domain.set_boundary({'right': Bo})
}}}
The model time can also be accessed through the public interface {{{domain.get_time()}}},
or changed (at your own peril) through {{{domain.set_time()}}}.

== Why does a file_function return a list of numbers when evaluated? ==

Currently, file_function works by returning values for the conserved
quantities {{{stage}}}, {{{xmomentum}}} and {{{ymomentum}}} at a given point in time
and space as a triplet. To access, or example, {{{stage}}} one must specify element 0 of the
triplet returned by file_function, to access {{{xmomentum}}} one must specify element 1 of the triplet, etc.

== How do I use a DEM in my simulation? ==

You use {{{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 {{{domain.set_quantity}}}.

== What sort of DEM resolution should I use? ==

Try and work with the '''best''' you have available. Onshore DEMs
are typically available in 25m, 100m and 250m grids. Note, offshore
data is often sparse, or non-existent.

Note that onshore DEMS can be much finer as the underlying datasets from which they
are created often contain several datapoints per squate metre.
It may be necessary to thin out the data so that it can be imported
without exceeding available memory. One tool available on the net is called 'decimate'. (Need reference?).

== 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 square metres (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.
If meshes are too coarse, discretisation errors in both stage and momentum may lead to unrealistic results. All studies should include sensitivity and convergence studies based on different resolutions.

== 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:
{{{
# 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)
}}}

Note that a mesh object is returned from {{{create_mesh_from_regions}}}
when file name is omitted.

== 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 {{{run_sydney_smf.py}}} example).

== How can I set the friction in different areas in the domain? ==

The model area will typically be estimating the water height and momentum over varying
topographies which will have different friction values. One way of assigning
different friction values is to create polygons (say {{{poly1, poly2 and poly3}}}) describing each
area and then set the corresponding friction values in the following way:

{{{
domain.set_quantity('friction',Polygon_function([(poly1,f1), (poly2,f2), (poly3,f3))]))
}}}

The values of {{{f1}}}, {{{f2}}} and {{{f3}}} could be constant or functions
as determined by the user.

== How can I combine data sets? ==

A user may have access to a range of different resolution DEMs and raw data points (such
as beach profiles, spot heights, single or multi-beam data etc) and will need
to combine them to create an overall elevation data set.

If there are multiple DEMs, say of 10m and 25m resolution, then the technique is similar to
that defined in the Cairns example described earlier, that is:

{{{
convert_dem_from_ascii2netcdf(10m_dem_name, use_cache=True, verbose=True)
convert_dem_from_ascii2netcdf(25m_dem_name, use_cache=True, verbose=True)
}}}
followed by:
{{{
dem2pts(10m_dem_name, use_cache=True, verbose=True)
dem2pts(25m_dem_name, use_cache=True, verbose=True)
}}}
These data sets can now be combined by
{{{
from anuga.geospatial_data.geospatial_data import *
G1 = Geospatial_data(file_name = 10m_dem_name + '.pts')
G2 = Geospatial_data(file_name = 25m_dem_name + '.pts')
G = G1 + G2
G.export_points_file(combined_dem_name + '.pts')
}}}
This is the basic way of combining data sets, however, the user will need to
assess the boundaries of each data set and whether they overlap. For example, consider
if the 10m DEM is describing by {{{poly1}}} and the 25m DEM is described by {{{poly2}}}
with {{{poly1}}} completely enclosed in {{{poly2}}} as shown here:
\begin{figure}[hbt]
  \centerline{\includegraphics{graphics/polyanddata.jpg}}
  \caption{Polygons describing the extent of the 10m and 25m DEM.}
  \label{fig:polydata}
\end{figure}
To combine the data sets, the geospatial addition is updated to
{{{
G = G1 + G2.clip_outside(Geospatial_data(poly1))
}}}
For this example, we assume that {{{poly2}}} is the domain, otherwise an additional dataset
would be required for the remainder of the domain.

This technique can be expanded to handle point data sets as well. In the case
of a bathymetry data set available in text format in an {{{.csv}}} file, then
the geospatial addition is updated to
{{{
G3 = Geospatial_data(file_name = bathy_data_name + '.csv')
G = G1 + G2.clip_outside(Geospatial_data(poly1)) + G3
}}}
The {{{.csv}}} file has the data stored as {{{x,y,elevation}} with the text {{{elevation}}}
on the first line.

The coastline could be included
as part of the clipping polygon to separate the offshore and onshore datasets if required.
Assume that {{{poly1}}} crosses the coastline
In this case, two new polygons could be created out of {{{poly1}}} which uses the coastline
as the divider. As shown in Figure \ref{fig:polycoast}, {{{poly3}}} describes the
onshore data and {{{poly4}}} describes the offshore data.
\begin{figure}[hbt]
  \centerline{\includegraphics{graphics/polyanddata2.jpg}}
  \caption{Inclusion of new polygons separating the 10m DEM area into an
  onshore (poly3) and offshore (poly4) data set.}
  \label{fig:polycoast}
\end{figure}
Let's include the bathymetry
data described above, so to combine the datasets in this case,
{{{
G = G1.clip(Geospatial_data(poly3)) + G2.clip_outside(Geospatial_data(poly1)) + G3
}}}

Finally, to fit the elevation data to the mesh, the script is adjusted in this way
{{{
domain.set_quantity('elevation',
                    filename = combined_dem_name + '.pts',
                    use_cache = True,
                    verbose = True)
}}}