Added different bits of documentation, added code for a parameter

which wasn't being used (and changed its name but since it wasn't
implemented hopefully noone was using outtimestep_every). Removed two
scheduled routines which were not doing anything.

Fixes Cactus/1377, Cactus/1378, Cactus/1384, Cactus/1379.

Does not fix Cactus/1385 yet.


git-svn-id: http://svn.cactuscode.org/arrangements/CactusBase/Time/trunk@55 5633253d-7678-4964-a54d-f87795f8ee59

1 files changed, 31 insertions, 12 deletions

diff --git a/doc/documentation.tex b/doc/documentation.tex
index 69a6593..8e9e4b3 100644
--- a/doc/documentation.tex
+++ b/doc/documentation.tex
@@ -35,10 +35,14 @@ keyword parameter {\tt time::timestep\_method}.
 
 \begin{itemize}
 
-\item{} {\tt time::timestep\_method = ``given''} The timestep is fixed to the
+\item{} {\tt time::timestep\_method = "given"} 
+
+	The timestep is fixed to the
 	value of the parameter {\tt time::timestep}. 
 
-\item{} {\tt time::timestep\_method = ``courant\_static''} This is the default
+\item{} {\tt time::timestep\_method = "courant\_static"} 
+
+	This is the default
 	method, which calculates the timestep once at the start of the
 	simulation, based on a simple courant type condition using 
 	the spatial gridsizes and the parameter {\tt time::dtfac}.
@@ -48,25 +52,37 @@ $$
 	Note that it is up to the user to custom {\tt dtfac} to take
 	into account the dimension of the space being used, and the wave speed.
 
-\item{} {\tt time::timestep\_method = ``courant\_speed''} This choice implements a 
+\item{} {\tt time::timestep\_method = "courant\_speed"} 
+
+	This choice implements a 
 	dynamic courant type condition, the timestep being set before each
 	iteration using the spatial dimension of the grid, the spatial grid sizes, the 
 	parameter {\tt courant\_fac} and the grid variable {\tt courant\_wave\_speed}. 
 	The algorithm used is
 $$
-\Delta t = \mbox{\tt courant\_fac} * \mbox{min}(\Delta x^i)/\mbox{courant\_wave\_speed}/\sqrt(\mbox{dim})
+\Delta t = \mbox{\tt courant\_fac} * \mbox{min}(\Delta x^i)/\mbox{\tt courant\_wave\_speed}/\sqrt{\mbox dim}
 $$
 	For this algorithm to be successful, the variable {\tt courant\_wave\_speed}
-	must have been set by a thorn to the maximum wave speed on the grid.
+	must have been set by some thorn to the maximum propagation speed on the grid {\it before}
+	this thorn sets the timestep, that is {\tt AT POSTSTEP BEFORE Time\_Courant} (or earlier 
+	in the evolution loop). [Note: The name {\tt courant\_wave\_speed} was poorly 
+	chosen here, the required speed is the maximum propagation speed on 
+        the grid which may be larger than the maximum wave speed (for example
+        with a shock wave in hydrodynamics, also it is possible to have
+        propagation without waves as with a pure advection equation).
+
+\item{} {\tt time::timestep\_method = "courant\_time"} 
 
-\item{} {\tt time::timestep\_method = ``courant\_time''} This choice is similar to the
+	This choice is similar to the
 	method {\tt courant\_speed} above, in implementing a dynamic timestep.
 	However the timestep is chosen using
 $$
-\Delta t = \mbox{\tt courant\_fac} * \mbox{\tt courant\_min\_time}/\sqrt(\mbox{dim})
+\Delta t = \mbox{\tt courant\_fac} * \mbox{\tt courant\_min\_time}/\sqrt{\mbox dim}
 $$
-        where the grid variable {\tt courant\_min\_time} must be set by a thorn to
-	the minimum time for a wave to cross a gridzone.
+        where the grid variable {\tt courant\_min\_time} must be set by some thorn to
+	the minimum time for a wave to cross a gridzone {\it before}
+	this thorn sets the timestep, that is {\tt AT POSTSTEP BEFORE Time\_Courant} (or earlier 
+	in the evolution loop). 
 
 \end{itemize}
 
@@ -78,23 +94,26 @@ Note that for hyperbolic problems, the Courant condition gives a minimum
 requirement for stability, namely that the numerical domain of dependency
 must encompass the physical domain of dependency, or
 $$
-\Delta t \le \mbox{min}(\Delta x^i)/\mbox{wave speed}/\sqrt(\mbox{dim})
+\Delta t \le \mbox{min}(\Delta x^i)/\mbox{wave speed}/\sqrt{\mbox dim}
 $$
 
 \section{Examples}
 
+\noindent
 {\bf Fixed Value Timestep}
 
 {\tt
 \begin{verbatim}
-time::timestep_method = ``given''
+time::timestep_method = "given"
 time::timestep        = 0.1
 \end{verbatim}
 }
 
 
+\noindent
 {\bf Calculate Static Timestep Based on Grid Spacings}
 
+\noindent
 The following parameters set the timestep to be 0.25
 
 {\tt
@@ -102,7 +121,7 @@ The following parameters set the timestep to be 0.25
 grid::dx    = 0.5
 grid::dy    = 1.0
 grid::dz    = 1.0
-time::timestep_method = ``courant_static''
+time::timestep_method = "courant_static"
 time::dtfac = 0.5
 \end{verbatim}
 }