[cig-commits] r11543 - doc/cigma/manual

[luis at geodynamics.org]

Author: luis
Date: 2008-03-25 02:25:12 -0700 (Tue, 25 Mar 2008)
New Revision: 11543

Added:
   doc/cigma/manual/gpl-license.lyx
Modified:
   doc/cigma/manual/cigma.lyx
Log:
Update to manual


Modified: doc/cigma/manual/cigma.lyx
===================================================================
--- doc/cigma/manual/cigma.lyx	2008-03-25 05:43:42 UTC (rev 11542)
+++ doc/cigma/manual/cigma.lyx	2008-03-25 09:25:12 UTC (rev 11543)
@@ -1,2689 +1,2081 @@
-#LyX 1.5.1 created this file. For more info see http://www.lyx.org/
-\lyxformat 276
-\begin_document
-\begin_header
-\textclass book
-\begin_preamble
-\usepackage{hyperref}
-
-\let\myUrl\url
-\renewcommand{\url}[1]{(\myUrl{#1})}
-\end_preamble
-\language english
-\inputencoding auto
-\font_roman default
-\font_sans default
-\font_typewriter default
-\font_default_family default
-\font_sc false
-\font_osf false
-\font_sf_scale 100
-\font_tt_scale 100
-\graphics default
-\paperfontsize default
-\spacing single
-\papersize default
-\use_geometry true
-\use_amsmath 1
-\use_esint 0
-\cite_engine basic
-\use_bibtopic false
-\paperorientation portrait
-\leftmargin 1in
-\topmargin 1in
-\rightmargin 1in
-\bottommargin 1in
-\secnumdepth 3
-\tocdepth 3
-\paragraph_separation indent
-\defskip medskip
-\quotes_language swedish
-\papercolumns 1
-\papersides 2
-\paperpagestyle headings
-\tracking_changes false
-\output_changes false
-\author "" 
-\author "" 
-\end_header
-
-\begin_body
-
-\begin_layout Standard
-\noindent
-\align center
-
-\color none
-\begin_inset ERT
-status collapsed
-
-\begin_layout Standard
-
-
-\backslash
-thispagestyle{empty}
-\end_layout
-
-\end_inset
-
-
-\begin_inset Float figure
-placement H
-wide false
-sideways false
-status collapsed
-
-\begin_layout Standard
-\begin_inset Graphics
-	filename figures/cigma_cover.pdf
-	display color
-	width 75page%
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-\noindent
-\align center
-
-\color none
-\begin_inset ERT
-status collapsed
-
-\begin_layout Standard
-
-
-\backslash
-thispagestyle{empty}
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Title
-Cigma
-\end_layout
-
-\begin_layout Author
-© California Institute of Technology
-\newline
-Version 0.9.1
-\end_layout
-
-\begin_layout Date
-\begin_inset ERT
-status collapsed
-
-\begin_layout Standard
-
-
-\backslash
-today
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-\begin_inset LatexCommand tableofcontents
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-\begin_inset FloatList figure
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-\begin_inset ERT
-status collapsed
-
-\begin_layout Standard
-
-
-\backslash
-raggedbottom
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-
-\newpage
-
-\end_layout
-
-\begin_layout Chapter
-Introduction
-\end_layout
-
-\begin_layout Section
-About Cigma
-\end_layout
-
-\begin_layout Standard
-The CIG Model Analyzer (Cigma) consists of a suite of tools for comparing
- numerical models.
- CIG has developed Cigma in response to demand from the short-term tectonics
- community for a simple tool that can perform rigorous error analysis on
- their finite element codes.
- The long-term goal for Cigma, however, is for it to be used for nearly
- all geodynamics modeling codes.
-\end_layout
-
-\begin_layout Standard
-The current version of Cigma is intended for the calculation of 
-\begin_inset Formula $L_{2}$
-\end_inset
-
- residuals for finite element models.
- This software was designed for performing the following three main tasks:
- (1) error analysis, (2) benchmarking, and (3) code verification.
- In error analysis, Cigma can calculate a global measure of the error between
- two solutions by performing an integration over a discretized version of
- the common domain.
- This comparison can take place even when the underlying discretizations
- do not overlap.
- In benchmarking, Cigma can help the geodynamics community agree on a standard
- solution to specific problems by facilitating the process of comparing
- different numerical codes against each other.
- Lastly, as an automated tool, Cigma can help application developers create
- regression tests to ensure that software changes do not affect the consistency
- of the results.
-\end_layout
-
-\begin_layout Standard
-At its core, Cigma draws from a variety of libraries.
- The 
-\begin_inset LatexCommand htmlurl
-name "FInite element Automatic Tabulator (FIAT)"
-target "www.fenics.org/wiki/FIAT"
-
-\end_inset
-
- Python Library supports generation of arbitrary order instances of the
- Lagrange elements on lines, triangles, and tetrahedra.
- It can also generate higher order instances of Jacobi-type quadrature rules
- on the same element shapes.
- The 
-\begin_inset LatexCommand htmlurl
-name "Approximate Nearest Neighbor (ANN)"
-target "www.cs.umd.edu/~mount/ANN/"
-
-\end_inset
-
- Library, written in C++, supports data structures and algorithms for both
- exact and nearest-neighbor searching in arbitrarily high dimensions.
-\end_layout
-
-\begin_layout Standard
-Both of these libraries extend and generalize Cigma's functionality so it
- can handle other types of elements, and provide the ability to compare
- vector fields.
-\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 the hope that the software will enhance your research
- in geophysics.
- This is a brand-new code and at present no papers are published or press.
- Please cite this manual as follows:
-\end_layout
-
-\begin_layout Itemize
-Armendariz, L., and S.
- Kientz.
- 
-\emph on
-Cigma User Manual.
-
-\emph default
- Pasadena, CA: Computational Infrastructure of Geodynamics, 2008.
- URL: geodynamics.org/cig/software/cs/cigma/cigma.pdf
-\end_layout
-
-\begin_layout Standard
-CIG requests that in your oral presentations and in your papers that you
- indicate your use of this code and acknowledge the author of the code and
- 
-\begin_inset LatexCommand htmlurl
-name "CIG"
-target "geodynamics.org"
-
-\end_inset
-
-.
-\end_layout
-
-\begin_layout Section
-Support
-\end_layout
-
-\begin_layout Standard
-Cigma development is based upon work supported by the National Science Foundatio
-n under Grant No.
- EAR-0406751.
- Any opinions, findings, and conclusions or recommendations expressed in
- this material are those of the authors and do not necessarily reflect the
- views of the National Science Foundation.
- The code is being released under the GNU General Public License.
-\end_layout
-
-\begin_layout Chapter
-Installation and Getting Help
-\end_layout
-
-\begin_layout Section
-Getting Help
-\end_layout
-
-\begin_layout Standard
-For help, send an e-mail to the 
-\begin_inset LatexCommand url
-name "CIG Computational Science Mailing List"
-target "cig-cs at geodynamics.org"
-
-\end_inset
-
-.
- You can subscribe to the 
-\family typewriter
-cig-cs
-\family default
- mailing list and view archived discussions at the 
-\begin_inset LatexCommand htmlurl
-name "CIG Mail Lists web page"
-target "geodynamics.org/cig/lists"
-
-\end_inset
-
-.
- If you encounter any bugs or have problems installing Cigma, please submit
- a report to the 
-\begin_inset LatexCommand htmlurl
-name "CIG Bug Tracker"
-target "geodynamics.org/bugs"
-
-\end_inset
-
-.
-\end_layout
-
-\begin_layout Section
-Installating from Source
-\end_layout
-
-\begin_layout Standard
-To install Cigma, download the source package from the 
-\begin_inset LatexCommand htmlurl
-name "CIG Cigma web page"
-target "geodynamics.org/cig/software/packages/cs/cigma"
-
-\end_inset
-
-.
- You will need the GNU C++ compiler for this step.
- The HDF5 and VTK libraries, described later in this section, are also required.
-\end_layout
-
-\begin_layout Standard
-After installing the necessary dependencies, simply unpack the source tar
- file and issue the following commands
-\end_layout
-
-\begin_layout LyX-Code
-$ tar xvfz cigma-0.9.1.tar.gz
-\end_layout
-
-\begin_layout LyX-Code
-$ cd cigma-0.9.1
-\end_layout
-
-\begin_layout LyX-Code
-$ ./configure --with-hdf5=$HDF5_PREFIX --with-vtk=$VTK_PREFIX
-\end_layout
-
-\begin_layout LyX-Code
-$ make
-\end_layout
-
-\begin_layout LyX-Code
-$ sudo make install
-\end_layout
-
-\begin_layout Subsection
-HDF5
-\end_layout
-
-\begin_layout Standard
-The Hierarchical Data Format (HDF5) library is available for download from
- 
-\begin_inset LatexCommand htmlurl
-name "The HDF Group"
-target "hdfgroup.org/HDF5"
-
-\end_inset
-
-.
- Binaries can be obtained at 
-\begin_inset LatexCommand htmlurl
-name "hdfgroup.org/HDF5/release/obtain5.html"
-target "hdfgroup.org/HDF5/release/obtain5.html"
-
-\end_inset
-
-.
- To install from source, download the latest stable 1.6 version of this library
- (currently 1.6.5) and issue the following commands
-\end_layout
-
-\begin_layout LyX-Code
-$ tar xvfz hdf5-1.6.5
-\end_layout
-
-\begin_layout LyX-Code
-$ cd hdf5-1.6.5
-\end_layout
-
-\begin_layout LyX-Code
-$ ./configure
-\end_layout
-
-\begin_layout LyX-Code
-$ make
-\end_layout
-
-\begin_layout LyX-Code
-$ sudo make install
-\end_layout
-
-\begin_layout Subsection
-VTK
-\end_layout
-
-\begin_layout Standard
-The Visualization Toolkit (VTK) library is a popular open source graphics
- library for scientific visualizations.
- We recommend that you obtain the binaries from a package manager, making
- sure to install the associated development headers along with the library.
- The source for the VTK library is available from 
-\begin_inset LatexCommand htmlurl
-name "Kitware, Inc."
-target "www.vtk.org/get-software.php"
-
-\end_inset
-
-.
- If you decide to compile VTK from source, you will also need the CMake
- build environment, available from 
-\begin_inset LatexCommand htmlurl
-name "CMake"
-target "cmake.org"
-
-\end_inset
-
-.
-\end_layout
-
-\begin_layout Standard
-After downloading the source package, you can issue the following commands
-\end_layout
-
-\begin_layout LyX-Code
-$ tar xvfz vtk-5.0.4.tar.gz
-\end_layout
-
-\begin_layout LyX-Code
-$ cd VTK
-\end_layout
-
-\begin_layout LyX-Code
-$ mkdir build
-\end_layout
-
-\begin_layout LyX-Code
-$ cd build
-\end_layout
-
-\begin_layout LyX-Code
-$ ccmake ..
-\end_layout
-
-\begin_layout LyX-Code
-$ make
-\end_layout
-
-\begin_layout LyX-Code
-$ sudo make install
-\end_layout
-
-\begin_layout Subsection
-NumPy
-\end_layout
-
-\begin_layout Standard
-NumPy is a Python module which adds support for large multi-dimensional
- arrays and matrices, and is available for download from the 
-\begin_inset LatexCommand htmlurl
-name "NumPy Home Page"
-target "numpy.scipy.org "
-
-\end_inset
-
-.
- To install this extension module from source, download it and issue the
- following command in the NumPy source directory
-\end_layout
-
-\begin_layout LyX-Code
-$ sudo python setup.py install
-\end_layout
-
-\begin_layout Standard
-To verify the installation, the command `
-\family typewriter
-import numpy
-\family default
-' should run successfully from within your standard Python interpreter shell.
-\end_layout
-
-\begin_layout Subsection
-PyTables
-\end_layout
-
-\begin_layout Standard
-PyTables is a Python extension module that builds on top of the HDF5 library.
- It provides a convenient scripting interface to manipulate HDF5 files,
- which can be used to manipulate the input/output files created by Cigma.
- PyTables is available for download from 
-\begin_inset LatexCommand htmlurl
-name "PyTables"
-target "www.pytables.org"
-
-\end_inset
-
-.
-\end_layout
-
-\begin_layout Standard
-To install this extension from source, download the latest stable version
- (currently 2.0.2) and issue the following commands
-\end_layout
-
-\begin_layout LyX-Code
-$ tar xvfz pytables-2.0.2
-\end_layout
-
-\begin_layout LyX-Code
-$ cd pytables-2.0.2
-\end_layout
-
-\begin_layout LyX-Code
-$ sudo python setup.py install
-\end_layout
-
-\begin_layout Standard
-To verify the installation, the command `
-\family typewriter
-import tables
-\family default
-' should run successfully from within your standard Python interpreter shell.
-\end_layout
-
-\begin_layout Subsection
-FIAT
-\end_layout
-
-\begin_layout Standard
-The Finite Element Automatic Tabulator (FIAT) Python module supports generation
- of arbitrary order instances of the Lagrange elements, as well as arbitrary
- order instances of the Jacobi-type quadrature rules on the same element
- shapes.
- It is available from 
-\begin_inset LatexCommand htmlurl
-name "The FEniCS Project"
-target "www.fenics.org/wiki/FIAT"
-
-\end_inset
-
-.
-\end_layout
-
-\begin_layout Standard
-To install this module, download it and issue the following command inside
- the FIAT source directory:
-\end_layout
-
-\begin_layout LyX-Code
-$ sudo python setup.py install
-\end_layout
-
-\begin_layout Standard
-You should now be able to run `
-\family typewriter
-import FIAT
-\family default
-' from within your standard Python interpreter shell.
-\end_layout
-
-\begin_layout Subsection
-HDFView (optional)
-\end_layout
-
-\begin_layout Standard
-NCSA HDFView is a graphical user interface tool for accessing data in your
- HDF5 files.
- You can use it for viewing the internal file hierarchy in a tree structure
- (see Figure 
-\begin_inset LatexCommand ref
-reference "fig:With-HFDFView,-you"
-
-\end_inset
-
-), adding new datasets, and modifying or deleting existing datasets, or
- altering metadata on groups and datasets.
- You can download it from the 
-\begin_inset LatexCommand htmlurl
-name "HDFView home page"
-target "hdf.ncsa.uiuc.edu/hdf-java-html/hdfview"
-
-\end_inset
-
-.
-\end_layout
-
-\begin_layout Standard
-\noindent
-\align center
-\begin_inset Float figure
-placement H
-wide false
-sideways false
-status open
-
-\begin_layout Standard
-\noindent
-\align center
-\begin_inset Graphics
-	filename figures/hdfview-bmrsnog.png
-	lyxscale 70
-	width 60page%
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-\begin_inset Caption
-
-\begin_layout Standard
-\begin_inset LatexCommand label
-name "fig:With-HFDFView,-you"
-
-\end_inset
-
-With HFDFView, you can view the internal file hierarchy in a tree structure,
- add new datasets, and modify or delete existing datasets
-\end_layout
-
-\end_inset
-
- 
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Chapter
-\begin_inset LatexCommand label
-name "cha:Error-Analysis"
-
-\end_inset
-
-Error Analysis
-\end_layout
-
-\begin_layout Section
-Introduction
-\end_layout
-
-\begin_layout Standard
-When studying differential equations that represent physical systems we
- often obtain solutions by using a variety of techniques.
- Solving these equations using classical analytical methods is almost impossible
-, so we often resort to numerical algorithms such as the finite element
- method.
-\end_layout
-
-\begin_layout Standard
-For assessing the quality of the solution to our equations, it is important
- to quantify the error in our numerical solutions.
- To calculate this error, we will have to compare these solutions against
- each other through the use of a distance measure between two functions.
-\end_layout
-
-\begin_layout Section
-Distance Measures
-\end_layout
-
-\begin_layout Standard
-The simplest possible quantitative measure of the difference between two
- distinct fields consists of taking the pointwise difference of both fields
- at a common set of points.
- While no finite sample of points can perfectly represent a continuum of
- values, valuable information can be inferred from the statistics of the
- resulting set of differences.
-\end_layout
-
-\begin_layout Standard
-A very useful distance measure we can use is the 
-\begin_inset Formula $L_{2}$
-\end_inset
-
- norm, defined by the following integral
-\end_layout
-
-\begin_layout Standard
-\begin_inset Formula \[
-\varepsilon=||u-v||_{L_{2}}=\sqrt{\int_{\Omega}||u(\vec{x})-v(\vec{x})||^{2}d\vec{x}}\]
-
-\end_inset
-
-where 
-\begin_inset Formula $u$
-\end_inset
-
- and 
-\begin_inset Formula $v$
-\end_inset
-
- are the two functions on a global coordinate system.
- This gives us a single global estimate 
-\begin_inset Formula $\varepsilon$
-\end_inset
-
- representing the distance between the two fields 
-\begin_inset Formula $u(\vec{x})$
-\end_inset
-
- and 
-\begin_inset Formula $v(\vec{x})$
-\end_inset
-
-.
- Alternatively, you may think of this as the size, or norm, of the residual
- field 
-\begin_inset Formula $\rho(\vec{x})=u(\vec{x})-v(\vec{x})$
-\end_inset
-
-.
- 
-\end_layout
-
-\begin_layout Standard
-If we discretize the domain 
-\begin_inset Formula $\Omega$
-\end_inset
-
- into an appropriate set of finite elements 
-\begin_inset Formula $\{\Omega_{e}\}_{e=1}^{n_{el}}$
-\end_inset
-
-, we can compute the above integral as a sum over local contributions on
- each element.
- For efficiency purposes, each local contribution can in turn be integrated
- over a reference element 
-\begin_inset Formula $\hat{\Omega}_{e}$
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-\begin_inset Formula \begin{eqnarray*}
-\varepsilon^{2} & = & \sum_{e=1}^{\mathrm{n_{el}}}\varepsilon_{e}^{2}\\
- & = & \sum_{e=1}^{\mathrm{n_{el}}}\int_{\Omega_{e}}||u(\vec{x})-v(\vec{x})||^{2}d\vec{x}\\
- & = & \sum_{e=1}^{\mathrm{n_{el}}}\int_{\hat{\Omega}_{e}}||u(\vec{\xi})-v(\vec{\xi})||^{2}J_{e}(\vec{\xi})d\vec{\xi}\end{eqnarray*}
-
-\end_inset
-
-where the additional factor 
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-
-\begin_inset Formula $J_{e}(\vec{\xi})$
-\end_inset
-
- is the Jacobian determinant of the reference map 
-\family default
-\series default
-\shape default
-\size default
-\emph default
-\bar default
-\noun default
-\color inherit
-
-\begin_inset Formula $\vec{x}_{e}(\vec{\xi})$
-\end_inset
-
- which describes how the physical element 
-\begin_inset Formula $\Omega_{e}$
-\end_inset
-
- maps to its corresponding reference element 
-\begin_inset Formula $\hat{\Omega}_{e}$
-\end_inset
-
-.
-\end_layout
-
-\begin_layout Standard
-In general, we won't be able to integrate each local contribution exactly
- since the two fields 
-\begin_inset Formula $u$
-\end_inset
-
- and 
-\begin_inset Formula $v$
-\end_inset
-
- may have an incompatible representation with the local domain 
-\begin_inset Formula $\Omega_{e}$
-\end_inset
-
-.
- However, we can approximate each 
-\begin_inset Formula $\varepsilon_{e}^{2}$
-\end_inset
-
- by applying an appropriate quadrature rule with a tolerable truncation
- error 
-\begin_inset LatexCommand cite
-key "Encyclopaedia of Cubature Formulas 2005"
-
-\end_inset
-
-.
-\end_layout
-
-\begin_layout Section
-Global Error
-\end_layout
-
-\begin_layout Standard
-Assuming we apply the same quadrature rule on every element, with 
-\begin_inset Formula $n_{Q}$
-\end_inset
-
- weights 
-\begin_inset Formula $w_{q}$
-\end_inset
-
- and integration points 
-\begin_inset Formula $\vec{\xi}_{q}$
-\end_inset
-
- for 
-\begin_inset Formula $q=1,\ldots,n_{Q}$
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-\begin_inset Formula \begin{eqnarray*}
-\varepsilon_{e}^{2} & = & \sum_{q=1}^{\mathrm{n_{Q}}}w_{q}||\hat{\rho}(\vec{x}_{q})||^{2}\\
- & = & \sum_{q=1}^{\mathrm{n_{Q}}}w_{q}||u(\vec{\xi}_{q})-v(\vec{\xi}_{q})||^{2}J(\vec{\xi}_{q})\end{eqnarray*}
-
-\end_inset
-
-thus we arrive at the final form
-\end_layout
-
-\begin_layout Standard
-\begin_inset Formula \begin{eqnarray*}
-\varepsilon & = & \sqrt{\sum_{e=1}^{\mathrm{n_{el}}}\sum_{q=1}^{\mathrm{n_{q}}}w_{q}||u(\vec{\xi}_{q})-v(\vec{\xi}_{q})||^{2}J(\vec{\xi}_{q})}\end{eqnarray*}
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-In calculating the norm of the residual field 
-\begin_inset Formula $\rho$
-\end_inset
-
-, Cigma will output each of the local contributions 
-\begin_inset Formula $\varepsilon_{e}^{2}$
-\end_inset
-
- which by definition are scalar-valued cell quantities over each of their
- corresponding elements 
-\begin_inset Formula $\Omega_{e}$
-\end_inset
-
-.
-\end_layout
-
-\begin_layout Section
-Comparing Residuals
-\end_layout
-
-\begin_layout Standard
-For comparing errors of different solutions, you can normalize the global
- error by the norm of the exact solution.
- For a family of solutions 
-\begin_inset Formula $u^{h}(\vec{x})$
-\end_inset
-
-, parametrized by the the maximum element size 
-\begin_inset Formula $h$
-\end_inset
-
- of the underlying discretization, and an exact solution 
-\begin_inset Formula $u(\vec{x})$
-\end_inset
-
-, this normalized error is given by
-\end_layout
-
-\begin_layout Standard
-\begin_inset Formula \begin{eqnarray*}
-\varepsilon_{rel} & = & \frac{||u-u^{h}||_{L_{2}}}{||u||_{L_{2}}}\\
- & = & \frac{\int_{\Omega}||u(\vec{x})-u^{h}(\vec{x})||^{2}d\vec{x}}{\int_{\Omega}||u(\vec{x})||^{2}d\vec{x}}\end{eqnarray*}
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-This normalized error can be interpreted as the average error in the physical
- quantity being evaluated, so that a value of 0.01 corresponds to a 1% averaged
- error.
-\end_layout
-
-\begin_layout Standard
-Even if the exact solution is not currently known, this normalized error
- may be used to test the accuracy between two or more numerical solutions,
- defined on successively refined meshes.
-\end_layout
-
-\begin_layout Chapter
-\begin_inset LatexCommand label
-name "cha:Running-Cigma"
-
-\end_inset
-
-Running Cigma
-\end_layout
-
-\begin_layout Standard
-Cigma is used for obtaining error estimates between arbitrary fields, so
- naturally its primary operation is centered around the 
-\family typewriter
-compare
-\family default
- command.
- You will need to provide two datasets describing each of the two fields,
- along with an integration rule and a mesh over which to integrate, although
- these last two will have reasonable defaults if they are not specified.
- This chapter aims to summarize the information you'll need to run cigma.
-\end_layout
-
-\begin_layout Section
-Input and Output
-\end_layout
-
-\begin_layout Standard
-The underlying data storage format for Cigma is the HDF5 format, due to
- its flexibility for storing and organizing large amounts of data.
- 
-\end_layout
-
-\begin_layout Standard
-The Hierarchical Data Format (HDF) is a portable file format developed at
- the 
-\begin_inset LatexCommand htmlurl
-name "National Center for Supercomputing Applications (NCSA)"
-target "hdf.ncsa.uiuc.edu/HDF5"
-
-\end_inset
-
-.
- It is designed for storing, retrieving, analyzing, visualizing, and converting
- scientific data.
- The current and most popular version is HDF5, which stores multi-dimensional
- arrays together with ancillary data in a portable self-describing format.
- It uses a hierarchical structure that provides application programmers
- with a host of options for organizing how data is stored in HDF5 files.
-\end_layout
-
-\begin_layout Standard
-Using HDF5 datasets in Cigma allows us to avoid having to convert between
- too many distinct formats.
- Moreover, due to the amount of disk I/O, large finite element meshes can
- be handled more efficiently in binary format.
- 
-\end_layout
-
-\begin_layout Standard
-Cigma also supports the popular VTK format for providing mesh and field
- inputs.
- A simple text format is also supported to aid in debugging.
- As described in Chapter 
-\begin_inset LatexCommand ref
-reference "cha:Running-Cigma"
-
-\end_inset
-
-, you can easily examine the structure of an input file by using the 
-\family typewriter
-cigma list
-\family default
- command, which will simply reveal the names and dimensions of all datasets
- inside the specified file.
-\end_layout
-
-\begin_layout Section
-Mesh
-\end_layout
-
-\begin_layout Standard
-In Cigma, we define a finite element mesh simply by coordinates, 
-\begin_inset Formula $(x_{n},y_{n},z_{n})$
-\end_inset
-
- of its degrees of freedom, and the connectivity relations 
-\begin_inset Formula $\Omega_{e}=\{n_{1},n_{2},\ldots\}$
-\end_inset
-
- among them which define each individual element in the corresponding discretiza
-tion.
-\end_layout
-
-\begin_layout Standard
-As seen from Equation Since the integration points on two distinct meshes
- will not typically coincide, it is very important to index the location
- of each element into spatial data structure.
- 
-\end_layout
-
-\begin_layout Section
-Fields
-\end_layout
-
-\begin_layout Standard
-A field is a function which assigns a physical quantity to every point in
- space.
- This quantity may correspond to a scalar, a vector, or even a tensor.
- A finite element approximation to an unknown field 
-\begin_inset Formula $\phi(\vec{x})$
-\end_inset
-
- is simply the weighed sum over a fixed set of localized shape functions
- 
-\begin_inset Formula $\phi_{n}(\vec{x})$
-\end_inset
-
-.
- 
-\end_layout
-
-\begin_layout Standard
-\begin_inset Formula \[
-\phi(\vec{x})=\sum_{n=1}^{N}d_{n}\phi_{n}(\vec{x})\]
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-Naturally, once the weights 
-\begin_inset Formula $d_{n}$
-\end_inset
-
-, or degrees of freedom as they are also called, are known to us, we can
- evaluate 
-\begin_inset Formula $\phi(\vec{x})$
-\end_inset
-
- at any point 
-\begin_inset Formula $\vec{x}$
-\end_inset
-
- we desire.
- Thus, in Cigma a field is represented simply by a list of degrees of freedom
- 
-\begin_inset Formula $d_{n}$
-\end_inset
-
-, which may be a scalar, vector or tensor quantity, depending on the nature
- of 
-\begin_inset Formula $\phi$
-\end_inset
-
-.
-\end_layout
-
-\begin_layout Section
-Elements
-\end_layout
-
-\begin_layout Standard
-The most common element types used in the finite element method are given
- by the following shape functions, defined on their respective domains,
-\end_layout
-
-\begin_layout Paragraph*
-Function Space 
-\bar under
-tet4
-\end_layout
-
-\begin_layout Standard
-\begin_inset Formula \begin{eqnarray*}
-TN_{a} & = & \frac{1}{2}(-1-x-y-z)\\
-TN_{b} & = & \frac{1}{2}(1+x)\\
-TN_{c} & = & \frac{1}{2}(1+y)\\
-TN_{d} & = & \frac{1}{2}(1+z)\end{eqnarray*}
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Paragraph*
-Function Space 
-\bar under
-hex8
-\end_layout
-
-\begin_layout Standard
-\begin_inset Formula \begin{eqnarray*}
-HN_{a} & = & \frac{1}{8}\left(1-x\right)\left(1-y\right)\left(1-z\right)\\
-HN_{b} & = & \frac{1}{8}\left(1+x\right)\left(1-y\right)\left(1-z\right)\\
-HN_{c} & = & \frac{1}{8}\left(1-x\right)\left(1+y\right)\left(1-z\right)\\
-HN_{d} & = & \frac{1}{8}\left(1+x\right)\left(1+y\right)\left(1-z\right)\\
-HN_{e} & = & \frac{1}{8}\left(1-x\right)\left(1-y\right)\left(1+z\right)\\
-HN_{f} & = & \frac{1}{8}\left(1+x\right)\left(1-y\right)\left(1+z\right)\\
-HN_{g} & = & \frac{1}{8}\left(1-x\right)\left(1+y\right)\left(1+z\right)\\
-HN_{h} & = & \frac{1}{8}\left(1+x\right)\left(1+y\right)\left(1+z\right)\end{eqnarray*}
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-These are built-in elements in Cigma, and you may refer to them by name
- in the FunctionSpace metadata attribute on your datasets.
-\end_layout
-
-\begin_layout Standard
-Higher order elements can also be used by specifying an explicit tabulation
- matrix representing the values of your shape functions on the corresponding
- set of quadrature points.
- 
-\end_layout
-
-\begin_layout Section
-Command Line Interface
-\end_layout
-
-\begin_layout Standard
-Cigma is designed to be scriptable.
- Thus, all operations can be specified as command line arguments given to
- a single executable called 
-\family typewriter
-cigma
-\family default
-.
- A list of available commands can be obtained by typing
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
-cigma --help
-\end_layout
-
-\begin_layout Standard
-Further usage information can also be obtained with 
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
-cigma help <command>
-\end_layout
-
-\begin_layout Standard
-Specifying the complete path to a dataset consists of the special form 
-\family typewriter
-\series bold
-filepath:dataset
-\family default
-\series default
-, a colon-delimited pair of file path and dataset path.
-\end_layout
-
-\begin_layout Subsection
-Listing Data
-\end_layout
-
-\begin_layout Standard
-Because Cigma relies on the ability of the user to specify dataset paths,
- we have provided a command called 
-\family typewriter
-list
-\family default
- for viewing the structure of an input file.
- Its usage is very simple.
- 
-\end_layout
-
-\begin_layout Standard
-To view the structure of an HDF5 file:
-\end_layout
-
-\begin_layout LyX-Code
-$ 
-\series bold
-cigma list file.h5
-\end_layout
-
-\begin_deeper
-\begin_layout LyX-Code
-/mesh/coordinates           Dataset {119827, 3}
-\end_layout
-
-\begin_layout LyX-Code
-/mesh/connectivity          Dataset {661929, 4}
-\end_layout
-
-\begin_layout LyX-Code
-/vars/displacement/step0    Dataset {119827, 3}
-\end_layout
-
-\begin_layout LyX-Code
-/residuals/comparison0      Dataset {661929, 1}
-\end_layout
-
-\end_deeper
-\begin_layout Standard
-If VTK support is enabled, you can view the structure of a VTK file with:
-\end_layout
-
-\begin_layout LyX-Code
-$ 
-\series bold
-cigma list file.vtk
-\end_layout
-
-\begin_deeper
-\begin_layout LyX-Code
-Reading file.vtk
-\end_layout
-
-\begin_layout LyX-Code
-Points = 119827
-\end_layout
-
-\begin_layout LyX-Code
-Cells = 661929
-\end_layout
-
-\begin_layout LyX-Code
-PointDataArray[0] = displacements_t0 (119827 x 3)
-\end_layout
-
-\end_deeper
-\begin_layout LyX-Code
-
-\end_layout
-
-\begin_layout Subsection
-Comparing Two Fields
-\end_layout
-
-\begin_layout Standard
-Comparing two arbitrary finite element fields can be accomplished with the
- 
-\family typewriter
-cigma compare
-\family default
- command-line utility.
- By default, the comparison will take place over the elements in the mesh
- of the first field.
- Finally, the square of each of the local residual values are written to
- the specified VTK output file as cell-based scalars.
-\end_layout
-
-\begin_layout Standard
-A basic comparison can be as simple as specifying the following arguments:
-\end_layout
-
-\begin_layout LyX-Code
-cigma compare --output=squared-residuals.vtk
-\end_layout
-
-\begin_layout LyX-Code
-
-\series bold
- 
-\series default
-             --first=field1.h5:/field1/stepN
-\end_layout
-
-\begin_layout LyX-Code
-
-\series bold
- 
-\series default
-             --second=field2.h5:/field2/stepN
-\end_layout
-
-\begin_layout Subsection
-Specifying a Mesh
-\end_layout
-
-\begin_layout Standard
-To override the mesh used in the integration, you can specify an extra argument
- providing the location of the mesh:
-\end_layout
-
-\begin_layout LyX-Code
-cigma compare [...]
-\end_layout
-
-\begin_layout LyX-Code
-  --mesh=mesh.h5:/model/mesh/
-\end_layout
-
-\begin_layout Standard
-You can also specify the coordinates and connectivity arrays separately,
- in case they reside in separate files.
-\end_layout
-
-\begin_layout LyX-Code
-cigma compare [...]
-\end_layout
-
-\begin_layout LyX-Code
-  --mesh-coordinates=file1.h5:/model/mesh/coordinates
-\end_layout
-
-\begin_layout LyX-Code
-  --mesh-connectivity=file2.h5:/model/mesh/connectivity
-\end_layout
-
-\begin_layout Subsection
-Specifying a Quadrature Rule
-\end_layout
-
-\begin_layout Standard
-To specify a quadrature rule, you will have to provide the quadrature weights
- and points in the appropriate reference element.
- This can be done with the following additional argument:
-\end_layout
-
-\begin_layout LyX-Code
-cigma compare [...]
-\end_layout
-
-\begin_layout LyX-Code
-  --rule=quadrature-rules.h5:/path/to/rule
-\end_layout
-
-\begin_layout Standard
-You may also specify the location of the points and weights separately:
-\end_layout
-
-\begin_layout LyX-Code
-cigma compare [...]
-\end_layout
-
-\begin_layout LyX-Code
-  --rule-points=file.h5:/path/to/rule/points
-\end_layout
-
-\begin_layout LyX-Code
-  --rule-weights=file.h5:/path/to/rule/weights
-\end_layout
-
-\begin_layout LyX-Code
-
-\end_layout
-
-\begin_layout Subsection
-Comparing against Known Values
-\end_layout
-
-\begin_layout Standard
-A finite element description might not always be available for one of the
- fields.
- However, you can break the comparison into several steps if you have a
- means to compute that field on any of the required points.
-\end_layout
-
-\begin_layout Standard
-First, extract the global coordinates of the integration points.
- This will result in an explicit list of points over which to evaluate your
- field.
-\end_layout
-
-\begin_layout LyX-Code
-cigma extract --mesh=field1.h5:/model/mesh/
-\end_layout
-
-\begin_layout LyX-Code
-              --output=points.h5:/points
-\end_layout
-
-\begin_layout Standard
-Now you can evaluate your function at the designated points.
- You can provide the path to the explicit set of values with
-\end_layout
-
-\begin_layout LyX-Code
-cigma compare --output=squared-residuals.vtk
-\end_layout
-
-\begin_layout LyX-Code
-              --first=field1.h5:/field1/stepN
-\end_layout
-
-\begin_layout LyX-Code
-              --second=values.h5:/stepN_values
-\end_layout
-
-\begin_layout Subsection
-\begin_inset LatexCommand label
-name "sub:Comparing-against-a"
-
-\end_inset
-
-Comparing against a Known Function
-\end_layout
-
-\begin_layout Standard
-If one of your fields is easily described by an analytic expression, then
- you also have the option to compile your analytic function into Cigma,
- which will enable the 
-\family typewriter
-compare
-\family default
- command to reference your function by name:
-\end_layout
-
-\begin_layout LyX-Code
-cigma compare --output=squared-residuals.vtk
-\end_layout
-
-\begin_layout LyX-Code
-
-\series bold
- 
-\series default
-             --first=field1.h5:/vars/displacement/step0
-\end_layout
-
-\begin_layout LyX-Code
-
-\series bold
- 
-\series default
-             --second=
-\bar under
-disloc3d
-\series bold
-\bar default
- 
-\series default
- 
-\end_layout
-
-\begin_layout Standard
-You may also interact with your analytic function by using the 
-\family typewriter
-cigma
-\family default
- 
-\family typewriter
-eval
-\family default
- command, and obtain a set of values which may then be passed back to the
- 
-\family typewriter
-compare
-\family default
- command.
- 
-\end_layout
-
-\begin_layout LyX-Code
-cigma eval --function=disloc3d
-\end_layout
-
-\begin_layout LyX-Code
-           --points=points.h5:/points
-\end_layout
-
-\begin_layout LyX-Code
-           --values=values.h5:/disloc3d_values
-\end_layout
-
-\begin_layout LyX-Code
-
-\end_layout
-
-\begin_layout LyX-Code
-cigma compare --output=squared-residuals.vtk
-\end_layout
-
-\begin_layout LyX-Code
-              --first=field1.h5:/vars/displacement/step0
-\end_layout
-
-\begin_layout LyX-Code
-              --second=values.h5:/disloc3d_values
-\end_layout
-
-\begin_layout Standard
-Another built-in function you might find useful for evaluating the norm
- of your field is the 
-\family typewriter
-\bar under
-zero
-\family default
-\bar default
- function, which simply returns zero when evaluated at any point.
-\end_layout
-
-\begin_layout Chapter
-Examples
-\end_layout
-
-\begin_layout Standard
-In this Chapter we will use sample datasets from the strike-slip benchmark
- case defined by the CIG Short-Term Tectonics working group.
- In this benchmark problem, we solve for the viscoelastic relaxation of
- stresses from a single finite earthquake while ignoring gravity.
- The problem is defined on a cube domain with sides of 24 km consisting
- of two layers of different material types.
- The top layer of the cube is nearly elastic, while the bottom layer is
- viscoelastic.
-\end_layout
-
-\begin_layout Section
-Convergence
-\end_layout
-
-\begin_layout Standard
-When the exact solution of your equations is known, the norm of the error
- for a finite element solution is easily computed through the procedure
- given in Chapter 
-\begin_inset LatexCommand ref
-reference "cha:Error-Analysis"
-
-\end_inset
-
-.
- 
-\end_layout
-
-\begin_layout Standard
-Another way of checking the accuracy of a solution is by rerunning the same
- problem with a finer mesh.
- Recall that in the finite element method, the weight functions and trial
- solutions are chosen so that the finite element method is convergent.
- In other words, as the element size 
-\begin_inset Formula $h$
-\end_inset
-
- decreases, the solution tends to the correct solution.
- Thus, if the difference between the coarse and fine mesh solutions is small,
- we can conclude that the coarse mesh solution is quite accurate.
- However, if a solution changes noticeably with refinement of the mesh,
- the coarse mesh solution is inaccurate, and even the finer mesh may be
- inadequate as well.
-\end_layout
-
-\begin_layout Standard
-As can be seen from these results, the log of the error varies linearly
- with element size and the slope depends on the order of the element.
- Denoting the slope by 
-\begin_inset Formula $\alpha$
-\end_inset
-
-, then the error in the function can be expressed as
-\end_layout
-
-\begin_layout Standard
-\begin_inset Formula \[
-\log\varepsilon=\log C+\alpha\log h\]
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-where 
-\begin_inset Formula $\log C$
-\end_inset
-
- is an arbitrary constant, the y-intercept of the curve.
- The slope 
-\begin_inset Formula $\alpha$
-\end_inset
-
- is the rate of convergence of the element.
- We can rewrite this as
-\end_layout
-
-\begin_layout Standard
-\begin_inset Formula \[
-\varepsilon=Ch^{\alpha}\]
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Section
-Different Element Types
-\end_layout
-
-\begin_layout Standard
-Here we compare
-\end_layout
-
-\begin_layout Section
-Different FEM Codes
-\end_layout
-
-\begin_layout Chapter
-\start_of_appendix
-File Formats
-\end_layout
-
-\begin_layout Standard
-To differentiate between these formats, you will need to provide an appropriate
- extension for your input and output files.
- The supported extensions are currently 
-\family typewriter
-.h5
-\family default
- for HDF5, 
-\family typewriter
-.vtk
-\family default
- for VTK files, and 
-\family typewriter
-.txt
-\family default
- for simple text files.
-\end_layout
-
-\begin_layout Section
-Input File Format
-\end_layout
-
-\begin_layout Standard
-There are about six different objects you will want to use as input to cigma,
- all of which can be represented as two-dimensional datasets.
- These are the 
-\end_layout
-
-\begin_layout Itemize
-mesh coordinates
-\end_layout
-
-\begin_layout Itemize
-mesh connectivity
-\end_layout
-
-\begin_layout Itemize
-field coefficients (degrees of freedom)
-\end_layout
-
-\begin_layout Itemize
-quadrature rule points
-\end_layout
-
-\begin_layout Itemize
-quadrature rule weights
-\end_layout
-
-\begin_layout Itemize
-shape function tabulation matrix
-\end_layout
-
-\begin_layout Subsection
-HDF5
-\end_layout
-
-\begin_layout Standard
-HDF5 files are organized in a hierarchical structure, similar to a UNIX
- file system.
- Two types of primary objects, groups and datasets, are stored in this structure.
- A group contains instances of zero or more groups or datasets, while a
- dataset stores a multi-dimensional array of data elements.
- Both kinds of objects are accompanied by supporting metadata known as attribute
-s.
-\end_layout
-
-\begin_layout Standard
-A dataset is physically stored in two parts: a header and a data array.
- The header contains miscellaneous metadata describing the dataset as well
- as information that is needed to interpret the array portion of the dataset.
- Essentially, it includes the name, datatype, dataspace, and storage layout
- of the dataset.
- The name is a text string identifying the dataset.
- The datatype describes the type of the data array elements.
- The dataspace defines the dimensionality of the dataset, i.e., the size and
- shape of the multi-dimensional array.
-\end_layout
-
-\begin_layout Standard
-In Cigma you always provide an explicit path to every dataset, so you have
- a fair amount of flexibility for how you organize your datasets inside
- HDF5 files.
- For example, a typical Cigma HDF5 file could have the following structure.
-\end_layout
-
-\begin_layout LyX-Code
-model.h5
-\end_layout
-
-\begin_layout LyX-Code
-
-\backslash
-__ model
-\end_layout
-
-\begin_layout LyX-Code
-    |__ mesh
-\end_layout
-
-\begin_layout LyX-Code
-    |   |__ coordinates    [nno x nsd]
-\end_layout
-
-\begin_layout LyX-Code
-    |   
-\backslash
-__ connectivity   [nel x ndof]
-\end_layout
-
-\begin_layout LyX-Code
-    
-\backslash
-__ variables
-\end_layout
-
-\begin_layout LyX-Code
-        |__ temperature
-\end_layout
-
-\begin_layout LyX-Code
-        |   |__ step00000  [nno x 1]
-\end_layout
-
-\begin_layout LyX-Code
-        |   |__ step00010  [nno x 1]
-\end_layout
-
-\begin_layout LyX-Code
-        |   
-\backslash
-...
-\end_layout
-
-\begin_layout LyX-Code
-        |__ displacement
-\end_layout
-
-\begin_layout LyX-Code
-        |   |__ step00000  [nno x 3]
-\end_layout
-
-\begin_layout LyX-Code
-        |   |__ step00010  [nno x 3]
-\end_layout
-
-\begin_layout LyX-Code
-        |   
-\backslash
-...
-\end_layout
-
-\begin_layout LyX-Code
-        
-\backslash
-__ velocity
-\end_layout
-
-\begin_layout LyX-Code
-            |__ step00000  [nno x 3]
-\end_layout
-
-\begin_layout LyX-Code
-            |__ step00010  [nno x 3]
-\end_layout
-
-\begin_layout LyX-Code
-            
-\backslash
-...
-\end_layout
-
-\begin_layout Standard
-Generally, Cigma will only require you to specify the path to a specific
- field dataset.
- If a small amount of metadata is present in your field dataset, the rest
- of the required information, such as which mesh and finite elements to
- use, will be deduced from that metadata.
-\end_layout
-
-\begin_layout Description
-MeshID an identifier assigned for use in linking child datasets to their
- parent mesh.
-\end_layout
-
-\begin_layout Description
-MeshLocation points to the HDF5 group which contains the appropriate coordinates
- and connectivity datasets.
-\end_layout
-
-\begin_layout Description
-FunctionSpace string identifier to determine which shape functions to use
- for interpolating values inside the element (e.g., tet4, hex8, quad4, tri3,
- ...).
-\end_layout
-
-\begin_layout Description
-DatasetType string identifier for classifying the type of data contained
- in the dataset (e.g., points, connectivity, degrees of freedom, quadrature
- rules, global quadrature points, global field values).
-\end_layout
-
-\begin_layout Subsection
-VTK
-\end_layout
-
-\begin_layout Standard
-The current version of Cigma only supports VTK unstructured grid datasets
- of a single element type.
- You can still compare various unstructured grids with different element
- types to each other.
-\end_layout
-
-\begin_layout Standard
-Note that while you typically provide a path (or name) for every dataset,
- this is not necessary when specifying a VTK mesh, since this data is taken
- from the special Points and Cells arrays, which you cannot rename.
- However, you will still need to provide a name when referring to the field
- coefficients, which are assumed to be stored as Point Data in the input
- VTK file.
-\end_layout
-
-\begin_layout Standard
-For more information, you may want to refer to Visualization ToolKit's 
-\begin_inset LatexCommand htmlurl
-name "File Formats"
-target "www.vtk.org/pdf/file-formats.pdf"
-
-\end_inset
-
- document.
- 
-\end_layout
-
-\begin_layout Subsection
-Text
-\end_layout
-
-\begin_layout Standard
-The text format is always in table form, with the dimensions of the table
- specified in the first line.
- For example, mesh coordinates can be specified in the following format
-\end_layout
-
-\begin_layout LyX-Code
-nno nsd
-\end_layout
-
-\begin_layout LyX-Code
-x1 y1 z1
-\end_layout
-
-\begin_layout LyX-Code
-x2 y2 z2
-\end_layout
-
-\begin_layout LyX-Code
-x3 y3 z3
-\end_layout
-
-\begin_layout LyX-Code
-...
-\end_layout
-
-\begin_layout Standard
-Mesh connectivity with 
-\end_layout
-
-\begin_layout LyX-Code
-nel ndofs
-\end_layout
-
-\begin_layout LyX-Code
-node_1 node_2 node_3 node_4 ...
-\end_layout
-
-\begin_layout LyX-Code
-node_1 node_2 node_3 node_4 ...
-\end_layout
-
-\begin_layout LyX-Code
-node_1 node_2 node_3 node_4 ...
-\end_layout
-
-\begin_layout LyX-Code
-...
-\end_layout
-
-\begin_layout Standard
-A generic field with 
-\family typewriter
-ndim
-\family default
- components (i.e., scalar, vector, or tensor) is specified by
-\end_layout
-
-\begin_layout LyX-Code
-num ndim
-\end_layout
-
-\begin_layout LyX-Code
-f1 f2 f3 ..
-\end_layout
-
-\begin_layout LyX-Code
-f1 f2 f3 ..
-\end_layout
-
-\begin_layout LyX-Code
-...
-\end_layout
-
-\begin_layout Standard
-In this last case, the number of rows could refer to either 
-\family typewriter
-nno
-\family default
- or 
-\family typewriter
-nel
-\family default
-, depending on whether the field is node-based or cell-based.
-\end_layout
-
-\begin_layout Section
-Output File Format
-\end_layout
-
-\begin_layout Standard
-The output format for residuals consists simply of a list of scalars for
- each element in the discretization.
- If you specify a 
-\family typewriter
-.vtk
-\family default
- extension for your output file, this will result in an scalar dataset named
- epsilon stored using the legacy VTK file format in the Cell Data section
- of the output file.
- Note that this output consists of the squared values of the local residuals,
- so further post-processing will be necessary.
-\end_layout
-
-\begin_layout Chapter
-License 
-\end_layout
-
-\begin_layout Standard
-
-\series bold
-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
-\series default
- 
-\newline
-
-\series medium
-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
-\begin_inset ERT
-status collapsed
-
-\begin_layout Standard
-
-
-\backslash
-begin{itemize}
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-\begin_inset ERT
-status collapsed
-
-\begin_layout Standard
-
-
-\backslash
-item[0.]
-\end_layout
-
-\end_inset
-
-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."
-\newline
-
-\newline
-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
-\begin_inset ERT
-status collapsed
-
-\begin_layout Standard
-
-
-\backslash
-end{itemize}
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Enumerate
-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_deeper
-\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
-
-\end_deeper
-\begin_layout Enumerate
-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_deeper
-\begin_layout Enumerate
-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 Enumerate
-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 Enumerate
-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
-
-\end_deeper
-\begin_layout Enumerate
-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_deeper
-\begin_layout Enumerate
-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 Enumerate
-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 Enumerate
-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
-
-\end_deeper
-\begin_layout Enumerate
-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 Enumerate
-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 Enumerate
-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 Enumerate
-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_deeper
-\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
-
-\end_deeper
-\begin_layout Enumerate
-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 geographic
-al 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 Enumerate
-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_deeper
-\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
-
-\end_deeper
-\begin_layout Enumerate
-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 Section*
-NO WARRANTY 
-\end_layout
-
-\begin_layout Standard
-\begin_inset ERT
-status collapsed
-
-\begin_layout Standard
-
-
-\backslash
-begin{itemize}
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-\begin_inset ERT
-status collapsed
-
-\begin_layout Standard
-
-
-\backslash
-item[11.]
-\end_layout
-
-\end_inset
-
-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
-\begin_inset ERT
-status collapsed
-
-\begin_layout Standard
-
-
-\backslash
-item[12.]
-\end_layout
-
-\end_inset
-
-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 Standard
-\begin_inset ERT
-status collapsed
-
-\begin_layout Standard
-
-
-\backslash
-end{itemize}
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-END OF TERMS AND CONDITIONS 
-\end_layout
-
-\begin_layout Standard
-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.
- For example:
-\end_layout
-
-\begin_layout Standard
-One line to give the program's name and a brief idea of what it does.
- Copyright 
-\size footnotesize
-© (
-\size default
-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 © 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.
- 
-\end_layout
-
-\begin_layout Standard
-(signature of Ty Coon)
-\newline
-1 April 1989 
-\newline
-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
-
-\begin_layout Bibliography
-\begin_inset LatexCommand bibitem
-label "1"
-key "Akin 2005"
-
-\end_inset
-
-Akin, J.E.
- (2005), 
-\emph on
-Finite Element Analysis with Error Estimators,
-\emph default
- Butterworth-Heinemann, Oxford, 447 pp.
- 
-\end_layout
-
-\begin_layout Bibliography
-\begin_inset LatexCommand bibitem
-label "2"
-key "Encyclopaedia of Cubature Formulas 2005"
-
-\end_inset
-
-Encyclopaedia of Cubature Formulas (1998-2005), Katholieke Universiteit
- Leuven, Dept.
- Computerwetenschappen, www.cs.kuleuven.be/~nines/research/ecf/
-\end_layout
-
-\begin_layout Bibliography
-\begin_inset LatexCommand bibitem
-label "3"
-key "Hughes 2000"
-
-\end_inset
-
-Hughes, Thomas J.R.
- (2000), 
-\emph on
-The Finite Element Method: Linear Static and Dynamic Finite Element Analysis
-\emph default
-, Dover, 672 pp.
-\end_layout
-
-\begin_layout Bibliography
-\begin_inset LatexCommand bibitem
-label "4"
-key "KarniadakisSherwin2005"
-
-\end_inset
-
-Karniadakis, George E.
- and Spencer J.
- Sherwin (2005), 
-\emph on
-Spectral/
-\emph default
-hp 
-\emph on
-Element Methods for Computational Fluid Dynamics, Second Edition
-\emph default
-, Numerical Mathematics and Scientific Computation, Oxford, 657 pp.
-\end_layout
-
-\begin_layout Bibliography
-\begin_inset LatexCommand bibitem
-label "5"
-key "Uesu-etal2005"
-
-\end_inset
-
-Uesu, D., L.
- Bavoil, S.
- Fleishman, J.
- Shepherd, and C.
- Silva (2005), Simplification of Unstructured Tetrahedral Meshes by Point-Sampli
-ng, 
-\emph on
-Proceedings of the 2005 International Workshop on Volume Graphics,
-\emph default
- 157-165, doi: 10.2312/VG/VG05/157-165.
-\end_layout
-
-\end_body
-\end_document
+#LyX 1.5.4 created this file. For more info see http://www.lyx.org/
+\lyxformat 276
+\begin_document
+\begin_header
+\textclass book
+\begin_preamble
+\usepackage{hyperref}
+
+\let\myUrl\url
+\renewcommand{\url}[1]{(\myUrl{#1})}
+\end_preamble
+\language english
+\inputencoding auto
+\font_roman default
+\font_sans default
+\font_typewriter default
+\font_default_family default
+\font_sc false
+\font_osf false
+\font_sf_scale 100
+\font_tt_scale 100
+\graphics default
+\paperfontsize default
+\spacing single
+\papersize default
+\use_geometry true
+\use_amsmath 1
+\use_esint 0
+\cite_engine basic
+\use_bibtopic false
+\paperorientation portrait
+\leftmargin 1in
+\topmargin 1in
+\rightmargin 1in
+\bottommargin 1in
+\secnumdepth 3
+\tocdepth 3
+\paragraph_separation indent
+\defskip medskip
+\quotes_language swedish
+\papercolumns 1
+\papersides 2
+\paperpagestyle headings
+\tracking_changes false
+\output_changes false
+\author "" 
+\author "" 
+\end_header
+
+\begin_body
+
+\begin_layout Standard
+\noindent
+\align center
+
+\color none
+\begin_inset ERT
+status collapsed
+
+\begin_layout Standard
+
+
+\backslash
+thispagestyle{empty}
+\end_layout
+
+\end_inset
+
+
+\begin_inset Float figure
+placement H
+wide false
+sideways false
+status collapsed
+
+\begin_layout Standard
+\begin_inset Graphics
+	filename figures/cigma_cover.pdf
+	display color
+	width 75page%
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+\noindent
+\align center
+
+\color none
+\begin_inset ERT
+status collapsed
+
+\begin_layout Standard
+
+
+\backslash
+thispagestyle{empty}
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Title
+Cigma
+\end_layout
+
+\begin_layout Author
+© California Institute of Technology
+\newline
+Version 0.9.1
+\end_layout
+
+\begin_layout Date
+\begin_inset ERT
+status collapsed
+
+\begin_layout Standard
+
+
+\backslash
+today
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+\begin_inset LatexCommand tableofcontents
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+\begin_inset FloatList figure
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+\begin_inset ERT
+status collapsed
+
+\begin_layout Standard
+
+
+\backslash
+raggedbottom
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+
+\newpage
+
+\end_layout
+
+\begin_layout Chapter
+Introduction
+\end_layout
+
+\begin_layout Section
+About Cigma
+\end_layout
+
+\begin_layout Standard
+The CIG Model Analyzer (Cigma) consists of a suite of tools for comparing
+ numerical models.
+ CIG has developed Cigma in response to demand from the short-term tectonics
+ community for a simple tool that can perform rigorous error analysis on
+ their finite element codes.
+ The long-term goal for Cigma, however, is for it to be used for nearly
+ all geodynamics modeling codes.
+\end_layout
+
+\begin_layout Standard
+The current version of Cigma is intended for the calculation of 
+\begin_inset Formula $L_{2}$
+\end_inset
+
+ residuals for finite element models.
+ This software was designed for performing the following three main tasks:
+ (1) error analysis, (2) benchmarking, and (3) code verification.
+ In error analysis, Cigma can calculate a global measure of the error between
+ two solutions by performing an integration over a discretized version of
+ the common domain.
+ This comparison can take place even when the underlying discretizations
+ do not overlap.
+ In benchmarking, Cigma can help the geodynamics community agree on a standard
+ solution to specific problems by facilitating the process of comparing
+ different numerical codes against each other.
+ Lastly, as an automated tool, Cigma can help application developers create
+ regression tests to ensure that software changes do not affect the consistency
+ of the results.
+\end_layout
+
+\begin_layout Standard
+At its core, Cigma draws from a variety of libraries.
+ The 
+\begin_inset LatexCommand htmlurl
+name "FInite element Automatic Tabulator (FIAT)"
+target "www.fenics.org/wiki/FIAT"
+
+\end_inset
+
+ Python Library supports generation of arbitrary order instances of the
+ Lagrange elements on lines, triangles, and tetrahedra.
+ It can also generate higher order instances of Jacobi-type quadrature rules
+ on the same element shapes.
+ The 
+\begin_inset LatexCommand htmlurl
+name "Approximate Nearest Neighbor (ANN)"
+target "www.cs.umd.edu/~mount/ANN/"
+
+\end_inset
+
+ Library, written in C++, supports data structures and algorithms for both
+ exact and nearest-neighbor searching in arbitrarily high dimensions.
+\end_layout
+
+\begin_layout Standard
+Both of these libraries extend and generalize Cigma's functionality so it
+ can handle other types of elements, and provide the ability to compare
+ vector fields.
+\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 the hope that the software will enhance your research
+ in geophysics.
+ This is a brand-new code and at present no papers are published or press.
+ Please cite this manual as follows:
+\end_layout
+
+\begin_layout Itemize
+Armendariz, L., and S.
+ Kientz.
+ 
+\emph on
+Cigma User Manual.
+
+\emph default
+ Pasadena, CA: Computational Infrastructure of Geodynamics, 2008.
+ URL: geodynamics.org/cig/software/cs/cigma/cigma.pdf
+\end_layout
+
+\begin_layout Standard
+CIG requests that in your oral presentations and in your papers that you
+ indicate your use of this code and acknowledge the author of the code and
+ 
+\begin_inset LatexCommand htmlurl
+name "CIG"
+target "geodynamics.org"
+
+\end_inset
+
+.
+\end_layout
+
+\begin_layout Section
+Support
+\end_layout
+
+\begin_layout Standard
+Cigma development is based upon work supported by the National Science Foundatio
+n under Grant No.
+ EAR-0406751.
+ Any opinions, findings, and conclusions or recommendations expressed in
+ this material are those of the authors and do not necessarily reflect the
+ views of the National Science Foundation.
+ The code is being released under the GNU General Public License.
+\end_layout
+
+\begin_layout Chapter
+Installation and Getting Help
+\end_layout
+
+\begin_layout Section
+Getting Help
+\end_layout
+
+\begin_layout Standard
+For help, send an e-mail to the 
+\begin_inset LatexCommand url
+name "CIG Computational Science Mailing List"
+target "cig-cs at geodynamics.org"
+
+\end_inset
+
+.
+ You can subscribe to the 
+\family typewriter
+cig-cs
+\family default
+ mailing list and view archived discussions at the 
+\begin_inset LatexCommand htmlurl
+name "CIG Mail Lists web page"
+target "geodynamics.org/cig/lists"
+
+\end_inset
+
+.
+ If you encounter any bugs or have problems installing Cigma, please submit
+ a report to the 
+\begin_inset LatexCommand htmlurl
+name "CIG Bug Tracker"
+target "geodynamics.org/bugs"
+
+\end_inset
+
+.
+\end_layout
+
+\begin_layout Section
+Installating from Source
+\end_layout
+
+\begin_layout Standard
+To install Cigma, download the source package from the 
+\begin_inset LatexCommand htmlurl
+name "CIG Cigma web page"
+target "geodynamics.org/cig/software/packages/cs/cigma"
+
+\end_inset
+
+.
+ You will need the GNU C++ compiler for this step.
+ The HDF5 and VTK libraries, described later in this section, are also required.
+\end_layout
+
+\begin_layout Standard
+After installing the necessary dependencies, simply unpack the source tar
+ file and issue the following commands
+\end_layout
+
+\begin_layout LyX-Code
+$ tar xvfz cigma-0.9.1.tar.gz
+\end_layout
+
+\begin_layout LyX-Code
+$ cd cigma-0.9.1
+\end_layout
+
+\begin_layout LyX-Code
+$ ./configure --with-hdf5=$HDF5_PREFIX --with-vtk=$VTK_PREFIX
+\end_layout
+
+\begin_layout LyX-Code
+$ make
+\end_layout
+
+\begin_layout LyX-Code
+$ make install
+\end_layout
+
+\begin_layout Subsection
+HDF5
+\end_layout
+
+\begin_layout Standard
+The Hierarchical Data Format (HDF5) library is available for download from
+ 
+\begin_inset LatexCommand htmlurl
+name "The HDF Group"
+target "hdfgroup.org/HDF5"
+
+\end_inset
+
+.
+ Binaries can be obtained at 
+\begin_inset LatexCommand htmlurl
+name "hdfgroup.org/HDF5/release/obtain5.html"
+target "hdfgroup.org/HDF5/release/obtain5.html"
+
+\end_inset
+
+.
+ To install from source, download the latest stable 1.6 version of this library
+ (currently 1.6.5) and issue the following commands
+\end_layout
+
+\begin_layout LyX-Code
+$ tar xvfz hdf5-1.6.5
+\end_layout
+
+\begin_layout LyX-Code
+$ cd hdf5-1.6.5
+\end_layout
+
+\begin_layout LyX-Code
+$ ./configure
+\end_layout
+
+\begin_layout LyX-Code
+$ make
+\end_layout
+
+\begin_layout LyX-Code
+$ make install
+\end_layout
+
+\begin_layout Subsection
+VTK
+\end_layout
+
+\begin_layout Standard
+The Visualization Toolkit (VTK) library is a popular open source graphics
+ library for scientific visualizations.
+ We recommend that you obtain the binaries from a package manager, making
+ sure to install the associated development headers along with the library.
+ The source for the VTK library is available from 
+\begin_inset LatexCommand htmlurl
+name "Kitware, Inc."
+target "www.vtk.org/get-software.php"
+
+\end_inset
+
+.
+ If you decide to compile VTK from source, you will also need the CMake
+ build environment, available from 
+\begin_inset LatexCommand htmlurl
+name "CMake"
+target "cmake.org"
+
+\end_inset
+
+.
+\end_layout
+
+\begin_layout Standard
+After downloading the source package, you can issue the following commands
+\end_layout
+
+\begin_layout LyX-Code
+$ tar xvfz vtk-5.0.4.tar.gz
+\end_layout
+
+\begin_layout LyX-Code
+$ cd VTK
+\end_layout
+
+\begin_layout LyX-Code
+$ mkdir build
+\end_layout
+
+\begin_layout LyX-Code
+$ cd build
+\end_layout
+
+\begin_layout LyX-Code
+$ ccmake ..
+\end_layout
+
+\begin_layout LyX-Code
+$ make
+\end_layout
+
+\begin_layout LyX-Code
+$ make install
+\end_layout
+
+\begin_layout Subsection
+NumPy
+\end_layout
+
+\begin_layout Standard
+NumPy is a Python module which adds support for large multi-dimensional
+ arrays and matrices, and is available for download from the 
+\begin_inset LatexCommand htmlurl
+name "NumPy Home Page"
+target "numpy.scipy.org "
+
+\end_inset
+
+.
+ To install this extension module from source, download it and issue the
+ following command in the NumPy source directory
+\end_layout
+
+\begin_layout LyX-Code
+$ python setup.py install
+\end_layout
+
+\begin_layout Standard
+To verify the installation, the command `
+\family typewriter
+import numpy
+\family default
+' should run successfully from within your standard Python interpreter shell.
+\end_layout
+
+\begin_layout Subsection
+PyTables
+\end_layout
+
+\begin_layout Standard
+PyTables is a Python extension module that builds on top of the HDF5 library.
+ It provides a convenient scripting interface to manipulate HDF5 files,
+ which can be used to manipulate the input/output files created by Cigma.
+ PyTables is available for download from 
+\begin_inset LatexCommand htmlurl
+name "PyTables"
+target "www.pytables.org"
+
+\end_inset
+
+.
+\end_layout
+
+\begin_layout Standard
+To install this extension from source, download the latest stable version
+ (currently 2.0.2) and issue the following commands
+\end_layout
+
+\begin_layout LyX-Code
+$ tar xvfz pytables-2.0.2
+\end_layout
+
+\begin_layout LyX-Code
+$ cd pytables-2.0.2
+\end_layout
+
+\begin_layout LyX-Code
+$ python setup.py install
+\end_layout
+
+\begin_layout Standard
+To verify the installation, the command `
+\family typewriter
+import tables
+\family default
+' should run successfully from within your standard Python interpreter shell.
+\end_layout
+
+\begin_layout Subsection
+FIAT
+\end_layout
+
+\begin_layout Standard
+The Finite Element Automatic Tabulator (FIAT) Python module supports generation
+ of arbitrary order instances of the Lagrange elements, as well as arbitrary
+ order instances of the Jacobi-type quadrature rules on the same element
+ shapes.
+ It is available from 
+\begin_inset LatexCommand htmlurl
+name "The FEniCS Project"
+target "www.fenics.org/wiki/FIAT"
+
+\end_inset
+
+.
+\end_layout
+
+\begin_layout Standard
+To install this module, download it and issue the following command inside
+ the FIAT source directory:
+\end_layout
+
+\begin_layout LyX-Code
+$ sudo python setup.py install
+\end_layout
+
+\begin_layout Standard
+You should now be able to run `
+\family typewriter
+import FIAT
+\family default
+' from within your standard Python interpreter shell.
+\end_layout
+
+\begin_layout Subsection
+HDFView (optional)
+\end_layout
+
+\begin_layout Standard
+NCSA HDFView is a graphical user interface tool for accessing data in your
+ HDF5 files.
+ You can use it for viewing the internal file hierarchy in a tree structure
+ (see Figure 
+\begin_inset LatexCommand ref
+reference "fig:With-HFDFView,-you"
+
+\end_inset
+
+), adding new datasets, and modifying or deleting existing datasets, or
+ altering metadata on groups and datasets.
+ You can download it from the 
+\begin_inset LatexCommand htmlurl
+name "HDFView home page"
+target "hdf.ncsa.uiuc.edu/hdf-java-html/hdfview"
+
+\end_inset
+
+.
+\end_layout
+
+\begin_layout Standard
+\noindent
+\align center
+\begin_inset Float figure
+placement H
+wide false
+sideways false
+status collapsed
+
+\begin_layout Standard
+\noindent
+\align center
+\begin_inset Graphics
+	filename figures/hdfview-bmrsnog.png
+	lyxscale 70
+	width 60page%
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+\begin_inset Caption
+
+\begin_layout Standard
+\begin_inset LatexCommand label
+name "fig:With-HFDFView,-you"
+
+\end_inset
+
+With HFDFView, you can view the internal file hierarchy in a tree structure,
+ add new datasets, and modify or delete existing datasets
+\end_layout
+
+\end_inset
+
+ 
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Chapter
+\begin_inset LatexCommand label
+name "cha:Error-Analysis"
+
+\end_inset
+
+Error Analysis
+\end_layout
+
+\begin_layout Section
+Introduction
+\end_layout
+
+\begin_layout Standard
+When studying differential equations that represent physical systems we
+ often obtain solutions by using a variety of techniques.
+ Solving these equations using classical analytical methods is almost impossible
+, so we often resort to numerical algorithms such as the finite element
+ method.
+\end_layout
+
+\begin_layout Standard
+For assessing the quality of the solution to our equations, it is important
+ to quantify the error in our numerical solutions.
+ To calculate this error, we will have to compare these solutions against
+ each other through the use of a distance measure between two functions.
+\end_layout
+
+\begin_layout Section
+Distance Measures
+\end_layout
+
+\begin_layout Standard
+The simplest possible quantitative measure of the difference between two
+ distinct fields consists of taking the pointwise difference of both fields
+ at a common set of points.
+ While no finite sample of points can perfectly represent a continuum of
+ values, valuable information can be inferred from the statistics of the
+ resulting set of differences.
+\end_layout
+
+\begin_layout Standard
+A very useful distance measure we can use is the 
+\begin_inset Formula $L_{2}$
+\end_inset
+
+ norm, defined by the following integral
+\end_layout
+
+\begin_layout Standard
+\begin_inset Formula \[
+\varepsilon=||u-v||_{L_{2}}=\sqrt{\int_{\Omega}||u(\vec{x})-v(\vec{x})||^{2}d\vec{x}}\]
+
+\end_inset
+
+where 
+\begin_inset Formula $u$
+\end_inset
+
+ and 
+\begin_inset Formula $v$
+\end_inset
+
+ are the two functions on a global coordinate system.
+ This gives us a single global estimate 
+\begin_inset Formula $\varepsilon$
+\end_inset
+
+ representing the distance between the two fields 
+\begin_inset Formula $u(\vec{x})$
+\end_inset
+
+ and 
+\begin_inset Formula $v(\vec{x})$
+\end_inset
+
+.
+ Alternatively, you may think of this as the size, or norm, of the residual
+ field 
+\begin_inset Formula $\rho(\vec{x})=u(\vec{x})-v(\vec{x})$
+\end_inset
+
+.
+ 
+\end_layout
+
+\begin_layout Standard
+If we discretize the domain 
+\begin_inset Formula $\Omega$
+\end_inset
+
+ into an appropriate set of finite elements 
+\begin_inset Formula $\{\Omega_{e}\}_{e=1}^{n_{el}}$
+\end_inset
+
+, we can compute the above integral as a sum over local contributions on
+ each element.
+ For efficiency purposes, each local contribution can in turn be integrated
+ over a reference element 
+\begin_inset Formula $\hat{\Omega}_{e}$
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+\begin_inset Formula \begin{eqnarray*}
+\varepsilon^{2} & = & \sum_{e=1}^{\mathrm{n_{el}}}\varepsilon_{e}^{2}\\
+ & = & \sum_{e=1}^{\mathrm{n_{el}}}\int_{\Omega_{e}}||u(\vec{x})-v(\vec{x})||^{2}d\vec{x}\\
+ & = & \sum_{e=1}^{\mathrm{n_{el}}}\int_{\hat{\Omega}_{e}}||u(\vec{\xi})-v(\vec{\xi})||^{2}J_{e}(\vec{\xi})d\vec{\xi}\end{eqnarray*}
+
+\end_inset
+
+where the additional factor 
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+
+\begin_inset Formula $J_{e}(\vec{\xi})$
+\end_inset
+
+ is the Jacobian determinant of the reference map 
+\family default
+\series default
+\shape default
+\size default
+\emph default
+\bar default
+\noun default
+\color inherit
+
+\begin_inset Formula $\vec{x}_{e}(\vec{\xi})$
+\end_inset
+
+ which describes how the physical element 
+\begin_inset Formula $\Omega_{e}$
+\end_inset
+
+ maps to its corresponding reference element 
+\begin_inset Formula $\hat{\Omega}_{e}$
+\end_inset
+
+.
+\end_layout
+
+\begin_layout Standard
+In general, we won't be able to integrate each local contribution exactly
+ since the two fields 
+\begin_inset Formula $u$
+\end_inset
+
+ and 
+\begin_inset Formula $v$
+\end_inset
+
+ may have an incompatible representation with the local domain 
+\begin_inset Formula $\Omega_{e}$
+\end_inset
+
+.
+ However, we can approximate each 
+\begin_inset Formula $\varepsilon_{e}^{2}$
+\end_inset
+
+ by applying an appropriate quadrature rule with a tolerable truncation
+ error 
+\begin_inset LatexCommand cite
+key "Encyclopaedia of Cubature Formulas 2005"
+
+\end_inset
+
+.
+\end_layout
+
+\begin_layout Section
+Global Error
+\end_layout
+
+\begin_layout Standard
+Assuming we apply the same quadrature rule on every element, with 
+\begin_inset Formula $n_{Q}$
+\end_inset
+
+ weights 
+\begin_inset Formula $w_{q}$
+\end_inset
+
+ and integration points 
+\begin_inset Formula $\vec{\xi}_{q}$
+\end_inset
+
+ for 
+\begin_inset Formula $q=1,\ldots,n_{Q}$
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+\begin_inset Formula \begin{eqnarray*}
+\varepsilon_{e}^{2} & = & \sum_{q=1}^{\mathrm{n_{Q}}}w_{q}||\hat{\rho}(\vec{x}_{q})||^{2}\\
+ & = & \sum_{q=1}^{\mathrm{n_{Q}}}w_{q}||u(\vec{\xi}_{q})-v(\vec{\xi}_{q})||^{2}J(\vec{\xi}_{q})\end{eqnarray*}
+
+\end_inset
+
+thus we arrive at the final form
+\end_layout
+
+\begin_layout Standard
+\begin_inset Formula \begin{eqnarray*}
+\varepsilon & = & \sqrt{\sum_{e=1}^{\mathrm{n_{el}}}\sum_{q=1}^{\mathrm{n_{q}}}w_{q}||u(\vec{\xi}_{q})-v(\vec{\xi}_{q})||^{2}J(\vec{\xi}_{q})}\end{eqnarray*}
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+In calculating the norm of the residual field 
+\begin_inset Formula $\rho$
+\end_inset
+
+, Cigma will output each of the local contributions 
+\begin_inset Formula $\varepsilon_{e}^{2}$
+\end_inset
+
+ which by definition are scalar-valued cell quantities over each of their
+ corresponding elements 
+\begin_inset Formula $\Omega_{e}$
+\end_inset
+
+.
+\end_layout
+
+\begin_layout Section
+Comparing Residuals
+\end_layout
+
+\begin_layout Standard
+For comparing errors of different solutions, you can normalize the global
+ error by the norm of the exact solution.
+ For a family of solutions 
+\begin_inset Formula $u^{h}(\vec{x})$
+\end_inset
+
+, parametrized by the the maximum element size 
+\begin_inset Formula $h$
+\end_inset
+
+ of the underlying discretization, and an exact solution 
+\begin_inset Formula $u(\vec{x})$
+\end_inset
+
+, this normalized error is given by
+\end_layout
+
+\begin_layout Standard
+\begin_inset Formula \begin{eqnarray*}
+\varepsilon_{rel} & = & \frac{||u-u^{h}||_{L_{2}}}{||u||_{L_{2}}}\\
+ & = & \frac{\int_{\Omega}||u(\vec{x})-u^{h}(\vec{x})||^{2}d\vec{x}}{\int_{\Omega}||u(\vec{x})||^{2}d\vec{x}}\end{eqnarray*}
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+This normalized error can be interpreted as the average error in the physical
+ quantity being evaluated, so that a value of 0.01 corresponds to a 1% averaged
+ error.
+\end_layout
+
+\begin_layout Standard
+Even if the exact solution is not currently known, this normalized error
+ may be used to test the accuracy between two or more numerical solutions,
+ defined on successively refined meshes.
+\end_layout
+
+\begin_layout Chapter
+\begin_inset LatexCommand label
+name "cha:Running-Cigma"
+
+\end_inset
+
+Running Cigma
+\end_layout
+
+\begin_layout Standard
+Cigma is used for obtaining error estimates between arbitrary fields, so
+ naturally its primary operation is centered around the 
+\family typewriter
+compare
+\family default
+ command.
+ You will need to provide two datasets describing each of the two fields,
+ along with an integration rule and a mesh over which to integrate, although
+ these last two will have reasonable defaults if they are not specified.
+ This chapter aims to summarize the information you'll need to run cigma.
+\end_layout
+
+\begin_layout Section
+Input and Output
+\end_layout
+
+\begin_layout Standard
+The underlying data storage format for Cigma is the HDF5 format, due to
+ its flexibility for storing and organizing large amounts of data.
+ 
+\end_layout
+
+\begin_layout Standard
+The Hierarchical Data Format (HDF) is a portable file format developed at
+ the 
+\begin_inset LatexCommand htmlurl
+name "National Center for Supercomputing Applications (NCSA)"
+target "hdf.ncsa.uiuc.edu/HDF5"
+
+\end_inset
+
+.
+ It is designed for storing, retrieving, analyzing, visualizing, and converting
+ scientific data.
+ The current and most popular version is HDF5, which stores multi-dimensional
+ arrays together with ancillary data in a portable self-describing format.
+ It uses a hierarchical structure that provides application programmers
+ with a host of options for organizing how data is stored in HDF5 files.
+\end_layout
+
+\begin_layout Standard
+Using HDF5 datasets in Cigma allows us to avoid having to convert between
+ too many distinct formats.
+ Moreover, due to the amount of disk I/O, large finite element meshes can
+ be handled more efficiently in binary format.
+ 
+\end_layout
+
+\begin_layout Standard
+Cigma also supports the popular VTK format for providing mesh and field
+ inputs.
+ A simple text format is also supported to aid in debugging.
+ As described in Chapter 
+\begin_inset LatexCommand ref
+reference "cha:Running-Cigma"
+
+\end_inset
+
+, you can easily examine the structure of an input file by using the 
+\family typewriter
+cigma list
+\family default
+ command, which will simply reveal the names and dimensions of all datasets
+ inside the specified file.
+\end_layout
+
+\begin_layout Section
+Mesh
+\end_layout
+
+\begin_layout Standard
+In Cigma, we define a finite element mesh simply by coordinates, 
+\begin_inset Formula $(x_{n},y_{n},z_{n})$
+\end_inset
+
+ of its degrees of freedom, and the connectivity relations 
+\begin_inset Formula $\Omega_{e}=\{n_{1},n_{2},\ldots\}$
+\end_inset
+
+ among them which define each individual element in the corresponding discretiza
+tion.
+\end_layout
+
+\begin_layout Standard
+As seen from Equation Since the integration points on two distinct meshes
+ will not typically coincide, it is very important to index the location
+ of each element into spatial data structure.
+ 
+\end_layout
+
+\begin_layout Section
+Fields
+\end_layout
+
+\begin_layout Standard
+A field is a function which assigns a physical quantity to every point in
+ space.
+ This quantity may correspond to a scalar, a vector, or even a tensor.
+ A finite element approximation to an unknown field 
+\begin_inset Formula $\phi(\vec{x})$
+\end_inset
+
+ is simply the weighed sum over a fixed set of localized shape functions
+ 
+\begin_inset Formula $\phi_{n}(\vec{x})$
+\end_inset
+
+.
+ 
+\end_layout
+
+\begin_layout Standard
+\begin_inset Formula \[
+\phi(\vec{x})=\sum_{n=1}^{N}d_{n}\phi_{n}(\vec{x})\]
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+Naturally, once the weights 
+\begin_inset Formula $d_{n}$
+\end_inset
+
+, or degrees of freedom as they are also called, are known to us, we can
+ evaluate 
+\begin_inset Formula $\phi(\vec{x})$
+\end_inset
+
+ at any point 
+\begin_inset Formula $\vec{x}$
+\end_inset
+
+ we desire.
+ Thus, in Cigma a field is represented simply by a list of degrees of freedom
+ 
+\begin_inset Formula $d_{n}$
+\end_inset
+
+, which may be a scalar, vector or tensor quantity, depending on the nature
+ of 
+\begin_inset Formula $\phi$
+\end_inset
+
+.
+\end_layout
+
+\begin_layout Section
+Elements
+\end_layout
+
+\begin_layout Standard
+The most common element types used in the finite element method are given
+ by the following shape functions, defined on their respective domains,
+\end_layout
+
+\begin_layout Paragraph*
+Function Space 
+\bar under
+tet4
+\end_layout
+
+\begin_layout Standard
+\begin_inset Formula \begin{eqnarray*}
+TN_{a} & = & \frac{1}{2}(-1-x-y-z)\\
+TN_{b} & = & \frac{1}{2}(1+x)\\
+TN_{c} & = & \frac{1}{2}(1+y)\\
+TN_{d} & = & \frac{1}{2}(1+z)\end{eqnarray*}
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Paragraph*
+Function Space 
+\bar under
+hex8
+\end_layout
+
+\begin_layout Standard
+\begin_inset Formula \begin{eqnarray*}
+HN_{a} & = & \frac{1}{8}\left(1-x\right)\left(1-y\right)\left(1-z\right)\\
+HN_{b} & = & \frac{1}{8}\left(1+x\right)\left(1-y\right)\left(1-z\right)\\
+HN_{c} & = & \frac{1}{8}\left(1-x\right)\left(1+y\right)\left(1-z\right)\\
+HN_{d} & = & \frac{1}{8}\left(1+x\right)\left(1+y\right)\left(1-z\right)\\
+HN_{e} & = & \frac{1}{8}\left(1-x\right)\left(1-y\right)\left(1+z\right)\\
+HN_{f} & = & \frac{1}{8}\left(1+x\right)\left(1-y\right)\left(1+z\right)\\
+HN_{g} & = & \frac{1}{8}\left(1-x\right)\left(1+y\right)\left(1+z\right)\\
+HN_{h} & = & \frac{1}{8}\left(1+x\right)\left(1+y\right)\left(1+z\right)\end{eqnarray*}
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+These are built-in elements in Cigma, and you may refer to them by name
+ in the FunctionSpace metadata attribute on your datasets.
+\end_layout
+
+\begin_layout Standard
+Higher order elements can also be used by specifying an explicit tabulation
+ matrix representing the values of your shape functions on the corresponding
+ set of quadrature points.
+ 
+\end_layout
+
+\begin_layout Section
+Command Line Interface
+\end_layout
+
+\begin_layout Standard
+Cigma is designed to be scriptable.
+ Thus, all operations can be specified as command line arguments given to
+ a single executable called 
+\family typewriter
+cigma
+\family default
+.
+ A list of available commands can be obtained by typing
+\end_layout
+
+\begin_layout LyX-Code
+
+\family typewriter
+cigma --help
+\end_layout
+
+\begin_layout Standard
+Further usage information can also be obtained with 
+\end_layout
+
+\begin_layout LyX-Code
+
+\family typewriter
+cigma help <command>
+\end_layout
+
+\begin_layout Standard
+Specifying the complete path to a dataset consists of the special form 
+\family typewriter
+\series bold
+filepath:dataset
+\family default
+\series default
+, a colon-delimited pair of file path and dataset path.
+\end_layout
+
+\begin_layout Subsection
+Listing Data
+\end_layout
+
+\begin_layout Standard
+Because Cigma relies on the ability of the user to specify dataset paths,
+ we have provided a command called 
+\family typewriter
+list
+\family default
+ for viewing the structure of an input file.
+ Its usage is very simple.
+ 
+\end_layout
+
+\begin_layout Standard
+To view the structure of an HDF5 file:
+\end_layout
+
+\begin_layout LyX-Code
+$ 
+\series bold
+cigma list file.h5
+\end_layout
+
+\begin_deeper
+\begin_layout LyX-Code
+/mesh/coordinates           Dataset {119827, 3}
+\end_layout
+
+\begin_layout LyX-Code
+/mesh/connectivity          Dataset {661929, 4}
+\end_layout
+
+\begin_layout LyX-Code
+/vars/displacement/step0    Dataset {119827, 3}
+\end_layout
+
+\begin_layout LyX-Code
+/residuals/comparison0      Dataset {661929, 1}
+\end_layout
+
+\end_deeper
+\begin_layout Standard
+If VTK support is enabled, you can view the structure of a VTK file with:
+\end_layout
+
+\begin_layout LyX-Code
+$ 
+\series bold
+cigma list file.vtk
+\end_layout
+
+\begin_deeper
+\begin_layout LyX-Code
+Reading file.vtk
+\end_layout
+
+\begin_layout LyX-Code
+Points = 119827
+\end_layout
+
+\begin_layout LyX-Code
+Cells = 661929
+\end_layout
+
+\begin_layout LyX-Code
+PointDataArray[0] = displacements_t0 (119827 x 3)
+\end_layout
+
+\end_deeper
+\begin_layout LyX-Code
+
+\end_layout
+
+\begin_layout Subsection
+Comparing Two Fields
+\end_layout
+
+\begin_layout Standard
+Comparing two arbitrary finite element fields can be accomplished with the
+ 
+\family typewriter
+cigma compare
+\family default
+ command-line utility.
+ By default, the comparison will take place over the elements in the mesh
+ of the first field.
+ Finally, the square of each of the local residual values are written to
+ the specified VTK output file as cell-based scalars.
+\end_layout
+
+\begin_layout Standard
+A basic comparison can be as simple as specifying the following arguments:
+\end_layout
+
+\begin_layout LyX-Code
+cigma compare --output=squared-residuals.vtk
+\end_layout
+
+\begin_layout LyX-Code
+
+\series bold
+ 
+\series default
+             --first=field1.h5:/field1/stepN
+\end_layout
+
+\begin_layout LyX-Code
+
+\series bold
+ 
+\series default
+             --second=field2.h5:/field2/stepN
+\end_layout
+
+\begin_layout Subsection
+Specifying a Mesh
+\end_layout
+
+\begin_layout Standard
+To override the mesh used in the integration, you can specify an extra argument
+ providing the location of the mesh:
+\end_layout
+
+\begin_layout LyX-Code
+cigma compare [...]
+\end_layout
+
+\begin_layout LyX-Code
+  --quadrature-mesh=mesh.h5:/model/mesh/
+\end_layout
+
+\begin_layout Standard
+You can also specify the coordinates and connectivity arrays separately,
+ in case they reside in separate files.
+\end_layout
+
+\begin_layout LyX-Code
+cigma compare [...]
+\end_layout
+
+\begin_layout LyX-Code
+  --quadrature-mesh-coordinates=file1.h5:/model/mesh/coordinates
+\end_layout
+
+\begin_layout LyX-Code
+  --quadrature-mesh-connectivity=file2.h5:/model/mesh/connectivity
+\end_layout
+
+\begin_layout Subsection
+Specifying a Quadrature Rule
+\end_layout
+
+\begin_layout Standard
+To specify a quadrature rule, you will have to provide the quadrature weights
+ and points in the appropriate reference element.
+ This can be done with the following additional argument:
+\end_layout
+
+\begin_layout LyX-Code
+cigma compare [...]
+\end_layout
+
+\begin_layout LyX-Code
+  --quadrature-rule=quadrature-rules.h5:/path/to/rule
+\end_layout
+
+\begin_layout Standard
+You may also specify the location of the points and weights separately:
+\end_layout
+
+\begin_layout LyX-Code
+cigma compare [...]
+\end_layout
+
+\begin_layout LyX-Code
+  --quadrature-rule-points=file.h5:/path/to/rule/points
+\end_layout
+
+\begin_layout LyX-Code
+  --quadrature-rule-weights=file.h5:/path/to/rule/weights
+\end_layout
+
+\begin_layout LyX-Code
+
+\end_layout
+
+\begin_layout Subsection
+Comparing against Known Values
+\end_layout
+
+\begin_layout Standard
+A finite element description might not always be available for one of the
+ fields.
+ However, you can break the comparison into several steps if you have a
+ means to compute that field on any of the required points.
+\end_layout
+
+\begin_layout Standard
+First, extract the global coordinates of the integration points.
+ This will result in an explicit list of points over which to evaluate your
+ field.
+\end_layout
+
+\begin_layout LyX-Code
+cigma extract --mesh=field1.h5:/model/mesh/
+\end_layout
+
+\begin_layout LyX-Code
+              --output=points.h5:/points
+\end_layout
+
+\begin_layout Standard
+Now you can evaluate your function at the designated points.
+ You can provide the path to the explicit set of values with
+\end_layout
+
+\begin_layout LyX-Code
+cigma compare --output=squared-residuals.vtk
+\end_layout
+
+\begin_layout LyX-Code
+              --first=field1.h5:/field1/stepN
+\end_layout
+
+\begin_layout LyX-Code
+              --second=values.h5:/stepN_values
+\end_layout
+
+\begin_layout Subsection
+\begin_inset LatexCommand label
+name "sub:Comparing-against-a"
+
+\end_inset
+
+Comparing against a Known Function
+\end_layout
+
+\begin_layout Standard
+If one of your fields is easily described by an analytic expression, then
+ you also have the option to compile your analytic function into Cigma,
+ which will enable the 
+\family typewriter
+compare
+\family default
+ command to reference your function by name:
+\end_layout
+
+\begin_layout LyX-Code
+cigma compare --output=squared-residuals.vtk
+\end_layout
+
+\begin_layout LyX-Code
+
+\series bold
+ 
+\series default
+             --first=field1.h5:/vars/displacement/step0
+\end_layout
+
+\begin_layout LyX-Code
+
+\series bold
+ 
+\series default
+             --second=
+\bar under
+disloc3d
+\series bold
+\bar default
+ 
+\series default
+ 
+\end_layout
+
+\begin_layout Standard
+You may also interact with your analytic function by using the 
+\family typewriter
+cigma
+\family default
+ 
+\family typewriter
+eval
+\family default
+ command, and obtain a set of values which may then be passed back to the
+ 
+\family typewriter
+compare
+\family default
+ command.
+ 
+\end_layout
+
+\begin_layout LyX-Code
+cigma eval --function=disloc3d
+\end_layout
+
+\begin_layout LyX-Code
+           --points=points.h5:/points
+\end_layout
+
+\begin_layout LyX-Code
+           --values=values.h5:/disloc3d_values
+\end_layout
+
+\begin_layout LyX-Code
+
+\end_layout
+
+\begin_layout LyX-Code
+cigma compare --output=squared-residuals.vtk
+\end_layout
+
+\begin_layout LyX-Code
+              --first=field1.h5:/vars/displacement/step0
+\end_layout
+
+\begin_layout LyX-Code
+              --second=values.h5:/disloc3d_values
+\end_layout
+
+\begin_layout Standard
+Another built-in function you might find useful for evaluating the norm
+ of your field is the 
+\family typewriter
+\bar under
+zero
+\family default
+\bar default
+ function, which simply returns zero when evaluated at any point.
+\end_layout
+
+\begin_layout Chapter
+Examples
+\end_layout
+
+\begin_layout Standard
+In this Chapter we will use sample datasets from the strike-slip benchmark
+ case defined by the CIG Short-Term Tectonics working group.
+ In this benchmark problem, we solve for the viscoelastic relaxation of
+ stresses from a single finite earthquake while ignoring gravity.
+ The problem is defined on a cube domain with sides of 24 km consisting
+ of two layers of different material types.
+ The top layer of the cube is nearly elastic, while the bottom layer is
+ viscoelastic.
+\end_layout
+
+\begin_layout Section
+Convergence
+\end_layout
+
+\begin_layout Standard
+When the exact solution of your equations is known, the norm of the error
+ for a finite element solution is easily computed through the procedure
+ given in Chapter 
+\begin_inset LatexCommand ref
+reference "cha:Error-Analysis"
+
+\end_inset
+
+.
+ 
+\end_layout
+
+\begin_layout Standard
+Another way of checking the accuracy of a solution is by rerunning the same
+ problem with a finer mesh.
+ Recall that in the finite element method, the weight functions and trial
+ solutions are chosen so that the finite element method is convergent.
+ In other words, as the element size 
+\begin_inset Formula $h$
+\end_inset
+
+ decreases, the solution tends to the correct solution.
+ Thus, if the difference between the coarse and fine mesh solutions is small,
+ we can conclude that the coarse mesh solution is quite accurate.
+ However, if a solution changes noticeably with refinement of the mesh,
+ the coarse mesh solution is inaccurate, and even the finer mesh may be
+ inadequate as well.
+\end_layout
+
+\begin_layout Standard
+As can be seen from these results, the log of the error varies linearly
+ with element size and the slope depends on the order of the element.
+ Denoting the slope by 
+\begin_inset Formula $\alpha$
+\end_inset
+
+, then the error in the function can be expressed as
+\end_layout
+
+\begin_layout Standard
+\begin_inset Formula \[
+\log\varepsilon=\log C+\alpha\log h\]
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+where 
+\begin_inset Formula $\log C$
+\end_inset
+
+ is an arbitrary constant, the y-intercept of the curve.
+ The slope 
+\begin_inset Formula $\alpha$
+\end_inset
+
+ is the rate of convergence of the element.
+ We can rewrite this as
+\end_layout
+
+\begin_layout Standard
+\begin_inset Formula \[
+\varepsilon=Ch^{\alpha}\]
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Section
+Different Element Types
+\end_layout
+
+\begin_layout Standard
+Here we compare
+\end_layout
+
+\begin_layout Section
+Different FEM Codes
+\end_layout
+
+\begin_layout Chapter
+\start_of_appendix
+File Formats
+\end_layout
+
+\begin_layout Standard
+To differentiate between these formats, you will need to provide an appropriate
+ extension for your input and output files.
+ The supported extensions are currently 
+\family typewriter
+.h5
+\family default
+ for HDF5, 
+\family typewriter
+.vtk
+\family default
+ for VTK files, and 
+\family typewriter
+.txt
+\family default
+ for simple text files.
+\end_layout
+
+\begin_layout Section
+Input File Format
+\end_layout
+
+\begin_layout Standard
+There are about six different objects you will want to use as input to cigma,
+ all of which can be represented as two-dimensional datasets.
+ These are the 
+\end_layout
+
+\begin_layout Itemize
+mesh coordinates
+\end_layout
+
+\begin_layout Itemize
+mesh connectivity
+\end_layout
+
+\begin_layout Itemize
+field coefficients (degrees of freedom)
+\end_layout
+
+\begin_layout Itemize
+quadrature rule points
+\end_layout
+
+\begin_layout Itemize
+quadrature rule weights
+\end_layout
+
+\begin_layout Itemize
+shape function tabulation matrix
+\end_layout
+
+\begin_layout Subsection
+HDF5
+\end_layout
+
+\begin_layout Standard
+HDF5 files are organized in a hierarchical structure, similar to a UNIX
+ file system.
+ Two types of primary objects, groups and datasets, are stored in this structure.
+ A group contains instances of zero or more groups or datasets, while a
+ dataset stores a multi-dimensional array of data elements.
+ Both kinds of objects are accompanied by supporting metadata known as attribute
+s.
+\end_layout
+
+\begin_layout Standard
+A dataset is physically stored in two parts: a header and a data array.
+ The header contains miscellaneous metadata describing the dataset as well
+ as information that is needed to interpret the array portion of the dataset.
+ Essentially, it includes the name, datatype, dataspace, and storage layout
+ of the dataset.
+ The name is a text string identifying the dataset.
+ The datatype describes the type of the data array elements.
+ The dataspace defines the dimensionality of the dataset, i.e., the size and
+ shape of the multi-dimensional array.
+\end_layout
+
+\begin_layout Standard
+In Cigma you always provide an explicit path to every dataset, so you have
+ a fair amount of flexibility for how you organize your datasets inside
+ HDF5 files.
+ For example, a typical Cigma HDF5 file could have the following structure.
+\end_layout
+
+\begin_layout LyX-Code
+model.h5
+\end_layout
+
+\begin_layout LyX-Code
+
+\backslash
+__ model
+\end_layout
+
+\begin_layout LyX-Code
+    |__ mesh
+\end_layout
+
+\begin_layout LyX-Code
+    |   |__ coordinates    [nno x nsd]
+\end_layout
+
+\begin_layout LyX-Code
+    |   
+\backslash
+__ connectivity   [nel x ndof]
+\end_layout
+
+\begin_layout LyX-Code
+    
+\backslash
+__ variables
+\end_layout
+
+\begin_layout LyX-Code
+        |__ temperature
+\end_layout
+
+\begin_layout LyX-Code
+        |   |__ step00000  [nno x 1]
+\end_layout
+
+\begin_layout LyX-Code
+        |   |__ step00010  [nno x 1]
+\end_layout
+
+\begin_layout LyX-Code
+        |   
+\backslash
+...
+\end_layout
+
+\begin_layout LyX-Code
+        |__ displacement
+\end_layout
+
+\begin_layout LyX-Code
+        |   |__ step00000  [nno x 3]
+\end_layout
+
+\begin_layout LyX-Code
+        |   |__ step00010  [nno x 3]
+\end_layout
+
+\begin_layout LyX-Code
+        |   
+\backslash
+...
+\end_layout
+
+\begin_layout LyX-Code
+        
+\backslash
+__ velocity
+\end_layout
+
+\begin_layout LyX-Code
+            |__ step00000  [nno x 3]
+\end_layout
+
+\begin_layout LyX-Code
+            |__ step00010  [nno x 3]
+\end_layout
+
+\begin_layout LyX-Code
+            
+\backslash
+...
+\end_layout
+
+\begin_layout Standard
+Generally, Cigma will only require you to specify the path to a specific
+ field dataset.
+ If a small amount of metadata is present in your field dataset, the rest
+ of the required information, such as which mesh and finite elements to
+ use, will be deduced from that metadata.
+\end_layout
+
+\begin_layout Description
+MeshID an identifier assigned for use in linking child datasets to their
+ parent mesh.
+\end_layout
+
+\begin_layout Description
+MeshLocation points to the HDF5 group which contains the appropriate coordinates
+ and connectivity datasets.
+\end_layout
+
+\begin_layout Description
+FunctionSpace string identifier to determine which shape functions to use
+ for interpolating values inside the element (e.g., tet4, hex8, quad4, tri3,
+ ...).
+\end_layout
+
+\begin_layout Description
+DatasetType string identifier for classifying the type of data contained
+ in the dataset (e.g., points, connectivity, degrees of freedom, quadrature
+ rules, global quadrature points, global field values).
+\end_layout
+
+\begin_layout Subsection
+VTK
+\end_layout
+
+\begin_layout Standard
+The current version of Cigma only supports VTK unstructured grid datasets
+ of a single element type.
+ You can still compare various unstructured grids with different element
+ types to each other.
+\end_layout
+
+\begin_layout Standard
+Note that while you typically provide a path (or name) for every dataset,
+ this is not necessary when specifying a VTK mesh, since this data is taken
+ from the special Points and Cells arrays, which you cannot rename.
+ However, you will still need to provide a name when referring to the field
+ coefficients, which are assumed to be stored as Point Data in the input
+ VTK file.
+\end_layout
+
+\begin_layout Standard
+For more information, you may want to refer to Visualization ToolKit's 
+\begin_inset LatexCommand htmlurl
+name "File Formats"
+target "www.vtk.org/pdf/file-formats.pdf"
+
+\end_inset
+
+ document.
+ 
+\end_layout
+
+\begin_layout Subsection
+Text
+\end_layout
+
+\begin_layout Standard
+The text format is always in table form, with the dimensions of the table
+ specified in the first line.
+ For example, mesh coordinates can be specified in the following format
+\end_layout
+
+\begin_layout LyX-Code
+nno nsd
+\end_layout
+
+\begin_layout LyX-Code
+x1 y1 z1
+\end_layout
+
+\begin_layout LyX-Code
+x2 y2 z2
+\end_layout
+
+\begin_layout LyX-Code
+x3 y3 z3
+\end_layout
+
+\begin_layout LyX-Code
+...
+\end_layout
+
+\begin_layout Standard
+Mesh connectivity with 
+\end_layout
+
+\begin_layout LyX-Code
+nel ndofs
+\end_layout
+
+\begin_layout LyX-Code
+node_1 node_2 node_3 node_4 ...
+\end_layout
+
+\begin_layout LyX-Code
+node_1 node_2 node_3 node_4 ...
+\end_layout
+
+\begin_layout LyX-Code
+node_1 node_2 node_3 node_4 ...
+\end_layout
+
+\begin_layout LyX-Code
+...
+\end_layout
+
+\begin_layout Standard
+A generic field with 
+\family typewriter
+ndim
+\family default
+ components (i.e., scalar, vector, or tensor) is specified by
+\end_layout
+
+\begin_layout LyX-Code
+num ndim
+\end_layout
+
+\begin_layout LyX-Code
+f1 f2 f3 ..
+\end_layout
+
+\begin_layout LyX-Code
+f1 f2 f3 ..
+\end_layout
+
+\begin_layout LyX-Code
+...
+\end_layout
+
+\begin_layout Standard
+In this last case, the number of rows could refer to either 
+\family typewriter
+nno
+\family default
+ or 
+\family typewriter
+nel
+\family default
+, depending on whether the field is node-based or cell-based.
+\end_layout
+
+\begin_layout Section
+Output File Format
+\end_layout
+
+\begin_layout Standard
+The output format for residuals consists simply of a list of scalars for
+ each element in the discretization.
+ If you specify a 
+\family typewriter
+.vtk
+\family default
+ extension for your output file, this will result in an scalar dataset named
+ epsilon stored using the legacy VTK file format in the Cell Data section
+ of the output file.
+ Note that this output consists of the squared values of the local residuals,
+ so further post-processing will be necessary.
+\end_layout
+
+\begin_layout Standard
+\begin_inset Include \include{gpl-license.lyx}
+preview false
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Bibliography
+\begin_inset LatexCommand bibitem
+label "1"
+key "Akin 2005"
+
+\end_inset
+
+Akin, J.E.
+ (2005), 
+\emph on
+Finite Element Analysis with Error Estimators,
+\emph default
+ Butterworth-Heinemann, Oxford, 447 pp.
+ 
+\end_layout
+
+\begin_layout Bibliography
+\begin_inset LatexCommand bibitem
+label "2"
+key "Encyclopaedia of Cubature Formulas 2005"
+
+\end_inset
+
+Encyclopaedia of Cubature Formulas (1998-2005), Katholieke Universiteit
+ Leuven, Dept.
+ Computerwetenschappen, www.cs.kuleuven.be/~nines/research/ecf/
+\end_layout
+
+\begin_layout Bibliography
+\begin_inset LatexCommand bibitem
+label "3"
+key "Hughes 2000"
+
+\end_inset
+
+Hughes, Thomas J.R.
+ (2000), 
+\emph on
+The Finite Element Method: Linear Static and Dynamic Finite Element Analysis
+\emph default
+, Dover, 672 pp.
+\end_layout
+
+\begin_layout Bibliography
+\begin_inset LatexCommand bibitem
+label "4"
+key "KarniadakisSherwin2005"
+
+\end_inset
+
+Karniadakis, George E.
+ and Spencer J.
+ Sherwin (2005), 
+\emph on
+Spectral/
+\emph default
+hp 
+\emph on
+Element Methods for Computational Fluid Dynamics, Second Edition
+\emph default
+, Numerical Mathematics and Scientific Computation, Oxford, 657 pp.
+\end_layout
+
+\begin_layout Bibliography
+\begin_inset LatexCommand bibitem
+label "5"
+key "Uesu-etal2005"
+
+\end_inset
+
+Uesu, D., L.
+ Bavoil, S.
+ Fleishman, J.
+ Shepherd, and C.
+ Silva (2005), Simplification of Unstructured Tetrahedral Meshes by Point-Sampli
+ng, 
+\emph on
+Proceedings of the 2005 International Workshop on Volume Graphics,
+\emph default
+ 157-165, doi: 10.2312/VG/VG05/157-165.
+\end_layout
+
+\end_body
+\end_document

Added: doc/cigma/manual/gpl-license.lyx
===================================================================
--- doc/cigma/manual/gpl-license.lyx	                        (rev 0)
+++ doc/cigma/manual/gpl-license.lyx	2008-03-25 09:25:12 UTC (rev 11543)
@@ -0,0 +1,660 @@
+#LyX 1.5.4 created this file. For more info see http://www.lyx.org/
+\lyxformat 276
+\begin_document
+\begin_header
+\textclass book
+\language english
+\inputencoding auto
+\font_roman default
+\font_sans default
+\font_typewriter default
+\font_default_family default
+\font_sc false
+\font_osf false
+\font_sf_scale 100
+\font_tt_scale 100
+\graphics default
+\paperfontsize default
+\spacing single
+\papersize default
+\use_geometry false
+\use_amsmath 1
+\use_esint 1
+\cite_engine basic
+\use_bibtopic false
+\paperorientation portrait
+\secnumdepth 3
+\tocdepth 3
+\paragraph_separation indent
+\defskip medskip
+\quotes_language english
+\papercolumns 1
+\papersides 1
+\paperpagestyle default
+\tracking_changes false
+\output_changes false
+\author "" 
+\author "" 
+\end_header
+
+\begin_body
+
+\begin_layout Chapter
+License 
+\end_layout
+
+\begin_layout Standard
+
+\series bold
+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
+\series default
+ 
+\newline
+
+\series medium
+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
+\begin_inset ERT
+status collapsed
+
+\begin_layout Standard
+
+
+\backslash
+begin{itemize}
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+\begin_inset ERT
+status collapsed
+
+\begin_layout Standard
+
+
+\backslash
+item[0.]
+\end_layout
+
+\end_inset
+
+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."
+\newline
+
+\newline
+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
+\begin_inset ERT
+status collapsed
+
+\begin_layout Standard
+
+
+\backslash
+end{itemize}
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Enumerate
+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_deeper
+\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
+
+\end_deeper
+\begin_layout Enumerate
+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_deeper
+\begin_layout Enumerate
+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 Enumerate
+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 Enumerate
+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
+
+\end_deeper
+\begin_layout Enumerate
+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_deeper
+\begin_layout Enumerate
+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 Enumerate
+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 Enumerate
+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
+
+\end_deeper
+\begin_layout Enumerate
+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 Enumerate
+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 Enumerate
+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 Enumerate
+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_deeper
+\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
+
+\end_deeper
+\begin_layout Enumerate
+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 geographic
+al 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 Enumerate
+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_deeper
+\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
+
+\end_deeper
+\begin_layout Enumerate
+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 Section*
+NO WARRANTY 
+\end_layout
+
+\begin_layout Standard
+\begin_inset ERT
+status collapsed
+
+\begin_layout Standard
+
+
+\backslash
+begin{itemize}
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+\begin_inset ERT
+status collapsed
+
+\begin_layout Standard
+
+
+\backslash
+item[11.]
+\end_layout
+
+\end_inset
+
+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
+\begin_inset ERT
+status collapsed
+
+\begin_layout Standard
+
+
+\backslash
+item[12.]
+\end_layout
+
+\end_inset
+
+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 Standard
+\begin_inset ERT
+status collapsed
+
+\begin_layout Standard
+
+
+\backslash
+end{itemize}
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+END OF TERMS AND CONDITIONS 
+\end_layout
+
+\begin_layout Standard
+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.
+ For example:
+\end_layout
+
+\begin_layout Standard
+One line to give the program's name and a brief idea of what it does.
+ Copyright 
+\size footnotesize
+© (
+\size default
+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 © 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.
+ 
+\end_layout
+
+\begin_layout Standard
+(signature of Ty Coon)
+\newline
+1 April 1989 
+\newline
+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