Begin to improve documentation

git-svn-id: http://svn.einsteintoolkit.org/cactus/EinsteinEOS/EOS_Omni/trunk@39 8e189c6b-2ab8-4400-aa02-70a9cfce18b9

1 files changed, 185 insertions, 33 deletions

diff --git a/doc/documentation.tex b/doc/documentation.tex
index 5f7d36f..40905bc 100644
--- a/doc/documentation.tex
+++ b/doc/documentation.tex
@@ -97,15 +97,13 @@
 % Add all definitions used in this documentation here
 %   \def\mydef etc
 
-% Add an abstract for this thorn's documentation
 \begin{abstract}
-This Thorn provides a unified EOS interface and implements
-multiple EOS. These currently are the polytropic EOS, the
-gamma-law EOS, and the hybrid EOS.
+  This thorn provides a unified EOS (Equation Of State) interface and
+  implements multiple EOS\@. Currently, these are the polytropic EOS,
+  the gamma-law EOS, and a hybrid EOS\@.
 \end{abstract}
 
-% The following sections are suggestive only.
-% Remove them or add your own.
+
 
 \section{Introduction}
 
@@ -114,20 +112,28 @@ 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 caculation of a time update.
 
-{\tt EOS\_Omni} is presently coded for cold and hot EOS, 
+\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 density,
 specific internal energy (or temperature), and electron fraction
-being the independent variables. {\tt EOS\_Omni} may be called
-on vectors or on single points.
+being the independent variables. \texttt{EOS\_Omni} can be called
+on arrays or on single grid points.
 
-\section{Using This Thorn}
 
 
+\section{Units}
+
+This thorn uses \emph{solar} units where $c = G = M_{sun} = 1$.
+\textbf{TODO: confirm this.}
+
+
+
+\section{Using This Thorn}
+
 \subsection{Basic Usage}
 
-{\tt EOS\_Omni} works via the aliased-function interface and
-EOS functions to be used must be declared in {\tt interface.ccl}.
+\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,         \
@@ -144,31 +150,36 @@ void FUNCTION EOS_Omni_press(CCTK_INT IN eoskey,         \
 
 Here, 
 \begin{itemize}
-\item {\tt eoskey} is the type of EOS to be used in this call.
+\item \texttt{eoskey} is the type of EOS to be used in this call.
   \begin{itemize}
-    \item {\tt eoskey = 1}: Polytropic EOS
-    \item {\tt eoskey = 2}: Gamma-Law EOS
-    \item {\tt eoskey = 3}: Hybrid EOS (2 Polys, 1 Gamma-Law), used
+    \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 core-collapse simulations.
   \end{itemize}
-\item {\tt havetemp} tells the EOS if the call is $X=X(\rho,T,Y_e)$
-  ({\tt havetemp = 1}) or $X=X(\rho,\epsilon,Y_e)$  ({\tt havetemp = 0}),
-\item {\tt npoints} tells the EOS how many data points are passed
+\item \texttt{havetemp} tells the EOS whether the internal energy
+  should be calculated from the temperature first, i.e.\ whether the
+  call is $\epsilon=\epsilon(\rho,T,Y_e), X=X(\rho,\epsilon,Y_e)$
+  (both $\epsilon$ and $X$ are calculated and returned \textbf{TODO:
+    confirm this}) (\texttt{havetemp = 1}), or
+  $X=X(\rho,\epsilon,Y_e)$ (the temperature is ignored)
+  (\texttt{havetemp = 0}),
+\item \texttt{npoints} tells the EOS how many data points are passed
   in,
-\item {\tt rho,eps,temp,ye,press} are obvious,
-\item {\tt keyerr} is an array (with n entries for n data points)
+\item \texttt{rho,eps,temp,ye,press} are obvious,
+\item \texttt{keyerr} is an array (with $n$ entries for $n$ data points)
   containing error codes (relevant only for tabular EOS),
-\item {\tt anyerr} is an integer that is .gt. 0 in the case
+\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 {\tt
-EinsteinEvolve/GRHydro}. If you want to use {\tt EOS\_Omni} with {\tt
-GRHydro}, you must set parameters for the EOS of your choice and, {\bf
-in addition}, the following parameters must be set to sensible values:
+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 
@@ -176,18 +187,159 @@ eos_omni::poly_gamma_ini
 eos_omni::poly_k 
 \end{verbatim}
 
-The only non-obvious parameter here is {\tt poly\_gamma\_ini}.
-In most simulations it should be set equal to {\tt poly\_gamma}.
+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, {\tt poly\_gamma} should
-be the evolution value, and {\tt poly\_gamma\_ini} should be the initial
+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 out {\tt param.ccl} for parameters for other EOS.
+Check \texttt{param.ccl} for parameters for the other EOS\@.
+
+
+
+\section{Equations of State Details}
+
+\subsection{Polytropic}
+
+The \textt{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}
+\end{eqnarray}
+(which actually ignores the temperature).
+
+The parameter \texttt{poly\_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{poly\_gamma}. \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.
+
+Note: Although this EOS depends on a parameter called $\gamma$, it
+should not be confused with the ``gamma-law'' EOS, which is different.
+
+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}.
+
+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}{ll}
+    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}
 
-\subsection{Special Behavior}
 
-If special behavior occurs, please report it to {\tt cott@tapir.caltech.edu}.
 
 %\begin{thebibliography}{9}