[cig-commits] r4398 - in
short/3D/PyLith/branches/pylith-0.8/doc/userguide: .
fileformats install intro materials tutorials
tutorials/reversenog tutorials/splittest
baagaard at geodynamics.org
baagaard at geodynamics.org
Tue Aug 22 08:30:54 PDT 2006
Author: baagaard
Date: 2006-08-22 08:30:52 -0700 (Tue, 22 Aug 2006)
New Revision: 4398
Added:
short/3D/PyLith/branches/pylith-0.8/doc/userguide/docdefs.tex
short/3D/PyLith/branches/pylith-0.8/doc/userguide/fileformats/bc.tex
short/3D/PyLith/branches/pylith-0.8/doc/userguide/fileformats/connect.tex
short/3D/PyLith/branches/pylith-0.8/doc/userguide/fileformats/coord.tex
short/3D/PyLith/branches/pylith-0.8/doc/userguide/fileformats/fileformats.tex
short/3D/PyLith/branches/pylith-0.8/doc/userguide/fileformats/fuldat.tex
short/3D/PyLith/branches/pylith-0.8/doc/userguide/fileformats/hist.tex
short/3D/PyLith/branches/pylith-0.8/doc/userguide/fileformats/keyval.tex
short/3D/PyLith/branches/pylith-0.8/doc/userguide/fileformats/prop.tex
short/3D/PyLith/branches/pylith-0.8/doc/userguide/fileformats/skew.tex
short/3D/PyLith/branches/pylith-0.8/doc/userguide/fileformats/split.tex
short/3D/PyLith/branches/pylith-0.8/doc/userguide/fileformats/statevar.tex
short/3D/PyLith/branches/pylith-0.8/doc/userguide/fileformats/time.tex
short/3D/PyLith/branches/pylith-0.8/doc/userguide/fileformats/wink.tex
short/3D/PyLith/branches/pylith-0.8/doc/userguide/install/install.tex
short/3D/PyLith/branches/pylith-0.8/doc/userguide/intro/intro.tex
short/3D/PyLith/branches/pylith-0.8/doc/userguide/license.tex
short/3D/PyLith/branches/pylith-0.8/doc/userguide/materials/materials.tex
short/3D/PyLith/branches/pylith-0.8/doc/userguide/materials/maxwell_linear.tex
short/3D/PyLith/branches/pylith-0.8/doc/userguide/preface.tex
short/3D/PyLith/branches/pylith-0.8/doc/userguide/references.bib
short/3D/PyLith/branches/pylith-0.8/doc/userguide/tutorials/reversenog/reversenog.tex
short/3D/PyLith/branches/pylith-0.8/doc/userguide/tutorials/splittest/
short/3D/PyLith/branches/pylith-0.8/doc/userguide/tutorials/splittest/figs/
short/3D/PyLith/branches/pylith-0.8/doc/userguide/tutorials/splittest/splittest.tex
short/3D/PyLith/branches/pylith-0.8/doc/userguide/tutorials/tutorials.tex
short/3D/PyLith/branches/pylith-0.8/doc/userguide/userguide.tex
Modified:
short/3D/PyLith/branches/pylith-0.8/doc/userguide/makefile
Log:
First stab at converting docbook files to LaTeX.
Added: short/3D/PyLith/branches/pylith-0.8/doc/userguide/docdefs.tex
===================================================================
--- short/3D/PyLith/branches/pylith-0.8/doc/userguide/docdefs.tex 2006-08-22 13:08:01 UTC (rev 4397)
+++ short/3D/PyLith/branches/pylith-0.8/doc/userguide/docdefs.tex 2006-08-22 15:30:52 UTC (rev 4398)
@@ -0,0 +1,34 @@
+% Miscellaneous
+\newcommand{\email}[1]{\tt #1}
+
+
+\newenvironment{warning}{Warning\par}{}
+\newenvironment{tip}{Hint\par}{}
+
+% GUI markup
+\newcommand{\guibutton}[1]{\fbox #1}
+\newcommand{\guimenu}[1]{\bf #1}
+\newcommand{\guimenuitem}[1]{\bf #1}
+\newcommand{\guiselect}{$\rightarrow$}
+
+\newcommand{\prompt}[1]{\tt\bf #1}
+\newcommand{\userinput}[1]{\tt #1}
+\newenvironment{screen}{}{}
+
+% Source code markup
+\newcommand{\application}[1]{\bf #1}
+\newcommand{\directory}[1]{\tt #1}
+\newcommand{\filename}[1]{\tt #1}
+\newcommand{\envvar}[1]{\tt #1}
+\newcommand{\replaceable}[1]{\it #1}
+\newcommand{\command}[1]{\tt #1}
+\newcommand{\option}[1]{\it\tt #1}
+
+\newcommand{\classname}[1]{\em #1}
+
+% temporary, should use hyperref
+\newcommand{\link}[2]{#1 ({\tt #2})}
+
+% shortcuts
+\newcommand{\shellprompt}{\prompt{bash\$~}}
+
Added: short/3D/PyLith/branches/pylith-0.8/doc/userguide/fileformats/bc.tex
===================================================================
--- short/3D/PyLith/branches/pylith-0.8/doc/userguide/fileformats/bc.tex 2006-08-22 13:08:01 UTC (rev 4397)
+++ short/3D/PyLith/branches/pylith-0.8/doc/userguide/fileformats/bc.tex 2006-08-22 15:30:52 UTC (rev 4398)
@@ -0,0 +1,47 @@
+\subsection{xx.bc}
+
+The \filename{xx.bc} file specifies the displacements, velocity,
+and/or forces applied to vertices on the boundaries.
+
+\begin{figure}[htbp]
+ \begin{center}
+\begin{verbatim}
+# File containing boundary conditions at vertices.
+#
+# Comment lines begin with '#'
+#
+# First, specify units of coordinates for each type of boundary
+# conditon. All three are required even if they are not all used.
+#
+displacement_units = m
+velocity_units = m/s
+force_units = newton
+#
+#
+# Boundary conditions applied to vertices. You must specify a flag and
+# value for each degree of freedom, even if some are free.
+#
+# Columns:
+# (1) Vertex number
+# (2) Boundary condition flag for x DOF
+# (3) Boundary condition flag for y DOF
+# (4) Boundary condition flag for z DOF
+# 0 = Free
+# 1 = Fixed displacement
+# 2 = Constant velocity
+# 3 = Constant force
+# A 2 or more digit code may be used for the boundary condition
+# flag. If used, the the final digit refers to the condition
+# type as defined above, while the beginning digit(s) refer to
+# the time history to be used.
+# (5) Boundary condition value for x DOF
+# (6) Boundary condition value for y DOF
+# (7) Boundary condition value for z DOF
+1 0 1 0 0.0000e+00 0.0000e+00 0.0000e+00
+3 0 1 0 0.0000e+00 0.0000e+00 0.0000e+00
+12 0 1 0 0.0000e+00 0.0000e+00 0.0000e+00
+\end{verbatim}
+ \ldots
+ \caption{Format of \filename{xx.bc} files.}
+ \end{center}
+\end{figure}
Added: short/3D/PyLith/branches/pylith-0.8/doc/userguide/fileformats/connect.tex
===================================================================
--- short/3D/PyLith/branches/pylith-0.8/doc/userguide/fileformats/connect.tex 2006-08-22 13:08:01 UTC (rev 4397)
+++ short/3D/PyLith/branches/pylith-0.8/doc/userguide/fileformats/connect.tex 2006-08-22 15:30:52 UTC (rev 4398)
@@ -0,0 +1,48 @@
+\subsection{xx.connect}
+
+The \filename{xx.connect} file contains the finite-element mesh
+topology and material type information, including the element type,
+material type, and the lists of vertices for each element.
+
+\begin{figure}
+ \begin{center}
+\begin{verbatim}
+# File containing finite-element mesh topology and material type
+# information.
+#
+# Comment lines begin with '#'
+#
+# Columns:
+# (1) Element number
+# (2) Element type
+# 1 = Linear hexahedron (8 vertices)
+# 2 = Linear hexahedron with 1 set of collapsed vertices
+# (7 vertices) [NOT IMPLEMENTED]
+# 3 = Linear hexahedron with 2 sets of collapsed vertices
+# (6 vertices) [NOT IMPLEMENTED]
+# 4 = Linear hexahedron with 4 vertices collapsed to a point
+# (5 vertices) [NOT IMPLEMENTED]
+# 5 = Linear tetrahedron (4 vertices)
+# 6 = Quadratix hexahedron (20 vertices) [NOT IMPLEMENTED]
+# 7 = Quadratic hexahedron with 3 vertices along one edge
+# collapsed to a point (18 vertices) [NOT IMPLEMENTED]
+# 8 = Quadratic hexahedron with 3 sets of collapsed vertices
+# (15 vertices) [NOT IMPLEMENTED]
+# 9 = Quadratic hexahedron with 9 vertices collapsed to a point
+# (13 vertices) [NOT IMPLEMENTED]
+# 10 = Quadratic tetrahedron (10 vertices) [NOT IMPLEMENTED]
+# (3) Material type, numbered consecutively beginning with '1'
+# (4) Infinite element flag, required but not currently implemented
+# 0 = only valid value
+# (5)+ Vertices in the element, identified by vertex number
+#
+# Note: No comments are allowed within the mesh information.
+#
+1 5 1 0 2911 2865 2886 2864
+2 5 2 0 843 3999 4029 3926
+3 5 1 0 684 8975 2346 6219
+\end{verbatim}
+ \ldots
+ \caption{Format of \filename{xx.connect} files.}
+ \end{center}
+\end{figure}
Added: short/3D/PyLith/branches/pylith-0.8/doc/userguide/fileformats/coord.tex
===================================================================
--- short/3D/PyLith/branches/pylith-0.8/doc/userguide/fileformats/coord.tex 2006-08-22 13:08:01 UTC (rev 4397)
+++ short/3D/PyLith/branches/pylith-0.8/doc/userguide/fileformats/coord.tex 2006-08-22 15:30:52 UTC (rev 4398)
@@ -0,0 +1,36 @@
+\subsection{xx.coord}
+
+The \filename{xx.coord} file contains the coordinates of all of the
+vertices in the finite-element mesh.
+
+\begin{figure}
+ \begin{center}
+\begin{verbatim}
+# File containing vertices of the finite-element mesh.
+#
+# Comment lines begin with '#'
+#
+# First, specify units of coordinates.
+#
+coord_unit = km
+#
+#
+# Now specify the coordinates of each vertex.
+#
+# Columns:
+# (1) Vertex number
+# (2) X coordinate
+# (3) Y coordinate
+# (4) Z coordinate
+#
+# Note: No comments are allowed within the list of vertex coordinates
+#
+1 0.000000e+00 0.000000e+00 0.000000e+00
+2 1.000000e+00 0.000000e+00 0.000000e+00
+3 0.000000e+00 2.000000e+00 0.000000e+00
+4 1.000000e+00 2.000000e+00 3.000000e+00
+\end{verbatim}
+ \ldots
+ \caption{Format of \filename{xx.coord} files.}
+ \end{center}
+\end{figure}
Added: short/3D/PyLith/branches/pylith-0.8/doc/userguide/fileformats/fileformats.tex
===================================================================
--- short/3D/PyLith/branches/pylith-0.8/doc/userguide/fileformats/fileformats.tex 2006-08-22 13:08:01 UTC (rev 4397)
+++ short/3D/PyLith/branches/pylith-0.8/doc/userguide/fileformats/fileformats.tex 2006-08-22 15:30:52 UTC (rev 4398)
@@ -0,0 +1,25 @@
+\chapter{File Formats}
+
+\section{Input Files}
+
+PyLith gathers its input from several different types of files. All of
+these area ASCII files and can include comment lines that begin with
+'\#'. Note that the placement of comments is restricted to certain
+locations in some files (see the discussion of each file format for
+more information).
+
+% Required input files
+\input{coord.tex}
+\input{connect.tex}
+\input{bc.tex}
+\input{time.tex}
+\input{prop.tex}
+\input{statevar.tex}
+
+% Optional input files
+\input{split.tex}
+\input{fuldat.tex}
+\input{skew.tex}
+\input{keyval.tex}
+\input{hist.tex}
+\input{wink.tex}
Added: short/3D/PyLith/branches/pylith-0.8/doc/userguide/fileformats/fuldat.tex
===================================================================
--- short/3D/PyLith/branches/pylith-0.8/doc/userguide/fileformats/fuldat.tex 2006-08-22 13:08:01 UTC (rev 4397)
+++ short/3D/PyLith/branches/pylith-0.8/doc/userguide/fileformats/fuldat.tex 2006-08-22 15:30:52 UTC (rev 4398)
@@ -0,0 +1,27 @@
+\subsection{xx.fuldat}
+
+The \filename{xx.fuldat} file lists the time step numbers at which
+full output is desired. The elastic solution (time step 0) is always
+included in the output. This file is required for time-dependent
+problems.
+
+\begin{figure}
+ \begin{center}
+\begin{verbatim}
+# File containing time steps at which full output is desired.
+#
+# Comment lines begin with '#'
+#
+# Note: Time step 0 (elastic solution) is always included in the
+# output.
+#
+# List the time steps, one per line.
+#
+ 10
+ 50
+ 100
+\end{verbatim}
+\ldots
+ \caption{Format of \filename{xx.time} files.}
+ \end{center}
+\end{figure}
Added: short/3D/PyLith/branches/pylith-0.8/doc/userguide/fileformats/hist.tex
===================================================================
--- short/3D/PyLith/branches/pylith-0.8/doc/userguide/fileformats/hist.tex 2006-08-22 13:08:01 UTC (rev 4397)
+++ short/3D/PyLith/branches/pylith-0.8/doc/userguide/fileformats/hist.tex 2006-08-22 15:30:52 UTC (rev 4398)
@@ -0,0 +1,29 @@
+\subsection{xx.hist}
+
+The \filename{xx.hist} files provide time histories for use in
+boundary conditions.
+
+\begin{figure}
+ \begin{center}
+\begin{verbatim}
+# File specifying time variation of boundary conditions.
+#
+# Comment lines begin with '#'
+#
+# Each time history consists of two or more lines. The first line
+# indicates the number of points in the history and the default load
+# value for the history. Subsequent lines define time/load pairs.
+#
+# Line 1, column 1: The number of points in the time history
+# Line 1, column 2: The value assigned to every point by default
+# (overridden by values in time history)
+# Line 2+, column 1: Time (in seconds) for a given load value
+# Line 2+, column 2: Load value at given time
+#
+ 2 1.0
+2.84014e+08 0.1
+3.15576e+08 0.5
+\end{verbatim}
+ \caption{Format of \filename{xx.hist} files.}
+ \end{center}
+\end{figure}
Added: short/3D/PyLith/branches/pylith-0.8/doc/userguide/fileformats/keyval.tex
===================================================================
--- short/3D/PyLith/branches/pylith-0.8/doc/userguide/fileformats/keyval.tex 2006-08-22 13:08:01 UTC (rev 4397)
+++ short/3D/PyLith/branches/pylith-0.8/doc/userguide/fileformats/keyval.tex 2006-08-22 15:30:52 UTC (rev 4398)
@@ -0,0 +1,107 @@
+\subsection{xx.keyval}
+
+The \filename{xx.keyval} file specifies some simple parameter
+settings.
+
+\subsubsection{Winkler forces}
+
+Scaling factors can be applied to Winkler forces, permitting a quick
+and easy way to change the density or gravitational acceleration when
+Winkler forces are used to simulate gravity.
+
+\paragraph{Quadrature order}
+
+\begin{description}
+\item[Full] Quadrature order that should give the exact element
+ matrices when the elements are geometrically undistorted.
+\item[Reduced] Quadrature order that is one order less than full
+ quadrature. Note that for linear tetrahedra full and reduced
+ quadrature are equivalent (single integration point).
+
+ \begin{warning}
+ Use with caution as reduced quadrature can lead to numerical
+ instabilities.
+ \end{warning}
+
+\item[Selective] Uses Hughes' b-bar formulation to perform reduced
+ quadrature on the dilatational parts of the strain-displacement
+ matrix. This can be useful in nearly-incompressible problems.
+\end{description}
+
+\paragraph{Prestresses}
+
+Gravitational prestresses can be computed automatically. In such
+cases, the elastic properties in the prestress calculation can be set
+to uniform values independent of the parameters for any of the
+material models. When gravity is being used and prestresses are not
+computed automatically, each prestress component can be scaled
+independently. Reading prestresses from files is presently disabled.
+
+\begin{figure}
+\begin{center}
+\begin{verbatim}
+# Simple parameter values for various PyLith settings. Defaults are
+# listed.
+#
+# Scaling factors applied to Winkler forces.
+#
+winklerScaleX = 1.0
+winklerScaleY = 1.0
+winklerScaleZ = 1.0
+#
+# Scaling factors applied to differential Winkler forces.
+#
+winklerSlipScaleX = 1.0
+winklerSlipScaleY = 1.0
+winklerSlipScaleZ = 1.0
+#
+# Stress integration and numerical computation of the tangent
+# material matrix. Default values should be reasonable for most cases.
+#
+stressTolerance = 1.0e-12*Pa
+minimumStrainPerturbation = 1.0e-7
+initialStrainPerturbation = 1.0e-1
+#
+# Specify whether to use the solution from the previous time step as
+# the starting guess for the elastic solution in the current time step.
+# This feature has not been tested.
+#
+usePreviousDisplacementFlag = 0
+#
+# Quadrature order for the problem.
+#
+quadratureOrder = "Full"
+#
+# Gravitational acceleration in each direction.
+#
+gravityX = 0.0*m/(s*s)
+gravityY = 0.0*m/(s*s)
+gravityZ = 0.0*m/(s*s)
+#
+# Factors controlling computation of prestresses.
+#
+prestressAutoCompute = False
+prestressAutoChangeElasticProperties = False
+prestressAutoComputePoisson = 0.49
+prestressAutoComputeYoungs = 1.0e30*Pa
+#
+prestressScaleXx = 1.0
+prestressScaleYy = 1.0
+prestressScaleZz = 1.0
+prestressScaleXy = 1.0
+prestressScaleXz = 1.0
+prestressScaleYz = 1.0
+#
+# Unit numbers used in Fortran code. These defaults should work for
+# most Unix systems, but may be altered if necessary.
+#
+f77StandardInput = 5
+f77StandardOutput = 6
+f77FileInput = 10
+f77AsciiOutput = 11
+f77PlotOutput = 12
+f77UcdOutput = 13
+\end{verbatim}
+ \caption{Format of \filename{xx.keyval} files.}
+ \end{center}
+\end{figure}
Added: short/3D/PyLith/branches/pylith-0.8/doc/userguide/fileformats/prop.tex
===================================================================
--- short/3D/PyLith/branches/pylith-0.8/doc/userguide/fileformats/prop.tex 2006-08-22 13:08:01 UTC (rev 4397)
+++ short/3D/PyLith/branches/pylith-0.8/doc/userguide/fileformats/prop.tex 2006-08-22 15:30:52 UTC (rev 4398)
@@ -0,0 +1,62 @@
+\subsection{xx.prop}
+
+The \filename{xx.prop} file specifies the properties for each material
+model in the problem.
+
+\begin{warning}
+ The materials must be listed in order according to the material
+ number assigned to the elements in \filename{xx.connect}.
+\end{warning}
+
+\begin{figure}
+ \begin{center}
+\begin{verbatim}
+# File containing material properties.
+#
+# Comment lines begin with '#'
+#
+# The material type and material property values are specified using a
+# "keyword = value" syntax. The keywords for the different material
+# types are given below. Units for each of the values with dimensions
+# must follow the value as illustrated in the examples below.
+#
+# Materials and keywords:
+# Isotropic linear elastic
+# materialType ='IsotropicLinearElastic'
+# density
+# youngsModulus
+# poissonsRatio
+# endMaterial ='True' (flag indicating end of material)
+# Isotropic linear maxwell viscoelastic
+# materialType ='IsotropicLinearMaxwellViscoelastic'
+# density
+# youngsModulus
+# poissonsRatio
+# viscosity
+# endMaterial ='True' (flag indicating end of material)
+#
+# Material number 1
+materialType = 'IsotropicLinearMaxwellViscoelastic'
+density = 3000.0*kg/m**3
+youngsModulus = 7.5e10*Pa
+poissonsRatio = 0.25
+viscosity = 1.0e+18*Pa*s
+endMaterial = True
+# Material number 2
+materialType = 'IsotropicLinearElastic'
+density = 3000.0*kg/m**3
+youngsModulus = 7.5e10*Pa
+poissonsRatio = 0.25
+endMaterial = True
+# Material number 3
+materialType = 'IsotropicLinearMaxwellViscoelastic'
+density = 3000.0*kg/m**3
+youngsModulus = 7.5e10*Pa
+poissonsRatio = 0.25
+viscosity = 1.0e+18*Pa*s
+endMaterial = True
+\end{verbatim}
+ \ldots
+ \caption{Format of \filename{xx.prop} files.}
+ \end{center}
+\end{figure}
Added: short/3D/PyLith/branches/pylith-0.8/doc/userguide/fileformats/skew.tex
===================================================================
--- short/3D/PyLith/branches/pylith-0.8/doc/userguide/fileformats/skew.tex 2006-08-22 13:08:01 UTC (rev 4397)
+++ short/3D/PyLith/branches/pylith-0.8/doc/userguide/fileformats/skew.tex 2006-08-22 15:30:52 UTC (rev 4398)
@@ -0,0 +1,39 @@
+\subsection{xx.skew}
+
+The \filename{xx.skew} file specifies local coordinate systems for
+nodes. The local coordinate system is specified using two Euler angles
+that rotate the local coordinate system to the global coordinate
+system.
+
+The applied coordinate rotations apply to all boundary conditions
+associated with the nodes listed in the file. These are useful, for
+example, if it is desired to apply boundary conditions in a direction
+normal or tangential to a side of the mesh when the side does not
+align with the global coordinate directions. Similarly, skew
+conditions could be used when specifying slip on a fault that lies at
+an angle to the global coordinates.
+
+\begin{figure}
+ \begin{center}
+\begin{verbatim}
+# File containing local nodal coordinates.
+#
+# Comment lines begin with '#'
+#
+# First, specify units for rotations.
+#
+rotation_units = degree
+#
+#
+# Columns:
+# (1) Node number
+# (2) Euler angle for rotation in the x-y plane
+# (3) Euler angle for rotation in the x-z plane
+#
+68 12.3 4.2
+132 -12.3 -4.2
+\end{verbatim}
+ \ldots
+ \caption{Format of \filename{xx.time} files.}
+ \end{center}
+\end{figure}
Added: short/3D/PyLith/branches/pylith-0.8/doc/userguide/fileformats/split.tex
===================================================================
--- short/3D/PyLith/branches/pylith-0.8/doc/userguide/fileformats/split.tex 2006-08-22 13:08:01 UTC (rev 4397)
+++ short/3D/PyLith/branches/pylith-0.8/doc/userguide/fileformats/split.tex 2006-08-22 15:30:52 UTC (rev 4398)
@@ -0,0 +1,39 @@
+\subsection{xx.split}
+
+The \filename{xx.split} file specifies the split node information for
+modeling dislocations. Dislocations may be used in simulating slip on
+faults as well as dike intrusions.
+
+\begin{figure}
+ \begin{center}
+\begin{verbatim}
+# File containing time stepping parameters.
+#
+# Comment lines begin with '#'
+#
+# Displacements are specified for each vertex on the fault for each
+# element containing the vertex. The displacements on each side of the
+# fault or dike should have opposite signs. The displacements
+# associated with a single side of the fault for each vertex should be
+# the same.
+#
+# Columns:
+# (1) Element number
+# (2) Vertex number
+# (3) Time history flag
+# 0 = Slip only in elastic solution
+# -1 = Slip at constant velocity
+# n = Slip according to load history n (requires xx.hist file)
+# (4) Displacement in x direction
+# (5) Displacement in y direction
+# (6) Displacement in z direction
+#
+ 14886 36 0 0.353500000 0.00000000 -0.353500000
+ 14887 36 0 0.353500000 0.00000000 -0.353500000
+ 14896 36 0 -0.353500000 0.00000000 0.353500000
+ 14981 36 0 -0.353500000 0.00000000 0.353500000
+\end{verbatim}
+ \ldots
+ \caption{Format of \filename{xx.split} files.}
+ \end{center}
+\end{figure}
Added: short/3D/PyLith/branches/pylith-0.8/doc/userguide/fileformats/statevar.tex
===================================================================
--- short/3D/PyLith/branches/pylith-0.8/doc/userguide/fileformats/statevar.tex 2006-08-22 13:08:01 UTC (rev 4397)
+++ short/3D/PyLith/branches/pylith-0.8/doc/userguide/fileformats/statevar.tex 2006-08-22 15:30:52 UTC (rev 4398)
@@ -0,0 +1,35 @@
+\subsection{xx.statevar}
+
+The \filename{xx.statevar} file specifies which state variables are to
+be included in the output of the elastic and time dependent solutions.
+
+\begin{figure}
+ \begin{center}
+\begin{verbatim}
+# File specifying which state variables to output.
+#
+# Comment lines begin with '#'
+#
+# State variables occur in groups of 6, corresponding to the number of
+# stress/strain components. The present groups are:
+# 1-6: Cauchy stress
+# 7-12: Total strain
+# 13-18: Viscous strain
+# 18-24: Plastic strain
+#
+# Lines:
+# (1) Total accumulated values for the current time step
+# (2) Incremental values (previous to current)
+# (3) Rate values (previous to current)
+#
+# Columns (per line):
+# (1) Number of state variables to output (0 ≤ value ≤ 24)
+# (2)+ State variable number to output (1 ≤ value ≤ 24)
+#
+ 12 1 2 3 4 5 6 7 8 9 10 11 12
+ 12 1 2 3 4 5 6 7 8 9 10 11 12
+ 0
+\end{verbatim}
+ \caption{Format of \filename{xx.statevar} files.}
+ \end{center}
+\end{figure}
Added: short/3D/PyLith/branches/pylith-0.8/doc/userguide/fileformats/time.tex
===================================================================
--- short/3D/PyLith/branches/pylith-0.8/doc/userguide/fileformats/time.tex 2006-08-22 13:08:01 UTC (rev 4397)
+++ short/3D/PyLith/branches/pylith-0.8/doc/userguide/fileformats/time.tex 2006-08-22 15:30:52 UTC (rev 4398)
@@ -0,0 +1,61 @@
+\subsection{xx.time}
+
+The \filename{xx.time} file specifies the time stepping parameters for
+the simulation.
+
+\begin{warning}
+ The convergence criteria depend on the type of solution and material
+ models. The time step for a linear elastic problem is much different
+ than that for a nonlinear or time-dependent problem.
+\end{warning}
+
+\begin{figure}
+ \begin{center}
+\begin{verbatim}
+# File containing time stepping parameters.
+#
+# Comment lines begin with '#'
+#
+# First, specify units used in values with dimensions of time.
+#
+time_units = year
+#
+#
+# Time stepping parameters are given in groups. The elastic solution
+# corresponds to group 0 and must always be defined. Although some of
+# the parameters do not have any meaning for the elastic solution,
+# they must be present anyway.
+#
+# Columns:
+# (1) Time step group number (=0 for elastic solution).
+# (2) The number of time steps in the group (=1 for elastic solution).
+# (3) Time step size (given in units of time_units).
+# (4) Amount of implicitness. Real dimensionless parameter that
+# ranges from 0.0 (fully explicit) to 1.0 (fully implicit). The
+# value is generally set to 0.5.
+# (5) Maximum number of equilibrium iterations before stiffness
+# matrix is reformed.
+# (6) Number of time steps between initial reformation of stiffness
+# matrix.
+# <0 Indicates that reformation should occur only for the first
+# step in each time step group.
+# =0 Indicates that reformation should never occur.
+# (7) Large deformation solution flag (only Linear strain is
+# presently available).
+# 0 = Linear strain
+# 1 = Large strain but use only linear contribution to the
+# stiffness matrix (sometimes results in better convergence)
+# 2 = Large strain and use nonlinear contribution to the
+# stiffness matrix
+# (8) Convergence tolerance for displacements (dimensionless value)
+# (9) Convergence tolerance for forces (dimensionless value)
+# (10) Convergence tolerance for energy (dimensionless value)
+# (11) Maximum number of equilibrium iterations
+#
+ 0 1 0.0 5.0e-01 1001 4 0 1.0e+00 1.0e+0 1.0e+00 1
+ 1 100 0.1 5.0e-01 1001 -1 0 1.0e+00 1.0e+0 1.0e+00 1
+\end{verbatim}
+ \ldots
+ \caption{Format of \filename{xx.time} files.}
+ \end{center}
+\end{figure}
Added: short/3D/PyLith/branches/pylith-0.8/doc/userguide/fileformats/wink.tex
===================================================================
--- short/3D/PyLith/branches/pylith-0.8/doc/userguide/fileformats/wink.tex 2006-08-22 13:08:01 UTC (rev 4397)
+++ short/3D/PyLith/branches/pylith-0.8/doc/userguide/fileformats/wink.tex 2006-08-22 15:30:52 UTC (rev 4398)
@@ -0,0 +1,34 @@
+\subsection{xx.wink}
+
+The \filename{xx.wink} file specifies Winkler elements, which may be
+used as spring foundations in the simulation of gravity.
+
+\begin{figure}
+ \begin{center}
+\begin{verbatim}
+# File containing Winkler elements.
+#
+# Comment lines begin with '#'
+#
+# Flags for the degrees of freedom can have the following values:
+# 0 = no Winkler force
+# 1 = Winkler force applied at all times
+# -n = Winkler force applied according to load history n
+# (requires xx.hist file)
+#
+# Columns:
+# (1) Vertex number
+# (2) Flag for DOF in x-direction
+# (3) Flag for DOF in y-direction
+# (4) Flag for DOF in z-direction
+# (5) Magnitude of restoring force for x-direction
+# (6) Magnitude of restoring force for x-direction
+# (7) Magnitude of restoring force for x-direction
+#
+14 0 -1 0 0.0e+00 1.0e+25 0.0e+00
+18 0 1 0 1.0e+20 0.0e+00 0.0e+00
+\end{verbatim}
+ \ldots
+ \caption{Format of \filename{xx.wink} files.}
+ \end{center}
+\end{figure}
Added: short/3D/PyLith/branches/pylith-0.8/doc/userguide/install/install.tex
===================================================================
--- short/3D/PyLith/branches/pylith-0.8/doc/userguide/install/install.tex 2006-08-22 13:08:01 UTC (rev 4397)
+++ short/3D/PyLith/branches/pylith-0.8/doc/userguide/install/install.tex 2006-08-22 15:30:52 UTC (rev 4398)
@@ -0,0 +1,381 @@
+\chapter{Installation and Getting Help}
+
+\section{Introduction}
+
+Installation of PyLith on a desktop or laptop machine is, in most
+cases, very easy. Binary packages have been created for the most
+common platforms, including Linux, OSX, and Windows. Installation on
+machines that are not compatible with any of these operating systems
+requires building the software from the source code, which can be
+difficult for inexperienced users.
+
+\section{Getting Help}
+
+Help is available via the CIG Short-Term Crustal Dynamics Mailing List
+and CIG's issue tracking system.
+
+\subsection{Requesting help}
+
+The CIG Short-Term Crustal Dynamics Mailing List,
+\email{cig-short at geodynamics.org}, is a mailing list dedicated to CIG
+issues associated with short-term crustal dynamics, including the use
+of PyLith. You can subscribe to the mailing list and view messages at
+the \link{CIG website}{http://www.geodynamics.org}.
+
+\subsection{Reporting bugs and errors}
+
+CIG uses the \application{Roundup} for bug tracking. If you find a bug
+in PyLith, please submit a bug report to the \link{CIG
+\application{Roundup} system}{http://www.geodynamics.org/roundup}. Of
+course, it is helpful to first check to see if someone else already
+submitted a report related to the issue; one of the CIG developers may
+have already posted a solution to the problem. You can reply to a
+current issue by clicking on the issue title. To submit a new issue,
+click on \guibutton{Create New} under \guimenu{Issues}.
+
+\section{Installation}
+
+Binary executables are available for three of the most widely used
+platforms: 32-bit Linux, Mac OSX, and Windows. If your platform is not
+compatible with any of these, you can build the software from the
+source code.
+
+\subsection{Linux}
+
+Running the Linux binary version of PyLith requires a 32-bit
+compatible machine with GLIBC 2.2 or later.
+
+\begin{enumerate}
+\item Download the \link{tarball}{http://crust.geodynamics.org/~leif/shipping/}
+\item Unpack the tarball in a suitable location.
+ \begin{screen}
+ \prompt{bash~}\userinput{tar -zxvf pylith-0.8-linux-x86.tar.gz}
+ \end{screen}
+\item Add \directory{pylith-0.8-linux-x86/bin} to your \envvar{PATH}.
+ You will likely want to add something like
+ \begin{screen}
+ PATH=\$\{PATH\}:\replaceable{replace\_with\_absolute\_path}/pylith-0.8-linux-x86/bin
+ \end{screen}
+ to your \filename{.bashrc} file (if you are using bash as your shell)
+ or the equivalent to your \filename{.cshrc} file (if you are using
+ tcsh as your shell).
+\item Add \directory{pylith-0.8-linux-x86/lib}to your
+ \envvar{LD\_LIBRARY\_PATH}. You will likely want to add something like
+ \begin{screen}
+ export LD\_LIBRARY\_PATH=\$\{LD\_LIBRARY\_PATH\}:\replaceable{replace\_with\_}
+ \replaceable{absolute\_path}/pylith-0.8-linux-x86/lib
+ \end{screen}
+ to your \filename{.bashrc} file (if you are using bash as your
+ shell) or the equivalent to your \filename{.cshrc</filename} file
+ (if you are using tcsh as your shell).
+\item To uninstall PyLith, simply remove the \directory{pylith-0.8-linux-x86}
+ directory and all of its sub-directories.
+\end{enumerate}
+
+\subsection{Mac OSX}
+
+The OSX binary version was built to run on the Macintosh PowerPC
+architecture with OSX version 10.2 or later. The binary will run on
+the Macintosh Intel architecture, but only in emulation mode (i.e.,
+rather slowly).
+
+\begin{enumerate}
+\item Download the \link{disk image}{http://crust.geodynamics.org/~leif/shipping/}.
+\item Double click on the disk image to mount the disk.
+\item Double click on the disk and copy the \directory{PyLith} folder
+ to a suiteable location.
+\item To run PyLith, double click on the PyLith icon provided in the \directory{PyLith} folder.
+\item To uninstall PyLith, simply drag the \directory{PyLith} folder
+ to the trash.
+\end{enumerate}
+
+\subsection{Windows}
+
+This Windows binary version of PyLith should be compatible with
+Windows NT, Windows 2000, and Windows XP.
+
+\begin{enumerate}
+\item Download theq
+ \link{installer}{http://crust.geodynamics.org/~leif/shipping/}.
+\item Double click on the \filename{setup.exe} file you just
+ downloaded and follow the instructions for installing.
+\item To run PyLith, double click on the PyLith icon on the desktop or
+ select
+ \guimenu{Start}\guiselect\guimenuitem{All~Programs}\guiselect\guimenuitem{PyLith}\guiselect\guimenuitem{PyLith}.
+\item To uninstall PyLith, simply select
+ \guimenu{Start}\guiselect\guimenuitem{All
+ Programs}\guiselect\guimenuitem{PyLith}\guiselect\guimenuitem{Uninstall~PyLith}.
+\end{enumerate}
+
+\section{Building using source tarball}
+
+Building PyLith from the source code is not a trivial task because
+PyLith depends on several other packages. In general, each package
+must be compiled from source using compilers for each language that
+are compatible with one another. The stable version of the PyLith
+source code is available from the \link{Geodynamics subversion
+ repository}{http://www.geodynamics.org:8080/cig/software/Repository/}
+\directory{cig/short/3D/PyLith/branches/pylith-0.8}.
+
+\subsection{System Requirements}
+
+\begin{itemize}
+\item Unix flavored operating system.
+\item Fortran, C, and C++ compilers.
+\item Python (2.3 or later)
+\end{itemize}
+
+The software must be built starting from the bottom of the dependency
+list and working upwards. The steps below describe the recommended way
+to build PyLith and the external packages on which it depends. Some of
+the dependencies can be satisfied using precompiled binaries (e.g.,
+RedHat and Fink packages). When considering whether to use a
+precompiled binary package to satisfy any of the dependencies,
+remember that all of the compilers and settings used in building the
+code must be compatible.
+
+\begin{enumerate}
+\item Build PETSc and MPI.
+ \begin{enumerate}
+ \item ADD STUFF HERE (LINK TO PETSC SITE? GET MATT'S THOUGHTS ON HOW
+ MUCH DETAIL TO PUT HERE)
+ \end{enumerate}
+\item Build Pythia.
+ \begin{enumerate}
+ \item ADD STUFF HERE
+ \end{enumerate}
+\item Build PyLith.
+ \begin{enumerate}
+ \item ADD STUFF HERE
+ \end{enumerate}
+\end{enumerate}
+
+\section{Building using source repositories}
+
+\begin{warning}
+ Building PyLith using the source repositories is recommended
+ only for expert users who are willing to work with a moving
+ target and rebuild on a frequent basis. The installation
+ instructions cover the basic steps and assume the user has
+ experience building and installing software.
+\end{warning}
+
+The PyLith-0.8 source code is available from the \link{Geodynamics
+ subversion
+ repository}{http://www.geodynamics.org:8080/cig/software/Repository}
+\directory{cig/short/3D/PyLith/branches/pylith-0.8}.
+
+\subsection{System Requirements}
+
+\begin{itemize}
+\item Unix flavored operating system
+\item Fortran, C, and C++ compilers
+\item Python (2.3 or later)
+\item Subversion
+\item Mercurial (0.9 or later)
+\end{itemize}
+
+\begin{tip}
+ Many flavors of Unix have Subversion packages. In most
+ cases you do not need anything but the basic subversion
+ package. You will likely have to build Mercurial from
+ source, but this is a very easy task that takes only a
+ couple of minutes.
+\end{tip}
+
+\subsection{Building the packages}
+
+The software must be built starting from the bottom of the dependency
+list and working upwards. The steps below describe the recommended way
+to build PyLith and the external packages on which it depends.
+
+\begin{enumerate}
+\item Build \link{PETSc (developers
+ version)}{http://www-unix.mcs.anl.gov/petsc/petsc-as/developers/index.html}
+ and MPI.
+
+ If you have an architecture optimized version of BLAS/LAPACK you
+ should use those instead of asking PETSc to download and build one
+ for you. In some cases, PETSc will find known optimized
+ implementations of BLAS/LAPACK (e.g., vecLib on Mac OSX).
+
+ If you have an MPI implementation installed, you can use it or let
+ PETSc download and install one for you.
+
+ \begin{tip}
+ If you run into problems configuring or building PETSc, send {\em
+ both} \filename{configure.log} and
+ \filename{make\_\replaceable{PETSC\_ARCH}} to
+ \email{petsc-maint at mcs.anl.gov}.
+ \end{tip}
+
+ \begin{enumerate}
+ \item Pull the source code from ANL and place the source tree in a
+ suitable location. The steps below will create a
+ \directory{petsc-dev} sub-directory in the current directory.
+
+ \begin{screen}
+ \shellprompt\userinput{hg clone http://mercurial.mcs.anl.gov/petsc/petsc-dev}
+ \shellprompt\userinput{cd petsc-dev/python}
+ \shellprompt\userinput{hg clone http://mercurial.mcs.anl.gov/petsc/BuildSystem \
+ BuildSystem}
+ \end{screen}
+
+ \item Set the \envvar{PETSC\_DIR} and \envvar{PETSC\_ARCH} environment
+ variables. \envvar{PETSC\_DIR} corresponds to the top-level
+ directory in the PETSc source tree and \envvar{PETSC\_ARCH} is a tag
+ for this configuration of PETSc (e.g., linux\_gcc-4.0\_debug,
+ darwin\_gcc-3.4\_opt, etc). You will want to set these environment
+ variables in your \filename{.bashrc}, \filename{.cshrc}, or
+ similar file.
+
+ \begin{screen}
+ \shellprompt\userinput{export PETSC\_DIR=\replaceable{replace\_with\_absolute\_path}/petsc-dev}
+ \shellprompt\userinput{export PETSC\_ARCH=\replaceable{replace\_with\_PETSc\_arch\_tag}}
+ \end{screen}
+ \item Configure PETSc.
+
+ Run \command{config/configure.py} with the appropriate arguments
+ to configure PETSc for your computer. Run
+ \command{config/configure.py --help} to see the long list of
+ possible options. Building PETSc for use with PyLith requires the
+ following arguments:
+
+ \begin{screen}
+ \option{--with-clanguage=c++}
+ \option{--with-c-support}
+ \option{--with-shared=1}
+ \option{--with-boost=1}
+ \option{--download-boost=1}
+ \option{--with-sieve=1}
+ \end{screen}
+
+ Be sure to include flags indicating where MPI and
+ BLAS/LAPACK are if you want to use a preinstalled
+ implementation. If not, be sure to tell PETSc to
+ download those packages. If you do not want build
+ PETSc using the gnu compilers, be sure to let PETSc
+ know which compilers you want to use instead.
+
+ After several minutes, the configure script should
+ finish and display the PETSc settings. Check to make
+ sure these match your expectations before continuing.
+
+ \item Build PETSc.
+ \begin{screen}
+ \shellprompt\userinput{make}
+ \end{screen}
+ \item Test PETSc installation.
+
+ One of the tests will attempt to display some X windows. If X
+ windows is not available from the shell in which you run
+ \command{make test}, then that test will fail.
+
+ \begin{screen}
+ \shellprompt\userinput{make test}
+ \end{screen}
+
+ \item In the future, you will likely want to update the PETSc source
+ tree to include bug fixes, new features etc.
+
+ To update PETSc (use to \command{hg update -v} to see what files
+ are being updated):
+
+ \begin{screen}
+ \shellprompt\userinput{cd petsc-dev}
+ \shellprompt\userinput{hg pull}
+ \shellprompt\userinput{hg update}
+ \shellprompt\userinput{cd python/BuildSystem}
+ \shellprompt\userinput{hg pull}
+ \shellprompt\userinput{hg update}
+ \end{screen}
+ \end{enumerate}
+
+\item Build Pythia.
+
+ \begin{tip}
+ If you run into problems configuring or building Pythia, send
+ {\em both} the \filename{config.log} and
+ \filename{make.log} files to
+ \email{cig-short at geodynamics.org}. To create the
+ \filename{make.log} file, run make via \command{make $>$ make.log}.
+ \end{tip}
+
+ \begin{enumerate}
+ \item Pull the source code from CIG and place the source tree in a
+ suitable location. The steps below will create a
+ \directory{pythia-0.8} sub-directory in the current directory.
+
+ \begin{screen}
+ \shellprompt\userinput{svn co svn://geodynamics.org/cig/vendor/pythia [cont.]\\
+ /v0.8/pythia-0.8}
+ \end{screen}
+
+ \item Configure Pythia.
+
+ Run \command{configure} with the appropriate arguments.
+ Run \command{configure --help} to see a list of possible
+ options. You may want to specify compilers and/or an install
+ location.
+
+ \begin{screen}
+ \shellprompt\userinput{cd pythia-0.8}
+ \shellprompt\userinput{autoreconf -i}
+ \shellprompt\userinput{./configure}
+ \end{screen}
+
+ \item Build Pythia.
+
+ Run \command{make} and \command{make install}.
+
+ \begin{screen}
+ \shellprompt\userinput{make}
+ \shellprompt\userinput{make install}
+ \end{screen}
+
+ \end{enumerate}
+
+\item Build PyLith.
+
+ \begin{tip}
+ If you run into problems configuring or building PyLith, send
+ {\em both} the \filename{config.log} and
+ \filename{make.log} files to
+ \email{cig-short at geodynamics.org}. To create the
+ \filename{make.log} file, run make via \command{make $>$ make.log}.
+ \end{tip}
+
+ \begin{enumerate}
+ \item Pull the source code from CIG and place the source tree in a
+ suitable location. The steps below will create a
+ \directory{pylith-0.8} sub-directory in the current directory.
+
+ \begin{screen}
+ \shellprompt\userinput{svn co svn://geodynamics.org/cig/short/3D/PyLith [cont.]\\
+ /branches/pylith-0.8}
+ \end{screen}
+
+ \item Configure PyLith.
+
+ Run \command{configure} with the appropriate arguments. Run
+ \command{configure --help} to see a list of possible options. You
+ may want to specify compilers and/or an install location. If you
+ installed pythia-0.8 in a non-system location, you will need to
+ set \envvar{CPPFLAGS} and \envvar{LDFLAGS} appropriately.
+
+ \begin{screen}
+ \shellprompt\userinput{cd pylith-0.8}
+ \shellprompt\userinput{autoreconf -i}
+ \shellprompt\userinput{./configure}
+ \end{screen}
+
+ \item Build PyLith.
+
+ Run \command{make} and \command{make install}.
+
+ \begin{screen}
+ \shellprompt\userinput{make}
+ \shellprompt\userinput{make install}
+ \end{screen}
+ \end{enumerate}
+\end{enumerate}
Added: short/3D/PyLith/branches/pylith-0.8/doc/userguide/intro/intro.tex
===================================================================
--- short/3D/PyLith/branches/pylith-0.8/doc/userguide/intro/intro.tex 2006-08-22 13:08:01 UTC (rev 4397)
+++ short/3D/PyLith/branches/pylith-0.8/doc/userguide/intro/intro.tex 2006-08-22 15:30:52 UTC (rev 4398)
@@ -0,0 +1,220 @@
+\chapter{Introduction}
+
+\section{Overview}
+
+PyLith is a multi-scale simulation software package for earthquake
+physics. It is portable, scalable software for simulation of crustal
+deformation across spatial scales ranging from meters to hundreds of
+kilometers and temporal scales ranging from milliseconds to thousands
+of years
+
+\section{History}
+
+This first version of PyLith is a direct descendant of Lithomop and
+marks the first version that runs in parallel. Lithomop was the
+product of major reengineering of Tecton, a finite-element code for
+simulating static and quasi-static crustal deformation. The major new
+features present in Lithomop included dynamic memory allocation and
+the use of the Pyre simulation framework and PETSc solvers. </para>
+<para> PyLith is currently being rewritten from scratch to create a
+much more modular, powerful simulation package. This new code will
+include earthquake dynamics (both rupture propagation and seismic wave
+propagation). A beta release is expected in late 2006.
+
+\section{Governing Equations}
+
+Both LithoMop3d and PyLith-0.8 are quasi-static codes, meaning that
+time-dependence only enters through the constitutive relationships and
+the loading conditions. The description here is for the small-strain
+formulation, which is the only formulation available at present. If a
+large deformation solution is desired, interested users may contact
+Charles Williams (willic3 at rpi.edu) about a version of the finite
+element code TECTON.
+
+The problem is formulated in terms of the stresses ($\sigma_{ij}$),
+displacements ($u_i$), and body forces per unit volume
+(figs/g-inlineeq1.eps). We use standard index notation for all
+equations here, such that repeated indices imply summation and a comma
+denotes differentiation. For a general three-dimensional body, the
+problem must satisfy the equilibrium conditions
+\begin{equation}
+ \text{figs/g-eq1.eps}
+\end{equation}
+subject to the natural boundary conditions
+\begin{equation}
+ \text{figs/g-eq2.eps}
+\end{equation}
+and the essential boundary conditions
+\begin{equation}
+ \text{figs/g-eq3.eps}
+\end{equation}
+The surface of the body is $S$, given by
+\begin{equation}
+ \text{figs/g-eq4.eps}
+\end{equation}
+The $n_j$ are the components of the unit normal vector to $S$, the
+\begin{equation}
+ \text{figs/g-inlineeq2.eps}
+\end{equation}
+are the components of the surface tractions, and the
+\begin{equation}
+ \text{figs/g-inlineeq3.eps}
+\end{equation}
+are the components of the applied displacements. The stresses are
+computed from the strains and any existing initial stresses using a
+given constitutive relationship. The strains are given by
+\begin{equation}
+\text{figs/g-eq5.eps}
+\end{equation}
+For a linear elastic material, the constitutive relationship between
+stress and strain is
+\begin{equation}
+ \text{figs/g-eq6.eps}
+\end{equation}
+where
+\begin{equation}
+ \text{figs/g-inlineeq4.eps}
+\end{equation}
+are the initial stresses, and $C$
+\begin{equation}
+ \text{g-inlineeq5.eps}
+\end{equation}
+is the elastic constitutive relation.
+
+For inelastic behavior (viscous, plastic, etc.), we assume an additive
+decomposition of the strain tensor into elastic and inelastic parts,
+and use an integrated form of the classical incremental theory of
+plasticity. At time $t+\Delta t$, he stresses are therefore computed
+from the total elastic strain:
+\begin{equation}
+ \text{figs/g-eq7.eps}
+\end{equation}
+where
+\begin{equation}
+ \text{figs/g-inlineeq6.eps}
+\end{equation}
+are the total strains and
+\begin{equation}
+ \text{figs/g-inlineeq7.eps}
+\end{equation}
+are the inelastic strains, with the difference being the elastic
+strains. In our actual computations, we use a formulation that
+decomposes the stresses into the deviatoric and volumetric parts,
+using ideas based on the "effective stress function"
+\cite{Kojic:Bathe:1987}. This allows the time integration of stresses
+to be performed in terms of a single parameter related to the second
+deviatoric stress invariant.
+
+\section{Software Components}
+
+PyLith is separated into modules to encapsulate behavior and
+facilitate use across multiple applications. That way expert users can
+replace functionality of a wide variety of components without
+recompiling or polluting the main code. External packages reduce
+development time and enhance computational efficiency, for example,
+PyLith runs 2x faster by using the PETSc linear solver.
+
+PyLith is based on several programming languages. High-level code is
+written in Python; this rich, expressive interpreted language with
+dynamic typing reduces development time. Low-level code is written in
+Fortran 77 for fast execution. Bindings, written in C/C++, are used to
+allow the low-level code (Fortran 77) to be called from high-level
+code (Python).
+
+PyLith makes extensive use of external software. Pyre is a science
+neutral simulation framework being developed at Caltech. PETSc is used
+to perform operations on matrices and vectors in parallel.
+
+\subsection{PETSc}
+
+\link{PETSc}{http://www-unix.mcs.anl.gov/petsc/petsc-as/}, the
+Portable, Extensible Toolkit for Scientific computation, provides a
+suite of routines for parallel, numerical solution of partial
+differential equations for linear and nonlinear systems with large,
+sparse systems of equations. PETSc includes solvers that implement a
+variety of Newton and Krylov subspace methods. It can also interface
+with many external packages, including BlockSolve95, ESSL, Matlab,
+ParMeTis, PVODE, and SPAI, thereby providing additional solvers and
+interaction with other software packages.
+
+PETSc includes interfaces for Fortran, C, and C++ for nearly all of
+the routines and PETSc can be installed on most Unix systems. PETSc
+can be built with user supplied highly optimized linear algebra
+routines (e.g., ATLAS and commercial versions of BLAS/LAPACK), thereby
+improving application performance. Users can use PETSc parallel
+matrices, vectors, and other data structures for most parallel
+operations, eliminating the need for explicit calls to Message Passing
+Interface (MPI) routines. Many settings and options can be controlled
+with PETSc specific command-line arguments, including selection of
+preconditions, solvers, and generation of performance logs.
+
+\subsection{Pyre}
+
+Pyre is an object-oriented environment capable of specifying and
+launching numerical simulations on multiple platforms, including
+Beowulf class parallel computers and grid computing systems. Pyre
+allows the binding of multiple components such as solid and fluid
+models used in Earth science simulations, and different meshers. The
+Pyre framework enables the elegant setup, modification and launching
+of massively parallel three-dimensional solver applications.
+
+Pyre is a framework, a combination of software and design philosophy
+that promotes the reuse of code. In their canonical software design
+book, {\em Design Patterns}, Erich Gamma {\it et al}. condense the
+concept of a framework concept down to, "When you use a framework, you
+reuse the main body and write the code it calls." In the context of
+frameworks and object-oriented programming, Pyre can be thought of as
+a collection of classes and the way their instances interact.
+Programming applications based on Pyre will look similar to those
+written in any other object-oriented language. The Pyre framework
+contains a subset of parts that make up the overall framework. Each of
+those parts is designed to solve a specific problem.
+
+The framework approach to computation offers many advantages. It
+permits the exchange of codes and promotes the reuse of standardized
+software while preserving efficiency. Frameworks are also an efficient
+way to handle changes in computer architecture. They present
+programmers and scientists with a unified and well-defined task and
+allow for shared costs of the housekeeping aspects of software
+development. They provide greater institutional continuity to model
+development than piecemeal approaches.
+
+
+The Pyre framework incorporates features aimed at enabling the
+scientific non-expert to perform tasks easily without hindering the
+expert. Target features for end users allow complete and intuitive
+simulation specification, reasonable defaults, consistency checks of
+input, good diagnostics, easy access to remote facilities, and status
+monitoring. Target features for developers include easy access to user
+input, a shorter development cycle, and good debugging support.
+
+\begin{figure}[htbp]
+ \begin{center}
+ \includegraphics[scale=0.75]{figs/pyre_overview}
+ \caption{Pyre Architecture. The integration framework is a set of
+ cooperating abstract services.}
+ \end{center}
+\end{figure}
+
+\section{PyLith Design}
+
+In transforming Lithomop, a serial code, into PyLith, a parallel code,
+a principal concern was to preserve the existing structure of the
+serial Fortran code. Active development of purely analytic features in
+PyLith, such as new material models or discretization schemes, depends
+on the familiarity of application scientists with the traditional
+Fortran programming paradigm. Global, topological operation should be
+strictly segregated from the existing code. In fact, with the
+exception of integrating PETSc for serial linear algebra and solver
+operations, PyLith can be run purely in serial without activating any
+of the parallel capabilities.
+
+In order to accomplish this separation, we use the PETSc
+\classname{Sieve} structure to create a model of the serial
+PyLith mesh. This model is then partitioned and distributed to a set
+of processes. Each process receives a self-consistent mesh, meaning
+the pieces are overlapping. Each process then executes a serial PyLith
+step on that particular mesh piece. The PETSc linear algebra
+operations are overloaded, using the \classname{Sieve}
+information, to produce a globally consistent field.
+
Added: short/3D/PyLith/branches/pylith-0.8/doc/userguide/license.tex
===================================================================
--- short/3D/PyLith/branches/pylith-0.8/doc/userguide/license.tex 2006-08-22 13:08:01 UTC (rev 4397)
+++ short/3D/PyLith/branches/pylith-0.8/doc/userguide/license.tex 2006-08-22 15:30:52 UTC (rev 4398)
@@ -0,0 +1,22 @@
+\chapter{PyLith Software License}
+
+Copyright (C) 2004-2006 Rensselaer Polytechnic Institute
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Modified: short/3D/PyLith/branches/pylith-0.8/doc/userguide/makefile
===================================================================
--- short/3D/PyLith/branches/pylith-0.8/doc/userguide/makefile 2006-08-22 13:08:01 UTC (rev 4397)
+++ short/3D/PyLith/branches/pylith-0.8/doc/userguide/makefile 2006-08-22 15:30:52 UTC (rev 4398)
@@ -1,5 +1,5 @@
-XSLSTYLESHEET_DIR=/usr/share/sgml/docbook/xsl-stylesheets
-#XSLSTYLESHEET_DIR=/sw/share/xml/xsl/docbook-xsl
+#XSLSTYLESHEET_DIR=/usr/share/sgml/docbook/xsl-stylesheets
+XSLSTYLESHEET_DIR=/sw/share/xml/xsl/docbook-xsl
pylith_userguide.pdf pdf: pylith_userguide.fo
fop $< pylith_userguide.pdf
Added: short/3D/PyLith/branches/pylith-0.8/doc/userguide/materials/materials.tex
===================================================================
--- short/3D/PyLith/branches/pylith-0.8/doc/userguide/materials/materials.tex 2006-08-22 13:08:01 UTC (rev 4397)
+++ short/3D/PyLith/branches/pylith-0.8/doc/userguide/materials/materials.tex 2006-08-22 15:30:52 UTC (rev 4398)
@@ -0,0 +1,3 @@
+\chapter{Material Models}
+
+\input{maxwell_linear.tex}
Added: short/3D/PyLith/branches/pylith-0.8/doc/userguide/materials/maxwell_linear.tex
===================================================================
--- short/3D/PyLith/branches/pylith-0.8/doc/userguide/materials/maxwell_linear.tex 2006-08-22 13:08:01 UTC (rev 4397)
+++ short/3D/PyLith/branches/pylith-0.8/doc/userguide/materials/maxwell_linear.tex 2006-08-22 15:30:52 UTC (rev 4398)
@@ -0,0 +1,127 @@
+\section{Effective Stress Function Formulation for a Maxwell Linear
+Viscoelastic Material}
+
+\subsection{Determination of stresses}
+
+The element stresses are
+\begin{equation}
+ \text{figs/ml-eq1.eps}
+\end{equation}
+where ?? is the total strain and $\text{ml-inlineeq1}$ is the initial
+stress. In terms of the deviatoric stress,
+\begin{equation}
+ \text{figs/ml-eq2.eps}
+\end{equation}
+where
+\begin{equation}
+ \text{figs/ml-eq3.eps}
+\end{equation}
+and the mean stress and strain are given by
+\begin{equation}
+ \text{figs/ml-eq4.eps}
+\end{equation}
+Equation~(2) [REPLACE WITH REF] may also be written as
+\begin{equation}
+ \text{figs/ml-eq4.eps}
+\end{equation}
+where
+\begin{equation}
+ \text{figs/ml-eq6.eps}
+\end{equation}
+The creep strain increment is approximated using
+\begin{equation}
+ \text{figs/ml-eq7.eps}
+\end{equation}
+where, using the $\alpha$-method of time integration,
+\begin{equation}
+ \text{figs/ml-eq8.eps}
+\end{equation}
+and
+\begin{equation}
+ \text{figs/ml-eq9.eps}
+\end{equation}
+where
+\begin{equation}
+ \text{figs/ml-eq10.eps}
+\end{equation}
+and
+\begin{equation}
+ \text{figs/ml-eq11.eps}
+\end{equation}
+For a linear Maxwell viscoelastic material
+\begin{equation}
+ \text{figs/ml-eq12.eps}
+\end{equation}
+Therefore,
+\begin{equation}
+ \text{figs/ml-eq13.eps}
+\end{equation}
+Subsituting (8), (12), and (13) into (5) [REPLACE WITH REFS], we obtain
+\begin{equation}
+ \text{figs/ml-eq14.eps}
+\end{equation}
+Solving for $\text{figs/ml-inlineeq2}$,
+\begin{equation}
+ \text{figs/ml-eq15.eps}
+\end{equation}
+In this case it is possible to solve directly for the deviatoric
+stresses, and the effective stress function approach is not needed. To
+obtain the total stress, we simply use
+\begin{equation}
+ \text{figs/ml-eq16.eps}
+\end{equation}
+
+\subsection{Tangent stress-strain relation}
+
+It is now necessary to provide a relationship for the viscoelastic
+tangent material matrix. If we use vectors composed of the stresses
+and tensor strains, this relationship is
+\begin{equation}
+ \text{figs/ml-eq17.eps}
+\end{equation}
+In terms of the vectors, we have
+\begin{equation}
+ \text{figs/ml-eq18.eps}
+\end{equation}
+Therefore,
+\begin{equation}
+ \text{figs/ml-eq19.eps}
+\end{equation}
+Using the chain rule,
+\begin{equation}
+ \text{figs/ml-eq20.eps}
+\end{equation}
+From (6) [REPLACE WITH REF], we obtain
+\begin{equation}
+ \text{figs/ml-eq21.eps}
+\end{equation}
+and from (3) [REPLACE WITH REF]
+\begin{equation}
+ \text{figs/ml-eq22.eps}
+\end{equation}
+Finally, from (15) [REPLACE WITH REF], we have
+\begin{equation}
+ \text{figs/ml-eq23.eps}
+\end{equation}
+From (19) [REPLACE WITH REF], the final material matrix relating
+stress and tensor strain is
+\begin{equation}
+ \text{figs/ml-eq24.eps}
+\end{equation}
+Note that the coefficient of the second matrix approaches $E/3(1+\nu)$
+as $\eta$ goes to infinity. Since finite element computations
+typically use engineering strain measures, the matrix that is actually
+used is
+\begin{equation}
+ \text{figs/ml-eq25.eps}
+\end{equation}
+To check the results we make sure that the regular elastic
+constitutive matrix is obtained for selected terms in the case where
+$\eta$ goes to infinity.
+\begin{equation}
+ \text{figs/ml-eq26.eps}
+\end{equation}
+This is consistent with the regular elasticity matrix, and equation
+(25) [REPLACE WITH REF] should thus be used when forming the stiffness
+matrix.
+
Added: short/3D/PyLith/branches/pylith-0.8/doc/userguide/preface.tex
===================================================================
--- short/3D/PyLith/branches/pylith-0.8/doc/userguide/preface.tex 2006-08-22 13:08:01 UTC (rev 4397)
+++ short/3D/PyLith/branches/pylith-0.8/doc/userguide/preface.tex 2006-08-22 15:30:52 UTC (rev 4398)
@@ -0,0 +1,45 @@
+\chapter{Preface}
+
+\section{About This Document}
+
+This document is organized into two parts. Part I begins with an
+introduction to PyLith and discusses how to run the software. Part II
+provides appendices and references.
+
+\section{Who Will Use This Documentation}
+
+This documentation is aimed at scientists who prefer to use
+prepackaged and specialized analysis tools. Users are likely to be
+experienced computational earth scientists and have familiarity with
+basic scripting, software installation, and programming; but are not
+likely to be professional programmers. Of those, there are likely to
+be two classes of users: those who run models and those who modify the
+source code.
+
+\section{Citation}
+
+The Computational Infrastructure for Geodynamics (CIG) is making this
+source code available to you at no cost in hopes that the software
+will enhance your research in geophysics. A number of individuals have
+contributed a significant portion of their careers toward the
+development of this software. It is essential that you recognize these
+individuals in the normal scientific practice by citing the
+appropriate peer reviewed papers and making appropriate
+acknowledgements in talks and publications. NEED CITATION INFORMATION
+
+\section{Support}
+
+Current PyLith development is supported by the Southern California
+Earthquake Center, the National Science Foundation, the CIG, and
+internal U.S. Geological Survey funding. Pyre development is funded by
+the \link{Department of
+ Energy's}{http://www.doe.gov/engine/content.do} Advanced Simulation
+and Computing program and the \link{National Science
+ Foundation's}{http://www.nsf.gov} Information Technology Research
+(ITR) program.
+
+\section{Request for Comments}
+
+Your suggestions and corrections can only improve this documentation.
+Please report any errors, inaccuracies, or typos to sue (at)
+geodynamics.org.
Added: short/3D/PyLith/branches/pylith-0.8/doc/userguide/references.bib
===================================================================
--- short/3D/PyLith/branches/pylith-0.8/doc/userguide/references.bib 2006-08-22 13:08:01 UTC (rev 4397)
+++ short/3D/PyLith/branches/pylith-0.8/doc/userguide/references.bib 2006-08-22 15:30:52 UTC (rev 4398)
@@ -0,0 +1,10 @@
+ at Article{Kojic:Bathe:1987,
+ author = {Kojic, M. and K.~J. Bathe},
+ title = {The 'Effective Stress-Function' Algorithm for
+ Thermo-Elasto-Plasticity and Creep},
+ journal = {Int. J. Num. Meth. Eng.},
+ year = {1987},
+ volume = {24},
+ pages = {1509--1532},
+}
+
Added: short/3D/PyLith/branches/pylith-0.8/doc/userguide/tutorials/reversenog/reversenog.tex
===================================================================
--- short/3D/PyLith/branches/pylith-0.8/doc/userguide/tutorials/reversenog/reversenog.tex 2006-08-22 13:08:01 UTC (rev 4397)
+++ short/3D/PyLith/branches/pylith-0.8/doc/userguide/tutorials/reversenog/reversenog.tex 2006-08-22 15:30:52 UTC (rev 4398)
@@ -0,0 +1,416 @@
+\section{Tutorial Using Reverse-Slip Without Gravity Benchmark}
+
+\subsection{Overview}
+
+In this tutorial, we will walk through the steps necessary to
+construct, run, and view the results of a benchmark problem involving
+reverse slip on a dipping fault. This problem examines the
+viscoelastic (Maxwell) relaxation of stress from a single, finite,
+reverse-slip earthquake in 3-D without body forces.
+
+
+\subsection{Problem Description}
+
+The model domain is a cube with edges 24 km long (0 km $\leq$ x $\leq$
+24 km; 0 km $\leq$ y $\leq$ 24 km; -24 km $\leq$ z $\leq$ 0) and
+is composed of two materials. One material occupies the top-half of
+the domain, -12 km $\leq$ z $\leq$ 0 km, while the other occupies
+the lower half, -24 km $\leq$ z $<$ 12 km. Both materials are Poisson
+solids with Lame's constants ($\mu$ and $\lambda$) equal to 30 GPa and
+Maxwell viscoelastic properties. The top layer has a viscosity of
+$10^25$ Pa-s (and is essentially elastic) while the bottom layer has a
+viscosity of $10^18$ Pa-s.
+
+The reverse fault dips at an angle of 45 degrees. The top of the fault
+sits at x = 4 km with the bottom of the fault at x = 20 km. The fault
+surface is confined to the region 0 km $\leq$ y $\leq$ 16 km and -16
+km $\leq$ z $\leq$ 0 km. The slip distribution is 1.0 m of uniform
+thrust motion for -12 km $\leq$ z with a linear taper to 0 at z = -16
+km.
+
+The plane y=0 is a plane of symmetry, so the y-DOF displacements on
+this face are zero. The boundary conditions on the other lateral faces
+and bottom of the mesh are the displacements from the analytical
+elastic solution. These displacements are held fixed through time.
+
+\begin{figure}
+ \begin{center}
+ \includegraphics{figs/geometry}
+ \caption{Geometry of model domain for reverse-slip benchmark.}
+ \end{center}
+\end{figure}
+
+\subsubsection{Workflow}
+
+The complete workflow used to create the input files for this tutorial
+is shown in figure~\ref{fig:bmrsnog:workflow}. Because some of the
+steps involve commercial software (e.g., Matlab), we will skip those
+steps in this tutorial.
+
+\begin{figure}[htbp]
+ \begin{center}
+ \includegraphics{figs/workflow}
+ \caption{Workflow for setting up input files for benchmark with reverse
+ slip and no gravity.}
+ \label{fig:bmrsnog:workflow}
+ \end{center}
+\end{figure}
+
+\subsection{Download and unpack}
+
+We will start by downloading the tutorial tarball and unpacking it.
+
+\begin{enumerate}
+\item Download the \link{tutorial
+ tarball}{http://www.geodynamics.org:8080/cig/Members/willic3/pylithusers/pylith0.8/pylith-0.8\_tutorials.tgz}
+ and unpack it in a location of your choosing.
+
+ \begin{screen}
+ \shellprompt\userinput{tar -zxvf pylith-0.8\_tutorials.tgz}
+ \end{screen}
+
+\item Go to the \directory{tutorials/reversenog} directory.
+ The \directory{archive} directory contains all of the input and
+ output files associated with this tutorial. We will copy input files
+ from this directory into the \directory{workarea} directory. At each
+ step, you can check to make sure your input and output agree with
+ the files in the \directory{archive} directory. These files also
+ allow you to start at an intermediate step as described in the next
+ section.
+
+ \begin{screen}
+ \shellprompt\userinput{cd tutorials/reversenog}
+ \end{screen}
+
+\end{enumerate}
+
+\subsection{Tutor}
+
+Copy the \filename{tutor.py} script from the \directory{archive}
+directory into the \directory{workarea} directory.
+
+\begin{tip}
+ If you have run this tutorial previously, you may want to run
+ \command{tutor.py} in mode "clean" with step "all" to clear out all
+ old tutorial files.
+\end{tip}
+
+\begin{screen}
+\shellprompt\userinput{cd workarea}
+\shellprompt\userinput{cp ../archive/tutor.py .}
+\shellprompt\userinput{./tutor.py -m clean -s all}
+\end{screen}
+
+\subsection{Generate the mesh}
+
+In this step we will generate the finite-element mesh for the
+benchmark problem using \application{NETGEN}.
+
+\begin{enumerate}
+\item In the \directory{reversenog/workarea} directory, run
+ \command{tutor.py} for step "mesh" with mode "retrieve" to fetch the
+ geometry file for \application{NETGEN}. You may also want to run
+ \command{tutor.py} for this step with mode "clean" to clean out old
+ files.
+
+ \begin{screen}
+ \shellprompt\userinput{./tutor.py -m retrieve -s mesh}
+ \shellprompt\userinput{./tutor.py -m clean -s mesh}
+ \end{screen}
+
+\item Examine the \filename{bmrsnog.geo} file to see how the geometry
+ for the problem is defined. Notice that the different planes have
+ been flagged with different boundary condition codes. These will be
+ used to associate boundary conditions with surfaces and element
+ nodes.
+\item Start up \application{NETGEN} by running \command{ng}.
+
+ \begin{screen}
+ \shellprompt\userinput{ng}
+ \end{screen}
+
+\item Select \guimenu{File}\guiselect\guimenuitem{Load Geometry}
+ and select \filename{bmrsnog.geo}.
+\item Click on \guibutton{Generate Mesh}.
+\item Export the mesh to a file named \filename{bmrsnog.netgen},
+ making sure the export filetype is "Neutral format".
+\item You can now exit \application{NETGEN}.
+\end{enumerate}
+
+\subsection{Setup simulation input files}
+
+In this step we will setup the PyLith input files for the mesh and
+boundary conditions.
+
+\begin{enumerate}
+\item Run \command{tutor.py} for step "setup" with mode "retrieve" to
+ fetch files from the archive.
+
+ \begin{screen}
+ \shellprompt\userinput{./tutor.py -m retrieve -s setup}
+ \end{screen}
+
+\item We will use two simple Fortran utilities to generate PyLith
+ input files from the \application{NETGEN} output.
+
+ \begin{description}
+ \item[\command{readnetgen}] A Fortran program to read
+ \application{NETGEN} neutral format and create several of the
+ input files needed by PyLith.
+ \item[\command{faultcalc}] A Fortran program to compute split node
+ displacements using second order polynomials over specified
+ regions.
+ \end{description}
+
+\item Run the \command{readnetgen} utility program to process the
+ \application{NETGEN} output file into PyLith compatible input files.
+ It will ask for a root filename, enter \filename{bmrsnog}. This
+ utilitiy will generate the following files:
+ \filename{bmrsnog.w01.wink}, \filename{bmrsnog.coord},
+ \filename{bmrsnog.connect}, \filename{bmrsnog.bc},
+ \filename{bmrsnog.1.fcoord}, \filename{bmrsnog.1.fbc}.
+
+ \begin{screen}
+ \shellprompt\userinput{../../utils/readnetgen}
+ \prompt{~Enter root name for all files. Both input and}\\
+ \prompt{~output files will all have this prefix:}\\
+ \userinput{bmrsnog}
+ \end{screen}
+
+\item The boundary conditions on the fault for this benchmark are
+ somewhat complex. The utility program \command{faultcalc} creates
+ split node boundary conditions over specified regions, using
+ functions based on second degree polynomials. The
+ \command{readnetgen} program has already produced the main input for
+ \command{faultcalc} -- split node definitions in
+ \filename{bmrsnog.1.fbc} and nodal coordinates in
+ \filename{bmrsnog.coord}. The file \filename{bmrsnog.fault.par}
+ contains the polynomial coefficients for this benchmark problem. Run
+ \command{faultcalc} to get the \filename{bmrsnog.split} file that
+ PyLith needs as input.
+
+ \begin{screen}
+ \shellprompt\userinput{../../utils/faultcalc p=bmrsnog.fault.par n=bmrsnog.coord\\
+ i=bmrsnog.1.fbc o=bmrsnog.split}
+ \end{screen}
+
+\item The external boundary conditions for this benchmark are also
+ complicated and require computing the displacements for the
+ analytical elastic solution at each finite element node on the
+ external boundaries. The file specifying these boundary conditions,
+ \filename{bmrsnog.bc}, was produced with \command{readnetgen} using
+ the \filename{bmrsnog.aux} file (which contains precomputed
+ displacements for the external boundaries for the mesh produced from
+ the \filename{bmrsnog.geo} geometry).
+
+ \begin{warning}
+ If you make any changes to \filename{bmrsnog.geo} or change the
+ geometry within \application{NETGEN}, the boundary condition file
+ \filename{bmrsnog.bc} will no longer be correct and you will have
+ to generate one yourself. Note that it is also possible that a
+ different version of \application{NETGEN} may provide a slightly
+ different mesh, which would also be incompatible with the provided
+ boundary conditions.
+ \end{warning}
+\end{enumerate}
+
+\subsection{Run the simulation on one processor}
+
+In this step we will run the simulation on a single processor.
+
+\begin{enumerate}
+\item Run \command{tutor.py} for step "run1" with mode "retrieve" to
+ fetch some parameter files from the archive.
+
+ \begin{screen}
+ \shellprompt\userinput{./tutor.py -m retrieve -s run1}
+ \end{screen}
+
+\item In \filename{bmrsnog.fuldat}, we have specified that we want
+ full output at time steps 10, 50, and 100. We define six materials
+ with both elastic and viscoelastic behavior in
+ \filename{bmrsnog.prop}. In \filename{bmrsnog.statevar} we choose to
+ include total stress, total strain, incremental stress, and
+ incremental strain in the output. As defined in
+ \filename{bmrsnog.time}, the simulation will have 100 time steps of
+ 0.1 year each.
+\item Run the simulation by executing \userinput{runbm.py -n 1}, where
+ the 1 refers to the number of processors.
+
+ \begin{tip}
+ All of the input is echoed in the file \filename{bmrsnog.ascii}.
+ You can check to make sure your input is digested correctly by
+ examining this file. For large problems, this file can be quite
+ large. You can suppress creation of this file using the command
+ line argument \option{--scanner.asciiOutput=none} flag. On the
+ other hand, for debugging purposes in small problems, you may wish
+ to output everything, including the computed results, in this file
+ using \option{--scanner.asciiOutput=full}.
+ \end{tip}
+
+ \begin{screen}
+ \shellprompt\userinput{./runbm.py -n 1}
+ \end{screen}
+\end{enumerate}
+
+\subsection{Visualize the single processor run}
+
+Now it is time to visualize the results of the simulation. By default,
+PyLith writes simulation output using \link{\application{AVS} UCD
+ files}{http://help.avs.com/Express/doc/help/reference/dvmac/UCD\_Form.htm}.
+These can be read by several other visualization tools besides
+\application{AVS}, e.g., \application{ParaView} and \application{Iris
+ Explorer}. We will use the open-source application
+\application{ParaView} to visualize the results.
+
+\begin{enumerate}
+\item If necessary, run \command{tutor.py} for step "viz1" with mode
+ "retrieve" to fetch the simulation output from the archive.
+
+ \begin{screen}
+ \shellprompt\userinput{./tutor.py -m retrieve -s viz1}
+ \end{screen}
+
+\item PyLith does not write complete UCD files. So the first step is
+ to combine the mesh topology information with the output at a given
+ time step into a complete UCD file. For example, use \command{cat}
+ to merge the nodal coordinates file
+ (\filename{bmrsnog\_1.0.mesh.inp}) and the nodal displacements at
+ time step 10 file (\filename{bmrsnog\_1.0.mesh.time.00010.inp}) into
+ \filename{bmrsnog\_1.0.mesh.t00010.inp}.
+
+ \begin{screen}
+ \shellprompt\userinput{cat bmrsnog\_1.0.mesh.inp bmrsnog\_1.0.mesh.time.00010.inp \ \\
+> bmrsnog\_1.0.mesh.t00010.inp}
+\end{screen}
+
+\item Start \application{ParaView} by executing \command{paraview}.
+
+ \begin{screen}
+ \shellprompt\userinput{paraview}
+ \end{screen}
+
+\item Load the UCD file that you just created by selecting
+ \guimenu{File}\guiselect\guimenuitem{Open Data}. Select the file in
+ the dialog box and the click the \guibutton{Open} button. Click the
+ \guibutton{Accept} button. You should see a color rendering of the x
+ displacements. You can use the mouse to rotate, translate, and zoom.
+ Your image should look similar to the one in
+ figure~\ref{fig::bmrsnog:xdisp:t10}.
+
+ \begin{figure}[htbp]
+ \begin{center}
+ \includegraphics{figs/xdisp_t10}
+ \caption{ParaView rendering of displacement in x-direction at
+ time step 10 (10 yrs after imposed dislocation) for the
+ reverse slip without gravity benchmark.}
+ \label{fig:bmrsnog:xdisp:t10}
+ \end{center}
+ \end{figure}
+
+\item In the \guibutton{Display} tab, you can change several options,
+ such as including a color bar, coloring a different component,
+ interpolating colors, and changing the color map.
+\item Let's show the displacements as vectors. Click on the calculator
+ icon, and add the three displacement components together. Enter
+ "XDispl*iHat+YDispl*jHat+ZDispl*kHat" in the \guimenuitem{Calculator}
+ box. Note the variable names are available by clicking on the
+ \guibutton{scalars} button and the \guibutton{iHat},
+ \guibutton{jHat}, \guibutton{kHat} buttons are on the right side of
+ the top row. Click on the \guibutton{Accept} button. To show the
+ dataset as vectors, click on the \guibutton{glyph} button (looks
+ like several dots) in the toolbar. After clicking the
+ \guibutton{Accept} button, you should have a vector plot. You can
+ turn on/off other datasets by clicking on the eye icon to the left
+ of the dataset name. If you color the surfaces using the
+ x-displacements field while also making the displacement vectors
+ visible (colored using property), you should see an image similar to
+ the one in figure~\ref{fig:bmrsnog:xdisp:vec:t10}.
+
+ \begin{figure}[htbp]
+ \begin{center}
+ \includegraphics{figs/xdisp_vec_t10}
+ \caption{ParaView rendering of displacement in x-direction and
+ displacement vectors at time step 10 (10 yrs after imposed
+ dislocation) for the reverse slip without gravity
+ benchmark.}
+ \label{fig:bmrsnog:xdisp:vec:t10}
+ \end{center}
+ \end{figure}
+
+\end{enumerate}
+
+\subsection{Run the simulation on two processors}
+
+In this step we will run the simulation on two processors. Even if
+your machine only has one processor, a "multprocessor" job will run as
+multiple processes on the single processor. In such cases, the job
+will run slightly slower than the single processor run, but the two
+processes will behave independently as if they are on different
+processors.
+
+\begin{enumerate}
+\item Run \command{tutor.py} for step "run2" with mode "retrieve" to
+ make sure all parameter files are available.
+
+ \begin{screen}
+ \shellprompt\userinput{./tutor.py -m retrieve -s run2}
+ \end{screen}
+
+\item The parameter files are the same as those in the single
+ processor run. The \command{runbm} script will automatically take
+ care of duplicating these files so that there is one for each
+ processor.
+\item Run the simulation by executing \command{runbm.py -n 2}, where
+ the 2 refers to the number of processors.
+
+ \begin{screen}
+ \shellprompt\userinput{./runbm.py -n 2}
+ \end{screen}
+\end{enumerate}
+
+\subsection{Visualize the two processor run}
+
+PyLith does not currently support parallel output, so each processor
+writes its UCD output to a different file. This means that you need to
+form complete UCD files for each processor and then load each one into
+\application{ParaView}.
+
+\begin{enumerate}
+\item If necessary, run \command{tutor.py} for step "viz2" with mode
+ "retrieve" to fetch the simulation output from the archive.
+
+ \begin{screen}
+ \shellprompt\userinput{./tutor.py -m retrieve -s viz2}
+ \end{screen}
+
+\item As in the case of the single processor run, the first step is to
+ combine the mesh topology information with the output at a given
+ time step into a complete UCD file. Because PyLith writes the output
+ from each processor into a different file, we must run \command{cat}
+ twice to create UCD files for each processor.
+
+ \begin{screen}
+ \shellprompt\userinput{cat bmrsnog\_2.0.mesh.inp bmrsnog\_2.0.mesh.time.00010.inp \\
+ > bmrsnog\_2.0.mesh.t00010.inp} \\
+ \shellprompt\userinput{cat bmrsnog\_2.1.mesh.inp bmrsnog\_2.1.mesh.time.00010.inp \\
+ > bmrsnog\_2.1.mesh.t00010.inp}
+ \end{screen}
+
+\item Start \application{ParaView} by executing \command{paraview}.
+
+ \begin{screen}
+ \shellprompt\userinput{paraview}
+ \end{screen}
+
+\item Load the UCD files that you just created by selecting
+ \guimenu{File}\guiselect\guimenuitem{Open Data}. Select the file in
+ the dialog box and the click the \guibutton{Open} button. Click the
+ \guibutton{Accept} button. You can now visualize the datasets just
+ like you did for the single processor case.
+\item You can merge the datasets from the different processors by
+ selecting \guimenu{Filter}\guiselect\guimenuitem{Append}. Doing so
+ will allow you to operate on the data from all of the processors
+ simultaneously instead of having to repeat any processing for every
+ processor.
+\end{enumerate}
Added: short/3D/PyLith/branches/pylith-0.8/doc/userguide/tutorials/splittest/splittest.tex
===================================================================
--- short/3D/PyLith/branches/pylith-0.8/doc/userguide/tutorials/splittest/splittest.tex 2006-08-22 13:08:01 UTC (rev 4397)
+++ short/3D/PyLith/branches/pylith-0.8/doc/userguide/tutorials/splittest/splittest.tex 2006-08-22 15:30:52 UTC (rev 4398)
@@ -0,0 +1,394 @@
+\section{Tutorial For Simple Strike-Slip Fault}
+
+\subsection{Overview}
+
+In this tutorial we will walk through the steps necessary to
+construct, run, and view the results of a benchmark problem involving
+a simple, vertical, through-going strike-slip fault. This problem
+examines the elastic deformation from a single, finite, right-lateral
+earthquake in 3-D without body forces.
+
+\subsection{Problem Description}
+
+The model domain is a cube with edges 1 km long (0 km $\leq$ x $\leq$
+1 km; 0 km $\leq$ y $\leq$ 1 km; 0 km $\leq$ z $\leq$ 1 km) and is
+composed of two materials. The fault separates two materials that have
+the same properties. Both materials are Poisson solids with Lame's
+constants ($\mu$ and $\lambda$) equal to 30 GPa.
+
+The strike-slip fault dips at an angle of 90 degrees. The slip
+distribution is 1.0 m of uniform right-lateral motion.
+
+The plane y=0 is a plane of symmetry, so the y-DOF displacements on
+this face are zero. The other lateral faces and bottom of the mesh are
+traction-free.
+
+\begin{figure}
+ \begin{center}
+ %\includegraphics{figs/geometry}
+ \caption{Geometry of model domain for simple model with strike-slip fault.}
+ \end{center}
+\end{figure}
+
+\subsubsection{Workflow}
+
+The complete workflow used to create the input files for this tutorial
+is shown in figure~\ref{fig:splittest:workflow}.
+
+\begin{figure}[htbp]
+ \begin{center}
+ \includegraphics{figs/workflow}
+ \caption{Workflow for setting up input files for example with
+ simple strike-slip faylt.}
+ \label{fig:splittest:workflow}
+ \end{center}
+\end{figure}
+
+\subsection{Download and unpack}
+
+We will start by downloading the tutorial tarball and unpacking it.
+
+\begin{enumerate}
+\item Download the \link{tutorial
+ tarball}{http://www.geodynamics.org:8080/cig/Members/willic3/pylithusers/pylith0.8/pylith-0.8\_tutorials.tgz}
+ and unpack it in a location of your choosing.
+
+ \begin{screen}
+ \shellprompt\userinput{tar -zxvf pylith-0.8\_tutorials.tgz}
+ \end{screen}
+
+\item Go to the \directory{tutorials/splittest} directory.
+ The \directory{archive} directory contains all of the input and
+ output files associated with this tutorial. We will copy input files
+ from this directory into the \directory{workarea} directory. At each
+ step, you can check to make sure your input and output agree with
+ the files in the \directory{archive} directory. These files also
+ allow you to start at an intermediate step as described in the next
+ section.
+
+ \begin{screen}
+ \shellprompt\userinput{cd tutorials/splittest}
+ \end{screen}
+
+\end{enumerate}
+
+\subsection{Tutor}
+
+Copy the \filename{tutor.py} script from the \directory{archive}
+directory into the \directory{workarea} directory.
+
+\begin{tip}
+ If you have run this tutorial previously, you may want to run
+ \command{tutor.py} in mode "clean" with step "all" to clear out all
+ old tutorial files.
+\end{tip}
+
+\begin{screen}
+\shellprompt\userinput{cd workarea}
+\shellprompt\userinput{cp ../archive/tutor.py .}
+\shellprompt\userinput{./tutor.py -m clean -s all}
+\end{screen}
+
+\subsection{Generate the mesh}
+
+In this step we will generate the finite-element mesh for the
+benchmark problem using \application{NETGEN}.
+
+\begin{enumerate}
+\item In the \directory{splittest/workarea} directory, run
+ \command{tutor.py} for step "mesh" with mode "retrieve" to fetch the
+ geometry file for \application{NETGEN}. You may also want to run
+ \command{tutor.py} for this step with mode "clean" to clean out old
+ files.
+
+ \begin{screen}
+ \shellprompt\userinput{./tutor.py -m retrieve -s mesh}
+ \shellprompt\userinput{./tutor.py -m clean -s mesh}
+ \end{screen}
+
+\item Examine the \filename{splittest.geo} file to see how the geometry
+ for the problem is defined. Notice that the fault plan has
+ been flagged with a boundary condition code. This will be
+ used to associate boundary conditions with the fault surface and the
+ associated nodes. We do not have to flag the lateral faces and top
+ and bottom of the mesh because they are traction-free, which is a
+ natural boundary condition in the finite-element formulation.
+\item Start up \application{NETGEN} by running \command{ng}.
+
+ \begin{screen}
+ \shellprompt\userinput{ng}
+ \end{screen}
+
+\item Select \guimenu{File}\guiselect\guimenuitem{Load Geometry}
+ and select \filename{splittest.geo}.
+\item Click on \guibutton{Generate Mesh}.
+\item Export the mesh to a file named \filename{splittest.netgen},
+ making sure the export filetype is "Neutral format".
+\item You can now exit \application{NETGEN}.
+\end{enumerate}
+
+\subsection{Setup simulation input files}
+
+In this step we will setup the PyLith input files for the mesh and
+boundary conditions.
+
+\begin{enumerate}
+\item Run \command{tutor.py} for step "setup" with mode "retrieve" to
+ fetch files from the archive.
+
+ \begin{screen}
+ \shellprompt\userinput{./tutor.py -m retrieve -s setup}
+ \end{screen}
+
+\item We will use a simple Fortran utility to generate PyLith
+ input files from the \application{NETGEN} output.
+
+ \begin{description}
+ \item[\command{readnetgen}] A Fortran program to read
+ \application{NETGEN} neutral format and create several of the
+ input files needed by PyLith.
+ \end{description}
+
+\item Run the \command{readnetgen} utility program to process the
+ \application{NETGEN} output file into PyLith compatible input files.
+ It will ask for a root filename, enter \filename{splittest}. This
+ utilitiy will generate the following files:
+ \filename{splittest.w01.wink}, \filename{splittest.coord},
+ \filename{splittest.connect}, \filename{splittest.bc},
+ \filename{splittest.1.fcoord}, \filename{splittest.1.fbc}.
+
+ \begin{screen}
+ \shellprompt\userinput{../../utils/readnetgen}
+ \prompt{~Enter root name for all files. Both input and}\\
+ \prompt{~output files will all have this prefix:}\\
+ \userinput{splittest}
+ \end{screen}
+
+\item The boundary conditions on the fault for this example are
+ very simple. As a result, the \filename{splittest.split} file was
+ generated by hand. You should examine this file to see how a uniform
+ right-lateral slip of 1.0 m is applied to the fault surface.
+
+ \begin{warning}
+ If you make any changes to \filename{splittest.geo} or change the
+ geometry within \application{NETGEN}, the split-node file
+ \filename{splittest.split} will no longer be correct and you will
+ have to generate one yourself. Note that it is also possible that
+ a different version of \application{NETGEN} may provide a slightly
+ different mesh, which would also be incompatible with the provided
+ boundary conditions.
+ \end{warning}
+
+\item The external boundary conditions for this benchmark simply
+ involve ... ADD STUFF HERE.
+
+ \begin{warning}
+ If you make any changes to \filename{splittest.geo} or change the
+ geometry within \application{NETGEN}, the boundary condition file
+ \filename{splittest.bc} will no longer be correct and you will
+ have to generate one yourself. Note that it is also possible that
+ a different version of \application{NETGEN} may provide a slightly
+ different mesh, which would also be incompatible with the provided
+ boundary conditions.
+ \end{warning}
+\end{enumerate}
+
+\subsection{Run the simulation on one processor}
+
+In this step we will run the simulation on a single processor.
+
+\begin{enumerate}
+\item Run \command{tutor.py} for step "run1" with mode "retrieve" to
+ fetch some parameter files from the archive.
+
+ \begin{screen}
+ \shellprompt\userinput{./tutor.py -m retrieve -s run1}
+ \end{screen}
+
+\item In \filename{splittest.fuldat}, we have specified that we want
+ full output at time steps 10, 50, and 100. We define two materials
+ with elastic behavior in
+ \filename{splittest.prop}. In \filename{splittest.statevar} we choose to
+ include total stress, total strain, incremental stress, and
+ incremental strain in the output. As defined in
+ \filename{splittest.time}, the simulation will have 100 time steps of
+ 0.1 year each.
+\item Run the simulation by executing \userinput{runbm.py -n 1}, where
+ the 1 refers to the number of processors.
+
+ \begin{tip}
+ All of the input is echoed in the file \filename{splittest.ascii}.
+ You can check to make sure your input is digested correctly by
+ examining this file. For large problems, this file can be quite
+ large. You can suppress creation of this file using the command
+ line argument \option{--scanner.asciiOutput=none} flag. On the
+ other hand, for debugging purposes in small problems, you may wish
+ to output everything, including the computed results, in this file
+ using \option{--scanner.asciiOutput=full}.
+ \end{tip}
+
+ \begin{screen}
+ \shellprompt\userinput{./runbm.py -n 1}
+ \end{screen}
+\end{enumerate}
+
+\subsection{Visualize the single processor run}
+
+Now it is time to visualize the results of the simulation. By default,
+PyLith writes simulation output using \link{\application{AVS} UCD
+ files}{http://help.avs.com/Express/doc/help/reference/dvmac/UCD\_Form.htm}.
+These can be read by several other visualization tools besides
+\application{AVS}, e.g., \application{ParaView} and \application{Iris
+ Explorer}. We will use the open-source application
+\application{ParaView} to visualize the results.
+
+\begin{enumerate}
+\item If necessary, run \command{tutor.py} for step "viz1" with mode
+ "retrieve" to fetch the simulation output from the archive.
+
+ \begin{screen}
+ \shellprompt\userinput{./tutor.py -m retrieve -s viz1}
+ \end{screen}
+
+\item PyLith does not write complete UCD files. So the first step is
+ to combine the mesh topology information with the output at a given
+ time step into a complete UCD file. For example, use \command{cat}
+ to merge the nodal coordinates file
+ (\filename{splittest\_1.0.mesh.inp}) and the nodal displacements at
+ time step 10 file (\filename{splittest\_1.0.mesh.time.00010.inp}) into
+ \filename{splittest\_1.0.mesh.t00010.inp}.
+
+ \begin{screen}
+ \shellprompt\userinput{cat splittest\_1.0.mesh.inp splittest\_1.0.mesh.time.00010.inp \ \\
+> splittest\_1.0.mesh.t00010.inp}
+\end{screen}
+
+\item Start \application{ParaView} by executing \command{paraview}.
+
+ \begin{screen}
+ \shellprompt\userinput{paraview}
+ \end{screen}
+
+\item Load the UCD file that you just created by selecting
+ \guimenu{File}\guiselect\guimenuitem{Open Data}. Select the file in
+ the dialog box and the click the \guibutton{Open} button. Click the
+ \guibutton{Accept} button. You should see a color rendering of the x
+ displacements. You can use the mouse to rotate, translate, and zoom.
+ Your image should look similar to the one in
+ figure~\ref{fig::splittest:xdisp:t10}.
+
+ \begin{figure}[htbp]
+ \begin{center}
+ %\includegraphics{figs/xdisp_t10}
+ \caption{ParaView rendering of displacement in x-direction at
+ time step 10 (10 yrs after imposed dislocation) for the
+ simple strike-slip example.}
+ \label{fig:splittest:xdisp:t10}
+ \end{center}
+ \end{figure}
+
+\item In the \guibutton{Display} tab, you can change several options,
+ such as including a color bar, coloring a different component,
+ interpolating colors, and changing the color map.
+\item Let's show the displacements as vectors. Click on the calculator
+ icon, and add the three displacement components together. Enter
+ "XDispl*iHat+YDispl*jHat+ZDispl*kHat" in the \\guimenuitem{Calculator}
+ box. Note the variable names are available by clicking on the
+ \guibutton{scalars} button and the \guibutton{iHat},
+ \guibutton{jHat}, \guibutton{kHat} buttons are on the right side of
+ the top row. Click on the \guibutton{Accept} button. To show the
+ dataset as vectors, click on the \guibutton{glyph} button (looks
+ like several dots) in the toolbar. After clicking the
+ \guibutton{Accept} button, you should have a vector plot. You can
+ turn on/off other datasets by clicking on the eye icon to the left
+ of the dataset name. If you color the surfaces using the
+ x-displacements field while also making the displacement vectors
+ visible (colored using property), you should see an image similar to
+ the one in figure~\ref{fig:splittest:xdisp:vec:t10}.
+
+ \begin{figure}[htbp]
+ \begin{center}
+ %\includegraphics{figs/splittest_xdisp_vec_t10}
+ \caption{ParaView rendering of displacement in x-direction and
+ displacement vectors at time step 10 (10 yrs after imposed
+ dislocation) for the simple strike-slip example.}
+ \label{fig:splittest:xdisp:vec:t10}
+ \end{center}
+ \end{figure}
+
+\end{enumerate}
+
+\subsection{Run the simulation on two processors}
+
+In this step we will run the simulation on two processors. Even if
+your machine only has one processor, a "multprocessor" job will run as
+multiple processes on the single processor. In such cases, the job
+will run slightly slower than the single processor run, but the two
+processes will behave independently as if they are on different
+processors.
+
+\begin{enumerate}
+\item Run \command{tutor.py} for step "run2" with mode "retrieve" to
+ make sure all parameter files are available.
+
+ \begin{screen}
+ \shellprompt\userinput{./tutor.py -m retrieve -s run2}
+ \end{screen}
+
+\item The parameter files are the same as those in the single
+ processor run. The \command{runbm} script will automatically take
+ care of duplicating these files so that there is one for each
+ processor.
+\item Run the simulation by executing \command{runbm.py -n 2}, where
+ the 2 refers to the number of processors.
+
+ \begin{screen}
+ \shellprompt\userinput{./runbm.py -n 2}
+ \end{screen}
+\end{enumerate}
+
+\subsection{Visualize the two processor run}
+
+PyLith does not currently support parallel output, so each processor
+writes its UCD output to a different file. This means that you need to
+form complete UCD files for each processor and then load each one into
+\application{ParaView}.
+
+\begin{enumerate}
+\item If necessary, run \command{tutor.py} for step "viz2" with mode
+ "retrieve" to fetch the simulation output from the archive.
+
+ \begin{screen}
+ \shellprompt\userinput{./tutor.py -m retrieve -s viz2}
+ \end{screen}
+
+\item As in the case of the single processor run, the first step is to
+ combine the mesh topology information with the output at a given
+ time step into a complete UCD file. Because PyLith writes the output
+ from each processor into a different file, we must run \command{cat}
+ twice to create UCD files for each processor.
+
+ \begin{screen}
+ \shellprompt\userinput{cat splittest\_2.0.mesh.inp splittest\_2.0.mesh.time.00010.inp \\
+ > splittest\_2.0.mesh.t00010.inp} \\
+ \shellprompt\userinput{cat splittest\_2.1.mesh.inp splittest\_2.1.mesh.time.00010.inp \\
+ > splittest\_2.1.mesh.t00010.inp}
+ \end{screen}
+
+\item Start \application{ParaView} by executing \command{paraview}.
+
+ \begin{screen}
+ \shellprompt\userinput{paraview}
+ \end{screen}
+
+\item Load the UCD files that you just created by selecting
+ \guimenu{File}\guiselect\guimenuitem{Open Data}. Select the file in
+ the dialog box and the click the \guibutton{Open} button. Click the
+ \guibutton{Accept} button. You can now visualize the datasets just
+ like you did for the single processor case.
+\item You can merge the datasets from the different processors by
+ selecting \guimenu{Filter}\guiselect\guimenuitem{Append}. Doing so
+ will allow you to operate on the data from all of the processors
+ simultaneously instead of having to repeat any processing for every
+ processor.
+\end{enumerate}
Added: short/3D/PyLith/branches/pylith-0.8/doc/userguide/tutorials/tutorials.tex
===================================================================
--- short/3D/PyLith/branches/pylith-0.8/doc/userguide/tutorials/tutorials.tex 2006-08-22 13:08:01 UTC (rev 4397)
+++ short/3D/PyLith/branches/pylith-0.8/doc/userguide/tutorials/tutorials.tex 2006-08-22 15:30:52 UTC (rev 4398)
@@ -0,0 +1,47 @@
+\chapter{Tutorials}
+
+\section{Overview}
+
+Each tutorial is a self-contained lesson in how to use PyLith. The
+tutorials increase in degree of complexity from one to the next.
+
+\subsection{Prerequisites}
+
+Before you begin any of the tutorials, you will need to install PyLith
+following the instructions in section~\ref{sec:install}. In order to
+work through a full tutorial, in addition to \application{PyLith} you
+will need \link{\application{NETGEN}}{http://www.hpfem.jku.at/netgen/}
+to generate the mesh and \link{ParaView}{http://www.paraview.org} to
+view simulation results. You may use other packages, but some adaption
+from what is described here will be necessary. Alternatively, you can
+just complete a subset of the tutorial using files provided (as
+described below), skipping the steps for which you do not have the
+proper software packages installed.
+
+The files needed to work through the tutorials have been collected
+into a single tarball. Each tutorial contains instructions for
+downloading and unpacking the tutorial tarball.
+
+\subsection{Tutor}
+
+Each tutorial includes a simple Python script, \filename{tutor.py}, to
+help with miscellaneous tasks, such as copying provided files into a
+working directory. This script can (1) check to make sure the files
+necessary for a given step in the tutorial exist, (2) retrieve any
+missing files from the tutorial archive directory that are needed for
+a given step, or (3) prepare the work area for a given step by
+removing old files that would otherwise be overwritten. You can run
+\command{tutor.py} with the \option{-h} option for more
+information. We will use this script at the beginning of each step of
+the tutorials to retrieve files as necessary from the tutorial archive
+directory.
+
+\begin{tip}
+ When retrieving files from the archive directory, \command{tutor.py}
+ will not overwrite files that already exist in the workarea
+ directory. This means that if you mangle files in the working area,
+ you should remove them and let the tutor retrieve clean copies.
+\end{tip}
+
+\input{splittest/splittest.tex}
+\input{reversenog/reversenog.tex}
Added: short/3D/PyLith/branches/pylith-0.8/doc/userguide/userguide.tex
===================================================================
--- short/3D/PyLith/branches/pylith-0.8/doc/userguide/userguide.tex 2006-08-22 13:08:01 UTC (rev 4397)
+++ short/3D/PyLith/branches/pylith-0.8/doc/userguide/userguide.tex 2006-08-22 15:30:52 UTC (rev 4398)
@@ -0,0 +1,39 @@
+% -*- TeX -*-
+\documentclass{report}
+\usepackage{amsmath}
+\usepackage{graphicx}
+
+
+\input{docdefs.tex}
+
+\begin{document}
+
+% For reference only. Will be replaced with graphic cover.
+\title{PyLith User Manual}
+\author{Charles Williams\\
+ Matthew Knepley\\
+ Brad Aagaard\\
+ Cassie Ferguson\\
+ Sue Kientz}
+\date{\today}
+
+\maketitle
+
+\part{Preface}
+
+\input{preface.tex}
+
+\part{PyLith}
+
+\input{intro/intro.tex}
+\input{install/install.tex}
+\input{tutorials/tutorials.tex}
+
+\part{Appendices}
+\input{fileformats/fileformats.tex}
+\input{materials/materials.tex}
+\input{license.tex}
+
+\end{document}
+
+% End of file
\ No newline at end of file
More information about the cig-commits
mailing list