[cig-commits] r7722 - cs/cigma/branches/cigma-0.9b1/doc/manual
luis at geodynamics.org
luis at geodynamics.org
Fri Jul 20 10:14:55 PDT 2007
Author: luis
Date: 2007-07-20 10:14:55 -0700 (Fri, 20 Jul 2007)
New Revision: 7722
Modified:
cs/cigma/branches/cigma-0.9b1/doc/manual/cigma.lyx
Log:
Final (penultimate?) set of changes to manual
Modified: cs/cigma/branches/cigma-0.9b1/doc/manual/cigma.lyx
===================================================================
--- cs/cigma/branches/cigma-0.9b1/doc/manual/cigma.lyx 2007-07-20 15:56:18 UTC (rev 7721)
+++ cs/cigma/branches/cigma-0.9b1/doc/manual/cigma.lyx 2007-07-20 17:14:55 UTC (rev 7722)
@@ -184,16 +184,31 @@
\begin_layout Standard
In general, Cigma is intended for three types of tasks, namely (1) error
analysis, (2) benchmarking, and (3) code verification.
+
\end_layout
\begin_layout Standard
There are two ways in which Cigma can help you with error analysis.
It can take a random sampling of points inside a domain of interest and
- analyze the pointwise differences between physical fields, or it can perform
- an integration of the errors over a discretized version of the domain.
+ analyze the pointwise differences between physical fields, or otherwise
+ perform an integration of the errors over a discretized version of the
+ domain.
+ This comparison can take place even when the meshes are not compatible.
\end_layout
\begin_layout Standard
+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.
+\end_layout
+
+\begin_layout Standard
+Lastly, as an automated tool, Cigma can help developers in creating 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, particularly the
\begin_inset LatexCommand \htmlurl[Tetrahedral Mesh Comparator (TMC)]{www.sci.utah.edu/~bavoil/research/tetsimp/tmc/}
@@ -206,7 +221,7 @@
.
Cigma extends and generalizes the functionality therein to handle other
- types of elements and be able to compare vector fields.
+ types of elements as well as adding the ability to compare vector fields.
\end_layout
\begin_layout Section
@@ -259,6 +274,36 @@
\end_layout
\begin_layout Section
+Getting Help
+\end_layout
+
+\begin_layout Standard
+For help, send an e-mail to the
+\begin_inset LatexCommand \url[CIG Computational Science Mailing List]{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[CIG Mail Lists web page]{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[CIG Bug Tracker]{geodynamics.org/bugs}
+
+\end_inset
+
+.
+\end_layout
+
+\begin_layout Section
Installation from Source
\end_layout
@@ -270,6 +315,7 @@
\end_inset
.
+ This step will require the GNU C and C++ compilers.
After unpacking the source and installing the dependencies, issue the following
commands
\end_layout
@@ -282,10 +328,6 @@
$ sudo make install
\end_layout
-\begin_layout Section
-Software Dependencies
-\end_layout
-
\begin_layout Subsection
HDF5
\end_layout
@@ -408,34 +450,8 @@
\end_layout
-\begin_layout Section
-Getting Help
-\end_layout
-
\begin_layout Standard
-For help, send an e-mail to the
-\begin_inset LatexCommand \url[CIG Computational Science Mailing List]{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[CIG Mail Lists web page]{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[CIG Bug Tracker]{geodynamics.org/bugs}
-
-\end_inset
-
-.
\end_layout
\begin_layout Chapter
@@ -631,31 +647,6 @@
\end_layout
\begin_layout Section
-Design Goals
-\end_layout
-
-\begin_layout Standard
-As mentioned in the introduction, Cigma was designed with the following
- use cases in mind:
-\end_layout
-
-\begin_layout Description
-Error\InsetSpace ~
-Analysis To assist scientists in comparing two different codes, possibly
- on different meshes.
-\end_layout
-
-\begin_layout Description
-Benchmarking To help the geodynamics community agree on a standard solution
- to a specific problem.
-\end_layout
-
-\begin_layout Description
-Verification For developers to test software changes so as to ensure that
- those changes don't affect the consistency of the results.
-\end_layout
-
-\begin_layout Section
Mesh
\end_layout
@@ -735,21 +726,14 @@
\end_layout
\begin_layout Standard
-Cigma provides you with two built-in finite element spaces, along with a
- framework for inserting new types of elements.
+This release of Cigma provides you with two built-in finite element spaces
+ shown below.
+ The location of each element is indexed into a spatial database in order
+ to speed up the evaluation process.
\end_layout
-\begin_layout Subsection
-Shape Functions
-\end_layout
-
\begin_layout Standard
-Note that the shape functions have been defined on the reference-coordinate
- space.
-\end_layout
-\begin_layout Standard
-
\newpage
\end_layout
@@ -761,6 +745,10 @@
\end_layout
\begin_layout Standard
+(TODO: place image and equations side by side..)
+\end_layout
+
+\begin_layout Standard
\noindent
\align center
\begin_inset Float figure
@@ -816,6 +804,10 @@
\end_layout
\begin_layout Standard
+(TODO: place image and equations side by side..)
+\end_layout
+
+\begin_layout Standard
\noindent
\align center
\begin_inset Float figure
@@ -862,214 +854,78 @@
\end_layout
-\begin_layout Section
-Data Format
-\end_layout
-
-\begin_layout Standard
-There are various reasons to use HDF5:
-\end_layout
-
-\begin_layout Enumerate
-A common format is necessary for comparisons in order to avoid having to
- convert between formats
-\end_layout
-
-\begin_layout Enumerate
-In order to support large finite element meshes efficiently
-\end_layout
-
-\begin_layout Enumerate
-Support for metadata
-\end_layout
-
-\begin_layout Standard
-The Hierarchical Data Format (HDF) is a portable file format developed at
- the
-\begin_inset LatexCommand \htmlurl[National Center for Supercomputing Applications (NCSA)]{hdf.ncsa.uiuc.edu/HDF5}
-
-\end_inset
-
-.
- It is designed for storing, retrieving, analyzing, visualizing, and converting
- scientific data.
- The current and most popular version is HDF5, which stores multi-dimensional
- arrays together with ancillary data in a portable self-describing format.
- It uses a hierarchical structure that provides application programmers
- with a host of options for organizing how data is stored in HDF5 files.
-\end_layout
-
-\begin_layout Standard
-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.
-\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.
- The dimensions of a dataset can be either fixed or unlimited (extensible).
- The storage layout specifies how the data arrays are arranged in the file.
-\end_layout
-
-\begin_layout Section
-Field Metadata
-\end_layout
-
-\begin_layout Standard
-Each field keeps a certain amount of metadata that allows Cigma to correctly
- interpret the meaning of the field data.
-\end_layout
-
-\begin_layout Description
-MeshID a universally unique identifier (uuid) assigned to the mesh
-\end_layout
-
-\begin_layout Description
-MeshLocation the HDF5 group which contains the appropriate coordinates and
- connectivity datasets.
-\end_layout
-
-\begin_layout Description
-FunctionSpace identifies which shape functions to use for interpolating
- values inside the element.
-\end_layout
-
\begin_layout Chapter
Running Cigma
\end_layout
-\begin_layout Standard
-As a command line utility
-\end_layout
-
\begin_layout Section
-Importing data
+Comparing Two Fields
\end_layout
\begin_layout Standard
-Cigma can easily import datasets from simple text files consisting of a
- single header line followed by data.
- The header consists of two numbers, the first of which consists of the
- number of lines to read next, and the second number representing the number
- of columns to read on each line.
- Thus, after the header, each of the lines begin with an appropriate id
- number, followed by the requisite number of columns.
- For simplicity, the maximum line size is 1024, and lines beginning with
- the '#' character are skipped.
-\newline
-
-\newline
-Mesh coordinates can be specified in the following
- format
+Comparing two arbitrary finite element fields can be accomplished with
+\family typewriter
+cigma-compare
+\family default
+ command line utility, which takes a number of arguments in order to facilitate
+ writing shell scripts.
+ The comparisons always take place using the mesh of the first field.
+ Note that the first and second arguments take the special form
+\family typewriter
+\series bold
+filename:dataset
+\family default
+\series default
+.
+ Finally, the square of each of the local residual values are written to
+ the specified VTK output file as cell-based scalars.
\end_layout
-\begin_layout LyX-Code
-nno nsd
-\end_layout
-
-\begin_layout LyX-Code
-1 x1 y1 z1
-\end_layout
-
-\begin_layout LyX-Code
-2 x2 y2 z2
-\end_layout
-
-\begin_layout LyX-Code
-3 x3 y3 z3
-\end_layout
-
-\begin_layout LyX-Code
-...
-\end_layout
-
\begin_layout Standard
-Mesh connectivity with
+To use a quadrature rule for the field comparisons, you can specify arguments
+ similar to the following
\end_layout
\begin_layout LyX-Code
-nel ndof
-\end_layout
-\begin_layout LyX-Code
-1 node_1 node_2 node_3 node_4 ...
-\end_layout
+\series bold
+cigma-compare --output=squared-residuals.vtk
+\backslash
-\begin_layout LyX-Code
-2 node_1 node_2 node_3 node_4 ...
\end_layout
\begin_layout LyX-Code
-3 node_1 node_2 node_3 node_4 ...
-\end_layout
-\begin_layout LyX-Code
-...
-\end_layout
+\series bold
+ --first=field1.h5:/field1/stepN
+\backslash
-\begin_layout Standard
-A generic field with
-\family typewriter
-ndim
-\family default
- components is specified by
\end_layout
\begin_layout LyX-Code
-nno ndim
-\end_layout
-\begin_layout LyX-Code
-1 f1 f2 f3 ..
-\end_layout
+\series bold
+ --second=field2.h5:/field2/stepN
+\backslash
-\begin_layout LyX-Code
-2 f1 f2 f3 ..
\end_layout
\begin_layout LyX-Code
-...
-\end_layout
-\begin_layout Standard
-A quadrature rule may be explicitly specified by
+\series bold
+ --rule=qr.h5:/path/to/rule
\end_layout
-\begin_layout LyX-Code
-nq nsd
-\end_layout
-
-\begin_layout LyX-Code
-w1 x1 y1 z1
-\end_layout
-
-\begin_layout LyX-Code
-w2 x2 y2 z2
-\end_layout
-
-\begin_layout LyX-Code
-...
-\end_layout
-
\begin_layout Standard
-The comma
+Alternatively, to perform a pointwise comparison at random sample points
+ inside each element in the first mesh, you can use arguments similar to
+ the following
\end_layout
\begin_layout LyX-Code
\series bold
-cigma-import.py --output=model.h5:/model
+cigma-compare --output=squared-residuals.vtk
\backslash
\end_layout
@@ -1077,7 +933,7 @@
\begin_layout LyX-Code
\series bold
- --coordinates=mesh.coord
+ --first=field1.h5:/field1/stepN
\backslash
\end_layout
@@ -1085,7 +941,7 @@
\begin_layout LyX-Code
\series bold
- --connectivity=mesh.connect
+ --second=field2.h5:/field2/stepN
\backslash
\end_layout
@@ -1093,26 +949,62 @@
\begin_layout LyX-Code
\series bold
- --variable=velocity/step00010
-\backslash
-
+ --samples-per-element=1
\end_layout
\begin_layout LyX-Code
-\series bold
- --variable-data=velocity.10.time
\end_layout
\begin_layout Section
-Data Layout
+Input Format
\end_layout
\begin_layout Standard
-The effect of this command is to create an HDF5 file with the following
- structure:
+The Hierarchical Data Format (HDF) is a portable file format developed at
+ the
+\begin_inset LatexCommand \htmlurl[National Center for Supercomputing Applications (NCSA)]{hdf.ncsa.uiuc.edu/HDF5}
+
+\end_inset
+
+.
+ It is designed for storing, retrieving, analyzing, visualizing, and converting
+ scientific data.
+ The current and most popular version is HDF5, which stores multi-dimensional
+ arrays together with ancillary data in a portable self-describing format.
+ It uses a hierarchical structure that provides application programmers
+ with a host of options for organizing how data is stored in HDF5 files.
\end_layout
+\begin_layout Standard
+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.
+\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
+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.
+ A typical Cigma HDF5 file has the following structure:
+\end_layout
+
\begin_layout LyX-Code
model.h5
\end_layout
@@ -1155,103 +1047,117 @@
__ step00010 [nno x ndim]
\end_layout
-\begin_layout LyX-Code
+\begin_layout Standard
+You have a certain amount of flexibility in grouping your own data.
+ Cigma will only require you to provide a small amount of metadata on your
+ field and mesh datasets, described below:
+\end_layout
+\begin_layout Description
+MeshID a universally unique identifier (uuid) assigned to the mesh for easily
+ distinguishing identical meshes
\end_layout
-\begin_layout Section
-Comparing Two Fields
+\begin_layout Description
+MeshLocation points to the HDF5 group which contains the appropriate coordinates
+ and connectivity datasets.
\end_layout
-\begin_layout Standard
-Comparing two arbitrary finite element fields can be accomplished with
-\family typewriter
-cigma-compare
-\family default
- command line utility.
- The comparisons always take place using the mesh of the first field.
+\begin_layout Description
+FunctionSpace string identifier to determine which shape functions to use
+ for interpolating values inside the element.
\end_layout
+\begin_layout Subsection
+Importing Data
+\end_layout
+
\begin_layout Standard
-To use a quadrature rule for the field comparisons, you can specify arguments
- similar to the following
+In its source distribution, Cigma provides two examples for importing data
+ from two different codes into its standard HDF5 format
+\newline
+
+\newline
+Mesh coordinates
+ can be specified in the following format
\end_layout
\begin_layout LyX-Code
+nno nsd
+\end_layout
-\series bold
-cigma-compare --output=squared-residuals.vtk
-\backslash
+\begin_layout LyX-Code
+1 x1 y1 z1
+\end_layout
+\begin_layout LyX-Code
+2 x2 y2 z2
\end_layout
\begin_layout LyX-Code
+3 x3 y3 z3
+\end_layout
-\series bold
- --first=field1.h5:/field1/stepN
-\backslash
+\begin_layout LyX-Code
+...
+\end_layout
+\begin_layout Standard
+Mesh connectivity with
\end_layout
\begin_layout LyX-Code
+nel ndof
+\end_layout
-\series bold
- --second=field2.h5:/field2/stepN
-\backslash
+\begin_layout LyX-Code
+1 node_1 node_2 node_3 node_4 ...
+\end_layout
+\begin_layout LyX-Code
+2 node_1 node_2 node_3 node_4 ...
\end_layout
\begin_layout LyX-Code
+3 node_1 node_2 node_3 node_4 ...
+\end_layout
-\series bold
- --rule=qr.h5:/path/to/rule
+\begin_layout LyX-Code
+...
\end_layout
\begin_layout Standard
-Alternatively, to perform a pointwise comparison at random sample points
- inside each element in the first mesh, you can use arguments similar to
- the following
+A generic field with
+\family typewriter
+ndim
+\family default
+ components is specified by
\end_layout
\begin_layout LyX-Code
-
-\series bold
-cigma-compare --output=squared-residuals.vtk
-\backslash
-
+nno ndim
\end_layout
\begin_layout LyX-Code
-
-\series bold
- --first=field1.h5:/field1/stepN
-\backslash
-
+1 f1 f2 f3 ..
\end_layout
\begin_layout LyX-Code
+2 f1 f2 f3 ..
+\end_layout
-\series bold
- --second=field2.h5:/field2/stepN
-\backslash
-
+\begin_layout LyX-Code
+...
\end_layout
\begin_layout LyX-Code
-\series bold
- --samples-per-element=1
\end_layout
\begin_layout LyX-Code
\end_layout
-\begin_layout Standard
-The square of each of the local residual values are written to the specified
- VTK output file as cell-based scalars.
-\end_layout
-
\begin_layout Chapter
Visualization
\end_layout
@@ -1333,7 +1239,9 @@
) with sides having a length of 24 km, consisting of two layers of different
material types.
- The top layer is nearly elastic while the bottom layer is viscoelastic.
+ The top layer is nearly elastic while the bottom layer follows viscoelastic
+ relaxation of stresses.
+ Bottom and side displacements are set to the elastic analytic solution.
A symmetric boundary condition is also imposed on the y=0 plane.
\end_layout
@@ -2191,10 +2099,14 @@
\end_layout
-\begin_layout Section
+\begin_layout Subsection
Jacobian Matrix
\end_layout
+\begin_layout Standard
+Recall the definition of the Jacobian matrix:
+\end_layout
+
\begin_layout LyX-Code
\end_layout
@@ -2277,11 +2189,19 @@
\end_layout
-\begin_layout Paragraph*
-Tet4
+\begin_layout LyX-Code
+
\end_layout
\begin_layout Standard
+Applying these to our shape functions on a tetrahedron, we obtain
+\end_layout
+
+\begin_layout LyX-Code
+
+\end_layout
+
+\begin_layout Standard
\begin_inset Tabular
<lyxtabular version="3" rows="5" columns="5">
<features>
More information about the cig-commits
mailing list