Changeset 2672

Timestamp:

Apr 6, 2006, 3:34:42 PM (17 years ago)

Author:

howard

Message:

Changed some usages of \code{...} to \function{...}, \class{...}, \method{...}, etc in accordance with the Python documentation framework.

File:

• documentation/user_manual/anuga_user_manual.tex (modified) (18 diffs)

documentation/user_manual/anuga_user_manual.tex

@@ -150 +150 @@
 \subsection{Overview}
 
-What follows is a discussion of the structure and operation of the file
-\code{bedslopephysical.py}, with just enough detail to allow the reader
-to appreciate what's involved in setting up a scenario like the
-one it depicts.
+What follows is a discussion of the structure and operation of the
+file \file{bedslopephysical.py}, with just enough detail to allow
+the reader to appreciate what's involved in setting up a scenario
+like the one it depicts.
 
 This example carries out the solution of the shallow-water wave
@@ -188 +188 @@
 \subsection{Outline of the Program}
 
-In outline, \code{bedslopephysical.py} performs the following steps:
+In outline, \file{bedslopephysical.py} performs the following steps:
 
 \begin{enumerate}
@@ -213 +213 @@
 %This should be used wherever possible
 For reference we include below the complete code listing for
-\code{bedslopephysical.py}. Subsequent paragraphs provide a `commentary'
-that describes each step of the program and explains it significance.
+\file{bedslopephysical.py}. Subsequent paragraphs provide a
+`commentary' that describes each step of the program and explains it
+significance.
 
 %\verbatiminput{examples/bedslopephysical.py}
@@ -228 +229 @@
 \end{verbatim}}
 
-The function \code{rectangular} is imported from a module
-\code{mesh\_factory} defined elsewhere. (\anuga also contains
+The function \function{rectangular} is imported from a module
+\module{mesh\_factory} defined elsewhere. (\anuga also contains
 several other schemes that can be used for setting up meshes, but we
 shall not discuss these now.) The above assignment sets up a $10
@@ -267 +268 @@
 \end{verbatim}}
 
-This uses a Python class \code{Domain}, imported from
-\code{shallow\_water}, which is an extension of a more generic
-class of the same name in the module \code{domain}, and inherits
+This uses a Python class \class{Domain}, imported from
+\module{shallow\_water}, which is an extension of a more generic
+class of the same name in the module \module{domain}, and inherits
 some methods from the generic class but has others specific to the
-shallow-water scenarios in which it is used. Specific options for domain
-are set at this point. One of them is to set the basename for the output file:
+shallow-water scenarios in which it is used. Specific options for
+domain are set at this point. One of them is to set the basename for
+the output file:
 
 {\small \begin{verbatim}
@@ -281 +283 @@
 \subsection{Specifying the Quantities}
 
-The next task is to specify a number of quantities that we wish to set
-for each mesh point. The class \code{Domain} has a method
-\code{set\_quantity}, used to specify these quantities. It is a
-particularly flexible method that allows the user to set quantities in
-a variety of ways---using constants, functions, numeric arrays or
+The next task is to specify a number of quantities that we wish to
+set for each mesh point. The class \class{Domain} has a method
+\method{set\_quantity}, used to specify these quantities. It is a
+particularly flexible method that allows the user to set quantities
+in a variety of ways---using constants, functions, numeric arrays or
 expressions involving other quantities, arbitrary data points with
 associated values, all of which can be passed as arguments. All
-quantities can be initialised using \code{set\_quantity}. For
+quantities can be initialised using \method{set\_quantity}. For
 conserved quantities (\code{stage, xmomentum, ymomentum}) this is
-called the \emph{initial condition}, for other quantities that aren't
-updated by the equation, the same interface is used to assign their
-values. The code in the present example demonstrates a number of forms
-in which we can invoke \code{set\_quantity}.
+called the \emph{initial condition}, for other quantities that
+aren't updated by the equation, the same interface is used to assign
+their values. The code in the present example demonstrates a number
+of forms in which we can invoke \method{set\_quantity}.
 
 
@@ -313 +315 @@
 the \code{y} direction.  %[screen shot?]
 
-Once the function \code{f} is specified, the quantity
+Once the function \function{f} is specified, the quantity
 \code{elevation} is assigned through the simple statement:
 
@@ -485 +487 @@
 \begin{figure}[hbt]
 
-%  \centerline{ \includegraphics[width=75mm, height=75mm]{examples/bedslopestart.eps}}
+  \centerline{ \includegraphics[width=75mm, height=75mm]{examples/bedslopestart.eps}}
 
   \caption{Bedslope example viewed with Swollen}
@@ -495 +497 @@
 
   \centerline{
-%    \includegraphics[width=75mm, height=75mm]{examples/bedslopeduring.eps}
-%    \includegraphics[width=75mm, height=75mm]{examples/bedslopeend.eps}
+    \includegraphics[width=75mm, height=75mm]{examples/bedslopeduring.eps}
+    \includegraphics[width=75mm, height=75mm]{examples/bedslopeend.eps}
    }
 
@@ -864 +866 @@
 \end{center}
 
+Each listing details the full set of parameters for the class or
+function; however, the description is generally limited to the most
+important parameters and the reader is again referred to the code
+for more details.
+
+The following parameters are common to many functions and classes
+and are omitted from the descriptions given below:
+
+\begin{tabular}{|l|l|}  \hline
+\textbf{Name } & \textbf{Description}\\
+\hline
+\code{usecache} & Specifies whether caching is to be used\\
+\code{verbose} & If \code{True}, provides detailed terminal output
+to the user\\   \hline
+\end{tabular}
+
 
 \section{Mesh Generation}
-
+\refmodindex[pmesh.meshinterface]{pmesh.mesh\_interface}
 \begin{funcdesc}  {create\_mesh\_from\_regions}{bounding_polygon,
                              boundary_tags,
@@ -877 +895 @@
 Module: \code{pmesh.mesh\_interface}
 
+
 % Translate following into layman's language
 This function is used to create a triangular mesh suitable for use with
@@ -886 +905 @@
 the user specifies a list of boundary tags, one for each edge of the bounding
 polygon.
+
+This function is used to create a triangular mesh within a specified
+region, suitable for use with \anuga. The user specifies a polygon
+(the \code{bounding polygon}) that serves as the boundary for the
+region as well as an upper bound (\code{maximum\_triangle\_area},
+also referred to as the \emph{resolution}) for the areas of the
+inscribed triangles. The function uses a random process to compute a
+mesh within the bounding polygon and returns a meshfile, in the form
+of a
 \end{funcdesc}
 
@@ -912 +940 @@
     Module: \code{pyvolution.domain}
 
-    Assigns the name \code{name} to the domain
+    Assigns the name \code{name} to the domain.
 \end{funcdesc}
 
@@ -925 +953 @@
     Module: \code{pyvolution.domain}
 
-    Sets the directory used for data to the value \code{name}. The default value, before
-    \code{set\_datadir} is run, is the value \code{default_datadir}
+    Specifies the directory used for data, assigning it to the pathname \code{name}. The default value, before
+    \code{set\_datadir} has been run, is the value \code{default_datadir}
     specified in \code{config.py}.
+
+    Since different operating systems use different formats for specifying pathnames,
+    it is necessary to specify path separators using the Python code \code{os.sep}, rather than
+    the operating-specific ones such as `$\slash$' or `$\backslash$'.
+    For this to work you will need to include the statement \code{import os}
+    in your code, before the first appearance of \code{set\_datadir}.
+
+    For example, if you wished to set the data directory to a subdirectory
+    \code{data} of the directory \code{project}, you might use
+    statements of the following type:
+
+    {\small \begin{verbatim}
+        import os
+        domain.set_datadir{'project' + os.sep + 'data'}
+    \end{verbatim}}
 \end{funcdesc}
 
@@ -938 +981 @@
 \end{funcdesc}
 
-\begin{funcdesc} {set_time}{??}
+\begin{funcdesc} {set_time}{time=0.0}
+    Module: \code{pyvolution.domain}
+
+    Sets the initial time, in seconds, for the simulation. The
+    default is 0.0.
 \end{funcdesc}
 
@@ -1072 +1119 @@
 point \code{(x, y)} within a mesh region.
 
-The actual time series at which data is available is specified by means
-of an array \code{time} of monotonically increasing times.
-The quantities containing the values to be interpolated are specified in
-an array---or dictionary of arrays (used in conjunction with the optional argument
-\code{quantitity\_names}) --- called \code{quantities}.
-The optional arguments \code{vertex_coordinates} and \code{triangles} represent
-the spatial mesh associated with the quantity arrays. If omitted the function created
-by \code{Interpolation\_function} will be a function of \code{t} only.
-
-
-Since, in practice, values need to be computed at specified
-points, the syntax allows the user to specify, once and for all, a list
-\code{interpolation\_points} of points at which values are required. In this case,
-the function may be called using the form \code{f(t, id)}, where \code{id} is an
-index identifying a member of \code{interpolation\_points}.
-
-
-
-
+The actual time series at which data is available is specified by
+means of an array \code{time} of monotonically increasing times. The
+quantities containing the values to be interpolated are specified in
+an array---or dictionary of arrays (used in conjunction with the
+optional argument \code{quantity\_names}) --- called
+\code{quantities}. The optional arguments \code{vertex_coordinates}
+and \code{triangles} represent the spatial mesh associated with the
+quantity arrays. If omitted the function created by
+\code{Interpolation\_function} will be a function of \code{t} only.
+
+Since, in practice, values need to be computed at specified points,
+the syntax allows the user to specify, once and for all, a list
+\code{interpolation\_points} of points at which values are required.
+In this case, the function may be called using the form \code{f(t,
+id)}, where \code{id} is an index for the list
+\code{interpolation\_points}.
 
 \end{classdesc}
@@ -1690 +1734 @@
 \subsubsection{Can I start the simulation at an arbitrary time?}
 Yes, using \code{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. 
+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.
 
 \subsubsection{Why does a file\_function return a list of numbers when evaluated?}
@@ -1701 +1745 @@
 
 \subsubsection{How do I know which boundary tags are available?}
-The method \code{domain.get_boundary_tags()} will return a list of 
+The method \code{domain.get_boundary_tags()} will return a list of
 available tags for use with \code{domain.set_boundary_condition()}.