From cf7a8b58f4ae85517bbe0797efdc95c2a539d76e Mon Sep 17 00:00:00 2001
From: knarf <knarf@e77735cb-7dd8-4a7a-87c7-7cc99eb84b11>
Date: Wed, 2 Dec 2009 22:22:51 +0000
Subject: thorns for general eos interface (moved from Whisky_Dev repositories)

git-svn-id: http://svn.einsteintoolkit.org/cactus/EinsteinBase/EOSG_Base/trunk@2 e77735cb-7dd8-4a7a-87c7-7cc99eb84b11
---
 doc/documentation.tex | 457 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 457 insertions(+)
 create mode 100755 doc/documentation.tex

(limited to 'doc/documentation.tex')

diff --git a/doc/documentation.tex b/doc/documentation.tex
new file mode 100755
index 0000000..b1cd8d9
--- /dev/null
+++ b/doc/documentation.tex
@@ -0,0 +1,457 @@
+% *======================================================================*
+%  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{Ian Hawke \textless ih@maths.soton.ac.uk\textgreater}
+
+% The title of the document (not necessarily the name of the Thorn)
+\title{General equations of state}
+
+% the date your document was last changed, if your document is in CVS,
+% please use:
+%    \date{$ $Date$ $}
+\date{March 15 2005}
+
+\maketitle
+
+% Do not delete next line
+% START CACTUS THORNGUIDE
+
+% Add all definitions used in this documentation here
+%   \def\mydef etc
+
+% Add an abstract for this thorn's documentation
+\begin{abstract}
+  This thorn provides a generalized equation of state interface.
+\end{abstract}
+
+% The following sections are suggestive only.
+% Remove them or add your own.
+
+\section{Equations of state}
+
+In solving the equations of hydrodynamics there are five independent
+variables (typically $\rho, v^i, \epsilon$ for the rest mass density,
+velocity and specific internal energy) and further variables, such as
+the pressure $P$ which depend on the independent variables. Such
+dependent variables are specified by an {\em equation of state} (EOS)
+that closes the system of equations. Simple EOSs depend only on the
+independent variables and are usually given in terms of the pressure,
+i.e.\ $P = P(\rho, \epsilon)$ which then implicitly defines other
+variables such as the temperature $T$, pressure derivatives $P_{\rho},
+P_{\epsilon}$ and the speed of sound $c_s$.
+
+However there is no physical reason to prefer such simple EOSs. A
+realistic EOS will depend on the composition of the fluid as well as
+the independent variables. This thorn is meant to provide an interface
+so that a hydrodynamics code can depend on such a realistic EOS
+without having to know about the details of the composition --
+without, in fact, needing an knowledge of the additional variables
+required by the EOS at all.
+
+\section{Calling an EOS}
+
+The most efficient way of using the EOS is to call it to set grid
+functions. The interface is simple on the face of it; one function
+call will give you a {\em call handle}, and another function call will
+actually set the EOS. The complexity comes in setting up the key value
+tables involved in the function calls.
+
+\begin{FunctionDescription}{EOS\_SetupCall}
+  \label{Whisky_Dev_EOSBase_General_EOS_SetupCall}
+
+  Sets up an equation of state call. If the call handle is stored
+  (which is recommended) then this only needs to be performed once at
+  startup time, and the call handle can be reused.
+
+  \begin{SynopsisSection}
+    \begin{Synopsis}{C}
+\begin{verbatim}
+CCTK_INT call_handle = EOS_SetupCall(CCTK_INT table_handle)
+\end{verbatim}
+    \end{Synopsis}
+    \begin{Synopsis}{Fortran}
+\begin{verbatim}
+CCTK_INT call_handle = EOS_SetupCall(CCTK_INT table_handle)
+\end{verbatim}
+    \end{Synopsis}
+  \end{SynopsisSection}
+
+  \begin{ResultSection}
+    \begin{ResultNote}
+      The {\tt call\_handle} return must be stored for later use in
+      the EOS call. The value should be $\geq 0$. Typically a level
+      0 warning will be given rather than returning an error code.
+    \end{ResultNote}
+    \begin{Result}{$\geq 0$}
+      The call handle, to be stored for later use.
+    \end{Result}
+  \end{ResultSection}
+  
+  \begin{ParameterSection}
+    \begin{Parameter}{table\_handle}
+      The handle of an existing key value table. Appropriate
+      arguments will be described elsewhere.
+    \end{Parameter}
+  \end{ParameterSection}
+  
+  \begin{Discussion}
+    The complexity comes in setting up the key-value table to be
+    passed through. Effectively any arguments can be given that will
+    be interpreted by the EOS, but the following are expected (note
+    capitalization - it is always useful to set up the table using the
+    CASE INSENSITIVE flag):
+    \begin{itemize}
+    \item {\tt EOS Name}: This must correspond to the name that the
+      EOS thorn has registered.
+    \item {\tt Independent variable names}: This is a string (a
+      CCTK\_STRING) of whitespace separated names describing the
+      independent variables. Although there is no particular values
+      for these ``names'' required by this base thorns the following
+      conventions for variable names have been used in existing thorns
+      (name in parantheses is the variable name in {\sc whisky}):
+      \begin{itemize}
+      \item {\tt Rho}: Rest mass density ({\tt rho})
+      \item {\tt SpecificInternalEnergy}: Specific internal energy
+        ({\tt eps})
+      \item {\tt Pressure}: Pressure ({\tt press})
+      \item {\tt DPressureDRho}: Partial derivative of pressure with
+        respect to rest mass density, all else being fixed ({\tt
+          dpdrho})
+      \item {\tt DPressureDSpecificInternalEnergy}: Partial derivative
+        of pressure with respect to specific internal energy, all else
+        being fixed ({\tt dpdeps})
+      \item {\tt c\_s\^{}2}: Speed of sound squared ({\tt cs2}).
+      \end{itemize}
+    \item {\tt Dependent variable names}: A string describing the
+      dependent variables, following the same syntax as the {\tt
+        Independent variable names}
+    \item {\tt N independent variables}: The number of independent
+      variables
+    \item {\tt N dependent variables}: The number of dependent
+      variables
+    \item {\tt Independent GFs}: An array of integers containing the
+      indices of the grid functions corresponding to the independent
+      variables. E.g., if the first dependent variable name is {\tt
+        Rho} which is contained in the grid function {\tt whisky::rho}
+      then the first entry of this array is found from {\tt
+        CCTK\_VarIndex("whisky::rho")}.
+    \item {\tt Dependent GFs}: An array of integers containing the
+      indices of the dependent grid functions, following the syntax of
+      the {\tt Independent GFs}.
+    \end{itemize}
+  \end{Discussion}
+
+  \begin{SeeAlsoSection}
+    \begin{SeeAlso}{EOS\_SetGFs}
+      Sets the EOS.
+    \end{SeeAlso}
+  \end{SeeAlsoSection}
+\end{FunctionDescription}
+
+
+
+\begin{FunctionDescription}{EOS\_SetGFs}
+  \label{Whisky_Dev_EOSBase_General_EOS_SetGFs}  
+  
+  Actually sets the dependent GFs in an EOS call. The call must have
+  been previously set up using EOS\_SetupCall. Must be called from
+  routines scheduled in {\tt local} mode.
+
+  \begin{SynopsisSection}
+    \begin{Synopsis}{C}
+\begin{verbatim}
+CCTK_INT ierr = EOS_SetGFs(CCTK_POINTER_TO_CONST cGH, CCTK_INT call_handle)
+\end{verbatim}
+    \end{Synopsis}
+    \begin{Synopsis}{Fortran}
+\begin{verbatim}
+CCTK_INT ierr = EOS_SetGFs(CCTK_POINTER_TO_CONST cGH, CCTK_INT call_handle)
+\end{verbatim}
+    \end{Synopsis}
+  \end{SynopsisSection}
+
+  \begin{ResultSection}
+    \begin{ResultNote}
+      The {\tt call\_handle} should have been previously set up by
+      EOS\_SetupCall. Currently only successful returns (0) are
+      given.
+    \end{ResultNote}
+    \begin{Result}{\rm 0}
+      success.
+    \end{Result}
+  \end{ResultSection}
+
+  \begin{ParameterSection}
+    \begin{Parameter}{cGH}
+      The Cactus GH structure, and the reason why this must be called
+      in {\tt local} mode.
+    \end{Parameter}
+    \begin{Parameter}{call\_handle}
+      An EOS call previously set up by EOS\_SetupCall.
+    \end{Parameter}
+  \end{ParameterSection}
+
+  \begin{Discussion}
+    Once the EOS call has been setup this routine basically tells the
+    EOS function to apply the appropriate EOS calls at this point to
+    the appropriate arrays.
+  \end{Discussion}
+
+  \begin{SeeAlsoSection}
+    \begin{SeeAlso}{EOS\_SetupCall}
+      Setup the EOS call.
+    \end{SeeAlso}
+  \end{SeeAlsoSection}
+\end{FunctionDescription}
+
+\pagebreak
+\section{Registering an EOS}
+
+Before you can use an EOS one first has to be registered. The best way
+of learning how to do this is to look at the example thorns, such as
+the ``generalized'' polytropic EOS (thorn {\tt EOS\_GeneralPolytrope}) or
+ideal gas EOS (thorn {\tt EOS\_GeneralIdealFluid}). Here is just the
+essential description.
+
+The essential thing that is required is a function (probably in C,
+although in theory it's language independent) that sets arbitrary
+sized arrays\footnote{The arbitrariness applies to the different
+  calls, not different arrays: all arrays, whether for independent or
+  dependent variables are assumed to have the same size in any given
+  call.} of dependent variables from the independent variables. This
+function is registered using the aliased function {\tt
+  EOS\_RegisterCall}. This function, and the function pointer that
+must be called, are as follows.
+
+
+
+
+\begin{FunctionDescription}{EOS\_RegisterCall}
+  \label{Whisky_Dev_EOSBase_General_EOS_RegisterCall}  
+  
+  Register an EOS with the base thorn.
+
+  \begin{SynopsisSection}
+    \begin{Synopsis}{C}
+\begin{verbatim}
+CCTK_INT ierr = EOS_RegisterCall(CCTK_INT table_handle, \
+                                 CCTK_INT CCTK_FPOINTER EOS_fn(...))
+\end{verbatim}
+    \end{Synopsis}
+    \begin{Synopsis}{Fortran}
+\begin{verbatim}
+CCTK_INT ierr = EOS_RegisterCall(CCTK_INT table_handle, \
+                                 CCTK_INT CCTK_FPOINTER EOS_fn(...))
+\end{verbatim}
+    \end{Synopsis}
+  \end{SynopsisSection}
+
+  \begin{ResultSection}
+    \begin{ResultNote}
+      The function pointer {\tt EOS\_fn} is described below on
+      page~\pageref{Whiskty_Dev_EOSBase_General_EOS_fn}.  
+
+      Currently only successful returns (0) are given.
+    \end{ResultNote}
+    \begin{Result}{\rm 0}
+      success.
+    \end{Result}
+  \end{ResultSection}
+
+  \begin{ParameterSection}
+    \begin{Parameter}{table\_handle}
+      A key/value table containing any persistent information that the
+      EOS thorn may want to store. This is not used by the base thorn,
+      and is there for the convenience of the EOS thorn.
+    \end{Parameter}
+    \begin{Parameter}{EOS\_fn}
+      A function pointer for the EOS call itself, described below.
+    \end{Parameter}
+  \end{ParameterSection}
+
+  \begin{Discussion}
+    The table can be used to differentiate between different
+    calls. For example, if one thorn implements many different
+    EOSs and the number is not known at compile time (e.g., a table
+    interpolator thorn that provides multiple tables) then only one
+    registration need take place, and the key/value table can be used
+    store which (interpolation) table is being used in the particular
+    call. 
+  \end{Discussion}
+
+  \begin{SeeAlsoSection}
+    \begin{SeeAlso}{EOS\_fn}
+      The actual EOS function.
+    \end{SeeAlso}
+  \end{SeeAlsoSection}
+\end{FunctionDescription}
+
+
+\begin{FunctionDescription}{EOS\_fn}
+  \label{Whisky_Dev_EOSBase_General_EOS_fn}  
+  
+  The actual EOS function that must be provided.
+
+  \begin{SynopsisSection}
+    \begin{Synopsis}{C}
+\begin{verbatim}
+CCTK_INT ierr = EOS_fn(CCTK_INT param_table, \
+                       CCTK_INT n_elems, \
+                       CCTK_POINTER* indep_arrays, \
+                       CCTK_INT* which_dep_arrays_to_set, \
+                       CCTK_POINTER* dep_arrys)
+\end{verbatim}
+    \end{Synopsis}
+    \begin{Synopsis}{Fortran}
+\begin{verbatim}
+CCTK_INT ierr = EOS_fn(CCTK_INT param_table, \
+                       CCTK_INT n_elems, \
+                       CCTK_POINTER* indep_arrays, \
+                       CCTK_INT* which_dep_arrays_to_set, \
+                       CCTK_POINTER* dep_arrys)
+\end{verbatim}
+    \end{Synopsis}
+  \end{SynopsisSection}
+
+  \begin{ResultSection}
+    \begin{ResultNote}
+      Currently only successful returns (0) are given.
+    \end{ResultNote}
+    \begin{Result}{\rm 0}
+      success.
+    \end{Result}
+  \end{ResultSection}
+
+  \begin{ParameterSection}
+    \begin{Parameter}{param\_table}
+      A key/value table containing any persistent information that the
+      EOS thorn may want to store. This is not used by the base thorn,
+      and is there for the convenience of the EOS thorn.
+    \end{Parameter}
+    \begin{Parameter}{n\_elems}
+      The size of the arrays that are passed in.
+    \end{Parameter}
+    \begin{Parameter}{indep\_arrays}
+      The independent arrays (should essentially be cast to a {\tt
+        CCTK\_REAL**}).
+    \end{Parameter}
+    \begin{Parameter}{which\_dep\_arrays\_to\_set}
+      An array telling the EOS thorn which dependent arrays should be
+      set in this thorn. This is important because dependent arrays
+      that are not needed will NOT be passed in the call; see below.
+    \end{Parameter}
+    \begin{Parameter}{dep\_arrays}
+      The dependent arrays (should essentially be cast to a {\tt
+        CCTK\_REAL**}). Note that you should not assume that all these
+      pointers are non-null (hence the difficulty in using this with
+      Fortran). In general, if the calling thorn does NOT request that
+      a dependent variable be set then the equivalent pointer WILL be
+      null.
+    \end{Parameter}
+  \end{ParameterSection}
+
+  \begin{Discussion}
+    The table can be used to differentiate between different
+    calls. For example, if one thorn implements many different
+    EOSs and the number is not known at compile time (e.g., a table
+    interpolator thorn that provides multiple tables) then only one
+    registration need take place, and the key/value table can be used
+    store which (interpolation) table is being used in the particular
+    call. 
+  \end{Discussion}
+
+  \begin{SeeAlsoSection}
+    \begin{SeeAlso}{EOS\_RegisterCall}
+      Register the EOS function with the base thorn.
+    \end{SeeAlso}
+  \end{SeeAlsoSection}
+\end{FunctionDescription}
+
+
+
+\begin{thebibliography}{9}
+
+\end{thebibliography}
+
+% Do not delete next line
+% END CACTUS THORNGUIDE
+
+\end{document}
-- 
cgit v1.2.3

