[Commits] [svn:einsteintoolkit] EOS_Omni/trunk/doc/ (Rev. 42)
cott at tapir.caltech.edu
cott at tapir.caltech.edu
Tue Apr 19 10:16:15 CDT 2011
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 at tapir.caltech.edu\textgreater}
+\author{Christian D. Ott \textless cott at tapir.caltech.edu\textgreater, \\
+Erik Schnetter \textless eschnetter at 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,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 \\
More information about the Commits
mailing list