Binary file doc/pdf/eilmer3-user-guide.pdf has changed

--- a/doc/sphinx/getting-started.rst	Sun Jun 09 11:20:20 2013 +0100
+++ b/doc/sphinx/getting-started.rst	Mon Jun 10 10:26:53 2013 +0100
@@ -24,6 +24,12 @@
 #. You will need a password for any access.  Please ask.
 #. You can read but not write with the "cfcfdlocal" username.
 #. Some usernames (by negotiation) may push changesets back to the repository.
+#. Some gas models depend on the NASA CEA code or the NIST REFPROP library.
+   If you want to use these models (and there is no look-up-table equivalent
+   already available) you will need to obtain these codes and place them 
+   into the extern/ directory.  
+   They are not included as part of our cfcfd3 repository but the cfcfd3 makefiles
+   will be aware of them if they are sitting in the extern/ directory.
 
 
 Licence

--- a/doc/sphinx/index.rst	Sun Jun 09 11:20:20 2013 +0100
+++ b/doc/sphinx/index.rst	Mon Jun 10 10:26:53 2013 +0100
@@ -6,7 +6,9 @@
 The Compressible-Flow CFD Project
 =================================
 
-Since the 1980s, we have been building compressible flow simulation codes. 
+Since the 1980s, we have been building compressible flow simulation codes.
+Our goal is to make these codes into reliable simulation tools 
+for high-temperature gasdynamic flows. 
 
 .. figure:: _static/slot-injection-by-vince.jpeg
    :align: center

--- a/doc/sphinx/intro.rst	Sun Jun 09 11:20:20 2013 +0100
+++ b/doc/sphinx/intro.rst	Mon Jun 10 10:26:53 2013 +0100
@@ -56,14 +56,20 @@
 ---------------------
 Daryl Bond;
 Wilson Chan;
-Jason Czapla;
+Zac Denman;
+Elise Fahy;
 David Gildfind;
 Rowan J. Gollan;
 Peter A. Jacobs;
+Ingo Jahn;
+Chris James;
+Matthew McGilvray, University of Oxford;
+Andrew Pastrello;
 Paul J. Petrie-Repar, RPM-Turbo, Brisbane;
 Daniel Potter, DLR, Goettingen;
-Emilie Sauret;
+Anand Veeraragavan;
 Carlos de Miranda Ventura;
+Han Wei;
 Vincent Wheatley;
 Fabian Zander.
 
@@ -72,9 +78,9 @@
 Joanna M. Austin, University of Illinois, Urbana;
 Kevin J. Austin, UQ, Brisbane;
 Peter Blyton, Brisbane;
-Russell Boyce, UQ, Brisbane;
 Chris S. Craddock, BMT, UK;
 Brian Cook;
+Jason Czapla;
 Andrew Denman;
 Michael Elford;
 James M. Faddy;
@@ -89,6 +95,7 @@
 Andrew M. McGhee, Brisbane;
 Brendan O'Flaherty, WBM Pty Ltd, Brisbane;
 Leon Prucha;
+Emilie Sauret;
 Michael Scott; 
 Todd Silvester; 
 Ben Stewart;

--- a/doc/sphinx/poshax3/FireII-1634s.rst	Sun Jun 09 11:20:20 2013 +0100
+++ b/doc/sphinx/poshax3/FireII-1634s.rst	Mon Jun 10 10:26:53 2013 +0100
@@ -1,1 +1,1 @@
-../../../examples/poshax3/FireII/1634s/README.txt
\ No newline at end of file
+../../../examples/poshax3/FireII/1634s/2T/README.txt
\ No newline at end of file

--- a/examples/eilmer3/user-guide/gas_models.tex	Sun Jun 09 11:20:20 2013 +0100
+++ b/examples/eilmer3/user-guide/gas_models.tex	Mon Jun 10 10:26:53 2013 +0100
@@ -279,7 +279,7 @@
 
 \subsubsection{Building your own look-up table}
 Of course, you might have a gas mixture you wish to simulate that is not listed in Table~\ref{tab:lut}.
-The tool \texttt{build-cea-lut} is provided as part of the code collection to aid in building a 
+The tool \texttt{build-cea-lut.py} is provided as part of the code collection to aid in building a 
 look-up table of the appropriate format.
 You will need access to the \texttt{cea2} program~\cite{gordon_mcbride_1994, mcbride_gordon_1996}, and have that setup in your working area
 \footnote{By setup, I mean
@@ -287,65 +287,79 @@
 are available in the working directory.
 Also, the program \texttt{cea2} needs to be available as an executable in your \texttt{\$PATH}.}.
 
-The first step is to build a ``template'' file.
-This file specifies the composition of the gas model and some other options appropriate to the modelling.
-Here is an example template file to build a look-up table for a Mars-like atmosphere with no ionisation but
-includes trace species. 
+\medskip
+The \texttt{build-cea-lut.py} program has a lot of options.
+If you invoke it with out any options at all, you get the following text:
+{\footnotesize
+\begin{verbatim}
+Begin build-cea-lut.py...
+Usage: build-cea-lut.py [options]
 
-\noindent
-\topbar
-\lstinputlisting[language={}]{../../../lib/gas/cea-cases/Mars-trace.lua}
-\bottombar
+Options:
+  -h, --help            show this help message and exit
+  -g GASNAME, --gas=GASNAME
+                        name of built-in gas mixture
+  -l, --list-gases      list available gas names and exit
+  -c, --custom          build a custom gas model from reactants
+  -b BOUNDS, --bounds=BOUNDS
+                        bounds of the table in form
+                        "T_min,T_max,log_rho_min,log_rho_max"
+  -T T_FOR_OFFSET, --T-for-offset=T_FOR_OFFSET
+                        Temperature (degree K) at which to evaluate the
+                        internal energy offset.
+
+  Custom gas options:
+    -r REACTANTS, --reactants=REACTANTS
+                        reactant fractions in dictionary form
+    -o ONLYLIST, --only-list=ONLYLIST
+                        limit species to this list
+    -m, --moles         reactant fractions as mole fractions [default]
+    -f, --massf         reactant fractions as mass fractions
+    -n, --no-ions       excluding ions [default]
+    -i, --with-ions     including ions
+
+Example 1: build-cea-lut.py --gas=air5species
+Example 2: build-cea-lut.py --custom --reactants="N2:0.79,O2:0.21" --only-list="N2,O2,NO,O,N"
+Example 3: build-cea-lut.py --gas=air-ions --bounds="500,20000,-6.0,2.0"
+Example 4: build-cea-lut.py --gas=co2 --T-for-offset=650.0 --bounds="1000.0,20000,-6.0,2.0"
+Example 5: build-cea-lut.py --gas=co2-ions --T-for-offset=1000.0 --bounds="1000.0,20000,-6.0,2.0"
 
-\noindent
-The list of expected parameters are given in Table~\ref{tab:lut-template}
-\begin{table}[ht]
-\begin{center}
-\caption{Description of parameters required to build a template file for \texttt{build-cea-lut}}
-\label{tab:lut-template}
-\begin{tabular}{llp{8cm}}
-\hline \hline
-Parameter & Type & Description \\ \hline
-\texttt{fname} & \textit{string} & A name for the look-up table.  Usually just specifed as
-                                   \texttt{some\_name.lua}.  The program will add a trailing
-                                   \texttt{.gz} when it zips up the look-up table. \\
-\texttt{units} & \textit{string} & This denotes the units for specifying the relative amount of reactants.
-                                   The choices are:
-                                   \begin{itemize}
-                                      \item \texttt{'moles'} \textit{(default if not specified)} to specify by molar composition
-                                      \item \texttt{'massf'} to specify by mass (weight) composition 
-                                   \end{itemize} \\
-\texttt{reactants} & \textit{table} & This table lists the reactants in the mixture.  The keys are the species names as
-                                      recognised by CEA and the values are the composition. \\
-\texttt{with\_ions} & \textit{boolean} & If true, allow ionisation (by specifying \texttt{'ions'} in the CEA input files.
-                                         If false, ionisation is not allowed \textit{(default)}. \\
-\texttt{only\_list} & \textit{string} & This string restricts the allowable species in gas mixture computation.  The format for
-                                        the string is a space separated list of species.  This item is optional: if omitted, 
-                                        the CEA program is free to choose which species are considered according to its
-                                        own internal algorithm. \\
-\hline
-\end{tabular}
-\end{center}
-\end{table}
+Sometimes CEA2 has problems and the table will fail to build.
+The best approach to fixing the problem seems to be to raise
+the lower temperatures, as shown in examples 3, 4 and 5 (above).
+\end{verbatim}
+} % end of \footnotesize
 
-For more examples, the template files for all of the pre-built tables listed in Table~\ref{tab:lut} are available in
-\texttt{\$HOME/e3bin/cea-cases/}.
+\medskip
+These options allow you to set bounds on the range of the table,
+select a gas model from a small library of prespecified gases or
+to make your own \textit{custom} mixture.
+The available gases (as at mid June 2013) are:
+   ``air'',
+   ``air-ions'',
+   ``air5species'',
+   ``air7species'',
+   ``air11species'',
+   ``air13species'',
+   ``n2'',
+   ``n2-ions'',
+   ``co2'',
+   ``co2-ions'',
+   ``mars-basic'',
+   ``h2ne'',
+   ``h2ne-ions'', and
+   ``ar''.
+If you make a custom mixture, you specify the reactants as a dictionary where the keys are
+species names, as recognised by the \verb!CEA2! program.
+The \verb!only_list! option can be used to restrict the allowable species in the gas mixture.
+If it is not specified, \verb!CEA2! is free to choose which species are considered according to its
+own internal algorithm.
+To make equilibrium gas models that are consistent with a corresponding finite-rate kinetics model,
+it would probably be best to supply a value for the \verb!only_list! option.
 
-Once you have created a template file, the \texttt{build-cea-lut} tool can be called.
-Supposing your template file is called \texttt{Venus-atmosphere.lua}, then issue
-the following command in your working directory:\\
-\topbar\\
-\texttt{> build-cea-lut --user-defined=Venus-atmosphere.lua} \\
-\bottombar\\
-You may use the \texttt{--extrapolate} flag to fill in the edges
-of the look-up table by linear interpolation where no data is available, however, this option
-is not presently recommended.
-If this flag is omitted, a smaller table is built that does not extrapolate at the edges.
-Note that this flag only controls extrapolation during the \textit{construction} of the table; in 
-the actual use of the table during \textit{simulation}, the values are always extrapolated
-if they exceed the limits of the table.
-Upon successful execution of the \texttt{build-cea-lut}, you will have a compressed (gzipped)
-file in your working directory.
-This file (not the template file) can be used to select an equilibrium gas in the
+\medskip
+Upon successful execution of the \texttt{build-cea-lut.py}, you will have a compressed (gzipped)
+Lua file in your working directory.
+This file can be used to select an equilibrium gas in the
 same manner as using a pre-built table, as was discussed in the preceding section. 
 

--- a/examples/eilmer3/user-guide/hakkinen-SWLBLI.tex	Sun Jun 09 11:20:20 2013 +0100
+++ b/examples/eilmer3/user-guide/hakkinen-SWLBLI.tex	Mon Jun 10 10:26:53 2013 +0100
@@ -131,6 +131,18 @@
 Figure\,\ref{fig:hakkinen-field-data} shows some of the flow field data at $t$=1.75\,ms after flow start.
 The magnitude of the gradients of density (Fig.\,\ref{fig:hakkinen-gradient}) are also shown 
 as an approximation to the schlieren image of Figure\,\ref{fig:hakkinen-fig6b-schlieren}.
+The image of the pressure clearly shows the waves propagating from the leading-edge viscous interaction
+and their reflection from the shock generator.
+As expected, the boundary layer is not directly evident in the pressure field but shows up
+clearly in the temperature field.
+The more gradual compression, as the boundary layer approaches the incident shock, is evident
+as a much as a much broader band in the pressure field.
+This is followed by an expansion and then a recompression.
+All of these waves are most clearly shown in the gradient of density field.
+The shock, expansion and recomression shock from the leading-edge viscous interaction 
+are displayed more distinctly and the convergence of the gradual compressions becomes clear.
+The structure of expansion fans also appears more clearly in this gradient field
+than in the pressure or temperature fields.
 
 \begin{figure}[htbp]
  \centering
@@ -150,10 +162,12 @@
 The simulation has done a reasonable job of estimating the pressure distribution right 
 through the separation zone.
 Features that look a little wrong include the viscous interaction region at $x$=0,
-which is a bit extended because of lack of resolution at the start of the boundary layer.
+which is a bit extended because of lack of resolution at the start of the boundary layer,
+however, doubling the grid resolution (factor=8) tightens up solution in this region.
 Also, there is an artificial drop in pressure at the right end of the simulation domain
 where the boundary layer exits the flow domain but this is of no concern because  
 the flat plate used in the experiment was more than twice the length of this simulated version.
+This behaviour is grid independent.
 
 \medskip
 The simulation has done a reasonable job on the shear stress,
@@ -164,13 +178,19 @@
 just before rising toward the end of the flow domain.
 This is, again, the interaction with the outflow boundary condition and would be removed from view
 if the full length of the plate was simulated.
+The only discernible difference with increasing grid resolution (from factor=4 to factor=8) is that
+the early development of the boundary layer moves a little closer to the Blasius behaviour.
 
 \begin{figure}[htbp]
  \centering
- \subfloat[Pressure.]{\includegraphics[width=0.5\textwidth]
+ \subfloat[Pressure (factor=4).]{\includegraphics[width=0.5\textwidth]
     {../2D/hakkinen-SWLBLI/pressure.pdf}\label{fig:hakkinen-pressure-on-plate}}
- \subfloat[Shear stress.]{\includegraphics[width=0.5\textwidth]
-    {../2D/hakkinen-SWLBLI/shear.pdf}\label{fig:hakkinen-shear-stress-on-plate}}
+ \subfloat[Shear stress (factor=4).]{\includegraphics[width=0.5\textwidth]
+    {../2D/hakkinen-SWLBLI/shear.pdf}\label{fig:hakkinen-shear-stress-on-plate}}\\
+ \subfloat[Pressure (factor=8).]{\includegraphics[width=0.5\textwidth]
+    {../2D/hakkinen-SWLBLI/pressure-factor-8.pdf}\label{fig:hakkinen-pressure-on-plate-factor-8}}
+ \subfloat[Shear stress (factor=8).]{\includegraphics[width=0.5\textwidth]
+    {../2D/hakkinen-SWLBLI/shear-factor-8.pdf}\label{fig:hakkinen-shear-stress-on-plate-factor-8}}
  \caption{Distribution of pressure and shear along the plate at $t$=1.75\,ms.}
  \label{fig:hakkinen-plate-data-compare}
 \end{figure}

--- a/examples/eilmer3/user-guide/user-input-script.tex	Sun Jun 09 11:20:20 2013 +0100
+++ b/examples/eilmer3/user-guide/user-input-script.tex	Mon Jun 10 10:26:53 2013 +0100
@@ -668,9 +668,23 @@
   The WEST and EAST boundaries progress SOUTH to NORTH.
   If the \texttt{e3prep.py} program complains that the corners of your patch are ``open'',
   that may be a symptom of having one, or more, of your bounding paths having incorrect orientation.
-\item \texttt{AOPatch}($p_S, p_N, p_W, p_E$): an interpolated surface \index{geometric element!AOPatch}
+\item \texttt{CoonsPatch}($p00, p10, p11, p01$): a quadrilateral surface defined by it corners.
+  Straight line segments (implicitly) join the corners.
+  This is convenient for building simple regions that can be tiled with straight edged patches,
+  since you don't need to explicitly generate Lines to form the edges of each patch.
+  Note that the order for specifying the corners is counter-clockwise,
+  starting with the South-West corner.
+\item \texttt{AOPatch}($p_S, p_N, p_W, p_E$): an interpolated surface, \index{geometric element!AOPatch}
+  bounded by four paths,
   that tries to keep the grid orthogonal near the edges and 
   also tries to keep equal areas across the surface.
+\item \texttt{AOPatch}($p00, p10, p11, p01$): a quadrilateral surface defined by it corners.
+  Straight line segments (implicitly) join the corners.
+  Note that the order for specifying the corners is counter-clockwise,
+  starting with the South-West corner.
+  The difference with the corresponding CoonsPatch is that the internal grid, here,
+  tries to be orthogonal to the edges and maintain
+  equal cell areas across the surface.
 \item \texttt{MeshPatch}: a surface defined over a structured mesh of
   quadrilateral facets.\index{geometric element!MeshPatch}
   This might be useful for generating new grids from files imported from
@@ -968,7 +982,7 @@
 region of interest (Figure\,\ref{the-minimal-grid-fig}).
 These are created as \texttt{Nodes} with labels so that they show up in
 the generated SVG plot.
-The simplest way to define the region is to make a patch with the four sides
+A simple way to define the region is to make a patch with the four sides
 specified as staight-line paths.
 The \texttt{Block2D} is initialized with this patch, the number of cells
 in each direction and the initial gas state within the region.
@@ -1509,6 +1523,10 @@
   Since the time stepping is synchronous across all parts of the flow domain,
   this time step size should be smaller than half of the smallest time for a signal
   (pressure wave) to cross any cell in the flow domain. 
+  If you are sure that your geometric and boundary descriptions but your simulation
+  fails for no clear reason, try setting the initial time step to a very small value.
+  For some simulations of viscous hypersonic flow on fine grids, 
+  it is not unusual to require time steps to be as small as a nanosecond.
 \item \texttt{dt\_chem}: suggested time-step for finite-rate chemistry update;
   default value of -1.0 indicates that we want the code to work it out.
 \item \texttt{dt\_therm}: default value -1.0.
@@ -1585,7 +1603,9 @@
      that are described below.
    \item \verb!"ausm_plus_up"!: Implemented from Ref.\,\cite{liou_2006a}.
      It should be accurate and robust for all speed regimes.  
-     It is the flux calculator of choice for very low Mach number flows.
+     It is the flux calculator of choice for very low Mach number flows,
+     where the fluid behaviour approaches the incompressible limit.
+     For best results, you should set the value of \verb!M_inf!.
    \item \verb!"hlle"! The MHD version of the HLLE scheme.
   \end{itemize}  
   The ADAPTIVE scheme is a good all-round scheme that uses AUSMDV away from