User: cott Date: 2011/04/19 10:16 AM
Modified: /trunk/doc/ documentation.tex
Log: * some work on documentation. more to come
File Changes:
Directory: /trunk/doc/ ======================
File [modified]: documentation.tex Delta lines: +84 -62 =================================================================== --- trunk/doc/documentation.tex 2011-03-31 17:40:09 UTC (rev 41) +++ trunk/doc/documentation.tex 2011-04-19 15:16:15 UTC (rev 42) @@ -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%7D%5C@. 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,24 +116,22 @@ 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}
\subsection{Basic Usage} @@ -138,12 +142,13 @@ \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 @@ \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 @@
\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,22 +232,20 @@ 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. +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: 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.
@@ -245,27 +260,34 @@ 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. +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.
-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.
+ +%%% 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.} @@ -301,8 +323,8 @@
\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 @@ \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 \