% *======================================================================*
%  Cactus Thorn template for ThornGuide documentation
%  Author: Ian Kelley
%  Date: Sun Jun 02, 2002
%
%  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/Proca/ProcaEvolve/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/}}
%
% *======================================================================*

\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{Helvi Witek, Miguel Zilh\~ao}

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

% the date your document was last changed:
\date{October 26 2018}

\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}

% \end{abstract}

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

\section{Notes}

This thorn evolves the Proca equations in generic spacetimes, as outlined
in~\cite{Zilhao:2015tya}. When setting the mass of the vector field $\mu$
(parameter \texttt{mu} from thorn \texttt{ProcaBase}) to zero, the system
reduces to the Maxwell equations in the Lorenz gauge.

``Right-hand-side'' variables \texttt{rhs\_Ai}, \texttt{rhs\_Ei},
\texttt{rhs\_Aphi} and \texttt{rhs\_Zeta} defined in \texttt{interface.ccl} are
given by equations (2.12), (2.13), (2.15) and (2.16) respectively
in~\cite{Zilhao:2015tya}.




\begin{thebibliography}{9}

% \cite{Zilhao:2015tya}
\bibitem{Zilhao:2015tya}
  M.~Zilh\~ao, H.~Witek and V.~Cardoso,
  ``Nonlinear interactions between black holes and Proca fields,''
  Class.\ Quant.\ Grav.\  {\bf 32} (2015) 234003
  doi:10.1088/0264-9381/32/23/234003
  [arXiv:1505.00797 [gr-qc]].
  %%CITATION = doi:10.1088/0264-9381/32/23/234003;%%
  %25 citations counted in INSPIRE as of 26 Oct 2018

\end{thebibliography}

% Do not delete next line
% END CACTUS THORNGUIDE



\section{Parameters} 


\parskip = 0pt

\setlength{\tableWidth}{160mm}

\setlength{\paraWidth}{\tableWidth}
\setlength{\descWidth}{\tableWidth}
\settowidth{\maxVarWidth}{procaevolve\_maxnumconstrainedvars}

\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}}{chi\_floor} & {\bf Scope:} private & REAL \\\hline
\multicolumn{3}{|p{\descWidth}|}{{\bf Description:}   {\em Minimal value of abs(chi)}} \\
\hline{\bf Range} & &  {\bf Default:} 1.0d-05 \\\multicolumn{1}{|p{\maxVarWidth}|}{\centering *:*} & \multicolumn{2}{p{\paraWidth}|}{Any value possible} \\\hline
\end{tabular*}

\vspace{0.5cm}\noindent \begin{tabular*}{\tableWidth}{|c|l@{\extracolsep{\fill}}r|}
\hline
\multicolumn{1}{|p{\maxVarWidth}}{conf\_fac\_exponent} & {\bf Scope:} private & REAL \\\hline
\multicolumn{3}{|p{\descWidth}|}{{\bf Description:}   {\em Exponent n for hgamma\_ij = chi\^n gamma\_ij conformal decomposition}} \\
\hline{\bf Range} & &  {\bf Default:} 1 \\\multicolumn{1}{|p{\maxVarWidth}|}{\centering (*:*)} & \multicolumn{2}{p{\paraWidth}|}{1 or 2 are good choices} \\\hline
\end{tabular*}

\vspace{0.5cm}\noindent \begin{tabular*}{\tableWidth}{|c|l@{\extracolsep{\fill}}r|}
\hline
\multicolumn{1}{|p{\maxVarWidth}}{derivs\_order} & {\bf Scope:} private & INT \\\hline
\multicolumn{3}{|p{\descWidth}|}{{\bf Description:}   {\em Order for derivatives}} \\
\hline{\bf Range} & &  {\bf Default:} 4 \\\multicolumn{1}{|p{\maxVarWidth}|}{\centering 4} & \multicolumn{2}{p{\paraWidth}|}{4th order stencils} \\\multicolumn{1}{|p{\maxVarWidth}|}{\centering 6} & \multicolumn{2}{p{\paraWidth}|}{6th order stencils} \\\hline
\end{tabular*}

\vspace{0.5cm}\noindent \begin{tabular*}{\tableWidth}{|c|l@{\extracolsep{\fill}}r|}
\hline
\multicolumn{1}{|p{\maxVarWidth}}{kappa} & {\bf Scope:} private & REAL \\\hline
\multicolumn{3}{|p{\descWidth}|}{{\bf Description:}   {\em Damping parameter for Maxwell equations}} \\
\hline{\bf Range} & &  {\bf Default:} 1 \\\multicolumn{1}{|p{\maxVarWidth}|}{\centering 0:*} & \multicolumn{2}{p{\paraWidth}|}{non-negative} \\\hline
\end{tabular*}

\vspace{0.5cm}\noindent \begin{tabular*}{\tableWidth}{|c|l@{\extracolsep{\fill}}r|}
\hline
\multicolumn{1}{|p{\maxVarWidth}}{use\_advection\_stencils} & {\bf Scope:} private & BOOLEAN \\\hline
\multicolumn{3}{|p{\descWidth}|}{{\bf Description:}   {\em Use lop-sided stencils for advection derivs}} \\
\hline & & {\bf Default:} yes \\\hline
\end{tabular*}

\vspace{0.5cm}\noindent \begin{tabular*}{\tableWidth}{|c|l@{\extracolsep{\fill}}r|}
\hline
\multicolumn{1}{|p{\maxVarWidth}}{zeta\_omega\_fac} & {\bf Scope:} private & REAL \\\hline
\multicolumn{3}{|p{\descWidth}|}{{\bf Description:}   {\em Set to zero to not evolve Zeta and Omega}} \\
\hline{\bf Range} & &  {\bf Default:} 1 \\\multicolumn{1}{|p{\maxVarWidth}|}{\centering *:*} & \multicolumn{2}{p{\paraWidth}|}{zero or one} \\\hline
\end{tabular*}

\vspace{0.5cm}\noindent \begin{tabular*}{\tableWidth}{|c|l@{\extracolsep{\fill}}r|}
\hline
\multicolumn{1}{|p{\maxVarWidth}}{procaevolve\_maxnumconstrainedvars} & {\bf Scope:} restricted & INT \\\hline
\multicolumn{3}{|p{\descWidth}|}{{\bf Description:}   {\em The maximum number of constrained variables used by ProcaEvolve}} \\
\hline{\bf Range} & &  {\bf Default:} (none) \\\multicolumn{1}{|p{\maxVarWidth}|}{\centering 0:0} & \multicolumn{2}{p{\paraWidth}|}{none} \\\hline
\end{tabular*}

\vspace{0.5cm}\noindent \begin{tabular*}{\tableWidth}{|c|l@{\extracolsep{\fill}}r|}
\hline
\multicolumn{1}{|p{\maxVarWidth}}{procaevolve\_maxnumevolvedvars} & {\bf Scope:} restricted & INT \\\hline
\multicolumn{3}{|p{\descWidth}|}{{\bf Description:}   {\em The maximum number of evolved variables used by ProcaEvolve}} \\
\hline{\bf Range} & &  {\bf Default:} 8 \\\multicolumn{1}{|p{\maxVarWidth}|}{\centering 8:8} & \multicolumn{2}{p{\paraWidth}|}{Just 8: E\^i, A\_i, Aphi, Zeta} \\\hline
\end{tabular*}

\vspace{0.5cm}\noindent \begin{tabular*}{\tableWidth}{|c|l@{\extracolsep{\fill}}r|}
\hline
\multicolumn{1}{|p{\maxVarWidth}}{procaevolve\_maxnumsandrvars} & {\bf Scope:} restricted & INT \\\hline
\multicolumn{3}{|p{\descWidth}|}{{\bf Description:}   {\em The maximum number of save and restore variables used by ProcaEvolve}} \\
\hline{\bf Range} & &  {\bf Default:} 16 \\\multicolumn{1}{|p{\maxVarWidth}|}{\centering 16:16} & \multicolumn{2}{p{\paraWidth}|}{lapse, shift, metric, and extrinsic curvature} \\\hline
\end{tabular*}

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

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

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

\vspace{0.5cm}\noindent \begin{tabular*}{\tableWidth}{|c|l@{\extracolsep{\fill}}r|}
\hline
\multicolumn{1}{|p{\maxVarWidth}}{evolution\_method} & {\bf Scope:} shared from PROCABASE & KEYWORD \\\hline
\multicolumn{3}{|l|}{\bf Extends ranges:}\\ 
\hline\multicolumn{1}{|p{\maxVarWidth}|}{\centering ProcaEvolve} & \multicolumn{2}{p{\paraWidth}|}{Use ProcaEvolve to evolve Proca variables} \\\hline
\end{tabular*}

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

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

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

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

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

\vspace{0.5cm}\parskip = 10pt 

\section{Interfaces} 


\parskip = 0pt

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

\noindent {\bf Implements}: 

procaevolve
\vspace{2mm}

\noindent {\bf Inherits}: 

admbase

tmunubase

procabase

boundary
\vspace{2mm}
\subsection*{Grid Variables}
\vspace{5mm}\subsubsection{PUBLIC GROUPS}

\vspace{5mm}

\begin{tabular*}{150mm}{|c|c@{\extracolsep{\fill}}|rl|} \hline 
~ {\bf Group Names} ~ & ~ {\bf Variable Names} ~  &{\bf Details} ~ & ~\\ 
\hline 
rhs\_ei &  & compact & 0 \\ 
 & rhs\_Ex & description & right hand sides for E\^i evolution equations \\ 
 & rhs\_Ey & dimensions & 3 \\ 
 & rhs\_Ez & distribution & DEFAULT \\ 
 &  & group type & GF \\ 
 &  & tags & tensortypealias="U" tensorweight=0 prolongation="none" Checkpoint="no" \\ 
 &  & timelevels & 1 \\ 
 &  & variable type & REAL \\ 
\hline 
rhs\_ai &  & compact & 0 \\ 
 & rhs\_Ax & description & right hand sides for A\_i evolution equations \\ 
 & rhs\_Ay & dimensions & 3 \\ 
 & rhs\_Az & distribution & DEFAULT \\ 
 &  & group type & GF \\ 
 &  & tags & tensortypealias="D" tensorweight=0 prolongation="none" Checkpoint="no" \\ 
 &  & timelevels & 1 \\ 
 &  & variable type & REAL \\ 
\hline 
rhs\_aphi & rhs\_Aphi & compact & 0 \\ 
 &  & description & right hand sides for Aphi evolution equation \\ 
 &  & dimensions & 3 \\ 
 &  & distribution & DEFAULT \\ 
 &  & group type & GF \\ 
 &  & tags & tensortypealias="Scalar" tensorweight=0 prolongation="none" Checkpoint="no" \\ 
 &  & timelevels & 1 \\ 
 &  & variable type & REAL \\ 
\hline 
rhs\_zeta & rhs\_Zeta & compact & 0 \\ 
 &  & description & right hand sides for Zeta evolution equation \\ 
 &  & dimensions & 3 \\ 
 &  & distribution & DEFAULT \\ 
 &  & group type & GF \\ 
 &  & tags & tensortypealias="Scalar" tensorweight=0 prolongation="none" Checkpoint="no" \\ 
 &  & timelevels & 1 \\ 
 &  & variable type & REAL \\ 
\hline 
hmetric &  & compact & 0 \\ 
 & hxx & description & {\textbackslash}tilde gamma\_ij \\ 
 & hxy & dimensions & 3 \\ 
 & hxz & distribution & DEFAULT \\ 
 & hyy & group type & GF \\ 
 & hyz & tags & tensortypealias="DD\_sym" tensorweight=-0.66666666666666666667 prolongation="none" Checkpoint="no" \\ 
 & hzz & timelevels & 1 \\ 
 &  & variable type & REAL \\ 
\hline 
conf\_fac\_chi &  & compact & 0 \\ 
 & chi & description & conformal factor {\textbackslash}chi \\ 
 &  & dimensions & 3 \\ 
 &  & distribution & DEFAULT \\ 
 &  & group type & GF \\ 
 &  & tags & tensortypealias="Scalar" tensorweight=-0.66666666666666666667 prolongation="none" Checkpoint="no" \\ 
 &  & timelevels & 1 \\ 
 &  & variable type & REAL \\ 
\hline 
\end{tabular*} 



\vspace{5mm}
\vspace{5mm}

\begin{tabular*}{150mm}{|c|c@{\extracolsep{\fill}}|rl|} \hline 
~ {\bf Group Names} ~ & ~ {\bf Variable Names} ~  &{\bf Details} ~ & ~ \\ 
\hline 
trk &  & compact & 0 \\ 
 & tracek & description & Tr(K) \\ 
 &  & dimensions & 3 \\ 
 &  & distribution & DEFAULT \\ 
 &  & group type & GF \\ 
 &  & tags & tensortypealias="Scalar" tensorweight=0 prolongation="none" Checkpoint="no" \\ 
 &  & timelevels & 1 \\ 
 &  & 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 Proca/ProcaEvolve.  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 Conditional:} \\ 
~ &  rhs\_Ei rhs\_Ai rhs\_Aphi rhs\_Zeta\\ 
~ &  hmetric conf\_fac\_chi trk\\ 
~ & ~\\ 
\end{tabular*} 


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

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

\hspace{5mm} proca\_initsymbound 

\hspace{5mm}{\it schedule symmetries } 


\hspace{5mm}

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


\vspace{5mm}

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

\hspace{5mm} proca\_zero\_rhs 

\hspace{5mm}{\it set all rhs functions to zero to prevent spurious nans } 


\hspace{5mm}

 \begin{tabular*}{160mm}{cll} 
~ & After:  & proca\_initsymbound \\ 
~ & Language:  & fortran \\ 
~ & Type:  & function \\ 
\end{tabular*} 


\vspace{5mm}

\noindent {\bf MoL\_Register}   (conditional) 

\hspace{5mm} proca\_registervars 

\hspace{5mm}{\it register variables for mol } 


\hspace{5mm}

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


\vspace{5mm}

\noindent {\bf MoL\_CalcRHS}   (conditional) 

\hspace{5mm} proca\_calc\_rhs 

\hspace{5mm}{\it mol rhs calculation for proca variables } 


\hspace{5mm}

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


\vspace{5mm}

\noindent {\bf MoL\_CalcRHS}   (conditional) 

\hspace{5mm} proca\_calc\_rhs\_bdry 

\hspace{5mm}{\it mol boundary rhs calculation for proca variables } 


\hspace{5mm}

 \begin{tabular*}{160mm}{cll} 
~ & After:  & proca\_calcrhs \\ 
~ & Language:  & fortran \\ 
~ & Type:  & function \\ 
\end{tabular*} 


\vspace{5mm}

\noindent {\bf MoL\_PostStep}   (conditional) 

\hspace{5mm} proca\_boundaries 

\hspace{5mm}{\it mol boundary enforcement for proca variables } 


\hspace{5mm}

 \begin{tabular*}{160mm}{cll} 
~ & Language:  & fortran \\ 
~ & Options:  & level \\ 
~ & Sync:  & procabase::ei \\ 
~& ~ &procabase::ai\\ 
~& ~ &procabase::aphi\\ 
~& ~ &procabase::zeta\\ 
~ & Type:  & function \\ 
\end{tabular*} 


\vspace{5mm}

\noindent {\bf MoL\_PostStep}   (conditional) 

\hspace{5mm} applybcs 

\hspace{5mm}{\it apply boundary conditions } 


\hspace{5mm}

 \begin{tabular*}{160mm}{cll} 
~ & After:  & proca\_boundaries \\ 
~ & Type:  & group \\ 
\end{tabular*} 


\vspace{5mm}

\noindent {\bf AddToTmunu}   (conditional) 

\hspace{5mm} proca\_calc\_tmunu 

\hspace{5mm}{\it compute the energy-momentum tensor } 


\hspace{5mm}

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


\subsection*{Aliased Functions}

\hspace{5mm}

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

{\bf Alias Name:} ~~~~~~~ & {\bf Function Name:} \\ 
ApplyBCs & Proca\_ApplyBCs \\ 
Proca\_calc\_Tmunu & Proca\_AddToTmunu \\ 
Proca\_calc\_rhs & Proca\_CalcRHS \\ 
Proca\_calc\_rhs\_bdry & Proca\_CalcRHS\_Bdry \\ 
\end{tabular*} 



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