From 9bb734167f40f70b01622ccbd57829bf80481581 Mon Sep 17 00:00:00 2001 From: cott Date: Tue, 19 Apr 2011 15:16:15 +0000 Subject: * 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 --- doc/documentation.tex | 148 +++++++++++++++++++++++++++++--------------------- 1 file changed, 85 insertions(+), 63 deletions(-) (limited to 'doc') 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 \\ -- cgit v1.2.3