[cig-commits] r6384 - in long/3D/Gale/trunk: . documentation

[walter at geodynamics.org]

Author: walter
Date: 2007-03-23 16:53:27 -0700 (Fri, 23 Mar 2007)
New Revision: 6384

Modified:
   long/3D/Gale/trunk/
   long/3D/Gale/trunk/documentation/gale.lyx
Log:
 r1739 at earth:  boo | 2007-03-23 16:52:22 -0700
 Updates to the manual



Property changes on: long/3D/Gale/trunk
___________________________________________________________________
Name: svk:merge
   - 3a629746-de10-0410-b17b-fd6ecaaa963e:/cig:1737
   + 3a629746-de10-0410-b17b-fd6ecaaa963e:/cig:1739

Modified: long/3D/Gale/trunk/documentation/gale.lyx
===================================================================
--- long/3D/Gale/trunk/documentation/gale.lyx	2007-03-23 23:39:09 UTC (rev 6383)
+++ long/3D/Gale/trunk/documentation/gale.lyx	2007-03-23 23:53:27 UTC (rev 6384)
@@ -89,7 +89,7 @@
 Walter Landry and Luke Hodkinson
 \newline
 Version
- 1.1.1
+ 1.1.2
 \end_layout
 
 \begin_layout Date
@@ -1021,7 +1021,7 @@
 \end_layout
 
 \begin_layout LyX-Code
-./Gale-1_1_1  input/extension.xml
+./Gale-1_1_2  input/extension.xml
 \end_layout
 
 \begin_layout Standard
@@ -1053,26 +1053,47 @@
 \end_layout
 
 \begin_layout Standard
-If you do not specify an input file, you will get the following (slightly
- cryptic) error:
+If you do not specify an input file, you will get an error like
 \end_layout
 
 \begin_layout LyX-Code
 
 \family typewriter
 \color none
-Gale: build/Gale/src/main.c:154: main: Assertion `componentDict' failed.
+Error in _AbstractContext_New: The dictionary is empty, meaning no input
+ parameters have been feed
 \end_layout
 
 \begin_layout LyX-Code
 
 \family typewriter
 \color none
-p0_16686:  p4_error: interrupt SIGx: 6
+into your program.
+ Perhaps you've forgot to pass any input files ( or command-line arguments
+ ) in.
 \end_layout
 
+\begin_layout LyX-Code
+
+\family typewriter
+\color none
+Gale: build/StGermain/Base/IO/src/Journal.c:603: Journal_Firewall: Assertion
+ `expression' failed.
+\end_layout
+
+\begin_layout LyX-Code
+
+\family typewriter
+\color none
+p0_27845:  p4_error: interrupt SIGx: 6 
+\end_layout
+
+\begin_layout LyX-Code
+
+\end_layout
+
 \begin_layout Standard
-If Gale cannot find the file, you will get a more descriptive error:
+If Gale cannot find the file, you will get a different error:
 \end_layout
 
 \begin_layout LyX-Code
@@ -1092,7 +1113,7 @@
 Due to quirks in some implementations of MPI, you may have to specify the
  complete path to the input file (e.g., 
 \family typewriter
-./Gale-1_1_1 /home/juser/gale/input/extension.xml
+./Gale-1_1_2 /home/juser/gale/input/extension.xml
 \family default
 ).
 \end_layout
@@ -1116,8 +1137,8 @@
 \end_layout
 
 \begin_layout Standard
-If you compile Gale yourself, you run it from where you installed it.
- If running in parallel, prepend 
+If you compile Gale yourself, you can run it from where you installed it.
+ If running in parallel on your own machine, prepend 
 \family typewriter
 mpirun
 \family default
@@ -1126,7 +1147,19 @@
 mpiexec
 \family default
  (depending on your local implementation of MPI).
- The 
+ For example, if your computer has two processors, then
+\end_layout
+
+\begin_layout LyX-Code
+mpirun -np 2 bin/Gale /home/juser/gale/input/extension.xml
+\end_layout
+
+\begin_layout Standard
+will use both processors.
+\end_layout
+
+\begin_layout Standard
+The 
 \family typewriter
 extension.xml
 \family default
@@ -1136,35 +1169,35 @@
 output.extension
 \family default
  directory.
- There you will find examples of shortening, subduction, and relaxation
- of a sinusoid.
+ There are also examples of shortening, subduction, and relaxation of topography.
 \end_layout
 
 \begin_layout Standard
-Since Gale uses PETSc for solving the equations, 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, on serial machines, a direct solve can be much
- faster than the default iterative solver.
+Gale uses PETSc's GMRES linear solver by default.
+ However, PETSc has a facility where you can use command line arguments
+ to change the solver.
+ For example, on serial machines with small problems, a direct solve can
+ be much faster than GMRES.
  So to use a direct LU solve, you only need to append arguments to the command
  line
 \end_layout
 
 \begin_layout LyX-Code
-./Gale-1_1_1  extension.xml -pc_type lu -ksp_type preonly
+./Gale-1_1_2  input/extension.xml -pc_type lu -ksp_type preonly
 \end_layout
 
 \begin_layout Standard
-You can also change the default values of extension.xml without modifying
- that file by appending arguments.
+You can also change the default values of 
+\family typewriter
+extension.xml
+\family default
+ without modifying that file by appending arguments.
  For example, to just change the number of time steps from default value
  500 to 10, use the following command
 \end_layout
 
 \begin_layout LyX-Code
-./Gale-1_1_1  extension.xml --maxtimesteps=10
+./Gale-1_1_2  input/extension.xml --maxTimeSteps=10
 \end_layout
 
 \begin_layout Standard
@@ -1172,41 +1205,10 @@
 \end_layout
 
 \begin_layout LyX-Code
-./Gale-1_1_1  extension.xml --maxtimesteps=10 --dim=3 Since Gale uses PETSc
- for solving the equations, 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, 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
+./Gale-1_1_2  input/extension.xml --maxTimeSteps=10 --dim=3 --elementResI=64
+ --elementResJ=64 --elementResK=64 --particlesPerCell=60 --dumpEvery=10
 \end_layout
 
-\begin_layout LyX-Code
-./Gale-1_1_1  extension.xml -pc_type lu -ksp_type preonly
-\end_layout
-
-\begin_layout Standard
-You can also change the default values of extension.xml without modifying
- that file by appending arguments.
- For example, to just change the number of time steps from default value
- 500 to 10, use the following command
-\end_layout
-
-\begin_layout LyX-Code
-./Gale-1_1_1  extension.xml --maxtimesteps=10
-\end_layout
-
-\begin_layout Standard
-You can append any number of modified parameters in one unbroken line
-\end_layout
-
-\begin_layout LyX-Code
-./Gale-1_1_1  extension.xml --maxtimesteps=10 --dim=3 --elementResI=64 --elementRe
-sJ=64 --elementResK=64 --particlesPerCell=60 --dumpEvery=10
-\end_layout
-
 \begin_layout Section
 Output and Visualization
 \end_layout
@@ -1287,8 +1289,31 @@
 .
 \end_layout
 
+\begin_layout LyX-Code
+<param name="dumpEvery">25</param>
+\end_layout
+
 \begin_layout Standard
-(TODO: Need example of what changing dumpEvery will look like.)
+
+\color red
+Note:
+\color none
+ In order to get viscosity information out, you must add a 
+\family typewriter
+StoreViscosity
+\family default
+ struct to your rheology as in Section 
+\begin_inset LatexCommand \ref{sec:Viscous-Material}
+
+\end_inset
+
+ (see also Section 
+\begin_inset LatexCommand \ref{sub:StoreViscosity}
+
+\end_inset
+
+).
+ This is already done in all of the example input files.
 \end_layout
 
 \begin_layout Standard
@@ -1726,6 +1751,7 @@
 \family default
  directory.
  The scripts also work with Octave, a free Matlab clone.
+ However, they only work with 2D runs with yielding rheologies.
  To use these scripts, 
 \end_layout
 
@@ -2005,93 +2031,16 @@
 \end_layout
 
 \end_deeper
-\begin_layout Section
-Controlling Output for Visualization
-\end_layout
-
-\begin_layout Standard
-TODO: make this more general
-\end_layout
-
-\begin_layout Standard
-If you wish see viscosity (in the output VTK file), you have to add stored
- viscosity in the rheology.
- In order for Gale to do this, you must save the effective isotropic viscosity
- by adding a component to 
-\family typewriter
-extensions.xml
-\end_layout
-
 \begin_layout LyX-Code
-<struct name="storeViscosity"> 
-\end_layout
 
-\begin_layout LyX-Code
-<param name="Type">StoreVisc</param>
 \end_layout
 
-\begin_layout LyX-Code
-<param name="MaterialPointsSwarm">materialSwarm</param> </struct> 
-\end_layout
-
-\begin_layout Standard
-and then changing the ambient rheology from 
-\end_layout
-
-\begin_layout LyX-Code
-<param name="Rheology">ambientViscosity</param> 
-\end_layout
-
-\begin_layout Standard
-to 
-\end_layout
-
-\begin_layout LyX-Code
-<list name="Rheology"> 
-\end_layout
-
-\begin_layout LyX-Code
-<param>ambientViscosity</param> 
-\end_layout
-
-\begin_layout LyX-Code
-<param>storeViscosity</param> 
-\end_layout
-
-\begin_layout LyX-Code
-</list> 
-\end_layout
-
-\begin_layout Standard
-and the dense layer rheology from 
-\end_layout
-
-\begin_layout LyX-Code
-<param name="Rheology">denseLayerViscosity</param> 
-\end_layout
-
-\begin_layout Standard
-to 
-\end_layout
-
-\begin_layout LyX-Code
-<list name="Rheology"> 
-\end_layout
-
-\begin_layout LyX-Code
-<param>denseLayerViscosity</param> <param>storeViscosity</param> 
-\end_layout
-
-\begin_layout LyX-Code
-</list>
-\end_layout
-
 \begin_layout Section
 Gauging Accuracy
 \end_layout
 
 \begin_layout Standard
-Gale makes a number of approximations when simulating.
+Gale makes a number of approximations.
  Before trusting any results you get from Gale, you must vary a number of
  parameters to insure that the results are not an artifact of Gale's approximati
 ons.
@@ -2112,6 +2061,17 @@
 particlesPerCell
 \family default
 ).
+ For problems with inflow boundaries (see Sections 
+\begin_inset LatexCommand \ref{sec:Viscous-In-Outflow}
+
+\end_inset
+
+ and 
+\begin_inset LatexCommand \ref{sub:Flux-Boundary-Conditions}
+
+\end_inset
+
+), you must vary the size of the boundary box.
  In addition, depending on the boundary conditions, you may need to vary
  the size of the box (
 \family typewriter
@@ -2233,7 +2193,7 @@
 \end_layout
 
 \begin_layout Standard
-Finished versions of all of these examples are found` in 
+Finished versions of all of these examples are found in 
 \family typewriter
 input/cookbook
 \family default
@@ -2365,7 +2325,13 @@
 
 \end_deeper
 \begin_layout Enumerate
-Next Gale must store the viscosity on the material points
+In order for Gale to include the viscosity in the output, we have to store
+ the viscosity in a separate field (see Section 
+\begin_inset LatexCommand \ref{sub:StoreViscosity}
+
+\end_inset
+
+).
 \end_layout
 
 \begin_deeper
@@ -2386,13 +2352,11 @@
 \end_layout
 
 \begin_layout Standard
-In a particle-based approach, 
+Here, 
 \family typewriter
 materialswarm
 \family default
  is a collection of particles.
- You are creating a new component that stores the viscosity for all of these
- components.
 \end_layout
 
 \end_deeper
@@ -2469,8 +2433,6 @@
  it.
  In this next example, you will make the material extend by having the right
  boundary move.
- This simple model is the basis for many problems of current interest involving
- lithospheric and crustal extensions.
 \end_layout
 
 \begin_layout Enumerate
@@ -2660,34 +2622,9 @@
 \begin_layout Standard
 The banding is a numerical artifact that arises from having a finite number
  of particles per cell.
+ This example generates no topography, since the material is stretched uniformly.
 \end_layout
 
-\begin_layout Standard
-[TODO: Gurnis asks: Maybe a scale is needed? Landry: Color bar scale? Maybe.
- More work, and it would make it more difficult to display the same image
- output for some.
- 
-\end_layout
-
-\begin_layout Standard
-Gurnis asks: If there are only small variations in and if the 
-\begin_inset Quotes sld
-\end_inset
-
-banding
-\begin_inset Quotes srd
-\end_inset
-
- is an artifact, mabe we need to visualizze a different quantity.
- Landry: It's important that people see it so they see what happens when
- particle numbers are increased.
-\end_layout
-
-\begin_layout Standard
-Gurnis asks: Does any topography get generated in this problem? Landry:
- no.]
-\end_layout
-
 \begin_layout Section
 Viscous Material with Complex Boundaries
 \end_layout
@@ -2930,6 +2867,10 @@
 \end_layout
 
 \begin_layout Section
+\begin_inset LatexCommand \label{sec:Viscous-In-Outflow}
+
+\end_inset
+
 Viscous Material with Inflow/Outflow Boundaries
 \end_layout
 
@@ -2941,9 +2882,15 @@
 \end_inset
 
 .
- This example is not intended to be geologically realistic in any sense,
- but is meant to illustrate the enormous flexibility we have in the development
- of complex boundary conditions.
+ The current example is not intended to be geologically realistic in any
+ sense, but is meant to illustrate the enormous flexibility we have in the
+ development of complex boundary conditions.
+ A more realistic model of subduction is included in the sample input file
+ 
+\family typewriter
+input/subduction.xml
+\family default
+.
 \end_layout
 
 \begin_layout Standard
@@ -2996,8 +2943,11 @@
 \end_layout
 
 \begin_layout Enumerate
-Then, add the following lines so that Gale keeps the left and bottom sides
- fixed:
+Then, add the following lines after the 
+\family typewriter
+wrapTop
+\family default
+ line so that Gale keeps the left and bottom sides fixed:
 \end_layout
 
 \begin_deeper
@@ -3009,14 +2959,6 @@
 <param name="staticBottom">True</param>
 \end_layout
 
-\begin_layout Standard
-after the 
-\family typewriter
-wrapTop
-\family default
- line.
-\end_layout
-
 \end_deeper
 \begin_layout Enumerate
 Now specify the velocities on the boundaries using the 
@@ -3666,15 +3608,6 @@
 
 \end_layout
 
-\begin_layout Standard
-[TODO: These show substantial asymmetries, maybe if we use a topography
- such that 
-\begin_inset Formula $\frac{\delta topo}{ox}=o$
-\end_inset
-
- at the left and right?]
-\end_layout
-
 \begin_layout Section
 Multiple Viscous Materials
 \end_layout
@@ -3770,7 +3703,7 @@
 
 \begin_layout Standard
 Note: If run in 3D, this is a sphere.
- The example shown here is run in 2D, so in fact the result is a circle.
+ The example shown here is run in 2D, so the result is a circle.
 \end_layout
 
 \end_deeper
@@ -4335,12 +4268,6 @@
 
 \end_layout
 
-\begin_layout Standard
-[TODO: Gurnis asks: Shouldn't the first localization example be for a homogeneou
-s material? Can this be run for a longer period of time? Landry: Yes, but
- maybe this should be done in Benchmarks.]
-\end_layout
-
 \begin_layout Chapter
 Modifying Gale
 \begin_inset LatexCommand \label{cha:Modifying-Gale}
@@ -8392,7 +8319,151 @@
 </struct>
 \end_layout
 
+\begin_layout Standard
+To output the effective isotropic viscosity, you have to add a 
+\family typewriter
+StoreVisc
+\family default
+ component
+\end_layout
+
+\begin_layout LyX-Code
+<struct name="storeViscosity">
+\end_layout
+
+\begin_layout LyX-Code
+  <param name="Type">StoreVisc</param>
+\end_layout
+
+\begin_layout LyX-Code
+  <param name="MaterialPointsSwarm">materialSwarm</param>
+\end_layout
+
+\begin_layout LyX-Code
+</struct>
+\end_layout
+
+\begin_layout Standard
+and then add that to the material
+\end_layout
+
+\begin_layout LyX-Code
+<struct name="yieldingMaterial">
+\end_layout
+
+\begin_layout LyX-Code
+  <param name="Type">RheologyMaterial</param>
+\end_layout
+
+\begin_layout LyX-Code
+  <param name="Shape">yieldingShape</param>
+\end_layout
+
+\begin_layout LyX-Code
+  <list name="Rheology">
+\end_layout
+
+\begin_layout LyX-Code
+    <param>storeViscosity</param>
+\end_layout
+
+\begin_layout LyX-Code
+    <param>viscousRheology</param>
+\end_layout
+
+\begin_layout LyX-Code
+    <param>yieldingRheology</param>
+\end_layout
+
+\begin_layout LyX-Code
+  </list>
+\end_layout
+
+\begin_layout LyX-Code
+</struct>
+\end_layout
+
 \begin_layout Subsection
+StoreVisc
+\begin_inset LatexCommand \label{sub:StoreViscosity}
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+This is not a rheology per se, but rather it is an extra field where Gale
+ saves the effective isotropic viscosity.
+ For pure viscous materials, this will be the same as the viscosity you
+ supply.
+ For yielding rheologies, the effective viscosity will change as the particle
+ yields.
+ This component needs a 
+\family typewriter
+MaterialPointsSwarm
+\family default
+, which in the all of the sample input files is called 
+\family typewriter
+materialSwarm
+\family default
+.
+\end_layout
+
+\begin_layout Standard
+\begin_inset Tabular
+<lyxtabular version="3" rows="2" 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
+Defaults
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+MaterialPointsSwarm
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+1
+\end_layout
+
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Subsection
 Viscous
 \end_layout