% *======================================================================*
%  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]{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}

\begin{document}

% The author of the documentation
\author{Christian D. Ott \textless cott@tapir.caltech.edu\textgreater, \\
Erik Schnetter \textless eschnetter@perimeterinstitute.ca\textgreater}

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

% the date your document was last changed, if your document is in CVS,
% please use:
%    \date{$ $Date: 2004-01-07 12:12:39 -0800 (Wed, 07 Jan 2004) $ $}
\date{April 19, 2011}

\maketitle

% Do not delete next line
% START CACTUS THORNGUIDE

% Add all definitions used in this documentation here
%   \def\mydef etc

\begin{abstract}
  \noindent This thorn provides a unified EOS (Equation Of State)
  interface and implements multiple analytic EOS and provides table
  reader and interpolation routines for finite-temperature
  microphysical EOS available from {\tt
    http://www.stellarcollapse.org}\@. Currently, the implemented
  analytic EOS are the polytropic EOS, the gamma-law EOS, a hybrid EOS
  consisting of a 2-piece piecewise-polytrope with an a thermal,
  gamma-law component.
\end{abstract}



\section{Introduction}

Equations of State (EOS) are crucial for hydrodynamics and hydro
codes (as well as other codes needing/providing microphysics)
are closely coupled to EOS and call EOS routines many times for
each grid point during the calculation of a time update.

\texttt{EOS\_Omni} is presently coded for cold and hot EOS, including
those based on microphysical models. It does currently assume nuclear
statistical equilibrium (NSE) with rest-mass density $\rho$, specific
internal energy $\epsilon$ (or temperature $T$), and electron fraction
$Y_e$ being the independent variables. \texttt{EOS\_Omni} can be
called on arrays or on single grid points.



\section{Units}

This thorn uses \emph{solar} units where $c = G = M_{\odot} = 1$.
Temperatures are measured in MeV.

\section{Using This Thorn}

\subsection{Basic Usage}

\texttt{EOS\_Omni} works via the aliased-function interface, and
EOS functions to be used must be declared in \texttt{interface.ccl}.
Here is an example call/{interface.ccl} entry:
\begin{verbatim}
void FUNCTION EOS_Omni_press(CCTK_INT IN eoskey,         \
                             CCTK_INT IN havetemp,       \
                             CCTK_REAL IN rf_precision,  \
                             CCTK_INT IN npoints,        \
                             CCTK_REAL IN ARRAY rho,     \
                             CCTK_REAL INOUT ARRAY eps,  \
                             CCTK_REAL INOUT ARRAY temp, \
                             CCTK_REAL IN ARRAY ye,      \
                             CCTK_REAL OUT ARRAY press   \
                             CCTK_INT OUT ARRAY keyerr,  \
                             CCTK_INT OUT anyerr)
\end{verbatim}

Here, 
\begin{itemize}
\item \texttt{eoskey} is the type of EOS to be used in this call.
  \begin{itemize}
    \item \texttt{eoskey = 1}: Polytropic EOS
    \item \texttt{eoskey = 2}: Gamma-Law EOS
    \item \texttt{eoskey = 3}: Hybrid EOS (2 Polys, 1 Gamma-Law), used
      for stellar core collapse simulations.
    \item \texttt{eoskey = 4}: Finite-temperature microphysical EOS
  \end{itemize}
\item \texttt{havetemp} determines whether the EOS is to be called as
  a function of $(\rho,\epsilon,Y_e)$ (\texttt{havetemp = 0}), as a
  function of $(\rho,T,Y_e)$ (\texttt{havetemp = 1}).
  \texttt{havetemp = 0} is the method of choice for analytic EOS during
  evolution, but at the initial data stage one may need to set
  \texttt{havetemp = 1} (with $T=0$) to obtain initial values for
  $\epsilon$.  In the case of a finite-temperature EOS (that usually
  is a function of $(\rho,T,Y_e)$), a call with \texttt{havetemp = 0}
  will first lead to the solution of $T(\rho,\epsilon,Y_e$) via a
  Newton-Raphson-type iteration (using the supplied value of $T$ as
  the starting point) and will then calculate the requested dependent
  variable as a function of $X=X(\rho,T,Y_e)$. Both $X$ and the updated
  $T$ are returned.

\item \texttt{npoints} tells the EOS how many data points are passed
  in,
\item \texttt{rho,eps,temp,ye,press} are obvious,
\item \texttt{rf\_precision} is a real number telling the root finding
  algorithm (for finding $T(\rho,\epsilon,Y_e)$) at what relative error
  to terminate the iteration. $10^{-10}$ is a good value.
\item \texttt{keyerr} is an array (with $n$ entries for $n$ data
  points) containing error codes (relevant only for tabulated
  microphysical EOS),
\item \texttt{anyerr} is an integer $>0$ in case
  any error occured.
\end{itemize}

\subsection{Parameter Settings}

Many hydro codes require a fallback EOS in case something goes
wrong. This is also true for the Einstein Toolkit GR hydro code
\texttt{EinsteinEvolve/GRHydro}. If you want to use \texttt{EOS\_Omni} with
\texttt{GRHydro}, you must set parameters for the EOS of your choice and,
\emph{in addition}, the following parameters must be set to sensible values:

\begin{verbatim}
eos_omni::poly_gamma 
eos_omni::poly_gamma_ini 
eos_omni::poly_k 
\end{verbatim}

The only non-obvious parameter here is \texttt{poly\_gamma\_ini}.
In most simulations it should be set equal to \texttt{poly\_gamma}.
In simulations that are run with a different adiabatic index than
what was used to set up the initial data, \texttt{poly\_gamma} should
be the evolution value, and \texttt{poly\_gamma\_ini} should be the initial
data value.

Check \texttt{param.ccl} for parameters for the other EOS\@.



\section{Equations of State Details}

\subsection{Polytropic}

The \texttt{poly} EOS is a \emph{polytropic} equation of state, which
does not allow for changes in entropy:
\begin{eqnarray}
  p & = & K \rho^\gamma
\end{eqnarray}
where $p$ is the pressure, $\rho$ the density, $K$ the polytropic
constant set via \texttt{poly\_k}, and $\gamma$ is the adiabatic index
set via \texttt{poly\_gamma}.

If the internal energy $\epsilon$ is to be ``calculated from the
temperature'' (\texttt{havetemp = 1}), then this is done using the
relation
\begin{eqnarray}
  \epsilon & = & \frac{K}{\gamma-1} \rho^{\gamma-1}
\label{eq:polyeps}
\end{eqnarray}
(which actually ignores the temperature).

Internally, \texttt{EOS\_Omni} uses cgs units and on startup converts
the EOS parameters from solar units to cgs units. This conversion
depends on $\gamma$ and the value of $\gamma$ at the initial
data stage (\texttt{poly\_gamma\_ini}) is used for this.
Note that contrary to what the parameter name suggests, 
\texttt{EOS\_Omni} does not make a distinction between initial data
setup and time evolution; if such a distinction is required, it must
be implemented outside of this thorn.

Note also: This polytropic EOS is also used as fall-back when other
EOS fail.

\subsection{Gamma-Law}

The \texttt{gl} EOS is a \emph{gamma-law} equation of state,
corresponding to an ideal gas:
\begin{eqnarray}
  p & = & (\gamma-1) \rho \epsilon
\end{eqnarray}
where $p$ is the pressure, $\rho$ the density, $\epsilon$ the internal
energy, and $\gamma$ is the adiabatic index set via
\texttt{gl\_gamma}.

At the initial data stage, it may be necessary to set up initial
values for $\epsilon$. For this, the \texttt{gl} EOS 
implements equation (\ref{eq:polyeps}) just like the \texttt{poly}
EOS and the parameters \texttt{poly\_gamma\_ini} and 
\texttt{gl\_k} must be set for this.



%%% The parameter \texttt{poly\_gamma\_ini} (not \texttt{gl\_gamma\_ini}!)
%%% influences the definition of this EOS via unit conversions: $K$ is
%%% first converted from solar units to cgs units using
%%% \texttt{poly\_gamma\_ini}, and then converted back to solar units
%%% using \texttt{gl\_gamma}. \textbf{TODO: confirm this.} Note that the
%%% parameter \texttt{gl\_gamma\_ini} is actually unused. \textbf{TODO:
%%%   confirm this.} Contrary to what the parameter name suggests, this
%%% EOS thorn makes no distinction between initial data setup and time
%%% evolution; if such a distinction is required, then it must be
%%% implemented outside of this thorn.
%%% If the internal energy $\epsilon$ is to be ``calculated from the
%%% temperature'' (\texttt{havetemp = 1}), then this is done using the
%%% relation
%%% \begin{eqnarray}
%%%   \epsilon & = & \frac{K}{\gamma-1} rho^{\gamma-1}
%%% \end{eqnarray}
%%% (which actually ignores the temperature). $K$ the polytropic constant
%%% set via \texttt{gl\_k}. This is the same relation as for the
%%% polytropic equation of state above.

\subsection{Hybrid}

\textbf{TODO: Not yet documented.}

\subsection{Finite-Temperature Nuclear}

\textbf{TODO: Not yet documented; not even mentioned yet in some other
  sections of this documentation.}



\section{Converting Old Parameter Files}

If you have a parameter file that uses the previous EOS interface in
Cactus, you will have to convert it so that it runs with
\texttt{EOS\_Omni}. The following describes a set of simple rules for
this conversion.

\begin{enumerate}
\item Add \texttt{EOS\_Omni} to the thorn list. You can then remove
  all other \texttt{EOS\_*} thorns from the thorn list (or you can
  leave them in; they are unused).
\item Activate \texttt{EOS\_Omni} in the parameter file: Add
  \texttt{EOS\_Omni} to your active thorns, and do not activate any
  other \texttt{EOS\_*} thorns.
\item Translate all EOS parameters according to table
  \ref{tab:paramconv}.
\item All thorns using this EOS interface will have a parameter that
  determines which EOS to use, typically via a string/keyword
  parameter specifying an EOS name. Convert these names using table
  \ref{tab:eosnames}.
\end{enumerate}

\begin{table}
  \begin{tabular}{ll|ll}
    Old Parameter & Old Value & New Parameter & New Value\\
    \hline
    EOS\_Polytrope::eos\_gamma & &
    EOS\_Omni::poly\_gamma &
    \\
    EOS\_Polytrope::eos\_k & &
    EOS\_Omni::poly\_k &
    \\
    EOS\_Polytrope::use\_cgs & yes &
    --- &
    \\
    EOS\_Polytrope::use\_cgs & no &
    unsupported &
    \\
    EOS\_Polytrope::gamma\_ini & &
    EOS\_Omni::poly\_gamma\_ini &
    \\
    EOS\_Ideal\_Fluid::eos\_ideal\_fluid\_gamma & &
    EOS\_Omni::gl\_gamma &
    \\
    \textbf{TODO: complete this table}
  \end{tabular}
  \caption{Parameter conversion table}
  \label{tab:paramconv}
\end{table}

\begin{table}
  \begin{tabular}{llll}
    EOS    & Description                & Old Name & New Name \\\hline
    poly   & polytropic                 & ???      & 2D\_Polytrope \\
    gl     & gamma-law                  & ???      & Ideal\_Fluid \\
    hybrid & hybrid                     & ???      & Hybrid \\
    nuc    & finite-temperature nuclear & ???      & nuc\_eos
  \end{tabular}
  \caption{EOS name conversion table}
  \label{tab:eosnames}
\end{table}



%\begin{thebibliography}{9}

%\end{thebibliography}

% Do not delete next line
% END CACTUS THORNGUIDE

\end{document}
