% *======================================================================*
%  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/EinsteinInitialData/TwoPuncturesX/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{Marcus Ansorg \textless marcus.ansorg@aei.mpg.de\textgreater \\ Erik Schnetter \textless schnetter@cct.lsu.edu\textgreater}

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

% the date your document was last changed:
\date{May 12 2026}

\maketitle

% Do not delete next line
% START CACTUS THORNGUIDE

\begin{abstract}
TwoPuncturesX generates binary black hole initial data using the puncture
method with the Bowen-York extrinsic curvature ansatz.  It implements exactly
the same spectral algorithm as the companion thorn TwoPunctures
\cite{einsteininitialdata_TwoPuncturesX_Ansorg04} but targets the CarpetX
(AMReX-based) infrastructure: it inherits from ADMBaseX and CoordinatesX
rather than from ADMBase and StaticConformal, and the setup computation is
protected by an OpenMP critical section so that it executes correctly when
called from within a threaded CarpetX loop.  TwoPunctures
(\texttt{EinsteinInitialData/TwoPunctures}) must be present in the same build
because TwoPuncturesX reuses the solver source files from that thorn.
\end{abstract}

\section{Introduction}

TwoPuncturesX is the CarpetX port of TwoPunctures.  It provides identical
physics and parameters; the differences are entirely in the Cactus
infrastructure layer:

\begin{itemize}
  \item \textbf{ADMBaseX} instead of ADMBase: metric and extrinsic curvature
    are stored as \texttt{CCTK\_REAL} grid functions under the ADMBaseX
    interface ({\tt gxx}, {\tt kxx}, {\tt alp}, etc.).
  \item \textbf{CoordinatesX} for coordinates: the physical grid coordinates
    \texttt{vcoordx}, \texttt{vcoordy}, \texttt{vcoordz} are obtained from
    CoordinatesX rather than from the Carpet grid.
  \item \textbf{Thread safety}: CarpetX may call a scheduled function
    concurrently from multiple OpenMP threads.  The one-time spectral solve is
    guarded by a named OpenMP critical section so that it is performed exactly
    once regardless of how many threads enter the function simultaneously.
  \item \textbf{Physical metric storage}: TwoPuncturesX always fills the
    physical (non-conformal) metric.  The conformal factor and its derivatives
    that TwoPunctures optionally stores via StaticConformal are not available
    under CarpetX.
\end{itemize}

For full details of the underlying physics and algorithm, see the TwoPunctures
documentation and \cite{einsteininitialdata_TwoPuncturesX_Ansorg04}.

\section{Physical System}

The physics is identical to TwoPunctures.  The conformal decomposition

\begin{equation}
  \psi = 1 + \frac{m_+}{2 r_+} + \frac{m_-}{2 r_-} + u
\end{equation}

is used, where $m_\pm$ are the bare masses of the two punctures at
$(\pm b, 0, 0)$, $r_\pm$ are distances from the respective punctures, and
$u$ is a smooth correction solved spectrally.  The Bowen-York extrinsic
curvature \cite{einsteininitialdata_TwoPuncturesX_BY80} encodes linear momenta
and spins.

The output metric is the \emph{physical} metric $\gamma_{ij} = \psi^4 f_{ij}$
(conformally flat), not the conformal metric.

\section{Numerical Implementation}

\subsection{Shared Solver}

TwoPuncturesX reuses the spectral solver from TwoPunctures by including the
header \texttt{TP\_Guts.h} directly into the scheduling function body.  This
header contains the full solve-and-interpolate logic.  Because TwoPunctures
must be present in the same build, the compiler sees both thorns' object files
and can share the Newton solver and spectral machinery.

\subsection{Thread Safety}

Under CarpetX, the scheduled function \texttt{TwoPuncturesX} may be invoked
from within an OpenMP parallel region.  The expensive spectral solve must run
exactly once.  This is guaranteed by a static boolean flag \texttt{did\_setup}
and a named OpenMP critical section:

\begin{verbatim}
#pragma omp critical(TwoPunctures_setup)
  if (!did_setup) {
    // ... perform spectral solve ...
    did_setup = true;
  }
\end{verbatim}

Using a named critical section avoids interference with the unnamed critical
section inside Newton's parallel reduction loop in \texttt{Newton.cc}.

\subsection{Grid Fill}

After the spectral solve the 3D grid is filled point-by-point using the same
interpolation path as TwoPunctures (\texttt{grid\_setup\_method = "Taylor
expansion"} or \texttt{"evaluation"}).  The inner loop is parallelized with
\texttt{\#pragma omp parallel for}.

\subsection{Scalar Grid Functions}

CarpetX resets grid scalars at the start of each scheduled call.  TwoPuncturesX
therefore saves the computed scalars (\texttt{mp}, \texttt{mm}, \texttt{mp\_adm},
\texttt{mm\_adm}, \texttt{E}, \texttt{J1}, \texttt{J2}, \texttt{J3}) into
static variables during setup and restores them on every call so that they
remain available to other thorns.

\section{Using This Thorn}

\subsection{Requirements}

\begin{itemize}
  \item \texttt{EinsteinInitialData/TwoPunctures} must be compiled into the
    same executable.  TwoPuncturesX includes header files from that thorn and
    will fail to compile otherwise.
  \item The CarpetX infrastructure thorns (CarpetX, ADMBaseX, CoordinatesX)
    must be present.
\end{itemize}

\subsection{Basic Usage}

Add both \texttt{EinsteinInitialData/TwoPunctures} and
\texttt{EinsteinInitialData/TwoPuncturesX} to your thorn list, then set:

\begin{verbatim}
ADMBaseX::initial_data  = "twopunctures"
ADMBaseX::initial_lapse = "twopunctures-antisymmetric"

TwoPuncturesX::par_b       = 3.0   # half separation (M)
TwoPuncturesX::par_m_plus  = 0.5
TwoPuncturesX::par_m_minus = 0.5
TwoPuncturesX::par_P_plus[1]  =  0.084
TwoPuncturesX::par_P_minus[1] = -0.084
TwoPuncturesX::npoints_A   = 30
TwoPuncturesX::npoints_B   = 30
TwoPuncturesX::npoints_phi = 16
\end{verbatim}

The parameter names and semantics are the same as in TwoPunctures (see that
thorn's documentation for a full description of each parameter).

\subsection{Lapse Options}

The same lapse choices are available as in TwoPunctures:
\textbf{twopunctures-antisymmetric}, \textbf{twopunctures-averaged},
\textbf{psi\^{}n}, \textbf{W}, and \textbf{brownsville}.  See the TwoPunctures
documentation for details.  Note that the conformal-factor-based lapse options
(\textbf{psi\^{}n}, \textbf{brownsville}) compute $\psi$ locally during the
grid fill; no separate conformal storage thorn is required.

\subsection{ADM Mass Iteration}

Setting \texttt{give\_bare\_mass = no} enables iterative determination of
bare masses to match target ADM masses \texttt{target\_M\_plus} and
\texttt{target\_M\_minus}, exactly as in TwoPunctures.

\subsection{Interaction With Other Thorns}

TwoPuncturesX writes to the ADMBaseX grid functions \texttt{gxx}, \texttt{gyy},
\texttt{gzz}, \texttt{gxy}, \texttt{gxz}, \texttt{gyz}, \texttt{kxx},
\texttt{kyy}, \texttt{kzz}, \texttt{kxy}, \texttt{kxz}, \texttt{kyz}, and
\texttt{alp}.  It also populates the scalar grid functions \texttt{mp},
\texttt{mm}, \texttt{mp\_adm}, \texttt{mm\_adm}, \texttt{E}, \texttt{J1},
\texttt{J2}, and \texttt{J3}.

Matter sources can be supplied via the same optional function interfaces
\texttt{Set\_Rho\_ADM} and \texttt{Set\_Initial\_Guess\_for\_u} as in
TwoPunctures; however, \texttt{rescale\_sources = yes} with
\texttt{use\_sources = yes} is not yet supported and will trigger a run-time
error.

\section{History}

TwoPuncturesX was derived from TwoPunctures to support the CarpetX AMR
framework.  The underlying spectral algorithm is unchanged from Ansorg,
Br\"ugmann \& Tichy (2004) \cite{einsteininitialdata_TwoPuncturesX_Ansorg04}.

\begin{thebibliography}{9}

\bibitem{einsteininitialdata_TwoPuncturesX_BY80}
  J.~M.~Bowen and J.~W.~York,
  {\em Time-asymmetric initial data for black holes and black-hole collisions},
  Phys.\ Rev.\ D {\bf 21}, 2047 (1980).

\bibitem{einsteininitialdata_TwoPuncturesX_Brandt97}
  S.~Brandt and B.~Br\"ugmann,
  {\em A simple construction of initial data for multiple black holes},
  Phys.\ Rev.\ Lett.\ {\bf 78}, 3606 (1997),
  gr-qc/9703066.

\bibitem{einsteininitialdata_TwoPuncturesX_Ansorg04}
  M.~Ansorg, B.~Br\"ugmann, and W.~Tichy,
  {\em Single-domain spectral method for black hole puncture data},
  Phys.\ Rev.\ D {\bf 70}, 064011 (2004),
  gr-qc/0404056.

\bibitem{einsteininitialdata_TwoPuncturesX_Campanelli06}
  M.~Campanelli, C.~O.~Lousto, and Y.~Zlochower,
  {\em Spinning-black-hole binary evolutions, recoil velocities, and
  spin-orbit effects},
  Phys.\ Rev.\ D {\bf 74}, 041501 (2006),
  gr-qc/0604012.

\bibitem{einsteininitialdata_TwoPuncturesX_Alic24}
  D.~Alic et al.,
  {\em Constraint-preserving boundary treatment for a harmonic formulation of
  the Einstein equations},
  Phys.\ Rev.\ D {\bf 110}, 064045 (2024),
  arXiv:2404.01137.

\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}{schedule\_in\_admbase\_initialdata}

\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}}{adm\_tol} & {\bf Scope:} restricted & REAL \\\hline
\multicolumn{3}{|p{\descWidth}|}{{\bf Description:}   {\em Tolerance of ADM masses when give\_bare\_mass=no}} \\
\hline{\bf Range} & &  {\bf Default:} 1.0e-10 \\\multicolumn{1}{|p{\maxVarWidth}|}{\centering (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}}{center\_offset} & {\bf Scope:} restricted & REAL \\\hline
\multicolumn{3}{|p{\descWidth}|}{{\bf Description:}   {\em offset b=0 to position (x,y,z)}} \\
\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}}{do\_initial\_debug\_output} & {\bf Scope:} restricted & BOOLEAN \\\hline
\multicolumn{3}{|p{\descWidth}|}{{\bf Description:}   {\em Output debug information about initial guess}} \\
\hline & & {\bf Default:} no \\\hline
\end{tabular*}

\vspace{0.5cm}\noindent \begin{tabular*}{\tableWidth}{|c|l@{\extracolsep{\fill}}r|}
\hline
\multicolumn{1}{|p{\maxVarWidth}}{do\_residuum\_debug\_output} & {\bf Scope:} restricted & BOOLEAN \\\hline
\multicolumn{3}{|p{\descWidth}|}{{\bf Description:}   {\em Output debug information about the residuum}} \\
\hline & & {\bf Default:} no \\\hline
\end{tabular*}

\vspace{0.5cm}\noindent \begin{tabular*}{\tableWidth}{|c|l@{\extracolsep{\fill}}r|}
\hline
\multicolumn{1}{|p{\maxVarWidth}}{give\_bare\_mass} & {\bf Scope:} restricted & BOOLEAN \\\hline
\multicolumn{3}{|p{\descWidth}|}{{\bf Description:}   {\em User provides bare masses rather than target ADM masses}} \\
\hline & & {\bf Default:} yes \\\hline
\end{tabular*}

\vspace{0.5cm}\noindent \begin{tabular*}{\tableWidth}{|c|l@{\extracolsep{\fill}}r|}
\hline
\multicolumn{1}{|p{\maxVarWidth}}{grid\_setup\_method} & {\bf Scope:} restricted & KEYWORD \\\hline
\multicolumn{3}{|p{\descWidth}|}{{\bf Description:}   {\em How to fill the 3D grid from the spectral grid}} \\
\hline{\bf Range} & &  {\bf Default:} Taylor expansion \\\multicolumn{1}{|p{\maxVarWidth}|}{\centering Taylor expansion} & \multicolumn{2}{p{\paraWidth}|}{use a Taylor expansion about the nearest collocation point (fast, but might be inaccurate)} \\\multicolumn{1}{|p{\maxVarWidth}|}{\centering evaluation} & \multicolumn{2}{p{\paraWidth}|}{evaluate using all spectral coefficients (slow)} \\\hline
\end{tabular*}

\vspace{0.5cm}\noindent \begin{tabular*}{\tableWidth}{|c|l@{\extracolsep{\fill}}r|}
\hline
\multicolumn{1}{|p{\maxVarWidth}}{initial\_lapse\_psi\_exponent} & {\bf Scope:} restricted & REAL \\\hline
\multicolumn{3}{|p{\descWidth}|}{{\bf Description:}   {\em Exponent n for psi\^-n initial lapse profile}} \\
\hline{\bf Range} & &  {\bf Default:} -2.0 \\\multicolumn{1}{|p{\maxVarWidth}|}{\centering (*:*)} & \multicolumn{2}{p{\paraWidth}|}{Should be negative} \\\hline
\end{tabular*}

\vspace{0.5cm}\noindent \begin{tabular*}{\tableWidth}{|c|l@{\extracolsep{\fill}}r|}
\hline
\multicolumn{1}{|p{\maxVarWidth}}{keep\_u\_around} & {\bf Scope:} restricted & BOOLEAN \\\hline
\multicolumn{3}{|p{\descWidth}|}{{\bf Description:}   {\em Keep the variable u around after solving}} \\
\hline & & {\bf Default:} no \\\hline
\end{tabular*}

\vspace{0.5cm}\noindent \begin{tabular*}{\tableWidth}{|c|l@{\extracolsep{\fill}}r|}
\hline
\multicolumn{1}{|p{\maxVarWidth}}{multiply\_old\_lapse} & {\bf Scope:} restricted & BOOLEAN \\\hline
\multicolumn{3}{|p{\descWidth}|}{{\bf Description:}   {\em Multiply the old lapse with the new one}} \\
\hline & & {\bf Default:} no \\\hline
\end{tabular*}

\vspace{0.5cm}\noindent \begin{tabular*}{\tableWidth}{|c|l@{\extracolsep{\fill}}r|}
\hline
\multicolumn{1}{|p{\maxVarWidth}}{newton\_maxit} & {\bf Scope:} restricted & INT \\\hline
\multicolumn{3}{|p{\descWidth}|}{{\bf Description:}   {\em Maximum number of Newton iterations}} \\
\hline{\bf Range} & &  {\bf Default:} 5 \\\multicolumn{1}{|p{\maxVarWidth}|}{\centering 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}}{newton\_tol} & {\bf Scope:} restricted & REAL \\\hline
\multicolumn{3}{|p{\descWidth}|}{{\bf Description:}   {\em Tolerance for Newton solver}} \\
\hline{\bf Range} & &  {\bf Default:} 1.0e-10 \\\multicolumn{1}{|p{\maxVarWidth}|}{\centering (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}}{npoints\_a} & {\bf Scope:} restricted & INT \\\hline
\multicolumn{3}{|p{\descWidth}|}{{\bf Description:}   {\em Number of coefficients in the compactified radial direction}} \\
\hline{\bf Range} & &  {\bf Default:} 30 \\\multicolumn{1}{|p{\maxVarWidth}|}{\centering 4:*} & \multicolumn{2}{p{\paraWidth}|}{} \\\hline
\end{tabular*}

\vspace{0.5cm}\noindent \begin{tabular*}{\tableWidth}{|c|l@{\extracolsep{\fill}}r|}
\hline
\multicolumn{1}{|p{\maxVarWidth}}{npoints\_b} & {\bf Scope:} restricted & INT \\\hline
\multicolumn{3}{|p{\descWidth}|}{{\bf Description:}   {\em Number of coefficients in the angular direction}} \\
\hline{\bf Range} & &  {\bf Default:} 30 \\\multicolumn{1}{|p{\maxVarWidth}|}{\centering 4:*} & \multicolumn{2}{p{\paraWidth}|}{} \\\hline
\end{tabular*}

\vspace{0.5cm}\noindent \begin{tabular*}{\tableWidth}{|c|l@{\extracolsep{\fill}}r|}
\hline
\multicolumn{1}{|p{\maxVarWidth}}{npoints\_phi} & {\bf Scope:} restricted & INT \\\hline
\multicolumn{3}{|p{\descWidth}|}{{\bf Description:}   {\em Number of coefficients in the phi direction}} \\
\hline{\bf Range} & &  {\bf Default:} 16 \\\multicolumn{1}{|p{\maxVarWidth}|}{\centering 4:*:2} & \multicolumn{2}{p{\paraWidth}|}{} \\\hline
\end{tabular*}

\vspace{0.5cm}\noindent \begin{tabular*}{\tableWidth}{|c|l@{\extracolsep{\fill}}r|}
\hline
\multicolumn{1}{|p{\maxVarWidth}}{par\_b} & {\bf Scope:} restricted & REAL \\\hline
\multicolumn{3}{|p{\descWidth}|}{{\bf Description:}   {\em x coordinate of the m+ puncture}} \\
\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}}{par\_m\_minus} & {\bf Scope:} restricted & REAL \\\hline
\multicolumn{3}{|p{\descWidth}|}{{\bf Description:}   {\em mass of the m- puncture}} \\
\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}}{par\_m\_plus} & {\bf Scope:} restricted & REAL \\\hline
\multicolumn{3}{|p{\descWidth}|}{{\bf Description:}   {\em mass of the m+ puncture}} \\
\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}}{par\_p\_minus} & {\bf Scope:} restricted & REAL \\\hline
\multicolumn{3}{|p{\descWidth}|}{{\bf Description:}   {\em momentum of the m- puncture}} \\
\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}}{par\_p\_plus} & {\bf Scope:} restricted & REAL \\\hline
\multicolumn{3}{|p{\descWidth}|}{{\bf Description:}   {\em momentum of the m+ puncture}} \\
\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}}{par\_s\_minus} & {\bf Scope:} restricted & REAL \\\hline
\multicolumn{3}{|p{\descWidth}|}{{\bf Description:}   {\em spin of the m- puncture}} \\
\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}}{par\_s\_plus} & {\bf Scope:} restricted & REAL \\\hline
\multicolumn{3}{|p{\descWidth}|}{{\bf Description:}   {\em spin of the m+ puncture}} \\
\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}}{rescale\_sources} & {\bf Scope:} restricted & BOOLEAN \\\hline
\multicolumn{3}{|p{\descWidth}|}{{\bf Description:}   {\em If sources are used - rescale them after solving?}} \\
\hline & & {\bf Default:} yes \\\hline
\end{tabular*}

\vspace{0.5cm}\noindent \begin{tabular*}{\tableWidth}{|c|l@{\extracolsep{\fill}}r|}
\hline
\multicolumn{1}{|p{\maxVarWidth}}{schedule\_in\_admbase\_initialdata} & {\bf Scope:} restricted & BOOLEAN \\\hline
\multicolumn{3}{|p{\descWidth}|}{{\bf Description:}   {\em Schedule in (instead of after) ADMBase\_InitialData}} \\
\hline & & {\bf Default:} yes \\\hline
\end{tabular*}

\vspace{0.5cm}\noindent \begin{tabular*}{\tableWidth}{|c|l@{\extracolsep{\fill}}r|}
\hline
\multicolumn{1}{|p{\maxVarWidth}}{solve\_momentum\_constraint} & {\bf Scope:} restricted & BOOLEAN \\\hline
\multicolumn{3}{|p{\descWidth}|}{{\bf Description:}   {\em Solve for momentum constraint?}} \\
\hline & & {\bf Default:} no \\\hline
\end{tabular*}

\vspace{0.5cm}\noindent \begin{tabular*}{\tableWidth}{|c|l@{\extracolsep{\fill}}r|}
\hline
\multicolumn{1}{|p{\maxVarWidth}}{swap\_xz} & {\bf Scope:} restricted & BOOLEAN \\\hline
\multicolumn{3}{|p{\descWidth}|}{{\bf Description:}   {\em Swap x and z coordinates when interpolating, so that the black holes are separated in the z direction}} \\
\hline & & {\bf Default:} no \\\hline
\end{tabular*}

\vspace{0.5cm}\noindent \begin{tabular*}{\tableWidth}{|c|l@{\extracolsep{\fill}}r|}
\hline
\multicolumn{1}{|p{\maxVarWidth}}{target\_m\_minus} & {\bf Scope:} restricted & REAL \\\hline
\multicolumn{3}{|p{\descWidth}|}{{\bf Description:}   {\em target ADM mass for m-}} \\
\hline{\bf Range} & &  {\bf Default:} 0.5 \\\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}}{target\_m\_plus} & {\bf Scope:} restricted & REAL \\\hline
\multicolumn{3}{|p{\descWidth}|}{{\bf Description:}   {\em target ADM mass for m+}} \\
\hline{\bf Range} & &  {\bf Default:} 0.5 \\\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}}{tp\_epsilon} & {\bf Scope:} restricted & REAL \\\hline
\multicolumn{3}{|p{\descWidth}|}{{\bf Description:}   {\em A small number to smooth out singularities at the puncture locations}} \\
\hline{\bf Range} & &  {\bf Default:} 0.0 \\\multicolumn{1}{|p{\maxVarWidth}|}{\centering 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}}{tp\_extend\_radius} & {\bf Scope:} restricted & REAL \\\hline
\multicolumn{3}{|p{\descWidth}|}{{\bf Description:}   {\em Radius of an extended spacetime instead of the puncture}} \\
\hline{\bf Range} & &  {\bf Default:} 0.0 \\\multicolumn{1}{|p{\maxVarWidth}|}{\centering 0:*} & \multicolumn{2}{p{\paraWidth}|}{anything positive, should be smaller than the horizon} \\\hline
\end{tabular*}

\vspace{0.5cm}\noindent \begin{tabular*}{\tableWidth}{|c|l@{\extracolsep{\fill}}r|}
\hline
\multicolumn{1}{|p{\maxVarWidth}}{tp\_tiny} & {\bf Scope:} restricted & REAL \\\hline
\multicolumn{3}{|p{\descWidth}|}{{\bf Description:}   {\em Tiny number to avoid nans near or at the puncture locations}} \\
\hline{\bf Range} & &  {\bf Default:} 0.0 \\\multicolumn{1}{|p{\maxVarWidth}|}{\centering 0:*} & \multicolumn{2}{p{\paraWidth}|}{anything positive, usually very small} \\\hline
\end{tabular*}

\vspace{0.5cm}\noindent \begin{tabular*}{\tableWidth}{|c|l@{\extracolsep{\fill}}r|}
\hline
\multicolumn{1}{|p{\maxVarWidth}}{use\_external\_initial\_guess} & {\bf Scope:} restricted & BOOLEAN \\\hline
\multicolumn{3}{|p{\descWidth}|}{{\bf Description:}   {\em Set initial guess by external function?}} \\
\hline & & {\bf Default:} no \\\hline
\end{tabular*}

\vspace{0.5cm}\noindent \begin{tabular*}{\tableWidth}{|c|l@{\extracolsep{\fill}}r|}
\hline
\multicolumn{1}{|p{\maxVarWidth}}{use\_sources} & {\bf Scope:} restricted & BOOLEAN \\\hline
\multicolumn{3}{|p{\descWidth}|}{{\bf Description:}   {\em Use sources?}} \\
\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:} restricted & BOOLEAN \\\hline
\multicolumn{3}{|p{\descWidth}|}{{\bf Description:}   {\em Print screen output while solving}} \\
\hline & & {\bf Default:} no \\\hline
\end{tabular*}

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

\vspace{0.5cm}\parskip = 10pt 

\section{Interfaces} 


\parskip = 0pt

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

\noindent {\bf Implements}: 

twopuncturesx
\vspace{2mm}

\noindent {\bf Inherits}: 

admbasex

coordinatesx
\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 
puncture\_u & puncture\_u & compact & 0 \\ 
 &  & dimensions & 3 \\ 
 &  & distribution & DEFAULT \\ 
 &  & group type & GF \\ 
 &  & tags & prolongation="none" \\ 
 &  & timelevels & 1 \\ 
 &  & variable type & REAL \\ 
\hline 
energy &  & compact & 0 \\ 
 & E & description & ADM energy of the Bowen-York spacetime \\ 
 &  & dimensions & 0 \\ 
 &  & distribution & CONSTANT \\ 
 &  & group type & SCALAR \\ 
 &  & timelevels & 1 \\ 
 &  & variable type & REAL \\ 
\hline 
angular\_momentum &  & compact & 0 \\ 
 & J1 & description & Angular momentum of the Bowen-York spacetime \\ 
 & J2 & dimensions & 0 \\ 
 & J3 & distribution & CONSTANT \\ 
 &  & group type & SCALAR \\ 
 &  & timelevels & 1 \\ 
 &  & variable type & REAL \\ 
\hline 
\end{tabular*} 


\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 
bare\_mass &  & compact & 0 \\ 
 & mp & description & Bare masses of the punctures \\ 
 & mm & dimensions & 0 \\ 
 &  & distribution & CONSTANT \\ 
 &  & group type & SCALAR \\ 
 &  & timelevels & 1 \\ 
 &  & variable type & REAL \\ 
\hline 
puncture\_adm\_mass &  & compact & 0 \\ 
 & mp\_adm & description & ADM masses of the punctures (measured at the other spatial infinities) \\ 
 & mm\_adm & dimensions & 0 \\ 
 &  & distribution & CONSTANT \\ 
 &  & group type & SCALAR \\ 
 &  & timelevels & 1 \\ 
 &  & variable type & REAL \\ 
\hline 
\end{tabular*} 



\vspace{5mm}

\noindent {\bf Uses header}: 

TwoPunctures.h

TP\_utilities.h

TP\_params.h

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

\section{Schedule} 


\parskip = 0pt


\noindent This section lists all the variables which are assigned storage by thorn EinsteinInitialData/TwoPuncturesX.  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:} \\ 
~ &  energy angular\_momentum puncture\_adm\_mass bare\_mass\\ 
~ &  puncture\_u\\ 
~ & ~\\ 
\end{tabular*} 


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

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

\hspace{5mm} twopuncturesx\_paramcheck 

\hspace{5mm}{\it check parameters and thorn needs } 


\hspace{5mm}

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


\vspace{5mm}

\noindent {\bf ADMBaseX\_InitialData}   (conditional) 

\hspace{5mm} twopuncturesx\_group 

\hspace{5mm}{\it twopuncturesx initial data group } 


\hspace{5mm}

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


\vspace{5mm}

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

\hspace{5mm} twopuncturesx\_group 

\hspace{5mm}{\it twopuncturesx initial data group } 


\hspace{5mm}

 \begin{tabular*}{160mm}{cll} 
~ & After:  & admbasex\_initialdata \\ 
~& ~ &hydrobase\_initial\\ 
~ & Before:  & admbasex\_postinitial \\ 
~& ~ &settmunu\\ 
~& ~ &hydrobase\_prim2coninitial\\ 
~ & Type:  & group \\ 
\end{tabular*} 


\vspace{5mm}

\noindent {\bf TwoPuncturesX\_Group}   (conditional) 

\hspace{5mm} twopuncturesx 

\hspace{5mm}{\it create puncture black hole initial data } 


\hspace{5mm}

 \begin{tabular*}{160mm}{cll} 
~ & Language:  & c \\ 
~ & Reads:  & coordinatesx::vertex\_coords(everywhere) \\ 
~ & Storage:  & puncture\_u \\ 
~ & Type:  & function \\ 
~ & Writes:  & twopuncturesx::mp(everywhere) \\ 
~& ~ &twopuncturesx::mm(everywhere)\\ 
~& ~ &twopuncturesx::mp\_adm(everywhere)\\ 
~& ~ &twopuncturesx::mm\_adm(everywhere)\\ 
~& ~ &twopuncturesx::e(everywhere)\\ 
~& ~ &twopuncturesx::j1(everywhere)\\ 
~& ~ &twopuncturesx::j2(everywhere)\\ 
~& ~ &twopuncturesx::j3(everywhere)\\ 
~& ~ &twopuncturesx::puncture\_u(everywhere)\\ 
~& ~ &admbasex::alp(everywhere)\\ 
~& ~ &admbasex::metric(everywhere)\\ 
~& ~ &admbasex::curv(everywhere)\\ 
\end{tabular*} 


\vspace{5mm}

\noindent {\bf TwoPuncturesX\_Group}   (conditional) 

\hspace{5mm} twopuncturesx\_metadata 

\hspace{5mm}{\it output twopuncturesx metadata } 


\hspace{5mm}

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



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