% *======================================================================*
%  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/Seed_Magnetic_Fields_BNS/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}

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

\newcommand{\thornname}{\texttt{Seed\_Magnetic\_Fields\_BNS}\xspace}

% The title of the document (not necessarily the name of the Thorn)
\title{\thornname: An Einstein Toolkit thorn for seeding magnetic fields to binary neutron star systems}

% 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 designed to seed a poloidal magnetic field to binary
  neutron star (BNS) initial data.
\end{abstract}

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

We provide a basic overview of the mathematical expressions implemented
by this thorn, as well as key references.

\subsection{Poloidal $\vec{A}$: \texttt{A\_field\_type = poloidal\_A\_interior}.}
\label{sec:poloidal_A_interior}

We seed a poloidal magnetic field in the interior of the two neutron
stars (NSs) following the prescription described in Appendix~C
of~\cite{etienne2015illinoisgrmhd}, namely
%%
\begin{align}
  A_{x} &= -yA_{\rm b}\max\left(P-P_{\rm cut},0\right)\;,\\
  A_{y} &= +xA_{\rm b}\max\left(P-P_{\rm cut},0\right)\;,\\
  A_{z} &= 0\;.
\end{align}
%%
It is recommended to set $P_{\rm cut}$ to about 4\% of the initial
maximum pressure. Furthermore, $A_{\rm b}$ should be adjusted in order
to obtain the desired initial magnetic-to-gas pressure ratio.


\subsection{Dipolar $\vec{A}$: \texttt{A\_field\_type = dipolar\_A\_everywhere}}
\label{sec:dipolar_A_everywhere}

We seed a dipolar magnetic field onto the BNS system by extending the
prescription of~\cite{paschalidis2013general} from one to two
NSs. Namely, we consider that each neutron star contributes the
following term to the vector potential $\vec{A}$ in spherical basis:
%%
\begin{equation}
  A^{\phi,n} = \frac{\pi r_{0,n}^{2}I_{0,n}\varpi^{2}}{\left(r_{0,n}^{2} + r_{n}^{2}\right)^{3/2}}
             \left[1 + \frac{15}{8}\frac{r_{0,n}^{2}\left(r_{0,n}^{2} + \varpi_{n}^{2}\right)}{\left(r_{0,n}^{2}+r_{n}^{2}\right)}\right]\;,
\end{equation}
%%
where $n=1,2$ identifies the neutron star, $r_{0,n}^{2} \equiv r^{\mathrm{NS}}_{n}r^{\mathrm{NS}}_{0,n}$,
where $r^{\mathrm{NS}}_{n}$ are the NS radii and $r^{\mathrm{NS}}_{0,n}$
the radii of the current loops, $r_{n}^{2} = \left(x-x^{\mathrm{NS}}_{n}\right)^{2}+y^{2}+z^{2}$,
$x^{\mathrm{NS}}_{n}$ is the position of each neutron star (assumed to be in the $x$-axis),
and $\varpi_{n}^{2} = \left(x-x_{n}\right)^{2}+y^{2}$.

We then set the vector potential in the Cartesian basis using the
standard formulae
%%
\begin{align}
  A^{x} &= -\left(y+\frac{\Delta y}{2}\right)\left(A^{\phi,1} + A^{\phi,2}\right)\;,\\
  A^{y} &= \left(x_{1}+\frac{\Delta x}{2}\right)A^{\phi,1} + \left(x_{2}+\frac{\Delta x}{2}\right)A^{\phi,2}\;.
\end{align}
%%

Note that the behavior described above is valid when using
\emph{staggered} vector potentials (see Table\,\ref{tab:A_staggering} for details).

\begin{table}
  \centering
  \begin{tabular}{c c}
    \hline
    \hline
    Variable & Storage location\\
    \hline
    Non-staggered & $\left(x_{i},y_{j},z_{k}\right)$\\
    $A^{x}$        & $\left(x_{i},y_{j}+\frac{\Delta y}{2},z_{k}+\frac{\Delta z}{2}\right)$\\
    $A^{y}$        & $\left(x_{i}+\frac{\Delta x}{2},y_{j},z_{k}+\frac{\Delta z}{2}\right)$\\
    $A^{z}$        & $\left(x_{i}+\frac{\Delta x}{2},y_{j}+\frac{\Delta y}{2},z_{k}\right)$\\
    \hline
    \hline
  \end{tabular}
  \caption{Storage location on grid of vector potential $A^{i}$.}
  \label{tab:A_staggering}
\end{table}

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

The following lines provide an example of how to use this thorn to use
this thorn to seed a poloidal magnetic field to the interior of two
stars located at $x=\pm15$ (in code units). The star radii are not
specified explicitly, and we use the default radius $13.5$ as a good
enough estimate.

%%
\begin{verbatim}
ActiveThorns = "Seed_Magnetic_Fields_BNS"
Seed_Magnetic_Fields_BNS::enable_IllinoisGRMHD_staggered_A_fields = "yes"
Seed_Magnetic_Fields_BNS::A_field_type = "poloidal_A_interior"
Seed_Magnetic_Fields_BNS::have_two_NSs_along_x_axis = "yes"
Seed_Magnetic_Fields_BNS::x_c1 = +15
Seed_Magnetic_Fields_BNS::x_c2 = -15
Seed_Magnetic_Fields_BNS::A_b = 49529.954
Seed_Magnetic_Fields_BNS::n_s = 2.0
# Set to 4% initial max pressure, which is 0.000113824867150113*0.04 = .00000455299468600452
Seed_Magnetic_Fields_BNS::P_cut = 0.00000455299468600452
\end{verbatim}
%%


%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%% References %%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%
\begin{thebibliography}{2}

\bibitem{etienne2015illinoisgrmhd}
  Z.~B.~Etienne, V.~Paschalidis, R.~Haas, P.~Mösta, \& S.~L.~Shapiro,
  \newblock {\em IllinoisGRMHD: an open-source, user-friendly GRMHD code for dynamical spacetimes},
  Classical and Quantum Gravity, 32(17), 175009 (2015).

\bibitem{paschalidis2013general}
  V.~Paschalidis, Z.~B.~Etienne, \& S.~L.~Shapiro,
  \newblock {\em General-relativistic simulations of binary black hole-neutron stars: precursor electromagnetic signals},
  Physical Review D, 88(2), 021504 (2013).

\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}{enable\_illinoisgrmhd\_staggered\_a\_fields}

\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}}{a\_b} & {\bf Scope:} restricted & REAL \\\hline
\multicolumn{3}{|p{\descWidth}|}{{\bf Description:}   {\em Magnetic field strength parameter.}} \\
\hline{\bf Range} & &  {\bf Default:} 1e-3 \\\multicolumn{1}{|p{\maxVarWidth}|}{\centering *:*} & \multicolumn{2}{p{\paraWidth}|}{Any real} \\\hline
\end{tabular*}

\vspace{0.5cm}\noindent \begin{tabular*}{\tableWidth}{|c|l@{\extracolsep{\fill}}r|}
\hline
\multicolumn{1}{|p{\maxVarWidth}}{a\_field\_type} & {\bf Scope:} restricted & KEYWORD \\\hline
\multicolumn{3}{|p{\descWidth}|}{{\bf Description:}   {\em Which field structure to use.}} \\
\hline{\bf Range} & &  {\bf Default:} poloidal\_A\_interior \\\multicolumn{1}{|p{\maxVarWidth}|}{see [1] below} & \multicolumn{2}{p{\paraWidth}|}{Dipole magnetic field, interior to the star} \\\multicolumn{1}{|p{\maxVarWidth}|}{see [1] below} & \multicolumn{2}{p{\paraWidth}|}{Dipole magnetic field everywhere} \\\hline
\end{tabular*}

\vspace{0.5cm}\noindent {\bf [1]} \noindent \begin{verbatim}poloidal\_A\_interior\end{verbatim}\noindent {\bf [1]} \noindent \begin{verbatim}dipolar\_A\_everywhere\end{verbatim}\noindent \begin{tabular*}{\tableWidth}{|c|l@{\extracolsep{\fill}}r|}
\hline
\multicolumn{1}{|p{\maxVarWidth}}{enable\_illinoisgrmhd\_staggered\_a\_fields} & {\bf Scope:} restricted & BOOLEAN \\\hline
\multicolumn{3}{|p{\descWidth}|}{{\bf Description:}   {\em Define A fields on an IllinoisGRMHD staggered grid}} \\
\hline & & {\bf Default:} no \\\hline
\end{tabular*}

\vspace{0.5cm}\noindent \begin{tabular*}{\tableWidth}{|c|l@{\extracolsep{\fill}}r|}
\hline
\multicolumn{1}{|p{\maxVarWidth}}{have\_two\_nss\_along\_x\_axis} & {\bf Scope:} restricted & BOOLEAN \\\hline
\multicolumn{3}{|p{\descWidth}|}{{\bf Description:}   {\em Do we have two NSs centered along x-axis?}} \\
\hline & & {\bf Default:} no \\\hline
\end{tabular*}

\vspace{0.5cm}\noindent \begin{tabular*}{\tableWidth}{|c|l@{\extracolsep{\fill}}r|}
\hline
\multicolumn{1}{|p{\maxVarWidth}}{i\_zero\_ns1} & {\bf Scope:} restricted & REAL \\\hline
\multicolumn{3}{|p{\descWidth}|}{{\bf Description:}   {\em Magnetic field loop current of NS1.}} \\
\hline{\bf Range} & &  {\bf Default:} 0.0 \\\multicolumn{1}{|p{\maxVarWidth}|}{\centering 0.0:*)} & \multicolumn{2}{p{\paraWidth}|}{} \\\hline
\end{tabular*}

\vspace{0.5cm}\noindent \begin{tabular*}{\tableWidth}{|c|l@{\extracolsep{\fill}}r|}
\hline
\multicolumn{1}{|p{\maxVarWidth}}{i\_zero\_ns2} & {\bf Scope:} restricted & REAL \\\hline
\multicolumn{3}{|p{\descWidth}|}{{\bf Description:}   {\em Magnetic field loop current of NS2.}} \\
\hline{\bf Range} & &  {\bf Default:} 0.0 \\\multicolumn{1}{|p{\maxVarWidth}|}{\centering 0.0:*)} & \multicolumn{2}{p{\paraWidth}|}{} \\\hline
\end{tabular*}

\vspace{0.5cm}\noindent \begin{tabular*}{\tableWidth}{|c|l@{\extracolsep{\fill}}r|}
\hline
\multicolumn{1}{|p{\maxVarWidth}}{n\_s} & {\bf Scope:} restricted & REAL \\\hline
\multicolumn{3}{|p{\descWidth}|}{{\bf Description:}   {\em Magnetic field strength pressure exponent.}} \\
\hline{\bf Range} & &  {\bf Default:} 1.0 \\\multicolumn{1}{|p{\maxVarWidth}|}{\centering *:*} & \multicolumn{2}{p{\paraWidth}|}{Any real} \\\hline
\end{tabular*}

\vspace{0.5cm}\noindent \begin{tabular*}{\tableWidth}{|c|l@{\extracolsep{\fill}}r|}
\hline
\multicolumn{1}{|p{\maxVarWidth}}{p\_cut} & {\bf Scope:} restricted & REAL \\\hline
\multicolumn{3}{|p{\descWidth}|}{{\bf Description:}   {\em Cutoff pressure, below which vector potential is set to zero. Typically set to 4\% of the maximum initial pressure.}} \\
\hline{\bf Range} & &  {\bf Default:} 1e-5 \\\multicolumn{1}{|p{\maxVarWidth}|}{\centering 0:*} & \multicolumn{2}{p{\paraWidth}|}{Positive} \\\hline
\end{tabular*}

\vspace{0.5cm}\noindent \begin{tabular*}{\tableWidth}{|c|l@{\extracolsep{\fill}}r|}
\hline
\multicolumn{1}{|p{\maxVarWidth}}{r\_ns1} & {\bf Scope:} restricted & REAL \\\hline
\multicolumn{3}{|p{\descWidth}|}{{\bf Description:}   {\em Radius of NS1. Does not have to be perfect, but must not overlap other star.}} \\
\hline{\bf Range} & &  {\bf Default:} 13.5 \\\multicolumn{1}{|p{\maxVarWidth}|}{\centering 0:*} & \multicolumn{2}{p{\paraWidth}|}{Any positive} \\\hline
\end{tabular*}

\vspace{0.5cm}\noindent \begin{tabular*}{\tableWidth}{|c|l@{\extracolsep{\fill}}r|}
\hline
\multicolumn{1}{|p{\maxVarWidth}}{r\_ns2} & {\bf Scope:} restricted & REAL \\\hline
\multicolumn{3}{|p{\descWidth}|}{{\bf Description:}   {\em Radius of NS2. Does not have to be perfect, but must not overlap other star.}} \\
\hline{\bf Range} & &  {\bf Default:} 13.5 \\\multicolumn{1}{|p{\maxVarWidth}|}{\centering 0:*} & \multicolumn{2}{p{\paraWidth}|}{Any positive} \\\hline
\end{tabular*}

\vspace{0.5cm}\noindent \begin{tabular*}{\tableWidth}{|c|l@{\extracolsep{\fill}}r|}
\hline
\multicolumn{1}{|p{\maxVarWidth}}{r\_zero\_ns1} & {\bf Scope:} restricted & REAL \\\hline
\multicolumn{3}{|p{\descWidth}|}{{\bf Description:}   {\em Current loop radius of NS1.}} \\
\hline{\bf Range} & &  {\bf Default:} 1.0 \\\multicolumn{1}{|p{\maxVarWidth}|}{\centering 0.0:*)} & \multicolumn{2}{p{\paraWidth}|}{} \\\hline
\end{tabular*}

\vspace{0.5cm}\noindent \begin{tabular*}{\tableWidth}{|c|l@{\extracolsep{\fill}}r|}
\hline
\multicolumn{1}{|p{\maxVarWidth}}{r\_zero\_ns2} & {\bf Scope:} restricted & REAL \\\hline
\multicolumn{3}{|p{\descWidth}|}{{\bf Description:}   {\em Current loop radius of NS2.}} \\
\hline{\bf Range} & &  {\bf Default:} 1.0 \\\multicolumn{1}{|p{\maxVarWidth}|}{\centering 0.0:*)} & \multicolumn{2}{p{\paraWidth}|}{} \\\hline
\end{tabular*}

\vspace{0.5cm}\noindent \begin{tabular*}{\tableWidth}{|c|l@{\extracolsep{\fill}}r|}
\hline
\multicolumn{1}{|p{\maxVarWidth}}{x\_c1} & {\bf Scope:} restricted & REAL \\\hline
\multicolumn{3}{|p{\descWidth}|}{{\bf Description:}   {\em x coordinate of NS1 center}} \\
\hline{\bf Range} & &  {\bf Default:} -15.2 \\\multicolumn{1}{|p{\maxVarWidth}|}{\centering *:*} & \multicolumn{2}{p{\paraWidth}|}{Any real} \\\hline
\end{tabular*}

\vspace{0.5cm}\noindent \begin{tabular*}{\tableWidth}{|c|l@{\extracolsep{\fill}}r|}
\hline
\multicolumn{1}{|p{\maxVarWidth}}{x\_c2} & {\bf Scope:} restricted & REAL \\\hline
\multicolumn{3}{|p{\descWidth}|}{{\bf Description:}   {\em x coordinate of NS2 center}} \\
\hline{\bf Range} & &  {\bf Default:} 15.2 \\\multicolumn{1}{|p{\maxVarWidth}|}{\centering *:*} & \multicolumn{2}{p{\paraWidth}|}{Any real} \\\hline
\end{tabular*}

\vspace{0.5cm}\parskip = 10pt 

\section{Interfaces} 


\parskip = 0pt

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

\noindent {\bf Implements}: 

seed\_magnetic\_fields\_privt
\vspace{2mm}

\noindent {\bf Inherits}: 

grid

admbase

hydrobase
\vspace{2mm}

\vspace{5mm}\parskip = 10pt 

\section{Schedule} 


\parskip = 0pt


\noindent This section lists all the variables which are assigned storage by thorn WVUThorns\_Diagnostics/Seed\_Magnetic\_Fields\_BNS.  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:}&  ~ \\ 
 HydroBase::rho[1] HydroBase::press[1] HydroBase::eps[1] HydroBase::vel[1] HydroBase::Bvec[1] HydroBase::Avec[1] HydroBase::Aphi[1] & ~\\ 
~ & ~\\ 
\end{tabular*} 


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

\noindent {\bf HydroBase\_Initial} 

\hspace{5mm} seed\_magnetic\_fields\_privt 

\hspace{5mm}{\it set up binary neutron star seed magnetic fields. } 


\hspace{5mm}

 \begin{tabular*}{160mm}{cll} 
~ & After:  & meudon\_bin\_ns\_initialise \\ 
~ & Before:  & illinoisgrmhd\_id\_converter \\ 
~ & Language:  & c \\ 
~ & Type:  & function \\ 
\end{tabular*} 



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