[cig-commits] r7103 - cs/cigma/trunk/doc/manual

sue at geodynamics.org sue at geodynamics.org
Fri Jun 8 12:17:59 PDT 2007 

Author: sue
Date: 2007-06-08 12:17:58 -0700 (Fri, 08 Jun 2007)
New Revision: 7103

Modified:
   cs/cigma/trunk/doc/manual/cigma.lyx
Log:
added usage content and one appendix

Modified: cs/cigma/trunk/doc/manual/cigma.lyx
===================================================================
--- cs/cigma/trunk/doc/manual/cigma.lyx	2007-06-08 18:26:59 UTC (rev 7102)
+++ cs/cigma/trunk/doc/manual/cigma.lyx	2007-06-08 19:17:58 UTC (rev 7103)
@@ -68,7 +68,7 @@
 \newline
 Luis Armendariz
 \newline
-Version 1.0
+Version 0.9
 \end_layout
 
 \begin_layout Date
@@ -130,16 +130,14 @@
 \end_layout
 
 \begin_layout Section
-Who Will Use CIGMA?
+About CIGMA
 \end_layout
 
 \begin_layout Standard
-The main audience for CIGMA is research scientists interested in ???????.
- Examples of problems that can be solved are the development of tectonic
- structure associated with extension and compression, especially where localizat
-ion is important.
- You do not have to be an expert in finite element analysis or scientific
- computing to use this software.
+The CIG Model Analyzer (CIGMA) is a suite of tools intended to simplify
+ the process of comparing numerical solutions.
+ CIG has developed CIGMA in response to community demand by __???___.
+ The code is being released under the GNU General Public License.
 \end_layout
 
 \begin_layout Section
@@ -147,11 +145,13 @@
 \end_layout
 
 \begin_layout Standard
+TODO: Should we adapt the following or remove it altogether? 
+\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.
- The underlying C code for the finite element package was donated to CIG
- in July of 2005.
  A number of individuals have contributed a significant portion of their
  careers toward the development of Gale.
  It is essential that you recognize these individuals in the normal scientific
@@ -181,88 +181,621 @@
 \end_layout
 
 \begin_layout Standard
-The code was originally developed by the Victorian Partnership for Advanced
- Computing (VPAC) and Louis Moresi's group at Monash University.
- Walter Landry of CIG and Luke Hodkinson of VPAC have enhanced the code
- to satisfy the requirements of the long-term tectonics community.
- Roger Buck, Gus Correa, and Robert Bialas from the Lamont-Doherty Earth
- Observatory, Columbia University, provided valuable user testing.
- The Gale team requests that in your oral presentations and in your papers
- that you indicate your use of this code and acknowledge the authors of
- the code, 
+CIG requests that in your oral presentations and in your papers that you
+ indicate your use of this code and acknowledge the authors of the code
+ and 
 \begin_inset LatexCommand \htmlurl[CIG]{www.geodynamics.org}
 
 \end_inset
 
-, 
-\begin_inset LatexCommand \htmlurl[Victoria Partnership for Advanced Computing]{www.vpac.org}
+.
+\end_layout
 
-\end_inset
+\begin_layout Section
+Support
+\end_layout
 
-, and 
-\begin_inset LatexCommand \htmlurl[Monash University]{www.monash.edu}
+\begin_layout Standard
+CIGMA development is supported by a grant from the National Science Foundation
+ to CIG, managed by the California Institute of Technology.
+ 
+\end_layout
 
-\end_inset
+\begin_layout Chapter
+Components
+\end_layout
 
-.
+\begin_layout Section
+Design Goals
 \end_layout
 
+\begin_layout Standard
+CIGMA was developed with the following design goals in mind:
+\end_layout
+
+\begin_layout Standard
+TODO
+\end_layout
+
 \begin_layout Section
-About CIGMA
+Object Registry
 \end_layout
 
 \begin_layout Standard
-Gale is a parallel, two- or three-dimensional, implicit finite element code
- that solves problems related to orogenesis, rifting, and subduction with
- coupling to surface erosion models.
- Gale uses a hybrid particle-in-cell scheme which combines a deformable
- mesh of computational points and a dense arrangement of mobile material
- points.
- The boundaries of the deformable mesh conform to the boundaries of the
- material as the simulation progresses, but the interior is constrained
- to remain as regular as possible.
- The particles track history-dependent properties such as strain for strain-soft
-ening materials.
- This allows Gale to simulate  problems with large deformations and irregular
- boundaries.
+To reduce the number of command-line options you need to specify, CIGMA
+ will remember objects you have referenced in the past.
+ This information will be kept in the following database
 \end_layout
 
+\begin_layout LyX-Code
+$HOME/.cigma/registry.db 
+\end_layout
+
 \begin_layout Standard
-CIG has developed Gale in response to community demand by building on existing
- work by VPAC and Louis Moresi's group at Monash University.
- The code is being released under the GNU General Public License.
+If this file does not exist, it will be created whenever you attempt to
+ register a particular object.
 \end_layout
 
+\begin_layout Standard
+The following objects can be registered in the database
+\end_layout
+
+\begin_layout Itemize
+models
+\end_layout
+
+\begin_layout Itemize
+meshes
+\end_layout
+
+\begin_layout Itemize
+rules
+\end_layout
+
+\begin_layout Itemize
+fields
+\end_layout
+
+\begin_layout Itemize
+elements
+\end_layout
+
 \begin_layout Section
-Support
+Model Metadata
 \end_layout
 
 \begin_layout Standard
-Gale development is supported by a grant from the National Science Foundation
- to CIG, managed by the California Institute of Technology.
- However, most of the software components below Gale have been developed
- by the Victoria Partnership for Advanced Computing (VPAC) and Monash University.
+Each model keeps a certain amount of metadata.
+ The following HDF5 attributes are defined:
 \end_layout
 
-\begin_layout Chapter
-Numerical Methods
+\begin_layout Itemize
+uuid - unique id for 
 \end_layout
 
+\begin_layout Itemize
+mesh_id
+\end_layout
+
 \begin_layout Section
-Discretization
+FE Metadata
 \end_layout
 
+\begin_layout Standard
+In order to accept a general finite element space, 
+\end_layout
+
+\begin_layout LyX-Code
+struct fe_space {
+\end_layout
+
+\begin_layout LyX-Code
+int nsd;
+\end_layout
+
+\begin_layout LyX-Code
+int ndim;
+\end_layout
+
+\begin_layout LyX-Code
+int ndof;
+\end_layout
+
+\begin_layout LyX-Code
+shape_fn *N;
+\end_layout
+
+\begin_layout LyX-Code
+shape_fn *dN;
+\end_layout
+
+\begin_layout LyX-Code
+};
+\end_layout
+
+\begin_layout LyX-Code
+
+\end_layout
+
+\begin_layout LyX-Code
+void fe_init();
+\end_layout
+
+\begin_layout LyX-Code
+void fe_jacobian(fe_space *fe, double *x, double *xi, double *J);
+\end_layout
+
+\begin_layout LyX-Code
+void fe_tabulate(fe_space *fe, double *xs, double npts, double *tab);
+\end_layout
+
+\begin_layout LyX-Code
+void fe_eval(fe_space *fe, double *dof, double *xi, double *val);
+\end_layout
+
+\begin_layout LyX-Code
+void fe_batch_eval(fe_space *fe, double *dof, double *tab, int npts, double
+ *vals);
+\end_layout
+
+\begin_layout Standard
+There are two builtin finite element spaces called tet4 and hex8.
+ The rest can be loaded dynamically from the following directories
+\end_layout
+
+\begin_layout LyX-Code
+$HOME/.cigma/fe/
+\end_layout
+
+\begin_layout LyX-Code
+/etc/cigma/fe/
+\end_layout
+
+\begin_layout Standard
+If you specify a function space called foo, cigma will search for libfoo.so
+ in the above directories, and call foo_init() to initialize any required
+ parameters
+\end_layout
+
+\begin_layout Section
+Analytic Solutions
+\end_layout
+
+\begin_layout LyX-Code
+struct fn_space {
+\end_layout
+
+\begin_layout LyX-Code
+    int nsd;
+\end_layout
+
+\begin_layout LyX-Code
+    int ndim;
+\end_layout
+
+\begin_layout LyX-Code
+    eval_t *call;
+\end_layout
+
+\begin_layout LyX-Code
+    eval_t *batch_call;
+\end_layout
+
+\begin_layout LyX-Code
+};
+\end_layout
+
+\begin_layout LyX-Code
+
+\end_layout
+
+\begin_layout LyX-Code
+void fn_init();
+\end_layout
+
+\begin_layout LyX-Code
+void fn_eval(fn_space *fn, double *x, double *val);
+\end_layout
+
+\begin_layout LyX-Code
+void fn_batch_eval(fn_space *fn, double *xs, int npts, double *vals);
+\end_layout
+
+\begin_layout LyX-Code
+void fn_fini();
+\end_layout
+
+\begin_layout LyX-Code
+
+\end_layout
+
+\begin_layout LyX-Code
+Function
+\end_layout
+
+\begin_layout Section
+Available Commands
+\end_layout
+
+\begin_layout Subsection
+Principal Commands
+\end_layout
+
+\begin_layout Description
+create -
+\end_layout
+
+\begin_layout Description
+import -
+\end_layout
+
+\begin_layout Description
+extract -
+\end_layout
+
+\begin_layout Description
+eval -
+\end_layout
+
+\begin_layout Description
+diff -
+\end_layout
+
+\begin_layout Description
+project -
+\end_layout
+
+\begin_layout Subsection
+Auxiliary Commands
+\end_layout
+
+\begin_layout Description
+cube - simple discretization of the unit cube
+\end_layout
+
+\begin_layout Description
+rule - rules
+\end_layout
+
+\begin_layout Description
+mesh - querying the database
+\end_layout
+
+\begin_layout Description
+index - updating index
+\end_layout
+
+\begin_layout Description
+shell - shell
+\end_layout
+
+\begin_layout Section
+Command Line Usage
+\end_layout
+
+\begin_layout Subsection
+Creating a new model
+\end_layout
+
 \begin_layout Paragraph*
 
+\family typewriter
+cigma create model.h5:/model
 \end_layout
 
 \begin_layout Standard
-\noindent
-\align center
- 
+The above command initializes the group structure inside model.h5 on the
+ specified root group
 \end_layout
 
+\begin_layout LyX-Code
+model.h5
+\end_layout
+
+\begin_layout LyX-Code
+ `-- model (uuid)
+\end_layout
+
+\begin_layout LyX-Code
+     |-- mesh  
+\end_layout
+
+\begin_layout LyX-Code
+     |-- snapshots
+\end_layout
+
+\begin_layout LyX-Code
+      `-- variables
+\end_layout
+
+\begin_layout Standard
+It also attaches a uuid attribute to the model root
+\end_layout
+
+\begin_layout Subsection
+Importing the node coordinates
+\end_layout
+
+\begin_layout Paragraph*
+
+\family typewriter
+cigma import --coordinates --input=file --output=model.h5:/model
+\end_layout
+
+\begin_layout Standard
+The effect of this command is to create the following dataset
+\end_layout
+
+\begin_layout LyX-Code
+model.h5
+\end_layout
+
+\begin_layout LyX-Code
+`-- model
+\end_layout
+
+\begin_layout LyX-Code
+    `-- mesh
+\end_layout
+
+\begin_layout LyX-Code
+        `-- coordinates [nno x nsd]
+\end_layout
+
+\begin_layout Subsection
+Importing the node connectivity
+\end_layout
+
+\begin_layout Paragraph*
+
+\family typewriter
+cigma import --connectivity --input=file --output=model.h5:/model
+\end_layout
+
+\begin_layout Standard
+The effect of this command is to create the following dataset
+\end_layout
+
+\begin_layout LyX-Code
+model.h5
+\end_layout
+
+\begin_layout LyX-Code
+`-- model
+\end_layout
+
+\begin_layout LyX-Code
+    `-- mesh
+\end_layout
+
+\begin_layout LyX-Code
+        `-- connectivity [nel x ndof]
+\end_layout
+
+\begin_layout Subsection
+Importing field data
+\end_layout
+
+\begin_layout Paragraph
+
+\family typewriter
+cigma import --variable=velocity/0 --input=file --output=model.h5:/model
+\end_layout
+
+\begin_layout Standard
+The above command reads the input file and creates the following groups
+ and datasets
+\end_layout
+
+\begin_layout LyX-Code
+model.h5
+\end_layout
+
+\begin_layout LyX-Code
+`-- model
+\end_layout
+
+\begin_layout LyX-Code
+    |-- snapshots
+\end_layout
+
+\begin_layout LyX-Code
+    |   `-- 0
+\end_layout
+
+\begin_layout LyX-Code
+    |       `-- velocity [symlink]
+\end_layout
+
+\begin_layout LyX-Code
+    `-- variables
+\end_layout
+
+\begin_layout LyX-Code
+        `-- velocity
+\end_layout
+
+\begin_layout LyX-Code
+            `-- 0 [nno x ndim]
+\end_layout
+
+\begin_layout Subsection
+Extracting integration points
+\end_layout
+
+\begin_layout Paragraph*
+
+\family typewriter
+cigma extract --rule=qr.h5:/path/to/rule --input=model.h5:/model --output=points.h5
+:/points --elements=10000
+\end_layout
+
+\begin_layout Standard
+Given a quadrature rule and a mesh, we can map the quadrature points on
+ each reference element onto the actual domain and use these as a set of
+ common points on which to perform future comparisons.
+\end_layout
+
+\begin_layout Standard
+Memory usage can be controlled by using the --elements argument.
+\end_layout
+
+\begin_layout Subsection
+Extracting random set of points
+\end_layout
+
+\begin_layout LyX-Code
+
+\series bold
+cigma extract --random 
+\end_layout
+
+\begin_layout LyX-Code
+
+\series bold
+              --input=/path/to/model.h5:/model 
+\end_layout
+
+\begin_layout LyX-Code
+
+\series bold
+              --output=points.h5:/points
+\end_layout
+
+\begin_layout Standard
+Given a finite element mesh, we can iterate through each element and generate
+ random points on which future comparisons can be based.
+\end_layout
+
+\begin_layout Subsection
+Evaluating a field on its quadrature points
+\end_layout
+
+\begin_layout Paragraph*
+
+\family typewriter
+cigma eval --field=model.h5:/model/variables/velocity/0 --rule=qr.h5:/rule
+ --output=values.h5
+\end_layout
+
+\begin_layout Standard
+Given a finite element field and a quadrature rule, this command extracts
+ the required quadrature
+\end_layout
+
+\begin_layout Standard
+points from its associated mesh.
+\end_layout
+
+\begin_layout Subsection
+Evaluating a field on a given set of points
+\end_layout
+
+\begin_layout Paragraph*
+
+\family typewriter
+cigma eval --field=model.h5:/model/variables/velocity/0 --input=points.h5:/points
+ --output=values.h5
+\end_layout
+
+\begin_layout Standard
+Given a finite element field and a common set of points, 
+\end_layout
+
+\begin_layout Subsection
+Evalutating an external function on a set of points
+\end_layout
+
+\begin_layout Paragraph*
+
+\family typewriter
+cigma eval --field=/path/to/libfoo.so --input=model.h5:/model --output=file.h5
+\end_layout
+
+\begin_layout Standard
+If we know that our field has an analytic function representation, 
+\end_layout
+
+\begin_layout Subsection
+Compare two fields
+\end_layout
+
+\begin_layout LyX-Code
+cigma diff --first=field1.h5:/displacement/0 --second=field2.h5:/displacement/0
+\end_layout
+
+\begin_layout LyX-Code
+
+\end_layout
+
+\begin_layout LyX-Code
+cigma diff --first=model1.h5:/model/variables/velocity/0 --second=model2.h5:/model
+/variables/velocity/0
+\end_layout
+
+\begin_layout Subsection
+Create a sample mesh
+\end_layout
+
+\begin_layout Paragraph*
+
+\family typewriter
+cigma cube file.h5
+\end_layout
+
+\begin_layout Standard
+Creates two models inside the file.h5
+\end_layout
+
+\begin_layout LyX-Code
+file.h5
+\end_layout
+
+\begin_layout LyX-Code
+|-- <cube-coordinates> [nno x 3]
+\end_layout
+
+\begin_layout LyX-Code
+|-- tetmodel
+\end_layout
+
+\begin_layout LyX-Code
+|   `-- mesh
+\end_layout
+
+\begin_layout LyX-Code
+|      |-- coordinates (symlink)
+\end_layout
+
+\begin_layout LyX-Code
+|      `-- connectivity [nel x 4]
+\end_layout
+
+\begin_layout LyX-Code
+`-- hexmodel
+\end_layout
+
+\begin_layout LyX-Code
+    `-- mesh
+\end_layout
+
+\begin_layout LyX-Code
+        |-- coordinates (symlink)
+\end_layout
+
+\begin_layout LyX-Code
+        `-- connectivity [nel x 8]
+\end_layout
+
+\begin_layout LyX-Code
+
+\end_layout
+
 \begin_layout Chapter
+Numerical Methods
+\end_layout
+
+\begin_layout Chapter
 Implementation
 \end_layout
 
@@ -271,7 +804,7 @@
 \end_layout
 
 \begin_layout Standard
-You must also have pyth
+More
 \end_layout
 
 \begin_layout Section
@@ -304,10 +837,95 @@
 
 \begin_layout Chapter
 \start_of_appendix
-Code
+Text Input File Formats
 \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 the appropriate row
+ number, followed by the requisite number of columns.
+ For simplicity, the maximum line size is 1024, and lines beginning with
+ the '#' character are skipped.
+ 
+\end_layout
+
+\begin_layout Standard
+Mesh coordinates can be read from
+\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 
+\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
+
+\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
+
+\begin_layout Standard
+A generic field with ndim components would be specified by
+\end_layout
+
+\begin_layout LyX-Code
+nno ndim
+\end_layout
+
+\begin_layout LyX-Code
+1 f1 f2 f3 ..
+\end_layout
+
+\begin_layout LyX-Code
+2 f1 f2 f3 ..
+\end_layout
+
+\begin_layout LyX-Code
+...
+\end_layout
+
+\begin_layout Chapter
+Shape Functions
+\end_layout
+
+\begin_layout Standard
 \begin_inset Float figure
 placement H
 wide false

More information about the cig-commits mailing list