% *======================================================================*
%  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/CactusSgrid/DNSdata/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{Wolfgang Tichy \textless wolf@fau.edu\textgreater \\ Michal Pirog \textless mpirog@fau.edu\textgreater}

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

% the date your document was last changed, if your document is in CVS,
% please use:
%    \date{$ $Date$ $}
% when using git instead record the commit ID:
%    \date{\gitrevision{<path-to-your-.git-directory>}}
\date{October 28 2023}

\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}
This thorn allows one to use SGRID-generated initial data of Binary
Neutron Stars as a starting point for the Cactus simulation.
\end{abstract}

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

\section{Introduction}

To initiate the simulations of Binary Neutron Stars, one needs realistic
initial data that accurately encodes the state of both stars in orbit prior
to merger. The numerical code, SGRID, allows the generation of initial data
for stars characterized by arbitrary masses, spins, and orbital
eccentricities, along with an equation of state.

SGRID is a separate numerical code that can create initial data. To do this,
it has to be compiled and run separately from Cactus.
This initial data can then be used by Cactus to conduct a time-dependent
simulation. However, SGRID writes ID files in its own format. To make it
usable for Cactus, it is necessary to provide this data on the grid points
used by Cactus. This is achieved by interpolating data from SGRID's grid
points onto the grid points used by Cactus. The functions that perform the
actual interpolation reside inside the SGRID library, which is usually
compiled into Cactus by adding the thorn ExternalLibraries-SGRID.

To simplify this process, we have developed a Cactus thorn called DNSdata,
which can read SGRID initial data into Cactus, allowing Cactus to perform
the subsequent evolution.

%\section{Physical System}

\section{Numerical Implementation}

Sgrid is a separate numerical code which creates initial data. One may find the details
in: \\
https://www.physics.fau.edu/\verb!~!wolf/Research/FAU-sgrid/

\section{Using This Thorn}

\subsection{Obtaining This Thorn}

The arrangement containing the thorn can be downloaded by typing:

git clone git@github.com:wofti/CactusSgrid.git

The thorn is in the directory DNSdata.

The directory "DNSdata/useful\_files" contains several files that might
be useful to a new user, such as the parfile example "dns.par".

Among other files, there is also a script named "prepare\_DNSdata.sh". One
can use it to set up Cactus together with this thorn. The only thing you
need to do is execute the script, which will result in the downloading of
Cactus and its components according to the thornlist "dns.th". The script
contains many more lines that are currently commented out. These lines allow
the user more flexibility during compilation, but it requires more
independent work.

Explanation of the files in "DNSdata/useful\_files":

\begin{itemize}
\item dns.th - it is a thorns list required by Cactus (and by GetComponents script to download all necessary components to compile Cactus).
\item dns.par - it is an example of Cactus input parameter file. There is a place in it to set the parameters related to DNSdata thorn. In particular, you must set the path to SGRID-generated initial data in it.
\item dns.cfg - it is a configuration file which contains a compilation options. (In particular, the SGRID library path is set in it. These lines are commented out because it is not necessary as you compile Cactus with SGRID as an External Library, see next line)
\item MyConfig  - it is a file required by SGRID to be compiled with a proper options. You are setting here the compiler, libraries, etc. (Not necessary anymore, since SGRID exist as a Cactus External Library now and is already included in the thornlist "dns.th")
\item s\_comp.sh - it is just a sbatch submission script which you may use to compile Cactus. Of course, it is a template to be modified before using.
\end{itemize}

\subsection{Basic Usage}

In order to read SGRID-generated initial data and make them ready for
interpolation, the correct path to the ID directory must be provided. It
requires the following variable in the parfile:

DNSdata::sgrid\_datadir = "path\_to\_ID\_directory"

The standard SGRID ID packet is a directory containing three files:
\begin{enumerate}
\item "checkpoint.0" - contains the SGIRD ID
\item "ID\_directory.par" - is SGRID's own parameter file - needs to have the same name as the containing dir plus the .par extension
\item "BNSdata\_properties.txt" - contains essential system characteristics that summarize the model
\end{enumerate}

After the first initial stage of the run, when the SGRID interpolation is
completed, the rest belongs solely to Cactus and is independent on the
choice of ID delivery, in particular it is independent on this thorn.

%\subsection{Special Behaviour}

\subsection{Interaction With Other Thorns}

The thorn DNSdata requires the following other thorns:
ExternalLibraries-SGRID, ADMBase, and HydroBase.

To import metric quantities from an initial data solution, the following
HydroBase and ADMBase variables need to be set to DNSdata:
\begin{itemize}
\item HydroBase::initial\_hydro          = "DNSdata"
\item ADMBase::initial\_data             = "DNSdata"
\item ADMBase::initial\_lapse            = "DNSdata"
\item ADMBase::initial\_shift            = "zero"
\item ADMBase::initial\_dtlapse          = "DNSdata"
\item ADMBase::initial\_dtshift          = "zero"
\end{itemize}

\subsection{Other useful information}

Since some system characteristics are required by Cactus and should be
correctly set in Cactus' .par file, it is recommended to get familiar with
"BNSdata\_properties.txt" file. Important points are:

a) Ensure that the center of the grid box in Cactus, specified by
"CarpetRegrid2::position\_x\_1," corresponds to the density maximum of the
neutron star (NS), denoted as "xmax1" in the SGRID-generated
"BNSdata\_properties.txt" file. IMPORTANT COMMENT about unequal mass
binaries: SGRID uses coordinates where the origin of the coordinate system
is at the point halfway between the two stars, whereas Cactus prefers
coordinates where the origin is at the center of mass of the binary. The
DNSdata thorn will translate the stars accordingly, but the user must
understand where the stars then lie and should adjust the Cactus grid
centers accordingly. I.e. "xmax1" in "BNSdata\_properties.txt" needs to be
shifted by the CM location "x\_CM" to obtain the x-coordinate in Cactus.

b) Ensure that the parameters related to the choice of the equation of state
(EoS) align with SGRID's EoS parameters. SGRID's EoS is described in the
file "BNSdata\_properties.txt". For a piecewise polytrope the relevant lines
are indicated by "rho0\_list", "n\_list", and "kappa". Here "rho0\_list"
specifies the rest mass densities at which we switch between polytropes.
"n\_list" gives the polytropic index n for each piece. Note that
   $\Gamma = 1 + 1/n$    and    $P = K \rho_0^\Gamma$.
"kappa" specifies the K of the polytrope used for the lowest density.

\subsection{Examples}

We provide a sample of initial data located in the directory "sgrid\_id" within a standard "test" directory. A brief test, which does not produce any output for the importer's verification interface, is set up in the parfile "DNSdata\_test.par", also located in the standard "test" directory. It is a parfile based on slightly modified version of the "bns.par" available at: https://www.einsteintoolkit.org/gallery/bns/bns.par.

It loads low-resolution initial data for spinless, equal-mass, highly eccentric, SLy-EoS system of Binary Neutron Star. The "cctk\_final\_time" is set to be equal to 10.0.


%\subsection{Support and Feedback}

%\section{History}

\subsection{Thorn Source Code}

\subsection{Thorn Documentation}

\subsection{Acknowledgements}


\begin{thebibliography}{9}

\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}{interpolate\_make\_finer\_grid2}

\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}}{idfiles\_dir} & {\bf Scope:} private & STRING \\\hline
\multicolumn{3}{|p{\descWidth}|}{{\bf Description:}   {\em Directory with ID .dat-files already interpolated to our current bam grid (needed if DNSdataReader\_use\_interpolator = no)}} \\
\hline{\bf Range} & &  {\bf Default:} (none) \\\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}}{interpolate\_make\_finer\_grid2} & {\bf Scope:} private & BOOLEAN \\\hline
\multicolumn{3}{|p{\descWidth}|}{{\bf Description:}   {\em make finer grid2 to get a good guess for X,Y,Z [yes,no]}} \\
\hline & & {\bf Default:} yes \\\hline
\end{tabular*}

\vspace{0.5cm}\noindent \begin{tabular*}{\tableWidth}{|c|l@{\extracolsep{\fill}}r|}
\hline
\multicolumn{1}{|p{\maxVarWidth}}{interpolate\_max\_xyz\_diff} & {\bf Scope:} private & REAL \\\hline
\multicolumn{3}{|p{\descWidth}|}{{\bf Description:}   {\em if positive we quit if x(X,Y,Z), y(X,Y,Z), z(X,Y,Z) differ by more than this from bam's x,y,x}} \\
\hline{\bf Range} & &  {\bf Default:} -1.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}}{interpolate\_verbose} & {\bf Scope:} private & BOOLEAN \\\hline
\multicolumn{3}{|p{\descWidth}|}{{\bf Description:}   {\em whether we print all points to stdout}} \\
\hline & & {\bf Default:} no \\\hline
\end{tabular*}

\vspace{0.5cm}\noindent \begin{tabular*}{\tableWidth}{|c|l@{\extracolsep{\fill}}r|}
\hline
\multicolumn{1}{|p{\maxVarWidth}}{keep\_sgrid\_output} & {\bf Scope:} private & BOOLEAN \\\hline
\multicolumn{3}{|p{\descWidth}|}{{\bf Description:}   {\em whether we keep the output sgrid creates while running [yes,no]}} \\
\hline & & {\bf Default:} no \\\hline
\end{tabular*}

\vspace{0.5cm}\noindent \begin{tabular*}{\tableWidth}{|c|l@{\extracolsep{\fill}}r|}
\hline
\multicolumn{1}{|p{\maxVarWidth}}{rotation180} & {\bf Scope:} private & BOOLEAN \\\hline
\multicolumn{3}{|p{\descWidth}|}{{\bf Description:}   {\em rotate DNSdata by 180 degrees about z-axis [yes,no]}} \\
\hline & & {\bf Default:} no \\\hline
\end{tabular*}

\vspace{0.5cm}\noindent \begin{tabular*}{\tableWidth}{|c|l@{\extracolsep{\fill}}r|}
\hline
\multicolumn{1}{|p{\maxVarWidth}}{sgrid\_datadir} & {\bf Scope:} private & STRING \\\hline
\multicolumn{3}{|p{\descWidth}|}{{\bf Description:}   {\em location of sgrid outdir with data}} \\
\hline{\bf Range} & &  {\bf Default:} (none) \\\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}}{sgrid\_exe} & {\bf Scope:} private & STRING \\\hline
\multicolumn{3}{|p{\descWidth}|}{{\bf Description:}   {\em location of sgrid executable}} \\
\hline{\bf Range} & &  {\bf Default:} ./sgrid \\\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}}{use\_interpolator} & {\bf Scope:} private & BOOLEAN \\\hline
\multicolumn{3}{|p{\descWidth}|}{{\bf Description:}   {\em whether we use DNSdataReader\_interpolator}} \\
\hline & & {\bf Default:} yes \\\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}: 

dnsdata
\vspace{2mm}

\noindent {\bf Inherits}: 

grid

summationbyparts

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 CactusSgrid/DNSdata.  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}NONE
\subsection*{Scheduled Functions}
\vspace{5mm}

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

\hspace{5mm} dnsdatapars 

\hspace{5mm}{\it read pars from bnsdata\_properties.txt } 


\hspace{5mm}

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


\vspace{5mm}

\noindent {\bf HydroBase\_Initial}   (conditional) 

\hspace{5mm} dnsdatareader 

\hspace{5mm}{\it read binary neutron star initial data } 


\hspace{5mm}

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



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