Carpet: Explain initialisation better

darcs-hash:20060125180351-dae7b-dd6c24fe1c07a9b5e2c60fe7b0e4695787842955.gz

1 files changed, 58 insertions, 4 deletions

diff --git a/Carpet/doc/internals.tex b/Carpet/doc/internals.tex
index aec174a71..b00222aea 100644
--- a/Carpet/doc/internals.tex
+++ b/Carpet/doc/internals.tex
@@ -228,11 +228,31 @@
 
 \subsubsection{Initialisation}
 
+
+
    (See file \texttt{Carpet/src/Initialise.cc}.)  In this stage Carpet
    initialises the simulation.  This includes setting up the grids,
    calling routines to register symmetries and boundary conditions, as
    well as calculating the actual initial data on several refinement
-   levels.  It traverses the scheduling bins in the following order:
+   levels.
+
+There are three parameters influencing initial data generation, and
+it does not make sense to set more than one to "yes":
+
+\begin{verbatim}
+MoL::initial_data_is_crap
+Carpet::init_each_timelevel
+Carpet::init_3_timelevels
+\end{verbatim}
+
+That is, you have four methods, and the default (all no) gives you
+wrong data on the past timelevels and hence wrong data on the
+interpolated refinement boundaries when you use second order time
+interpolation.  For first order time interpolation, all four methods
+are identical.
+
+With all three parameters set to "no"
+Carpet traverses the scheduling bins in the following order:
 \begin{enumerate}
 \itemsep 0pt
 \item
@@ -243,25 +263,31 @@
    PARAMCHECK
 \item
    Loop over refinement levels, starting from coarsest:
+%\begin{enumerate}
 \item \quad
    BASEGRID
+\label{startinitsubloop}
 \item \quad
    INITIAL
 \item \quad
    POSTINITIAL
 \item \quad
    POSTSTEP
+\label{almostendinitsubloop}
 \item \quad
    Regrid (possibly creating new levels)
+\label{endinitsubloop}
+%\end{enumerate}
 \item
    End loop over refinement levels
 \item
    Restrict from finer to coarser grids
-\item
-   If desired, perform Scott Hawley's initialisation scheme for three
-   timelevels
+%\item
+%  If desired, perform Scott Hawley's initialisation scheme for three
+%  timelevels
 \item
    Loop over refinement levels, starting from coarsest:
+%\begin{enumerate}
 \item \quad
    RECOVER\_VARIABLES
 \item \quad
@@ -270,8 +296,10 @@
    ANALYSIS
 \item \quad
    OutputGH
+%\end{enumerate}
 \item
    End loop over refinement levels
+\label{endinitloop}
 \end{enumerate}
 
    In the beginning, only the coarsest level exists.  The first loop
@@ -280,6 +308,32 @@
    decision depend on an automatic refinement criterion.
 
 
+\texttt{ MoL::initial\_data\_is\_crap} performs all steps as indicated.
+%, except 12
+ After \ref{endinitloop}, when the evolution starts, \texttt{MoL} copies the
+current
+timelevels to the past timelevels.
+
+\texttt{Carpet::init\_each\_timelevel} loops the steps \ref{startinitsubloop}
+ to
+\ref{almostendinitsubloop} over all
+timelevels, setting \texttt{cctk\_time} differently each time.
+
+Finally, \texttt{Carpet::init\_3\_timelevels} performs all steps in order, but
+evolves each level forward one and backwards two steps, creating two
+past time levels.
+
+The parameter that specifies the number of refinement levels is not a
+Carpet parameter, but a CarpetRegrid parameter.  CarpetRegrid
+determines item \ref{endinitsubloop}, i.e., whether to create a new, finer
+level when
+the coarser levels have been initialised.  CarpetRegrid has a host of
+other parameters, and it can decide item  \ref{endinitsubloop} also by a
+different means,
+e.g. ---in principle--- through the local truncation error.
+
+
+
 
 \subsubsection{Evolution}