Changeset 5506

Timestamp:

Jul 16, 2008, 11:42:15 AM (16 years ago)

Author:

ole

Message:

Documentation of forcing terms added

Location:

anuga_core

Files:

• documentation/user_manual/anuga_user_manual.tex (modified) (4 diffs)
• source/anuga/shallow_water/shallow_water_domain.py (modified) (2 diffs)

anuga_core/documentation/user_manual/anuga_user_manual.tex

@@ -191 +191 @@
 (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
+drive the system such as rain_fall, abstraction of water, wind stress or atmospheric pressure
 gradients. Gravity and frictional resistance from the different
 terrains in the model are represented by predefined forcing terms.
+See section \ref{sec:forcing terms} for details on forcing terms available in ANUGA.
 
 The built-in mesh generator, called \code{graphical\_mesh\_generator},
@@ -266 +267 @@
 (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.
+system such as rain_fall, abstraction of water, 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
@@ -2293 +2294 @@
 
 
-%\section{Forcing Functions}
-%
-%\anuga provides a number of predefined forcing functions to be used with .....
+\section{Forcing Terms}
+\label{forcing terms}
+
+\anuga provides a number of predefined forcing functions to be used with simulations.
+Gravity and friction are always calculated using the elevation and friction quantities, but the user may additionally add forcing terms to the list 
+\code{domain.forcing_terms} and have them affect the model. 
+ 
+Currently, predifiend forcing terms are
+
+\begin{funcdesc}{General_forcing}{}
+  Module: \module{shallow\_water.shallow\_water\_domain}
+
+  This is a general class to modify any quantity according to a given rate of change.
+  Other specific forcing terms are based on this class but it can be used by itself as well (e.g.\ to modify momentum).
+  
+  The General\_forcing class takes as input:
+  \begin{itemize} 
+    \item \code{domain}: a reference to the domain being evolved
+    \item \code{quantity\_name}: The name of the quantity that will be affected by this forcing term
+    \item \code{rate}: The rate at which the quantity should change. The parameter \code{rate} can be eithe a constant or a
+                function of time. Positive values indicate increases, 
+                negative values indicate decreases.
+                The parametr \code{rate} can be \code{None} at initialisation but must be specified
+                before forcing term is applied (i.e. simulation has started).
+                The default value is 0.0 - i.e.\ no forcing.
+    \item \code{center, radius}: Optionally restrict forcing to a circle with given center and radius.
+    \item \code{polygon}: Optionally restrict forcing to an area enclosed by given polygon.             
+  \end{itemize}
+  Note specifying both center, radius and polygon will cause an exception to be thrown.
+  
+  Example:
+  {\scriptsize \begin{verbatim} 
+        xmom = General_forcing(domain, 'xmomentum', polygon=P)
+        ymom = General_forcing(domain, 'ymomentum', polygon=P)
+
+        xmom.rate = f
+        ymom.rate = g
+  
+        domain.forcing_terms.append(xmom)
+        domain.forcing_terms.append(ymom)       
+  \end{itemize}}
+  Here, \code{f}, \code{g} are assumed to be defined as functions of time providing a time dependent rate of change for xmomentum and ymomentum respectively.
+  P is assumed to be polygon, specified as a list of points, e.g. a square \code{P = [[x0, y0], [x1, y0], [x1, y1], [x0, y1]]}.  
+  
+\end{funcdesc} 
+
+
+\begin{funcdesc}{Inflow}{}
+  Module: \module{shallow\_water.shallow\_water\_domain}
+
+  This is a general class for infiltration and abstraction of water according to a given rate of change.
+  This class will always modify the \code{stage} quantity.
+  
+  Inflow is based on the General_forcing class so the functionality is similar.
+  
+  The Inflow class takes as input:
+  \begin{itemize} 
+    \item \code{domain}: a reference to the domain being evolved
+    \item \code{rate}: The flow rate in $m^3/s$ at which the stage should change. The parameter \code{rate} can be eithe a constant or a
+                function of time. Positive values indicate inflow, 
+                negative values indicate outflow.
+                
+                Note: The specified flow will be divided by the area of
+                the inflow region and then applied to update the
+                stage quantity.     
+    \item \code{center, radius}: Optionally restrict forcing to a circle with given center and radius.
+    \item \code{polygon}: Optionally restrict forcing to an area enclosed by given polygon.             
+  \end{itemize}
+  
+  Example:
+  {\scriptsize \begin{verbatim} 
+    hydrograph = Inflow(center=(320, 300), radius=10,
+                        rate=file_function('QPMF_Rot_Sub13.tms'))
+
+    domain.forcing_terms.append(hydrograph)
+  \end{itemize}}
+  Here, \code{'QPMF_Rot_Sub13.tms') is assumed to be a NetCDF file in the format \code{tms} defining a timeseries for a hydrograph.
+\end{funcdesc} 
+
+
+\begin{funcdesc}{Rainfall}{}
+  Module: \module{shallow\_water.shallow\_water\_domain}
+
+  This is a general class for implementing rainfall over the domain, possibly restricted to a given circle or polygon.
+  This class will always modify the \code{stage} quantity.
+  
+  Rainfall is based on the General_forcing class so the functionality is similar.
+  
+  The Rainfall class takes as input:
+  \begin{itemize} 
+    \item \code{domain}: a reference to the domain being evolved
+    \item \code{rate}: Total rain rate over the specified domain.  
+                  Note: Raingauge Data needs to reflect the time step.
+                  For example: if rain gauge is mm read every \code{dt} seconds, then the input
+                  here is as \code{mm/dt} so 10 mm in 5 minutes becomes
+                  10/(5x60) = 0.0333mm/s.
+        
+                  This parameter can be either a constant or a
+                  function of time. Positive values indicate rain being added (or be used for general infiltration), 
+                  negative values indicate outflow at the specified rate (presumably this could model evaporation or abstraction).
+    \item \code{center, radius}: Optionally restrict forcing to a circle with given center and radius.
+    \item \code{polygon}: Optionally restrict forcing to an area enclosed by given polygon.             
+  \end{itemize}
+  
+  Example:
+  {\scriptsize \begin{verbatim} 
+  
+    catchmentrainfall = Rainfall(rain=file_function('Q100_2hr_Rain.tms'))  
+    domain.forcing_terms.append(catchmentrainfall)
+
+  \end{itemize}}
+  Here, \code{'Q100_2hr_Rain.tms') is assumed to be a NetCDF file in the format \code{tms} defining a timeseries for the rainfall.
+\end{funcdesc} 
+
+
+
+\begin{funcdesc}{Culvert\_flow}{}
+  Module: \module{culver\_flows.culvert\_class}
+
+  This is a general class for implementing flow through a culvert.
+  This class modifies the quantities \code{stage, xmomentum, ymomentum} in areas at both ends of the culvert.
+  
+  The Culvert\_flow forcing term uses \code{Inflow} and {General\_forcing} to update the quantities. The flow direction is determined on-the-fly so
+  openings are referenced simple as opening0 and opening1 with either being able to take the role as Inflow and Outflow.
+  
+  The Culvert\_flow class takes as input:
+  \begin{itemize} 
+    \item \code{domain}: a reference to the domain being evolved
+    \item \code{label}: Short text naming the culvert
+    \item \code{description}: Text describing it
+    \item \code{end_point0}: Coordinates of one opening 
+    \item \code{end_point1}: Coordinates of other opening
+    \item \code{width}: 
+    \item \code{height}:
+    \item \code{diameter}:
+    \item \code{manning}: Mannings Roughness for Culvert
+    \item \code{invert_level0}: Invert level if not the same as the Elevation on the Domain
+    \item \code{invert_level1}: Invert level if not the same as the Elevation on the Domain
+    \item \code{culvert_routine}: Function specifying the calculation of flow based on energy difference between the two openings (see below)
+  \end{itemize}
+
+  The user can specify different culvert routines. Hower ANUGA currently specifies one, namely the \code{boyd\_generalised\_culvert\_model} as used in the example below.
+      
+  Example:
+  {\scriptsize \begin{verbatim} 
+    from anuga.culvert_flows.culvert_class import Culvert_flow
+    from anuga.culvert_flows.culvert_routines import boyd_generalised_culvert_model  
+
+    culvert1 = Culvert_flow(domain,
+                           label='Culvert No. 1',
+                           description='This culvert is a test unit 1.2m Wide by 0.75m High',   
+                           end_point0=[9.0, 2.5], 
+                           end_point1=[13.0, 2.5],
+                           width=1.20,height=0.75,
+                           culvert_routine=boyd_generalised_culvert_model,        
+                           verbose=True)
+
+    culvert2 = Culvert_flow(domain,
+                           label='Culvert No. 2',
+                           description='This culvert is a circular test with d=1.2m',   
+                           end_point0=[9.0, 1.5], 
+                           end_point1=[30.0, 3.5],
+                           diameter=1.20,
+                           invert_level0=7,
+                           culvert_routine=boyd_generalised_culvert_model,        
+                           verbose=True)
+                           
+    domain.forcing_terms.append(culvert1)
+    domain.forcing_terms.append(culvert2)
+
+    
+  \end{itemize}}
+\end{funcdesc} 
+
+
 
 
@@ -4341 +4514 @@
     Mercator) coordinate. & \\
 
+
     \indexedbold{points file} & A PTS or CSV file & \\  \hline
 

anuga_core/source/anuga/shallow_water/shallow_water_domain.py

@@ -1696 +1696 @@
 
     domain
-    flow [m^3/s]: Total flow rate over the specified area.  
+    rate [m^3/s]: Total flow rate over the specified area.  
                   This parameter can be either a constant or a
                   function of time. Positive values indicate inflow, 
                   negative values indicate outflow.
                   The specified flow will be divided by the area of
-                  the inflow region and then applied to update the
-                  quantity in question.     
+                  the inflow region and then applied to update stage.     
     center [m]: Coordinates at center of flow point
     radius [m]: Size of circular area
@@ -1732 +1731 @@
 
     hydrograph = Inflow(center=(320, 300), radius=10,
-                        flow=file_function('Q/QPMF_Rot_Sub13.tms'))
+                        rate=file_function('Q/QPMF_Rot_Sub13.tms'))
 
     domain.forcing_terms.append(hydrograph)