source: documentation/requirements/anuga_API_requirements.tex @ 3158

\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 exeption 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 plase
  remove geo_reference as a keyword.
  
\end{itemize}   
 
 
 
\chapter{Internal API}


\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 performane. 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}   


\end{document}