From 1c67a495d4c391845f06209734f15471bdd0c861 Mon Sep 17 00:00:00 2001
From: cott <cott@8e189c6b-2ab8-4400-aa02-70a9cfce18b9>
Date: Fri, 2 Jul 2010 21:41:36 +0000
Subject: * add prelim documentation

git-svn-id: http://svn.einsteintoolkit.org/cactus/EinsteinEOS/EOS_Omni/EOS_Omni@2 8e189c6b-2ab8-4400-aa02-70a9cfce18b9
---
 doc/documentation.tex | 103 ++++++++++++++++++++++++++++++++++++++------------
 1 file changed, 79 insertions(+), 24 deletions(-)

diff --git a/doc/documentation.tex b/doc/documentation.tex
index 3912bd2..5f7d36f 100644
--- a/doc/documentation.tex
+++ b/doc/documentation.tex
@@ -99,7 +99,9 @@
 
 % 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.
 \end{abstract}
 
 % The following sections are suggestive only.
@@ -107,36 +109,89 @@
 
 \section{Introduction}
 
-\section{Physical System}
+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.
 
-\section{Numerical Implementation}
+{\tt 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.
 
 \section{Using This Thorn}
 
-\subsection{Obtaining This Thorn}
 
 \subsection{Basic Usage}
 
-\subsection{Special Behaviour}
-
-\subsection{Interaction With Other Thorns}
-
-\subsection{Examples}
-
-\subsection{Support and Feedback}
-
-\section{History}
-
-\subsection{Thorn Source Code}
-
-\subsection{Thorn Documentation}
-
-\subsection{Acknowledgements}
-
-
-\begin{thebibliography}{9}
-
-\end{thebibliography}
+{\tt EOS\_Omni} works via the aliased-function interface and
+EOS functions to be used must be declared in {\tt 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_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 {\tt 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
+      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
+  in,
+\item {\tt rho,eps,temp,ye,press} are obvious,
+\item {\tt 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
+  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:
+
+\begin{verbatim}
+eos_omni::poly_gamma 
+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}.
+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
+data value.
+
+Check out {\tt param.ccl} for parameters for other EOS.
+
+\subsection{Special Behavior}
+
+If special behavior occurs, please report it to {\tt cott@tapir.caltech.edu}.
+
+%\begin{thebibliography}{9}
+
+%\end{thebibliography}
 
 % Do not delete next line
 % END CACTUS THORNGUIDE
-- 
cgit v1.2.3