[cig-commits] r5860 - in long/3D/Gale/trunk: . documentation
walter at geodynamics.org
walter at geodynamics.org
Tue Jan 23 08:17:49 PST 2007
Author: walter
Date: 2007-01-23 08:17:48 -0800 (Tue, 23 Jan 2007)
New Revision: 5860
Modified:
long/3D/Gale/trunk/
long/3D/Gale/trunk/documentation/gale.lyx
Log:
r1473 at earth: boo | 2007-01-23 08:15:53 -0800
Numerous updates to the manual
Property changes on: long/3D/Gale/trunk
___________________________________________________________________
Name: svk:merge
- 3a629746-de10-0410-b17b-fd6ecaaa963e:/cig:1467
+ 3a629746-de10-0410-b17b-fd6ecaaa963e:/cig:1473
Modified: long/3D/Gale/trunk/documentation/gale.lyx
===================================================================
--- long/3D/Gale/trunk/documentation/gale.lyx 2007-01-22 23:35:32 UTC (rev 5859)
+++ long/3D/Gale/trunk/documentation/gale.lyx 2007-01-23 16:17:48 UTC (rev 5860)
@@ -154,11 +154,11 @@
\begin_layout Standard
The main audience for Gale is research scientists interested in modeling
- the tectonic processes on long time scales.
+ tectonic processes on long time scales.
Examples of problems that can be solved are the development of tectonic
structure associated with extension and compression, especially where localizat
ion is important.
- One should not have to be an expert in finite element analysis or scientific
+ You do not have to be an expert in finite element analysis or scientific
computing to use this software.
\end_layout
@@ -207,8 +207,8 @@
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 paper
- acknowledgements that you indicate your use of this code, the authors of
+ 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,
\begin_inset LatexCommand \htmlurl[CIG]{www.geodynamics.org}
@@ -233,7 +233,7 @@
\begin_layout Standard
Gale development is supported by a grant from the National Science Foundation
- to CIG, managed by the Caltech Institute of Technology.
+ 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.
\end_layout
@@ -285,6 +285,20 @@
\end_layout
\begin_layout Subsection
+Units
+\end_layout
+
+\begin_layout Standard
+Gale has no internal knowledge of units.
+ So if you tell Gale that a box is 10 units across, it does not know or
+ care whether it is 10 cm or 10 km.
+ You only have to make sure that you are self consistent.
+ So if you give velocities in cm/year, then make sure that, for example,
+ your viscosities and lengths also use cm and years.
+
+\end_layout
+
+\begin_layout Subsection
Basic Equations
\end_layout
@@ -358,9 +372,6 @@
\begin_layout Standard
Note that there is no explicit time dependency in the momentum equation
-\end_layout
-
-\begin_layout Standard
\begin_inset LatexCommand \ref{eq:simple momentum conservation}
\end_inset
@@ -390,7 +401,7 @@
\end_inset
-, we assume a simple Linear viscous material.
+, we assume a simple Newtonian fluid.
This allows us to write
\begin_inset Formula $\tau$
\end_inset
@@ -506,23 +517,17 @@
\end_inset
-.
- It should be noted that CIG's finite element code CitCom used to solve
- mantle convection problems uses the same approach as in Equations
-\begin_inset LatexCommand \ref{eq:matrix form}
-\end_inset
+\begin_inset Foot
+status open
- and
-\begin_inset LatexCommand \ref{eq:final simple elliptic}
+\begin_layout Standard
+CIG's finite element code CitCOM also uses the same equations and approach
+ to solve problems in mantle convection.
+\end_layout
\end_inset
-
-\begin_inset LatexCommand \cite{key-4}
-
-\end_inset
-
.
\end_layout
@@ -661,15 +666,18 @@
primarily at Dalhousie University in Canada.
It solves a Stokes flow problem on an Eulerian grid and uses a Lagrangian
grid to track material properties and to integrate strain.
- This method has seen much use in crustal and lithospheric deformation problems
- such as orogenesis, rifting, and subduction, as well as in coupling to
- surface erosion models, and has been employed for deeper mantle dynamics
+ This method has seen a great deal of use in crustal and lithospheric deformatio
+n problems such as orogenesis, rifting, and subduction, as well as in coupling
+ to surface erosion models, and has been employed for deeper mantle dynamics
problems.
Gale is an open-source code that we hope will be at least as useful as
- SOPALE and MicroFEM for addressing these research areas
-\color red
-[TODO: References? - MG]
-\color default
+ SOPALE and MicroFEM
+\begin_inset LatexCommand \cite{key-1}
+
+\end_inset
+
+ for addressing these research areas
+\color none
, with the addition of 3D capability.
In the future, Gale will run benchmarks such as extension and shortening,
as well as the traditional subduction model as shown in Fig.
@@ -766,40 +774,32 @@
\end_layout
\begin_layout Section
-Introduction
+Binaries
\end_layout
\begin_layout Standard
-To install Gale, you follow the procedure that is commonly used with other
- open source software packages.
- First, download the binaries for your platform or the source package (in
- the form of a compressed
-\family typewriter
-tar
-\family default
- file) available at the
-\begin_inset LatexCommand \htmlurl[CIG Software Packages: Long-Term Crustal Dynamics: Gale]{geodynamics.org/cig/software/packages/long/gale/}
+If you do not need to run on parallel machines, the easiest way to install
+ Gale is to download binaries for your platform from the
+\begin_inset LatexCommand \htmlurl[Gale website]{geodynamics.org/cig/software/packages/long/gale/}
\end_inset
.
- After unpacking the source, you run an .xml script to configure Gale for
- your system.
-
+ Then you can run Gale from the command line or DOS prompt.
+ CIG provides binaries for Linux, Mac OS X (10.4 or greater), and Windows
+ (2000 and XP).
\end_layout
-\begin_layout Standard
-Advanced users and software developers may be interested in downloading
- the latest Gale source code directly from the CIG source code repository,
- instead of using the prepared source package; see Section
-\begin_inset LatexCommand \ref{sec:Downloading-the-Code}
+\begin_layout Section
+Building from Source
+\end_layout
-\end_inset
-
- later in this chapter.
+\begin_layout Standard
+Only read this if the binaries are not sufficient for you.
+
\end_layout
-\begin_layout Section
+\begin_layout Subsection
System Requirements
\end_layout
@@ -837,12 +837,12 @@
Enterprise Linux 3 (EM64T).
\end_layout
-\begin_layout Section
+\begin_layout Subsection
Dependencies
\end_layout
\begin_layout Standard
-In order to install Gale, you must have the headers and development libraries
+In order to build Gale, you must have the headers and development libraries
for
\end_layout
@@ -851,7 +851,7 @@
\end_layout
\begin_layout Itemize
-Petsc 2.3.0 or 2.3.1, but not 2.3.2
+PETSc 2.3.2
\end_layout
\begin_layout Itemize
@@ -860,12 +860,12 @@
\begin_layout Standard
You must also have python 2.2.1 or greater installed.
- If you do not already have MPI, then in many cases Petsc can install a
+ If you do not already have MPI, then in many cases PETSc can install a
version for you.
- Installing Petsc also requires a Blas/Lapack implementation.requires
+ Installing PETSc also requires a Blas/Lapack implementation.
\end_layout
-\begin_layout Section
+\begin_layout Subsection
\begin_inset LatexCommand \label{sec:Downloading-the-Code}
\end_inset
@@ -874,12 +874,25 @@
\end_layout
\begin_layout Standard
-Gale can be downloaded at
-\begin_inset LatexCommand \htmlurl[CIG Software Packages: Long-Term Crustal Dynamics: Gale]{geodynamics.org/cig/software/packages/long/gale/}
+You can get the source for the latest release from the
+\begin_inset LatexCommand \htmlurl[Gale website]{geodynamics.org/cig/software/packages/long/gale/}
\end_inset
- as a tar file or via the CIG Subversion software repository.
+.
+ In that tarball is the file INSTALL.
+ For some platforms, there are platform-specific instructions.
+ Generally, the hardest part is not installing Gale itself, but PETSc.
+\end_layout
+
+\begin_layout Subsubsection
+Source Code Repository (Experts Only)
+\end_layout
+
+\begin_layout Standard
+Advanced users and software developers may be interested in downloading
+ the latest Gale source code directly from the CIG source code repository,
+ instead of using the prepared source package.
To check whether you have a subversion client installed on your machine,
type:
\end_layout
@@ -911,251 +924,11 @@
svn checkout http://geodynamics.org/svn/cig/long/3D/Gale/trunk Gale
\end_layout
-\begin_layout Section
-Installation
-\end_layout
-
-\begin_layout Standard
-Installation instructions are given below as well as in the tarball in the
- file INSTALL.
- For some platforms (Linux, Mac OS X, and Windows 2000/XP), binaries are
- available.
-
-\end_layout
-
-\begin_layout Subsection
-Linux
-\end_layout
-
-\begin_layout Standard
-Running the Linux binary version of Gale requires a 32-bit compatible machine
- with GLIBC 2.2 or later.
-\end_layout
-
-\begin_layout Enumerate
-\noindent
-Download the
-\family typewriter
-\size footnotesize
-
-\begin_inset LatexCommand \htmlurl[tarball]{www.geodynamics.org/cig/software/packages/long/gale/Gale-Linux-1.0.1.tar.gz}
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Enumerate
-\noindent
-Unpack the tarball in a suitable location
-\newline
-
-\newline
-
-\family typewriter
-\color black
-$ tar -zxvf Gale-Linux-1.1.tar.gz
-\end_layout
-
-\begin_layout Enumerate
-Add
-\family typewriter
-Gale/bin
-\family default
- to your
-\family typewriter
-PATH
-\family default
-.
- You will likely want to add something like
-\newline
-
-\newline
-
-\family typewriter
-PATH=${PATH}:
-\emph on
-replace_with_absolute_path
-\emph default
-/Gale/bin
-\family default
-
-\newline
-
-\newline
-to your
-\family typewriter
-.bashrc
-\family default
-file (if you are using bash as your shell) or the equivalent to your
-\family typewriter
-.cshrc
-\family default
- file (if you are using tcsh as your shell).
-
-\end_layout
-
-\begin_layout Enumerate
-\noindent
-Add
-\family typewriter
-Gale/lib
-\family default
- to your
-\family typewriter
-LD_LIBRARY_PATH
-\family default
-.
- You will likely want to add something like
-\size footnotesize
-
-\newline
-
-\newline
-
-\family typewriter
-export LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:
-\emph on
-replace_with_absolute_path
-\emph default
-/Gale/lib
-\family default
-\size default
-
-\newline
-
-\newline
-to your
-\family typewriter
-.bashrc
-\family default
- file (if you are using bash as your shell) or the equivalent to your
-\family typewriter
-.cshrc
-\family default
- file (if you are using tcsh as your shell).
-
-\end_layout
-
-\begin_layout Enumerate
-At the command line, navigate to the install directory and run
-\end_layout
-
\begin_layout LyX-Code
-./Gale-Linux-1.1 extension.xml
-\end_layout
-\begin_layout Subsection
-Mac OS X
\end_layout
-\begin_layout Standard
-The OS X binary version was built to run on the Macintosh PowerPC architecture
- with OS X version 10.4.
- The binary will run on the Macintosh Intel architecture, but only in emulation
- mode (i.e., rather slowly).
-\end_layout
-
-\begin_layout Enumerate
-Download the
-\begin_inset LatexCommand \htmlurl[disk image]{www.geodynamics.org/cig/software/packages/long/gale/Gale-Mac-1_1.dmg}
-
-\end_inset
-
-.
-
-\end_layout
-
-\begin_layout Enumerate
-Double click on the disk image to mount the disk.
-
-\end_layout
-
-\begin_layout Enumerate
-Double click on the disk and copy the
-\family typewriter
-PyLith
-\family default
- folder to a suitable location.
-
-\end_layout
-
-\begin_layout Enumerate
-At the command line, navigate to the install directory and run
-\end_layout
-
-\begin_layout LyX-Code
-./Gale-Mac_1_1 extension.xml
-\end_layout
-
-\begin_layout Subsection
-Windows
-\end_layout
-
-\begin_layout Standard
-This Windows binary version of PyLith should be compatible with Windows
- NT, Windows 2000, and Windows XP.
-\end_layout
-
-\begin_layout Enumerate
-Download the
-\begin_inset LatexCommand \htmlurl[installer]{www.geodynamics.org/cig/software/packages/long/gale/Gale-Win32-1_1.zip}
-
-\end_inset
-
-.
-
-\end_layout
-
-\begin_layout Enumerate
-Unpack the .zip file you just downloaded
-\end_layout
-
-\begin_layout Enumerate
-At the command line, navigate to the install directory and run
-\end_layout
-
-\begin_layout LyX-Code
-./Gale-Win32-1_1 extension.xml
-\end_layout
-
\begin_layout Section
-Building Using Source Tarball
-\end_layout
-
-\begin_layout Standard
-For building from source, platform-specific installation instructions are
- given for Mac OS X, Windows, RedHat Fedora Core 5, OpenSuse 10.0, and Debian
- stable, testing, and unstable in the tarball in the file
-\family typewriter
-INSTALL
-\family default
-.
- Generally, the hardest part is not installing Gale itself, but PETSc.The
- stable version of the Gale source code is available at
-\newline
-
-\family typewriter
-
-\newline
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-cig/software/Repository/cig/long/3D/Gale/trunk
-\family default
-
-\newline
-
-\newline
-in the
-\begin_inset LatexCommand \htmlurl[Geodynamics Subversion Repository]{www.geodynamics.org/cig/software/Repository/}
-
-\end_inset
-
-.
-\end_layout
-
-\begin_layout Section
Support
\end_layout
@@ -1263,19 +1036,19 @@
\family default
directory.
There are also examples of shortening, subduction, relaxation of a sinusoid,
- and a fountain.
+ and stress boundary conditions.
\end_layout
\begin_layout Standard
-Since Gale uses PETSc for solving the equation, so you can easily change
- which solver to use.
+Since Gale uses PETSc for solving the equation, you can easily change which
+ solver to use.
The default solver is preconditioned conjugate gradient.
There are an enormous number of PETSc options that the expert user may
want to explore.
- But as a simple example, to use a direct LU solve, simply append arguments
- to the command line
-\color red
-[TODO: sentence awkward, how to fix?]
+ But as a simple example, on serial machines, a direct solve can be much
+ faster than the default iterative solver.
+ So to use a direct LU solve, you only need to append arguments to the command
+ line
\end_layout
\begin_layout LyX-Code
@@ -1312,7 +1085,7 @@
\end_layout
\begin_layout Standard
-In the output directory you will find a number of
+Gale will output a number of
\family typewriter
.dat
\family default
@@ -1320,80 +1093,55 @@
\family typewriter
.txt
\family default
- files that
-\color red
-[TODO:
-\begin_inset Quotes sld
-\end_inset
-
-Please say at least a few words
-\begin_inset Quotes srd
-\end_inset
-
- -MG]
-\color default
+ files in the output directory
+\color none
.
- See Appendix
+ Their format is described fully in Appendix
\begin_inset LatexCommand \ref{cha:Output-File-Format}
\end_inset
- for more information.
-\end_layout
-
-\begin_layout Standard
-
-\color red
-[TODO:
-\begin_inset Quotes sld
-\end_inset
-
-Is this a visualization section or visualization chapter?
-\begin_inset Quotes srd
-\end_inset
-
- -MG]
-\end_layout
-
-\begin_layout Standard
-You can visualise the output using the Matlab scripts found in the
+.
+ Gale includes a number of Matlab visualization scripts in the
\family typewriter
tools/
\family default
directory.
- The scripts also work with Octave and Octave B.
- Also, you can set the DumpSwarm plugin (see Section
+ The scripts also work with Octave, a free Matlab clone.
+ Furthermore, you can set the DumpSwarm plugin (see Section
\begin_inset LatexCommand \ref{sec:.txt-Files-(Particle}
\end_inset
-) to directly output either vtk files which you can visualize with either
-
-\begin_inset LatexCommand \htmlurl[MayaVI]{mayavi.sf.net}
-
-\end_inset
-
-,
+) to directly output either
+\family typewriter
+.vtk
+\family default
+ files or
+\family typewriter
+.csv
+\family default
+ files.
+ You can visualize
+\family typewriter
+.vtk
+\family default
+ files with either
\begin_inset LatexCommand \htmlurl[ParaView]{paraview.org}
\end_inset
-, or csv files which are simple to visualize with a spreadsheet program
- such as Excel.
-\end_layout
+ (recommended) or
+\begin_inset LatexCommand \htmlurl[MayaVI]{mayavi.sf.net}
-\begin_layout Standard
-
-\color red
-[TODO:
-\begin_inset Quotes sld
\end_inset
-What about default values? Are there any?
-\begin_inset Quotes srd
-\end_inset
-
- -MG]
+.
+ You can visualize
+\family typewriter
+.csv
+\family default
+ files with a spreadsheet program such as Excel.
\end_layout
\begin_layout Section
@@ -1523,20 +1271,6 @@
</struct>
\end_layout
-\begin_layout Standard
-
-\color red
-[TODO:
-\begin_inset Quotes sld
-\end_inset
-
-Should the above coordinates be shown in a line diagram?
-\begin_inset Quotes srd
-\end_inset
-
- -MG]
-\end_layout
-
\end_deeper
\begin_layout Enumerate
Then we set the material's viscosity
@@ -1560,18 +1294,12 @@
\end_layout
\begin_layout Standard
-
-\color red
-[TODO:
-\begin_inset Quotes sld
+Remember that Gale has no internal knowledge of units, so if we think of
+ everything in cgs, then this gives a viscosity of
+\begin_inset Formula $1\frac{g}{cm^{2}\, s}$
\end_inset
-RE: 1.0 immediately above, does Gale work with dimensional or nondimensional
- variables?
-\begin_inset Quotes srd
-\end_inset
-
- -MG]
+.
\end_layout
\end_deeper
@@ -1662,10 +1390,7 @@
\begin_layout Standard
The input file you have just created is valid, but Gale will complain if
- you try to run it because there are no dynamics.
-
-\color red
-[TODO: need more intro here]
+ you try to run it because nothing is moving.
\end_layout
\begin_layout Enumerate
@@ -1731,7 +1456,7 @@
\color red
Warning:
\series default
-\color default
+\color none
There are several
\family typewriter
WallVC
@@ -1811,21 +1536,6 @@
\end_layout
\begin_layout Standard
-
-\color red
-[TODO:
-\begin_inset Quotes sld
-\end_inset
-
-All of the following examples seem to be EXCELLENT but all would benefit
- from more intro discussion, showing results, and then explaining the results
-\begin_inset Quotes srd
-\end_inset
-
- - MG]
-\end_layout
-
-\begin_layout Standard
Now we want to make the bottom boundary move differently, and not just have
the material slide along.
In particular, we want to simulate a box like in Figure
@@ -1868,21 +1578,6 @@
\end_layout
-\begin_layout Standard
-
-\color red
-[TODO:
-\begin_inset Quotes sld
-\end_inset
-
-Wouldn't it be better to include all these as cookbook1.xml etc., so that
- there is no possibility of error?
-\begin_inset Quotes srd
-\end_inset
-
- - MG]
-\end_layout
-
\begin_layout Enumerate
First, copy
\family typewriter
@@ -2012,7 +1707,7 @@
\color red
Warning:
\series default
-\color default
+\color none
Do not add it in the list named
\family typewriter
``variables
@@ -2029,20 +1724,6 @@
.
\end_layout
-\begin_layout Standard
-
-\color red
-[TODO:
-\begin_inset Quotes sld
-\end_inset
-
-Visualization? What do we see? Why? Please explain.
-\begin_inset Quotes srd
-\end_inset
-
- - MG]
-\end_layout
-
\begin_layout Subsection
Viscous Material with Inflow/Outflow Boundaries
\end_layout
@@ -3025,21 +2706,6 @@
\end_layout
\begin_layout Standard
-
-\color red
-[TODO:
-\begin_inset Quotes sld
-\end_inset
-
-This would be a good chapter with specific links to a web site with results
- shown.
-\begin_inset Quotes srd
-\end_inset
-
- - MG]
-\end_layout
-
-\begin_layout Standard
Gale makes a number of approximations when simulating.
Before trusting any results we get from Gale, we need to vary a number
of parameters to insure that the results are not an artifact of Gale's
More information about the cig-commits
mailing list