Changeset 7086


Ignore:
Timestamp:
May 26, 2009, 11:33:53 AM (11 years ago)
Author:
rwilson
Message:

More changes - make text agree with changed Cairns code.

Location:
anuga_core/documentation/user_manual
Files:
4 edited

Legend:

Unmodified
Added
Removed
  • anuga_core/documentation/user_manual/anuga_user_manual.tex

    r7071 r7086  
    2929\usepackage[english]{babel}
    3030\usepackage{datetime}
     31\usepackage[hang,small,bf]{caption}
    3132
    3233\input{definitions}
     
    158159
    159160The latest installation instructions may be found at:
    160 \url{http://datamining.anu.edu.au/~ole/anuga/user_manual/anuga_installation_guide.pdf}.
     161\url{http://datamining.anu.edu.au/\~{}ole/anuga/user_manual/anuga_installation_guide.pdf}.
    161162
    162163\section{Audience}
     
    320321\subsection{The Code}
    321322
    322 %FIXME: we are using the \code function here.
    323 %This should be used wherever possible
    324323For reference we include below the complete code listing for
    325324\file{runup.py}. Subsequent paragraphs provide a
     
    327326significance.
    328327
     328\label{ref:runup_py_code}
    329329\verbatiminput{demos/runup.py}
    330330
     
    384384\end{verbatim}
    385385
    386 In addition, the following statement now specifies that the
     386In addition, the following statement could be used to state that
    387387quantities \code{stage}, \code{xmomentum} and \code{ymomentum} are
    388388to be stored:
     
    391391domain.set_quantities_to_be_stored(['stage', 'xmomentum', 'ymomentum'])
    392392\end{verbatim}
     393
     394However, this is not necessary, as the above quantities are always stored by default.
    393395
    394396\subsection{Initial Conditions}
     
    416418
    417419\begin{verbatim}
    418 def f(x,y):
     420def topography(x, y):
    419421    return -x/2
    420422\end{verbatim}
     
    425427the \code{y} direction.
    426428
    427 Once the function \function{f} is specified, the quantity
     429Once the function \function{topography} is specified, the quantity
    428430\code{elevation} is assigned through the simple statement:
    429431
    430432\begin{verbatim}
    431 domain.set_quantity('elevation', f)
     433domain.set_quantity('elevation', topography)
    432434\end{verbatim}
    433435
    434436NOTE: If using function to set \code{elevation} it must be vector
    435 compatible. For example square root will not work.
     437compatible. For example, using square root will not work.
    436438
    437439\subsubsection{Friction}
     
    465467
    466468which specifies that the surface level is set to a height of $-0.4$,
    467 i.e. 0.4 units (m) below the zero level.
     469i.e. 0.4 units (metres) below the zero level.
    468470
    469471Although it is not necessary for this example, it may be useful to
     
    496498\begin{verbatim}
    497499Br = Reflective_boundary(domain)
    498 
    499500Bt = Transmissive_boundary(domain)
    500 
    501501Bd = Dirichlet_boundary([0.2, 0.0, 0.0])
    502 
    503 Bw = Time_boundary(domain=domain, f=lambda t: [(0.1*sin(t*2*pi)-0.3), 0.0, 0.0])
     502Bw = Time_boundary(domain=domain,
     503                   f=lambda t: [(0.1*sin(t*2*pi)-0.3)*exp(-t), 0.0, 0.0])
    504504\end{verbatim}
    505505
     
    511511follows:
    512512\begin{itemize}
    513     \item \textbf{Reflective boundary}\label{def:reflective boundary} Returns same \code{stage} as
    514           as present in its neighbour volume but momentum vector
    515           reversed 180 degrees (reflected).
     513    \item \textbf{Reflective boundary}\label{def:reflective boundary}
     514          Returns same \code{stage} as in its neighbour volume but momentum
     515          vector reversed 180 degrees (reflected).
    516516          Specific to the shallow water equation as it works with the
    517517          momentum quantities assumed to be the second and third conserved
     
    615615
    616616\begin{verbatim}
    617 for t in domain.evolve(yieldstep=0.1, duration=4.0):
     617for t in domain.evolve(yieldstep=0.1, duration=10.0):
    618618    print domain.timestepping_statistics()
    619619\end{verbatim}
     
    629629The output is a NetCDF file with the extension \code{.sww}. It
    630630contains stage and momentum information and can be used with the
    631 ANUGA viewer \code{animate} visualisation package to generate a visual
     631ANUGA viewer \code{animate} to generate a visual
    632632display (see Section \ref{sec:animate}). See Section \ref{sec:file formats}
    633633(page \pageref{sec:file formats}) for more on NetCDF and other file
     
    661661on the previously dry bed.
    662662
    663 All figures are screenshots from an interactive animation tool called \code{animate}
    664 which is part of \anuga and distributed as in the package anuga\_viewer.
    665 \code{animate} is described in more detail is Section \ref{sec:animate}.
     663\code{animate} is described in more detail in Section \ref{sec:animate}.
    666664
    667665\begin{figure}[htp]
     
    713711
    714712Here is the code for the first version of the channel flow \file{channel1.py}:
     713
    715714\verbatiminput{demos/channel1.py}
     715
    716716In discussing the details of this example, we follow the outline
    717717given above, discussing each major step of the code in turn.
     
    747747as we will later in this example, one merely decreases the values of \code{dx} and \code{dy}.
    748748
    749 The rest of this script is as in the previous example.
     749The rest of this script is similar to the previous example on page \pageref{ref:runup_py_code}.
    750750% except for an application of the 'expression' form of \code{set\_quantity} where we use
    751751% the value of \code{elevation} to define the (dry) initial condition for \code{stage}:
     
    784784
    785785\begin{verbatim}
    786 for t in domain.evolve(yieldstep = 0.2, finaltime = 40.0):
     786for t in domain.evolve(yieldstep=0.2, finaltime=40.0):
    787787    domain.write_time()
    788788
     
    793793
    794794\label{sec:change boundary code}
    795 The \code{if} statement in the timestepping loop (evolve) gets the quantity
     795The \code{if} statement in the timestepping loop (\code{evolve}) gets the quantity
    796796\code{stage} and obtains the interpolated value at the point (10m,
    7977972.5m) which is on the right boundary. If the stage exceeds 0m a
     
    923923using a mesh-generator.
    924924
    925 In its simplest form, the mesh-generator creates the mesh within a single
     925The mesh-generator creates the mesh within a single
    926926polygon whose vertices are at geographical locations specified by
    927927the user. The user specifies the \emph{resolution} -- that is, the
    928 maximal area of a triangle used for triangulationR -- and a triangular
     928maximal area of a triangle used for triangulation -- and a triangular
    929929mesh is created inside the polygon using a mesh generation engine.
    930930On any given platform, the same mesh will be returned.
    931 %Figure
    932 %\ref{fig:pentagon} shows a simple example of this, in which the
    933 %triangulation is carried out within a pentagon.
    934 
    935 %\begin{figure}[htp]
    936 %  \caption{Mesh points are created inside the polygon}
    937   %\label{fig:pentagon}
    938 %\end{figure}
    939931
    940932Boundary tags are not restricted to \code{'left'}, \code{'bottom'},
     
    951943polygons in which no triangulation is required.
    952944
    953 %\begin{figure}[htp]
    954 %  \caption{Interior meshes with individual resolution}
    955 %  \label{fig:interior meshes}
    956 %\end{figure}
    957 
    958945In its general form, the mesh-generator takes for its input a bounding
    959946polygon and (optionally) a list of interior polygons. The user
     
    963950
    964951The function used to implement this process is
    965 \function{create\_mesh\_from\_regions}. Its arguments include the
     952\function{create\_domain\_from\_regions} which creates a Domain object as
     953well as a mesh file.  Its arguments include the
    966954bounding polygon and its resolution, a list of boundary tags, and a
    967 list of pairs \code{[polygon, resolution]}, specifying the interior
     955list of pairs \code{[polygon, resolution]} specifying the interior
    968956polygons and their resolutions.
    969957
     
    10331021\begin{verbatim}
    10341022remainder_res = 10000000
    1035 create_mesh_from_regions(project.bounding_polygon,
    1036                          boundary_tags={'top': [0],
    1037                                         'ocean_east': [1],
    1038                                         'bottom': [2],
    1039                                         'onshore': [3]},
    1040                          maximum_triangle_area=remainder_res,
    1041                          filename=meshname,
    1042                          interior_regions=interior_regions,
    1043                          use_cache=True,
    1044                          verbose=True)
     1023domain = create_domain_from_regions(project.bounding_polygon,
     1024                                    boundary_tags={'top': [0],
     1025                                                   'ocean_east': [1],
     1026                                                   'bottom': [2],
     1027                                                   'onshore': [3]},
     1028                                    maximum_triangle_area=project.default_res,
     1029                                    mesh_filename=project.meshname,
     1030                                    interior_regions=project.interior_regions,
     1031                                    use_cache=True,
     1032                                    verbose=True)
    10451033\end{verbatim}
    10461034
     
    10561044(Here, the values associated with each boundary tag are one-element lists, but they can have as many indices as there are edges)
    10571045If polygons intersect, or edges coincide (or are even very close) the resolution may be undefined in some regions.
    1058 Use the underlying mesh interface for such cases.
    1059 See Section \ref{sec:mesh interface}.
     1046Use the underlying mesh interface for such cases
     1047(see Chapter \ref{sec:mesh interface}).
    10601048If a segment is omitted in the tags definition an Exception is raised.
    10611049
     
    10671055\subsection{Initialising the Domain}
    10681056
    1069 As with \file{runup.py}, once we have created the mesh, the next
    1070 step is to create the data structure \code{domain}. We did this for
    1071 \file{runup.py} by inputting lists of points and triangles and
    1072 specifying the boundary tags directly. However, in the present case,
    1073 we use a method that works directly with the mesh file
    1074 \code{meshname}, as follows:
     1057Since we used \code{create_domain_from_regions} to create the mesh file, we do not need to
     1058create the domain explicitly, as the above function also does that.
     1059
     1060The following statements specify a basename and data directory, and
     1061sets a minimum storable height, which helps with visualisation.
    10751062
    10761063\begin{verbatim}
    1077 domain = Domain(meshname, use_cache=True, verbose=True)
    1078 \end{verbatim}
    1079 
    1080 Providing a filename instead of the lists used in \file{runup.py}
    1081 above causes \code{Domain} to convert a mesh file \code{meshname}
    1082 into an instance of \code{Domain}, allowing us to use methods like
    1083 \method{set\_quantity} to set quantities and to apply other
    1084 operations.
    1085 
    1086 %(In principle, the
    1087 %second argument of \function{pmesh\_to\_domain\_instance} can be any
    1088 %subclass of \class{Domain}, but for applications involving the
    1089 %shallow-water wave equation, the second argument of
    1090 %\function{pmesh\_to\_domain\_instance} can always be set simply to
    1091 %\class{Domain}.)
    1092 
    1093 The following statements specify a basename and data directory, and
    1094 identify quantities to be stored. For the first two, values are
    1095 taken from \file{project.py}.
    1096 
    1097 \begin{verbatim}
    1098 domain.set_name(project.basename)
    1099 domain.set_datadir(project.outputdir)
    1100 domain.set_quantities_to_be_stored(['stage', 'xmomentum', 'ymomentum'])
     1064domain.set_name('cairns_' + project.scenario) # Name of sww file
     1065domain.set_datadir('.')                       # Store sww output here
     1066domain.set_minimum_storable_height(0.01)      # Store only depth > 1cm
    11011067\end{verbatim}
    11021068
     
    11111077\subsubsection{Stage}
    11121078
    1113 For the scenario we are modelling in this case, we use a callable
    1114 object \code{tsunami\_source}, assigned by means of a function
    1115 \function{slide\_tsunami}. This is similar to how we set elevation in
    1116 \file{runup.py} using a function -- however, in this case the
    1117 function is both more complex and more interesting.
    1118 
    1119 The function returns the water displacement for all \code{x} and
    1120 \code{y} in the domain. The water displacement is a double Gaussian
    1121 function that depends on the characteristics of the slide (length,
    1122 width, thickness, slope, etc), its location (origin) and the depth at that
    1123 location. For this example, we choose to apply the slide function
    1124 at a specified time into the simulation. {\bf Note, the parameters used
    1125 in this example have been deliberately chosen to generate a suitably
    1126 large amplitude tsunami which would inundate the Cairns region.}
     1079The stage is initially set to 0.0 by the following statements:
     1080
     1081\begin{verbatim}
     1082tide = 0.0
     1083domain.set_quantity('stage', tide)
     1084\end{verbatim}
     1085
     1086%For the scenario we are modelling in this case, we use a callable
     1087%object \code{tsunami_source}, assigned by means of a function
     1088%\function{slide\_tsunami}. This is similar to how we set elevation in
     1089%\file{runup.py} using a function -- however, in this case the
     1090%function is both more complex and more interesting.
     1091
     1092%The function returns the water displacement for all \code{x} and
     1093%\code{y} in the domain. The water displacement is a double Gaussian
     1094%function that depends on the characteristics of the slide (length,
     1095%width, thickness, slope, etc), its location (origin) and the depth at that
     1096%location. For this example, we choose to apply the slide function
     1097%at a specified time into the simulation. {\bf Note, the parameters used
     1098%in this example have been deliberately chosen to generate a suitably
     1099%large amplitude tsunami which would inundate the Cairns region.}
    11271100
    11281101\subsubsection{Friction}
     
    11401113\begin{verbatim}
    11411114domain.set_quantity('elevation',
    1142                     filename=project.dem_name+'.pts',
     1115                    filename=project.demname + '.pts',
    11431116                    use_cache=True,
    1144                     verbose=True)
     1117                    verbose=True,
     1118                    alpha=0.1)
    11451119\end{verbatim}
    1146 
    1147 %However, before this step can be executed, some preliminary steps
    1148 %are needed to prepare the file from which the data is taken. Two
    1149 %source files are used for this data -- their names are specified in
    1150 %the file \file{project.py}, in the variables \code{coarsedemname}
    1151 %and \code{finedemname}. They contain 'coarse' and 'fine' data,
    1152 %respectively -- that is, data sampled at widely spaced points over a
    1153 %large region and data sampled at closely spaced points over a
    1154 %smaller subregion. The data in these files is combined through the
    1155 %statement
    1156 
    1157 %\begin{verbatim}
    1158 %combine_rectangular_points_files(project.finedemname + '.pts',
    1159 %                                 project.coarsedemname + '.pts',
    1160 %                                 project.combineddemname + '.pts')
    1161 %\end{verbatim}
    1162 %
    1163 %The effect of this is simply to combine the datasets by eliminating
    1164 %any coarse data associated with points inside the smaller region
    1165 %common to both datasets. The name to be assigned to the resulting
    1166 %dataset is also derived from the name stored in the variable
    1167 %\code{combinedname} in the file \file{project.py}.
    11681120
    11691121\subsection{Boundary Conditions}\index{boundary conditions}
     
    11741126boundary tag names introduced when we established the mesh. In place of the four
    11751127boundary types introduced for \file{runup.py}, we use the reflective
    1176 boundary for each of the eight tagged segments defined by \code{create_mesh_from_regions}:
     1128boundary for each of the tagged segments defined by \code{create_domain_from_regions}:
    11771129
    11781130\begin{verbatim}
    1179 Bd = Dirichlet_boundary([0.0,0.0,0.0])
    1180 domain.set_boundary({'ocean_east': Bd, 'bottom': Bd, 'onshore': Bd, 'top': Bd})
     1131Bd = Dirichlet_boundary([tide,0,0]) # Mean water level
     1132Bs = Transmissive_stage_zero_momentum_boundary(domain) # Neutral boundary
     1133
     1134if project.scenario == 'fixed_wave':
     1135    # Huge 50m wave starting after 60 seconds and lasting 1 hour.
     1136    Bw = Time_boundary(domain=domain,
     1137                       function=lambda t: [(60<t<3660)*50, 0, 0])
     1138    domain.set_boundary({'ocean_east': Bw,
     1139                         'bottom': Bs,
     1140                         'onshore': Bd,
     1141                         'top': Bs})
     1142
     1143if project.scenario == 'slide':
     1144    # Boundary conditions for slide scenario
     1145    domain.set_boundary({'ocean_east': Bd,
     1146                         'bottom': Bd,
     1147                         'onshore': Bd,
     1148                         'top': Bd})
    11811149\end{verbatim}
    11821150
     1151Note that we use different boundary conditions depending on the \code{scenario}
     1152defined in \file{project.py}.
     1153
    11831154\subsection{Evolution}
    11841155
    11851156With the basics established, the running of the 'evolve' step is
    1186 very similar to the corresponding step in \file{runup.py}. For the slide
    1187 scenario, the simulation is run for 5000 seconds with the output stored every ten seconds.
    1188 For this example, we choose to apply the slide at 60 seconds into the simulation:
     1157very similar to the corresponding step in \file{runup.py}, except we have different \code{evolve}
     1158loops for the two scenarios.
     1159
     1160For the slide scenario, the simulation is run for an intial 60 seconds, at which time
     1161the slide occurs.  We use the function \function{tsunami_source} to adjust \code{stage}
     1162values.  We then run the simulation until 5000 seconds with the output stored
     1163every ten seconds.
    11891164
    11901165\begin{verbatim}
    1191 import time
    1192 
    1193 t0 = time.time()
    1194 
    1195 for t in domain.evolve(yieldstep=10, finaltime=60):
    1196         domain.write_time()
    1197         domain.write_boundary_statistics(tags = 'ocean_east')
    1198 
    1199     # add slide
     1166if project.scenario == 'slide':
     1167    for t in domain.evolve(yieldstep=10, finaltime=60):
     1168        print domain.timestepping_statistics()
     1169        print domain.boundary_statistics(tags='ocean_east')
     1170
     1171    # Add slide
    12001172    thisstagestep = domain.get_quantity('stage')
    12011173    if allclose(t, 60):
     
    12051177
    12061178    for t in domain.evolve(yieldstep=10, finaltime=5000,
    1207                            skip_initial_ste=True):
    1208         domain.write_time()
    1209 
    1210     domain.write_boundary_statistics(tags = 'ocean_east')
     1179                           skip_initial_step=True):
     1180        print domain.timestepping_statistics()
     1181        print domain.boundary_statistics(tags='ocean_east')
     1182
     1183if project.scenario == 'fixed_wave':
     1184    # Save every two mins leading up to wave approaching land
     1185    for t in domain.evolve(yieldstep=120, finaltime=5000):
     1186        print domain.timestepping_statistics()
     1187        print domain.boundary_statistics(tags='ocean_east')
     1188
     1189    # Save every 30 secs as wave starts inundating ashore
     1190    for t in domain.evolve(yieldstep=10, finaltime=10000,
     1191                           skip_initial_step=True):
     1192        print domain.timestepping_statistics()
     1193        print domain.boundary_statistics(tags='ocean_east')
    12111194\end{verbatim}
    12121195
     
    12161199This functionality is especially convenient as it allows the detailed
    12171200parts of the simulation to be viewed at higher time resolution.
    1218 
    1219 \begin{verbatim}
    1220 # save every two mins leading up to wave approaching land
    1221 for t in domain.evolve(yieldstep=120, finaltime=5000):
    1222     domain.write_time()
    1223     domain.write_boundary_statistics(tags='ocean_east')
    1224 
    1225 # save every 30 secs as wave starts inundating ashore
    1226 for t in domain.evolve(yieldstep=10, finaltime=10000, skip_initial_step=True):
    1227     domain.write_time()
    1228     domain.write_boundary_statistics(tags='ocean_east')
    1229 \end{verbatim}
    1230 
    12311201
    12321202\section{Exploring the Model Output}
     
    37303700
    37313701
    3732 /pagebreak
     3702\pagebreak
    37333703\section{utilities/polygons}
    37343704
  • anuga_core/documentation/user_manual/demos/cairns/runcairns.py

    r7078 r7086  
    146146    # Continue propagating wave
    147147    for t in domain.evolve(yieldstep=10, finaltime=5000,
    148                            skip_initial_step = True):
     148                           skip_initial_step=True):
    149149        print domain.timestepping_statistics()
    150150        print domain.boundary_statistics(tags='ocean_east')   
  • anuga_core/documentation/user_manual/demos/channel1.py

    r7064 r7086  
    2424# Setup initial conditions
    2525#------------------------------------------------------------------------------
    26 def topography(x,y):
     26def topography(x, y):
    2727    return -x/10                             # linear bed slope
    2828
     
    3030domain.set_quantity('friction', 0.01)        # Constant friction
    3131domain.set_quantity('stage',                 # Dry bed
    32                     expression='elevation + 0.0') 
     32                    expression='elevation') 
    3333
    3434#------------------------------------------------------------------------------
  • anuga_core/documentation/user_manual/demos/runup.py

    r7064 r7086  
    2929# Setup initial conditions
    3030#------------------------------------------------------------------------------
    31 def topography(x,y):
     31def topography(x, y):
    3232    return -x/2                              # linear bed slope
    3333    #return x*(-(2.0-x)*.5)                  # curved bed slope
     
    3535domain.set_quantity('elevation', topography) # Use function for elevation
    3636domain.set_quantity('friction', 0.1)         # Constant friction
    37 domain.set_quantity('stage', -.4)            # Constant negative initial stage
     37domain.set_quantity('stage', -0.4)           # Constant negative initial stage
    3838
    3939#------------------------------------------------------------------------------
     
    4444Bd = Dirichlet_boundary([-0.2,0.,0.]) # Constant boundary values
    4545Bw = Time_boundary(domain=domain,     # Time dependent boundary 
    46                    f=lambda t: [(.1*sin(t*2*pi)-0.3) * exp(-t), 0.0, 0.0])
     46                   f=lambda t: [(0.1*sin(t*2*pi)-0.3)*exp(-t), 0.0, 0.0])
    4747
    4848# Associate boundary tags with boundary objects
     
    5252# Evolve system through time
    5353#------------------------------------------------------------------------------
    54 for t in domain.evolve(yieldstep = 0.1, finaltime = 10.0):
     54for t in domain.evolve(yieldstep=0.1, finaltime=10.0):
    5555    print domain.timestepping_statistics()
Note: See TracChangeset for help on using the changeset viewer.