[cig-commits] [commit] master: First attempt to reorganize manual for version 0.9.1. Keep transferring sections and content between these two docs until we converge. (4d598d3)

Fri May 9 15:23:55 PDT 2014

Repository : https://github.com/geodynamics/cigma

On branch  : master
Link       : https://github.com/geodynamics/cigma/compare/65c02138d3ae8b87c088cc14fe4f98e21e3f0805...a26f592c25c89a40622404999ba1effcdf6df9e3

>---------------------------------------------------------------

commit 4d598d3c4c599781031c8eb685c818781f1eb64b
Author: Luis Armendariz <luis>
Date:   Wed Feb 27 21:11:10 2008 +0000

    First attempt to reorganize manual for version 0.9.1. Keep transferring sections and content
    between these two docs until we converge.


>---------------------------------------------------------------

4d598d3c4c599781031c8eb685c818781f1eb64b
 cigma.lyx   |   2 +-
 scratch.lyx | 600 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 601 insertions(+), 1 deletion(-)

diff --git a/cigma.lyx b/cigma.lyx
index 4fb26ca..8701192 100644
--- a/cigma.lyx
+++ b/cigma.lyx
@@ -1,4 +1,4 @@
-#LyX 1.5.1 created this file. For more info see http://www.lyx.org/
+#LyX 1.5.3 created this file. For more info see http://www.lyx.org/
 \lyxformat 276
 \begin_document
 \begin_header
diff --git a/scratch.lyx b/scratch.lyx
new file mode 100644
index 0000000..ae630d2
--- /dev/null
+++ b/scratch.lyx
@@ -0,0 +1,600 @@
+#LyX 1.5.3 created this file. For more info see http://www.lyx.org/
+\lyxformat 276
+\begin_document
+\begin_header
+\textclass book
+\language english
+\inputencoding auto
+\font_roman default
+\font_sans default
+\font_typewriter default
+\font_default_family default
+\font_sc false
+\font_osf false
+\font_sf_scale 100
+\font_tt_scale 100
+\graphics default
+\paperfontsize default
+\spacing single
+\papersize default
+\use_geometry false
+\use_amsmath 1
+\use_esint 1
+\cite_engine basic
+\use_bibtopic false
+\paperorientation portrait
+\secnumdepth 3
+\tocdepth 3
+\paragraph_separation indent
+\defskip medskip
+\quotes_language english
+\papercolumns 1
+\papersides 1
+\paperpagestyle default
+\tracking_changes false
+\output_changes false
+\author "" 
+\author "" 
+\end_header
+
+\begin_body
+
+\begin_layout Chapter
+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 developed Cigma in response to demand from the short-term tectonics
+ community for a tool that could perform rigorous error analysis on their
+ FEM codes.
+ [[XXX: additional notes here]]
+\end_layout
+
+\begin_layout Standard
+Cigma relies upon a number of software 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 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.
+ The Hierarchical Data Format (HDF5) library is used for organizing the
+ input and output datasets.
+ The Visualization Toolkit (VTK) library can be used to provide input datasets,
+ as well as for visualization of output files.
+ [[XXX]]
+\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 at press
+ for use as citations other than this manual, which is cited 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, 2007.
+ 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 supported by a grant from the National Science Foundation
+ to CIG, managed by the California Institute of Technology.
+ The code is being released under the GNU General Public License.
+\end_layout
+
+\begin_layout Chapter
+Error Analysis
+\end_layout
+
+\begin_layout Standard
+[[This chapter discusses error analysis, the basic components of cigma (discount
+ing I/O stuff), and the kinds of operations you'd perform with those components]
+]
+\end_layout
+
+\begin_layout Section
+Introduction
+\end_layout
+
+\begin_layout Standard
+XXX: Transfer most of this one
+\end_layout
+
+\begin_layout Standard
+[[move changes here]]
+\end_layout
+
+\begin_layout Standard
+[[move discussion of file formats to chapter 4]]
+\end_layout
+
+\begin_layout Chapter
+Installation and Getting Help
+\end_layout
+
+\begin_layout Standard
+[[In this chapter, give installation instructions for cigma.
+ Give list of dependencies, plus instructions for Debian system.
+ For each dependency, explain how to install from source if it's easy, otherwise
+ refer the reader to the installation instructions on the appropriate web
+ site]]
+\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
+Installation from Source
+\end_layout
+
+\begin_layout Standard
+To install Cigma, first 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
+
+.
+ For this step, you will need the GNU C++ compiler and the HDF5 library.
+ After unpacking the compressed tar file, issue the following commands
+\end_layout
+
+\begin_layout LyX-Code
+$ tar xvfz cigma-0.9.1
+\end_layout
+
+\begin_layout LyX-Code
+$ cd cigma-0.9.1
+\end_layout
+
+\begin_layout LyX-Code
+$ ./configure --with-hdf5=${HDF5_PREFIX}
+\end_layout
+
+\begin_layout LyX-Code
+$ make
+\end_layout
+
+\begin_layout LyX-Code
+$ sudo make install
+\end_layout
+
+\begin_layout Standard
+You should now be able to access the cigma executable.
+ If your HDF5 library is installed with a default prefix location, then
+ you can omit the configure flag --with-hdf5 in the commands listed above.
+\end_layout
+
+\begin_layout Section
+Software Dependencies
+\end_layout
+
+\begin_layout Standard
+While only the HDF5 library is required to be preinstalled, several other
+ software packages are recommended to easily access the data in the output
+ files, or to provide additional functionality.
+\end_layout
+
+\begin_layout Subsection
+HDF5
+\end_layout
+
+\begin_layout Standard
+HDF5 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 this library from source, download the latest stable version
+ (currently 1.6.5) and issue the following commands
+\end_layout
+
+\begin_layout LyX-Code
+$ tar xvfz hdf5-1.6.5
+\end_layout
+
+\begin_layout LyX-Code
+$ cd hdf5-1.6.5
+\end_layout
+
+\begin_layout LyX-Code
+$ ./configure
+\end_layout
+
+\begin_layout LyX-Code
+$ make
+\end_layout
+
+\begin_layout LyX-Code
+$ sudo make install
+\end_layout
+
+\begin_layout Standard
+After running the above installation procedure, you should be able to access
+ the h5ls and h5dump command line utilities.
+\end_layout
+
+\begin_layout Subsection
+VTK
+\end_layout
+
+\begin_layout Standard
+VTK is available from 
+\begin_inset LatexCommand htmlurl
+name "Kitware, Inc."
+target "www.vtk.org/get-software.php"
+
+\end_inset
+
+.
+ We recommend that you install this library from a binary package by using
+ your favorite package manager.
+ However, make sure to install the associated development headers, which
+ will typically be included inside a package suffixed with -dev or -devel.
+ If you have installed VTK in a non-standard location, you will have to
+ use the following additional flag when running configure in the installation
+ procedure for Cigma.
+\end_layout
+
+\begin_layout LyX-Code
+$ ./configure [...] --with-vtk=${VTK_PREFIX}
+\end_layout
+
+\begin_layout Standard
+where you should substitute for your custom prefix path pointing to the
+ VTK library.
+\end_layout
+
+\begin_layout Subsection
+NumPy
+\end_layout
+
+\begin_layout Standard
+NumPy is a Python module which adds support for large multi-dimensional
+ arrays and matrices, and is available for download from the 
+\begin_inset LatexCommand htmlurl
+name "NumPy Home Page"
+target "numpy.scipy.org "
+
+\end_inset
+
+.
+ To install this extension module from source, download it and issue the
+ following command in the NumPy source directory
+\end_layout
+
+\begin_layout LyX-Code
+$ sudo python setup.py install
+\end_layout
+
+\begin_layout Standard
+You should now be able to successfully run 'import numpy' 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 successfully run 'import FIAT' 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) and issue the following command in the PyTables 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 'import tables' 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 file hierarchy in a tree structure,
+ adding new datasets, and modifying or deleting existing datasets.
+ You can download it from the 
+\begin_inset LatexCommand htmlurl
+name "HDFView home page"
+target "hdf.ncsa.uiuc.edu/hdf-java-html/hdfview"
+
+\end_inset
+
+.
+\end_layout
+
+\begin_layout Chapter
+Running Cigma
+\end_layout
+
+\begin_layout Standard
+[[This chapter explains the usage of every command in cigma, and any other
+ information necessary for running the program (as such, the description
+ of the file formats belongs here, not in chapter 2).
+ The information given here should also be converted into the corresponding
+ set of man pages and usage messages.]]
+\end_layout
+
+\begin_layout Section
+Design
+\end_layout
+
+\begin_layout Standard
+Cigma is designed to run from shell scripts, and thus all operations can
+ be specifiead as command line arguments given to an executable program
+ called cigma.
+ This program understands a number of subcommands.
+\end_layout
+
+\begin_layout Standard
+Since cigma is used for obtaining error estimates between arbitrary fields,
+ its primary operation revolves around the compare subcommand.
+ When calling this subcommand, you will need to provide two dataset arguments
+ (one for each field), a quadrature rule, and a mesh over which to integrate.
+ 
+\end_layout
+
+\begin_layout Standard
+[[XXX: more notes here]]
+\end_layout
+
+\begin_layout Chapter
+Examples
+\end_layout
+
+\begin_layout Standard
+[[In this chapter offer various case studies as examples.
+ Explain how to download the sample data, and provide the exact commands
+ to run on that data.
+ Show various visualization techniques for the output residuals.
+ Some of these comparisons are targetted to be incorporated as examples
+ for cigma-1.0 release.
+ Preview images are to be included in a separtae lyx file.]]
+\end_layout
+
+\begin_layout Standard
+[[5.1 Sequence of meshes -- give 2d and 3d examples using a sequence of meshes
+ with decreasing $h$ (or increasing $p$)]]
+\end_layout
+
+\begin_layout Standard
+[[5.2 Finite element vs.
+ Finite element comparison -- pylith strikeslip benchmark for 3d example
+ (hex vs tet)]]
+\end_layout
+
+\begin_layout Standard
+[[5.3 Finite element vs.
+ Analytic -- gale vs analytic benchmark for 2d example, pylith vs disloc3d
+ benchmark for 3d example]]
+\end_layout
+
+\begin_layout Standard
+[[5.4 Spectral vs.
+ Finite element -- hc vs citcoms for 3d example]]
+\end_layout
+
+\begin_layout Standard
+[[5.5 Spectral vs.
+ Analytic -- magma vs benchmarks]]
+\end_layout
+
+\begin_layout Standard
+[[5.6 Spectral vs.
+ Analytic -- MAG vs analytic benchmark]]
+\end_layout
+
+\begin_layout Section
+Convergence of Global Residual
+\end_layout
+
+\begin_layout Standard
+XXX: Transfer more notes...
+\end_layout
+
+\begin_layout Standard
+[[Quick plot of h-sequence of meshes generated with gmsh]]
+\end_layout
+
+\begin_layout Standard
+[[Here, reproduce (similar?) convergence results as in Jasak H.'s Error analysis
+ and estimation PhD thesis (chapter 4, pg 210)...XXX: add to refs!]]
+\end_layout
+
+\begin_layout Section
+Comparing two distinct finite element discretizations
+\end_layout
+
+\begin_layout Standard
+XXX: transfer notes
+\end_layout
+
+\begin_layout Standard
+[[Copy description of pylith from its manual]]
+\end_layout
+
+\begin_layout Standard
+[[Describing benchmark problem being solved...(only strikeslip benchmark, so
+ cut discussion about the reverse slip benchmark]]
+\end_layout
+
+\begin_layout Section
+Comparing against analytic solution
+\end_layout
+
+\begin_layout Standard
+XXX: transfer notes...
+\end_layout
+
+\begin_layout Standard
+[[Describing okada disloc3d solution from paper (add okada paper to refs!)]]
+\end_layout
+
+\begin_layout Standard
+[[Describing (extract -> eval -> compare) command sequence]]
+\end_layout
+
+\begin_layout Standard
+[[Describing separate evaluation step using disloc3d executable]]
+\end_layout
+
+\begin_layout Bibliography
+\begin_inset LatexCommand bibitem
+key "key-1"
+
+\end_inset
+
+[[XXX: Add new refs here]]
+\end_layout
+
+\end_body
+\end_document

