[cig-commits] r7276 - in short/3D/PyLith/trunk/doc/userguide: .
boundaryconditions fileformats install intro materials
runpylith tutorials
brad at geodynamics.org
brad at geodynamics.org
Sat Jun 16 20:32:29 PDT 2007
Author: brad
Date: 2007-06-16 20:32:28 -0700 (Sat, 16 Jun 2007)
New Revision: 7276
Modified:
short/3D/PyLith/trunk/doc/userguide/TODO
short/3D/PyLith/trunk/doc/userguide/boundaryconditions/boundaryconditions.lyx
short/3D/PyLith/trunk/doc/userguide/fileformats/fileformats.lyx
short/3D/PyLith/trunk/doc/userguide/install/install.lyx
short/3D/PyLith/trunk/doc/userguide/intro/intro.lyx
short/3D/PyLith/trunk/doc/userguide/materials/materials.lyx
short/3D/PyLith/trunk/doc/userguide/runpylith/runpylith.lyx
short/3D/PyLith/trunk/doc/userguide/tutorials/tutorials.lyx
Log:
Made pass through user manual. Deleted out of date 0.8 stuff.
Modified: short/3D/PyLith/trunk/doc/userguide/TODO
===================================================================
--- short/3D/PyLith/trunk/doc/userguide/TODO 2007-06-16 22:41:51 UTC (rev 7275)
+++ short/3D/PyLith/trunk/doc/userguide/TODO 2007-06-17 03:32:28 UTC (rev 7276)
@@ -1,16 +1,38 @@
Outline of user manual:
-1. Cover (not sure what image to use) [Sue?]
+1. Cover
+ Replace with new benchmark image if we have one in time.
+
5. Preface (should be able to mostly copy from PyLith 0.8) [Charles]
DONE
-6. Intro (I can start with stuff from 0.8 and do some editing) [Charles]
-MOSTLY DONE -- Need to rewrite PyLith Design section.
+6. Intro [MOSTLY DONE]
-7. Governing equations [Charles]
-MOSTLY DONE -- Needs some checking.
+ Needs more work on PyLith design section.
+ Figures
+
+ Workflow [Brad]
+
+ PyLith Diagram [Brad]
+
+ Pyre
+
+ PyLith
+
+ Faults, Topology, BC, FEAssemble, Problems, MeshIO, Solver, Materials
+
+ PETSc
+
+ Sieve
+
+ MPI
+
+7. Governing equations [MOSTLY DONE]
+
+ Needs some checking. [Charles]
+
8. Installing binary PyLith [Charles with some input from Leif]
9. Running PyLith (an overview) [Charles with some input from Brad]
@@ -37,7 +59,7 @@
f. Explicit problems
-10. Installation [Charles with some input from Leif and Brad]
+10. Installation from source [Leif will write after CFEM]
C++, Python
@@ -84,15 +106,24 @@
a. Specifying .cfg and spatial database info.
- b. Existing (and future?) material models. Include discussion of specifying material properties in terms of vp, vs, and density.
+ b. Existing material models.
- * ElasticStrain1D
- * ElasticStress1D
- * ElasticPlaneStrain
- * ElasticPlaneStress
- * ElasticIsotropic3D
- * MaxwellIsotropic3D
+ * ElasticStrain1D [Brad]
+ * ElasticStress1D [Brad]
+
+ * ElasticPlaneStrain [Brad]
+
+ * ElasticPlaneStress [Brad]
+
+ * ElasticIsotropic3D [DONE]
+
+ * MaxwellIsotropic3D [Charles]
+
+ Need to rewrite formulation in terms of mu and lambda.
+
+ c. List material models in 0.8 that will be added soon.
+
13. Boundary and interface conditions (includes faults) [Charles]
a. Specifying .cfg and spatial database info.
Modified: short/3D/PyLith/trunk/doc/userguide/boundaryconditions/boundaryconditions.lyx
===================================================================
--- short/3D/PyLith/trunk/doc/userguide/boundaryconditions/boundaryconditions.lyx 2007-06-16 22:41:51 UTC (rev 7275)
+++ short/3D/PyLith/trunk/doc/userguide/boundaryconditions/boundaryconditions.lyx 2007-06-17 03:32:28 UTC (rev 7276)
@@ -30,7 +30,7 @@
\begin_body
\begin_layout Chapter
-Boundary and interface conditions
+Boundary and Interface Conditions
\end_layout
\begin_layout Standard
Modified: short/3D/PyLith/trunk/doc/userguide/fileformats/fileformats.lyx
===================================================================
--- short/3D/PyLith/trunk/doc/userguide/fileformats/fileformats.lyx 2007-06-16 22:41:51 UTC (rev 7275)
+++ short/3D/PyLith/trunk/doc/userguide/fileformats/fileformats.lyx 2007-06-17 03:32:28 UTC (rev 7276)
@@ -45,304 +45,24 @@
\end_layout
\begin_layout Section
-Input Files
-\end_layout
+\begin_inset LatexCommand \label{sec:MeshIOAscii}
-\begin_layout Standard
-PyLith gathers its input from several different types of files.
- All of these are 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).
-\end_layout
-
-\begin_layout Subsection
-
-\family typewriter
-\color black
-xx.coord
-\end_layout
-
-\begin_layout Standard
-The
-\family typewriter
-\color black
-xx.coord
-\family default
-\color none
- file contains the coordinates of all of the vertices in the finite-element
- mesh.
-\end_layout
-
-\begin_layout LyX-Code
-# File containing vertices of the finite-element mesh.
-\end_layout
-
-\begin_layout LyX-Code
-#
-\end_layout
-
-\begin_layout LyX-Code
-# Comment lines begin with '#'
-\end_layout
-
-\begin_layout LyX-Code
-#
-\end_layout
-
-\begin_layout LyX-Code
-# First, specify units of coordinates.
-\end_layout
-
-\begin_layout LyX-Code
-#
-\end_layout
-
-\begin_layout LyX-Code
-coord_unit = km
-\end_layout
-
-\begin_layout LyX-Code
-#
-\end_layout
-
-\begin_layout LyX-Code
-#
-\end_layout
-
-\begin_layout LyX-Code
-# Now specify the coordinates of each vertex.
-\end_layout
-
-\begin_layout LyX-Code
-#
-\end_layout
-
-\begin_layout LyX-Code
-# Columns:
-\end_layout
-
-\begin_layout LyX-Code
-# (1) Vertex number
-\end_layout
-
-\begin_layout LyX-Code
-# (2) X coordinate
-\end_layout
-
-\begin_layout LyX-Code
-# (3) Y coordinate
-\end_layout
-
-\begin_layout LyX-Code
-# (4) Z coordinate
-\end_layout
-
-\begin_layout LyX-Code
-#
-\end_layout
-
-\begin_layout LyX-Code
-# Note: No comments are allowed within the list of vertex coordinates
-\end_layout
-
-\begin_layout LyX-Code
-#
-\end_layout
-
-\begin_layout LyX-Code
-1 0.000000e+00 0.000000e+00 0.000000e+00
-\end_layout
-
-\begin_layout LyX-Code
-2 1.000000e+00 0.000000e+00 0.000000e+00
-\end_layout
-
-\begin_layout LyX-Code
-3 0.000000e+00 2.000000e+00 0.000000e+00
-\end_layout
-
-\begin_layout LyX-Code
-4 1.000000e+00 2.000000e+00 3.000000e+00
-\end_layout
-
-\begin_layout Standard
-\begin_inset Float figure
-placement H
-wide false
-sideways false
-status open
-
-\begin_layout Caption
-Format of
-\family typewriter
-\color black
-xx.coord
-\family default
-\color none
- files.
-\end_layout
-
\end_inset
-
+PyLith Mesh ASCII Files
\end_layout
-\begin_layout Subsection
-
-\family typewriter
-\color black
-xx.connect
-\end_layout
-
\begin_layout Standard
-The
-\family typewriter
-\color black
-xx.connect
-\family default
-\color none
- 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.
+PyLith Mesh ASCII files allow quick specification of the mesh information
+ for very small, simple meshes that are most easily written by hand.
+ We do not recommend using this format for anything other than these very
+ small, simple meshes.
\end_layout
\begin_layout LyX-Code
-# File containing finite-element mesh topology and material type
+SAMPLE MESH FILE GOES HERE
\end_layout
-\begin_layout LyX-Code
-# information.
-\end_layout
-
-\begin_layout LyX-Code
-#
-\end_layout
-
-\begin_layout LyX-Code
-# Comment lines begin with '#'
-\end_layout
-
-\begin_layout LyX-Code
-#
-\end_layout
-
-\begin_layout LyX-Code
-# Columns:
-\end_layout
-
-\begin_layout LyX-Code
-# (1) Element number
-\end_layout
-
-\begin_layout LyX-Code
-# (2) Element type
-\end_layout
-
-\begin_layout LyX-Code
-# 1 = Linear hexahedron (8 vertices)
-\end_layout
-
-\begin_layout LyX-Code
-# 2 = Linear hexahedron with 1 set of collapsed vertices
-\end_layout
-
-\begin_layout LyX-Code
-# (7 vertices) [NOT IMPLEMENTED]
-\end_layout
-
-\begin_layout LyX-Code
-# 3 = Linear hexahedron with 2 sets of collapsed vertices
-\end_layout
-
-\begin_layout LyX-Code
-# (6 vertices) [NOT IMPLEMENTED]
-\end_layout
-
-\begin_layout LyX-Code
-# 4 = Linear hexahedron with 4 vertices collapsed to a point
-\end_layout
-
-\begin_layout LyX-Code
-# (5 vertices) [NOT IMPLEMENTED]
-\end_layout
-
-\begin_layout LyX-Code
-# 5 = Linear tetrahedron (4 vertices)
-\end_layout
-
-\begin_layout LyX-Code
-# 6 = Quadratix hexahedron (20 vertices) [NOT IMPLEMENTED]
-\end_layout
-
-\begin_layout LyX-Code
-# 7 = Quadratic hexahedron with 3 vertices along one edge
-\end_layout
-
-\begin_layout LyX-Code
-# collapsed to a point (18 vertices) [NOT IMPLEMENTED]
-\end_layout
-
-\begin_layout LyX-Code
-# 8 = Quadratic hexahedron with 3 sets of collapsed vertices
-\end_layout
-
-\begin_layout LyX-Code
-# (15 vertices) [NOT IMPLEMENTED]
-\end_layout
-
-\begin_layout LyX-Code
-# 9 = Quadratic hexahedron with 9 vertices collapsed to a point
-\end_layout
-
-\begin_layout LyX-Code
-# (13 vertices) [NOT IMPLEMENTED]
-\end_layout
-
-\begin_layout LyX-Code
-# 10 = Quadratic tetrahedron (10 vertices) [NOT IMPLEMENTED]
-\end_layout
-
-\begin_layout LyX-Code
-# (3) Material type, numbered consecutively beginning with '1'
-\end_layout
-
-\begin_layout LyX-Code
-# (4) Infinite element flag, required but not currently implemented
-\end_layout
-
-\begin_layout LyX-Code
-# 0 = only valid value
-\end_layout
-
-\begin_layout LyX-Code
-# (5)+ Vertices in the element, identified by vertex number
-\end_layout
-
-\begin_layout LyX-Code
-#
-\end_layout
-
-\begin_layout LyX-Code
-# Note: No comments are allowed within the mesh information.
-\end_layout
-
-\begin_layout LyX-Code
-#
-\end_layout
-
-\begin_layout LyX-Code
-1 5 1 0 2911 2865 2886 2864
-\end_layout
-
-\begin_layout LyX-Code
-2 5 2 0 843 3999 4029 3926
-\end_layout
-
-\begin_layout LyX-Code
-3 5 1 0 684 8975 2346 6219
-\end_layout
-
\begin_layout Standard
\begin_inset Float figure
placement H
@@ -353,11 +73,9 @@
\begin_layout Caption
Format of
\family typewriter
-\color black
-xx.connect
+PyLith
\family default
-\color none
- files.
+ mesh ASCII files.
\end_layout
\end_inset
@@ -365,391 +83,26 @@
\end_layout
-\begin_layout Subsection
+\begin_layout Section
+\begin_inset LatexCommand \label{sec:Spatialdata:SimpleIOAscii}
-\family typewriter
-\color black
-xx.bc
-\end_layout
-
-\begin_layout Standard
-The
-\family typewriter
-\color black
-xx.bc
-\family default
-\color none
- file specifies the displacements, velocity, and/or forces applied to vertices
- on the boundaries.
-\end_layout
-
-\begin_layout LyX-Code
-# File containing boundary conditions at vertices.
-\end_layout
-
-\begin_layout LyX-Code
-#
-\end_layout
-
-\begin_layout LyX-Code
-# Comment lines begin with '#'
-\end_layout
-
-\begin_layout LyX-Code
-#
-\end_layout
-
-\begin_layout LyX-Code
-# First, specify units of coordinates for each type of boundary
-\end_layout
-
-\begin_layout LyX-Code
-# conditon.
- All three are required even if they are not all used.
-\end_layout
-
-\begin_layout LyX-Code
-#
-\end_layout
-
-\begin_layout LyX-Code
-displacement_units = m
-\end_layout
-
-\begin_layout LyX-Code
-velocity_units = m/s
-\end_layout
-
-\begin_layout LyX-Code
-force_units = newton
-\end_layout
-
-\begin_layout LyX-Code
-#
-\end_layout
-
-\begin_layout LyX-Code
-#
-\end_layout
-
-\begin_layout LyX-Code
-# Boundary conditions applied to vertices.
- You must specify a flag and
-\end_layout
-
-\begin_layout LyX-Code
-# value for each degree of freedom, even if some are free.
-\end_layout
-
-\begin_layout LyX-Code
-#
-\end_layout
-
-\begin_layout LyX-Code
-# Columns:
-\end_layout
-
-\begin_layout LyX-Code
-# (1) Vertex number
-\end_layout
-
-\begin_layout LyX-Code
-# (2) Boundary condition flag for x DOF
-\end_layout
-
-\begin_layout LyX-Code
-# (3) Boundary condition flag for y DOF
-\end_layout
-
-\begin_layout LyX-Code
-# (4) Boundary condition flag for z DOF
-\end_layout
-
-\begin_layout LyX-Code
-# 0 = Free
-\end_layout
-
-\begin_layout LyX-Code
-# 1 = Fixed displacement
-\end_layout
-
-\begin_layout LyX-Code
-# 2 = Constant velocity
-\end_layout
-
-\begin_layout LyX-Code
-# 3 = Constant force
-\end_layout
-
-\begin_layout LyX-Code
-# A 2 or more digit code may be used for the boundary condition
-\end_layout
-
-\begin_layout LyX-Code
-# flag.
- If used, the final digit refers to the condition
-\end_layout
-
-\begin_layout LyX-Code
-# type as defined above, while the beginning digit(s) refer to
-\end_layout
-
-\begin_layout LyX-Code
-# the time history to be used.
-\end_layout
-
-\begin_layout LyX-Code
-# (5) Boundary condition value for x DOF
-\end_layout
-
-\begin_layout LyX-Code
-# (6) Boundary condition value for y DOF
-\end_layout
-
-\begin_layout LyX-Code
-# (7) Boundary condition value for z DOF
-\end_layout
-
-\begin_layout LyX-Code
-1 0 1 0 0.0000e+00 0.0000e+00 0.0000e+00
-\end_layout
-
-\begin_layout LyX-Code
-3 0 1 0 0.0000e+00 0.0000e+00 0.0000e+00
-\end_layout
-
-\begin_layout LyX-Code
-12 0 1 0 0.0000e+00 0.0000e+00 0.0000e+00
-\end_layout
-
-\begin_layout Standard
-\begin_inset Float figure
-placement H
-wide false
-sideways false
-status open
-
-\begin_layout Caption
-Format of
-\family typewriter
-\color black
-xx.bc
-\family default
-\color none
- files.
-\end_layout
-
\end_inset
-
+Spatialdata Files
\end_layout
-\begin_layout Subsection
-
-\family typewriter
-\color black
-xx.time
-\end_layout
-
\begin_layout Standard
-The
-\family typewriter
-\color black
-xx.time
-\family default
-\color none
- file specifies the time stepping parameters for the simulation.
+Spatialdata files provide specification of a field over some set of points.
+ There is not topology associated with the points.
+ Spatialdata files contain a header describing the set of points and then
+ the data with each line listing the coordinates of a point followed by
+ the values of the fields for that point.
\end_layout
-\begin_layout Quote
-
-\series bold
-\color red
-Warning:
-\series default
-\color none
-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.
- The example below is appropriate for a linear elastic problem.
-\end_layout
-
\begin_layout LyX-Code
-# File containing time stepping parameters.
+SAMPLE DATA FILE GOES HERE
\end_layout
-\begin_layout LyX-Code
-#
-\end_layout
-
-\begin_layout LyX-Code
-# Comment lines begin with '#'
-\end_layout
-
-\begin_layout LyX-Code
-#
-\end_layout
-
-\begin_layout LyX-Code
-# First, specify units used in values with dimensions of time.
-\end_layout
-
-\begin_layout LyX-Code
-#
-\end_layout
-
-\begin_layout LyX-Code
-time_units = year
-\end_layout
-
-\begin_layout LyX-Code
-#
-\end_layout
-
-\begin_layout LyX-Code
-#
-\end_layout
-
-\begin_layout LyX-Code
-# Time stepping parameters are given in groups.
- The elastic solution
-\end_layout
-
-\begin_layout LyX-Code
-# corresponds to group 0 and must always be defined.
- Although some of
-\end_layout
-
-\begin_layout LyX-Code
-# the parameters do not have any meaning for the elastic solution,
-\end_layout
-
-\begin_layout LyX-Code
-# they must be present anyway.
-\end_layout
-
-\begin_layout LyX-Code
-#
-\end_layout
-
-\begin_layout LyX-Code
-# Columns:
-\end_layout
-
-\begin_layout LyX-Code
-# (1) Time step group number (=0 for elastic solution).
-\end_layout
-
-\begin_layout LyX-Code
-# (2) The number of time steps in the group (=1 for elastic solution).
-\end_layout
-
-\begin_layout LyX-Code
-# (3) Time step size (given in units of time_units).
-\end_layout
-
-\begin_layout LyX-Code
-# (4) Amount of implicitness.
- Real dimensionless parameter that
-\end_layout
-
-\begin_layout LyX-Code
-# ranges from 0.0 (fully explicit) to 1.0 (fully implicit).
- The
-\end_layout
-
-\begin_layout LyX-Code
-# value is generally set to 0.5.
-\end_layout
-
-\begin_layout LyX-Code
-# (5) Maximum number of equilibrium iterations before stiffness
-\end_layout
-
-\begin_layout LyX-Code
-# matrix is reformed.
-\end_layout
-
-\begin_layout LyX-Code
-# (6) Number of time steps between initial reformation of stiffness
-\end_layout
-
-\begin_layout LyX-Code
-# matrix.
-\end_layout
-
-\begin_layout LyX-Code
-#
-\begin_inset Formula $<$
-\end_inset
-
-0 Indicates that reformation should occur only for the first
-\end_layout
-
-\begin_layout LyX-Code
-# step in each time step group.
-\end_layout
-
-\begin_layout LyX-Code
-# =0 Indicates that reformation should never occur.
-\end_layout
-
-\begin_layout LyX-Code
-# (7) Large deformation solution flag (only Linear strain is
-\end_layout
-
-\begin_layout LyX-Code
-# presently available).
-\end_layout
-
-\begin_layout LyX-Code
-# 0 = Linear strain
-\end_layout
-
-\begin_layout LyX-Code
-# 1 = Large strain but use only linear contribution to the
-\end_layout
-
-\begin_layout LyX-Code
-# stiffness matrix (sometimes results in better convergence)
-\end_layout
-
-\begin_layout LyX-Code
-# 2 = Large strain and use nonlinear contribution to the
-\end_layout
-
-\begin_layout LyX-Code
-# stiffness matrix
-\end_layout
-
-\begin_layout LyX-Code
-# (8) Convergence tolerance for displacements (dimensionless value)
-\end_layout
-
-\begin_layout LyX-Code
-# (9) Convergence tolerance for forces (dimensionless value)
-\end_layout
-
-\begin_layout LyX-Code
-# (10) Convergence tolerance for energy (dimensionless value)
-\end_layout
-
-\begin_layout LyX-Code
-# (11) Maximum number of equilibrium iterations
-\end_layout
-
-\begin_layout LyX-Code
-#
-\end_layout
-
-\begin_layout LyX-Code
- 0 1 0.0 5.0e-01 1001 4 0 1.0e+00 1.0e+0 1.0e+00 1
-\end_layout
-
-\begin_layout LyX-Code
- 1 100 0.1 5.0e-01 1001 -1 0 1.0e+00 1.0e+0 1.0e+00 1
-\end_layout
-
\begin_layout Standard
\begin_inset Float figure
placement H
@@ -758,13 +111,7 @@
status open
\begin_layout Caption
-Format of
-\family typewriter
-\color black
-xx.time
-\family default
-\color none
- files.
+Format of spatial data files.
\end_layout
\end_inset
@@ -772,1172 +119,9 @@
\end_layout
-\begin_layout Subsection
-
-\family typewriter
-xx.prop
-\end_layout
-
\begin_layout Standard
-The
-\family typewriter
-xx.prop
-\family default
- file specifies the properties for each material model in the problem.
-\end_layout
-\begin_layout Quote
-
-\series bold
-\color red
-Warning:
-\series default
-\color none
- The materials must be listed in order according to the material number
- assigned to the elements in
-\family typewriter
-xx.connect.
-
-\family default
-
\end_layout
-\begin_layout LyX-Code
-# File containing material properties.
-\end_layout
-
-\begin_layout LyX-Code
-#
-\end_layout
-
-\begin_layout LyX-Code
-# Comment lines begin with '#'
-\end_layout
-
-\begin_layout LyX-Code
-#
-\end_layout
-
-\begin_layout LyX-Code
-# The material type and material property values are specified using a
-\end_layout
-
-\begin_layout LyX-Code
-# "keyword = value" syntax.
- The keywords for the different material
-\end_layout
-
-\begin_layout LyX-Code
-# types are given below.
- Units for each of the values with dimensions
-\end_layout
-
-\begin_layout LyX-Code
-# must follow the value as illustrated in the examples below.
-\end_layout
-
-\begin_layout LyX-Code
-#
-\end_layout
-
-\begin_layout LyX-Code
-# Materials and keywords:
-\end_layout
-
-\begin_layout LyX-Code
-# Isotropic linear elastic
-\end_layout
-
-\begin_layout LyX-Code
-# materialType ='IsotropicLinearElastic'
-\end_layout
-
-\begin_layout LyX-Code
-# density
-\end_layout
-
-\begin_layout LyX-Code
-# youngsModulus
-\end_layout
-
-\begin_layout LyX-Code
-# poissonsRatio
-\end_layout
-
-\begin_layout LyX-Code
-# endMaterial ='True' (flag indicating end of material)
-\end_layout
-
-\begin_layout LyX-Code
-#
-\end_layout
-
-\begin_layout LyX-Code
-# Isotropic linear maxwell viscoelastic
-\end_layout
-
-\begin_layout LyX-Code
-# materialType ='IsotropicLinearMaxwellViscoelastic'
-\end_layout
-
-\begin_layout LyX-Code
-# density
-\end_layout
-
-\begin_layout LyX-Code
-# youngsModulus
-\end_layout
-
-\begin_layout LyX-Code
-# poissonsRatio
-\end_layout
-
-\begin_layout LyX-Code
-# viscosity
-\end_layout
-
-\begin_layout LyX-Code
-# endMaterial ='True' (flag indicating end of material)
-\end_layout
-
-\begin_layout LyX-Code
-#
-\end_layout
-
-\begin_layout LyX-Code
-# Isotropic linear maxwell viscoelastic (ESF formulation)
-\end_layout
-
-\begin_layout LyX-Code
-# materialType ='IsotropicLinearMaxwellViscoelasticESF'
-\end_layout
-
-\begin_layout LyX-Code
-# density
-\end_layout
-
-\begin_layout LyX-Code
-# youngsModulus
-\end_layout
-
-\begin_layout LyX-Code
-# poissonsRatio
-\end_layout
-
-\begin_layout LyX-Code
-# viscosity
-\end_layout
-
-\begin_layout LyX-Code
-# endMaterial ='True' (flag indicating end of material)
-\end_layout
-
-\begin_layout LyX-Code
-#
-\end_layout
-
-\begin_layout LyX-Code
-# Isotropic linear generalized maxwell viscoelastic
-\end_layout
-
-\begin_layout LyX-Code
-# (3 Maxwell models in parallel)
-\end_layout
-
-\begin_layout LyX-Code
-# materialType ='IsotropicLinearMaxwellViscoelastic'
-\end_layout
-
-\begin_layout LyX-Code
-# density
-\end_layout
-
-\begin_layout LyX-Code
-# youngsModulus
-\end_layout
-
-\begin_layout LyX-Code
-# poissonsRatio
-\end_layout
-
-\begin_layout LyX-Code
-# shearRatio1
-\end_layout
-
-\begin_layout LyX-Code
-# viscosity1
-\end_layout
-
-\begin_layout LyX-Code
-# shearRatio2
-\end_layout
-
-\begin_layout LyX-Code
-# viscosity2
-\end_layout
-
-\begin_layout LyX-Code
-# shearRatio3
-\end_layout
-
-\begin_layout LyX-Code
-# viscosity3
-\end_layout
-
-\begin_layout LyX-Code
-# endMaterial ='True' (flag indicating end of material)
-\end_layout
-
-\begin_layout LyX-Code
-#
-\end_layout
-
-\begin_layout LyX-Code
-# Isotropic power-law maxwell viscoelastic
-\end_layout
-
-\begin_layout LyX-Code
-# materialType ='IsotropicPowerLawMaxwellViscoelastic'
-\end_layout
-
-\begin_layout LyX-Code
-# density
-\end_layout
-
-\begin_layout LyX-Code
-# youngsModulus
-\end_layout
-
-\begin_layout LyX-Code
-# poissonsRatio
-\end_layout
-
-\begin_layout LyX-Code
-# powerLawExponent
-\end_layout
-
-\begin_layout LyX-Code
-# viscosityCoefficient
-\end_layout
-
-\begin_layout LyX-Code
-# endMaterial ='True' (flag indicating end of material)
-\end_layout
-
-\begin_layout LyX-Code
-#
-\end_layout
-
-\begin_layout LyX-Code
-# Isotropic power-law maxwell viscoelastic
-\end_layout
-
-\begin_layout LyX-Code
-# (Zienkiewicz and Taylor formulation)
-\end_layout
-
-\begin_layout LyX-Code
-# materialType ='IsotropicPowerLawMaxwellViscoelasticZT'
-\end_layout
-
-\begin_layout LyX-Code
-# density
-\end_layout
-
-\begin_layout LyX-Code
-# youngsModulus
-\end_layout
-
-\begin_layout LyX-Code
-# poissonsRatio
-\end_layout
-
-\begin_layout LyX-Code
-# powerLawExponent
-\end_layout
-
-\begin_layout LyX-Code
-# viscosityCoefficient
-\end_layout
-
-\begin_layout LyX-Code
-# endMaterial ='True' (flag indicating end of material)
-\end_layout
-
-\begin_layout LyX-Code
-#
-\end_layout
-
-\begin_layout LyX-Code
-# Material number 1
-\end_layout
-
-\begin_layout LyX-Code
-materialType = 'IsotropicLinearMaxwellViscoelastic'
-\end_layout
-
-\begin_layout LyX-Code
-density = 3000.0*kg/m**3
-\end_layout
-
-\begin_layout LyX-Code
-youngsModulus = 7.5e10*Pa
-\end_layout
-
-\begin_layout LyX-Code
-poissonsRatio = 0.25
-\end_layout
-
-\begin_layout LyX-Code
-viscosity = 1.0e+18*Pa*s
-\end_layout
-
-\begin_layout LyX-Code
-endMaterial = True
-\end_layout
-
-\begin_layout LyX-Code
-# Material number 2
-\end_layout
-
-\begin_layout LyX-Code
-materialType = 'IsotropicLinearElastic'
-\end_layout
-
-\begin_layout LyX-Code
-density = 3000.0*kg/m**3
-\end_layout
-
-\begin_layout LyX-Code
-youngsModulus = 7.5e10*Pa
-\end_layout
-
-\begin_layout LyX-Code
-poissonsRatio = 0.25
-\end_layout
-
-\begin_layout LyX-Code
-endMaterial = True
-\end_layout
-
-\begin_layout LyX-Code
-# Material number 3
-\end_layout
-
-\begin_layout LyX-Code
-materialType = 'IsotropicLinearMaxwellViscoelastic'
-\end_layout
-
-\begin_layout LyX-Code
-density = 3000.0*kg/m**3
-\end_layout
-
-\begin_layout LyX-Code
-youngsModulus = 7.5e10*Pa
-\end_layout
-
-\begin_layout LyX-Code
-poissonsRatio = 0.25
-\end_layout
-
-\begin_layout LyX-Code
-viscosity = 1.0e+18*Pa*s
-\end_layout
-
-\begin_layout LyX-Code
-endMaterial = True
-\end_layout
-
-\begin_layout Standard
-\begin_inset Float figure
-placement htbp
-wide false
-sideways false
-status open
-
-\begin_layout Caption
-Format of
-\family typewriter
-xx.prop
-\family default
- files.
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Subsection
-
-\family typewriter
-xx.statevar
-\end_layout
-
-\begin_layout Standard
-The
-\family typewriter
-xx.statevar
-\family default
- file specifies which state variables are to be included in the output of
- the elastic and time dependent solutions.
-\end_layout
-
-\begin_layout LyX-Code
-# File specifying which state variables to output.
-\end_layout
-
-\begin_layout LyX-Code
-#
-\end_layout
-
-\begin_layout LyX-Code
-# Comment lines begin with '#'
-\end_layout
-
-\begin_layout LyX-Code
-#
-\end_layout
-
-\begin_layout LyX-Code
-# State variables occur in groups of 6, corresponding to the number of
-\end_layout
-
-\begin_layout LyX-Code
-# stress/strain components.
- The present groups are:
-\end_layout
-
-\begin_layout LyX-Code
-# 1-6: Cauchy stress
-\end_layout
-
-\begin_layout LyX-Code
-# 7-12: Total strain
-\end_layout
-
-\begin_layout LyX-Code
-# 13-18: Viscous strain
-\end_layout
-
-\begin_layout LyX-Code
-# 18-24: Plastic strain
-\end_layout
-
-\begin_layout LyX-Code
-#
-\end_layout
-
-\begin_layout LyX-Code
-# Lines:
-\end_layout
-
-\begin_layout LyX-Code
-# (1) Total accumulated values for the current time step
-\end_layout
-
-\begin_layout LyX-Code
-# (2) Incremental values (previous to current)
-\end_layout
-
-\begin_layout LyX-Code
-# (3) Rate values (previous to current)
-\end_layout
-
-\begin_layout LyX-Code
-#
-\end_layout
-
-\begin_layout LyX-Code
-# Columns (per line):
-\end_layout
-
-\begin_layout LyX-Code
-# (1) Number of state variables to output (0
-\begin_inset Formula $\leq$
-\end_inset
-
- value
-\begin_inset Formula $\leq$
-\end_inset
-
- 24)
-\end_layout
-
-\begin_layout LyX-Code
-# (2)+ State variable number to output (1
-\begin_inset Formula $\leq$
-\end_inset
-
- value
-\begin_inset Formula $\leq$
-\end_inset
-
- 24)
-\end_layout
-
-\begin_layout LyX-Code
-#
-\end_layout
-
-\begin_layout LyX-Code
- 12 1 2 3 4 5 6 7 8 9 10 11 12
-\end_layout
-
-\begin_layout LyX-Code
- 12 1 2 3 4 5 6 7 8 9 10 11 12
-\end_layout
-
-\begin_layout LyX-Code
- 0
-\end_layout
-
-\begin_layout Standard
-\begin_inset Float figure
-placement H
-wide false
-sideways false
-status open
-
-\begin_layout Caption
-Format of
-\family typewriter
-xx.statevar
-\family default
- files.
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Subsection
-
-\family typewriter
-xx.split
-\end_layout
-
-\begin_layout Standard
-The
-\family typewriter
-xx.split
-\family default
- file specifies the split node information for modeling dislocations.
- Dislocations may be used in simulating slip on faults as well as dike intrusion
-s.
-\end_layout
-
-\begin_layout LyX-Code
-# File containing time stepping parameters.
-\end_layout
-
-\begin_layout LyX-Code
-#
-\end_layout
-
-\begin_layout LyX-Code
-# Comment lines begin with '#'
-\end_layout
-
-\begin_layout LyX-Code
-#
-\end_layout
-
-\begin_layout LyX-Code
-# Displacements are specified for each vertex on the fault for each
-\end_layout
-
-\begin_layout LyX-Code
-# element containing the vertex.
- The displacements on each side of the
-\end_layout
-
-\begin_layout LyX-Code
-# fault or dike should have opposite signs.
- The displacements
-\end_layout
-
-\begin_layout LyX-Code
-# associated with a single side of the fault for each vertex should be
-\end_layout
-
-\begin_layout LyX-Code
-# the same.
-\end_layout
-
-\begin_layout LyX-Code
-#
-\end_layout
-
-\begin_layout LyX-Code
-# Columns:
-\end_layout
-
-\begin_layout LyX-Code
-# (1) Element number
-\end_layout
-
-\begin_layout LyX-Code
-# (2) Vertex number
-\end_layout
-
-\begin_layout LyX-Code
-# (3) Time history flag
-\end_layout
-
-\begin_layout LyX-Code
-# 0 = Slip only in elastic solution
-\end_layout
-
-\begin_layout LyX-Code
-# -1 = Slip at constant velocity
-\end_layout
-
-\begin_layout LyX-Code
-# n = Slip according to load history n (requires xx.hist file)
-\end_layout
-
-\begin_layout LyX-Code
-# (4) Displacement in x direction
-\end_layout
-
-\begin_layout LyX-Code
-# (5) Displacement in y direction
-\end_layout
-
-\begin_layout LyX-Code
-# (6) Displacement in z direction
-\end_layout
-
-\begin_layout LyX-Code
-#
-\end_layout
-
-\begin_layout LyX-Code
- 14886 36 0 0.353500000 0.00000000 -0.353500000
-\end_layout
-
-\begin_layout LyX-Code
- 14887 36 0 0.353500000 0.00000000 -0.353500000
-\end_layout
-
-\begin_layout LyX-Code
- 14896 36 0 -0.353500000 0.00000000 0.353500000
-\end_layout
-
-\begin_layout LyX-Code
- 14981 36 0 -0.353500000 0.00000000 0.353500000
-\end_layout
-
-\begin_layout Standard
-\begin_inset Float figure
-placement H
-wide false
-sideways false
-status open
-
-\begin_layout Caption
-Format of
-\family typewriter
-xx.split
-\family default
- files.
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Subsection
-
-\family typewriter
-xx.fuldat
-\end_layout
-
-\begin_layout Standard
-The
-\family typewriter
-xx.fuldat
-\family default
- 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.
-\end_layout
-
-\begin_layout LyX-Code
-# File containing time steps at which full output is desired.
-\end_layout
-
-\begin_layout LyX-Code
-#
-\end_layout
-
-\begin_layout LyX-Code
-# Comment lines begin with '#'
-\end_layout
-
-\begin_layout LyX-Code
-#
-\end_layout
-
-\begin_layout LyX-Code
-# Note: Time step 0 (elastic solution) is always included in the
-\end_layout
-
-\begin_layout LyX-Code
-# output.
-\end_layout
-
-\begin_layout LyX-Code
-#
-\end_layout
-
-\begin_layout LyX-Code
-# List the time steps, one per line.
-\end_layout
-
-\begin_layout LyX-Code
-#
-\end_layout
-
-\begin_layout LyX-Code
- 10
-\end_layout
-
-\begin_layout LyX-Code
- 50
-\end_layout
-
-\begin_layout LyX-Code
- 100
-\end_layout
-
-\begin_layout Standard
-\begin_inset Float figure
-placement H
-wide false
-sideways false
-status open
-
-\begin_layout Caption
-Format of
-\family typewriter
-xx.fuldat
-\family default
- files.
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Subsection
-
-\family typewriter
-\color black
-xx.skew
-\end_layout
-
-\begin_layout Standard
-The
-\family typewriter
-xx.skew
-\family default
- 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.
-\end_layout
-
-\begin_layout Standard
-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.
-\end_layout
-
-\begin_layout Quote
-
-\series bold
-\color red
-Note:
-\series default
-\color none
-Coordinate rotations have not yet been implemented for PyLith.
-\end_layout
-
-\begin_layout LyX-Code
-# File containing local nodal coordinates.
-\end_layout
-
-\begin_layout LyX-Code
-#
-\end_layout
-
-\begin_layout LyX-Code
-# Comment lines begin with '#'
-\end_layout
-
-\begin_layout LyX-Code
-#
-\end_layout
-
-\begin_layout LyX-Code
-# First, specify units for rotations.
-\end_layout
-
-\begin_layout LyX-Code
-#
-\end_layout
-
-\begin_layout LyX-Code
-rotation_units = degree
-\end_layout
-
-\begin_layout LyX-Code
-#
-\end_layout
-
-\begin_layout LyX-Code
-#
-\end_layout
-
-\begin_layout LyX-Code
-# Columns:
-\end_layout
-
-\begin_layout LyX-Code
-# (1) Node number
-\end_layout
-
-\begin_layout LyX-Code
-# (2) Euler angle for rotation in the x-y plane
-\end_layout
-
-\begin_layout LyX-Code
-# (3) Euler angle for rotation in the x-z plane
-\end_layout
-
-\begin_layout LyX-Code
-#
-\end_layout
-
-\begin_layout LyX-Code
-68 12.3 4.2
-\end_layout
-
-\begin_layout LyX-Code
-132 -12.3 -4.2
-\end_layout
-
-\begin_layout Standard
-\begin_inset Float figure
-placement H
-wide false
-sideways false
-status open
-
-\begin_layout Caption
-Format of
-\family typewriter
-xx.skew
-\family default
- files.
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Subsubsection
-Winkler Forces
-\end_layout
-
-\begin_layout Standard
-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.
-\end_layout
-
-\begin_layout Paragraph
-Quadrature order
-\end_layout
-
-\begin_layout Description
-Full Quadrature order that should give the exact element matrices when the
- elements are geometrically undistorted.
-
-\end_layout
-
-\begin_layout Description
-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).
-\end_layout
-
-\begin_deeper
-\begin_layout Quote
-
-\series bold
-\color red
-Warning:
-\series default
-\color none
-Use with caution as reduced quadrature can lead to numerical instabilities.
-
-\end_layout
-
-\end_deeper
-\begin_layout Description
-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_layout
-
-\begin_layout Paragraph
-Prestresses
-\end_layout
-
-\begin_layout Standard
-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.
-\end_layout
-
-\begin_layout Subsection
-
-\family typewriter
-\color black
-xx.hist
-\end_layout
-
-\begin_layout Standard
-The
-\family typewriter
-xx.hist
-\family default
- files provide time histories for use in boundary conditions.
-\end_layout
-
-\begin_layout LyX-Code
-# File specifying time variation of boundary conditions.
-\end_layout
-
-\begin_layout LyX-Code
-#
-\end_layout
-
-\begin_layout LyX-Code
-# Comment lines begin with '#'
-\end_layout
-
-\begin_layout LyX-Code
-#
-\end_layout
-
-\begin_layout LyX-Code
-# Each time history consists of two or more lines.
- The first line
-\end_layout
-
-\begin_layout LyX-Code
-# indicates the number of points in the history and the default load
-\end_layout
-
-\begin_layout LyX-Code
-# value for the history.
- Subsequent lines define time/load pairs.
-\end_layout
-
-\begin_layout LyX-Code
-#
-\end_layout
-
-\begin_layout LyX-Code
-# Line 1, column 1: The number of points in the time history
-\end_layout
-
-\begin_layout LyX-Code
-# Line 1, column 2: The value assigned to every point by default
-\end_layout
-
-\begin_layout LyX-Code
-# (overridden by values in time history)
-\end_layout
-
-\begin_layout LyX-Code
-# Line 2+, column 1: Time (in seconds) for a given load value
-\end_layout
-
-\begin_layout LyX-Code
-# Line 2+, column 2: Load value at given time
-\end_layout
-
-\begin_layout LyX-Code
-#
-\end_layout
-
-\begin_layout LyX-Code
- 2 1.0
-\end_layout
-
-\begin_layout LyX-Code
-2.84014e+08 0.1
-\end_layout
-
-\begin_layout LyX-Code
-3.15576e+08 0.5
-\end_layout
-
-\begin_layout Standard
-\begin_inset Float figure
-placement H
-wide false
-sideways false
-status open
-
-\begin_layout Caption
-Format of
-\family typewriter
-xx.hist
-\family default
- files.
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Subsection
-
-\family typewriter
-xx.wink
-\end_layout
-
-\begin_layout Standard
-The
-\family typewriter
-xx.wink
-\family default
- file specifies Winkler elements, which may be used as spring foundations
- in the simulation of gravity.
-\end_layout
-
-\begin_layout LyX-Code
-# File containing Winkler elements.
-\end_layout
-
-\begin_layout LyX-Code
-#
-\end_layout
-
-\begin_layout LyX-Code
-# Comment lines begin with '#'
-\end_layout
-
-\begin_layout LyX-Code
-#
-\end_layout
-
-\begin_layout LyX-Code
-# Flags for the degrees of freedom can have the following values:
-\end_layout
-
-\begin_layout LyX-Code
-# 0 = no Winkler force
-\end_layout
-
-\begin_layout LyX-Code
-# 1 = Winkler force applied at all times
-\end_layout
-
-\begin_layout LyX-Code
-# -n = Winkler force applied according to load history n
-\end_layout
-
-\begin_layout LyX-Code
-# (requires xx.hist file)
-\end_layout
-
-\begin_layout LyX-Code
-#
-\end_layout
-
-\begin_layout LyX-Code
-# Columns:
-\end_layout
-
-\begin_layout LyX-Code
-# (1) Vertex number
-\end_layout
-
-\begin_layout LyX-Code
-# (2) Flag for DOF in x-direction
-\end_layout
-
-\begin_layout LyX-Code
-# (3) Flag for DOF in y-direction
-\end_layout
-
-\begin_layout LyX-Code
-# (4) Flag for DOF in z-direction
-\end_layout
-
-\begin_layout LyX-Code
-# (5) Magnitude of restoring force for x-direction
-\end_layout
-
-\begin_layout LyX-Code
-# (6) Magnitude of restoring force for x-direction
-\end_layout
-
-\begin_layout LyX-Code
-# (7) Magnitude of restoring force for x-direction
-\end_layout
-
-\begin_layout LyX-Code
-#
-\end_layout
-
-\begin_layout LyX-Code
-14 0 -1 0 0.0e+00 1.0e+25 0.0e+00
-\end_layout
-
-\begin_layout LyX-Code
-18 0 1 0 1.0e+20 0.0e+00 0.0e+00
-\end_layout
-
-\begin_layout Standard
-\begin_inset Float figure
-placement H
-wide false
-sideways false
-status open
-
-\begin_layout Caption
-Format of
-\family typewriter
-xx.wink
-\family default
- files.
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
\end_body
\end_document
Modified: short/3D/PyLith/trunk/doc/userguide/install/install.lyx
===================================================================
--- short/3D/PyLith/trunk/doc/userguide/install/install.lyx 2007-06-16 22:41:51 UTC (rev 7275)
+++ short/3D/PyLith/trunk/doc/userguide/install/install.lyx 2007-06-17 03:32:28 UTC (rev 7276)
@@ -1,2698 +1,2662 @@
-#LyX 1.4.3-4 created this file. For more info see http://www.lyx.org/
-\lyxformat 245
-\begin_document
-\begin_header
-\textclass book
-\begin_preamble
-
-\end_preamble
-\language english
-\inputencoding latin1
-\fontscheme default
-\graphics default
-\paperfontsize default
-\spacing single
-\papersize default
-\use_geometry true
-\use_amsmath 1
-\cite_engine basic
-\use_bibtopic false
-\paperorientation portrait
-\leftmargin 1in
-\topmargin 1in
-\rightmargin 1in
-\bottommargin 2in
-\secnumdepth 3
-\tocdepth 3
-\paragraph_separation indent
-\defskip medskip
-\quotes_language english
-\papercolumns 1
-\papersides 2
-\paperpagestyle default
-\tracking_changes false
-\output_changes false
-\end_header
-
-\begin_body
-
-\begin_layout Chapter
-\begin_inset LatexCommand \label{cha:Installation-and-Getting}
-
-\end_inset
-
-Installation and Getting Help
-\end_layout
-
-\begin_layout Section
-Introduction
-\end_layout
-
-\begin_layout Standard
-Installing PyLith is a three-stage process:
-\end_layout
-
-\begin_layout Enumerate
-Install the development version of PETSc (Section
-\begin_inset LatexCommand \vref{sec:Installing-PETSc}
-
-\end_inset
-
-)
-\end_layout
-
-\begin_layout Enumerate
-Install PyLith (Section
-\begin_inset LatexCommand \vref{sec:Installing-PyLith}
-
-\end_inset
-
-)
-\end_layout
-
-\begin_layout Enumerate
-Configure Pyre to launch parallel runs of PyLith (Section
-\begin_inset LatexCommand \vref{sec:Pyre-Configuration}
-
-\end_inset
-
-)
-\end_layout
-
-\begin_layout Standard
-Each stage is substantially faster and easier than the one before it.
- In fact, after successfully installing PETSc, you are close to being done.
- So review Section
-\begin_inset LatexCommand \ref{sec:System-Requirements}
-
-\end_inset
-
- to make sure you have the required tools at hand; and then proceed fearlessly,
- dear reader, to Section
-\begin_inset LatexCommand \ref{sec:Installing-PETSc}
-
-\end_inset
-
-.
-\end_layout
-
-\begin_layout Standard
-Advanced users and software developers may be interested in downloading
- the latest PyLith and PETSc source code directly from the source code repositor
-ies, instead of using the prepared source packages; see Section
-\begin_inset LatexCommand \ref{sec:Software-Repository}
-
-\end_inset
-
- later in this chapter.
-\end_layout
-
-\begin_layout Standard
-PyLith is developed and tested on Linux and Mac OS X.
-\end_layout
-
-\begin_layout Section
-Getting Help
-\end_layout
-
-\begin_layout Standard
-Help is available via the CIG Short-Term Crustal Dynamics Mailing List and
- CIG's issue tracking system.
-\end_layout
-
-\begin_layout Subsection
-Requesting Help
-\end_layout
-
-\begin_layout Standard
-The
-\begin_inset LatexCommand \url[CIG Short-Term Crustal Dynamics Mailing List]{cig-short at geodynamics.org}
-
-\end_inset
-
- is 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
-\begin_inset LatexCommand \htmlurl[CIG Mailing Lists]{www.geodynamics.org/cig/lists/}
-
-\end_inset
-
-.
-\end_layout
-
-\begin_layout Subsection
-Reporting Bugs
-\end_layout
-
-\begin_layout Standard
-CIG uses
-\family typewriter
-Roundup
-\family default
- for bug tracking.
- If you find a bug in PyLith, please submit a bug report to the
-\begin_inset LatexCommand \htmlurl[CIG Roundup System]{www.geodynamics.org/roundup/}
-
-\end_inset
-
-.
- 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
-\family sans
-Create New
-\family default
- under
-\family sans
-Issues
-\family default
-.
-\end_layout
-
-\begin_layout Section
-\begin_inset LatexCommand \label{sec:System-Requirements}
-
-\end_inset
-
-System Requirements
-\end_layout
-
-\begin_layout Standard
-Installation of PyLith requires the following:
-\end_layout
-
-\begin_layout Itemize
-A Fortran compiler
-\end_layout
-
-\begin_layout Itemize
-A C++ compiler
-\end_layout
-
-\begin_layout Itemize
-Python 2.3 or greater (Python 2.4 or greater is required on 64-bit machines)
-\end_layout
-
-\begin_layout Itemize
-The development version of the PETSc library
-\end_layout
-
-\begin_layout Subsection
-Fortran Compiler
-\end_layout
-
-\begin_layout Standard
-The core of PyLith is Fortran-77 code which can be compiled with any Fortran-77
- or Fortran-9x compiler.
-\end_layout
-
-\begin_layout Standard
-There are several free Fortran compilers available.
- GCC 4 contains a Fortran-95 compiler called
-\family typewriter
-gfortran
-\family default
-.
- Earlier versions of GCC include
-\family typewriter
-g77
-\family default
-, which is also suitable for building PyLith.
- Another free alternative is
-\family typewriter
-g95
-\family default
-; the G95 project offers pre-built binaries for a variety of systems, which
- makes it an attractive option for Mac OS X users.
-\end_layout
-
-\begin_layout Standard
-PyLith has also been tested with commercial Fortran compilers, including
- Intel's
-\family typewriter
-ifort
-\family default
- and the Portland Group compiler.
-\end_layout
-
-\begin_layout Subsection
-C++ Compiler
-\end_layout
-
-\begin_layout Standard
-A C++ compiler is required for building PETSc's Sieve component and the
- PyLith components that interface with Sieve.
- The C++ compiler is also used to compile the layer which connects the high-leve
-l Python code with the low-level Fortran code.
-\end_layout
-
-\begin_layout Standard
-On Unix systems, there is a high likelihood that a usable C++ compiler is
- already installed.
- Check with your system administrator if you are unsure of the name of the
- C++ compiler command.
-\end_layout
-
-\begin_layout Standard
-On Linux, the standard C++ compiler is
-\family typewriter
-g++
-\family default
-.
- If the
-\family typewriter
-g++
-\family default
- command is not available, install GCC using the package manager for your
- distribution.
-\end_layout
-
-\begin_layout Standard
-The Mac OS X version of GCC is included in a software development suite
- called Xcode.
- Xcode is available as a free download at the
-\begin_inset LatexCommand \htmlurl[Apple Developer Connection]{developer.apple.com}
-
-\end_inset
-
-.
- (Note that Xcode does not include a Fortran compiler.)
-\end_layout
-
-\begin_layout Subsection
-Python
-\end_layout
-
-\begin_layout Standard
-PyLith's high-level user interface code is written in Python, utilizing
- the Pyre framework.
- Pyre is included in the Python package known as Pythia.
- PyLith requires Pythia v0.8.1.3 or later, but you need not install Pythia
- because PyLith's
-\family typewriter
-configure
-\family default
- script automatically downloads Pythia directly from CIG.
-\end_layout
-
-\begin_layout Standard
-Pythia (and therefore PyLith) requires Python 2.3 or later.
-\end_layout
-
-\begin_layout Quote
-
-\color red
-Warning:
-\color none
- On 64-bit machines, Python 2.4 or later is required.
- Python 2.3 contains a bug which prevents installation on 64-bit hardware.
-\end_layout
-
-\begin_layout Standard
-Your system may already have a suitable Python interpreter installed.
- To check, type the `
-\family typewriter
-python
-\family default
-' command:
-\end_layout
-
-\begin_layout LyX-Code
-$ python -V
-\end_layout
-
-\begin_layout LyX-Code
-Python 2.3.4
-\end_layout
-
-\begin_layout Standard
-Mac OS X 10.3 and later ships with a suitable version of Python preinstalled.
- If you're using an older version of Mac OS X, or for more information in
- general, see
-\begin_inset LatexCommand \htmlurl[Python on the Mac]{www.python.org/download/mac}
-
-\end_inset
-
- at the Python web site.
-\end_layout
-
-\begin_layout Standard
-On Linux, simply install the binary system package available for your distributi
-on.
- Be sure to select the Python development package (typically called
-\family typewriter
-python-dev
-\family default
-) in addition to the core Python package -- even if you don't plan on doing
- any Python software development.
- The development package contains the Python
-\family typewriter
-include
-\family default
- files, which are necessary for building PyLith.
-\end_layout
-
-\begin_layout Standard
-If you are working on a cluster and
-\family typewriter
-python
-\family default
- is too old, try poking around a little.
- Sometimes multiple versions of Python are installed on the same system:
-\end_layout
-
-\begin_layout LyX-Code
-$ python -V
-\end_layout
-
-\begin_layout LyX-Code
-Python 2.2.3
-\end_layout
-
-\begin_layout LyX-Code
-$ which python
-\end_layout
-
-\begin_layout LyX-Code
-/usr/bin/python
-\end_layout
-
-\begin_layout LyX-Code
-$ ls /usr/bin/python*
-\end_layout
-
-\begin_layout LyX-Code
-/usr/bin/python /usr/bin/python2 /usr/bin/python2.2
-\end_layout
-
-\begin_layout LyX-Code
-/usr/bin/python24 /usr/bin/python2.4
-\end_layout
-
-\begin_layout LyX-Code
-$
-\end_layout
-
-\begin_layout Standard
-In the above scenario, it is useful to create an alias to the newer Python:
-\end_layout
-
-\begin_layout LyX-Code
-$ cd ~/bin
-\end_layout
-
-\begin_layout LyX-Code
-$ ln -s /usr/bin/python2.4 python
-\end_layout
-
-\begin_layout LyX-Code
-$ cd
-\end_layout
-
-\begin_layout LyX-Code
-$ hash -r
-\end_layout
-
-\begin_layout LyX-Code
-$ which python
-\end_layout
-
-\begin_layout LyX-Code
-~/bin/python
-\end_layout
-
-\begin_layout LyX-Code
-$ python -V
-\end_layout
-
-\begin_layout LyX-Code
-Python 2.4.1
-\end_layout
-
-\begin_layout LyX-Code
-$
-\end_layout
-
-\begin_layout Standard
-If absolutely necessary, one can easily build Python from source using a
- C compiler.
- You can download Python from the
-\begin_inset LatexCommand \htmlurl[Python website]{www.python.org}
-
-\end_inset
-
-.
-
-\end_layout
-
-\begin_layout Subsection
-PETSc
-\end_layout
-
-\begin_layout Standard
-PyLith requires PETSc -- including PETSc's new Sieve component.
- Sieve is still under development; as of this writing, Sieve is only available
- in the development version of PETSc.
-\end_layout
-
-\begin_layout Standard
-PETSc itself depends upon several other sofware packages.
- Fortunately, PETSc's configuration script can automatically download and
- build these software packages for you.
-\end_layout
-
-\begin_layout Standard
-For general information about the development version of PETSc, visit
-\begin_inset LatexCommand \htmlurl[the PETSc Developers Site]{http://www-unix.mcs.anl.gov/petsc/petsc-as/developers/}
-
-\end_inset
-
-.
-\end_layout
-
-\begin_layout Section
-\begin_inset LatexCommand \label{sec:Installing-PETSc}
-
-\end_inset
-
-Installing PETSc
-\end_layout
-
-\begin_layout Standard
-To install PETSc, you will download and unpack the
-\family typewriter
-petsc-dev
-\family default
- tarball, run a Python configure script (
-\family typewriter
-config/configure.py
-\family default
-), set a pair of environment variables, and finally build PETSc from source
- by running
-\family typewriter
-make
-\family default
-.
-\end_layout
-
-\begin_layout Quote
-
-\series bold
-TIP:
-\series default
-If you run into problems configuring or building PETSc, send
-\emph on
-both
-\family typewriter
-\emph default
- configure.log
-\family default
- and
-\family typewriter
-make_log_
-\emph on
-$PETSC_ARCH
-\family default
-\emph default
- to
-\begin_inset LatexCommand \url[PETSc Maintenance Mailing List]{petsc-maint at mcs.anl.gov}
-
-\end_inset
-
-.
-\end_layout
-
-\begin_layout Standard
-For detailed information on installing PETSc, see
-\begin_inset LatexCommand \htmlurl[the PETSc Installation Docs]{http://www-unix.mcs.anl.gov/petsc/petsc-as/documentation/installation.html}
-
-\end_inset
-
-.
-\end_layout
-
-\begin_layout Subsection
-Downloading and Unpacking
-\family typewriter
-petsc-dev
-\end_layout
-
-\begin_layout Standard
-The development version of PETSc is called
-\family typewriter
-petsc-dev
-\family default
-.
- Download the nightly tarball snapshot of
-\family typewriter
-petsc-dev
-\family default
- from the
-\begin_inset LatexCommand \htmlurl[the PETSc Developers Site]{http://www-unix.mcs.anl.gov/petsc/petsc-as/developers/}
-
-\end_inset
-
-.
- Unpack it using the
-\family typewriter
-tar
-\family default
- command:
-\end_layout
-
-\begin_layout LyX-Code
-$ tar xzf petsc-dev.tar.gz
-\end_layout
-
-\begin_layout Standard
-If you don't have GNU Tar, try the following command instead:
-\end_layout
-
-\begin_layout LyX-Code
-$ gunzip -c petsc-dev.tar.gz | tar xf -
-\end_layout
-
-\begin_layout Standard
-After unpacking, a directory called
-\family typewriter
-petsc-dev
-\family default
- will be visible in your working directory.
-\end_layout
-
-\begin_layout Subsection
-PETSc Configuration
-\end_layout
-
-\begin_layout Standard
-Navigate to the directory containing the PETSc source:
-\end_layout
-
-\begin_layout Quote
-
-\family typewriter
-$ cd petsc-dev
-\end_layout
-
-\begin_layout Standard
-To configure PETSc, run
-\family typewriter
-./config/configure.py
-\family default
- with the appropriate arguments to configure PETSc for your system.
- At a minimum, configuring PETSc for use with PyLith requires the following
- arguments:
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
---with-clanguage=c++
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
---with-boost=1
-\end_layout
-
-\begin_layout LyX-Code
---with-chaco=1
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
---with-sieve=1
-\end_layout
-
-\begin_layout Standard
-You will need to specify additional options; the specific set of options
- you will use depends upon the libraries and compilers you have available.
- See the examples below.
-\end_layout
-
-\begin_layout Quote
-
-\series bold
-TIP:
-\series default
- Run
-\family typewriter
-./config/configure.py --help
-\family default
- to see the long list of all possible options.
-\end_layout
-
-\begin_layout Standard
-Building PETSc with Sieve requires the following external libraries:
-\end_layout
-
-\begin_layout Itemize
-an MPI library
-\end_layout
-
-\begin_layout Itemize
-BLAS/LAPACK
-\end_layout
-
-\begin_layout Itemize
-Boost
-\end_layout
-
-\begin_layout Itemize
-Chaco
-\end_layout
-
-\begin_layout Standard
-You can instruct PETSc to download and install any or all of these libraries
- for you.
-\end_layout
-
-\begin_layout Standard
-If you have an MPI implementation installed on your workstation, you can
- use it, or let PETSc download and install one for you.
- If you are installing on a cluster, you should configure PETSc to use an
- existing MPI library installed by the system administrators.
-\end_layout
-
-\begin_layout Standard
-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 OS X).
-\end_layout
-
-\begin_layout Standard
-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 to build PETSc using the GNU compilers, be sure to let
- PETSc know which compilers you want to use instead.
-\end_layout
-
-\begin_layout Subsubsection
-PETSc Configuration Examples
-\end_layout
-
-\begin_layout Standard
-In our first example, we configure PETSc on a Linux workstation.
- BLAS and LAPACK are preinstalled under
-\family typewriter
-/usr/lib
-\family default
-; PETSc finds these system libraries automatically.
- We happen to have MPICH already installed;
-\family typewriter
-mpicc
-\family default
- and other related MPI commands are accessible via our
-\family typewriter
-PATH
-\family default
-, so PETSc finds our MPICH installation automatically.
- However, we don't have Boost or Chaco installed, so we instruct PETSc to
- download these packages for us.
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
-$ ls -1 /usr/lib/libblas.so /usr/lib/liblapack.so
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
-/usr/lib/libblas.so
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
-/usr/lib/liblapack.so
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
-$ which mpicc
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
-/opt/mpich/bin/mpicc
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
-$
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
-$ ./config/configure.py
-\backslash
-
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
- --with-sieve=1
-\backslash
-
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
- --with-clanguage=C++
-\backslash
-
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
- --with-boost=1 --download-boost=1
-\backslash
-
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
- --with-chaco=1 --download-chaco=1
-\end_layout
-
-\begin_layout Standard
-In our next example, we configure PETSc on a Mac OS X machine.
- We have installed Apple's Xcode and the G95 Fortran compiler.
- However, we don't have anything else preinstalled, so we instruct PETSc
- to download almost everything else, including MPICH.
- Intentionally, we don't specify anything about BLAS/LAPACK: PETSc automatically
- finds vecLib, which is built-in to Mac OS X.
-\end_layout
-
-\begin_layout LyX-Code
-$ ./config/configure.py
-\backslash
-
-\end_layout
-
-\begin_layout LyX-Code
- --with-sieve=1
-\backslash
-
-\end_layout
-
-\begin_layout LyX-Code
- --with-clanguage=C++
-\backslash
-
-\end_layout
-
-\begin_layout LyX-Code
- --with-fc=g95
-\backslash
-
-\end_layout
-
-\begin_layout LyX-Code
- --with-boost=1 --download-boost=1
-\backslash
-
-\end_layout
-
-\begin_layout LyX-Code
- --with-chaco=1 --download-chaco=1
-\backslash
-
-\end_layout
-
-\begin_layout LyX-Code
- --with-mpi=1 --download-mpich=1
-\backslash
-
-\end_layout
-
-\begin_layout LyX-Code
- --with-x=0
-\end_layout
-
-\begin_layout Standard
-In our final example, we configure PETSc on a 64-bit Linux cluster.
- We use an existing MPI implementation installed by the system administrators.
- BLAS/LAPACK is missing, so we instruct PETSc to download it, in addition
- to Boost and Chaco.
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
-$ ./config/configure.py
-\backslash
-
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
- --with-sieve=1
-\backslash
-
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
- --with-clanguage=C++
-\backslash
-
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
- --with-mpi-dir=/opt/mpich/myrinet_mx2g/intel
-\backslash
-
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
- --download-f-blas-lapack=1
-\family default
-
-\family typewriter
-
-\backslash
-
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
- --with-boost=1 --download-boost=1
-\backslash
-
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
- --with-chaco=1 --download-chaco=1
-\end_layout
-
-\begin_layout Subsubsection
-Running
-\family typewriter
-configure.py
-\end_layout
-
-\begin_layout Standard
-After several minutes, the configure script should finish and display the
- PETSc settings.
- Check to make sure these match your expectations before continuing.
-\end_layout
-
-\begin_layout Subsection
-Setting PETSC Environment Variables
-\end_layout
-
-\begin_layout Standard
-Before building PETSc, set the
-\family typewriter
-PETSC_DIR
-\family default
- and
-\family typewriter
-PETSC_ARCH
-\family default
- environment variables.
- Upon completion, the configure script displays instructions for setting
- these two variables:
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
-**
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
-** Before running "make" your PETSC_ARCH must be specified with:
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
-** ** setenv PETSC_ARCH linux-gnu-cxx-debug (csh/tcsh)
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
-** ** PETSC_ARCH=linux-gnu-cxx-debug; export PETSC_ARCH (sh/bash)
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
-**
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
-**
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
-** Before running "make" your PETSC_DIR must be specified with:
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
-** ** setenv PETSC_DIR /opt/petsc-dev (csh/tcsh)
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
-** ** PETSC_DIR=/opt/petsc-dev; export PETSC_DIR (sh/bash)
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
-**
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
-**
-\end_layout
-
-\begin_layout Standard
-
-\family typewriter
-PETSC_ARCH
-\family default
- is a tag identifying this configuration of PETSc.
-
-\family typewriter
-PETSC_DIR
-\family default
- is set to the full path of the top-level directory in the PETSc source
- tree (the
-\family typewriter
-petsc-dev
-\family default
- directory).
- You will want to set these environment variables in your
-\family typewriter
-.bashrc
-\family default
-,
-\family typewriter
-.cshrc
-\family default
-, or similar file.
-\end_layout
-
-\begin_layout Subsection
-Building PETSc
-\end_layout
-
-\begin_layout Standard
-After setting
-\family typewriter
-PETSC_DIR
-\family default
- and
-\family typewriter
-PETSC_ARCH
-\family default
-, run
-\family typewriter
-make
-\family default
- to build PETSc:
-\end_layout
-
-\begin_layout Quote
-
-\family typewriter
-$ make
-\end_layout
-
-\begin_layout Subsection
-Testing the PETSc Installation
-\end_layout
-
-\begin_layout Standard
-Optionally, you may test your PETSc installation:
-\end_layout
-
-\begin_layout Quote
-
-\family typewriter
-$ make test
-\end_layout
-
-\begin_layout Standard
-One of the tests will attempt to display some X windows.
- If X windows is not available from the shell in which you run
-\family typewriter
-make test
-\family default
-, then that test will fail.
-\end_layout
-
-\begin_layout Section
-\begin_inset LatexCommand \label{sec:Installing-PyLith}
-
-\end_inset
-
-Installing PyLith
-\end_layout
-
-\begin_layout Standard
-To install PyLith, you follow the procedure that is commonly used with other
- open source software packages.
- First, download the source package available at the
-\begin_inset LatexCommand \htmlurl[Geodynamics Software Packages web page]{www.geodynamics.org/cig/software/packages}
-
-\end_inset
-
-.
- After unpacking the source, you run a prepackaged shell script to configure
- PyLith for your system.
- Finally, you use the
-\family typewriter
-make
-\family default
- utility to build and install PyLith from source.
-
-\end_layout
-
-\begin_layout Subsection
-Downloading and Unpacking the PyLith Source
-\end_layout
-
-\begin_layout Standard
-Download PyLith from the
-\begin_inset LatexCommand \htmlurl[Geodynamics website]{www.geodynamics.org}
-
-\end_inset
-
-.
- Click the
-\family sans
-software
-\family default
- tab at the top of the page.
- Then click
-\family sans
-Software Packages
-\family default
-, then
-\family sans
-Short-Term Crustal Dynamics
-\family default
-.
- Once you click the PyLith link, download the source archive and unpack
- it using the
-\family typewriter
-tar
-\family default
- command:
-\end_layout
-
-\begin_layout LyX-Code
-$ tar xzf pylith3d-0.8.2.tar.gz
-\end_layout
-
-\begin_layout Standard
-If you don't have GNU Tar, try the following command instead:
-\end_layout
-
-\begin_layout LyX-Code
-$ gunzip -c pylith3d-0.8.2.tar.gz | tar xf -
-\end_layout
-
-\begin_layout Subsection
-PyLith Installation Procedure
-\end_layout
-
-\begin_layout Quote
-
-\series bold
-TIP:
-\series default
- If you run into problems configuring or building PyLith, send both the
-
-\family typewriter
-config.log
-\family default
- and
-\family typewriter
-make.log
-\family default
- files to the
-\begin_inset LatexCommand \url[CIG Short-Term Crustal Dynamics Mailing List]{cig-short at geodynamics.org}
-
-\end_inset
-
-.
- To create the
-\family typewriter
-make.log
-\family default
- file, redirect the output of
-\family typewriter
-make
-\family default
- to a file:
-\family typewriter
-make
-\begin_inset Formula $>$
-\end_inset
-
- make.log
-\family default
-.
-
-\end_layout
-
-\begin_layout Standard
-After unpacking the source, use the following procedure to install PyLith:
-\end_layout
-
-\begin_layout Enumerate
-Navigate (i.e.,
-\family typewriter
-cd
-\family default
-) to the directory containing the PyLith source
-\family typewriter
-.
-\newline
-
-\newline
-$ cd pylith3d-0.8.2
-\end_layout
-
-\begin_layout Enumerate
-Type .
-\family typewriter
-/configure
-\family default
- to configure the package for your system
-\family typewriter
-.
-\newline
-
-\newline
-$ ./configure
-\end_layout
-
-\begin_layout Enumerate
-Type
-\family typewriter
-make
-\family default
- to build the package.
-\family typewriter
-
-\newline
-
-\newline
-$ make
-\end_layout
-
-\begin_layout Standard
-If you are content to run PyLith from the build directory, then you are
- done.
- Upon successful completion, the
-\family typewriter
-make
-\family default
- command creates a script called
-\family typewriter
-pylith3dapp.py
-\family default
- in the
-\family typewriter
-pylith3d
-\family default
- subdirectory; this is the script you will use to run PyLith.
- You may wish to add the
-\family typewriter
-pylith3d
-\family default
- directory to your
-\family typewriter
-PATH
-\family default
-.
-\end_layout
-
-\begin_layout Standard
-For more details about
-\family typewriter
-configure
-\family default
-, see Section
-\begin_inset LatexCommand \ref{sec:Configuration}
-
-\end_inset
-
- below.
-\end_layout
-
-\begin_layout Subsubsection
-Installing PyLith to a Secondary Location
-\end_layout
-
-\begin_layout Standard
-Optionally, after building PyLith, you can install it in a secondary location
- using the
-\family typewriter
-make install
-\family default
- command.
-\end_layout
-
-\begin_layout Quotation
-
-\series bold
-Note:
-\series default
- The following is not recommended if you plan on modifying the PyLith source.
-\end_layout
-
-\begin_layout Standard
-By default, PyLith is configured to install under
-\family typewriter
-/usr/local
-\family default
-, which requires that you become
-\family typewriter
-root
-\family default
- before issuing the
-\family typewriter
-make install
-\family default
- command.
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
-$ su
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
-Password:
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
-# make install
-\end_layout
-
-\begin_layout Standard
-To install as an ordinary user instead of
-\family typewriter
-root
-\family default
-, give
-\family typewriter
-configure
-\family default
- the
-\family typewriter
---prefix
-\family default
- option, specifying a directory to which you have write access:
-\end_layout
-
-\begin_layout LyX-Code
-$ cd
-\family typewriter
-pylith3d-0.8.2
-\end_layout
-
-\begin_layout LyX-Code
-$ ./configure --prefix=$HOME/cig
-\end_layout
-
-\begin_layout LyX-Code
-$ make
-\end_layout
-
-\begin_layout LyX-Code
-$ make install
-\end_layout
-
-\begin_layout Standard
-The above commands will install PyLith under
-\family typewriter
-$HOME/cig
-\family default
-.
- Afterwards, you may wish to add
-\family typewriter
-PREFIX/bin
-\family default
- (
-\family typewriter
-$HOME/cig/bin
-\family default
-, in this example) to your
-\family typewriter
-PATH
-\family default
-.
-\end_layout
-
-\begin_layout Standard
-After running
-\family typewriter
-make install
-\family default
-, you may (if desired) run
-\family typewriter
-make clean
-\family default
- in the build directory to save disk space.
- You are also free to delete the source/build directory altogether.
- (Note that
-\family typewriter
-make install
-\family default
- installs the examples under
-\family typewriter
-PREFIX/share/pylith3d/examples
-\family default
-.)
-\end_layout
-
-\begin_layout Subsection
-\begin_inset LatexCommand \label{sec:Configuration}
-
-\end_inset
-
-PyLith Configuration
-\end_layout
-
-\begin_layout Standard
-The
-\family typewriter
-configure
-\family default
- script checks for various system features.
- As it runs, it prints messages informing you of which features it is checking
- for.
- Upon successful completion, it generates a
-\family typewriter
-Makefile
-\family default
- in each source directory of the package.
- It also generates a
-\family typewriter
-config.h
-\family default
- header file, which contains system-dependent definitions.
-
-\end_layout
-
-\begin_layout Standard
-The
-\family typewriter
-configure
-\family default
- script will attempt to guess the correct values of various installation
- parameters.
- In the event that the default values used by
-\family typewriter
-configure
-\family default
- are incorrect for your system, or
-\family typewriter
-configure
-\family default
- is unable to guess the value of a certain parameter, you may have to specify
- the correct value by hand.
-\end_layout
-
-\begin_layout Quote
-
-\series bold
-Important:
-\series default
- If the
-\family typewriter
-configure
-\family default
- script fails, and you don't know what went wrong, examine the log file
-
-\family typewriter
-config.log
-\family default
-.
- This file contains a detailed transcript of all the checks
-\family typewriter
-configure
-\family default
- performed.
- Most importantly, it includes the error output (if any) from your compiler.
- When seeking help for
-\family typewriter
-configure
-\family default
- failures on the
-\begin_inset LatexCommand \url[CIG Short-Term Crustal Dynamics Mailing List]{cig-short at geodynamics.org}
-
-\end_inset
-
-, please send
-\family typewriter
-config.log
-\family default
- as an attachment.
-\end_layout
-
-\begin_layout Standard
-The
-\family typewriter
-configure
-\family default
- script will automatically check for needed Python dependencies, including
- the Pythia package (which includes the Pyre framework).
- If necessary,
-\family typewriter
-configure
-\family default
- will download missing Python packages from the Internet.
-\end_layout
-
-\begin_layout Standard
-PyLith v0.8.2 requires Pythia v0.8.1.3 or later, which
-\family typewriter
-configure
-\family default
- downloads directly from CIG.
- (Pythia v0.8.1.x is distinct from Pythia v0.8, which you may have installed
- previously.) Pythia v0.8.1.x is pure Python, and resides in a file or directory
- with the extension
-\family typewriter
-.egg
-\family default
- (e.g.,
-\family typewriter
-pythia-0.8.1.3.egg
-\family default
-).
- The
-\family typewriter
-configure
-\family default
- script may download other
-\family typewriter
-.egg
-\family default
- packages, in addition to Pythia.
- These are Python packages which are required (either directly or indirectly)
- by PyLith.
-\end_layout
-
-\begin_layout Subsubsection
-Configure Usage
-\end_layout
-
-\begin_layout Standard
-For a detailed list of
-\family typewriter
-configure
-\family default
- variables and options, give
-\family typewriter
-configure
-\family default
- the
-\family typewriter
---help
-\family default
- option:
-\end_layout
-
-\begin_layout LyX-Code
-$ ./configure --help
-\end_layout
-
-\begin_layout Standard
-The following is a summary of the variables and options that are important
- when installing PyLith.
-
-\end_layout
-
-\begin_layout Subsubsection
-Environment Variables
-\end_layout
-
-\begin_layout Standard
-Environment variables may be specified as arguments to
-\family typewriter
-configure
-\family default
-, e.g.,
-\end_layout
-
-\begin_layout LyX-Code
-$ ./configure PYTHON=/usr/bin/python2.4
-\end_layout
-
-\begin_layout Standard
-\noindent
-\align center
-\begin_inset Float table
-placement H
-wide false
-sideways false
-status open
-
-\begin_layout Standard
-\noindent
-\align center
-\begin_inset Tabular
-<lyxtabular version="3" rows="4" columns="2">
-<features>
-<column alignment="center" valignment="top" leftline="true" width="1in">
-<column alignment="left" valignment="top" leftline="true" rightline="true" width="3.5in">
-<row topline="true" bottomline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Standard
-
-\series bold
-Variable
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Standard
-
-\series bold
-Description
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Standard
-PYTHON
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Standard
-Python interpreter.
- This is useful if you have Python installed in a non-standard location,
- e.g.,
-\end_layout
-
-\begin_layout Standard
-
-\family typewriter
-\InsetSpace ~
-\InsetSpace ~
-./configure
-\backslash
-
-\end_layout
-
-\begin_layout Standard
-
-\family typewriter
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-PYTHON=/opt/python2.3/bin/python
-\family default
-
-\end_layout
-
-\begin_layout Standard
-By default,
-\family typewriter
-configure
-\family default
- will search for a suitable Python interpreter using your
-\family typewriter
-PATH
-\family default
- environment variable.
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Standard
-PETSC_DIR
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Standard
-PETSc installation/build directory.
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row topline="true" bottomline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Standard
-PETSC_ARCH
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Standard
-(optional) PETSc configuration tag.
- If not specified,
-\family typewriter
-configure
-\family default
- will pick a default configuration.
-\end_layout
-
-\end_inset
-</cell>
-</row>
-</lyxtabular>
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-\align left
-The configure script will automatically select the appropriate C++ and Fortran
- compilers using information from the PETSc configuration.
-\end_layout
-
-\begin_layout Quote
-
-\series bold
-\color red
-Warning:
-\series default
-\color none
- Manually specifying the C++ or Fortran compiler (using
-\family typewriter
-CXX
-\family default
- or
-\family typewriter
-FC
-\family default
-) is not recommended.
- Different Fortran compilers tend to be incompatible with one another.
- With C++, even different versions of the same compiler can be incompatible.
- Therefore, PyLith must be built using the same C++ and Fortran compilers
- used to configure and build PETSc.
- It is best to let PyLith's
-\family typewriter
-configure
-\family default
- script handle this automatically.
-\end_layout
-
-\begin_layout Section
-\begin_inset LatexCommand \label{sec:Pyre-Configuration}
-
-\end_inset
-
-Pyre Configuration
-\end_layout
-
-\begin_layout Standard
-Pyre is automatically downloaded by PyLith's configure script as a part
- of the Pythia package.
- Pythia is pure Python, so it requires no special configuration to build
- or install.
-\end_layout
-
-\begin_layout Standard
-However, Pyre manages the launching of parallel runs of PyLith under MPI,
- and the scheduling of PyLith jobs when used with a batch system.
- Therefore, before running PyLith, you must create a small configuration
- file which instructs Pyre how to launch and schedule PyLith runs on your
- system.
-\end_layout
-
-\begin_layout Subsection
-Pyre Configuration on a Personal Computer
-\end_layout
-
-\begin_layout Standard
-On a workstation or laptop, there is no job scheduler or communication network
- between compute nodes.
- In this scenario, Pyre is trivial to configure.
- Simply create the file
-\family typewriter
-~/.pyre/pylith3d/pylith3d.cfg
-\family default
- with the following contents:
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
-[pylith3d.launcher]
-\end_layout
-
-\begin_layout LyX-Code
-command = mpiexec -np ${nodes}
-\end_layout
-
-\begin_layout Standard
-The only trick is to specify the right command for your MPI implementation.
- Specify the
-\family typewriter
-mpiexec
-\family default
- command if you are using MPICH2 (which will be the case if you instructed
- PETSc to download MPICH for you).
-\end_layout
-
-\begin_layout Standard
-If you are using MPICH1, enter the following instead:
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
-[pylith3d.launcher]
-\end_layout
-
-\begin_layout LyX-Code
-command = mpirun -np ${nodes}
-\end_layout
-
-\begin_layout Standard
-See the documentation for your MPI implementation if you are unsure of the
- command to specify.
-\end_layout
-
-\begin_layout Subsection
-Pyre Configuration on a Cluster
-\end_layout
-
-\begin_layout Standard
-If you are installing PyLith on a cluster with a batch system, you can configure
- Pyre such that the
-\family typewriter
-pylith3dapp.py
-\family default
- command automatically submits jobs to the batch queue.
- Pyre contains support for the LSF, PBS, and Globus batch systems.
-\end_layout
-
-\begin_layout Standard
-The command to submit a batch job depends upon the particular batch system
- used.
- Further, the command used in a batch script to launch an MPI program varies
- from one cluster to the next.
- This command can vary between two clusters, even if the clusters use the
- same batch system! On some systems,
-\family typewriter
-mpirun
-\family default
- is invoked directly from the batch script.
- On others, a special wrapper is used instead.
-\end_layout
-
-\begin_layout Standard
-Properly configured, Pyre can handle job submissions automatically, insulating
- users from the details of the batch system and the site configuration.
- This feature has the most value when the system administrator installs
- a global Pyre configuration file on the cluster (under
-\family typewriter
-/etc/pythia-0.8
-\family default
-), for the benefit of all users and all Pyre-based applications.
-\end_layout
-
-\begin_layout Subsubsection
-\begin_inset LatexCommand \label{sub:Launchers-and-Schedulers}
-
-\end_inset
-
-Launchers and Schedulers
-\end_layout
-
-\begin_layout Standard
-If you have used one of the batch systems, you will know that the batch
- system requires you to write a script to launch a job.
- Fortunately, launching a parallel PyLith job is simplified by Pyre's
-\family typewriter
-launcher
-\family default
- and
-\family typewriter
-scheduler
-\family default
- facilities.
- Many properties associated with
-\family typewriter
-launcher
-\family default
- and
-\family typewriter
-scheduler
-\family default
- are pertinent to the cluster you are on, and are best customized in a configura
-tion file.
- Your personal PyLith configuration file (
-\family typewriter
-~/.pyre/pylith3d/pylith3d.cfg
-\family default
-) is suitable for this purpose.
- On a cluster, the ideal setup is to install a system-wide configuration
- file under
-\family typewriter
-/etc/pythia-0.8
-\family default
-, for the benefit of all users.
-\end_layout
-
-\begin_layout Standard
-Pyre's
-\family typewriter
-scheduler
-\family default
- facility is used to specify the type of batch system you are using (if
- any):
-\end_layout
-
-\begin_layout LyX-Code
-[pylith3d]
-\end_layout
-
-\begin_layout LyX-Code
-scheduler = lsf
-\end_layout
-
-\begin_layout Standard
-The valid values for
-\family typewriter
-scheduler
-\family default
- are
-\family typewriter
-lsf
-\family default
-,
-\family typewriter
-pbs
-\family default
-,
-\family typewriter
-globus
-\family default
-, and
-\family typewriter
-none
-\family default
-.
-\end_layout
-
-\begin_layout Standard
-Pyre's
-\family typewriter
-launcher
-\family default
- facility is used to specify which MPI implementation you are using:
-\end_layout
-
-\begin_layout LyX-Code
-[pylith3d]
-\end_layout
-
-\begin_layout LyX-Code
-launcher = mpich
-\end_layout
-
-\begin_layout Standard
-The valid values for
-\family typewriter
-launcher
-\family default
- include
-\family typewriter
-mpich
-\family default
- and
-\family typewriter
-lam-mpi
-\family default
-.
-\end_layout
-
-\begin_layout Standard
-You may find the
-\family typewriter
-dry
-\family default
- option useful while debugging the
-\family typewriter
-launcher
-\family default
- and
-\family typewriter
-scheduler
-\family default
- configuration.
- To debug the scheduler configuration, use the
-\family typewriter
---scheduler.dry
-\family default
- option:
-\end_layout
-
-\begin_layout LyX-Code
-pylith3dapp.py --scheduler.dry
-\end_layout
-
-\begin_layout Standard
-This option will cause PyLith to perform a ``dry run,'' dumping the batch
- script to the console, instead of actually submitting it for execution
- (the output is only meaningful if you're using a batch system).
- Likewise, to debug the launcher configuration, use the
-\family typewriter
---launcher.dry
-\family default
- option:
-\end_layout
-
-\begin_layout LyX-Code
-pylith3dapp.py --launcher.dry
-\end_layout
-
-\begin_layout Standard
-This option will cause PyLith to print the
-\family typewriter
-mpirun
-\family default
- command, instead of actually executing it.
- (If you're using a batch system, a job will be submitted for execution;
- when it runs, PyLith will simply print the
-\family typewriter
-mpirun
-\family default
- command, and the job will immediately terminate.)
-\end_layout
-
-\begin_layout Subsubsection
-Running without a Batch System
-\end_layout
-
-\begin_layout Standard
-On a cluster without a batch system, you need to explicitly specify the
- machines on which the job will run.
- Supposing the machines on your cluster are named n001, n002, \SpecialChar \ldots{}
-, etc., but
- you want to run the job on machines n001, n003, n004, and n005 (maybe n002
- is down for the moment).
- To run an example, create a file named
-\family typewriter
-mymachines.cfg
-\family default
- which specifies the machines to use:
-\end_layout
-
-\begin_layout LyX-Code
-[pylith3d.launcher]
-\end_layout
-
-\begin_layout LyX-Code
-nodegen = n%03d
-\end_layout
-
-\begin_layout LyX-Code
-nodelist = [1,3-5]
-\end_layout
-
-\begin_layout Standard
-The
-\family typewriter
-nodegen
-\family default
- property is a printf-style format string, used in conjunction with
-\family typewriter
-nodelist
-\family default
- to generate the list of machine names.
- The
-\family typewriter
-nodelist
-\family default
- property is a comma-separated list of machine names in square brackets.
-\end_layout
-
-\begin_layout Standard
-Now, invoke the following:
-\end_layout
-
-\begin_layout LyX-Code
-$ pylith3dapp.py example.cfg mymachines.cfg
-\end_layout
-
-\begin_layout Standard
-This strategy gives you the flexibility to create an assortment of
-\family typewriter
-.cfg
-\family default
- files (with one
-\family typewriter
-.cfg
-\family default
- file for each machine list) which can be easily paired with different parameter
- files.
-\end_layout
-
-\begin_layout Standard
-If your machine list does not change often, you may find it more convenient
- to specify default values for
-\family typewriter
-nodegen
-\family default
- and
-\family typewriter
-nodelist
-\family default
- in
-\family typewriter
-~/.pyre/pylith3d/pylith3d.cfg
-\family default
- (which is read automatically).
- Then, you can run any simulation with no additional arguments:
-\end_layout
-
-\begin_layout LyX-Code
-$ pylith3dapp.py example.cfg
-\end_layout
-
-\begin_layout Quote
-
-\color red
-Warning:
-\color none
-This assumes your machine list has enough nodes for the simulation in question.
-\end_layout
-
-\begin_layout Standard
-You will notice that a machine file
-\family typewriter
-mpirun.nodes
-\family default
- is generated.
- It will contain a list of the nodes where PyLith has run.
-\end_layout
-
-\begin_layout Subsubsection
-Using a Batch System
-\end_layout
-
-\begin_layout Standard
-The settings which are important when using a batch system are summarized
- in the sample configuration file which follows.
-\end_layout
-
-\begin_layout LyX-Code
-[pylith3d]
-\end_layout
-
-\begin_layout LyX-Code
-scheduler = lsf ; the type of the installed batch system
-\end_layout
-
-\begin_layout LyX-Code
-
-\end_layout
-
-\begin_layout LyX-Code
-[pylith3d.lsf]
-\end_layout
-
-\begin_layout LyX-Code
-bsub-options = [-a mpich_gm] ; special options for 'bsub'
-\end_layout
-
-\begin_layout LyX-Code
-
-\end_layout
-
-\begin_layout LyX-Code
-[pylith3d.launcher]
-\end_layout
-
-\begin_layout LyX-Code
-command = mpirun.lsf ; 'mpirun' command to use on our cluster
-\end_layout
-
-\begin_layout LyX-Code
-
-\end_layout
-
-\begin_layout LyX-Code
-[pylith3d.job]
-\end_layout
-
-\begin_layout LyX-Code
-queue = normal ; default queue for jobs
-\end_layout
-
-\begin_layout Standard
-These settings are usually placed in
-\family typewriter
-~/.pyre/pylith3d/pylith3d.cfg
-\family default
- or in a system-wide configuration file.
- They can be overridden on the command line, where one typically specifies
- the job name and the allotted time for the job:
-\end_layout
-
-\begin_layout LyX-Code
-$ pylith3dapp.py example1.cfg --job.queue=debug
-\backslash
-
-\end_layout
-
-\begin_layout LyX-Code
- --job.name=example1 --job.walltime=5*minute
-\backslash
-
-\end_layout
-
-\begin_layout LyX-Code
- --nodes=4
-\end_layout
-
-\begin_layout Standard
-The number of processors to allocate for the job is given using the
-\family typewriter
-nodes
-\family default
- parameter.
-\end_layout
-
-\begin_layout Standard
-For more information on configuring Pyre for your batch system, see CIG's
-
-\begin_inset LatexCommand \htmlurl[Pythia page]{www.geodynamics.org/cig/software/packages/cs/pythia}
-
-\end_inset
-
-.
-\end_layout
-
-\begin_layout Section
-\begin_inset LatexCommand \label{sec:Software-Repository}
-
-\end_inset
-
-Installing from the Software Repository
-\end_layout
-
-\begin_layout Standard
-The PyLith source code is available via the
-\begin_inset LatexCommand \htmlurl[Geodynamics Subversion Repository]{www.geodynamics.org/cig/software/Repository/}
-
-\end_inset
-
-.
- The PETSc source code is available via a Mercurial repository.
- This allows users to view the revision history of the code and check out
- the most recent development version of the software.
-\end_layout
-
-\begin_layout Quote
-
-\series bold
-\color red
-Warning:
-\series default
-\color none
- 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_layout
-
-\begin_layout Quote
-If you are content with the prepared source packages, you may skip this
- section.
-\end_layout
-
-\begin_layout Subsection
-Additional Tools You Will Need
-\end_layout
-
-\begin_layout Standard
-In addition to the usual system requirements, you will need a handful of
- additional development tools installed in order to work with the source
- from the software repositories.
-\end_layout
-
-\begin_layout Itemize
-Subversion
-\end_layout
-
-\begin_layout Itemize
-Mercurial (0.9 or later)
-\end_layout
-
-\begin_layout Itemize
-GNU Autotools (Autoconf, Automake, and Libtool)
-\end_layout
-
-\begin_layout Itemize
-Pyrex (v0.9.5.1 or later)
-\end_layout
-
-\begin_layout Subsubsection
-Subversion
-\end_layout
-
-\begin_layout Standard
-To check out the PyLith source, you must have a Subversion client installed.
- To check, type
-\family typewriter
-svn
-\family default
-; it should return a usage message.
-\end_layout
-
-\begin_layout LyX-Code
-$ svn
-\end_layout
-
-\begin_layout LyX-Code
-Type 'svn help' for usage.
-\end_layout
-
-\begin_layout Standard
-Many flavors of Unix have Subversion packages.
- You do not need anything but the basic Subversion client package.
-\end_layout
-
-\begin_layout Standard
-For more information on Subversion, visit the
-\begin_inset LatexCommand \htmlurl[Subversion website]{subversion.tigris.org}
-
-\end_inset
-
-.
-\end_layout
-
-\begin_layout Subsubsection
-Mercurial
-\end_layout
-
-\begin_layout Standard
-To check out the PETSc source, you must have Mercurial 0.9 or later installed.
- You will likely have to build Mercurial from source, but this is a very
- easy task that takes only a couple of minutes.
- To learn how to download and install Mercurial, visit
-\begin_inset LatexCommand \htmlurl[the Mercurial web site]{http://www.selenic.com/mercurial/}
-
-\end_inset
-
-.
-\end_layout
-
-\begin_layout Subsubsection
-Pyrex
-\end_layout
-
-\begin_layout Standard
-The software layer which connects PyLith's high-level Python code with its
- low-level Fortran code is written in a language called
-\emph on
-Pyrex
-\emph default
-.
- Pyrex is a Python-like language for writing native Python extension modules.
- To download Pyrex, visit
-\begin_inset LatexCommand \htmlurl[the Pyrex web site]{http://www.cosc.canterbury.ac.nz/greg.ewing/python/Pyrex/}
-
-\end_inset
-
-.
- After installing Pyrex, make sure the
-\family typewriter
-pyrexc
-\family default
- command is accessible via your
-\family typewriter
-PATH
-\family default
-.
-\end_layout
-
-\begin_layout Standard
-The Pyrex compiler generates C code as its output.
- Due to PETSc-related C/C++ linkage issues, the PyLith build system compiles
- this generated C code using the C++ compiler.
- For this reason and others, PyLith requires Pyrex v0.9.5.1 or later.
-\end_layout
-
-\begin_layout Subsubsection
-Autotools
-\end_layout
-
-\begin_layout Standard
-To generate the build system for PyLith, you must have the GNU tools Autoconf,
- Automake, and Libtool installed.
- To check, enter the following commands:
-\end_layout
-
-\begin_layout LyX-Code
-$ autoconf --version
-\end_layout
-
-\begin_layout LyX-Code
-$ automake --version
-\end_layout
-
-\begin_layout LyX-Code
-$ libtoolize --version
-\end_layout
-
-\begin_layout Standard
-For more information about these GNU tools, see the
-\begin_inset LatexCommand \htmlurl[GNU website]{www.gnu.org/software}
-
-\end_inset
-
-.
- The PyLith source package was created with Autoconf 2.61, Automake 1.9.6,
- and Libtool 1.5.22.
-\end_layout
-
-\begin_layout Subsection
-Downloading the PETSc Source using Mercurial
-\end_layout
-
-\begin_layout Standard
-Pull the source code from Argonne National Laboratory (ANL) and place the
- source tree in a suitable location.
- The steps below will create a
-\family typewriter
-petsc-dev
-\family default
- sub-directory in the current directory.
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
-$ hg clone http://mercurial.mcs.anl.gov/petsc/petsc-dev
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
-$ cd petsc-dev/python
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
-$ hg clone http://mercurial.mcs.anl.gov/petsc/BuildSystem BuildSystem
-\end_layout
-
-\begin_layout Standard
-In the future, you will likely want to update the PETSc source tree to include
- bug fixes, new features, etc.
- To update PETSc, perform the following commands:
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
-$ cd petsc-dev
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
-$ hg pull
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
-$ hg update
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
-$ cd python/BuildSystem
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
-$ hg pull
-\end_layout
-
-\begin_layout LyX-Code
-$ hg update
-\end_layout
-
-\begin_layout Subsection
-Downloading the PyLith Source using Subversion
-\end_layout
-
-\begin_layout Standard
-To check out the latest version of PyLith, use the
-\family typewriter
-svn checkout
-\family default
- command:
-\end_layout
-
-\begin_layout LyX-Code
-$ svn checkout
-\family typewriter
-http://geodynamics.org/svn/cig/short/3D/PyLith/branches/pylith-0.8
-\end_layout
-
-\begin_layout Standard
-This will create the local directory
-\family typewriter
-pylith-0.8
-\family default
- (if it doesn't already exist) and fill it with the latest PyLith source
- from the CIG software repository.
-\end_layout
-
-\begin_layout Standard
-The
-\family typewriter
-pylith-0.8
-\family default
- directory thus created is called a
-\emph on
-working copy
-\emph default
-.
- To merge the latest changes into an existing working copy, use the
-\family typewriter
-svn update
-\family default
- command:
-\end_layout
-
-\begin_layout LyX-Code
-$ cd pylith-0.8
-\end_layout
-
-\begin_layout LyX-Code
-$ svn update
-\end_layout
-
-\begin_layout Standard
-This will preserve any local changes you have made to your working copy.
-\end_layout
-
-\begin_layout Subsection
-Generating the GNU Build System
-\end_layout
-
-\begin_layout Standard
-Your working directory should now contain a fresh checkout of PyLith and
- PETSc:
-\end_layout
-
-\begin_layout LyX-Code
-$ ls
-\end_layout
-
-\begin_layout LyX-Code
-petsc-dev
-\end_layout
-
-\begin_layout LyX-Code
-pylith-0.8
-\end_layout
-
-\begin_layout LyX-Code
-$
-\end_layout
-
-\begin_layout Standard
-You are now ready to install PETSc as described in Section
-\begin_inset LatexCommand \ref{sec:Installing-PETSc}
-
-\end_inset
-
- earlier in this chapter.
-\end_layout
-
-\begin_layout Standard
-However, before you can run
-\family typewriter
-configure
-\family default
- or
-\family typewriter
-make
-\family default
- in the
-\family typewriter
-pylith-0.8
-\family default
- directory, you must generate the necessary files using the GNU tools.
- The easiest way to do this is to run
-\family typewriter
-autoreconf -if
-\family default
-:
-\end_layout
-
-\begin_layout LyX-Code
-$ cd pylith-0.8
-\end_layout
-
-\begin_layout LyX-Code
-$ autoreconf -if
-\end_layout
-
-\begin_layout LyX-Code
-$ ./configure
-\end_layout
-
-\begin_layout LyX-Code
-$ make
-\end_layout
-
-\begin_layout Standard
-The
-\family typewriter
-autoreconf
-\family default
- tool runs Autoconf to generate the
-\family typewriter
-configure
-\family default
- script from
-\family typewriter
-configure.ac
-\family default
-.
- It also runs Automake to generate
-\family typewriter
-Makefile.in
-\family default
- from
-\family typewriter
-Makefile.am
-\family default
- in each source directory.
- After running
-\family typewriter
-autoreconf
-\family default
-, install PyLith as described in Section
-\begin_inset LatexCommand \ref{sec:Installing-PyLith}
-
-\end_inset
-
- earlier in this chapter.
-\end_layout
-
-\begin_layout LyX-Code
-
-\end_layout
-
-\end_body
-\end_document
+#LyX 1.4.3 created this file. For more info see http://www.lyx.org/
+\lyxformat 245
+\begin_document
+\begin_header
+\textclass book
+\begin_preamble
+
+\end_preamble
+\language english
+\inputencoding latin1
+\fontscheme default
+\graphics default
+\paperfontsize default
+\spacing single
+\papersize default
+\use_geometry true
+\use_amsmath 1
+\cite_engine basic
+\use_bibtopic false
+\paperorientation portrait
+\leftmargin 1in
+\topmargin 1in
+\rightmargin 1in
+\bottommargin 2in
+\secnumdepth 3
+\tocdepth 3
+\paragraph_separation indent
+\defskip medskip
+\quotes_language english
+\papercolumns 1
+\papersides 2
+\paperpagestyle default
+\tracking_changes false
+\output_changes false
+\end_header
+
+\begin_body
+
+\begin_layout Chapter
+\begin_inset LatexCommand \label{cha:Installation-and-Getting}
+
+\end_inset
+
+Installation and Getting Help
+\end_layout
+
+\begin_layout Section
+Installation of Binary Executable
+\end_layout
+
+\begin_layout Standard
+[ADD STUFF HERE]
+\end_layout
+
+\begin_layout Section
+Installation from Source
+\end_layout
+
+\begin_layout Standard
+PyLith 1.0 depends on a number of other packages.
+ This complicates building the software from the source code.
+ In many cases some of the packages required by PyLith are available as
+ binary packages.
+ On the one hand, using these packages removes the burden of configuring,
+ building, and installing these packages, but it can come with its own host
+ of complications if a consistent compiler and configuration settings are
+ not used across all of the packages on which PyLith depends.
+ This is usually not an issue with Linux distributions, such as Fedora,
+ Ubuntu, and Debian that have good quality control; it can be an issue with
+ Darwin package managers, such as Fink, where there is limited enforcement
+ of consistency across pacakges.
+ Nevertheless, PyLith can be built on most systems provided the instructions
+ are followed carefully.
+ PyLith is developed and tested on Linux and Mac OS X.
+\end_layout
+
+\begin_layout Subsection
+Introduction
+\end_layout
+
+\begin_layout Standard
+Installing PyLith is a three-stage process:
+\end_layout
+
+\begin_layout Enumerate
+Install the development version of PETSc (Section
+\begin_inset LatexCommand \vref{sec:Installing-PETSc}
+
+\end_inset
+
+)
+\end_layout
+
+\begin_layout Enumerate
+Install PyLith (Section
+\begin_inset LatexCommand \vref{sec:Installing-PyLith}
+
+\end_inset
+
+)
+\end_layout
+
+\begin_layout Enumerate
+Configure Pyre to launch parallel runs of PyLith (Section
+\begin_inset LatexCommand \vref{sec:Pyre-Configuration}
+
+\end_inset
+
+)
+\end_layout
+
+\begin_layout Standard
+Each stage is substantially faster and easier than the one before it.
+ In fact, after successfully installing PETSc, you are close to being done.
+ So review Section
+\begin_inset LatexCommand \ref{sec:System-Requirements}
+
+\end_inset
+
+ to make sure you have the required tools at hand; and then proceed fearlessly,
+ dear reader, to Section
+\begin_inset LatexCommand \ref{sec:Installing-PETSc}
+
+\end_inset
+
+.
+\end_layout
+
+\begin_layout Standard
+Advanced users and software developers may be interested in downloading
+ the latest PyLith and PETSc source code directly from the source code repositor
+ies, instead of using the prepared source packages; see Section
+\begin_inset LatexCommand \ref{sec:Software-Repository}
+
+\end_inset
+
+ later in this chapter.
+\end_layout
+
+\begin_layout Section
+Getting Help
+\end_layout
+
+\begin_layout Standard
+Help is available via the CIG Short-Term Crustal Dynamics Mailing List and
+ CIG's issue tracking system.
+ The mailing list, ,
+\begin_inset LatexCommand \htmlurl[cig-short at geodynamics.org]{http://www.geodynamics.org/cig/lists}
+
+\end_inset
+
+, is dedicated to CIG issues associated with short-term crustal dynamics,
+ including the use of PyLith.
+ CIG uses
+\family typewriter
+Roundup
+\family default
+ for bug tracking.
+ If you find a bug in PyLith, please submit a bug report to the
+\begin_inset LatexCommand \htmlurl[CIG Roundup System]{www.geodynamics.org/roundup/}
+
+\end_inset
+
+.
+ 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
+\family sans
+Create New
+\family default
+ under
+\family sans
+Issues
+\family default
+.
+\end_layout
+
+\begin_layout Section
+\begin_inset LatexCommand \label{sec:System-Requirements}
+
+\end_inset
+
+System Requirements
+\end_layout
+
+\begin_layout Standard
+Installation of PyLith requires the following:
+\end_layout
+
+\begin_layout Itemize
+A C++ compiler
+\end_layout
+
+\begin_layout Itemize
+Python 2.3 or greater (Python 2.4 or greater is required on 64-bit machines)
+\end_layout
+
+\begin_layout Itemize
+The development version of PETSc
+\end_layout
+
+\begin_layout Subsection
+C++ Compiler
+\end_layout
+
+\begin_layout Standard
+A C++ compiler is required for building PETSc's Sieve component and the
+ PyLith components that interface with Sieve.
+ The C++ compiler is also used to compile the layer which connects the high-leve
+l Python code with the low-level Fortran code.
+\end_layout
+
+\begin_layout Standard
+On Unix systems, there is a high likelihood that a usable C++ compiler is
+ already installed.
+ Check with your system administrator if you are unsure of the name of the
+ C++ compiler command.
+\end_layout
+
+\begin_layout Standard
+On Linux, the standard C++ compiler is
+\family typewriter
+g++
+\family default
+.
+ If the
+\family typewriter
+g++
+\family default
+ command is not available, install GCC using the package manager for your
+ distribution.
+\end_layout
+
+\begin_layout Standard
+The Mac OS X version of GCC is included in a software development suite
+ called Xcode.
+ Xcode is available as a free download at the
+\begin_inset LatexCommand \htmlurl[Apple Developer Connection]{developer.apple.com}
+
+\end_inset
+
+.
+ (Note that Xcode does not include a Fortran compiler.)
+\end_layout
+
+\begin_layout Subsection
+Python
+\end_layout
+
+\begin_layout Standard
+PyLith's high-level user interface code is written in Python, utilizing
+ the Pyre framework.
+ Pyre is included in the Python package known as Pythia.
+ PyLith requires Pythia v0.8.1.3 or later, but you need not install Pythia
+ because PyLith's
+\family typewriter
+configure
+\family default
+ script automatically downloads Pythia directly from CIG.
+\end_layout
+
+\begin_layout Standard
+Pythia (and therefore PyLith) requires Python 2.3 or later.
+\end_layout
+
+\begin_layout Quote
+
+\color red
+Warning:
+\color none
+ On 64-bit machines, Python 2.4 or later is required.
+ Python 2.3 contains a bug which prevents installation on 64-bit hardware.
+\end_layout
+
+\begin_layout Standard
+Your system may already have a suitable Python interpreter installed.
+ To check, type the `
+\family typewriter
+python
+\family default
+' command:
+\end_layout
+
+\begin_layout LyX-Code
+$ python -V
+\end_layout
+
+\begin_layout LyX-Code
+Python 2.3.4
+\end_layout
+
+\begin_layout Standard
+Mac OS X 10.3 and later ships with a suitable version of Python preinstalled.
+ If you're using an older version of Mac OS X, or for more information in
+ general, see
+\begin_inset LatexCommand \htmlurl[Python on the Mac]{www.python.org/download/mac}
+
+\end_inset
+
+ at the Python web site.
+\end_layout
+
+\begin_layout Standard
+On Linux, simply install the binary system package available for your distributi
+on.
+ Be sure to select the Python development package (typically called
+\family typewriter
+python-dev
+\family default
+) in addition to the core Python package -- even if you don't plan on doing
+ any Python software development.
+ The development package contains the Python
+\family typewriter
+include
+\family default
+ files, which are necessary for building PyLith.
+\end_layout
+
+\begin_layout Standard
+If you are working on a cluster and
+\family typewriter
+python
+\family default
+ is too old, try poking around a little.
+ Sometimes multiple versions of Python are installed on the same system:
+\end_layout
+
+\begin_layout LyX-Code
+$ python -V
+\end_layout
+
+\begin_layout LyX-Code
+Python 2.2.3
+\end_layout
+
+\begin_layout LyX-Code
+$ which python
+\end_layout
+
+\begin_layout LyX-Code
+/usr/bin/python
+\end_layout
+
+\begin_layout LyX-Code
+$ ls /usr/bin/python*
+\end_layout
+
+\begin_layout LyX-Code
+/usr/bin/python /usr/bin/python2 /usr/bin/python2.2
+\end_layout
+
+\begin_layout LyX-Code
+/usr/bin/python24 /usr/bin/python2.4
+\end_layout
+
+\begin_layout LyX-Code
+$
+\end_layout
+
+\begin_layout Standard
+In the above scenario, it is useful to create an alias to the newer Python:
+\end_layout
+
+\begin_layout LyX-Code
+$ cd ~/bin
+\end_layout
+
+\begin_layout LyX-Code
+$ ln -s /usr/bin/python2.4 python
+\end_layout
+
+\begin_layout LyX-Code
+$ cd
+\end_layout
+
+\begin_layout LyX-Code
+$ hash -r
+\end_layout
+
+\begin_layout LyX-Code
+$ which python
+\end_layout
+
+\begin_layout LyX-Code
+~/bin/python
+\end_layout
+
+\begin_layout LyX-Code
+$ python -V
+\end_layout
+
+\begin_layout LyX-Code
+Python 2.4.1
+\end_layout
+
+\begin_layout LyX-Code
+$
+\end_layout
+
+\begin_layout Standard
+If absolutely necessary, one can easily build Python from source using a
+ C compiler.
+ You can download Python from the
+\begin_inset LatexCommand \htmlurl[Python website]{www.python.org}
+
+\end_inset
+
+.
+
+\end_layout
+
+\begin_layout Subsection
+PETSc
+\end_layout
+
+\begin_layout Standard
+PyLith requires PETSc -- including PETSc's new Sieve component.
+ Sieve is still under development; as of this writing, Sieve is only available
+ in the development version of PETSc.
+\end_layout
+
+\begin_layout Standard
+PETSc itself depends upon several other sofware packages.
+ Fortunately, PETSc's configuration script can automatically download and
+ build these software packages for you.
+\end_layout
+
+\begin_layout Standard
+For general information about the development version of PETSc, visit
+\begin_inset LatexCommand \htmlurl[the PETSc Developers Site]{http://www-unix.mcs.anl.gov/petsc/petsc-as/developers/}
+
+\end_inset
+
+.
+\end_layout
+
+\begin_layout Section
+\begin_inset LatexCommand \label{sec:Installing-PETSc}
+
+\end_inset
+
+Installing PETSc
+\end_layout
+
+\begin_layout Standard
+To install PETSc, you will download and unpack the
+\family typewriter
+petsc-dev
+\family default
+ tarball, run a Python configure script (
+\family typewriter
+config/configure.py
+\family default
+), set a pair of environment variables, and finally build PETSc from source
+ by running
+\family typewriter
+make
+\family default
+.
+\end_layout
+
+\begin_layout Quote
+
+\series bold
+TIP:
+\series default
+If you run into problems configuring or building PETSc, send
+\emph on
+both
+\family typewriter
+\emph default
+ configure.log
+\family default
+ and
+\family typewriter
+make_log_
+\emph on
+$PETSC_ARCH
+\family default
+\emph default
+ to
+\begin_inset LatexCommand \url[PETSc Maintenance Mailing List]{petsc-maint at mcs.anl.gov}
+
+\end_inset
+
+.
+\end_layout
+
+\begin_layout Standard
+For detailed information on installing PETSc, see
+\begin_inset LatexCommand \htmlurl[the PETSc Installation Docs]{http://www-unix.mcs.anl.gov/petsc/petsc-as/documentation/installation.html}
+
+\end_inset
+
+.
+\end_layout
+
+\begin_layout Subsection
+Downloading and Unpacking
+\family typewriter
+petsc-dev
+\end_layout
+
+\begin_layout Standard
+The development version of PETSc is called
+\family typewriter
+petsc-dev
+\family default
+.
+ Download the nightly tarball snapshot of
+\family typewriter
+petsc-dev
+\family default
+ from the
+\begin_inset LatexCommand \htmlurl[the PETSc Developers Site]{http://www-unix.mcs.anl.gov/petsc/petsc-as/developers/}
+
+\end_inset
+
+.
+ Unpack it using the
+\family typewriter
+tar
+\family default
+ command:
+\end_layout
+
+\begin_layout LyX-Code
+$ tar xzf petsc-dev.tar.gz
+\end_layout
+
+\begin_layout Standard
+If you don't have GNU Tar, try the following command instead:
+\end_layout
+
+\begin_layout LyX-Code
+$ gunzip -c petsc-dev.tar.gz | tar xf -
+\end_layout
+
+\begin_layout Standard
+After unpacking, a directory called
+\family typewriter
+petsc-dev
+\family default
+ will be visible in your working directory.
+\end_layout
+
+\begin_layout Subsection
+PETSc Configuration
+\end_layout
+
+\begin_layout Standard
+Navigate to the directory containing the PETSc source:
+\end_layout
+
+\begin_layout Quote
+
+\family typewriter
+$ cd petsc-dev
+\end_layout
+
+\begin_layout Standard
+To configure PETSc, run
+\family typewriter
+./config/configure.py
+\family default
+ with the appropriate arguments to configure PETSc for your system.
+ At a minimum, configuring PETSc for use with PyLith requires the following
+ arguments:
+\end_layout
+
+\begin_layout LyX-Code
+
+\family typewriter
+--with-clanguage=c++
+\end_layout
+
+\begin_layout LyX-Code
+
+\family typewriter
+--with-boost=1
+\end_layout
+
+\begin_layout LyX-Code
+--with-chaco=1
+\end_layout
+
+\begin_layout LyX-Code
+
+\family typewriter
+--with-sieve=1
+\end_layout
+
+\begin_layout Standard
+You will need to specify additional options; the specific set of options
+ you will use depends upon the libraries and compilers you have available.
+ See the examples below.
+\end_layout
+
+\begin_layout Quote
+
+\series bold
+TIP:
+\series default
+ Run
+\family typewriter
+./config/configure.py --help
+\family default
+ to see the long list of all possible options.
+\end_layout
+
+\begin_layout Standard
+Building PETSc with Sieve requires the following external libraries:
+\end_layout
+
+\begin_layout Itemize
+an MPI library
+\end_layout
+
+\begin_layout Itemize
+BLAS/LAPACK
+\end_layout
+
+\begin_layout Itemize
+Boost
+\end_layout
+
+\begin_layout Itemize
+Chaco
+\end_layout
+
+\begin_layout Standard
+You can instruct PETSc to download and install any or all of these libraries
+ for you.
+\end_layout
+
+\begin_layout Standard
+If you have an MPI implementation installed on your workstation, you can
+ use it, or let PETSc download and install one for you.
+ If you are installing on a cluster, you should configure PETSc to use an
+ existing MPI library installed by the system administrators.
+\end_layout
+
+\begin_layout Standard
+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 OS X).
+\end_layout
+
+\begin_layout Standard
+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 to build PETSc using the GNU compilers, be sure to let
+ PETSc know which compilers you want to use instead.
+\end_layout
+
+\begin_layout Subsubsection
+PETSc Configuration Examples
+\end_layout
+
+\begin_layout Standard
+In our first example, we configure PETSc on a Linux workstation.
+ BLAS and LAPACK are preinstalled under
+\family typewriter
+/usr/lib
+\family default
+; PETSc finds these system libraries automatically.
+ We happen to have MPICH already installed;
+\family typewriter
+mpicc
+\family default
+ and other related MPI commands are accessible via our
+\family typewriter
+PATH
+\family default
+, so PETSc finds our MPICH installation automatically.
+ However, we don't have Boost or Chaco installed, so we instruct PETSc to
+ download these packages for us.
+\end_layout
+
+\begin_layout LyX-Code
+
+\family typewriter
+$ ls -1 /usr/lib/libblas.so /usr/lib/liblapack.so
+\end_layout
+
+\begin_layout LyX-Code
+
+\family typewriter
+/usr/lib/libblas.so
+\end_layout
+
+\begin_layout LyX-Code
+
+\family typewriter
+/usr/lib/liblapack.so
+\end_layout
+
+\begin_layout LyX-Code
+
+\family typewriter
+$ which mpicc
+\end_layout
+
+\begin_layout LyX-Code
+
+\family typewriter
+/opt/mpich/bin/mpicc
+\end_layout
+
+\begin_layout LyX-Code
+
+\family typewriter
+$
+\end_layout
+
+\begin_layout LyX-Code
+
+\family typewriter
+$ ./config/configure.py
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+
+\family typewriter
+ --with-sieve=1
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+
+\family typewriter
+ --with-clanguage=C++
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+
+\family typewriter
+ --with-boost=1 --download-boost=1
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+
+\family typewriter
+ --with-chaco=1 --download-chaco=1
+\end_layout
+
+\begin_layout Standard
+In our next example, we configure PETSc on a Mac OS X machine.
+ We have installed Apple's Xcode and the G95 Fortran compiler.
+ However, we don't have anything else preinstalled, so we instruct PETSc
+ to download almost everything else, including MPICH.
+ Intentionally, we don't specify anything about BLAS/LAPACK: PETSc automatically
+ finds vecLib, which is built-in to Mac OS X.
+\end_layout
+
+\begin_layout LyX-Code
+$ ./config/configure.py
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+ --with-sieve=1
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+ --with-clanguage=C++
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+ --with-fc=g95
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+ --with-boost=1 --download-boost=1
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+ --with-chaco=1 --download-chaco=1
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+ --with-mpi=1 --download-mpich=1
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+ --with-x=0
+\end_layout
+
+\begin_layout Standard
+In our final example, we configure PETSc on a 64-bit Linux cluster.
+ We use an existing MPI implementation installed by the system administrators.
+ BLAS/LAPACK is missing, so we instruct PETSc to download it, in addition
+ to Boost and Chaco.
+\end_layout
+
+\begin_layout LyX-Code
+
+\family typewriter
+$ ./config/configure.py
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+
+\family typewriter
+ --with-sieve=1
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+
+\family typewriter
+ --with-clanguage=C++
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+
+\family typewriter
+ --with-mpi-dir=/opt/mpich/myrinet_mx2g/intel
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+
+\family typewriter
+ --download-f-blas-lapack=1
+\family default
+
+\family typewriter
+
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+
+\family typewriter
+ --with-boost=1 --download-boost=1
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+
+\family typewriter
+ --with-chaco=1 --download-chaco=1
+\end_layout
+
+\begin_layout Subsubsection
+Running
+\family typewriter
+configure.py
+\end_layout
+
+\begin_layout Standard
+After several minutes, the configure script should finish and display the
+ PETSc settings.
+ Check to make sure these match your expectations before continuing.
+\end_layout
+
+\begin_layout Subsection
+Setting PETSC Environment Variables
+\end_layout
+
+\begin_layout Standard
+Before building PETSc, set the
+\family typewriter
+PETSC_DIR
+\family default
+ and
+\family typewriter
+PETSC_ARCH
+\family default
+ environment variables.
+ Upon completion, the configure script displays instructions for setting
+ these two variables:
+\end_layout
+
+\begin_layout LyX-Code
+
+\family typewriter
+**
+\end_layout
+
+\begin_layout LyX-Code
+
+\family typewriter
+** Before running "make" your PETSC_ARCH must be specified with:
+\end_layout
+
+\begin_layout LyX-Code
+
+\family typewriter
+** ** setenv PETSC_ARCH linux-gnu-cxx-debug (csh/tcsh)
+\end_layout
+
+\begin_layout LyX-Code
+
+\family typewriter
+** ** PETSC_ARCH=linux-gnu-cxx-debug; export PETSC_ARCH (sh/bash)
+\end_layout
+
+\begin_layout LyX-Code
+
+\family typewriter
+**
+\end_layout
+
+\begin_layout LyX-Code
+
+\family typewriter
+**
+\end_layout
+
+\begin_layout LyX-Code
+
+\family typewriter
+** Before running "make" your PETSC_DIR must be specified with:
+\end_layout
+
+\begin_layout LyX-Code
+
+\family typewriter
+** ** setenv PETSC_DIR /opt/petsc-dev (csh/tcsh)
+\end_layout
+
+\begin_layout LyX-Code
+
+\family typewriter
+** ** PETSC_DIR=/opt/petsc-dev; export PETSC_DIR (sh/bash)
+\end_layout
+
+\begin_layout LyX-Code
+
+\family typewriter
+**
+\end_layout
+
+\begin_layout LyX-Code
+
+\family typewriter
+**
+\end_layout
+
+\begin_layout Standard
+
+\family typewriter
+PETSC_ARCH
+\family default
+ is a tag identifying this configuration of PETSc.
+
+\family typewriter
+PETSC_DIR
+\family default
+ is set to the full path of the top-level directory in the PETSc source
+ tree (the
+\family typewriter
+petsc-dev
+\family default
+ directory).
+ You will want to set these environment variables in your
+\family typewriter
+.bashrc
+\family default
+,
+\family typewriter
+.cshrc
+\family default
+, or similar file.
+\end_layout
+
+\begin_layout Subsection
+Building PETSc
+\end_layout
+
+\begin_layout Standard
+After setting
+\family typewriter
+PETSC_DIR
+\family default
+ and
+\family typewriter
+PETSC_ARCH
+\family default
+, run
+\family typewriter
+make
+\family default
+ to build PETSc:
+\end_layout
+
+\begin_layout Quote
+
+\family typewriter
+$ make
+\end_layout
+
+\begin_layout Subsection
+Testing the PETSc Installation
+\end_layout
+
+\begin_layout Standard
+Optionally, you may test your PETSc installation:
+\end_layout
+
+\begin_layout Quote
+
+\family typewriter
+$ make test
+\end_layout
+
+\begin_layout Standard
+One of the tests will attempt to display some X windows.
+ If X windows is not available from the shell in which you run
+\family typewriter
+make test
+\family default
+, then that test will fail.
+\end_layout
+
+\begin_layout Section
+\begin_inset LatexCommand \label{sec:Installing-PyLith}
+
+\end_inset
+
+Installing PyLith
+\end_layout
+
+\begin_layout Standard
+To install PyLith, you follow the procedure that is commonly used with other
+ open source software packages.
+ First, download the source package available at the
+\begin_inset LatexCommand \htmlurl[Geodynamics Software Packages web page]{www.geodynamics.org/cig/software/packages}
+
+\end_inset
+
+.
+ After unpacking the source, you run a prepackaged shell script to configure
+ PyLith for your system.
+ Finally, you use the
+\family typewriter
+make
+\family default
+ utility to build and install PyLith from source.
+
+\end_layout
+
+\begin_layout Subsection
+Downloading and Unpacking the PyLith Source
+\end_layout
+
+\begin_layout Standard
+Download PyLith from the
+\begin_inset LatexCommand \htmlurl[Geodynamics website]{www.geodynamics.org}
+
+\end_inset
+
+.
+ Click the
+\family sans
+software
+\family default
+ tab at the top of the page.
+ Then click
+\family sans
+Software Packages
+\family default
+, then
+\family sans
+Short-Term Crustal Dynamics
+\family default
+.
+ Once you click the PyLith link, download the source archive and unpack
+ it using the
+\family typewriter
+tar
+\family default
+ command:
+\end_layout
+
+\begin_layout LyX-Code
+$ tar xzf pylith3d-0.8.2.tar.gz
+\end_layout
+
+\begin_layout Standard
+If you don't have GNU Tar, try the following command instead:
+\end_layout
+
+\begin_layout LyX-Code
+$ gunzip -c pylith3d-0.8.2.tar.gz | tar xf -
+\end_layout
+
+\begin_layout Subsection
+PyLith Installation Procedure
+\end_layout
+
+\begin_layout Quote
+
+\series bold
+TIP:
+\series default
+ If you run into problems configuring or building PyLith, send both the
+
+\family typewriter
+config.log
+\family default
+ and
+\family typewriter
+make.log
+\family default
+ files to the
+\begin_inset LatexCommand \url[CIG Short-Term Crustal Dynamics Mailing List]{cig-short at geodynamics.org}
+
+\end_inset
+
+.
+ To create the
+\family typewriter
+make.log
+\family default
+ file, redirect the output of
+\family typewriter
+make
+\family default
+ to a file:
+\family typewriter
+make
+\begin_inset Formula $>$
+\end_inset
+
+ make.log
+\family default
+.
+
+\end_layout
+
+\begin_layout Standard
+After unpacking the source, use the following procedure to install PyLith:
+\end_layout
+
+\begin_layout Enumerate
+Navigate (i.e.,
+\family typewriter
+cd
+\family default
+) to the directory containing the PyLith source
+\family typewriter
+.
+\newline
+
+\newline
+$ cd pylith3d-0.8.2
+\end_layout
+
+\begin_layout Enumerate
+Type .
+\family typewriter
+/configure
+\family default
+ to configure the package for your system
+\family typewriter
+.
+\newline
+
+\newline
+$ ./configure
+\end_layout
+
+\begin_layout Enumerate
+Type
+\family typewriter
+make
+\family default
+ to build the package.
+\family typewriter
+
+\newline
+
+\newline
+$ make
+\end_layout
+
+\begin_layout Standard
+If you are content to run PyLith from the build directory, then you are
+ done.
+ Upon successful completion, the
+\family typewriter
+make
+\family default
+ command creates a script called
+\family typewriter
+pylith3dapp.py
+\family default
+ in the
+\family typewriter
+pylith3d
+\family default
+ subdirectory; this is the script you will use to run PyLith.
+ You may wish to add the
+\family typewriter
+pylith3d
+\family default
+ directory to your
+\family typewriter
+PATH
+\family default
+.
+\end_layout
+
+\begin_layout Standard
+For more details about
+\family typewriter
+configure
+\family default
+, see Section
+\begin_inset LatexCommand \ref{sec:Configuration}
+
+\end_inset
+
+ below.
+\end_layout
+
+\begin_layout Subsubsection
+Installing PyLith to a Secondary Location
+\end_layout
+
+\begin_layout Standard
+Optionally, after building PyLith, you can install it in a secondary location
+ using the
+\family typewriter
+make install
+\family default
+ command.
+\end_layout
+
+\begin_layout Quotation
+
+\series bold
+Note:
+\series default
+ The following is not recommended if you plan on modifying the PyLith source.
+\end_layout
+
+\begin_layout Standard
+By default, PyLith is configured to install under
+\family typewriter
+/usr/local
+\family default
+, which requires that you become
+\family typewriter
+root
+\family default
+ before issuing the
+\family typewriter
+make install
+\family default
+ command.
+\end_layout
+
+\begin_layout LyX-Code
+
+\family typewriter
+$ su
+\end_layout
+
+\begin_layout LyX-Code
+
+\family typewriter
+Password:
+\end_layout
+
+\begin_layout LyX-Code
+
+\family typewriter
+# make install
+\end_layout
+
+\begin_layout Standard
+To install as an ordinary user instead of
+\family typewriter
+root
+\family default
+, give
+\family typewriter
+configure
+\family default
+ the
+\family typewriter
+--prefix
+\family default
+ option, specifying a directory to which you have write access:
+\end_layout
+
+\begin_layout LyX-Code
+$ cd
+\family typewriter
+pylith3d-0.8.2
+\end_layout
+
+\begin_layout LyX-Code
+$ ./configure --prefix=$HOME/cig
+\end_layout
+
+\begin_layout LyX-Code
+$ make
+\end_layout
+
+\begin_layout LyX-Code
+$ make install
+\end_layout
+
+\begin_layout Standard
+The above commands will install PyLith under
+\family typewriter
+$HOME/cig
+\family default
+.
+ Afterwards, you may wish to add
+\family typewriter
+PREFIX/bin
+\family default
+ (
+\family typewriter
+$HOME/cig/bin
+\family default
+, in this example) to your
+\family typewriter
+PATH
+\family default
+.
+\end_layout
+
+\begin_layout Standard
+After running
+\family typewriter
+make install
+\family default
+, you may (if desired) run
+\family typewriter
+make clean
+\family default
+ in the build directory to save disk space.
+ You are also free to delete the source/build directory altogether.
+ (Note that
+\family typewriter
+make install
+\family default
+ installs the examples under
+\family typewriter
+PREFIX/share/pylith3d/examples
+\family default
+.)
+\end_layout
+
+\begin_layout Subsection
+\begin_inset LatexCommand \label{sec:Configuration}
+
+\end_inset
+
+PyLith Configuration
+\end_layout
+
+\begin_layout Standard
+The
+\family typewriter
+configure
+\family default
+ script checks for various system features.
+ As it runs, it prints messages informing you of which features it is checking
+ for.
+ Upon successful completion, it generates a
+\family typewriter
+Makefile
+\family default
+ in each source directory of the package.
+ It also generates a
+\family typewriter
+config.h
+\family default
+ header file, which contains system-dependent definitions.
+
+\end_layout
+
+\begin_layout Standard
+The
+\family typewriter
+configure
+\family default
+ script will attempt to guess the correct values of various installation
+ parameters.
+ In the event that the default values used by
+\family typewriter
+configure
+\family default
+ are incorrect for your system, or
+\family typewriter
+configure
+\family default
+ is unable to guess the value of a certain parameter, you may have to specify
+ the correct value by hand.
+\end_layout
+
+\begin_layout Quote
+
+\series bold
+Important:
+\series default
+ If the
+\family typewriter
+configure
+\family default
+ script fails, and you don't know what went wrong, examine the log file
+
+\family typewriter
+config.log
+\family default
+.
+ This file contains a detailed transcript of all the checks
+\family typewriter
+configure
+\family default
+ performed.
+ Most importantly, it includes the error output (if any) from your compiler.
+ When seeking help for
+\family typewriter
+configure
+\family default
+ failures on the
+\begin_inset LatexCommand \url[CIG Short-Term Crustal Dynamics Mailing List]{cig-short at geodynamics.org}
+
+\end_inset
+
+, please send
+\family typewriter
+config.log
+\family default
+ as an attachment.
+\end_layout
+
+\begin_layout Standard
+The
+\family typewriter
+configure
+\family default
+ script will automatically check for needed Python dependencies, including
+ the Pythia package (which includes the Pyre framework).
+ If necessary,
+\family typewriter
+configure
+\family default
+ will download missing Python packages from the Internet.
+\end_layout
+
+\begin_layout Standard
+PyLith v0.8.2 requires Pythia v0.8.1.3 or later, which
+\family typewriter
+configure
+\family default
+ downloads directly from CIG.
+ (Pythia v0.8.1.x is distinct from Pythia v0.8, which you may have installed
+ previously.) Pythia v0.8.1.x is pure Python, and resides in a file or directory
+ with the extension
+\family typewriter
+.egg
+\family default
+ (e.g.,
+\family typewriter
+pythia-0.8.1.3.egg
+\family default
+).
+ The
+\family typewriter
+configure
+\family default
+ script may download other
+\family typewriter
+.egg
+\family default
+ packages, in addition to Pythia.
+ These are Python packages which are required (either directly or indirectly)
+ by PyLith.
+\end_layout
+
+\begin_layout Subsubsection
+Configure Usage
+\end_layout
+
+\begin_layout Standard
+For a detailed list of
+\family typewriter
+configure
+\family default
+ variables and options, give
+\family typewriter
+configure
+\family default
+ the
+\family typewriter
+--help
+\family default
+ option:
+\end_layout
+
+\begin_layout LyX-Code
+$ ./configure --help
+\end_layout
+
+\begin_layout Standard
+The following is a summary of the variables and options that are important
+ when installing PyLith.
+
+\end_layout
+
+\begin_layout Subsubsection
+Environment Variables
+\end_layout
+
+\begin_layout Standard
+Environment variables may be specified as arguments to
+\family typewriter
+configure
+\family default
+, e.g.,
+\end_layout
+
+\begin_layout LyX-Code
+$ ./configure PYTHON=/usr/bin/python2.4
+\end_layout
+
+\begin_layout Standard
+\noindent
+\align center
+\begin_inset Float table
+placement H
+wide false
+sideways false
+status open
+
+\begin_layout Standard
+\noindent
+\align center
+\begin_inset Tabular
+<lyxtabular version="3" rows="4" columns="2">
+<features>
+<column alignment="center" valignment="top" leftline="true" width="1in">
+<column alignment="left" valignment="top" leftline="true" rightline="true" width="3.5in">
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\series bold
+Variable
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+
+\series bold
+Description
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+PYTHON
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+Python interpreter.
+ This is useful if you have Python installed in a non-standard location,
+ e.g.,
+\end_layout
+
+\begin_layout Standard
+
+\family typewriter
+\InsetSpace ~
+\InsetSpace ~
+./configure
+\backslash
+
+\end_layout
+
+\begin_layout Standard
+
+\family typewriter
+\InsetSpace ~
+\InsetSpace ~
+\InsetSpace ~
+\InsetSpace ~
+\InsetSpace ~
+\InsetSpace ~
+PYTHON=/opt/python2.3/bin/python
+\family default
+
+\end_layout
+
+\begin_layout Standard
+By default,
+\family typewriter
+configure
+\family default
+ will search for a suitable Python interpreter using your
+\family typewriter
+PATH
+\family default
+ environment variable.
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+PETSC_DIR
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+PETSc installation/build directory.
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+PETSC_ARCH
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Standard
+(optional) PETSc configuration tag.
+ If not specified,
+\family typewriter
+configure
+\family default
+ will pick a default configuration.
+\end_layout
+
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+\align left
+The configure script will automatically select the appropriate C++ and Fortran
+ compilers using information from the PETSc configuration.
+\end_layout
+
+\begin_layout Quote
+
+\series bold
+\color red
+Warning:
+\series default
+\color none
+ Manually specifying the C++ or Fortran compiler (using
+\family typewriter
+CXX
+\family default
+ or
+\family typewriter
+FC
+\family default
+) is not recommended.
+ Different Fortran compilers tend to be incompatible with one another.
+ With C++, even different versions of the same compiler can be incompatible.
+ Therefore, PyLith must be built using the same C++ and Fortran compilers
+ used to configure and build PETSc.
+ It is best to let PyLith's
+\family typewriter
+configure
+\family default
+ script handle this automatically.
+\end_layout
+
+\begin_layout Section
+\begin_inset LatexCommand \label{sec:Pyre-Configuration}
+
+\end_inset
+
+Pyre Configuration
+\end_layout
+
+\begin_layout Standard
+Pyre is automatically downloaded by PyLith's configure script as a part
+ of the Pythia package.
+ Pythia is pure Python, so it requires no special configuration to build
+ or install.
+\end_layout
+
+\begin_layout Standard
+However, Pyre manages the launching of parallel runs of PyLith under MPI,
+ and the scheduling of PyLith jobs when used with a batch system.
+ Therefore, before running PyLith, you must create a small configuration
+ file which instructs Pyre how to launch and schedule PyLith runs on your
+ system.
+\end_layout
+
+\begin_layout Subsection
+Pyre Configuration on a Personal Computer
+\end_layout
+
+\begin_layout Standard
+On a workstation or laptop, there is no job scheduler or communication network
+ between compute nodes.
+ In this scenario, Pyre is trivial to configure.
+ Simply create the file
+\family typewriter
+~/.pyre/pylith3d/pylith3d.cfg
+\family default
+ with the following contents:
+\end_layout
+
+\begin_layout LyX-Code
+
+\family typewriter
+[pylith3d.launcher]
+\end_layout
+
+\begin_layout LyX-Code
+command = mpiexec -np ${nodes}
+\end_layout
+
+\begin_layout Standard
+The only trick is to specify the right command for your MPI implementation.
+ Specify the
+\family typewriter
+mpiexec
+\family default
+ command if you are using MPICH2 (which will be the case if you instructed
+ PETSc to download MPICH for you).
+\end_layout
+
+\begin_layout Standard
+If you are using MPICH1, enter the following instead:
+\end_layout
+
+\begin_layout LyX-Code
+
+\family typewriter
+[pylith3d.launcher]
+\end_layout
+
+\begin_layout LyX-Code
+command = mpirun -np ${nodes}
+\end_layout
+
+\begin_layout Standard
+See the documentation for your MPI implementation if you are unsure of the
+ command to specify.
+\end_layout
+
+\begin_layout Subsection
+Pyre Configuration on a Cluster
+\end_layout
+
+\begin_layout Standard
+If you are installing PyLith on a cluster with a batch system, you can configure
+ Pyre such that the
+\family typewriter
+pylith3dapp.py
+\family default
+ command automatically submits jobs to the batch queue.
+ Pyre contains support for the LSF, PBS, and Globus batch systems.
+\end_layout
+
+\begin_layout Standard
+The command to submit a batch job depends upon the particular batch system
+ used.
+ Further, the command used in a batch script to launch an MPI program varies
+ from one cluster to the next.
+ This command can vary between two clusters, even if the clusters use the
+ same batch system! On some systems,
+\family typewriter
+mpirun
+\family default
+ is invoked directly from the batch script.
+ On others, a special wrapper is used instead.
+\end_layout
+
+\begin_layout Standard
+Properly configured, Pyre can handle job submissions automatically, insulating
+ users from the details of the batch system and the site configuration.
+ This feature has the most value when the system administrator installs
+ a global Pyre configuration file on the cluster (under
+\family typewriter
+/etc/pythia-0.8
+\family default
+), for the benefit of all users and all Pyre-based applications.
+\end_layout
+
+\begin_layout Subsubsection
+\begin_inset LatexCommand \label{sub:Launchers-and-Schedulers}
+
+\end_inset
+
+Launchers and Schedulers
+\end_layout
+
+\begin_layout Standard
+If you have used one of the batch systems, you will know that the batch
+ system requires you to write a script to launch a job.
+ Fortunately, launching a parallel PyLith job is simplified by Pyre's
+\family typewriter
+launcher
+\family default
+ and
+\family typewriter
+scheduler
+\family default
+ facilities.
+ Many properties associated with
+\family typewriter
+launcher
+\family default
+ and
+\family typewriter
+scheduler
+\family default
+ are pertinent to the cluster you are on, and are best customized in a configura
+tion file.
+ Your personal PyLith configuration file (
+\family typewriter
+~/.pyre/pylith3d/pylith3d.cfg
+\family default
+) is suitable for this purpose.
+ On a cluster, the ideal setup is to install a system-wide configuration
+ file under
+\family typewriter
+/etc/pythia-0.8
+\family default
+, for the benefit of all users.
+\end_layout
+
+\begin_layout Standard
+Pyre's
+\family typewriter
+scheduler
+\family default
+ facility is used to specify the type of batch system you are using (if
+ any):
+\end_layout
+
+\begin_layout LyX-Code
+[pylith3d]
+\end_layout
+
+\begin_layout LyX-Code
+scheduler = lsf
+\end_layout
+
+\begin_layout Standard
+The valid values for
+\family typewriter
+scheduler
+\family default
+ are
+\family typewriter
+lsf
+\family default
+,
+\family typewriter
+pbs
+\family default
+,
+\family typewriter
+globus
+\family default
+, and
+\family typewriter
+none
+\family default
+.
+\end_layout
+
+\begin_layout Standard
+Pyre's
+\family typewriter
+launcher
+\family default
+ facility is used to specify which MPI implementation you are using:
+\end_layout
+
+\begin_layout LyX-Code
+[pylith3d]
+\end_layout
+
+\begin_layout LyX-Code
+launcher = mpich
+\end_layout
+
+\begin_layout Standard
+The valid values for
+\family typewriter
+launcher
+\family default
+ include
+\family typewriter
+mpich
+\family default
+ and
+\family typewriter
+lam-mpi
+\family default
+.
+\end_layout
+
+\begin_layout Standard
+You may find the
+\family typewriter
+dry
+\family default
+ option useful while debugging the
+\family typewriter
+launcher
+\family default
+ and
+\family typewriter
+scheduler
+\family default
+ configuration.
+ To debug the scheduler configuration, use the
+\family typewriter
+--scheduler.dry
+\family default
+ option:
+\end_layout
+
+\begin_layout LyX-Code
+pylith3dapp.py --scheduler.dry
+\end_layout
+
+\begin_layout Standard
+This option will cause PyLith to perform a ``dry run,'' dumping the batch
+ script to the console, instead of actually submitting it for execution
+ (the output is only meaningful if you're using a batch system).
+ Likewise, to debug the launcher configuration, use the
+\family typewriter
+--launcher.dry
+\family default
+ option:
+\end_layout
+
+\begin_layout LyX-Code
+pylith3dapp.py --launcher.dry
+\end_layout
+
+\begin_layout Standard
+This option will cause PyLith to print the
+\family typewriter
+mpirun
+\family default
+ command, instead of actually executing it.
+ (If you're using a batch system, a job will be submitted for execution;
+ when it runs, PyLith will simply print the
+\family typewriter
+mpirun
+\family default
+ command, and the job will immediately terminate.)
+\end_layout
+
+\begin_layout Subsubsection
+Running without a Batch System
+\end_layout
+
+\begin_layout Standard
+On a cluster without a batch system, you need to explicitly specify the
+ machines on which the job will run.
+ Supposing the machines on your cluster are named n001, n002, \SpecialChar \ldots{}
+, etc., but
+ you want to run the job on machines n001, n003, n004, and n005 (maybe n002
+ is down for the moment).
+ To run an example, create a file named
+\family typewriter
+mymachines.cfg
+\family default
+ which specifies the machines to use:
+\end_layout
+
+\begin_layout LyX-Code
+[pylith3d.launcher]
+\end_layout
+
+\begin_layout LyX-Code
+nodegen = n%03d
+\end_layout
+
+\begin_layout LyX-Code
+nodelist = [1,3-5]
+\end_layout
+
+\begin_layout Standard
+The
+\family typewriter
+nodegen
+\family default
+ property is a printf-style format string, used in conjunction with
+\family typewriter
+nodelist
+\family default
+ to generate the list of machine names.
+ The
+\family typewriter
+nodelist
+\family default
+ property is a comma-separated list of machine names in square brackets.
+\end_layout
+
+\begin_layout Standard
+Now, invoke the following:
+\end_layout
+
+\begin_layout LyX-Code
+$ pylith3dapp.py example.cfg mymachines.cfg
+\end_layout
+
+\begin_layout Standard
+This strategy gives you the flexibility to create an assortment of
+\family typewriter
+.cfg
+\family default
+ files (with one
+\family typewriter
+.cfg
+\family default
+ file for each machine list) which can be easily paired with different parameter
+ files.
+\end_layout
+
+\begin_layout Standard
+If your machine list does not change often, you may find it more convenient
+ to specify default values for
+\family typewriter
+nodegen
+\family default
+ and
+\family typewriter
+nodelist
+\family default
+ in
+\family typewriter
+~/.pyre/pylith3d/pylith3d.cfg
+\family default
+ (which is read automatically).
+ Then, you can run any simulation with no additional arguments:
+\end_layout
+
+\begin_layout LyX-Code
+$ pylith3dapp.py example.cfg
+\end_layout
+
+\begin_layout Quote
+
+\color red
+Warning:
+\color none
+This assumes your machine list has enough nodes for the simulation in question.
+\end_layout
+
+\begin_layout Standard
+You will notice that a machine file
+\family typewriter
+mpirun.nodes
+\family default
+ is generated.
+ It will contain a list of the nodes where PyLith has run.
+\end_layout
+
+\begin_layout Subsubsection
+Using a Batch System
+\end_layout
+
+\begin_layout Standard
+The settings which are important when using a batch system are summarized
+ in the sample configuration file which follows.
+\end_layout
+
+\begin_layout LyX-Code
+[pylith3d]
+\end_layout
+
+\begin_layout LyX-Code
+scheduler = lsf ; the type of the installed batch system
+\end_layout
+
+\begin_layout LyX-Code
+
+\end_layout
+
+\begin_layout LyX-Code
+[pylith3d.lsf]
+\end_layout
+
+\begin_layout LyX-Code
+bsub-options = [-a mpich_gm] ; special options for 'bsub'
+\end_layout
+
+\begin_layout LyX-Code
+
+\end_layout
+
+\begin_layout LyX-Code
+[pylith3d.launcher]
+\end_layout
+
+\begin_layout LyX-Code
+command = mpirun.lsf ; 'mpirun' command to use on our cluster
+\end_layout
+
+\begin_layout LyX-Code
+
+\end_layout
+
+\begin_layout LyX-Code
+[pylith3d.job]
+\end_layout
+
+\begin_layout LyX-Code
+queue = normal ; default queue for jobs
+\end_layout
+
+\begin_layout Standard
+These settings are usually placed in
+\family typewriter
+~/.pyre/pylith3d/pylith3d.cfg
+\family default
+ or in a system-wide configuration file.
+ They can be overridden on the command line, where one typically specifies
+ the job name and the allotted time for the job:
+\end_layout
+
+\begin_layout LyX-Code
+$ pylith3dapp.py example1.cfg --job.queue=debug
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+ --job.name=example1 --job.walltime=5*minute
+\backslash
+
+\end_layout
+
+\begin_layout LyX-Code
+ --nodes=4
+\end_layout
+
+\begin_layout Standard
+The number of processors to allocate for the job is given using the
+\family typewriter
+nodes
+\family default
+ parameter.
+\end_layout
+
+\begin_layout Standard
+For more information on configuring Pyre for your batch system, see CIG's
+
+\begin_inset LatexCommand \htmlurl[Pythia page]{www.geodynamics.org/cig/software/packages/cs/pythia}
+
+\end_inset
+
+.
+\end_layout
+
+\begin_layout Section
+\begin_inset LatexCommand \label{sec:Software-Repository}
+
+\end_inset
+
+Installing from the Software Repository
+\end_layout
+
+\begin_layout Standard
+The PyLith source code is available via the
+\begin_inset LatexCommand \htmlurl[Geodynamics Subversion Repository]{www.geodynamics.org/cig/software/Repository/}
+
+\end_inset
+
+.
+ The PETSc source code is available via a Mercurial repository.
+ This allows users to view the revision history of the code and check out
+ the most recent development version of the software.
+\end_layout
+
+\begin_layout Quote
+
+\series bold
+\color red
+Warning:
+\series default
+\color none
+ 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_layout
+
+\begin_layout Quote
+If you are content with the prepared source packages, you may skip this
+ section.
+\end_layout
+
+\begin_layout Subsection
+Additional Tools You Will Need
+\end_layout
+
+\begin_layout Standard
+In addition to the usual system requirements, you will need a handful of
+ additional development tools installed in order to work with the source
+ from the software repositories.
+\end_layout
+
+\begin_layout Itemize
+Subversion
+\end_layout
+
+\begin_layout Itemize
+Mercurial (0.9 or later)
+\end_layout
+
+\begin_layout Itemize
+GNU Autotools (Autoconf, Automake, and Libtool)
+\end_layout
+
+\begin_layout Itemize
+Pyrex (v0.9.5.1 or later)
+\end_layout
+
+\begin_layout Subsubsection
+Subversion
+\end_layout
+
+\begin_layout Standard
+To check out the PyLith source, you must have a Subversion client installed.
+ To check, type
+\family typewriter
+svn
+\family default
+; it should return a usage message.
+\end_layout
+
+\begin_layout LyX-Code
+$ svn
+\end_layout
+
+\begin_layout LyX-Code
+Type 'svn help' for usage.
+\end_layout
+
+\begin_layout Standard
+Many flavors of Unix have Subversion packages.
+ You do not need anything but the basic Subversion client package.
+\end_layout
+
+\begin_layout Standard
+For more information on Subversion, visit the
+\begin_inset LatexCommand \htmlurl[Subversion website]{subversion.tigris.org}
+
+\end_inset
+
+.
+\end_layout
+
+\begin_layout Subsubsection
+Mercurial
+\end_layout
+
+\begin_layout Standard
+To check out the PETSc source, you must have Mercurial 0.9 or later installed.
+ You will likely have to build Mercurial from source, but this is a very
+ easy task that takes only a couple of minutes.
+ To learn how to download and install Mercurial, visit
+\begin_inset LatexCommand \htmlurl[the Mercurial web site]{http://www.selenic.com/mercurial/}
+
+\end_inset
+
+.
+\end_layout
+
+\begin_layout Subsubsection
+Pyrex
+\end_layout
+
+\begin_layout Standard
+The software layer which connects PyLith's high-level Python code with its
+ low-level Fortran code is written in a language called
+\emph on
+Pyrex
+\emph default
+.
+ Pyrex is a Python-like language for writing native Python extension modules.
+ To download Pyrex, visit
+\begin_inset LatexCommand \htmlurl[the Pyrex web site]{http://www.cosc.canterbury.ac.nz/greg.ewing/python/Pyrex/}
+
+\end_inset
+
+.
+ After installing Pyrex, make sure the
+\family typewriter
+pyrexc
+\family default
+ command is accessible via your
+\family typewriter
+PATH
+\family default
+.
+\end_layout
+
+\begin_layout Standard
+The Pyrex compiler generates C code as its output.
+ Due to PETSc-related C/C++ linkage issues, the PyLith build system compiles
+ this generated C code using the C++ compiler.
+ For this reason and others, PyLith requires Pyrex v0.9.5.1 or later.
+\end_layout
+
+\begin_layout Subsubsection
+Autotools
+\end_layout
+
+\begin_layout Standard
+To generate the build system for PyLith, you must have the GNU tools Autoconf,
+ Automake, and Libtool installed.
+ To check, enter the following commands:
+\end_layout
+
+\begin_layout LyX-Code
+$ autoconf --version
+\end_layout
+
+\begin_layout LyX-Code
+$ automake --version
+\end_layout
+
+\begin_layout LyX-Code
+$ libtoolize --version
+\end_layout
+
+\begin_layout Standard
+For more information about these GNU tools, see the
+\begin_inset LatexCommand \htmlurl[GNU website]{www.gnu.org/software}
+
+\end_inset
+
+.
+ The PyLith source package was created with Autoconf 2.61, Automake 1.9.6,
+ and Libtool 1.5.22.
+\end_layout
+
+\begin_layout Subsection
+Downloading the PETSc Source using Mercurial
+\end_layout
+
+\begin_layout Standard
+Pull the source code from Argonne National Laboratory (ANL) and place the
+ source tree in a suitable location.
+ The steps below will create a
+\family typewriter
+petsc-dev
+\family default
+ sub-directory in the current directory.
+\end_layout
+
+\begin_layout LyX-Code
+
+\family typewriter
+$ hg clone http://mercurial.mcs.anl.gov/petsc/petsc-dev
+\end_layout
+
+\begin_layout LyX-Code
+
+\family typewriter
+$ cd petsc-dev/python
+\end_layout
+
+\begin_layout LyX-Code
+
+\family typewriter
+$ hg clone http://mercurial.mcs.anl.gov/petsc/BuildSystem BuildSystem
+\end_layout
+
+\begin_layout Standard
+In the future, you will likely want to update the PETSc source tree to include
+ bug fixes, new features, etc.
+ To update PETSc, perform the following commands:
+\end_layout
+
+\begin_layout LyX-Code
+
+\family typewriter
+$ cd petsc-dev
+\end_layout
+
+\begin_layout LyX-Code
+
+\family typewriter
+$ hg pull
+\end_layout
+
+\begin_layout LyX-Code
+
+\family typewriter
+$ hg update
+\end_layout
+
+\begin_layout LyX-Code
+
+\family typewriter
+$ cd python/BuildSystem
+\end_layout
+
+\begin_layout LyX-Code
+
+\family typewriter
+$ hg pull
+\end_layout
+
+\begin_layout LyX-Code
+$ hg update
+\end_layout
+
+\begin_layout Subsection
+Downloading the PyLith Source using Subversion
+\end_layout
+
+\begin_layout Standard
+To check out the latest version of PyLith, use the
+\family typewriter
+svn checkout
+\family default
+ command:
+\end_layout
+
+\begin_layout LyX-Code
+$ svn checkout
+\family typewriter
+http://geodynamics.org/svn/cig/short/3D/PyLith/branches/pylith-0.8
+\end_layout
+
+\begin_layout Standard
+This will create the local directory
+\family typewriter
+pylith-0.8
+\family default
+ (if it doesn't already exist) and fill it with the latest PyLith source
+ from the CIG software repository.
+\end_layout
+
+\begin_layout Standard
+The
+\family typewriter
+pylith-0.8
+\family default
+ directory thus created is called a
+\emph on
+working copy
+\emph default
+.
+ To merge the latest changes into an existing working copy, use the
+\family typewriter
+svn update
+\family default
+ command:
+\end_layout
+
+\begin_layout LyX-Code
+$ cd pylith-0.8
+\end_layout
+
+\begin_layout LyX-Code
+$ svn update
+\end_layout
+
+\begin_layout Standard
+This will preserve any local changes you have made to your working copy.
+\end_layout
+
+\begin_layout Subsection
+Generating the GNU Build System
+\end_layout
+
+\begin_layout Standard
+Your working directory should now contain a fresh checkout of PyLith and
+ PETSc:
+\end_layout
+
+\begin_layout LyX-Code
+$ ls
+\end_layout
+
+\begin_layout LyX-Code
+petsc-dev
+\end_layout
+
+\begin_layout LyX-Code
+pylith-0.8
+\end_layout
+
+\begin_layout LyX-Code
+$
+\end_layout
+
+\begin_layout Standard
+You are now ready to install PETSc as described in Section
+\begin_inset LatexCommand \ref{sec:Installing-PETSc}
+
+\end_inset
+
+ earlier in this chapter.
+\end_layout
+
+\begin_layout Standard
+However, before you can run
+\family typewriter
+configure
+\family default
+ or
+\family typewriter
+make
+\family default
+ in the
+\family typewriter
+pylith-0.8
+\family default
+ directory, you must generate the necessary files using the GNU tools.
+ The easiest way to do this is to run
+\family typewriter
+autoreconf -if
+\family default
+:
+\end_layout
+
+\begin_layout LyX-Code
+$ cd pylith-0.8
+\end_layout
+
+\begin_layout LyX-Code
+$ autoreconf -if
+\end_layout
+
+\begin_layout LyX-Code
+$ ./configure
+\end_layout
+
+\begin_layout LyX-Code
+$ make
+\end_layout
+
+\begin_layout Standard
+The
+\family typewriter
+autoreconf
+\family default
+ tool runs Autoconf to generate the
+\family typewriter
+configure
+\family default
+ script from
+\family typewriter
+configure.ac
+\family default
+.
+ It also runs Automake to generate
+\family typewriter
+Makefile.in
+\family default
+ from
+\family typewriter
+Makefile.am
+\family default
+ in each source directory.
+ After running
+\family typewriter
+autoreconf
+\family default
+, install PyLith as described in Section
+\begin_inset LatexCommand \ref{sec:Installing-PyLith}
+
+\end_inset
+
+ earlier in this chapter.
+\end_layout
+
+\begin_layout LyX-Code
+
+\end_layout
+
+\end_body
+\end_document
Modified: short/3D/PyLith/trunk/doc/userguide/intro/intro.lyx
===================================================================
--- short/3D/PyLith/trunk/doc/userguide/intro/intro.lyx 2007-06-16 22:41:51 UTC (rev 7275)
+++ short/3D/PyLith/trunk/doc/userguide/intro/intro.lyx 2007-06-17 03:32:28 UTC (rev 7276)
@@ -186,12 +186,8 @@
\end_layout
-\begin_layout Standard
-
-\end_layout
-
\begin_layout Section
-Software Components
+PyLith Design
\end_layout
\begin_layout Standard
@@ -223,66 +219,80 @@
PETSc is used to perform operations on matrices and vectors in parallel.
\end_layout
-\begin_layout Subsection
-PETSc
+\begin_layout Standard
+[
+\series bold
+BRAD, MATT
+\series default
+ -- This section needs to be completely rewritten, since it came from PyLith
+ 0.8.
+ Any help would be appreciated.]
\end_layout
\begin_layout Standard
-\begin_inset LatexCommand \htmlurl[PETSc]{www-unix.mcs.anl.gov/petsc/petsc-as}
+In rewriting PyLith, the code was completely redesigned to be object-oriented
+ and modular.
+ Each type of module is accessed through a specified interface (set of functions
+).
+ This permits adding, replacing, and rewriting modules without affecting
+ other parts of the code.
+ This code structure simplifies code maintenance and developement.
+ Extending the set of code features is also easier, since developers can
+ create new modules derived from the existing ones.
+\end_layout
-\end_inset
+\begin_layout Standard
+The new code design leverages Pyre, Sieve, and PETSc much more extensively
+ than the previous version.
+ Pyre is used to glue together the various modules used to construct a simulatio
+n and specify the simulation parameters.
+ Sieve is used for all finite-element storage and manipulation and handles
+ the creation of the PETSc matrices and vectors.
+ As a result, most of the PyLith source code pertains to implementing the
+ geodynamics, such as bulk rheology, boundary conditions, and slip on faults.
+
+\end_layout
-, 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 ESSL, MUMPS,
- Matlab, ParMeTis, PVODE, and Hypre, thereby providing additional solvers
- and interaction with other software packages.
+\begin_layout Standard
+During development tests were constructed for nearly every module function.
+ These unit tests are distributed with the source code.
+ During development these tests were run on a frequent basis to expose bugs
+ and isolate their origin.
+ As additional changes are made to the code, the tests are rerun to help
+ prevent introduction of bugs.
+ A number of simple, full scale tests, such as axial compression, simple
+ shear, and slip between two cells have been used to test the code.
\end_layout
\begin_layout Standard
-PETSc includes interfaces for Fortran 77/90, C, C++, and Python 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.
+[ADD DESCRIPTION OF WHAT HAPPENS WHEN EXECUTING PYLITH IN PARALLEL, next
+ paragraph is too technical (too much nomenclature)]
\end_layout
\begin_layout Standard
-PyLith 0.8 and PyLith 1.0 make use of a new aspect of PETSc known as
+Our new design begins with the
\family typewriter
-Sieve
+ Sieve
\family default
-, which is still under active development.
-
+ to represent the topology of our domain.
+ Zero volume elements are inserted along all fault surfaces which can implement
+ both split node and cohesive element schemes.
+ Material properties and other parameters are represented as
\family typewriter
-Sieve
+ Sections
\family default
- is a new method for representing computational meshes, and it greatly simplifie
-s the task of code parallelization.
-
+ over the sieve, and values can be retrieved by restriction.
+ For each problem, methods are provided to calculate the residual and its
+ Jacobian.
+ All analytic work is done in these functions, and parallel assembly is
+ accomplished using the restrict/update paradigm from the
\family typewriter
-Sieve
+ Sieve
\family default
- also provides a number of other useful features, such as the ability to
- grab ``sections'' of a mesh that share common characteristics, such as
- elements of the same material type or nodes to which boundary conditions
- have been applied.
- This version of PyLith uses
-\family typewriter
-Sieve
-\family default
- much more extensively than PyLith 0.8, and should provide significantly
- better performance.
+ framework.
+ We assemble into PETSc linear algebra objects and then call PETSc solvers.
+ The solution is mapped back into a section, which can be output in VTK
+ format.
\end_layout
\begin_layout Subsection
@@ -372,85 +382,68 @@
development cycle, and good debugging support.
\end_layout
-\begin_layout Section
-PyLith Design
+\begin_layout Subsection
+Sieve and PETSc
\end_layout
\begin_layout Standard
-[
-\series bold
-BRAD, MATT
-\series default
- -- This section needs to be completely rewritten, since it came from PyLith
- 0.8.
- Any help would be appreciated.]
+PyLith 0.8 and PyLith 1.0 make use of a new set of data structures and routines
+ in PETSc called
+\family typewriter
+Sieve
+\family default
+, which is still under active development.
+
+\family typewriter
+Sieve
+\family default
+ is a new method for representing computational meshes, and it greatly simplifie
+s finite-element computations.
+
+\family typewriter
+Sieve
+\family default
+ provides a number of useful features, such as the ability to grab ``sections''
+ of a mesh that share common characteristics, such as cells of the same
+ material type or vertices to which boundary conditions need to be applied.
+ This version of PyLith uses
+\family typewriter
+Sieve
+\family default
+ much more extensively than PyLith 0.8, and should provide significantly
+ better performance.
+ Sieve interfaces with PETSc for solving the system of equations.
\end_layout
\begin_layout Standard
-In rewriting PyLith, the code was completely redesigned to be object-oriented
- and modular.
- Each type of module is accessed through a specified interface (set of functions
-).
- This permits adding, replacing, and rewriting modules without affecting
- other parts of the code.
- This code structure simplifies code maintenance and developement.
- Extending the set of code features is also easier, since developers can
- create new modules derived from the existing ones.
-\end_layout
+\begin_inset LatexCommand \htmlurl[PETSc]{www-unix.mcs.anl.gov/petsc/petsc-as}
-\begin_layout Standard
-The new code design leverages Pyre, Sieve, and PETSc much more extensively
- than the previous version.
- Pyre is used to glue together the various modules used to construct a simulatio
-n and specify the simulation parameters.
- Sieve is used for all finite-element storage and manipulation and handles
- the creation of the PETSc matrices and vectors.
- As a result, most of the PyLith source code pertains to implementing the
- geodynamics, such as bulk rheology, boundary conditions, and slip on faults.
-
-\end_layout
+\end_inset
-\begin_layout Standard
-During development tests were constructed for nearly every module function.
- These unit tests are distributed with the source code.
- During development these tests were run on a frequent basis to expose bugs
- and isolate their origin.
- As additional changes are made to the code, the tests are rerun to help
- prevent introduction of bugs.
- A number of simple, full scale tests, such as axial compression, simple
- shear, and slip between two cells have been used to test the code.
+, 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 ESSL, MUMPS,
+ Matlab, ParMeTis, PVODE, and Hypre, thereby providing additional solvers
+ and interaction with other software packages.
\end_layout
\begin_layout Standard
-[ADD DESCRIPTION OF WHAT HAPPENS WHEN EXECUTING PYLITH IN PARALLEL, next
- paragraph is too technical (too much nomenclature)]
+PETSc includes interfaces for Fortran 77/90, C, C++, and Python 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.
\end_layout
-\begin_layout Standard
-Our new design begins with the
-\family typewriter
- Sieve
-\family default
- to represent the topology of our domain.
- Zero volume elements are inserted along all fault surfaces which can implement
- both split node and cohesive element schemes.
- Material properties and other parameters are represented as
-\family typewriter
- Sections
-\family default
- over the sieve, and values can be retrieved by restriction.
- For each problem, methods are provided to calculate the residual and its
- Jacobian.
- All analytic work is done in these functions, and parallel assembly is
- accomplished using the restrict/update paradigm from the
-\family typewriter
- Sieve
-\family default
- framework.
- We assemble into PETSc linear algebra objects and then call PETSc solvers.
- The solution is mapped back into a section, which can be output in VTK
- format.
-\end_layout
-
\end_body
\end_document
Modified: short/3D/PyLith/trunk/doc/userguide/materials/materials.lyx
===================================================================
--- short/3D/PyLith/trunk/doc/userguide/materials/materials.lyx 2007-06-16 22:41:51 UTC (rev 7275)
+++ short/3D/PyLith/trunk/doc/userguide/materials/materials.lyx 2007-06-17 03:32:28 UTC (rev 7276)
@@ -56,7 +56,143 @@
\end_layout
+\begin_layout Section
+1-D Material Models
+\end_layout
+
+\begin_layout Subsection
+Elastic
+\begin_inset Quotes eld
+\end_inset
+
+Linear
+\begin_inset Quotes erd
+\end_inset
+
+ Strain
+\end_layout
+
+\begin_layout Subsection
+Elastic
+\begin_inset Quotes eld
+\end_inset
+
+Linear
+\begin_inset Quotes erd
+\end_inset
+
+ Stress
+\end_layout
+
+\begin_layout Section
+2-D Material Models
+\end_layout
+
+\begin_layout Subsection
+Elastic Plane Strain
+\end_layout
+
+\begin_layout Subsection
+Elastic Plane Stress
+\end_layout
+
+\begin_layout Section
+3-D Material Models
+\end_layout
+
+\begin_layout Subsection
+Isotropic Elastic Material
+\end_layout
+
\begin_layout Standard
+The generalized form of Hooke's law relating stress and strain for linear
+ elastic materials is
+\end_layout
+
+\begin_layout Standard
+\begin_inset Formula \begin{gather}
+\sigma_{ij}=C_{ijkl}\epsilon_{kl}\,.\label{eq:6}\end{gather}
+
+\end_inset
+
+Due to symmetry considerations, however, the 81 components of the elasticity
+ matrix are reduced to 21 independent components for the most general case
+ of anisotropic elasticity; for the case of isotropic elasticity, the number
+ of independent components reduces to two.
+ Representing the stress and strain in terms of vectors, the constitutive
+ relation may be written
+\begin_inset Formula \begin{gather}
+\overrightarrow{\sigma}=\underline{C}\overrightarrow{\epsilon\,}.\label{eq:7}\end{gather}
+
+\end_inset
+
+This model may be characterized by two parameters, Lame's constants
+\begin_inset Formula $\mu$
+\end_inset
+
+ and
+\begin_inset Formula $\lambda$
+\end_inset
+
+.
+ In terms of these two parameters, the stress-strain matrix,
+\begin_inset Formula $\underline{C}$
+\end_inset
+
+, may be written:
+\end_layout
+
+\begin_layout Standard
+\begin_inset Formula \begin{gather}
+\underline{C}=\left[\begin{array}{cccccc}
+\lambda+2\mu & \lambda & \lambda & 0 & 0 & 0\\
+\lambda & \lambda+2\mu & \lambda & 0 & 0 & 0\\
+\lambda & \lambda & \lambda+2\mu & 0 & 0 & 0\\
+0 & 0 & 0 & 2\mu & 0 & 0\\
+0 & 0 & 0 & 0 & 2\mu & 0\\
+0 & 0 & 0 & 0 & 0 & 2\mu\end{array}\right]\:.\label{eq:8}\end{gather}
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+Lame's constants are related to the density (
+\begin_inset Formula $\rho$
+\end_inset
+
+), shear wave speed (
+\begin_inset Formula $v_{s}$
+\end_inset
+
+), and compressional wave speed (
+\begin_inset Formula $v_{p}$
+\end_inset
+
+) via
+\end_layout
+
+\begin_layout Standard
+\begin_inset Formula $ $
+\end_inset
+
+
+\begin_inset Formula \[
+\begin{aligned}\mu= & \rho v_{s}^{2}\\
+\lambda= & \rho v_{p}^{2}-2\mu\end{aligned}
+\]
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Subsection
+Viscoelastic Materials
+\end_layout
+
+\begin_layout Standard
There are six material models presently available in PyLith, as shown in
Table
\begin_inset LatexCommand \ref{tab:Material-models-available}
@@ -367,7 +503,7 @@
\end_layout
-\begin_layout Section
+\begin_layout Subsubsection
Definitions
\end_layout
@@ -617,71 +753,7 @@
\end_layout
-\begin_layout Section
-Isotropic Elastic Material
-\end_layout
-
-\begin_layout Standard
-The generalized form of Hooke's law relating stress and strain for linear
- elastic materials is
-\end_layout
-
-\begin_layout Standard
-\begin_inset Formula \begin{gather}
-\sigma_{ij}=C_{ijkl}\epsilon_{kl}\:.\label{eq:6}\end{gather}
-
-\end_inset
-
-Due to symmetry considerations, however, the 81 components of the elasticity
- matrix are reduced to 21 independent components for the most general case
- of anisotropic elasticity.
- For the case of isotropic elasticity, the number of independent components
- is further reduced to 2.
- Representing the stress and strain in terms of vectors and considering
- initial stresses, the constitutive relation may be written
-\begin_inset Formula \begin{gather}
-\overrightarrow{\sigma}=\underline{D}\overrightarrow{\epsilon}+^{I}\overrightarrow{\sigma}\:,\label{eq:7}\end{gather}
-
-\end_inset
-
-where
-\begin_inset Formula $^{I}\overrightarrow{\sigma}$
-\end_inset
-
- is the initial stress existing in the material.
- This model may be characterized by two parameters: the Young's modulus
- (
-\begin_inset Formula $E$
-\end_inset
-
-) and Poisson's ratio (
-\begin_inset Formula $\nu$
-\end_inset
-
-).
- In terms of these two parameters, the stress-strain matrix,
-\begin_inset Formula $\underline{D}$
-\end_inset
-
-, may be written:
-\end_layout
-
-\begin_layout Standard
-\begin_inset Formula \begin{gather}
-\underline{D}=\frac{E\left(1-\nu\right)}{\left(1+\nu\right)\left(1-2\nu\right)}\left[\begin{array}{cccccc}
-1 & \frac{\nu}{1-\nu} & \frac{\nu}{1-\nu} & 0 & 0 & 0\\
-\frac{\nu}{1-\nu} & 1 & \frac{\nu}{1-\nu} & 0 & 0 & 0\\
-\frac{\nu}{1-\nu} & \frac{\nu}{1-\nu} & 1 & 0 & 0 & 0\\
-0 & 0 & 0 & \frac{1-2\nu}{2\left(1-\nu\right)} & 0 & 0\\
-0 & 0 & 0 & 0 & \frac{1-2\nu}{2\left(1-\nu\right)} & 0\\
-0 & 0 & 0 & 0 & 0 & \frac{1-2\nu}{2\left(1-\nu\right)}\end{array}\right]\:.\label{eq:8}\end{gather}
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Section
+\begin_layout Subsubsection
Effective Stress Formulations for Viscoelastic Materials
\end_layout
@@ -783,7 +855,7 @@
\end_layout
-\begin_layout Subsection
+\begin_layout Subsubsection
Linear Maxwell Viscoelastic Material
\end_layout
@@ -1005,761 +1077,9 @@
\end_layout
-\begin_layout Subsection
-Power-law Maxwell Viscoelastic Material
-\end_layout
-
\begin_layout Standard
-A power-law Maxwell viscoelastic material may be parameterized with the
- elastic parameters
-\begin_inset Formula $E$
-\end_inset
- and
-\begin_inset Formula $\nu$
-\end_inset
-
-, the viscosity coefficient
-\begin_inset Formula $\eta$
-\end_inset
-
-, and the power-law exponent
-\begin_inset Formula $n$
-\end_inset
-
-.
- The creep strain increment is approximated as
-\begin_inset Formula \begin{gather}
-\underline{\Delta e}^{C}=\frac{\Delta t\sqrt{^{\tau}J_{2}^{\prime}}^{n-1}\,^{\tau}\underline{S}}{2\eta^{n}}=\frac{\Delta t^{\tau}\overline{\sigma}^{n-1}\,^{\tau}\underline{S}}{2\sqrt{3}\eta^{n}}\,.\label{eq:32}\end{gather}
-
-\end_inset
-
-Therefore,
-\begin_inset Formula \begin{gather}
-\Delta\bar{e}^{C}=\frac{\Delta t\sqrt{^{\tau}J_{2}^{\prime}}^{n}}{\sqrt{3}\eta^{n}}=\frac{\Delta t^{\tau}\overline{\sigma}^{n}}{\sqrt{3}^{n+1}\eta^{n}}\,,\,\textrm{and}\,^{\tau}\gamma=\frac{\sqrt{^{\tau}J_{2}^{\prime}}^{n-1}}{2\eta^{n}}\,.\label{eq:33}\end{gather}
-
-\end_inset
-
-substituting equations
-\begin_inset LatexCommand \ref{eq:13}
-
-\end_inset
-
-,
-\begin_inset LatexCommand \ref{eq:32}
-
-\end_inset
-
-, and
-\begin_inset LatexCommand \ref{eq:33}
-
-\end_inset
-
- into
-\begin_inset LatexCommand \ref{eq:10}
-
-\end_inset
-
-, we obtain:
-\begin_inset Formula \begin{gather}
-^{t+\Delta t}\underline{S}=\frac{E}{1+\nu}\left\{ ^{t+\Delta t}\underline{e}^{\prime\prime}-\Delta t^{\tau}\gamma\left[\left(1-\alpha\right)^{t}\underline{S}+\alpha{}^{t+\Delta t}\underline{S}\right]\right\} +^{I}\underline{S}\,,\label{eq:34}\end{gather}
-
-\end_inset
-
-which may be rewritten:
-\begin_inset Formula \begin{gather}
-^{t+\Delta t}\underline{S}\left(\frac{1+\nu}{E}+\alpha\Delta t^{\tau}\gamma\right)={}^{t+\Delta t}\underline{e}^{\prime\prime}-\Delta t^{\tau}\gamma\left(1-\alpha\right)^{t}\underline{S}+\frac{1+\nu}{E}\,^{I}\underline{S}\,.\label{eq:35}\end{gather}
-
-\end_inset
-
-Taking the scalar inner product of both sides we obtain:
-\begin_inset Formula \begin{gather}
-a^{2}\,\,{}^{t+\Delta t}J_{2}^{\prime}-b+c^{\tau}\gamma-d^{2}\,^{\tau}\gamma^{2}=F=0\,,\label{eq:36}\end{gather}
-
-\end_inset
-
-where
-\begin_inset Formula \begin{gather}
-a=\frac{1+\nu}{E}+\alpha\Delta t^{\tau}\gamma\,\,\nonumber \\
-b=\frac{1}{2}{}^{t+\Delta t}\underline{e}^{\prime\prime}\cdot{}^{t+\Delta t}\underline{e}^{\prime\prime}+\frac{1+\nu}{E}{}^{t+\Delta t}\underline{e}^{\prime\prime}\cdot^{I}\underline{S}+\left(\frac{1+\nu}{E}\right)^{2}\,^{I}J_{2}^{\prime}\,.\label{eq:37}\\
-c=\Delta t\left(1-\alpha\right){}^{t+\Delta t}\underline{e}^{\prime\prime}\cdot^{t}\underline{S}+\Delta t\left(1-\alpha\right)\frac{1+\nu}{E}\,^{t}\underline{S}\cdot^{I}\underline{S}\,\,\nonumber \\
-d=\Delta t\left(1-\alpha\right)\sqrt{^{t}J_{2}^{\prime}}\,\,\nonumber \end{gather}
-
-\end_inset
-
-Equation
-\begin_inset LatexCommand \ref{eq:36}
-
-\end_inset
-
- is a function of a single unknown -- the second deviatoric stress invariant
- at time
-\begin_inset Formula $t+\Delta t$
-\end_inset
-
- -- and may be solved by bisection or by Newton's method.
- Once this parameter has been found, the deviatoric stresses for the current
- time step may be found from equations
-\begin_inset LatexCommand \ref{eq:34}
-
-\end_inset
-
- and
-\begin_inset LatexCommand \ref{eq:33}
-
-\end_inset
-
-, and the total stresses may be found from equation
-\begin_inset LatexCommand \ref{eq:21}
-
-\end_inset
-
-.
\end_layout
-\begin_layout Subsubsection
-Tangent Stress-Strain Relation
-\end_layout
-
-\begin_layout Standard
-We proceed as for the linear case, but the evaluation of the first derivative
- in equation
-\begin_inset LatexCommand \ref{eq:25}
-
-\end_inset
-
- is more complicated.
- We begin by rewriting equation
-\begin_inset LatexCommand \ref{eq:35}
-
-\end_inset
-
- as
-\begin_inset Formula \begin{gather}
-^{t+\Delta t}\underline{S}=\frac{1}{\left(a_{E}+\alpha\Delta t^{\tau}\gamma\right)}\left[^{t+\Delta t}\underline{e}^{\prime\prime}-\Delta t^{\tau}\gamma\left(1-\alpha\right)^{t}\underline{S}+a_{E}\,^{I}\underline{S}\right]\,,\label{eq:38}\end{gather}
-
-\end_inset
-
-where
-\begin_inset Formula \begin{gather}
-a_{E}=\frac{1+\nu}{E}\,.\label{eq:39}\end{gather}
-
-\end_inset
-
-The derivative is then
-\begin_inset Formula \begin{gather}
-\frac{\partial{}^{t+\Delta t}S_{i}}{\partial{}^{t+\Delta t}e_{k}^{\prime\prime}}=\frac{1}{a_{E}+\alpha\Delta t^{\tau}\gamma}\nonumber \\
-\left\langle \delta_{ik}-\frac{\partial^{\tau}\gamma}{\partial{}^{t+\Delta t}e_{k}^{\prime\prime}}\left\{ \Delta t\left(1-\alpha\right)^{t}S_{i}+\frac{\alpha\Delta t}{a_{E}+\alpha\Delta t^{\tau}\gamma}\left[^{t+\Delta t}e_{i}^{\prime\prime}-\Delta t^{\tau}\gamma\left(1-\alpha\right)^{t}S_{i}+a_{E}\,^{I}S_{i}\right]\right\} \right\rangle \,.\label{eq:40}\end{gather}
-
-\end_inset
-
-From equation
-\begin_inset LatexCommand \ref{eq:33}
-
-\end_inset
-
-,
-\begin_inset Formula \begin{gather}
-\frac{\partial^{\tau}\gamma}{\partial{}^{t+\Delta t}e_{k}^{\prime\prime}}=\frac{\left(n-1\right)\sqrt{^{\tau}J_{2}^{\prime}}^{n-2}}{2\eta^{n}}\frac{\partial\sqrt{^{\tau}J_{2}^{\prime}}}{\partial{}^{t+\Delta t}e_{k}^{\prime\prime}}=K_{1}\frac{\partial\sqrt{^{\tau}J_{2}^{\prime}}}{\partial{}^{t+\Delta t}e_{k}^{\prime\prime}}\,.\label{eq:41}\end{gather}
-
-\end_inset
-
-We first note that
-\begin_inset Formula \begin{gather}
-\sqrt{^{t+\Delta t}J_{2}^{\prime}}=\frac{1}{\alpha}\left[\sqrt{^{\tau}J_{2}^{\prime}}-\left(1-\alpha\right)\sqrt{^{t}J_{2}^{\prime}}\right]\,,\label{eq:42}\end{gather}
-
-\end_inset
-
- which allows us to rewrite equation
-\begin_inset LatexCommand \ref{eq:36}
-
-\end_inset
-
- as
-\begin_inset Formula \begin{gather}
-\frac{a^{2}}{\alpha^{2}}\left[\sqrt{^{\tau}J_{2}^{\prime}}-\left(1-\alpha\right)\sqrt{^{t}J_{2}^{\prime}}\right]^{2}-b+c\,^{\tau}\gamma-d^{2}\,^{\tau}\gamma^{2}=\frac{a^{2}}{\alpha^{2}}K_{2}^{2}-b+c\,^{\tau}\gamma-d^{2}\,^{\tau}\gamma^{2}=F=0\,.\label{eq:43}\end{gather}
-
-\end_inset
-
-The derivatives of this function are
-\begin_inset Formula \begin{gather}
-\frac{\partial F}{\partial\sqrt{^{\tau}J_{2}^{\prime}}}=\frac{2aK_{2}}{\alpha^{2}}\left(\alpha\Delta tK_{1}K_{2}+a\right)+K_{1}\left(c-2d^{2}\,^{\tau}\gamma\right)\nonumber \\
-\frac{\partial F}{\partial{}^{t+\Delta t}e_{k}^{\prime\prime}}=-\delta_{ik}\left[\frac{^{t+\Delta t}e_{i}^{\prime\prime}}{2}\right]+a_{E}\,^{I}S_{i}-\Delta t\left(1-\alpha\right)^{t}S_{i}\,^{\tau}\gamma\,.\label{eq:44}\end{gather}
-
-\end_inset
-
-Then using the quotient rule for derivatives,
-\begin_inset Formula \begin{gather}
-\frac{\partial\sqrt{^{\tau}J_{2}^{\prime}}}{\partial{}^{t+\Delta t}e_{k}^{\prime\prime}}=\frac{\delta_{ik}\left[\frac{^{t+\Delta t}e_{i}^{\prime\prime}}{2}+a_{E}\,^{I}S_{i}-\Delta t\left(1-\alpha\right)^{t}S_{i}\,^{\tau}\gamma\right]}{\frac{2aK_{2}}{\alpha^{2}}\left(\alpha\Delta tK_{1}K_{2}+a\right)+K_{1}\left(c-2d^{2}\,^{\tau}\gamma\right)}\,.\label{eq:45}\end{gather}
-
-\end_inset
-
-This yields
-\begin_inset Formula \begin{gather}
-\frac{\partial\sqrt{^{\tau}J_{2}^{\prime}}}{\partial{}^{t+\Delta t}e_{j}^{\prime\prime}}=\frac{\delta_{ik}K_{1}\left[\frac{^{t+\Delta t}e_{i}^{\prime\prime}}{2}+a_{E}\,^{I}S_{i}-\Delta t\left(1-\alpha\right)^{t}S_{i}\,^{\tau}\gamma\right]}{\frac{2aK_{2}}{\alpha^{2}}\left(\alpha\Delta tK_{1}K_{2}+a\right)+K_{1}\left(c-2d^{2}\,^{\tau}\gamma\right)}\,.\label{eq:46}\end{gather}
-
-\end_inset
-
-Note that for a linear material
-\begin_inset Formula $\left(n=1\right)$
-\end_inset
-
-, this derivative is zero.
- This relation may be used in equation
-\begin_inset LatexCommand \ref{eq:40}
-
-\end_inset
-
-.
- Then, using equations
-\begin_inset LatexCommand \ref{eq:24}
-
-\end_inset
-
- through
-\begin_inset LatexCommand \ref{eq:27}
-
-\end_inset
-
-,
-\begin_inset Formula \begin{gather}
-C_{ij}^{VE}=\frac{E}{3\left(1-2\nu\right)}\left[\begin{array}{cccccc}
-1 & 1 & 1 & 0 & 0 & 0\\
-1 & 1 & 1 & 0 & 0 & 0\\
-1 & 1 & 1 & 0 & 0 & 0\\
-0 & 0 & 0 & 0 & 0 & 0\\
-0 & 0 & 0 & 0 & 0 & 0\\
-0 & 0 & 0 & 0 & 0 & 0\end{array}\right]+\frac{1}{3}\frac{\partial{}^{t+\Delta t}S_{i}}{\partial{}^{t+\Delta t}e_{k}^{\prime\prime}}\left[\begin{array}{cccccc}
-2 & -1 & -1 & 0 & 0 & 0\\
--1 & 2 & -1 & 0 & 0 & 0\\
--1 & -1 & 2 & 0 & 0 & 0\\
-0 & 0 & 0 & 3 & 0 & 0\\
-0 & 0 & 0 & 0 & 3 & 0\\
-0 & 0 & 0 & 0 & 0 & 3\end{array}\right]\,.\label{eq:47}\end{gather}
-
-\end_inset
-
-As for the linear case, we use an altered version of the matrix appropriate
- for engineering strain measures.
- At the beginning of a time step, the strains have not yet been computed,
- and we use the following approximation:
-\begin_inset Formula \begin{gather}
-\frac{\partial{}^{t+\Delta t}S_{i}}{\partial{}^{t+\Delta t}e_{k}^{\prime\prime}}\approx\frac{\delta_{ik}}{a_{E}+\Delta t^{\tau}\gamma}\,,\label{eq:48}\end{gather}
-
-\end_inset
-
-where we have neglected the changes in
-\begin_inset Formula $^{\tau}\gamma$
-\end_inset
-
- due to changes in
-\begin_inset Formula $^{t+\Delta t}e_{k}^{\prime\prime}$
-\end_inset
-
-, and we have used a value of
-\begin_inset Formula $\alpha=1$
-\end_inset
-
-.
-\end_layout
-
-\begin_layout Subsubsection
-Derivative of Effective Stress Function
-\end_layout
-
-\begin_layout Standard
-To compute the zero of the effective stress function using Newton's method,
- we require the derivative of equation
-\begin_inset LatexCommand \ref{eq:36}
-
-\end_inset
-
-, which may be written:
-\begin_inset Formula \begin{gather}
-\frac{\partial F}{\partial\sqrt{^{t+\Delta t}J_{2}^{\prime}}}=2a^{2}\sqrt{^{t+\Delta t}J_{2}^{\prime}}+\frac{\alpha\left(n-1\right)\sqrt{^{\tau}J_{2}^{\prime}}^{n-2}}{2\eta^{n}}\left(2a\alpha\Delta t{}^{t+\Delta t}J_{2}^{\prime}+c-2d^{2}\,^{\tau}\gamma\right)\,.\label{eq:49}\end{gather}
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Section
-Generalized Maxwell Viscoelastic Model
-\end_layout
-
-\begin_layout Standard
-The generalized Maxwell viscoelastic model consists of a number of Maxwell
- linear viscoelastic models in parallel with a spring, as shown in Figure
-
-\begin_inset LatexCommand \ref{fig:Material-models}
-
-\end_inset
-
-.
- In the specific model available in PyLith 0.8.2, we specify 3 Maxwell models.
- A number of common material models may be obtained from this model by setting
- the shear moduli of various springs to zero, such as the Maxwell model,
- the Kelvin model, and the standard linear solid.
- We follow formulations similar to those used by Zienkiewicz and Taylor
-
-\begin_inset LatexCommand \cite{Zienkiewicz:Taylor:2000}
-
-\end_inset
-
- and Taylor
-\begin_inset LatexCommand \cite{Taylor:2003}
-
-\end_inset
-
-.
- In this formulation, we specify the total shear modulus of the model (
-\begin_inset Formula $\mu_{tot}$
-\end_inset
-
-) by specifying the Young's modulus and Poisson's ratio.
- We then specify the fractional shear modulus for each Maxwell element spring
- in the model.
- It is not necessary to specify the fractional modulus for
-\begin_inset Formula $\mu_{0}$
-\end_inset
-
-, since this is obtained by subtracting the sum of the other ratios from
- 1.
- Note that the sum of all these fractions must equal 1.
- We use a similar formulation for the first instance of our linear Maxwell
- viscoelastic model (Model 5), but in that case
-\begin_inset Formula $\mu_{0}$
-\end_inset
-
- is always zero and we only use a single Maxwell model.
-\end_layout
-
-\begin_layout Subsection
-Constitutive Relation
-\end_layout
-
-\begin_layout Standard
-As for our other viscoelastic models, the volumetric strain is completely
- elastic, and the viscoelastic deformation may be expressed purely in terms
- of the deviatoric components:
-\end_layout
-
-\begin_layout Standard
-\begin_inset Formula \begin{gather}
-\underline{S}=2\mu_{tot}\left(\mu_{0}\underline{e}+\sum_{i=1}^{N}\mu_{i}\underline{q}^{i}\right)\,,\label{eq:50}\end{gather}
-
-\end_inset
-
-where
-\begin_inset Formula $N$
-\end_inset
-
- is the number of Maxwell models and the variable
-\begin_inset Formula $\underline{q}^{i}$
-\end_inset
-
- follows the evolution equations
-\end_layout
-
-\begin_layout Standard
-\begin_inset Formula \begin{gather}
-\underline{\dot{q}}^{i}+\frac{1}{\lambda_{i}}\underline{q}^{i}=\underline{\dot{e}}.\label{eq:51}\end{gather}
-
-\end_inset
-
-The
-\begin_inset Formula $\lambda_{i}$
-\end_inset
-
- are the relaxation times for each Maxwell model.
-\end_layout
-
-\begin_layout Standard
-An alternative to the differential equation form above is an integral equation
- form expressed in terms of the relaxation modulus function.
- This function is defined in terms of an idealized experiment in which,
- at time labeled zero (
-\begin_inset Formula $t=0$
-\end_inset
-
-), a specimen is subjected to a constant strain,
-\begin_inset Formula $\underline{e}_{0}$
-\end_inset
-
-, and the stress response,
-\begin_inset Formula $\underline{S}\left(t\right)$
-\end_inset
-
-, is measured.
- For a linear material we obtain:
-\end_layout
-
-\begin_layout Standard
-\begin_inset Formula \begin{gather}
-\underline{S}\left(t\right)=2\mu\left(t\right)\underline{e}_{0}\,,\label{eq:52}\end{gather}
-
-\end_inset
-
-where
-\begin_inset Formula $\mu\left(t\right)$
-\end_inset
-
- is the shear relaxation modulus function.
- Using linearity and superposition for an arbitrary state of strain yields
- an integral equation:
-\end_layout
-
-\begin_layout Standard
-\begin_inset Formula \begin{gather}
-\underline{S}\left(t\right)=\intop_{-\infty}^{t}\mu\left(t-\tau\right)\underline{\dot{e}}\, d\tau\,.\label{eq:53}\end{gather}
-
-\end_inset
-
-If we assume the modulus function in Prony series form we obtain
-\end_layout
-
-\begin_layout Standard
-\begin_inset Formula \begin{gather}
-\mu\left(t\right)=\mu_{tot}\left(\mu_{0}+\sum_{i=1}^{N}\mu_{i}\exp\frac{-t}{\lambda_{i}}\right)\,,\label{eq:54}\end{gather}
-
-\end_inset
-
-where
-\end_layout
-
-\begin_layout Standard
-\begin_inset Formula \begin{gather}
-\mu_{0}+\sum_{i=1}^{N}\mu_{i}=1\,.\label{eq:55}\end{gather}
-
-\end_inset
-
-With the form in equation
-\begin_inset LatexCommand \ref{eq:54}
-
-\end_inset
-
-, the integral equation form is identical to the differential equation form.
-\end_layout
-
-\begin_layout Standard
-Considering a single Maxwell model, the relaxation modulus function is
-\end_layout
-
-\begin_layout Standard
-\begin_inset Formula \begin{gather}
-\mu\left(t\right)=\mu_{tot}\left(\mu_{0}+\mu_{1}\exp\frac{-t}{\lambda_{1}}\right)\,,\label{eq:56}\end{gather}
-
-\end_inset
-
-where
-\end_layout
-
-\begin_layout Standard
-\begin_inset Formula \begin{gather}
-\mu_{0}+\mu_{1}=1\,.\label{eq:57}\end{gather}
-
-\end_inset
-
-If we assume the material is undisturbed until a strain is suddenly applied
- at time zero, we can divide the integral into
-\end_layout
-
-\begin_layout Standard
-\begin_inset Formula \begin{gather}
-\intop_{-\infty}^{t}\left(\cdot\right)\, d\tau=\intop_{-\infty}^{0^{-}}\left(\cdot\right)\, d\tau+\intop_{0^{-}}^{0^{+}}\left(\cdot\right)\, d\tau+\intop_{0^{+}}^{t}\left(\cdot\right)\, d\tau\,.\label{eq:58}\end{gather}
-
-\end_inset
-
-The first term is zero, the second term includes a jump term associated
- with
-\begin_inset Formula $\underline{e}_{0}$
-\end_inset
-
- at time zero, and the last term covers the subsequent history of strain.
- Applying this separation to equation
-\begin_inset LatexCommand \ref{eq:53}
-
-\end_inset
-
-,
-\end_layout
-
-\begin_layout Standard
-\begin_inset Formula \begin{gather}
-\underline{S}\left(t\right)=2\mu\left(t\right)\underline{e}_{0}+2\int_{0}^{t}\mu\left(t-\tau\right)\underline{\dot{e}}\left(\tau\right)\, d\tau\,,\label{eq:59}\end{gather}
-
-\end_inset
-
-where we have left the sign off of the lower limit on the integral.
-\end_layout
-
-\begin_layout Standard
-Substituting equation
-\begin_inset LatexCommand \ref{eq:54}
-
-\end_inset
-
- into
-\begin_inset LatexCommand \ref{eq:59}
-
-\end_inset
-
-, we obtain
-\end_layout
-
-\begin_layout Standard
-\begin_inset Formula \begin{gather}
-\underline{S}\left(t\right)=2\mu\left[\mu_{0}\underline{e}\left(t\right)+\mu_{1}\exp\frac{-t}{\lambda_{1}}\left(\underline{e}_{0}+\intop_{0}^{t}\exp\frac{t}{\lambda_{1}}\underline{\dot{e}}\left(\tau\right)\, d\tau\right)\right]\,.\label{eq:60}\end{gather}
-
-\end_inset
-
-We then split the integral into two ranges: from 0 to
-\begin_inset Formula $t_{n}$
-\end_inset
-
-, and from
-\begin_inset Formula $t_{n}$
-\end_inset
-
- to
-\begin_inset Formula $t$
-\end_inset
-
-, and define the integral as
-\end_layout
-
-\begin_layout Standard
-\begin_inset Formula \begin{gather}
-\underline{i}^{1}\left(t\right)=\intop_{0}^{t}\exp\frac{\tau}{\lambda_{1}}\underline{\dot{e}}\left(\tau\right)\, d\tau\,.\label{eq:61}\end{gather}
-
-\end_inset
-
-The integral then becomes
-\end_layout
-
-\begin_layout Standard
-\begin_inset Formula \begin{gather}
-\underline{i}^{1}\left(t\right)=\underline{i}^{1}\left(t_{n}\right)+\intop_{t_{n}}^{t}\exp\frac{\tau}{\lambda_{1}}\underline{\dot{e}}\left(\tau\right)\, d\tau\,.\label{eq:62}\end{gather}
-
-\end_inset
-
-Including the negative exponential multiplier:
-\end_layout
-
-\begin_layout Standard
-\begin_inset Formula \begin{gather}
-\underline{h}^{1}\left(t\right)=\exp\frac{-t}{\lambda_{1}}\underline{i}^{1}\,.\label{eq:63}\end{gather}
-
-\end_inset
-
-Then
-\end_layout
-
-\begin_layout Standard
-\begin_inset Formula \begin{gather}
-\underline{h}^{1}\left(t\right)=\exp\frac{-\Delta t}{\lambda_{1}}\underline{h}_{n}^{1}+\Delta\underline{h}\,,\label{eq:64}\end{gather}
-
-\end_inset
-
-where
-\end_layout
-
-\begin_layout Standard
-\begin_inset Formula \begin{gather}
-\Delta\underline{h}=\exp\frac{-t}{\lambda_{1}}\intop_{t_{n}}^{t}\exp\frac{\tau}{\lambda_{1}}\underline{\dot{e}}\left(\tau\right)\, d\tau\,.\label{eq:65}\end{gather}
-
-\end_inset
-
-Approximating the strain rate as constant over each time step, the solution
- may be found as
-\end_layout
-
-\begin_layout Standard
-\begin_inset Formula \begin{gather}
-\Delta\underline{h}=\frac{\lambda_{1}}{\Delta t}\left(1-\exp\frac{-\Delta t}{\lambda_{1}}\right)\left(\underline{e}-\underline{e}_{n}\right)=\Delta h\left(\underline{e}-\underline{e}_{n}\right)\,.\label{eq:66}\end{gather}
-
-\end_inset
-
-The approximation is singular for zero time steps, but a series expansion
- may be used for small time-step sizes:
-\end_layout
-
-\begin_layout Standard
-\begin_inset Formula \begin{gather}
-\Delta h\approx1-\frac{1}{2}\left(\frac{\Delta t}{\lambda_{1}}\right)+\frac{1}{3!}\left(\frac{\Delta t}{\lambda_{1}}\right)^{2}-\frac{1}{4!}\left(\frac{\Delta t}{\lambda_{1}}\right)^{3}+\cdots\,.\label{eq:67}\end{gather}
-
-\end_inset
-
-This converges with only a few terms.
- With this formulation, the constitutive relation now has the simple form:
-\end_layout
-
-\begin_layout Standard
-\begin_inset Formula \begin{gather}
-\underline{S}\left(t\right)=2\mu_{tot}\left(\mu_{0}\underline{e}\left(t\right)+\mu_{1}\underline{h}^{1}\left(t\right)\right)\,.\label{eq:68}\end{gather}
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Subsection
-Tangent Stress-Strain Relation
-\end_layout
-
-\begin_layout Standard
-In addition to the volumetric contribution to the tangent constitutive matrix,
- we require the deviatoric part:
-\end_layout
-
-\begin_layout Standard
-\begin_inset Formula \begin{gather}
-\frac{\partial\underline{S}}{\partial\underline{\epsilon}}=\frac{\partial\underline{S}}{\partial\underline{e}}\frac{\partial\underline{e}}{\partial\underline{\epsilon}}\,,\label{eq:69}\end{gather}
-
-\end_inset
-
-where the second derivative on the right may be easily deduced from equation
-
-\begin_inset LatexCommand \ref{eq:3}
-
-\end_inset
-
-.
- The other derivative is given by
-\end_layout
-
-\begin_layout Standard
-\begin_inset Formula \begin{gather}
-\frac{\partial\underline{S}}{\partial\underline{e}}=2\mu_{tot}\left[\mu_{0}\underline{I}+\mu_{1}\frac{\partial\underline{h}^{1}}{\partial\underline{e}}\right]\,,\label{eq:70}\end{gather}
-
-\end_inset
-
-where
-\begin_inset Formula $\underline{I}$
-\end_inset
-
- is the identity matrix.
- From equations
-\begin_inset LatexCommand \ref{eq:64}
-
-\end_inset
-
- through
-\begin_inset LatexCommand \ref{eq:66}
-
-\end_inset
-
-, the derivative inside the brackets is
-\end_layout
-
-\begin_layout Standard
-\begin_inset Formula \begin{gather}
-\frac{\partial\underline{h}^{1}}{\partial\underline{e}}=\Delta h\left(\Delta t\right)\underline{I}\,.\label{eq:71}\end{gather}
-
-\end_inset
-
-
-\begin_inset Formula $ $
-\end_inset
-
-The complete deviatoric tangent relation is then
-\end_layout
-
-\begin_layout Standard
-\begin_inset Formula \begin{gather}
-\frac{\partial\underline{S}}{\partial\underline{\epsilon}}=2\mu_{tot}\left[\mu_{0}+\mu_{1}\Delta h\left(\Delta t\right)\right]\frac{\partial\underline{e}}{\partial\underline{\epsilon}}\,.\label{eq:72}\end{gather}
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Section
-Power-Law Maxwell Model (Zienkiewicz and Taylor Formulation)
-\end_layout
-
-\begin_layout Standard
-This material model is identical to the previous power-law model, formulated
- in terms of the creep strain rate:
-\end_layout
-
-\begin_layout Standard
-\begin_inset Formula \begin{gather}
-\underline{\dot{\epsilon}}^{C}=\underline{\beta}\left(\underline{\sigma},\underline{\epsilon}^{C}\right)=\frac{\sqrt{^{\tau}J_{2}^{\prime}}^{n-1}\,^{\tau}\underline{S}}{2\eta^{n}}\,.\label{eq:73}\end{gather}
-
-\end_inset
-
-The stress and creep strain at time step
-\begin_inset Formula $n+1$
-\end_inset
-
- are given by
-\end_layout
-
-\begin_layout Standard
-\begin_inset Formula \begin{gather}
-\underline{\sigma}_{n+1}=\underline{D}\left(\underline{\epsilon}_{n+1}-\underline{\epsilon}_{n+1}^{C}\right)+^{I}\underline{\sigma}\nonumber \\
-\underline{\epsilon}_{n+1}^{C}=\underline{\epsilon}_{n}^{C}+\Delta t\underline{\beta}_{n+\theta}\,,\label{eq:74}\end{gather}
-
-\end_inset
-
-where
-\begin_inset Formula \begin{gather}
-\underline{\beta}_{n+\theta}=\left(1-\theta\right)\underline{\beta}_{n}+\theta\underline{\beta}_{n+1}\,,\label{eq:75}\end{gather}
-
-\end_inset
-
-and
-\begin_inset Formula $\underline{D}$
-\end_inset
-
- is the elasticity matrix.
- This can be arranged into a simple nonlinear equation:
-\end_layout
-
-\begin_layout Standard
-\begin_inset Formula \begin{gather}
-\underline{R}_{n+1}\equiv\underline{\epsilon}_{n+1}-\underline{D}^{-1}\left(\underline{\sigma}_{n+1}-^{I}\underline{\sigma}\right)-\underline{\epsilon}_{n}^{C}-\Delta t\underline{\beta}_{n+\theta}=\underline{0}\,.\label{eq:76}\end{gather}
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-The equations may be solved iteratively using a Newton-Raphson procedure.
- Given an increment of strain determined from the current displacements
- and an initial guess for the stress, an iterative procedure may be written
- as:
-\end_layout
-
-\begin_layout Standard
-\begin_inset Formula \begin{gather}
-\underline{R}^{i+1}=\underline{0}=\underline{R}^{i}-\left(\underline{D}^{-1}+\Delta t\underline{C}_{n+1}\right)d\underline{\sigma}_{n+1}^{i}\,,\label{eq:77}\end{gather}
-
-\end_inset
-
-where
-\end_layout
-
-\begin_layout Standard
-\begin_inset Formula \begin{gather}
-\underline{C}_{n+1}=\frac{\partial\underline{\beta}}{\partial\underline{\sigma}}\Biggl\|_{n+\theta}=\theta\frac{\partial\underline{\beta}}{\partial\underline{\sigma}}\Biggl\|_{n+1}\,.\label{eq:78}\end{gather}
-
-\end_inset
-
-These stresses are obtained using the iterative procedure, and the tangent
- matrix is:
-\end_layout
-
-\begin_layout Standard
-\begin_inset Formula \begin{gather}
-\underline{D}_{n+1}^{*}\equiv\left[\underline{D}^{-1}+\Delta\underline{C}_{n+1}\right]^{-1}\,.\label{eq:79}\end{gather}
-
-\end_inset
-
-
-\end_layout
-
\end_body
\end_document
Modified: short/3D/PyLith/trunk/doc/userguide/runpylith/runpylith.lyx
===================================================================
--- short/3D/PyLith/trunk/doc/userguide/runpylith/runpylith.lyx 2007-06-16 22:41:51 UTC (rev 7275)
+++ short/3D/PyLith/trunk/doc/userguide/runpylith/runpylith.lyx 2007-06-17 03:32:28 UTC (rev 7276)
@@ -61,19 +61,41 @@
\begin_layout Enumerate
Mesh information.
- This includes nodal coordinates, element connectivities, and flagged sets
- of nodes to which boundary conditions can be applied.
- This information can be provided using PyLith ASCII format (***reference***),
- or by importing the information from the LaGriT or CUBIT meshing packages
- (***put in references to tutorials and appendix***).
+ This includes the topology of the finite-element mesh (coordinates of vertices
+ and how the vertices are connected into cells), the material identifier
+ for each cell, and sets of vertices associated with boundary conditions,
+ faults, and output (for subsets of the mesh).
+ This information can be provided using the PyLith Mesh ASCII format (See
+ Chapter
+\begin_inset LatexCommand \ref{cha:Tutorials}
+
+\end_inset
+
+ for examples and Section
+\begin_inset LatexCommand \ref{sec:MeshIOAscii}
+
+\end_inset
+
+ for the format specification) or by importing the information from the
+ LaGriT or CUBIT meshing packages (See Section XX [LaGriT/CUBIT tutorials]).
\end_layout
\begin_layout Enumerate
Databases specifying the material properties and boundary conditions to
be used.
- Arbitrarily complex spatial variations in boundary conditions (including
- fault specifications) and material properties may be given in the spatial
- database (***put in references to tutorials and appendix***).
+ Arbitrarily complex spatial variations in boundary and fault conditions
+ and material properties may be given in the spatial database (See Chapter
+
+\begin_inset LatexCommand \ref{cha:Tutorials}
+
+\end_inset
+
+ for examples and Section
+\begin_inset LatexCommand \ref{sec:Spatialdata:SimpleIOAscii}
+
+\end_inset
+
+ for the format specification).
\end_layout
\begin_layout Section
@@ -681,9 +703,14 @@
\begin_layout Standard
Geometrical and topological information for the finite element mesh may
be provided by exporting an EXODUS format file from CUBIT, by exporting
- a GMV file and an accompanying pset file from LaGriT, or by specifying
- the information in PyLith ASCII format.
- ***Put in references to tutorials and appendix.***
+ a GMV file and an accompanying Pset file from LaGriT, or by specifying
+ the information in PyLith Mesh ASCII format.
+ See Chapter
+\begin_inset LatexCommand \ref{cha:Tutorials}
+
+\end_inset
+
+ for examples.
\end_layout
\begin_layout Standard
@@ -749,7 +776,7 @@
\end_layout
\begin_layout Caption
-Linear bar element available for 1D problems.
+Linear bar element available for 1-D problems.
\end_layout
\begin_layout Standard
@@ -781,7 +808,9 @@
\end_inset
-
+ \InsetSpace ~
+\InsetSpace ~
+
\begin_inset Graphics
filename figs/quad4.eps
@@ -791,7 +820,7 @@
\end_layout
\begin_layout Caption
-Linear elements available for 2D problems are the triangle (left) and the
+Linear elements available for 2-D problems are the triangle (left) and the
quadrilateral (right).
\end_layout
@@ -811,6 +840,7 @@
\begin_layout Standard
\noindent
\align center
+-
\begin_inset Float figure
wide false
sideways false
@@ -823,6 +853,8 @@
\end_inset
+\InsetSpace ~
+\InsetSpace ~
\begin_inset Graphics
filename figs/hex8.eps
@@ -848,7 +880,7 @@
\end_layout
\begin_layout Section
-Boundary Condition and Material Property Databases
+Databases for Boundaries, Interfaces, and Material Properties
\end_layout
\begin_layout Standard
@@ -880,7 +912,7 @@
\begin_inset Quotes erd
\end_inset
-, or 0D variation).
+, or 0-D variation).
A slightly more complex case would be a mesh where the elements of a given
type have properties that vary linearly along a given direction (
\begin_inset Quotes eld
@@ -890,7 +922,7 @@
\begin_inset Quotes erd
\end_inset
-, or 1D variation).
+, or 1-D variation).
In more complex models, the material properties might have different values
at each point in the mesh (
\begin_inset Quotes eld
@@ -900,7 +932,7 @@
\begin_inset Quotes erd
\end_inset
-, or 3D variation).
+, or 3-D variation).
This might be the case, for example, if the material properties are provided
by a database of seismic velocities and densities.
***Provide references***
@@ -916,7 +948,7 @@
\begin_inset Quotes erd
\end_inset
-, or 0D variation).
+, or 0-D variation).
A more complex case might specify a variation in the conditions on a given
surface (
\begin_inset Quotes eld
@@ -926,37 +958,15 @@
\begin_inset Quotes erd
\end_inset
-, or 2D variation).
+, or 2-D variation).
This sort of condition might be used, for example, to specify the variation
of slip on a fault plane.
***Provide references***
-\begin_inset Note Comment
-status open
-
-\begin_layout Standard
-Maybe I should not be mixing
\end_layout
\begin_layout Standard
-together BC and fault info,
-\end_layout
-\begin_layout Standard
-or maybe I should change
\end_layout
-\begin_layout Standard
-the title of this section.
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-
-\end_layout
-
\end_body
\end_document
Modified: short/3D/PyLith/trunk/doc/userguide/tutorials/tutorials.lyx
===================================================================
--- short/3D/PyLith/trunk/doc/userguide/tutorials/tutorials.lyx 2007-06-16 22:41:51 UTC (rev 7275)
+++ short/3D/PyLith/trunk/doc/userguide/tutorials/tutorials.lyx 2007-06-17 03:32:28 UTC (rev 7276)
@@ -37,6 +37,10 @@
\begin_body
\begin_layout Chapter
+\begin_inset LatexCommand \label{cha:Tutorials}
+
+\end_inset
+
Tutorials
\end_layout
More information about the cig-commits
mailing list