* some work on documentation. more to come

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

1 files changed, 85 insertions, 63 deletions

diff --git a/doc/documentation.tex b/doc/documentation.tex
index 40905bc..490fe55 100644
--- a/doc/documentation.tex
+++ b/doc/documentation.tex
@@ -79,7 +79,8 @@
 \begin{document}
 
 % The author of the documentation
-\author{Christian D. Ott \textless cott@tapir.caltech.edu\textgreater}
+\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}
@@ -87,7 +88,7 @@
 % 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{June 27 2010}
+\date{April 19, 2011}
 
 \maketitle
 
@@ -98,9 +99,14 @@
 %   \def\mydef etc
 
 \begin{abstract}
-  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\@.
+  \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}
 
 
@@ -110,23 +116,21 @@
 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 caculation of a time update.
+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 density,
-specific internal energy (or temperature), and electron fraction
-being the independent variables. \texttt{EOS\_Omni} can be called
-on arrays or on single grid points.
+\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_{sun} = 1$.
-\textbf{TODO: confirm this.}
-
-
+This thorn uses \emph{solar} units where $c = G = M_{\odot} = 1$.
+Temperatures are measured in MeV.
 
 \section{Using This Thorn}
 
@@ -138,12 +142,13 @@ 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_REAL OUT ARRAY press   \
                              CCTK_INT OUT ARRAY keyerr,  \
                              CCTK_INT OUT anyerr)
 \end{verbatim}
@@ -155,20 +160,32 @@ Here,
     \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.
+      for stellar core collapse simulations.
+    \item \texttt{eoskey = 4}: Finite-temperature microphysical EOS
   \end{itemize}
-\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{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{keyerr} is an array (with $n$ entries for $n$ data points)
-  containing error codes (relevant only for tabular EOS),
+\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}
@@ -202,7 +219,7 @@ Check \texttt{param.ccl} for parameters for the other EOS\@.
 
 \subsection{Polytropic}
 
-The \textt{poly} EOS is a \emph{polytropic} equation of state, which
+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
@@ -215,21 +232,19 @@ 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}
+  \epsilon & = & \frac{K}{\gamma-1} \rho^{\gamma-1}
+\label{eq:polyeps}
 \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.
+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.
@@ -245,26 +260,33 @@ 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.
+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}
 
@@ -301,8 +323,8 @@ this conversion.
 
 \begin{table}
   \begin{tabular}{ll|ll}
-    Old Parameter & Old Value & New Parameter & New Value
-    \\\hline
+    Old Parameter & Old Value & New Parameter & New Value\\
+    \hline
     EOS\_Polytrope::eos\_gamma & &
     EOS\_Omni::poly\_gamma &
     \\
@@ -328,7 +350,7 @@ this conversion.
 \end{table}
 
 \begin{table}
-  \begin{tabular}{ll}
+  \begin{tabular}{llll}
     EOS    & Description                & Old Name & New Name \\\hline
     poly   & polytropic                 & ???      & 2D\_Polytrope \\
     gl     & gamma-law                  & ???      & Ideal\_Fluid \\