% *======================================================================*
%  Cactus Thorn template for ThornGuide documentation
%  Author: Ian Kelley
%  Date: Sun Jun 02, 2002
%  $Header$
%
%  Thorn documentation in the latex file doc/documentation.tex
%  will be included in ThornGuides built with the Cactus make system.
%  The scripts employed by the make system automatically include
%  pages about variables, parameters and scheduling parsed from the
%  relevant thorn CCL files.
%
%  This template contains guidelines which help to assure that your
%  documentation will be correctly added to ThornGuides. More
%  information is available in the Cactus UsersGuide.
%
%  Guidelines:
%   - Do not change anything before the line
%       % START CACTUS THORNGUIDE",
%     except for filling in the title, author, date, etc. fields.
%        - Each of these fields should only be on ONE line.
%        - Author names should be separated with a \\ or a comma.
%   - You can define your own macros, but they must appear after
%     the START CACTUS THORNGUIDE line, and must not redefine standard
%     latex commands.
%   - To avoid name clashes with other thorns, 'labels', 'citations',
%     'references', and 'image' names should conform to the following
%     convention:
%       ARRANGEMENT_THORN_LABEL
%     For example, an image wave.eps in the arrangement CactusWave and
%     thorn WaveToyC should be renamed to CactusWave_WaveToyC_wave.eps
%   - Graphics should only be included using the graphicx package.
%     More specifically, with the "\includegraphics" command.  Do
%     not specify any graphic file extensions in your .tex file. This
%     will allow us to create a PDF version of the ThornGuide
%     via pdflatex.
%   - References should be included with the latex "\bibitem" command.
%   - Use \begin{abstract}...\end{abstract} instead of \abstract{...}
%   - Do not use \appendix, instead include any appendices you need as
%     standard sections.
%   - For the benefit of our Perl scripts, and for future extensions,
%     please use simple latex.
%
% *======================================================================*
%
% Example of including a graphic image:
%    \begin{figure}[ht]
%       \begin{center}
%          \includegraphics[width=6cm]{/home/runner/work/tests/tests/arrangements/EinsteinAnalysis/PunctureTracker/doc/MyArrangement_MyThorn_MyFigure}
%       \end{center}
%       \caption{Illustration of this and that}
%       \label{MyArrangement_MyThorn_MyLabel}
%    \end{figure}
%
% Example of using a label:
%   \label{MyArrangement_MyThorn_MyLabel}
%
% Example of a citation:
%    \cite{MyArrangement_MyThorn_Author99}
%
% Example of including a reference
%   \bibitem{MyArrangement_MyThorn_Author99}
%   {J. Author, {\em The Title of the Book, Journal, or periodical}, 1 (1999),
%   1--16. {\tt http://www.nowhere.com/}}
%
% *======================================================================*

% If you are using CVS use this line to give version information
% $Header$

\documentclass{article}

% Use the Cactus ThornGuide style file
% (Automatically used from Cactus distribution, if you have a
%  thorn without the Cactus Flesh download this from the Cactus
%  homepage at www.cactuscode.org)
\usepackage{../../../../../doc/latex/cactus}

\newlength{\tableWidth} \newlength{\maxVarWidth} \newlength{\paraWidth} \newlength{\descWidth} \begin{document}

% The author of the documentation
\author{Michael Koppitz \textless koppitz@aei.mpg.de\textgreater}

% The title of the document (not necessarily the name of the Thorn)
\title{PunctureTracker}

% the date your document was last changed, if your document is in CVS,
% please use:
\date{$ $Date$ $}

\maketitle

% Do not delete next line
% START CACTUS THORNGUIDE

% Add all definitions used in this documentation here
%   \def\mydef etc

% Add an abstract for this thorn's documentation
\begin{abstract}
   \texttt{PunctureTracker} tracks black hole Punctures
   (singularities) by subtracting the value of the shift at the
   current location (the pucnture is advected with the shift)
   storing the location in a ``SphericalSurface'' one can use this
   information in Regrid2 to let the grid follow the BHs.
\end{abstract}

% The following sections are suggestive only.
% Remove them or add your own.

\section{Parameters}

   \texttt{PunctureTracker} has the followoing options:
   -pt\_track\_punctures (boolean, that triggers action)\\
   -pt\_verbose         (integer that give the verbosity level)\\
   -pt\_num\_tracked     (integer that tells how many Punctures are to
   be tracked)\\
   -pt\_initial\_x (double: Initial x coordinate positions of BHs)\\
   -pt\_initial\_y     (double: Initial y coordinate positions of BHs)\\
   -pt\_initial\_z     (double: Initial z coordinate positions of BHs)\\
   -pt\_which\_surface\_to\_take (integer: which Spherical Surface should
   be used to store the new puncture location)

\section{Grid Scalars}
   -(pt\_loc\_x, pt\_loc\_y, pt\_loc\_z) location of puncture
   -(pt\_shiftx, pt\_shifty, pt\_shiftz) value of shift at location of puncture


% Do not delete next line
% END CACTUS THORNGUIDE



\section{Parameters} 


\parskip = 0pt

\setlength{\tableWidth}{160mm}

\setlength{\paraWidth}{\tableWidth}
\setlength{\descWidth}{\tableWidth}
\settowidth{\maxVarWidth}{which\_surface\_to\_store\_info}

\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}}{initial\_x} & {\bf Scope:} private & REAL \\\hline
\multicolumn{3}{|p{\descWidth}|}{{\bf Description:}   {\em Initial x coordinate positions of punctures}} \\
\hline{\bf Range} & &  {\bf Default:} 0.0 \\\multicolumn{1}{|p{\maxVarWidth}|}{\centering *:*} & \multicolumn{2}{p{\paraWidth}|}{} \\\hline
\end{tabular*}

\vspace{0.5cm}\noindent \begin{tabular*}{\tableWidth}{|c|l@{\extracolsep{\fill}}r|}
\hline
\multicolumn{1}{|p{\maxVarWidth}}{initial\_y} & {\bf Scope:} private & REAL \\\hline
\multicolumn{3}{|p{\descWidth}|}{{\bf Description:}   {\em Initial y coordinate positions of punctures}} \\
\hline{\bf Range} & &  {\bf Default:} 0.0 \\\multicolumn{1}{|p{\maxVarWidth}|}{\centering *:*} & \multicolumn{2}{p{\paraWidth}|}{} \\\hline
\end{tabular*}

\vspace{0.5cm}\noindent \begin{tabular*}{\tableWidth}{|c|l@{\extracolsep{\fill}}r|}
\hline
\multicolumn{1}{|p{\maxVarWidth}}{initial\_z} & {\bf Scope:} private & REAL \\\hline
\multicolumn{3}{|p{\descWidth}|}{{\bf Description:}   {\em Initial z coordinate positions of punctures}} \\
\hline{\bf Range} & &  {\bf Default:} 0.0 \\\multicolumn{1}{|p{\maxVarWidth}|}{\centering *:*} & \multicolumn{2}{p{\paraWidth}|}{} \\\hline
\end{tabular*}

\vspace{0.5cm}\noindent \begin{tabular*}{\tableWidth}{|c|l@{\extracolsep{\fill}}r|}
\hline
\multicolumn{1}{|p{\maxVarWidth}}{modify\_distance} & {\bf Scope:} private & REAL \\\hline
\multicolumn{3}{|p{\descWidth}|}{{\bf Description:}   {\em Modify levels when the distance is less than this}} \\
\hline{\bf Range} & &  {\bf Default:} 0.0 \\\multicolumn{1}{|p{\maxVarWidth}|}{\centering 0.0:*} & \multicolumn{2}{p{\paraWidth}|}{zero or positive} \\\hline
\end{tabular*}

\vspace{0.5cm}\noindent \begin{tabular*}{\tableWidth}{|c|l@{\extracolsep{\fill}}r|}
\hline
\multicolumn{1}{|p{\maxVarWidth}}{modify\_puncture} & {\bf Scope:} private & INT \\\hline
\multicolumn{3}{|p{\descWidth}|}{{\bf Description:}   {\em Punctures to use for modification criteria}} \\
\hline{\bf Range} & &  {\bf Default:} -1 \\\multicolumn{1}{|p{\maxVarWidth}|}{\centering -1:9} & \multicolumn{2}{p{\paraWidth}|}{One of the tracking punctures or negative for no modification} \\\hline
\end{tabular*}

\vspace{0.5cm}\noindent \begin{tabular*}{\tableWidth}{|c|l@{\extracolsep{\fill}}r|}
\hline
\multicolumn{1}{|p{\maxVarWidth}}{new\_reflevel\_number} & {\bf Scope:} private & INT \\\hline
\multicolumn{3}{|p{\descWidth}|}{{\bf Description:}   {\em The new number of refinement levels}} \\
\hline{\bf Range} & &  {\bf Default:} -1 \\\multicolumn{1}{|p{\maxVarWidth}|}{\centering -1:*} & \multicolumn{2}{p{\paraWidth}|}{Negative for no change} \\\hline
\end{tabular*}

\vspace{0.5cm}\noindent \begin{tabular*}{\tableWidth}{|c|l@{\extracolsep{\fill}}r|}
\hline
\multicolumn{1}{|p{\maxVarWidth}}{shift\_limit} & {\bf Scope:} private & REAL \\\hline
\multicolumn{3}{|p{\descWidth}|}{{\bf Description:}   {\em Shift components must be less than this in magnitude}} \\
\hline{\bf Range} & &  {\bf Default:} 1.0e10 \\\multicolumn{1}{|p{\maxVarWidth}|}{\centering 0.0:*} & \multicolumn{2}{p{\paraWidth}|}{zero or positive} \\\hline
\end{tabular*}

\vspace{0.5cm}\noindent \begin{tabular*}{\tableWidth}{|c|l@{\extracolsep{\fill}}r|}
\hline
\multicolumn{1}{|p{\maxVarWidth}}{track} & {\bf Scope:} private & BOOLEAN \\\hline
\multicolumn{3}{|p{\descWidth}|}{{\bf Description:}   {\em Track this puncture}} \\
\hline & & {\bf Default:} no \\\hline
\end{tabular*}

\vspace{0.5cm}\noindent \begin{tabular*}{\tableWidth}{|c|l@{\extracolsep{\fill}}r|}
\hline
\multicolumn{1}{|p{\maxVarWidth}}{verbose} & {\bf Scope:} private & BOOLEAN \\\hline
\multicolumn{3}{|p{\descWidth}|}{{\bf Description:}   {\em speak up?}} \\
\hline & & {\bf Default:} no \\\hline
\end{tabular*}

\vspace{0.5cm}\noindent \begin{tabular*}{\tableWidth}{|c|l@{\extracolsep{\fill}}r|}
\hline
\multicolumn{1}{|p{\maxVarWidth}}{which\_surface\_to\_store\_info} & {\bf Scope:} private & INT \\\hline
\multicolumn{3}{|p{\descWidth}|}{{\bf Description:}   {\em A spherical surface index where we can store the puncture location}} \\
\hline{\bf Range} & &  {\bf Default:} -1 \\\multicolumn{1}{|p{\maxVarWidth}|}{\centering -1} & \multicolumn{2}{p{\paraWidth}|}{don't store puncture location} \\\multicolumn{1}{|p{\maxVarWidth}|}{\centering 0:*} & \multicolumn{2}{p{\paraWidth}|}{any spherical surface index} \\\hline
\end{tabular*}

\vspace{0.5cm}\noindent \begin{tabular*}{\tableWidth}{|c|l@{\extracolsep{\fill}}r|}
\hline
\multicolumn{1}{|p{\maxVarWidth}}{nsurfaces} & {\bf Scope:} shared from SPHERICALSURFACE & INT \\\hline
\end{tabular*}

\vspace{0.5cm}\parskip = 10pt 

\section{Interfaces} 


\parskip = 0pt

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

\noindent {\bf Implements}: 

puncturetracker
\vspace{2mm}

\noindent {\bf Inherits}: 

admbase

carpetregrid2

sphericalsurface
\vspace{2mm}
\subsection*{Grid Variables}
\vspace{5mm}\subsubsection{PRIVATE GROUPS}

\vspace{5mm}

\begin{tabular*}{150mm}{|c|c@{\extracolsep{\fill}}|rl|} \hline 
~ {\bf Group Names} ~ & ~ {\bf Variable Names} ~  &{\bf Details} ~ & ~\\ 
\hline 
pt\_loc &  & compact & 0 \\ 
 & pt\_loc\_t & description & Location of punctures \\ 
 & pt\_loc\_x & dimensions & 0 \\ 
 & pt\_loc\_y & distribution & CONSTANT \\ 
 & pt\_loc\_z & group type & SCALAR \\ 
 &  & timelevels & 1 \\ 
 &  & vararray\_size & 10 \\ 
 &  & variable type & REAL \\ 
\hline 
pt\_loc\_p &  & compact & 0 \\ 
 & pt\_loc\_t\_p & description & Previous location of punctures \\ 
 & pt\_loc\_x\_p & dimensions & 0 \\ 
 & pt\_loc\_y\_p & distribution & CONSTANT \\ 
 & pt\_loc\_z\_p & group type & SCALAR \\ 
 &  & timelevels & 1 \\ 
 &  & vararray\_size & 10 \\ 
 &  & variable type & REAL \\ 
\hline 
pt\_vel &  & compact & 0 \\ 
 & pt\_vel\_t & description & Velocity of punctures \\ 
 & pt\_vel\_x & dimensions & 0 \\ 
 & pt\_vel\_y & distribution & CONSTANT \\ 
 & pt\_vel\_z & group type & SCALAR \\ 
 &  & timelevels & 1 \\ 
 &  & vararray\_size & 10 \\ 
 &  & variable type & REAL \\ 
\hline 
\end{tabular*} 



\vspace{5mm}\parskip = 10pt 

\section{Schedule} 


\parskip = 0pt


\noindent This section lists all the variables which are assigned storage by thorn EinsteinAnalysis/PunctureTracker.  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}

\hspace{5mm}

 \begin{tabular*}{160mm}{ll} 

{\bf Always:}&  ~ \\ 
 pt\_loc pt\_loc\_p pt\_vel & ~\\ 
~ & ~\\ 
\end{tabular*} 


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

\noindent {\bf CCTK\_INITIAL} 

\hspace{5mm} puncturetracker\_init 

\hspace{5mm}{\it calculate initial location of punctures } 


\hspace{5mm}

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


\vspace{5mm}

\noindent {\bf CCTK\_EVOL} 

\hspace{5mm} puncturetracker\_track 

\hspace{5mm}{\it calculate new location of punctures } 


\hspace{5mm}

 \begin{tabular*}{160mm}{cll} 
~ & After:  & mol\_evolution \\ 
~ & Language:  & c \\ 
~ & Options:  & global \\ 
~ & Type:  & function \\ 
\end{tabular*} 


\vspace{5mm}

\noindent {\bf CCTK\_POSTSTEP} 

\hspace{5mm} puncturetracker\_setpositions 

\hspace{5mm}{\it copy puncture positions to spherical surfaces } 


\hspace{5mm}

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



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