[cig-commits] r4202 - mc/3D/CitcomS/trunk/doc/manual

[sue at geodynamics.org]

Author: sue
Date: 2006-08-02 12:42:02 -0700 (Wed, 02 Aug 2006)
New Revision: 4202

Added:
   mc/3D/CitcomS/trunk/doc/manual/citcoms.lyx
Removed:
   mc/3D/CitcomS/trunk/doc/manual/citcoms_book.xml
   mc/3D/CitcomS/trunk/doc/manual/graphics.tar.gz
Log:
replace manual with lyx manual

Added: mc/3D/CitcomS/trunk/doc/manual/citcoms.lyx
===================================================================
--- mc/3D/CitcomS/trunk/doc/manual/citcoms.lyx	2006-08-02 00:17:49 UTC (rev 4201)
+++ mc/3D/CitcomS/trunk/doc/manual/citcoms.lyx	2006-08-02 19:42:02 UTC (rev 4202)
@@ -0,0 +1,12091 @@
+#LyX 1.4.1 created this file. For more info see http://www.lyx.org/
+\lyxformat 245
+\begin_document
+\begin_header
+\textclass book
+\language english
+\inputencoding auto
+\fontscheme default
+\graphics default
+\paperfontsize default
+\spacing single
+\papersize default
+\use_geometry false
+\use_amsmath 0
+\cite_engine basic
+\use_bibtopic false
+\paperorientation portrait
+\secnumdepth 2
+\tocdepth 2
+\paragraph_separation indent
+\defskip medskip
+\quotes_language english
+\papercolumns 1
+\papersides 2
+\paperpagestyle default
+\tracking_changes false
+\output_changes true
+\end_header
+
+\begin_body
+
+\begin_layout Title
+CitComS.py Manual
+\end_layout
+
+\begin_layout Author
+California Institute of Technology
+\end_layout
+
+\begin_layout Date
+05.15.06
+\end_layout
+
+\begin_layout Standard
+\begin_inset LatexCommand \tableofcontents{}
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Part
+Preface
+\end_layout
+
+\begin_layout Chapter*
+Preface
+\end_layout
+
+\begin_layout Section*
+About This Document
+\end_layout
+
+\begin_layout Standard
+This document is organized into three parts.
+ Part I consists of traditional book front matter, including this preface.
+ Part II begins with an introduction to Pyre and the Pyre-compatible version
+ of CitComS and their capabilities and proceeds to the details of implementation
+, including a "cookbook" of short tutorials.
+ Part III provides appendices and references.
+\end_layout
+
+\begin_layout Standard
+The style of this publication is based on the 
+\begin_inset LatexCommand \htmlurl[Apple Publications Style Guide]{<http://developer.apple.com/documentation/UserExperience/Conceptual/APStyleGuide/AppleStyleGuide2003.pdf>}
+
+\end_inset
+
+, as recommended by 
+\begin_inset LatexCommand \htmlurl[Python.org]{<http://www.python.org/>}
+
+\end_inset
+
+.
+ The documentation was produced using 
+\begin_inset LatexCommand \htmlurl[LyX]{<http://www.lyx.org/>}
+
+\end_inset
+
+ to facilitate the transformation of files from one format to another.
+ LyX is a document processor that encourages an approach to writing based
+ on the structure of your documents, not their appearance.
+ It is released under a Free Software / Open Source license.
+\end_layout
+
+\begin_layout Standard
+Errors and bug fixes in this manual should be directed to cig-mc at geodynamics.org.
+\end_layout
+
+\begin_layout Section*
+Who Will Use This Document
+\end_layout
+
+\begin_layout Standard
+This documentation is aimed at scientists who prefer to use prepackaged
+ and specialized analysis tools.
+ Users are likely to be experienced computational earth scientists and have
+ familiarity with basic scripting, software installation, and programming;
+ but are not likely to be professional programmers.
+ Of those, there are likely to be two classes of users: those who just run
+ models and those who modify the source code.
+ 
+\end_layout
+
+\begin_layout Standard
+The manual was written for the usage of CitComS.py on a variety of different
+ platforms.
+ CitComS has run on shared memory computers (Sun, Hewlett-Packard, SGI,
+ and IBM), commercial distributed memory machines (Intel and Cray/SGI),
+ and Beowulf implementations (including Beowulfs at the California Institute
+ of Technology's Center for Advanced Computing Research and Seismological
+ Laboratory, Sydney University, and the Geological Survey of Norway).
+ 
+\end_layout
+
+\begin_layout Section*
+Citation
+\end_layout
+
+\begin_layout Standard
+Computational Infrastructure for Geodynamics (CIG) is making this source
+ code available to you in hopes that the software will enhance your research
+ in geophysics.
+ The underlying C code for the finite element package and the Python bindings
+ for the framework were donated to CIG in July of 2005.
+ A number of individuals have contributed a significant portion of their
+ careers toward the development of CitComS.py and Pyre.
+ It is essential that you recognize these individuals in the normal scientific
+ practice by citing the appropriate peer reviewed papers and making appropriate
+ acknowledgements.
+ 
+\end_layout
+
+\begin_layout Standard
+The CitComS development team asks that you cite both Zhong, S., Zuber, M.
+ T., Moresi, L.
+ N.
+ and Gurnis, M.
+ The role of temperature-dependent viscosity and surface plates in spherical
+ shell models of mantle convection.
+ 
+\emph on
+J.
+ Geophys.
+ Res.
+ 
+\series bold
+\emph default
+105
+\series default
+, 11,063-11,082 (2000) and Tan, E., Thoutireddy, P., Choi, E., Gurnis, M., and
+ Aivazis, M., 2004, GeoFramework Part I: Coupling Models of Mantle Convection
+ with a Python Framework, in preparation, 
+\emph on
+Geochemistry, Geophysics, Geosystems
+\emph default
+ 2005.
+ The developers also request that in your oral presentations and in your
+ paper acknowledgements that you indicate your use of this code, the authors
+ of the code, and 
+\begin_inset LatexCommand \htmlurl[CIG]{<http://www.geodynamics.org/>}
+
+\end_inset
+
+.
+\end_layout
+
+\begin_layout Section*
+Support
+\end_layout
+
+\begin_layout Standard
+Pyre development is funded by the 
+\begin_inset LatexCommand \htmlurl[U.S. Dept. of Energy's]{<http://www.doe.gov/engine/content.do>}
+
+\end_inset
+
+ Advanced Simulation and Computing program and the 
+\begin_inset LatexCommand \htmlurl[National Science Foundation's]{<http://www.nsf.gov/>}
+
+\end_inset
+
+ Information Technology Research (ITR) program (grant #0205653).
+ Continued support of CitComS.py is made possible under NSF EAR-0406751.
+\end_layout
+
+\begin_layout Section*
+Conventions
+\end_layout
+
+\begin_layout Standard
+Throughout this documentation CitComS.py refers to the Pyre-compatible version
+ of CitComS unless specifically stated otherwise.
+ Any mention of "username" is meant to indicate the user, meaning you should
+ substitute your account name in its place.
+\end_layout
+
+\begin_layout Part
+Chapters
+\end_layout
+
+\begin_layout Chapter
+Introduction
+\end_layout
+
+\begin_layout Standard
+CitComS is a finite element code designed to solve thermal convection problems
+ relevant to earth's mantle.
+ Written in C, the code runs on a variety of parallel processing computers,
+ including shared and distributed memory platforms.
+ In an effort to increase the functionality of CitComS to include greater
+ control during simulations on large parallel systems, the software has
+ been reengineered from previous versions of CitComS to work with a Python-based
+ modeling framework called Pyre.
+ With Pyre, CitComS can be dynamically coupled with other CitComS simulations
+ or with other codes such as SNAC, which solves crustal and lithospheric
+ problems.
+ 
+\end_layout
+
+\begin_layout Section
+About CitComS
+\end_layout
+
+\begin_layout Standard
+CitComS is a finite element code written in C that solves for thermal convection
+ within a spherical shell.
+ 
+\family typewriter
+citcomsfull
+\family default
+ and 
+\family typewriter
+citcomsregional
+\family default
+ are modifications of CitComS which solve for problems within a full spherical
+ domain and a restricted domain of a full sphere, respectively.
+ Although the code is capable of solving many different kinds of convection
+ problems using the flexibility of finite elements, there are aspects of
+ 
+\family typewriter
+citcomsregional
+\family default
+ which make it well-suited for solving problems in which the plate tectonic
+ history of a region is incorporated.
+ CitComS.py allows easy use of either one of these two geometries by simply
+ changing command line options.
+\end_layout
+
+\begin_layout Standard
+The fundamental basis for the numerical solution of any time-dependent convectio
+n problem is the sequential solution of an equation of motion and an energy
+ equation.
+ Convection problems are initially valued with boundary conditions, including
+ all of the problems which are solved with CitComS.py.
+ The normal sequence of steps for the solution of convection problems start
+ with an initial temperature field.
+ First, the momentum equation is solved.
+ The solution of this equation gives us the velocity from which we then
+ solve the advection-diffusion equation, giving us a new temperature.
+ CitComS.py uses this interleaved strategy.
+ It is possible to run aduction backward in time so as to guess an initial
+ condition for a normal forward running initial and boundary value problem.
+ However, users should be aware that even specialists in mantle convection
+ modeling are just now starting to explore methods in this area and, as
+ such, this is an emerging area of research.
+ There are versions of CitCom which solve for these classes of forward and
+ backward problems.
+ Variable viscosity, including temperature-, pressure-, position-, composition-,
+ and stress-dependent viscosity are all possible, although they may not
+ be fully implemented in the current version.
+ 
+\end_layout
+
+\begin_layout Standard
+This code uses an iterative solution scheme to solve for the velocity and
+ pressure and as such, a converged solution cannot be guaranteed.
+ Currently, the code uses a conjugant gradient solver, although most of
+ the coding for full multi-grid is contained within the source code, only
+ the conjugate gradient solver has been implemented for use with an arbitrary
+ number of processors.
+\end_layout
+
+\begin_layout Section
+History
+\end_layout
+
+\begin_layout Standard
+CitCom (for 
+\series bold
+C
+\series default
+alifornia 
+\series bold
+I
+\series default
+nstitute of 
+\series bold
+T
+\series default
+echnology 
+\series bold
+Co
+\series default
+nvection in the 
+\series bold
+M
+\series default
+antle) was originally written in the early 1990's by Louis Moresi.
+ Although the code for three-dimensional problems was incorporated from
+ its inception, early versions of the softwareonly solved for time-dependent
+ convection problems within two-dimensional Cartesian domains.
+ Moresi's original code turned out to be incredibly modular and easily extensibl
+e.
+ Consequently, the fundamental finite element infrastructure which Louis
+ wrote is still in place and forms the basis for much of the code contained
+ in the present release.
+ 
+\end_layout
+
+\begin_layout Standard
+In the mid-1990's Moresi wrote versions of the code that solved the equations
+ within three-dimensional Cartesian domains.
+ Then Shijie Zhong successfully parallelized CitCom using message passing
+ routines on a limited release Intel supercomputer.
+ Zhong then created a spherical version of the code which he named CitComS.
+ Lijie Han then created a regional version of CitComS as well as an alternate
+ version of message passing for an arbitrarily large number of processors.
+ Clint Conrad created the first Beowulf implementations of the code, then
+ Conrad and Eh Tan re-coded the message passing of the fully spherical version
+ so that problems run on arbitrarily large numbers of processors could also
+ be solved.
+ A plethora of different versions of CitCom exist both on computers at the
+ California Institute of Technology and around the world.
+ 
+\end_layout
+
+\begin_layout Standard
+Consequently, by 2002, there were so many different versions of the code
+ that some rationalization was in order.
+ The software was migrated into a version control system and Eh Tan and
+ Eun-seo Choi created a version of the CitComS that generates either a fully
+ spherical or regional model, 
+\family typewriter
+citcomsfull
+\family default
+ and 
+\family typewriter
+citcomsregional
+\family default
+ respectively.
+ CitComS was released to the community through the 
+\begin_inset LatexCommand \htmlurl[Geoframework]{<http://www.geoframework.org>}
+
+\end_inset
+
+ website as version 1.0 and 1.1.
+\end_layout
+
+\begin_layout Standard
+At this time, in order to increase the functionality of CitComS, the developers
+ began to reengineer the code into an object-oriented environment specifically
+ so it could work with a Python-based modeling framework called Pyre.
+ This release of the software, now named CitComS.py, is essentially the product
+ of those reengineering efforts.
+ Eh Tan was the principal developer of CitComS.py, with considerable help
+ from Eun-seo Choi, Puru Thoutireddy, and Michael Aivazis.
+\end_layout
+
+\begin_layout Standard
+CitComS is one component of a larger collection of software encompassed
+ by the Geoframework, a collaborative project between the 
+\begin_inset LatexCommand \htmlurl[Center for Advanced Computing Research (CACR)]{<http://www.cacr.caltech.edu/>}
+
+\end_inset
+
+ and the 
+\begin_inset LatexCommand \htmlurl[Seismological Laboratory]{<http://www.seismolab.caltech.edu/>}
+
+\end_inset
+
+, both at Caltech, and the 
+\begin_inset LatexCommand \htmlurl[Victorian Partnership for Advanced Computing]{<http://www.vpac.org/>}
+
+\end_inset
+
+ in Australia.
+ The GeoFramework project has been developing a suite of tools to model
+ multi-scale deformation for Earth science problems.
+ This effort was motivated by the need to understand interactions between
+ the long-term evolution of plate tectonics and shorter term processes such
+ as the evolution of faults during and between earthquakes.
+ During 2005 and 2006 much of the remaining software developed by Geoframework
+ will be donated to CIG.
+\end_layout
+
+\begin_layout Standard
+The second major release of CitComS (2.0) incorporates the software framework
+ Pyre, free surface modeling methods, and stress boundary conditions around
+ the top and bottom surfaces.
+ In the summer of 2005, as part of the 2.0.1 release, the CIG replaced the
+ old build procedure with the GNU Build System.
+ A subsequent release, version 2.0.2, could compile and run on 64-bit systems.
+\end_layout
+
+\begin_layout Section
+About Pyre
+\end_layout
+
+\begin_layout Standard
+Pyre is an object-oriented environment capable of specifying and launching
+ numerical simulations on multiple platforms, including Beowulf class parallel
+ computers and grid computing systems.
+ Pyre allows the binding of multiple components such as solid and fluid
+ models used in Earth science simulations, and different meshers.
+ The Pyre framework enables the elegant setup, modification and launching
+ of massively parallel three-dimensional solver applications.
+ 
+\end_layout
+
+\begin_layout Standard
+Pyre is a framework, a combination of software and design philosophy that
+ promotes the reuse of code.
+ In their canonical software design book, 
+\emph on
+Design Patterns
+\emph default
+, Erich Gamma 
+\emph on
+et al
+\emph default
+ condense the concept of a framework concept down to, "When you use a framework,
+ you reuse the main body and write the code it calls." In the context of
+ frameworks and object-oriented programming, Pyre can be thought of as a
+ collection of classes and the way their instances interact.
+ Programming applications based on Pyre will look similar to those written
+ in any other object-oriented language.
+ The Pyre framework contains a subset of parts that make up the overall
+ framework.
+ Each of those parts is designed to solve a specific problem.
+ 
+\end_layout
+
+\begin_layout Standard
+The framework approach to computation offers many advantages.
+ It permits the exchange of codes and promotes the reuse of standardized
+ software while preserving efficiency.
+ Frameworks are also an efficient way to handle changes in computer architecture.
+ They present programmers and scientists with a unified and well-defined
+ task and allow for shared costs of the housekeeping aspects of software
+ development.
+ They provide greater institutional continuity to model development than
+ piecemeal approaches.
+\end_layout
+
+\begin_layout Standard
+The Pyre framework incorporates features aimed at enabling the scientific
+ non-expert to perform tasks easily without hindering the expert.
+ Target features for end users allow complete and intuitive simulation specifica
+tion, reasonable defaults, consistency checks of input, good diagnostics,
+ easy access to remote facilities, and status monitoring.
+ Target features for developers include easy access to user input, a shorter
+ development cycle, and good debugging support.
+ 
+\end_layout
+
+\begin_layout Section
+Pyre and CitComS.py
+\end_layout
+
+\begin_layout Standard
+Pyre provides a simulation framework that includes solver integration and
+ coupling, uniform access to facilities, and integrated visualization.
+ The framework offers a way to add new solvers to CitComS and to fine-tune
+ CitComS simulations.
+ Future versions of this documentation will cover coupled simulations generated
+ using via an "exchanger."
+\end_layout
+
+\begin_layout Standard
+\begin_inset Float figure
+wide false
+sideways false
+status open
+
+\begin_layout Description
+\begin_inset LatexCommand \label{Pyre-Architecture}
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+\begin_inset Graphics
+	filename graphics/c_fig1.eps
+	width 100col%
+	rotateOrigin center
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Caption
+Pyre\InsetSpace ~
+Architecture.
+ The integration framework is a set of cooperating abstract services.
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+Developers have created Pyre classes for CitComS to facilitate simulation
+ setup.
+ However, they are not independent classes in a strict sense.
+ They still share the same underlaying data structure and their functionality
+ is not divided clearly.
+ CitComS was not designed to be object-oriented and to make it so would
+ require significant investment of effort with little return.
+ However, the lack of object-oriented features does not hinder the coupling
+ of CitComS with other solvers.
+ 
+\end_layout
+
+\begin_layout Standard
+This version of CitComS "attaches" to Pyre via the use of bindings.
+ They are included with CitComS, eliminating the need for users to write
+ or alter them.
+\end_layout
+
+\begin_layout Section
+Governing Equations
+\end_layout
+
+\begin_layout Standard
+With CitComS, the mantle is treated as an incompressible viscous spherical
+ shell.
+ With these assumptions, thermal convection is governed by the equations
+ for conservation of mass, momentum, and energy:
+\end_layout
+
+\begin_layout Standard
+\align right
+\begin_inset Formula \begin{equation}
+u_{i,i}=0\label{eq:conservation of mass}\end{equation}
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+\align right
+\begin_inset Formula $ $
+\end_inset
+
+
+\begin_inset Formula \begin{equation}
+-P_{,i}+(\eta u_{i,j}+\eta u_{j,i})_{,j}+\delta\rho g\delta_{ir}=0\label{eq:conservation of momentum}\end{equation}
+
+\end_inset
+
+ 
+\end_layout
+
+\begin_layout Standard
+\align right
+\begin_inset Formula \begin{equation}
+T_{,t}+u_{i}T_{,i}=\kappa T_{,ii}+H\label{eq:conservation of energy}\end{equation}
+
+\end_inset
+
+ 
+\end_layout
+
+\begin_layout Standard
+\noindent
+where 
+\emph on
+u 
+\emph default
+is the velocity, 
+\emph on
+P
+\emph default
+ is the dynamic pressure, 
+\begin_inset Formula $\delta\rho$
+\end_inset
+
+ is the density anomaly, 
+\emph on
+g
+\emph default
+ is the gravitational acceleration, 
+\begin_inset Formula $\eta$
+\end_inset
+
+ is the viscosity, 
+\emph on
+T
+\emph default
+ is the temperature, 
+\begin_inset Formula $\kappa$
+\end_inset
+
+ is the thermal diffusivity, and 
+\emph on
+H
+\emph default
+ is the heat production rate.
+ 
+\begin_inset Formula $X_{,y}$
+\end_inset
+
+ represents the derivative of 
+\emph on
+X
+\emph default
+ with respect to 
+\emph on
+y
+\emph default
+, 
+\emph on
+i
+\emph default
+, and 
+\emph on
+j
+\emph default
+, which are spatial indices, and 
+\emph on
+t
+\emph default
+ is time.
+ Without phase transitions, the density anomalies are:
+\end_layout
+
+\begin_layout Standard
+\align right
+\begin_inset Formula \begin{equation}
+\delta\rho=-\alpha\rho_{0}(T-T_{0})\label{eq:density anomalies}\end{equation}
+
+\end_inset
+
+ 
+\end_layout
+
+\begin_layout Standard
+These equations lead to the following normalization in which primed quantities
+ are nondimensional:
+\end_layout
+
+\begin_layout Standard
+\align right
+\begin_inset Formula \begin{equation}
+x_{i}=R_{0}x_{i}^{'}\label{eq:5}\end{equation}
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+\begin_inset Formula \begin{equation}
+u_{i}=\frac{\kappa}{R_{0}}u_{i}^{'}\label{eq:6}\end{equation}
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+\align right
+\begin_inset Formula \begin{equation}
+T=\Delta TT'+T_{0}\label{eq:7}\end{equation}
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+\align right
+\begin_inset Formula \begin{equation}
+t=\frac{R_{0}^{2}}{\kappa}t^{'}\label{eq:8}\end{equation}
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+\align right
+\begin_inset Formula \begin{equation}
+\gamma=\frac{HR_{0}^{2}}{\kappa\Delta T}\label{eq:9}\end{equation}
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+\align right
+\begin_inset Formula \begin{equation}
+\eta=\eta_{0}\eta^{'}\label{eq:10}\end{equation}
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+\align right
+\begin_inset Formula \begin{equation}
+P=\frac{\eta_{0}\kappa}{R_{0}^{2}}P^{'}\label{eq:11}\end{equation}
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+\noindent
+where 
+\begin_inset Formula $R_{0}$
+\end_inset
+
+ is the radius of the earth, 
+\begin_inset Formula $\eta_{0}$
+\end_inset
+
+ is a reference viscosity, 
+\begin_inset Formula $\Delta T$
+\end_inset
+
+ is the superadiabatic temperature drop from the core-mantle boundary (CMB)
+ to the surface.
+ Dropping the primes, the equations become:
+\end_layout
+
+\begin_layout Standard
+\align right
+\begin_inset Formula \begin{equation}
+u_{i,i}=0\label{eq:conservation of mass}\end{equation}
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+\begin_inset Formula \begin{equation}
+-P_{,i}+(\eta u_{i,j}+\eta u_{j,i})_{,j}+RaT\delta_{ir}=0\label{eq:13}\end{equation}
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+\align right
+\begin_inset Formula \begin{equation}
+T_{,t}+u_{i}T_{,i}=T_{,ii}+\gamma\label{eq:14}\end{equation}
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+\noindent
+where 
+\emph on
+Ra
+\emph default
+, a Rayleigh number, is defined as:
+\end_layout
+
+\begin_layout Standard
+\align right
+\begin_inset Formula \begin{equation}
+Ra=\frac{\rho g\alpha\Delta TR_{0}^{3}}{\eta_{0}\kappa}\label{eq:Ra, a Rayleigh number}\end{equation}
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+If there is a phase change, 
+\begin_inset LatexCommand \ref{eq:13}
+
+\end_inset
+
+ is modified to:
+\end_layout
+
+\begin_layout Standard
+\align right
+\begin_inset Formula \begin{equation}
+-P_{,i}+(\eta u_{i,j}+\eta u_{j,i})_{,j}+(RaT+R_{b}\Gamma)\delta_{ir}=0\label{eq:16}\end{equation}
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+\align right
+\begin_inset Formula \begin{equation}
+\Gamma=\frac{1}{2}\left(1+\tanh\left(\frac{1-r-d_{ph}-s(T-T_{ph})}{w_{ph}}\right)\right)\label{eq:17}\end{equation}
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+\noindent
+where 
+\begin_inset Formula $d_{ph}$
+\end_inset
+
+ and 
+\begin_inset Formula $T_{ph}$
+\end_inset
+
+ are the ambient depth and temperature of a phase change,
+\emph on
+ s
+\emph default
+ is the Clapeyron slope of a phase change, and 
+\begin_inset Formula $w_{ph}$
+\end_inset
+
+ is the width of a phase transition.
+ The phase-change Rayleigh number, 
+\begin_inset Formula $R_{b}$
+\end_inset
+
+, is defined as:
+\end_layout
+
+\begin_layout Standard
+\align right
+\begin_inset Formula \begin{equation}
+R_{b}=\frac{\Delta\rho_{ph}gR_{0}^{3}}{\eta_{0}\kappa}\label{eq:Rb, the phase-change Rayleigh number}\end{equation}
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+\noindent
+where 
+\begin_inset Formula $\Delta\rho_{ph}$
+\end_inset
+
+ is the density jump across a phase change.
+\end_layout
+
+\begin_layout Standard
+
+\end_layout
+
+\begin_layout Section
+Numerical Methods
+\end_layout
+
+\begin_layout Standard
+The governing equations are solved with the finite element method, see 
+\begin_inset LatexCommand \cite{Hughes The Finite Element Method}
+
+\end_inset
+
+.
+ CitComS employs an Uzawa algorithm to solve the momentum equation coupled
+ with the incompressibility constraints 
+\begin_inset LatexCommand \cite{Moresi/Gurnis Contraints,Ramage/Wathen Iterative solution}
+
+\end_inset
+
+.
+ The energy equation is solved with a Petrov-Galerkin method 
+\begin_inset LatexCommand \cite{Brooks A.N.}
+
+\end_inset
+
+.
+ Brick elements are used, such as eight velocity nodes with trilinear shape
+ functions and one constant pressure node for each element.
+ The use of brick elements in 3-D (or rectangular elements in 2-D) is important
+ for accurately determining the pressure, such as dynamic topography, in
+ incompressible Stokes' flow 
+\begin_inset LatexCommand \cite{Hughes The Finite Element Method}
+
+\end_inset
+
+.
+ The discrete form of equations 
+\begin_inset LatexCommand \ref{eq:conservation of mass}
+
+\end_inset
+
+ and 
+\begin_inset LatexCommand \ref{eq:13}
+
+\end_inset
+
+ may be written in the following matrix form 
+\begin_inset LatexCommand \cite{Zhong et al The role of temperature}
+
+\end_inset
+
+:
+\end_layout
+
+\begin_layout Standard
+\align right
+\begin_inset Formula \begin{equation}
+\mathrm{\mathbf{B}^{\mathit{T}}\mathit{u=0}}\label{eq:19}\end{equation}
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+\align right
+\begin_inset Formula \begin{equation}
+\mathbf{A\mathit{u+}}\mathbf{B\mathit{p=f}}\label{eq:20}\end{equation}
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+\noindent
+where 
+\begin_inset Formula $\mathbf{A}$
+\end_inset
+
+ is the "stiffness" matrix, 
+\emph on
+u
+\emph default
+ is a vector of unknown velocities; 
+\begin_inset Formula $\mathbf{B}$
+\end_inset
+
+ is the discrete gradient operator, 
+\emph on
+p
+\emph default
+ is a vector of unknown pressures, and 
+\emph on
+f 
+\emph default
+is a vector composed of the body and boundary forces acting on the fluid.
+ The individual entries of 
+\begin_inset Formula $\mathbf{A}$
+\end_inset
+
+, 
+\begin_inset Formula $\mathbf{B}$
+\end_inset
+
+, and 
+\emph on
+f
+\emph default
+ are obtained using a standard finite element formulation, see 
+\begin_inset LatexCommand \cite{Zhong et al The role of temperature}
+
+\end_inset
+
+ for the explicit entries.
+ Equation 
+\begin_inset LatexCommand \ref{eq:20}
+
+\end_inset
+
+ can be transformed by premultiplying by 
+\begin_inset Formula $\mathrm{\mathbf{B}^{\mathit{T}}\mathit{\mathbf{A}^{\mathbf{\mathit{-1}}}}}$
+\end_inset
+
+ and using equation 
+\begin_inset LatexCommand \ref{eq:19}
+
+\end_inset
+
+ to eliminate the velocity unknowns:
+\end_layout
+
+\begin_layout Standard
+\align right
+\begin_inset Formula \begin{equation}
+\mathbf{B}^{\mathit{T}}\mathit{\mathbf{A}^{\mathbf{\mathit{-1}}}\mathbf{B}\mathit{p=\mathbf{B^{\mathit{T}}A^{\mathit{-1}}\mathit{f}}}}\label{eq:21}\end{equation}
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+This equation is solved using the Uzawa algorithm, an established method
+ for solving the minimization of a dual function 
+\begin_inset LatexCommand \cite{Cahouet/Chabard Some fast 3D}
+
+\end_inset
+
+, which simultaneously yields the velocity field.
+ A conjugate gradient scheme for this iteration is described by 
+\begin_inset LatexCommand \cite{Ramage/Wathen Iterative solution,Atanga/Silvester Iterative methods}
+
+\end_inset
+
+, and forms the basis for the technique used in CitComS.
+\end_layout
+
+\begin_layout Chapter
+Installation and Getting Help
+\end_layout
+
+\begin_layout Section
+Introduction
+\end_layout
+
+\begin_layout Standard
+To install CitComS.py, you will follow the procedure that is commonly used
+ with other open source software packages.
+ First, you will download the source package (in the form of a compressed
+ 'tar' file) from the 
+\begin_inset LatexCommand \htmlurl[Geodynamics website]{<http://www.geodynamics.org>}
+
+\end_inset
+
+.
+ After unpacking the source, you will run a prepackaged shell script to
+ configure CitComS for your system.
+ Then you will use the 'make' utility to build CitComS from source, and
+ finally install the CitComS programs and Python modules.
+ 
+\end_layout
+
+\begin_layout Standard
+Advanced users and software developers may be interested in downloading
+ the latest CitComS source code directly from the CIG source code repository,
+ instead of using the prepared source package.
+ See the Software Repository (LINK) section later in this chapter.
+ CitComS.py has been tested on Linux, Mac OS X, and several NSF TeraGrid
+ platforms.
+ 
+\end_layout
+
+\begin_layout Section
+Getting Help
+\end_layout
+
+\begin_layout Standard
+For help, send e-mail to the 
+\begin_inset LatexCommand \url[CIG Mantle Convection Mailing List]{<cig-mc at geodynamics.org>}
+
+\end_inset
+
+.
+ You can subscribe to the Mailing List and view archived discussion at the
+ 
+\begin_inset LatexCommand \htmlurl[Geodynamics website]{<http://www.geodynamics.org>}
+
+\end_inset
+
+.
+\end_layout
+
+\begin_layout Section
+System Requirements
+\end_layout
+
+\begin_layout Standard
+CitComS.py requires the following:
+\end_layout
+
+\begin_layout Itemize
+Python 2.3 or greater
+\end_layout
+
+\begin_layout Itemize
+An MPI library which implements version 1 of the MPI standard (If you are
+ using MPICH, MPICH version 1.2.3 or later is required.)
+\end_layout
+
+\begin_layout Itemize
+A modern C++ compiler
+\end_layout
+
+\begin_layout Itemize
+A C compiler
+\end_layout
+
+\begin_layout Standard
+Note: Users familiar with older versions of CitComS may prefer to install
+ only the legacy CitComS tools, CitcomSFull and CitcomSRegional, and forgo
+ use of the Pyre framework.
+ Installing the legacy tools requires simply:
+\end_layout
+
+\begin_layout Itemize
+An MPI library
+\end_layout
+
+\begin_layout Itemize
+A C compiler
+\end_layout
+
+\begin_layout Standard
+For more information, see the subsection 
+\begin_inset LatexCommand \ref{sec:Installing-without-Pyre}
+
+\end_inset
+
+ on page 
+\begin_inset LatexCommand \pageref{sec:Installing-without-Pyre}
+
+\end_inset
+
+.
+\end_layout
+
+\begin_layout Standard
+You can download Python from the 
+\begin_inset LatexCommand \htmlurl[Python]{<http://www.python.org/>}
+
+\end_inset
+
+ website.
+ If your system is running a recent release of Linux or Mac OS X, chances
+ are you already have a suitable Python interpreter installed.
+ To check, type the 'python' command:
+\end_layout
+
+\begin_layout LyX-Code
+$ python -V
+\end_layout
+
+\begin_layout LyX-Code
+Python 2.3.4
+\end_layout
+
+\begin_layout Standard
+MPICH is a freely available, portable implementation of MPI.
+ For more information, visit the 
+\begin_inset LatexCommand \htmlurl[MPICH home page]{<http://www-unix.mcs.anl.gov/mpi/mpich/>}
+
+\end_inset
+
+.
+ 
+\end_layout
+
+\begin_layout Standard
+Note for Mac OS X Users: You will need Xcode, which is freely available
+ from 
+\begin_inset LatexCommand \htmlurl[Apple]{<http://developer.apple.com/>}
+
+\end_inset
+
+.
+ Instead of using MPICH, you will probably want to use 
+\begin_inset LatexCommand \htmlurl[LAM/MPI]{<http://www.lam-mpi.org/>}
+
+\end_inset
+
+.
+ LAM/MPI is available as a Fink package; if you have 
+\begin_inset LatexCommand \htmlurl[Fink]{<http://fink.sourceforge.net/>}
+
+\end_inset
+
+ installed, simply enter the following command from a Terminal window to
+ install LAM/MPI:
+\end_layout
+
+\begin_layout LyX-Code
+$ fink install lammpi lammpi-dev
+\end_layout
+
+\begin_layout Section
+Downloading and Unpacking Source
+\end_layout
+
+\begin_layout Standard
+Download CitComS.py from the 
+\begin_inset LatexCommand \htmlurl[Geodynamics website]{<http://www.geodynamics.org/>}
+
+\end_inset
+
+.
+ Click the "software" tab at the top of the page.
+ Then click "Software Packages." Once you click the CitComS link, you will
+ be led through a simple registration process.
+ After you have downloaded the source archive, unpack it using the 
+\family typewriter
+tar
+\family default
+ command:
+\end_layout
+
+\begin_layout LyX-Code
+$ tar xzf CitcomS-2.0.1.tar.gz
+\end_layout
+
+\begin_layout Standard
+If you don't have GNU Tar, try the following command instead: 
+\end_layout
+
+\begin_layout LyX-Code
+$ gunzip -c CitcomS-2.0.1.tar.gz | tar xf -
+\end_layout
+
+\begin_layout Section
+Installation Procedure
+\end_layout
+
+\begin_layout Standard
+After unpacking the source, follow the following procedure to install CitComS:
+\end_layout
+
+\begin_layout Enumerate
+'cd' to the directory containing the CitComS source and type '.
+\family typewriter
+/configure'
+\family default
+ to configure the package for your system
+\newline
+
+\newline
+
+\family typewriter
+$ cd CitcomS-2.0.1
+\family default
+
+\newline
+
+\family typewriter
+$ ./configure
+\end_layout
+
+\begin_layout Enumerate
+Type '
+\family typewriter
+make
+\family default
+' to build the package.
+\family typewriter
+
+\newline
+
+\newline
+$ make
+\end_layout
+
+\begin_layout Enumerate
+Become '
+\family typewriter
+root
+\family default
+' and type '
+\family typewriter
+make install
+\family default
+' to install CitcomS.
+\newline
+
+\newline
+
+\family typewriter
+$ su
+\newline
+Password:
+\newline
+# make install
+\end_layout
+
+\begin_layout Standard
+To install as an ordinary user instead of '
+\family typewriter
+root
+\family default
+', give 
+\family typewriter
+'configure
+\family default
+' the '
+\family typewriter
+--prefix
+\family default
+' option, specifying a directory to which you have write access:
+\end_layout
+
+\begin_layout LyX-Code
+$ cd CitcomS-2.0.1
+\end_layout
+
+\begin_layout LyX-Code
+$ ./configure --prefix=$HOME/cig
+\end_layout
+
+\begin_layout LyX-Code
+$ make
+\end_layout
+
+\begin_layout LyX-Code
+$ make install
+\end_layout
+
+\begin_layout Standard
+For more details about 
+\family typewriter
+configure
+\family default
+, see the section "Configuration", below.
+\end_layout
+
+\begin_layout Quote
+
+\series bold
+NOTE:
+\series default
+ If you install as an ordinary user using 
+\family typewriter
+'--prefix=PREFIX'
+\family default
+ be mindful of the fact that you may have to set various environment variables
+ in order for CitComS to function properly under the given 
+\family typewriter
+PREFIX
+\family default
+.
+ First, you will want to add 
+\family typewriter
+PREFIX/bin
+\family default
+ to your 
+\family typewriter
+PATH.
+
+\family default
+ You may need or want to add 
+\family typewriter
+PREFIX/lib/python2.3/site-packages
+\family default
+ to your 
+\family typewriter
+PYTHONPATH
+\family default
+.
+ Finally, on some obscure Unix systems, you may need to add 
+\family typewriter
+PREFIX/lib
+\family default
+ to your 
+\family typewriter
+LD_LIBRARY_PATH
+\family default
+ (or equivalent).
+ 
+\end_layout
+
+\begin_layout Section
+Configuration
+\end_layout
+
+\begin_layout Standard
+The 'configure' script checks for various system features.
+ As it runs, it prints messages informing you of which features it is checking
+ for.
+ Upon successful completion, it generates a 
+\family typewriter
+Makefile
+\family default
+ in each source directory of the package.
+ It also generates one or more 
+\family typewriter
+portinfo
+\family default
+ header files, which contain system-dependent definitions (
+\family typewriter
+portinfo
+\family default
+ is equivalent to 
+\family typewriter
+config.h
+\family default
+ in other open-source software packages).
+ 
+\end_layout
+
+\begin_layout Standard
+The '
+\family typewriter
+configure
+\family default
+' script will attempt to guess the correct values of various installation
+ parameters.
+ In the event that the default values used by '
+\family typewriter
+configure
+\family default
+' are incorrect for your system, or '
+\family typewriter
+configure
+\family default
+' is unable to guess the value a certain parameter, you may have to specify
+ the correct value by hand.
+ 
+\end_layout
+
+\begin_layout Section
+Configure Usage
+\end_layout
+
+\begin_layout Standard
+For a detailed list of 'configure' variables and options, give '
+\family typewriter
+configure
+\family default
+' the '
+\family typewriter
+--help
+\family default
+' option:
+\end_layout
+
+\begin_layout LyX-Code
+$ ./configure --help
+\end_layout
+
+\begin_layout Standard
+The following is a summary of the variables and options that are important
+ when installing CitComS.
+ 
+\end_layout
+
+\begin_layout Section
+Environment Variables
+\end_layout
+
+\begin_layout Standard
+Environment variables may be specified as arguments to 'configure'; e.g.,
+\end_layout
+
+\begin_layout LyX-Code
+$ ./configure CXX=icpc # compile C++ using the Intel compiler
+\end_layout
+
+\begin_layout Standard
+\begin_inset Tabular
+<lyxtabular version="3" rows="5" columns="2">
+<features>
+<column alignment="left" valignment="top" leftline="true" width="1in">
+<column alignment="left" valignment="top" leftline="true" rightline="true" width="3.5in">
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+Variable
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+Description
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+PYTHON
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+Python interpreter.
+ This is useful if you have Python installed in a non-standard location;
+ e.g.,
+\end_layout
+
+\begin_layout Standard
+
+\end_layout
+
+\begin_layout Standard
+
+\family typewriter
+\InsetSpace ~
+\InsetSpace ~
+./configure 
+\backslash
+
+\end_layout
+
+\begin_layout Standard
+
+\family typewriter
+\InsetSpace ~
+\InsetSpace ~
+\InsetSpace ~
+\InsetSpace ~
+\InsetSpace ~
+\InsetSpace ~
+PYTHON=/opt/python2.3/bin/python
+\family default
+ 
+\end_layout
+
+\begin_layout Standard
+
+\end_layout
+
+\begin_layout Standard
+By default, '
+\family typewriter
+configure
+\family default
+' will search for a suitable Python interpreter using your 
+\family typewriter
+PATH
+\family default
+ environment variable.
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+CC
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+C compiler command
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+CXX
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+C++ compiler command
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+MPICC
+\end_layout
+
+\begin_layout Standard
+MPICXX
+\end_layout
+
+\begin_layout Standard
+MPIINCLUDES
+\end_layout
+
+\begin_layout Standard
+MILIBS
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+These variables collectively specify how to build MPI programs.
+ The variables MPICC and MPICXX specify compiler commands; MPIINCLUDES specifies
+ preprocessor flags, and MPILIBS specifies linker flags.
+ See 
+\begin_inset LatexCommand \ref{sec:MPI-Configuration}
+
+\end_inset
+
+ for details and examples.
+\end_layout
+
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Section
+\begin_inset LatexCommand \label{sec:MPI-Configuration}
+
+\end_inset
+
+MPI Configuration
+\end_layout
+
+\begin_layout Standard
+By default, '
+\family typewriter
+configure
+\family default
+' will search for MPI wrappers (such as
+\family typewriter
+ mpicxx/mpic++
+\family default
+ and 
+\family typewriter
+mpicc
+\family default
+) using your PATH environment variable.
+ You may specify MPI wrappers manually using the variables MPICC and MPICXX.
+ If found, the wrappers will be used to compile MPI-related source; and
+ CC and CXX will default to underlying C/C++ compiler commands (e.g., CC will
+ default to the result of '
+\family typewriter
+mpicc -compile_info
+\family default
+' if you are using MPICH).
+ You may also set CC and CXX manually.
+ The commands specified by CXX and CC are used to compile ordinary C/C++
+ source, and for linking shared libraries.
+\end_layout
+
+\begin_layout Subsection
+Manually specifying MPI wrappers
+\end_layout
+
+\begin_layout LyX-Code
+$ ./configure 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+MPICC=/opt/mpich-1.2.6/bin/mpicc 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+MPICXX=/opt/mpich-1.2.6/bin/mpicxx
+\end_layout
+
+\begin_layout Standard
+If MPI wrappers are not found, '
+\family typewriter
+configure
+\family default
+' will set MPICC and MPICXX to CC and CXX, respectively (i.e., the same commands
+ used to build ordinary C/C++ source).
+ Then, configure will attempt to find 
+\family typewriter
+mpi.h
+\family default
+ and an MPI library in the standard locations (e.g., 
+\family typewriter
+/usr/include
+\family default
+ and 
+\family typewriter
+/usr/lib
+\family default
+) using the ordinary compiler.
+ In this scenario, if your MPI header files and libraries are installed
+ in a non-standard location, you must specify MPIINCLUDES and MPILIBS, so
+ that the compiler can find the MPI header files and libraries.
+\end_layout
+
+\begin_layout Subsection
+Manually specifying MPI 'include' and 'lib' directories
+\end_layout
+
+\begin_layout LyX-Code
+$ ./configure 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+MPIINCLUDES="-I/opt/mpich-1.2.6/include" 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+MPILIBS="-L/opt/mpich-1.2.6/lib -lmpich"
+\end_layout
+
+\begin_layout Subsection
+Manually specifying MPI 'include' and 'lib' directories, and an alternative
+ compiler
+\end_layout
+
+\begin_layout LyX-Code
+$ ./configure 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+CC=icc 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+CXX=icpc 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+MPIINCLUDES="-I/opt/mpich-1.2.6/include" 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+MPILIBS="-L/opt/mpich-1.2.6/lib -lmpich"
+\end_layout
+
+\begin_layout Standard
+Some words of caution when specifying the MPI configuration:
+\end_layout
+
+\begin_layout Itemize
+Specifying MPI commands and flags in general-purpose '
+\family typewriter
+configure
+\family default
+' variables (such as CC, CXX, CPPFLAGS, and LDFLAGS) may work on some systems,
+ but is not recommended unless you happen to have a shared version of the
+ MPI library installed on your system (
+\family typewriter
+libmpich.so
+\family default
+ or 
+\family typewriter
+libmpi.so
+\family default
+).
+ 
+\end_layout
+
+\begin_layout Itemize
+If you explicitly specify both MPICXX and CXX, CXX will be used to compile
+ all C++ source; MPICXX is invoked merely to determine the correct values
+ for MPIINCLUDES and MPILIBS (if necessary).
+ Likewise, if you explicitly specify both MPICC and CC, CC will be used
+ to compile all C source; MPICC will only be used to determine the MPI flags.
+\end_layout
+
+\begin_layout Itemize
+Configuring CitComS with a different C++ compiler than was used to configure
+ your MPI library may cause link errors.
+ However, the 'configure' script attempts to detect this scenario and automatica
+lly work-around the problem for you.
+\end_layout
+
+\begin_layout Section
+Batch System Configuration
+\end_layout
+
+\begin_layout Standard
+If you are installing CitComS on a cluster with a batch system, you can
+ configure CitComS such that the Pyre-based commands 
+\family typewriter
+citcomsregional.sh
+\family default
+ and 
+\family typewriter
+citcomsfull.sh
+\family default
+ automatically submit jobs to the batch queue.
+ CitComS contains support for the LSF, PBS, and Globus batch systems.
+\end_layout
+
+\begin_layout Standard
+The 
+\family typewriter
+configure
+\family default
+ script searches for the 
+\family typewriter
+bsub
+\family default
+, 
+\family typewriter
+qsub
+\family default
+, and 
+\family typewriter
+globusrun
+\family default
+ batch commands.
+ If one of these is found, CitComS is configured to use the corresponding
+ batch system (LSF, PBS, and Globus, respectively) instead of launching
+ MPI jobs directly using 
+\family typewriter
+mpirun
+\family default
+.
+ Run 
+\family typewriter
+./configure --help
+\family default
+ for information on how to configure the batch system parameters manually.
+\end_layout
+
+\begin_layout Standard
+The proper commands to use in a batch script varies from one cluster to
+ the next.
+ On some systems, 
+\family typewriter
+mpirun
+\family default
+ is invoked directly from the batch script.
+ On others, a special wrapper is used instead.
+ Therefore, after successfully installing CitComS, you must edit the following
+ XML configuration file: 
+\end_layout
+
+\begin_layout LyX-Code
+PREFIX/etc/CitcomS/CitcomS.pml
+\end_layout
+
+\begin_layout Standard
+where PREFIX is the directory under which you installed CitcomS (default
+ 
+\family typewriter
+/usr/local
+\family default
+).
+ Edit the defaults as appropriate for your system.
+ For example, if you are using LSF, first verify that CitComS is configured
+ to use LSF: 
+\end_layout
+
+\begin_layout LyX-Code
+<property name="launcher">lsf</property>
+\end_layout
+
+\begin_layout Standard
+Next, edit the LSF section: 
+\end_layout
+
+\begin_layout LyX-Code
+<component name="lsf"> 
+\end_layout
+
+\begin_layout LyX-Code
+      <property name="command">mpijob mpirun</property>
+\end_layout
+
+\begin_layout LyX-Code
+      <property name="batch-command">bsub</property> 
+\end_layout
+
+\begin_layout LyX-Code
+</component>
+\end_layout
+
+\begin_layout Standard
+In particular, set the 
+\family typewriter
+command
+\family default
+ property to the correct command for launching MPI jobs from a batch script
+ on your system.
+ For example:
+\end_layout
+
+\begin_layout LyX-Code
+<property name="command">pam -g 1 gmmpirun_wrapper</property>
+\end_layout
+
+\begin_layout Standard
+You may find the 
+\family typewriter
+--launcher.dry
+\family default
+ option useful while debugging the batch system configuration: 
+\end_layout
+
+\begin_layout LyX-Code
+citcomsregional.sh --launcher.dry
+\end_layout
+
+\begin_layout Standard
+This option will cause CitcomS to perform a "dry run," dumping the batch
+ script to the console, instead of actually submitting it for execution.
+\end_layout
+
+\begin_layout Section
+\begin_inset LatexCommand \label{sec:Installing-without-Pyre}
+
+\end_inset
+
+Installing without Pyre
+\end_layout
+
+\begin_layout Standard
+To build just the CitComS tools (or "drivers") from the legacy C code, give
+ 
+\family typewriter
+configure
+\family default
+ the 
+\family typewriter
+--without-pyre
+\family default
+ option:
+\end_layout
+
+\begin_layout LyX-Code
+$ ./configure --without-pyre
+\end_layout
+
+\begin_layout Standard
+The only system requirements for this configuration are an MPI library and
+ a decent C compiler.
+ The final 
+\family typewriter
+make install
+\family default
+ step will install two command-line tools: 
+\family typewriter
+CitcomSFull
+\family default
+ and 
+\family typewriter
+CitcomSRegional
+\family default
+.
+\end_layout
+
+\begin_layout Section
+\begin_inset LatexCommand \label{sec:Software-Repository}
+
+\end_inset
+
+Software Repository
+\end_layout
+
+\begin_layout Standard
+The CitcomS source code is available via a Subversion server at geodynamics.org.
+ This allows users to view the revision history of the code, and check out
+ the most recent development version of the software.
+\end_layout
+
+\begin_layout Quote
+
+\series bold
+NOTE: 
+\series default
+If you are content with the prepared source package, feel free to skip this
+ section.
+\end_layout
+
+\begin_layout Subsection
+Tools You Will Need
+\end_layout
+
+\begin_layout Standard
+In addition to the usual system requirements, you will need a handful of
+ additional development tools installed in order to work with the source
+ from the CIG software repository.
+\end_layout
+
+\begin_layout Standard
+First you must have a Subversion client installed.
+ To check, type 
+\family typewriter
+svn
+\family default
+; it should return a usage message.
+ For more information on Subversion, visit the 
+\begin_inset LatexCommand \htmlurl[Subversion website]{<http://subversion.tigris.org/>}
+
+\end_inset
+
+.
+\end_layout
+
+\begin_layout LyX-Code
+$ svn
+\end_layout
+
+\begin_layout LyX-Code
+Type 'svn help' for usage.
+\end_layout
+
+\begin_layout Standard
+Second, you must have the GNU tools Autoconf, Automake, and Libtool installed.
+ To check, enter the following commands:
+\end_layout
+
+\begin_layout LyX-Code
+$ autoconf --version
+\end_layout
+
+\begin_layout LyX-Code
+$ automake --version
+\end_layout
+
+\begin_layout LyX-Code
+$ libtoolize --version
+\end_layout
+
+\begin_layout Standard
+For more information about these GNU tools, see the 
+\begin_inset LatexCommand \htmlurl[GNU website]{<http://www.gnu.org/software/>}
+
+\end_inset
+
+.
+ The CitComS v2.0.1 source package was created with Autoconf 2.59, Automake
+ 1.9.2, and Libtool 1.5.6.
+\end_layout
+
+\begin_layout Subsection
+Download Source from Subversion
+\end_layout
+
+\begin_layout Standard
+To check out the latest version of the software, use the 'svn checkout'
+ command:
+\end_layout
+
+\begin_layout LyX-Code
+$ svn checkout svn://geodynamics.org/cig/mc/3D/CitcomS/trunk CitcomS
+\end_layout
+
+\begin_layout Standard
+Like the release version, the development version depends upon Pythia v0.8.
+ In addition, the development version also depends upon a package called
+ Exchanger.
+ Unless you plan to build only the legacy CitComS tools (see 
+\begin_inset LatexCommand \ref{sec:Installing-without-Pyre}
+
+\end_inset
+
+ earlier in this chapter), you will need to check out the Pythia and Exchanger
+ packages as well.
+ Like CitComS, Exchanger is available from the geodynamics.org server.
+ For convenience, Pythia is also available from geodynamics.org.
+ To check out Pythia and Exchanger, use the following commands:
+\end_layout
+
+\begin_layout LyX-Code
+$ svn checkout svn://geodynamics.org/cig/vendor/pythia/v0.8 pythia-0.8 
+\end_layout
+
+\begin_layout LyX-Code
+$ svn checkout svn://geodynamics.org/cig/cs/Exchanger/trunk Exchanger
+\end_layout
+
+\begin_layout Subsection
+Generating the GNU Build System
+\end_layout
+
+\begin_layout Standard
+You working directory should now contain three subdirectories:
+\end_layout
+
+\begin_layout LyX-Code
+$ ls
+\end_layout
+
+\begin_layout LyX-Code
+CitcomS Exchanger pythia-0.8
+\end_layout
+
+\begin_layout Standard
+Each of the three packages must be configured and built separately, in the
+ following order:
+\end_layout
+
+\begin_layout Enumerate
+pythia-0.8
+\end_layout
+
+\begin_layout Enumerate
+Exchanger
+\end_layout
+
+\begin_layout Enumerate
+CitcomS
+\end_layout
+
+\begin_layout Standard
+But before you can run 'configure' or 'make', you must generate the necessary
+ files using the GNU tools.
+ The easiest way to do this is to run 'autoreconf -i':
+\end_layout
+
+\begin_layout LyX-Code
+$ cd pythia-0.8
+\end_layout
+
+\begin_layout LyX-Code
+$ autoreconf -i
+\end_layout
+
+\begin_layout LyX-Code
+$ ./configure --prefix=$HOME/cig
+\end_layout
+
+\begin_layout LyX-Code
+$ make
+\end_layout
+
+\begin_layout LyX-Code
+$ make install
+\end_layout
+
+\begin_layout Standard
+Then, repeat this process for Exchanger and CitcomS:
+\end_layout
+
+\begin_layout LyX-Code
+$ cd ../Exchanger
+\end_layout
+
+\begin_layout LyX-Code
+$ autoreconf -i
+\end_layout
+
+\begin_layout LyX-Code
+$ ./configure --prefix=$HOME/cig
+\end_layout
+
+\begin_layout LyX-Code
+$ make
+\end_layout
+
+\begin_layout LyX-Code
+$ make install
+\end_layout
+
+\begin_layout LyX-Code
+$ cd ../CitcomS
+\end_layout
+
+\begin_layout LyX-Code
+$ autoreconf -i
+\end_layout
+
+\begin_layout LyX-Code
+$ ./configure --prefix=$HOME/cig
+\end_layout
+
+\begin_layout LyX-Code
+$ make
+\end_layout
+
+\begin_layout LyX-Code
+$ make install
+\end_layout
+
+\begin_layout Standard
+The 'autoreconf' tool runs Autoconf to generate the 'configure' script from
+ 'configure.ac'.
+ It also runs Automake to generate 'Makefile.in' from 'Makefile.am' in each
+ source directory.
+\end_layout
+
+\begin_layout Chapter
+Running CitComS.py
+\end_layout
+
+\begin_layout Standard
+
+\end_layout
+
+\begin_layout Section
+Using CitComS.py
+\end_layout
+
+\begin_layout Standard
+CitComS.py usage is similar to that of previous versions of CitComS.
+ Installed under the 
+\family typewriter
+bin
+\family default
+ directory (default 
+\family typewriter
+/usr/local/bin
+\family default
+), 
+\family typewriter
+citcomsregional.sh
+\family default
+ is used for regional models and 
+\family typewriter
+citcomsfull.sh
+\family default
+ for full spherical models.
+ 
+\family typewriter
+citcomsregional.sh
+\family default
+ can be executed without any command line options and will run with default
+ parameters.
+ citcomsfull.sh requires at least 12 processors to run.
+ To do so, you must specify the 
+\family typewriter
+launcher
+\family default
+ parameters, which are called "facilities."
+\end_layout
+
+\begin_layout Standard
+Since you will likely want to specify the parameters of your CitComS runs,
+ you will need to alter both computational details (such as the number of
+ time steps) and controlling parameters specific to your problem (such as
+ the Rayleigh number).
+ Most of the properties you will set using CitComS.py have identical names
+ as the parameters for the old CitComS.
+ 
+\end_layout
+
+\begin_layout Section
+Changing Parameters
+\end_layout
+
+\begin_layout Standard
+Pyre has the following syntax to change parameters from their default values.
+ To change the value of a property of a component, use:
+\end_layout
+
+\begin_layout LyX-Code
+--[component].[property]=[value]
+\end_layout
+
+\begin_layout Standard
+Each component is attached to a facility, so the option above can also be
+ written: as: 
+\end_layout
+
+\begin_layout LyX-Code
+--[facility].[property]=[value]
+\end_layout
+
+\begin_layout Standard
+A different component can be attached to a facility by:
+\end_layout
+
+\begin_layout LyX-Code
+--[facility]=[new_component] 
+\end_layout
+
+\begin_layout Section
+Coordinate System and Mesh
+\end_layout
+
+\begin_layout Standard
+In general, CitComS uses meshes that are regular, although considerable
+ flexibility exists for grid refinement in the regional models.
+ In regional meshes, 
+\emph on
+theta
+\emph default
+ is the colatitude measured from the north pole, 
+\emph on
+fi
+\emph default
+ is the east longitude, and z is the radius.
+ 
+\emph on
+theta
+\emph default
+ and 
+\emph on
+fi
+\emph default
+ are in units of radians.
+ Figure 3.1 shows the organization of the mesh in a regional problem.
+ 
+\end_layout
+
+\begin_layout Standard
+\begin_inset Float figure
+wide false
+sideways false
+status open
+
+\begin_layout Description
+\begin_inset Graphics
+	filename graphics/c_fig3.jpg
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Caption
+Global\InsetSpace ~
+Node\InsetSpace ~
+Numbering.
+ Global node numbering starts at the base of arrow A (theta
+\size scriptsize
+min
+\size default
+, fi
+\size scriptsize
+min
+\size default
+, r
+\size scriptsize
+min
+\size default
+), and advances from 1 at the base to 
+\emph on
+nz
+\emph default
+ at the tip.
+ Upon reaching the tip, numbering continues from the base of arrow B (
+\emph on
+nz
+\emph default
++1) to its tip (2 
+\emph on
+nz
+\emph default
+), and so on for all nodes on the plane fi = fi
+\size scriptsize
+min
+\size default
+.
+ (left) After completing each theta radius plane, the fi index is incremented
+ and numbering commences from (theta
+\size scriptsize
+min
+\size default
+, r
+\size scriptsize
+min
+\size default
+) as on the left.
+ (right)
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Section
+A Simple CitComS Test
+\end_layout
+
+\begin_layout Standard
+CitComS runs similarly in full spherical or regional modes.
+ For the purpose of this example, you will perform a test run of the regional
+ version.
+ Instructions for using the full version can be found in example in Cookbook
+ 1 in a subsequent chapter.
+\end_layout
+
+\begin_layout Standard
+Execute the following on the command line:
+\end_layout
+
+\begin_layout Paragraph
+\begin_inset LatexCommand \label{sub:Uniprocessor-CitComS-from}
+
+\end_inset
+
+Example: Uniprocessor CitComS from the Command Line
+\end_layout
+
+\begin_layout LyX-Code
+citcomsregional.sh --steps=10 
+\end_layout
+
+\begin_layout LyX-Code
+--controller.monitoringFrequency=5 --solver.datafile=example 
+\end_layout
+
+\begin_layout LyX-Code
+--solver.mesher.nodex=17 --solver.mesher.nodey=17
+\end_layout
+
+\begin_layout Standard
+This runs a default convection problem in a regional domain for 10 times
+ steps and with a mesh of 17 x 17 x 9 nodal points.
+ See the next chapter for steps to immediately visualize your results with
+ OpenDX.
+\end_layout
+
+\begin_layout Section
+Multiprocessor Example
+\end_layout
+
+\begin_layout Standard
+On input, CitComS needs numerous parameters specified.
+ (See APPENDIX for full list.) Depending on those input parameters, CitComS
+ could also require numerous input files, such as velocity boundary conditions
+ which could be used for time dependent, plate tectonic problems.
+ Finally, CitComS will potentially output a large number of files which
+ will be spread throughout the file systems contained in the individual
+ nodes of your Beowulf.
+ This means that you will have to organize your directories carefully when
+ running CitComS so that you can find your way through these files as well
+ as use a post-processing program contained with this distribution.
+ (In the example that follows, these output files would be placed in 
+\family typewriter
+/scratch/username
+\family default
+ with a filename prefix 
+\family typewriter
+example1
+\family default
+ on each individual node.)
+\end_layout
+
+\begin_layout Standard
+It is possible to input the parameters relevant to your test run from the
+ command line:
+\end_layout
+
+\begin_layout Paragraph
+Example: Multiprocessor CitComS from the Command Line
+\end_layout
+
+\begin_layout LyX-Code
+$ citcomsregional.sh --launcher.nodes=4 
+\end_layout
+
+\begin_layout LyX-Code
+--launcher.nodegen="n%03d" --launcher.nodelist=[101-102] 
+\end_layout
+
+\begin_layout LyX-Code
+--solver.mesher.nprocx=2 --solver.mesher.nprocy=2 
+\end_layout
+
+\begin_layout LyX-Code
+--solver.datafile="/scratch/username/example1"
+\end_layout
+
+\begin_layout Standard
+However, entering all those parameters via the command line involves the
+ risk of typographical errors, which can lead to undesired results.
+ So, you may find it easier to write a brief shell script that contains
+ the parameters.
+ The file should have the suffix 
+\family typewriter
+.sh
+\family default
+.
+ When you downloaded the CitComS source, this included an 
+\family typewriter
+examples
+\family default
+ directory.
+ In this directory, you will find a script called 
+\family typewriter
+example1.sh
+\family default
+.
+ 
+\end_layout
+
+\begin_layout Paragraph
+Example: Simple Regional CitComS Shell Script, example1.sh 
+\end_layout
+
+\begin_layout LyX-Code
+#!/bin/sh
+\newline
+
+\end_layout
+
+\begin_layout LyX-Code
+citcomsregional.sh 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+--steps=71 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+--controller.monitoringFrequency=10 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+
+\backslash
+ --launcher.nodes=4 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+--launcher.nodegen="n%03d" 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+--launching.nodelist=[101-102,101-102] 
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+--solver.datafile=/scratch/username/example1 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+--solver.mesher.nprocx=2 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+--solver.mesher.nprocy=2 
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+--solver.mesher.nodex=17 
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+--solver.mesher.nodey=17 
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+--solver.mesher.nodez=9 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+# End of file
+\end_layout
+
+\begin_layout Standard
+This is a basic problem with 2 processors in colatitude (x-coordinate),
+ 2 in longitude (y-direction), and 1 in the radial (z-direction).
+ In addition, there will be 17 nodes in x, 17 nodes in y, and 9 nodes in
+ z.
+\end_layout
+
+\begin_layout Standard
+It is important to realize that within the code (and in finite element analysis)
+ the term "node" refers to the mesh points defining the corners of the elements.
+ Unfortunately, "nodes" also refers to the individual computers which make
+ up the Beowulf PC cluster.
+ In 
+\family typewriter
+example1.sh
+\family default
+, this is indicated with:
+\end_layout
+
+\begin_layout LyX-Code
+--solver.mesher.nprocx=2 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+--solver.mesher.nprocy=2 
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+--solver.mesher.nodex=17 
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+--solver.mesher.nodey=17 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+--solver.mesher.nodez=9 
+\backslash
+ 
+\end_layout
+
+\begin_layout Standard
+These quantities refer to the total number of FEM nodes in a given direction
+ for the complete problem and for the example it works out that within a
+ given processor there will be 9 x 9 x 9 nodes.
+ Note that in the x-direction (or y) that for the entire problem there are
+ 17 nodes and there is one node shared between two processors.
+ This shared node is duplicated in two adjacent processors.
+ The global numbering of FEM nodes is z-direction first, then x-direction,
+ then y-direction.
+ This numbering convention is used for the input and output data.
+\end_layout
+
+\begin_layout Standard
+In order to run this example you should be on your front end and be in the
+ directory in which the input file is located, in this case, the 
+\family typewriter
+examples
+\family default
+ directory.
+ To run the test example, invoke the following:
+\end_layout
+
+\begin_layout LyX-Code
+$ ./example1.sh
+\end_layout
+
+\begin_layout Standard
+Once you have completed your run, you will notice that it generates a file
+ called 
+\family typewriter
+mpirun.nodes
+\family default
+.
+ It will contain a list of the nodes where CitComS has run.
+ You may want to login to one of the nodes to check that the data appears
+ to have been properly generated.
+ You should also check the log file for any error messages.
+ 
+\end_layout
+
+\begin_layout Standard
+If you receive a message such as 
+\family typewriter
+bash: --solver.mesher.nodez=9: command not found
+\family default
+, chances are your script is missing a line continuation or has an extra
+ space.
+ However, most of the time CitComS will just run using the default values
+ -even if it finds a typographical error such as "nnode" instead of "node".
+ So, along with double-checking your parameters as you type them in, you
+ should check your results to be sure they make sense.
+ 
+\end_layout
+
+\begin_layout Standard
+Following your successful run, you will want to retrieve the output files
+ from all the nodes and process them so they can be visualized with the
+ visualization program OpenDX and proceed to the next chapter.
+\end_layout
+
+\begin_layout Section
+Using CitComS.py on the TeraGrid
+\end_layout
+
+\begin_layout Standard
+The TeraGrid is an open scientific discovery infrastructure combining leadership
+ class resources at eight partner sites to create an integrated, persistent
+ computational resource.
+ The TeraGrid takes its name from two concepts from high-end computing.
+ "Tera" is the metric prefix for "trillions" as in teraflops (trillions
+ of calculations per second) and terabytes (trillions of bytes) and reflects
+ the scale of the computing power provided by the TeraGrid.
+ The "Grid" portion of the TeraGrid reflects the idea of harnessing and
+ using distributed computers, data storage systems, networks, and other
+ resources as if they were a single massive system.
+ In other words, Grid computing uses software technologies to allow researchers
+ to create "virtual supercomputers" far larger than individual hardware
+ components.
+ 
+\end_layout
+
+\begin_layout Standard
+Although the TeraGrid is a high-end resource, it was developed to be accessible
+ to the general community of scientists and engineers as a production facility.
+ Since the TeraGrid software is based on commodity clusters, Linux/Unix,
+ and Globus, it should be easier to scale from a laboratory development
+ environment to a high-end environment in a straightforward manner which
+ promotes application performance.
+\end_layout
+
+\begin_layout Standard
+CitComS.py has already been installed on several NSF TeraGrid platforms.
+ Accounts for small allocations are available directly from CIG.
+\end_layout
+
+\begin_layout Chapter
+Postprocessing and Graphics
+\end_layout
+
+\begin_layout Section
+Introduction
+\end_layout
+
+\begin_layout Standard
+Once you have run CitComS, you should have a series of output files (potentially
+ spread throughout the file systems of your Beowulf).
+ You will have to retrieve and combine the data for the time-step (age)
+ of interest.
+\end_layout
+
+\begin_layout Standard
+To visualize your results, it is recommended that you use the open source
+ Open Visualization Data Explorer, better known as OpenDX.
+ Both the software and tutorials are available from the 
+\begin_inset LatexCommand \htmlurl[OpenDX website]{<http://www.opendx.org/>}
+
+\end_inset
+
+.
+ If you are using Mac OS X, a free version OpenDX is available via 
+\begin_inset LatexCommand \htmlurl[Fink]{<http://fink.sourceforge.net/>}
+
+\end_inset
+
+; however, if the installation proves to be difficult, a binary version
+ is available from 
+\begin_inset LatexCommand \htmlurl[HPC for Mac OS X]{<http://hpc.sourceforge.net/>}
+
+\end_inset
+
+.
+ 
+\end_layout
+
+\begin_layout Section
+Processing on a Beowulf Cluster
+\end_layout
+
+\begin_layout Standard
+Generally, the results from your CitComS run will be distributed on disks
+ attached to individual nodes of your Beowulf cluster.
+ The output files are written in each node under the directory that you
+ specified as your datafile in the input file.
+ To examine those files, login to a node and change directories to the one
+ you specified with a prefix.
+ For example, if you selected your datafile to be called 
+\family typewriter
+datafile="/scratch/username/test-case"
+\family default
+, then your output file will be written to 
+\family typewriter
+/scratch/username
+\family default
+ and will have the prefix 
+\family typewriter
+test-case
+\family default
+.
+ An example of a filename for the velocity output is 
+\family typewriter
+test-case.velo.2.10
+\family default
+ where 
+\family typewriter
+test-case
+\family default
+ is the model prefix; 
+\family typewriter
+velo
+\family default
+ means that this is a velocity data file; 
+\family typewriter
+2
+\family default
+ corresponds to the processor number (so it is using the 2nd processor);
+ 
+\family typewriter
+10
+\family default
+ corresponds to the time-step.
+ 
+\end_layout
+
+\begin_layout Standard
+To choose an age to export for postprocessing, you have to find out which
+ time step corresponds to the age that interests you.
+ This is done by looking at the log or time file, for example 
+\family typewriter
+test-case.log
+\family default
+.
+ The log file contains data that describes the details of the computation.
+ It also has a 
+\family typewriter
+current age
+\family default
+ field that lists the time step numbers and their corresponding times.
+ The time step value you selected is what will be exported for postprocessing.
+ The time file contains the non-dimensional model time.
+ The format of the time file can be found in Appendix C.
+ 
+\end_layout
+
+\begin_layout Standard
+These output files need to be post-processed before you can do the visualization.
+ There are two scripts both can post process (retrieve and combine) CitComS
+ output: 
+\family typewriter
+autocombine.py
+\family default
+ and 
+\family typewriter
+batchcombine.py
+\family default
+.
+ It is recommened to use 
+\family typewriter
+autocombine.py
+\family default
+ over 
+\family typewriter
+batchcombine.py
+\family default
+, as the former is easier to use.
+ 
+\end_layout
+
+\begin_layout Standard
+To use 
+\family typewriter
+autocombine.py
+\family default
+, you have to run CitComS.py in a slightly different way.
+ CitComS.py prints out the input parameters to the screen.
+ That print out can be redirected to a file, which can be used later to
+ retrieve input parameters.
+ This is done with: 
+\end_layout
+
+\begin_layout LyX-Code
+$ my_citcoms.py_script > input_param 
+\end_layout
+
+\begin_layout Standard
+Then, you can retrieve and combine data of step 10 by using: 
+\end_layout
+
+\begin_layout LyX-Code
+$ autocombine.py mpirun.nodes input_param 10 
+\end_layout
+
+\begin_layout Standard
+This reads the MPI machinefile (
+\family typewriter
+mpirun.nodes
+\family default
+) and CitComS.py input parameters (
+\family typewriter
+input_param
+\family default
+), then call 
+\family typewriter
+batchcombine.py
+\family default
+ to do the actual job.
+ The general useage for 
+\family typewriter
+autocombine.py
+\family default
+ is: 
+\end_layout
+
+\begin_layout LyX-Code
+$ autocombine.py [machinefile] [input_param] 
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+[step1] [step2 or more ...] 
+\end_layout
+
+\begin_layout Standard
+If you do not have the input parameters saved to a file, you have to use
+ 
+\family typewriter
+batchcombine.py
+\family default
+ to retrieve and combine the data.
+ The general usage for 
+\family typewriter
+batchcombine.py
+\family default
+ is: 
+\end_layout
+
+\begin_layout LyX-Code
+$ batchcombine.py [machinefile] [modeldir] [modelname] 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+[timestep] [nodex] [nodey] [nodez] [n-surf-cap] 
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+[nprocx] [nprocy] [nprocz] 
+\end_layout
+
+\begin_layout Standard
+where 
+\family typewriter
+machinefile
+\family default
+ is the file with a list of all the machines you are using, which, under
+ normal circumstances are the same as the launching nodes.
+ 
+\family typewriter
+modeldir
+\family default
+ is the scratch directory where all your files are located.
+ This should correspond to the first part of the 
+\family typewriter
+datafile
+\family default
+ entry, for example 
+\family typewriter
+/scratch/username
+\family default
+.
+ 
+\family typewriter
+modelname
+\family default
+ is the model prefix , for example 
+\family typewriter
+test_case
+\family default
+.
+ 
+\family typewriter
+timestep
+\family default
+ is the time step you want to export.
+ This corresponds to the last term in the filename of the velocity file.
+ 
+\family typewriter
+nodex
+\family default
+, 
+\family typewriter
+nodey
+\family default
+, nodez are the same values as those used in the input file.
+ 
+\family typewriter
+n-surf-cap
+\family default
+ is equal to 1 for regional CitComS and 12 for full CitComS.
+ 
+\family typewriter
+nprocx
+\family default
+, 
+\family typewriter
+nprocy
+\family default
+, 
+\family typewriter
+nprocz
+\family default
+ is the same as in the input file.
+ 
+\end_layout
+
+\begin_layout Standard
+If your Beowulf cluster uses ssh (rather than rsh) to access the computation
+ nodes, you have to manually edit bin/batchpaste.sh and replace 'rsh' to
+ 'ssh' in the file.
+ If your cluster forbids access to the computation nodes, you cannot use
+ neither 
+\family typewriter
+autocombine.py
+\family default
+ or 
+\family typewriter
+batchcombine.py
+\family default
+.
+ 
+\end_layout
+
+\begin_layout Standard
+Once 
+\family typewriter
+autocombine.py
+\family default
+ or 
+\family typewriter
+batchcombine.py
+\family default
+ has been run, you should end up with 2 files (or 24 files for full CitComS)
+ that resemble these: 
+\family typewriter
+test-case.cap0.10.general
+\family default
+ and 
+\family typewriter
+test-case.cap0.10
+\family default
+.
+ Those are the input files for OpenDX.
+ 
+\end_layout
+
+\begin_layout Section
+Postprocessing in a Non-Cluster Environment
+\end_layout
+
+\begin_layout Standard
+If you have run CitComS in a non-cluster environment or all of your data
+ are on local disk, you can still use 
+\family typewriter
+autocombine.py
+\family default
+ or 
+\family typewriter
+batchcombine.py
+\family default
+ to combine the data.
+ The machinefile is not needed and can be replaced by 
+\family typewriter
+localhost
+\family default
+, such as: 
+\end_layout
+
+\begin_layout LyX-Code
+$ autocombine.py localhost [input_param] 
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+[step1] [step2 or more ...] 
+\end_layout
+
+\begin_layout Standard
+or 
+\end_layout
+
+\begin_layout LyX-Code
+$ batchcombine.py localhost [modeldir] [modelname] [timestep] 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+[nodex] [nodey] [nodez] [n-surf-cap] 
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+[nprocx] [nprocy] [nprocz] 
+\end_layout
+
+\begin_layout Section
+Using OpenDX for Regional Visualization
+\end_layout
+
+\begin_layout Standard
+OpenDX modules designed for CitComS can be found in the 
+\family typewriter
+PREFIX/share/CitcomS/visual
+\family default
+ directory, where PREFIX is the directory under which you installed CitcomS
+ (default 
+\family typewriter
+/usr/local
+\family default
+).
+ You will need both the 
+\family typewriter
+.net
+\family default
+ and 
+\family typewriter
+.cfg
+\family default
+ files.
+ 
+\end_layout
+
+\begin_layout Standard
+In this example, you will use 
+\family typewriter
+visRegional.net
+\family default
+ to visualize the result of regional CitComS.py.
+ You should launch OpenDX by typing: 
+\end_layout
+
+\begin_layout LyX-Code
+$ dx 
+\end_layout
+
+\begin_layout Standard
+You will see an OpenDX 
+\family sans
+Data Explorer
+\family default
+ window.
+ Click 
+\family sans
+Edit\SpecialChar \menuseparator
+Visual Programs
+\family default
+ and select 
+\family typewriter
+visRegional.net
+\family default
+.
+ You will see a 
+\family sans
+Visual Program Editor
+\family default
+ window.
+ Then select on the 
+\family sans
+import
+\family default
+ tab in the main window and double-click on the 
+\family sans
+File Selector
+\family default
+ block, which will open a 
+\family sans
+Control Panel
+\family default
+ window.
+ In the 
+\family sans
+CitcomSImport
+\family default
+ filename input box, select your postprocessed data file, for example 
+\family typewriter
+test-case.cap0.10.general
+\family default
+ file.
+ (For the global model, select 
+\family sans
+import
+\family default
+ tab, double-click the 
+\family sans
+string
+\family default
+ block, enter the filename in 
+\family sans
+Citcoms Full Import format_string
+\family default
+ field.) In the pulldown menu, select 
+\family sans
+Execute\SpecialChar \menuseparator
+Execute Once
+\family default
+ or 
+\family sans
+Execute on Change
+\family default
+.
+ A new window will appear with the image of the model.
+ If you want to zoom, rotate, change projection and otherwise manipulate
+ the view of the model, experiment with the menu 
+\family sans
+Options\SpecialChar \menuseparator
+View Control
+\family default
+.
+ 
+\end_layout
+
+\begin_layout Standard
+\begin_inset Float figure
+wide false
+sideways false
+status open
+
+\begin_layout Standard
+\begin_inset Graphics
+	filename graphics/c_fig5.eps
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Caption
+Regional Model Visualized with OpenDX.
+ A snapshot of an upwelling (blue isosurface) with a slice of the velocity
+ field (bisecting plane).
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+Additional options in the control panel window for the regional model include:
+\end_layout
+
+\begin_layout Itemize
+
+\family sans
+CitcomSImport reduced
+\family default
+, can increase or reduce the resolution.
+ 
+\end_layout
+
+\begin_layout Itemize
+
+\family sans
+Core radius
+\family default
+ is the size of the orange sphere.
+ which represents the core-mantle boundary.
+\end_layout
+
+\begin_layout Itemize
+ 
+\family sans
+Isosurface value
+\family default
+ is the temperature isosurfaces.
+ You can change the values of the isosurfaces, including adding and deleting
+ them.
+ 
+\end_layout
+
+\begin_layout Itemize
+ 
+\family sans
+Slab cut dimension
+\family default
+ is the direction of the slab (an OpenDX term of cross-section).
+ 
+\end_layout
+
+\begin_layout Itemize
+ 
+\family sans
+Slab cut position
+\family default
+ is the position of the slab.
+  
+\end_layout
+
+\begin_layout Standard
+After changing any of these parameters, you must select 
+\family sans
+Execute\SpecialChar \menuseparator
+Execute Once
+\family default
+ to redraw the model.
+ You can change any of the parameters, visualization, or set-up by going
+ back to the main window and clicking on each tab.
+ If you click on each block, you will be able to change the settings for
+ that function.
+ 
+\end_layout
+
+\begin_layout Chapter
+Cookbooks
+\end_layout
+
+\begin_layout Section
+Introduction
+\end_layout
+
+\begin_layout Standard
+These cookbook examples are meant to serve as a guide to some of the types
+ of problems CitComS.py can solve.
+ Cookbook examples range from regional to full spherical shell problems
+ that address traditional convection problems.
+\end_layout
+
+\begin_layout Section
+Cookbook 1: Global Model Using 
+\family sans
+fullcitcoms
+\end_layout
+
+\begin_layout Subsection
+Problem
+\end_layout
+
+\begin_layout Standard
+You would like to solve for thermal convection within a full spherical shell
+ domain.
+ One of the versions of CitComS.py is designed to run on a cluster that decompose
+s the shell into 12 equal "caps" and then distributes the calculation for
+ caps onto separate processors.
+ To run CitComS.py with the full solver parameter set, it is recommended
+ that you have a minimum of 12 processors available on your cluster.
+ 
+\end_layout
+
+\begin_layout Standard
+\begin_inset Float figure
+wide false
+sideways false
+status open
+
+\begin_layout Standard
+\begin_inset Graphics
+	filename graphics/cookbook1.eps
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Caption
+Global Model "Caps": Three-dimensional perspective image showing the 12
+ spherical caps used in a full CitComS.py run.
+ (A) The temperature field at 1081 km depth from a Cookbook 1 run.
+ (B) 
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Subsection
+Solution
+\end_layout
+
+\begin_layout Standard
+You will be running 
+\family sans
+cookbook1.sh
+\family default
+ which calls the script 
+\family sans
+citcomsfull.sh
+\family default
+.
+ The first set of parameters specifies the number of nodes (12) and their
+ names on your cluster through Pyre's 
+\family sans
+launcher
+\family default
+ facility.
+\end_layout
+
+\begin_layout LyX-Code
+--launcher.nodes=12 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+--launcher.nodegen="n%03d" 
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+--launcher.nodelist=[101-106,101-106] 
+\backslash
+  
+\end_layout
+
+\begin_layout Standard
+The second set of parameters specify the number of time steps (101), and
+ how often the computation should be monitored (25).
+\end_layout
+
+\begin_layout LyX-Code
+--steps=101 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+--controller.monitoringFrequency=25 
+\backslash
+ 
+\end_layout
+
+\begin_layout Standard
+The last set of parameters include the location of the output (
+\family sans
+/scratch/username/cookbook1
+\family default
+), the number of perturbations (1), the number of nodal lines in the longitudina
+l direction (4), for example spherical harmonic in terms of time steps order
+ or 
+\family sans
+perturbm=2
+\family default
+, and the number of nodal lines in the latitudinal direction, for example
+ spherical harmonic degree 
+\family sans
+perturbl=3
+\family default
+.
+ Note that although the number of perturbations is assigned here as 
+\family sans
+solver.ic.num_perturbations=1
+\family default
+, that is actually the default value.
+\end_layout
+
+\begin_layout Standard
+
+\end_layout
+
+\begin_layout LyX-Code
+--solver.datafile="/scratch/username/cookbook1" 
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+--solver.ic.num_perturbations=1 
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+--solver.ic.perturbl=3 
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+--solver.ic.perturbm=2 
+\end_layout
+
+\begin_layout Standard
+Assuming your script is named 
+\family sans
+cookbook1.sh
+\family default
+, it is run by typing 
+\end_layout
+
+\begin_layout Standard
+
+\end_layout
+
+\begin_layout LyX-Code
+$ ./cookbook1.sh
+\end_layout
+
+\begin_layout Subsection
+Cookbook 1: Global Model
+\end_layout
+
+\begin_layout LyX-Code
+#!/bin/sh
+\end_layout
+
+\begin_layout LyX-Code
+
+\end_layout
+
+\begin_layout LyX-Code
+../../tests/citcomsfull.sh 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+--launcher.nodes=12 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+--launcher.nodegen="n%03d" 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+--launcher.nodelist=[141-146,141-146] 
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+--steps=101 
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+--controller.monitoringFrequency=25 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+--solver.datafile="/scratch/username/Test/cookbook1" 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+--solver.ic.num_perturbations=1 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+--solver.ic.perturbl=3 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+--solver.ic.perturbm=2 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+--solver.rayleigh=5.0e+4
+\end_layout
+
+\begin_layout LyX-Code
+
+\end_layout
+
+\begin_layout LyX-Code
+# End of file
+\end_layout
+
+\begin_layout Standard
+Once you have run the model, you can visualize it using OpenDX, described
+ in the previous chapter.
+ When you invoke "Edit Visual Program," you will need to select 
+\family typewriter
+visFull.net
+\family default
+.
+ 
+\end_layout
+
+\begin_layout Standard
+\begin_inset Float figure
+wide false
+sideways false
+status open
+
+\begin_layout Standard
+\begin_inset Graphics
+	filename graphics/cookbook1.2.jpg
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Caption
+Cookbook 1: Global Model.
+ This image depicts a slice through a spherical model of convection, with
+ warmer colors indicating upwelling and the cooler colors showing downwelling.
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Subsection
+Discussion
+\end_layout
+
+\begin_layout Standard
+You have generated a simple example of the full CitComS model, with minimal
+ parameter alterations.
+ With a default Rayleigh number of 
+\begin_inset Formula $10^{5}$
+\end_inset
+
+ and perturbation on the initial temperature field which has a degree
+\begin_inset Formula $^{3}$
+\end_inset
+
+ and an order
+\begin_inset Formula $^{2}$
+\end_inset
+
+ pattern, after 100 time steps, the convection pattern remains relatively
+ steady.
+\end_layout
+
+\begin_layout Standard
+As a note, it is not required that 12 processors, with one spherical cap
+ per processor, be used.
+ As an end-member possibility, 12 different jobs could be run on a single
+ computer by invoking:
+\end_layout
+
+\begin_layout LyX-Code
+--launcher.node=12 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+--launcher.node="n%03d" 
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+--launcher.nodelist=[101,101,101,101,101,101,101,101,101,101,101,101]
+\backslash
+
+\end_layout
+
+\begin_layout Standard
+This is not particularly efficient, but it does illustrate the flexibility
+ of both 
+\family typewriter
+mpi
+\family default
+ and Pyre.
+\end_layout
+
+\begin_layout Section
+Cookbook 2: Velocity Boundary Conditions
+\end_layout
+
+\begin_layout Subsection
+Problem
+\end_layout
+
+\begin_layout Standard
+You would like to solve for thermal convection and with velocity boundary
+ conditions on the top surface within a given region of a sphere.
+ As with 
+\begin_inset LatexCommand \vref{sub:Uniprocessor-CitComS-from}
+
+\end_inset
+
+, you will need to modify a script that calls the regional version of CitComS,
+ 
+\family typewriter
+citcomsregional.sh
+\family default
+.
+ 
+\end_layout
+
+\begin_layout Standard
+Solution
+\end_layout
+
+\begin_layout Standard
+You will be running 
+\family typewriter
+cookbook2.sh
+\family default
+, which calls the script 
+\family typewriter
+citcomsregional.sh
+\family default
+.
+ The parameters specify the number of processors or nodes (4), time steps
+ (61), the location of the output (
+\family typewriter
+/scratch/username/cookbook2
+\family default
+), and how often the computation will be monitored (30).
+\end_layout
+
+\begin_layout LyX-Code
+--steps=61 
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+--controller.monitoringFrequency=30 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+--launcher.nodes=4 
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+--launcher.nodegen="n%03d" 
+\end_layout
+
+\begin_layout LyX-Code
+
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+--launcher.nodelist=[101-102,101-102]
+\end_layout
+
+\begin_layout LyX-Code
+
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+--solver.datafile=/scratch/username/cookbook2 
+\backslash
+ 
+\end_layout
+
+\begin_layout Standard
+The 
+\family typewriter
+solver.mesher
+\family default
+ has several properties involved in the generation of the computational
+ mesh.
+ Continue to use the default values for the physical portion of the domain
+ in which you are interested.
+ However, try modifing the layout of the mesh as shown.
+ 
+\end_layout
+
+\begin_layout LyX-Code
+--solver.mesher.nprocx=2 
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+--solver.mesher.nprocy=2 
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+--solver.mesher.nodex=17 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+--solver.mesher.nodey=17 
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+--solver.mesher.nodez=9 
+\backslash
+ 
+\end_layout
+
+\begin_layout Standard
+\begin_inset Float figure
+wide false
+sideways false
+status open
+
+\begin_layout Standard
+\begin_inset Graphics
+	filename graphics/cookbook2.eps
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Caption
+Computational View.
+ Top view configuration of the layer of the computational nodes and the
+ processors.
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+The 
+\family typewriter
+solver.bc
+\family default
+ facility allows you to impose a uniform velocity across the top surface.
+ You have a velocity which is purely in the colatitude direction with a
+ non-dimensional velocity of 100.
+ (See 
+\begin_inset LatexCommand \vref{eq:6}
+
+\end_inset
+
+.) In addition, to determine the temperature, the temperature field associated
+ only with this imposed velocity, reset the initial perturbation to zero,
+ using the 
+\family typewriter
+solver.ic
+\family default
+ facility.
+ 
+\end_layout
+
+\begin_layout Standard
+
+\end_layout
+
+\begin_layout LyX-Code
+--solver.bc.topvbc=1 
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+--solver.bc.topvbxval=100 
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+--solver.bc.topvbyval=0 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+--solver.ic.num_perturbations=1 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+--solver.ic.perturbmag=0.0
+\end_layout
+
+\begin_layout Subsection
+Cookbook 2: Velocity Boundary Conditions
+\end_layout
+
+\begin_layout LyX-Code
+#!/bin/sh
+\end_layout
+
+\begin_layout LyX-Code
+../../tests/citcomsregional.sh 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+--steps=61 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+--controller.monitoringFrequency=30 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+--launcher.nodes=4 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+--launcher.nodegen="n%03d" 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+--launcher.nodelist=[101-102,101-102] 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+--solver.datafile=/scratch/username/cookbook2 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+--solver.mesher.nprocx=2 
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+--solver.mesher.nprocy=2 
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+--solver.mesher.nodex=17 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+--solver.mesher.nodey=17 
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+--solver.mesher.nodez=9 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+--solver.bc.topvbc=1 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+--solver.bc.topvbxval=100 
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+--solver.bc.topvbyval=0 
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+--solver.ic.num_perturbations=1 
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+--solver.ic.perturbmag=0.0
+\end_layout
+
+\begin_layout Standard
+\begin_inset Float figure
+wide false
+sideways false
+status open
+
+\begin_layout Standard
+\begin_inset Graphics
+	filename graphics/cookbook2.2.eps
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Caption
+\begin_inset LatexCommand \label{fig:Cookbook-2:-Velocity}
+
+\end_inset
+
+\InsetSpace ~
+Cookbook\InsetSpace ~
+2: \InsetSpace ~
+Velocity\InsetSpace ~
+boundary\InsetSpace ~
+conditions.
+ This model highlights a region of the overall sphere and the heated upwellings
+ (warm colors), downwellings (cool colors), and the even distribution of
+ the velocities (yellow arrows).
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Subsection
+Discussion
+\end_layout
+
+\begin_layout Standard
+Using OpenDX to visualize the results 
+\begin_inset LatexCommand \ref{fig:Cookbook-2:-Velocity}
+
+\end_inset
+
+, this model allows you to create a plate-model of convection in which there
+ is a thermal upwelling on one wall, a thermal downwelling on another, and
+ uniform horizontal velocity across the top.
+ The downwelling is not exactly subduction because the default boundary
+ conditions are close to zero shear stress on the boundaries.
+ This means that there is a symmetrical downwelling in a vertical domain
+ on the other side, which gives rise to symmetrical downwelling.
+ 
+\end_layout
+
+\begin_layout Section
+Cookbook 3: Temperature-dependant Viscosity
+\end_layout
+
+\begin_layout Subsection
+Problem
+\end_layout
+
+\begin_layout Standard
+A common problem in geophysics is the exploration of natural convection
+ in the presence of variable viscosity, including temperature-dependant
+ or stress-dependent viscosity.
+\end_layout
+
+\begin_layout Subsection
+Solution
+\end_layout
+
+\begin_layout Standard
+You will be running 
+\family typewriter
+cookbook3.sh
+\family default
+, which calls the script 
+\family typewriter
+citcomsregional.sh
+\family default
+.
+ The parameters specify the number of processors (4) and their names, time
+ steps (200), the location of the output (
+\family typewriter
+/scratch/username/cookbook3
+\family default
+) and how often the computation will be monitored (25).
+\end_layout
+
+\begin_layout LyX-Code
+--steps=200 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+--controller.monitoringFrequency=25 
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+--launcher.nodes=4 
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+--launcher.nodegen="n%03d" 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+--launcher.nodelist=[101-102,101-102] 
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+--solver.datafile=/scratch/username/cookbook3 
+\backslash
+
+\end_layout
+
+\begin_layout Standard
+The 
+\family typewriter
+solver.rayleigh
+\family default
+ indicates is the Rayleigh number you would like to set and the 
+\family typewriter
+solver.visc
+\family default
+  parameters assign the viscosities.
+\end_layout
+
+\begin_layout LyX-Code
+--solver.rayleigh=1e6 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+--solver.visc.VISC_UPDATE=on 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+--solver.visc.num_mat=4 
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+--solver.visc.visc0=1,1,1,1 
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+--solver.visc.TDEPV=on 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+--solver.visc.viscE=0.2,0.2,0.2,0.2 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+--solver.visc.viscT=0,0,0,0 
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+--solver.visc.VMIN=on 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+--solver.visc.visc_min=1.0 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+--solver.visc.VMAX=on 
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+--solver.visc.visc_max=100.0 
+\end_layout
+
+\begin_layout Subsection
+Cookbook 3: Temperature Dependant Viscosity
+\end_layout
+
+\begin_layout LyX-Code
+#!/bin/sh
+\end_layout
+
+\begin_layout LyX-Code
+
+\end_layout
+
+\begin_layout LyX-Code
+../../tests/citcomsregional.sh 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+--steps=200 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+--controller.monitoringFrequency=25 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+--launcher.nodes=4 
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+--launcher.nodegen="n%03d" 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+--launcher.nodelist=[101-102,101-102] 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+--solver.rayleigh=1e6 
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+--solver.datafile=/scratch/username/cookbook3 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+--solver.mesher.nprocx=2 
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+--solver.mesher.nprocy=2 
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+--solver.mesher.nodex=17 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+--solver.mesher.nodey=17 
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+--solver.mesher.nodez=9 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+--solver.visc.VISC_UPDATE=on 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+--solver.visc.num_mat=4 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+--solver.visc.visc0=1,1,1,1 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+--solver.visc.TDEPV=on 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+--solver.visc.viscE=0.2,0.2,0.2,0.2 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+--solver.visc.viscT=0,0,0,0 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+--solver.visc.VMIN=on 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+--solver.visc.visc_min=1.0 
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+--solver.visc.VMAX=on 
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+--solver.visc.visc_max=100.0
+\end_layout
+
+\begin_layout Standard
+\begin_inset Float figure
+wide false
+sideways false
+status open
+
+\begin_layout Standard
+\begin_inset Graphics
+	filename graphics/cookbook3.eps
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Caption
+Cookbook\InsetSpace ~
+3:\InsetSpace ~
+Velocity\InsetSpace ~
+Boundary\InsetSpace ~
+Conditions.
+ This model highlights a region that features both the heated upwelling
+ (warm colors) and the even distribution of the velocities (yellow arrows).
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Section
+Cookbook 4: Regionally Refined Meshes 
+\end_layout
+
+\begin_layout Subsection
+Problem
+\end_layout
+
+\begin_layout Standard
+Frequently for convection problems, particularly those with variable viscosity,
+ there are features with strong gradients in temperature or viscosity that
+ can be better resolved with retired meshes.
+ For example, for the problem just studied in Cookbook 3, temperature dependant
+ viscosity, a higher resolution is required for a narrow hot upwelling while
+ a lower resolution is sufficient for the wider cold downwelling.
+ 
+\end_layout
+
+\begin_layout Subsection
+Solution
+\end_layout
+
+\begin_layout Standard
+The parameter that controls if a mesh is to be uniform or refined 
+\family typewriter
+coor
+\family default
+.
+ Set the 
+\family typewriter
+coor
+\family default
+ to 
+\family typewriter
+ON (solver.mesher.coor=on)
+\family default
+ in order to read the uneven mesh point coordinates from an input file (such
+ as 
+\family typewriter
+coor.dat
+\family default
+).
+ The format of the coordinate input file, 
+\family typewriter
+coor_file
+\family default
+, is as follows.
+ The file is an ASCII file with only one column, with each line for each
+ mesh point, separated in three parts.
+ Each part corresponds to the coordinates in the colatitude (in radians
+ between 
+\family typewriter
+theta_min
+\family default
+ and 
+\family typewriter
+theta_max
+\family default
+), longitude (in radians between 
+\family typewriter
+fi_min
+\family default
+ and 
+\family typewriter
+fi_max
+\family default
+) and radial (non-dimensional between 
+\family typewriter
+radius_inner
+\family default
+ and 
+\family typewriter
+radius_outer
+\family default
+) directions.
+ The number of entries within each part must correspond exactly to the number
+ of entries for the other parts.
+ Also, each part has a header as follows: 
+\family typewriter
+nsd=1
+\family default
+, 
+\family typewriter
+nsd=2
+\family default
+ and 
+\family typewriter
+nsd=3
+\family default
+ for colatitude, longitude and radial direction respectively.
+ 
+\end_layout
+
+\begin_layout Subsection
+Cookbook 4: Regionally Refined Meshes Coordinate File Example
+\end_layout
+
+\begin_layout LyX-Code
+nsd=1 
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+theta_min 
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+theta_max 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+nsd=2 
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+fi_min 
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+fi_max 
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+nsd=3 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+radius_inner 
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+radius_outer 
+\backslash
+ 
+\end_layout
+
+\begin_layout Subsection
+Cookbook 4: Regionally Refined Meshes
+\end_layout
+
+\begin_layout LyX-Code
+#!/bin/sh
+\end_layout
+
+\begin_layout LyX-Code
+
+\end_layout
+
+\begin_layout LyX-Code
+../../tests/citcomsregional.sh 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+--steps=250 
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+--controller.monitoringFrequency=10 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+--launcher.nodes=32 
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+--launcher.nodegen="n%03d" 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+--launcher.nodelist=[151-166,151-166] 
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+--solver.rayleigh=1e6 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+--solver.datafile=/scratch/username/cookbook4 
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+--solver.ic.num_perturbations=1 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+--solver.ic.perturbmag=0.05 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+--solver.ic.perturbl=1 
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+--solver.ic.perturbm=0 
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+--solver.ic.perturblayer=10 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+--solver.mesher.coor=on 
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+--solver.mesher.coor_file=/scratch/username/coor.dat 
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+--solver.mesher.nprocx=4 
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+--solver.mesher.nprocy=4 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+--solver.mesher.nprocz=2 
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+--solver.mesher.nodex=33 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+--solver.mesher.nodey=33 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+--solver.mesher.nodez=17 
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+--solver.mesher.levels=1 
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+--solver.mesher.theta_min=1 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+--solver.mesher.theta_max=2 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+--solver.mesher.fi_min=0 
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+--solver.mesher.fi_max=1 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+--solver.visc.VISC_UPDATE=on 
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+--solver.visc.num_mat=4 
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+--solver.visc.visc0=1,1,1,1 
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+--solver.visc.TDEPV=on 
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+--solver.visc.viscE=0.2,0.2,0.2,0.2 
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+--solver.visc.viscT=0,0,0,0 
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+--solver.visc.VMIN=on 
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+--solver.visc.visc_min=1.0 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+--solver.visc.VMAX=on 
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+--solver.visc.visc_max=100.0
+\backslash
+
+\end_layout
+
+\begin_layout Standard
+\begin_inset Float figure
+wide false
+sideways false
+status open
+
+\begin_layout Standard
+\begin_inset Graphics
+	filename graphics/cookbook4.eps
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Caption
+Cookbook\InsetSpace ~
+4: This model shows the temperature (upwelling -- warm colors, downwelli
+ng -- cool colors) and the uneven distribution of the velocities (yellow
+ arrows).
+ Note the refined mesh for the left and bottom regions of the model (inset).
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Subsection
+Discussion
+\end_layout
+
+\begin_layout Standard
+The resulting model is like a 2D model, but extends in the longitudinal
+ direction.
+ To set up this type of model, the initial temperature gradient was perturbed
+ only in the longitudinal direction, by setting the parameters 
+\family typewriter
+perturbl=1
+\family default
+ and 
+\family typewriter
+perturbm=0
+\family default
+.
+ The model results show a thin thermal upwelling on one wall and a wide
+ thermal downwelling on the opposite wall.
+ Also, at the bottom of the model a thin layer of hot material can be shown.
+ Note the higher resolution in the narrow regions with hot material and
+ the lower resolution for the wide thermal downwelling region.
+\end_layout
+
+\begin_layout Section
+Cookbook 5: Subduction Models with Trench Rollback
+\end_layout
+
+\begin_layout Subsection
+Problem
+\end_layout
+
+\begin_layout Standard
+A common issue to address is the problem arising when the position of the
+ oceanic trench is not constant in time (trench rollback) for a subduction
+ zone.
+ In addition, the trench rollback speed may vary in time, which can be caused,
+ for example, by a rotation pole jump.
+ 
+\end_layout
+
+\begin_layout Subsection
+Solution
+\end_layout
+
+\begin_layout Standard
+In order to introduce in a convection model a trench rollback you have to
+ prepare the velocity files.
+ The following scenario is proposed for this cook book: there are two plates
+ centered along the equator, with two different Euler poles (See figure
+ 5.1).
+ Initially, both plates have Euler poles situated far, so the velocities
+ are approximately constants ( about 5 cm/yr for the left plate and about
+ 2 cm/yr for the right plate).
+ After 30 Ma a pole jump occurred for the right slab only, so the Euler
+ pole moved closer.
+ Since we impose a top velocity boundary in our model, the following facilities
+ should be turned on: 
+\end_layout
+
+\begin_layout Standard
+
+\end_layout
+
+\begin_layout LyX-Code
+--solver.bc.topvbc=1 
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+--solver.param.file_vbcs=on 
+\backslash
+
+\end_layout
+
+\begin_layout Standard
+The following two lines specify the location of the velocity files and the
+ starting age for the model: 
+\end_layout
+
+\begin_layout Standard
+
+\end_layout
+
+\begin_layout LyX-Code
+--solver.param.vel_bound_file=$PWD/velocity/vel.dat 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+--solver.param.start_age=55 
+\backslash
+ 
+\end_layout
+
+\begin_layout Standard
+Since the starting age is set to 55 Ma, there will be 56 velocity files,
+ one for each Ma (
+\family typewriter
+vel.dat0, vel.dat1,...vel.dat55, vel.dat56
+\family default
+).
+ The format of the velocity file is a two column ACSII file format as following:
+ 
+\end_layout
+
+\begin_layout LyX-Code
+v_theta     v_fi 
+\end_layout
+
+\begin_layout LyX-Code
+......
+\end_layout
+
+\begin_layout Standard
+There will be as many line as the total number of nodes for the top plane
+ (
+\family typewriter
+n_theta * n_fi
+\family default
+).
+ 
+\end_layout
+
+\begin_layout Subsection
+Cookbook 5: Subductions Models with Trench Rollback
+\end_layout
+
+\begin_layout LyX-Code
+#!/bin/sh 
+\end_layout
+
+\begin_layout LyX-Code
+
+\end_layout
+
+\begin_layout LyX-Code
+../../tests/citcomsregional.sh 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+--steps=1000 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+--controller.monitoringFrequency=10 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+--launcher.nodes=64 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+--launcher.nodegen="n%03d" 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+--launcher.nodelist=[131-162] 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+--solver.datafile=/scratch/username/cookbook5 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+--solver.rayleigh=4.07e+08 
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+--solver.bc.topvbc=1 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+--solver.param.file_vbcs=on 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+--solver.param.vel_bound_file=$PWD/velocity/bvel.dat 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+--solver.param.start_age=55 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+--solver.ic.restart=on 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+--solver.ic.solution_cycles_init=0 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+--solver.datafile_old=$PWD/restart_files/cookbook5 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+--solver.bc.temperature_bound_adj=off 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+--solver.bc.depth_bound_adj=0.157000 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+--solver.bc.width_bound_adj=0.050000 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+--solver.mesher.coor=on 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+--solver.mesher.coor_file=$PWD/coor.dat 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+--solver.mesher.mgunitx=2 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+--solver.mesher.nprocx=2 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+--solver.mesher.nprocy=8 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+--solver.mesher.nprocz=4 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+--solver.mesher.nodex=17 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+--solver.mesher.nodey=65 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+--solver.mesher.nodez=33 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+--solver.mesher.levels=1 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+--solver.mesher.theta_min=1.47 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+--solver.mesher.theta_max=1.67 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+--solver.mesher.fi_min=0 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+--solver.mesher.fi_max=0.5 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+--solver.mesher.radius_inner=0.7 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+--solver.visc.VISC_UPDATE=on 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+--solver.visc.rheol=3 
+\backslash
+ 
+\end_layout
+
+\begin_layout LyX-Code
+
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+--solver.const.refvisc=4e+21 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+--solver.visc.num_mat=4 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+--solver.visc.visc0=100,0.003,1,2 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+--solver.visc.TDEPV=on 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+--solver.visc.viscE=24,24,24,24 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+--solver.visc.viscT=0.182,0.182,0.182,0.182 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+--solver.visc.VMIN=on 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+--solver.visc.visc_min=0.01 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+--solver.visc.VMAX=on 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+--solver.visc.visc_max=100.0 
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+# End of file
+\end_layout
+
+\begin_layout Standard
+\begin_inset Float figure
+wide false
+sideways false
+status open
+
+\begin_layout Standard
+\begin_inset Graphics
+	filename graphics/cookbook5.eps
+	lyxscale 65
+	scale 65
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Caption
+Cookbook\InsetSpace ~
+5: Left (A): initially, both plates have Euler poles (magenta and
+ green dots) situated far, so the velocities are approximately constants
+ (about 5 cm/yr for the left plate and about 2 cm/yr for the right plate).
+ Right (B): after 30 Ma a pole jump occurred for the right slab only, so
+ the Euler pole moved closer.
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+\begin_inset Float figure
+wide false
+sideways false
+status open
+
+\begin_layout Standard
+\begin_inset Graphics
+	filename graphics/cookbook5.2.eps
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Caption
+\begin_inset LatexCommand \label{fig:Cookbook-5:-the}
+
+\end_inset
+
+\InsetSpace ~
+Cookbook\InsetSpace ~
+5: The pole jump after 30 Ma produced a flat slab on one side (fore
+ side) and a steep slab on the other side (back side).
+ 
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Subsection
+Discussion
+\end_layout
+
+\begin_layout Standard
+The results for this problem are presented in Figure 
+\begin_inset LatexCommand \ref{fig:Cookbook-5:-the}
+
+\end_inset
+
+.
+ Since the two Euler poles are kept fixed for the first 30 Ma, the shape
+ of the subducting slab will be the same along the trench.
+ At 25 Ma the Euler pole for the right plate jumps toward the plate.
+ Therefore, the velocity along the trench varies from about 1 cm/yr to about
+ 2.5 cm/yr.
+ This will produce in time a flat slab at one side of the model, and a steep
+ slab at the other side.
+\end_layout
+
+\begin_layout Section
+Cookbook 6: Pseudo-free-surface Formulation
+\end_layout
+
+\begin_layout Subsection
+Problem
+\end_layout
+
+\begin_layout Standard
+Free-slip boundary conditions are typically applied on the top surface of
+ mantle convection models and the dynamic topography is obtained by assuming
+ that the normal stress on the top surface is instantaneously compensated
+ by the deformed surface.
+ This type of boundary conditions works well for long-wavelength topography,
+ but a free-surface formulation becomes necessary in cases where intermediate
+ to short wavelength topography is of interest or lithosphere has a very
+ high effective viscosity.
+ Another situation where free-surface formulation desired is when two Pyre
+ solvers, Snac and Citcom, are coupled.
+\end_layout
+
+\begin_layout Standard
+The basic algorithm 
+\begin_inset LatexCommand \cite{Zhong et al Free-surface formulation,Zhong et al Three-dimensional}
+
+\end_inset
+
+ consists of four steps.
+ 
+\end_layout
+
+\begin_layout Enumerate
+On the nodes of the top surface, topography increment computed is by integrating
+ normal velocity over time.
+ 
+\end_layout
+
+\begin_layout Enumerate
+The normal traction on the top surface is calculated based on the accumulated
+ topography up to the current time step, and added to the forcing term in
+ the matrix version of the momentum equation.
+ 
+\end_layout
+
+\begin_layout Enumerate
+Update velocity field with the changed forcing term.
+ 
+\end_layout
+
+\begin_layout Enumerate
+Velocity field has not converged yet, reiterate steps 1 from 3.
+\end_layout
+
+\begin_layout Standard
+Solution
+\end_layout
+
+\begin_layout Standard
+To verify if the above algorithm works, you will run two different Citcom-only
+ models with each B.C.
+ (free-slip and pseudo-free-surface) and compare the topography computed
+ accordingly.
+ The scripts 
+\family typewriter
+citcom_only_freeslip.sh
+\family default
+, 
+\family typewriter
+citcom_only_freesurf.sh
+\family default
+ will include the following parameters.
+\end_layout
+
+\begin_layout Itemize
+Domain size: 45 deg x 45 deg x 1200 km 
+\end_layout
+
+\begin_layout Itemize
+Mesh size: 61 x 61 x 25 with mesh refinement (coord.dat) 
+\end_layout
+
+\begin_layout Itemize
+BC: free-slip/free-surface for top.
+ free-slip for all the other surfaces 
+\end_layout
+
+\begin_layout Itemize
+IC: spherical hot blob with diameter of 1/4 of radial dimension is placed
+ at the center of the domain
+\newline
+
+\end_layout
+
+\begin_layout Itemize
+specific options:
+\end_layout
+
+\begin_layout Itemize
+tsolver.fixed_timestep=7.770000e-10 (= ~1000 yrs)
+\end_layout
+
+\begin_layout Itemize
+vsolver.BC.pseudo_free_surf=on/off
+\end_layout
+
+\begin_layout Itemize
+scripts for running test models: 
+\family typewriter
+citcom_only_freeslip.sh
+\family default
+, 
+\family typewriter
+citcom_only_freesurf.sh
+\end_layout
+
+\begin_layout Subsection
+Discussion
+\end_layout
+
+\begin_layout Standard
+The plots of topography profile are consistent with results described in
+ 
+\begin_inset LatexCommand \cite{Zhong et al Free-surface formulation}
+
+\end_inset
+
+.
+ In the graphs below, the solid line indicates free-slip and the dashed
+ line indicates free-surface.
+ Note: the unit of x axis is radians, not degrees.
+ 
+\end_layout
+
+\begin_layout Standard
+\begin_inset Float figure
+wide false
+sideways false
+status open
+
+\begin_layout Standard
+\begin_inset Graphics
+	filename graphics/cookbook7.eps
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Caption
+Cookbook 6.
+ Graphs of topography profiles.
+ 
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Part
+Appendices
+\end_layout
+
+\begin_layout Chapter*
+Appendix A: Facilities, Properties, and Parameters
+\end_layout
+
+\begin_layout Section*
+Introduction
+\end_layout
+
+\begin_layout Standard
+Most of the properties have identical names as the parameters as those used
+ in the regular version of CitComS.
+ This section highlights those which have changed and those which are entirely
+ new.
+ All the parameters which can be set are included in an appendix at the
+ end of this documentation.
+ Parameters are given with their default values.
+ 
+\end_layout
+
+\begin_layout Section*
+Parameters that Control Input Files
+\end_layout
+
+\begin_layout Standard
+\begin_inset Tabular
+<lyxtabular version="3" rows="8" columns="2">
+<features>
+<column alignment="left" valignment="top" leftline="true" width="1.75in">
+<column alignment="left" valignment="top" leftline="true" rightline="true" width="3.5in">
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+datafile=""
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+datafile controls the location of output files and the prefix of their names.
+ In this case the directory /scratch/ must be created a priori.
+ Files such as test.xxx.
+ For example, 
+\family typewriter
+\size small
+datafile="/scratch/test"
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+file_vbcs=0 
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+If file_vbcs is true (it is set=1) then the top surface velocity boundary
+ conditions are read in from files which have location and name specified
+ by vel_bound_file.
+ The conditions on the top surface must be correctly set, as indicated below.
+ If you wish to have a uniform top surface velocity boundary condition or
+ some simple geometric pattern, then file_vbcs should be set to zero.
+ 
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+vel_bound_file=""
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+See explanation the entry for file_vbcs, above.
+ Velocity boundary conditions are read by setting the pathway to the boundary
+ conditions file, for example 
+\family typewriter
+\size footnotesize
+vel_bound_file="/username/Models/New_Tonga/Vel/bvel.dat" 
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+coor=off
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+If you wish to have a regular, but uneven, spacing between elements then
+ coor should be set to on.
+ If coor is set to off, then there will be uniform mesh in the latitudinal,
+ longitudinal, and radial directions.
+ For example, 
+\family typewriter
+\size small
+coor_file="/username/Models/New_Tonga/Case2/coor.dat"
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+coor_file=""
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+See coor, above.
+ For example, 
+\family typewriter
+\size small
+coor_file="/username/Models/New_Tonga/Case2/coor.dat"
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+mat_control=0
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\family typewriter
+\size small
+mat_file="/home/clint/back/ra8/mat.dat"
+\family default
+\size default
+ If mat_control is true (it is set=1) then the time- and positional-dependent
+ viscosity factor is defined by file having location and name specified
+ bymat_file.
+ These parameters allow you to define the material group of each element
+ (such as a moving weak zone).
+ 
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+lith_age=0
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\family typewriter
+\size footnotesize
+lith_age_file="/username/Models/New_Tonga/Case6/age.dat"
+\family default
+\size default
+ If lith_age is true (it is set=1) then the lith_age_file is read.
+ These parameters control the thermal age of the top thermal boundary condition.
+ 
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+tracer=0
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\family typewriter
+\size small
+tracer_file=""
+\family default
+\size default
+ This controls the tracer particles which are advected passively by the
+ flow.
+ This part of the code has not been made parallel and must be used with
+ caution with the present implementation.
+ 
+\end_layout
+
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Section*
+Mesh Set-up and Processors
+\end_layout
+
+\begin_layout Standard
+Parameters control the logical set-up of the mesh as well as the number
+ of processors in the three coordinate directions.
+\end_layout
+
+\begin_layout Standard
+\noindent
+\begin_inset Tabular
+<lyxtabular version="3" rows="5" columns="2">
+<features>
+<column alignment="left" valignment="top" leftline="true" width="1.75in">
+<column alignment="left" valignment="top" leftline="true" rightline="true" width="3.5in">
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+nproc_surf=1
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+This specifies the number of spherical caps of the mesh, must be 1 for CitComS.py
+ and 12 for fullCitComS.
+ 
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+nprocx=2
+\newline
+nprocy=2
+\newline
+nprocz=1
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+These specify the number of processors in each spherical cap.
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+nodex=17
+\newline
+nodey=17
+\newline
+nodez=9
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+These specify the number of FEM nodes in each spherical cap.
+ 
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+mgunitx=8
+\newline
+mgunity=8
+\newline
+mgunitz=8
+\newline
+levels=1
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+These specify the nested level of multigrid unit.
+ Used by multigrid solver only.
+ These parameters are not completely independent to each other.
+ Some constraints must be satisfied:
+\newline
+
+\newline
+nodex = 1 + nprocx * mgunitx * 2 **
+ (levels-1)
+\newline
+nodey = 1 + nprocy * mgunity * 2 ** (levels-1)
+\newline
+nodez = 1 + nprocz
+ * mgunitz * 2 ** (levels-1)
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+nprocx=nprocy; 
+\newline
+nodex=nodey;
+\newline
+mgunitx=mgunity
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+For fullCitComS only
+\end_layout
+
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Section*
+\noindent
+Domain Size
+\end_layout
+
+\begin_layout Standard
+\noindent
+Parameters which control the actual physical size of the domain (a cut out
+ of a sphere).
+\end_layout
+
+\begin_layout Standard
+\noindent
+\begin_inset Tabular
+<lyxtabular version="3" rows="2" columns="2">
+<features>
+<column alignment="left" valignment="top" leftline="true" width="1.75in">
+<column alignment="left" valignment="top" leftline="true" rightline="true" width="3.5in">
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+theta_min=1.0780
+\newline
+theta_max=2.0708
+\newline
+fi_min=0
+\newline
+fi_max=1
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+theta_min and theta_max are the colatitude measured in radians from the
+ north pole.
+ fi_min and fi_max are the longitudes measured from the prime meridian eastward
+ in radians.
+ Only in CitComS.py.
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+radius_inner=0.55
+\newline
+radius_outer=1.0 
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+radius_inner and radius_outer are the inner and outer radius in non-dimensional
+ unit.
+ It is probably most convenient to normalize lengths by the radius of the
+ Earth.
+ If you do this, then the Rayleigh number, given below, must be calculated
+ with the radius of the Earth, not the thickness of the mantle.
+ The core mantle boundary is close to having a non-dimensional radius of
+ 0.55.
+\end_layout
+
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Section*
+Restarting the Code
+\end_layout
+
+\begin_layout Standard
+Parameters which control the restarting of the code.
+\end_layout
+
+\begin_layout Standard
+\noindent
+\begin_inset Tabular
+<lyxtabular version="3" rows="2" columns="2">
+<features>
+<column alignment="left" valignment="top" leftline="true" width="1.75in">
+<column alignment="left" valignment="top" leftline="true" rightline="true" width="3.5in">
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+restart=0
+\newline
+post_p=0
+\newline
+datafile_old=""
+\newline
+solution_cycles_init=100
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+If restart is true, for example, processor #5 will read its initial temperature
+ field formfile /scratch/test.velo.5.100 in this case.
+ If post_p is true, for example, processor #5 will read its initial temperature
+ field form file /scratch/test.velo.5.100 in this case, just like when restart
+ is true.
+ But the program will run for 1 time step only.
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+zero_elapsed_time=1 
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+If zero_elapsed_time is true, the initial time is set to zero.
+ If it is false and restart or post_p is true, the initial time is read
+ in from previous output files.
+\end_layout
+
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Section*
+Run Length, Output Interval
+\end_layout
+
+\begin_layout Standard
+Parameters which control the length of the run and the interval between
+ writing output files.
+\end_layout
+
+\begin_layout Standard
+\noindent
+\begin_inset Tabular
+<lyxtabular version="3" rows="1" columns="2">
+<features>
+<column alignment="left" valignment="top" leftline="true" width="1.75in">
+<column alignment="left" valignment="top" leftline="true" rightline="true" width="3.5in">
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+minstep=1
+\newline
+run=8001
+\newline
+maxtotstep=8001
+\newline
+monitoringFrequency=10
+\newline
+cpu_limits_in_seconds=
+  \InsetSpace ~
+\InsetSpace ~
+\InsetSpace ~
+360000000
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+The maximum number of time steps is set with run and maxtotstep.
+ It is recommended that these be set to the same value.
+ Add one to the total number of steps; in this example, the total steps
+ is 8000.
+ The minimum numbers of time steps is set with minstep.
+ monitoringFrequency controls the interval between output files.
+ CitComS dynamically determines the non-dimensional time step (such as _t),
+ this means that you might not get an output at the exact time required,
+ but you can always get close depending on how small monitoringFrequency
+ is.
+ Do not make this number too small since outputs slow the code down and
+ you may end up with an unmanageable number of output files.
+ You can also control the termination of the code based on total wall clock
+ time using cpu_limits_in_seconds.
+ If you are just learning to use the code, you might want to give this a
+ small value so that it doesn't burn up valuable computer time.
+\end_layout
+
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Section*
+Initial Conditions
+\end_layout
+
+\begin_layout Standard
+\begin_inset Tabular
+<lyxtabular version="3" rows="1" columns="2">
+<features>
+<column alignment="left" valignment="top" leftline="true" width="1.75in">
+<column alignment="left" valignment="top" leftline="true" rightline="true" width="3.5in">
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+num_perturbations=1
+\newline
+perturbmag=0.05
+\newline
+perturbl=1 
+\newline
+perturbm=1  
+\newline
+perturblayer=5
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+The initial temperature is a linear temperature gradient with some perturbations.
+ num_perturbations specifies the number of perturbations.
+ The amplitude of the perturbations is specified in the list of real numbers
+ by perturbmag.
+ In fullCitComS, perturbl and perturbm specify the shape of the perturbations
+ in spherical harmonic degree and order; perturblayer specifies the layers
+ to be perturbed.
+ In regitcoms , perturbl and preturbm specify the number of nodal lines
+ in longitudinal and latitudinal directions; perturblayer is not used though
+ the pertublayer represents the number of the mesh node in radiad direction.
+ There must be as many entries in a comma-separated list as in num_perturbations
+ .
+ No spaces are allowed in the list.
+ 
+\end_layout
+
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Section*
+Boundary Conditions
+\end_layout
+
+\begin_layout Standard
+\begin_inset Tabular
+<lyxtabular version="3" rows="5" columns="2">
+<features>
+<column alignment="left" valignment="top" leftline="true" width="1.75in">
+<column alignment="left" valignment="top" leftline="true" rightline="true" width="3.5in">
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+topvbc=0
+\newline
+topvbxval=0.0
+\newline
+topvbyval=0.0
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+Surface velocity boundary condition parameters.
+ If topvbc is 0, the topvbxval and topvbyval specify the tangential surface
+ stress (forced BC).
+ If topvbc is 1, topvbxval and topvbyval specify the tangential surface
+ velocity (fixed BC).
+ The surface normal velocity is zero in these two cases (impermeable BC).
+ If topvbc is 2, the surface normal and tangential stress are zero (permeable
+ BC).
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+botvbc=0
+\newline
+botvbxval=0.0
+\newline
+botvbyval=0.0
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+As above, but for bottom velocity boundary conditions.
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+toptbc=1
+\newline
+toptbcval=0.0 
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+Surface temperature boundary conditions.
+ If toptbc is 0, the toptbcval specifies the surface heatflux.
+ If toptbc is 1, the toptbcval specifies the surface temperature.
+ 
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+bottbc=1
+\newline
+bottbcval=1.0
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+As above, but for bottom temperature boundary conditions.
+ 
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+lith_age_time=0  lith_age_depth=0.031400  mantle_temp=1.000000  temperature_bound_
+adj=0  depth_bound_adj=0.157000  width_bound_adj=0.087270 
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+Boundary condition when lith_age is true.
+\end_layout
+
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Section*
+Miscellaneous
+\end_layout
+
+\begin_layout Standard
+The following are some miscellaneous parameters.
+\end_layout
+
+\begin_layout Standard
+\noindent
+\begin_inset Tabular
+<lyxtabular version="3" rows="2" columns="2">
+<features>
+<column alignment="left" valignment="top" leftline="true" width="1.75in">
+<column alignment="left" valignment="top" leftline="true" rightline="true" width="3.5in">
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+stokes_flow_only=0 inputdiffusivity= 0.001000
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+stokes_flow_only is a parameter which can lead to confusion.
+ If you wish only to solve for the velocity once (e.g.
+ Stokes flow) than set then make this parameter true (i.e.
+ ,1 or on).
+ However, you want to do convection problem then this should be false, as
+ indicated in the example.
+ At this point, don't change the parameter inputdiffusivity-this may play
+ a role in problems which are integrated backward in time.
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+rayleigh=1.357e+08 
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+This specifies the Rayleigh number, which is one of the most important parameter
+s you may want to change.
+ It is defined as Q0=0.0 This specifies the internal heating number.
+ 
+\end_layout
+
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Section*
+Required Information
+\end_layout
+
+\begin_layout Standard
+\begin_inset Tabular
+<lyxtabular version="3" rows="1" columns="2">
+<features>
+<column alignment="left" valignment="top" leftline="true" width="1.75in">
+<column alignment="left" valignment="top" leftline="true" rightline="true" width="3.5in">
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+Problem=convection
+\newline
+Geometry=sphere
+\newline
+Spacing=regular 
+\newline
+Solver=cgrad 
+\newline
+node_assemble=1
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+For the version of CitComS you received in your distribution, all of these
+ parameters must be set as indicated.
+ You need other versions of CitComS if you wish these parameters to take
+ on different geometries, problems, mesh spacing or use different solvers.
+\end_layout
+
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Section*
+Depth Information
+\end_layout
+
+\begin_layout Standard
+\begin_inset Tabular
+<lyxtabular version="3" rows="1" columns="2">
+<features>
+<column alignment="left" valignment="top" leftline="true" width="1.75in">
+<column alignment="left" valignment="top" leftline="true" rightline="true" width="3.5in">
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+z_lith=0.014
+\newline
+z_410=0.06435
+\newline
+z_lmantle=0.105
+\newline
+z_cmb=0.439
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+Specify the non-dimensional depth of Moho, 410km discontinuity, 660km discontinu
+ity and D".
+ These parameters are used to determine the depth of material interfaces
+ and phase changes (see next two sections).
+ The names are only suggestive.
+ You are free to refer z_lith to an arbitrary depth, for example.
+\end_layout
+
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Section*
+Viscosity
+\end_layout
+
+\begin_layout Standard
+Parameters which control the viscosity.
+ 
+\end_layout
+
+\begin_layout Standard
+\noindent
+\begin_inset Tabular
+<lyxtabular version="3" rows="7" columns="2">
+<features>
+<column alignment="left" valignment="top" leftline="true" width="1.75in">
+<column alignment="left" valignment="top" leftline="true" rightline="true" width="3.5in">
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+Viscosity=system
+\newline
+rheol=3 
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+For the version of CitComS you received in your distribution, all of these
+ parameters must be set as indicated.
+ When rheol=3, temperature dependent viscosity is computed by: viscosity
+ = visc0 * exp( viscE/(T+viscT) - viscE/(1+viscT) ) 
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+visc_smooth_method=3 
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+This specifies which method to smooth viscosity projection for multigrid
+ solver.
+ 
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+VISC_UPDATE=on 
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+If visc_update is true (e.g., 1 or on), viscosity is updated every time step
+ by the following parameters.
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+num_mat=4
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+This specifies the number of material layers.
+ Material 1 is at depth between 0 and z_lith, material 2 is between z_lith
+ and z_410, material 3 is between z_410 and z_lmantle, and material 4 is
+ between z_lmantle and (radius_outer - radius_inner).
+ If mat_control is true, then a multiplicative factor is applied to the
+ viscosity, as defined below.
+ 
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+TDEPV=on  viscE=0.1,0.1,1.0,1.0  viscT=-1.02126,-1.01853, -1.32722,-1.32722
+\newline
+visc0=1.0e2,2.e
+-3, 2.e0,2.e1
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+If TDEPV is true (e.g., 1 or on), viscE, viscT, and visc0 are parameters defining
+ viscosity law.
+ See the equation above.
+ There must be as many entries in a comma-separated list as num_mat.
+ No space is allowed in the list.
+ 
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+SDEPV=off  sdepv_expt=1,1,1,1,1,1,1,1 sdepv_misfit=0.020
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+If SDEPV is true (e.g., 1 or on), these specify the exponent in the viscosity
+ law and the criterion of convergence test.
+ There must be as many entries in a comma-separated list as num_mat.
+ No space is allowed in the list.
+ 
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+VMIN=on visc_min=1.e-4 VMAX=on visc_max=1.e3
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+If VMIN is true (e.g., 1 or on), minimum viscosity is cut off at visc_min.
+ VMAX and visc_max are for the maximum viscosity cutoff.
+ 
+\end_layout
+
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Section*
+Phase Change Information
+\end_layout
+
+\begin_layout Standard
+\begin_inset Tabular
+<lyxtabular version="3" rows="3" columns="2">
+<features>
+<column alignment="left" valignment="top" leftline="true" width="1.75in">
+<column alignment="left" valignment="top" leftline="true" rightline="true" width="3.5in">
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+Ra_410=0.0
+\newline
+clapeyron410=0.0235
+\newline
+transT410=0.78
+\newline
+width410=0.0058 
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+These specify the phase change parameters (density change, Clapeyron slope,
+ ambient temperature, and phase change width, respectively).
+ The depth of this phase change is specified by z_410.
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+Ra_670=0.0
+\newline
+clapeyron670=-0.0235
+\newline
+transT670=0.875
+\newline
+width670=0.0058
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+As above.
+ The depth of this phase change is specified by z_lmantle.
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+Ra_cmb=0.0
+\newline
+clapeyroncmb=-0.0235
+\newline
+transTcmb=0.875
+\newline
+widthcmb=0.0058
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+As above.
+ The depth of this phase change is specified by z_cmb.
+\end_layout
+
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Section*
+Dimensional Information
+\end_layout
+
+\begin_layout Standard
+\begin_inset Tabular
+<lyxtabular version="3" rows="1" columns="2">
+<features>
+<column alignment="left" valignment="top" leftline="true" width="1.75in">
+<column alignment="left" valignment="top" leftline="true" rightline="true" width="3.5in">
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+layerd=6371e3
+\newline
+density=3500.0
+\newline
+thermdiff=1.0e-6
+\newline
+gravacc=10.0
+\newline
+thermexp=3.0e-5
+\newline
+refvisc=1e21
+\newline
+cp
+=1250
+\newline
+wdensity=0.0 
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+Various dimensional information.
+ 
+\end_layout
+
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Section*
+Data input and program debugging
+\end_layout
+
+\begin_layout Standard
+\begin_inset Tabular
+<lyxtabular version="3" rows="3" columns="2">
+<features>
+<column alignment="left" valignment="top" leftline="true" width="1.75in">
+<column alignment="left" valignment="top" leftline="true" rightline="true" width="3.5in">
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+DESCRIBE=off  BEGINNER=off 
+\newline
+VERBOSE=off
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+These parameters affect the echo behavior of CitComS parser.
+ 
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+verbose=off 
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+This is used for debugging.
+ If verbose is true, additional information is output to .info file.
+ 
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+see_convergence=1 
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+If see_convergence is true, the velocity residual will be output on the
+ screen for every iteration.
+\end_layout
+
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Section*
+Solver Related Parameters
+\end_layout
+
+\begin_layout Standard
+\begin_inset Tabular
+<lyxtabular version="3" rows="10" columns="2">
+<features>
+<column alignment="left" valignment="top" leftline="true" width="1.75in">
+<column alignment="left" valignment="top" leftline="true" rightline="true" width="3.5in">
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+mg_cycle=1
+\newline
+down_heavy=3
+\newline
+up_heavy=3
+\newline
+vlowstep=2000
+\newline
+vhighstep=3
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+Multigrid parameters.
+ 
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+piterations=375
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+Maximum iterations for momentum solver.
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+accuracy=1.0e-6  tole_compressibility=1.0e-7
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+Convergence criterion for momentum solver.
+ 
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+ADV=on
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+If true, solve energy equation.
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+fixed_timestep=0.0 
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+Set fixed time step.
+ If it is 0, the size of time step is variable and is determined dynamically.
+ 
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+finetunedt=0.7
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+Set fraction of maximum advection time step.
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+adv_sub_iterations=2
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+Set the numbers of iteration for energy solver.
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+maxadvtime=10
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+Maximum elapsed non-dimensional advection time.
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+precond=on
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+Pre-conditioning flag.
+ 
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+aug_lagr=on aug_number=2.0e3
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+Augmented stiff matrix flag and value.
+\end_layout
+
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Section*
+Age Information
+\end_layout
+
+\begin_layout Standard
+\begin_inset Tabular
+<lyxtabular version="3" rows="2" columns="2">
+<features>
+<column alignment="left" valignment="top" leftline="true" width="1.75in">
+<column alignment="left" valignment="top" leftline="true" rightline="true" width="3.5in">
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+start_age=40.0
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+Set initial age (in Myrs).
+ This age determines which vel_bound_file and mat_file to read in.
+ 
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+reset_startage=0 
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+If reset_startage is true, the initial age is set to start_age.
+ If it is false and restart or post_p is true, the initial age is read in
+ from previous output.
+ 
+\end_layout
+
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Section*
+Spherical Harmonics Information
+\end_layout
+
+\begin_layout Standard
+\begin_inset Tabular
+<lyxtabular version="3" rows="1" columns="2">
+<features>
+<column alignment="left" valignment="top" leftline="true" width="1.75in">
+<column alignment="left" valignment="top" leftline="true" rightline="true" width="3.5in">
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+ll_max=20
+\newline
+output_ll_max=20
+\newline
+nlong=361
+\newline
+nlati=181 
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+These parameters control the resolution of spherical harmonics.
+ Currently not used.
+ 
+\end_layout
+
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Section*
+launcher
+\end_layout
+
+\begin_layout Standard
+Launcher is a Pyre facility that controls how CitComS.py, an MPI application,
+ is executed on multiple processors.
+ It is the equivalent to mpirun in MPICH.
+ 
+\end_layout
+
+\begin_layout Standard
+\noindent
+\begin_inset Tabular
+<lyxtabular version="3" rows="5" columns="2">
+<features>
+<column alignment="left" valignment="top" leftline="true" width="1.75in">
+<column alignment="left" valignment="top" leftline="true" rightline="true" width="3.5in">
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+dry
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+If on, print command line and exit.
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+nodegen
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+A printf-style format string, used in conjunction with nodelist to generate
+ list of machine names.
+ Example: 
+\family typewriter
+n%&Oslash;3d
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+nodelist 
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+A comma-separated list of machine names in square brackets.
+ Example: 
+\family typewriter
+ [101-103,105,107] 
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+nodes
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+Number of machine nodes.
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+machinefile
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+Filename of machine file.
+\end_layout
+
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Section*
+journal 
+\end_layout
+
+\begin_layout Standard
+journal is a Pyre facility that provides five types of debugging output
+ for conceptually different types of information.
+ The journal output stream can be instantiated as separated channels multiple
+ times, and each channel can be individually activated or de-activated,
+ and sent to different locations (the terminal, sockets, files, devices,
+ etc.).
+ The streams and their default states of the journal streams are: 
+\newline
+
+\begin_inset Tabular
+<lyxtabular version="3" rows="5" columns="2">
+<features>
+<column alignment="left" valignment="top" leftline="true" rightline="true" width="1.75in">
+<column alignment="left" valignment="top" rightline="true" width="3.5in">
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+debug
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+Filename of machine file.
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+error
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+Unrecoverable runtime error.
+ Default on.
+ 
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+firewall
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+Fatal programming error.
+ Default on.
+ 
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+info
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+Descriptive information.
+ Default off.
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+warning
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+Recoverable runtime error.
+ Default off.
+\end_layout
+
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+\noindent
+
+\end_layout
+
+\begin_layout Standard
+The journal facility is not used in the uncoupled CitComS solver.
+ For coupled solvers, the are many debugging information that output through
+ journal facility.
+ They can be turned on/off with command line options.
+ The most important ones are  
+\family typewriter
+journal.debug.Exchanger
+\family default
+  and 
+\family typewriter
+journal.debug.CitComSExchanger
+\family default
+.
+  Try running the scripts with
+\end_layout
+
+\begin_layout LyX-Code
+
+\family typewriter
+--journal.debug.Exchanger=on --journal.debug.CitComSExchanger=on 
+\end_layout
+
+\begin_layout Section*
+controller
+\end_layout
+
+\begin_layout Standard
+\begin_inset Tabular
+<lyxtabular version="3" rows="1" columns="2">
+<features>
+<column alignment="left" valignment="top" leftline="true" width="1.75in">
+<column alignment="left" valignment="top" leftline="true" rightline="true" width="3.5in">
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+monitoringFrequency=100
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+The time step interval between disk output.
+ It replaces the storage_spacing parameter in the (old) CitComS input file.
+\end_layout
+
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Section*
+solver 
+\end_layout
+
+\begin_layout Standard
+\begin_inset Tabular
+<lyxtabular version="3" rows="16" columns="2">
+<features>
+<column alignment="left" valignment="top" leftline="true" width="1.75in">
+<column alignment="left" valignment="top" leftline="true" rightline="true" width="3.5in">
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+mesher 
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+Can be either full-sphere or regional-sphere.
+ It is set by the solver facility automatically.
+ 
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+tsolver 
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+A temperature solver using Petrov-Galerkin time integration.
+ 
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+vsolver 
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+A velocity solver using Bousinessq approximation and Uzawa algorithm.
+ 
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+bc 
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+Boundary conditions.
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+const
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+Dimensional constants.
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+ic
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+Initial conditions.
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+param
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+Some additional input parameter files.
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+phase 
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+Phase change.
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+visc
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+Viscosity.
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+datafile
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+default="regtest"
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+datafile_old
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+default="regtest"
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+rayleigh
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+default=1e+08
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+Q0 =0
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+stokes_flow_only =0 
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+verbos =0 
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+see_convergence =1
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Section*
+solver.mesher
+\end_layout
+
+\begin_layout Standard
+Available properties and default values include:
+\end_layout
+
+\begin_layout Standard
+\noindent
+\begin_inset Tabular
+<lyxtabular version="3" rows="20" columns="2">
+<features>
+<column alignment="left" valignment="top" leftline="true" width="1.75in">
+<column alignment="left" valignment="top" leftline="true" rightline="true" width="3.5in">
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+nproc_surf=1
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+nprocx=1
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+nprocy=1
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+nprocz=1 
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+coor=0 
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+coor_file="coor.dat"
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+nodex=9
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+nodey=9
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+nodez=9
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+levels=1 
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+radius_outer=1
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+radius_inner=0.55
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+theta_min=1.5
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+theta_max=1.8
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+fi_min=0 
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+fi_max=0.4
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+ll_max=20 
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+nlong=361
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+nlati=181
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+output_ll_max=20
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Section*
+solver.tsolver
+\end_layout
+
+\begin_layout Standard
+Available properties and default values include: 
+\end_layout
+
+\begin_layout Standard
+\noindent
+\begin_inset Tabular
+<lyxtabular version="3" rows="8" columns="2">
+<features>
+<column alignment="left" valignment="top" leftline="true" width="1.75in">
+<column alignment="left" valignment="top" leftline="true" rightline="true" width="3.5in">
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+inputdiffusivity=1
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+ADV=1
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+fixed_timestep=0
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+finetunedt=0.9
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+adv_sub_iterations=2
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+maxadvtime=10
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+aug_lagr=1
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+aug_number=2000
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Section*
+solver.vsolver
+\end_layout
+
+\begin_layout Standard
+Available properties and default values include:
+\end_layout
+
+\begin_layout Standard
+\noindent
+\begin_inset Tabular
+<lyxtabular version="3" rows="10" columns="2">
+<features>
+<column alignment="left" valignment="top" leftline="true" width="1.75in">
+<column alignment="left" valignment="top" leftline="true" rightline="true" width="3.5in">
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+node_assemble=1
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+precond=1
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+accuracy=1e-06
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+tole_compressibility=1e-07
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+mg_cycle=1 
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+down_heavy=3
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+up_heavy=3
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+vlowstep=1000
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+vhighstep=3
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+piterations=1000
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Section*
+solver.bc 
+\end_layout
+
+\begin_layout Standard
+Available properties and default values include: it can be 0, 1, or 2 is
+ open top.
+ You cannot use "yes" or "no" for these values.
+\end_layout
+
+\begin_layout Standard
+\noindent
+\begin_inset Tabular
+<lyxtabular version="3" rows="14" columns="2">
+<features>
+<column alignment="left" valignment="top" leftline="true" width="1.75in">
+<column alignment="left" valignment="top" leftline="true" rightline="true" width="3.5in">
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+side_sbcs=0 
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+topvbc=0
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+topvbxval=0
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+topvbyval=0
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+botvbc=0
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+botvbxval=0
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+botvbyval=0
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+toptbc=1
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+toptbcval=0
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+bottbc=1
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+bottbcval=1
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+temperature_bound_adj=0
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+depth_bound_adj=0.157
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+width_bound_adj=0.08727
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Section*
+solver.const 
+\end_layout
+
+\begin_layout Standard
+Available properties and default values include:
+\end_layout
+
+\begin_layout Standard
+\noindent
+\begin_inset Tabular
+<lyxtabular version="3" rows="13" columns="2">
+<features>
+<column alignment="left" valignment="top" leftline="true" rightline="true" width="1.75in">
+<column alignment="left" valignment="top" rightline="true" width="3.5in">
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+layerd=6.371e+06
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+density=3500
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+thermdiff=1e-06
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+gravacc=10
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+thermexp=3e-05
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+refvisc=1e+21
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+cp=1250
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+wdensity=0
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+surftemp=273
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+depth_lith=89000
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+depth_410=410000
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+depth_660=660000
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+depth_cmb=2.691e+06
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Section*
+solver.ic 
+\end_layout
+
+\begin_layout Standard
+Available properties and default values include:
+\end_layout
+
+\begin_layout Standard
+\noindent
+\begin_inset Tabular
+<lyxtabular version="3" rows="9" columns="2">
+<features>
+<column alignment="left" valignment="top" leftline="true" width="1.75in">
+<column alignment="left" valignment="top" leftline="true" rightline="true" width="3.5in">
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+restart=0
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+post_p=0
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+solution_cycles_init=0
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+zero_elapsed_time=1
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+num_perturbations=1
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+perturbl=1
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+perturbm=1
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+perturblayer=5 
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+perturbmag=0.05
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Section*
+solver.param
+\end_layout
+
+\begin_layout Standard
+Available properties and default values include:
+\end_layout
+
+\begin_layout Standard
+\noindent
+\begin_inset Tabular
+<lyxtabular version="3" rows="13" columns="2">
+<features>
+<column alignment="left" valignment="top" leftline="true" width="1.75in">
+<column alignment="left" valignment="top" leftline="true" rightline="true" width="3.5in">
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+file_vbcs=0 
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+vel_bound_file="bvel.dat"
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+mat_control=0
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+mat_file="mat.dat"
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+lith_age=0
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+lith_age_file="age.dat"
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+lith_age_time=0
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+lith_age_depth=0.0314
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+mantle_temp=1
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+tracer=0
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+tracer_file="tracer.dat"
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+start_age=40 
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+reset_startage=0
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Section*
+solver.phase
+\end_layout
+
+\begin_layout Standard
+Available properties and default values include:
+\end_layout
+
+\begin_layout Standard
+\noindent
+\begin_inset Tabular
+<lyxtabular version="3" rows="12" columns="2">
+<features>
+<column alignment="left" valignment="top" leftline="true" width="1.75in">
+<column alignment="left" valignment="top" leftline="true" rightline="true" width="3.5in">
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+Ra_410=0 
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+clapeyron410=0.0235
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+transT410=0.78 
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+width410=0.0058
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+Ra_670=0
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+clapeyron670=-0.0235
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+transT670=0.78
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+width670=0.0058
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+Ra_cmb=0
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+clapeyroncmb=-0.0235
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+transTcmb=0.875
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+widthcmb=0.0058
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Section*
+solver.visc
+\end_layout
+
+\begin_layout Standard
+Available properties and default values include:
+\end_layout
+
+\begin_layout Standard
+\noindent
+\begin_inset Tabular
+<lyxtabular version="3" rows="16" columns="2">
+<features>
+<column alignment="left" valignment="top" leftline="true" width="1.75in">
+<column alignment="left" valignment="top" leftline="true" rightline="true" width="3.5in">
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+Viscosity="system"
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+rheol=3 
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+visc_smooth_method=3
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+VISC_UPDATE=on
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+num_mat=4
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+visc0=1,1,1,1,
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+TDEPV=0
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+viscE=1,1,1,1,
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+viscT=1,1,1,1, 
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+SDEPV=0
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+sdepv_misfit=0.02
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+sdepv_expt=1,1,1,1,
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+VMIN=0
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+visc_min=0.001
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+VMAX=0
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+visc_max=1000
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+ 
+\end_layout
+
+\begin_layout Chapter*
+Appendix B: CitComS Input Files Format
+\end_layout
+
+\begin_layout Section*
+Introduction
+\end_layout
+
+\begin_layout Standard
+CitComS expects Unix-styled ASCII files (i.e., no carriage character following
+ new line character) for all input files.
+ This can be a nuisance in DOS/Windows systems.
+ You may want to find a text editor that can write Unix-style ASCII files.
+ In the following, words in normal 
+\family typewriter
+courier
+\family default
+ must be input exactly as shown, while 
+\series bold
+bold
+\series default
+ words should be substituted by your values.
+ All parameters are in non-dimensional units unless specified.
+ 
+\end_layout
+
+\begin_layout Section*
+Coordinate files
+\end_layout
+
+\begin_layout Standard
+For 
+\family typewriter
+regCitComS
+\family default
+, the mesh must be regular, but the mesh spacing may be unequal.
+ The 
+\family typewriter
+coor_file
+\family default
+ has the format: 
+\end_layout
+
+\begin_layout LyX-Code
+nsd=1 
+\end_layout
+
+\begin_layout LyX-Code
+1 
+\series bold
+    theta1
+\series default
+ 
+\end_layout
+
+\begin_layout LyX-Code
+2 
+\series bold
+    theta2
+\end_layout
+
+\begin_layout LyX-Code
+...
+   ...
+ 
+\end_layout
+
+\begin_layout LyX-Code
+
+\series bold
+nodex theta_nodex
+\series default
+ 
+\end_layout
+
+\begin_layout LyX-Code
+nsd=2 
+\end_layout
+
+\begin_layout LyX-Code
+1 
+\series bold
+    phi1
+\series default
+ 
+\end_layout
+
+\begin_layout LyX-Code
+2 
+\series bold
+    phi2
+\series default
+ 
+\end_layout
+
+\begin_layout LyX-Code
+...
+   ...
+ 
+\end_layout
+
+\begin_layout LyX-Code
+
+\series bold
+nodey phi_nodey
+\series default
+ 
+\end_layout
+
+\begin_layout LyX-Code
+nsd=3 
+\end_layout
+
+\begin_layout LyX-Code
+1 
+\series bold
+    r1
+\series default
+ 
+\end_layout
+
+\begin_layout LyX-Code
+2 
+\series bold
+    r2
+\series default
+ 
+\end_layout
+
+\begin_layout LyX-Code
+...
+   ...
+ 
+\end_layout
+
+\begin_layout LyX-Code
+
+\series bold
+nodez r_nodez
+\end_layout
+
+\begin_layout Standard
+For 
+\family typewriter
+fullCitComS
+\family default
+, the mesh must be regular and equidistant in the horizontal dimension.
+ Only vertical dimension is specified by 
+\family typewriter
+coor_file
+\family default
+.
+ The 
+\family typewriter
+coor_file
+\family default
+ has the format:
+\end_layout
+
+\begin_layout LyX-Code
+nsd=3 
+\end_layout
+
+\begin_layout LyX-Code
+1 
+\series bold
+    r1
+\series default
+ 
+\end_layout
+
+\begin_layout LyX-Code
+2 
+\series bold
+    r2
+\series default
+ 
+\end_layout
+
+\begin_layout LyX-Code
+...
+   ...
+ 
+\end_layout
+
+\begin_layout LyX-Code
+
+\series bold
+nodez r_nodez
+\end_layout
+
+\begin_layout Section*
+Velocity boundary condition files
+\end_layout
+
+\begin_layout Standard
+If 
+\family typewriter
+vel_bound_file
+\family default
+ is set to 
+\family typewriter
+bvel.dat
+\family default
+, then is necessary to have one 
+\family typewriter
+bvel.dat
+\family default
+ file for each million year interval.
+ For example, if 
+\family typewriter
+start_age=83
+\family default
+, then the following files are needed:  
+\end_layout
+
+\begin_layout LyX-Code
+bvel.dat84 
+\end_layout
+
+\begin_layout LyX-Code
+bvel.dat83 
+\end_layout
+
+\begin_layout LyX-Code
+bvel.dat82 
+\end_layout
+
+\begin_layout LyX-Code
+...
+ 
+\end_layout
+
+\begin_layout LyX-Code
+bvel.dat0
+\end_layout
+
+\begin_layout Standard
+TIP: Even through the model starts at 83 million years before present, by
+ default it will attempt to read in both a file for 84 and a file for 83
+ million years ago.
+ To deal with this just create a duplicate copy of 
+\family typewriter
+bvel.dat83
+\family default
+ and call it 
+\family typewriter
+bvel.d
+\family default
+ 
+\end_layout
+
+\begin_layout LyX-Code
+
+\series bold
+Vx Vy
+\end_layout
+
+\begin_layout Section*
+Material files
+\end_layout
+
+\begin_layout Standard
+If 
+\family typewriter
+mat_file
+\family default
+ is set to 
+\family typewriter
+mat.dat
+\family default
+, then is necessary to have one mat.dat file for each million year interval.
+ For example, if 
+\family typewriter
+start_age=83
+\family default
+, then the following files are needed: 
+\end_layout
+
+\begin_layout LyX-Code
+mat.dat84 
+\end_layout
+
+\begin_layout LyX-Code
+mat.dat83 
+\end_layout
+
+\begin_layout LyX-Code
+mat.dat82 
+\end_layout
+
+\begin_layout LyX-Code
+...
+ 
+\end_layout
+
+\begin_layout LyX-Code
+mat.dat0
+\end_layout
+
+\begin_layout Standard
+The same note about 
+\family typewriter
+vel_bound_file
+\family default
+ (see above) applies.
+ The format of 
+\family typewriter
+mat_file
+\family default
+ is: 
+\end_layout
+
+\begin_layout LyX-Code
+
+\series bold
+n viscosity_factor
+\end_layout
+
+\begin_layout Section*
+Lithosphere Age Files
+\end_layout
+
+\begin_layout Standard
+If 
+\family typewriter
+lith_age_file
+\family default
+ is set to 
+\family typewriter
+lith.dat
+\family default
+, then is necessary to have one 
+\family typewriter
+bvel.dat
+\family default
+ file for each million year interval.
+ For example, if 
+\family typewriter
+start_age=83
+\family default
+, then the following files are needed: 
+\end_layout
+
+\begin_layout LyX-Code
+lith.dat84
+\end_layout
+
+\begin_layout LyX-Code
+lith.dat83 
+\end_layout
+
+\begin_layout LyX-Code
+lith.dat82 
+\end_layout
+
+\begin_layout LyX-Code
+...
+ 
+\end_layout
+
+\begin_layout LyX-Code
+lith.dat0
+\end_layout
+
+\begin_layout Standard
+The same note about 
+\family typewriter
+vel_bound_file
+\family default
+ (see above) still applies.
+ The input age is in million years.
+ The format of 
+\family typewriter
+lith_age_file
+\family default
+ is: 
+\end_layout
+
+\begin_layout LyX-Code
+
+\series bold
+n age
+\end_layout
+
+\begin_layout Section*
+Tracer Files
+\end_layout
+
+\begin_layout Standard
+In this version of CitComS, the implementation of tracer is neither parallelized
+, nor has it been tested.
+ We strongly advise you not to use this feature.
+ The format of 
+\family typewriter
+tracer_file
+\family default
+ is described here for completion: 
+\end_layout
+
+\begin_layout LyX-Code
+num_tracers 
+\end_layout
+
+\begin_layout LyX-Code
+type x y z
+\end_layout
+
+\begin_layout Chapter*
+Appendix C: CitComS,
+\family typewriter
+ retrieve
+\family default
+ Output Files Format
+\end_layout
+
+\begin_layout Section*
+Introduction
+\end_layout
+
+\begin_layout Standard
+All outputs are in non-dimensional unit unless specified.
+\end_layout
+
+\begin_layout Section*
+Postprocessed Output
+\end_layout
+
+\begin_layout Standard
+The 
+\family typewriter
+autocombine.py
+\family default
+ and 
+\family typewriter
+batchcombine.py
+\family default
+ produces 1 cap file for regional CitcomS and 12 cap files for full CitcomS,
+ for example 
+\family typewriter
+test-case.cap0.10
+\family default
+.
+ The first line of the cap file is a comment describing the node geometry
+ (
+\family typewriter
+nodex
+\family default
+ x 
+\family typewriter
+nodey
+\family default
+ x 
+\family typewriter
+nodez
+\family default
+).
+ The rest of the file is column-based, where the meaning of each column
+ is: 
+\end_layout
+
+\begin_layout LyX-Code
+colatitude longitude radius vel_colat vel_lon vel_r temperature viscosity
+\end_layout
+
+\begin_layout Section*
+CitComS Output
+\end_layout
+
+\begin_layout Standard
+The format of the raw output of CitComS.py is described here.
+ In the following sections, the model prefix is assumed as 
+\family typewriter
+test-case
+\family default
+, the processor number as 0, and the time step as 10.
+ 
+\end_layout
+
+\begin_layout Subsection*
+Time Output (test-case.time)
+\end_layout
+
+\begin_layout Standard
+It reports non-dimensional elapsed model time and spent CPU time (in seconds).
+ Only outputted on computer node 0.
+ The meaning of each column is: 
+\end_layout
+
+\begin_layout LyX-Code
+step total_t delta_t total_cpu_time step_cpu_time 
+\end_layout
+
+\begin_layout Subsection*
+Coordinate Output (test-case.coord.0)
+\end_layout
+
+\begin_layout Standard
+Only outputted at 0th time step.
+ The first line is a header.
+ The rest of the file is column-based, where the meaning of each column
+ is: 
+\end_layout
+
+\begin_layout LyX-Code
+colatitude longitude radius
+\end_layout
+
+\begin_layout Subsection*
+Velocity and Temperature Output (test-case.velo.0.10)
+\end_layout
+
+\begin_layout Standard
+The two lines are headers.
+ The rest of the file is column-based, where the meaning of each column
+ is: 
+\end_layout
+
+\begin_layout LyX-Code
+vel_colat vel_lon vel_r temperature
+\end_layout
+
+\begin_layout Subsection*
+Viscosity Output (test-case.visc.0.10)
+\end_layout
+
+\begin_layout Standard
+The first line is a header.
+ The rest of the file is column-based, where the meaning of each column
+ is: 
+\end_layout
+
+\begin_layout LyX-Code
+viscosity
+\end_layout
+
+\begin_layout Subsection*
+Material Output (test-case.mat.0)
+\end_layout
+
+\begin_layout Standard
+Only output at 0th time step.
+ There is no header.
+ The meaning of each column is: 
+\end_layout
+
+\begin_layout LyX-Code
+node_number layer material
+\end_layout
+
+\begin_layout Subsection*
+Surface Variables Output (test-case.surf.0.10 and test-case.botm.0.10)
+\end_layout
+
+\begin_layout Standard
+The first line is a header.
+ The rest of the file is column-based, where the meaning of each column
+ is: 
+\end_layout
+
+\begin_layout LyX-Code
+topography heatflux vel_colat vel_lon
+\end_layout
+
+\begin_layout Bibliography
+
+\bibitem [1]{Moresi et al Plate tectonics}
+Moresi, L., Gurnis, M.
+ and Zhong, S.
+ Plate tectonics and convection in the Earth's mantle: Toward a numerical
+ simulation.
+ 
+\emph on
+Comp.
+ Sci.
+ Engin.
+ 
+\series bold
+\emph default
+2
+\series default
+, 22-33 (2000).
+\end_layout
+
+\begin_layout Bibliography
+
+\bibitem [2]{Moresi/Solomatov Numerical}
+Moresi, L.
+ N.
+ and Solomatov, V.
+ S.
+ Numerical investigation of 2D convection with extremely large viscosity
+ variations.
+ 
+\emph on
+Phys.
+ Fluid
+\emph default
+ 
+\series bold
+7
+\series default
+, 2,154-2,162 (1995).
+\end_layout
+
+\begin_layout Bibliography
+
+\bibitem [3]{Moresi/Gurnis Contraints}
+Moresi, L.
+ N.
+ and Gurnis, M.
+ Constraints on the lateral strength of slabs from three-dimensional dynamic
+ flow models.
+ 
+\emph on
+Earth Planet.
+ Sci.
+ Lett.
+
+\emph default
+ 
+\series bold
+138
+\series default
+, 15-28 (1996).
+\end_layout
+
+\begin_layout Bibliography
+
+\bibitem [4]{Zhong/Moresi The role of faults}
+Zhong, S., Gurnis, M.
+ and Moresi, L.
+ The role of faults, nonlinear rheology, and viscosity structure in generating
+ plates from instantaneous mantle flow models.
+ 
+\emph on
+J.
+ Geophys.
+ Res.
+
+\emph default
+ 
+\series bold
+103
+\series default
+, 15,255-15,268 (1998).
+\end_layout
+
+\begin_layout Bibliography
+
+\bibitem [5]{Zhong et al The role of temperature}
+Zhong, S., Zuber, M.
+ T., Moresi, L.
+ N.
+ and Gurnis, M.
+ The role of temperature-dependent viscosity and surface plates in spherical
+ shell models of mantle convection.
+ 
+\emph on
+J.
+ Geophys.
+ Res.
+ 
+\series bold
+\emph default
+105
+\series default
+, 11,063-11,082 (2000).
+\end_layout
+
+\begin_layout Bibliography
+
+\bibitem [6]{Tan et al Slabs in the lower}
+Tan, E., Gurnis, M.
+ and Han, L.
+ Slabs in the lower mantle and their modulation of plume formation.
+ 
+\emph on
+Geochem.
+ Geophys.
+ Geosyst.
+
+\emph default
+ 
+\series bold
+3
+\series default
+, 1067 (2002).
+\end_layout
+
+\begin_layout Bibliography
+
+\bibitem [7]{Conrad/Gurnis Seismic tomography}
+Conrad, C.
+ P.
+ and Gurnis, M.
+ Seismic tomography, surface uplift, and the breakup of Gondwanaland: Integratin
+g mantle convection backwards in time.
+ 
+\emph on
+Geochem., Geophys., Geosys.
+
+\emph default
+ (2001).
+\end_layout
+
+\begin_layout Bibliography
+
+\bibitem [8]{Hughes The Finite Element Method}
+Hughes, T.
+ J.
+ R.
+ 
+\emph on
+The Finite Element Method: Linear Static and Dynamic Finite Element Analysis
+\emph default
+ (Prentice-Hall, Inc., Englewood Cliffs, New Jersey, 1987).
+\end_layout
+
+\begin_layout Bibliography
+
+\bibitem [9]{Ramage/Wathen Iterative solution}
+Ramage, A.
+ and Wathen, A.
+ J.
+ Iterative solution techniques for the Stokes and Navier-Stokes equations.
+ 
+\emph on
+Int.
+ J.
+ Numer.
+ Methods.
+ Fluids
+\emph default
+ 
+\series bold
+19
+\series default
+, 67-83 (1994).
+\end_layout
+
+\begin_layout Bibliography
+
+\bibitem [10]{Brooks A.N.}
+Brooks, A.
+ N.
+
+\emph on
+ A Petrov-Galerkin Finite Element Formulation for Convecton Dominated Flows.
+
+\emph default
+ Unpublished doctoral thesis, California Institute of Technology, Pasadena,
+ CA, 1981.
+\end_layout
+
+\begin_layout Bibliography
+
+\bibitem [11]{Cahouet/Chabard Some fast 3D}
+Cahouet, J.
+ and Chabard, J.-P.
+ Some fast 3D finite element solvers for the generalized Stokes problem.
+ 
+\emph on
+Int.
+ J.
+ Numer.
+ Methods.
+ Fluids
+\emph default
+ 
+\series bold
+8
+\series default
+, 869-895 (1988).
+\end_layout
+
+\begin_layout Bibliography
+
+\bibitem [12]{Atanga/Silvester Iterative methods}
+Atanga, J.
+ and Silvester, D.
+ Iterative methods for stabilized mixed velocity-pressure finite elements.
+ 
+\emph on
+Int.
+ J.
+ Numer.
+ Methods.
+ Fluids
+\emph default
+ 
+\series bold
+14
+\series default
+, 71-81 (1992).
+\end_layout
+
+\begin_layout Bibliography
+
+\bibitem [13]{Hager/OConnell A simple global}
+Hager, B.
+ H.
+ and O'Connell, R.
+ J.
+ A simple global model of plate dynamics and mantle convection.
+ 
+\emph on
+J.
+ Geophys.
+ Res.
+
+\emph default
+ 
+\series bold
+86
+\series default
+, 4,843-4,867 (1981).
+\end_layout
+
+\begin_layout Bibliography
+
+\bibitem [14]{Tan et al GeoFramework Part I}
+Tan, E., Thoutireddy, P., Choi, E., Gurnis, M., and Aivazis, M., 2004, GeoFramework
+ Part I: Coupling Models of Mantle Convection with a Python Framework, in
+ preparation, 
+\emph on
+Geochemistry, Geophysics, Geosystems
+\emph default
+, 2004.
+\end_layout
+
+\begin_layout Bibliography
+
+\bibitem [15]{Zhong et al Free-surface formulation}
+Zhong, S., M.
+ Gurnis and L.
+ Moresi, Free-surface formulation of mantle convection--I.
+ Basic theory and appication to plumes, 
+\emph on
+Geophys.
+ J.
+ Int.
+
+\emph default
+ 
+\series bold
+127
+\series default
+, 708-718, 1996.
+\end_layout
+
+\begin_layout Bibliography
+
+\bibitem [16]{Zhong et al Three-dimensional}
+Zhong, S., A.
+ Paulson and J.
+ Wahr, Three-dimensional finite-element modeling of Earth's viscoelastic
+ deformation: effects of lateral variations in lithospheric thickness, 
+\emph on
+Geophys.
+ J.
+ Int.
+
+\emph default
+ 
+\series bold
+155
+\series default
+, 679-695, 2003.
+ 
+\end_layout
+
+\begin_layout Chapter*
+Appendix D: License  
+\end_layout
+
+\begin_layout Paragraph
+GNU GENERAL PUBLIC LICENSE Version 2, June 1991 Copyright (C) 1989, 1991
+ Free Software Foundation, Inc.
+ 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA 
+\end_layout
+
+\begin_layout Standard
+Everyone is permitted to copy and distribute verbatim copies of this license
+ document, but changing it is not allowed.
+\end_layout
+
+\begin_layout Section*
+Preamble
+\end_layout
+
+\begin_layout Standard
+The licenses for most software are designed to take away your freedom to
+ share and change it.
+ By contrast, the GNU General Public License is intended to guarantee your
+ freedom to share and change free software--to make sure the software is
+ free for all its users.
+ This General Public License applies to most of the Free Software Foundation's
+ software and to any other program whose authors commit to using it.
+ (Some other Free Software Foundation software is covered by the GNU Library
+ General Public License instead.) You can apply it to your programs, too.
+\end_layout
+
+\begin_layout Standard
+When we speak of free software, we are referring to freedom, not price.
+ Our General Public Licenses are designed to make sure that you have the
+ freedom to distribute copies of free software (and charge for this service
+ if you wish), that you receive source code or can get it if you want it,
+ that you can change the software or use pieces of it in new free programs;
+ and that you know you can do these things.
+\end_layout
+
+\begin_layout Standard
+To protect your rights, we need to make restrictions that forbid anyone
+ to deny you these rights or to ask you to surrender the rights.
+ These restrictions translate to certain responsibilities for you if you
+ distribute copies of the software, or if you modify it.
+\end_layout
+
+\begin_layout Standard
+For example, if you distribute copies of such a program, whether gratis
+ or for a fee, you must give the recipients all the rights that you have.
+ You must make sure that they, too, receive or can get the source code.
+ And you must show them these terms so they know their rights.
+\end_layout
+
+\begin_layout Standard
+We protect your rights with two steps:
+\end_layout
+
+\begin_layout Enumerate
+copyright the software, and 
+\end_layout
+
+\begin_layout Enumerate
+offer you this license which gives you legal permission to copy, distribute
+ and/or modify the software.
+\end_layout
+
+\begin_layout Standard
+Also, for each author's protection and ours, we want to make certain that
+ everyone understands that there is no warranty for this free software.
+ If the software is modified by someone else and passed on, we want its
+ recipients to know that what they have is not the original, so that any
+ problems introduced by others will not reflect on the original authors'
+ reputations.
+\end_layout
+
+\begin_layout Standard
+Finally, any free program is threatened constantly by software patents.
+ We wish to avoid the danger that redistributors of a free program will
+ individually obtain patent licenses, in effect making the program proprietary.
+ To prevent this, we have made it clear that any patent must be licensed
+ for everyone's free use or not licensed at all.
+ 
+\end_layout
+
+\begin_layout Standard
+The precise terms and conditions for copying, distribution and modification
+ follow.
+\end_layout
+
+\begin_layout Section*
+GNU GENERAL PUBLIC LICENSE TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION
+ AND MODIFICATION 
+\end_layout
+
+\begin_layout Standard
+0.
+ This License applies to any program or other work which contains a notice
+ placed by the copyright holder saying it may be distributed under the terms
+ of this General Public License.
+ The "Program", below, refers to any such program or work, and a "work based
+ on the Program" means either the Program or any derivative work under copyright
+ law: that is to say, a work containing the Program or a portion of it,
+ either verbatim or with modifications and/or translated into another language.
+ (Hereinafter, translation is included without limitation in the term "modificat
+ion".) Each licensee is addressed as "you".
+ 
+\end_layout
+
+\begin_layout Standard
+Activities other than copying, distribution and modification are not covered
+ by this License; they are outside its scope.
+ The act of running the Program is not restricted, and the output from the
+ Program is covered only if its contents constitute a work based on the
+ Program (independent of having been made by running the Program).
+ Whether that is true depends on what the Program does.
+ 
+\end_layout
+
+\begin_layout Standard
+1.
+ You may copy and distribute verbatim copies of the Program's source code
+ as you receive it, in any medium, provided that you conspicuously and appropria
+tely publish on each copy an appropriate copyright notice and disclaimer
+ of warranty; keep intact all the notices that refer to this License and
+ to the absence of any warranty; and give any other recipients of the Program
+ a copy of this License along with the Program.
+ 
+\end_layout
+
+\begin_layout Standard
+You may charge a fee for the physical act of transferring a copy, and you
+ may at your option offer warranty protection in exchange for a fee.
+ 
+\end_layout
+
+\begin_layout Standard
+2.
+ You may modify your copy or copies of the Program or any portion of it,
+ thus forming a work based on the Program, and copy and distribute such
+ modifications or work under the terms of Section 1 above, provided that
+ you also meet all of these conditions: 
+\end_layout
+
+\begin_layout Standard
+a) You must cause the modified files to carry prominent notices stating
+ that you changed the files and the date of any change.
+ 
+\end_layout
+
+\begin_layout Standard
+b) You must cause any work that you distribute or publish, that in whole
+ or in part contains or is derived from the Program or any part thereof,
+ to be licensed as a whole at no charge to all third parties under the terms
+ of this License.
+ 
+\end_layout
+
+\begin_layout Standard
+c) If the modified program normally reads commands interactively when run,
+ you must cause it, when started running for such interactive use in the
+ most ordinary way, to print or display an announcement including an appropriate
+ copyright notice and a notice that there is no warranty (or else, saying
+ that you provide a warranty) and that users may redistribute the program
+ under these conditions, and telling the user how to view a copy of this
+ License.
+ (Exception: if the Program itself is interactive but does not normally
+ print such an announcement, your work based on the Program is not required
+ to print an announcement.) 
+\end_layout
+
+\begin_layout Standard
+These requirements apply to the modified work as a whole.
+ If identifiable sections of that work are not derived from the Program,
+ and can be reasonably considered independent and separate works in themselves,
+ then this License, and its terms, do not apply to those sections when you
+ distribute them as separate works.
+ But when you distribute the same sections as part of a whole which is a
+ work based on the Program, the distribution of the whole must be on the
+ terms of this License, whose permissions for other licensees extend to
+ the entire whole, and thus to each and every part regardless of who wrote
+ it.
+ 
+\end_layout
+
+\begin_layout Standard
+Thus, it is not the intent of this section to claim rights or contest your
+ rights to work written entirely by you; rather, the intent is to exercise
+ the right to control the distribution of derivative or collective works
+ based on the Program.
+ 
+\end_layout
+
+\begin_layout Standard
+In addition, mere aggregation of another work not based on the Program with
+ the Program (or with a work based on the Program) on a volume of a storage
+ or distribution medium does not bring the other work under the scope of
+ this License.
+ 
+\end_layout
+
+\begin_layout Standard
+3.
+ You may copy and distribute the Program (or a work based on it, under Section
+ 2) in object code or executable form under the terms of Sections 1 and
+ 2 above provided that you also do one of the following: 
+\end_layout
+
+\begin_layout Standard
+a) Accompany it with the complete corresponding machine-readable source
+ code, which must be distributed under the terms of Sections 1 and 2 above
+ on a medium customarily used for software interchange; or, 
+\end_layout
+
+\begin_layout Standard
+b) Accompany it with a written offer, valid for at least three years, to
+ give any third party, for a charge no more than your cost of physically
+ performing source distribution, a complete machine-readable copy of the
+ corresponding source code, to be distributed under the terms of Sections
+ 1 and 2 above on a medium customarily used for software interchange; or,
+ 
+\end_layout
+
+\begin_layout Standard
+c) Accompany it with the information you received as to the offer to distribute
+ corresponding source code.
+ (This alternative is allowed only for noncommercial distribution and only
+ if you received the program in object code or executable form with such
+ an offer, in accord with Subsection b above.) 
+\end_layout
+
+\begin_layout Standard
+The source code for a work means the preferred form of the work for making
+ modifications to it.
+ For an executable work, complete source code means all the source code
+ for all modules it contains, plus any associated interface definition files,
+ plus the scripts used to control compilation and installation of the executable.
+ However, as a special exception, the source code distributed need not include
+ anything that is normally distributed (in either source or binary form)
+ with the major components (compiler, kernel, and so on) of the operating
+ system on which the executable runs, unless that component itself accompanies
+ the executable.
+\end_layout
+
+\begin_layout Standard
+If distribution of executable or object code is made by offering access
+ to copy from a designated place, then offering equivalent access to copy
+ the source code from the same place counts as distribution of the source
+ code, even though third parties are not compelled to copy the source along
+ with the object code.
+ 
+\end_layout
+
+\begin_layout Standard
+4.
+ You may not copy, modify, sublicense, or distribute the Program except
+ as expressly provided under this License.
+ Any attempt otherwise to copy, modify, sublicense or distribute the Program
+ is void, and will automatically terminate your rights under this License.
+ However, parties who have received copies, or rights, from you under this
+ License will not have their licenses terminated so long as such parties
+ remain in full compliance.
+ 
+\end_layout
+
+\begin_layout Standard
+5.
+ You are not required to accept this License, since you have not signed
+ it.
+ However, nothing else grants you permission to modify or distribute the
+ Program or its derivative works.
+ These actions are prohibited by law if you do not accept this License.
+ Therefore, by modifying or distributing the Program (or any work based
+ on the Program), you indicate your acceptance of this License to do so,
+ and all its terms and conditions for copying, distributing or modifying
+ the Program or works based on it.
+ 
+\end_layout
+
+\begin_layout Standard
+6.
+ Each time you redistribute the Program (or any work based on the Program),
+ the recipient automatically receives a license from the original licensor
+ to copy, distribute or modify the Program subject to these terms and conditions.
+ You may not impose any further restrictions on the recipients' exercise
+ of the rights granted herein.
+ You are not responsible for enforcing compliance by third parties to this
+ License.
+ 
+\end_layout
+
+\begin_layout Standard
+7.
+ If, as a consequence of a court judgment or allegation of patent infringement
+ or for any other reason (not limited to patent issues), conditions are
+ imposed on you (whether by court order, agreement or otherwise) that contradict
+ the conditions of this License, they do not excuse you from the conditions
+ of this License.
+ If you cannot distribute so as to satisfy simultaneously your obligations
+ under this License and any other pertinent obligations, then as a consequence
+ you may not distribute the Program at all.
+ For example, if a patent license would not permit royalty-free redistribution
+ of the Program by all those who receive copies directly or indirectly through
+ you, then the only way you could satisfy both it and this License would
+ be to refrain entirely from distribution of the Program.
+\end_layout
+
+\begin_layout Standard
+If any portion of this section is held invalid or unenforceable under any
+ particular circumstance, the balance of the section is intended to apply
+ and the section as a whole is intended to apply in other circumstances.
+\end_layout
+
+\begin_layout Standard
+It is not the purpose of this section to induce you to infringe any patents
+ or other property right claims or to contest validity of any such claims;
+ this section has the sole purpose of protecting the integrity of the free
+ software distribution system, which is implemented by public license practices.
+ Many people have made generous contributions to the wide range of software
+ distributed through that system in reliance on consistent application of
+ that system; it is up to the author/donor to decide if he or she is willing
+ to distribute software through any other system and a licensee cannot impose
+ that choice.
+ 
+\end_layout
+
+\begin_layout Standard
+This section is intended to make thoroughly clear what is believed to be
+ a consequence of the rest of this License.
+ 
+\end_layout
+
+\begin_layout Standard
+8.
+ If the distribution and/or use of the Program is restricted in certain
+ countries either by patents or by copyrighted interfaces, the original
+ copyright holder who places the Program under this License may add an explicit
+ geographical distribution limitation excluding those countries, so that
+ distribution is permitted only in or among countries not thus excluded.
+ In such case, this License incorporates the limitation as if written in
+ the body of this License.
+ 
+\end_layout
+
+\begin_layout Standard
+9.
+ The Free Software Foundation may publish revised and/or new versions of
+ the General Public License from time to time.
+ Such new versions will be similar in spirit to the present version, but
+ may differ in detail to address new problems or concerns.
+ 
+\end_layout
+
+\begin_layout Standard
+Each version is given a distinguishing version number.
+ If the Program specifies a version number of this License which applies
+ to it and "any later version", you have the option of following the terms
+ and conditions either of that version or of any later version published
+ by the Free Software Foundation.
+ If the Program does not specify a version number of this License, you may
+ choose any version ever published by the Free Software Foundation.
+\end_layout
+
+\begin_layout Standard
+10.
+ If you wish to incorporate parts of the Program into other free programs
+ whose distribution conditions are different, write to the author to ask
+ for permission.
+ For software which is copyrighted by the Free Software Foundation, write
+ to the Free Software Foundation; we sometimes make exceptions for this.
+ Our decision will be guided by the two goals of preserving the free status
+ of all derivatives of our free software and of promoting the sharing and
+ reuse of software generally.
+ 
+\end_layout
+
+\begin_layout Subsection*
+NO WARRANTY 
+\end_layout
+
+\begin_layout Standard
+11.
+ BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR
+ THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW.
+ EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER
+ PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER
+ EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+ OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
+ THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH
+ YOU.
+ SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY
+ SERVICING, REPAIR OR CORRECTION.
+ 
+\end_layout
+
+\begin_layout Standard
+12.
+ IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL
+ ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE
+ THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING
+ ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF
+ THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS
+ OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR
+ THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
+ EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY
+ OF SUCH DAMAGES.
+\end_layout
+
+\begin_layout Section*
+END OF TERMS AND CONDITIONS 
+\end_layout
+
+\begin_layout Subsection*
+How to Apply These Terms to Your New Programs
+\end_layout
+
+\begin_layout Standard
+If you develop a new program, and you want it to be of the greatest possible
+ use to the public, the best way to achieve this is to make it free software
+ which everyone can redistribute and change under these terms.
+ 
+\end_layout
+
+\begin_layout Standard
+To do so, attach the following notices to the program.
+ It is safest to attach them to the start of each source file to most effectivel
+y convey the exclusion of warranty; and each file should have at least the
+ "copyright" line and a pointer to where the full notice is found.
+ 
+\end_layout
+
+\begin_layout Standard
+one line to give the program's name and a brief idea of what it does.
+ Copyright (C) (year) (name of author) 
+\end_layout
+
+\begin_layout Standard
+This program is free software; you can redistribute it and/or modify it
+ under the terms of the GNU General Public License as published by the Free
+ Software Foundation; either version 2 of the License, or (at your option)
+ any later version.
+ 
+\end_layout
+
+\begin_layout Standard
+This program is distributed in the hope that it will be useful, but WITHOUT
+ ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+ FOR A PARTICULAR PURPOSE.
+ See the GNU General Public License for more details.
+ 
+\end_layout
+
+\begin_layout Standard
+You should have received a copy of the GNU General Public License along
+ with this program; if not, write to the Free Software Foundation, Inc.,
+ 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA 
+\end_layout
+
+\begin_layout Standard
+Also add information on how to contact you by electronic and paper mail.
+ 
+\end_layout
+
+\begin_layout Standard
+If the program is interactive, make it output a short notice like this when
+ it starts in an interactive mode: 
+\end_layout
+
+\begin_layout Standard
+Gnomovision version 69, Copyright (C) year name of author Gnomovision comes
+ with ABSOLUTELY NO WARRANTY; for details type `show w'.
+ This is free software, and you are welcome to redistribute it under certain
+ conditions; type `show c' for details.
+ 
+\end_layout
+
+\begin_layout Standard
+The hypothetical commands `show w' and `show c' should show the appropriate
+ parts of the General Public License.
+ Of course, the commands you use may be called something other than `show
+ w' and `show c'; they could even be mouse-clicks or menu items--whatever
+ suits your program.
+ 
+\end_layout
+
+\begin_layout Standard
+You should also get your employer (if you work as a programmer) or your
+ school, if any, to sign a "copyright disclaimer" for the program, if necessary.
+ Here is a sample; alter the names: 
+\end_layout
+
+\begin_layout Standard
+Yoyodyne, Inc., hereby disclaims all copyright interest in the program `Gnomovisi
+on' (which makes passes at compilers) written by James Hacker.
+ (signature of Ty Coon), 1 April 1989 Ty Coon, President of Vice 
+\end_layout
+
+\begin_layout Standard
+This General Public License does not permit incorporating your program into
+ proprietary programs.
+ If your program is a subroutine library, you may consider it more useful
+ to permit linking proprietary applications with the library.
+ If this is what you want to do, use the GNU Library General Public License
+ instead of this License.
+\end_layout
+
+\end_body
+\end_document

Deleted: mc/3D/CitcomS/trunk/doc/manual/citcoms_book.xml
===================================================================
--- mc/3D/CitcomS/trunk/doc/manual/citcoms_book.xml	2006-08-02 00:17:49 UTC (rev 4201)
+++ mc/3D/CitcomS/trunk/doc/manual/citcoms_book.xml	2006-08-02 19:42:02 UTC (rev 4202)
@@ -1,4030 +0,0 @@
-
-<!DOCTYPE part PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
-  "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
-
-<book>
-    <bookinfo>
-        <title>CitComS.py Manual</title>
-        <author>
-            <firstname>05.15.06</firstname>
-            <surname></surname>
-        </author>
-        <copyright>
-            <year>2006</year>
-            <holder>California Institute of Technology</holder>
-        </copyright>
-    </bookinfo>
-    <part>
-        <title>Preface</title>
-        <preface>
-            <title>Preface</title>
-            <sect1>
-                <title>About This Document</title>
-                <para>This document is organized into three parts. Part I consists of traditional
-                    book front matter, including this preface. Part II begins with an introduction
-                    to Pyre and the Pyre-compatible version of CitComS and their capabilities and
-                    proceeds to the details of implementation, including a "cookbook" of short tutorials. Part III provides appendices and
-                    references. </para>
-                <para>The style of this publication is based on the <ulink
-                        url="http://developer.apple.com/documentation/UserExperience/Conceptual/APStyleGuide/ AppleStyleGuide2003.pdf">Apple Publications Style Guide</ulink>, as recommended by <ulink
-                        url="http://www.python.org">Python.org</ulink>. The documentation was
-                    produced using <ulink url="http://www.docbook.org">DocBook</ulink> to facilitate
-                    the transformation of files from one format to another. DocBook is an open
-                    source, XML (or SGML) Document Type Definition originally designed by O'Reilly
-                    and Associates and HaL Computer Systems to help convert UNIX documentation into
-                    an exchangeable format. If you are reading this document on the web, chances are
-                    it was generated using a modified version of the DocBook Website DTD, available
-                    through <ulink url="http://sourceforge.net/projects/docbook/"
-                    >SourceForge</ulink>.</para><para>Errors and bug fixes in this manual should be directed to <email>cig-mc at geodynamics.org</email>.</para>
-            </sect1>
-            <sect1>
-                <title>Who Will Use This Document</title>
-                <para>This documentation is aimed at scientists who prefer to use prepackaged and
-                    specialized analysis tools. Users are likely to be experienced computational
-                    earth scientists and have familiarity with basic scripting, software
-                    installation, and programming; but are not likely to be professional
-                    programmers. Of those, there are likely to be two classes of users: those who
-                    just run models and those who modify the source code. </para>
-                <para> The manual was written for the useage of CitComS.py
-                    on a variety of different platforms. CitComS has run on shared
-                    memory computers (Sun, Hewlett-Packard, SGI, and IBM), commercial distributed
-                    memory machines (Intel and Cray/SGI), and Beowulf implementations (including
-                    Beowulfs at the California Institute of Technology's Center for Advanced
-                    Computing Research and Seismological Laboratory, Sydney University, and the
-                    Geological Survey of Norway). </para>
-            </sect1>
-            <sect1>
-                <title>Citation</title>
-                <para>Computational Infrastructure for Geodynamics (CIG) is making this source code
-                    available to you in hopes that the software will enhance your
-                    research in geophysics. The underlying C code for the finite element package and the
-                    Python bindings for the framework 
-                    were donated to CIG in July of 2005. A number of individuals have contributed a significant
-                    portion of their careers toward the development of CitComS.py and Pyre. It is
-                    essential that you recognize these individuals in the normal scientific practice
-                    by citing the appropriate peer reviewed papers and making appropriate
-                    acknowledgements. </para>
-                <para>The CitComS development team asks that you cite both Zhong, S., Zuber, M. T.,
-                    Moresi, L. N. and Gurnis, M. The role of temperature-dependent viscosity and
-                    surface plates in spherical shell models of mantle convection. <emphasis>J.
-                        Geophys. Res.</emphasis>
-                    <emphasis role="bold">105</emphasis>, 11,063-11,082 (2000) and Tan, E.,
-                    Thoutireddy, P., Choi, E., Gurnis, M., and Aivazis, M., 2004, GeoFramework Part
-                    I: Coupling Models of Mantle Convection with a Python Framework, in preparation,
-                        <emphasis>Geochemistry, Geophysics, Geosystems</emphasis>, 2005. The
-                    developers also request that in your oral presentations and in your paper
-                    acknowledgements that you indicate your use of this code, the authors of the
-                    code, and <ulink url="http://www.geodynamics.org"
-                >CIG</ulink>.</para>
-            </sect1>
-            <sect1>
-                <title>Support</title>
-                <para> Pyre development is funded by the <ulink
-                        url="http://www.doe.gov/engine/content.do">Department of Energy's</ulink>
-                    Advanced Simulation and Computing program and the <ulink
-                        url="http://www.nsf.gov/">National Science Foundation's</ulink> Information
-                    Technology Research (ITR) program (grant #0205653). Continued support of CitComS.py is made possible under NSF EAR-0406751.</para>
-            </sect1>
-            <sect1>
-                <title>Conventions</title>
-                <para>Throughout this documentation CitComS.py refers to the Pyre-compatible version
-                    of CitComS unless specifically stated otherwise. Any mention of "username" is
-                    meant to indicate the user, meaning you should substitute your account name in
-                    its place.</para>
-            </sect1>           
-        </preface>
-    </part>
-    <part>
-        <title>Chapters</title>
-        <chapter>
-            <title>Introduction</title>
-            <sect1>
-                <title>Introduction</title>
-                <para>CitComS is a finite element code designed to solve thermal convection problems
-                    relevant to earth's mantle. Written in C, the code runs on a variety of parallel
-                    processing computers, including shared and distributed memory platforms. In an
-                    effort to increase the functionality of CitComS to include greater control
-                    during simulations on large parallel systems, the software has been reengineered
-                    from previous versions of CitComS to work with a Python-based modeling framework
-                    called Pyre. With Pyre, CitComS can be dynamically coupled with other CitComS
-                    simulations or with other codes such as SNAC, which solves crustal and
-                    lithospheric problems. </para></sect1>
-                <sect1>
-                    <title>About CitComS</title>
-                    <para>CitComS is a finite element code written in C that solves for thermal
-                        convection within a spherical shell. <filename>citcomsfull</filename> and
-                            <filename>citcomsregional</filename> are modifications of CitComS which
-                        solve for problems within a full spherical domain and a restricted domain of
-                        a full sphere, respectively. Although the code is capable of solving many
-                        different kinds of convection problems using the flexibility of finite
-                        elements, there are aspects of <filename>citcomsregional</filename> which
-                        make it well-suited for solving problems in which the plate tectonic history
-                        of a region is incorporated. CitComS.py allows easy use of either one of these two geometries by simply changing command line options.</para>
-                    <para> The fundamental basis for the numerical solution of any time-dependent
-                        convection problem is the sequential solution of an equation of motion and
-                        an energy equation. Convection problems are initially valued with boundary
-                        conditions, including all of the problems which are solved with
-                            CitComS.py. The normal sequence of steps for
-                        the solution of convection problems start with an initial temperature field.
-                        First, the momentum equation is solved. The solution of this equation gives
-                        us the velocity from which we then solve the advection-diffusion equation,
-                        giving us a new temperature. CitComS.py uses this
-                        interleaved strategy. It is possible to run aduction backward in time so as
-                        to guess an initial condition for a normal forward running initial and
-                        boundary value problem. However, users should be aware that even specialists
-                        in mantle convection modeling are just now starting to explore methods in
-                        this area and, as such, this is an emerging area of research. There are
-                        versions of CitCom which solve for these
-                        classes of forward and backward problems. Variable viscosity, including
-                        temperature-, pressure-, position-, composition-, and stress-dependent
-                        viscosity are all possible, although they may not be fully implemented in
-                        the current version.</para>
-                    <para> This code uses an iterative solution scheme to solve for the velocity and
-                        pressure and as such, a converged solution cannot be guaranteed. Currently,
-                        the code uses a conjugant gradient solver, although most of the coding for
-                        full multi-grid is contained within the source code, only the conjugate
-                        gradient solver has been implemented for use with an arbitrary number of
-                        processors.</para>
-                </sect1>
-                <sect1>
-                    <title>History</title>
-                    <para>CitCom (for <emphasis role="bold">C</emphasis>alifornia <emphasis
-                            role="bold">I</emphasis>nstitute of <emphasis role="bold"
-                        >T</emphasis>echnology <emphasis role="bold">C</emphasis>onvection in the
-                            <emphasis role="bold">M</emphasis>antle) was originally written in the
-                        early 1990's by Louis Moresi. Although the code for three-dimensional
-                        problems was incorporated from its inception, early versions of the software
-                        only solved for time-dependent convection problems within two-dimensional
-                        Cartesian domains. Moresi's original code turned out to be incredibly
-                        modular and easily extensible. Consequently, the fundamental finite element
-                        infrastructure which Louis wrote is still in place and forms the basis for
-                        much of the code contained in the present release.</para>
-                    <para> In the mid-1990's Moresi wrote versions of the code that solved the
-                        equations within three-dimensional Cartesian domains. Then Shijie Zhong
-                        successfully parallelized CitCom using message passing routines on a limited
-                        release Intel supercomputer. Zhong then created a spherical version of the
-                        code which he named CitComS. Lijie Han then created a regional version of
-                        CitComS as well as an alternate version of message passing for an
-                        arbitrarily large number of processors. Clint Conrad created the first
-                        Beowulf implementations of the code, then Conrad and Eh Tan re-coded the
-                        message passing of the fully spherical version so that problems run on
-                        arbitrarily large numbers of processors could also be solved. A plethora of
-                        different versions of CitCom exist both on computers at the California
-                        Institute of Technology and around the world. </para>
-                    <para> Consequently, by 2002, there were so many different versions of the code
-                        that some rationalization was in order. The software was migrated into a
-                        version control system and Eh Tan and Eun-seo Choi created a version of the
-                        CitComS that generates either a fully spherical or regional model,
-                            <filename>citcomsfull</filename> and
-                        <filename>citcomsregional</filename>, respectively. CitComS was released to the community through the <ulink url="http://www.geoframework.org">Geoframework</ulink> website as version 1.0 and 1.1.</para>
-                    <para> At this time, in order to increase the functionality of CitComS, the
-                        developers began to reengineer the code into an object-oriented environment
-                        specifically so it could work with a Python-based modeling framework called
-                        Pyre. This release of the software, now named CitComS.py, is essentially the
-                        product of those reengineering efforts. Eh Tan was the principal developer
-                        of CitComS.py, with considerable help from Eun-seo Choi, Puru Thoutireddy,
-                        and Michael Aivazis.</para>
-                    <para>CitComS is one component of a larger collection of software encompassed by
-                        the Geoframework, a collaborative project between the <ulink
-                            url="http://www.cacr.caltech.edu/"> Center for Advanced Computing
-                            Research (CACR)</ulink> and the <ulink
-                            url="http://www.seismolab.caltech.edu/">Seismological
-                        Laboratory</ulink>, both at Caltech, and the <ulink
-                            url="http://www.vpac.org/"> Victorian Partnership for Advanced
-                        Computing</ulink> in Australia. The GeoFramework project has been developing
-                        a suite of tools to model multi-scale deformation for Earth science
-                        problems. This effort was motivated by the need to understand interactions
-                        between the long-term evolution of plate tectonics and shorter term
-                        processes such as the evolution of faults during and between earthquakes. During 2005 and 2006  much of the remaining software developed by Geoframework will be donated to CIG.</para>
-                    <para>The second major release of CitComS (2.0) incorporates the software
-                        framework Pyre, free surface modeling methods, and stress boundary
-                        conditions around the top and bottom surfaces. In the summer of
-                        2005, as part of the 2.0.1 release, the CIG replaced the old build procedure
-                        with the GNU Build System. A subsequent release, version 2.0.2, could compile and run on 64-bit systems.
-                    </para>
-                </sect1>
-                <sect1>
-                    <title>About Pyre</title>
-                    <para>Pyre is an object-oriented environment capable of specifying and launching
-                        numerical simulations on multiple platforms, including Beowulf class
-                        parallel computers and grid computing systems. Pyre allows the binding of
-                        multiple components such as solid and fluid models used in Earth science
-                        simulations, and different meshers. The Pyre framework enables the elegant
-                        setup, modification and launching of massively parallel three-dimensional
-                        solver applications. </para>
-                    <para> Pyre is a framework, a combination of software and design philosophy that
-                        promotes the reuse of code. In their canonical software design book,
-                        <citetitle>Design Patterns</citetitle>, Erich Gamma <emphasis>et
-                        al</emphasis>. condense the concept of a framework concept down to, "When
-                        you use a framework, you reuse the main body and write the code it calls."
-                        In the context of frameworks and object-oriented programming, Pyre can be
-                        thought of as a collection of classes and the way their instances interact.
-                        Programming applications based on Pyre will look similar to those written in
-                        any other object-oriented language. The Pyre framework contains a subset of
-                        parts that make up the overall framework. Each of those parts is designed to
-                        solve a specific problem. </para>
-                    <para>The framework approach to computation offers many advantages. It permits
-                        the exchange of codes and promotes the reuse of standardized software while
-                        preserving efficiency. Frameworks are also an efficient way to handle
-                        changes in computer architecture. They present programmers and scientists
-                        with a unified and well-defined task and allow for shared costs of the
-                        housekeeping aspects of software development. They provide greater
-                        institutional continuity to model development than piecemeal approaches.</para>
-                    <para> The Pyre framework incorporates features aimed at enabling the scientific
-                        non-expert to perform tasks easily without hindering the expert. Target
-                        features for end users allow complete and intuitive simulation
-                        specification, reasonable defaults, consistency checks of input, good
-                        diagnostics, easy access to remote facilities, and status monitoring. Target
-                        features for developers include easy access to user input, a shorter
-                        development cycle, and good debugging support. </para>
-                </sect1>
-                <sect1>
-                    <title>Pyre and CitComS.py</title>
-                    <para> Pyre provides a simulation framework that includes solver integration and
-                        coupling, uniform access to facilities, and integrated visualization. The
-                        framework offers a way to add new solvers to CitComS and to fine-tune
-                        CitComS simulations. Future versions of this documentation will cover coupled simulations generated using via an "exchanger". </para>
-                    <figure>
-                        <title>Pyre Architecture. The integration framework is a set of cooperating
-                            abstract services.</title>
-                        <mediaobject id="c_fig1.eps">
-                            <imageobject role="fo">
-                                <imagedata fileref="graphics/c_fig1.eps" format="EPS"/>
-                            </imageobject>
-                        </mediaobject>
-                    </figure>
-
-
-                    <para> Developers have created Pyre classes for CitComS to facilitate simulation
-                        setup. However, they are not independent classes in a strict sense. They
-                        still share the same underlaying data structure and their functionality is
-                        not divided clearly. CitComS was not designed to be object-oriented and to
-                        make it so would require significant investment of effort with little
-                        return. However, the lack of object-oriented features does not hinder the
-                        coupling of CitComS with other solvers. </para>
-                    <para>This version of CitComS "attaches" to Pyre via the use of bindings. They
-                        are included with CitComS, eliminating the need for users to write or alter
-                        them.</para>
-                </sect1>
-                <sect1>
-                    <title>Governing Equations</title>
-                    <para>With CitcomS, the mantle is treated as an incompressible viscous spherical
-                        shell. With these assumptions, thermal convection is governed by the
-                        equations for conservation of mass, momentum, and energy:</para>
-                    <informaltable frame="none">
-                        <tgroup cols="2" colsep="0" align="center" rowsep="0">
-                            <tbody>
-                                <row>
-                                    <entry align="left">
-                                        <mediaobject id="eq1">
-                                            <imageobject role="fo">
-                                                <imagedata fileref="graphics/eq1.eps" format="EPS"/>
-                                            </imageobject>
-                                        </mediaobject>
-                                    </entry>
-                                    <entry valign="middle" align="right">(equation 1)</entry>
-                                </row>
-                                <row>
-                                    <entry align="left">
-                                        <mediaobject id="eq2">
-                                            <imageobject role="fo">
-                                                <imagedata fileref="graphics/eq2.eps" format="EPS"/>
-                                            </imageobject>
-                                        </mediaobject>
-                                    </entry>
-                                    <entry valign="middle" align="right">(equation 2)</entry>
-                                </row>
-                                <row>
-                                    <entry align="left">
-                                        <mediaobject id="eq3">
-                                            <imageobject role="fo">
-                                                <imagedata fileref="graphics/eq3.eps" format="EPS"/>
-                                            </imageobject>
-                                        </mediaobject>
-                                    </entry>
-                                    <entry valign="middle" align="right">(equation 3)</entry>
-                                </row>
-                            </tbody>
-                        </tgroup>
-                    </informaltable>
-                    <para>Where <emphasis>u<subscript>i</subscript>
-                        </emphasis> is the velocity, <emphasis>P</emphasis> is the dynamic pressure,
-                            <phrase role="symbol">&delta;&rho;</phrase> is the density
-                        anomaly, <emphasis>g</emphasis> is the gravitational acceleration, <phrase
-                            role="symbol">&#951;</phrase> is the viscosity,
-                        <emphasis>T</emphasis> is the temperature, <phrase role="symbol"
-                        >&#954;</phrase> is the thermal diffusivity, and <emphasis>H</emphasis>
-                        is the heat production rate. <emphasis>X<subscript>,y</subscript>
-                        </emphasis> represents the derivative of <emphasis>X</emphasis> with respect
-                        to <emphasis>y</emphasis>, <emphasis>i</emphasis> and <emphasis>j</emphasis>
-                        are spatial indices, and <emphasis>t</emphasis> is time. Without phase
-                        transitions, the density anomalies are:</para>
-                    <informaltable frame="none">
-                        <tgroup cols="2" colsep="0" align="center" rowsep="0">
-                            <tbody>
-                                <row>
-                                    <entry align="left">
-                                        <mediaobject id="eq4">
-                                            <imageobject role="fo">
-                                                <imagedata fileref="graphics/eq4.eps" format="EPS"/>
-                                            </imageobject>
-                                        </mediaobject>
-                                    </entry>
-                                    <entry valign="middle" align="right">(equation 4)</entry>
-                                </row>
-                            </tbody>
-                        </tgroup>
-                    </informaltable>
-                    <para>These equations lead to the following normalization in which primed
-                        quantities are nondimensional:</para>
-                    <informaltable frame="none">
-                        <tgroup cols="2" colsep="0" align="center" rowsep="0">
-                            <tbody>
-                                <row>
-                                    <entry align="left">
-                                        <mediaobject id="eq5">
-                                            <imageobject role="fo">
-                                                <imagedata fileref="graphics/eq5.eps" format="EPS"/>
-                                            </imageobject>
-                                        </mediaobject>
-                                    </entry>
-                                    <entry valign="middle" align="right">(equation 5)</entry>
-                                </row>
-                                <row>
-                                    <entry align="left">
-                                        <mediaobject id="eq6">
-                                            <imageobject role="fo">
-                                                <imagedata fileref="graphics/eq6.eps" format="EPS"/>
-                                            </imageobject>
-                                        </mediaobject>
-                                    </entry>
-                                    <entry valign="middle" align="right">(equation 6)</entry>
-                                </row>
-                                <row>
-                                    <entry align="left">
-                                        <mediaobject id="eq7">
-                                            <imageobject role="fo">
-                                                <imagedata fileref="graphics/eq7.eps" format="EPS"/>
-                                            </imageobject>
-                                        </mediaobject>
-                                    </entry>
-                                    <entry valign="middle" align="right">(equation 7)</entry>
-                                </row>
-                                <row>
-                                    <entry align="left">
-                                        <mediaobject id="eq8">
-                                            <imageobject role="fo">
-                                                <imagedata fileref="graphics/eq8.eps" format="EPS"/>
-                                            </imageobject>
-                                        </mediaobject>
-                                    </entry>
-                                    <entry valign="middle" align="right">(equation 8)</entry>
-                                </row>
-                                <row>
-                                    <entry align="left">
-                                        <mediaobject id="eq9">
-                                            <imageobject role="fo">
-                                                <imagedata fileref="graphics/eq9.eps" format="EPS"/>
-                                            </imageobject>
-                                        </mediaobject>
-                                    </entry>
-                                    <entry valign="middle" align="right">(equation 9)</entry>
-                                </row>
-                                <row>
-                                    <entry align="left">
-                                        <mediaobject id="eq10">
-                                            <imageobject role="fo">
-                                                <imagedata fileref="graphics/eq10.eps" format="EPS"
-                                                />
-                                            </imageobject>
-                                        </mediaobject>
-                                    </entry>
-                                    <entry valign="middle" align="right">(equation 10)</entry>
-                                </row>
-                                <row>
-                                    <entry align="left">
-                                        <mediaobject id="eq11">
-                                            <imageobject role="fo">
-                                                <imagedata fileref="graphics/eq11.eps" format="EPS"
-                                                />
-                                            </imageobject>
-                                        </mediaobject>
-                                    </entry>
-                                    <entry valign="middle" align="right">(equation 11)</entry>
-                                </row>
-                            </tbody>
-                        </tgroup>
-                    </informaltable>
-                    <para>Where <emphasis>R<subscript>o</subscript>
-                        </emphasis> is the radius of the earth, <phrase role="symbol">&#951;</phrase><emphasis><superscript>o</superscript>
-                        </emphasis> is a reference viscosity, <phrase role="symbol"
-                        >&#916;</phrase>T is the superadiabatic temperature drop from the
-                        core-mantle boundary (CMB) to the surface. Dropping the primes, the
-                        equations become:</para>
-                    <informaltable frame="none">
-                        <tgroup cols="2" colsep="0" align="center" rowsep="0">
-                            <tbody>
-                                <row>
-                                    <entry align="left">
-                                        <mediaobject id="eq12">
-                                            <imageobject role="fo">
-                                                <imagedata fileref="graphics/eq12.eps" format="EPS"
-                                                />
-                                            </imageobject>
-                                        </mediaobject>
-                                    </entry>
-                                    <entry valign="middle" align="right">(equation 12)</entry>
-                                </row>
-                                <row>
-                                    <entry align="left">
-                                        <mediaobject id="eq13">
-                                            <imageobject role="fo">
-                                                <imagedata fileref="graphics/eq13.eps" format="EPS"
-                                                />
-                                            </imageobject>
-                                        </mediaobject>
-                                    </entry>
-                                    <entry valign="middle" align="right">(equation 13)</entry>
-                                </row>
-                                <row>
-                                    <entry align="left">
-                                        <mediaobject id="eq14">
-                                            <imageobject role="fo">
-                                                <imagedata fileref="graphics/eq14.eps" format="EPS"
-                                                />
-                                            </imageobject>
-                                        </mediaobject>
-                                    </entry>
-                                    <entry valign="middle" align="right">(equation 14)</entry>
-                                </row>
-                            </tbody>
-                        </tgroup>
-                    </informaltable>
-                    <para>Where <emphasis>Ra</emphasis>, a Rayleigh number, is defined as:</para>
-                    <informaltable frame="none">
-                        <tgroup cols="2" colsep="0" align="center" rowsep="0">
-                            <tbody>
-                                <row>
-                                    <entry align="left">
-                                        <mediaobject id="eq15">
-                                            <imageobject role="fo">
-                                                <imagedata fileref="graphics/eq15.eps" format="EPS"
-                                                />
-                                            </imageobject>
-                                        </mediaobject>
-                                    </entry>
-                                    <entry valign="middle" align="right">(equation 15)</entry>
-                                </row>
-                            </tbody>
-                        </tgroup>
-                    </informaltable>
-                    <para>If there is a phase change, equation 13 is modified to:</para>
-                    <informaltable frame="none">
-                        <tgroup cols="2" colsep="0" align="center" rowsep="0">
-                            <tbody>
-                                <row>
-                                    <entry align="left">
-                                        <mediaobject id="eq16">
-                                            <imageobject role="fo">
-                                                <imagedata fileref="graphics/eq16.eps" format="EPS"
-                                                />
-                                            </imageobject>
-                                        </mediaobject>
-                                    </entry>
-                                    <entry valign="middle" align="right">(equation 16)</entry>
-                                </row>
-                                <row>
-                                    <entry align="left">
-                                        <mediaobject id="eq17">
-                                            <imageobject role="fo">
-                                                <imagedata fileref="graphics/eq17.eps" format="EPS"
-                                                />
-                                            </imageobject>
-                                        </mediaobject>
-                                    </entry>
-                                    <entry valign="middle" align="right">(equation 17)</entry>
-                                </row>
-                            </tbody>
-                        </tgroup>
-                    </informaltable>
-                    <para>Where <emphasis>d<subscript>ph</subscript>
-                        </emphasis> and <emphasis>T<subscript>ph</subscript>
-                        </emphasis> are the ambient depth and temperature of a phase change,
-                            <emphasis>s</emphasis> is the Clapeyron slope of a phase change, and
-                                <emphasis>w<subscript>ph</subscript>
-                        </emphasis>is the width of a phase transition. The phase-change Rayleigh
-                        numbers, <emphasis>R<subscript>b</subscript>
-                        </emphasis>, is defined as:</para>
-                    <informaltable frame="none">
-                        <tgroup cols="2" colsep="0" align="center" rowsep="0">
-                            <tbody>
-                                <row>
-                                    <entry align="left">
-                                        <mediaobject id="eq18">
-                                            <imageobject role="fo">
-                                                <imagedata fileref="graphics/eq18.eps" format="EPS"
-                                                />
-                                            </imageobject>
-                                        </mediaobject>
-                                    </entry>
-                                    <entry valign="middle" align="right">(equation 18)</entry>
-                                </row>
-                            </tbody>
-                        </tgroup>
-                    </informaltable>
-                    <para>Where <phrase role="symbol">&#916;&#961;</phrase><subscript>ph</subscript> is the density jump across a phase change.</para>
-                </sect1>
-                <sect1>
-                    <title>Numerical Methods</title>
-                    <para>The governing equations are solved with the finite element method, see (8). CitcomS employs an Uzawa algorithm to solve the momentum equation coupled with the incompressibility constraints (3,9). The energy equation is solved with a Petrov-Galerkin method (10). Brick elements are used, such as eight velocity nodes with trilinear shape functions and one constant pressure node for each element. The use of brick elements in 3-D (or rectangular elements in 2-D) is important for accurately determining the pressure, such as dynamic topography, in incompressible Stokes' flow (8).</para> <para>The discrete form of equations 12 and 13 may be written in the following matrix form (5):</para>
-                    <informaltable frame="none">
-                        <tgroup cols="2" colsep="0" align="center" rowsep="0">
-                            <tbody>
-                                <row>
-                                    <entry align="left">
-                                        <mediaobject id="eq19">
-                                            <imageobject role="fo">
-                                                <imagedata fileref="graphics/eq19.eps" format="EPS"
-                                                />
-                                            </imageobject>
-                                        </mediaobject>
-                                    </entry>
-                                    <entry valign="middle" align="right">(equation 19)</entry>
-                                </row>
-                                <row>
-                                    <entry align="left">
-                                        <mediaobject id="eq20">
-                                            <imageobject role="fo">
-                                                <imagedata fileref="graphics/eq20.eps" format="EPS"
-                                                />
-                                            </imageobject>
-                                        </mediaobject>
-                                    </entry>
-                                    <entry valign="middle" align="right">(equation 20)</entry>
-                                </row>
-                            </tbody>
-                        </tgroup>
-                    </informaltable>
-                    <para>Where <emphasis role="bold">A</emphasis> is the "stiffness" matrix;
-                            <emphasis>u</emphasis> is a vector of unknown velocities; <emphasis
-                            role="bold">B</emphasis> is the discrete gradient operator;
-                        <emphasis>p</emphasis> is a vector of unknown pressures; and
-                        <emphasis>f</emphasis> is a vector composed of the body and boundary forces
-                        acting on the fluid. The individual entries of <emphasis
-                            role="bold">A</emphasis>, <emphasis role="bold">B</emphasis>, and
-                        <emphasis>f</emphasis> are obtained using a standard finite element
-                        formulation, see (5) for the explicit
-                        entries. Equation 20 can be transformed by premultiplying by 
-                        <inlinemediaobject id="eq20.2">
-                            <imageobject role="fo">
-                                <imagedata fileref="graphics/eq20.2.eps" format="EPS"/>
-                            </imageobject>
-                        </inlinemediaobject> and using equation 19 to eliminate the velocity
-                        unknowns:</para>
-                    <informaltable frame="none">
-                        <tgroup cols="2" colsep="0" align="center" rowsep="0">
-                            <tbody>
-                                <row>
-                                    <entry align="left">
-                                        <mediaobject id="eq21">
-                                            <imageobject role="fo">
-                                                <imagedata fileref="graphics/eq21.eps" format="EPS"
-                                                />
-                                            </imageobject>
-                                        </mediaobject>
-                                    </entry>
-                                    <entry valign="middle" align="right">(equation 21)</entry>
-                                </row>
-                            </tbody>
-                        </tgroup>
-                    </informaltable>
-                    <para>This equation is solved using the Uzawa algorithm, an established method
-                        for solving the minimization of a dual function (11), which simultaneously yields the velocity
-                        field. A conjugate gradient scheme for this iteration is described by (9,12), and forms the basis for the technique used in CitComS.</para>
-                </sect1>
-        </chapter>
-        <chapter>
-      <title>Installation and Getting Help</title>
-    <sect1>
-        <title>Introduction</title>
-        <para>To install CitComS.py, you will follow the procedure that is commonly used with other
-            open source software packages. First, you will download the source package (in the form
-            of a compressed 'tar' file) from the <ulink url="http://www.geodynamics.org">Geodynamics
-                website</ulink> Geodynamics.org. After unpacking the source, you will run a
-            prepackaged shell script to configure CitComS for your system. Then you will use the
-            'make' utility to build CitComS from source, and finally install the CitComS programs
-            and Python modules. </para>
-        <para> Advanced users and software developers may be interested in downloading the latest
-            CitComS source code directly from the CIG source code repository, instead of using the
-            prepared source package. See the section "Software Repository", later in this
-            chapter. CitComS.py has been tested on Linux, Mac OS X, and several NSF TeraGrid
-            platforms. </para>
-    </sect1>
-    <sect1>
-        <title>Getting Help</title>
-        <para> For help, send e-mail to the CIG Mantle Convection Mailing List
-            <email>cig-mc at geodynamics.org</email>. You can subscribe to the Mailing List and view archived discussion at the <ulink
-                url="http://www.geodynamics.org">Geodynamics website</ulink>.</para>
-    </sect1>
-    <sect1>
-        <title>System Requirements</title>
-        <para>CitComS.py requires the following:<itemizedlist spacing="compact">
-                <listitem>Python 2.3 or greater.</listitem>
-                <listitem>An MPI library which implements version 1 of the MPI standard. (If you are
-                    using MPICH, MPICH version 1.2.3 or later is required.)</listitem>
-                <listitem>A modern C++ compiler.</listitem>
-                <listitem>A C compiler.</listitem>
-            </itemizedlist>
-        </para>
-        <note><para>Users familiar with older versions of CitComS may prefer to install only the
-            legacy CitComS tools, <filename>CitcomSFull</filename> and
-            <filename>CitcomSRegional</filename>, and forgo use of the Pyre framework. Installing
-            the legacy tools requires simply:<itemizedlist spacing="compact">
-                <listitem>An MPI library.</listitem>
-                <listitem>A C compiler.</listitem>
-            </itemizedlist>
-            For more information, see the subsection "Installing without Pyre", later in this
-            chapter.</para></note>
-        <para>You can download Python from the <ulink url="http://www.python.org/">Python</ulink>
-            website. If your system is running a recent release of Linux or Mac OS X, chances are
-            you already have a suitable Python interpreter installed. To check, type the
-                <filename>'python'</filename> command:</para>
-        <programlisting>$ python -V
-Python 2.3.4</programlisting>
-        <para> MPICH is a freely available, portable implementation of MPI. For more information,
-            visit the <ulink url="http://www-unix.mcs.anl.gov/mpi/mpich/">MPICH Home Page</ulink>. </para>
-        <note>
-            <title>Note for Mac OS X Users</title>
-            <para>You will need Xcode, which is freely available from <ulink
-                url="http://developer.apple.com/">Apple</ulink>. Instead of using MPICH, you will
-            probably want to use <ulink url="http://www.lam-mpi.org/">LAM/MPI</ulink>. LAM/MPI is
-            available as a Fink package; if you have <ulink url="http://fink.sourceforge.net/">Fink
-                installed</ulink>, simply enter the following command from a Terminal window to
-            install LAM/MPI:</para>
-        <programlisting> $ fink install lammpi lammpi-dev</programlisting>
-            </note>
-    </sect1>
-    <sect1>
-        <title>Downloading and Unpacking Source</title>
-        <para>Download CitComS.py from the <ulink url="http://www.geodynamics.org">Geodynamics
-                website</ulink>. Click the "software" tab at the top of the page. Then click
-            "Software Packages". Once you click the CitComS link, you will be led through a simple
-            registration process. After you have downloaded the source archive, unpack it using the
-                <filename>'tar'</filename> command:
-        <programlisting>$ tar xzf CitcomS-2.0.1.tar.gz</programlisting>
-        If you don't have GNU Tar, try the following command instead: 
-            <programlisting>$ gunzip -c CitcomS-2.0.1.tar.gz | tar xf -</programlisting></para>
-    </sect1>
-    <sect1>
-        <title>Installation Procedure</title>
-        <para>After unpacking the source, follow the following procedure to install CitComS:
-            <orderedlist>
-            <listitem>'cd' to the directory containing the CitComS source and type './configure' to
-            configure the package for your system.
-            <programlisting>$ cd CitcomS-2.0.1
-$ ./configure</programlisting></listitem>
-            <listitem>Type 'make' to build the package.
-                <programlisting>$ make</programlisting></listitem>
-            <listitem>Become 'root' and type 'make install' to install CitcomS.
-            <programlisting>$ su
-Password:
-# make install</programlisting></listitem>
-                </orderedlist></para>
-            <para>To install as an ordinary user instead of 'root', give 'configure' the '--prefix'
-            option, specifying a directory to which you have write access:
-        <programlisting>$ cd CitcomS-2.0.1
-$ ./configure --prefix=$HOME/cig
-$ make
-$ make install</programlisting></para>
-        <para>For more details about <filename>'configure'</filename>, see the section
-            "Configuration", below.</para>
-        <note><para>If you install as an ordinary user using
-            <filename>'--prefix=PREFIX'</filename>, be mindful of the fact that you may have to set
-            various environment variables in order for CitComS to function properly under the given
-                <filename>PREFIX</filename>. First, you will want to add
-            <filename>PREFIX/bin</filename> to your <filename>PATH</filename>. You may need or want
-            to add <filename>PREFIX/lib/python2.3/site-packages</filename> to your
-                <filename>PYTHONPATH</filename>. Finally, on some obscure Unix systems, you may need
-            to add <filename>PREFIX/lib</filename> to your <filename>LD_LIBRARY_PATH</filename> (or
-            equivalent). </para></note>
-    </sect1>
-    <sect1>
-        <title>Configuration</title>
-        <para>The 'configure' script checks for various system features. As it runs, it prints
-            messages informing you of which features it is checking for. Upon successful completion,
-            it generates a <filename>Makefile</filename> in each source directory of the package. It also generates one
-            or more <filename>portinfo</filename> header files, which contain system-dependent definitions (<filename>portinfo</filename>
-            is equivalent to <filename>config.h</filename> in other open-source software packages). </para>
-        <para> The 'configure' script will attempt to guess the correct values of various
-            installation parameters. In the event that the default values used by 'configure' are
-            incorrect for your system, or 'configure' is unable to guess the value a certain
-            parameter, you may have to specify the correct value by hand. </para>
-        <sect2>
-            <title>Configure Usage</title>
-            <para>For a detailed list of 'configure' variables and options, give 'configure' the
-                '--help' option:
-                <programlisting>$ ./configure --help</programlisting> </para>
-            <para>The following is a summary of the variables and options that are important when
-                installing CitComS. </para>
-        </sect2>
-        <sect2>
-            <title>Environment Variables</title>
-            <para> Environment variables may be specified as arguments to 'configure'; e.g.,
-            <programlisting> $ ./configure CXX=icpc  # compile C++ using the Intel compiler</programlisting></para>
-            <informaltable>
-                <tgroup cols="2">
-                    <colspec colnum="1" colname="col1" colwidth="1*"/>
-                    <colspec colnum="2" colname="col2" colwidth="2*"/>
-                    <tbody valign="top">
-                        <row>
-                            <entry>Variable</entry>
-                            <entry> Description</entry>
-                        </row>
-                        <row>
-                            <entry>PYTHON</entry>
-                            <entry>Python interpreter. This is useful if you have Python installed
-                                in a non-standard location; e.g.,
-                                <programlisting>./configure \
-    PYTHON=/opt/python2.3/bin/python</programlisting>
-                                By default, 'configure' will search
-                                for a suitable Python interpreter using your PATH environment
-                                variable.</entry>
-                        </row>
-                        <row>
-                            <entry> CC</entry>
-                            <entry> C compiler command.</entry>
-                        </row>
-                        <row>
-                            <entry>CXX</entry>
-                            <entry>C++ compiler command.</entry>
-                        </row>
-                        <row>
-                            <entry>
-                                <simplelist>
-                                    <member>MPICC</member>
-                                    <member>MPICXX</member>
-                                    <member>MPIINCLUDES</member>
-                                    <member>MPILIBS</member>
-                                </simplelist>
-                            </entry>
-                            <entry> These variables collectively specify how to build MPI programs.
-                                The variables MPICC and MPICXX specify compiler commands;
-                                MPIINCLUDES specifies preprocessor flags, and MPILIBS specifies
-                                linker flags. See the section "MPI Configuration" (below) for
-                                details and examples.</entry>
-                        </row>
-                    </tbody>
-                </tgroup>
-            </informaltable>
-        </sect2>
-        <sect2>
-            <title>MPI Configuration</title>
-            <para>By default, 'configure' will search for MPI wrappers (such as
-                    <filename>mpicxx/mpic++</filename> and <filename>mpicc</filename>) using your
-                PATH environment variable. You may specify MPI wrappers manually using the variables
-                MPICC and MPICXX. If found, the wrappers will be used to compile MPI-related source;
-                and CC and CXX will default to underlying C/C++ compiler commands (e.g., CC will
-                default to the result of 'mpicc -compile_info' if you are using MPICH). You may also
-                set CC and CXX manually. The commands specified by CXX and CC are used to compile
-                ordinary C/C++ source, and for linking shared libraries.</para>
-            <example>
-                <title>Manually specifying MPI wrappers</title>
-                <programlisting>$ ./configure \
-MPICC=/opt/mpich-1.2.6/bin/mpicc \
-MPICXX=/opt/mpich-1.2.6/bin/mpicxx</programlisting>
-            </example>
-            <para>If MPI wrappers are not found, 'configure' will set MPICC and MPICXX to CC and CXX, respectively
-                (i.e., the same commands used to build ordinary C/C++ source). Then, configure will
-                attempt to find <filename>mpi.h</filename> and an MPI library in the standard
-                locations (e.g., <filename>/usr/include</filename> and
-                <filename>/usr/lib</filename>) using the ordinary compiler. In this scenario, if
-                your MPI header files and libraries are installed in a non-standard location, you
-                must specify MPIINCLUDES and MPILIBS, so that the compiler can find the MPI header
-                files and libraries.</para>
-            <example>
-                <title>Manually specifying MPI 'include' and 'lib' directories</title>
-                <programlisting>$ ./configure \
-MPIINCLUDES="-I/opt/mpich-1.2.6/include" \
-MPILIBS="-L/opt/mpich-1.2.6/lib -lmpich"</programlisting>
-            </example>
-            <example>
-                <title>Manually specifying MPI 'include' and 'lib' directories, and an alternative
-                    compiler</title>
-                <programlisting>$ ./configure \
-CC=icc \
-CXX=icpc \
-MPIINCLUDES="-I/opt/mpich-1.2.6/include" \
-MPILIBS="-L/opt/mpich-1.2.6/lib -lmpich"</programlisting>
-            </example>
-            <para>Some words of caution when specifying the MPI configuration:</para>
-            <itemizedlist>
-                <listitem>Specifying MPI commands and flags in general-purpose 'configure' variables
-                    (such as CC, CXX, CPPFLAGS, and LDFLAGS) may work on some systems, but is not
-                    recommended unless you happen to have a shared version of the MPI library
-                    installed on your system (<filename>libmpich.so</filename> or
-                        <filename>libmpi.so</filename>). </listitem>
-                <listitem>If you explicitly specify both MPICXX and CXX, CXX will be used
-                    to compile all C++ source; MPICXX is invoked merely to determine the correct
-                    values for MPIINCLUDES and MPILIBS (if necessary).  Likewise, if you
-                    explicitly specify both MPICC and CC, CC will be used to compile all
-                    C source; MPICC will only be used to determine the MPI flags.</listitem>
-                <listitem>Configuring CitComS with a different C++ compiler than was used to
-                    configure your MPI library may cause link errors. However, the 'configure' script
-                    attempts to detect this scenario and automatically work-around the problem for you.
-                </listitem>
-            </itemizedlist>
-        </sect2>
-        <sect2>
-            <title>Batch System Configuration</title>
-            <para>If you are installing CitComS on a cluster with a batch system, you can configure
-                CitComS such that the Pyre-based commands <filename>citcomsregional.sh</filename>
-                and <filename>citcomsfull.sh</filename> automatically submit jobs to the batch
-                queue. CitComS contains support for the LSF, PBS, and Globus batch systems.</para>
-            <para>The <filename>configure</filename> script searches for the
-                <filename>bsub</filename>, <filename>qsub</filename>, and
-                <filename>globusrun</filename> batch commands. If one of these is found, CitComS is
-                configured to use the corresponding batch system (LSF, PBS, and Globus,
-                respectively) instead of launching MPI jobs directly using
-                <filename>mpirun</filename>. Run <filename>./configure --help</filename> for
-                information on how to configure the batch system parameters manually.</para>
-            <para>The proper commands to use in a batch script varies from one cluster to the next.
-                On some systems, <filename>mpirun</filename> is invoked directly from the batch
-                script. On others, a special wrapper is used instead. Therefore, after successfully
-                installing CitComS, you must edit the following XML configuration file:
-                <programlisting>PREFIX/etc/CitcomS/CitcomS.pml</programlisting>
-                where PREFIX is the directory under which you installed CitcomS (default
-                <filename>/usr/local</filename>). Edit the defaults as appropriate for your system. For
-                example, if you are using LSF, first verify that CitComS is configured to use LSF:
-            <programlisting><![CDATA[<property name="launcher">lsf</property>]]></programlisting>
-                Next, edit the LSF section:
-            <programlisting><![CDATA[<component name="lsf">
-    <property name="command">mpijob mpirun</property>
-    <property name="batch-command">bsub</property>
-</component>]]></programlisting>
-                In particular, set the <filename>command</filename> property to the correct
-                command for launching MPI jobs from a batch script on your system. For example:
-                <programlisting><![CDATA[<property name="command">pam -g 1 gmmpirun_wrapper</property>]]></programlisting></para>
-            <para>You may find the <filename>--launcher.dry</filename> option useful while debugging
-                the batch system configuration:
-                <programlisting>citcomsregional.sh --launcher.dry</programlisting>
-                This option will cause CitcomS to perform a "dry run", dumping the batch script to
-                the console, instead of actually submitting it for execution.</para>
-        </sect2>
-        <sect2>
-            <title>Installing without Pyre</title>
-            <para>To build just the CitComS tools (or "drivers") from the legacy C code, give
-                    <filename>configure</filename> the <filename>--without-pyre</filename> option:
-                <programlisting>$ ./configure --without-pyre</programlisting>
-                The only system requirements for this configuration are an MPI library and a
-                decent C compiler. The final <filename>make install</filename> step will install two
-                command-line tools: <filename>CitcomSFull</filename> and
-                <filename>CitcomSRegional</filename>.</para>
-        </sect2>
-    </sect1>
-    <sect1>
-        <title>Software Repository</title>
-        <para>The CitcomS source code is available via a Subversion server at geodynamics.org. This
-            allows users to view the revision history of the code, and check out the most recent
-            development version of the software.</para>
-        <note><para>If you are content with the prepared source
-            package, feel free to skip this section.</para></note>
-        <sect2>
-            <title>Tools You Will Need</title>
-            <para>In addition to the usual system requirements, you will need a handful of
-                additional development tools installed in order to work with the source from the CIG
-                software repository.</para>
-            <para>First you must have a Subversion client installed. To check, type
-                <filename>svn</filename>; it should return a usage message. For more information on
-                Subversion, visit the <ulink url="http://subversion.tigris.org/">Subversion
-                website</ulink>.
-            <programlisting>$ svn
-Type 'svn help' for usage.</programlisting>
-                Second, you must have the GNU tools Autoconf, Automake, and Libtool installed. To
-                check, enter the following commands:
-            <programlisting>$ autoconf --version
-$ automake --version
-$ libtoolize --version</programlisting>
-                For more information about these GNU tools, see the <ulink
-                    url="http://www.gnu.org/software">GNU website </ulink>. The CitComS v2.0.1
-                source package was created with Autoconf 2.59, Automake 1.9.2, and Libtool
-            1.5.6.</para>
-        </sect2>
-        <sect2>
-            <title>Download Source from Subversion</title>
-            <para>To checkout the latest version of the software, use the 'svn checkout' command:
-                <programlisting>$ svn checkout svn://geodynamics.org/cig/mc/3D/CitcomS/trunk CitcomS</programlisting>
-                This will checkout the CitComS source into the subdirectory
-                <filename>CitcomS</filename>.</para>
-            <para>Like the release version, the development version depends upon Pythia v0.8. In
-                addition, the development version also depends upon a package called Exchanger.
-                Unless you plan to build only the legacy CitComS tools (see "Installing without
-                Pyre", earlier in this chapter), you will need to check out the Pythia and Exchanger
-                packages as well. Like CitComS, Exchanger is available from the geodynamics.org
-                server. For convenience, Pythia is also available from geodynamics.org. To checkout Pythia and
-                Exchanger, use the following commands:</para>
-            <programlisting>$ svn checkout svn://geodynamics.org/cig/vendor/pythia/v0.8 pythia-0.8
-$ svn checkout svn://geodynamics.org/cig/cs/Exchanger/trunk Exchanger</programlisting>
-        </sect2>
-        <sect2>
-            <title> Generating the GNU Build System</title>
-            <para>You working directory should now contain three subdirectories:
-            <programlisting>$ ls
-CitcomS  Exchanger  pythia-0.8</programlisting>
-                Each of the three packages must be configured and built separately, in the
-                following order:
-            <orderedlist spacing="compact">
-                <listitem>pythia-0.8</listitem>
-                <listitem>Exchanger</listitem>
-                <listitem>CitcomS</listitem>
-                </orderedlist>
-                But before you can run 'configure' or 'make', you must generate the necessary
-                files using the GNU tools. The easiest way to do this is to run 'autoreconf -i':
-            <programlisting>$ cd pythia-0.8
-$ autoreconf -i
-$ ./configure --prefix=$HOME/cig
-$ make
-$ make install</programlisting>
-            Then, repeat this process for Exchanger and CitcomS:
-            <programlisting>$ cd ../Exchanger
-$ autoreconf -i
-$ ./configure --prefix=$HOME/cig
-$ make
-$ make install
-$ cd ../CitcomS
-$ autoreconf -i
-$ ./configure --prefix=$HOME/cig
-$ make
-$ make install</programlisting>
-                The 'autoreconf' tool runs Autoconf to generate the 'configure' script from
-                'configure.ac'. It also runs Automake to generate 'Makefile.in' from 'Makefile.am'
-                in each source directory.</para></sect2>
-    </sect1>
-        </chapter>
-        <chapter>
-            <title>Running CitComS.py</title>
-            <sect1>
-                <title>Using CitComS.py</title>
-                <para>CitComS.py usage is similar to that of previous versions of CitComS. Installed under the <filename>bin</filename> directory (default <filename>/usr/local/bin</filename>), 
-                    <filename>citcomsregional.sh</filename> is used for
-                    regional models and <filename>citcomsfull.sh</filename> for full spherical
-                    models. <filename>citcomsregional.sh</filename> can be executed without any command line options and will run with
-                    default parameters. <filename>citcomsfull.sh</filename> requires at least 12
-                    processors to run. To do so, you must specify the <filename>launcher</filename>
-                    parameters, which are called "facilities."</para>
-                <para>Since you will likely want to specify the parameters of your CitComS runs, you
-                    will need to alter both computational details (such as the number of time steps)
-                    and controlling parameters specific to your problem (such as the Rayleigh
-                    number). Most of the properties you will set using CitComS.py have identical
-                    names as the parameters for the old CitComS. </para>
-                <sect2>
-                    <title>Changing Parameters</title>
-                    <para>Pyre has the following syntax to change parameters from their default
-                        values. To change the value of a property of a component, use:
-                        <programlisting>--[component].[property]=[value]</programlisting> Each
-                        component is attached to a facility, so the option above can also be
-                        written: as:
-                        <programlisting>--[facility].[property]=[value]</programlisting> A different
-                        component can be attached to a facility by:
-                        <programlisting>--[facility]=[new_component]</programlisting>
-                    </para>
-                </sect2>
-                <sect2>
-                    <title>Coordinate System and Mesh</title>
-                    <para> In general, CitComS uses meshes that are regular, although considerable
-                        flexibility exists for grid refinement in the regional models. In regional
-                        meshes, <emphasis>theta</emphasis> is the colatitude measured from the north
-                        pole, <emphasis>fi</emphasis> is the east longitude, and
-                        <emphasis>z</emphasis> is the radius. <emphasis>theta</emphasis> and
-                            <emphasis>fi</emphasis> are in units of radians. Figure 3.1 shows the
-                        organization of the mesh in a regional problem. </para>
-                    <para>
-                        <figure>
-                            <title>Global Node Numbering. Global node numbering starts at the base
-                                of arrow A (theta<subscript>min</subscript>,
-                                fi<subscript>min</subscript>, r<subscript>min</subscript>), and
-                                advances from 1 at the base to <emphasis>nz</emphasis> at the tip.
-                                Upon reaching the tip, numbering continues from the base of arrow B
-                                    (<emphasis>nz</emphasis>+1) to its tip (2
-                                <emphasis>nz</emphasis>), and so on for all nodes on the plane fi =
-                                    fi<subscript>min</subscript>. (left) After completing each theta radius
-                                plane, the fi index is incremented and numbering commences from
-                                    (theta<subscript>min</subscript>, r<subscript>min</subscript>) as on
-                                the left. (right)</title>
-                            <mediaobject id="c_fig3.jpg">
-                                <imageobject role="fo">
-                                    <imagedata fileref="graphics/c_fig3.jpg" format="JPG"/>
-                                </imageobject>
-                            </mediaobject>
-                        </figure>
-                    </para>
-                </sect2>
-            </sect1>
-            <sect1>
-                <title>A Simple CitComS Test</title>
-                <para> CitComS runs similarly in full spherical or regional modes. For the purpose
-                    of this example, you will perform a test run of the regional version.
-                    Instructions for using the full version can be found in example in Cookbook 1 in a
-                    subsequent chapter.</para>
-                
-                <para>
-                    Execute the following on the command line:</para>
-                <example>
-                    <title>Uniprocessor CitComS from the Command Line</title>
-                    <sidebar>
-<programlisting>citcomsregional.sh --steps=10 
---controller.monitoringFrequency=5 --solver.datafile=example 
---solver.mesher.nodex=17 --solver.mesher.nodey=17</programlisting>
-                    </sidebar>
-                </example>   
-                <para>This runs a default convection problem in a regional domain for 10 times steps and with a mesh of 17 x 17 x 9 nodal points. See the next chapter for steps to immediately visualize your results with OpenDX.</para>
-                        
-                        <sect2><title>Multiprocessor Example</title>
-
-                
-                    
-                    <para> On input, CitComS needs numerous parameters
-                        specified. (See appendix for full list.) Depending on those input
-                        parameters, CitComS could also require numerous
-                        input files, such as velocity boundary conditions which could be used for
-                        time dependent, plate tectonic problems. Finally,
-                        CitComS will potentially output a large number of
-                        files which will be spread throughout the file systems contained in the
-                        individual nodes of your Beowulf. This means that you will have to organize
-                        your directories carefully when running CitComS so
-                        that you can find your way through these files as well as use a
-                        post-processing program contained with this distribution.
-                        (In the example that follows, these output files would be placed
-                        in <filename>/scratch/username</filename> with a filename prefix 
-                        <filename>example1</filename> on each individual node.)</para>
-                    <para>It is possible to input the parameters relevant to your test run from the
-                        command line:</para>
-                    <example>
-                        <title>Multiprocessor CitComS from the Command Line</title>
-                        <sidebar>
-                            <programlisting><![CDATA[$ citcomsregional.sh --launcher.nodes=4 
---launcher.nodegen="n%03d" --launcher.nodelist=[101-102] 
---solver.mesher.nprocx=2 --solver.mesher.nprocy=2 
---solver.datafile="/scratch/username/example1"]]></programlisting>
-                        </sidebar>
-                    </example>
-                    <para> However, entering all those parameters via the command line involves the
-                        risk of typographical errors, which can lead to undesired results. So, you
-                        may find it easier to write a brief shell script that contains the
-                        parameters. The file should have the suffix <filename>.sh</filename>. When
-                        you downloaded the CitComS source, this included
-                        an <computeroutput>examples</computeroutput> directory.
-                        In this directory, you will find a script called
-                        <filename>example1.sh</filename>. </para>
-                    <example>
-                        <title>Simple Regional CitComS Shell Script,
-                            example1.sh
-                        </title>
-                        <sidebar>
-                            <programlisting>
-<![CDATA[ #!/bin/sh
-
-citcomsregional.sh \
-\
---steps=71 \
-\
---controller.monitoringFrequency=10 \
-\
---launcher.nodes=4 \
---launcher.nodegen="n%03d" \
---launching.nodelist=[101-102,101-102] \
-\
---solver.datafile=/scratch/username/example1 \
-\
---solver.mesher.nprocx=2 \
---solver.mesher.nprocy=2 \
---solver.mesher.nodex=17 \
---solver.mesher.nodey=17 \
---solver.mesher.nodez=9 \
-
-# End of file]]></programlisting>
-                        </sidebar>
-                    </example>
-                    <para> This is a basic problem with 2 processors in colatitude (x-coordinate), 2
-                        in longitude (y-direction), and 1 in the radial (z-direction). In addition,
-                        there will be 17 nodes in x, 17 nodes in y, and 9 nodes in z.</para>
-                    <para> It is important to realize that within the code (and in finite element
-                        analysis) the term "node" refers to the mesh points defining the corners of
-                        the elements. Unfortunately, "nodes" also refers to
-                       the individual computers which make up the Beowulf PC cluster. In
-                            <filename>example1.sh</filename>, this is indicated with:</para>
-                    <programlisting>
---solver.mesher.nprocx=2 \
---solver.mesher.nprocy=2 \
---solver.mesher.nodex=17 \
---solver.mesher.nodey=17 \
---solver.mesher.nodez=9 \
-</programlisting>
-                    <para> These quantities refer to the total number of FEM nodes in a given
-                        direction for the complete problem and for the example it works out that
-                        within a given processor there will be 9 x 9 x 9 nodes. Note that in the
-                        x-direction (or y) that for the entire problem there are 17 nodes and there
-                        is one node shared between two processors. This shared node is duplicated in
-                        two adjacent processors. The global numbering of FEM nodes is z-direction
-                        first, then x-direction, then y-direction. This numbering convention is used
-                        for the input and output data.</para>
-                    <para> In order to run this example you should be on your front end and be in
-                        the directory in which the input file is located, in this case, the
-                            <filename>examples</filename> directory. To run the test example, invoke
-                        the following:</para>
-                    <programlisting>$ ./example1.sh</programlisting>
-                    <para>Once you have completed your run, you will notice that it generates a file
-                        called <filename>mpirun.nodes</filename>. It will contain a list of the
-                        nodes where CitComS has run. You may want to login to one of the nodes to
-                        check that the data appears to have been properly generated. You should also
-                        check the log file for any error messages. </para>
-                   
-                    <para>If you receive a message such as <filename>bash: --solver.mesher.nodez=9:
-                        command not found</filename>, chances are your script is missing a line
-                        continuation or has an extra space. However, most of the time CitComS will
-                        just run using the default values -even if it finds a typographical error
-                        such as "nnode" instead of "node". So, along with double-checking your
-                        parameters as you type them in, you should check your results to be sure
-                        they make sense. </para><para>Following your successful run, you
-                        will want to retrieve the output files from all the nodes and process them
-                            so they can be visualized with the visualization program OpenDX and proceed to the next chapter.</para>
-                 
-                </sect2>
-                        
-                        <sect2><title>Using CitComS.py on the TeraGrid</title>
-                            <para> The TeraGrid is an open scientific discovery infrastructure combining leadership class resources at eight partner sites to create an integrated, persistent computational resource. The TeraGrid takes its name from two concepts from high-end computing. "Tera" is the metric prefix for "trillions" as in teraflops (trillions of calculations per second) and terabytes (trillions of bytes) and reflects the scale of the computing power provided by the TeraGrid. The "Grid" portion of the TeraGrid reflects the idea of harnessing and using distributed computers, data storage systems, networks, and other resources as if they were a single massive system. In other words, Grid computing uses software technologies to allow researchers to create "virtual supercomputers" far larger than individual hardware components. </para>
-                            <para>Although the TeraGrid is a high-end resource, it was developed to be accessible to the general community of scientists and engineers as a production facility. Since the TeraGrid software is based on commodity clusters, Linux/Unix, and Globus, it should be easier to scale from a laboratory development environment to a high-end environment in a straightforward manner which promotes application performance.</para>
-                            <para>CitComS.py has 
-                            already been installed on several NSF TeraGrid platforms. Accounts for small 
-                            allocations are available directly from CIG.</para>
-                        
-                        
-                        </sect2>
-            </sect1>
-        </chapter>
-        <chapter>
-            <title>Postprocessing and Graphics</title>
-            <sect1>
-                <title>Introduction</title>
-                <para>Once you have run CitComS, you should have a series of output files (potentially spread throughout the file systems of your Beowulf). You will have to retrieve
-                    and combine the data for the time-step (age) of interest.</para>
-                <para>To visualize your results, it is recommended that you use the open source Open
-                    Visualization Data Explorer, better known as OpenDX. Both the software and
-                    tutorials are available from the <ulink url="http://www.opendx.org/">OpenDX</ulink>
-                    website. If you are using Mac OS X, a free version OpenDX is available
-                    via <ulink url="http://fink.sourceforge.net/">Fink</ulink>, however, if the installation proves to be difficult, 
-                    a binary version is available from <ulink url="http://hpc.sourceforge.net">HPC for Mac OS X</ulink>. </para>
-
-                <sect2>
-                    <title>Processing on a Beowulf Cluster</title>
-
-                    
-                    <para>
-                         Generally, the results from your CitComS run will be distributed on
-                         disks attached to individual nodes of your Beowulf cluster. The output
-                         files are written in each node under the directory that you specified
-                         as your datafile in the input file. To examine those files, login to a
-                         node and change directories to the one you specified with a prefix. For
-                         example, if you selected your datafile to be called 
-                         <filename>datafile="/scratch/username/test-case"</filename>, then your
-                        output file will be written to <filename>/scratch/username</filename>
-                         and will have the prefix <filename>test-case</filename>. An example of
-                         a filename for the velocity output is <filename>test-case.velo.2.10</filename>
-                         where <filename>test-case</filename> is the model prefix; <filename>velo</filename>
-                         means that this is a velocity data file; <filename>2</filename>
-                         corresponds to the processor number (so it is using the 2nd processor);
-                         <filename>10</filename> corresponds to the time-step.
-                    </para>
-                    <para>
-                         To choose an age to export for postprocessing, you have to find out
-                         which time step corresponds to the age that interests you. This is done
-                         by looking at the log or time file, for example <filename>test-case.log</filename>.
-                         The log file contains data that describes the details of the computation.
-                         It also has a <filename>current age</filename> field that lists the time step numbers and their
-                         corresponding times. The time step value you selected is what will be exported
-                         for postprocessing. The time file contains the non-dimensional model time. 
-                         The format of the time file can be found in Appendix C.
-                    </para>
-                    <para>
-                         These output files need to be post-processed before you can do the 
-                         visualization. There are two scripts both can post process (retrieve and 
-                         combine) CitComS output: <filename>autocombine.py</filename> and 
-                         <filename>batchcombine.py</filename>. It is recommened to use 
-                         <filename>autocombine.py</filename> over <filename>batchcombine.py</filename>,
-                         as the former is easier to use.
-                    </para>
-                    <para>
-                         To use <filename>autocombine.py</filename>, you have to run CitComS.py in a 
-                         slightly different way. CitComS.py prints out the input parameters to the
-                         screen. That print out can be redirected to a file, which can be used later
-                         to retrieve input parameters. This is done with:
-                         <programlisting>$ my_citcoms.py_script > input_param</programlisting>
-                         Then, you can retrieve and combine data of step 10 by using:
-                         <programlisting>$ autocombine.py mpirun.nodes input_param 10</programlisting>
-                         This reads the MPI machinefile (<filename>mpirun.nodes</filename>) and 
-                         CitComS.py input parameters (<filename>input_param</filename>), then call
-                         <filename>batchcombine.py</filename> to do the actual job. The general useage
-                         for <filename>autocombine.py</filename> is:
-                         <programlisting>$ autocombine.py [machinefile] [input_param] \
-[step1] [step2 or more ...]</programlisting>
-                         If you do not have the input parameters saved to a file, you have to use
-                         <filename>batchcombine.py</filename> to retrieve and combine the data. The
-                         general usage for <filename>batchcombine.py</filename> is:
-                         <programlisting>$ batchcombine.py [machinefile] [modeldir] [modelname] \
-[timestep] [nodex] [nodey] [nodez] [n-surf-cap] \
-[nprocx] [nprocy] [nprocz]</programlisting>
-                         where <filename>machinefile</filename> is the file with a list of all the machines you are using,
-                         which, under normal circumstances are the same as the launching nodes. 
-                         <filename>modeldir</filename> is the scratch directory where all your files
-                         are located. This should correspond to the first part of the <filename>datafile</filename>
-                         entry, for example <filename>/scratch/username</filename>. <filename>modelname</filename>
-                         is the model prefix , for example <filename>test_case</filename>. 
-                         <filename>timestep</filename> is the time step you want to export. This corresponds
-                         to the last term in the filename of the velocity file. <filename>nodex</filename>,
-                         <filename>nodey</filename>, <filename>nodez</filename> are the same values as
-                         those used in the input file. <filename>n-surf-cap</filename> is equal to 1 for
-                         regional CitComS and 12 for full CitComS. <filename>nprocx</filename>, 
-                         <filename>nprocy</filename>, <filename>nprocz</filename> is the same as in the input file.
-                    </para>
-                    <para>
-                         If your Beowulf cluster uses ssh (rather than rsh) to access the computation 
-                         nodes, you have to manually edit bin/batchpaste.sh and replace 'rsh' to 'ssh' 
-                         in the file. If your cluster forbids access to the computation nodes, you cannot
-                         use neither <filename>autocombine.py</filename> or <filename>batchcombine.py</filename>.
-                    </para>
-                    <para>
-                         Once <filename>autocombine.py</filename> or <filename>batchcombine.py</filename>
-                         has been run, you should end up with 2 files (or 24 files for full CitComS)
-                         that resemble these: <filename>test-case.cap0.10.general</filename> and
-                         <filename>test-case.cap0.10</filename>. Those are the input files for OpenDX. 
-                    </para>
-                </sect2>
-                        
-                <sect2><title>Postprocessing in a Non-Cluster Environment</title>
-                    <para>
-                        If you have run CitComS in a non-cluster environment or all of your data 
-                        are on local disk, you can still use <filename>autocombine.py</filename>
-                        or <filename>batchcombine.py</filename> to combine the data. The 
-                        machinefile is not needed and can be replaced by <filename>localhost</filename>,
-                        such as:
-                        <programlisting>$ autocombine.py localhost [input_param] \
-[step1] [step2 or more ...]</programlisting>
-                        or
-                        <programlisting>$ batchcombine.py localhost [modeldir] [modelname] [timestep] \
-[nodex] [nodey] [nodez] [n-surf-cap] \
-[nprocx] [nprocy] [nprocz]</programlisting>
-                    </para>
-                </sect2>
-                        
-                <sect2>
-                    <title>Using OpenDX for Regional Visualization</title>
-                    <para>
-                        OpenDX modules designed for CitComS can be found in the
-                        <filename>PREFIX/share/CitcomS/visual</filename> directory,
-                        where PREFIX is the directory under which you installed CitcomS
-                        (default <filename>/usr/local</filename>).
-                        You will need both the <filename>.net</filename> and
-                        <filename>.cfg</filename> files.
-                    </para>
-                    <para>
-                        In this example, you will use <filename>visRegional.net</filename>
-                        to visualize the result of regional CitComS.py. You should
-                        launch OpenDX by typing:
-                        <programlisting>$ dx</programlisting>
-                        You will see an OpenDX <guibutton>Data Explorer</guibutton> window. Click <guibutton>Edit Visual Programs</guibutton>
-                        and select <filename>visRegional.net</filename>. You will see a <guibutton>Visual Program Editor</guibutton>
-                        window. Then select on the <guibutton>import</guibutton> tab in the main window and double-click on the 
-                        <guibutton>File Selector</guibutton>
-                        block, which will open a <guibutton>Control Panel</guibutton> window. In the <guibutton>CitcomSImport</guibutton>
-                        filename input box, select your postprocessed data file, for example 
-                        <filename>test-case.cap0.10.general</filename> file. (For the global model, 
-                        select <guibutton>import</guibutton> tab, double-click the <guibutton>string</guibutton> block, enter the filename in  
-                        <guibutton>Citcoms Full Import format_string</guibutton> field.) In the pulldown menu, select 
-                        <guibutton>Execute</guibutton>
-                        -> <guibutton>Execute Once</guibutton> or <guibutton>Execute on Change</guibutton>. A new window will appear with the image 
-                        of the model. If you want to zoom, rotate, change projection and otherwise manipulate
-                        the view of the model, experiment with the menu <guibutton>Options</guibutton> -> <guibutton>View Control</guibutton>.
-                    </para>
-                    <figure>
-                        <title>Regional Model Visualized with OpenDX. A snapshot of an upwelling
-                            (blue isosurface) with a slice of the velocity field (bisecting plane).</title>
-                        <mediaobject id="c_fig5.eps">
-                            <imageobject role="fo">
-                                <imagedata fileref="graphics/c_fig5.eps"  format="EPS"/>
-                            </imageobject>
-                        </mediaobject>
-                    </figure>
-                    <para>Additional options in the control panel window for the regional model include:
-                        <itemizedlist spacing="compact">
-                            <listitem>
-                                <guilabel>CitcomSImport reduced</guilabel>, 
-                                can increase or reduce the resolution. </listitem>
-                            <listitem>
-                                <guilabel>Core radius</guilabel> is the size of the orange sphere.
-                                which represents the core-mantle boundary.</listitem>
-                            <listitem>
-                                <guilabel>Isosurface value</guilabel> is the temperature isosurfaces. You can change
-                                the values of the isosurfaces, including adding and deleting them.</listitem>
-                            <listitem>
-                                <guilabel>Slab cut dimension</guilabel> is the direction of the
-                                slab (an OpenDX term of cross-section).</listitem>
-                            <listitem>
-                                <guilabel>Slab cut position</guilabel> is the position of the
-                               slab.</listitem>
-                        </itemizedlist>
-                        After changing any of these parameters, you must select
-                        <guibutton>Execute</guibutton> -> <guibutton>Execute Once</guibutton> to redraw the model. You can change any of
-                        the parameters, visualization, or set-up by going back to the main window
-                        and clicking on each tab. If you click on each block, you will be
-                        able to change the settings for that function. </para>
-                </sect2>
-            </sect1>
-        </chapter>
-        <chapter>
-            <title>Cookbooks</title>
-            <sect1>
-                <title>Introduction</title>
-                <para>These cookbook examples are meant to serve as a guide to some of the 
-                    types of problems CitComS.py can solve. Cookbook examples range from regional
-                    to full spherical shell problems that address traditional convection problems.</para>
-            </sect1>
-            <sect1>
-                <title>Cookbook 1: Global Model Using <filename>fullcitcoms</filename>
-                </title>
-                <sect2>
-                    <title>Problem</title>
-                    <para>You would like to solve for thermal convection within a full spherical
-                        shell domain. One of the versions of CitComS.py is designed to run on a cluster that
-                        decomposes the shell into 12 equal "caps" and then distributes the
-                        calculation for caps onto separate processors. To run
-                        CitComS.py with the full solver parameter set, it is recommended that you have a minimum of
-                        12 processors available on your cluster. </para>
-                    <figure>
-                        <title>Global Model "Caps": Three-dimensional perspective image showing the
-                            12 spherical caps used in a full CitComS.py run. (A) The temperature field at 1081 km depth from a Cookbook 1 run. (B)
-                             </title>
-                        <mediaobject id="cookbook1">
-                            <imageobject role="fo">
-                                <imagedata fileref="graphics/cookbook1.eps" format="eps"/>
-                            </imageobject>
-                        </mediaobject>
-                    </figure>
-                </sect2>
-                <sect2>
-                    <title>Solution</title>
-                    <para>You will be running <filename>cookbook1.sh</filename> 
-                        which calls the script <filename>citcomsfull.sh</filename>. The first set of
-                        parameters specifies the number of nodes (12) and their names on your cluster
-                        through Pyre's <filename>launcher</filename> facility.</para>
-                    <programlisting>
---launcher.nodes=12 \
---launcher.nodegen="n%03d" \
---launcher.nodelist=[101-106,101-106] \
-</programlisting>
-                    <para>The second set of parameters specify the number of time steps (101), and
-                        how often the computation should be monitored (25).</para>
-                    <programlisting>
---steps=101 \
---controller.monitoringFrequency=25 \
-</programlisting>
-                    <para>The last set of parameters include the location of the output
-                            (<filename>/scratch/username/cookbook1</filename>), the number of
-                        perturbations (1), the number of nodal lines in the longitudinal direction
-                        (4), for example spherical harmonic in terms of time 
-                        steps order or <filename>perturbm=2</filename>,                    
-                        and the number of nodal lines in the latitudinal direction, for example spherical harmonic 
-                        degree <filename>perturbl=3</filename>. Note
-                        that although the number of perturbations is assigned here as
-                            <filename>solver.ic.num_perturbations=1</filename>, that is actually the
-                        default value.</para>
-                    
-                    <programlisting>
---solver.datafile="/scratch/username/cookbook1" \
-\
---solver.ic.num_perturbations=1 \
---solver.ic.perturbl=3 \
---solver.ic.perturbm=2 
-</programlisting>
-                    <para> Assuming your script is named <filename>cookbook1.sh</filename>, it is
-                        run by typing </para>
-<programlisting>$ ./cookbook1.sh</programlisting> 
-                    <example>
-                        <title>Cookbook 1: Global Model</title>
-                        <sidebar>
-                            <programlisting><![CDATA[#!/bin/sh
-  
-../../tests/citcomsfull.sh \
-\
---launcher.nodes=12 \
---launcher.nodegen="n%03d" \
---launcher.nodelist=[141-146,141-146] \
-\
---steps=101 \
---controller.monitoringFrequency=25 \
-\
---solver.datafile="/scratch/username/Test/cookbook1" \
-\
---solver.ic.num_perturbations=1 \
---solver.ic.perturbl=3 \
---solver.ic.perturbm=2 \
-\
---solver.rayleigh=5.0e+4
-                                
-# End of file]]></programlisting>
-                        </sidebar>
-                    </example>
-                    <para>Once you have run the model, you can visualize it using OpenDX, described
-                        in the previous chapter. When you invoke "Edit Visual Program," you will
-                        need to select <filename>visFull.net</filename>. </para>
-                    <figure>
-                        <title> Cookbook 1: Global Model. This image depicts a slice through a
-                            spherical model of convection, with warmer colors indicating upwelling
-                            and the cooler colors showing downwelling.</title>
-                        <mediaobject id="cookbook1.2">
-                            <imageobject role="fo">
-                                <imagedata fileref="graphics/cookbook1.2.jpg" format="JPG"
-                                />
-                            </imageobject>
-                        </mediaobject>
-                    </figure>
-                </sect2>
-                <sect2>
-                    <title>Discussion</title>
-                    <para>You have generated a simple example of the full CitComS model, with minimal parameter
-                        alterations. With a default Rayleigh number of 10<inlinemediaobject>
-                            <imageobject role="fo">
-                                <imagedata fileref="graphics/exp5.eps" format="EPS"/>
-                            </imageobject>
-                        </inlinemediaobject> and perturbation on the initial temperature field which has a degree<inlinemediaobject>
-                            <imageobject role="fo">
-                                <imagedata fileref="graphics/exp3.eps" format="EPS"/>
-                            </imageobject>
-                        </inlinemediaobject> and an order<inlinemediaobject>
-                            <imageobject role="fo">
-                                <imagedata fileref="graphics/exp2.eps" format="EPS"/>
-                            </imageobject>
-                        </inlinemediaobject> pattern, after 100 time steps, the convection 
-                        pattern remains relatively steady.</para><para>As a note, it is not required that 12 processors, with one spherical cap
-                        per processor, be used. As an end-member possibility, 12 different jobs could be run on
-                        a single computer by
-                        invoking:<programlisting>
---launcher.node=12 \
---launcher.node="n%03d" \
---launcher.nodelist=[101,101,101,101,101,101,101,101,101,101,101,101]\</programlisting>
-                        This is not particularly efficient, but it does illustrate the flexibility of both
-                        <filename>mpi</filename> and Pyre.</para>
-                </sect2>
-            </sect1>
-            <sect1>
-                <title>Cookbook 2: Velocity Boundary Conditions</title>
-                <sect2>
-                    <title>Problem</title>
-                    <para>You would like to solve for thermal convection and with velocity boundary
-                        conditions on the top surface within a given region of a sphere. As with
-                        Example 1, described in Chapter 3, you will need to modify a script that
-                        calls the regional version of CitComS,
-                        <filename>citcomsregional.sh</filename>. </para>
-                </sect2>
-                <sect2>
-                    <title>Solution</title>
-                    <para>You will be running <filename>cookbook2.sh</filename>, which calls the
-                        script <filename>citcomsregional.sh</filename>. The parameters specify the
-                        number of processors or nodes (4), time steps (61), the location of the
-                        output (<filename>/scratch/username/cookbook2</filename>), and how often the
-                        computation will be monitored (30).</para>
-                    <programlisting>
---steps=61 \
-\
---controller.monitoringFrequency=30 \
-\
---launcher.nodes=4 \
---launcher.nodegen="n%03d" \
---launcher.nodelist=[101-102,101-102] \
-\
---solver.datafile=/scratch/username/cookbook2 \
-</programlisting>
-                    <para>The <filename>solver.mesher</filename> has several properties involved in the generation of the computational mesh. Continue to use the default
-                        values for the physical portion of the domain in which you are interested.
-                        However, try modifing the layout of the mesh as shown. </para>
-                    <programlisting>
---solver.mesher.nprocx=2 \
---solver.mesher.nprocy=2 \
---solver.mesher.nodex=17 \
---solver.mesher.nodey=17 \
---solver.mesher.nodez=9 \
-</programlisting>
-
-                    <figure>
-                        <title>Computational View. Top view configuration of the layer of the
-                            computational nodes and the processors.</title>
-                        <mediaobject id="cookbook2">
-                            <imageobject role="html">
-                                <imagedata fileref="graphics/cookbook2.eps" format="PNG"/>
-                            </imageobject>
-                            <imageobject role="fo">
-                                <imagedata fileref="graphics/cookbook2.eps"  format="EPS"/>
-                            </imageobject>
-                        </mediaobject>
-                    </figure>
-                    <para>The <filename>solver.bc</filename> facility allows you to
-                        impose a uniform velocity across the top surface. You have a velocity which
-                        is purely in the colatitude direction with a non-dimensional velocity of
-                        100. (See Equation 6 in Chapter 1.) In addition, to determine the
-                        temperature, the temperature field associated only with this imposed
-                        velocity, reset the initial perturbation to zero, using the
-                            <filename>solver.ic</filename> facility. </para>
-                    <programlisting>--solver.bc.topvbc=1 \
---solver.bc.topvbxval=100 \
---solver.bc.topvbyval=0 \
-\
---solver.ic.num_perturbations=1 \
---solver.ic.perturbmag=0.0</programlisting>
-                    <example>
-                        <title>Cookbook 2: Velocity Boundary Conditions</title>
-                        <sidebar>
-                            <programlisting>
-<![CDATA[#!/bin/sh
-
-../../tests/citcomsregional.sh \
-\
---steps=61 \
-\
---controller.monitoringFrequency=30 \
-\
---launcher.nodes=4 \
---launcher.nodegen="n%03d" \
---launcher.nodelist=[101-102,101-102] \
-\
---solver.datafile=/scratch/username/cookbook2 \
-\
---solver.mesher.nprocx=2 \
---solver.mesher.nprocy=2 \
---solver.mesher.nodex=17 \
---solver.mesher.nodey=17 \
---solver.mesher.nodez=9 \
-\
---solver.bc.topvbc=1 \
---solver.bc.topvbxval=100 \
---solver.bc.topvbyval=0 \
-\
---solver.ic.num_perturbations=1 \
---solver.ic.perturbmag=0.0]]>
-</programlisting>
-                        </sidebar>
-                    </example>
-                    <figure>
-                        <title> Cookbook 2: Velocity boundary conditions. This model highlights a
-                            region of the overall sphere and the heated upwellings (warm colors),
-                            downwellings (cool colors), and the even distribution of the velocities
-                            (yellow arrows).</title>
-                        <mediaobject id="cookbook2.2">
-                            <imageobject role="fo">
-                                <imagedata fileref="graphics/cookbook2.2.eps" format="eps"
-                                />
-                            </imageobject>
-                        </mediaobject>
-                    </figure>
-                </sect2>
-                <sect2>
-                    <title>Discussion</title>
-                    <para>Using OpenDX to visualize the results (Figure 5.4), this
-                        model allows you to create a plate-model of convection in
-                        which there is a thermal upwelling on one wall, a thermal downwelling on
-                        another, and uniform horizontal velocity across the top. The downwelling is
-                        not exactly subduction because the default boundary conditions are close to
-                        zero shear stress on the boundaries. This means that there is a symmetrical
-                        downwelling in a vertical domain on the other side, which gives rise to
-                        symmetrical downwelling. </para>
-                </sect2>
-            </sect1>
-            <sect1>
-                <title>Cookbook 3: Temperature-dependant Viscosity</title>
-                <para/>
-                <sect2>
-                    <title>Problem</title>
-                    <para>A common problem in geophysics is the exploration of natural convection in the
-                        presence of variable viscosity, including temperature-dependant or
-                        stress-dependent viscosity.</para>
-                </sect2>
-                <sect2>
-                    <title>Solution</title>
-                    <para>You will be running <filename>cookbook3.sh</filename>, which calls the
-                        script <filename>citcomsregional.sh</filename>. The parameters specify the
-                        number of processors (4) and their names, time steps (200), the location of
-                        the output (<filename>/scratch/username/cookbook3</filename>) and how often
-                        the computation will be monitored (25).</para>
-                    <programlisting>--steps=200 \
-\
---controller.monitoringFrequency=25 \
-\
---launcher.nodes=4 \
---launcher.nodegen="n%03d" \
---launcher.nodelist=[101-102,101-102] \
---solver.datafile=/scratch/username/cookbook3 \</programlisting>
-                    <para>The <filename>solver.rayleigh</filename> indicates is the Rayleigh number
-                        you would like to set and the <filename>solver.visc </filename> parameters
-                        assign the viscosities.</para>
-                    <programlisting>           
---solver.rayleigh=1e6 \
---solver.visc.VISC_UPDATE=on \
---solver.visc.num_mat=4 \
---solver.visc.visc0=1,1,1,1 \
---solver.visc.TDEPV=on \
---solver.visc.viscE=0.2,0.2,0.2,0.2 \
---solver.visc.viscT=0,0,0,0 \
---solver.visc.VMIN=on \
---solver.visc.visc_min=1.0 \
---solver.visc.VMAX=on \
---solver.visc.visc_max=100.0
-               </programlisting>
-                    <example>
-                        <title>Cookbook 3: Temperature Dependant Viscosity</title>
-                        <sidebar>
-                            <programlisting><![CDATA[#!/bin/sh
-
-../../tests/citcomsregional.sh \
-\
---steps=200 \
-\
---controller.monitoringFrequency=25 \
-\
---launcher.nodes=4 \
---launcher.nodegen="n%03d" \
---launcher.nodelist=[101-102,101-102] \
-\
---solver.rayleigh=1e6 \
---solver.datafile=/scratch/username/cookbook3 \
-\
---solver.mesher.nprocx=2 \
---solver.mesher.nprocy=2 \
---solver.mesher.nodex=17 \
---solver.mesher.nodey=17 \
---solver.mesher.nodez=9 \
-\
---solver.visc.VISC_UPDATE=on \
---solver.visc.num_mat=4 \
---solver.visc.visc0=1,1,1,1 \
---solver.visc.TDEPV=on \
---solver.visc.viscE=0.2,0.2,0.2,0.2 \
---solver.visc.viscT=0,0,0,0 \
---solver.visc.VMIN=on \
---solver.visc.visc_min=1.0 \
---solver.visc.VMAX=on \
---solver.visc.visc_max=100.0]]>
-</programlisting>
-                        </sidebar>
-                    </example>
-                    <figure>
-                        <title> Cookbook 3: Velocity Boundary Conditions. This model highlights a
-                            region that features both the heated upwelling (warm colors) and the
-                            even distribution of the velocities (yellow arrows).</title>
-                        <mediaobject id="cookbook3">
-                            <imageobject role="fo">
-                                <imagedata fileref="graphics/cookbook3.eps" format="eps"
-                                />
-                            </imageobject>
-                        </mediaobject>
-                    </figure>
-                </sect2>
-            </sect1>
-            <sect1>
-                <title>Cookbook 4: Regionally Refined Meshes </title>
-                <para/>
-                <sect2>
-                    <title>Problem</title>
-                    <para>Frequently for convection problems, particularly those with variable
-                        viscosity, there are features with strong gradients in temperature
-                        or viscosity that can be better resolved with retired meshes. For example, 
-                        for the problem just studied in Cookbook 3, temperature dependant
-                        viscosity, a higher resolution is required for a narrow hot upwelling while a
-                        lower resolution is sufficient for the wider cold downwelling. </para>
-                </sect2>
-                <sect2>
-                    <title>Solution</title>
-                    <para>The parameter that controls if a mesh is to be uniform or refined
-                            <filename>cooor</filename>. Set the <filename>coor</filename> to
-                            <filename>ON (solver.mesher.coor=on)</filename> in order to read the
-                        uneven mesh point coordinates from an input file (such as
-                        <filename>coor.dat</filename>). The format of the coordinate input file,
-                            <filename>coor_file</filename>, is as follows. The file is an ASCII file
-                        with only one column, with each line for each mesh point, separated in three
-                        parts. Each part corresponds to the coordinates in the colatitude (in
-                        radians between <filename>theta_min</filename> and
-                        <filename>theta_max</filename>), longitude (in radians between
-                            <filename>fi_min</filename> and <filename>fi_max</filename>) and radial
-                        (non-dimensional between <filename>radius_inner</filename> and
-                            <filename>radius_outer</filename>) directions. The number of entries
-                        within each part must correspond exactly to the number of entries for the
-                        other parts. Also, each part has a header as follows:
-                        <filename>nsd=1</filename>, <filename>nsd=2</filename> and
-                        <filename>nsd=3</filename> for colatitude, longitude and radial direction
-                        respectively. </para>
-                    <example>
-                        <title>Cookbook 4: Regionally Refined Meshes Coordinate File Example</title>
-                        <sidebar>
-                            <programlisting><![CDATA[
-nsd=1 \
-theta_min \
-theta_max \
-\
-nsd=2 \
-fi_min \
-fi_max \
-\
-nsd=3 \
-radius_inner \
-radius_outer \
-                            ]]></programlisting>
-                        </sidebar>
-                    </example>
-                    <example>
-                        <title>Cookbook 4: Regionally Refined Meshes</title>
-                        <sidebar>
-                            <programlisting><![CDATA[#!/bin/sh
-
-../../tests/citcomsregional.sh \
-\
---steps=250 \
-\
---controller.monitoringFrequency=10 \
-\
---launcher.nodes=32 \
---launcher.nodegen="n%03d" \
---launcher.nodelist=[151-166,151-166] \
-\
---solver.rayleigh=1e6 \
---solver.datafile=/scratch/username/cookbook4 \
-\
---solver.ic.num_perturbations=1 \
---solver.ic.perturbmag=0.05 \
---solver.ic.perturbl=1 \
---solver.ic.perturbm=0 \
---solver.ic.perturblayer=10 \
-\
---solver.mesher.coor=on \
---solver.mesher.coor_file=/scratch/username/coor.dat \
---solver.mesher.nprocx=4 \
---solver.mesher.nprocy=4 \
---solver.mesher.nprocz=2 \
---solver.mesher.nodex=33 \
---solver.mesher.nodey=33 \
---solver.mesher.nodez=17 \
---solver.mesher.levels=1 \
---solver.mesher.theta_min=1 \
---solver.mesher.theta_max=2 \
---solver.mesher.fi_min=0 \
---solver.mesher.fi_max=1 \
-\
---solver.visc.VISC_UPDATE=on \
---solver.visc.num_mat=4 \
---solver.visc.visc0=1,1,1,1 \
---solver.visc.TDEPV=on \
---solver.visc.viscE=0.2,0.2,0.2,0.2 \
---solver.visc.viscT=0,0,0,0 \
---solver.visc.VMIN=on \
---solver.visc.visc_min=1.0 \
---solver.visc.VMAX=on \
---solver.visc.visc_max=100.0\]]></programlisting>
-                        </sidebar>
-                    </example>
-                    <figure>
-                        <title> Cookbook 4: This model shows the temperature (upwelling – warm
-                            colors, downwelling – cool colors) and the uneven distribution of the
-                            velocities (yellow arrows). Note the refined mesh for the left and
-                            bottom regions of the model (inset).</title>
-                        <mediaobject id="cookbook4">
-                            <imageobject role="fo">
-                                <imagedata fileref="graphics/cookbook4.eps" format="eps"
-                                />
-                            </imageobject>
-                        </mediaobject>
-                    </figure>
-                </sect2>
-                <sect2>
-                    <title>Discussion</title>
-                
-                <para>The resulting model is like a 2D model, but extends in the longitudinal direction. To
-                    set up this type of model, the initial temperature gradient was perturbed only
-                    in the longitudinal direction, by setting the parameters
-                    <filename>perturbl=1</filename> and <filename>perturbm=0</filename>. The model
-                    results show a thin thermal upwelling on one wall and a wide thermal
-                    downwelling on the opposite wall. Also, at the bottom of the model a thin layer
-                    of hot material can be shown. Note the higher resolution in the narrow regions
-                    with hot material and the lower resolution for the wide thermal downwelling
-                    region.</para></sect2>
-            </sect1>
-            <sect1>
-                <title>Cookbook 5: Subduction Models with Trench Rollback</title>
-                <para/>
-                <sect2>
-                    <title>Problem</title>
-                    <para>A common issue to address is the problem arising when the position of the oceanic trench is not constant in time (trench rollback) for a subduction zone. In addition, the trench rollback speed may vary in time, which can be caused, for example, by a rotation pole jump. 
-                    </para>
-                </sect2>
-                <sect2>
-                    <title>Solution</title>
-                    <para>In order to introduce in a convection model a trench rollback you have to prepare the velocity files. The following scenario is proposed for this cook book: there are two plates centered along the equator, with two different Euler poles (See figure 5.1). Initially, both plates have Euler poles situated far, so the velocities are approximately constants ( about 5 cm/yr for the left plate and  about 2 cm/yr for the right plate). After 30 Ma a pole jump occurred for the right slab only, so the Euler pole moved closer. Since we impose a top velocity boundary in our model, the following facilities should be turned on: </para>
-                    <programlisting>
---solver.bc.topvbc=1 \
---solver.param.file_vbcs=on \</programlisting>
-                    <para>The following two lines specify the location of the velocity files and the starting age for the model: 
-                    </para>
-                    <programlisting>
---solver.param.vel_bound_file=$PWD/velocity/vel.dat \
---solver.param.start_age=55 \
-                    </programlisting>   <para>
-                        Since the starting age is set to 55 Ma, there will be 56 velocity files, one for each Ma (<filename>vel.dat0, vel.dat1,...vel.dat55, vel.dat56</filename>). The format of the velocity file is a two column ACSII file format as following: </para>
-                    <programlisting>
-v_theta     v_fi
-......</programlisting>
-     <para>
-         There will be as many line as the total number of nodes for the top plane (<filename>n_theta * n_fi</filename>). </para>
-                    <example>
-                        <title>Cookbook 5: Subductions Models with Trench Rollback</title>
-                        <sidebar>
-                            <programlisting><![CDATA[#!/bin/sh
-../../tests/citcomsregional.sh 
-\
-\--steps=1000 
-\
-\--controller.monitoringFrequency=10 
-\
-\--launcher.nodes=64 
-\--launcher.nodegen="n%03d" 
-\--launcher.nodelist=[131-162] 
-\
-\--solver.datafile=/scratch/username/cookbook5 
-\--solver.rayleigh=4.07e+08 
-\
-\--solver.bc.topvbc=1 
-\--solver.param.file_vbcs=on 
-\--solver.param.vel_bound_file=$PWD/velocity/bvel.dat 
-\--solver.param.start_age=55 
-\
-\--solver.ic.restart=on 
-\--solver.ic.solution_cycles_init=0 
-\--solver.datafile_old=$PWD/restart_files/cookbook5 
-\
-\--solver.bc.temperature_bound_adj=off 
-\--solver.bc.depth_bound_adj=0.157000 
-\--solver.bc.width_bound_adj=0.050000 
-\
-\--solver.mesher.coor=on 
-\--solver.mesher.coor_file=$PWD/coor.dat 
-\--solver.mesher.mgunitx=2 
-\--solver.mesher.nprocx=2 
-\--solver.mesher.nprocy=8 
-\--solver.mesher.nprocz=4 
-\--solver.mesher.nodex=17 
-\--solver.mesher.nodey=65 
-\--solver.mesher.nodez=33 
-\--solver.mesher.levels=1 
-\--solver.mesher.theta_min=1.47 
-\--solver.mesher.theta_max=1.67 
-\--solver.mesher.fi_min=0 
-\--solver.mesher.fi_max=0.5 
-\--solver.mesher.radius_inner=0.7 
-\
-\--solver.visc.VISC_UPDATE=on 
-\--solver.visc.rheol=3 
-\                                
-\--solver.const.refvisc=4e+21 
-\--solver.visc.num_mat=4 
-\--solver.visc.visc0=100,0.003,1,2 
-\--solver.visc.TDEPV=on 
-\--solver.visc.viscE=24,24,24,24 
-\--solver.visc.viscT=0.182,0.182,0.182,0.182 
-\--solver.visc.VMIN=on 
-\--solver.visc.visc_min=0.01 
-\--solver.visc.VMAX=on 
-\--solver.visc.visc_max=100.0 
-\
-\# End of file]]></programlisting>
-    </sidebar>
-</example>
-                    
-                    
-                    
-                    
-                    
-                    <figure>
-                        <title> Cookbook 5: Left (A): initially, both plates have Euler poles (magenta and green dots) situated far, so the velocities are approximately constants (about 5 cm/yr for the left plate and about 2 cm/yr for the right plate). Right (B): after 30 Ma a pole jump occurred for the right slab only, so the Euler pole moved closer.</title>
-                        <mediaobject id="cookbook5">
-                            <imageobject role="fo">
-                                <imagedata fileref="graphics/cookbook5.eps" format="EPS"
-                                />
-                            </imageobject>
-                        </mediaobject>
-                    </figure>
-                    
-                    
-                    <figure>
-                        <title> Cookbook 5: the pole jump after 30 Ma produced a flat slab on one side (fore side) and a steep slab on the other side (back side). </title>
-                        <mediaobject id="cookbook5.2">
-                            <imageobject role="fo">
-                                <imagedata fileref="graphics/cookbook5.2.eps" format="EPS"
-                                    />
-                            </imageobject>
-                        </mediaobject>
-                    </figure>
-                    </sect2>
-                    
-                   <sect2>
-                    <title>Discussion</title>
-                
-                       <para>The results for this problem are presented in Figure 5.8. Since the two Euler poles are kept fixed for the first 30 Ma, the shape of the subducting slab will be the same along the trench. At 25 Ma the Euler pole for the right plate jumps toward the plate. Therefore, the velocity along the trench varies from about 1 cm/yr to about 2.5 cm/yr. This will produce in time a flat slab at one side of the model, and a steep slab at the other side (Fig.5.8). 
-                       </para></sect2>
-            </sect1>
-            
-            <sect1>
-                <title>Cookbook 6: Pseudo-free-surface Formulation</title>
-                <para/>
-                <sect2>
-                    <title>Problem</title>
-                    <para>Free-slip boundary conditions are typically applied on the top surface of
-                        mantle convection models and the dynamic topography is obtained by assuming
-                        that the normal stress on the top surface is instantaneously compensated by
-                        the deformed surface. This type of boundary conditions works well for
-                        long-wavelength topography, but a free-surface formulation becomes necessary
-                        in cases where intermediate to short wavelength topography is of interest or
-                        lithosphere has a very high effective viscosity. Another situation where
-                        free-surface formulation desired is when two Pyre solvers, Snac and Citcom,
-                        are coupled.</para>
-                    <para>The basic algorithm (16) and (17) consists of four steps. 1. On the
-                        nodes of the top surface, topography increment computed is by integrating
-                        normal velocity over time. 2. The normal traction on the top surface is
-                        calculated based on the accumulated topography up to the current time step,
-                        and added to the forcing term in the matrix version of the momentum
-                        equation. 3. Update velocity field with the changed forcing term. 4. If
-                        velocity field has not converged yet, reiterate steps 1 from 3.</para>
-                </sect2>
-                <sect2>
-                    <title>Solution</title>
-                    <para>To verify if the above algorithm works, you will run two different
-                        Citcom-only models with each B.C. (free-slip and pseudo-free-surface) and
-                        compare the topography computed accordingly. The scripts
-                            <filename>citcom_only_freeslip.sh</filename>,
-                            <filename>citcom_only_freesurf.sh</filename> will include the following
-                        parameters.</para>
-                    <itemizedlist  spacing="compact">
-                        <listitem>Domain size: 45 deg x 45 deg x 1200 km</listitem>
-                        <listitem>Mesh size: 61 x 61 x 25 with mesh refinement (coord.dat)</listitem>
-                        <listitem>BC: free-slip/free-surface for top. free-slip for all the other
-                            surfaces</listitem>
-                        <listitem>IC: spherical hot blob with diameter of 1/4 of radial dimension is
-                            placed at the center of the domain</listitem>
-                    </itemizedlist>
-                    <itemizedlist  spacing="compact">
-                        <listitem>specific options:</listitem>
-                        <listitem>tsolver.fixed_timestep=7.770000e-10 (= ~1000 yrs)</listitem>
-                        <listitem>vsolver.BC.pseudo_free_surf=on/off</listitem>
-                        <listitem>scripts for running test models:
-                            <filename>citcom_only_freeslip.sh</filename>,
-                                <filename>citcom_only_freesurf.sh</filename>
-                        </listitem>
-                    </itemizedlist>
-                </sect2>
-                <sect2>
-                    <title>Discussion</title>
-                    <para>The plots of topography profile are consistent with results described in
-                        (16). In the graphs below, the solid line
-                        indicates free-slip and the dashed line indicates free-surface. Note: the
-                        unit of x axis is radians, not degrees. </para>
-                    <figure>
-                        <title>Cookbook 6. Graphs of topography profiles. </title>
-                        <mediaobject id="cookbook7">
-                            <imageobject>
-                                <imagedata fileref="graphics/cookbook7.eps" format="EPS"/>
-                            </imageobject>
-                        </mediaobject>
-                    </figure>
-                </sect2>
-            </sect1>
-        </chapter>
-        
-    </part>
-    <part>
-        <title>Appendices</title>
-        <appendix>
-            <title>Facilities, Properties, and Parameters</title>
-            <sect1>
-                <title>Introduction</title>
-                <para> Most of the properties have identical names as the parameters as those used
-                    in the regular version of CitComS. This section highlights those which have
-                    changed and those which are entirely new. All the parameters which can be set
-                    are included in an appendix at the end of this documentation. Parameters are
-                    given with their default values. </para>
-                <sect2>
-                    <title>Parameters that Control Input Files</title>
-                    <informaltable>
-                        <tgroup cols="2">
-                            <colspec colnum="1" colname="col1" colwidth="1*"/>
-                            <colspec colnum="2" colname="col2" colwidth="2*"/>
-                            <tbody valign="top">
-                                <row>
-                                    <entry> datafile="" </entry>
-                                    <entry> datafile controls the location of output files and the
-                                        prefix of their names. In this case the directory /scratch/
-                                        must be created a priori. Files such as test.xxx. For
-                                        example, datafile="/scratch/test" </entry>
-                                </row>
-                                <row>
-                                    <entry> file_vbcs=0 </entry>
-                                    <entry> If file_vbcs is true (it is set=1) then the top surface
-                                        velocity boundary conditions are read in from files which
-                                        have location and name specified by vel_bound_file. The
-                                        conditions on the top surface must be correctly set, as
-                                        indicated below. If you wish to have a uniform top surface
-                                        velocity boundary condition or some simple geometric
-                                        pattern, then file_vbcs should be set to zero. </entry>
-                                </row>
-                                <row>
-                                    <entry> vel_bound_file="" </entry>
-                                    <entry> See explanation the entry for file_vbcs, above. Velocity
-                                        boundary conditions are read by setting the pathway to the
-                                        boundary conditions file, for example
-                                        vel_bound_file="/username/Models/New_Tonga/Vel/bvel.dat"
-                                    </entry>
-                                </row>
-                                <row>
-                                    <entry> coor=off </entry>
-                                    <entry> If you wish to have a regular, but uneven, spacing
-                                        between elements then coor should be set to on. If coor is
-                                        set to off, then there will be uniform mesh in the
-                                        latitudinal, longitudinal, and radial directions. For
-                                        example,
-                                        coor_file="/username/Models/New_Tonga/Case2/coor.dat"
-                                    </entry>
-                                </row>
-                                <row>
-                                    <entry> coor_file="" </entry>
-                                    <entry> See coor, above. For example,
-                                        coor_file="/username/Models/New_Tonga/Case2/coor.dat"
-                                    </entry>
-                                </row>
-                                <row>
-                                    <entry> mat_control=0 </entry>
-                                    <entry> mat_file="/home/clint/back/ra8/mat.dat" If mat_control
-                                        is true (it is set=1) then the time- and
-                                        positional-dependent viscosity factor is defined by file
-                                        having location and name specified bymat_file. These
-                                        parameters allow you to define the material group of each
-                                        element (such as a moving weak zone). </entry>
-                                </row>
-                                <row>
-                                    <entry> lith_age=0 </entry>
-                                    <entry> lith_age_file="/username/Models/New_Tonga/Case6/age.dat"
-                                        If lith_age is true (it is set=1) then the lith_age_file is
-                                        read. These parameters control the thermal age of the top
-                                        thermal boundary condition. </entry>
-                                </row>
-                                <row>
-                                    <entry> tracer=0 </entry>
-                                    <entry> tracer_file="" This controls the tracer particles which
-                                        are advected passively by the flow. This part of the code
-                                        has not been made parallel and must be used with caution
-                                        with the present implementation. </entry>
-                                </row>
-                            </tbody>
-                        </tgroup>
-                    </informaltable>
-                </sect2>
-                <sect2>
-                    <title>Mesh Set-up and Processors</title>
-                    <para> Parameters control the logical set-up of the mesh as well as the number
-                        of processors in the three coordinate directions. </para>
-                    <informaltable>
-                        <tgroup cols="2">
-                            <colspec colnum="1" colname="col1" colwidth="1*"/>
-                            <colspec colnum="2" colname="col2" colwidth="2*"/>
-                            <tbody valign="top">
-                                <row>
-                                    <entry> nproc_surf=1 </entry>
-                                    <entry> This specifies the number of spherical caps of the mesh,
-                                        must be 1 for CitComS.py and 12 for fullCitComS. </entry>
-                                </row>
-                                <row>
-                                    <entry>
-                                        <simplelist>
-                                            <member> nprocx=2 </member>
-                                            <member> nprocy=2 </member>
-                                            <member> nprocz=1 </member>
-                                        </simplelist>
-                                    </entry>
-                                    <entry> These specify the number of processors in each spherical
-                                        cap. </entry>
-                                </row>
-                                <row>
-                                    <entry>
-                                        <simplelist>
-                                            <member> nodex=17 </member>
-                                            <member> nodey=17 </member>
-                                            <member> nodez=9 </member>
-                                        </simplelist>
-                                    </entry>
-                                    <entry> These specify the number of FEM nodes in each spherical
-                                        cap. </entry>
-                                </row>
-                                <row>
-                                    <entry>
-                                        <simplelist>
-                                            <member> mgunitx=8 </member>
-                                            <member> mgunity=8 </member>
-                                            <member> mgunitz=8 </member>
-                                            <member> levels=1 </member>
-                                        </simplelist>
-                                    </entry>
-                                    <entry> These specify the nested level of multigrid unit. Used
-                                        by multigrid solver only. These parameters are not
-                                        completely independent to each other. Some constraints must
-                                        be satisfied: <simplelist>
-                                            <member> nodex = 1 + nprocx * mgunitx * 2 ** (levels-1) </member>
-                                            <member> nodey = 1 + nprocy * mgunity * 2 ** (levels-1) </member>
-                                            <member> nodez = 1 + nprocz * mgunitz * 2 **
-                                            (levels-1)</member>
-                                        </simplelist>
-                                    </entry>
-                                </row>
-                                <row>
-                                    <entry>
-                                        <simplelist>
-                                            <member> nprocx = nprocy; </member>
-                                            <member> nodex = nodey; </member>
-                                            <member> mgunitx = mgunity; </member>
-                                        </simplelist>
-                                    </entry>
-                                    <entry> For fullCitComS only </entry>
-                                </row>
-                            </tbody>
-                        </tgroup>
-                    </informaltable>
-                </sect2>
-                <sect2>
-                    <title>Domain Size</title>
-                    <para> Parameters which control the actual physical size of the domain (a cut
-                        out of a sphere). </para>
-                    <informaltable>
-                        <tgroup cols="2">
-                            <colspec colnum="1" colname="col1" colwidth="1*"/>
-                            <colspec colnum="2" colname="col2" colwidth="2*"/>
-                            <tbody valign="top">
-                                <row>
-                                    <entry>
-                                        <simplelist>
-                                            <member> theta_min=1.0780 theta_max=2.0708 </member>
-                                            <member> fi_min=0 </member>
-                                            <member> fi_max=1 </member>
-                                        </simplelist>
-                                    </entry>
-                                    <entry> theta_min and theta_max are the colatitude measured in
-                                        radians from the north pole. fi_min and fi_max are the
-                                        longitudes measured from the prime meridian eastward in
-                                        radians. Only in CitComS.py. </entry>
-                                </row>
-                                <row>
-                                    <entry>
-                                        <simplelist>
-                                            <member> radius_inner=0.55 </member>
-                                            <member> radius_outer=1.0 </member>
-                                        </simplelist>
-                                    </entry>
-                                    <entry> radius_inner and radius_outer are the inner and outer
-                                        radius in non-dimensional unit. It is probably most
-                                        convenient to normalize lengths by the radius of the Earth.
-                                        If you do this, then the Rayleigh number, given below, must
-                                        be calculated with the radius of the Earth, not the
-                                        thickness of the mantle. The core mantle boundary is close
-                                        to having a non-dimensional radius of 0.55. </entry>
-                                </row>
-                            </tbody>
-                        </tgroup>
-                    </informaltable>
-                </sect2>
-                <sect2>
-                    <title>Restarting the Code</title>
-                    <para> Parameters which control the restarting of the code. </para>
-                    <informaltable>
-                        <tgroup cols="2">
-                            <colspec colnum="1" colname="col1" colwidth="1*"/>
-                            <colspec colnum="2" colname="col2" colwidth="2*"/>
-                            <tbody valign="top">
-                                <row>
-                                    <entry>
-                                        <simplelist>
-                                            <member> restart=0 </member>
-                                            <member> post_p=0 </member>
-                                            <member> datafile_old="" </member>
-                                            <member> solution_cycles_init=100 </member>
-                                        </simplelist>
-                                    </entry>
-                                    <entry> If restart is true, for example, processor #5 will read
-                                        its initial temperature field formfile
-                                        /scratch/test.velo.5.100 in this case. If post_p is true,
-                                        for example, processor #5 will read its initial temperature
-                                        field form file /scratch/test.velo.5.100 in this case, just
-                                        like when restart is true. But the program will run for 1
-                                        time step only. </entry>
-                                </row>
-                                <row>
-                                    <entry> zero_elapsed_time=1 </entry>
-                                    <entry> If zero_elapsed_time is true, the initial time is set to
-                                        zero. If it is false and restart or post_p is true, the
-                                        initial time is read in from previous output files. </entry>
-                                </row>
-                            </tbody>
-                        </tgroup>
-                    </informaltable>
-                </sect2>
-                <sect2>
-                    <title>Run Length, Output Interval</title>
-                    <para> Parameters which control the length of the run and the interval between
-                        writing output files. </para>
-                    <informaltable>
-                        <tgroup cols="2">
-                            <colspec colnum="1" colname="col1" colwidth="1*"/>
-                            <colspec colnum="2" colname="col2" colwidth="2*"/>
-                            <tbody valign="top">
-                                <row>
-                                    <entry>
-                                        <simplelist>
-                                            <member> minstep=1 </member>
-                                            <member> run=8001 </member>
-                                            <member> maxtotstep=8001 </member>
-                                            <member> monitoringFrequency=10 </member>
-                                            <member> cpu_limits_in_seconds= </member>
-                                            <member> 360000000 </member>
-                                        </simplelist>
-                                    </entry>
-                                    <entry> The maximum number of time steps is set with run and
-                                        maxtotstep. It is recommended that these be set to the same
-                                        value. Add one to the total number of steps; in this
-                                        example, the total steps is 8000. The minimum numbers of
-                                        time steps is set with minstep. monitoringFrequency controls
-                                        the interval between output files. CitComS dynamically
-                                        determines the non-dimensional time step (such as _t), this
-                                        means that you might not get an output at the exact time
-                                        required, but you can always get close depending on how
-                                        small monitoringFrequency is. Do not make this number too
-                                        small since outputs slow the code down and you may end up
-                                        with an unmanageable number of output files. You can also
-                                        control the termination of the code based on total wall
-                                        clock time using cpu_limits_in_seconds. If you are just
-                                        learning to use the code, you might want to give this a
-                                        small value so that it doesn't burn up valuable computer
-                                        time. </entry>
-                                </row>
-                            </tbody>
-                        </tgroup>
-                    </informaltable>
-                </sect2>
-                <sect2>
-                    <title>Initial Conditions </title>
-                    <informaltable>
-                        <tgroup cols="2">
-                            <colspec colnum="1" colname="col1" colwidth="1*"/>
-                            <colspec colnum="2" colname="col2" colwidth="2*"/>
-                            <tbody valign="top">
-                                <row>
-                                    <entry>
-                                        <simplelist>
-                                            <member> num_perturbations=1 </member>
-                                            <member> perturbmag=0.05 </member>
-                                            <member> perturbl=1 </member>
-                                            <member> perturbm=1 </member>
-                                            <member> perturblayer=5 </member>
-                                        </simplelist>
-                                    </entry>
-                                    <entry> The initial temperature is a linear temperature gradient
-                                        with some perturbations.  num_perturbations
-                                        specifies the number of perturbations. 
-                                        The amplitude of the perturbations
-                                        is specified in the list of real numbers by perturbmag. In
-                                        fullCitComS, perturbl and perturbm specify the shape of the
-                                        perturbations in spherical harmonic degree and order;
-                                        perturblayer specifies the layers to be perturbed. In
-                                        regitcoms , perturbl and preturbm specify the number of
-                                        nodal lines in longitudinal and latitudinal directions;
-                                        perturblayer is not used though the pertublayer represents
-                                        the number of the mesh node in radiad direction. There must
-                                        be as many entries in a comma-separated list as in
-                                        num_perturbations . No spaces are allowed in the list.
-                                    </entry>
-                                </row>
-                            </tbody>
-                        </tgroup>
-                    </informaltable>
-                </sect2>
-                <sect2>
-                    <title>Boundary Conditions</title>
-                    <informaltable>
-                        <tgroup cols="2">
-                            <colspec colnum="1" colname="col1" colwidth="1*"/>
-                            <colspec colnum="2" colname="col2" colwidth="2*"/>
-                            <tbody valign="top">
-                                <row>
-                                    <entry>
-                                        <simplelist>
-                                            <member> topvbc=0 </member>
-                                            <member> topvbxval=0.0 </member>
-                                            <member> topvbyval=0.0 </member>
-                                        </simplelist>
-                                    </entry>
-                                    <entry> Surface velocity boundary condition parameters. If
-                                        topvbc is 0, the topvbxval and topvbyval specify the
-                                        tangential surface stress (forced BC). If topvbc is 1,
-                                        topvbxval and topvbyval specify the tangential surface
-                                        velocity (fixed BC). The surface normal velocity is zero in
-                                        these two cases (impermeable BC). If topvbc is 2, the
-                                        surface normal and tangential stress are zero (permeable
-                                        BC). </entry>
-                                </row>
-                                <row>
-                                    <entry>
-                                        <simplelist>
-                                            <member> botvbc=0 </member>
-                                            <member> botvbxval=0.0 </member>
-                                            <member> botvbyval=0.0 </member>
-                                        </simplelist>
-                                    </entry>
-                                    <entry> As above, but for bottom velocity boundary conditions.
-                                    </entry>
-                                </row>
-                                <row>
-                                    <entry>
-                                        <simplelist>
-                                            <member> toptbc=1 </member>
-                                            <member> toptbcval=0.0 </member>
-                                        </simplelist>
-                                    </entry>
-                                    <entry> Surface temperature boundary conditions. If toptbc is 0,
-                                        the toptbcval specifies the surface heatflux. If toptbc is 1,
-                                        the toptbcval specifies the surface temperature. </entry>
-                                </row>
-                                <row>
-                                    <entry>
-                                        <simplelist>
-                                            <member> bottbc=1 </member>
-                                            <member> bottbcval=1.0 </member>
-                                        </simplelist>
-                                    </entry>
-                                    <entry> As above, but for bottom temperature boundary
-                                        conditions. </entry>
-                                </row>
-                                <row>
-                                    <entry>
-                                        <simplelist>
-                                            <member> lith_age_time=0 </member>
-                                            <member> lith_age_depth=0.031400 </member>
-                                            <member> mantle_temp=1.000000 </member>
-                                            <member> temperature_bound_adj=0 </member>
-                                            <member> depth_bound_adj=0.157000 </member>
-                                            <member> width_bound_adj=0.087270 </member>
-                                        </simplelist>
-                                    </entry>
-                                    <entry> Boundary condition when lith_age is true. </entry>
-                                </row>
-                            </tbody>
-                        </tgroup>
-                    </informaltable>
-                </sect2>
-                <sect2>
-                    <title>Miscellaneous</title>
-                    <para> The following are some miscellaneous parameters. </para>
-                    <informaltable>
-                        <tgroup cols="2">
-                            <colspec colnum="1" colname="col1" colwidth="1*"/>
-                            <colspec colnum="2" colname="col2" colwidth="2*"/>
-                            <tbody valign="top">
-                                <row>
-                                    <entry>
-                                        <simplelist>
-                                            <member> stokes_flow_only=0 </member>
-                                            <member> inputdiffusivity= </member>
-                                            <member> 0.001000 </member>
-                                        </simplelist>
-                                    </entry>
-                                    <entry> stokes_flow_only is a parameter which can lead to
-                                        confusion. If you wish only to solve for the velocity once
-                                        (e.g. Stokes flow) than set then make this parameter true
-                                        (i.e. 1 or on). However, you want to do convection problem
-                                        then this should be false, as indicated in the example. At
-                                        this point, don't change the parameter inputdiffusivity-this
-                                        may play a role in problems which are integrated backward in
-                                        time. </entry>
-                                </row>
-                                <row>
-                                    <entry> rayleigh=1.357e+08 </entry>
-                                    <entry> This specifies the Rayleigh number, which is one of the
-                                        most important parameters you may want to change. It is
-                                        defined as Q0=0.0 This specifies the internal heating
-                                        number. </entry>
-                                </row>
-                            </tbody>
-                        </tgroup>
-                    </informaltable>
-                </sect2>
-                <sect2>
-                    <title>Required Information</title>
-                    <informaltable>
-                        <tgroup cols="2">
-                            <colspec colnum="1" colname="col1" colwidth="1*"/>
-                            <colspec colnum="2" colname="col2" colwidth="2*"/>
-                            <tbody valign="top">
-                                <row>
-                                    <entry>
-                                        <simplelist>
-                                            <member> Problem=convection </member>
-                                            <member> Geometry=sphere </member>
-                                            <member> Spacing=regular </member>
-                                            <member> Solver=cgrad </member>
-                                            <member> node_assemble=1 </member>
-                                        </simplelist>
-                                    </entry>
-                                    <entry> For the version of CitComS you received in your
-                                        distribution, all of these parameters must be set as
-                                        indicated. You need other versions of CitComS if you wish
-                                        these parameters to take on different geometries, problems,
-                                        mesh spacing or use different solvers. </entry>
-                                </row>
-                            </tbody>
-                        </tgroup>
-                    </informaltable>
-                </sect2>
-                <sect2>
-                    <title>Depth Information</title>
-                    <informaltable>
-                        <tgroup cols="2">
-                            <colspec colnum="1" colname="col1" colwidth="1*"/>
-                            <colspec colnum="2" colname="col2" colwidth="2*"/>
-                            <tbody valign="top">
-                                <row>
-                                    <entry>
-                                        <simplelist>
-                                            <member> z_lith=0.014 </member>
-                                            <member> z_410=0.06435 </member>
-                                            <member> z_lmantle=0.105 </member>
-                                            <member> z_cmb=0.439 </member>
-                                        </simplelist>
-                                    </entry>
-                                    <entry> Specify the non-dimensional depth of Moho, 410km
-                                        discontinuity, 660km discontinuity and D". These parameters
-                                        are used to determine the depth of material interfaces and
-                                        phase changes (see next two sections). The names are only
-                                        suggestive. You are free to refer z_lith to an arbitrary
-                                        depth, for example. </entry>
-                                </row>
-                            </tbody>
-                        </tgroup>
-                    </informaltable>
-                </sect2>
-                <sect2>
-                    <title>Viscosity</title>
-                    <para> Parameters which control the viscosity. </para>
-                    <informaltable>
-                        <tgroup cols="2">
-                            <colspec colnum="1" colname="col1" colwidth="1*"/>
-                            <colspec colnum="2" colname="col2" colwidth="2*"/>
-                            <tbody valign="top">
-                                <row>
-                                    <entry>
-                                        <simplelist>
-                                            <member> Viscosity=system </member>
-                                            <member> rheol=3 </member>
-                                        </simplelist>
-                                    </entry>
-                                    <entry> For the version of CitComS you received in your
-                                        distribution, all of these parameters must be set as
-                                        indicated. When rheol=3, temperature dependent viscosity is
-                                        computed by: viscosity = visc0 * exp( viscE/(T+viscT) -
-                                        viscE/(1+viscT) ) </entry>
-                                </row>
-                                <row>
-                                    <entry> visc_smooth_method=3 </entry>
-                                    <entry> This specifies which method to smooth viscosity
-                                        projection for multigrid solver. </entry>
-                                </row>
-                                <row>
-                                    <entry> VISC_UPDATE=on </entry>
-                                    <entry> If visc_update is true (e.g. 1 or on), viscosity is
-                                        updated every time step by the following parameters.
-                                    </entry>
-                                </row>
-                                <row>
-                                    <entry> num_mat=4 </entry>
-                                    <entry> This specifies the number of material layers. Material 1
-                                        is at depth between 0 and z_lith, material 2 is between
-                                        z_lith and z_410, material 3 is between z_410 and z_lmantle,
-                                        and material 4 is between z_lmantle and (radius_outer -
-                                        radius_inner). If mat_control is true, then a multiplicative
-                                        factor is applied to the viscosity, as defined below.
-                                    </entry>
-                                </row>
-                                <row>
-                                    <entry>
-                                        <simplelist>
-                                            <member> TDEPV=on </member>
-                                            <member> viscE=0.1,0.1,1.0,1.0 </member>
-                                            <member> viscT=-1.02126, </member>
-                                            <member> -1.01853,-1.32722, </member>
-                                            <member> -1.32722 </member>
-                                            <member> visc0=1.0e2,2.e-3, </member>
-                                            <member> 2.e0,2.e1 </member>
-                                        </simplelist>
-                                    </entry>
-                                    <entry> If TDEPV is true (e.g. 1 or on), viscE, viscT, and visc0
-                                        are parameters defining viscosity law. See the equation
-                                        above. There must be as many entries in a comma-separated
-                                        list as num_mat. No space is allowed in the list. </entry>
-                                </row>
-                                <row>
-                                    <entry>
-                                        <simplelist>
-                                            <member> SDEPV=off </member>
-                                            <member> sdepv_expt=1,1,1,1,1,1,1,1 </member>
-                                            <member> sdepv_misfit=0.020 </member>
-                                        </simplelist>
-                                    </entry>
-                                    <entry> If SDEPV is true (e.g. 1 or on), these specify the
-                                        exponent in the viscosity law and the criterion of
-                                        convergence test. There must be as many entries in a
-                                        comma-separated list as num_mat. No space is allowed in the
-                                        list. </entry>
-                                </row>
-                                <row>
-                                    <entry>
-                                        <simplelist>
-                                            <member> VMIN=on visc_min=1.e-4 </member>
-                                            <member> VMAX=on visc_max=1.e3 </member>
-                                        </simplelist>
-                                    </entry>
-                                    <entry> If VMIN is true (e.g. 1 or on), minimum viscosity is cut
-                                        off at visc_min. VMAX and visc_max are for the maximum
-                                        viscosity cutoff. </entry>
-                                </row>
-                            </tbody>
-                        </tgroup>
-                    </informaltable>
-                </sect2>
-                <sect2>
-                    <title>Phase Change Information</title>
-                    <informaltable>
-                        <tgroup cols="2">
-                            <colspec colnum="1" colname="col1" colwidth="1*"/>
-                            <colspec colnum="2" colname="col2" colwidth="2*"/>
-                            <tbody valign="top">
-                                <row>
-                                    <entry>
-                                        <simplelist>
-                                            <member> Ra_410=0.0 clapeyron410=0.0235 </member>
-                                            <member> transT410=0.78 </member>
-                                            <member> width410=0.0058 </member>
-                                        </simplelist>
-                                    </entry>
-                                    <entry> These specify the phase change parameters (density
-                                        change, Clapeyron slope, ambient temperature, and phase
-                                        change width, respectively). The depth of this phase change
-                                        is specified by z_410. </entry>
-                                </row>
-                                <row>
-                                    <entry>
-                                        <simplelist>
-                                            <member> Ra_670=0.0 </member>
-                                            <member> clapeyron670=-0.0235 </member>
-                                            <member> transT670=0.875 </member>
-                                            <member> width670=0.0058 </member>
-                                        </simplelist>
-                                    </entry>
-                                    <entry> As above. The depth of this phase change is specified by
-                                        z_lmantle. </entry>
-                                </row>
-                                <row>
-                                    <entry>
-                                        <simplelist>
-                                            <member> Ra_cmb=0.0 </member>
-                                            <member> clapeyroncmb=-0.0235 </member>
-                                            <member> transTcmb=0.875 </member>
-                                            <member> widthcmb=0.0058 </member>
-                                        </simplelist>
-                                    </entry>
-                                    <entry> As above. The depth of this phase change is specified by
-                                        z_cmb. </entry>
-                                </row>
-                            </tbody>
-                        </tgroup>
-                    </informaltable>
-                </sect2>
-                <sect2>
-                    <title>Dimensional Information</title>
-                    <informaltable>
-                        <tgroup cols="2">
-                            <colspec colnum="1" colname="col1" colwidth="1*"/>
-                            <colspec colnum="2" colname="col2" colwidth="2*"/>
-                            <tbody valign="top">
-                                <row>
-                                    <entry>
-                                        <simplelist>
-                                            <member> layerd=6371e3 </member>
-                                            <member> density=3500.0 </member>
-                                            <member> thermdiff=1.0e-6 </member>
-                                            <member> gravacc=10.0 </member>
-                                            <member> thermexp=3.0e-5 </member>
-                                            <member> refvisc=1e21 </member>
-                                            <member> cp=1250 </member>
-                                            <member> wdensity=0.0 </member>
-                                        </simplelist>
-                                    </entry>
-                                    <entry> Various dimensional information. </entry>
-                                </row>
-                            </tbody>
-                        </tgroup>
-                    </informaltable>
-                </sect2>
-                <sect2>
-                    <title>Data input and program debugging</title>
-                    <informaltable>
-                        <tgroup cols="2">
-                            <colspec colnum="1" colname="col1" colwidth="1*"/>
-                            <colspec colnum="2" colname="col2" colwidth="2*"/>
-                            <tbody valign="top">
-                                <row>
-                                    <entry>
-                                        <simplelist>
-                                            <member> DESCRIBE=off </member>
-                                            <member> BEGINNER=off </member>
-                                            <member> VERBOSE=off </member>
-                                        </simplelist>
-                                    </entry>
-                                    <entry> These parameters affect the echo behavior of CitComS
-                                        parser. </entry>
-                                </row>
-                                <row>
-                                    <entry> verbose=off </entry>
-                                    <entry> This is used for debugging. If verbose is true,
-                                        additional information is output to .info file. </entry>
-                                </row>
-                                <row>
-                                    <entry> see_convergence=1 </entry>
-                                    <entry> If see_convergence is true, the velocity residual will
-                                        be output on the screen for every iteration. </entry>
-                                </row>
-                            </tbody>
-                        </tgroup>
-                    </informaltable>
-                </sect2>
-                <sect2>
-                    <title>Solver Related Parameters</title>
-                    <informaltable>
-                        <tgroup cols="2">
-                            <colspec colnum="1" colname="col1" colwidth="1*"/>
-                            <colspec colnum="2" colname="col2" colwidth="2*"/>
-                            <tbody valign="top">
-                                <row>
-                                    <entry>
-                                        <simplelist>
-                                            <member> mg_cycle=1 </member>
-                                            <member> down_heavy=3 </member>
-                                            <member> up_heavy=3 </member>
-                                            <member> vlowstep=2000 </member>
-                                            <member> vhighstep=3 </member>
-                                        </simplelist>
-                                    </entry>
-                                    <entry> Multigrid parameters. </entry>
-                                </row>
-                                <row>
-                                    <entry> piterations=375 </entry>
-                                    <entry> Maximum iterations for momentum solver. </entry>
-                                </row>
-                                <row>
-                                    <entry>
-                                        <simplelist>
-                                            <member> accuracy=1.0e-6 </member>
-                                            <member> tole_compressibility= </member>
-                                            <member> 1.0e-7 </member>
-                                        </simplelist>
-                                    </entry>
-                                    <entry> Convergence criterion for momentum solver. </entry>
-                                </row>
-                                <row>
-                                    <entry> ADV=on </entry>
-                                    <entry> If true, solve energy equation. </entry>
-                                </row>
-                                <row>
-                                    <entry> fixed_timestep=0.0 </entry>
-                                    <entry> Set fixed time step. If it is 0, the size of time step
-                                        is variable and is determined dynamically. </entry>
-                                </row>
-                                <row>
-                                    <entry> finetunedt=0.7 </entry>
-                                    <entry> Set fraction of maximum advection time step. </entry>
-                                </row>
-                                <row>
-                                    <entry> adv_sub_iterations=2 </entry>
-                                    <entry> Set the numbers of iteration for energy solver. </entry>
-                                </row>
-                                <row>
-                                    <entry> maxadvtime=10 </entry>
-                                    <entry> Maximum elapsed non-dimensional advection time. </entry>
-                                </row>
-                                <row>
-                                    <entry> precond=on </entry>
-                                    <entry> Pre-conditioning flag. </entry>
-                                </row>
-                                <row>
-                                    <entry>
-                                        <simplelist>
-                                            <member> aug_lagr=on </member>
-                                            <member> aug_number=2.0e3 </member>
-                                        </simplelist>
-                                    </entry>
-                                    <entry> Augmented stiff matrix flag and value. </entry>
-                                </row>
-                            </tbody>
-                        </tgroup>
-                    </informaltable>
-                </sect2>
-                <sect2>
-                    <title>Age Information</title>
-                    <informaltable>
-                        <tgroup cols="2">
-                            <colspec colnum="1" colname="col1" colwidth="1*"/>
-                            <colspec colnum="2" colname="col2" colwidth="2*"/>
-                            <tbody valign="top">
-                                <row>
-                                    <entry> start_age=40.0 </entry>
-                                    <entry> Set initial age (in Myrs). This age determines which
-                                        vel_bound_file and mat_file to read in. </entry>
-                                </row>
-                                <row>
-                                    <entry> reset_startage=0 </entry>
-                                    <entry> If reset_startage is true, the initial age is set to
-                                        start_age. If it is false and restart or post_p is true, the
-                                        initial age is read in from previous output. </entry>
-                                </row>
-                            </tbody>
-                        </tgroup>
-                    </informaltable>
-                </sect2>
-                <sect2>
-                    <title>Spherical Harmonics Information</title>
-                    <informaltable>
-                        <tgroup cols="2">
-                            <colspec colnum="1" colname="col1" colwidth="1*"/>
-                            <colspec colnum="2" colname="col2" colwidth="2*"/>
-                            <tbody valign="top">
-                                <row>
-                                    <entry>
-                                        <simplelist>
-                                            <member> ll_max=20 </member>
-                                            <member> output_ll_max=20 </member>
-                                            <member> nlong=361 </member>
-                                            <member> nlati=181 </member>
-                                        </simplelist>
-                                    </entry>
-                                    <entry> These parameters control the resolution of spherical
-                                        harmonics. Currently not used. </entry>
-                                </row>
-                            </tbody>
-                        </tgroup>
-                    </informaltable>
-                </sect2>
-                <sect2>
-                    <title>launcher</title>
-                    <para> Launcher is a Pyre facility that controls how CitComS.py, an MPI
-                        application, is executed on multiple processors. It is the equivalent to
-                        mpirun in MPICH. </para>
-                    <informaltable>
-                        <tgroup cols="2">
-                            <colspec colnum="1" colname="col1" colwidth="1*"/>
-                            <colspec colnum="2" colname="col2" colwidth="2*"/>
-                            <tbody valign="top">
-                                <row>
-                                    <entry> dry </entry>
-                                    <entry> If on, print command line and exit. </entry>
-                                </row>
-                                <row>
-                                    <entry> nodegen </entry>
-                                    <entry> A printf-style format string, used in conjunction with
-                                        nodelist to generate list of machine names. Example:
-                                        <computeroutput> n%&Oslash;3d </computeroutput> . </entry>
-                                </row>
-                                <row>
-                                    <entry> nodelist </entry>
-                                    <entry> A comma-separated list of machine names in square
-                                        brackets. Example: <computeroutput> [101-103,105,107]
-                                        </computeroutput>
-                                    </entry>
-                                </row>
-                                <row>
-                                    <entry> nodes </entry>
-                                    <entry> Number of machine nodes </entry>
-                                </row>
-                                <row>
-                                    <entry> machinefile. </entry>
-                                    <entry> Filename of machine file. </entry>
-                                </row>
-                            </tbody>
-                        </tgroup>
-                    </informaltable>
-                </sect2>
-                <sect2>
-                    <title> journal </title>
-                    <para> journal is a Pyre facility that provides five types of debugging output
-                        for conceptually different types of information. The journal output stream
-                        can be instantiated as separated channels multiple times, and each channel
-                        can be individually activated or de-activated, and sent to different
-                        locations (the terminal, sockets, files, devices, etc.). The streams and
-                        their default states of the journal streams are: </para>
-                    <para> The journal facility is not used in the uncoupled CitComS solver. For
-                        coupled solvers, the are many debugging information that output through
-                        journal facility. They can be turned on/off with command line options. The
-                        most important ones are <computeroutput> journal.debug.Exchanger
-                        </computeroutput> and <computeroutput> journal.debug.CitComSExchanger
-                        </computeroutput>. Try running the scripts with <computeroutput>
-                            --journal.debug.Exchanger=on --journal.debug.CitComSExchanger=on
-                        </computeroutput> . </para>
-                    <informaltable>
-                        <tgroup cols="2">
-                            <colspec colnum="1" colname="col1" colwidth="1*"/>
-                            <colspec colnum="2" colname="col2" colwidth="2*"/>
-                            <tbody valign="top">
-                                <row>
-                                    <entry> debug </entry>
-                                    <entry> Debugging information. Default off. </entry>
-                                </row>
-                                <row>
-                                    <entry> error </entry>
-                                    <entry> Unrecoverable runtime error. Default on. </entry>
-                                </row>
-                                <row>
-                                    <entry> firewall </entry>
-                                    <entry> Fatal programming error. Default on. </entry>
-                                </row>
-                                <row>
-                                    <entry> info </entry>
-                                    <entry> Descriptive information. Default off. </entry>
-                                </row>
-                                <row>
-                                    <entry> warning </entry>
-                                    <entry> Recoverable runtime error. Default off. </entry>
-                                </row>
-                            </tbody>
-                        </tgroup>
-                    </informaltable>
-                </sect2>
-                <sect2>
-                    <title> controller </title>
-                    <informaltable>
-                        <tgroup cols="2">
-                            <colspec colnum="1" colname="col1" colwidth="1*"/>
-                            <colspec colnum="2" colname="col2" colwidth="2*"/>
-                            <tbody valign="top">
-                                <row>
-                                    <entry> monitoringFrequency=100 </entry>
-                                    <entry> The time step interval between disk output. It replaces
-                                        the storage_spacing parameter in the (old) CitComS input
-                                        file. </entry>
-                                </row>
-                            </tbody>
-                        </tgroup>
-                    </informaltable>
-                </sect2>
-                <sect2>
-                    <title> solver </title>
-                    <informaltable>
-                        <tgroup cols="2">
-                            <colspec colnum="1" colname="col1" colwidth="1*"/>
-                            <colspec colnum="2" colname="col2" colwidth="2*"/>
-                            <tbody valign="top">
-                                <row>
-                                    <entry> mesher </entry>
-                                    <entry> Can be either full-sphere or regional-sphere. It is set
-                                        by the solver facility automatically. </entry>
-                                </row>
-                                <row>
-                                    <entry> tsolver </entry>
-                                    <entry> A temperature solver using Petrov-Galerkin time
-                                        integration. </entry>
-                                </row>
-                                <row>
-                                    <entry> vsolver </entry>
-                                    <entry> A velocity solver using Bousinessq approximation and
-                                        Uzawa algorithm. </entry>
-                                </row>
-                                <row>
-                                    <entry> bc </entry>
-                                    <entry> Boundary conditions. </entry>
-                                </row>
-                                <row>
-                                    <entry> const </entry>
-                                    <entry> Dimensional constants. </entry>
-                                </row>
-                                <row>
-                                    <entry> ic </entry>
-                                    <entry> Initial conditions. </entry>
-                                </row>
-                                <row>
-                                    <entry> param </entry>
-                                    <entry> Some additional input parameter files. </entry>
-                                </row>
-                                <row>
-                                    <entry> phase </entry>
-                                    <entry> Phase change. </entry>
-                                </row>
-                                <row>
-                                    <entry> visc </entry>
-                                    <entry> Viscosity. </entry>
-                                </row>
-                                <row>
-                                    <entry> datafile </entry>
-                                    <entry> default="regtest" </entry>
-                                </row>
-                                <row>
-                                    <entry> datafile_old </entry>
-                                    <entry> default="regtest" </entry>
-                                </row>
-                                <row>
-                                    <entry> rayleigh </entry>
-                                    <entry> default=1e+08 </entry>
-                                </row>
-                                <row>
-                                    <entry> Q0 =0 </entry>
-                                    <entry/>
-                                </row>
-                                <row>
-                                    <entry> stokes_flow_only =0 </entry>
-                                    <entry/>
-                                </row>
-                                <row>
-                                    <entry> verbos =0 </entry>
-                                    <entry/>
-                                </row>
-                                <row>
-                                    <entry> see_convergence =1 </entry>
-                                    <entry/>
-                                </row>
-                            </tbody>
-                        </tgroup>
-                    </informaltable>
-                </sect2>
-                <sect2>
-                    <title> solver.mesher </title>
-                    <para> Available properties and default values include: <informaltable>
-                            <tgroup cols="2">
-                                <colspec colnum="1" colname="col1" colwidth="1*"/>
-                                <colspec colnum="2" colname="col2" colwidth="2*"/>
-                                <tbody valign="top">
-                                    <row>
-                                        <entry> nproc_surf=1 </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> nprocx=1 </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> nprocy=1 </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> nprocz=1 </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> coor=0 </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> coor_file="coor.dat" </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> nodex=9 </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> nodey=9 </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> nodez=9 </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> levels=1 </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> radius_outer=1 </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> radius_inner=0.55 </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> theta_min=1.5 </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> theta_max=1.8 </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> fi_min=0 </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> fi_max=0.4 </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> ll_max=20 </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> nlong=361 </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> nlati=181 </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> output_ll_max=20 </entry>
-                                        <entry/>
-                                    </row>
-                                </tbody>
-                            </tgroup>
-                        </informaltable>
-                    </para>
-                </sect2>
-                <sect2>
-                    <title> solver.tsolver </title>
-                    <para> Available properties and default values include: <informaltable>
-                            <tgroup cols="2">
-                                <colspec colnum="1" colname="col1" colwidth="1*"/>
-                                <colspec colnum="2" colname="col2" colwidth="2*"/>
-                                <tbody valign="top">
-                                    <row>
-                                        <entry> inputdiffusivity=1 </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> ADV=1 </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> fixed_timestep=0 </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> finetunedt=0.9 </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> adv_sub_iterations=2 </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> maxadvtime=10 </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> aug_lagr=1 </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> aug_number=2000 </entry>
-                                        <entry/>
-                                    </row>
-                                </tbody>
-                            </tgroup>
-                        </informaltable>
-                    </para>
-                </sect2>
-                <sect2>
-                    <title> solver.vsolver </title>
-                    <para> Available properties and default values include: <informaltable>
-                            <tgroup cols="2">
-                                <colspec colnum="1" colname="col1" colwidth="1*"/>
-                                <colspec colnum="2" colname="col2" colwidth="2*"/>
-                                <tbody valign="top">
-                                    <row>
-                                        <entry> node_assemble=1 </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> precond=1 </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> accuracy=1e-06 </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> tole_compressibility=1e-07 </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> mg_cycle=1 </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> down_heavy=3 </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> up_heavy=3 </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> vlowstep=1000 </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> vhighstep=3 </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> piterations=1000 </entry>
-                                        <entry/>
-                                    </row>
-                                </tbody>
-                            </tgroup>
-                        </informaltable>
-                    </para>
-                </sect2>
-                <sect2>
-                    <title> solver.bc </title>
-                    <para> Available properties and default values include: it can be 0, 1, or 2 is
-                        open top. You cannot use "yes" or "no" for these values. <informaltable>
-                            <tgroup cols="2">
-                                <colspec colnum="1" colname="col1" colwidth="1*"/>
-                                <colspec colnum="2" colname="col2" colwidth="2*"/>
-                                <tbody valign="top">
-                                    <row>
-                                        <entry> side_sbcs=0 </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> topvbc=0 </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> topvbxval=0 </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> topvbyval=0 </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> botvbc=0 </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> botvbxval=0 </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> botvbyval=0 </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> toptbc=1 </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> toptbcval=0 </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> bottbc=1 </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> bottbcval=1 </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> temperature_bound_adj=0 </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> depth_bound_adj=0.157 </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> width_bound_adj=0.08727 </entry>
-                                        <entry/>
-                                    </row>
-                                </tbody>
-                            </tgroup>
-                        </informaltable>
-                    </para>
-                </sect2>
-                <sect2>
-                    <title> solver.const </title>
-                    <para> Available properties and default values include: <informaltable>
-                            <tgroup cols="2">
-                                <colspec colnum="1" colname="col1" colwidth="1*"/>
-                                <colspec colnum="2" colname="col2" colwidth="2*"/>
-                                <tbody valign="top">
-                                    <row>
-                                        <entry> layerd=6.371e+06 </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> density=3500 </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> thermdiff=1e-06 </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> gravacc=10 </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> thermexp=3e-05 </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> refvisc=1e+21 </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> cp=1250 </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> wdensity=0 </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> surftemp=273 </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> depth_lith=89000 </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> depth_410=410000 </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> depth_660=660000 </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> depth_cmb=2.691e+06 </entry>
-                                        <entry/>
-                                    </row>
-                                </tbody>
-                            </tgroup>
-                        </informaltable>
-                    </para>
-                </sect2>
-                <sect2>
-                    <title> solver.ic </title>
-                    <para> Available properties and default values include: <informaltable>
-                            <tgroup cols="2">
-                                <colspec colnum="1" colname="col1" colwidth="1*"/>
-                                <colspec colnum="2" colname="col2" colwidth="2*"/>
-                                <tbody valign="top">
-                                    <row>
-                                        <entry> restart=0 </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> post_p=0 </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> solution_cycles_init=0 </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> zero_elapsed_time=1 </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> num_perturbations=1 </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> perturbl=1 </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> perturbm=1 </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> perturblayer=5 </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> perturbmag=0.05 </entry>
-                                        <entry/>
-                                    </row>
-                                </tbody>
-                            </tgroup>
-                        </informaltable>
-                    </para>
-                </sect2>
-                <sect2>
-                    <title> solver.param </title>
-                    <para> Available properties and default values include: <informaltable>
-                            <tgroup cols="2">
-                                <colspec colnum="1" colname="col1" colwidth="1*"/>
-                                <colspec colnum="2" colname="col2" colwidth="2*"/>
-                                <tbody valign="top">
-                                    <row>
-                                        <entry> file_vbcs=0 </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> vel_bound_file="bvel.dat" </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> mat_control=0 </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> mat_file="mat.dat" </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> lith_age=0 </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> lith_age_file="age.dat" </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> lith_age_time=0 </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> lith_age_depth=0.0314 </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> mantle_temp=1 </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> tracer=0 </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> tracer_file="tracer.dat" </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> start_age=40 </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> reset_startage=0 </entry>
-                                        <entry/>
-                                    </row>
-                                </tbody>
-                            </tgroup>
-                        </informaltable>
-                    </para>
-                </sect2>
-                <sect2>
-                    <title> solver.phase </title>
-                    <para> Available properties and default values include: <informaltable>
-                            <tgroup cols="2">
-                                <colspec colnum="1" colname="col1" colwidth="1*"/>
-                                <colspec colnum="2" colname="col2" colwidth="2*"/>
-                                <tbody valign="top">
-                                    <row>
-                                        <entry> Ra_410=0 </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> clapeyron410=0.0235 </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> transT410=0.78 </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> width410=0.0058 </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> Ra_670=0 </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> clapeyron670=-0.0235 </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> transT670=0.78 </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> width670=0.0058 </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> Ra_cmb=0 </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> clapeyroncmb=-0.0235 </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> transTcmb=0.875 </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> widthcmb=0.0058 </entry>
-                                        <entry/>
-                                    </row>
-                                </tbody>
-                            </tgroup>
-                        </informaltable>
-                    </para>
-                </sect2>
-                <sect2>
-                    <title> solver.visc </title>
-                    <para> Available properties and default values include: <informaltable>
-                            <tgroup cols="2">
-                                <colspec colnum="1" colname="col1" colwidth="1*"/>
-                                <colspec colnum="2" colname="col2" colwidth="2*"/>
-                                <tbody valign="top">
-                                    <row>
-                                        <entry> Viscosity="system" </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> rheol=3 </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> visc_smooth_method=3 </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> VISC_UPDATE=on </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> num_mat=4 </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> visc0=1,1,1,1, </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> TDEPV=0 </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> viscE=1,1,1,1, </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> viscT=1,1,1,1, </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> SDEPV=0 </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> sdepv_misfit=0.02 </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> sdepv_expt=1,1,1,1, </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> VMIN=0 </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> visc_min=0.001 </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> VMAX=0 </entry>
-                                        <entry/>
-                                    </row>
-                                    <row>
-                                        <entry> visc_max=1000 </entry>
-                                        <entry/>
-                                    </row>
-                                </tbody>
-                            </tgroup>
-                        </informaltable>
-                    </para>
-                </sect2>
-            </sect1>
-        </appendix>
-        <appendix>
-            <title>CitComS Input Files Format</title>
-            <sect1>
-                <title>Introduction</title>
-                <para>CitComS expects Unix styled ASCII files (i.e. no carriage character following
-                    new line character) for all input files. This can be a nuisance in DOS/Windows
-                    systems. You may want to find a text editor that can write Unix-style ASCII
-                    files. In the following words in normal <filename>courier</filename>
-                    must be input exactly as shown, while <emphasis role="bold">bold</emphasis>
-                    words should be substitute by your values. All parameters are in non-dimensional
-                    units unless specified. </para>
-                <sect2>
-                    <title>Coordinate files</title>
-                    <para>For <filename>regCitComS</filename>, the mesh must be regular, but the
-                        mesh spacing may be unequal. The <filename>coor_file</filename> has the
-                        format:</para>
-                    <programlisting>nsd=1
-1		<emphasis role="bold">theta1</emphasis> 
-2		<emphasis role="bold">theta2</emphasis> 
-...		...
-<emphasis role="bold">nodex	theta_nodex</emphasis>
-nsd=2
-1		<emphasis role="bold">phi1</emphasis> 
-2		<emphasis role="bold">phi2</emphasis> 
-...		...
-<emphasis role="bold">nodey	phi_nodey</emphasis> 
-nsd=3
-1		<emphasis role="bold">r1</emphasis> 
-2		<emphasis role="bold">r2</emphasis> 
-...		...
-<emphasis role="bold">nodez	r_nodez</emphasis> </programlisting>
-                    <para>For <filename>fullCitComS</filename>, the mesh must be regular and
-                        equidistant in the horizontal dimension. Only vertical dimension is
-                        specified by <filename>coor_file</filename>. The
-                        <filename>coor_file</filename> has the format:</para>
-                    <programlisting>nsd=3
-1		<emphasis role="bold">r1</emphasis> 
-2		<emphasis role="bold">r2</emphasis> 
-...		...
-<emphasis role="bold">nodez	r_nodez</emphasis></programlisting>
-                </sect2>
-                <sect2>
-                    <title>Velocity boundary condition files</title>
-                    <para> If <filename>vel_bound_file</filename> is set to
-                        <filename>bvel.dat</filename>, then is necessary to have one
-                            <filename>bvel.dat</filename> file for each million year interval. For
-                        example, if <filename>start_age=83</filename>, then the following files are
-                        needed: </para>
-                    <programlisting>bvel.dat84
-bvel.dat83
-bvel.dat82
-...
-bvel.dat0</programlisting>
-                    <tip>Even through the model starts at 83 million years before present, by
-                        default it will attempt to read in both a file for 84 and a file for 83
-                        million years ago. To deal with this just create a duplicate copy of
-                            <filename>bvel.dat83</filename> and call it
-                        <filename>bvel.dat84</filename>.</tip>
-                    <para>The input velocity is in cm/yr. The format of
-                        <filename>vel_bound_file</filename> is:</para>
-                    <programlisting><emphasis role="bold">Vx	Vy</emphasis></programlisting>
-                </sect2>
-                <sect2>
-                    <title>Material files</title>
-                    <para>If <filename>mat_file</filename> is set to <filename>mat.dat</filename>,
-                        then is necessary to have one mat.dat file for each million year interval.
-                        For example, if <filename>start_age=83</filename>, then the following files
-                        are needed:</para>
-                    <programlisting>mat.dat84
-mat.dat83
-mat.dat82
-...
-mat.dat0</programlisting>
-                    <para>The same note about <filename>vel_bound_file</filename> (see above)
-                        applies. The format of <filename>mat_file</filename> is:</para>
-                    <programlisting><emphasis role="bold">n	viscosity_factor</emphasis></programlisting>
-                </sect2>
-                <sect2>
-                    <title>Lithosphere Age Files</title>
-                    <para>If <filename>lith_age_file</filename> is set to
-                        <filename>lith.dat</filename>, then is necessary to have one
-                            <filename>bvel.dat</filename> file for each million year interval. For
-                        example, if <filename>start_age=83</filename>, then the following files are
-                        needed:</para>
-                    <programlisting>lith.dat84
-lith.dat83
-lith.dat82
-...
-lith.dat0</programlisting>
-                    <para>The same note about <filename>vel_bound_file</filename> (see above) still
-                        applies. The input age is in million years. The format of
-                            <filename>lith_age_file</filename> is:</para>
-                    <programlisting><emphasis role="bold">n	age</emphasis></programlisting>
-                </sect2>
-                <sect2>
-                    <title>Tracer Files</title>
-                    <para>In this version of CitComS, the implementation of tracer is neither
-                        parallelized, nor has it been tested. We strongly advise you not to use this
-                        feature. The format of <filename>tracer_file</filename> is described here
-                        for completion:</para>
-                    <programlisting>num_tracers
-type	x	y	z</programlisting>
-                </sect2>
-            </sect1>
-        </appendix>
-
-        <appendix>
-            <title>CitComS, <filename>retrieve</filename> Output Files Format</title>
-            <sect1>
-                <title>Introduction</title>
-                <para>All outputs are in non-dimensional unit unless specified.</para>
-
-                <sect2>
-                    <title>Postprocessed Output</title>
-                    <sect3>
-                        <para>
-                            The <filename>autocombine.py</filename> and <filename>batchcombine.py</filename> 
-                            produces 1 cap file for regional CitcomS and 12 cap files for full CitcomS,
-                            for example <filename>test-case.cap0.10</filename>. The first line of the cap
-                            file is a comment describing the node geometry (<filename>nodex</filename> x
-                            <filename>nodey</filename> x <filename>nodez</filename>). The rest of the 
-                            file is column-based, where the meaning of each column is:
-                            <programlisting>colatitude longitude radius vel_colat vel_lon vel_r temperature viscosity</programlisting>
-                        </para>
-                    </sect3>
-                </sect2>
-
-                <sect2>
-                    <title>CitComS Output</title>
-                    <para>
-                         The format of the raw output of CitComS.py is described here. In the following
-                         sections, the model prefix is assumed as <filename>test-case</filename>, the 
-                         processor number as 0, and the time step as 10.
-                    </para>
-                    <sect3>
-                        <title>Time Output (test-case.time)</title>
-                        <para>
-                            It reports non-dimensional elapsed model time and spent CPU time (in
-                            seconds). Only outputted on computer node 0. The meaning of each column is:
-                            <programlisting>step total_t delta_t total_cpu_time step_cpu_time</programlisting>
-                        </para>
-                    </sect3>
-                    <sect3>
-                        <title>Coordinate Output (test-case.coord.0)</title>
-                        <para>
-                            Only outputted at 0th time step. The first line is a header. The rest of the
-                            file is column-based, where the meaning of each column is:
-                            <programlisting>colatitude longitude radius</programlisting>
-                        </para>
-                    </sect3>
-                    <sect3>
-                        <title>Velocity and Temperature Output (test-case.velo.0.10)</title>
-                        <para>
-                            The two lines are headers. The rest of the file is column-based, 
-                            where the meaning of each column is:
-                            <programlisting>vel_colat vel_lon vel_r temperature</programlisting>
-                        </para>
-                    </sect3>
-                    <sect3>
-                        <title>Viscosity Output (test-case.visc.0.10)</title>
-                        <para>
-                            The first line is a header. The rest of the file is column-based,
-                            where the meaning of each column is:
-                            <programlisting>viscosity</programlisting>
-                        </para>
-                    </sect3>
-                    <sect3>
-                        <title>Material Output (test-case.mat.0)</title>
-                        <para>
-                            Only output at 0th time step. There is no header. The meaning of each column is:
-                            <programlisting>node_number layer material</programlisting>
-                        </para>
-                    </sect3>
-                    <sect3>
-                        <title>Surface Variables Output (test-case.surf.0.10 and test-case.botm.0.10)</title>
-                        <para>
-                             The first line is a header. The rest of the file is column-based, 
-                             where the meaning of each column is:
-                             <programlisting>topography heatflux vel_colat vel_lon</programlisting>
-                        </para>
-                    </sect3>
-                </sect2>
-            </sect1>
-        </appendix>
-        <appendix>
-            <title>Bibliography</title>
-            <sect1><title>References</title>
-                <para>1. Moresi, L., Gurnis, M. and Zhong, S. Plate tectonics and convection
-                    in the Earth's mantle: Toward a numerical simulation. <emphasis>Comp. Sci.
-                        Engin.</emphasis>
-                    <emphasis role="bold">2</emphasis>, 22-33 (2000).</para>
-                <para>2. Moresi, L. N. and Solomatov, V. S. Numerical investigation of 2D
-                    convection with extremely large viscosity variations. <emphasis>Phys. Fluid</emphasis>
-                    <emphasis role="bold">7</emphasis>, 2154-2162 (1995).</para>
-                <para>3. Moresi, L. N. and Gurnis, M. Constraints on the lateral strength of
-                    slabs from three-dimensional dynamic flow models. <emphasis>Earth Planet. Sci.
-                        Lett.</emphasis>
-                    <emphasis role="bold">138</emphasis>, 15-28 (1996).</para>
-                <para>4. Zhong, S., Gurnis, M. and Moresi, L. The role of faults, nonlinear
-                    rheology, and viscosity structure in generating plates from instantaneous mantle
-                    flow models. <emphasis>J. Geophys. Res.</emphasis>
-                    <emphasis role="bold">103</emphasis>, 15,255-15,268 (1998).</para>
-                <para>5. Zhong, S., Zuber, M. T., Moresi, L. N. and Gurnis, M. The role of
-                    temperature-dependent viscosity and surface plates in spherical shell models of
-                    mantle convection. <emphasis>J. Geophys. Res.</emphasis>
-                    <emphasis role="bold">105</emphasis>, 11,063-11,082 (2000).</para>
-                <para>6. Tan, E., Gurnis, M. and Han, L. Slabs in the lower mantle and their
-                    modulation of plume formation. <emphasis>Geochem. Geophys. Geosyst.</emphasis>
-                    <emphasis role="bold">3</emphasis>, 1067 (2002).</para>
-                <para>7. Conrad, C. P. and Gurnis, M. Seismic tomography, surface uplift, and
-                    the breakup of Gondwanaland: Integrating mantle convection backwards in time.
-                    <emphasis>Geochem., Geophys., Geosys.</emphasis>(2001).</para>
-                <para>8. Hughes, T. J. R. <emphasis>The Finite Element Method: Linear Static and
-                    Dynamic Finite Element Analysis</emphasis>(Prentice-Hall, Inc., Englewood
-                    Cliffs, New Jersey, 1987).</para>
-                <para>9. Ramage, A. and Wathen, A. J. Iterative solution techniques for the
-                    Stokes and Navier-Stokes equations. <emphasis>Int. J. Numer. Methods. Fluids</emphasis>
-                    <emphasis role="bold">19</emphasis>, 67-83 (1994).</para>
-                <para>10. Brooks, A. N. (California Institute of Technology, Pasadena, CA, 1981).</para>
-                <para>11. Cahouet, J. and Chabard, J.-P. Some fast 3D finite element solvers
-                    for the generalized Stokes problem. <emphasis>Int. J. Numer. Methods. Fluids</emphasis>
-                    <emphasis role="bold">8</emphasis>, 869-895 (1988).</para>
-                <para>12. Atanga, J. and Silvester, D. Iterative methods for stabilized mixed
-                    velocity-pressure finite elements. <emphasis>Int. J. Numer. Methods. Fluids</emphasis>
-                    <emphasis role="bold">14</emphasis>, 71-81 (1992).</para>
-                <para>13. Hager, B. H. and O'Connell, R. J. A simple global model of plate
-                    dynamics and mantle convection. <emphasis>J. Geophys. Res.</emphasis>
-                    <emphasis role="bold">86</emphasis>, 4843-4867 (1981).</para>
-                <para>14. Hager, B. H. and O'Connell, R. J. A simple global model of plate
-                    dynamics and mantle convection. <emphasis>J. Geophys. Res.</emphasis>
-                    <emphasis role="bold">86</emphasis>, 4843-4867 (1981).</para>
-                <para>15. Tan, E., Thoutireddy, P., Choi, E., Gurnis, M., and Aivazis, M.,
-                    2004, GeoFramework Part I: Coupling Models of Mantle Convection with a Python
-                    Framework, in preparation, <emphasis>Geochemistry, Geophysics,
-                        Geosystems</emphasis>, 2004. </para>
-                <para>16.Zhong, S., M. Gurnis and L. Moresi, Free-surface formulation of
-                    mantle convection--I. Basic theory and appication to plumes,
-                    <emphasis>Geophys. J. Int.</emphasis>, <emphasis role="bold">127</emphasis>, pp. 708-718, 1996.</para>
-                
-                <para>17. Zhong, S., A. Paulson and J. Wahr, Three-dimensional
-                    finite-element modelling of Earth's viscoelastic deformation:
-                    effects of lateral variations in lithospheric thickness, <emphasis>Geophys.
-                        J. Int.</emphasis>, <emphasis role="bold">155</emphasis>, pp. 679-695, 2003. </para>
-            </sect1>
-        </appendix>
-        
-        
-        <appendix>
-            <title>License</title> <para> GNU GENERAL PUBLIC LICENSE Version 2, June 1991 Copyright
-        (C) 1989, 1991 Free Software Foundation, Inc. 59 Temple Place, Suite 330, Boston, MA
-        02111-1307 USA Everyone is permitted to copy and distribute verbatim copies of this license
-        document, but changing it is not allowed.</para>
-    <sect1>
-        <title>Preamble</title>
-        <para> The licenses for most software are designed to take away your freedom to share and
-            change it. By contrast, the GNU General Public License is intended to guarantee your
-            freedom to share and change free software--to make sure the software is free for all its
-            users. This General Public License applies to most of the Free Software Foundation's
-            software and to any other program whose authors commit to using it. (Some other Free
-            Software Foundation software is covered by the GNU Library General Public License
-            instead.) You can apply it to your programs, too.</para>
-        <para> When we speak of free software, we are referring to freedom, not price. Our General
-            Public Licenses are designed to make sure that you have the freedom to distribute copies
-            of free software (and charge for this service if you wish), that you receive source code
-            or can get it if you want it, that you can change the software or use pieces of it in
-            new free programs; and that you know you can do these things.</para>
-        <para> To protect your rights, we need to make restrictions that forbid anyone to deny you
-            these rights or to ask you to surrender the rights. These restrictions translate to
-            certain responsibilities for you if you distribute copies of the software, or if you
-            modify it.</para>
-        <para> For example, if you distribute copies of such a program, whether gratis or for a fee,
-            you must give the recipients all the rights that you have. You must make sure that they,
-            too, receive or can get the source code. And you must show them these terms so they know
-            their rights.</para>
-        <para> We protect your rights with two steps: (1) copyright the software, and (2) offer you
-            this license which gives you legal permission to copy, distribute and/or modify the
-            software.</para>
-        <para> Also, for each author's protection and ours, we want to make certain that everyone
-            understands that there is no warranty for this free software. If the software is
-            modified by someone else and passed on, we want its recipients to know that what they
-            have is not the original, so that any problems introduced by others will not reflect on
-            the original authors' reputations.</para>
-        <para> Finally, any free program is threatened constantly by software patents. We wish to
-            avoid the danger that redistributors of a free program will individually obtain patent
-            licenses, in effect making the program proprietary. To prevent this, we have made it
-            clear that any patent must be licensed for everyone's free use or not licensed at all. </para>
-        <para>The precise terms and conditions for copying, distribution and modification follow.
-        </para>
-    </sect1>
-            <sect1>
-                <title> GNU GENERAL PUBLIC LICENSE TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND
-                    MODIFICATION </title>
-                <para> 0. This License applies to any program or other work which contains a notice placed
-                    by the copyright holder saying it may be distributed under the terms of this General
-                    Public License. The "Program", below, refers to any such program or work, and a "work
-                    based on the Program" means either the Program or any derivative work under copyright
-                    law: that is to say, a work containing the Program or a portion of it, either verbatim
-                    or with modifications and/or translated into another language. (Hereinafter, translation
-                    is included without limitation in the term "modification".) Each licensee is addressed
-                    as "you". </para>
-                <para> Activities other than copying, distribution and modification are not covered by this
-                    License; they are outside its scope. The act of running the Program is not restricted,
-                    and the output from the Program is covered only if its contents constitute a work based
-                    on the Program (independent of having been made by running the Program). Whether that is
-                    true depends on what the Program does. </para>
-                <para> 1. You may copy and distribute verbatim copies of the Program's source code as you
-                    receive it, in any medium, provided that you conspicuously and appropriately publish on
-                    each copy an appropriate copyright notice and disclaimer of warranty; keep intact all
-                    the notices that refer to this License and to the absence of any warranty; and give any
-                    other recipients of the Program a copy of this License along with the Program. </para>
-                <para>You may charge a fee for the physical act of transferring a copy, and you may at your
-                    option offer warranty protection in exchange for a fee. </para>
-                <para>2. You may modify your copy or copies of the Program or any portion of it, thus
-                    forming a work based on the Program, and copy and distribute such modifications or work
-                    under the terms of Section 1 above, provided that you also meet all of these conditions: </para>
-                <para> a) You must cause the modified files to carry prominent notices stating that you
-                    changed the files and the date of any change. </para>
-                <para> b) You must cause any work that you distribute or publish, that in whole or in part
-                    contains or is derived from the Program or any part thereof, to be licensed as a whole
-                    at no charge to all third parties under the terms of this License. </para>
-                <para> c) If the modified program normally reads commands interactively when run, you must
-                    cause it, when started running for such interactive use in the most ordinary way, to
-                    print or display an announcement including an appropriate copyright notice and a notice
-                    that there is no warranty (or else, saying that you provide a warranty) and that users
-                    may redistribute the program under these conditions, and telling the user how to view a
-                    copy of this License. (Exception: if the Program itself is interactive but does not
-                    normally print such an announcement, your work based on the Program is not required to
-                    print an announcement.) </para>
-                <para>These requirements apply to the modified work as a whole. If identifiable sections of
-                    that work are not derived from the Program, and can be reasonably considered independent
-                    and separate works in themselves, then this License, and its terms, do not apply to
-                    those sections when you distribute them as separate works. But when you distribute the
-                    same sections as part of a whole which is a work based on the Program, the distribution
-                    of the whole must be on the terms of this License, whose permissions for other licensees
-                    extend to the entire whole, and thus to each and every part regardless of who wrote it. </para>
-                <para> Thus, it is not the intent of this section to claim rights or contest your rights to
-                    work written entirely by you; rather, the intent is to exercise the right to control the
-                    distribution of derivative or collective works based on the Program. </para>
-                <para>In addition, mere aggregation of another work not based on the Program with the
-                    Program (or with a work based on the Program) on a volume of a storage or distribution
-                    medium does not bring the other work under the scope of this License. </para>
-                <para>3. You may copy and distribute the Program (or a work based on it, under Section 2) in
-                    object code or executable form under the terms of Sections 1 and 2 above provided that
-                    you also do one of the following: </para>
-                <para> a) Accompany it with the complete corresponding machine-readable source code, which
-                    must be distributed under the terms of Sections 1 and 2 above on a medium customarily
-                    used for software interchange; or, </para>
-                <para> b) Accompany it with a written offer, valid for at least three years, to give any
-                    third party, for a charge no more than your cost of physically performing source
-                    distribution, a complete machine-readable copy of the corresponding source code, to be
-                    distributed under the terms of Sections 1 and 2 above on a medium customarily used for
-                    software interchange; or, </para>
-                <para> c) Accompany it with the information you received as to the offer to distribute
-                    corresponding source code. (This alternative is allowed only for noncommercial
-                    distribution and only if you received the program in object code or executable form with
-                    such an offer, in accord with Subsection b above.) </para>
-                <para> The source code for a work means the preferred form of the work for making
-                    modifications to it. For an executable work, complete source code means all the source
-                    code for all modules it contains, plus any associated interface definition files, plus
-                    the scripts used to control compilation and installation of the executable. However, as
-                    a special exception, the source code distributed need not include anything that is
-                    normally distributed (in either source or binary form) with the major components
-                    (compiler, kernel, and so on) of the operating system on which the executable runs,
-                    unless that component itself accompanies the executable.</para>
-                <para> If distribution of executable or object code is made by offering access to copy from
-                    a designated place, then offering equivalent access to copy the source code from the
-                    same place counts as distribution of the source code, even though third parties are not
-                    compelled to copy the source along with the object code. </para>
-                <para>4. You may not copy, modify, sublicense, or distribute the Program except as expressly
-                    provided under this License. Any attempt otherwise to copy, modify, sublicense or
-                    distribute the Program is void, and will automatically terminate your rights under this
-                    License. However, parties who have received copies, or rights, from you under this
-                    License will not have their licenses terminated so long as such parties remain in full
-                    compliance. </para>
-                <para>5. You are not required to accept this License, since you have not signed it. However,
-                    nothing else grants you permission to modify or distribute the Program or its derivative
-                    works. These actions are prohibited by law if you do not accept this License. Therefore,
-                    by modifying or distributing the Program (or any work based on the Program), you
-                    indicate your acceptance of this License to do so, and all its terms and conditions for
-                    copying, distributing or modifying the Program or works based on it. </para>
-                <para>6. Each time you redistribute the Program (or any work based on the Program), the
-                    recipient automatically receives a license from the original licensor to copy,
-                    distribute or modify the Program subject to these terms and conditions. You may not
-                    impose any further restrictions on the recipients' exercise of the rights granted
-                    herein. You are not responsible for enforcing compliance by third parties to this
-                    License. </para>
-                <para>7. If, as a consequence of a court judgment or allegation of patent infringement or
-                    for any other reason (not limited to patent issues), conditions are imposed on you
-                    (whether by court order, agreement or otherwise) that contradict the conditions of this
-                    License, they do not excuse you from the conditions of this License. If you cannot
-                    distribute so as to satisfy simultaneously your obligations under this License and any
-                    other pertinent obligations, then as a consequence you may not distribute the Program at
-                    all. For example, if a patent license would not permit royalty-free redistribution of
-                    the Program by all those who receive copies directly or indirectly through you, then the
-                    only way you could satisfy both it and this License would be to refrain entirely from
-                    distribution of the Program.</para>
-                <para>If any portion of this section is held invalid or unenforceable under any particular
-                    circumstance, the balance of the section is intended to apply and the section as a whole
-                    is intended to apply in other circumstances.</para>
-                <para> It is not the purpose of this section to induce you to infringe any patents or other
-                    property right claims or to contest validity of any such claims; this section has the
-                    sole purpose of protecting the integrity of the free software distribution system, which
-                    is implemented by public license practices. Many people have made generous contributions
-                    to the wide range of software distributed through that system in reliance on consistent
-                    application of that system; it is up to the author/donor to decide if he or she is
-                    willing to distribute software through any other system and a licensee cannot impose
-                    that choice. </para>
-                <para> This section is intended to make thoroughly clear what is believed to be a
-                    consequence of the rest of this License. </para>
-                <para> 8. If the distribution and/or use of the Program is restricted in certain countries
-                    either by patents or by copyrighted interfaces, the original copyright holder who places
-                    the Program under this License may add an explicit geographical distribution limitation
-                    excluding those countries, so that distribution is permitted only in or among countries
-                    not thus excluded. In such case, this License incorporates the limitation as if written
-                    in the body of this License. </para>
-                <para> 9. The Free Software Foundation may publish revised and/or new versions of the
-                    General Public License from time to time. Such new versions will be similar in spirit to
-                    the present version, but may differ in detail to address new problems or concerns. </para>
-                <para> Each version is given a distinguishing version number. If the Program specifies a
-                    version number of this License which applies to it and "any later version", you have the
-                    option of following the terms and conditions either of that version or of any later
-                    version published by the Free Software Foundation. If the Program does not specify a
-                    version number of this License, you may choose any version ever published by the Free
-                    Software Foundation.</para>
-                <para> 10. If you wish to incorporate parts of the Program into other free programs whose
-                    distribution conditions are different, write to the author to ask for permission. For
-                    software which is copyrighted by the Free Software Foundation, write to the Free
-                    Software Foundation; we sometimes make exceptions for this. Our decision will be guided
-                    by the two goals of preserving the free status of all derivatives of our free software
-                    and of promoting the sharing and reuse of software generally. </para>
-                <para> NO WARRANTY </para>
-                <para>11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE
-                    PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN
-                    WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT
-                    WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE
-                    IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE
-                    RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM
-                    PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. </para>
-                <para> 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY
-                    COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS
-                    PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL,
-                    INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
-                    PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR
-                    LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY
-                    OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY
-                    OF SUCH DAMAGES.</para>
-            </sect1>
-            <sect1>
-                <title> END OF TERMS AND CONDITIONS </title>
-                <para> How to Apply These Terms to Your New Programs</para>
-                <para> If you develop a new program, and you want it to be of the greatest possible use to
-                    the public, the best way to achieve this is to make it free software which everyone can
-                    redistribute and change under these terms. </para>
-                <para>To do so, attach the following notices to the program. It is safest to attach them to
-                    the start of each source file to most effectively convey the exclusion of warranty; and
-                    each file should have at least the "copyright" line and a pointer to where the full
-                    notice is found. </para>
-                <para>one line to give the program's name and a brief idea of what it does. Copyright (C)
-                    (year) (name of author) </para>
-                <para> This program is free software; you can redistribute it and/or modify it under the
-                    terms of the GNU General Public License as published by the Free Software Foundation;
-                    either version 2 of the License, or (at your option) any later version. </para>
-                <para> This program is distributed in the hope that it will be useful, but WITHOUT ANY
-                    WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
-                    PARTICULAR PURPOSE. See the GNU General Public License for more details. </para>
-                <para> You should have received a copy of the GNU General Public License along with this
-                    program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite
-                    330, Boston, MA 02111-1307 USA </para>
-                <para> Also add information on how to contact you by electronic and paper mail. </para>
-                <para> If the program is interactive, make it output a short notice like this when it starts
-                    in an interactive mode: </para>
-                <para> Gnomovision version 69, Copyright (C) year name of author Gnomovision comes with
-                    ABSOLUTELY NO WARRANTY; for details type `show w'. This is free software, and you are
-                    welcome to redistribute it under certain conditions; type `show c' for details. </para>
-                <para>The hypothetical commands `show w' and `show c' should show the appropriate parts of
-                    the General Public License. Of course, the commands you use may be called something
-                    other than `show w' and `show c'; they could even be mouse-clicks or menu
-                    items--whatever suits your program. </para>
-                <para> You should also get your employer (if you work as a programmer) or your school, if
-                    any, to sign a "copyright disclaimer" for the program, if necessary. Here is a sample;
-                    alter the names: </para>
-                <para> Yoyodyne, Inc., hereby disclaims all copyright interest in the program `Gnomovision'
-                    (which makes passes at compilers) written by James Hacker. (signature of Ty Coon), 1
-                    April 1989 Ty Coon, President of Vice </para>
-                <para> This General Public License does not permit incorporating your program into
-                    proprietary programs. If your program is a subroutine library, you may consider it more
-                    useful to permit linking proprietary applications with the library. If this is what you
-                    want to do, use the GNU Library General Public License instead of this License. </para>
-            </sect1>
-        </appendix>
-    </part>
-</book>

Deleted: mc/3D/CitcomS/trunk/doc/manual/graphics.tar.gz
===================================================================
(Binary files differ)