% /*@@
%   @file      documentation.tex
%   @date      16 May 2002
%   @author    Denis Pollney
%   @desc 
%              Thorn Noise user's guide.
%   @enddesc 
%   @version $Header$
% @@*/

\documentclass{article}

\usepackage{../../../../../doc/latex/cactus}

\newlength{\tableWidth} \newlength{\maxVarWidth} \newlength{\paraWidth} \newlength{\descWidth} \begin{document}
\title{Using the \texttt{Noise} thorn}
\author{Denis Pollney}
\date{April 2002}

\maketitle

% Do not delete next line
% START CACTUS THORNGUIDE

\begin{abstract}
The \texttt{Noise} thorn can be used to place random values on
Cactus grid functions at initial data and at the boundaries during
evolution. This can be used to carry out ``robust stability'' tests,
such as those proposed by Jeff Winicour.\\
\end{abstract}

\section{Initial data}

To apply a random perturbation to initial data, set
\texttt{noise::apply\_id\_noise="yes"}. Then each grid function
listed in the parameter \texttt{noise::id\_vars} will be adjusted
by a random factor. The maximum size of the random perturbation is
controlled by the parameter \texttt{noise::amplitude}. The
perturbations are applied during the \texttt{CCTK\_POSTINITIAL}
time bin.

\section{Boundary conditions}

A random number will be added to each point on the boundary of grid
functions listed in the \texttt{noise::bc\_vars} parameter if the
flag \texttt{noise::apply\_bc\_noise="yes"} is set. As with the
initial data, the maximum size of the perturbation is given by the
\texttt{noise::amplitude} parameter. The adjustments are applied at
each \texttt{CCTK\_POSTSTEP}.

\section{Example}

The following parameters can be used to apply a random adjustment 
of size $A=\pm0.0005$ to the initial data and boundaries of the metric
variables.
\begin{verbatim}
  ActiveThorns = "... Noise ..."

  noise::apply_id_noise = "yes"
  noise::id_vars        = "admbase::metric"

  noise::apply_bc_noise = "yes"
  noise::bc_vars        = "admbase::metric"

  noise::amplitude      = 0.001
\end{verbatim}

% Do not delete next line
% END CACTUS THORNGUIDE



\section{Parameters} 


\parskip = 0pt

\setlength{\tableWidth}{160mm}

\setlength{\paraWidth}{\tableWidth}
\setlength{\descWidth}{\tableWidth}
\settowidth{\maxVarWidth}{noise\_boundaries}

\addtolength{\paraWidth}{-\maxVarWidth}
\addtolength{\paraWidth}{-\columnsep}
\addtolength{\paraWidth}{-\columnsep}
\addtolength{\paraWidth}{-\columnsep}

\addtolength{\descWidth}{-\columnsep}
\addtolength{\descWidth}{-\columnsep}
\addtolength{\descWidth}{-\columnsep}
\noindent \begin{tabular*}{\tableWidth}{|c|l@{\extracolsep{\fill}}r|}
\hline
\multicolumn{1}{|p{\maxVarWidth}}{amplitude} & {\bf Scope:} private & REAL \\\hline
\multicolumn{3}{|p{\descWidth}|}{{\bf Description:}   {\em Maximum absolute value of random data}} \\
\hline{\bf Range} & &  {\bf Default:} 0.000001 \\\multicolumn{1}{|p{\maxVarWidth}|}{\centering 0:} & \multicolumn{2}{p{\paraWidth}|}{Positive number} \\\hline
\end{tabular*}

\vspace{0.5cm}\noindent \begin{tabular*}{\tableWidth}{|c|l@{\extracolsep{\fill}}r|}
\hline
\multicolumn{1}{|p{\maxVarWidth}}{apply\_bc\_noise} & {\bf Scope:} private & BOOLEAN \\\hline
\multicolumn{3}{|p{\descWidth}|}{{\bf Description:}   {\em Add random noise to initial data}} \\
\hline & & {\bf Default:} no \\\hline
\end{tabular*}

\vspace{0.5cm}\noindent \begin{tabular*}{\tableWidth}{|c|l@{\extracolsep{\fill}}r|}
\hline
\multicolumn{1}{|p{\maxVarWidth}}{apply\_id\_noise} & {\bf Scope:} private & BOOLEAN \\\hline
\multicolumn{3}{|p{\descWidth}|}{{\bf Description:}   {\em Add random noise to initial data}} \\
\hline & & {\bf Default:} no \\\hline
\end{tabular*}

\vspace{0.5cm}\noindent \begin{tabular*}{\tableWidth}{|c|l@{\extracolsep{\fill}}r|}
\hline
\multicolumn{1}{|p{\maxVarWidth}}{bc\_vars} & {\bf Scope:} private & STRING \\\hline
\multicolumn{3}{|p{\descWidth}|}{{\bf Description:}   {\em Variables to modify with noise at boundary}} \\
\hline{\bf Range} & &  {\bf Default:} (none) \\\multicolumn{1}{|p{\maxVarWidth}|}{\centering .*} & \multicolumn{2}{p{\paraWidth}|}{A regex which matches everything} \\\hline
\end{tabular*}

\vspace{0.5cm}\noindent \begin{tabular*}{\tableWidth}{|c|l@{\extracolsep{\fill}}r|}
\hline
\multicolumn{1}{|p{\maxVarWidth}}{id\_vars} & {\bf Scope:} private & STRING \\\hline
\multicolumn{3}{|p{\descWidth}|}{{\bf Description:}   {\em Initial data variables to modify with noise}} \\
\hline{\bf Range} & &  {\bf Default:} (none) \\\multicolumn{1}{|p{\maxVarWidth}|}{\centering .*} & \multicolumn{2}{p{\paraWidth}|}{A regex which matches everything} \\\hline
\end{tabular*}

\vspace{0.5cm}\noindent \begin{tabular*}{\tableWidth}{|c|l@{\extracolsep{\fill}}r|}
\hline
\multicolumn{1}{|p{\maxVarWidth}}{noise\_boundaries} & {\bf Scope:} private & BOOLEAN \\\hline
\multicolumn{3}{|p{\descWidth}|}{{\bf Description:}   {\em At which boundaries to apply noise}} \\
\hline & & {\bf Default:} yes \\\hline
\end{tabular*}

\vspace{0.5cm}\noindent \begin{tabular*}{\tableWidth}{|c|l@{\extracolsep{\fill}}r|}
\hline
\multicolumn{1}{|p{\maxVarWidth}}{noise\_stencil} & {\bf Scope:} private & INT \\\hline
\multicolumn{3}{|p{\descWidth}|}{{\bf Description:}   {\em Number of boundary points}} \\
\hline{\bf Range} & &  {\bf Default:} 1 \\\multicolumn{1}{|p{\maxVarWidth}|}{\centering 0:*} & \multicolumn{2}{p{\paraWidth}|}{0:*} \\\hline
\end{tabular*}

\vspace{0.5cm}\parskip = 10pt 

\section{Interfaces} 


\parskip = 0pt

\vspace{3mm} \subsection*{General}

\noindent {\bf Implements}: 

noise
\vspace{2mm}

\noindent {\bf Inherits}: 

grid
\vspace{2mm}

\vspace{5mm}

\noindent {\bf Uses header}: 

Symmetry.h
\vspace{2mm}\parskip = 10pt 

\section{Schedule} 


\parskip = 0pt


\noindent This section lists all the variables which are assigned storage by thorn CactusNumerical/Noise.  Storage can either last for the duration of the run ({\bf Always} means that if this thorn is activated storage will be assigned, {\bf Conditional} means that if this thorn is activated storage will be assigned for the duration of the run if some condition is met), or can be turned on for the duration of a schedule function.


\subsection*{Storage}NONE
\subsection*{Scheduled Functions}
\vspace{5mm}

\noindent {\bf CCTK\_INITIAL}   (conditional) 

\hspace{5mm} id\_noise 

\hspace{5mm}{\it add noise to initial data } 


\hspace{5mm}

 \begin{tabular*}{160mm}{cll} 
~ & After:  & admbase\_initialdata \\ 
~& ~ &admbase\_initialgauge\\ 
~& ~ &hydrobase\_initial\\ 
~ & Before:  & admbase\_postinitial \\ 
~& ~ &hydrobase\_prim2coninitial\\ 
~ & Language:  & c \\ 
~ & Type:  & function \\ 
\end{tabular*} 


\vspace{5mm}

\noindent {\bf CCTK\_POSTSTEP}   (conditional) 

\hspace{5mm} bc\_noise 

\hspace{5mm}{\it add noise to boundary condition } 


\hspace{5mm}

 \begin{tabular*}{160mm}{cll} 
~ & Language:  & c \\ 
~ & Type:  & function \\ 
\end{tabular*} 


\vspace{5mm}

\noindent {\bf CCTK\_POSTRESTRICT}   (conditional) 

\hspace{5mm} bc\_noise 

\hspace{5mm}{\it add noise to boundary condition } 


\hspace{5mm}

 \begin{tabular*}{160mm}{cll} 
~ & Language:  & c \\ 
~ & Type:  & function \\ 
\end{tabular*} 



\vspace{5mm}\parskip = 10pt 
\end{document}
