% *======================================================================* % 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} % 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{June 27 2010} \maketitle % Do not delete next line % START CACTUS THORNGUIDE % Add all definitions used in this documentation here % \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\@. \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 caculation 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. \section{Units} This thorn uses \emph{solar} units where $c = G = M_{sun} = 1$. \textbf{TODO: confirm this.} \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_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 core-collapse simulations. \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{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{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 \textt{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} \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. 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}. 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}{ll} 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}