% *======================================================================*
%  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/WVUThorns_Diagnostics/smallbPoynET/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}
%% \usepackage{cactus}
\usepackage{xspace}

\newcommand{\thornname}{\texttt{smallbPoynET}\xspace}

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

% The author of the documentation
\author{Zachariah B.~Etienne \textless zachetie *at* gmail *dot* com \textgreater\\
  Documentation by Leonardo R.~Werneck \textless wernecklr *at* gmail *dot* com \textgreater
}

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

% the date your document was last changed, if your document is in CVS,
% please use:
\date{Feb 2, 2022}

\maketitle

% Do not delete next line
% START CACTUS THORNGUIDE

% Add all definitions used in this documentation here
%   \def\mydef etc
\newcommand{\beq}{\begin{equation}}
\newcommand{\eeq}{\end{equation}}
\newcommand{\beqn}{\begin{eqnarray}}
\newcommand{\eeqn}{\end{eqnarray}}
\newcommand{\half} {{1\over 2}}
\newcommand{\sgam} {\sqrt{\gamma}}
\newcommand{\tB}{\tilde{B}}
\newcommand{\tS}{\tilde{S}}
\newcommand{\tF}{\tilde{F}}
\newcommand{\tf}{\tilde{f}}
\newcommand{\tT}{\tilde{T}}
\newcommand{\sg}{\sqrt{\gamma}\,}
\newcommand{\ve}[1]{\mbox{\boldmath $#1$}}
\newcommand{\Madm}{M_{\rm ADM}}
\newcommand{\Padm}{P_{\rm ADM}}
\newcommand{\Jadm}{J_{\rm ADM}}
\newcommand{\norm}[1]{\left\lVert#1\right\rVert}
\newcommand{\rhob}{\rho_{\rm b}}
\newcommand{\rhostar}{\rho_{\star}}

\newcommand{\GiR}{{\texttt{GiRaFFE}}}
\newcommand{\IGM}{{\texttt{IllinoisGRMHD}}}

\linespread{1.0}

\newenvironment{packed_itemize}{
\begin{itemize}
  \setlength{\itemsep}{0.0pt}
  \setlength{\parskip}{0.0pt}
  \setlength{\parsep}{ 0.0pt}
}{\end{itemize}}

\newenvironment{packed_enumerate}{
\begin{enumerate}
  \setlength{\itemsep}{0.0pt}
  \setlength{\parskip}{0.0pt}
  \setlength{\parsep}{ 0.0pt}
}{\end{enumerate}}

% Add an abstract for this thorn's documentation
\begin{abstract}
  \thornname is an Einstein Toolkit thorn for computing the
  time-component of the fluid four-velocity, $u^0$, the magnetic field
  measured by a comoving observer $b^{\mu}$, and the Poynting vector
  $S^i$.
\end{abstract}


%%%%%%%%%%%%%%%%%%%%%%%
%%%%%% Overview %%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%
\section{Overview}
\label{sec:overview}

We want to compute the time-component of the fluid four-velocity, $u^0$,
the magnetic field measured by a comoving observer $b^{\mu}$, and the
Poynting vector $S^i$. We are given the \texttt{ADMBase} and
\texttt{HydroBase} gridfunctions.

First, note that the magnetic field measured by a comoving observer,
$b^{\mu}$, is given by (see e.g.,~\cite{duez2005relativistic})
%%
\begin{align}
  b^{0} &= \frac{1}{\sqrt{4\pi}}\frac{u_{j}B^{j}}{\alpha}\;,\\
  b^{i} &= \frac{1}{\sqrt{4\pi}}\frac{B^{i} + \bigl(u_{j}B^{j}\bigr)u^{i}}{\alpha u^{0}}\;,
\end{align}
%%
where $B^{i}$ are the spatial components of the magnetic field,
$u^{\mu}$ is the fluid four-velocity, and $\alpha$ is the lapse
function. Furthermore, the spatial components of the fluid four-velocity
are given by
%%
\begin{equation}
  u^{i} = \alpha u^{0}\left(v^{i}-\beta^{i}/\alpha\right)\;,
\end{equation}
%%
where $\beta^{i}$ is the shift vector and $v^{i}$ is the Valencia
three-velocity. This means that all that we are missing in order to
compute $u^{i}$ and $b^{\mu}$ is the time-component of the fluid
four-velocity, $u^{0}$.

Consider, thus, the definition of the Lorentz factor $W$,
%%
\begin{equation}
  W = \frac{1}{\sqrt{1-\gamma_{ij}v^{i}v^{j}}}\;,
\end{equation}
%%
where $\gamma_{ij}$ is the physical spatial metric. Furthermore,
consider the constraint $u_{\mu}u^{\mu}=1$, from which we find
%%
\begin{equation}
  \begin{split}
    -1 &= g_{\mu\nu}u^{\mu}u^{\nu}\\
       &= g_{00}u^{0}u^{0} + 2g_{0i}u^{0}u^{i} + g_{ij}u^{i}u^{j}\\
       &= \left(-\alpha^{2}+\beta_{\ell}\beta^{\ell}\right)\left(u^{0}\right)^{2}
        + 2u^{0}\beta_{i}\left[\alpha u^{0}\left(v^{i}-\frac{\beta^{i}}{\alpha}\right)\right]
        + \gamma_{ij}\left[\alpha u^{0}\left(v^{i}-\frac{\beta^{i}}{\alpha}\right)\right]\left[\alpha u^{0}\left(v^{j}-\frac{\beta^{j}}{\alpha}\right)\right]\\
       &= -\left(\alpha u^{0}\right)^{2}\left(1 - \gamma_{ij}v^{i}v^{j}\right)\;,
  \end{split}
\end{equation}
%%
where we have used the ADM decomposition of the spacetime metric
%%
\begin{equation}
  g_{\mu\nu} =
  \begin{pmatrix}
    -\alpha^{2}+\beta_{\ell}\beta^{\ell} & \beta_{i}\\
    \beta_{j} & \gamma_{ij}
  \end{pmatrix}\;.
\end{equation}
%%
Therefore we find that
%%
\begin{equation}
  W^{2} = \frac{1}{1-\gamma_{ij}v^{i}v^{j}} = \left(\alpha
  u^{0}\right)^{2} \implies u^{0} = W/\alpha\;.
\end{equation}
%%
Therefore after computing $W$ using the \texttt{ADMBase} and
\texttt{HydroBase} variables, we are able to compute $u^{0}$ and
therefore $u^{i}$ and $b^{\mu}$.

The Poynting vector, $S^{i}$, is computed using Eq.\,(11)
in~\cite{kelly2017prompt} but adopting the sign convention
of~\cite{farris2012binary}, i.e.,
%%
\begin{equation}
  S^{i} \equiv -\alpha T^{i}_{\rm EM} = -\alpha\left(b^{2}u^{i}u_{0} +
  \frac{1}{2}b^{2}g^{i}_{\ 0} - b^{i}b_{0}\right)\;,
\end{equation}
%%
where $b^{2}\equiv b_{\mu}b^{\mu}$.

%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%% Basic usage %%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Basic usage}
\label{sec:basic_usage}

In other to use the \thornname thorn, the user must activate it in the
parfile \emph{and} specify the frequency in which the quantities above
are computed. Note that by default the frequency is set to zero, which
effectively disables the thorn. If you are using thorns that evolves
gridfunctions other than those defined by \texttt{ADMBase} or
\texttt{HydroBase}, then you must make sure to convert your
gridfunctions to the ones used by this thorn when before calling it.

Adding the following lines to your parfile will activate this thorn and
trigger the computation of $u^{0}$, $b^{\mu}$, and $S^{i}$ once every 16
time steps.

\begin{verbatim}
ActiveThorns = "smallbPoynET"
# Configure thorn to compute u^{0}, b^{mu}, and S^{i} every 16 time steps
smallbPoynET::smallbPoynET_compute_every = 16
\end{verbatim}

%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%% References %%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%
%% Example:
%%
%% \bibitem{identifier}
%%   Authors
%%   \newblock {\em Title},
%%   Journal (Year)
\begin{thebibliography}{3}

\bibitem{duez2005relativistic}
  M.D. Duez, Y.T. Liu, S.L. Shapiro, \& B.C. Stephens,
  \newblock {\em Relativistic magnetohydrodynamics in dynamical spacetimes: Numerical methods and tests},
  Physical Review D, 72, 2, 024028 (2005).

\bibitem{kelly2017prompt}
  B.~J.~Kelly, J.~G.~Baker, Z.~B.~Etienne, B.~Giacomazzo, \& J.~Schnittman, 
  \newblock {\em Prompt electromagnetic transients from binary black hole mergers},
  Physical Review D, 96(12), 123003 (2017).

\bibitem{farris2012binary}
  B.~D.~Farris, R.~Gold, V.~Paschalidis, Z.~B.~Etienne, \& S.~L.~Shapiro,
  \newblock {\em Binary black-hole mergers in magnetized disks: simulations in full general relativity},
  Physical Review Letters, 109(22), 221102 (2012).

\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}{smallbpoynet\_compute\_every}

\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}}{enable\_warning} & {\bf Scope:} private & INT \\\hline
\multicolumn{3}{|p{\descWidth}|}{{\bf Description:}   {\em Warn if regrid\_every divided by smallbPoynET\_compute\_every is not an integer {\textgreater}= 1. You may see AMR artifacts otherwise!}} \\
\hline{\bf Range} & &  {\bf Default:} 1 \\\multicolumn{1}{|p{\maxVarWidth}|}{\centering 0:1} & \multicolumn{2}{p{\paraWidth}|}{zero (disable) or one (enable)} \\\hline
\end{tabular*}

\vspace{0.5cm}\noindent \begin{tabular*}{\tableWidth}{|c|l@{\extracolsep{\fill}}r|}
\hline
\multicolumn{1}{|p{\maxVarWidth}}{smallbpoynet\_compute\_every} & {\bf Scope:} private & INT \\\hline
\multicolumn{3}{|p{\descWidth}|}{{\bf Description:}   {\em How often to compute smallbPoyn?}} \\
\hline{\bf Range} & &  {\bf Default:} (none) \\\multicolumn{1}{|p{\maxVarWidth}|}{\centering 0:100000} & \multicolumn{2}{p{\paraWidth}|}{zero (disable computation) or some other number (1 = every iteration)} \\\hline
\end{tabular*}

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

\vspace{0.5cm}\parskip = 10pt 

\section{Interfaces} 


\parskip = 0pt

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

\noindent {\bf Implements}: 

smallbpoynet
\vspace{2mm}

\noindent {\bf Inherits}: 

grid

hydrobase

admbase
\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 
smallbpoynetgfs &  & compact & 0 \\ 
 & smallbt & dimensions & 3 \\ 
 & smallbx & distribution & DEFAULT \\ 
 & smallby & group type & GF \\ 
 & smallbz & tags & InterpNumTimelevels=1 prolongation="none" Checkpoint="no" \\ 
 & smallb2 & timelevels & 1 \\ 
 & Poynx & 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 WVUThorns\_Diagnostics/smallbPoynET.  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:}&  ~ \\ 
 smallbPoynETGFs & ~\\ 
 ADMBase::metric[metric\_timelevels] ADMBase::curv[metric\_timelevels] ADMBase::lapse[lapse\_timelevels] ADMBase::shift[shift\_timelevels] & ~\\ 
 HydroBase::rho[timelevels] HydroBase::press[timelevels] HydroBase::eps[timelevels] HydroBase::vel[timelevels] HydroBase::Bvec[timelevels] & ~\\ 
~ & ~\\ 
\end{tabular*} 


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

\noindent {\bf CCTK\_ANALYSIS} 

\hspace{5mm} compute\_bi\_b2\_poyn\_fluxet 

\hspace{5mm}{\it set b\^mu, b\^2, and poynting flux gridfunctions. } 


\hspace{5mm}

 \begin{tabular*}{160mm}{cll} 
~ & Before:  & volumeintegralgroup \\ 
~ & Language:  & c \\ 
~ & Options:  & global-early \\ 
~& ~ &loop-local\\ 
~ & Type:  & function \\ 
\end{tabular*} 



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