% *======================================================================*
%  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/ExternalLibraries/RePrimAnd/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 Kastaun \textless physik@fangwolg.de\textgreater}

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

% 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{November 12 2021}

\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 provides the RePrimAnd library.
The RePrimAnd library is a support library for general relativistic
magnetohydrodynamics independent of the EinsteinToolkit/Cactus. 
It currently provides an EOS framework and an ideal GRMHD primitive variable 
recovery algorithm.
\end{abstract}
\section{The RePrimAnd library}
In detail, the following functionality is provided: 
\begin{itemize}
\item An algorithm for primitive variable recovery in ideal GRMHD
\item Generic EOS interface
\begin{itemize}
\item Three-parametric EOS with thermal and composition effects
\item One-parametric (barotropic) EOS
\item Validity ranges and strict error handling
\end{itemize}
\item Various EOS implementations
\begin{itemize}
\item Polytropic
\item Piecewise polytropic
\item Tabulated barotropic
\item Ideal gas
\item Hybrid EOS
\item Design allows adding custom EOSs 
\end{itemize}
\item Universal EOS file format 
\end{itemize}


The algorithm for primitive variable recovery is EOS-agnostic and very robust. 
The method and tests are described in~\cite{RePrimaAnd_PhysRevD.103.023018}. 
Full documentation of the library is available online at
\url{https://wokast.github.io/RePrimAnd/index.html}.

RePrimAnd is written in C++ and completely independent of Cactus/Einstein Toolkit or any other 
framework. The stand-alone version of the library can be found at
\url{https://github.com/wokast/RePrimAnd}.
The stand-alone version also provides unit tests and includes Python bindings. The latter
could be used for post-processing, making it possible to, e.g., apply an EOS to numpy arrays. 

\section{The RePrimAnd Thorn}
This thorn simply makes the C++ interface available for use by ET thorns, but provides no further
integration. In particular, the thorn provides no aliased functions and no Fortran interface.
At the moment, the thorn also contains no test suite.
Further thorns providing better integration are planned for the near future.

Some remarks on EOS are in order. 
First, there are two ways of specifying EOS, either creating them on-the-fly, or by loading 
from EOS files in the universal format defined by RePrimAnd. At the moment, there is no public repository 
for such EOS files. Users can however create such files themselves through a dedicated Python-API available in the 
github repository (see online documentation). The file format will remain backwards-compatible for the foreseeable future.
Second, the library allows the addition of custom EOS implementations without recompiling the library.
The same holds for extending the universal EOS file format. It should not be necessary to change the library 
source code for this. For details, see the online documentation.

\begin{thebibliography}{9}
\bibitem{RePrimaAnd_PhysRevD.103.023018}
Kastaun, W, Kalinani, J, Ciolfi, R. ``Robust recovery of primitive variables in
relativistic ideal magnetohydrodynamics''. Phys. Rev. D 2021; 103:023018.
\end{thebibliography}

% Do not delete next line
% END CACTUS THORNGUIDE



\section{Parameters} 


\parskip = 0pt
\parskip = 10pt 

\section{Interfaces} 


\parskip = 0pt

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

\noindent {\bf Implements}: 

reprimand
\vspace{2mm}

\vspace{5mm}\parskip = 10pt 

\section{Schedule} 


\parskip = 0pt


\noindent This section lists all the variables which are assigned storage by thorn ExternalLibraries/RePrimAnd.  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

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