[cig-commits] r12624 - in doc/cigma/manual: . error_analysis examples file_formats installation introduction running

[luis at geodynamics.org]

Author: luis
Date: 2008-08-13 13:21:18 -0700 (Wed, 13 Aug 2008)
New Revision: 12624

Modified:
   doc/cigma/manual/cigma.lyx
   doc/cigma/manual/error_analysis/error_analysis.lyx
   doc/cigma/manual/examples/examples.lyx
   doc/cigma/manual/file_formats/file_formats.lyx
   doc/cigma/manual/installation/installation.lyx
   doc/cigma/manual/introduction/introduction.lyx
   doc/cigma/manual/running/running.lyx
Log:
Synchronize current chapters.


Modified: doc/cigma/manual/cigma.lyx
===================================================================
--- doc/cigma/manual/cigma.lyx	2008-08-13 01:29:38 UTC (rev 12623)
+++ doc/cigma/manual/cigma.lyx	2008-08-13 20:21:18 UTC (rev 12624)
@@ -1,340 +1,465 @@
-#LyX 1.5.6 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})}
-
-\newcommand{\mynote}[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 cigma_cover.pdf
-	display color
-	width 75page%
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\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 1.0.0
-\end_layout
-
-\begin_layout Date
-\begin_inset ERT
-status collapsed
-
-\begin_layout Standard
-
-
-\backslash
-today
-\end_layout
-
-\end_inset
-
-
-\begin_inset LatexCommand tableofcontents
-
-\end_inset
-
-
-\begin_inset FloatList figure
-
-\end_inset
-
-
-\begin_inset ERT
-status collapsed
-
-\begin_layout Standard
-
-
-\backslash
-raggedbottom
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-
-\newpage
-
-\end_layout
-
-\begin_layout Standard
-\begin_inset ERT
-status open
-
-\begin_layout Standard
-
-
-\backslash
-mynote{
-\end_layout
-
-\begin_layout Standard
-
-  TODO: Update version on cover to version 1.0.0
-\end_layout
-
-\begin_layout Standard
-
-}
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-\begin_inset Include \include{introduction/introduction.lyx}
-preview false
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-\begin_inset Include \include{installation/installation.lyx}
-preview false
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-\begin_inset Include \include{error_analysis/error_analysis.lyx}
-preview false
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-\begin_inset Include \include{running/running.lyx}
-preview false
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-\begin_inset Include \include{examples/examples.lyx}
-preview false
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-\start_of_appendix
-\begin_inset ERT
-status collapsed
-
-\begin_layout Standard
-
-%dummy comment inserted to ensure this paragraph is not empty
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-\begin_inset Include \include{file_formats/file_formats.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
+#LyX 1.5.5 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})}
+
+\newcommand{\mynote}[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 cigma_cover.pdf
+	display color
+	width 75page%
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\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 1.0.0
+\end_layout
+
+\begin_layout Date
+\begin_inset ERT
+status collapsed
+
+\begin_layout Standard
+
+
+\backslash
+today
+\end_layout
+
+\end_inset
+
+
+\begin_inset LatexCommand tableofcontents
+
+\end_inset
+
+
+\begin_inset FloatList figure
+
+\end_inset
+
+
+\begin_inset ERT
+status collapsed
+
+\begin_layout Standard
+
+
+\backslash
+raggedbottom
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+
+\newpage
+
+\end_layout
+
+\begin_layout Standard
+\begin_inset ERT
+status open
+
+\begin_layout Standard
+
+
+\backslash
+mynote{
+\end_layout
+
+\begin_layout Standard
+
+  Global TODO Items
+\end_layout
+
+\begin_layout Standard
+
+    * Don't forget to change version on cover to version 1.0.0
+\end_layout
+
+\begin_layout Standard
+
+    * Change the cover image to use a newer comparison
+\end_layout
+
+\begin_layout Standard
+
+    * Add description of basic ExodusII format in file_formats.lyx (delay
+ this to version 1.1)
+\end_layout
+
+\begin_layout Standard
+
+    * grep for Chapter and replace all chapter numbers by relative references
+\end_layout
+
+\begin_layout Standard
+
+    * Fix alignment of tables where appropriate (left/center/right justified)
+\end_layout
+
+\begin_layout Standard
+
+    * Fix alignment of table cells where appropriate (left/center/right
+ justified)
+\end_layout
+
+\begin_layout Standard
+
+}
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+\begin_inset Include \include{introduction/introduction.lyx}
+preview false
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+\begin_inset Include \include{installation/installation.lyx}
+preview false
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+\begin_inset Include \include{error_analysis/error_analysis.lyx}
+preview false
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+\begin_inset Include \include{interpolation/interpolation.lyx}
+preview false
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+\begin_inset Include \include{integration/integration.lyx}
+preview false
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+\begin_inset Include \include{file_formats/file_formats.lyx}
+preview false
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+\begin_inset Include \include{running/running.lyx}
+preview false
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+\begin_inset Include \include{examples/examples.lyx}
+preview false
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+\start_of_appendix
+\begin_inset ERT
+status collapsed
+
+\begin_layout Standard
+
+%dummy comment inserted to ensure this paragraph is not empty
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+\begin_inset Include \include{appendix/appendix.lyx}
+preview false
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+\begin_inset ERT
+status open
+
+\begin_layout Standard
+
+
+\backslash
+mynote{
+\end_layout
+
+\begin_layout Standard
+
+References:
+\end_layout
+
+\begin_layout Standard
+
+\end_layout
+
+\begin_layout Standard
+
+* Hughes, Thomas J.R., The Finite Element Method: Linear Static and Dynamic
+ Finite Element Analysis, Prentice-Hall 1987 (use Dover ref instead)
+\end_layout
+
+\begin_layout Standard
+
+* Zienkiewicz, O.C., Taylor, R.L.
+ The Finite Element Method: The Basis (Vol.
+ 1)
+\end_layout
+
+\begin_layout Standard
+
+* Akin, J.E., Finite Element Analysis with Error Estimators, Elsevier 2005
+ (ISBN 0750667222)
+\end_layout
+
+\begin_layout Standard
+
+* Johnson, Claes - Numerical Solutions of Partial Differential Equations
+ by the Finite Element Method, Cambridge University Press 1987
+\end_layout
+
+\begin_layout Standard
+
+* Carlos Felippa, A Compendium of FEM integration formulas for symbolic
+ work, Engineering Computation, Volume 21, Number 8, 2004, pages 867-890
+\end_layout
+
+\begin_layout Standard
+
+ 
+\end_layout
+
+\begin_layout Standard
+
+}
+\end_layout
+
+\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

Modified: doc/cigma/manual/error_analysis/error_analysis.lyx
===================================================================
--- doc/cigma/manual/error_analysis/error_analysis.lyx	2008-08-13 01:29:38 UTC (rev 12623)
+++ doc/cigma/manual/error_analysis/error_analysis.lyx	2008-08-13 20:21:18 UTC (rev 12624)
@@ -1,474 +1,729 @@
-#LyX 1.5.6 created this file. For more info see http://www.lyx.org/
-\lyxformat 276
-\begin_document
-\begin_header
-\textclass book
-\begin_preamble
-\newcommand{\mynote}[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 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 Standard
-\begin_inset ERT
-status open
-
-\begin_layout Standard
-
-
-\backslash
-mynote{}
-\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 Standard
-The simplest possible quantitative measure of the difference between two
- distinct functions consists of taking the pointwise difference 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.
- However, the fields we want to compare may not be defined at a common set
- of points.
- This simple measure becomes unapplicable.
-\end_layout
-
-\begin_layout Section
-Interpolation Functions
-\end_layout
-
-\begin_layout Standard
-[XXX] Because We can apply a number of interpolation function
-\end_layout
-
-\begin_layout Section
-Distance Measures
-\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 Section
-Integral Approximations
-\end_layout
-
-\begin_layout Standard
-For a general approximation to
-\end_layout
-
-\begin_layout Section
-Global Error Approximation
-\end_layout
-
-\begin_layout Standard
-If we discretize the domain 
-\begin_inset Formula $\Omega$
-\end_inset
-
- into an appropriate set of cells 
-\begin_inset Formula $\Omega_{1},\Omega_{2},\ldots,\Omega_{n_{el}}$
-\end_inset
-
-, we can compute the global error 
-\begin_inset Formula $\varepsilon^{2}$
-\end_inset
-
- as a sum over localized cell contributions, 
-\begin_inset Formula $\varepsilon^{2}=\sum_{e}\varepsilon_{e}^{2}$
-\end_inset
-
-, where each cell residual 
-\begin_inset Formula $\varepsilon_{e}^{2}$
-\end_inset
-
- is given by
-\end_layout
-
-\begin_layout Standard
-\begin_inset Formula \begin{eqnarray*}
-\varepsilon_{e}^{2} & = & \int_{\Omega_{e}}||u(\vec{x})-v(\vec{x})||^{2}d\vec{x}\end{eqnarray*}
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-In general, we won't be able to integrate each cell residual 
-\begin_inset Formula $\varepsilon_{e}^{2}$
-\end_inset
-
- exactly since either of the functions 
-\begin_inset Formula $u$
-\end_inset
-
- and 
-\begin_inset Formula $v$
-\end_inset
-
- may have an incompatible representation relative to the finite element
- space on each domain 
-\begin_inset Formula $\Omega_{e}$
-\end_inset
-
-.
- However, we can still calculate an approximation of each cell residual
- 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 Standard
-To obtain an approximation to the integral of a function 
-\begin_inset Formula $F(\vec{x})$
-\end_inset
-
- over a cell 
-\begin_inset Formula $\Omega_{e}$
-\end_inset
-
-, we simply apply the quadrature rule with weights 
-\begin_inset Formula $w_{e,1},w_{e,2},\ldots,w_{e,n_{Q}}$
-\end_inset
-
- and integration points 
-\begin_inset Formula $\vec{x}_{e,1},\vec{x}_{e,2},\ldots,\vec{x}_{e,n_{Q}}$
-\end_inset
-
- appropriate for the physical element 
-\begin_inset Formula $\Omega_{e}$
-\end_inset
-
-:
-\end_layout
-
-\begin_layout Standard
-\begin_inset Formula \[
-\int_{\Omega_{e}}\ F(\vec{x})\ d\vec{x}=\sum_{q=1}^{n_{Q}}w_{e,q}F(\vec{x}_{e,q})\]
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-Applying this quadrature rule directly over the entire physical domain 
-\begin_inset Formula $\Omega=\cup\Omega_{e}$
-\end_inset
-
- gives us 
-\begin_inset Formula \[
-\int_{\Omega}\ F(\vec{x})\ d\vec{x}=\sum_{e=1}^{n_{el}}\sum_{q=1}^{n_{Q}}w_{e,q}F(\vec{x}_{e,q})\]
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-For efficiency reasons, it is undesirable in finite element applications
- to perform calculations in a global coordinate system.
- To avoid duplication of work, shape function evaluations may be performed
- once on a reference cell 
-\begin_inset Formula $\hat{\Omega}$
-\end_inset
-
- and then transformed back into the corresponding physical cell 
-\begin_inset Formula $\Omega_{e}$
-\end_inset
-
- as needed.
-\end_layout
-
-\begin_layout Standard
-To compute integrals of 
-\begin_inset Formula $F$
-\end_inset
-
- in a reference coordinate system, we need to apply a change of variables:
-\end_layout
-
-\begin_layout Standard
-\begin_inset Formula \[
-\int_{\Omega_{e}}\ F(\vec{x})\ d\vec{x}=\int_{\hat{\Omega}}\ F(\vec{x}_{e}(\vec{\xi}))J_{e}(\vec{\xi})\ d\vec{\xi}\]
-
-\end_inset
-
-where 
-\color none
-the additional factor 
-\begin_inset Formula $J_{e}(\vec{\xi})=\det\left[\frac{d\vec{x}_{e}}{d\vec{\xi}}\right]$
-\end_inset
-
- is the Jacobian determinant of the reference map 
-\begin_inset Formula $\vec{x}_{e}(\vec{\xi}):\hat{\Omega}\to\Omega_{e}$
-\end_inset
-
-.
- This map describes how the physical points 
-\begin_inset Formula $\vec{x}\in\Omega_{e}$
-\end_inset
-
- are transformed from the reference points 
-\begin_inset Formula $\vec{\xi}\in\hat{\Omega}$
-\end_inset
-
-.
- Put another way, the inverse reference map 
-\color inherit
-
-\begin_inset Formula $\vec{\xi}=\vec{x}_{e}^{-1}(\vec{x})$
-\end_inset
-
- tells us how the physical domain 
-\begin_inset Formula $\Omega_{e}$
-\end_inset
-
- maps into the reference cell 
-\begin_inset Formula $\hat{\Omega}$
-\end_inset
-
-.
-\end_layout
-
-\begin_layout Standard
-At this point, we can assume without loss of generality that every physical
- cell 
-\begin_inset Formula $\Omega_{e}$
-\end_inset
-
- can be derived from a single reference cell 
-\begin_inset Formula $\hat{\Omega}$
-\end_inset
-
-, so that our quadrature rule becomes simply a set of weights 
-\begin_inset Formula $w_{1},\ldots,w_{n_{Q}}$
-\end_inset
-
- and points 
-\begin_inset Formula $\vec{\xi}_{1},\ldots,\vec{\xi}_{n_{Q}}$
-\end_inset
-
- over 
-\begin_inset Formula $\hat{\Omega}$
-\end_inset
-
-.
- After changing variables, we end up with the final form of the quadrature
- rule that we can use to integrate the global residual field:
-\end_layout
-
-\begin_layout Standard
-\begin_inset Formula \[
-\int_{\hat{\Omega}}\ F(\vec{x}_{e}(\vec{\xi}))J_{e}(\vec{\xi})\ d\vec{\xi}=\sum_{q=1}^{n_{Q}}w_{q}F(\vec{x}_{e}(\vec{\xi}_{q}))J_{e}(\vec{\xi}_{q})\]
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-If we let 
-\begin_inset Formula $F(\vec{x})=||u(\vec{x})-v(\vec{x})||^{2}$
-\end_inset
-
- in the above expression, we can find the cell residual contribution over
- 
-\begin_inset Formula $\Omega_{e}$
-\end_inset
-
- from
-\end_layout
-
-\begin_layout Standard
-\begin_inset Formula \begin{eqnarray*}
-\varepsilon_{e}^{2} & = & \int_{\Omega_{e}}\ ||u(\vec{x})-v(\vec{x})||^{2}\ d\vec{x}\\
- & = & \int_{\hat{\Omega}}\ ||u(\vec{x}_{e}(\vec{\xi}))-v(\vec{x}_{e}(\vec{\xi}))||^{2}J_{e}(\vec{\xi})\ d\vec{\xi}\\
- & = & \sum_{q=1}^{\mathrm{n_{Q}}}w_{q}||u(\vec{x}_{e}(\vec{\xi}_{q}))-v(\vec{x}_{e}(\vec{\xi}_{q}))||^{2}J_{e}(\vec{\xi}_{q})\end{eqnarray*}
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-The global error 
-\begin_inset Formula $\varepsilon=\sqrt{\sum_{e}\varepsilon_{e}^{2}}$
-\end_inset
-
- is then approximated by the expression
-\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{x}_{e}(\vec{\xi}_{q}))-v(\vec{x}_{e}(\vec{\xi}_{q}))||^{2}J_{e}(\vec{\xi}_{q})}\end{eqnarray*}
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-We can make a number of observations based on our final expression for the
- global error,
-\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
-
-\end_body
-\end_document
+#LyX 1.5.5 created this file. For more info see http://www.lyx.org/
+\lyxformat 276
+\begin_document
+\begin_header
+\textclass book
+\begin_preamble
+\newcommand{\mynote}[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 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 Standard
+\begin_inset ERT
+status open
+
+\begin_layout Standard
+
+
+\backslash
+mynote{
+\end_layout
+
+\begin_layout Standard
+
+Purpose of this chapter is to provide a high-level description of cigma,
+ and just reference later chapters if we need to.
+\end_layout
+
+\begin_layout Standard
+
+\end_layout
+
+\begin_layout Standard
+
+In reference to error analysis, we introduce the topics in the following
+ order
+\end_layout
+
+\begin_layout Standard
+
+  - Quick reference to distance measures, both pointwise and global L2
+\end_layout
+
+\begin_layout Standard
+
+  - Define function as used in cigma
+\end_layout
+
+\begin_layout Standard
+
+  - Define integration rule in this chapter
+\end_layout
+
+\begin_layout Standard
+
+    * in general (1D, 2D, 3D)
+\end_layout
+
+\begin_layout Standard
+
+    * as applied to a discretization (sum over cells)
+\end_layout
+
+\begin_layout Standard
+
+    * generating own integration points (XXX: moved to integration.lyx) --
+ give references
+\end_layout
+
+\begin_layout Standard
+
+      (give warning about using a different reference element -- weights,
+ not just points, need to be adjusted -- perhaps this warning belongs in
+ the next chapter)
+\end_layout
+
+\begin_layout Standard
+
+  - Mention the interpolation functions that are available (XXX: moved to
+ interpolation.lyx)
+\end_layout
+
+\begin_layout Standard
+
+    * global functions (predefined: zero, scalar.one, ...)
+\end_layout
+
+\begin_layout Standard
+
+    * FEM on a given discretization (local interpolations on tet4, hex8,
+ tri3, quad3, ...
+ elements)
+\end_layout
+
+\begin_layout Standard
+
+\end_layout
+
+\begin_layout Standard
+
+Other tasks:
+\end_layout
+
+\begin_layout Standard
+
+  Change name of chapter to something else (no longer necessary)
+\end_layout
+
+\begin_layout Standard
+
+  Give formula in the last section
+\end_layout
+
+\begin_layout Standard
+
+  Move discussion of convergence order from examples.lyx and merge it at
+ the end of this chapter
+\end_layout
+
+\begin_layout Standard
+
+\end_layout
+
+\begin_layout Standard
+
+}
+\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 Standard
+\begin_inset Note Note
+status open
+
+\begin_layout Standard
+Here, discuss motivation and goals.
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+When solving differential equations representing physical systems of interest,
+ we are often able to obtain a family of solutions by applying a variety
+ of solution techniques.
+ Sometimes an analytic method can be found, but most of the time we end
+ up resorting to a numerical algorithm, such as the finite element method.
+ Assessing the quality of these solutions is an important task, so we would
+ like to develop a quantitative measure for indicating just how close our
+ solutions approach the exact answer.
+\end_layout
+
+\begin_layout Standard
+The simplest possible quantitative measure of the difference between two
+ distinct functions consists of taking the pointwise difference 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.
+ However, the functions we want to compare may not be defined at a common
+ set of points.
+ Unless we are able to interpolate the two functions on an intermediate
+ set of points, this simple pointwise measure becomes inapplicable.
+\end_layout
+
+\begin_layout Standard
+Another quantitative measure we can define is the energy norm.
+ 
+\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 defined on a global coordinate system.
+ This gives us a single global estimate 
+\begin_inset Formula $\varepsilon$
+\end_inset
+
+ representing the distance between the two functions 
+\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
+
+.
+ This measure is useful because it is well known that solutions obtained
+ with the finite element method converge only in a weak sense.
+\end_layout
+
+\begin_layout Section
+Integral Approximations
+\end_layout
+
+\begin_layout Standard
+In order to evaluate the integral for our 
+\begin_inset Formula $L_{2}$
+\end_inset
+
+ norm, we will need to specify an integration mesh which partitions the
+ common domain 
+\begin_inset Formula $\Omega$
+\end_inset
+
+.
+\end_layout
+
+\begin_layout Section
+Interpolation Functions
+\end_layout
+
+\begin_layout Standard
+Our two functions 
+\begin_inset Formula $u(\vec{x})$
+\end_inset
+
+ and 
+\begin_inset Formula $v(\vec{x})$
+\end_inset
+
+ are assumed to be defined on a common domain 
+\begin_inset Formula $\Omega$
+\end_inset
+
+.
+ Since the points 
+\begin_inset Formula $\vec{x}\in\Omega$
+\end_inset
+
+ are said to be defined on a global coordinate system.
+ If we define them 
+\end_layout
+
+\begin_layout Standard
+For more details, see Chapter 5.
+\end_layout
+
+\begin_layout Section
+Global Error Measure
+\end_layout
+
+\begin_layout Standard
+If we discretize the domain 
+\begin_inset Formula $\Omega$
+\end_inset
+
+ into an appropriate set of cells 
+\begin_inset Formula $\Omega_{1},\Omega_{2},\ldots,\Omega_{n_{el}}$
+\end_inset
+
+, we can compute the global error 
+\begin_inset Formula $\varepsilon^{2}$
+\end_inset
+
+ as a sum over localized cell contributions, 
+\begin_inset Formula $\varepsilon^{2}=\sum_{e}\varepsilon_{e}^{2}$
+\end_inset
+
+, where each cell residual 
+\begin_inset Formula $\varepsilon_{e}^{2}$
+\end_inset
+
+ is given by
+\end_layout
+
+\begin_layout Standard
+\begin_inset Formula \begin{eqnarray*}
+\varepsilon_{e}^{2} & = & \int_{\Omega_{e}}||u(\vec{x})-v(\vec{x})||^{2}d\vec{x}\end{eqnarray*}
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+In general, we won't be able to integrate each cell residual 
+\begin_inset Formula $\varepsilon_{e}^{2}$
+\end_inset
+
+ exactly since either of the functions 
+\begin_inset Formula $u$
+\end_inset
+
+ and 
+\begin_inset Formula $v$
+\end_inset
+
+ may have an incompatible representation relative to the finite element
+ space on each domain 
+\begin_inset Formula $\Omega_{e}$
+\end_inset
+
+.
+ However, we can still calculate an approximation of each cell residual
+ 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 Standard
+To obtain an approximation to the integral of a function 
+\begin_inset Formula $F(\vec{x})$
+\end_inset
+
+ over a cell 
+\begin_inset Formula $\Omega_{e}$
+\end_inset
+
+, we simply apply the quadrature rule with weights 
+\begin_inset Formula $w_{e,1},w_{e,2},\ldots,w_{e,n_{Q}}$
+\end_inset
+
+ and integration points 
+\begin_inset Formula $\vec{x}_{e,1},\vec{x}_{e,2},\ldots,\vec{x}_{e,n_{Q}}$
+\end_inset
+
+ appropriate for the physical element 
+\begin_inset Formula $\Omega_{e}$
+\end_inset
+
+:
+\end_layout
+
+\begin_layout Standard
+\begin_inset Formula \[
+\int_{\Omega_{e}}\ F(\vec{x})\ d\vec{x}=\sum_{q=1}^{n_{Q}}w_{e,q}F(\vec{x}_{e,q})\]
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+Applying this quadrature rule directly over the entire physical domain 
+\begin_inset Formula $\Omega=\cup\Omega_{e}$
+\end_inset
+
+ gives us 
+\begin_inset Formula \[
+\int_{\Omega}\ F(\vec{x})\ d\vec{x}=\sum_{e=1}^{n_{el}}\sum_{q=1}^{n_{Q}}w_{e,q}F(\vec{x}_{e,q})\]
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+For efficiency reasons, it is undesirable in finite element applications
+ to perform calculations in a global coordinate system.
+ To avoid duplication of work, shape function evaluations may be performed
+ once on a reference cell 
+\begin_inset Formula $\hat{\Omega}$
+\end_inset
+
+ and then transformed back into the corresponding physical cell 
+\begin_inset Formula $\Omega_{e}$
+\end_inset
+
+ as needed.
+\end_layout
+
+\begin_layout Standard
+To compute integrals of 
+\begin_inset Formula $F$
+\end_inset
+
+ in a reference coordinate system, we need to apply a change of variables:
+\end_layout
+
+\begin_layout Standard
+\begin_inset Formula \[
+\int_{\Omega_{e}}\ F(\vec{x})\ d\vec{x}=\int_{\hat{\Omega}}\ F(\vec{x}_{e}(\vec{\xi}))J_{e}(\vec{\xi})\ d\vec{\xi}\]
+
+\end_inset
+
+where 
+\color none
+the additional factor 
+\begin_inset Formula $J_{e}(\vec{\xi})=\det\left[\frac{d\vec{x}_{e}}{d\vec{\xi}}\right]$
+\end_inset
+
+ is the Jacobian determinant of the reference map 
+\begin_inset Formula $\vec{x}_{e}(\vec{\xi}):\hat{\Omega}\to\Omega_{e}$
+\end_inset
+
+.
+ This map describes how the physical points 
+\begin_inset Formula $\vec{x}\in\Omega_{e}$
+\end_inset
+
+ are transformed from the reference points 
+\begin_inset Formula $\vec{\xi}\in\hat{\Omega}$
+\end_inset
+
+.
+ Put another way, the inverse reference map 
+\color inherit
+
+\begin_inset Formula $\vec{\xi}=\vec{x}_{e}^{-1}(\vec{x})$
+\end_inset
+
+ tells us how the physical domain 
+\begin_inset Formula $\Omega_{e}$
+\end_inset
+
+ maps into the reference cell 
+\begin_inset Formula $\hat{\Omega}$
+\end_inset
+
+.
+\end_layout
+
+\begin_layout Standard
+At this point, we can assume without loss of generality that every physical
+ cell 
+\begin_inset Formula $\Omega_{e}$
+\end_inset
+
+ can be derived from a single reference cell 
+\begin_inset Formula $\hat{\Omega}$
+\end_inset
+
+, so that our quadrature rule becomes simply a set of weights 
+\begin_inset Formula $w_{1},\ldots,w_{n_{Q}}$
+\end_inset
+
+ and points 
+\begin_inset Formula $\vec{\xi}_{1},\ldots,\vec{\xi}_{n_{Q}}$
+\end_inset
+
+ over 
+\begin_inset Formula $\hat{\Omega}$
+\end_inset
+
+.
+ After changing variables, we end up with the final form of the quadrature
+ rule that we can use to integrate the global residual field:
+\end_layout
+
+\begin_layout Standard
+\begin_inset Formula \[
+\int_{\hat{\Omega}}\ F(\vec{x}_{e}(\vec{\xi}))J_{e}(\vec{\xi})\ d\vec{\xi}=\sum_{q=1}^{n_{Q}}w_{q}F(\vec{x}_{e}(\vec{\xi}_{q}))J_{e}(\vec{\xi}_{q})\]
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+If we let 
+\begin_inset Formula $F(\vec{x})=||u(\vec{x})-v(\vec{x})||^{2}$
+\end_inset
+
+ in the above expression, we can find the cell residual contribution over
+ 
+\begin_inset Formula $\Omega_{e}$
+\end_inset
+
+ from
+\end_layout
+
+\begin_layout Standard
+\begin_inset Formula \begin{eqnarray*}
+\varepsilon_{e}^{2} & = & \int_{\Omega_{e}}\ ||u(\vec{x})-v(\vec{x})||^{2}\ d\vec{x}\\
+ & = & \int_{\hat{\Omega}}\ ||u(\vec{x}_{e}(\vec{\xi}))-v(\vec{x}_{e}(\vec{\xi}))||^{2}J_{e}(\vec{\xi})\ d\vec{\xi}\\
+ & = & \sum_{q=1}^{\mathrm{n_{Q}}}w_{q}||u(\vec{x}_{e}(\vec{\xi}_{q}))-v(\vec{x}_{e}(\vec{\xi}_{q}))||^{2}J_{e}(\vec{\xi}_{q})\end{eqnarray*}
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+The global error 
+\begin_inset Formula $\varepsilon=\sqrt{\sum_{e}\varepsilon_{e}^{2}}$
+\end_inset
+
+ is then approximated by the expression
+\end_layout
+
+\begin_layout Standard
+\begin_inset Box Boxed
+position "t"
+hor_pos "c"
+has_inner_box 1
+inner_pos "t"
+use_parbox 0
+width "100text%"
+special "none"
+height "1in"
+height_special "totalheight"
+status open
+
+\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{x}_{e}(\vec{\xi}_{q}))-v(\vec{x}_{e}(\vec{\xi}_{q}))||^{2}J_{e}(\vec{\xi}_{q})}\end{eqnarray*}
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\newline
+
+\end_layout
+
+\begin_layout Standard
+We can make a number of observations based on our final expression for the
+ global error.
+\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 Section
+Convergence
+\end_layout
+
+\begin_layout Standard
+\begin_inset Note Note
+status open
+
+\begin_layout Standard
+TODO: Move discussion of convergence from old running.lyx into this section.
+\end_layout
+
+\begin_layout Standard
+Standard error estimate (Hughes, pg 190; Johnson, pg 97)
+\end_layout
+
+\begin_layout Standard
+Give formula for 
+\begin_inset Formula $\alpha$
+\end_inset
+
+ for when we know the exact solution (only need two levels), and we are
+ testing our numerical code.
+\end_layout
+
+\begin_layout Standard
+Give formula for 
+\begin_inset Formula $\alpha$
+\end_inset
+
+ for when we have three levels (same formula), and we are testing our code
+ for convergence.
+\end_layout
+
+\begin_layout Standard
+Talk about least squares fit for when we have more than three levels.
+ (mention scipy script, and reproduce it here, since it's short)
+\end_layout
+
+\begin_layout Standard
+SciPy script for optimizing least squares fit into the formula y = a*x^b
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+For elliptic problems, we can prove a formula
+\end_layout
+
+\begin_layout Standard
+Even if the exact solution 
+\begin_inset Formula $u(\vec{x})$
+\end_inset
+
+ is not known, we may calculate a convergence rate.
+ For a given family of solutions 
+\begin_inset Formula $u_{h}(\vec{x})$
+\end_inset
+
+, we may
+\end_layout
+
+\begin_layout Section
+Uses in Benchmarking
+\end_layout
+
+\begin_layout Standard
+\begin_inset Note Note
+status collapsed
+
+\begin_layout Standard
+Here we define what we mean by Benchmark, and how we can use.
+\end_layout
+
+\begin_layout Standard
+Give URLs for benchmark repositories on CIG svn tree.
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+If 
+\end_layout
+
+\end_body
+\end_document

Modified: doc/cigma/manual/examples/examples.lyx
===================================================================
--- doc/cigma/manual/examples/examples.lyx	2008-08-13 01:29:38 UTC (rev 12623)
+++ doc/cigma/manual/examples/examples.lyx	2008-08-13 20:21:18 UTC (rev 12624)
@@ -1,234 +1,399 @@
-#LyX 1.5.6 created this file. For more info see http://www.lyx.org/
-\lyxformat 276
-\begin_document
-\begin_header
-\textclass book
-\begin_preamble
-\newcommand{\mynote}[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 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 Standard
-\begin_inset ERT
-status open
-
-\begin_layout Standard
-
-
-\backslash
-mynote{}
-\end_layout
-
-\end_inset
-
-
-\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.
- (XXX: Anything else from Pylith manual or source?)
-\end_layout
-
-\begin_layout Standard
-\begin_inset Float figure
-wide false
-sideways false
-status collapsed
-
-\begin_layout Standard
-\begin_inset Graphics
-	filename ../../figures/strike-slip-fault.png
-	width 5cm
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-\begin_inset Caption
-
-\begin_layout Standard
-Geometry of Strike-Slip Benchmark
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\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 Standard
-XXX: list of examples to discuss here
-\end_layout
-
-\begin_layout Standard
-Viscoelastic strikeslip example (tet vs.
- hex elts) -- pylith-tet / pylith-hex
-\end_layout
-
-\begin_layout Standard
-Cylinder extension for maxwell material (newtonian) -- pylith / geofest
- / analytic
-\end_layout
-
-\begin_layout Standard
-Cylinder extension for maxwell material (non-newtonian) -- pylith / geofest
- / analytic
-\end_layout
-
-\begin_layout Standard
-Cylinder gravitation -- pylith / geofest / analytic
-\end_layout
-
-\begin_layout Standard
-Laplace example (linear, quadratic elements) -- deal.II / libmesh / analytic
-\end_layout
-
-\begin_layout Standard
-Citcom example (structured datasets) -- citcom (3d) / analytic
-\end_layout
-
-\begin_layout Standard
-Gale example (structured datasets) -- gale (2d) / analytic
-\end_layout
-
-\begin_layout Standard
-MADDs example -- 
-\end_layout
-
-\begin_layout Section
-Visualization
-\end_layout
-
-\begin_layout Standard
-The residual field obtained in the 
-\end_layout
-
-\end_body
-\end_document
+#LyX 1.5.5 created this file. For more info see http://www.lyx.org/
+\lyxformat 276
+\begin_document
+\begin_header
+\textclass book
+\begin_preamble
+\newcommand{\mynote}[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 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 Standard
+\begin_inset ERT
+status open
+
+\begin_layout Standard
+
+
+\backslash
+mynote{
+\end_layout
+
+\begin_layout Standard
+
+Here are the examples discussed in this section and the intended motivation
+ for introducing them
+\end_layout
+
+\begin_layout Standard
+
+  * Strikeslip Benchmark (without gravity)
+\end_layout
+
+\begin_layout Standard
+
+    - PyLith vs PyLith (hex8, tet4 elts...higher order available?)
+\end_layout
+
+\begin_layout Standard
+
+    - Demonstrate convergence order using sequence of meshes -- generated
+ using cubit
+\end_layout
+
+\begin_layout Standard
+
+    - Analytic (okada) vs Pylith -- initial timestep
+\end_layout
+
+\begin_layout Standard
+
+    - Variables compared: displacement, velocity
+\end_layout
+
+\begin_layout Standard
+
+    - Demonstrate vtk visualization techniques - cell-to-point filter, then
+ isosurface
+\end_layout
+
+\begin_layout Standard
+
+    - Same case but with gravity?
+\end_layout
+
+\begin_layout Standard
+
+    - http://www.geodynamics.org/cig/workinggroups/short/workarea/benchmarks/
+\end_layout
+
+\begin_layout Standard
+
+  * Poisson solution on unit cube
+\end_layout
+
+\begin_layout Standard
+
+    - Analytic vs deal.II vs libMesh
+\end_layout
+
+\begin_layout Standard
+
+    - Demonstrate use of quadratic elements vs.
+ linear
+\end_layout
+
+\begin_layout Standard
+
+    - tet{4,10} convergence, hex{8,20,27} convergence -- where possible
+\end_layout
+
+\begin_layout Standard
+
+    - take a planar slice and plot differences there
+\end_layout
+
+\begin_layout Standard
+
+    - inter-element solution comparisons (tet4 vs hex8, tet10 vs.
+ hex8)
+\end_layout
+
+\begin_layout Standard
+
+  * Cylinder viscoelastic extension
+\end_layout
+
+\begin_layout Standard
+
+    - Analytic (cylinder_extension.*.*) vs.
+ GeoFEST(tet4) vs.
+ PyLith (tet4,hex8)
+\end_layout
+
+\begin_layout Standard
+
+    - Demonstrate use of predefined function
+\end_layout
+
+\begin_layout Standard
+
+    - Maxwell material (cylinder_extension.maxwell.{displacement,velocity,stress})
+\end_layout
+
+\begin_layout Standard
+
+    - Non-newtonian material (cylinder_extension.non_newtonian.{displacement,veloc
+ity,stress})
+\end_layout
+
+\begin_layout Standard
+
+  * Cylinder viscoelastic relaxation
+\end_layout
+
+\begin_layout Standard
+
+    - Analytic (cylinder_relaxation.*.*) vs.
+ GeoFEST (tet4) vs.
+ PyLith (tet4,hex8)
+\end_layout
+
+\begin_layout Standard
+
+    - Demonstrate use of extract/eval -- on integration mesh
+\end_layout
+
+\begin_layout Standard
+
+    - Effect of varying the integration order
+\end_layout
+
+\begin_layout Standard
+
+    - Maxwell material (cylinder_relaxation.maxwell.{displacement,velocity,stress}
+)
+\end_layout
+
+\begin_layout Standard
+
+    - Non-newtonian material (cylinder_relaxation.non_newtonian.{displacement,velo
+city,stress})
+\end_layout
+
+\begin_layout Standard
+
+  * Gale Circular Inclusion benchmark
+\end_layout
+
+\begin_layout Standard
+
+    - Analytic (circular_inclusion.pressure) vs.
+ Gale
+\end_layout
+
+\begin_layout Standard
+
+    - Demonstrate use of the Parallel VTK Format (PVTS structured grid)
+\end_layout
+
+\begin_layout Standard
+
+    - limitations of FEM description (discontinuity near boundary of circle)
+\end_layout
+
+\begin_layout Standard
+
+    - need discontinuous elements, perhaps?
+\end_layout
+
+\begin_layout Standard
+
+  * Mantle Convection -- Cartesian
+\end_layout
+
+\begin_layout Standard
+
+    - CitcomCU convergence order
+\end_layout
+
+\begin_layout Standard
+
+    - Demonstrate use of Parallel VTK Format (PVTR files)
+\end_layout
+
+\begin_layout Standard
+
+    - http://www.geodynamics.org/cig/workinggroups/mc/workarea/benchmark/
+\end_layout
+
+\begin_layout Standard
+
+  * Mantle Convection -- Spherical
+\end_layout
+
+\begin_layout Standard
+
+    - CitcomS vs HC
+\end_layout
+
+\begin_layout Standard
+
+    - Demonstrate use of global basis functions (spherical harmonics)
+\end_layout
+
+\begin_layout Standard
+
+  * MADDS
+\end_layout
+
+\begin_layout Standard
+
+    - Run SpecRidge example
+\end_layout
+
+\begin_layout Standard
+
+    - Compare spectral solution against higher order elements
+\end_layout
+
+\begin_layout Standard
+
+    - http://www.geodynamics.org/cig/workinggroups/magma/workarea/benchmark/
+\end_layout
+
+\begin_layout Standard
+
+}
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+\begin_inset Note Note
+status open
+
+\begin_layout Standard
+The core concept for this chapter is to show-case specific use cases for
+ cigma.
+\end_layout
+
+\begin_layout Standard
+All the necessary data should be available in the 
+\family typewriter
+examples/
+\family default
+ directory.
+\newline
+
+\end_layout
+
+\begin_layout Standard
+The following points should be emphasized for each example:
+\end_layout
+
+\begin_layout Enumerate
+Problem definition and method used to obtain the solutions.
+\end_layout
+
+\begin_layout Enumerate
+Pre-processing step for preparing the data
+\end_layout
+
+\begin_layout Enumerate
+Cigma command line usage
+\end_layout
+
+\begin_layout Enumerate
+Post-processing step for visualizing the resulting residuals, or for calculating
+ the required convergence rate.
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Chapter
+Examples
+\end_layout
+
+\begin_layout Section
+Strikeslip Benchmark
+\end_layout
+
+\begin_layout Standard
+This benchmark problem computes the viscoelastic (Maxwell) relaxation of
+ stresses from a single, finite, strike-slip earthquake in 3D without gravity.
+ Dirichlet boundary conditions equal to the analytical elastic solution
+ are imposed on the sides of a cube with sides of length 24 km.
+ Anti-plane strain boundary conditions are imposed at 
+\begin_inset Formula $y=0$
+\end_inset
+
+, so the solution is equivalent to that for a domain with a 48 km length
+ in the 
+\begin_inset Formula $y$
+\end_inset
+
+ direction.
+ In the initial time-step, we can use the analytical solution both to apply
+ the boundary conditions, and to compare against the numerically-computed
+ elastic solution.
+\end_layout
+
+\begin_layout Subsection
+Problem Description
+\end_layout
+
+\begin_layout Standard
+Figure 8.X
+\end_layout
+
+\begin_layout Section
+Cylinder Extension
+\end_layout
+
+\begin_layout Section
+Cylinder Relaxation
+\end_layout
+
+\begin_layout Section
+Circular Inclusion
+\end_layout
+
+\begin_layout Section
+Mantle Convection on Rectangular Box
+\end_layout
+
+\begin_layout Standard
+Given the benchmark files in /examples/mc1/
+\end_layout
+
+\begin_layout Section
+Mantle Convection on a Sphere
+\end_layout
+
+\begin_layout Standard
+Here we use the output from CitcomS and the spherical.
+\end_layout
+
+\end_body
+\end_document

Modified: doc/cigma/manual/file_formats/file_formats.lyx
===================================================================
--- doc/cigma/manual/file_formats/file_formats.lyx	2008-08-13 01:29:38 UTC (rev 12623)
+++ doc/cigma/manual/file_formats/file_formats.lyx	2008-08-13 20:21:18 UTC (rev 12624)
@@ -1,403 +1,1098 @@
-#LyX 1.5.6 created this file. For more info see http://www.lyx.org/
-\lyxformat 276
-\begin_document
-\begin_header
-\textclass book
-\begin_preamble
-\newcommand{\mynote}[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 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 Standard
-\begin_inset ERT
-status open
-
-\begin_layout Standard
-
-
-\backslash
-mynote{}
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Chapter
-File Formats
-\end_layout
-
-\begin_layout Standard
-To differentiate between these input and output file formats, you will need
- to provide an appropriate file extension.
- Currently recognized file extensions include 
-\family typewriter
-*.h5
-\family default
- for HDF5 files, 
-\family typewriter
-*.vtk
-\family default
- for legacy VTK files, and 
-\family typewriter
-*.dat
-\family default
- for simple text files.
-\end_layout
-
-\begin_layout Section
-Input File Format
-\end_layout
-
-\begin_layout Standard
-There are five 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 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
-
-\end_body
-\end_document
+#LyX 1.5.5 created this file. For more info see http://www.lyx.org/
+\lyxformat 276
+\begin_document
+\begin_header
+\textclass book
+\begin_preamble
+\newcommand{\mynote}[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 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 Standard
+\begin_inset ERT
+status collapsed
+
+\begin_layout Standard
+
+
+\backslash
+mynote{
+\end_layout
+
+\begin_layout Standard
+
+TODO: Rename file_formats.lyx to formats.lyx
+\end_layout
+
+\begin_layout Standard
+
+\end_layout
+
+\begin_layout Standard
+
+Define the dimensions for every object in the file (summarize only the tables
+ in the appendix)
+\end_layout
+
+\begin_layout Standard
+
+  Mesh Coordinates
+\end_layout
+
+\begin_layout Standard
+
+  Mesh Connectivity (list of Element Blocks)
+\end_layout
+
+\begin_layout Standard
+
+  Field Variables (Global, Nodal, Element)
+\end_layout
+
+\begin_layout Standard
+
+  Element Tabulation (Shape function, Shape Function Derivatives)
+\end_layout
+
+\begin_layout Standard
+
+  Integration Rule (Weights and Local Points)
+\end_layout
+
+\begin_layout Standard
+
+  Global Integration Points
+\end_layout
+
+\begin_layout Standard
+
+\end_layout
+
+\begin_layout Standard
+
+\end_layout
+
+\begin_layout Standard
+
+Explain structure of each file format:
+\end_layout
+
+\begin_layout Standard
+
+\end_layout
+
+\begin_layout Standard
+
+ Text Format
+\end_layout
+
+\begin_layout Standard
+
+\end_layout
+
+\begin_layout Standard
+
+    All arrays specified explicitly in several text files containing a list
+ of floating point numbers.
+\end_layout
+
+\begin_layout Standard
+
+    The first two numbers indicate the dimensions of the array, followed
+ by a list of floats
+\end_layout
+
+\begin_layout Standard
+
+\end_layout
+
+\begin_layout Standard
+
+      --integration-mesh-coordinates=imesh_coords.dat
+\end_layout
+
+\begin_layout Standard
+
+      --integration-mesh-connectivity=imesh_connect.dat
+\end_layout
+
+\begin_layout Standard
+
+\end_layout
+
+\begin_layout Standard
+
+      --integration-rule-points=tet4_order10_points.dat
+\end_layout
+
+\begin_layout Standard
+
+      --integration-rule-weights=tet4_order10_weights.dat
+\end_layout
+
+\begin_layout Standard
+
+\end_layout
+
+\begin_layout Standard
+
+      --first-mesh-coordinates=first_coords.dat
+\end_layout
+
+\begin_layout Standard
+
+      --first-mesh-connectivity=first_connect.dat
+\end_layout
+
+\begin_layout Standard
+
+\end_layout
+
+\begin_layout Standard
+
+      --second-mesh-coordinates=first_coords.dat
+\end_layout
+
+\begin_layout Standard
+
+      --second-mesh-connectivity=first_connect.dat
+\end_layout
+
+\begin_layout Standard
+
+\end_layout
+
+\begin_layout Standard
+
+      --first-dofs=first_var_stepN.dat
+\end_layout
+
+\begin_layout Standard
+
+      --second-dofs=second_var_stepN.dat
+\end_layout
+
+\begin_layout Standard
+
+\end_layout
+
+\begin_layout Standard
+
+      --integration-rule=tet4_order10.dat      <-- (weights in first column)
+\end_layout
+
+\begin_layout Standard
+
+\end_layout
+
+\begin_layout Standard
+
+  Simple Arrays (HDF5)
+\end_layout
+
+\begin_layout Standard
+
+\end_layout
+
+\begin_layout Standard
+
+    Structure of Model Definition
+\end_layout
+
+\begin_layout Standard
+
+      root group at /model
+\end_layout
+
+\begin_layout Standard
+
+      mesh data at /model/mesh
+\end_layout
+
+\begin_layout Standard
+
+        node coordinates as specified on global coordinate system at /model/mesh
+/coordinates
+\end_layout
+
+\begin_layout Standard
+
+        list of element blocks at /model/mesh/connectivity
+\end_layout
+
+\begin_layout Standard
+
+        note that each element block is tagged by element type in the FE
+ attribute
+\end_layout
+
+\begin_layout Standard
+
+      degrees-of-freedom data
+\end_layout
+
+\begin_layout Standard
+
+        organized by variable at /model/vars/var, or even just /model/var
+\end_layout
+
+\begin_layout Standard
+
+        list of steps: /model/var/step{0,1,...,N}
+\end_layout
+
+\begin_layout Standard
+
+\end_layout
+
+\begin_layout Standard
+
+    Structure of file defining an Integration Rule
+\end_layout
+
+\begin_layout Standard
+
+      root group is / by default, but may be specified directly (eg, as
+ /rule)
+\end_layout
+
+\begin_layout Standard
+
+      root group is tagged with FE string indicating the source element
+ (tet4, ...)
+\end_layout
+
+\begin_layout Standard
+
+      integration points contained at /rule/points
+\end_layout
+
+\begin_layout Standard
+
+      integration points contained at /rule/weights
+\end_layout
+
+\begin_layout Standard
+
+    Structure of file with Residuals
+\end_layout
+
+\begin_layout Standard
+
+      root group is / by default, but it must exist if specified
+\end_layout
+
+\begin_layout Standard
+
+      
+\end_layout
+
+\begin_layout Standard
+
+  VTK
+\end_layout
+
+\begin_layout Standard
+
+      Basic structure:
+\end_layout
+
+\begin_layout Standard
+
+        VTK Grid
+\end_layout
+
+\begin_layout Standard
+
+          VTK Dataset consists of the mesh information (node coordinates
+ and associated connectivity relations)
+\end_layout
+
+\begin_layout Standard
+
+          VTK Data Arrays come in two types (Point Data and Cell Data)
+\end_layout
+
+\begin_layout Standard
+
+            VTK Point Data - scalars, vectors, tensors as defined on the
+ nodes
+\end_layout
+
+\begin_layout Standard
+
+            VTK Cell Data - scalars, vectors, tensors as defined on each
+ element
+\end_layout
+
+\begin_layout Standard
+
+      Structure of different types
+\end_layout
+
+\begin_layout Standard
+
+        Unstructured Grid
+\end_layout
+
+\begin_layout Standard
+
+           mesh points: given explicitly in a simple array
+\end_layout
+
+\begin_layout Standard
+
+           mesh connectivity: given explicitly in a list of simple arrays
+\end_layout
+
+\begin_layout Standard
+
+           element types: Line, Quad, Tetra, Hexahedron, Quadratic Triangle,
+ Quadratic Quad, Quadratic Tetra, Quadratic Hexahedron
+\end_layout
+
+\begin_layout Standard
+
+        Structured Grid
+\end_layout
+
+\begin_layout Standard
+
+           mesh points: given explicitly in a simple array
+\end_layout
+
+\begin_layout Standard
+
+           mesh connectivity: derived from dimensions (nx, ny, nz)
+\end_layout
+
+\begin_layout Standard
+
+           element types: Quad, Pixel, Hex, Voxel
+\end_layout
+
+\begin_layout Standard
+
+        Rectilinear Grid
+\end_layout
+
+\begin_layout Standard
+
+           mesh dimensions: (nx, ny, nz)
+\end_layout
+
+\begin_layout Standard
+
+           mesh points: derived from 'double xcoords[nx], ycoords[ny], zcoords[n
+z]' arrays
+\end_layout
+
+\begin_layout Standard
+
+           element types: Pixel, Voxel
+\end_layout
+
+\begin_layout Standard
+
+\end_layout
+
+\begin_layout Standard
+
+  UCD
+\end_layout
+
+\begin_layout Standard
+
+    Format described in (LINK-TO-DOCUMENT).
+\end_layout
+
+\begin_layout Standard
+
+    Using VTK API (vtkAVSucdReader) to read (*.inp) files
+\end_layout
+
+\begin_layout Standard
+
+    Just extracts the data into an Unstructured Grid
+\end_layout
+
+\begin_layout Standard
+
+\end_layout
+
+\begin_layout Standard
+
+  ExodusII
+\end_layout
+
+\begin_layout Standard
+
+    This type of mesh can be generated by other programs, such as CUBIT
+\end_layout
+
+\begin_layout Standard
+
+    Currently only used to specify an integration mesh, but it is capable
+ of storing degree-of-freedom data as well.
+\end_layout
+
+\begin_layout Standard
+
+    Utility script for converting *.exo into the appropriate *.h5 file (need
+ PyTables, Numpy, Scientific.IO.NetCDF)
+\end_layout
+
+\begin_layout Standard
+
+\end_layout
+
+\begin_layout Standard
+
+\end_layout
+
+\begin_layout Standard
+
+--------------
+\end_layout
+
+\begin_layout Standard
+
+From running.lyx:
+\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.
+ The Hierarchical Data Format (HDF) is designed for storing, retrieving,
+ analyzing, visualizing, and converting scientific data.
+ It uses a hierarchical structure that provides users a host of options
+ for organizing how their data is stored in HDF5 files.
+ 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
+
+Another popular format for providing mesh and field inputs.You can easily
+ examine the structure of an input file by using the cigma list command,
+ which will simply reveal the names and dimensions of all datasets inside
+ the specified file.
+\end_layout
+
+\begin_layout Standard
+
+Inputs can be either HDF5 or VTK.
+ Specifying the complete path to a dataset consists of the special form
+ filepath:dataset, a colon-delimited pair of file path and dataset path.
+\end_layout
+
+\begin_layout Standard
+
+Mesh inputs are currently only unstructured grids.
+\end_layout
+
+\begin_layout Standard
+
+Only exception are the residuals, which are written in legacy VTK format
+ as scalar cell data over an unstructured grid.
+\end_layout
+
+\begin_layout Standard
+
+Because Cigma relies on the ability of the user to specify dataset paths,
+ we have provided a command called list for viewing the structure of an
+ input file.
+ Its usage is very simple.
+ 
+\end_layout
+
+\begin_layout Standard
+
+\end_layout
+
+\begin_layout Standard
+
+}
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+\begin_inset Note Note
+status collapsed
+
+\begin_layout Standard
+This chapter may be summarized by simply stating that most input data can
+ be specified as a two-dimensional array.
+ The meaning of this array, of course, is dependent on context.
+ That is the main concept that we have to get accross in this chapter.
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Chapter
+Data and File Formats
+\end_layout
+
+\begin_layout Standard
+As we've seen in the previous chapters, there are a number of data objects
+ involved in making any particular comparison.
+ Here, we discuss the variety of formats available, as well as the layout
+ within the corresponding data file.
+\end_layout
+
+\begin_layout Section
+Data Formats
+\end_layout
+
+\begin_layout Standard
+The basic data structure is a two-dimensional array of values, stored in
+ 
+\newline
+
+\end_layout
+
+\begin_layout Standard
+\begin_inset Tabular
+<lyxtabular version="3" rows="5" columns="2">
+<features>
+<column alignment="center" valignment="top" leftline="true" width="0">
+<column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+Array shape
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+\begin_inset Formula $(m,n)$
+\end_inset
+
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+Array Data
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+\begin_inset Formula $a_{11},a_{12},\ldots,a_{1n}$
+\end_inset
+
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+\begin_inset Formula $a_{21},a_{22},\ldots,a_{2n}$
+\end_inset
+
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+\begin_inset Formula $\cdots$
+\end_inset
+
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+\begin_inset Formula $a_{m1},a_{m2},\ldots,a_{mn}$
+\end_inset
+
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Subsection
+Mesh
+\end_layout
+
+\begin_layout Subsection
+Field Variables
+\end_layout
+
+\begin_layout Subsection
+Integration Rule
+\end_layout
+
+\begin_layout Subsection
+Integration Points and Values
+\end_layout
+
+\begin_layout Subsection
+Spherical Harmonics
+\end_layout
+
+\begin_layout Section
+File Formats
+\end_layout
+
+\begin_layout Section
+Input Files
+\end_layout
+
+\begin_layout Standard
+\begin_inset Note Note
+status collapsed
+
+\begin_layout Standard
+There are five 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
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+Now that we have examined what kinds of objects we will be accessing, let's
+ discuss the actual layout.
+\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 may 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.
+ 
+\begin_inset Note Note
+status open
+
+\begin_layout Standard
+Mention these assumptions in the corresponding section in running.lyx
+\end_layout
+
+\end_inset
+
+
+\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
+\end_layout
+
+\begin_layout Standard
+Depending on the particular operation you perform, there are three different
+ kinds of output files.
+ 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
+
+\end_body
+\end_document

Modified: doc/cigma/manual/installation/installation.lyx
===================================================================
--- doc/cigma/manual/installation/installation.lyx	2008-08-13 01:29:38 UTC (rev 12623)
+++ doc/cigma/manual/installation/installation.lyx	2008-08-13 20:21:18 UTC (rev 12624)
@@ -1,455 +1,605 @@
-#LyX 1.5.6 created this file. For more info see http://www.lyx.org/
-\lyxformat 276
-\begin_document
-\begin_header
-\textclass book
-\begin_preamble
-\newcommand{\mynote}[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 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 Standard
-\begin_inset ERT
-status open
-
-\begin_layout Standard
-
-
-\backslash
-mynote{}
-\end_layout
-
-\end_inset
-
-
-\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 Boost, 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-1.0.0.tar.gz
-\end_layout
-
-\begin_layout LyX-Code
-$ cd cigma-1.0.0
-\end_layout
-
-\begin_layout LyX-Code
-$ ./configure --with-boost=$BOOST_PREFIX
-\end_layout
-
-\begin_layout LyX-Code
-              --with-hdf5=$HDF5_PREFIX 
-\end_layout
-
-\begin_layout LyX-Code
-              --with-vtk=$VTK_PREFIX 
-\end_layout
-
-\begin_layout LyX-Code
-$ make
-\end_layout
-
-\begin_layout LyX-Code
-$ make install
-\end_layout
-
-\begin_layout Standard
-Both HDF5 and VTK prefixes are required if you have installed these libraries
- in a custom location.
-\end_layout
-
-\begin_layout Subsection
-Boost
-\end_layout
-
-\begin_layout Standard
-The Boost C++ libraries are used in Cigma for parsing command-line options,
- and ensuring cross-platform access to the filesystem.
-\end_layout
-
-\begin_layout LyX-Code
-$ tar xvfz boost_1_35_0.tar.gz
-\end_layout
-
-\begin_layout LyX-Code
-$ cd boost_1_35_0
-\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 Standard
-Without a custom installation prefix, Boost will target your 
-\family typewriter
-/usr/local
-\family default
- directory.
-\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
- (1.6.7, for example) and issue the following commands
-\end_layout
-
-\begin_layout LyX-Code
-$ tar xvfz hdf5-1.6.7.tar.gz
-\end_layout
-
-\begin_layout LyX-Code
-$ cd hdf5-1.6.7
-\end_layout
-
-\begin_layout LyX-Code
-$ ./configure --prefix=$HOME/opt/hdf5/1.6.7
-\end_layout
-
-\begin_layout LyX-Code
-$ make
-\end_layout
-
-\begin_layout LyX-Code
-$ make install
-\end_layout
-
-\begin_layout Standard
-Without the custom prefix, this installation procedure will target your
- 
-\family typewriter
-/usr
-\family default
- directory.
-\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 Standard
-You can set the installation prefix during the 
-\family typewriter
-ccmake
-\family default
- step above, which defaults to your 
-\family typewriter
-/usr/local
-\family default
- directory.
-\end_layout
-
-\begin_layout Section
-Additional Software
-\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
-\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 group hierarchy, 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
-
-\end_body
-\end_document
+#LyX 1.5.5 created this file. For more info see http://www.lyx.org/
+\lyxformat 276
+\begin_document
+\begin_header
+\textclass book
+\begin_preamble
+\newcommand{\mynote}[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 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 Standard
+\begin_inset ERT
+status open
+
+\begin_layout Standard
+
+
+\backslash
+mynote{
+\end_layout
+
+\begin_layout Standard
+
+Things to mention:
+\end_layout
+
+\begin_layout Standard
+
+  Mention installation from binary (test the binaries from buildbot and
+ make sure they install properly)
+\end_layout
+
+\begin_layout Standard
+
+  Mention how to obtain a copy of the development tree
+\end_layout
+
+\begin_layout Standard
+
+  Add Scientific.IO.NetCDF to list of optional tools
+\end_layout
+
+\begin_layout Standard
+
+  Add SciPy to the list of optional tools
+\end_layout
+
+\begin_layout Standard
+
+\end_layout
+
+\begin_layout Standard
+
+Portions of Boost that we use
+\end_layout
+
+\begin_layout Standard
+
+  boost::filesystem
+\end_layout
+
+\begin_layout Standard
+
+  boost::program_options
+\end_layout
+
+\begin_layout Standard
+
+  boost::regex (parsing parameters from source strings)
+\end_layout
+
+\begin_layout Standard
+
+  boost::python (for wrapping the core library objects)
+\end_layout
+
+\begin_layout Standard
+
+}
+\end_layout
+
+\end_inset
+
+
+\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
+Installing 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 Boost, HDF5, and VTK libraries, described later in this section, are
+ also required components.
+\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-1.0.0.tar.gz
+\end_layout
+
+\begin_layout LyX-Code
+$ cd cigma-1.0.0
+\end_layout
+
+\begin_layout LyX-Code
+$ ./configure --with-boost=$BOOST_PREFIX
+\end_layout
+
+\begin_layout LyX-Code
+              --with-hdf5=$HDF5_PREFIX 
+\end_layout
+
+\begin_layout LyX-Code
+              --with-vtk=$VTK_PREFIX 
+\end_layout
+
+\begin_layout LyX-Code
+$ make
+\end_layout
+
+\begin_layout LyX-Code
+$ make install
+\end_layout
+
+\begin_layout Standard
+Both HDF5 and VTK prefixes are required if you have installed these libraries
+ in a custom location.
+ After these steps are complete, you should be able to run the 
+\family typewriter
+cigma
+\family default
+ binary.
+\end_layout
+
+\begin_layout Subsection
+Boost
+\end_layout
+
+\begin_layout Standard
+The Boost C++ libraries are used in Cigma for parsing command-line options,
+ ensuring cross-platform access to the filesystem, and providing Python
+ bindings to certain Cigma C++ functions and classes.
+\end_layout
+
+\begin_layout LyX-Code
+$ tar xvfz boost_1_35_0.tar.gz
+\end_layout
+
+\begin_layout LyX-Code
+$ cd boost_1_35_0
+\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 Standard
+Without a custom installation prefix, Boost will target your 
+\family typewriter
+/usr/local
+\family default
+ directory.
+\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
+target "hdfgroup.org/HDF5/release/obtain5.html"
+
+\end_inset
+
+.
+ To install from source, download the latest stable 1.6 version of this library
+ (1.6.7, for example) and issue the following commands
+\end_layout
+
+\begin_layout LyX-Code
+$ tar xvfz hdf5-1.6.7.tar.gz
+\end_layout
+
+\begin_layout LyX-Code
+$ cd hdf5-1.6.7
+\end_layout
+
+\begin_layout LyX-Code
+$ ./configure --prefix=$HOME/opt/hdf5/1.6.7
+\end_layout
+
+\begin_layout LyX-Code
+$ make
+\end_layout
+
+\begin_layout LyX-Code
+$ make install
+\end_layout
+
+\begin_layout Standard
+Without the custom prefix, this installation procedure will target your
+ 
+\family typewriter
+/usr
+\family default
+ directory.
+\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 Standard
+You can set the installation prefix during the 
+\family typewriter
+ccmake
+\family default
+ step above, which defaults to your 
+\family typewriter
+/usr/local
+\family default
+ directory.
+\end_layout
+
+\begin_layout Section
+Additional Software (optional)
+\end_layout
+
+\begin_layout Standard
+The following software packages are not strictly required, but are listed
+ here for completeness since they are used by various utility scripts included
+ in the Cigma source tree.
+ These utilities are meant for creating and manipulating Cigma input/output
+ files.
+ We include a short description for how we use these software packages in
+ our utility scripts and how they depend on each other, so that you can
+ decide which of these to install.
+ You should be able to find binary packages for each of these Python modules
+ in the respective project home pages.
+ Note that you will need a C and Fortran compiler to install these from
+ source, as well as the appropriate libraries and development headers.
+\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
+
+.
+ 
+\end_layout
+
+\begin_layout Standard
+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 files needed 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
+ScientificPython
+\end_layout
+
+\begin_layout Standard
+The ScientificPython module is a Python library for common tasks in scientific
+ computing.
+ Primarily, we use it to convert the ExodusII mesh files generated by the
+ Sandia National Laboratories CUBIT package.
+ Prior to installing this Python module, you must also install the NetCDF
+ development libraries and headers in order for the Scientific.IO.NetCDF module
+ to work properly.
+\end_layout
+
+\begin_layout Standard
+ScientificPython is available for download from 
+\begin_inset LatexCommand htmlurl
+target "dirac.cnrs-orleans.fr/plone/software/scientificpython"
+
+\end_inset
+
+.
+ To install this extension from source, download the latest version and
+ proceed as follows:
+\end_layout
+
+\begin_layout LyX-Code
+$ tar xvfz ScientificPython-2.x.y.tar.gz
+\end_layout
+
+\begin_layout LyX-Code
+$ cd ScientificPython-2.x.y
+\end_layout
+
+\begin_layout LyX-Code
+$ python setup.py install
+\end_layout
+
+\begin_layout Standard
+To test whether the Scientific.IO.NetCDF module was installed correctly, you
+ can run `
+\family typewriter
+import Scientific.IO.NetCDF
+\family default
+' from within your standard Python interpreter shell.
+\end_layout
+
+\begin_layout Subsection
+SciPy
+\end_layout
+
+\begin_layout Standard
+SciPy is a Python module for use in mathematics, science, and engineering.
+ It contains algorithms for optimization, linear algebra, and other common
+ scientific tasks.
+ SciPy is available for download from 
+\begin_inset LatexCommand url
+target "scipy.org"
+
+\end_inset
+
+.
+\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.
+ We can also use it to evaluate the shape function values at the required
+ integration points.
+\end_layout
+
+\begin_layout Standard
+FIAT is available from 
+\begin_inset LatexCommand htmlurl
+name "The FEniCS Project"
+target "www.fenics.org/wiki/FIAT"
+
+\end_inset
+
+.
+ To install this module, download it and issue the following command inside
+ the FIAT source directory:
+\end_layout
+
+\begin_layout LyX-Code
+$ 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
+\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 group hierarchy, 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
+
+\end_body
+\end_document

Modified: doc/cigma/manual/introduction/introduction.lyx
===================================================================
--- doc/cigma/manual/introduction/introduction.lyx	2008-08-13 01:29:38 UTC (rev 12623)
+++ doc/cigma/manual/introduction/introduction.lyx	2008-08-13 20:21:18 UTC (rev 12624)
@@ -1,182 +1,227 @@
-#LyX 1.5.6 created this file. For more info see http://www.lyx.org/
-\lyxformat 276
-\begin_document
-\begin_header
-\textclass book
-\begin_preamble
-\newcommand{\mynote}[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 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 Standard
-\begin_inset ERT
-status open
-
-\begin_layout Standard
-
-
-\backslash
-mynote{}
-\end_layout
-
-\end_inset
-
-
-\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
-
-\end_body
-\end_document
+#LyX 1.5.5 created this file. For more info see http://www.lyx.org/
+\lyxformat 276
+\begin_document
+\begin_header
+\textclass book
+\begin_preamble
+\newcommand{\mynote}[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 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 Standard
+\begin_inset ERT
+status open
+
+\begin_layout Standard
+
+
+\backslash
+mynote{
+\end_layout
+
+\begin_layout Standard
+
+Anything to emphasize here?
+\end_layout
+
+\begin_layout Standard
+
+  Talk about requirements: quantitative definition, automatic, verification
+ of numerical codes
+\end_layout
+
+\begin_layout Standard
+
+}
+\end_layout
+
+\end_inset
+
+
+\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.
+\end_layout
+
+\begin_layout Standard
+The current version of Cigma is intended for the calculation of 
+\begin_inset Formula $L_{2}$
+\end_inset
+
+ residuals in finite element models, but can be extended to compare arbitrary
+ functions.
+ 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 differences
+ 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
+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
+\begin_inset Note Note
+status open
+
+\begin_layout Standard
+\begin_inset ERT
+status open
+
+\begin_layout Standard
+
+
+\backslash
+mynote{implementation details -- move contents of this note to other chapters}
+\end_layout
+
+\end_inset
+
+
+\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
+
+\end_inset
+
+
+\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
+
+\end_body
+\end_document

Modified: doc/cigma/manual/running/running.lyx
===================================================================
--- doc/cigma/manual/running/running.lyx	2008-08-13 01:29:38 UTC (rev 12623)
+++ doc/cigma/manual/running/running.lyx	2008-08-13 20:21:18 UTC (rev 12624)
@@ -1,881 +1,645 @@
-#LyX 1.5.6 created this file. For more info see http://www.lyx.org/
-\lyxformat 276
-\begin_document
-\begin_header
-\textclass book
-\begin_preamble
-\newcommand{\mynote}[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 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 Standard
-\begin_inset ERT
-status open
-
-\begin_layout Standard
-
-
-\backslash
-mynote{}
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Chapter
-\begin_inset LatexCommand label
-name "cha:Running-Cigma"
-
-\end_inset
-
-Running Cigma
-\end_layout
-
-\begin_layout Standard
-Cigma is primarily designed for calculating error estimates between arbitrary
- fields, so its primary usage is centered on the following operation
-\end_layout
-
-\begin_layout LyX-Code
-$ 
-\series bold
-cigma compare 
-\emph on
-\bar under
-field1
-\emph default
-\bar default
- 
-\emph on
-\bar under
-field2
-\emph default
-\bar default
- -o residuals.vtk
-\end_layout
-
-\begin_layout Standard
-You will need to provide two datasets describing each of the two fields,
- specify an integration rule and a domain discretization over which to integrate
-, although these last two will have reasonable defaults if they are not
- specified.
-\end_layout
-
-\begin_layout Standard
-The default data storage format for Cigma is the Hierarchical Data Format
- (HDF5), 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
-
-.
- The HDF5 is designed for storing multi-dimensional arrays together with
- meta-data in a portable self-describing format.
-\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 set of available commands can be obtained by typing
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
-$ 
-\family default
-\series bold
-cigma help
-\end_layout
-
-\begin_layout LyX-Code
-
-\end_layout
-
-\begin_layout LyX-Code
-Usage: cigma <subcommand> [options]
-\end_layout
-
-\begin_layout LyX-Code
-Type 'cigma help <subcommand>' for help on a specific subcommand.
-\end_layout
-
-\begin_layout LyX-Code
-Available subcommands
-\end_layout
-
-\begin_layout LyX-Code
-   help
-\end_layout
-
-\begin_layout LyX-Code
-   list
-\end_layout
-
-\begin_layout LyX-Code
-   extract
-\end_layout
-
-\begin_layout LyX-Code
-   eval
-\end_layout
-
-\begin_layout LyX-Code
-   compare 
-\end_layout
-
-\begin_layout Standard
-Examples for each of these commands are given in the sections below.
-\end_layout
-
-\begin_layout Section
-Input and Output Formats
-\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.
- The Hierarchical Data Format (HDF) is designed for storing, retrieving,
- analyzing, visualizing, and converting scientific data.
- It uses a hierarchical structure that provides users a host of options
- for organizing how their data is stored in HDF5 files.
- 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
-Another popular format for providing mesh and field inputs.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 Standard
-Inputs can be either HDF5 or VTK.
- 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 Standard
-Mesh inputs are currently only unstructured grids.
-\end_layout
-
-\begin_layout Standard
-Only exception are the residuals, which are written in legacy VTK format
- as scalar cell data over an unstructured grid.
-\end_layout
-
-\begin_layout Standard
-XXX New section?
-\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
-
-\end_deeper
-\begin_layout Standard
-You can also view the structure of a VTK file with this command:
-\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 Section
-Cigma Datasets
-\end_layout
-
-\begin_layout Standard
-A field is a function which assigns a physical quantity to every point in
- a domain 
-\begin_inset Formula $\Omega$
-\end_inset
-
-.
- This quantity may correspond to a scalar, a vector, or even a tensor.
- As in Chapter 
-\begin_inset LatexCommand ref
-reference "cha:Error-Analysis"
-
-\end_inset
-
-, we shall use the same discretization 
-\begin_inset Formula $\Omega_{e}$
-\end_inset
-
-.
- 
-\end_layout
-
-\begin_layout Standard
-A finite element approximation to an solution field 
-\begin_inset Formula $\phi(\vec{x})$
-\end_inset
-
- on an element 
-\begin_inset Formula $\Omega_{e}$
-\end_inset
-
- is essentially specified by the weighed sum over a fixed set of local shape
- functions 
-\begin_inset Formula $\phi_{e,1}(\vec{\xi}),\phi_{e,2}(\vec{\xi}),\ldots,\phi_{e,N}(\vec{\xi})$
-\end_inset
-
- defined on the appropriate reference cell,
-\end_layout
-
-\begin_layout Standard
-\begin_inset Formula \[
-\phi(\vec{x})=\sum_{n=1}^{N}d_{e,n}\phi_{e,n}(\vec{\xi})\]
-
-\end_inset
-
-where the global point 
-\begin_inset Formula $\vec{x}\in\Omega_{e}$
-\end_inset
-
- corresponds to the local reference point 
-\begin_inset Formula $\vec{\xi}=\vec{x}_{e}^{-1}(\vec{x})\in\hat{\Omega}$
-\end_inset
-
-, and the weights 
-\begin_inset Formula $d_{e,n}$
-\end_inset
-
-, also known as degrees of freedom, are given on each global node.
- These shape functions define a basis for the function space on the finite
- element 
-\begin_inset Formula $\Omega_{e}$
-\end_inset
-
-.
-\end_layout
-
-\begin_layout Standard
-For a mesh consisting of a single element type, we need to specify the 
-\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
-The most common element types used in the finite element method are given
- by the following shape functions, which define the interior of a tetrahedron
- with vertices at 
-\begin_inset Formula $a=(0,0,0)$
-\end_inset
-
-, 
-\begin_inset Formula $b=(1,0,0)$
-\end_inset
-
-, 
-\begin_inset Formula $c=(0,1,0)$
-\end_inset
-
-, 
-\begin_inset Formula $d=(0,0,1)$
-\end_inset
-
-, 
-\end_layout
-
-\begin_layout Standard
-\begin_inset Float figure
-placement H
-wide false
-sideways false
-status open
-
-\begin_layout Standard
-\begin_inset Box Frameless
-position "c"
-hor_pos "c"
-has_inner_box 1
-inner_pos "b"
-use_parbox 0
-width "50col%"
-special "none"
-height "1in"
-height_special "totalheight"
-status open
-
-\begin_layout Standard
-\begin_inset Formula \begin{eqnarray*}
-N_{a} & = & \frac{1}{2}(-1-x-y-z)\\
-N_{b} & = & \frac{1}{2}(1+x)\\
-N_{c} & = & \frac{1}{2}(1+y)\\
-N_{d} & = & \frac{1}{2}(1+z)\end{eqnarray*}
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\begin_inset Box Frameless
-position "c"
-hor_pos "c"
-has_inner_box 1
-inner_pos "c"
-use_parbox 0
-width "50col%"
-special "none"
-height "1in"
-height_special "totalheight"
-status collapsed
-
-\begin_layout Standard
-\begin_inset Graphics
-	filename ../../figures/reference-tet4.png
-	width 5cm
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-\begin_inset Caption
-
-\begin_layout Standard
-Reference Tetrahedron
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-Likewise, a hexahedral element with vertices located at 
-\begin_inset Formula $a=(-1,-1,-1)$
-\end_inset
-
-, 
-\begin_inset Formula $b=(1,-1,-1)$
-\end_inset
-
-, 
-\begin_inset Formula $c=(1,1,-1)$
-\end_inset
-
-, 
-\begin_inset Formula $d=(-1,1,-1)$
-\end_inset
-
-, 
-\begin_inset Formula $e=(-1,-1,1)$
-\end_inset
-
-, 
-\begin_inset Formula $f=(1,-1,1)$
-\end_inset
-
-, 
-\begin_inset Formula $g=(1,1,1)$
-\end_inset
-
-, 
-\begin_inset Formula $h=(-1,1,1)$
-\end_inset
-
-.
-\end_layout
-
-\begin_layout Standard
-\begin_inset Float figure
-placement H
-wide false
-sideways false
-status open
-
-\begin_layout Standard
-\begin_inset Box Frameless
-position "c"
-hor_pos "c"
-has_inner_box 1
-inner_pos "c"
-use_parbox 0
-width "50col%"
-special "none"
-height "1in"
-height_special "totalheight"
-status collapsed
-
-\begin_layout Standard
-\begin_inset Graphics
-	filename ../../figures/reference-hex8.png
-	width 5cm
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\begin_inset Box Frameless
-position "c"
-hor_pos "c"
-has_inner_box 1
-inner_pos "c"
-use_parbox 0
-width "50col%"
-special "none"
-height "1in"
-height_special "totalheight"
-status open
-
-\begin_layout Standard
-\begin_inset Formula \begin{eqnarray*}
-N_{a} & = & \frac{1}{8}\left(1-x\right)\left(1-y\right)\left(1-z\right)\\
-N_{b} & = & \frac{1}{8}\left(1+x\right)\left(1-y\right)\left(1-z\right)\\
-N_{c} & = & \frac{1}{8}\left(1-x\right)\left(1+y\right)\left(1-z\right)\\
-N_{d} & = & \frac{1}{8}\left(1+x\right)\left(1+y\right)\left(1-z\right)\\
-N_{e} & = & \frac{1}{8}\left(1-x\right)\left(1-y\right)\left(1+z\right)\\
-N_{f} & = & \frac{1}{8}\left(1+x\right)\left(1-y\right)\left(1+z\right)\\
-N_{g} & = & \frac{1}{8}\left(1-x\right)\left(1+y\right)\left(1+z\right)\\
-N_{h} & = & \frac{1}{8}\left(1+x\right)\left(1+y\right)\left(1+z\right)\end{eqnarray*}
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-\begin_inset Caption
-
-\begin_layout Standard
-Reference Hexahedron
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-XXX: Take description of higher order elements from Karniadakis book
-\end_layout
-
-\begin_layout Subsection
-Comparing Two Finite Element 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 involve a numerical integration over each
- of the elements in the mesh associated with the first field.
- If this discretization is inadequate, you may also specify an alternative
- discretization over which to perform the integration.
- The comparison operation will output the local residual values are into
- the specified output file.
-\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 --first=field1.h5:/field1/stepN
-\end_layout
-
-\begin_layout LyX-Code
-
-\series bold
- 
-\series default
-             --second=field2.h5:/field2/stepN
-\end_layout
-
-\begin_layout LyX-Code
-              --output=residuals.vtk
-\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 field1.h5:/model/mesh/ -o points.h5:/projected_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 --first=field1.h5:/field1/stepN
-\end_layout
-
-\begin_layout LyX-Code
-              --second-points=points.h5:/projected_points
-\end_layout
-
-\begin_layout LyX-Code
-              --second-values=values.h5:/projected_values
-\end_layout
-
-\begin_layout LyX-Code
-              --output=residuals.vtk
-\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 as a builtin
- Cigma function.
- This will enable you to reference your function by name when using the
- 
-\family typewriter
-compare
-\family default
- command.
- For example,
-\end_layout
-
-\begin_layout LyX-Code
-cigma compare --first=field1.h5:/vars/displacement/step0
-\end_layout
-
-\begin_layout LyX-Code
-
-\series bold
- 
-\series default
-             --second=
-\bar under
-disloc3d
-\end_layout
-
-\begin_layout LyX-Code
-              --output=residuals.vtk
-\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=
-\bar under
-disloc3d
-\end_layout
-
-\begin_layout LyX-Code
-           --points=points.h5:/projected_points
-\end_layout
-
-\begin_layout LyX-Code
-           --values=values.h5:/disloc3d_values
-\end_layout
-
-\begin_layout Standard
-Once these values have been obtained, we can use it to resume the calculation
- of 
-\end_layout
-
-\begin_layout LyX-Code
-cigma compare --output=residuals.vtk
-\end_layout
-
-\begin_layout LyX-Code
-              --first=field1.h5:/vars/displacement/step0
-\end_layout
-
-\begin_layout LyX-Code
-              --second-points=points.h5:/projected_points
-\end_layout
-
-\begin_layout LyX-Code
-              --second-values=values.h5:/disloc3d_values
-\end_layout
-
-\begin_layout Standard
-Another built-in function you might find useful is the 
-\family typewriter
-\bar under
-zero
-\family default
-\bar default
- function, which is defined to return 0 everywhere.
- You can use this function for estimating the norm of your field.
-\end_layout
-
-\begin_layout Subsection
-Specifying a Integration 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
-Alternatively, 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 Standard
-In the 
-\family typewriter
-src/
-\family default
- directory of the Cigma distribution, you can find a Python script called
- 
-\family typewriter
-rules.py
-\family default
- that uses FIAT for calculating an appropriate set of quadrature rules for
- use in Cigma.
-\end_layout
-
-\end_body
-\end_document
+#LyX 1.5.5 created this file. For more info see http://www.lyx.org/
+\lyxformat 276
+\begin_document
+\begin_header
+\textclass book
+\begin_preamble
+\newcommand{\mynote}[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 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 Standard
+\begin_inset ERT
+status open
+
+\begin_layout Standard
+
+
+\backslash
+mynote{
+\end_layout
+
+\begin_layout Standard
+
+\end_layout
+
+\begin_layout Standard
+
+In general, verify that the output of the commands, whenever given, matches
+ the actual output when running a similar command
+\end_layout
+
+\begin_layout Standard
+
+\end_layout
+
+\begin_layout Standard
+
+Do not forget to mention the following:
+\end_layout
+
+\begin_layout Standard
+
+  - Default behaviour if a flag or option is not specified (eg., what if
+ we omit --output?)
+\end_layout
+
+\begin_layout Standard
+
+  - Common flags:
+\end_layout
+
+\begin_layout Standard
+
+     Misc options: --quiet and --verbose (misc option)
+\end_layout
+
+\begin_layout Standard
+
+     Hidden options: --debug flag to enable logging
+\end_layout
+
+\begin_layout Standard
+
+  - Turn off logging if --disable-logging is given to ./configure script
+ (logging on by default)
+\end_layout
+
+\begin_layout Standard
+
+  - The --output option needs an override flag so we can force the rewriting
+ of specific datasets
+\end_layout
+
+\begin_layout Standard
+
+     * Default behavior? Exit if output dataset already exists
+\end_layout
+
+\begin_layout Standard
+
+     * Possible names if default behavior is to exit: --force-writes, --force-ou
+tput, --overwrite-output
+\end_layout
+
+\begin_layout Standard
+
+     * Possible names if default is to allow overwrites: --dont-overwrite
+\end_layout
+
+\begin_layout Standard
+
+  - Addition modifiers to compare command?
+\end_layout
+
+\begin_layout Standard
+
+     * Try --weighed-residuals={0,1} flag in order to divide the cell residuals
+ by the volume
+\end_layout
+
+\begin_layout Standard
+
+\end_layout
+
+\begin_layout Standard
+
+Given the context of the previous chapter (on file formats), define the
+\end_layout
+
+\begin_layout Standard
+
+'Dataset Path' when discussing the location of datasets within a file
+\end_layout
+
+\begin_layout Standard
+
+\end_layout
+
+\begin_layout Standard
+
+XXX: Split the discussion of datasets and I/O into their corresponding chapters
+\end_layout
+
+\begin_layout Standard
+
+\end_layout
+
+\begin_layout Standard
+
+  Ensure that most instances of the world 'Field' are replaced by 'Function'
+\end_layout
+
+\begin_layout Standard
+
+  Ensure that 'Quadrature Rule' is changed into 'Integration Rule'
+\end_layout
+
+\begin_layout Standard
+
+  Reference datasets in HDF5 files as 'Simple Arrays'
+\end_layout
+
+\begin_layout Standard
+
+  Discuss ExodusII format
+\end_layout
+
+\begin_layout Standard
+
+  Discuss VTK formats: Legacy VTK (.vtk), Unstructured Grid (.vtu), Structured
+ Grid (.vts), Rectilinear Grid (.vtr)
+\end_layout
+
+\begin_layout Standard
+
+  Discuss Parallel VTK formats: *.pvtu, *.pvts, *.pvtr
+\end_layout
+
+\begin_layout Standard
+
+  Discuss UCD format: *.inp, *.ucd -- uses class vtkAVSucdReader from the
+ VTK API
+\end_layout
+
+\begin_layout Standard
+
+\end_layout
+
+\begin_layout Standard
+
+Mention man pages as well -- which also provide an EXAMPLES section
+\end_layout
+
+\begin_layout Standard
+
+  Usage string from 'cigma help' displays short form of command -- using
+ the positional arguments
+\end_layout
+
+\begin_layout Standard
+
+  Commonly used long options are also provided
+\end_layout
+
+\begin_layout Standard
+
+  For more advanced usage, 'man cigma-compare' would bring up more examples.
+\end_layout
+
+\begin_layout Standard
+
+\end_layout
+
+\begin_layout Standard
+
+Don't forget to mention that every positional argument can also be specified
+ through the use of a long option
+\end_layout
+
+\begin_layout Standard
+
+Mention common flags, such as --quiet and --verbose for tuning the amount
+ of output, and --debug for turning on logging (off by default)
+\end_layout
+
+\begin_layout Standard
+
+In general, --verbose should turn on the progress meter for long-running
+ operations, while --quiet will emit the minimal amount of output (none
+ for most commands, but the compare command should output just the (L2 norm,
+ Linf norm, time in seconds))
+\end_layout
+
+\begin_layout Standard
+
+\end_layout
+
+\begin_layout Standard
+
+Command for tracking memory usage of a running process?
+\end_layout
+
+\begin_layout Standard
+
+\end_layout
+
+\begin_layout Standard
+
+----------------------------
+\end_layout
+
+\begin_layout Standard
+
+The default data storage format for Cigma is the Hierarchical Data Format
+ (HDF5), a portable file format developed at the $X .
+ The HDF5 is designed for storing multi-dimensional arrays together with
+ meta-data in a portable self-describing format.
+ X = [National Center for Supercomputing Applications (NCSA)](hdf.ncsa.uiuc.edu/HDF
+5)
+\end_layout
+
+\begin_layout Standard
+
+\end_layout
+
+\begin_layout Standard
+
+-----------------------------------------------------
+\end_layout
+
+\begin_layout Standard
+
+\end_layout
+
+\begin_layout Standard
+
+}
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Chapter
+\begin_inset LatexCommand label
+name "cha:Running-Cigma"
+
+\end_inset
+
+Running Cigma
+\end_layout
+
+\begin_layout Standard
+As mentioned in the first chapter, Cigma is primarily designed for calculating
+ error estimates between arbitrary functions.
+ Therefore its primary usage revolves around the following operation
+\end_layout
+
+\begin_layout LyX-Code
+$ 
+\series bold
+cigma compare 
+\emph on
+\bar under
+FunctionA
+\emph default
+\bar default
+ 
+\emph on
+\bar under
+FunctionB
+\emph default
+\bar default
+ -o residuals.vtk
+\end_layout
+
+\begin_layout Standard
+In general, you will provide two paths pointing to the location of the data
+ describing the two functions you wish to compare, although in special cases
+ you will be able to refer to specific functions by name instead.
+\end_layout
+
+\begin_layout Standard
+You may also need to provide further information by using additional command
+ line options.
+ For example, you may want to use a different domain discretization for
+ the numerical integration step.
+ or you may need to increase the order of the quadrature rule in order to
+ improve accuracy of the integration.
+\end_layout
+
+\begin_layout Section
+Command Line Interface
+\end_layout
+
+\begin_layout Standard
+\begin_inset ERT
+status open
+
+\begin_layout Standard
+
+
+\backslash
+mynote{Summarize commands.
+ Explain 'cigma help foo' and 'man cigma-foo'.
+ Include flow diagram showing the relationship between the various commands.}
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Subsection
+Comparing Two Finite Element 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 involve a numerical integration over each
+ of the elements in the mesh associated with the first field.
+ If this discretization is inadequate, you may also specify an alternative
+ discretization over which to perform the integration.
+ The comparison operation will output the local residual values are into
+ the specified output file.
+\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 --first=field1.h5:/field1/stepN
+\end_layout
+
+\begin_layout LyX-Code
+
+\series bold
+ 
+\series default
+             --second=field2.h5:/field2/stepN
+\end_layout
+
+\begin_layout LyX-Code
+              --output=residuals.vtk
+\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 field1.h5:/model/mesh/ -o points.h5:/projected_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 --first=field1.h5:/field1/stepN
+\end_layout
+
+\begin_layout LyX-Code
+              --second-points=points.h5:/projected_points
+\end_layout
+
+\begin_layout LyX-Code
+              --second-values=values.h5:/projected_values
+\end_layout
+
+\begin_layout LyX-Code
+              --output=residuals.vtk
+\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 as a builtin
+ Cigma function.
+ This will enable you to reference your function by name when using the
+ 
+\family typewriter
+compare
+\family default
+ command.
+ For example,
+\end_layout
+
+\begin_layout LyX-Code
+cigma compare --first=field1.h5:/vars/displacement/step0
+\end_layout
+
+\begin_layout LyX-Code
+
+\series bold
+ 
+\series default
+             --second=
+\bar under
+disloc3d
+\end_layout
+
+\begin_layout LyX-Code
+              --output=residuals.vtk
+\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=
+\bar under
+disloc3d
+\end_layout
+
+\begin_layout LyX-Code
+           --points=points.h5:/projected_points
+\end_layout
+
+\begin_layout LyX-Code
+           --values=values.h5:/disloc3d_values
+\end_layout
+
+\begin_layout Standard
+Once these values have been obtained, we can use it to resume the calculation
+ of 
+\end_layout
+
+\begin_layout LyX-Code
+cigma compare --output=residuals.vtk
+\end_layout
+
+\begin_layout LyX-Code
+              --first=field1.h5:/vars/displacement/step0
+\end_layout
+
+\begin_layout LyX-Code
+              --second-points=points.h5:/projected_points
+\end_layout
+
+\begin_layout LyX-Code
+              --second-values=values.h5:/disloc3d_values
+\end_layout
+
+\begin_layout Standard
+Another built-in function you might find useful is the 
+\family typewriter
+\bar under
+zero
+\family default
+\bar default
+ function, which is defined to return 0 everywhere.
+ You can use this function for estimating the norm of your field.
+\end_layout
+
+\begin_layout Subsection
+Specifying a Integration 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
+Alternatively, 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 Standard
+In the 
+\family typewriter
+src/
+\family default
+ directory of the Cigma distribution, you can find a Python script called
+ 
+\family typewriter
+rules.py
+\family default
+ that uses FIAT for calculating an appropriate set of quadrature rules for
+ use in Cigma.
+\end_layout
+
+\end_body
+\end_document