Updated documentation.

git-svn-id: http://svn.cactuscode.org/arrangements/CactusPUGH/PUGHReduce/trunk@24 d60812e6-3970-4df4-986e-c251b06effeb

1 files changed, 65 insertions, 56 deletions

diff --git a/doc/documentation.tex b/doc/documentation.tex
index 68f584b..4f889ba 100644
--- a/doc/documentation.tex
+++ b/doc/documentation.tex
@@ -40,76 +40,85 @@
 \author{Gabrielle Allen, Thomas Radke}
 \date{2000}
 \maketitle
-
+%
 \abstract{Reductions operations which are performed using the PUGH driver}
-
+%
+%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 \section{Purpose}
-
+%
 This thorn registers a number of reduction operators with the flesh. The 
 reductions are performed using internals of the PUGH driver, so that this
-thorn can only be used when {\tt CactusPUGH/PUGH} is active.
-
-The reduction operations this thorn registers are
-
-\begin{Lentry}
-\item[maximum]
-	Calculates the maximum of a grid variable
-\item[minimum]
-	Calculates the minimum of a grid variable
-\item[sum]
-	Calculates the sum of the elements of a grid variable
-\item[norm1]
-	Calculates the norm of a grid variable
-	$$
-	\left(\Sigma | GV | \right)/n
-	$$
-	where $n$ is the number of elements
-	
-\item[norm2]
-	Calculates the norm of a grid variable
-	$$
-	\sqrt{\Sigma GV^2}/n
-	$$
-	where $n$ is the number of elements
-	
-\end{Lentry}
-
+thorn can only be used when {\tt CactusPUGH/PUGH} is active.\\
+
+The reduction operations this thorn registers are\\
+
+\begin{tabular}{|l|l|l|}
+\hline
+Reduction Operator & Calculates & By \\
+\hline
+{\tt minimum}   & the minimum of a grid variable & $ \min{ GV } $ \\
+{\tt maximum}   & the maximum of a grid variable & $ \max{ GV } $ \\
+{\tt sum}       & the sum of the elements of a grid variable & $ \sum{ GV } $ \\
+{\tt norm1}     & the L1 norm of a grid variable & $ \left(\Sigma | GV | \right)/n $ \\
+{\tt norm2}     & the L2 norm of a grid variable & $ \sqrt{\Sigma GV^2}/n $ \\
+{\tt norm\_inf} & the Inf norm of a grid variable & $ \max{| GV |} $ \\
+\hline
+\end{tabular}\\
+
+In the formulas $GV$ is the grid variable to be reduced, and $n$ denotes the
+number of its elements.
+%
+%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 \section{Examples}
-
-\begin{itemize}
-
-\item{} Maximum Value of a Grid Function
-
-{\tt
+%
+The following C example illustrates how the get the maximum value of a grid
+function.
+%
 \begin{verbatim}
-    int ierr;
-    int handle;         /* handle for reduction operator */
-    int index; 	        /* grid variable index */
-    CCTK_REAL *value;   /* value returned from reduction */
-    const char *reduction_name = "maximum";
-                        /* reduction operation to use */
-
-    handle = CCTK_ReductionHandle (reduction_name);
-    if (handle >= 0) 
+  int vindex;             /* grid variable index */
+  CCTK_REAL result;       /* resulting reduction value */
+  int target_proc;        /* processor to hold the result */
+  int reduction_handle;   /* handle for reduction operator */
+  char *reduction_name;   /* reduction operator to use */
+
+
+  /* want to get the maximum for the wavetoy grid function */
+  reduction_name = "maximum";
+  vindex = CCTK_VarIndex ("wavetoy::phi");
+
+  /* the reduction result will be obtained by processor 0 only */
+  target_proc = 0;
+
+  /* get the handle for the given reduction operator */
+  reduction_handle = CCTK_ReductionHandle (reduction_name);
+  if (reduction_handle >= 0) 
+  {
+    /* now do the reduction using the flesh's generic reduction API
+      (passing in one input, expecting one output value of REAL type) */
+    if (CCTK_Reduce (cctkGH, target_proc, reduction_handle,
+                     1, CCTK_VARIABLE_REAL, &result, 1, vindex) == 0)
     {
-      if ( CCTK_Reduce (cctkGH, 0, handle, 
-                        1, CCTK_VARIABLE_REAL,
-                        &value, 1, index) == 0 
-           && CCTK_MyProc(cctkGH) == 0)
+      if (CCTK_MyProc (cctkGH) == target_proc)
       {
-        printf("Reduction (%s) value is %f\n",reduction_name,value);
+        printf ("%s reduction value is %f\n", reduction_name, result);
       }
     }
     else
     {
-      CCTK_WARN(1,"Invalid reduction operator"); 
+      CCTK_VWarn (1, __LINE__, __FILE__, CCTK_THORNSTRING,
+                  "%s reduction failed", reduction_name);
     }
+  }
+  else
+  {
+    CCTK_VWarn (1, __LINE__, __FILE__, CCTK_THORNSTRING,
+                "Invalid reduction operator '%s'", reduction_name); 
+  }
 \end{verbatim}
-}
-
-\end{itemize}
-
-
+%
+%
 % Automatically created from the ccl files by using gmake thorndoc
 \include{interface}
 \include{param}