% *======================================================================* % Cactus Thorn template for ThornGuide documentation % Author: Ian Kelley % Date: Sun Jun 02, 2002 % $Header$ % % Thorn documentation in the latex file doc/documentation.tex % will be included in ThornGuides built with the Cactus make system. % The scripts employed by the make system automatically include % pages about variables, parameters and scheduling parsed from the % relevant thorn CCL files. % % This template contains guidelines which help to assure that your % documentation will be correctly added to ThornGuides. More % information is available in the Cactus UsersGuide. % % Guidelines: % - Do not change anything before the line % % START CACTUS THORNGUIDE", % except for filling in the title, author, date, etc. fields. % - Each of these fields should only be on ONE line. % - Author names should be separated with a \\ or a comma. % - You can define your own macros, but they must appear after % the START CACTUS THORNGUIDE line, and must not redefine standard % latex commands. % - To avoid name clashes with other thorns, 'labels', 'citations', % 'references', and 'image' names should conform to the following % convention: % ARRANGEMENT_THORN_LABEL % For example, an image wave.eps in the arrangement CactusWave and % thorn WaveToyC should be renamed to CactusWave_WaveToyC_wave.eps % - Graphics should only be included using the graphicx package. % More specifically, with the "\includegraphics" command. Do % not specify any graphic file extensions in your .tex file. This % will allow us to create a PDF version of the ThornGuide % via pdflatex. % - References should be included with the latex "\bibitem" command. % - Use \begin{abstract}...\end{abstract} instead of \abstract{...} % - Do not use \appendix, instead include any appendices you need as % standard sections. % - For the benefit of our Perl scripts, and for future extensions, % please use simple latex. % % *======================================================================* % % Example of including a graphic image: % \begin{figure}[ht] % \begin{center} % \includegraphics[width=6cm]{MyArrangement_MyThorn_MyFigure} % \end{center} % \caption{Illustration of this and that} % \label{MyArrangement_MyThorn_MyLabel} % \end{figure} % % Example of using a label: % \label{MyArrangement_MyThorn_MyLabel} % % Example of a citation: % \cite{MyArrangement_MyThorn_Author99} % % Example of including a reference % \bibitem{MyArrangement_MyThorn_Author99} % {J. Author, {\em The Title of the Book, Journal, or periodical}, 1 (1999), % 1--16. {\tt http://www.nowhere.com/}} % % *======================================================================* % If you are using CVS use this line to give version information % $Header$ \documentclass{article} % Use the Cactus ThornGuide style file % (Automatically used from Cactus distribution, if you have a % thorn without the Cactus Flesh download this from the Cactus % homepage at www.cactuscode.org) \usepackage{../../../../doc/latex/cactus} \begin{document} % The author of the documentation \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} % 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{April 19, 2011} \maketitle % Do not delete next line % START CACTUS THORNGUIDE % Add all definitions used in this documentation here % \def\mydef etc \begin{abstract} \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} \section{Introduction} 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 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 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_{\odot} = 1$. Temperatures are measured in MeV. \section{Using This Thorn} \subsection{Basic Usage} \texttt{EOS\_Omni} works via the aliased-function interface, and EOS functions to be used must be declared in \texttt{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_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_INT OUT ARRAY keyerr, \ CCTK_INT OUT anyerr) \end{verbatim} Here, \begin{itemize} \item \texttt{eoskey} is the type of EOS to be used in this call. \begin{itemize} \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 stellar core collapse simulations. \item \texttt{eoskey = 4}: Finite-temperature microphysical EOS \end{itemize} \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{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} \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 \texttt{EinsteinEvolve/GRHydro}. If you want to use \texttt{EOS\_Omni} with \texttt{GRHydro}, you must set parameters for the EOS of your choice and, \emph{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 \texttt{poly\_gamma\_ini}. In most simulations it should be set equal to \texttt{poly\_gamma}. In simulations that are run with a different adiabatic index than what was used to set up the initial data, \texttt{poly\_gamma} should be the evolution value, and \texttt{poly\_gamma\_ini} should be the initial data value. Check \texttt{param.ccl} for parameters for the other EOS\@. \section{Equations of State Details} \subsection{Polytropic} 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 \end{eqnarray} where $p$ is the pressure, $\rho$ the density, $K$ the polytropic constant set via \texttt{poly\_k}, and $\gamma$ is the adiabatic index set via \texttt{poly\_gamma}. 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} \label{eq:polyeps} \end{eqnarray} (which actually ignores the temperature). 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. \subsection{Gamma-Law} The \texttt{gl} EOS is a \emph{gamma-law} equation of state, corresponding to an ideal gas: \begin{eqnarray} p & = & (\gamma-1) \rho \epsilon \end{eqnarray} where $p$ is the pressure, $\rho$ the density, $\epsilon$ the internal energy, and $\gamma$ is the adiabatic index set via \texttt{gl\_gamma}. 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} \textbf{TODO: Not yet documented.} \subsection{Finite-Temperature Nuclear} \textbf{TODO: Not yet documented; not even mentioned yet in some other sections of this documentation.} \section{Converting Old Parameter Files} If you have a parameter file that uses the previous EOS interface in Cactus, you will have to convert it so that it runs with \texttt{EOS\_Omni}. The following describes a set of simple rules for this conversion. \begin{enumerate} \item Add \texttt{EOS\_Omni} to the thorn list. You can then remove all other \texttt{EOS\_*} thorns from the thorn list (or you can leave them in; they are unused). \item Activate \texttt{EOS\_Omni} in the parameter file: Add \texttt{EOS\_Omni} to your active thorns, and do not activate any other \texttt{EOS\_*} thorns. \item Translate all EOS parameters according to table \ref{tab:paramconv}. \item All thorns using this EOS interface will have a parameter that determines which EOS to use, typically via a string/keyword parameter specifying an EOS name. Convert these names using table \ref{tab:eosnames}. \end{enumerate} \begin{table} \begin{tabular}{ll|ll} Old Parameter & Old Value & New Parameter & New Value\\ \hline EOS\_Polytrope::eos\_gamma & & EOS\_Omni::poly\_gamma & \\ EOS\_Polytrope::eos\_k & & EOS\_Omni::poly\_k & \\ EOS\_Polytrope::use\_cgs & yes & --- & \\ EOS\_Polytrope::use\_cgs & no & unsupported & \\ EOS\_Polytrope::gamma\_ini & & EOS\_Omni::poly\_gamma\_ini & \\ EOS\_Ideal\_Fluid::eos\_ideal\_fluid\_gamma & & EOS\_Omni::gl\_gamma & \\ \textbf{TODO: complete this table} \end{tabular} \caption{Parameter conversion table} \label{tab:paramconv} \end{table} \begin{table} \begin{tabular}{llll} EOS & Description & Old Name & New Name \\\hline poly & polytropic & ??? & 2D\_Polytrope \\ gl & gamma-law & ??? & Ideal\_Fluid \\ hybrid & hybrid & ??? & Hybrid \\ nuc & finite-temperature nuclear & ??? & nuc\_eos \end{tabular} \caption{EOS name conversion table} \label{tab:eosnames} \end{table} %\begin{thebibliography}{9} %\end{thebibliography} % Do not delete next line % END CACTUS THORNGUIDE \end{document}