Mon Jun 25 09:38:46 PDT 2012

Author: brad
Date: 2012-06-25 09:38:44 -0700 (Mon, 25 Jun 2012)
New Revision: 20404

Added:
   short/3D/PyLith/branches/v1.7-trunk/tests/runtests.sh
Modified:
   short/3D/PyLith/branches/v1.7-trunk/doc/releasenotes/announce_v1.7.1.txt
   short/3D/PyLith/branches/v1.7-trunk/doc/userguide/boundaryconditions/boundaryconditions.lyx
   short/3D/PyLith/branches/v1.7-trunk/doc/userguide/extending/extending.lyx
   short/3D/PyLith/branches/v1.7-trunk/doc/userguide/runpylith/runpylith.lyx
   short/3D/PyLith/branches/v1.7-trunk/doc/userguide/tutorials/3dhex8/dike/dike.lyx
   short/3D/PyLith/branches/v1.7-trunk/doc/userguide/tutorials/3dhex8/friction/friction.lyx
   short/3D/PyLith/branches/v1.7-trunk/doc/userguide/tutorials/3dhex8/quasistatic/quasistatic.lyx
   short/3D/PyLith/branches/v1.7-trunk/doc/userguide/tutorials/3dhex8/surfload/surfload.lyx
   short/3D/PyLith/branches/v1.7-trunk/doc/userguide/tutorials/3dtet4/3dtet4.lyx
   short/3D/PyLith/branches/v1.7-trunk/doc/userguide/tutorials/greensfns2d/greensfns2d.lyx
   short/3D/PyLith/branches/v1.7-trunk/doc/userguide/tutorials/shearwave/hex8.lyx
   short/3D/PyLith/branches/v1.7-trunk/doc/userguide/tutorials/shearwave/quad4.lyx
   short/3D/PyLith/branches/v1.7-trunk/doc/userguide/tutorials/shearwave/shearwave.lyx
   short/3D/PyLith/branches/v1.7-trunk/doc/userguide/tutorials/shearwave/tet4.lyx
   short/3D/PyLith/branches/v1.7-trunk/doc/userguide/tutorials/shearwave/tri3.lyx
   short/3D/PyLith/branches/v1.7-trunk/doc/userguide/tutorials/subduction/subduction.lyx
   short/3D/PyLith/branches/v1.7-trunk/doc/userguide/tutorials/twohex8/twohex8.lyx
   short/3D/PyLith/branches/v1.7-trunk/doc/userguide/tutorials/twoquad4/twoquad4.lyx
   short/3D/PyLith/branches/v1.7-trunk/doc/userguide/tutorials/twotet4-geoproj/twotet4-geoproj.lyx
   short/3D/PyLith/branches/v1.7-trunk/doc/userguide/tutorials/twotet4/twotet4.lyx
   short/3D/PyLith/branches/v1.7-trunk/doc/userguide/tutorials/twotri3/twotri3.lyx
   short/3D/PyLith/branches/v1.7-trunk/doc/userguide/userguide.lyx
   short/3D/PyLith/branches/v1.7-trunk/examples/2d/greensfns/strikeslip/greensfns.cfg
   short/3D/PyLith/branches/v1.7-trunk/examples/3d/hex8/step05.cfg
   short/3D/PyLith/branches/v1.7-trunk/examples/meshing/surface_nurbs/triangles/mkfacets.py
   short/3D/PyLith/branches/v1.7-trunk/examples/twocells/twohex8/dislocation_sliptime.spatialdb
   short/3D/PyLith/branches/v1.7-trunk/examples/twocells/twoquad4/dislocation_sliptime.spatialdb
   short/3D/PyLith/branches/v1.7-trunk/examples/twocells/twotet4-geoproj/dislocation_sliptime.spatialdb
   short/3D/PyLith/branches/v1.7-trunk/examples/twocells/twotet4/dislocation_sliptime.spatialdb
   short/3D/PyLith/branches/v1.7-trunk/examples/twocells/twotri3/dislocation_sliptime.spatialdb
   short/3D/PyLith/branches/v1.7-trunk/libsrc/pylith/faults/FaultCohesiveImpulses.cc
   short/3D/PyLith/branches/v1.7-trunk/libsrc/pylith/faults/FaultCohesiveLagrange.cc
   short/3D/PyLith/branches/v1.7-trunk/pylith/faults/FaultCohesiveImpulses.py
Log:
Merge from stable.

Modified: short/3D/PyLith/branches/v1.7-trunk/doc/releasenotes/announce_v1.7.1.txt
===================================================================

--- short/3D/PyLith/branches/v1.7-trunk/doc/releasenotes/announce_v1.7.1.txt	2012-06-25 04:52:47 UTC (rev 20403)
+++ short/3D/PyLith/branches/v1.7-trunk/doc/releasenotes/announce_v1.7.1.txt	2012-06-25 16:38:44 UTC (rev 20404)
@@ -17,7 +17,7 @@
 We strongly recommend all users of previous PyLith releases switch to
 this latest release. In addition to adding features this release also
 fixes a minor parallel processing bug related to fault friction in
-quasi-static simulations. 
+quasi-static simulations.
 
 See the README file for changes required to switch to the v1.7.x
 release series from previous versions.
@@ -27,8 +27,8 @@
     http://geodynamics.org/cig/software/packages/short/pylith
 
 Detailed installation instructions for the binary packages are in the
-User Manual with detailed building instructions for a few platforms
-in the INSTALL file bundled with the PyLith Installer utility.
+User Manual with detailed building instructions for a few platforms in
+the INSTALL file bundled with the PyLith Installer utility.
 
 
 RELEASE NOTES - PyLith v1.7.1

Modified: short/3D/PyLith/branches/v1.7-trunk/doc/userguide/boundaryconditions/boundaryconditions.lyx
===================================================================
--- short/3D/PyLith/branches/v1.7-trunk/doc/userguide/boundaryconditions/boundaryconditions.lyx	2012-06-25 04:52:47 UTC (rev 20403)
+++ short/3D/PyLith/branches/v1.7-trunk/doc/userguide/boundaryconditions/boundaryconditions.lyx	2012-06-25 16:38:44 UTC (rev 20404)
@@ -1,7860 +1,7860 @@
-#LyX 2.0 created this file. For more info see http://www.lyx.org/
-\lyxformat 413
-\begin_document
-\begin_header
-\textclass book
-\use_default_options false
-\maintain_unincluded_children false
-\language english
-\language_package default
-\inputencoding auto
-\fontencoding global
-\font_roman default
-\font_sans default
-\font_typewriter default
-\font_default_family default
-\use_non_tex_fonts false
-\font_sc false
-\font_osf false
-\font_sf_scale 100
-\font_tt_scale 100
-
-\graphics default
-\default_output_format default
-\output_sync 0
-\bibtex_command default
-\index_command default
-\paperfontsize default
-\spacing single
-\use_hyperref false
-\papersize default
-\use_geometry true
-\use_amsmath 1
-\use_esint 0
-\use_mhchem 1
-\use_mathdots 1
-\cite_engine basic
-\use_bibtopic false
-\use_indices false
-\paperorientation portrait
-\suppress_date false
-\use_refstyle 0
-\index Index
-\shortcut idx
-\color #008000
-\end_index
-\leftmargin 1in
-\topmargin 1in
-\rightmargin 1in
-\bottommargin 1in
-\secnumdepth 3
-\tocdepth 3
-\paragraph_separation indent
-\paragraph_indentation default
-\quotes_language english
-\papercolumns 1
-\papersides 1
-\paperpagestyle default
-\tracking_changes false
-\output_changes false
-\html_math_output 0
-\html_css_as_file 0
-\html_be_strict false
-\end_header
-
-\begin_body
-
-\begin_layout Chapter
-\begin_inset CommandInset label
-LatexCommand label
-name "cha:boundary:interface:conditions"
-
-\end_inset
-
-Boundary and Interface Conditions
-\end_layout
-
-\begin_layout Section
-Assigning Boundary Conditions
-\end_layout
-
-\begin_layout Standard
-There are four basic steps in assigning a specific boundary condition to
- a portion of the domain.
-\end_layout
-
-\begin_layout Enumerate
-Create sets of vertices in the mesh generation process for each boundary
- condition.
-\end_layout
-
-\begin_layout Enumerate
-Define boundary condition groups corresponding to the vertex sets.
-\end_layout
-
-\begin_layout Enumerate
-Set the parameters for each boundary condition group using 
-\family typewriter
-.cfg
-\family default
- or 
-\family typewriter
-.pml
-\family default
- files and/or command line arguments.
-\end_layout
-
-\begin_layout Enumerate
-Specify the spatial variation in parameters for the boundary condition using
- a spatial database file.
-\end_layout
-
-\begin_layout Subsection
-Creating Sets of Vertices
-\end_layout
-
-\begin_layout Standard
-The procedure for creating sets of vertices differs depending on the mesh
- generator.
- For meshes specified using the PyLith mesh ASCII format, the sets of vertices
- are specified using groups (see Appendix 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "sec:MeshIOAscii"
-
-\end_inset
-
-).
- In CUBIT the groups of vertices are created using nodesets.
- Similarly, in LaGriT, psets are used.
- Note that we chose to associated boundary conditions with groups of vertices
- because nearly every mesh generation package supports associating a string
- or integer with groups of vertices.
- Note also that we currently associate boundary conditions with string identifie
-rs, so even if the mesh generator uses integers, the name is specified as
- the digits of the integer value.
- Finally, note that every vertex set that ultimately is associated with
- a boundary condition on a cell face (e.g., Neumann boundary conditions and
- fault interface conditions) must correspond to a simply-connected surface.
-\end_layout
-
-\begin_layout Subsection
-Arrays of Boundary Condition Components
-\end_layout
-
-\begin_layout Standard
-A dynamic array of boundary condition components associates a name (string)
- with each boundary condition.
- This dynamic array of boundary conditions replaces the boundary condition
- container in PyLith 1.0.
- User-defined containers are no longer necessary, and the predefined containers
- are no longer available (or necessary).
- The default boundary condition for each component in the array is the Dirichlet
-Points object.
- Other boundary conditions can be bound to the named items in the array
- via a 
-\family typewriter
-.cfg
-\family default
- file, 
-\family typewriter
-.pml
-\family default
- file, or the command line.
- The parameters for the boundary condition are set using the name of the
- boundary condition.
- An example of setting the array of boundary condition components and changing
- the types of boundary conditions in a 
-\family typewriter
-.cfg
-\family default
- file:
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.problem]
-\end_layout
-
-\begin_layout LyX-Code
-bc = [x_neg,x_pos,y_pos,z_neg] ; Array of boundary conditions
-\end_layout
-
-\begin_layout LyX-Code
-# Default boundary condition is DirichletPoints
-\end_layout
-
-\begin_layout LyX-Code
-# Keep default value for bc.x_neg
-\end_layout
-
-\begin_layout LyX-Code
-bc.x_pos = pylith.bc.DirichletBoundary ; change BC type to DirichletBoundary
-\end_layout
-
-\begin_layout LyX-Code
-bc.y_pos = pylith.bc.AbsorbingDampers ; change BC type to AbsorbingDampers
-\end_layout
-
-\begin_layout LyX-Code
-bc.z_neg = pylith.bc.Neumann ; change BC type to Neumann (traction)
-\end_layout
-
-\begin_layout Section
-\begin_inset CommandInset label
-LatexCommand label
-name "sec:Time:Dependent:BC"
-
-\end_inset
-
-Time-Dependent Boundary Conditions
-\end_layout
-
-\begin_layout Standard
-Several boundary conditions use a common formulation for the spatial and
- temporal variation of the boundary condition parameters,
-\begin_inset Formula 
-\begin{equation}
-f(\vec{x})=f_{0}(\vec{x})+\dot{f}_{0}(\vec{x})(t-t_{0}(\vec{x}))+f_{1}(\vec{x})a(t-t_{1}(\vec{x})),
-\end{equation}
-
-\end_inset
-
-where 
-\begin_inset Formula $f(\vec{x})$
-\end_inset
-
- may be a scalar or vector parameter, 
-\begin_inset Formula $f_{0}(\vec{x})$
-\end_inset
-
- is a constant value, 
-\begin_inset Formula $\dot{f}_{0}(\vec{x})$
-\end_inset
-
- is a constant rate of change in the value, 
-\begin_inset Formula $t_{0}(\vec{x})$
-\end_inset
-
- is the onset time for the constant rate of change, 
-\begin_inset Formula $f_{1}(\vec{x})$
-\end_inset
-
- is the amplitude for the temporal modulation, 
-\begin_inset Formula $a(t)$
-\end_inset
-
- is the variation in amplitude with time, 
-\begin_inset Formula $t_{1}(\vec{x})$
-\end_inset
-
- is the onset time for the temporal modulation, and 
-\begin_inset Formula $\vec{x}$
-\end_inset
-
- is the position of a location in space.
- This common formulation permits easy specification of a scalar or vector
- with a constant value, constant rate of change of a value, and/or modulation
- of a value in time.
- One can specify just the initial value, just the rate of change of the
- value (along with the corresponding onset time), or just the modulation
- in amplitude (along with the corresponding temporal variation and onset
- time), or any combination of the three.
- The facilities associated with this formulation are:
-\end_layout
-
-\begin_layout Description
-db_initial Spatial database specifying the spatial variation in the initial
- value (default is none).
-\end_layout
-
-\begin_layout Description
-db_rate Spatial database specifying rate of change in the value (default
- is none).
-\end_layout
-
-\begin_layout Description
-db_change Spatial database specifying the amplitude of the temporal modulation
- (default is none).
-\end_layout
-
-\begin_layout Description
-th_change Time history database specifying the temporal change in amplitude
- (default is none).
-\end_layout
-
-\begin_layout Subsection
-Dirichlet Boundary Conditions
-\end_layout
-
-\begin_layout Standard
-Dirichlet boundary conditions in PyLith prescribe the displacement of a
- subset of the vertices of the finite-element mesh.
- While Dirichlet boundary conditions can be applied to any vertex, usually
- they are applied to vertices on the lateral and bottom boundaries of the
- domain.
- There are two types of Dirichlet boundary conditions, DirichletBC and Dirichlet
-Boundary.
- Both provide identical constraints on the solution, but DirichletBoundary
- is limited to vertices of a simply-connected surface, which allows diagnostic
- output of the prescribed displacements.
- DirichletBC can be applied to a set of unconnected vertices.
-\end_layout
-
-\begin_layout Subsubsection
-Dirichlet Boundary Condition Parameters
-\end_layout
-
-\begin_layout Standard
-The properties and components common to both the DirichletPoints and DirichletBo
-undary boundary conditions are:
-\end_layout
-
-\begin_layout Description
-label Label of the group of vertices associated with the boundary condition.
-\end_layout
-
-\begin_layout Description
-bc_dof Array of degrees of freedom to be fixed (first degree of freedom
- is 0).
-\end_layout
-
-\begin_layout Standard
-DirichletBoundary contains an additional component:
-\end_layout
-
-\begin_layout Description
-output Manager for output of displacements on boundary with specified displaceme
-nts.
-\end_layout
-
-\begin_layout Standard
-By default the output manager does not output any information.
- The specified displacements and velocities can be output by including ``displac
-ements'' and ``velocities'' in the output manager's 
-\family typewriter
-vertex_info_fields
-\family default
- array parameter.
- An example of setting the Dirichlet boundary condition parameters in a
- 
-\family typewriter
-.cfg
-\family default
- file is:
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.problem]
-\end_layout
-
-\begin_layout LyX-Code
-bc = [mybc]
-\end_layout
-
-\begin_layout LyX-Code
-
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.problem.bc.mybc]
-\end_layout
-
-\begin_layout LyX-Code
-label = group A 
-\end_layout
-
-\begin_layout LyX-Code
-bc_dof = [2] ; fixed displacement in z direction
-\end_layout
-
-\begin_layout LyX-Code
-db_initial = spatialdata.spatialdb.SimpleDB
-\end_layout
-
-\begin_layout LyX-Code
-db_initial.iohandler.filename = disp_A.spatialdb
-\end_layout
-
-\begin_layout LyX-Code
-db_initial.query_type = nearest ; change query type to nearest point algorithm
-\end_layout
-
-\begin_layout LyX-Code
-db_rate = spatialdata.spatialdb.UniformDB
-\end_layout
-
-\begin_layout LyX-Code
-db_rate.values = [displacement-rate-z]
-\end_layout
-
-\begin_layout LyX-Code
-db_rate.data = [1.0e-06*m/s] ; velocity is 1.0e-06 m/s
-\end_layout
-
-\begin_layout Standard
-We have created an array with one boundary condition, mybc.
- The group of vertices associated with the boundary condition is group A.
- For the database associated with the constant displacement, we use a SimpleDB.
- We set the filename and query type for the database.
- For the rate of change of values, we use a UniformDB and specify the velocity
- in the z-direction to be 1.0e-06 m/s.
- See Section 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "sec:spatial:databases"
-
-\end_inset
-
- for a discussion of the different types of spatial databases available.
-\end_layout
-
-\begin_layout Standard
-\noindent
-\align center
-\begin_inset Float table
-placement H
-wide false
-sideways false
-status open
-
-\begin_layout Plain Layout
-\noindent
-\align center
-\begin_inset Caption
-
-\begin_layout Plain Layout
-\begin_inset CommandInset label
-LatexCommand label
-name "tab:dirichlet:output"
-
-\end_inset
-
-Fields available in output of DirichletBoundary boundary condition information.
-\end_layout
-
-\end_inset
-
-
-\begin_inset VSpace defskip
-\end_inset
-
-
-\begin_inset Tabular
-<lyxtabular version="3" rows="6" columns="3">
-<features tabularvalignment="middle">
-<column alignment="center" valignment="top" width="0">
-<column alignment="center" valignment="top" width="0">
-<column alignment="center" valignment="top" width="3in">
-<row>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\series bold
-Field Type
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\series bold
-Field
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\series bold
-Description
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-vertex_info_fields
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-displacement_initial
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Initial displacement field in global coordinate system
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-velocity
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Rate of change of displacement field in global coordinate system
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-velocity_start_time
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Onset time in seconds for rate of change in displacement field
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-displacement_change
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Amplitude of change in displacement field in global coordinate system
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-change_start_time
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Onset time in seconds for the amplitude change in the displacement field
-\end_layout
-
-\end_inset
-</cell>
-</row>
-</lyxtabular>
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Subsubsection
-Dirichlet Boundary Condition Spatial Database Files
-\end_layout
-
-\begin_layout Standard
-The spatial database files for the Dirichlet boundary condition specify
- the fixed displacements.
- The spatial database file may contain displacements at more degrees of
- freedom than those specified in the Dirichlet boundary condition settings
- using the 
-\family typewriter
-bc_dof
-\family default
- setting.
- Only those listed in 
-\family typewriter
-bc_dof
-\family default
- will be used.
- This permits using the same spatial database file for multiple Dirichlet
- boundary conditions with the same displacement field.
-\end_layout
-
-\begin_layout Standard
-\noindent
-\align center
-\begin_inset Float table
-placement H
-wide false
-sideways false
-status open
-
-\begin_layout Plain Layout
-\noindent
-\align center
-\begin_inset Caption
-
-\begin_layout Plain Layout
-Values in the spatial databases used for Dirichlet boundary conditions.
-\end_layout
-
-\end_inset
-
-
-\begin_inset VSpace defskip
-\end_inset
-
-
-\begin_inset Tabular
-<lyxtabular version="3" rows="4" columns="2">
-<features tabularvalignment="middle">
-<column alignment="center" valignment="top" width="0">
-<column alignment="center" valignment="top" width="4in">
-<row>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\series bold
-Spatial database
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\series bold
-Name in Spatial Database
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-db_initial
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-displacement-x, displacement-y, displacement-z
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-db_rate
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-displacement-rate-x, displacement-rate-y, displacement-rate-z, rate-start-time
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-db_change
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-displacement-x, displacement-y, displacement-z, change-start-time
-\end_layout
-
-\end_inset
-</cell>
-</row>
-</lyxtabular>
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Subsection
-Neumann Boundary Conditions
-\end_layout
-
-\begin_layout Standard
-Neumann boundary conditions are surface tractions applied over a subset
- of the mesh.
- As with the DirichletBoundary condition, each Neumann boundary condition
- can only be applied to a simply-connected surface.
- The surface over which the tractions are applied always has a spatial dimension
- that is one less than the dimension of the finite-element mesh.
- Traction values are computed at the integration points of each cell on
- the surface, using values from a spatial database.
- The tractions are integrated over each cell and assembled to obtain the
- forces applied at the vertices.
- See Section 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "sub:Tutorial-twoquad4-traction"
-
-\end_inset
-
- for a tutorial that uses Neumann boundary conditions.
-\end_layout
-
-\begin_layout Subsubsection
-Neumann Boundary Condition Parameters
-\end_layout
-
-\begin_layout Standard
-The Neumann boundary condition properties and components are:
-\end_layout
-
-\begin_layout Description
-label Name of the group of vertices defining the mesh boundary for the Neumann
- boundary condition.
-\end_layout
-
-\begin_layout Description
-up_dir This is a 3-vector that provides a hint for the direction perpendicular
- to the horizontal tangent direction that is not collinear with the direction
- normal to the surface.
- The default value is (0,0,1), which assumes that the z-axis is positive
- upward.
- This vector is only needed for three-dimensional problems where the positive
- upward direction differs from the default.
-\end_layout
-
-\begin_layout Description
-output The output manager associated with diagnostic output (traction vector).
-\end_layout
-
-\begin_layout Description
-quadrature The quadrature object to be used for numerical integration.
- Since we are integrating over a surface that is one dimension lower than
- the problem domain, this would typically be set to something like 
-\family typewriter
-Quadrature2Din3D
-\family default
- (for a three-dimensional problem).
-\end_layout
-
-\begin_layout Standard
-By default the output manager does not output any information.
- The specified tractions can be output in global coordinates by including
- ``tractions'' in the output manager's 
-\family typewriter
-cell_info_fields
-\family default
- array parameter.
- An example of setting these parameters in a 
-\family typewriter
-.cfg
-\family default
- file is:
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.timedependent]
-\end_layout
-
-\begin_layout LyX-Code
-bc = [x_neg,x_pos,y_neg]
-\end_layout
-
-\begin_layout LyX-Code
-bc.x_pos = pylith.bc.Neumann ; Change BC type to Neumann
-\end_layout
-
-\begin_layout LyX-Code
- 
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.timedependent.bc.x_pos]
-\end_layout
-
-\begin_layout LyX-Code
-label = x_pos ; Name of group of vertices for +x boundary
-\end_layout
-
-\begin_layout LyX-Code
-db_initial = spatialdata.spatialdb.SimpleDB
-\end_layout
-
-\begin_layout LyX-Code
-db_initial.label = Neumann BC +x edge
-\end_layout
-
-\begin_layout LyX-Code
-db_initial.iohandler.filename = axialtract.spatialdb
-\end_layout
-
-\begin_layout LyX-Code
-db_initial.query_type = nearest
-\end_layout
-
-\begin_layout LyX-Code
-quadrature.cell = pylith.feassemble.FIATLagrange
-\end_layout
-
-\begin_layout LyX-Code
-quadrature.cell.dimension = 1
-\end_layout
-
-\begin_layout LyX-Code
-quadrature.cell.quad_order = 2
-\end_layout
-
-\begin_layout Standard
-These settings correspond to the example problem described in Section 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "sub:Tutorial-twoquad4-traction"
-
-\end_inset
-
-.
- It is necessary to set the boundary condition type to 
-\family typewriter
-pylith.bc.Neumann
-\family default
-, since the default value is 
-\family typewriter
-Dirichlet
-\family default
-BC.
- Constant tractions are used for this particular problem, so a quadrature
- order of one would have been sufficient; however, for problems involving
- more complex variations (e.g., a linear variation), a quadrature order of
- two will provide more accurate results.
- Note that there is no advantage to specifying an integration order higher
- than two, since linear elements are being used for this problem.
-\end_layout
-
-\begin_layout Standard
-\noindent
-\align center
-\begin_inset Float table
-placement H
-wide false
-sideways false
-status open
-
-\begin_layout Plain Layout
-\noindent
-\align center
-\begin_inset Caption
-
-\begin_layout Plain Layout
-\begin_inset CommandInset label
-LatexCommand label
-name "tab:neumann:output"
-
-\end_inset
-
-Fields available in output of Neumann boundary condition information.
-\end_layout
-
-\end_inset
-
-
-\begin_inset VSpace defskip
-\end_inset
-
-
-\begin_inset Tabular
-<lyxtabular version="3" rows="6" columns="3">
-<features tabularvalignment="middle">
-<column alignment="center" valignment="top" width="0">
-<column alignment="center" valignment="top" width="0">
-<column alignment="center" valignment="top" width="3in">
-<row>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\series bold
-Field Type
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\series bold
-Field
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\series bold
-Description
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-cell_info_fields
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-tracton_initial
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Initial traction field in global coordinate system
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-traction_rate
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Rate of change of traction field in global coordinate system
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-rate_start_time
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Onset time in seconds for rate of change in traction field
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-traction_change
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Amplitude of change in traction field in global coordinate system
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-change_start_time
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Onset time in seconds for the amplitude change in the traction field
-\end_layout
-
-\end_inset
-</cell>
-</row>
-</lyxtabular>
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Subsubsection
-Neumann Boundary Condition Spatial Database Files
-\end_layout
-
-\begin_layout Standard
-The spatial database files for the Neumann boundary condition specify the
- applied tractions.
- The number of traction components is equal to the spatial dimension for
- the problem.
- The tractions are specified in a local coordinate system for the boundary.
- The names of the components of the traction vector are:
-\end_layout
-
-\begin_layout Description
-one-dimensional 
-\family typewriter
-normal
-\end_layout
-
-\begin_layout Description
-two-dimensional 
-\family typewriter
-shear
-\family default
-, 
-\family typewriter
-normal
-\end_layout
-
-\begin_layout Description
-three-dimensional 
-\family typewriter
-horiz-shear
-\family default
-, 
-\family typewriter
-vert-shear
-\family default
-, 
-\family typewriter
-normal
-\end_layout
-
-\begin_layout Standard
-Ambiguities in specifying the shear tractions in 3D problems are resolved
- using the 
-\family typewriter
-up_dir
-\family default
- parameter.
- In the case of a horizontal surface, users will need to pick an alternative
- vector, as the default 
-\family typewriter
-up_dir
-\family default
- would coincide with the normal direction.
- In this case, the orientation for the 
-\family typewriter
-vert-shear-traction
-\family default
- component will correspond to whatever the user specifies for 
-\family typewriter
-up_dir
-\family default
-, rather than the actual vertical direction.
-\end_layout
-
-\begin_layout Standard
-\noindent
-\align center
-\begin_inset Float table
-placement H
-wide false
-sideways false
-status open
-
-\begin_layout Plain Layout
-\noindent
-\align center
-\begin_inset Caption
-
-\begin_layout Plain Layout
-Values in the spatial databases used for Dirichlet boundary conditions in
- three dimensions.
- In one- and two-dimensional problems, the names of the components are slightly
- different as described earlier in this section.
-\end_layout
-
-\end_inset
-
-
-\begin_inset VSpace defskip
-\end_inset
-
-
-\begin_inset Tabular
-<lyxtabular version="3" rows="4" columns="2">
-<features tabularvalignment="middle">
-<column alignment="center" valignment="top" width="0">
-<column alignment="center" valignment="top" width="4in">
-<row>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\series bold
-Spatial database
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\series bold
-Name in Spatial Database
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-db_initial
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-traction-shear-horiz, traction-shear-vert, traction-normal
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-db_rate
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-traction-rate-horiz-shear, traction-rate-vert-shear, traction-rate-normal,
- rate-start-time
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-db_change
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-traction-horiz-shear, traction-vert-shear, traction-normal, change-start-time
-\end_layout
-
-\end_inset
-</cell>
-</row>
-</lyxtabular>
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Subsection
-Point Force Boundary Conditions
-\end_layout
-
-\begin_layout Standard
-Point force boundary conditions in PyLith prescribe the application of point
- forces to a subset of the vertices of the finite-element mesh.
- While point force boundary conditions can be applied to any vertex, usually
- they are applied to vertices on the lateral, top, and bottom boundaries
- of the domain.
-\end_layout
-
-\begin_layout Subsubsection
-Point Force Parameters
-\end_layout
-
-\begin_layout Standard
-The properties and components common to both the DirichletBC and DirichletBounda
-ry boundary conditions are:
-\end_layout
-
-\begin_layout Description
-label Label of the group of vertices associated with the boundary condition.
-\end_layout
-
-\begin_layout Description
-bc_dof Array of degrees of freedom to which forces are applied (first degree
- of freedom is 0).
-\end_layout
-
-\begin_layout Standard
-An example of setting the point force boundary condition parameters in a
- 
-\family typewriter
-.cfg
-\family default
- file is:
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.problem]
-\end_layout
-
-\begin_layout LyX-Code
-bc = [mybc]
-\end_layout
-
-\begin_layout LyX-Code
-bc.mybc = pylith.bc.PointForce
-\end_layout
-
-\begin_layout LyX-Code
-
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.problem.bc.mybc]
-\end_layout
-
-\begin_layout LyX-Code
-label = group A 
-\end_layout
-
-\begin_layout LyX-Code
-bc_dof = [2] ; fixed displacement in z direction
-\end_layout
-
-\begin_layout LyX-Code
-db_initial = spatialdata.spatialdb.SimpleDB
-\end_layout
-
-\begin_layout LyX-Code
-db_initial.iohandler.filename = force_A.spatialdb
-\end_layout
-
-\begin_layout LyX-Code
-db_initial.query_type = nearest ; change query type to nearest point algorithm
-\end_layout
-
-\begin_layout LyX-Code
-db_rate = spatialdata.spatialdb.UniformDB
-\end_layout
-
-\begin_layout LyX-Code
-db_rate.values = [force-rate-z]
-\end_layout
-
-\begin_layout LyX-Code
-db_rate.data = [1.0e+5*newton/s]
-\end_layout
-
-\begin_layout Standard
-We have created an array with one boundary condition, mybc.
- The group of vertices associated with the boundary condition is group A.
- For the database associated with the constant force, we use a SimpleDB.
- We set the filename and query type for the database.
- For the rate of change of values, we use a UniformDB and specify the rate
- of change in the force to be 1.0e+5 Newton/s.
- See Section 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "sec:spatial:databases"
-
-\end_inset
-
- for a discussion of the different types of spatial databases available.
-\end_layout
-
-\begin_layout Subsubsection
-Point Force Spatial Database Files
-\end_layout
-
-\begin_layout Standard
-The spatial database files for the Dirichlet boundary condition specify
- the fixed displacements.
- The spatial database file may contain displacements at more degrees of
- freedom than those specified in the Dirichlet boundary condition settings
- using the 
-\family typewriter
-bc_dof
-\family default
- setting.
- Only those listed in 
-\family typewriter
-bc_dof
-\family default
- will be used.
- This permits using the same spatial database file for multiple Dirichlet
- boundary conditions with the same displacement field.
-\end_layout
-
-\begin_layout Standard
-\noindent
-\align center
-\begin_inset Float table
-placement H
-wide false
-sideways false
-status open
-
-\begin_layout Plain Layout
-\noindent
-\align center
-\begin_inset Caption
-
-\begin_layout Plain Layout
-Values in the spatial databases used for point force boundary conditions.
-\end_layout
-
-\end_inset
-
-
-\begin_inset VSpace defskip
-\end_inset
-
-
-\begin_inset Tabular
-<lyxtabular version="3" rows="4" columns="2">
-<features tabularvalignment="middle">
-<column alignment="center" valignment="top" width="0">
-<column alignment="center" valignment="top" width="4in">
-<row>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\series bold
-Spatial database
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\series bold
-Name in Spatial Database
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-db_initial
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-force-x, force-y, force-z
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-db_rate
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-force-rate-x, force-rate-y, force-rate-z, rate-start-time
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-db_change
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-force-x, force-y, force-z, change-start-time
-\end_layout
-
-\end_inset
-</cell>
-</row>
-</lyxtabular>
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Section
-\begin_inset CommandInset label
-LatexCommand label
-name "sec:absorbing:boundaries"
-
-\end_inset
-
-Absorbing Boundary Conditions
-\end_layout
-
-\begin_layout Standard
-This boundary condition attempts to prevent seismic waves reflecting off
- of a boundary by placing simple dashpots on the boundary.
- Normally incident dilatational and shear waves are perfectly absorbed.
- Waves incident at other angles are only partially absorbed.
- This boundary condition is simpler than a perfectly matched layer (PML)
- boundary condition but does not perform quite as well, especially for surface
- waves.
- If the waves arriving at the absorbing boundary are relatively small in
- amplitude compared to the amplitudes of primary interest, this boundary
- condition gives reasonable results.
-\end_layout
-
-\begin_layout Standard
-The Absorbing boundary condition properties and components are:
-\end_layout
-
-\begin_layout Description
-label Name of the group of vertices defining the mesh boundary for the absorbing
- boundary condition.
-\end_layout
-
-\begin_layout Description
-up_dir This is a 3-vector that provides a hint for the direction perpendicular
- to the horizontal tangent direction that is not collinear with the direction
- normal to the surface.
- The default value is (0,0,1), which assumes that the z-axis is positive
- upward.
- This vector is only needed for three-dimensional problems where the positive
- upward direction differs from the default.
-\end_layout
-
-\begin_layout Description
-db The spatial database specifying the material properties for the seismic
- velocities.
-\end_layout
-
-\begin_layout Description
-quadrature The quadrature object to be used for numerical integration.
- Since we are integrating over a surface that is one dimension lower than
- the problem domain, this would typically be set to something like 
-\family typewriter
-Quadrature2Din3D
-\family default
- (for a three-dimensional problem).
-\end_layout
-
-\begin_layout Subsection
-Finite-Element Implementation of Absorbing Boundary
-\end_layout
-
-\begin_layout Standard
-Consider a plane wave propagating at a velocity 
-\begin_inset Formula $c$
-\end_inset
-
-.
- We can write the displacement field as
-\begin_inset Formula 
-\begin{equation}
-\vec{u}(\vec{x},t)=\vec{u^{t}}(t-\frac{\vec{x}}{c}),
-\end{equation}
-
-\end_inset
-
-where 
-\begin_inset Formula $\vec{x}$
-\end_inset
-
- is position, 
-\begin_inset Formula $t$
-\end_inset
-
- is time, and 
-\begin_inset Formula $\vec{u^{t}}$
-\end_inset
-
- is the shape of the propagating wave.
- For an absorbing boundary we want the traction on the boundary to be equal
- to the traction associated with wave propagating out of the domain.
- Starting with the expression for the traction on a boundary, 
-\begin_inset Formula $T_{i}=\sigma_{ij}n_{j},$
-\end_inset
-
- and using the local coordinate system for the boundary 
-\begin_inset Formula $s_{h}s_{v}n,$
-\end_inset
-
- where 
-\begin_inset Formula $\vec{n}$
-\end_inset
-
- is the direction normal to the boundary, 
-\begin_inset Formula $\overrightarrow{s}_{h}$
-\end_inset
-
- is the horizontal direction tangent to the boundary, and 
-\begin_inset Formula $\overrightarrow{s}_{v}$
-\end_inset
-
- is the vertical direction tangent to the boundary, the tractions on the
- boundary are
-\begin_inset Formula 
-\begin{gather}
-T_{s_{h}}=\sigma_{s_{h}n}\\
-T_{s_{v}}=\sigma_{s_{v}n}\\
-T_{n}=\sigma_{nn}.
-\end{gather}
-
-\end_inset
-
-In the case of a horizontal boundary, we can define an auxiliary direction
- in order to assign unique tangential directions.
- For a linear elastic isotropic material, 
-\begin_inset Formula $\sigma_{ij}=\lambda\epsilon_{kk}\delta_{ij}+2\mu\epsilon_{ij},$
-\end_inset
-
- and we can write the tractions as 
-\begin_inset Formula 
-\begin{gather}
-T_{s_{h}}=2\mu\epsilon_{s_{h}n}\\
-T_{s_{v}}=2\epsilon_{s_{v}n}\\
-T_{n}=(\lambda+2\mu)\epsilon_{nn}+\lambda(\epsilon_{s_{h}s_{h}}+\epsilon_{s_{v}s_{v}}).
-\end{gather}
-
-\end_inset
-
-For infinitesimal strains, 
-\begin_inset Formula $\epsilon_{ij}=\frac{1}{2}(u_{i,j}+u_{j,i})$
-\end_inset
-
- and we have
-\begin_inset Formula 
-\begin{gather}
-\epsilon_{s_{h}n}=\frac{1}{2}(u_{s_{h},n}+u_{n,s_{h}})\\
-\epsilon_{s_{v}n}=\frac{1}{2}(u_{s_{v},n}+u_{n,s_{v}})\\
-\epsilon_{nn}=u_{n,n}.
-\end{gather}
-
-\end_inset
-
-For our propagating plane wave, we recognize that
-\begin_inset Formula 
-\begin{equation}
-\frac{\partial\vec{u^{t}}(t-\frac{\vec{x}}{c})}{\partial x_{i}}=-\frac{1}{c}\frac{\partial\vec{u^{t}}(t-\frac{\vec{x}}{c})}{\partial t},
-\end{equation}
-
-\end_inset
-
-so that our expressions for the tractions become
-\begin_inset Formula 
-\begin{gather}
-T_{s_{h}}=-\frac{\mu}{c}\left(\frac{\partial u_{s_{h}}^{t}(t-\frac{\vec{x}}{c})}{\partial t}+\frac{\partial u_{n}^{t}(t-\frac{\vec{x}}{c})}{\partial t}\right),\\
-T_{s_{v}}=-\frac{\mu}{c}\left(\frac{\partial u_{s_{v}}^{t}(t-\frac{\vec{x}}{c})}{\partial t}+\frac{\partial u_{n}^{t}(t-\frac{\vec{x}}{c})}{\partial t}\right).
-\end{gather}
-
-\end_inset
-
-For the normal traction, consider a dilatational wave propagating normal
- to the boundary at speed 
-\begin_inset Formula $v_{p}$
-\end_inset
-
-; in this case 
-\begin_inset Formula $u_{s_{h}}=u_{s_{v}}=0$
-\end_inset
-
- and 
-\begin_inset Formula $c=v_{p}$
-\end_inset
-
-.
- For the shear tractions, consider a shear wave propagating normal to the
- boundary at speed 
-\begin_inset Formula $v_{s}$
-\end_inset
-
-; we can decompose this into one case where 
-\begin_inset Formula $u_{n}=u_{s_{v}}=0$
-\end_inset
-
- and another case where 
-\begin_inset Formula $u_{n}=u_{s_{h}}=0$
-\end_inset
-
-, with 
-\begin_inset Formula $c=v_{s}$
-\end_inset
-
- in both cases.
- We also recognize that 
-\begin_inset Formula $\mu=\rho v_{s}^{2}$
-\end_inset
-
- and 
-\begin_inset Formula $\lambda+2\mu=\rho v_{p}^{2}$
-\end_inset
-
-.
- This leads to the following expressions for the tractions:
-\begin_inset Formula 
-\begin{gather}
-T_{s_{h}}=-\rho v_{s}\frac{\partial u_{s_{h}}^{t}(t-\frac{\vec{x}}{c})}{\partial t}\\
-T_{s_{v}}=-\rho v_{s}\frac{\partial u_{v}^{t}(t-\frac{\vec{x}}{c})}{\partial t}\\
-T_{n}=-\rho v_{p}\frac{\partial u_{n}^{t}(t-\frac{\vec{x}}{c})}{\partial t}
-\end{gather}
-
-\end_inset
-
-We write the weak form of the boundary condition as
-\begin_inset Formula 
-\[
-\int_{S_{T}}T_{i}\phi_{i}\, dS=\int_{S_{T}}-\rho c_{i}\frac{\partial u_{i}}{\partial t}\phi_{i}\, dS,
-\]
-
-\end_inset
-
-where 
-\begin_inset Formula $c_{i}$
-\end_inset
-
- equals 
-\begin_inset Formula $v_{p}$
-\end_inset
-
- for the normal traction and 
-\begin_inset Formula $v_{s}$
-\end_inset
-
- for the shear tractions, and 
-\begin_inset Formula $\phi_{i}$
-\end_inset
-
- is our weighting function.
- We express the trial solution and weighting function as linear combinations
- of basis functions,
-\begin_inset Formula 
-\begin{gather}
-u_{i}=\sum_{m}a_{i}^{m}N^{m},\\
-\phi_{i}=\sum_{n}c_{i}^{n}N^{n}.
-\end{gather}
-
-\end_inset
-
-Substituting into our integral over the absorbing boundaries yields
-\end_layout
-
-\begin_layout Standard
-\begin_inset Formula 
-\begin{equation}
-\int_{S_{T}}T_{i}\phi_{i}\, dS=\int_{S_{T}}-\rho c_{i}\sum_{m}\dot{a}_{i}^{m}N^{m}\sum_{n}c_{i}^{n}N^{n}\, dS.
-\end{equation}
-
-\end_inset
-
-In the derivation of the governing equations, we recognized that the weighting
- function is arbitrary, so we form the residual by setting the terms associated
- with the coefficients 
-\begin_inset Formula $c_{i}^{n}$
-\end_inset
-
- to zero,
-\end_layout
-
-\begin_layout Standard
-\begin_inset Formula 
-\begin{equation}
-r_{i}^{n}=\sum_{\text{tract cells}}\sum_{\text{quad pts}}-\rho(x_{q})c_{i}(x_{q})\sum_{m}\dot{a}_{i}^{m}N^{m}(x_{q})N^{n}(x_{q})w_{q}|J_{cell}(x_{q})|,
-\end{equation}
-
-\end_inset
-
- where 
-\begin_inset Formula $x_{q}$
-\end_inset
-
- are the coordinates of the quadrature points, 
-\begin_inset Formula $w_{q}$
-\end_inset
-
- are the weights of the quadrature points, and 
-\begin_inset Formula $|J_{cell}(x_{q})|$
-\end_inset
-
- is the determinant of the Jacobian matrix evaluated at the quadrature points
- associated with mapping the reference cell to the actual cell.
-\end_layout
-
-\begin_layout Standard
-The appearance of velocity in the expression for the residual means that
- the absorbing dampers also contribute to the system Jacobian matrix.
- Use the central difference method, the velocity is written in terms of
- the displacements,
-\end_layout
-
-\begin_layout Standard
-\begin_inset Formula 
-\begin{equation}
-\dot{u}_{i}(t)=\frac{1}{2\Delta t}(u_{i}(t+\Delta t)-u_{i}(t-\Delta t)).
-\end{equation}
-
-\end_inset
-
-Expressing the displacement at time 
-\begin_inset Formula $t+\Delta t$
-\end_inset
-
- in terms of the displacement at time 
-\begin_inset Formula $t$
-\end_inset
-
- (
-\begin_inset Formula $u_{i}(t)$
-\end_inset
-
-) and the increment in the displacement at time 
-\begin_inset Formula $t$
-\end_inset
-
- (
-\begin_inset Formula $du_{i}(t)$
-\end_inset
-
-) leads to
-\end_layout
-
-\begin_layout Standard
-\begin_inset Formula 
-\begin{equation}
-\dot{u}_{i}(t)=\frac{1}{2\Delta t}(du_{i}(t)+u_{i}(t)-u_{i}(t-\Delta t))
-\end{equation}
-
-\end_inset
-
-The terms contributing to the system Jacobian are associated with the increment
- in the displacement at time time.
- Substituting into the governing equations and isolating the term associated
- with the increment in the displacement at time t yields
-\end_layout
-
-\begin_layout Standard
-\begin_inset Formula 
-\begin{equation}
-A_{ij}^{nm}=\sum_{\text{tract cells}}\sum_{\text{quad pts}}\delta_{ij}\frac{1}{2\Delta t}\rho(x_{q})v_{i}(x_{q})N^{m}(x_{q})N^{n}(x_{q})w_{q}|J_{cells}(x_{q})|,
-\end{equation}
-
-\end_inset
-
-where 
-\begin_inset Formula $A_{ij}^{mn}$
-\end_inset
-
- is a 
-\begin_inset Formula $nd$
-\end_inset
-
- by 
-\begin_inset Formula $md$
-\end_inset
-
- matrix (
-\begin_inset Formula $d$
-\end_inset
-
- is the dimension of the vector space), 
-\begin_inset Formula $m$
-\end_inset
-
- and 
-\begin_inset Formula $n$
-\end_inset
-
- refer to the basis functions and 
-\begin_inset Formula $i$
-\end_inset
-
- and 
-\begin_inset Formula $j$
-\end_inset
-
- are vector space components.
-\end_layout
-
-\begin_layout Section
-\begin_inset CommandInset label
-LatexCommand label
-name "sec:fault"
-
-\end_inset
-
-Fault Interface Conditions
-\end_layout
-
-\begin_layout Standard
-Fault interfaces are used to create dislocations (jumps in the displacement
- field) in the model.
- The dislocations arise from slip across a fault surface.
- Both shear and tensile dislocations are supported.
- For fault interfaces, dislocations in 1D correspond to fault-opening (and
- closing), in 2D lateral-slip and fault opening, and in 3D lateral-slip,
- reverse-slip, and fault opening.
- PyLith supports kinematic (prescribed) slip and dynamic (spontaneous) rupture
- simulations.
-\end_layout
-
-\begin_layout Subsection
-Conventions
-\end_layout
-
-\begin_layout Standard
-Slip corresponds to relative motion across a fault surface.
- Figure 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "fig:fault:orientation"
-
-\end_inset
-
- shows the orientation of the slip vector in 3D with respect to the fault
- surface and coordinate axes.
- PyLith automatically determines the orientation of the fault surface.
- This alleviates the user from having to compute the strike, dip, and rake
- angles over potentially complex, nonplanar fault surfaces.
- Instead, the user specifies fault parameters in terms of lateral motion,
- reverse motion, and fault opening as shown in Figure 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "fig:fault:slip:motions"
-
-\end_inset
-
-.
-\end_layout
-
-\begin_layout Standard
-\noindent
-\align center
-\begin_inset Float figure
-placement H
-wide false
-sideways false
-status open
-
-\begin_layout Plain Layout
-\align center
-\begin_inset Graphics
-	filename figs/faultOrientation.eps
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Plain Layout
-\begin_inset Caption
-
-\begin_layout Plain Layout
-Orientation of a fault surface in 3D, where 
-\begin_inset Formula $\phi$
-\end_inset
-
- denotes the angle of the fault strike, 
-\begin_inset Formula $\delta$
-\end_inset
-
- denotes the angle of the fault dip, and 
-\begin_inset Formula $\lambda$
-\end_inset
-
- the rake angle.
- 
-\begin_inset CommandInset label
-LatexCommand label
-name "fig:fault:orientation"
-
-\end_inset
-
- 
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-\noindent
-\align center
-\begin_inset Float figure
-placement H
-wide false
-sideways false
-status open
-
-\begin_layout Plain Layout
-\align center
-\begin_inset Graphics
-	filename figs/slipmotions.eps
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Plain Layout
-\begin_inset Caption
-
-\begin_layout Plain Layout
-Sign conventions associated with fault slip.
- Positive values are associated with left-lateral, reverse, and fault opening
- motions.
-\begin_inset CommandInset label
-LatexCommand label
-name "fig:fault:slip:motions"
-
-\end_inset
-
- 
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Subsection
-Fault Implementation
-\end_layout
-
-\begin_layout Standard
-In order to create relative motion across the fault surface in the finite-elemen
-t mesh, additional degrees of freedom are added along with adjustment of
- the topology of the mesh.
- These additional degrees of freedom are associated with cohesive cells.
- These zero-volume cells allow control of the relative motion between vertices
- on the two sides of the fault.
- PyLith automatically adds cohesive cells for each fault surface.
- Figure 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "fig:fault:cohesive:quad4"
-
-\end_inset
-
- illustrates the results of inserting a cohesive cell in a mesh consisting
- of two quadrilateral cells.
-\end_layout
-
-\begin_layout Standard
-\noindent
-\align center
-\begin_inset Float figure
-placement H
-wide false
-sideways false
-status open
-
-\begin_layout Plain Layout
-\align center
-\begin_inset Graphics
-	filename figs/quad4cohesivekin.eps
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Plain Layout
-\begin_inset Caption
-
-\begin_layout Plain Layout
-Example of cohesive cell inserted into a mesh of two quadrilateral cells.
- The zero thickness cohesive cell (shown with dashed lines) controls slip
- on the fault via the relative motion between vertices 3 and 7 and 2 and
- 6.
-\begin_inset CommandInset label
-LatexCommand label
-name "fig:fault:cohesive:quad4"
-
-\end_inset
-
- 
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Subsection
-Fault Parameters
-\end_layout
-
-\begin_layout Standard
-The principal parameters for fault interface conditions are:
-\end_layout
-
-\begin_layout Description
-id This is an integer identifier for the fault surface.
- It is used to specify the 
-\family typewriter
-material-id
-\family default
- of the cohesive cells in the mesh.
- Material identifiers must be unique so this value cannot be the same as
- any of the material models or any other fault.
-\end_layout
-
-\begin_layout Description
-name Name or label for the fault.
- This associates sets of vertices with the fault surface in addition to
- being used in error and diagnostic reports.
-\end_layout
-
-\begin_layout Description
-up_dir Up-dir or up direction (used in 2D and 3D simulations).
- In 2D the default in-plane slip is left-lateral, so we use the up-direction
- to resolve the ambiguity in specifying reverse slip.
- In 3D the up-direction is used to resolve the ambiguity in the along-strike
- and dip-dir directions.
- If the fault plane is horizontal, then the up-dir corresponds to the reverse-mo
-tion on the +z side of the fault.
- The only requirement for this direction is that it not be collinear with
- the fault normal direction.
- The default value of [0, 0, 1] is appropriate for most 3D problems.
-\end_layout
-
-\begin_layout Description
-quadrature Quadrature object used in integrating fault quantities.
-\end_layout
-
-\begin_layout Description
-output Manager for output of diagnostic and data fields for the fault.
-\end_layout
-
-\begin_layout Standard
-By default the output manager outputs both diagnostic information (e.g., fault
- normal direction) and the slip at each time step.
- Tables 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "tab:fault:kin:output"
-
-\end_inset
-
- and 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "tab:fault:dyn:output"
-
-\end_inset
-
- list the fields available for output for a fault with kinematic (prescribed)
- earthquake rupture and a fault with dynamic rupture, respectively.
- The fault coordinate system is shown in Figure 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "fig:fault:slip:motions"
-
-\end_inset
-
-.
- The vectors in the fault coordinate system can be transformed to the global
- coordinate system using the direction vectors in the diagnostic output.
- An example of setting these parameters in a 
-\family typewriter
-.cfg
-\family default
- file is:
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.problem]
-\end_layout
-
-\begin_layout LyX-Code
-interfaces = [fault]
-\end_layout
-
-\begin_layout LyX-Code
-
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.problem.interfaces]
-\end_layout
-
-\begin_layout LyX-Code
-fault = pylith.faults.FaultCohesiveKin ; default
-\end_layout
-
-\begin_layout LyX-Code
-
-\end_layout
-
-\begin_layout LyX-Code
-label = fault A ; Group of vertices defining the fault surface
-\end_layout
-
-\begin_layout LyX-Code
-id = 100 ; Value for material identifier associated with fault's cohesive
- cells
-\end_layout
-
-\begin_layout LyX-Code
-up_dir = [0, 0, 1] ; default
-\end_layout
-
-\begin_layout LyX-Code
-quadrature.cell = pylith.feassemble.FIATLagrange
-\end_layout
-
-\begin_layout LyX-Code
-quadrature.cell.dimension = 2
-\end_layout
-
-\begin_layout Standard
-The group of vertices has the label ``fault A.'' We replicate the default
- values for the fault ``up'' direction.
- These settings apply to a 2D fault surface embedded within a 3D mesh, so
- we use 2D Lagrange reference cells.
- The spatial database for elastic properties is used to determine the approximat
-e shear modulus and condition the equations for faster convergence rates.
-\end_layout
-
-\begin_layout Subsection
-Kinematic Earthquake Rupture
-\end_layout
-
-\begin_layout Standard
-Kinematic earthquake ruptures use the FaultCohesiveKin object to specify
- the slip as a function of time on the fault surface.
- Slip may evolve simultaneously over the fault surface instantaneously in
- a single time step (as is usually done in quasi-static simulations) or
- propagate over the fault surface over hundreds and up to thousands of time
- steps (as is usually done in a dynamic simulation).
-\end_layout
-
-\begin_layout Subsubsection
-Governing Equations
-\end_layout
-
-\begin_layout Standard
-The insertion of cohesive cells into the finite-element mesh has the effect
- of decoupling the motion of the two sides of the fault surface.
- In order to impose the desired relative motion, we must adjust the governing
- equations.
- PyLith employs Lagrange multiplier constraints to enforce the constraint
- of the relative motion in the strong sense.
- That is, we enforce the slip across the fault at each degree of freedom.
-\end_layout
-
-\begin_layout Standard
-In conventional implementations the additional degrees of freedom associated
- with the Lagrange multipliers results in a complex implementation.
- However, the use of Lagrange multiplier constraints with cohesive cells
- provides for a simple formulation; we simply add the additional degrees
- of freedom associated with the Lagrange multipliers to the cohesive cells
- as shown in Figure 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "fig:fault:cohesive:quad4"
-
-\end_inset
-
-.
- As a result, the fault implementation is completely confined to the cohesive
- cell.
- Furthermore, the Lagrange multiplier constraints correspond to forces required
- to impose the relative motions, so they are related to the change in stress
- on the fault surface associated with fault slip.
- If we write the algebraic system of equations we are solving in the form
-\begin_inset Formula 
-\begin{equation}
-\underline{A}\overrightarrow{u}=\overrightarrow{b}\,,
-\end{equation}
-
-\end_inset
-
-then including the Lagrange multiplier constraints results in
-\begin_inset Formula 
-\begin{equation}
-\left[\begin{array}{cc}
-\underline{A} & \underline{C}^{T}\\
-\underline{C} & 0
-\end{array}\right]\left[\begin{array}{c}
-\overrightarrow{u}\\
-\overrightarrow{l}
-\end{array}\right]=\left[\begin{array}{c}
-\overrightarrow{b}\\
-\overrightarrow{d}
-\end{array}\right]\,,\label{eq:fault:cohesive:lagrange}
-\end{equation}
-
-\end_inset
-
-where 
-\begin_inset Formula $\overrightarrow{l}$
-\end_inset
-
- is the vector of Lagrange multipliers and 
-\begin_inset Formula $\underline{C}$
-\end_inset
-
- is composed of rotation submatrices, 
-\begin_inset Formula $\underline{R}$
-\end_inset
-
-, associated with the direction cosines relating the relative displacements
- across the fault to the vector of fault slip, 
-\begin_inset Formula $\overrightarrow{d}$
-\end_inset
-
-.
- Note that by using the direction cosines to relate the relative motion
- across the fault, the slip vector and Lagrange multipliers (forces required
- to impose the slip) are in the local fault coordinate system (lateral motion,
- reverse motion, and fault opening).
- 
-\end_layout
-
-\begin_layout Paragraph
-Non-diagonal A
-\end_layout
-
-\begin_layout Standard
-The Lagrange multipliers contribute to both the system Jacobian matrix and
- the residual.
- Because we enforce the constraints in a strong sense, the terms do not
- involve integrals over the fault surface.
- The additional terms in the residual are
-\begin_inset Formula 
-\begin{gather}
-r_{i}^{n}=-C_{ji}^{pn}l_{j}^{p},\\
-r_{i}^{p}=d_{i}^{p}-C_{ij}^{pn}u_{j}^{n},
-\end{gather}
-
-\end_inset
-
-where 
-\begin_inset Formula $n$
-\end_inset
-
- denotes a conventional degree of freedom and 
-\begin_inset Formula $p$
-\end_inset
-
- denotes a degree of freedom associated with a Lagrange multiplier.
- The additional terms in the system Jacobian matrix are simply the direction
- cosines,
-\begin_inset Formula 
-\begin{gather}
-J_{ij}^{np}=C_{ji}^{pn},\\
-J_{ij}^{pn}=C_{ij}^{pn}.
-\end{gather}
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Paragraph
-Diagonal A
-\end_layout
-
-\begin_layout Standard
-When we use a lumped system Jacobian matrix, we cannot lump the terms associated
- with the Lagrange multipliers.
- Instead, we formulate the Jacobian ignoring the contributions from the
- Lagrange multipliers, and then adjust the solution after the solve to account
- for their presence.
- Including the Lagrange multipliers in the general expression for the residual
- at time 
-\begin_inset Formula $t+\Delta t$
-\end_inset
-
-, we have
-\begin_inset Formula 
-\begin{equation}
-r_{i}^{n}(t+\Delta t)=A_{ij}^{nm}(u_{j}^{m}(t)+du_{j}^{m}(t))+C_{ki}^{pn}(l_{k}^{p}(t)+dl_{k}^{p}(t)),
-\end{equation}
-
-\end_inset
-
-where we have written the displacements and Lagrange multipliers at time
- 
-\begin_inset Formula $t+\Delta t$
-\end_inset
-
- in terms of the values at time 
-\begin_inset Formula $t$
-\end_inset
-
- and the increment from time 
-\begin_inset Formula $t$
-\end_inset
-
- to 
-\begin_inset Formula $t+\Delta t$
-\end_inset
-
-.
- When we solve the lumped system ignoring the Lagrange multipliers contributions
- to the Jacobian, we formulate the residual assuming the values 
-\begin_inset Formula $du_{i}^{n}$
-\end_inset
-
-(t) and 
-\begin_inset Formula $dl_{k}^{p}(t)$
-\end_inset
-
- are zero.
- So our task is to determine the increment in the Lagrange multiplier, 
-\begin_inset Formula $dl_{k}^{p}$
-\end_inset
-
-, and the correction to the displacement increment, 
-\begin_inset Formula $du_{i}^{n}$
-\end_inset
-
-, and by setting the residual with all terms included to zero; thus, we
- have
-\begin_inset Formula 
-\begin{gather}
-A_{ij}^{nm}(u_{j}^{m}(t)+du_{j}^{m}(t))+C_{ki}^{pn}(l_{k}^{p}(t)+dl_{k}^{p}(t))=0\text{ subject to}\\
-C_{ij}^{pn}(u_{j}^{n}(t)+du_{j}^{n}(t))=d_{i}^{p}.
-\end{gather}
-
-\end_inset
-
-Making use of the residual computed with 
-\begin_inset Formula $du_{i}^{n}(t)=0$
-\end_inset
-
- and 
-\begin_inset Formula $dl_{k}^{p}(t)=0$
-\end_inset
-
-,
-\begin_inset Formula 
-\begin{gather}
-r_{i}^{n}+A_{ij}^{nm}du_{j}^{m}+C_{ki}^{pn}dl_{k}^{p}=0\text{ subject to}\\
-C_{ij}^{pn}(u_{j}^{n}(t)+du_{j}^{n}(t))=d_{i}^{p}.
-\end{gather}
-
-\end_inset
-
-Explicitly writing the equations for the vertices on the negative and positive
- sides of the fault yields
-\begin_inset Formula 
-\begin{gather}
-r_{i}^{n-}+A_{ij}^{nm-}du_{j}^{m-}+R_{ki}^{pn}dl_{k}^{p}=0,\\
-r_{i}^{n+}+A_{ij}^{nm+}du_{j}^{m+}+R_{ki}^{pn}dl_{k}^{p}=0,\\
-R_{ij}^{pn}(u_{j}^{n+}+du_{j}^{n+}-u_{j}^{n-}-du_{j}^{n-})=d_{i}^{p}.
-\end{gather}
-
-\end_inset
-
-Solving the first two equations for 
-\begin_inset Formula $du_{j}^{m-}$
-\end_inset
-
- and 
-\begin_inset Formula $du_{j}^{m+}$
-\end_inset
-
- and combining them using the third equation leads to
-\begin_inset Formula 
-\begin{multline}
-R_{ij}^{pn}\left((A_{ij}^{nm+})^{-1}+(A_{ij}^{nm+})^{-1}\right)R_{ki}^{pn}dl_{k}^{p}=d_{i}^{p}-R_{ij}^{pn}(u_{j}^{n+}-u_{j}^{n-})\\
-+R_{ij}^{pn}\left((A_{ij}^{nm+})^{-1}r_{i}^{n+}-(A_{ij}^{nm-})^{-1}r_{i}^{n-}\right).
-\end{multline}
-
-\end_inset
-
-We do not allow overlap between the fault interface and the absorbing boundary,
- so 
-\begin_inset Formula $A_{ij}^{nm}$
-\end_inset
-
- is the same for all components at a vertex.
- As a result the matrix on the left hand side simplifies to
-\begin_inset Formula 
-\begin{equation}
-S_{ik}^{pn}=\delta_{ik}\left(\frac{1}{A^{nm+}}+\frac{1}{A^{nm-}}\right),
-\end{equation}
-
-\end_inset
-
-and
-\begin_inset Formula 
-\begin{equation}
-dl_{k}^{p}=(S_{ik}^{pn})^{-1}\left(d_{i}^{p}-R_{ij}^{pn}(u_{j}^{n+}-u_{j}^{n-})+R_{ij}^{pn}\left((A_{ij}^{nm+})^{-1}r_{i}^{n+}-(A_{ij}^{nm-})^{-1}r_{i}^{n-}\right)\right).
-\end{equation}
-
-\end_inset
-
-Now that we know the value of the increment in the Lagrange multiplier from
- time 
-\begin_inset Formula $t$
-\end_inset
-
- to time 
-\begin_inset Formula $t+\Delta t$
-\end_inset
-
-, we can correct the value for the displacement increment from time 
-\begin_inset Formula $t$
-\end_inset
-
- to 
-\begin_inset Formula $t+\Delta t$
-\end_inset
-
- using
-\begin_inset Formula 
-\begin{gather}
-\Delta du_{j}^{n-}=(A_{ij}^{nm-})^{-1}C_{ki}^{pn}dl_{k}^{p}\text{ and}\\
-\Delta du_{j}^{n+}=-(A_{ij}^{nm+})^{-1}C_{ki}^{pn}dl_{k}^{p}.
-\end{gather}
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Subsubsection
-Arrays of Kinematic Rupture Components
-\end_layout
-
-\begin_layout Standard
-Multiple earthquake ruptures can be specified on a single fault surface.
- This permits repeatedly rupturing the same portion of a fault or combining
- earthquake rupture on one subset of the fault surface with steady aseismic
- slip on another subset (the two subsets may overlap in both time and space).
- A dynamic array of kinematic earthquake rupture components associates a
- name (string) with each kinematic rupture.
- The default dynamic array contains a single earthquake rupture, ``rupture''.
- The 
-\family typewriter
-eq_srcs
-\family default
- is the 
-\family typewriter
-FaultCohesiveKin
-\family default
- facility for this dynamic array.
- An example of setting the array of kinematic rupture components in a 
-\family typewriter
-.cfg
-\family default
- file:
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.problem.interfaces.fault]
-\end_layout
-
-\begin_layout LyX-Code
-eq_srcs = [earthquake,creep]
-\end_layout
-
-\begin_layout Standard
-The output manager includes generic fault information (orientation) as well
- as the final slip or slip rate (as in the case of the constant slip rate
- slip time function) and slip initiation time for each kinematic rupture.
- The name of the slip and slip initiation time vertex fields are of the
- form 
-\family typewriter
-final_slip_NAME
-\family default
- and 
-\family typewriter
-slip_time_NAME
-\family default
-, respectively, where 
-\family typewriter
-NAME
-\family default
- refers to the name used in the dynamic array of kinematic ruptures, 
-\family typewriter
-eq_srcs
-\family default
-.
-\end_layout
-
-\begin_layout Standard
-\noindent
-\align center
-\begin_inset Float table
-placement H
-wide false
-sideways false
-status open
-
-\begin_layout Plain Layout
-\noindent
-\align center
-\begin_inset Caption
-
-\begin_layout Plain Layout
-\begin_inset CommandInset label
-LatexCommand label
-name "tab:fault:kin:output"
-
-\end_inset
-
-Fields available in output of fault information.
-\end_layout
-
-\end_inset
-
-
-\begin_inset VSpace defskip
-\end_inset
-
-
-\begin_inset Tabular
-<lyxtabular version="3" rows="8" columns="3">
-<features tabularvalignment="middle">
-<column alignment="center" valignment="top" width="0">
-<column alignment="center" valignment="top" width="0">
-<column alignment="center" valignment="top" width="3.5in">
-<row>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\series bold
-Field Type
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\series bold
-Field
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\series bold
-Description
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-vertex_info_fields
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-normal_dir
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Direction of fault normal in global coordinate system
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-strike_dir
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Direction of fault strike in global coordinate system
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-dip_dir
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Up-dip direction on hanging wall in global coordinate system
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-final_slip_NAME
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Vector of final slip (in fault coordinate system) in meters
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" bottomline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-slip_time
-\family default
-_
-\family typewriter
-\noun on
-NAME
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" bottomline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Time at which slip begins in seconds
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-vertex_data_fields
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-slip
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Slip vector at time step (in fault coordinate system) in meters
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" bottomline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-traction_change
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" bottomline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Change in fault tractions (in fault coordinate system) in Pa
-\end_layout
-
-\end_inset
-</cell>
-</row>
-</lyxtabular>
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Subsubsection
-Kinematic Rupture Parameters
-\end_layout
-
-\begin_layout Standard
-The kinematic rupture parameters include the origin time and slip time function.
- The slip initiation time in the slip time function is relative to the origin
- time (default is 0).
- This means that slip initiates at a point at a time corresponding to the
- sum of the kinematic rupture's origin time and the slip initiation time
- for that point.
- An example of specifying the kinematic earthquake rupture properties and
- components in a 
-\family typewriter
-.cfg
-\family default
- file:
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.problem.interfaces.fault]
-\end_layout
-
-\begin_layout LyX-Code
-eq_srcs = [earthquake,creep]
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.problem.interfaces.fault.eq_srcs.earthquake]
-\end_layout
-
-\begin_layout LyX-Code
-origin_time = 0.0*s ; default origin time
-\end_layout
-
-\begin_layout LyX-Code
-slip_function = pylith.faults.StepSlipFn ; default slip time function
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.problem.interfaces.fault.eq_srcs.creep]
-\end_layout
-
-\begin_layout LyX-Code
-origin_time = 10.0*year ; start creep at 10.0 years
-\end_layout
-
-\begin_layout LyX-Code
-slip_function = pylith.faults.ConstRateSlipFn ; switch to constant slip rate
- slip function
-\end_layout
-
-\begin_layout Subsubsection
-Slip Time Function
-\end_layout
-
-\begin_layout Standard
-The current release of PyLith supports specification of the evolution of
- fault slip using analytical expressions for the slip time history at each
- point, where the parameters for the slip time function may vary over the
- fault surface.
- Currently, three slip time functions are available: (1) a step-function
- for quasi-static modeling of earthquake rupture, (2) a constant slip rate
- time function for modeling steady aseismic slip, and (3) the integral of
- Brune's far-field time function 
-\begin_inset CommandInset citation
-LatexCommand cite
-key "Brune:1970"
-
-\end_inset
-
- for modeling the dynamics of earthquake rupture.
- Additional slip time functions will likely be available in future releases.
- The default slip time function is the step-function slip function.
-\end_layout
-
-\begin_layout Paragraph
-Step-Function Slip Time Function
-\end_layout
-
-\begin_layout Standard
-This slip function prescribes a step in slip at a given time at a point:
- 
-\end_layout
-
-\begin_layout Standard
-\begin_inset Formula 
-\begin{gather}
-D(t)=\left\{ \begin{array}{cc}
-0 & 0\leq t<t_{r}\\
-D_{final} & t\ge t_{r}
-\end{array}\right.\,,
-\end{gather}
-
-\end_inset
-
-where 
-\begin_inset Formula $D(t)$
-\end_inset
-
- is slip at time 
-\begin_inset Formula $t$
-\end_inset
-
-, 
-\begin_inset Formula $D_{final}$
-\end_inset
-
- is the final slip, and 
-\begin_inset Formula $t_{r}$
-\end_inset
-
- is the slip initiation time (time when rupture reaches the location).
- The slip is specified independently for each of the components of slip,
- and the slip and slip starting time may vary over the fault surface.
-\end_layout
-
-\begin_layout Description
-final_slip Spatial database of slip (
-\begin_inset Formula $D_{final})$
-\end_inset
-
-.
-\end_layout
-
-\begin_layout Description
-slip_time Spatial database of slip initiation times (
-\begin_inset Formula $t_{r}$
-\end_inset
-
-).
-\end_layout
-
-\begin_layout Standard
-An example of setting these parameters in a 
-\family typewriter
-.cfg
-\family default
- file is:
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.problem.interfaces.fault.eq_srcs.rupture]
-\end_layout
-
-\begin_layout LyX-Code
-slip_function = pylith.faults.StepSlipFn
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.problem.interfaces.fault.eq_srcs.rupture.slip_function]
-\end_layout
-
-\begin_layout LyX-Code
-final_slip.iohandler.filename = final_slip.spatialdb
-\end_layout
-
-\begin_layout LyX-Code
-slip_time.iohandler.filename = sliptime.spatialdb
-\end_layout
-
-\begin_layout Standard
-The spatial database files for the slip time function specify the spatial
- variation in the parameters for the slip time function, as shown in Table
- 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "tab:step-function-db-params"
-
-\end_inset
-
-.
-\end_layout
-
-\begin_layout Standard
-\noindent
-\align center
-\begin_inset Float table
-placement H
-wide false
-sideways false
-status open
-
-\begin_layout Plain Layout
-\noindent
-\align center
-\begin_inset Caption
-
-\begin_layout Plain Layout
-\begin_inset CommandInset label
-LatexCommand label
-name "tab:step-function-db-params"
-
-\end_inset
-
-Values in spatial database used as parameters in the step function slip
- time function.
-\end_layout
-
-\end_inset
-
-
-\begin_inset VSpace defskip
-\end_inset
-
-
-\begin_inset Tabular
-<lyxtabular version="3" rows="5" columns="3">
-<features tabularvalignment="middle">
-<column alignment="left" valignment="top" width="0">
-<column alignment="left" valignment="top" width="0">
-<column alignment="left" valignment="top" width="2.5in">
-<row>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\series bold
-Spatial database
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\series bold
-Value
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\series bold
-Description
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-final_slip
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-left-lateral-slip
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Amount of left-lateral final slip in meters.
- Use negative values for right-lateral slip.
- Applies to faults in 2D and 3D only.
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-reverse-slip
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Amount of reverse slip in meters.
- Use negative values for normal slip.
- Applies to faults in 3D only.
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-fault-opening
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Amount of fault opening in meters.
- Negative values imply penetration.
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-slip_time
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-slip-time
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Slip initiation time (
-\begin_inset Formula $t_{t})$
-\end_inset
-
- in seconds.
-\end_layout
-
-\end_inset
-</cell>
-</row>
-</lyxtabular>
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Paragraph
-Constant Slip Rate Slip Time Function
-\end_layout
-
-\begin_layout Standard
-This slip function prescribes a constant slip rate for the evolution of
- slip at a point: 
-\end_layout
-
-\begin_layout Standard
-\begin_inset Formula 
-\begin{gather}
-D(t)=\left\{ \begin{array}{cc}
-0 & 0\leq t<t_{r}\\
-V(t-t_{r}) & t\ge t_{r}
-\end{array}\right.\,,
-\end{gather}
-
-\end_inset
-
-where 
-\begin_inset Formula $D(t)$
-\end_inset
-
- is slip at time 
-\begin_inset Formula $t$
-\end_inset
-
-, 
-\begin_inset Formula $V$
-\end_inset
-
- is the slip rate, and 
-\begin_inset Formula $t_{r}$
-\end_inset
-
- is the slip initiation time (time when rupture reaches the location).
- The slip rate is specified independently for each of the components of
- slip, and the slip rate and slip starting time may vary over the fault
- surface.
-\end_layout
-
-\begin_layout Description
-slip_rate Spatial database of slip rate (
-\begin_inset Formula $V)$
-\end_inset
-
-.
-\end_layout
-
-\begin_layout Description
-slip_time Spatial database of slip initiation times (
-\begin_inset Formula $t_{r}$
-\end_inset
-
-).
-\end_layout
-
-\begin_layout Standard
-An example of setting these parameters in a 
-\family typewriter
-.cfg
-\family default
- file is:
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.problem.interfaces.fault.eq_srcs.ruptures]
-\end_layout
-
-\begin_layout LyX-Code
-slip_function = pylith.faults.ConstRateSlipFn
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.problem.interfaces.fault.eq_srcs.ruptures.slip_function]
-\end_layout
-
-\begin_layout LyX-Code
-slip_rate.iohandler.filename = slip_rate.spatialdb
-\end_layout
-
-\begin_layout LyX-Code
-slip_time.iohandler.filename = sliptime.spatialdb
-\end_layout
-
-\begin_layout Standard
-The spatial database files for the slip time function specify the spatial
- variation in the parameters for the slip time function, as shown in Table
- 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "tab:const-slip-rate-db-params"
-
-\end_inset
-
-.
-\end_layout
-
-\begin_layout Standard
-\noindent
-\align center
-\begin_inset Float table
-placement H
-wide false
-sideways false
-status open
-
-\begin_layout Plain Layout
-\noindent
-\align center
-\begin_inset Caption
-
-\begin_layout Plain Layout
-\begin_inset CommandInset label
-LatexCommand label
-name "tab:const-slip-rate-db-params"
-
-\end_inset
-
-Values in spatial database used as parameters in the constant slip rate
- slip time function.
-\end_layout
-
-\end_inset
-
-
-\begin_inset VSpace defskip
-\end_inset
-
-
-\begin_inset Tabular
-<lyxtabular version="3" rows="5" columns="3">
-<features tabularvalignment="middle">
-<column alignment="left" valignment="top" width="0">
-<column alignment="left" valignment="top" width="0">
-<column alignment="left" valignment="top" width="2.5in">
-<row>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\series bold
-Spatial database
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\series bold
-Value
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\series bold
-Description
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-slip_rate
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-left-lateral-slip
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Slip rate for left-lateral final slip in meters per second.
- Use negative values for right-lateral slip.
- Applies to faults in 2D and 3D only.
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-reverse-slip
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Slip rate for reverse slip in meters per second.
- Use negative values for normal slip.
- Applies to faults in 3D only.
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-fault-opening
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Slip rate for fault opening in meters per second.
- Negative values imply penetration.
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-slip_time
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-slip-time
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Slip initiation time (
-\begin_inset Formula $t_{t})$
-\end_inset
-
- in seconds.
-\end_layout
-
-\end_inset
-</cell>
-</row>
-</lyxtabular>
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Paragraph
-Brune Slip Time Function
-\end_layout
-
-\begin_layout Standard
-We use an integral of Brune's far-field time function 
-\begin_inset CommandInset citation
-LatexCommand cite
-key "Brune:1970"
-
-\end_inset
-
- to describe the evolution in time of slip at a point: 
-\end_layout
-
-\begin_layout Standard
-\begin_inset Formula 
-\begin{gather}
-D(t)=\left\{ \begin{array}{cc}
-0 & 0\leq t<t_{r}\\
-D_{final}\left(1-exp\left(-\frac{t-t_{r}}{t_{0}}\right)\left(1+\frac{t-t_{r}}{t_{0}}\right)\right) & t\ge t_{r}
-\end{array}\right.\,,\\
-t_{0}=0.6195t_{\mathit{rise}}\,,
-\end{gather}
-
-\end_inset
-
-where 
-\begin_inset Formula $D(t)$
-\end_inset
-
- is slip at time 
-\begin_inset Formula $t$
-\end_inset
-
-, 
-\begin_inset Formula $D_{final}$
-\end_inset
-
- is the final slip at the location, 
-\begin_inset Formula $t_{r}$
-\end_inset
-
- is the slip initiation time (time when rupture reaches the location), and
- 
-\begin_inset Formula $t_{\mathit{rise}}$
-\end_inset
-
- is the rise time.
-\end_layout
-
-\begin_layout Description
-slip Spatial database of final slip distribution (
-\begin_inset Formula $D_{final})$
-\end_inset
-
-.
-\end_layout
-
-\begin_layout Description
-slip_time Spatial database of slip initiation times (
-\begin_inset Formula $t_{r}$
-\end_inset
-
-).
-\end_layout
-
-\begin_layout Description
-rise_time Spatial database for rise time (
-\begin_inset Formula $t_{\mathit{rise}}$
-\end_inset
-
-).
-\end_layout
-
-\begin_layout Standard
-An example of setting these parameters in a 
-\family typewriter
-.cfg
-\family default
- file is:
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.problem.interfaces.fault.eq_srcs.ruptures]
-\end_layout
-
-\begin_layout LyX-Code
-slip_function = pylith.faults.BruneSlipFn
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.problem.interfaces.fault.eq_srcs.rupture.slip_function]
-\end_layout
-
-\begin_layout LyX-Code
-slip.iohandler.filename = finalslip.spatialdb
-\end_layout
-
-\begin_layout LyX-Code
-rise_time.iohandler.filename = risetime.spatialdb
-\end_layout
-
-\begin_layout LyX-Code
-slip_time.iohandler.filename = sliptime.spatialdb
-\end_layout
-
-\begin_layout Standard
-The spatial database files for the slip time function specify the spatial
- variation in the parameters for the slip time function, as shown in Table
- 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "tab:Brune-slip-db-params"
-
-\end_inset
-
-.
-\end_layout
-
-\begin_layout Standard
-\noindent
-\align center
-\begin_inset Float table
-placement H
-wide false
-sideways false
-status open
-
-\begin_layout Plain Layout
-\noindent
-\align center
-\begin_inset Caption
-
-\begin_layout Plain Layout
-\begin_inset CommandInset label
-LatexCommand label
-name "tab:Brune-slip-db-params"
-
-\end_inset
-
-Values in spatial database used as parameters in the Brune slip time function.
-\end_layout
-
-\end_inset
-
-
-\begin_inset VSpace defskip
-\end_inset
-
-
-\begin_inset Tabular
-<lyxtabular version="3" rows="6" columns="3">
-<features tabularvalignment="middle">
-<column alignment="left" valignment="top" width="0">
-<column alignment="left" valignment="top" width="0">
-<column alignment="left" valignment="top" width="2.5in">
-<row>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\series bold
-Spatial database
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\series bold
-Value
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\series bold
-Description
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-slip
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-left-lateral-slip
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Amount of left-lateral final slip in meters.
- Use negative values for right-lateral slip.
- Applies to faults in 2D and 3D only.
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-reverse-slip
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Amount of reverse slip in meters.
- Use negative values for normal slip.
- Applies to faults in 3D only.
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-fault-opening
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Amount of fault opening in meters.
- Negative values imply penetration.
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-rise_time
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-rise-time
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Rise time (
-\begin_inset Formula $t_{r})$
-\end_inset
-
- in seconds.
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-slip_time
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-slip-time
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Slip initiation time (
-\begin_inset Formula $t_{t})$
-\end_inset
-
- in meters.
-\end_layout
-
-\end_inset
-</cell>
-</row>
-</lyxtabular>
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Paragraph
-Liu-Cosine Slip Time Function
-\end_layout
-
-\begin_layout Standard
-This slip time function, proposed by Liu, Archuleta, and Hartzell for use
- in ground-motion modeling
-\begin_inset CommandInset citation
-LatexCommand cite
-key "Liu:etal:2006"
-
-\end_inset
-
-, combines several cosine and sine functions together to create a slip time
- history with a sharp rise and gradual termination with a finite duration
- of slip.
- The evolution of slip at a point follows: 
-\end_layout
-
-\begin_layout Standard
-\begin_inset Formula 
-\begin{gather}
-D(t)=\left\{ \begin{array}{cc}
-D_{\mathit{final}}C_{n}\left(0.7t-0.7\frac{t_{1}}{\pi}\sin\frac{\pi t}{t_{1}}-1.2\frac{t_{1}}{\pi}\left(\cos\frac{\pi t}{2t_{1}}-1\right)\right) & 0\leq t<t_{1}\\
-D_{\mathit{final}}C_{n}\left(1.0t-0.7\frac{t1}{\pi}\sin\frac{\pi t}{t_{1}}+0.3\frac{t2}{\pi}\sin\frac{\pi(t-t1)}{t_{2}}+\frac{1.2}{\pi}t_{1}-0.3t_{1}\right) & t_{1}\leq t<2t_{1}\\
-D_{\mathit{final}}C_{n}\left(0.7-0.7\cos\frac{\pi t}{t_{1}}+0.6\sin\frac{\pi t}{2t_{1}}\right) & 2t_{1}\leq t\leq t_{0}
-\end{array}\right.\,,\\
-C_{n}=\frac{\pi}{1.4\pi t_{1}+1.2t_{1}+0.3\pi t_{2}},\\
-t_{0}=1.525t_{\mathit{rise}},\\
-t_{1}=0.13t_{0},\\
-t_{2}=t_{0}-t_{1},
-\end{gather}
-
-\end_inset
-
-where 
-\begin_inset Formula $D(t)$
-\end_inset
-
- is slip at time 
-\begin_inset Formula $t$
-\end_inset
-
-, 
-\begin_inset Formula $D_{final}$
-\end_inset
-
- is the final slip at the location, 
-\begin_inset Formula $t_{r}$
-\end_inset
-
- is the slip initiation time (time when rupture reaches the location), and
- 
-\begin_inset Formula $t_{\mathit{rise}}$
-\end_inset
-
- is the rise time.
-\end_layout
-
-\begin_layout Description
-slip Spatial database of final slip distribution (
-\begin_inset Formula $D_{final})$
-\end_inset
-
-.
-\end_layout
-
-\begin_layout Description
-slip_time Spatial database of slip initiation times (
-\begin_inset Formula $t_{r}$
-\end_inset
-
-).
-\end_layout
-
-\begin_layout Description
-rise_time Spatial database for rise time (
-\begin_inset Formula $t_{\mathit{rise}}$
-\end_inset
-
-).
-\end_layout
-
-\begin_layout Standard
-The spatial database files for the slip time function use the same parameters
- for the slip time function as the Brune slip time function shown in Table
- 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "tab:Brune-slip-db-params"
-
-\end_inset
-
-.
-\end_layout
-
-\begin_layout Paragraph
-Time-History Slip Time Function
-\end_layout
-
-\begin_layout Standard
-This slip time function reads the slip time function from a data file, so
- it can have an arbitrary shape.
- The slip and slip initiation times are specified using spatial databases,
- so the slip time function, in general, will use a normalized amplitude.
-\end_layout
-
-\begin_layout Description
-slip Spatial database of final slip distribution (
-\begin_inset Formula $D_{final})$
-\end_inset
-
-.
-\end_layout
-
-\begin_layout Description
-slip_time Spatial database of slip initiation times (
-\begin_inset Formula $t_{r}$
-\end_inset
-
-).
-\end_layout
-
-\begin_layout Description
-time_history Temporal database for slip evolution.
-\end_layout
-
-\begin_layout Standard
-An example of setting these parameters in a 
-\family typewriter
-.cfg
-\family default
- file is:
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.problem.interfaces.fault.eq_srcs.ruptures]
-\end_layout
-
-\begin_layout LyX-Code
-slip_function = pylith.faults.TimeHistorySlipFn
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.problem.interfaces.fault.eq_srcs.rupture.slip_function]
-\end_layout
-
-\begin_layout LyX-Code
-slip.iohandler.filename = finalslip.spatialdb
-\end_layout
-
-\begin_layout LyX-Code
-slip_time.iohandler.filename = sliptime.spatialdb
-\end_layout
-
-\begin_layout LyX-Code
-time_history.iohandler.filename = myfunction.timedb
-\end_layout
-
-\begin_layout Standard
-The spatial database files for the slip time function specify the spatial
- variation in the parameters for the slip time function, as shown in Table
- 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "tab:Brune-slip-db-params-2"
-
-\end_inset
-
-.
-\end_layout
-
-\begin_layout Standard
-\noindent
-\align center
-\begin_inset Float table
-placement H
-wide false
-sideways false
-status open
-
-\begin_layout Plain Layout
-\noindent
-\align center
-\begin_inset Caption
-
-\begin_layout Plain Layout
-\begin_inset CommandInset label
-LatexCommand label
-name "tab:Brune-slip-db-params-2"
-
-\end_inset
-
-Values in spatial database used as parameters in the time history slip time
- function.
-\end_layout
-
-\end_inset
-
-
-\begin_inset VSpace defskip
-\end_inset
-
-
-\begin_inset Tabular
-<lyxtabular version="3" rows="6" columns="3">
-<features tabularvalignment="middle">
-<column alignment="left" valignment="top" width="0">
-<column alignment="left" valignment="top" width="0">
-<column alignment="left" valignment="top" width="2.5in">
-<row>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\series bold
-Spatial database
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\series bold
-Value
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\series bold
-Description
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-slip
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-left-lateral-slip
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Amount of left-lateral final slip in meters.
- Use negative values for right-lateral slip.
- Applies to faults in 2D and 3D only.
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-reverse-slip
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Amount of reverse slip in meters.
- Use negative values for normal slip.
- Applies to faults in 3D only.
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-fault-opening
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Amount of fault opening in meters.
- Negative values imply penetration.
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-rise_time
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-rise-time
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Rise time (
-\begin_inset Formula $t_{r})$
-\end_inset
-
- in seconds.
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-slip_time
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-slip-time
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Slip initiation time (
-\begin_inset Formula $t_{t})$
-\end_inset
-
- in meters.
-\end_layout
-
-\end_inset
-</cell>
-</row>
-</lyxtabular>
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Subsection
-Dynamic Earthquake Rupture
-\end_layout
-
-\begin_layout Standard
-Dynamic fault interfaces use the FaultCohesiveDyn object to specify a fault
- constitutive model to govern the fault tractions (friction) and the resulting
- slip.
- When friction is large enough such that there is no sliding on the fault,
- the fault is locked (slip is zero) and the Lagrange multipliers assume
- their values just as they do in kinematic ruptures.
- In this case, the Lagrange multipliers correspond to the forces necessary
- to keep the slip zero.
- When the driving forces exceed those allowed by friction, we reduce the
- values of the Lagrange multipliers to those consistent with friction from
- the fault constitutive model.
- When we reduce the Lagrange multipliers, we must increment the slip accordingly
- to maintain consistency in the algebraic system of equations.
-\end_layout
-
-\begin_layout Subsubsection
-Governing Equations
-\end_layout
-
-\begin_layout Standard
-The algebraic systems of equations for dynamic earthquake rupture are the
- same as those for kinematic rupture
-\begin_inset Formula 
-\begin{equation}
-\left[\begin{array}{cc}
-\underline{A} & \underline{C}^{T}\\
-\underline{C} & 0
-\end{array}\right]\left[\begin{array}{c}
-\overrightarrow{u}\\
-\overrightarrow{l}
-\end{array}\right]=\left[\begin{array}{c}
-\overrightarrow{b}\\
-\overrightarrow{d}
-\end{array}\right].
-\end{equation}
-
-\end_inset
-
-Enforcing the limits imposed on the Lagrange multipliers by the fault constituti
-ve model requires determining the increment in slip for an increment in
- the Lagrange multipliers.
- The increment in the Lagrange multipliers is the difference between the
- value computed for the current slip (either zero or the slip at the previous
- time step) and the value computed from the fault constitutive model.
- Starting from our system of algebraic equations,
-\begin_inset Formula 
-\begin{equation}
-A_{ij}^{nm}u_{j}^{m}+C_{ji}^{pn}l_{j}^{p}=b_{i}^{n},
-\end{equation}
-
-\end_inset
-
-we compute the sensitivity for the given loading and boundary conditions,
-\begin_inset Formula 
-\begin{equation}
-A_{ij}^{nm}\partial u_{j}^{m}=-C_{ji}^{pn}\partial l_{j}^{p}.
-\end{equation}
-
-\end_inset
-
-Computing the increment in the slip requires computing the increment in
- the displacements.
- Solving this equation rigorously would require inverting the system Jacobian,
- which we do not want to do unless it is diagonal (as it is in the case
- of the lumped formulations).
- 
-\end_layout
-
-\begin_layout Paragraph
-Non-diagonal A
-\end_layout
-
-\begin_layout Standard
-In general A is a sparse matrix with off-diagonal terms of the form
-\begin_inset Formula 
-\begin{equation}
-A=\left(\begin{array}{ccc}
-A_{0} & A_{1} & A_{2}\\
-A_{3} & A_{n-} & 0\\
-A_{4} & 0 & A_{n+}
-\end{array}\right),
-\end{equation}
-
-\end_inset
-
-where the degrees of freedom on either side of the fault are uncoupled.
- We formulate two small linear systems involving just the degrees of freedom
- associated with vertices on either the positive or negative sides of the
- fault,
-\begin_inset Formula 
-\begin{gather}
-A_{ij}^{nm-}\partial u_{j}^{m-}=-R_{ij}^{pn}\partial l_{j}^{p},\\
-A_{ij}^{nm+}\partial u_{j}^{m+}=R_{ij}^{pn}\partial l_{j}^{p},
-\end{gather}
-
-\end_inset
-
-where we have replaced 
-\begin_inset Formula $\underline{C}$
-\end_inset
-
- with 
-\begin_inset Formula $\underline{R}$
-\end_inset
-
- to denote the explicit inclusion of the signs for the terms in 
-\begin_inset Formula $\underline{C}$
-\end_inset
-
- associated with the positive (
-\begin_inset Formula $n^{+}$
-\end_inset
-
-) and negative (
-\begin_inset Formula $n^{-}$
-\end_inset
-
-) sides of the fault.
- After solving these two linear systems of equations, we compute the increment
- in slip using
-\begin_inset Formula 
-\begin{equation}
-\partial d_{i}^{p}=R_{ij}^{pn}(\partial u_{j}^{n+}-\partial u_{j}^{n-}).
-\end{equation}
-
-\end_inset
-
-The solution of these two linear systems gives the increment in slip assuming
- all the degrees of freedom except those immediately adjacent to the fault
- remain fixed.
- In real applications where the deformation associated with fault slip is
- localized around the fault, this provides good enough approximations so
- that the nonlinear solver converges quickly.
- In problems where deformation associated with slip on the fault is not
- localized (as in the case in some of the example problems), the increment
- in slip computed by solving these two linear systems is not a good approximatio
-n and the nonlinear solve requires a large number of iterations.
-\end_layout
-
-\begin_layout Standard
-We use the PETSc Krylov subspace solver (KSP) to solve these two linear
- systems.
- The PETSc settings for the KSP object are set in the same manner as the
- main solver, except we use the prefix friction_ in all of the settings
- related to the KSP solver for these two linear systems.
- For example, to use the recommended additive Schwarz preconditioner in
- the friction sensitivity solves, the settings in a .cfg file are:
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.petsc]
-\end_layout
-
-\begin_layout LyX-Code
-friction_pc_type = asm
-\end_layout
-
-\begin_layout Standard
-See the examples in Sections 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "sec:Tutorial-3d-hex8-friction"
-
-\end_inset
-
- and 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "sec:tutorial:shearwave:quad4"
-
-\end_inset
-
- for details.
-\end_layout
-
-\begin_layout Paragraph
-Diagonal A
-\end_layout
-
-\begin_layout Standard
-With a lumped Jacobian matrix, we can solve for the increment in slip directly,
-\begin_inset Formula 
-\begin{equation}
-\partial d_{i}^{p}=-C_{ij}^{pn}(A_{jk}^{nm})^{-1}C_{lk}^{pm}\partial l_{l}^{p}.
-\end{equation}
-
-\end_inset
-
-By not allowing the fault interface to overlap with the absorbing boundary,
- the terms in 
-\begin_inset Formula $A$
-\end_inset
-
- for a given vertex are identical and the expression on the right-hand side
- reduces to
-\begin_inset Formula 
-\begin{equation}
-\partial d_{i}^{p}=-\left(\frac{1}{A^{n+}}+\frac{1}{A^{n-}}\right)\partial l_{i}^{p}.
-\end{equation}
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Subsubsection
-Dynamic Rupture Parameters
-\end_layout
-
-\begin_layout Standard
-The components of the FaultCohesiveDyn object include
-\end_layout
-
-\begin_layout Description
-open_free_surface If true, enforce traction free surface when the fault
- opens, otherwise apply prescribed tractions even when the fault opens (default
- is true); to mimic a dike opening use false.
-\end_layout
-
-\begin_layout Description
-zero_tolerance Tolerance for detecting zero values (default is 1.0e-10);
- should be larger than absolute tolerance in KSP solves.
-\end_layout
-
-\begin_layout Description
-traction_perturbation Prescribed tractions on fault surface (generally used
- for nucleating earthquake ruptures, default is none).
-\end_layout
-
-\begin_layout Description
-friction Fault constitutive model.
-\end_layout
-
-\begin_layout Standard
-An example of specifying the dynamic earthquake rupture properties and component
-s in a 
-\family typewriter
-.cfg
-\family default
- file:
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.problem.interfaces.fault]
-\end_layout
-
-\begin_layout LyX-Code
-open_free_surface = True ; default
-\end_layout
-
-\begin_layout LyX-Code
-traction_perturbation = pylith.faults.TractPerturbation ; not default
-\end_layout
-
-\begin_layout LyX-Code
-traction_perturbation.db_initial = spatialdata.spatialdb.SimpleDB
-\end_layout
-
-\begin_layout LyX-Code
-traction_perturbation.db_initial.iohandler.filename = tractions.spatialdb
-\end_layout
-
-\begin_layout LyX-Code
-friction = pylith.friction.StaticFriction
-\end_layout
-
-\begin_layout LyX-Code
-friction.db_properties = spatialdata.spatialdb.SimpleDB
-\end_layout
-
-\begin_layout LyX-Code
-friction.db_properties.iohandler.filename = friction.spatialdb
-\end_layout
-
-\begin_layout Standard
-The prescribed traction perturbation is specified using the same fault coordinat
-e system as the slip directions in the kinematic ruptures.
- The perurbation has the same functional form as the time-dependent boundary
- conditions (and same spatial databases).
- Table 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "tab:fault:cohesive:dyn:prescribed:tractions"
-
-\end_inset
-
- gives the values in the spatial database for the prescribed tractions.
- Table 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "tab:fault:dyn:output"
-
-\end_inset
-
- shows the fields available for output.
- Additional fields are available depending on the fault constitutive model.
-\end_layout
-
-\begin_layout Standard
-\noindent
-\align center
-\begin_inset Float table
-placement H
-wide false
-sideways false
-status open
-
-\begin_layout Plain Layout
-\noindent
-\align center
-\begin_inset Caption
-
-\begin_layout Plain Layout
-\begin_inset CommandInset label
-LatexCommand label
-name "tab:fault:cohesive:dyn:prescribed:tractions"
-
-\end_inset
-
-Values in spatial databases for prescribed tractions.
-\end_layout
-
-\end_inset
-
-
-\begin_inset VSpace defskip
-\end_inset
-
-
-\begin_inset Tabular
-<lyxtabular version="3" rows="22" columns="4">
-<features tabularvalignment="middle">
-<column alignment="left" valignment="top" width="0">
-<column alignment="left" valignment="top" width="0">
-<column alignment="left" valignment="top" width="0">
-<column alignment="left" valignment="top" width="2.5in">
-<row>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\series bold
-Spatial database
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\series bold
-Dimension
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\series bold
-Value
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\series bold
-Description
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-db_initial
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-1-D
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-traction-normal
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Normal traction (tension is positive)
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-2-D
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-traction-shear
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Left-lateral shear traction (reverse shear for dipping faults)
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-traction-normal
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Normal traction (tension is positive)
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-3-D
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-traction-shear-leftlateral
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Left-lateral shear traction
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-traction-shear-updip
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Reverse shear traction
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-traction-normal
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Normal traction (tension is positive)
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-db_rate
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-1-D
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-traction-rate-normal
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Rate of change of normal traction (tension is positive)
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-2-D
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-traction-rate-shear
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Rate of change of left-lateral shear traction (reverse shear for dipping
- faults)
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-traction-rate-normal
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" bottomline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Rate of change of normal traction (tension is positive)
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-3-D
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-traction-rate-leftlateral
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Rate of change of eft-lateral shear traction
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-traction-rate-shear-updip
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Rate of change of reverse shear traction
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-traction-rate-normal
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" bottomline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Rate of change of normal traction (tension is positive)
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-all
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-rate-start-time
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Time at which rate of change begins
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-db_change
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-1-D
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-traction-normal
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Change in normal traction (tension is positive)
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-2-D
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-traction-shear
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Change in left-lateral shear traction (reverse shear for dipping faults)
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-traction-normal
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" bottomline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Change in normal traction (tension is positive)
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-3-D
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-traction-leftlateral
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Change in left-lateral shear traction
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-traction-shear-updip
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Change in reverse shear traction
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-traction-normal
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" bottomline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Change in normal traction (tension is positive)
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-all
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-change-start-time
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" bottomline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Time at which change begins
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-th_change
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-all
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-None
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" bottomline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Time history for change
-\end_layout
-
-\end_inset
-</cell>
-</row>
-</lyxtabular>
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\begin_inset Float table
-placement H
-wide false
-sideways false
-status open
-
-\begin_layout Plain Layout
-\noindent
-\align center
-\begin_inset Caption
-
-\begin_layout Plain Layout
-\begin_inset CommandInset label
-LatexCommand label
-name "tab:fault:dyn:output"
-
-\end_inset
-
-Fields available in output of fault information.
-\end_layout
-
-\end_inset
-
-
-\begin_inset VSpace defskip
-\end_inset
-
-
-\begin_inset Tabular
-<lyxtabular version="3" rows="11" columns="3">
-<features tabularvalignment="middle">
-<column alignment="center" valignment="top" width="0">
-<column alignment="center" valignment="top" width="0">
-<column alignment="center" valignment="top" width="3.5in">
-<row>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\series bold
-Field Type
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\series bold
-Field
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\series bold
-Description
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-vertex_info_fields
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-normal_dir
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Direction of fault normal in global coordinate system
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-strike_dir
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Direction of fault strike in global coordinate system
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-dip_dir
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Up-dip direction on hanging wall in global coordinate system
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-traction_initial
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Initial tractions (if specified) in fault coordinate system
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-traction_rate
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Rate of change in tractions (if specified) in fault coordinate system
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-rate_start_time
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Time at which rate of change begins (if specified)
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-traction_change
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Change in tractions (if specified) in fault coordinate system
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" bottomline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-change_start_time
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" bottomline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Time at which change occurs (if specified)
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-vertex_data_fields
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-slip
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Slip vector at time step (in fault coordinate system) in meters
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" bottomline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-traction
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" bottomline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Fault tractions (in fault coordinate system) in Pa
-\end_layout
-
-\end_inset
-</cell>
-</row>
-</lyxtabular>
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Subsubsection
-Fault Constitutive Models
-\begin_inset CommandInset label
-LatexCommand label
-name "sec:fault:constitutive:models"
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-PyLith provides four fault constitutive models.
- Future releases may contain additional models and a template is provided
- for you to construct your own (see Section 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "sec:Extending:FaultConstitutiveModels"
-
-\end_inset
-
-).
- The fault constitutive model implementations are independent of dimension
- and work in both 2-D and 3-D.
- In solving the governing equations, PyLith will use a scalar representation
- of the shear traction in 2-D and a vector representation of the shear traction
- in 3-D, with the shear traction resolved in the direction of current slip.
- The fault constitutive models contain a common set of properties and components
-:
-\end_layout
-
-\begin_layout Description
-label Name of the friction model.
-\end_layout
-
-\begin_layout Description
-db_properties Spatial database of the friction model parameters (default
- is SimpleDB).
-\end_layout
-
-\begin_layout Description
-db_initial_state Spatial database for initial state variables (default is
- none).
-\end_layout
-
-\begin_layout Paragraph
-Static Friction
-\end_layout
-
-\begin_layout Standard
-The static friction model produces shear tractions proportional to the fault
- normal traction plus a cohesive stress,
-\begin_inset Formula 
-\begin{equation}
-T_{f}=\begin{cases}
-T_{c}-\mu_{f}T_{n} & T_{n}\leq0\\
-0 & T_{n}>0
-\end{cases}.
-\end{equation}
-
-\end_inset
-
-The spatial database file for the static friction model properties specifies
- the spatial variation of the parameters given in Table 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "tab:static:friction:properties"
-
-\end_inset
-
-.
-\end_layout
-
-\begin_layout Standard
-\noindent
-\align center
-\begin_inset Float table
-placement H
-wide false
-sideways false
-status open
-
-\begin_layout Plain Layout
-\noindent
-\align center
-\begin_inset Caption
-
-\begin_layout Plain Layout
-\begin_inset CommandInset label
-LatexCommand label
-name "tab:static:friction:properties"
-
-\end_inset
-
-Values in the spatial database for constant friction parameters.
-\end_layout
-
-\end_inset
-
-
-\begin_inset VSpace defskip
-\end_inset
-
-
-\begin_inset Tabular
-<lyxtabular version="3" rows="3" columns="2">
-<features tabularvalignment="middle">
-<column alignment="left" valignment="top" width="0">
-<column alignment="left" valignment="top" width="2.5in">
-<row>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\series bold
-Value
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\series bold
-Description
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-friction-coefficient
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Coefficient of friction, 
-\begin_inset Formula $\mu_{f}$
-\end_inset
-
-
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-cohesion
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Cohesive stress, 
-\begin_inset Formula $T_{c}$
-\end_inset
-
-
-\end_layout
-
-\end_inset
-</cell>
-</row>
-</lyxtabular>
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Paragraph
-\begin_inset CommandInset label
-LatexCommand label
-name "sec:friction:slip:weakening"
-
-\end_inset
-
-Slip-Weakening Friction
-\end_layout
-
-\begin_layout Standard
-The linear slip-weakening friction model produces shear tractions equal
- to the cohesive stress plus a contribution proportional to the fault normal
- traction that decreases from a static value to a dynamic value as slip
- progresses,
-\begin_inset Formula 
-\begin{equation}
-T_{f}=\begin{cases}
-T_{c}-(\mu_{s}-(\mu_{s}-\mu_{d})\frac{d}{d_{0}})T_{n} & d\leq d_{0}\text{ and }T_{n}\leq0\\
-T_{c}-\mu_{d}T_{n} & d>d_{0}\text{ and }T_{n}\leq0\\
-0 & T_{n}>0
-\end{cases}
-\end{equation}
-
-\end_inset
-
-The spatial database files for the slip-weakening friction model properties
- and state variables specify the spatial variation of the fault constitutive
- model parameters given in Table 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "tab:slip:weakening:properties:statevars"
-
-\end_inset
-
-.
- As long as the fault is locked, the initial state variables are zero, so
- specifying the initial state variables for slip-weakening friction is rare.
- The slip-weakening friction also includes a parameter, 
-\family typewriter
-force_healing
-\family default
-, to control healing.
- In quasi-static simulations, one usually wants slip confined to a single
- time step (
-\family typewriter
-force_healing
-\family default
- = True), whereas in a dynamic simulation slip occurs over many time steps
- (
-\family typewriter
-force_healing
-\family default
- = False; default behavior) and fault healing is often neglected.
- The properties include:
-\end_layout
-
-\begin_layout Description
-force_healing Flag indicating whether healing (cumalative slip state variable
- reset to zero) is forced after every time step.
-\end_layout
-
-\begin_layout Standard
-An example of setting the properties for the rate and state friction component
- in a 
-\family typewriter
-.cfg
-\family default
- file is:
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.problem.interfaces.fault]
-\end_layout
-
-\begin_layout LyX-Code
-friction = pylith.friction.SlipWeakening ; Change friction model from the
- default
-\end_layout
-
-\begin_layout LyX-Code
-friction.force_healing = False ; default value
-\end_layout
-
-\begin_layout Standard
-\noindent
-\align center
-\begin_inset Float table
-placement H
-wide false
-sideways false
-status open
-
-\begin_layout Plain Layout
-\noindent
-\align center
-\begin_inset Caption
-
-\begin_layout Plain Layout
-\begin_inset CommandInset label
-LatexCommand label
-name "tab:slip:weakening:properties:statevars"
-
-\end_inset
-
-Values in spatial databases for slip-weakening friction.
-\end_layout
-
-\end_inset
-
-
-\begin_inset VSpace defskip
-\end_inset
-
-
-\begin_inset Tabular
-<lyxtabular version="3" rows="7" columns="3">
-<features tabularvalignment="middle">
-<column alignment="left" valignment="top" width="0">
-<column alignment="left" valignment="top" width="0">
-<column alignment="left" valignment="top" width="2.5in">
-<row>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\series bold
-Spatial database
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\series bold
-Value
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\series bold
-Description
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-db_properties
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-static-coefficient
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Static coefficient of friction, 
-\begin_inset Formula $\mu_{s}$
-\end_inset
-
-
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-dynamic-coefficient
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Dynamic coefficient of friction, 
-\begin_inset Formula $\mu_{d}$
-\end_inset
-
-
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-slip-weakening-parameter
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Slip-weakening parameter, 
-\begin_inset Formula $d_{0}$
-\end_inset
-
-
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-cohesion
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Cohesive stress, 
-\begin_inset Formula $T_{c}$
-\end_inset
-
-
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-db_initial_state
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-cumulative-slip
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Cumulative slip, 
-\begin_inset Formula $d$
-\end_inset
-
-
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-previous-slip
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Slip at previous time step, 
-\begin_inset Formula $d(t-\Delta t)$
-\end_inset
-
-
-\end_layout
-
-\end_inset
-</cell>
-</row>
-</lyxtabular>
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Paragraph
-Time-Weakening Friction
-\end_layout
-
-\begin_layout Standard
-The linear time-weakening friction model is analogous to the linear slip-weakeni
-ng friction model with time replacing slip.
- It produces shear tractions equal to the cohesive stress plus a contribution
- proportional to the fault normal traction that decreases from a static
- value to a dynamic value as time progresses,
-\begin_inset Formula 
-\begin{equation}
-T_{f}=\begin{cases}
-T_{c}-(\mu_{s}-(\mu_{s}-\mu_{d})\frac{t}{t_{0}})T_{n} & t\leq t_{0}\text{ and }T_{n}\leq0\\
-T_{c}-\mu_{d}T_{n} & t>t_{0}\text{ and }T_{n}\leq0\\
-0 & T_{n}>0
-\end{cases}
-\end{equation}
-
-\end_inset
-
-The spatial database files for the time-weakening friction model properties
- and state variables specify the spatial variation of the fault constitutive
- model parameters given in Table 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "tab:time:weakening:properties:statevars"
-
-\end_inset
-
-.
- As long as the fault is locked, the initial state variable is zero, so
- specifying the initial state variable for time-weakening friction is rare.
-\end_layout
-
-\begin_layout Standard
-\noindent
-\align center
-\begin_inset Float table
-placement H
-wide false
-sideways false
-status open
-
-\begin_layout Plain Layout
-\noindent
-\align center
-\begin_inset Caption
-
-\begin_layout Plain Layout
-\begin_inset CommandInset label
-LatexCommand label
-name "tab:time:weakening:properties:statevars"
-
-\end_inset
-
-Values in spatial databases for time-weakening friction.
-\end_layout
-
-\end_inset
-
-
-\begin_inset VSpace defskip
-\end_inset
-
-
-\begin_inset Tabular
-<lyxtabular version="3" rows="6" columns="3">
-<features tabularvalignment="middle">
-<column alignment="left" valignment="top" width="0">
-<column alignment="left" valignment="top" width="0">
-<column alignment="left" valignment="top" width="2.5in">
-<row>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\series bold
-Database
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\series bold
-Value
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\series bold
-Description
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-db_properties
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-static-coefficient
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Static coefficient of friction, 
-\begin_inset Formula $\mu_{s}$
-\end_inset
-
-
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-dynamic-coefficient
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Dynamic coefficient of friction, 
-\begin_inset Formula $\mu_{d}$
-\end_inset
-
-
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-time-weakening-parameter
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Time-weakening parameter, 
-\begin_inset Formula $t_{0}$
-\end_inset
-
-
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-cohesion
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Cohesive stress, 
-\begin_inset Formula $T_{c}$
-\end_inset
-
-
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-db_initial_state
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-elapsed-time
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Elasped time of slip, 
-\begin_inset Formula $t$
-\end_inset
-
-
-\end_layout
-
-\end_inset
-</cell>
-</row>
-</lyxtabular>
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Paragraph
-\begin_inset CommandInset label
-LatexCommand label
-name "sec:friction:rate:state:ageing"
-
-\end_inset
-
-Rate- and State-Friction with Ageing Law
-\end_layout
-
-\begin_layout Standard
-The Dieterich-Ruina rate and state friction model produces shear tractions
- equal to the cohesive stress plus a contribution proportional to the fault
- normal traction that depends on a state variable,
-\begin_inset Formula 
-\begin{gather}
-T_{f}=\begin{cases}
-T_{c}-\mu_{f}T_{n} & T_{n}\leq0\\
-0 & T_{n}>0
-\end{cases}\\
-\mu_{f}=\begin{cases}
-\mu_{0}+a\ln\left(\frac{V}{V_{0}}\right)+b\ln\left(\frac{V_{0}\theta}{L}\right) & V\ge V_{\mathit{min}}\\
-\mu_{0}+a\ln\left(\frac{V_{min}}{V}\right)+b\ln\left(\frac{V_{0}\theta}{L}\right)-a\left(1-\frac{V}{V_{min}}\right) & V<V_{min}
-\end{cases}\\
-\frac{d\theta}{dt}=1-\frac{V\theta}{L}
-\end{gather}
-
-\end_inset
-
-where 
-\begin_inset Formula $V$
-\end_inset
-
- is slip rate, 
-\begin_inset Formula $V_{min}$
-\end_inset
-
- is a minimum slip rate, 
-\begin_inset Formula $a$
-\end_inset
-
- and 
-\begin_inset Formula $b$
-\end_inset
-
- are coefficients, 
-\begin_inset Formula $L$
-\end_inset
-
- is the characteristic slip distance, 
-\begin_inset Formula $\theta$
-\end_inset
-
- is a state variable.
- With an interative solver in quasi-static simulations with a small, but
- nonzero residual tolerance we never encounter zero slip rates in quasi-static
- simulations.
- Instead we want to avoid significant variations in the coefficient of friction
- for slip rates on the same order as our residual tolerance.
- We regularize the rate and state friction model by iposing a linearization
- of the variation of the coefficient of friction with slip rate when the
- slip rate drops below a minimum slip rate, 
-\begin_inset Formula $V_{min}$
-\end_inset
-
- (
-\family typewriter
-min_slip_rate
-\family default
- property with a default value of 1.0e-12).
- Note that this is different than the popular inverse hypoerbolic sine regulariz
-ation proposed by Ben-Zion and Rice 
-\begin_inset CommandInset citation
-LatexCommand cite
-key "BenZion:Rice:1997"
-
-\end_inset
-
- to permit zero slip rates.
- Following Kaneko 
-\shape italic
-et al.
-
-\shape default
- 
-\begin_inset CommandInset citation
-LatexCommand cite
-key "Kaneko:etal:2008"
-
-\end_inset
-
-, we integrate the evolution equation for the state variable keeping slip
- rate constant to get
-\begin_inset Formula 
-\begin{equation}
-\theta(t+\Delta t)=\theta(t)\exp\left(\frac{-V(t)\Delta t}{L}\right)+\frac{L}{V(t)}\left(1-\exp\left(-\frac{V(t)\Delta t}{L}\right)\right).
-\end{equation}
-
-\end_inset
-
-As the slip rate approaches zero, the first exponential term approaches
- 1.
- Using the first three terms of the Taylor series expansion of the second
- exponential yields
-\begin_inset Formula 
-\begin{equation}
-\theta(t+\Delta t)=\begin{cases}
-\theta(t)\exp\left(-\frac{V(t)\Delta t}{L}\right)+\Delta t-\frac{1}{2}\frac{V(t)\Delta t^{2}}{L} & \frac{V(t)\Delta t}{L}<0.00001\\
-\theta(t)\exp\left(-\frac{V(t)\Delta t}{L}\right)+\frac{L}{V(t)}\left(1-\exp\left(-\frac{V(t)\Delta t}{L}\right)\right) & \frac{V(t)\Delta t}{L}\ge0.00001
-\end{cases}.
-\end{equation}
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-The properties include:
-\end_layout
-
-\begin_layout Description
-min_slip_rate Slip rate at which linearization occurs, 
-\begin_inset Formula $V_{min}$
-\end_inset
-
-.
- Should be about one order of magnitude larger than absolute tolerance in
- solve.
-\end_layout
-
-\begin_layout Standard
-An example of setting the properties for the rate and state friction component
- in a 
-\family typewriter
-.cfg
-\family default
- file is:
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.problem.interfaces.fault]
-\end_layout
-
-\begin_layout LyX-Code
-friction = pylith.friction.RateStateAgeing ; Change friction model from the
- default
-\end_layout
-
-\begin_layout LyX-Code
-friction.min_slip_rate = 1.0e-12 ; default value
-\end_layout
-
-\begin_layout Standard
-The spatial database files for the rate and state friction model properties
- and state variables specify the spatial variation of the fault constitutive
- model parameters given in Table 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "tab:rate:state:ageing:properties:statevars"
-
-\end_inset
-
-.
-\end_layout
-
-\begin_layout Standard
-\noindent
-\align center
-\begin_inset Float table
-placement H
-wide false
-sideways false
-status open
-
-\begin_layout Plain Layout
-\noindent
-\align center
-\begin_inset Caption
-
-\begin_layout Plain Layout
-\begin_inset CommandInset label
-LatexCommand label
-name "tab:rate:state:ageing:properties:statevars"
-
-\end_inset
-
-Values in spatial databases for Dieterich-Ruina rate-state friction.
-\end_layout
-
-\end_inset
-
-
-\begin_inset VSpace defskip
-\end_inset
-
-
-\begin_inset Tabular
-<lyxtabular version="3" rows="8" columns="3">
-<features tabularvalignment="middle">
-<column alignment="left" valignment="top" width="0">
-<column alignment="left" valignment="top" width="0">
-<column alignment="left" valignment="top" width="2.5in">
-<row>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\series bold
-Database
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\series bold
-Value
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\series bold
-Description
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-db_properties
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-reference-friction-coefficient
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Steady-state coefficient of friction at slip rate 
-\begin_inset Formula $V_{0}$
-\end_inset
-
-, 
-\begin_inset Formula $\mu_{s}$
-\end_inset
-
-
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-reference-slip-rate
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Reference slip rate, 
-\begin_inset Formula $V_{0}$
-\end_inset
-
-
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-characteristic-slip-distance
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Slip-weakening parameter, 
-\begin_inset Formula $L$
-\end_inset
-
-
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-constitutive-parameter-a
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Coefficient for the 
-\begin_inset Formula $\ln$
-\end_inset
-
- slip rate term, 
-\begin_inset Formula $a$
-\end_inset
-
-
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-constitutive-parameter-b
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Coefficient for the 
-\begin_inset Formula $\ln$
-\end_inset
-
- state variable term, 
-\begin_inset Formula $b$
-\end_inset
-
-
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-cohesion
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Cohesive stress, 
-\begin_inset Formula $T_{c}$
-\end_inset
-
-
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-db_initial_state
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-state-variable
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-State variable, 
-\begin_inset Formula $\theta$
-\end_inset
-
-
-\end_layout
-
-\end_inset
-</cell>
-</row>
-</lyxtabular>
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Subsection
-\begin_inset CommandInset label
-LatexCommand label
-name "sec:fault:cohesive:impulses"
-
-\end_inset
-
-Slip Impulses for Green's Functions
-\end_layout
-
-\begin_layout Standard
-Computing static Green's functions using the GreensFns problem requires
- a specialized fault implementation, FaultCohesiveImpulses, to setup the
- slip impulses.
- The parameters controlling the slip impulses include the components involved
- (lateral, reverse, and/or fault opening) and the amplitude of the pulses
- (e.g., selecting a subset of a fault or including a spatial variation).
- The GreensFns properties and facilities include:
-\end_layout
-
-\begin_layout Description
-threshold Threshold for non-zero amplitude; impulses will only be generated
- at locations on the fault where the amplitude excees this threshold.
-\end_layout
-
-\begin_layout Description
-impulse_dof Array of components associated with impulses, e.g., [0, 1] for
- slip involving the lateral and up-dip components.
-\end_layout
-
-\begin_layout Description
-db_impulse_amplitude Spatial database for amplitude of slip impulse (scalar
- field).
- Default is SimpleDB.
-\end_layout
-
-\begin_layout Standard
-An example of setting the properties and facilities for FaultCohesiveImpulses
- in a 
-\family typewriter
-.cfg
-\family default
- file is:
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.problem.interfaces]
-\end_layout
-
-\begin_layout LyX-Code
-fault = pylith.faults.FaultCohesiveImpulses ; Change from the default
-\end_layout
-
-\begin_layout LyX-Code
-
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.problem.interfaces.fault]
-\end_layout
-
-\begin_layout LyX-Code
-threshold = 1.0e-6*m ; default
-\end_layout
-
-\begin_layout LyX-Code
-impulse_dof = [0] ; lateral slip-only
-\end_layout
-
-\begin_layout LyX-Code
-db_impulse_amplitude.iohandler.filename = myimpulse.spatialdb
-\end_layout
-
-\begin_layout LyX-Code
-db_impulse_amplitude.label = Impulse amplitude
-\end_layout
-
-\begin_layout Section
-Gravitational Body Forces
-\end_layout
-
-\begin_layout Standard
-Many problems in geophysics require the consideration of gravitational body
- forces.
- For example, it is often important to include the effects of the lithostatic
- (overburden) pressure.
- In future releases of PyLith that permit nonlinear bulk rheologies, body
- forces will affect plastic yield criteria and the deformation field for
- large deformation/finite strain problems.
- As described in Chapter 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "cha:Governing-Equations"
-
-\end_inset
-
-, the body forces contribute to the residual,
-\begin_inset Formula 
-\begin{equation}
-r_{i}^{n}=\int_{V}f_{i}N^{n}\: dV.
-\end{equation}
-
-\end_inset
-
-For gravitational body forces the body force per unit volume, 
-\begin_inset Formula $f_{i}$
-\end_inset
-
-, is given as the product of the mass density, 
-\begin_inset Formula $\rho$
-\end_inset
-
-, the scalar gravitational acceleration value, 
-\begin_inset Formula $g$
-\end_inset
-
-, and the gravitational acceleration orientation vector, 
-\begin_inset Formula $a_{i}$
-\end_inset
-
-:
-\begin_inset Formula 
-\begin{equation}
-f_{i}=\rho ga_{i}.
-\end{equation}
-
-\end_inset
-
-The mass density is a property of every material model, and is thus included
- in the spatial database with the physical properties for each material.
- The gravitational acceleration is assumed to be uniform and constant for
- a given problem, with a default value of 9.80665 m/s
-\begin_inset Formula $^{\text{2}}$
-\end_inset
-
-.
- The orientation vector will depend on the dimension of the problem as well
- as the coordinate system being used.
- The default orientation vector has components (0, 0, -1).
- This is appropriate for three-dimensional problems where the gravity vector
- is aligned with the negative z-axis, as would be the case in a geographic-proje
-cted coordinate system or a generic Cartesian coordinate system.
- For cases in which the curvature of the earth should be considered, the
- spatialdata package provides an earth-centered, earth-fixed (ECEF) coordinate
- system and a local georeferenced Cartesian system; in each of these cases
- the orientation vector is computed automatically, although this feature
- has not been tested.
- For problems in one or two dimensions where the orientation vector is constant,
- the vector will need to be explicitly specified.
- For example, in a two-dimensional problem, the vector might be specified
- as (0, -1, 0).
- The vector still has three components, although the extra component is
- not used.
-\end_layout
-
-\begin_layout Standard
-Gravity is turned off by default.
- To include gravitational effects in a simulation, you can turn it on as
- follows:
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.timedependent]
-\end_layout
-
-\begin_layout LyX-Code
-use_gravity = true
-\end_layout
-
-\begin_layout Standard
-By simply adding this flag, the default gravity field values will be used
- and a 
-\family typewriter
-gravity_field
-\family default
- component will be assigned for the problem.
- The default values may be changed by altering the properties of 
-\family typewriter
-gravity_field
-\family default
-:
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.timedependent.gravity_field]
-\end_layout
-
-\begin_layout LyX-Code
-acceleration = 100.0*m*s**-2
-\end_layout
-
-\begin_layout LyX-Code
-gravity_dir = [0, -1, 0]
-\end_layout
-
-\begin_layout Standard
-An example problem using gravity is described in Section 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "sec:Tutorial-3d-hex8-gravity"
-
-\end_inset
-
-.
-\end_layout
-
-\end_body
-\end_document
+#LyX 2.0 created this file. For more info see http://www.lyx.org/
+\lyxformat 413
+\begin_document
+\begin_header
+\textclass book
+\use_default_options false
+\maintain_unincluded_children false
+\language english
+\language_package default
+\inputencoding auto
+\fontencoding global
+\font_roman default
+\font_sans default
+\font_typewriter default
+\font_default_family default
+\use_non_tex_fonts false
+\font_sc false
+\font_osf false
+\font_sf_scale 100
+\font_tt_scale 100
+
+\graphics default
+\default_output_format default
+\output_sync 0
+\bibtex_command default
+\index_command default
+\paperfontsize default
+\spacing single
+\use_hyperref false
+\papersize default
+\use_geometry true
+\use_amsmath 1
+\use_esint 0
+\use_mhchem 1
+\use_mathdots 1
+\cite_engine basic
+\use_bibtopic false
+\use_indices false
+\paperorientation portrait
+\suppress_date false
+\use_refstyle 0
+\index Index
+\shortcut idx
+\color #008000
+\end_index
+\leftmargin 1in
+\topmargin 1in
+\rightmargin 1in
+\bottommargin 1in
+\secnumdepth 3
+\tocdepth 3
+\paragraph_separation indent
+\paragraph_indentation default
+\quotes_language english
+\papercolumns 1
+\papersides 1
+\paperpagestyle default
+\tracking_changes false
+\output_changes false
+\html_math_output 0
+\html_css_as_file 0
+\html_be_strict false
+\end_header
+
+\begin_body
+
+\begin_layout Chapter
+\begin_inset CommandInset label
+LatexCommand label
+name "cha:boundary:interface:conditions"
+
+\end_inset
+
+Boundary and Interface Conditions
+\end_layout
+
+\begin_layout Section
+Assigning Boundary Conditions
+\end_layout
+
+\begin_layout Standard
+There are four basic steps in assigning a specific boundary condition to
+ a portion of the domain.
+\end_layout
+
+\begin_layout Enumerate
+Create sets of vertices in the mesh generation process for each boundary
+ condition.
+\end_layout
+
+\begin_layout Enumerate
+Define boundary condition groups corresponding to the vertex sets.
+\end_layout
+
+\begin_layout Enumerate
+Set the parameters for each boundary condition group using 
+\family typewriter
+.cfg
+\family default
+ or 
+\family typewriter
+.pml
+\family default
+ files and/or command line arguments.
+\end_layout
+
+\begin_layout Enumerate
+Specify the spatial variation in parameters for the boundary condition using
+ a spatial database file.
+\end_layout
+
+\begin_layout Subsection
+Creating Sets of Vertices
+\end_layout
+
+\begin_layout Standard
+The procedure for creating sets of vertices differs depending on the mesh
+ generator.
+ For meshes specified using the PyLith mesh ASCII format, the sets of vertices
+ are specified using groups (see Appendix 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "sec:MeshIOAscii"
+
+\end_inset
+
+).
+ In CUBIT the groups of vertices are created using nodesets.
+ Similarly, in LaGriT, psets are used.
+ Note that we chose to associated boundary conditions with groups of vertices
+ because nearly every mesh generation package supports associating a string
+ or integer with groups of vertices.
+ Note also that we currently associate boundary conditions with string identifie
+rs, so even if the mesh generator uses integers, the name is specified as
+ the digits of the integer value.
+ Finally, note that every vertex set that ultimately is associated with
+ a boundary condition on a cell face (e.g., Neumann boundary conditions and
+ fault interface conditions) must correspond to a simply-connected surface.
+\end_layout
+
+\begin_layout Subsection
+Arrays of Boundary Condition Components
+\end_layout
+
+\begin_layout Standard
+A dynamic array of boundary condition components associates a name (string)
+ with each boundary condition.
+ This dynamic array of boundary conditions replaces the boundary condition
+ container in PyLith 1.0.
+ User-defined containers are no longer necessary, and the predefined containers
+ are no longer available (or necessary).
+ The default boundary condition for each component in the array is the Dirichlet
+Points object.
+ Other boundary conditions can be bound to the named items in the array
+ via a 
+\family typewriter
+.cfg
+\family default
+ file, 
+\family typewriter
+.pml
+\family default
+ file, or the command line.
+ The parameters for the boundary condition are set using the name of the
+ boundary condition.
+ An example of setting the array of boundary condition components and changing
+ the types of boundary conditions in a 
+\family typewriter
+.cfg
+\family default
+ file:
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.problem]
+\end_layout
+
+\begin_layout LyX-Code
+bc = [x_neg,x_pos,y_pos,z_neg] ; Array of boundary conditions
+\end_layout
+
+\begin_layout LyX-Code
+# Default boundary condition is DirichletPoints
+\end_layout
+
+\begin_layout LyX-Code
+# Keep default value for bc.x_neg
+\end_layout
+
+\begin_layout LyX-Code
+bc.x_pos = pylith.bc.DirichletBoundary ; change BC type to DirichletBoundary
+\end_layout
+
+\begin_layout LyX-Code
+bc.y_pos = pylith.bc.AbsorbingDampers ; change BC type to AbsorbingDampers
+\end_layout
+
+\begin_layout LyX-Code
+bc.z_neg = pylith.bc.Neumann ; change BC type to Neumann (traction)
+\end_layout
+
+\begin_layout Section
+\begin_inset CommandInset label
+LatexCommand label
+name "sec:Time:Dependent:BC"
+
+\end_inset
+
+Time-Dependent Boundary Conditions
+\end_layout
+
+\begin_layout Standard
+Several boundary conditions use a common formulation for the spatial and
+ temporal variation of the boundary condition parameters,
+\begin_inset Formula 
+\begin{equation}
+f(\vec{x})=f_{0}(\vec{x})+\dot{f}_{0}(\vec{x})(t-t_{0}(\vec{x}))+f_{1}(\vec{x})a(t-t_{1}(\vec{x})),
+\end{equation}
+
+\end_inset
+
+where 
+\begin_inset Formula $f(\vec{x})$
+\end_inset
+
+ may be a scalar or vector parameter, 
+\begin_inset Formula $f_{0}(\vec{x})$
+\end_inset
+
+ is a constant value, 
+\begin_inset Formula $\dot{f}_{0}(\vec{x})$
+\end_inset
+
+ is a constant rate of change in the value, 
+\begin_inset Formula $t_{0}(\vec{x})$
+\end_inset
+
+ is the onset time for the constant rate of change, 
+\begin_inset Formula $f_{1}(\vec{x})$
+\end_inset
+
+ is the amplitude for the temporal modulation, 
+\begin_inset Formula $a(t)$
+\end_inset
+
+ is the variation in amplitude with time, 
+\begin_inset Formula $t_{1}(\vec{x})$
+\end_inset
+
+ is the onset time for the temporal modulation, and 
+\begin_inset Formula $\vec{x}$
+\end_inset
+
+ is the position of a location in space.
+ This common formulation permits easy specification of a scalar or vector
+ with a constant value, constant rate of change of a value, and/or modulation
+ of a value in time.
+ One can specify just the initial value, just the rate of change of the
+ value (along with the corresponding onset time), or just the modulation
+ in amplitude (along with the corresponding temporal variation and onset
+ time), or any combination of the three.
+ The facilities associated with this formulation are:
+\end_layout
+
+\begin_layout Description
+db_initial Spatial database specifying the spatial variation in the initial
+ value (default is none).
+\end_layout
+
+\begin_layout Description
+db_rate Spatial database specifying rate of change in the value (default
+ is none).
+\end_layout
+
+\begin_layout Description
+db_change Spatial database specifying the amplitude of the temporal modulation
+ (default is none).
+\end_layout
+
+\begin_layout Description
+th_change Time history database specifying the temporal change in amplitude
+ (default is none).
+\end_layout
+
+\begin_layout Subsection
+Dirichlet Boundary Conditions
+\end_layout
+
+\begin_layout Standard
+Dirichlet boundary conditions in PyLith prescribe the displacement of a
+ subset of the vertices of the finite-element mesh.
+ While Dirichlet boundary conditions can be applied to any vertex, usually
+ they are applied to vertices on the lateral and bottom boundaries of the
+ domain.
+ There are two types of Dirichlet boundary conditions, DirichletBC and Dirichlet
+Boundary.
+ Both provide identical constraints on the solution, but DirichletBoundary
+ is limited to vertices of a simply-connected surface, which allows diagnostic
+ output of the prescribed displacements.
+ DirichletBC can be applied to a set of unconnected vertices.
+\end_layout
+
+\begin_layout Subsubsection
+Dirichlet Boundary Condition Parameters
+\end_layout
+
+\begin_layout Standard
+The properties and components common to both the DirichletPoints and DirichletBo
+undary boundary conditions are:
+\end_layout
+
+\begin_layout Description
+label Label of the group of vertices associated with the boundary condition.
+\end_layout
+
+\begin_layout Description
+bc_dof Array of degrees of freedom to be fixed (first degree of freedom
+ is 0).
+\end_layout
+
+\begin_layout Standard
+DirichletBoundary contains an additional component:
+\end_layout
+
+\begin_layout Description
+output Manager for output of displacements on boundary with specified displaceme
+nts.
+\end_layout
+
+\begin_layout Standard
+By default the output manager does not output any information.
+ The specified displacements and velocities can be output by including ``displac
+ements'' and ``velocities'' in the output manager's 
+\family typewriter
+vertex_info_fields
+\family default
+ array parameter.
+ An example of setting the Dirichlet boundary condition parameters in a
+ 
+\family typewriter
+.cfg
+\family default
+ file is:
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.problem]
+\end_layout
+
+\begin_layout LyX-Code
+bc = [mybc]
+\end_layout
+
+\begin_layout LyX-Code
+
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.problem.bc.mybc]
+\end_layout
+
+\begin_layout LyX-Code
+label = group A 
+\end_layout
+
+\begin_layout LyX-Code
+bc_dof = [2] ; fixed displacement in z direction
+\end_layout
+
+\begin_layout LyX-Code
+db_initial = spatialdata.spatialdb.SimpleDB
+\end_layout
+
+\begin_layout LyX-Code
+db_initial.iohandler.filename = disp_A.spatialdb
+\end_layout
+
+\begin_layout LyX-Code
+db_initial.query_type = nearest ; change query type to nearest point algorithm
+\end_layout
+
+\begin_layout LyX-Code
+db_rate = spatialdata.spatialdb.UniformDB
+\end_layout
+
+\begin_layout LyX-Code
+db_rate.values = [displacement-rate-z]
+\end_layout
+
+\begin_layout LyX-Code
+db_rate.data = [1.0e-06*m/s] ; velocity is 1.0e-06 m/s
+\end_layout
+
+\begin_layout Standard
+We have created an array with one boundary condition, mybc.
+ The group of vertices associated with the boundary condition is group A.
+ For the database associated with the constant displacement, we use a SimpleDB.
+ We set the filename and query type for the database.
+ For the rate of change of values, we use a UniformDB and specify the velocity
+ in the z-direction to be 1.0e-06 m/s.
+ See Section 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "sec:spatial:databases"
+
+\end_inset
+
+ for a discussion of the different types of spatial databases available.
+\end_layout
+
+\begin_layout Standard
+\noindent
+\align center
+\begin_inset Float table
+placement H
+wide false
+sideways false
+status open
+
+\begin_layout Plain Layout
+\noindent
+\align center
+\begin_inset Caption
+
+\begin_layout Plain Layout
+\begin_inset CommandInset label
+LatexCommand label
+name "tab:dirichlet:output"
+
+\end_inset
+
+Fields available in output of DirichletBoundary boundary condition information.
+\end_layout
+
+\end_inset
+
+
+\begin_inset VSpace defskip
+\end_inset
+
+
+\begin_inset Tabular
+<lyxtabular version="3" rows="6" columns="3">
+<features tabularvalignment="middle">
+<column alignment="center" valignment="top" width="0">
+<column alignment="center" valignment="top" width="0">
+<column alignment="center" valignment="top" width="3in">
+<row>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\series bold
+Field Type
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\series bold
+Field
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\series bold
+Description
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+vertex_info_fields
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+displacement_initial
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Initial displacement field in global coordinate system
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+velocity
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Rate of change of displacement field in global coordinate system
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+velocity_start_time
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Onset time in seconds for rate of change in displacement field
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+displacement_change
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Amplitude of change in displacement field in global coordinate system
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+change_start_time
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Onset time in seconds for the amplitude change in the displacement field
+\end_layout
+
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Subsubsection
+Dirichlet Boundary Condition Spatial Database Files
+\end_layout
+
+\begin_layout Standard
+The spatial database files for the Dirichlet boundary condition specify
+ the fixed displacements.
+ The spatial database file may contain displacements at more degrees of
+ freedom than those specified in the Dirichlet boundary condition settings
+ using the 
+\family typewriter
+bc_dof
+\family default
+ setting.
+ Only those listed in 
+\family typewriter
+bc_dof
+\family default
+ will be used.
+ This permits using the same spatial database file for multiple Dirichlet
+ boundary conditions with the same displacement field.
+\end_layout
+
+\begin_layout Standard
+\noindent
+\align center
+\begin_inset Float table
+placement H
+wide false
+sideways false
+status open
+
+\begin_layout Plain Layout
+\noindent
+\align center
+\begin_inset Caption
+
+\begin_layout Plain Layout
+Values in the spatial databases used for Dirichlet boundary conditions.
+\end_layout
+
+\end_inset
+
+
+\begin_inset VSpace defskip
+\end_inset
+
+
+\begin_inset Tabular
+<lyxtabular version="3" rows="4" columns="2">
+<features tabularvalignment="middle">
+<column alignment="center" valignment="top" width="0">
+<column alignment="center" valignment="top" width="4in">
+<row>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\series bold
+Spatial database
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\series bold
+Name in Spatial Database
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+db_initial
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+displacement-x, displacement-y, displacement-z
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+db_rate
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+displacement-rate-x, displacement-rate-y, displacement-rate-z, rate-start-time
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+db_change
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+displacement-x, displacement-y, displacement-z, change-start-time
+\end_layout
+
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Subsection
+Neumann Boundary Conditions
+\end_layout
+
+\begin_layout Standard
+Neumann boundary conditions are surface tractions applied over a subset
+ of the mesh.
+ As with the DirichletBoundary condition, each Neumann boundary condition
+ can only be applied to a simply-connected surface.
+ The surface over which the tractions are applied always has a spatial dimension
+ that is one less than the dimension of the finite-element mesh.
+ Traction values are computed at the integration points of each cell on
+ the surface, using values from a spatial database.
+ The tractions are integrated over each cell and assembled to obtain the
+ forces applied at the vertices.
+ See Section 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "sub:Tutorial-twoquad4-traction"
+
+\end_inset
+
+ for a tutorial that uses Neumann boundary conditions.
+\end_layout
+
+\begin_layout Subsubsection
+Neumann Boundary Condition Parameters
+\end_layout
+
+\begin_layout Standard
+The Neumann boundary condition properties and components are:
+\end_layout
+
+\begin_layout Description
+label Name of the group of vertices defining the mesh boundary for the Neumann
+ boundary condition.
+\end_layout
+
+\begin_layout Description
+up_dir This is a 3-vector that provides a hint for the direction perpendicular
+ to the horizontal tangent direction that is not collinear with the direction
+ normal to the surface.
+ The default value is (0,0,1), which assumes that the z-axis is positive
+ upward.
+ This vector is only needed for three-dimensional problems where the positive
+ upward direction differs from the default.
+\end_layout
+
+\begin_layout Description
+output The output manager associated with diagnostic output (traction vector).
+\end_layout
+
+\begin_layout Description
+quadrature The quadrature object to be used for numerical integration.
+ Since we are integrating over a surface that is one dimension lower than
+ the problem domain, this would typically be set to something like 
+\family typewriter
+Quadrature2Din3D
+\family default
+ (for a three-dimensional problem).
+\end_layout
+
+\begin_layout Standard
+By default the output manager does not output any information.
+ The specified tractions can be output in global coordinates by including
+ ``tractions'' in the output manager's 
+\family typewriter
+cell_info_fields
+\family default
+ array parameter.
+ An example of setting these parameters in a 
+\family typewriter
+.cfg
+\family default
+ file is:
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.timedependent]
+\end_layout
+
+\begin_layout LyX-Code
+bc = [x_neg,x_pos,y_neg]
+\end_layout
+
+\begin_layout LyX-Code
+bc.x_pos = pylith.bc.Neumann ; Change BC type to Neumann
+\end_layout
+
+\begin_layout LyX-Code
+ 
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.timedependent.bc.x_pos]
+\end_layout
+
+\begin_layout LyX-Code
+label = x_pos ; Name of group of vertices for +x boundary
+\end_layout
+
+\begin_layout LyX-Code
+db_initial = spatialdata.spatialdb.SimpleDB
+\end_layout
+
+\begin_layout LyX-Code
+db_initial.label = Neumann BC +x edge
+\end_layout
+
+\begin_layout LyX-Code
+db_initial.iohandler.filename = axialtract.spatialdb
+\end_layout
+
+\begin_layout LyX-Code
+db_initial.query_type = nearest
+\end_layout
+
+\begin_layout LyX-Code
+quadrature.cell = pylith.feassemble.FIATLagrange
+\end_layout
+
+\begin_layout LyX-Code
+quadrature.cell.dimension = 1
+\end_layout
+
+\begin_layout LyX-Code
+quadrature.cell.quad_order = 2
+\end_layout
+
+\begin_layout Standard
+These settings correspond to the example problem described in Section 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "sub:Tutorial-twoquad4-traction"
+
+\end_inset
+
+.
+ It is necessary to set the boundary condition type to 
+\family typewriter
+pylith.bc.Neumann
+\family default
+, since the default value is 
+\family typewriter
+Dirichlet
+\family default
+BC.
+ Constant tractions are used for this particular problem, so a quadrature
+ order of one would have been sufficient; however, for problems involving
+ more complex variations (e.g., a linear variation), a quadrature order of
+ two will provide more accurate results.
+ Note that there is no advantage to specifying an integration order higher
+ than two, since linear elements are being used for this problem.
+\end_layout
+
+\begin_layout Standard
+\noindent
+\align center
+\begin_inset Float table
+placement H
+wide false
+sideways false
+status open
+
+\begin_layout Plain Layout
+\noindent
+\align center
+\begin_inset Caption
+
+\begin_layout Plain Layout
+\begin_inset CommandInset label
+LatexCommand label
+name "tab:neumann:output"
+
+\end_inset
+
+Fields available in output of Neumann boundary condition information.
+\end_layout
+
+\end_inset
+
+
+\begin_inset VSpace defskip
+\end_inset
+
+
+\begin_inset Tabular
+<lyxtabular version="3" rows="6" columns="3">
+<features tabularvalignment="middle">
+<column alignment="center" valignment="top" width="0">
+<column alignment="center" valignment="top" width="0">
+<column alignment="center" valignment="top" width="3in">
+<row>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\series bold
+Field Type
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\series bold
+Field
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\series bold
+Description
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+cell_info_fields
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+tracton_initial
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Initial traction field in global coordinate system
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+traction_rate
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Rate of change of traction field in global coordinate system
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+rate_start_time
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Onset time in seconds for rate of change in traction field
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+traction_change
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Amplitude of change in traction field in global coordinate system
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+change_start_time
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Onset time in seconds for the amplitude change in the traction field
+\end_layout
+
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Subsubsection
+Neumann Boundary Condition Spatial Database Files
+\end_layout
+
+\begin_layout Standard
+The spatial database files for the Neumann boundary condition specify the
+ applied tractions.
+ The number of traction components is equal to the spatial dimension for
+ the problem.
+ The tractions are specified in a local coordinate system for the boundary.
+ The names of the components of the traction vector are:
+\end_layout
+
+\begin_layout Description
+one-dimensional 
+\family typewriter
+normal
+\end_layout
+
+\begin_layout Description
+two-dimensional 
+\family typewriter
+shear
+\family default
+, 
+\family typewriter
+normal
+\end_layout
+
+\begin_layout Description
+three-dimensional 
+\family typewriter
+horiz-shear
+\family default
+, 
+\family typewriter
+vert-shear
+\family default
+, 
+\family typewriter
+normal
+\end_layout
+
+\begin_layout Standard
+Ambiguities in specifying the shear tractions in 3D problems are resolved
+ using the 
+\family typewriter
+up_dir
+\family default
+ parameter.
+ In the case of a horizontal surface, users will need to pick an alternative
+ vector, as the default 
+\family typewriter
+up_dir
+\family default
+ would coincide with the normal direction.
+ In this case, the orientation for the 
+\family typewriter
+vert-shear-traction
+\family default
+ component will correspond to whatever the user specifies for 
+\family typewriter
+up_dir
+\family default
+, rather than the actual vertical direction.
+\end_layout
+
+\begin_layout Standard
+\noindent
+\align center
+\begin_inset Float table
+placement H
+wide false
+sideways false
+status open
+
+\begin_layout Plain Layout
+\noindent
+\align center
+\begin_inset Caption
+
+\begin_layout Plain Layout
+Values in the spatial databases used for Dirichlet boundary conditions in
+ three dimensions.
+ In one- and two-dimensional problems, the names of the components are slightly
+ different as described earlier in this section.
+\end_layout
+
+\end_inset
+
+
+\begin_inset VSpace defskip
+\end_inset
+
+
+\begin_inset Tabular
+<lyxtabular version="3" rows="4" columns="2">
+<features tabularvalignment="middle">
+<column alignment="center" valignment="top" width="0">
+<column alignment="center" valignment="top" width="4in">
+<row>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\series bold
+Spatial database
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\series bold
+Name in Spatial Database
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+db_initial
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+traction-shear-horiz, traction-shear-vert, traction-normal
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+db_rate
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+traction-rate-horiz-shear, traction-rate-vert-shear, traction-rate-normal,
+ rate-start-time
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+db_change
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+traction-horiz-shear, traction-vert-shear, traction-normal, change-start-time
+\end_layout
+
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Subsection
+Point Force Boundary Conditions
+\end_layout
+
+\begin_layout Standard
+Point force boundary conditions in PyLith prescribe the application of point
+ forces to a subset of the vertices of the finite-element mesh.
+ While point force boundary conditions can be applied to any vertex, usually
+ they are applied to vertices on the lateral, top, and bottom boundaries
+ of the domain.
+\end_layout
+
+\begin_layout Subsubsection
+Point Force Parameters
+\end_layout
+
+\begin_layout Standard
+The properties and components common to both the DirichletBC and DirichletBounda
+ry boundary conditions are:
+\end_layout
+
+\begin_layout Description
+label Label of the group of vertices associated with the boundary condition.
+\end_layout
+
+\begin_layout Description
+bc_dof Array of degrees of freedom to which forces are applied (first degree
+ of freedom is 0).
+\end_layout
+
+\begin_layout Standard
+An example of setting the point force boundary condition parameters in a
+ 
+\family typewriter
+.cfg
+\family default
+ file is:
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.problem]
+\end_layout
+
+\begin_layout LyX-Code
+bc = [mybc]
+\end_layout
+
+\begin_layout LyX-Code
+bc.mybc = pylith.bc.PointForce
+\end_layout
+
+\begin_layout LyX-Code
+
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.problem.bc.mybc]
+\end_layout
+
+\begin_layout LyX-Code
+label = group A 
+\end_layout
+
+\begin_layout LyX-Code
+bc_dof = [2] ; fixed displacement in z direction
+\end_layout
+
+\begin_layout LyX-Code
+db_initial = spatialdata.spatialdb.SimpleDB
+\end_layout
+
+\begin_layout LyX-Code
+db_initial.iohandler.filename = force_A.spatialdb
+\end_layout
+
+\begin_layout LyX-Code
+db_initial.query_type = nearest ; change query type to nearest point algorithm
+\end_layout
+
+\begin_layout LyX-Code
+db_rate = spatialdata.spatialdb.UniformDB
+\end_layout
+
+\begin_layout LyX-Code
+db_rate.values = [force-rate-z]
+\end_layout
+
+\begin_layout LyX-Code
+db_rate.data = [1.0e+5*newton/s]
+\end_layout
+
+\begin_layout Standard
+We have created an array with one boundary condition, mybc.
+ The group of vertices associated with the boundary condition is group A.
+ For the database associated with the constant force, we use a SimpleDB.
+ We set the filename and query type for the database.
+ For the rate of change of values, we use a UniformDB and specify the rate
+ of change in the force to be 1.0e+5 Newton/s.
+ See Section 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "sec:spatial:databases"
+
+\end_inset
+
+ for a discussion of the different types of spatial databases available.
+\end_layout
+
+\begin_layout Subsubsection
+Point Force Spatial Database Files
+\end_layout
+
+\begin_layout Standard
+The spatial database files for the Dirichlet boundary condition specify
+ the fixed displacements.
+ The spatial database file may contain displacements at more degrees of
+ freedom than those specified in the Dirichlet boundary condition settings
+ using the 
+\family typewriter
+bc_dof
+\family default
+ setting.
+ Only those listed in 
+\family typewriter
+bc_dof
+\family default
+ will be used.
+ This permits using the same spatial database file for multiple Dirichlet
+ boundary conditions with the same displacement field.
+\end_layout
+
+\begin_layout Standard
+\noindent
+\align center
+\begin_inset Float table
+placement H
+wide false
+sideways false
+status open
+
+\begin_layout Plain Layout
+\noindent
+\align center
+\begin_inset Caption
+
+\begin_layout Plain Layout
+Values in the spatial databases used for point force boundary conditions.
+\end_layout
+
+\end_inset
+
+
+\begin_inset VSpace defskip
+\end_inset
+
+
+\begin_inset Tabular
+<lyxtabular version="3" rows="4" columns="2">
+<features tabularvalignment="middle">
+<column alignment="center" valignment="top" width="0">
+<column alignment="center" valignment="top" width="4in">
+<row>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\series bold
+Spatial database
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\series bold
+Name in Spatial Database
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+db_initial
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+force-x, force-y, force-z
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+db_rate
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+force-rate-x, force-rate-y, force-rate-z, rate-start-time
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+db_change
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+force-x, force-y, force-z, change-start-time
+\end_layout
+
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Section
+\begin_inset CommandInset label
+LatexCommand label
+name "sec:absorbing:boundaries"
+
+\end_inset
+
+Absorbing Boundary Conditions
+\end_layout
+
+\begin_layout Standard
+This boundary condition attempts to prevent seismic waves reflecting off
+ of a boundary by placing simple dashpots on the boundary.
+ Normally incident dilatational and shear waves are perfectly absorbed.
+ Waves incident at other angles are only partially absorbed.
+ This boundary condition is simpler than a perfectly matched layer (PML)
+ boundary condition but does not perform quite as well, especially for surface
+ waves.
+ If the waves arriving at the absorbing boundary are relatively small in
+ amplitude compared to the amplitudes of primary interest, this boundary
+ condition gives reasonable results.
+\end_layout
+
+\begin_layout Standard
+The Absorbing boundary condition properties and components are:
+\end_layout
+
+\begin_layout Description
+label Name of the group of vertices defining the mesh boundary for the absorbing
+ boundary condition.
+\end_layout
+
+\begin_layout Description
+up_dir This is a 3-vector that provides a hint for the direction perpendicular
+ to the horizontal tangent direction that is not collinear with the direction
+ normal to the surface.
+ The default value is (0,0,1), which assumes that the z-axis is positive
+ upward.
+ This vector is only needed for three-dimensional problems where the positive
+ upward direction differs from the default.
+\end_layout
+
+\begin_layout Description
+db The spatial database specifying the material properties for the seismic
+ velocities.
+\end_layout
+
+\begin_layout Description
+quadrature The quadrature object to be used for numerical integration.
+ Since we are integrating over a surface that is one dimension lower than
+ the problem domain, this would typically be set to something like 
+\family typewriter
+Quadrature2Din3D
+\family default
+ (for a three-dimensional problem).
+\end_layout
+
+\begin_layout Subsection
+Finite-Element Implementation of Absorbing Boundary
+\end_layout
+
+\begin_layout Standard
+Consider a plane wave propagating at a velocity 
+\begin_inset Formula $c$
+\end_inset
+
+.
+ We can write the displacement field as
+\begin_inset Formula 
+\begin{equation}
+\vec{u}(\vec{x},t)=\vec{u^{t}}(t-\frac{\vec{x}}{c}),
+\end{equation}
+
+\end_inset
+
+where 
+\begin_inset Formula $\vec{x}$
+\end_inset
+
+ is position, 
+\begin_inset Formula $t$
+\end_inset
+
+ is time, and 
+\begin_inset Formula $\vec{u^{t}}$
+\end_inset
+
+ is the shape of the propagating wave.
+ For an absorbing boundary we want the traction on the boundary to be equal
+ to the traction associated with wave propagating out of the domain.
+ Starting with the expression for the traction on a boundary, 
+\begin_inset Formula $T_{i}=\sigma_{ij}n_{j},$
+\end_inset
+
+ and using the local coordinate system for the boundary 
+\begin_inset Formula $s_{h}s_{v}n,$
+\end_inset
+
+ where 
+\begin_inset Formula $\vec{n}$
+\end_inset
+
+ is the direction normal to the boundary, 
+\begin_inset Formula $\overrightarrow{s}_{h}$
+\end_inset
+
+ is the horizontal direction tangent to the boundary, and 
+\begin_inset Formula $\overrightarrow{s}_{v}$
+\end_inset
+
+ is the vertical direction tangent to the boundary, the tractions on the
+ boundary are
+\begin_inset Formula 
+\begin{gather}
+T_{s_{h}}=\sigma_{s_{h}n}\\
+T_{s_{v}}=\sigma_{s_{v}n}\\
+T_{n}=\sigma_{nn}.
+\end{gather}
+
+\end_inset
+
+In the case of a horizontal boundary, we can define an auxiliary direction
+ in order to assign unique tangential directions.
+ For a linear elastic isotropic material, 
+\begin_inset Formula $\sigma_{ij}=\lambda\epsilon_{kk}\delta_{ij}+2\mu\epsilon_{ij},$
+\end_inset
+
+ and we can write the tractions as 
+\begin_inset Formula 
+\begin{gather}
+T_{s_{h}}=2\mu\epsilon_{s_{h}n}\\
+T_{s_{v}}=2\epsilon_{s_{v}n}\\
+T_{n}=(\lambda+2\mu)\epsilon_{nn}+\lambda(\epsilon_{s_{h}s_{h}}+\epsilon_{s_{v}s_{v}}).
+\end{gather}
+
+\end_inset
+
+For infinitesimal strains, 
+\begin_inset Formula $\epsilon_{ij}=\frac{1}{2}(u_{i,j}+u_{j,i})$
+\end_inset
+
+ and we have
+\begin_inset Formula 
+\begin{gather}
+\epsilon_{s_{h}n}=\frac{1}{2}(u_{s_{h},n}+u_{n,s_{h}})\\
+\epsilon_{s_{v}n}=\frac{1}{2}(u_{s_{v},n}+u_{n,s_{v}})\\
+\epsilon_{nn}=u_{n,n}.
+\end{gather}
+
+\end_inset
+
+For our propagating plane wave, we recognize that
+\begin_inset Formula 
+\begin{equation}
+\frac{\partial\vec{u^{t}}(t-\frac{\vec{x}}{c})}{\partial x_{i}}=-\frac{1}{c}\frac{\partial\vec{u^{t}}(t-\frac{\vec{x}}{c})}{\partial t},
+\end{equation}
+
+\end_inset
+
+so that our expressions for the tractions become
+\begin_inset Formula 
+\begin{gather}
+T_{s_{h}}=-\frac{\mu}{c}\left(\frac{\partial u_{s_{h}}^{t}(t-\frac{\vec{x}}{c})}{\partial t}+\frac{\partial u_{n}^{t}(t-\frac{\vec{x}}{c})}{\partial t}\right),\\
+T_{s_{v}}=-\frac{\mu}{c}\left(\frac{\partial u_{s_{v}}^{t}(t-\frac{\vec{x}}{c})}{\partial t}+\frac{\partial u_{n}^{t}(t-\frac{\vec{x}}{c})}{\partial t}\right).
+\end{gather}
+
+\end_inset
+
+For the normal traction, consider a dilatational wave propagating normal
+ to the boundary at speed 
+\begin_inset Formula $v_{p}$
+\end_inset
+
+; in this case 
+\begin_inset Formula $u_{s_{h}}=u_{s_{v}}=0$
+\end_inset
+
+ and 
+\begin_inset Formula $c=v_{p}$
+\end_inset
+
+.
+ For the shear tractions, consider a shear wave propagating normal to the
+ boundary at speed 
+\begin_inset Formula $v_{s}$
+\end_inset
+
+; we can decompose this into one case where 
+\begin_inset Formula $u_{n}=u_{s_{v}}=0$
+\end_inset
+
+ and another case where 
+\begin_inset Formula $u_{n}=u_{s_{h}}=0$
+\end_inset
+
+, with 
+\begin_inset Formula $c=v_{s}$
+\end_inset
+
+ in both cases.
+ We also recognize that 
+\begin_inset Formula $\mu=\rho v_{s}^{2}$
+\end_inset
+
+ and 
+\begin_inset Formula $\lambda+2\mu=\rho v_{p}^{2}$
+\end_inset
+
+.
+ This leads to the following expressions for the tractions:
+\begin_inset Formula 
+\begin{gather}
+T_{s_{h}}=-\rho v_{s}\frac{\partial u_{s_{h}}^{t}(t-\frac{\vec{x}}{c})}{\partial t}\\
+T_{s_{v}}=-\rho v_{s}\frac{\partial u_{v}^{t}(t-\frac{\vec{x}}{c})}{\partial t}\\
+T_{n}=-\rho v_{p}\frac{\partial u_{n}^{t}(t-\frac{\vec{x}}{c})}{\partial t}
+\end{gather}
+
+\end_inset
+
+We write the weak form of the boundary condition as
+\begin_inset Formula 
+\[
+\int_{S_{T}}T_{i}\phi_{i}\, dS=\int_{S_{T}}-\rho c_{i}\frac{\partial u_{i}}{\partial t}\phi_{i}\, dS,
+\]
+
+\end_inset
+
+where 
+\begin_inset Formula $c_{i}$
+\end_inset
+
+ equals 
+\begin_inset Formula $v_{p}$
+\end_inset
+
+ for the normal traction and 
+\begin_inset Formula $v_{s}$
+\end_inset
+
+ for the shear tractions, and 
+\begin_inset Formula $\phi_{i}$
+\end_inset
+
+ is our weighting function.
+ We express the trial solution and weighting function as linear combinations
+ of basis functions,
+\begin_inset Formula 
+\begin{gather}
+u_{i}=\sum_{m}a_{i}^{m}N^{m},\\
+\phi_{i}=\sum_{n}c_{i}^{n}N^{n}.
+\end{gather}
+
+\end_inset
+
+Substituting into our integral over the absorbing boundaries yields
+\end_layout
+
+\begin_layout Standard
+\begin_inset Formula 
+\begin{equation}
+\int_{S_{T}}T_{i}\phi_{i}\, dS=\int_{S_{T}}-\rho c_{i}\sum_{m}\dot{a}_{i}^{m}N^{m}\sum_{n}c_{i}^{n}N^{n}\, dS.
+\end{equation}
+
+\end_inset
+
+In the derivation of the governing equations, we recognized that the weighting
+ function is arbitrary, so we form the residual by setting the terms associated
+ with the coefficients 
+\begin_inset Formula $c_{i}^{n}$
+\end_inset
+
+ to zero,
+\end_layout
+
+\begin_layout Standard
+\begin_inset Formula 
+\begin{equation}
+r_{i}^{n}=\sum_{\text{tract cells}}\sum_{\text{quad pts}}-\rho(x_{q})c_{i}(x_{q})\sum_{m}\dot{a}_{i}^{m}N^{m}(x_{q})N^{n}(x_{q})w_{q}|J_{cell}(x_{q})|,
+\end{equation}
+
+\end_inset
+
+ where 
+\begin_inset Formula $x_{q}$
+\end_inset
+
+ are the coordinates of the quadrature points, 
+\begin_inset Formula $w_{q}$
+\end_inset
+
+ are the weights of the quadrature points, and 
+\begin_inset Formula $|J_{cell}(x_{q})|$
+\end_inset
+
+ is the determinant of the Jacobian matrix evaluated at the quadrature points
+ associated with mapping the reference cell to the actual cell.
+\end_layout
+
+\begin_layout Standard
+The appearance of velocity in the expression for the residual means that
+ the absorbing dampers also contribute to the system Jacobian matrix.
+ Use the central difference method, the velocity is written in terms of
+ the displacements,
+\end_layout
+
+\begin_layout Standard
+\begin_inset Formula 
+\begin{equation}
+\dot{u}_{i}(t)=\frac{1}{2\Delta t}(u_{i}(t+\Delta t)-u_{i}(t-\Delta t)).
+\end{equation}
+
+\end_inset
+
+Expressing the displacement at time 
+\begin_inset Formula $t+\Delta t$
+\end_inset
+
+ in terms of the displacement at time 
+\begin_inset Formula $t$
+\end_inset
+
+ (
+\begin_inset Formula $u_{i}(t)$
+\end_inset
+
+) and the increment in the displacement at time 
+\begin_inset Formula $t$
+\end_inset
+
+ (
+\begin_inset Formula $du_{i}(t)$
+\end_inset
+
+) leads to
+\end_layout
+
+\begin_layout Standard
+\begin_inset Formula 
+\begin{equation}
+\dot{u}_{i}(t)=\frac{1}{2\Delta t}(du_{i}(t)+u_{i}(t)-u_{i}(t-\Delta t))
+\end{equation}
+
+\end_inset
+
+The terms contributing to the system Jacobian are associated with the increment
+ in the displacement at time time.
+ Substituting into the governing equations and isolating the term associated
+ with the increment in the displacement at time t yields
+\end_layout
+
+\begin_layout Standard
+\begin_inset Formula 
+\begin{equation}
+A_{ij}^{nm}=\sum_{\text{tract cells}}\sum_{\text{quad pts}}\delta_{ij}\frac{1}{2\Delta t}\rho(x_{q})v_{i}(x_{q})N^{m}(x_{q})N^{n}(x_{q})w_{q}|J_{cells}(x_{q})|,
+\end{equation}
+
+\end_inset
+
+where 
+\begin_inset Formula $A_{ij}^{mn}$
+\end_inset
+
+ is a 
+\begin_inset Formula $nd$
+\end_inset
+
+ by 
+\begin_inset Formula $md$
+\end_inset
+
+ matrix (
+\begin_inset Formula $d$
+\end_inset
+
+ is the dimension of the vector space), 
+\begin_inset Formula $m$
+\end_inset
+
+ and 
+\begin_inset Formula $n$
+\end_inset
+
+ refer to the basis functions and 
+\begin_inset Formula $i$
+\end_inset
+
+ and 
+\begin_inset Formula $j$
+\end_inset
+
+ are vector space components.
+\end_layout
+
+\begin_layout Section
+\begin_inset CommandInset label
+LatexCommand label
+name "sec:fault"
+
+\end_inset
+
+Fault Interface Conditions
+\end_layout
+
+\begin_layout Standard
+Fault interfaces are used to create dislocations (jumps in the displacement
+ field) in the model.
+ The dislocations arise from slip across a fault surface.
+ Both shear and tensile dislocations are supported.
+ For fault interfaces, dislocations in 1D correspond to fault-opening (and
+ closing), in 2D lateral-slip and fault opening, and in 3D lateral-slip,
+ reverse-slip, and fault opening.
+ PyLith supports kinematic (prescribed) slip and dynamic (spontaneous) rupture
+ simulations.
+\end_layout
+
+\begin_layout Subsection
+Conventions
+\end_layout
+
+\begin_layout Standard
+Slip corresponds to relative motion across a fault surface.
+ Figure 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "fig:fault:orientation"
+
+\end_inset
+
+ shows the orientation of the slip vector in 3D with respect to the fault
+ surface and coordinate axes.
+ PyLith automatically determines the orientation of the fault surface.
+ This alleviates the user from having to compute the strike, dip, and rake
+ angles over potentially complex, nonplanar fault surfaces.
+ Instead, the user specifies fault parameters in terms of lateral motion,
+ reverse motion, and fault opening as shown in Figure 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "fig:fault:slip:motions"
+
+\end_inset
+
+.
+\end_layout
+
+\begin_layout Standard
+\noindent
+\align center
+\begin_inset Float figure
+placement H
+wide false
+sideways false
+status open
+
+\begin_layout Plain Layout
+\align center
+\begin_inset Graphics
+	filename figs/faultOrientation.eps
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Plain Layout
+\begin_inset Caption
+
+\begin_layout Plain Layout
+Orientation of a fault surface in 3D, where 
+\begin_inset Formula $\phi$
+\end_inset
+
+ denotes the angle of the fault strike, 
+\begin_inset Formula $\delta$
+\end_inset
+
+ denotes the angle of the fault dip, and 
+\begin_inset Formula $\lambda$
+\end_inset
+
+ the rake angle.
+ 
+\begin_inset CommandInset label
+LatexCommand label
+name "fig:fault:orientation"
+
+\end_inset
+
+ 
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+\noindent
+\align center
+\begin_inset Float figure
+placement H
+wide false
+sideways false
+status open
+
+\begin_layout Plain Layout
+\align center
+\begin_inset Graphics
+	filename figs/slipmotions.eps
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Plain Layout
+\begin_inset Caption
+
+\begin_layout Plain Layout
+Sign conventions associated with fault slip.
+ Positive values are associated with left-lateral, reverse, and fault opening
+ motions.
+\begin_inset CommandInset label
+LatexCommand label
+name "fig:fault:slip:motions"
+
+\end_inset
+
+ 
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Subsection
+Fault Implementation
+\end_layout
+
+\begin_layout Standard
+In order to create relative motion across the fault surface in the finite-elemen
+t mesh, additional degrees of freedom are added along with adjustment of
+ the topology of the mesh.
+ These additional degrees of freedom are associated with cohesive cells.
+ These zero-volume cells allow control of the relative motion between vertices
+ on the two sides of the fault.
+ PyLith automatically adds cohesive cells for each fault surface.
+ Figure 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "fig:fault:cohesive:quad4"
+
+\end_inset
+
+ illustrates the results of inserting a cohesive cell in a mesh consisting
+ of two quadrilateral cells.
+\end_layout
+
+\begin_layout Standard
+\noindent
+\align center
+\begin_inset Float figure
+placement H
+wide false
+sideways false
+status open
+
+\begin_layout Plain Layout
+\align center
+\begin_inset Graphics
+	filename figs/quad4cohesivekin.eps
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Plain Layout
+\begin_inset Caption
+
+\begin_layout Plain Layout
+Example of cohesive cell inserted into a mesh of two quadrilateral cells.
+ The zero thickness cohesive cell (shown with dashed lines) controls slip
+ on the fault via the relative motion between vertices 3 and 7 and 2 and
+ 6.
+\begin_inset CommandInset label
+LatexCommand label
+name "fig:fault:cohesive:quad4"
+
+\end_inset
+
+ 
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Subsection
+Fault Parameters
+\end_layout
+
+\begin_layout Standard
+The principal parameters for fault interface conditions are:
+\end_layout
+
+\begin_layout Description
+id This is an integer identifier for the fault surface.
+ It is used to specify the 
+\family typewriter
+material-id
+\family default
+ of the cohesive cells in the mesh.
+ Material identifiers must be unique so this value cannot be the same as
+ any of the material models or any other fault.
+\end_layout
+
+\begin_layout Description
+name Name or label for the fault.
+ This associates sets of vertices with the fault surface in addition to
+ being used in error and diagnostic reports.
+\end_layout
+
+\begin_layout Description
+up_dir Up-dir or up direction (used in 2D and 3D simulations).
+ In 2D the default in-plane slip is left-lateral, so we use the up-direction
+ to resolve the ambiguity in specifying reverse slip.
+ In 3D the up-direction is used to resolve the ambiguity in the along-strike
+ and dip-dir directions.
+ If the fault plane is horizontal, then the up-dir corresponds to the reverse-mo
+tion on the +z side of the fault.
+ The only requirement for this direction is that it not be collinear with
+ the fault normal direction.
+ The default value of [0, 0, 1] is appropriate for most 3D problems.
+\end_layout
+
+\begin_layout Description
+quadrature Quadrature object used in integrating fault quantities.
+\end_layout
+
+\begin_layout Description
+output Manager for output of diagnostic and data fields for the fault.
+\end_layout
+
+\begin_layout Standard
+By default the output manager outputs both diagnostic information (e.g., fault
+ normal direction) and the slip at each time step.
+ Tables 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "tab:fault:kin:output"
+
+\end_inset
+
+ and 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "tab:fault:dyn:output"
+
+\end_inset
+
+ list the fields available for output for a fault with kinematic (prescribed)
+ earthquake rupture and a fault with dynamic rupture, respectively.
+ The fault coordinate system is shown in Figure 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "fig:fault:slip:motions"
+
+\end_inset
+
+.
+ The vectors in the fault coordinate system can be transformed to the global
+ coordinate system using the direction vectors in the diagnostic output.
+ An example of setting these parameters in a 
+\family typewriter
+.cfg
+\family default
+ file is:
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.problem]
+\end_layout
+
+\begin_layout LyX-Code
+interfaces = [fault]
+\end_layout
+
+\begin_layout LyX-Code
+
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.problem.interfaces]
+\end_layout
+
+\begin_layout LyX-Code
+fault = pylith.faults.FaultCohesiveKin ; default
+\end_layout
+
+\begin_layout LyX-Code
+
+\end_layout
+
+\begin_layout LyX-Code
+label = fault A ; Group of vertices defining the fault surface
+\end_layout
+
+\begin_layout LyX-Code
+id = 100 ; Value for material identifier associated with fault's cohesive
+ cells
+\end_layout
+
+\begin_layout LyX-Code
+up_dir = [0, 0, 1] ; default
+\end_layout
+
+\begin_layout LyX-Code
+quadrature.cell = pylith.feassemble.FIATLagrange
+\end_layout
+
+\begin_layout LyX-Code
+quadrature.cell.dimension = 2
+\end_layout
+
+\begin_layout Standard
+The group of vertices has the label ``fault A.'' We replicate the default
+ values for the fault ``up'' direction.
+ These settings apply to a 2D fault surface embedded within a 3D mesh, so
+ we use 2D Lagrange reference cells.
+ The spatial database for elastic properties is used to determine the approximat
+e shear modulus and condition the equations for faster convergence rates.
+\end_layout
+
+\begin_layout Subsection
+Kinematic Earthquake Rupture
+\end_layout
+
+\begin_layout Standard
+Kinematic earthquake ruptures use the FaultCohesiveKin object to specify
+ the slip as a function of time on the fault surface.
+ Slip may evolve simultaneously over the fault surface instantaneously in
+ a single time step (as is usually done in quasi-static simulations) or
+ propagate over the fault surface over hundreds and up to thousands of time
+ steps (as is usually done in a dynamic simulation).
+\end_layout
+
+\begin_layout Subsubsection
+Governing Equations
+\end_layout
+
+\begin_layout Standard
+The insertion of cohesive cells into the finite-element mesh has the effect
+ of decoupling the motion of the two sides of the fault surface.
+ In order to impose the desired relative motion, we must adjust the governing
+ equations.
+ PyLith employs Lagrange multiplier constraints to enforce the constraint
+ of the relative motion in the strong sense.
+ That is, we enforce the slip across the fault at each degree of freedom.
+\end_layout
+
+\begin_layout Standard
+In conventional implementations the additional degrees of freedom associated
+ with the Lagrange multipliers results in a complex implementation.
+ However, the use of Lagrange multiplier constraints with cohesive cells
+ provides for a simple formulation; we simply add the additional degrees
+ of freedom associated with the Lagrange multipliers to the cohesive cells
+ as shown in Figure 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "fig:fault:cohesive:quad4"
+
+\end_inset
+
+.
+ As a result, the fault implementation is completely confined to the cohesive
+ cell.
+ Furthermore, the Lagrange multiplier constraints correspond to forces required
+ to impose the relative motions, so they are related to the change in stress
+ on the fault surface associated with fault slip.
+ If we write the algebraic system of equations we are solving in the form
+\begin_inset Formula 
+\begin{equation}
+\underline{A}\overrightarrow{u}=\overrightarrow{b}\,,
+\end{equation}
+
+\end_inset
+
+then including the Lagrange multiplier constraints results in
+\begin_inset Formula 
+\begin{equation}
+\left[\begin{array}{cc}
+\underline{A} & \underline{C}^{T}\\
+\underline{C} & 0
+\end{array}\right]\left[\begin{array}{c}
+\overrightarrow{u}\\
+\overrightarrow{l}
+\end{array}\right]=\left[\begin{array}{c}
+\overrightarrow{b}\\
+\overrightarrow{d}
+\end{array}\right]\,,\label{eq:fault:cohesive:lagrange}
+\end{equation}
+
+\end_inset
+
+where 
+\begin_inset Formula $\overrightarrow{l}$
+\end_inset
+
+ is the vector of Lagrange multipliers and 
+\begin_inset Formula $\underline{C}$
+\end_inset
+
+ is composed of rotation submatrices, 
+\begin_inset Formula $\underline{R}$
+\end_inset
+
+, associated with the direction cosines relating the relative displacements
+ across the fault to the vector of fault slip, 
+\begin_inset Formula $\overrightarrow{d}$
+\end_inset
+
+.
+ Note that by using the direction cosines to relate the relative motion
+ across the fault, the slip vector and Lagrange multipliers (forces required
+ to impose the slip) are in the local fault coordinate system (lateral motion,
+ reverse motion, and fault opening).
+ 
+\end_layout
+
+\begin_layout Paragraph
+Non-diagonal A
+\end_layout
+
+\begin_layout Standard
+The Lagrange multipliers contribute to both the system Jacobian matrix and
+ the residual.
+ Because we enforce the constraints in a strong sense, the terms do not
+ involve integrals over the fault surface.
+ The additional terms in the residual are
+\begin_inset Formula 
+\begin{gather}
+r_{i}^{n}=-C_{ji}^{pn}l_{j}^{p},\\
+r_{i}^{p}=d_{i}^{p}-C_{ij}^{pn}u_{j}^{n},
+\end{gather}
+
+\end_inset
+
+where 
+\begin_inset Formula $n$
+\end_inset
+
+ denotes a conventional degree of freedom and 
+\begin_inset Formula $p$
+\end_inset
+
+ denotes a degree of freedom associated with a Lagrange multiplier.
+ The additional terms in the system Jacobian matrix are simply the direction
+ cosines,
+\begin_inset Formula 
+\begin{gather}
+J_{ij}^{np}=C_{ji}^{pn},\\
+J_{ij}^{pn}=C_{ij}^{pn}.
+\end{gather}
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Paragraph
+Diagonal A
+\end_layout
+
+\begin_layout Standard
+When we use a lumped system Jacobian matrix, we cannot lump the terms associated
+ with the Lagrange multipliers.
+ Instead, we formulate the Jacobian ignoring the contributions from the
+ Lagrange multipliers, and then adjust the solution after the solve to account
+ for their presence.
+ Including the Lagrange multipliers in the general expression for the residual
+ at time 
+\begin_inset Formula $t+\Delta t$
+\end_inset
+
+, we have
+\begin_inset Formula 
+\begin{equation}
+r_{i}^{n}(t+\Delta t)=A_{ij}^{nm}(u_{j}^{m}(t)+du_{j}^{m}(t))+C_{ki}^{pn}(l_{k}^{p}(t)+dl_{k}^{p}(t)),
+\end{equation}
+
+\end_inset
+
+where we have written the displacements and Lagrange multipliers at time
+ 
+\begin_inset Formula $t+\Delta t$
+\end_inset
+
+ in terms of the values at time 
+\begin_inset Formula $t$
+\end_inset
+
+ and the increment from time 
+\begin_inset Formula $t$
+\end_inset
+
+ to 
+\begin_inset Formula $t+\Delta t$
+\end_inset
+
+.
+ When we solve the lumped system ignoring the Lagrange multipliers contributions
+ to the Jacobian, we formulate the residual assuming the values 
+\begin_inset Formula $du_{i}^{n}$
+\end_inset
+
+(t) and 
+\begin_inset Formula $dl_{k}^{p}(t)$
+\end_inset
+
+ are zero.
+ So our task is to determine the increment in the Lagrange multiplier, 
+\begin_inset Formula $dl_{k}^{p}$
+\end_inset
+
+, and the correction to the displacement increment, 
+\begin_inset Formula $du_{i}^{n}$
+\end_inset
+
+, and by setting the residual with all terms included to zero; thus, we
+ have
+\begin_inset Formula 
+\begin{gather}
+A_{ij}^{nm}(u_{j}^{m}(t)+du_{j}^{m}(t))+C_{ki}^{pn}(l_{k}^{p}(t)+dl_{k}^{p}(t))=0\text{ subject to}\\
+C_{ij}^{pn}(u_{j}^{n}(t)+du_{j}^{n}(t))=d_{i}^{p}.
+\end{gather}
+
+\end_inset
+
+Making use of the residual computed with 
+\begin_inset Formula $du_{i}^{n}(t)=0$
+\end_inset
+
+ and 
+\begin_inset Formula $dl_{k}^{p}(t)=0$
+\end_inset
+
+,
+\begin_inset Formula 
+\begin{gather}
+r_{i}^{n}+A_{ij}^{nm}du_{j}^{m}+C_{ki}^{pn}dl_{k}^{p}=0\text{ subject to}\\
+C_{ij}^{pn}(u_{j}^{n}(t)+du_{j}^{n}(t))=d_{i}^{p}.
+\end{gather}
+
+\end_inset
+
+Explicitly writing the equations for the vertices on the negative and positive
+ sides of the fault yields
+\begin_inset Formula 
+\begin{gather}
+r_{i}^{n-}+A_{ij}^{nm-}du_{j}^{m-}+R_{ki}^{pn}dl_{k}^{p}=0,\\
+r_{i}^{n+}+A_{ij}^{nm+}du_{j}^{m+}+R_{ki}^{pn}dl_{k}^{p}=0,\\
+R_{ij}^{pn}(u_{j}^{n+}+du_{j}^{n+}-u_{j}^{n-}-du_{j}^{n-})=d_{i}^{p}.
+\end{gather}
+
+\end_inset
+
+Solving the first two equations for 
+\begin_inset Formula $du_{j}^{m-}$
+\end_inset
+
+ and 
+\begin_inset Formula $du_{j}^{m+}$
+\end_inset
+
+ and combining them using the third equation leads to
+\begin_inset Formula 
+\begin{multline}
+R_{ij}^{pn}\left((A_{ij}^{nm+})^{-1}+(A_{ij}^{nm+})^{-1}\right)R_{ki}^{pn}dl_{k}^{p}=d_{i}^{p}-R_{ij}^{pn}(u_{j}^{n+}-u_{j}^{n-})\\
++R_{ij}^{pn}\left((A_{ij}^{nm+})^{-1}r_{i}^{n+}-(A_{ij}^{nm-})^{-1}r_{i}^{n-}\right).
+\end{multline}
+
+\end_inset
+
+We do not allow overlap between the fault interface and the absorbing boundary,
+ so 
+\begin_inset Formula $A_{ij}^{nm}$
+\end_inset
+
+ is the same for all components at a vertex.
+ As a result the matrix on the left hand side simplifies to
+\begin_inset Formula 
+\begin{equation}
+S_{ik}^{pn}=\delta_{ik}\left(\frac{1}{A^{nm+}}+\frac{1}{A^{nm-}}\right),
+\end{equation}
+
+\end_inset
+
+and
+\begin_inset Formula 
+\begin{equation}
+dl_{k}^{p}=(S_{ik}^{pn})^{-1}\left(d_{i}^{p}-R_{ij}^{pn}(u_{j}^{n+}-u_{j}^{n-})+R_{ij}^{pn}\left((A_{ij}^{nm+})^{-1}r_{i}^{n+}-(A_{ij}^{nm-})^{-1}r_{i}^{n-}\right)\right).
+\end{equation}
+
+\end_inset
+
+Now that we know the value of the increment in the Lagrange multiplier from
+ time 
+\begin_inset Formula $t$
+\end_inset
+
+ to time 
+\begin_inset Formula $t+\Delta t$
+\end_inset
+
+, we can correct the value for the displacement increment from time 
+\begin_inset Formula $t$
+\end_inset
+
+ to 
+\begin_inset Formula $t+\Delta t$
+\end_inset
+
+ using
+\begin_inset Formula 
+\begin{gather}
+\Delta du_{j}^{n-}=(A_{ij}^{nm-})^{-1}C_{ki}^{pn}dl_{k}^{p}\text{ and}\\
+\Delta du_{j}^{n+}=-(A_{ij}^{nm+})^{-1}C_{ki}^{pn}dl_{k}^{p}.
+\end{gather}
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Subsubsection
+Arrays of Kinematic Rupture Components
+\end_layout
+
+\begin_layout Standard
+Multiple earthquake ruptures can be specified on a single fault surface.
+ This permits repeatedly rupturing the same portion of a fault or combining
+ earthquake rupture on one subset of the fault surface with steady aseismic
+ slip on another subset (the two subsets may overlap in both time and space).
+ A dynamic array of kinematic earthquake rupture components associates a
+ name (string) with each kinematic rupture.
+ The default dynamic array contains a single earthquake rupture, ``rupture''.
+ The 
+\family typewriter
+eq_srcs
+\family default
+ is the 
+\family typewriter
+FaultCohesiveKin
+\family default
+ facility for this dynamic array.
+ An example of setting the array of kinematic rupture components in a 
+\family typewriter
+.cfg
+\family default
+ file:
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.problem.interfaces.fault]
+\end_layout
+
+\begin_layout LyX-Code
+eq_srcs = [earthquake,creep]
+\end_layout
+
+\begin_layout Standard
+The output manager includes generic fault information (orientation) as well
+ as the final slip or slip rate (as in the case of the constant slip rate
+ slip time function) and slip initiation time for each kinematic rupture.
+ The name of the slip and slip initiation time vertex fields are of the
+ form 
+\family typewriter
+final_slip_NAME
+\family default
+ and 
+\family typewriter
+slip_time_NAME
+\family default
+, respectively, where 
+\family typewriter
+NAME
+\family default
+ refers to the name used in the dynamic array of kinematic ruptures, 
+\family typewriter
+eq_srcs
+\family default
+.
+\end_layout
+
+\begin_layout Standard
+\noindent
+\align center
+\begin_inset Float table
+placement H
+wide false
+sideways false
+status open
+
+\begin_layout Plain Layout
+\noindent
+\align center
+\begin_inset Caption
+
+\begin_layout Plain Layout
+\begin_inset CommandInset label
+LatexCommand label
+name "tab:fault:kin:output"
+
+\end_inset
+
+Fields available in output of fault information.
+\end_layout
+
+\end_inset
+
+
+\begin_inset VSpace defskip
+\end_inset
+
+
+\begin_inset Tabular
+<lyxtabular version="3" rows="8" columns="3">
+<features tabularvalignment="middle">
+<column alignment="center" valignment="top" width="0">
+<column alignment="center" valignment="top" width="0">
+<column alignment="center" valignment="top" width="3.5in">
+<row>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\series bold
+Field Type
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\series bold
+Field
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\series bold
+Description
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+vertex_info_fields
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+normal_dir
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Direction of fault normal in global coordinate system
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+strike_dir
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Direction of fault strike in global coordinate system
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+dip_dir
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Up-dip direction on hanging wall in global coordinate system
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+final_slip_NAME
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Vector of final slip (in fault coordinate system) in meters
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" bottomline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+slip_time
+\family default
+_
+\family typewriter
+\noun on
+NAME
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" bottomline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Time at which slip begins in seconds
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+vertex_data_fields
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+slip
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Slip vector at time step (in fault coordinate system) in meters
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" bottomline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+traction_change
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" bottomline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Change in fault tractions (in fault coordinate system) in Pa
+\end_layout
+
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Subsubsection
+Kinematic Rupture Parameters
+\end_layout
+
+\begin_layout Standard
+The kinematic rupture parameters include the origin time and slip time function.
+ The slip initiation time in the slip time function is relative to the origin
+ time (default is 0).
+ This means that slip initiates at a point at a time corresponding to the
+ sum of the kinematic rupture's origin time and the slip initiation time
+ for that point.
+ An example of specifying the kinematic earthquake rupture properties and
+ components in a 
+\family typewriter
+.cfg
+\family default
+ file:
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.problem.interfaces.fault]
+\end_layout
+
+\begin_layout LyX-Code
+eq_srcs = [earthquake,creep]
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.problem.interfaces.fault.eq_srcs.earthquake]
+\end_layout
+
+\begin_layout LyX-Code
+origin_time = 0.0*s ; default origin time
+\end_layout
+
+\begin_layout LyX-Code
+slip_function = pylith.faults.StepSlipFn ; default slip time function
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.problem.interfaces.fault.eq_srcs.creep]
+\end_layout
+
+\begin_layout LyX-Code
+origin_time = 10.0*year ; start creep at 10.0 years
+\end_layout
+
+\begin_layout LyX-Code
+slip_function = pylith.faults.ConstRateSlipFn ; switch to constant slip rate
+ slip function
+\end_layout
+
+\begin_layout Subsubsection
+Slip Time Function
+\end_layout
+
+\begin_layout Standard
+The current release of PyLith supports specification of the evolution of
+ fault slip using analytical expressions for the slip time history at each
+ point, where the parameters for the slip time function may vary over the
+ fault surface.
+ Currently, three slip time functions are available: (1) a step-function
+ for quasi-static modeling of earthquake rupture, (2) a constant slip rate
+ time function for modeling steady aseismic slip, and (3) the integral of
+ Brune's far-field time function 
+\begin_inset CommandInset citation
+LatexCommand cite
+key "Brune:1970"
+
+\end_inset
+
+ for modeling the dynamics of earthquake rupture.
+ Additional slip time functions will likely be available in future releases.
+ The default slip time function is the step-function slip function.
+\end_layout
+
+\begin_layout Paragraph
+Step-Function Slip Time Function
+\end_layout
+
+\begin_layout Standard
+This slip function prescribes a step in slip at a given time at a point:
+ 
+\end_layout
+
+\begin_layout Standard
+\begin_inset Formula 
+\begin{gather}
+D(t)=\left\{ \begin{array}{cc}
+0 & 0\leq t<t_{r}\\
+D_{final} & t\ge t_{r}
+\end{array}\right.\,,
+\end{gather}
+
+\end_inset
+
+where 
+\begin_inset Formula $D(t)$
+\end_inset
+
+ is slip at time 
+\begin_inset Formula $t$
+\end_inset
+
+, 
+\begin_inset Formula $D_{final}$
+\end_inset
+
+ is the final slip, and 
+\begin_inset Formula $t_{r}$
+\end_inset
+
+ is the slip initiation time (time when rupture reaches the location).
+ The slip is specified independently for each of the components of slip,
+ and the slip and slip starting time may vary over the fault surface.
+\end_layout
+
+\begin_layout Description
+final_slip Spatial database of slip (
+\begin_inset Formula $D_{final})$
+\end_inset
+
+.
+\end_layout
+
+\begin_layout Description
+slip_time Spatial database of slip initiation times (
+\begin_inset Formula $t_{r}$
+\end_inset
+
+).
+\end_layout
+
+\begin_layout Standard
+An example of setting these parameters in a 
+\family typewriter
+.cfg
+\family default
+ file is:
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.problem.interfaces.fault.eq_srcs.rupture]
+\end_layout
+
+\begin_layout LyX-Code
+slip_function = pylith.faults.StepSlipFn
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.problem.interfaces.fault.eq_srcs.rupture.slip_function]
+\end_layout
+
+\begin_layout LyX-Code
+final_slip.iohandler.filename = final_slip.spatialdb
+\end_layout
+
+\begin_layout LyX-Code
+slip_time.iohandler.filename = sliptime.spatialdb
+\end_layout
+
+\begin_layout Standard
+The spatial database files for the slip time function specify the spatial
+ variation in the parameters for the slip time function, as shown in Table
+ 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "tab:step-function-db-params"
+
+\end_inset
+
+.
+\end_layout
+
+\begin_layout Standard
+\noindent
+\align center
+\begin_inset Float table
+placement H
+wide false
+sideways false
+status open
+
+\begin_layout Plain Layout
+\noindent
+\align center
+\begin_inset Caption
+
+\begin_layout Plain Layout
+\begin_inset CommandInset label
+LatexCommand label
+name "tab:step-function-db-params"
+
+\end_inset
+
+Values in spatial database used as parameters in the step function slip
+ time function.
+\end_layout
+
+\end_inset
+
+
+\begin_inset VSpace defskip
+\end_inset
+
+
+\begin_inset Tabular
+<lyxtabular version="3" rows="5" columns="3">
+<features tabularvalignment="middle">
+<column alignment="left" valignment="top" width="0">
+<column alignment="left" valignment="top" width="0">
+<column alignment="left" valignment="top" width="2.5in">
+<row>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\series bold
+Spatial database
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\series bold
+Value
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\series bold
+Description
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+final_slip
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+left-lateral-slip
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Amount of left-lateral final slip in meters.
+ Use negative values for right-lateral slip.
+ Applies to faults in 2D and 3D only.
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+reverse-slip
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Amount of reverse slip in meters.
+ Use negative values for normal slip.
+ Applies to faults in 3D only.
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+fault-opening
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Amount of fault opening in meters.
+ Negative values imply penetration.
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+slip_time
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+slip-time
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Slip initiation time (
+\begin_inset Formula $t_{t})$
+\end_inset
+
+ in seconds.
+\end_layout
+
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Paragraph
+Constant Slip Rate Slip Time Function
+\end_layout
+
+\begin_layout Standard
+This slip function prescribes a constant slip rate for the evolution of
+ slip at a point: 
+\end_layout
+
+\begin_layout Standard
+\begin_inset Formula 
+\begin{gather}
+D(t)=\left\{ \begin{array}{cc}
+0 & 0\leq t<t_{r}\\
+V(t-t_{r}) & t\ge t_{r}
+\end{array}\right.\,,
+\end{gather}
+
+\end_inset
+
+where 
+\begin_inset Formula $D(t)$
+\end_inset
+
+ is slip at time 
+\begin_inset Formula $t$
+\end_inset
+
+, 
+\begin_inset Formula $V$
+\end_inset
+
+ is the slip rate, and 
+\begin_inset Formula $t_{r}$
+\end_inset
+
+ is the slip initiation time (time when rupture reaches the location).
+ The slip rate is specified independently for each of the components of
+ slip, and the slip rate and slip starting time may vary over the fault
+ surface.
+\end_layout
+
+\begin_layout Description
+slip_rate Spatial database of slip rate (
+\begin_inset Formula $V)$
+\end_inset
+
+.
+\end_layout
+
+\begin_layout Description
+slip_time Spatial database of slip initiation times (
+\begin_inset Formula $t_{r}$
+\end_inset
+
+).
+\end_layout
+
+\begin_layout Standard
+An example of setting these parameters in a 
+\family typewriter
+.cfg
+\family default
+ file is:
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.problem.interfaces.fault.eq_srcs.ruptures]
+\end_layout
+
+\begin_layout LyX-Code
+slip_function = pylith.faults.ConstRateSlipFn
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.problem.interfaces.fault.eq_srcs.ruptures.slip_function]
+\end_layout
+
+\begin_layout LyX-Code
+slip_rate.iohandler.filename = slip_rate.spatialdb
+\end_layout
+
+\begin_layout LyX-Code
+slip_time.iohandler.filename = sliptime.spatialdb
+\end_layout
+
+\begin_layout Standard
+The spatial database files for the slip time function specify the spatial
+ variation in the parameters for the slip time function, as shown in Table
+ 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "tab:const-slip-rate-db-params"
+
+\end_inset
+
+.
+\end_layout
+
+\begin_layout Standard
+\noindent
+\align center
+\begin_inset Float table
+placement H
+wide false
+sideways false
+status open
+
+\begin_layout Plain Layout
+\noindent
+\align center
+\begin_inset Caption
+
+\begin_layout Plain Layout
+\begin_inset CommandInset label
+LatexCommand label
+name "tab:const-slip-rate-db-params"
+
+\end_inset
+
+Values in spatial database used as parameters in the constant slip rate
+ slip time function.
+\end_layout
+
+\end_inset
+
+
+\begin_inset VSpace defskip
+\end_inset
+
+
+\begin_inset Tabular
+<lyxtabular version="3" rows="5" columns="3">
+<features tabularvalignment="middle">
+<column alignment="left" valignment="top" width="0">
+<column alignment="left" valignment="top" width="0">
+<column alignment="left" valignment="top" width="2.5in">
+<row>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\series bold
+Spatial database
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\series bold
+Value
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\series bold
+Description
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+slip_rate
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+left-lateral-slip
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Slip rate for left-lateral final slip in meters per second.
+ Use negative values for right-lateral slip.
+ Applies to faults in 2D and 3D only.
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+reverse-slip
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Slip rate for reverse slip in meters per second.
+ Use negative values for normal slip.
+ Applies to faults in 3D only.
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+fault-opening
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Slip rate for fault opening in meters per second.
+ Negative values imply penetration.
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+slip_time
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+slip-time
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Slip initiation time (
+\begin_inset Formula $t_{t})$
+\end_inset
+
+ in seconds.
+\end_layout
+
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Paragraph
+Brune Slip Time Function
+\end_layout
+
+\begin_layout Standard
+We use an integral of Brune's far-field time function 
+\begin_inset CommandInset citation
+LatexCommand cite
+key "Brune:1970"
+
+\end_inset
+
+ to describe the evolution in time of slip at a point: 
+\end_layout
+
+\begin_layout Standard
+\begin_inset Formula 
+\begin{gather}
+D(t)=\left\{ \begin{array}{cc}
+0 & 0\leq t<t_{r}\\
+D_{final}\left(1-exp\left(-\frac{t-t_{r}}{t_{0}}\right)\left(1+\frac{t-t_{r}}{t_{0}}\right)\right) & t\ge t_{r}
+\end{array}\right.\,,\\
+t_{0}=0.6195t_{\mathit{rise}}\,,
+\end{gather}
+
+\end_inset
+
+where 
+\begin_inset Formula $D(t)$
+\end_inset
+
+ is slip at time 
+\begin_inset Formula $t$
+\end_inset
+
+, 
+\begin_inset Formula $D_{final}$
+\end_inset
+
+ is the final slip at the location, 
+\begin_inset Formula $t_{r}$
+\end_inset
+
+ is the slip initiation time (time when rupture reaches the location), and
+ 
+\begin_inset Formula $t_{\mathit{rise}}$
+\end_inset
+
+ is the rise time.
+\end_layout
+
+\begin_layout Description
+slip Spatial database of final slip distribution (
+\begin_inset Formula $D_{final})$
+\end_inset
+
+.
+\end_layout
+
+\begin_layout Description
+slip_time Spatial database of slip initiation times (
+\begin_inset Formula $t_{r}$
+\end_inset
+
+).
+\end_layout
+
+\begin_layout Description
+rise_time Spatial database for rise time (
+\begin_inset Formula $t_{\mathit{rise}}$
+\end_inset
+
+).
+\end_layout
+
+\begin_layout Standard
+An example of setting these parameters in a 
+\family typewriter
+.cfg
+\family default
+ file is:
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.problem.interfaces.fault.eq_srcs.ruptures]
+\end_layout
+
+\begin_layout LyX-Code
+slip_function = pylith.faults.BruneSlipFn
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.problem.interfaces.fault.eq_srcs.rupture.slip_function]
+\end_layout
+
+\begin_layout LyX-Code
+slip.iohandler.filename = finalslip.spatialdb
+\end_layout
+
+\begin_layout LyX-Code
+rise_time.iohandler.filename = risetime.spatialdb
+\end_layout
+
+\begin_layout LyX-Code
+slip_time.iohandler.filename = sliptime.spatialdb
+\end_layout
+
+\begin_layout Standard
+The spatial database files for the slip time function specify the spatial
+ variation in the parameters for the slip time function, as shown in Table
+ 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "tab:Brune-slip-db-params"
+
+\end_inset
+
+.
+\end_layout
+
+\begin_layout Standard
+\noindent
+\align center
+\begin_inset Float table
+placement H
+wide false
+sideways false
+status open
+
+\begin_layout Plain Layout
+\noindent
+\align center
+\begin_inset Caption
+
+\begin_layout Plain Layout
+\begin_inset CommandInset label
+LatexCommand label
+name "tab:Brune-slip-db-params"
+
+\end_inset
+
+Values in spatial database used as parameters in the Brune slip time function.
+\end_layout
+
+\end_inset
+
+
+\begin_inset VSpace defskip
+\end_inset
+
+
+\begin_inset Tabular
+<lyxtabular version="3" rows="6" columns="3">
+<features tabularvalignment="middle">
+<column alignment="left" valignment="top" width="0">
+<column alignment="left" valignment="top" width="0">
+<column alignment="left" valignment="top" width="2.5in">
+<row>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\series bold
+Spatial database
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\series bold
+Value
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\series bold
+Description
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+slip
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+left-lateral-slip
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Amount of left-lateral final slip in meters.
+ Use negative values for right-lateral slip.
+ Applies to faults in 2D and 3D only.
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+reverse-slip
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Amount of reverse slip in meters.
+ Use negative values for normal slip.
+ Applies to faults in 3D only.
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+fault-opening
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Amount of fault opening in meters.
+ Negative values imply penetration.
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+rise_time
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+rise-time
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Rise time (
+\begin_inset Formula $t_{r})$
+\end_inset
+
+ in seconds.
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+slip_time
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+slip-time
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Slip initiation time (
+\begin_inset Formula $t_{t})$
+\end_inset
+
+ in meters.
+\end_layout
+
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Paragraph
+Liu-Cosine Slip Time Function
+\end_layout
+
+\begin_layout Standard
+This slip time function, proposed by Liu, Archuleta, and Hartzell for use
+ in ground-motion modeling
+\begin_inset CommandInset citation
+LatexCommand cite
+key "Liu:etal:2006"
+
+\end_inset
+
+, combines several cosine and sine functions together to create a slip time
+ history with a sharp rise and gradual termination with a finite duration
+ of slip.
+ The evolution of slip at a point follows: 
+\end_layout
+
+\begin_layout Standard
+\begin_inset Formula 
+\begin{gather}
+D(t)=\left\{ \begin{array}{cc}
+D_{\mathit{final}}C_{n}\left(0.7t-0.7\frac{t_{1}}{\pi}\sin\frac{\pi t}{t_{1}}-1.2\frac{t_{1}}{\pi}\left(\cos\frac{\pi t}{2t_{1}}-1\right)\right) & 0\leq t<t_{1}\\
+D_{\mathit{final}}C_{n}\left(1.0t-0.7\frac{t1}{\pi}\sin\frac{\pi t}{t_{1}}+0.3\frac{t2}{\pi}\sin\frac{\pi(t-t1)}{t_{2}}+\frac{1.2}{\pi}t_{1}-0.3t_{1}\right) & t_{1}\leq t<2t_{1}\\
+D_{\mathit{final}}C_{n}\left(0.7-0.7\cos\frac{\pi t}{t_{1}}+0.6\sin\frac{\pi t}{2t_{1}}\right) & 2t_{1}\leq t\leq t_{0}
+\end{array}\right.\,,\\
+C_{n}=\frac{\pi}{1.4\pi t_{1}+1.2t_{1}+0.3\pi t_{2}},\\
+t_{0}=1.525t_{\mathit{rise}},\\
+t_{1}=0.13t_{0},\\
+t_{2}=t_{0}-t_{1},
+\end{gather}
+
+\end_inset
+
+where 
+\begin_inset Formula $D(t)$
+\end_inset
+
+ is slip at time 
+\begin_inset Formula $t$
+\end_inset
+
+, 
+\begin_inset Formula $D_{final}$
+\end_inset
+
+ is the final slip at the location, 
+\begin_inset Formula $t_{r}$
+\end_inset
+
+ is the slip initiation time (time when rupture reaches the location), and
+ 
+\begin_inset Formula $t_{\mathit{rise}}$
+\end_inset
+
+ is the rise time.
+\end_layout
+
+\begin_layout Description
+slip Spatial database of final slip distribution (
+\begin_inset Formula $D_{final})$
+\end_inset
+
+.
+\end_layout
+
+\begin_layout Description
+slip_time Spatial database of slip initiation times (
+\begin_inset Formula $t_{r}$
+\end_inset
+
+).
+\end_layout
+
+\begin_layout Description
+rise_time Spatial database for rise time (
+\begin_inset Formula $t_{\mathit{rise}}$
+\end_inset
+
+).
+\end_layout
+
+\begin_layout Standard
+The spatial database files for the slip time function use the same parameters
+ for the slip time function as the Brune slip time function shown in Table
+ 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "tab:Brune-slip-db-params"
+
+\end_inset
+
+.
+\end_layout
+
+\begin_layout Paragraph
+Time-History Slip Time Function
+\end_layout
+
+\begin_layout Standard
+This slip time function reads the slip time function from a data file, so
+ it can have an arbitrary shape.
+ The slip and slip initiation times are specified using spatial databases,
+ so the slip time function, in general, will use a normalized amplitude.
+\end_layout
+
+\begin_layout Description
+slip Spatial database of final slip distribution (
+\begin_inset Formula $D_{final})$
+\end_inset
+
+.
+\end_layout
+
+\begin_layout Description
+slip_time Spatial database of slip initiation times (
+\begin_inset Formula $t_{r}$
+\end_inset
+
+).
+\end_layout
+
+\begin_layout Description
+time_history Temporal database for slip evolution.
+\end_layout
+
+\begin_layout Standard
+An example of setting these parameters in a 
+\family typewriter
+.cfg
+\family default
+ file is:
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.problem.interfaces.fault.eq_srcs.ruptures]
+\end_layout
+
+\begin_layout LyX-Code
+slip_function = pylith.faults.TimeHistorySlipFn
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.problem.interfaces.fault.eq_srcs.rupture.slip_function]
+\end_layout
+
+\begin_layout LyX-Code
+slip.iohandler.filename = finalslip.spatialdb
+\end_layout
+
+\begin_layout LyX-Code
+slip_time.iohandler.filename = sliptime.spatialdb
+\end_layout
+
+\begin_layout LyX-Code
+time_history.iohandler.filename = myfunction.timedb
+\end_layout
+
+\begin_layout Standard
+The spatial database files for the slip time function specify the spatial
+ variation in the parameters for the slip time function, as shown in Table
+ 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "tab:Brune-slip-db-params-2"
+
+\end_inset
+
+.
+\end_layout
+
+\begin_layout Standard
+\noindent
+\align center
+\begin_inset Float table
+placement H
+wide false
+sideways false
+status open
+
+\begin_layout Plain Layout
+\noindent
+\align center
+\begin_inset Caption
+
+\begin_layout Plain Layout
+\begin_inset CommandInset label
+LatexCommand label
+name "tab:Brune-slip-db-params-2"
+
+\end_inset
+
+Values in spatial database used as parameters in the time history slip time
+ function.
+\end_layout
+
+\end_inset
+
+
+\begin_inset VSpace defskip
+\end_inset
+
+
+\begin_inset Tabular
+<lyxtabular version="3" rows="6" columns="3">
+<features tabularvalignment="middle">
+<column alignment="left" valignment="top" width="0">
+<column alignment="left" valignment="top" width="0">
+<column alignment="left" valignment="top" width="2.5in">
+<row>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\series bold
+Spatial database
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\series bold
+Value
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\series bold
+Description
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+slip
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+left-lateral-slip
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Amount of left-lateral final slip in meters.
+ Use negative values for right-lateral slip.
+ Applies to faults in 2D and 3D only.
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+reverse-slip
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Amount of reverse slip in meters.
+ Use negative values for normal slip.
+ Applies to faults in 3D only.
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+fault-opening
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Amount of fault opening in meters.
+ Negative values imply penetration.
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+rise_time
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+rise-time
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Rise time (
+\begin_inset Formula $t_{r})$
+\end_inset
+
+ in seconds.
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+slip_time
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+slip-time
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Slip initiation time (
+\begin_inset Formula $t_{t})$
+\end_inset
+
+ in meters.
+\end_layout
+
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Subsection
+Dynamic Earthquake Rupture
+\end_layout
+
+\begin_layout Standard
+Dynamic fault interfaces use the FaultCohesiveDyn object to specify a fault
+ constitutive model to govern the fault tractions (friction) and the resulting
+ slip.
+ When friction is large enough such that there is no sliding on the fault,
+ the fault is locked (slip is zero) and the Lagrange multipliers assume
+ their values just as they do in kinematic ruptures.
+ In this case, the Lagrange multipliers correspond to the forces necessary
+ to keep the slip zero.
+ When the driving forces exceed those allowed by friction, we reduce the
+ values of the Lagrange multipliers to those consistent with friction from
+ the fault constitutive model.
+ When we reduce the Lagrange multipliers, we must increment the slip accordingly
+ to maintain consistency in the algebraic system of equations.
+\end_layout
+
+\begin_layout Subsubsection
+Governing Equations
+\end_layout
+
+\begin_layout Standard
+The algebraic systems of equations for dynamic earthquake rupture are the
+ same as those for kinematic rupture
+\begin_inset Formula 
+\begin{equation}
+\left[\begin{array}{cc}
+\underline{A} & \underline{C}^{T}\\
+\underline{C} & 0
+\end{array}\right]\left[\begin{array}{c}
+\overrightarrow{u}\\
+\overrightarrow{l}
+\end{array}\right]=\left[\begin{array}{c}
+\overrightarrow{b}\\
+\overrightarrow{d}
+\end{array}\right].
+\end{equation}
+
+\end_inset
+
+Enforcing the limits imposed on the Lagrange multipliers by the fault constituti
+ve model requires determining the increment in slip for an increment in
+ the Lagrange multipliers.
+ The increment in the Lagrange multipliers is the difference between the
+ value computed for the current slip (either zero or the slip at the previous
+ time step) and the value computed from the fault constitutive model.
+ Starting from our system of algebraic equations,
+\begin_inset Formula 
+\begin{equation}
+A_{ij}^{nm}u_{j}^{m}+C_{ji}^{pn}l_{j}^{p}=b_{i}^{n},
+\end{equation}
+
+\end_inset
+
+we compute the sensitivity for the given loading and boundary conditions,
+\begin_inset Formula 
+\begin{equation}
+A_{ij}^{nm}\partial u_{j}^{m}=-C_{ji}^{pn}\partial l_{j}^{p}.
+\end{equation}
+
+\end_inset
+
+Computing the increment in the slip requires computing the increment in
+ the displacements.
+ Solving this equation rigorously would require inverting the system Jacobian,
+ which we do not want to do unless it is diagonal (as it is in the case
+ of the lumped formulations).
+ 
+\end_layout
+
+\begin_layout Paragraph
+Non-diagonal A
+\end_layout
+
+\begin_layout Standard
+In general A is a sparse matrix with off-diagonal terms of the form
+\begin_inset Formula 
+\begin{equation}
+A=\left(\begin{array}{ccc}
+A_{0} & A_{1} & A_{2}\\
+A_{3} & A_{n-} & 0\\
+A_{4} & 0 & A_{n+}
+\end{array}\right),
+\end{equation}
+
+\end_inset
+
+where the degrees of freedom on either side of the fault are uncoupled.
+ We formulate two small linear systems involving just the degrees of freedom
+ associated with vertices on either the positive or negative sides of the
+ fault,
+\begin_inset Formula 
+\begin{gather}
+A_{ij}^{nm-}\partial u_{j}^{m-}=-R_{ij}^{pn}\partial l_{j}^{p},\\
+A_{ij}^{nm+}\partial u_{j}^{m+}=R_{ij}^{pn}\partial l_{j}^{p},
+\end{gather}
+
+\end_inset
+
+where we have replaced 
+\begin_inset Formula $\underline{C}$
+\end_inset
+
+ with 
+\begin_inset Formula $\underline{R}$
+\end_inset
+
+ to denote the explicit inclusion of the signs for the terms in 
+\begin_inset Formula $\underline{C}$
+\end_inset
+
+ associated with the positive (
+\begin_inset Formula $n^{+}$
+\end_inset
+
+) and negative (
+\begin_inset Formula $n^{-}$
+\end_inset
+
+) sides of the fault.
+ After solving these two linear systems of equations, we compute the increment
+ in slip using
+\begin_inset Formula 
+\begin{equation}
+\partial d_{i}^{p}=R_{ij}^{pn}(\partial u_{j}^{n+}-\partial u_{j}^{n-}).
+\end{equation}
+
+\end_inset
+
+The solution of these two linear systems gives the increment in slip assuming
+ all the degrees of freedom except those immediately adjacent to the fault
+ remain fixed.
+ In real applications where the deformation associated with fault slip is
+ localized around the fault, this provides good enough approximations so
+ that the nonlinear solver converges quickly.
+ In problems where deformation associated with slip on the fault is not
+ localized (as in the case in some of the example problems), the increment
+ in slip computed by solving these two linear systems is not a good approximatio
+n and the nonlinear solve requires a large number of iterations.
+\end_layout
+
+\begin_layout Standard
+We use the PETSc Krylov subspace solver (KSP) to solve these two linear
+ systems.
+ The PETSc settings for the KSP object are set in the same manner as the
+ main solver, except we use the prefix friction_ in all of the settings
+ related to the KSP solver for these two linear systems.
+ For example, to use the recommended additive Schwarz preconditioner in
+ the friction sensitivity solves, the settings in a .cfg file are:
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.petsc]
+\end_layout
+
+\begin_layout LyX-Code
+friction_pc_type = asm
+\end_layout
+
+\begin_layout Standard
+See the examples in Sections 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "sec:Tutorial-3d-hex8-friction"
+
+\end_inset
+
+ and 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "sec:tutorial:shearwave:quad4"
+
+\end_inset
+
+ for details.
+\end_layout
+
+\begin_layout Paragraph
+Diagonal A
+\end_layout
+
+\begin_layout Standard
+With a lumped Jacobian matrix, we can solve for the increment in slip directly,
+\begin_inset Formula 
+\begin{equation}
+\partial d_{i}^{p}=-C_{ij}^{pn}(A_{jk}^{nm})^{-1}C_{lk}^{pm}\partial l_{l}^{p}.
+\end{equation}
+
+\end_inset
+
+By not allowing the fault interface to overlap with the absorbing boundary,
+ the terms in 
+\begin_inset Formula $A$
+\end_inset
+
+ for a given vertex are identical and the expression on the right-hand side
+ reduces to
+\begin_inset Formula 
+\begin{equation}
+\partial d_{i}^{p}=-\left(\frac{1}{A^{n+}}+\frac{1}{A^{n-}}\right)\partial l_{i}^{p}.
+\end{equation}
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Subsubsection
+Dynamic Rupture Parameters
+\end_layout
+
+\begin_layout Standard
+The components of the FaultCohesiveDyn object include
+\end_layout
+
+\begin_layout Description
+open_free_surface If true, enforce traction free surface when the fault
+ opens, otherwise apply prescribed tractions even when the fault opens (default
+ is true); to mimic a dike opening use false.
+\end_layout
+
+\begin_layout Description
+zero_tolerance Tolerance for detecting zero values (default is 1.0e-10);
+ should be larger than absolute tolerance in KSP solves.
+\end_layout
+
+\begin_layout Description
+traction_perturbation Prescribed tractions on fault surface (generally used
+ for nucleating earthquake ruptures, default is none).
+\end_layout
+
+\begin_layout Description
+friction Fault constitutive model.
+\end_layout
+
+\begin_layout Standard
+An example of specifying the dynamic earthquake rupture properties and component
+s in a 
+\family typewriter
+.cfg
+\family default
+ file:
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.problem.interfaces.fault]
+\end_layout
+
+\begin_layout LyX-Code
+open_free_surface = True ; default
+\end_layout
+
+\begin_layout LyX-Code
+traction_perturbation = pylith.faults.TractPerturbation ; not default
+\end_layout
+
+\begin_layout LyX-Code
+traction_perturbation.db_initial = spatialdata.spatialdb.SimpleDB
+\end_layout
+
+\begin_layout LyX-Code
+traction_perturbation.db_initial.iohandler.filename = tractions.spatialdb
+\end_layout
+
+\begin_layout LyX-Code
+friction = pylith.friction.StaticFriction
+\end_layout
+
+\begin_layout LyX-Code
+friction.db_properties = spatialdata.spatialdb.SimpleDB
+\end_layout
+
+\begin_layout LyX-Code
+friction.db_properties.iohandler.filename = friction.spatialdb
+\end_layout
+
+\begin_layout Standard
+The prescribed traction perturbation is specified using the same fault coordinat
+e system as the slip directions in the kinematic ruptures.
+ The perurbation has the same functional form as the time-dependent boundary
+ conditions (and same spatial databases).
+ Table 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "tab:fault:cohesive:dyn:prescribed:tractions"
+
+\end_inset
+
+ gives the values in the spatial database for the prescribed tractions.
+ Table 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "tab:fault:dyn:output"
+
+\end_inset
+
+ shows the fields available for output.
+ Additional fields are available depending on the fault constitutive model.
+\end_layout
+
+\begin_layout Standard
+\noindent
+\align center
+\begin_inset Float table
+placement H
+wide false
+sideways false
+status open
+
+\begin_layout Plain Layout
+\noindent
+\align center
+\begin_inset Caption
+
+\begin_layout Plain Layout
+\begin_inset CommandInset label
+LatexCommand label
+name "tab:fault:cohesive:dyn:prescribed:tractions"
+
+\end_inset
+
+Values in spatial databases for prescribed tractions.
+\end_layout
+
+\end_inset
+
+
+\begin_inset VSpace defskip
+\end_inset
+
+
+\begin_inset Tabular
+<lyxtabular version="3" rows="22" columns="4">
+<features tabularvalignment="middle">
+<column alignment="left" valignment="top" width="0">
+<column alignment="left" valignment="top" width="0">
+<column alignment="left" valignment="top" width="0">
+<column alignment="left" valignment="top" width="2.5in">
+<row>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\series bold
+Spatial database
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\series bold
+Dimension
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\series bold
+Value
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\series bold
+Description
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+db_initial
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+1-D
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+traction-normal
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Normal traction (tension is positive)
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+2-D
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+traction-shear
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Left-lateral shear traction (reverse shear for dipping faults)
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+traction-normal
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Normal traction (tension is positive)
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+3-D
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+traction-shear-leftlateral
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Left-lateral shear traction
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+traction-shear-updip
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Reverse shear traction
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+traction-normal
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Normal traction (tension is positive)
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+db_rate
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+1-D
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+traction-rate-normal
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Rate of change of normal traction (tension is positive)
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+2-D
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+traction-rate-shear
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Rate of change of left-lateral shear traction (reverse shear for dipping
+ faults)
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+traction-rate-normal
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" bottomline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Rate of change of normal traction (tension is positive)
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+3-D
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+traction-rate-leftlateral
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Rate of change of eft-lateral shear traction
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+traction-rate-shear-updip
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Rate of change of reverse shear traction
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+traction-rate-normal
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" bottomline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Rate of change of normal traction (tension is positive)
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+all
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+rate-start-time
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Time at which rate of change begins
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+db_change
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+1-D
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+traction-normal
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Change in normal traction (tension is positive)
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+2-D
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+traction-shear
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Change in left-lateral shear traction (reverse shear for dipping faults)
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+traction-normal
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" bottomline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Change in normal traction (tension is positive)
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+3-D
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+traction-leftlateral
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Change in left-lateral shear traction
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+traction-shear-updip
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Change in reverse shear traction
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+traction-normal
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" bottomline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Change in normal traction (tension is positive)
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+all
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+change-start-time
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" bottomline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Time at which change begins
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+th_change
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+all
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+None
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" bottomline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Time history for change
+\end_layout
+
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\begin_inset Float table
+placement H
+wide false
+sideways false
+status open
+
+\begin_layout Plain Layout
+\noindent
+\align center
+\begin_inset Caption
+
+\begin_layout Plain Layout
+\begin_inset CommandInset label
+LatexCommand label
+name "tab:fault:dyn:output"
+
+\end_inset
+
+Fields available in output of fault information.
+\end_layout
+
+\end_inset
+
+
+\begin_inset VSpace defskip
+\end_inset
+
+
+\begin_inset Tabular
+<lyxtabular version="3" rows="11" columns="3">
+<features tabularvalignment="middle">
+<column alignment="center" valignment="top" width="0">
+<column alignment="center" valignment="top" width="0">
+<column alignment="center" valignment="top" width="3.5in">
+<row>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\series bold
+Field Type
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\series bold
+Field
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\series bold
+Description
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+vertex_info_fields
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+normal_dir
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Direction of fault normal in global coordinate system
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+strike_dir
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Direction of fault strike in global coordinate system
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+dip_dir
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Up-dip direction on hanging wall in global coordinate system
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+traction_initial
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Initial tractions (if specified) in fault coordinate system
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+traction_rate
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Rate of change in tractions (if specified) in fault coordinate system
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+rate_start_time
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Time at which rate of change begins (if specified)
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+traction_change
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Change in tractions (if specified) in fault coordinate system
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" bottomline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+change_start_time
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" bottomline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Time at which change occurs (if specified)
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+vertex_data_fields
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+slip
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Slip vector at time step (in fault coordinate system) in meters
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" bottomline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+traction
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" bottomline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Fault tractions (in fault coordinate system) in Pa
+\end_layout
+
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Subsubsection
+Fault Constitutive Models
+\begin_inset CommandInset label
+LatexCommand label
+name "sec:fault:constitutive:models"
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+PyLith provides four fault constitutive models.
+ Future releases may contain additional models, and a template is provided
+ for you to construct your own (see Section 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "sec:Extending:FaultConstitutiveModels"
+
+\end_inset
+
+).
+ The fault constitutive model implementations are independent of dimension
+ and work in both 2-D and 3-D.
+ In solving the governing equations, PyLith will use a scalar representation
+ of the shear traction in 2-D and a vector representation of the shear traction
+ in 3-D, with the shear traction resolved in the direction of current slip.
+ The fault constitutive models contain a common set of properties and components
+:
+\end_layout
+
+\begin_layout Description
+label Name of the friction model.
+\end_layout
+
+\begin_layout Description
+db_properties Spatial database of the friction model parameters (default
+ is SimpleDB).
+\end_layout
+
+\begin_layout Description
+db_initial_state Spatial database for initial state variables (default is
+ none).
+\end_layout
+
+\begin_layout Paragraph
+Static Friction
+\end_layout
+
+\begin_layout Standard
+The static friction model produces shear tractions proportional to the fault
+ normal traction plus a cohesive stress,
+\begin_inset Formula 
+\begin{equation}
+T_{f}=\begin{cases}
+T_{c}-\mu_{f}T_{n} & T_{n}\leq0\\
+0 & T_{n}>0
+\end{cases}.
+\end{equation}
+
+\end_inset
+
+The spatial database file for the static friction model properties specifies
+ the spatial variation of the parameters given in Table 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "tab:static:friction:properties"
+
+\end_inset
+
+.
+\end_layout
+
+\begin_layout Standard
+\noindent
+\align center
+\begin_inset Float table
+placement H
+wide false
+sideways false
+status open
+
+\begin_layout Plain Layout
+\noindent
+\align center
+\begin_inset Caption
+
+\begin_layout Plain Layout
+\begin_inset CommandInset label
+LatexCommand label
+name "tab:static:friction:properties"
+
+\end_inset
+
+Values in the spatial database for constant friction parameters.
+\end_layout
+
+\end_inset
+
+
+\begin_inset VSpace defskip
+\end_inset
+
+
+\begin_inset Tabular
+<lyxtabular version="3" rows="3" columns="2">
+<features tabularvalignment="middle">
+<column alignment="left" valignment="top" width="0">
+<column alignment="left" valignment="top" width="2.5in">
+<row>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\series bold
+Value
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\series bold
+Description
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+friction-coefficient
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Coefficient of friction, 
+\begin_inset Formula $\mu_{f}$
+\end_inset
+
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+cohesion
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Cohesive stress, 
+\begin_inset Formula $T_{c}$
+\end_inset
+
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Paragraph
+\begin_inset CommandInset label
+LatexCommand label
+name "sec:friction:slip:weakening"
+
+\end_inset
+
+Slip-Weakening Friction
+\end_layout
+
+\begin_layout Standard
+The linear slip-weakening friction model produces shear tractions equal
+ to the cohesive stress plus a contribution proportional to the fault normal
+ traction that decreases from a static value to a dynamic value as slip
+ progresses,
+\begin_inset Formula 
+\begin{equation}
+T_{f}=\begin{cases}
+T_{c}-(\mu_{s}-(\mu_{s}-\mu_{d})\frac{d}{d_{0}})T_{n} & d\leq d_{0}\text{ and }T_{n}\leq0\\
+T_{c}-\mu_{d}T_{n} & d>d_{0}\text{ and }T_{n}\leq0\\
+0 & T_{n}>0
+\end{cases}
+\end{equation}
+
+\end_inset
+
+The spatial database files for the slip-weakening friction model properties
+ and state variables specify the spatial variation of the fault constitutive
+ model parameters given in Table 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "tab:slip:weakening:properties:statevars"
+
+\end_inset
+
+.
+ As long as the fault is locked, the initial state variables are zero, so
+ specifying the initial state variables for slip-weakening friction is rare.
+ The slip-weakening friction also includes a parameter, 
+\family typewriter
+force_healing
+\family default
+, to control healing.
+ In quasi-static simulations, one usually wants slip confined to a single
+ time step (
+\family typewriter
+force_healing
+\family default
+ = True), whereas in a dynamic simulation slip occurs over many time steps
+ (
+\family typewriter
+force_healing
+\family default
+ = False; default behavior) and fault healing is often neglected.
+ The properties include:
+\end_layout
+
+\begin_layout Description
+force_healing Flag indicating whether healing (cumalative slip state variable
+ reset to zero) is forced after every time step.
+\end_layout
+
+\begin_layout Standard
+An example of setting the properties for the rate and state friction component
+ in a 
+\family typewriter
+.cfg
+\family default
+ file is:
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.problem.interfaces.fault]
+\end_layout
+
+\begin_layout LyX-Code
+friction = pylith.friction.SlipWeakening ; Change friction model from the
+ default
+\end_layout
+
+\begin_layout LyX-Code
+friction.force_healing = False ; default value
+\end_layout
+
+\begin_layout Standard
+\noindent
+\align center
+\begin_inset Float table
+placement H
+wide false
+sideways false
+status open
+
+\begin_layout Plain Layout
+\noindent
+\align center
+\begin_inset Caption
+
+\begin_layout Plain Layout
+\begin_inset CommandInset label
+LatexCommand label
+name "tab:slip:weakening:properties:statevars"
+
+\end_inset
+
+Values in spatial databases for slip-weakening friction.
+\end_layout
+
+\end_inset
+
+
+\begin_inset VSpace defskip
+\end_inset
+
+
+\begin_inset Tabular
+<lyxtabular version="3" rows="7" columns="3">
+<features tabularvalignment="middle">
+<column alignment="left" valignment="top" width="0">
+<column alignment="left" valignment="top" width="0">
+<column alignment="left" valignment="top" width="2.5in">
+<row>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\series bold
+Spatial database
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\series bold
+Value
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\series bold
+Description
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+db_properties
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+static-coefficient
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Static coefficient of friction, 
+\begin_inset Formula $\mu_{s}$
+\end_inset
+
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+dynamic-coefficient
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Dynamic coefficient of friction, 
+\begin_inset Formula $\mu_{d}$
+\end_inset
+
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+slip-weakening-parameter
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Slip-weakening parameter, 
+\begin_inset Formula $d_{0}$
+\end_inset
+
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+cohesion
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Cohesive stress, 
+\begin_inset Formula $T_{c}$
+\end_inset
+
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+db_initial_state
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+cumulative-slip
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Cumulative slip, 
+\begin_inset Formula $d$
+\end_inset
+
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+previous-slip
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Slip at previous time step, 
+\begin_inset Formula $d(t-\Delta t)$
+\end_inset
+
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Paragraph
+Time-Weakening Friction
+\end_layout
+
+\begin_layout Standard
+The linear time-weakening friction model is analogous to the linear slip-weakeni
+ng friction model with time replacing slip.
+ It produces shear tractions equal to the cohesive stress plus a contribution
+ proportional to the fault normal traction that decreases from a static
+ value to a dynamic value as time progresses,
+\begin_inset Formula 
+\begin{equation}
+T_{f}=\begin{cases}
+T_{c}-(\mu_{s}-(\mu_{s}-\mu_{d})\frac{t}{t_{0}})T_{n} & t\leq t_{0}\text{ and }T_{n}\leq0\\
+T_{c}-\mu_{d}T_{n} & t>t_{0}\text{ and }T_{n}\leq0\\
+0 & T_{n}>0
+\end{cases}
+\end{equation}
+
+\end_inset
+
+The spatial database files for the time-weakening friction model properties
+ and state variables specify the spatial variation of the fault constitutive
+ model parameters given in Table 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "tab:time:weakening:properties:statevars"
+
+\end_inset
+
+.
+ As long as the fault is locked, the initial state variable is zero, so
+ specifying the initial state variable for time-weakening friction is rare.
+\end_layout
+
+\begin_layout Standard
+\noindent
+\align center
+\begin_inset Float table
+placement H
+wide false
+sideways false
+status open
+
+\begin_layout Plain Layout
+\noindent
+\align center
+\begin_inset Caption
+
+\begin_layout Plain Layout
+\begin_inset CommandInset label
+LatexCommand label
+name "tab:time:weakening:properties:statevars"
+
+\end_inset
+
+Values in spatial databases for time-weakening friction.
+\end_layout
+
+\end_inset
+
+
+\begin_inset VSpace defskip
+\end_inset
+
+
+\begin_inset Tabular
+<lyxtabular version="3" rows="6" columns="3">
+<features tabularvalignment="middle">
+<column alignment="left" valignment="top" width="0">
+<column alignment="left" valignment="top" width="0">
+<column alignment="left" valignment="top" width="2.5in">
+<row>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\series bold
+Database
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\series bold
+Value
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\series bold
+Description
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+db_properties
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+static-coefficient
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Static coefficient of friction, 
+\begin_inset Formula $\mu_{s}$
+\end_inset
+
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+dynamic-coefficient
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Dynamic coefficient of friction, 
+\begin_inset Formula $\mu_{d}$
+\end_inset
+
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+time-weakening-parameter
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Time-weakening parameter, 
+\begin_inset Formula $t_{0}$
+\end_inset
+
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+cohesion
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Cohesive stress, 
+\begin_inset Formula $T_{c}$
+\end_inset
+
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+db_initial_state
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+elapsed-time
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Elasped time of slip, 
+\begin_inset Formula $t$
+\end_inset
+
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Paragraph
+\begin_inset CommandInset label
+LatexCommand label
+name "sec:friction:rate:state:ageing"
+
+\end_inset
+
+Rate- and State-Friction with Ageing Law
+\end_layout
+
+\begin_layout Standard
+The Dieterich-Ruina rate and state friction model produces shear tractions
+ equal to the cohesive stress plus a contribution proportional to the fault
+ normal traction that depends on a state variable,
+\begin_inset Formula 
+\begin{gather}
+T_{f}=\begin{cases}
+T_{c}-\mu_{f}T_{n} & T_{n}\leq0\\
+0 & T_{n}>0
+\end{cases}\\
+\mu_{f}=\begin{cases}
+\mu_{0}+a\ln\left(\frac{V}{V_{0}}\right)+b\ln\left(\frac{V_{0}\theta}{L}\right) & V\ge V_{\mathit{min}}\\
+\mu_{0}+a\ln\left(\frac{V_{min}}{V}\right)+b\ln\left(\frac{V_{0}\theta}{L}\right)-a\left(1-\frac{V}{V_{min}}\right) & V<V_{min}
+\end{cases}\\
+\frac{d\theta}{dt}=1-\frac{V\theta}{L}
+\end{gather}
+
+\end_inset
+
+where 
+\begin_inset Formula $V$
+\end_inset
+
+ is slip rate, 
+\begin_inset Formula $V_{min}$
+\end_inset
+
+ is a minimum slip rate, 
+\begin_inset Formula $a$
+\end_inset
+
+ and 
+\begin_inset Formula $b$
+\end_inset
+
+ are coefficients, 
+\begin_inset Formula $L$
+\end_inset
+
+ is the characteristic slip distance, 
+\begin_inset Formula $\theta$
+\end_inset
+
+ is a state variable.
+ With an interative solver in quasi-static simulations with a small, but
+ nonzero residual tolerance we never encounter zero slip rates in quasi-static
+ simulations.
+ Instead we want to avoid significant variations in the coefficient of friction
+ for slip rates on the same order as our residual tolerance.
+ We regularize the rate and state friction model by iposing a linearization
+ of the variation of the coefficient of friction with slip rate when the
+ slip rate drops below a minimum slip rate, 
+\begin_inset Formula $V_{min}$
+\end_inset
+
+ (
+\family typewriter
+min_slip_rate
+\family default
+ property with a default value of 1.0e-12).
+ Note that this is different than the popular inverse hypoerbolic sine regulariz
+ation proposed by Ben-Zion and Rice 
+\begin_inset CommandInset citation
+LatexCommand cite
+key "BenZion:Rice:1997"
+
+\end_inset
+
+ to permit zero slip rates.
+ Following Kaneko 
+\shape italic
+et al.
+
+\shape default
+ 
+\begin_inset CommandInset citation
+LatexCommand cite
+key "Kaneko:etal:2008"
+
+\end_inset
+
+, we integrate the evolution equation for the state variable keeping slip
+ rate constant to get
+\begin_inset Formula 
+\begin{equation}
+\theta(t+\Delta t)=\theta(t)\exp\left(\frac{-V(t)\Delta t}{L}\right)+\frac{L}{V(t)}\left(1-\exp\left(-\frac{V(t)\Delta t}{L}\right)\right).
+\end{equation}
+
+\end_inset
+
+As the slip rate approaches zero, the first exponential term approaches
+ 1.
+ Using the first three terms of the Taylor series expansion of the second
+ exponential yields
+\begin_inset Formula 
+\begin{equation}
+\theta(t+\Delta t)=\begin{cases}
+\theta(t)\exp\left(-\frac{V(t)\Delta t}{L}\right)+\Delta t-\frac{1}{2}\frac{V(t)\Delta t^{2}}{L} & \frac{V(t)\Delta t}{L}<0.00001\\
+\theta(t)\exp\left(-\frac{V(t)\Delta t}{L}\right)+\frac{L}{V(t)}\left(1-\exp\left(-\frac{V(t)\Delta t}{L}\right)\right) & \frac{V(t)\Delta t}{L}\ge0.00001
+\end{cases}.
+\end{equation}
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+The properties include:
+\end_layout
+
+\begin_layout Description
+min_slip_rate Slip rate at which linearization occurs, 
+\begin_inset Formula $V_{min}$
+\end_inset
+
+.
+ Should be about one order of magnitude larger than absolute tolerance in
+ solve.
+\end_layout
+
+\begin_layout Standard
+An example of setting the properties for the rate and state friction component
+ in a 
+\family typewriter
+.cfg
+\family default
+ file is:
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.problem.interfaces.fault]
+\end_layout
+
+\begin_layout LyX-Code
+friction = pylith.friction.RateStateAgeing ; Change friction model from the
+ default
+\end_layout
+
+\begin_layout LyX-Code
+friction.min_slip_rate = 1.0e-12 ; default value
+\end_layout
+
+\begin_layout Standard
+The spatial database files for the rate and state friction model properties
+ and state variables specify the spatial variation of the fault constitutive
+ model parameters given in Table 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "tab:rate:state:ageing:properties:statevars"
+
+\end_inset
+
+.
+\end_layout
+
+\begin_layout Standard
+\noindent
+\align center
+\begin_inset Float table
+placement H
+wide false
+sideways false
+status open
+
+\begin_layout Plain Layout
+\noindent
+\align center
+\begin_inset Caption
+
+\begin_layout Plain Layout
+\begin_inset CommandInset label
+LatexCommand label
+name "tab:rate:state:ageing:properties:statevars"
+
+\end_inset
+
+Values in spatial databases for Dieterich-Ruina rate-state friction.
+\end_layout
+
+\end_inset
+
+
+\begin_inset VSpace defskip
+\end_inset
+
+
+\begin_inset Tabular
+<lyxtabular version="3" rows="8" columns="3">
+<features tabularvalignment="middle">
+<column alignment="left" valignment="top" width="0">
+<column alignment="left" valignment="top" width="0">
+<column alignment="left" valignment="top" width="2.5in">
+<row>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\series bold
+Database
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\series bold
+Value
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\series bold
+Description
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+db_properties
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+reference-friction-coefficient
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Steady-state coefficient of friction at slip rate 
+\begin_inset Formula $V_{0}$
+\end_inset
+
+, 
+\begin_inset Formula $\mu_{s}$
+\end_inset
+
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+reference-slip-rate
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Reference slip rate, 
+\begin_inset Formula $V_{0}$
+\end_inset
+
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+characteristic-slip-distance
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Slip-weakening parameter, 
+\begin_inset Formula $L$
+\end_inset
+
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+constitutive-parameter-a
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Coefficient for the 
+\begin_inset Formula $\ln$
+\end_inset
+
+ slip rate term, 
+\begin_inset Formula $a$
+\end_inset
+
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+constitutive-parameter-b
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Coefficient for the 
+\begin_inset Formula $\ln$
+\end_inset
+
+ state variable term, 
+\begin_inset Formula $b$
+\end_inset
+
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+cohesion
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Cohesive stress, 
+\begin_inset Formula $T_{c}$
+\end_inset
+
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+db_initial_state
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+state-variable
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+State variable, 
+\begin_inset Formula $\theta$
+\end_inset
+
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Subsection
+\begin_inset CommandInset label
+LatexCommand label
+name "sec:fault:cohesive:impulses"
+
+\end_inset
+
+Slip Impulses for Green's Functions
+\end_layout
+
+\begin_layout Standard
+Computing static Green's functions using the GreensFns problem requires
+ a specialized fault implementation, FaultCohesiveImpulses, to setup the
+ slip impulses.
+ The parameters controlling the slip impulses include the components involved
+ (lateral, reverse, and/or fault opening) and the amplitude of the pulses
+ (e.g., selecting a subset of a fault or including a spatial variation).
+ The GreensFns properties and facilities include:
+\end_layout
+
+\begin_layout Description
+threshold Threshold for non-zero amplitude; impulses will only be generated
+ at locations on the fault where the amplitude excees this threshold.
+\end_layout
+
+\begin_layout Description
+impulse_dof Array of components associated with impulses, e.g., [0, 1] for
+ slip involving the lateral and up-dip components.
+\end_layout
+
+\begin_layout Description
+db_impulse_amplitude Spatial database for amplitude of slip impulse (scalar
+ field).
+ Default is SimpleDB.
+\end_layout
+
+\begin_layout Standard
+An example of setting the properties and facilities for FaultCohesiveImpulses
+ in a 
+\family typewriter
+.cfg
+\family default
+ file is:
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.problem.interfaces]
+\end_layout
+
+\begin_layout LyX-Code
+fault = pylith.faults.FaultCohesiveImpulses ; Change from the default
+\end_layout
+
+\begin_layout LyX-Code
+
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.problem.interfaces.fault]
+\end_layout
+
+\begin_layout LyX-Code
+threshold = 1.0e-6*m ; default
+\end_layout
+
+\begin_layout LyX-Code
+impulse_dof = [0] ; lateral slip-only
+\end_layout
+
+\begin_layout LyX-Code
+db_impulse_amplitude.iohandler.filename = myimpulse.spatialdb
+\end_layout
+
+\begin_layout LyX-Code
+db_impulse_amplitude.label = Impulse amplitude
+\end_layout
+
+\begin_layout Section
+Gravitational Body Forces
+\end_layout
+
+\begin_layout Standard
+Many problems in geophysics require the consideration of gravitational body
+ forces.
+ For example, it is often important to include the effects of the lithostatic
+ (overburden) pressure.
+ In future releases of PyLith that permit nonlinear bulk rheologies, body
+ forces will affect plastic yield criteria and the deformation field for
+ large deformation/finite strain problems.
+ As described in Chapter 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "cha:Governing-Equations"
+
+\end_inset
+
+, the body forces contribute to the residual,
+\begin_inset Formula 
+\begin{equation}
+r_{i}^{n}=\int_{V}f_{i}N^{n}\: dV.
+\end{equation}
+
+\end_inset
+
+For gravitational body forces the body force per unit volume, 
+\begin_inset Formula $f_{i}$
+\end_inset
+
+, is given as the product of the mass density, 
+\begin_inset Formula $\rho$
+\end_inset
+
+, the scalar gravitational acceleration value, 
+\begin_inset Formula $g$
+\end_inset
+
+, and the gravitational acceleration orientation vector, 
+\begin_inset Formula $a_{i}$
+\end_inset
+
+:
+\begin_inset Formula 
+\begin{equation}
+f_{i}=\rho ga_{i}.
+\end{equation}
+
+\end_inset
+
+The mass density is a property of every material model, and is thus included
+ in the spatial database with the physical properties for each material.
+ The gravitational acceleration is assumed to be uniform and constant for
+ a given problem, with a default value of 9.80665 m/s
+\begin_inset Formula $^{\text{2}}$
+\end_inset
+
+.
+ The orientation vector will depend on the dimension of the problem as well
+ as the coordinate system being used.
+ The default orientation vector has components (0, 0, -1).
+ This is appropriate for three-dimensional problems where the gravity vector
+ is aligned with the negative z-axis, as would be the case in a geographic-proje
+cted coordinate system or a generic Cartesian coordinate system.
+ For cases in which the curvature of the earth should be considered, the
+ spatialdata package provides an earth-centered, earth-fixed (ECEF) coordinate
+ system and a local georeferenced Cartesian system; in each of these cases
+ the orientation vector is computed automatically, although this feature
+ has not been tested.
+ For problems in one or two dimensions where the orientation vector is constant,
+ the vector will need to be explicitly specified.
+ For example, in a two-dimensional problem, the vector might be specified
+ as (0, -1, 0).
+ The vector still has three components, although the extra component is
+ not used.
+\end_layout
+
+\begin_layout Standard
+Gravity is turned off by default.
+ To include gravitational effects in a simulation, you can turn it on as
+ follows:
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.timedependent]
+\end_layout
+
+\begin_layout LyX-Code
+use_gravity = true
+\end_layout
+
+\begin_layout Standard
+By simply adding this flag, the default gravity field values will be used
+ and a 
+\family typewriter
+gravity_field
+\family default
+ component will be assigned for the problem.
+ The default values may be changed by altering the properties of 
+\family typewriter
+gravity_field
+\family default
+:
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.timedependent.gravity_field]
+\end_layout
+
+\begin_layout LyX-Code
+acceleration = 100.0*m*s**-2
+\end_layout
+
+\begin_layout LyX-Code
+gravity_dir = [0, -1, 0]
+\end_layout
+
+\begin_layout Standard
+An example problem using gravity is described in Section 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "sec:Tutorial-3d-hex8-gravity"
+
+\end_inset
+
+.
+\end_layout
+
+\end_body
+\end_document

Modified: short/3D/PyLith/branches/v1.7-trunk/doc/userguide/extending/extending.lyx
===================================================================
--- short/3D/PyLith/branches/v1.7-trunk/doc/userguide/extending/extending.lyx	2012-06-25 04:52:47 UTC (rev 20403)
+++ short/3D/PyLith/branches/v1.7-trunk/doc/userguide/extending/extending.lyx	2012-06-25 16:38:44 UTC (rev 20404)
@@ -1,1035 +1,1053 @@
-#LyX 1.6.5 created this file. For more info see http://www.lyx.org/
-\lyxformat 345
-\begin_document
-\begin_header
-\textclass book
-\begin_preamble
-
-\end_preamble
-\use_default_options false
-\language english
-\inputencoding latin1
-\font_roman default
-\font_sans default
-\font_typewriter default
-\font_default_family default
-\font_sc false
-\font_osf false
-\font_sf_scale 100
-\font_tt_scale 100
-
-\graphics default
-\paperfontsize default
-\spacing single
-\use_hyperref false
-\papersize default
-\use_geometry true
-\use_amsmath 1
-\use_esint 0
-\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
-\author "" 
-\author "" 
-\end_header
-
-\begin_body
-
-\begin_layout Chapter
-\begin_inset CommandInset label
-LatexCommand label
-name "cha:Extending"
-
-\end_inset
-
-Extending PyLith
-\end_layout
-
-\begin_layout Standard
-One of the powerful features of using the Pyre framework in PyLith is the
- ability to extend the functionality of the software without altering any
- of the PyLith code.
- Any of the components can be replaced with other compatible components.
- You are already familiar with this feature from running the examples; when
- you set the spatial database to UniformDB, SimpleDB, or SCECCVMH you are
- switching between different compatible components for a spatial database
- facility.
- Modifying the governing equations to include other physical processes requires
- changing the data structures associated with the solution and altering
- the PyLith code.
-\end_layout
-
-\begin_layout Standard
-In this section we provide examples of how to extend PyLith for components
- that users will most likely want to replace with their own custom versions.
- You will need a familiarity with Python, Makefiles, and C++ to write your
- own components.
- The primary steps in constructing a component to extend PyLith's functionality
- include:
-\end_layout
-
-\begin_layout Enumerate
-Setting up the source files for the component or set of components based
- on the templates.
-\end_layout
-
-\begin_layout Enumerate
-Edit the Python source file (
-\family typewriter
-.py
-\family default
-) for the component.
-\end_layout
-
-\begin_deeper
-\begin_layout Enumerate
-Define the user-specified properties and facilities.
-\end_layout
-
-\begin_layout Enumerate
-Transfer the user-specified data from the Python object to the corresponding
- C++ object via calls to the SWIG interface object.
-\end_layout
-
-\end_deeper
-\begin_layout Enumerate
-Edit the C++ header (
-\family typewriter
-.hh
-\family default
-) and implementation files (
-\family typewriter
-.cc
-\family default
-) for the component.
-\end_layout
-
-\begin_deeper
-\begin_layout Enumerate
-Implement the methods required to satisfy the interface definition of the
- component.
-\end_layout
-
-\begin_layout Enumerate
-Implement the desired functionality of the component in C++.
-\end_layout
-
-\end_deeper
-\begin_layout Enumerate
-Edit the SWIG interface files (
-\family typewriter
-.i
-\family default
-) that provide the glue between Python and C++.
-\end_layout
-
-\begin_layout Enumerate
-Edit the Python source file that tests the functionality of the component.
-\end_layout
-
-\begin_layout Enumerate
-Run configure, build, install, and run the tests of the component.
-\end_layout
-
-\begin_layout Section
-\begin_inset CommandInset label
-LatexCommand label
-name "sec:Extending:SpatialDatabases"
-
-\end_inset
-
-Spatial Databases
-\end_layout
-
-\begin_layout Standard
-PyLith provides several types of spatial databases that can be used for
- specification of parameters associated with boundary conditions, earthquake
- ruptures, and physical properties.
- In this example we demonstrate how to provide a spatial database, UniformVelMod
-el, for specifying elastic properties.
- The source files are included in the source for the spatialdata package
- in the 
-\family typewriter
-templates/spatialdb
-\family default
- directory.
- The 
-\family typewriter
-README
-\family default
- file in 
-\family typewriter
-templates/spatialdb
-\family default
- provides detailed instructions for the various steps involved, and the
- source files contain numerous comments to help guide you through the customizat
-ion process.
- 
-\end_layout
-
-\begin_layout Standard
-The UniformVelModel component provides uniform physical properties: P wave
- speed, S wave speed, and density.
- Although this is a rather trivial specification of physical properties
- that could be easily done using a UniformDB, this example demonstrates
- how to create a user-defined component that matches the requirements of
- a spatial database for elastic physical properties.
- Adding additional physical properties is simply a matter of including some
- additional values in the spatial database.
- Furthermore, in cases where we are constructing a spatial database for
- a seismic velocity model, the data points are georeferenced.
- With our uniform physical properties we do not need to worry about any
- differences in coordinate systems between our seismic velocity model and
- points at which the model is queried.
- However, in many cases we do, so we illustrate this functionality by using
- a geographic projection as the coordinate system in our example.
-\end_layout
-
-\begin_layout Standard
-Using a top-down approach, the first step is to determine what information
- the user will need to supply to the component.
- Is the data for the spatial database in a file or a series of files? If
- so, file names and possible paths to a directory containing files with
- known names might be necessary.
- Are there other parameters that control the behavior of the component,
- such as a minimum shear wave speed? In our example the user supplies values
- for the P wave speed, S wave speed, and density.
- The user-supplied parameters become Pyre properties and facilities in the
- Python source file.
- Because our user supplied parameters are floating point values with dimensions,
- we create dimensional properties 
-\family typewriter
-vs
-\family default
-, 
-\family typewriter
-vp
-\family default
-, and 
-\family typewriter
-density
-\family default
-.
- In addition to defining the properties of the component, we also need to
- transfer these properties to the C++ object that does the real work.
- This is done by calling the C++ 
-\family typewriter
-vs()
-\family default
-, 
-\family typewriter
-vp()
-\family default
-, and 
-\family typewriter
-density()
-\family default
- accessor functions that are accessible via the Python module created by
- SWIG.
-\end_layout
-
-\begin_layout Standard
-In the C++ object we must implement the functions that are required by the
- spatial database interface.
- These functions are listed near the beginning of the UniformVelModel class
- definition at the top of the C++ header file, 
-\family typewriter
-UniformVelModel.hh
-\family default
-.
- The C++ object also includes the accessor functions that allow us to set
- the P wave speed, S wave speed, and density values to the user-specified
- values in the Python object.
- Additional information, such as a file name, parameters defined as data
- structures, etc., would be set via similar accessor functions.
- You can also add additional functions and data structures to the C++ class
- to provide the necessary operations and functionality of the spatial database.
- 
-\end_layout
-
-\begin_layout Standard
-In SimpleDB we use a separate class to read in the spatial database and
- yet another class to perform the actual query.
- In our example, the C++ object also creates and stores the UTM zone 10
- geographic projection for the seismic velocity model.
- When the spatial database gets a query for physical properties, we transform
- the coordinates of the query point from its coordinate system to the coordinate
- system of our seismic velocity model.
-\end_layout
-
-\begin_layout Standard
-In order to use SWIG to create the Python module that allows us to call
- C++ from Python, we use a ``main'' SWIG interface file (
-\family typewriter
-\size small
-spatialdbcontrib.i
-\family default
-\size default
- in this case) and then one for each object (
-\family typewriter
-\size small
-UniformVelModel.i
-\family default
-\size default
- in this case).
- This greatly simplifies keeping the Python module synchronized with the
- C++ and Python code.
- The 
-\family typewriter
-\size small
-UniformVelModel.i
-\family default
-\size default
- SWIG file is nearly identical to the corresponding C++ header file.
- There are a few differences, as noted in the comments within the file.
- Copying and pasting the C++ header file and then doing a little cleanup
- is a very quick and easy way to construct a SWIG interface file for a C++
- object.
- Because very little changes from SWIG module to SWIG module, it is usually
- easiest to construct the ``main'' SWIG interface by copying and customizing
- an existing one.
-\end_layout
-
-\begin_layout Standard
-Once the Python, C++, and SWIG interface files are complete, we are ready
- to build the module.
- The 
-\family typewriter
-Makefile.am
-\family default
- file defines how to compile and link the C++ library and generate the Python
- module via SWIG.
- The 
-\family typewriter
-configure.ac
-\family default
- file contains the information used to build a configure script.
- The configure script checks to make sure it can find all of the tools needed
- to build the component (C++ compiler, Python, installed spatial database
- package, etc.).
- See the README file for detailed instructions on how to generate the configure
- script, and build and install the component.
-\end_layout
-
-\begin_layout Standard
-We recommend constructing tests of the component to insure that it is functionin
-g properly before attempting to use it in an application.
- The 
-\family typewriter
-\size small
-tests
-\family default
-\size default
- directory within 
-\family typewriter
-\size small
-templates/spatialdb
-\family default
-\size default
- contains a Python script, 
-\family typewriter
-\size small
-testcontrib.py
-\family default
-\size default
-, that runs the tests of the UniformVelModel component defined in 
-\family typewriter
-\size small
-TestUniformVelModel.py
-\family default
-\size default
-.
- Normally, one would want to test each function individually to isolate
- errors and create C++ tests as well as the Python tests included here.
- In our rather simple example, we simply test the overall functionality
- of the component.
- For examples of thorough testing, see the spatialdata and PyLith source
- code.
-\end_layout
-
-\begin_layout Standard
-Once you have built, installed, and tested the UniformVelModel, it is time
- to use it in a simple example.
- Because the seismic velocity model uses georeferenced coordinates, our
- example must also use georeferenced coordinates.
- The dislocation example in the PyLith 
-\family typewriter
-examples/twocells/twotet4-geopro
-\family default
-j directory uses UTM zone 11 coordinates.
- The spatial database package will transform the coordinates between the
- two projections as defined in the UniformVelModel 
-\family typewriter
-query()
-\family default
- function.
- The dislocation example uses the SCEC CVM-H seismic velocity model.
- In order to replace the SCEC CVM-H seismic velocity with our uniform velocity
- model, in 
-\family typewriter
-pylithapp.cfg
-\family default
- we replace the lines
-\end_layout
-
-\begin_layout LyX-Code
-db_properties = spatialdata.spatialdb.SCECCVMH
-\end_layout
-
-\begin_layout LyX-Code
-db_properties.data_dir = /home/brad/data/sceccvm-h/vx53/bin
-\end_layout
-
-\begin_layout Standard
-with the lines
-\end_layout
-
-\begin_layout LyX-Code
-db_properties = spatialdata.spatialdb.contrib.UniformVelModel
-\end_layout
-
-\begin_layout Standard
-When you run the dislocation example, the 
-\family typewriter
-dislocation-statevars_info.vtk
-\family default
- file should reflect the use of physical properties from the uniform seismic
- velocity with 
-\begin_inset Formula $\mu=1.69\times10^{10}\mathrm{Pa}$
-\end_inset
-
-, 
-\begin_inset Formula $\lambda=1.6825\times10^{10}\mathrm{Pa}$
-\end_inset
-
-, and 
-\begin_inset Formula $\rho=2500\mathrm{kg/m^{3}}$
-\end_inset
-
-.
-\end_layout
-
-\begin_layout Section
-\begin_inset CommandInset label
-LatexCommand label
-name "sec:Extending:BulkConstitutiveModels"
-
-\end_inset
-
-Bulk Constitutive Models
-\end_layout
-
-\begin_layout Standard
-PyLith includes several linearly elastic and inelastic bulk constitutive
- models for 2D and 3D problems.
- In this example, we demonstrate how to extend PyLith by adding your own
- bulk constitutive model.
- We reimplement the 2D plane strain constitutive model while adding the
- current strain and stress tensors as state variables.
- This constitutive model, 
-\family typewriter
-PlaneStrainState
-\family default
-, is not particularly useful, but it illustrates the basic steps involved
- in creating a bulk constitutive model with state variables.
- The sources files are included with the main PyLith source code in the
- 
-\family typewriter
-templates/materials
-\family default
- directory.
- The 
-\family typewriter
-README
-\family default
- file in 
-\family typewriter
-templates/materials
-\family default
- provides detailed instructions for the various steps, and the source files
- contain numerous comments to guide you through the customization process.
-\end_layout
-
-\begin_layout Standard
-In contrast to our previous example of creating a customized spatial database,
- which involved gathering user-specified parameters via the Pyre framework,
- there are no user-defined parameters for bulk constitutive models.
- The specification of the physical properties and state variables associated
- with the constitutive model is handled directly in the C++ code.
- As a result, the Python object for the constitutive model component is
- very simple and customization is limited to simply changing the names of
- objects and labels.
-\end_layout
-
-\begin_layout Standard
-The properties and state variables used in the bulk constitutive model are
- set using arguments to the constructor of the C++ 
-\family typewriter
-ElasticMaterial
-\family default
- object.
- We define a number of constants at the top of the C++ file and use the
- 
-\family typewriter
-Metadata
-\family default
- object to define the properties and state variables.
- The C++ object for the bulk constitutive component includes a number of
- functions that implement elasticity behavior of a bulk material as well
- as several utility routines:
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-_dbToProperties()
-\family default
- Computes the physical properties used in the constitutive model equations
- from the physical properties supplied in spatial databases.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-_nondimProperties()
-\family default
- Nondimensionalizes the physical properties used in the constitutive model
- equations.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-_dimProperties()
-\family default
- Dimensionalizes the physical properties used in the constitutive model
- equations.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-_stableTimeStepImplicit()
-\family default
- Computes the stable time step for implicit time stepping in quasi-static
- simulations given the current state (strain, stress, and state variables).
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-_calcDensity()
-\family default
- Computes the density given the physical properties and state variables.
- In most cases density is a physical property used in the constitutive equations
-, so this is a trivial function in those cases.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-_calcStress()
-\family default
- Computes the stress tensor given the physical properties, state variables,
- total strain, initial stress, and initial strain.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-_calcElasticConsts()
-\family default
- Computes the elastic constants given the physical properties, state variables,
- total strain, initial stress, and initial strain.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-_updateStateVars()
-\family default
- Updates the state variables given the physical properties, total strain,
- initial stress, and initial strain.
- If a constitutive model does not use state variables, then this routine
- is omitted.
-\end_layout
-
-\begin_layout Standard
-Because it is sometimes convenient to supply physical properties for a bulk
- constitutive model that are equivalent but different from the ones that
- appear in the constitutive equations (e.g., P wave speed, S wave speed, and
- density rather then Lame's constants 
-\begin_inset Formula $\mu,$
-\end_inset
-
-
-\begin_inset Formula $\lambda,$
-\end_inset
-
- and density), each bulk constitutive model component has routines to convert
- the physical property parameters and state variables a user specifies via
- spatial databases to the physical property properties and state variables
- used in the constitutive model equations.
- In quasi-static problems, PyLith computes an elastic solution for the first
- time step (
-\begin_inset Formula $-\Delta t$
-\end_inset
-
- to 
-\begin_inset Formula $t$
-\end_inset
-
-).
- This means that for inelastic materials, we supply two sets of functions
- for the constitutive behavior: one set for the initial elastic step and
- one set for the remainder of the simulation.
- See the source code for the inelastic materials in PyLith for an illustration
- of an efficient mechanism for doing this.
-\end_layout
-
-\begin_layout Standard
-The SWIG interface files for a bulk constitutive component are setup in
- the same manner as in the previous example of creating a customized spatial
- database component.
- The ``main'' SWIG interface file (
-\family typewriter
-materialscontrib.i
-\family default
- in this case) sets up the Python module, and the SWIG interface file for
- the component (
-\family typewriter
-PlaneStrainState.i
-\family default
- in this case) defines the functions that should be included in the Python
- module.
- Note that because the C++ 
-\family typewriter
-ElasticMaterial
-\family default
- object defines a number of pure virtual methods (which merely specify the
- interface for the functions and do not implement default behavior), we
- must include many protected functions in the SWIG interface file.
- If these are omitted, SWIG will give a warning indicating that some of
- the functions remain abstract (i.e., some pure virtual functions defined
- in the parent class 
-\family typewriter
-ElasticMaterial
-\family default
- were not implemented in the child class 
-\family typewriter
-PlaneStrainState
-\family default
-), and no constructor is created.
- When this happens, you cannot create a 
-\family typewriter
-PlaneStrainState
-\family default
- Python object.
-\end_layout
-
-\begin_layout Standard
-Once the Python, C++, and SWIG interface files are complete, you are ready
- to configure and build the C++ library and Python module for the component.
- Edit the 
-\family typewriter
-Makefile.am
-\family default
- file as necessary, then generate the configure script, run configure, and
- then build and install the library and module (see the 
-\family typewriter
-README
-\family default
- file for detailed instructions).
-\end_layout
-
-\begin_layout Standard
-Because most functionality of the bulk constitutive model component is at
- the C++ level, properly constructed unit tests for the 
-\family typewriter
-component
-\family default
- should include tests for both the C++ code and Python code.
- The C++ unit tests can be quite complex, and it is best to examine those
- used for the bulk constitutive models included with PyLith.
- In this example we create the Python unit tests to verify that we can create
- a 
-\family typewriter
-PlaneStrainState
-\family default
- Python object and call some of the simple underlying C++ functions.
- The source files are in the 
-\family typewriter
-templates/materials/tests
-\family default
- directory.
- The 
-\family typewriter
-testcontrib.py
-\family default
- Python script runs the tests defined in 
-\family typewriter
-TestPlaneStrainState.py
-\family default
-.
-\end_layout
-
-\begin_layout Standard
-Once you have built, installed, and tested the 
-\family typewriter
-PlaneStrainState
-\family default
- component, it is time to use it in a simple example.
- You can try using it in any of the 2D examples.
- For the examples in 
-\family typewriter
-examples/twocells/twoquad4
-\family default
-, in 
-\family typewriter
-pylithapp.cfg
-\family default
- replace the line
-\end_layout
-
-\begin_layout LyX-Code
-material = pylith.materials.ElasticPlaneStrain
-\end_layout
-
-\begin_layout Standard
-with the line
-\end_layout
-
-\begin_layout LyX-Code
-material = pylith.materials.contrib.PlaneStrainState
-\end_layout
-
-\begin_layout Standard
-or simply add the command line argument
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
---timedependent.homogeneous.material=pylith.materials.contrib.PlaneStrainState
-\end_layout
-
-\begin_layout Standard
-when running any of the 2D examples.
- The output should remain identical, but you should see the 
-\family typewriter
-PlaneStrainState
-\family default
- object listed in the information written to 
-\family typewriter
-stdout
-\family default
-.
-\end_layout
-
-\begin_layout Section
-\begin_inset CommandInset label
-LatexCommand label
-name "sec:Extending:FaultConstitutiveModels"
-
-\end_inset
-
-Fault Constitutive Models
-\end_layout
-
-\begin_layout Standard
-PyLith includes a two of the most widely used fault constitutive models,
- but there are a wide range of models that have been proposed to explain
- earthquake source processes.
- In this example, we demonstrate how to extend PyLith by adding your own
- fault constitutive model.
- We implement a linear viscous fault constitutive model wherein the perturbation
- in the coefficient of friction is linearly proportional to the slip rate.
- This constitutive model, 
-\family typewriter
-ViscousFriction
-\family default
-, is not particularly useful, but it illustrates the basic steps involved
- in creating a fault constitutive model.
- The sources files are included with the main PyLith source code in the
- 
-\family typewriter
-templates/friction
-\family default
- directory.
- The 
-\family typewriter
-README
-\family default
- file in 
-\family typewriter
-templates/friction
-\family default
- provides detailed instructions for the various steps, and the source files
- contain numerous comments to guide you through the customization process.
-\end_layout
-
-\begin_layout Standard
-Similar to our previous example of creating a customized bulk constitutive
- model, the parameters are defined in the C++ code, not in the Pyre framework.
- As a result, the Python object for the fault constitutive model component
- is very simple and customization is limited to simply changing the names
- of objects and labels.
-\end_layout
-
-\begin_layout Standard
-The properties and state variables used in the fault constitutive model
- are set using arguments to the constructor of the C++ 
-\family typewriter
-FrictionModel
-\family default
- object, analogous to the 
-\family typewriter
-ElasticMaterial
-\family default
- object for bulk constitutive models.
- In fact, both types of constitutive models used the same underlying C++
- object (
-\family typewriter
-Metadata::ParamDescription
-\family default
-) to store the description of the parameters and state variables.
- We define a number of constants at the top of the C++ file and use the
- 
-\family typewriter
-Metadata
-\family default
- object to define the properties and state variables.
- The C++ object for the fault constitutive component includes a number of
- functions that implement friction as well as several utility routines:
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-_dbToProperties()
-\family default
- Computes the physical properties used in the constitutive model equations
- from the physical properties supplied in spatial databases.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-_nondimProperties()
-\family default
- Nondimensionalizes the physical properties used in the constitutive model
- equations.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-_dimProperties()
-\family default
- Dimensionalizes the physical properties used in the constitutive model
- equations.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-_dbToStateVars()
-\family default
- Computes the initial state variables used in the constitutive model equations
- from the initial values supplied in spatial databases.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-_nondimStateVars()
-\family default
- Nondimensionalizes the state variables used in the constitutive model equations.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-_dimStateVars()
-\family default
- Dimensionalizes the state variables used in the constitutive model equations.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-_calcFriction()
-\family default
- Computes the friction stress given the physical properties, state variables,
- slip, slip rate, and normal traction.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-_updateStateVars()
-\family default
- Updates the state variables given the physical properties, slip, slip rate,
- and normal traction.
-\end_layout
-
-\begin_layout Standard
-If a constitutive model does not use state variables, then the state variable
- routines are omitted.
- 
-\end_layout
-
-\begin_layout Standard
-Because it is sometimes convenient to supply physical properties for a fault
- constitutive model that are equivalent but different from the ones that
- appear in the constitutive equations, each fault constitutive model component
- has routines to convert the physical property parameters and state variables
- a user specifies via spatial databases to the physical property properties
- and state variables used in the constitutive model equations.
- 
-\end_layout
-
-\begin_layout Standard
-The SWIG interface files for a fault constitutive component are setup in
- the same manner as in the previous examples of creating a bulk constitutive
- model or a customized spatial database component.
- The ``main'' SWIG interface file (
-\family typewriter
-frictioncontrib.i
-\family default
- in this case) sets up the Python module, and the SWIG interface file for
- the component (
-\family typewriter
-ViscousFriction.i
-\family default
- in this case) defines the functions that should be included in the Python
- module.
- Note that because the C++ 
-\family typewriter
-FrictionModel
-\family default
- object defines a number of pure virtual methods (which merely specify the
- interface for the functions and do not implement default behavior), we
- must include many protected functions in the SWIG interface file.
- If these are omitted, SWIG will give a warning indicating that some of
- the functions remain abstract (i.e., some pure virtual functions defined
- in the parent class 
-\family typewriter
-FrictionModel
-\family default
- were not implemented in the child class 
-\family typewriter
-ViscousFriction
-\family default
-), and no constructor is created.
- When this happens, you cannot create a 
-\family typewriter
-ViscousFriction
-\family default
- Python object.
-\end_layout
-
-\begin_layout Standard
-Once the Python, C++, and SWIG interface files are complete, you are ready
- to configure and build the C++ library and Python module for the component.
- Edit the 
-\family typewriter
-Makefile.am
-\family default
- file as necessary, then generate the configure script, run configure, and
- then build and install the library and module (see the 
-\family typewriter
-README
-\family default
- file for detailed instructions).
-\end_layout
-
-\begin_layout Standard
-Because most functionality of the fault constitutive model component is
- at the C++ level, properly constructed unit tests for the 
-\family typewriter
-component
-\family default
- should include tests for both the C++ code and Python code.
- The C++ unit tests can be quite complex, and it is best to examine those
- used for the fault constitutive models included with PyLith.
- In this example we create the Python unit tests to verify that we can create
- a 
-\family typewriter
-ViscousFriction
-\family default
- Python object and call some of the simple underlying C++ functions.
- The source files are in the 
-\family typewriter
-templates/friction/tests
-\family default
- directory.
- The 
-\family typewriter
-testcontrib.py
-\family default
- Python script runs the tests defined in 
-\family typewriter
-TestViscousFriction.py
-\family default
-.
-\end_layout
-
-\begin_layout Standard
-Once you have built, installed, and tested the 
-\family typewriter
-ViscousFriction
-\family default
- component, it is time to use it in a simple example.
- You can try using it in any of the 2D or 3D examples.
- For the examples in 
-\family typewriter
-examples/bar_shearwave/quad4, in shearwave_staticfriction.cfg
-\family default
- replace the line
-\end_layout
-
-\begin_layout LyX-Code
-friction = pylith.friction.StaticFriction
-\end_layout
-
-\begin_layout Standard
-with the line
-\end_layout
-
-\begin_layout LyX-Code
-friction = pylith.friction.contrib.ViscousFriction
-\end_layout
-
-\begin_layout Standard
-or simply add the command line argument
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
---timedependent.interfaces.fault.friction=pylith.friction.contrib.ViscousFriction
-\end_layout
-
-\begin_layout Standard
-when running any of the friction examples.
- You will also need to supply a corresponding spatial database with the
- physical properties for the viscous friction constitutive model.
-\end_layout
-
-\end_body
-\end_document
+#LyX 2.0 created this file. For more info see http://www.lyx.org/
+\lyxformat 413
+\begin_document
+\begin_header
+\textclass book
+\begin_preamble
+
+\end_preamble
+\use_default_options false
+\maintain_unincluded_children false
+\language english
+\language_package default
+\inputencoding latin1
+\fontencoding global
+\font_roman default
+\font_sans default
+\font_typewriter default
+\font_default_family default
+\use_non_tex_fonts false
+\font_sc false
+\font_osf false
+\font_sf_scale 100
+\font_tt_scale 100
+
+\graphics default
+\default_output_format default
+\output_sync 0
+\bibtex_command default
+\index_command default
+\paperfontsize default
+\spacing single
+\use_hyperref false
+\papersize default
+\use_geometry true
+\use_amsmath 1
+\use_esint 0
+\use_mhchem 1
+\use_mathdots 1
+\cite_engine basic
+\use_bibtopic false
+\use_indices false
+\paperorientation portrait
+\suppress_date false
+\use_refstyle 0
+\index Index
+\shortcut idx
+\color #008000
+\end_index
+\leftmargin 1in
+\topmargin 1in
+\rightmargin 1in
+\bottommargin 2in
+\secnumdepth 3
+\tocdepth 3
+\paragraph_separation indent
+\paragraph_indentation default
+\quotes_language english
+\papercolumns 1
+\papersides 2
+\paperpagestyle default
+\tracking_changes false
+\output_changes false
+\html_math_output 0
+\html_css_as_file 0
+\html_be_strict false
+\end_header
+
+\begin_body
+
+\begin_layout Chapter
+\begin_inset CommandInset label
+LatexCommand label
+name "cha:Extending"
+
+\end_inset
+
+Extending PyLith
+\end_layout
+
+\begin_layout Standard
+One of the powerful features of using the Pyre framework in PyLith is the
+ ability to extend the functionality of the software without altering any
+ of the PyLith code.
+ Any of the components can be replaced with other compatible components.
+ You are already familiar with this feature from running the examples; when
+ you set the spatial database to UniformDB, SimpleDB, or SCECCVMH you are
+ switching between different compatible components for a spatial database
+ facility.
+ Modifying the governing equations to include other physical processes requires
+ changing the data structures associated with the solution and altering
+ the PyLith code.
+\end_layout
+
+\begin_layout Standard
+In this section we provide examples of how to extend PyLith for components
+ that users will most likely want to replace with their own custom versions.
+ You will need a familiarity with Python, Makefiles, and C++ to write your
+ own components.
+ The primary steps in constructing a component to extend PyLith's functionality
+ include:
+\end_layout
+
+\begin_layout Enumerate
+Setting up the source files for the component or set of components based
+ on the templates.
+\end_layout
+
+\begin_layout Enumerate
+Edit the Python source file (
+\family typewriter
+.py
+\family default
+) for the component.
+\end_layout
+
+\begin_deeper
+\begin_layout Enumerate
+Define the user-specified properties and facilities.
+\end_layout
+
+\begin_layout Enumerate
+Transfer the user-specified data from the Python object to the corresponding
+ C++ object via calls to the SWIG interface object.
+\end_layout
+
+\end_deeper
+\begin_layout Enumerate
+Edit the C++ header (
+\family typewriter
+.hh
+\family default
+) and implementation files (
+\family typewriter
+.cc
+\family default
+) for the component.
+\end_layout
+
+\begin_deeper
+\begin_layout Enumerate
+Implement the methods required to satisfy the interface definition of the
+ component.
+\end_layout
+
+\begin_layout Enumerate
+Implement the desired functionality of the component in C++.
+\end_layout
+
+\end_deeper
+\begin_layout Enumerate
+Edit the SWIG interface files (
+\family typewriter
+.i
+\family default
+) that provide the glue between Python and C++.
+\end_layout
+
+\begin_layout Enumerate
+Edit the Python source file that tests the functionality of the component.
+\end_layout
+
+\begin_layout Enumerate
+Run configure, build, install, and run the tests of the component.
+\end_layout
+
+\begin_layout Section
+\begin_inset CommandInset label
+LatexCommand label
+name "sec:Extending:SpatialDatabases"
+
+\end_inset
+
+Spatial Databases
+\end_layout
+
+\begin_layout Standard
+PyLith provides several types of spatial databases that can be used for
+ specification of parameters associated with boundary conditions, earthquake
+ ruptures, and physical properties.
+ In this example we demonstrate how to provide a spatial database, UniformVelMod
+el, for specifying elastic properties.
+ The source files are included in the source for the spatialdata package
+ in the 
+\family typewriter
+templates/spatialdb
+\family default
+ directory.
+ The 
+\family typewriter
+README
+\family default
+ file in 
+\family typewriter
+templates/spatialdb
+\family default
+ provides detailed instructions for the various steps involved, and the
+ source files contain numerous comments to help guide you through the customizat
+ion process.
+ 
+\end_layout
+
+\begin_layout Standard
+The UniformVelModel component provides uniform physical properties: P wave
+ speed, S wave speed, and density.
+ Although this is a rather trivial specification of physical properties
+ that could be easily done using a UniformDB, this example demonstrates
+ how to create a user-defined component that matches the requirements of
+ a spatial database for elastic physical properties.
+ Adding additional physical properties is simply a matter of including some
+ additional values in the spatial database.
+ Furthermore, in cases where we are constructing a spatial database for
+ a seismic velocity model, the data points are georeferenced.
+ With our uniform physical properties we do not need to worry about any
+ differences in coordinate systems between our seismic velocity model and
+ points at which the model is queried.
+ However, in many cases we do, so we illustrate this functionality by using
+ a geographic projection as the coordinate system in our example.
+\end_layout
+
+\begin_layout Standard
+Using a top-down approach, the first step is to determine what information
+ the user will need to supply to the component.
+ Is the data for the spatial database in a file or a series of files? If
+ so, file names and possible paths to a directory containing files with
+ known names might be necessary.
+ Are there other parameters that control the behavior of the component,
+ such as a minimum shear wave speed? In our example the user supplies values
+ for the P wave speed, S wave speed, and density.
+ The user-supplied parameters become Pyre properties and facilities in the
+ Python source file.
+ Because our user supplied parameters are floating point values with dimensions,
+ we create dimensional properties 
+\family typewriter
+vs
+\family default
+, 
+\family typewriter
+vp
+\family default
+, and 
+\family typewriter
+density
+\family default
+.
+ In addition to defining the properties of the component, we also need to
+ transfer these properties to the C++ object that does the real work.
+ This is done by calling the C++ 
+\family typewriter
+vs()
+\family default
+, 
+\family typewriter
+vp()
+\family default
+, and 
+\family typewriter
+density()
+\family default
+ accessor functions that are accessible via the Python module created by
+ SWIG.
+\end_layout
+
+\begin_layout Standard
+In the C++ object we must implement the functions that are required by the
+ spatial database interface.
+ These functions are listed near the beginning of the UniformVelModel class
+ definition at the top of the C++ header file, 
+\family typewriter
+UniformVelModel.hh
+\family default
+.
+ The C++ object also includes the accessor functions that allow us to set
+ the P wave speed, S wave speed, and density values to the user-specified
+ values in the Python object.
+ Additional information, such as a file name, parameters defined as data
+ structures, etc., would be set via similar accessor functions.
+ You can also add additional functions and data structures to the C++ class
+ to provide the necessary operations and functionality of the spatial database.
+ 
+\end_layout
+
+\begin_layout Standard
+In SimpleDB we use a separate class to read in the spatial database and
+ yet another class to perform the actual query.
+ In our example, the C++ object also creates and stores the UTM zone 10
+ geographic projection for the seismic velocity model.
+ When the spatial database gets a query for physical properties, we transform
+ the coordinates of the query point from its coordinate system to the coordinate
+ system of our seismic velocity model.
+\end_layout
+
+\begin_layout Standard
+In order to use SWIG to create the Python module that allows us to call
+ C++ from Python, we use a ``main'' SWIG interface file (
+\family typewriter
+\size small
+spatialdbcontrib.i
+\family default
+\size default
+ in this case) and then one for each object (
+\family typewriter
+\size small
+UniformVelModel.i
+\family default
+\size default
+ in this case).
+ This greatly simplifies keeping the Python module synchronized with the
+ C++ and Python code.
+ The 
+\family typewriter
+\size small
+UniformVelModel.i
+\family default
+\size default
+ SWIG file is nearly identical to the corresponding C++ header file.
+ There are a few differences, as noted in the comments within the file.
+ Copying and pasting the C++ header file and then doing a little cleanup
+ is a very quick and easy way to construct a SWIG interface file for a C++
+ object.
+ Because very little changes from SWIG module to SWIG module, it is usually
+ easiest to construct the ``main'' SWIG interface by copying and customizing
+ an existing one.
+\end_layout
+
+\begin_layout Standard
+Once the Python, C++, and SWIG interface files are complete, we are ready
+ to build the module.
+ The 
+\family typewriter
+Makefile.am
+\family default
+ file defines how to compile and link the C++ library and generate the Python
+ module via SWIG.
+ The 
+\family typewriter
+configure.ac
+\family default
+ file contains the information used to build a configure script.
+ The configure script checks to make sure it can find all of the tools needed
+ to build the component (C++ compiler, Python, installed spatial database
+ package, etc.).
+ See the README file for detailed instructions on how to generate the configure
+ script, and build and install the component.
+\end_layout
+
+\begin_layout Standard
+We recommend constructing tests of the component to insure that it is functionin
+g properly before attempting to use it in an application.
+ The 
+\family typewriter
+\size small
+tests
+\family default
+\size default
+ directory within 
+\family typewriter
+\size small
+templates/spatialdb
+\family default
+\size default
+ contains a Python script, 
+\family typewriter
+\size small
+testcontrib.py
+\family default
+\size default
+, that runs the tests of the UniformVelModel component defined in 
+\family typewriter
+\size small
+TestUniformVelModel.py
+\family default
+\size default
+.
+ Normally, one would want to test each function individually to isolate
+ errors and create C++ tests as well as the Python tests included here.
+ In our rather simple example, we simply test the overall functionality
+ of the component.
+ For examples of thorough testing, see the spatialdata and PyLith source
+ code.
+\end_layout
+
+\begin_layout Standard
+Once you have built, installed, and tested the UniformVelModel, it is time
+ to use it in a simple example.
+ Because the seismic velocity model uses georeferenced coordinates, our
+ example must also use georeferenced coordinates.
+ The dislocation example in the PyLith 
+\family typewriter
+examples/twocells/twotet4-geopro
+\family default
+j directory uses UTM zone 11 coordinates.
+ The spatial database package will transform the coordinates between the
+ two projections as defined in the UniformVelModel 
+\family typewriter
+query()
+\family default
+ function.
+ The dislocation example uses the SCEC CVM-H seismic velocity model.
+ In order to replace the SCEC CVM-H seismic velocity with our uniform velocity
+ model, in 
+\family typewriter
+pylithapp.cfg
+\family default
+ we replace the lines
+\end_layout
+
+\begin_layout LyX-Code
+db_properties = spatialdata.spatialdb.SCECCVMH
+\end_layout
+
+\begin_layout LyX-Code
+db_properties.data_dir = /home/brad/data/sceccvm-h/vx53/bin
+\end_layout
+
+\begin_layout Standard
+with the lines
+\end_layout
+
+\begin_layout LyX-Code
+db_properties = spatialdata.spatialdb.contrib.UniformVelModel
+\end_layout
+
+\begin_layout Standard
+When you run the dislocation example, the 
+\family typewriter
+dislocation-statevars_info.vtk
+\family default
+ file should reflect the use of physical properties from the uniform seismic
+ velocity with 
+\begin_inset Formula $\mu=1.69\times10^{10}\mathrm{Pa}$
+\end_inset
+
+, 
+\begin_inset Formula $\lambda=1.6825\times10^{10}\mathrm{Pa}$
+\end_inset
+
+, and 
+\begin_inset Formula $\rho=2500\mathrm{kg/m^{3}}$
+\end_inset
+
+.
+\end_layout
+
+\begin_layout Section
+\begin_inset CommandInset label
+LatexCommand label
+name "sec:Extending:BulkConstitutiveModels"
+
+\end_inset
+
+Bulk Constitutive Models
+\end_layout
+
+\begin_layout Standard
+PyLith includes several linearly elastic and inelastic bulk constitutive
+ models for 2D and 3D problems.
+ In this example, we demonstrate how to extend PyLith by adding your own
+ bulk constitutive model.
+ We reimplement the 2D plane strain constitutive model while adding the
+ current strain and stress tensors as state variables.
+ This constitutive model, 
+\family typewriter
+PlaneStrainState
+\family default
+, is not particularly useful, but it illustrates the basic steps involved
+ in creating a bulk constitutive model with state variables.
+ The sources files are included with the main PyLith source code in the
+ 
+\family typewriter
+templates/materials
+\family default
+ directory.
+ The 
+\family typewriter
+README
+\family default
+ file in 
+\family typewriter
+templates/materials
+\family default
+ provides detailed instructions for the various steps, and the source files
+ contain numerous comments to guide you through the customization process.
+\end_layout
+
+\begin_layout Standard
+In contrast to our previous example of creating a customized spatial database,
+ which involved gathering user-specified parameters via the Pyre framework,
+ there are no user-defined parameters for bulk constitutive models.
+ The specification of the physical properties and state variables associated
+ with the constitutive model is handled directly in the C++ code.
+ As a result, the Python object for the constitutive model component is
+ very simple and customization is limited to simply changing the names of
+ objects and labels.
+\end_layout
+
+\begin_layout Standard
+The properties and state variables used in the bulk constitutive model are
+ set using arguments to the constructor of the C++ 
+\family typewriter
+ElasticMaterial
+\family default
+ object.
+ We define a number of constants at the top of the C++ file and use the
+ 
+\family typewriter
+Metadata
+\family default
+ object to define the properties and state variables.
+ The C++ object for the bulk constitutive component includes a number of
+ functions that implement elasticity behavior of a bulk material as well
+ as several utility routines:
+\end_layout
+
+\begin_layout Description
+
+\family typewriter
+_dbToProperties()
+\family default
+ Computes the physical properties used in the constitutive model equations
+ from the physical properties supplied in spatial databases.
+\end_layout
+
+\begin_layout Description
+
+\family typewriter
+_nondimProperties()
+\family default
+ Nondimensionalizes the physical properties used in the constitutive model
+ equations.
+\end_layout
+
+\begin_layout Description
+
+\family typewriter
+_dimProperties()
+\family default
+ Dimensionalizes the physical properties used in the constitutive model
+ equations.
+\end_layout
+
+\begin_layout Description
+
+\family typewriter
+_stableTimeStepImplicit()
+\family default
+ Computes the stable time step for implicit time stepping in quasi-static
+ simulations given the current state (strain, stress, and state variables).
+\end_layout
+
+\begin_layout Description
+
+\family typewriter
+_calcDensity()
+\family default
+ Computes the density given the physical properties and state variables.
+ In most cases density is a physical property used in the constitutive equations
+, so this is a trivial function in those cases.
+\end_layout
+
+\begin_layout Description
+
+\family typewriter
+_calcStress()
+\family default
+ Computes the stress tensor given the physical properties, state variables,
+ total strain, initial stress, and initial strain.
+\end_layout
+
+\begin_layout Description
+
+\family typewriter
+_calcElasticConsts()
+\family default
+ Computes the elastic constants given the physical properties, state variables,
+ total strain, initial stress, and initial strain.
+\end_layout
+
+\begin_layout Description
+
+\family typewriter
+_updateStateVars()
+\family default
+ Updates the state variables given the physical properties, total strain,
+ initial stress, and initial strain.
+ If a constitutive model does not use state variables, then this routine
+ is omitted.
+\end_layout
+
+\begin_layout Standard
+Because it is sometimes convenient to supply physical properties for a bulk
+ constitutive model that are equivalent but different from the ones that
+ appear in the constitutive equations (e.g., P wave speed, S wave speed, and
+ density rather then Lame's constants 
+\begin_inset Formula $\mu,$
+\end_inset
+
+
+\begin_inset Formula $\lambda,$
+\end_inset
+
+ and density), each bulk constitutive model component has routines to convert
+ the physical property parameters and state variables a user specifies via
+ spatial databases to the physical property properties and state variables
+ used in the constitutive model equations.
+ In quasi-static problems, PyLith computes an elastic solution for the first
+ time step (
+\begin_inset Formula $-\Delta t$
+\end_inset
+
+ to 
+\begin_inset Formula $t$
+\end_inset
+
+).
+ This means that for inelastic materials, we supply two sets of functions
+ for the constitutive behavior: one set for the initial elastic step and
+ one set for the remainder of the simulation.
+ See the source code for the inelastic materials in PyLith for an illustration
+ of an efficient mechanism for doing this.
+\end_layout
+
+\begin_layout Standard
+The SWIG interface files for a bulk constitutive component are setup in
+ the same manner as in the previous example of creating a customized spatial
+ database component.
+ The ``main'' SWIG interface file (
+\family typewriter
+materialscontrib.i
+\family default
+ in this case) sets up the Python module, and the SWIG interface file for
+ the component (
+\family typewriter
+PlaneStrainState.i
+\family default
+ in this case) defines the functions that should be included in the Python
+ module.
+ Note that because the C++ 
+\family typewriter
+ElasticMaterial
+\family default
+ object defines a number of pure virtual methods (which merely specify the
+ interface for the functions and do not implement default behavior), we
+ must include many protected functions in the SWIG interface file.
+ If these are omitted, SWIG will give a warning indicating that some of
+ the functions remain abstract (i.e., some pure virtual functions defined
+ in the parent class 
+\family typewriter
+ElasticMaterial
+\family default
+ were not implemented in the child class 
+\family typewriter
+PlaneStrainState
+\family default
+), and no constructor is created.
+ When this happens, you cannot create a 
+\family typewriter
+PlaneStrainState
+\family default
+ Python object.
+\end_layout
+
+\begin_layout Standard
+Once the Python, C++, and SWIG interface files are complete, you are ready
+ to configure and build the C++ library and Python module for the component.
+ Edit the 
+\family typewriter
+Makefile.am
+\family default
+ file as necessary, then generate the configure script, run configure, and
+ then build and install the library and module (see the 
+\family typewriter
+README
+\family default
+ file for detailed instructions).
+\end_layout
+
+\begin_layout Standard
+Because most functionality of the bulk constitutive model component is at
+ the C++ level, properly constructed unit tests for the 
+\family typewriter
+component
+\family default
+ should include tests for both the C++ code and Python code.
+ The C++ unit tests can be quite complex, and it is best to examine those
+ used for the bulk constitutive models included with PyLith.
+ In this example we create the Python unit tests to verify that we can create
+ a 
+\family typewriter
+PlaneStrainState
+\family default
+ Python object and call some of the simple underlying C++ functions.
+ The source files are in the 
+\family typewriter
+templates/materials/tests
+\family default
+ directory.
+ The 
+\family typewriter
+testcontrib.py
+\family default
+ Python script runs the tests defined in 
+\family typewriter
+TestPlaneStrainState.py
+\family default
+.
+\end_layout
+
+\begin_layout Standard
+Once you have built, installed, and tested the 
+\family typewriter
+PlaneStrainState
+\family default
+ component, it is time to use it in a simple example.
+ You can try using it in any of the 2D examples.
+ For the examples in 
+\family typewriter
+examples/twocells/twoquad4
+\family default
+, in 
+\family typewriter
+pylithapp.cfg
+\family default
+ replace the line
+\end_layout
+
+\begin_layout LyX-Code
+material = pylith.materials.ElasticPlaneStrain
+\end_layout
+
+\begin_layout Standard
+with the line
+\end_layout
+
+\begin_layout LyX-Code
+material = pylith.materials.contrib.PlaneStrainState
+\end_layout
+
+\begin_layout Standard
+or simply add the command line argument
+\end_layout
+
+\begin_layout LyX-Code
+
+\family typewriter
+--timedependent.homogeneous.material=pylith.materials.contrib.PlaneStrainState
+\end_layout
+
+\begin_layout Standard
+when running any of the 2D examples.
+ The output should remain identical, but you should see the 
+\family typewriter
+PlaneStrainState
+\family default
+ object listed in the information written to 
+\family typewriter
+stdout
+\family default
+.
+\end_layout
+
+\begin_layout Section
+\begin_inset CommandInset label
+LatexCommand label
+name "sec:Extending:FaultConstitutiveModels"
+
+\end_inset
+
+Fault Constitutive Models
+\end_layout
+
+\begin_layout Standard
+PyLith includes two of the most widely used fault constitutive models, but
+ there are a wide range of models that have been proposed to explain earthquake
+ source processes.
+ In this example, we demonstrate how to extend PyLith by adding your own
+ fault constitutive model.
+ We implement a linear viscous fault constitutive model wherein the perturbation
+ in the coefficient of friction is linearly proportional to the slip rate.
+ This constitutive model, 
+\family typewriter
+ViscousFriction
+\family default
+, is not particularly useful, but it illustrates the basic steps involved
+ in creating a fault constitutive model.
+ The sources files are included with the main PyLith source code in the
+ 
+\family typewriter
+templates/friction
+\family default
+ directory.
+ The 
+\family typewriter
+README
+\family default
+ file in 
+\family typewriter
+templates/friction
+\family default
+ provides detailed instructions for the various steps, and the source files
+ contain numerous comments to guide you through the customization process.
+\end_layout
+
+\begin_layout Standard
+Similar to our previous example of creating a customized bulk constitutive
+ model, the parameters are defined in the C++ code, not in the Pyre framework.
+ As a result, the Python object for the fault constitutive model component
+ is very simple and customization is limited to simply changing the names
+ of objects and labels.
+\end_layout
+
+\begin_layout Standard
+The properties and state variables used in the fault constitutive model
+ are set using arguments to the constructor of the C++ 
+\family typewriter
+FrictionModel
+\family default
+ object, analogous to the 
+\family typewriter
+ElasticMaterial
+\family default
+ object for bulk constitutive models.
+ In fact, both types of constitutive models used the same underlying C++
+ object (
+\family typewriter
+Metadata::ParamDescription
+\family default
+) to store the description of the parameters and state variables.
+ We define a number of constants at the top of the C++ file and use the
+ 
+\family typewriter
+Metadata
+\family default
+ object to define the properties and state variables.
+ The C++ object for the fault constitutive component includes a number of
+ functions that implement friction as well as several utility routines:
+\end_layout
+
+\begin_layout Description
+
+\family typewriter
+_dbToProperties()
+\family default
+ Computes the physical properties used in the constitutive model equations
+ from the physical properties supplied in spatial databases.
+\end_layout
+
+\begin_layout Description
+
+\family typewriter
+_nondimProperties()
+\family default
+ Nondimensionalizes the physical properties used in the constitutive model
+ equations.
+\end_layout
+
+\begin_layout Description
+
+\family typewriter
+_dimProperties()
+\family default
+ Dimensionalizes the physical properties used in the constitutive model
+ equations.
+\end_layout
+
+\begin_layout Description
+
+\family typewriter
+_dbToStateVars()
+\family default
+ Computes the initial state variables used in the constitutive model equations
+ from the initial values supplied in spatial databases.
+\end_layout
+
+\begin_layout Description
+
+\family typewriter
+_nondimStateVars()
+\family default
+ Nondimensionalizes the state variables used in the constitutive model equations.
+\end_layout
+
+\begin_layout Description
+
+\family typewriter
+_dimStateVars()
+\family default
+ Dimensionalizes the state variables used in the constitutive model equations.
+\end_layout
+
+\begin_layout Description
+
+\family typewriter
+_calcFriction()
+\family default
+ Computes the friction stress given the physical properties, state variables,
+ slip, slip rate, and normal traction.
+\end_layout
+
+\begin_layout Description
+
+\family typewriter
+_updateStateVars()
+\family default
+ Updates the state variables given the physical properties, slip, slip rate,
+ and normal traction.
+\end_layout
+
+\begin_layout Standard
+If a constitutive model does not use state variables, then the state variable
+ routines are omitted.
+ 
+\end_layout
+
+\begin_layout Standard
+Because it is sometimes convenient to supply physical properties for a fault
+ constitutive model that are equivalent but different from the ones that
+ appear in the constitutive equations, each fault constitutive model component
+ has routines to convert the physical property parameters and state variables
+ a user specifies via spatial databases to the physical property properties
+ and state variables used in the constitutive model equations.
+ 
+\end_layout
+
+\begin_layout Standard
+The SWIG interface files for a fault constitutive component are setup in
+ the same manner as in the previous examples of creating a bulk constitutive
+ model or a customized spatial database component.
+ The ``main'' SWIG interface file (
+\family typewriter
+frictioncontrib.i
+\family default
+ in this case) sets up the Python module, and the SWIG interface file for
+ the component (
+\family typewriter
+ViscousFriction.i
+\family default
+ in this case) defines the functions that should be included in the Python
+ module.
+ Note that because the C++ 
+\family typewriter
+FrictionModel
+\family default
+ object defines a number of pure virtual methods (which merely specify the
+ interface for the functions and do not implement default behavior), we
+ must include many protected functions in the SWIG interface file.
+ If these are omitted, SWIG will give a warning indicating that some of
+ the functions remain abstract (i.e., some pure virtual functions defined
+ in the parent class 
+\family typewriter
+FrictionModel
+\family default
+ were not implemented in the child class 
+\family typewriter
+ViscousFriction
+\family default
+), and no constructor is created.
+ When this happens, you cannot create a 
+\family typewriter
+ViscousFriction
+\family default
+ Python object.
+\end_layout
+
+\begin_layout Standard
+Once the Python, C++, and SWIG interface files are complete, you are ready
+ to configure and build the C++ library and Python module for the component.
+ Edit the 
+\family typewriter
+Makefile.am
+\family default
+ file as necessary, then generate the configure script, run configure, and
+ then build and install the library and module (see the 
+\family typewriter
+README
+\family default
+ file for detailed instructions).
+\end_layout
+
+\begin_layout Standard
+Because most functionality of the fault constitutive model component is
+ at the C++ level, properly constructed unit tests for the 
+\family typewriter
+component
+\family default
+ should include tests for both the C++ code and Python code.
+ The C++ unit tests can be quite complex, and it is best to examine those
+ used for the fault constitutive models included with PyLith.
+ In this example we create the Python unit tests to verify that we can create
+ a 
+\family typewriter
+ViscousFriction
+\family default
+ Python object and call some of the simple underlying C++ functions.
+ The source files are in the 
+\family typewriter
+templates/friction/tests
+\family default
+ directory.
+ The 
+\family typewriter
+testcontrib.py
+\family default
+ Python script runs the tests defined in 
+\family typewriter
+TestViscousFriction.py
+\family default
+.
+\end_layout
+
+\begin_layout Standard
+Once you have built, installed, and tested the 
+\family typewriter
+ViscousFriction
+\family default
+ component, it is time to use it in a simple example.
+ You can try using it in any of the 2D or 3D examples.
+ For the examples in 
+\family typewriter
+examples/bar_shearwave/quad4, in shearwave_staticfriction.cfg
+\family default
+ replace the line
+\end_layout
+
+\begin_layout LyX-Code
+friction = pylith.friction.StaticFriction
+\end_layout
+
+\begin_layout Standard
+with the line
+\end_layout
+
+\begin_layout LyX-Code
+friction = pylith.friction.contrib.ViscousFriction
+\end_layout
+
+\begin_layout Standard
+or simply add the command line argument
+\end_layout
+
+\begin_layout LyX-Code
+
+\family typewriter
+--timedependent.interfaces.fault.friction=pylith.friction.contrib.ViscousFriction
+\end_layout
+
+\begin_layout Standard
+when running any of the friction examples.
+ You will also need to supply a corresponding spatial database with the
+ physical properties for the viscous friction constitutive model.
+\end_layout
+
+\end_body
+\end_document

Modified: short/3D/PyLith/branches/v1.7-trunk/doc/userguide/runpylith/runpylith.lyx
===================================================================
--- short/3D/PyLith/branches/v1.7-trunk/doc/userguide/runpylith/runpylith.lyx	2012-06-25 04:52:47 UTC (rev 20403)
+++ short/3D/PyLith/branches/v1.7-trunk/doc/userguide/runpylith/runpylith.lyx	2012-06-25 16:38:44 UTC (rev 20404)
@@ -1,5595 +1,5601 @@
-#LyX 2.0 created this file. For more info see http://www.lyx.org/
-\lyxformat 413
-\begin_document
-\begin_header
-\textclass book
-\begin_preamble
-
-\end_preamble
-\use_default_options false
-\maintain_unincluded_children false
-\language english
-\language_package default
-\inputencoding latin1
-\fontencoding global
-\font_roman default
-\font_sans default
-\font_typewriter default
-\font_default_family default
-\use_non_tex_fonts false
-\font_sc false
-\font_osf false
-\font_sf_scale 100
-\font_tt_scale 100
-
-\graphics default
-\default_output_format default
-\output_sync 0
-\bibtex_command default
-\index_command default
-\paperfontsize default
-\spacing single
-\use_hyperref false
-\papersize default
-\use_geometry true
-\use_amsmath 1
-\use_esint 0
-\use_mhchem 1
-\use_mathdots 1
-\cite_engine basic
-\use_bibtopic false
-\use_indices false
-\paperorientation portrait
-\suppress_date false
-\use_refstyle 0
-\index Index
-\shortcut idx
-\color #008000
-\end_index
-\leftmargin 1in
-\topmargin 1in
-\rightmargin 1in
-\bottommargin 2in
-\secnumdepth 3
-\tocdepth 3
-\paragraph_separation indent
-\paragraph_indentation default
-\quotes_language english
-\papercolumns 1
-\papersides 2
-\paperpagestyle default
-\tracking_changes false
-\output_changes false
-\html_math_output 0
-\html_css_as_file 0
-\html_be_strict false
-\end_header
-
-\begin_body
-
-\begin_layout Chapter
-Running PyLith
-\end_layout
-
-\begin_layout Standard
-There are essentially three major inputs needed to run a problem with PyLith:
-\end_layout
-
-\begin_layout Enumerate
-A set of parameters describing the problem.
- These parameters describe the type of problem to be run, solver information,
- time-stepping information, boundary conditions, materials, etc.
- This information can be provided from the command-line or by using a 
-\family typewriter
-.cfg
-\family default
- or 
-\family typewriter
-.pml
-\family default
- file.
-\end_layout
-
-\begin_layout Enumerate
-Mesh information.
- This includes the topology of the finite-element mesh (coordinates of vertices
- and how the vertices are connected into cells), a 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 CommandInset ref
-LatexCommand ref
-reference "cha:Tutorials"
-
-\end_inset
-
- for examples and Section 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "sec:MeshIOAscii"
-
-\end_inset
-
- for the format specification) or by importing the information from the
- LaGriT or CUBIT meshing packages (see Chapter 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "cha:Tutorials"
-
-\end_inset
-
- for examples).
-\end_layout
-
-\begin_layout Enumerate
-Databases specifying the material property values and boundary condition
- values to be used.
- Arbitrarily complex spatial variations in boundary and fault conditions
- and material properties may be given in the spatial database (see Chapter
- 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "cha:Tutorials"
-
-\end_inset
-
- for examples and Appendix 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "sec:Spatialdata:SimpleIOAscii"
-
-\end_inset
-
- for the format specification).
-\end_layout
-
-\begin_layout Section
-Defining the Simulation
-\end_layout
-
-\begin_layout Standard
-The parameters for PyLith are specified as a hierarchy or tree of modules.
- The application assembles the hierarchy of modules from user input and
- then calls the 
-\family typewriter
-main
-\family default
- function in the top-level module in the same manner as a C or C++ program.
- The behavior of the application is determined by the modules included in
- the hierarchy as specified by the user.
- The Pyre framework provides the interface for defining this hierarchy.
- Pyre properties correspond to simple settings in the form of strings, integers,
- and real numbers.
- Pyre facilities correspond to software modules.
- Facilities may have their own facilities (branches in the tree) and any
- number of properties.
- See Figure 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "fig:Pyre:Architecture"
-
-\end_inset
-
- for the general concept of Pyre facilities and properties.
- The top-level object is the PyLith application with three facilities: 
-\family typewriter
-mesher
-\family default
-, 
-\family typewriter
-problem
-\family default
-, and 
-\family typewriter
-petsc
-\family default
-.
- The 
-\family typewriter
-mesher
-\family default
- specifies how to import the mesh, the 
-\family typewriter
-problem
-\family default
- specifies the physical properties, boundary conditions, etc., and 
-\family typewriter
-petsc
-\family default
- is used to specify PETSc settings.
- Appendix 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "cha:components"
-
-\end_inset
-
- contains a list of the components provided by PyLith and spatialdata.
-\end_layout
-
-\begin_layout Subsection
-\begin_inset CommandInset label
-LatexCommand label
-name "sec:setting:parameters"
-
-\end_inset
-
-Setting PyLith Parameters
-\end_layout
-
-\begin_layout Standard
-There are several methods for setting input parameters for the 
-\family typewriter
-pylith
-\family default
- executable: via the command line or by using a text file in 
-\family typewriter
-.cfg
-\family default
- or 
-\family typewriter
-.pml
-\family default
- format.
- Both facilities and properties have default values provided, so you only
- need to set values when you want to deviate from the default behavior.
-\end_layout
-
-\begin_layout Subsubsection
-Units
-\end_layout
-
-\begin_layout Standard
-All dimensional parameters require units.
- The units are specified using Python and FORTRAN syntax, so square meters
- is m**2.
- Whitespace is not allowed in the string, for units and dimensioned quantities
- are multiplied by the units string; for example, two meters per second
- is 2.0*m/s.
- Available units are shown in Table 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "tab:pyre:units"
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-\noindent
-\align center
-\begin_inset Float table
-placement H
-wide false
-sideways false
-status open
-
-\begin_layout Plain Layout
-\align center
-\begin_inset Caption
-
-\begin_layout Plain Layout
-\begin_inset CommandInset label
-LatexCommand label
-name "tab:pyre:units"
-
-\end_inset
-
-Pyre supported units.
- Aliases are in parentheses.
-\end_layout
-
-\end_inset
-
-
-\begin_inset Tabular
-<lyxtabular version="3" rows="5" columns="2">
-<features tabularvalignment="middle">
-<column alignment="left" valignment="top" width="0.9in">
-<column alignment="left" valignment="top" width="4in">
-<row>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\series bold
-Scale
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\series bold
-Available Units
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-length
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-meter (m), micrometer (um, micron), millimeter (mm), centimeter (cm), kilometer
- (km), inch, foot, yard, mile
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-time
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-second (s), nanosecond (ns), microsecond (us), millisecond (ms), minute,
- hour, day, year
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-mass
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-kilogram (kg), gram (g), centigram (cg), milligram (mg), ounce, pound, ton
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-pressure
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-pascal (Pa), kPa, MPa, GPa, bar, millibar, atmosphere (atm)
-\end_layout
-
-\end_inset
-</cell>
-</row>
-</lyxtabular>
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Subsubsection
-Using the Command Line
-\end_layout
-
-\begin_layout Standard
-Pyre uses the following syntax to change properties from the command line.
- To change the value of a property of a component, use:
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
---[component].[property]=[value]
-\end_layout
-
-\begin_layout Standard
-Each component is attached to a facility, so the option above can also be
- written as: 
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
---[facility].[property]=[value]
-\end_layout
-
-\begin_layout Standard
-Each facility has a default component attached to it.
- A different component can be attached to a facility by:
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
---[facility]=[new_component] 
-\end_layout
-
-\begin_layout Standard
-PyLith's command-line arguments can control Pyre and PyLith properties and
- facilities, MPI settings, and PETSc settings.
- You can get more information on the available options by typing
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
-$ pylith --help
-\end_layout
-
-\begin_layout Standard
-All PyLith-related properties are associated with the 
-\family typewriter
-pylithapp
-\family default
- component.
- You can get a list of all of these top-level properties along with a descriptio
-n of what they do by running PyLith with the 
-\family typewriter
---help-properties
-\family default
- command-line argument.
- To get information on user-configurable facilities and components, you
- can run PyLith with the 
-\family typewriter
---help-components
-\family default
- command-line argument.
- To find out about the properties associated with a given component, you
- can run PyLith with the 
-\family typewriter
---[component].help-properties
-\family default
- flag:
-\end_layout
-
-\begin_layout LyX-Code
-$ pylith --problem.help-properties
-\end_layout
-
-\begin_layout Standard
-Each component may also have sub-components associated with it:
-\end_layout
-
-\begin_layout LyX-Code
-$ pylith -- problem.help-components
-\end_layout
-
-\begin_layout Standard
-By starting at the top-level components, you can determine the components
- and properties at each level by working down to lower-level components:
-\end_layout
-
-\begin_layout LyX-Code
-$ pylith --problem.bc.help-components
-\end_layout
-
-\begin_layout LyX-Code
-$ pylith --problem.bc.help-properties
-\end_layout
-
-\begin_layout Standard
-Using the 
-\family typewriter
---help-components
-\family default
- and 
-\family typewriter
---help-properties
-\family default
- flags for the various components and sub-components is a good way to discover
- potential problems in a simulation.
-\end_layout
-
-\begin_layout Subsubsection
-Using a 
-\family typewriter
-.cfg
-\family default
- File
-\end_layout
-
-\begin_layout Standard
-Entering all those parameters via the command line involves the risk of
- typographical errors, which can lead to undesired results.
- You will generally find it easier to write a brief 
-\family typewriter
-.cfg
-\family default
- input file that contains the parameters.
- This file has a format similar to a Windows INI file.
- The file is composed of one or more sections which are formatted as follows:
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.subcomponent1.subcomponent2]
-\end_layout
-
-\begin_layout LyX-Code
-# this is a comment
-\end_layout
-
-\begin_layout LyX-Code
-property1 = value1
-\end_layout
-
-\begin_layout LyX-Code
-property2 = value2 ; this is another comment
-\end_layout
-
-\begin_layout Standard
-We strongly recommend that you use 
-\family typewriter
-.cfg
-\family default
- files for your work.
- The files are syntax-colored in the vim editor.
-\end_layout
-
-\begin_layout Subsubsection
-Using a 
-\family typewriter
-.pml
-\family default
- File
-\end_layout
-
-\begin_layout Standard
-A 
-\family typewriter
-.pml
-\family default
- file is an XML file that specifies parameter values in a highly structured
- format.
- It is composed of nested sections which are formatted as follows:
-\end_layout
-
-\begin_layout LyX-Code
-<component name='component1'>
-\end_layout
-
-\begin_layout LyX-Code
-    <component name='component2'>
-\end_layout
-
-\begin_layout LyX-Code
-        <property name='property1'>value1</property>
-\end_layout
-
-\begin_layout LyX-Code
-        <property name='property2'>value2</property>
-\end_layout
-
-\begin_layout LyX-Code
-    </component>
-\end_layout
-
-\begin_layout LyX-Code
-</component>
-\end_layout
-
-\begin_layout Standard
-XML files are intended to be read and written by machines, not edited manually
- by humans.
- The 
-\family typewriter
-.pml
-\family default
- file format is intended for applications in which PyLith input files are
- generated by another program, e.g., a GUI, web application, or a high-level
- structured editor.
- This file format will not be discussed further here, but if you are interested
- in using 
-\family typewriter
-.pml
-\family default
- files, note that 
-\family typewriter
-.pml
-\family default
- files and 
-\family typewriter
-.cfg
-\family default
- files can be used interchangeably; in the following discussion, a file
- with a 
-\family typewriter
-.pml
-\family default
- extension can be substituted anywhere a 
-\family typewriter
-.cfg
-\family default
- file can be used.
-\end_layout
-
-\begin_layout Subsubsection
-Specification and Placement of Configuration Files
-\end_layout
-
-\begin_layout Standard
-Configuration files may be specified on the command line:
-\end_layout
-
-\begin_layout LyX-Code
-$ pylith example.cfg
-\end_layout
-
-\begin_layout Standard
-In addition, the Pyre framework searches for configuration files named 
-\family typewriter
-pylithapp.cfg
-\family default
- in several predefined locations.
- You may put settings in any or all of these locations, depending on the
- scope you want the settings to have:
-\end_layout
-
-\begin_layout Enumerate
-
-\family typewriter
-$PREFIX/etc/pylithapp.cfg
-\family default
-, for system-wide settings;
-\end_layout
-
-\begin_layout Enumerate
-
-\family typewriter
-$HOME/.pyre/pylithapp/pylithapp.cfg
-\family default
-, for user settings and preferences;
-\end_layout
-
-\begin_layout Enumerate
-the current directory (
-\family typewriter
-./pylithapp.cfg
-\family default
-), for local overrides.
- 
-\end_layout
-
-\begin_layout Standard
-Parameters given directly on the command line will override any input contained
- in a configuration file.
- Configuration files given on the command line override all others.
- The 
-\family typewriter
-pylithapp.cfg
-\family default
- files placed in (3) will override those in (2), (2) overrides (1), and
- (1) overrides only the built-in defaults.
-\end_layout
-
-\begin_layout Standard
-All of the example problems are set up using configuration files in the
- example directory, and specific problems are defined by including the appropria
-te configuration file on the command-line.
- Referring to the directory 
-\family typewriter
-examples/twocells/twohex8
-\family default
-, the following configuration files are present:
-\end_layout
-
-\begin_layout LyX-Code
-axialdisp.cfg
-\end_layout
-
-\begin_layout LyX-Code
-dislocation.cfg
-\end_layout
-
-\begin_layout LyX-Code
-pylithapp.cfg
-\end_layout
-
-\begin_layout LyX-Code
-sheardisp.cfg
-\end_layout
-
-\begin_layout Standard
-The settings in pylithapp.cfg will be read automatically, and additional
- settings are included by specifying one of the other files on the command-line:
-\end_layout
-
-\begin_layout LyX-Code
-$ pylith axialdisp.cfg
-\end_layout
-
-\begin_layout Standard
-If you want to see what settings are being used, you can either examine
- the 
-\family typewriter
-.cfg
-\family default
- files, or use the help flags as described above:
-\end_layout
-
-\begin_layout LyX-Code
-$ pylith axialdisp.cfg --problem.help-components
-\end_layout
-
-\begin_layout LyX-Code
-$ pylith axialdisp.cfg --problem.help-properties
-\end_layout
-
-\begin_layout LyX-Code
-$ pylith axialdisp.cfg --problem.bc.help-components
-\end_layout
-
-\begin_layout LyX-Code
-$ pylith axialdisp.cfg --problem.bc.help-properties
-\end_layout
-
-\begin_layout Standard
-This is generally a more useful way of determining problem settings, since
- it includes default values as well as those that have been specified in
- the 
-\family typewriter
-.cfg
-\family default
- file.
-\end_layout
-
-\begin_layout Subsubsection
-List of PyLith Parameters (
-\family typewriter
-pylithinfo
-\family default
-)
-\end_layout
-
-\begin_layout Standard
-The Python application 
-\family typewriter
-pylithinfo
-\family default
- writes all of the current parameters to a text file.
- The default name of the text file is 
-\family typewriter
-pylith_parameters.txt
-\family default
-.
- The usage synopsis is
-\end_layout
-
-\begin_layout LyX-Code
-$ pylithinfo [--verbose] [--fileout=pylith_parameters.txt] [PyLith args]
-\end_layout
-
-\begin_layout Standard
-where 
-\family typewriter
---verbose
-\family default
- (or 
-\family typewriter
--v
-\family default
-) turns on printing the descriptions of the properties and components as
- well as the location where the current value was set, and 
-\family typewriter
---fileout=pylith_parameters.txt
-\family default
- (or 
-\family typewriter
--o pylith_parameters.txt
-\family default
-) sets the name of the output file.
- The lines in the text file are indented to show the hierarchy of the properties
- and components.
- 
-\end_layout
-
-\begin_layout Subsection
-Mesh Information (
-\family typewriter
-mesher
-\family default
-)
-\end_layout
-
-\begin_layout Standard
-Geometrical and topological information for the finite element mesh may
- be provided by exporting an Exodus II format file from CUBIT, by exporting
- a GMV file and an accompanying Pset file from LaGriT, or by specifying
- the information in PyLith mesh ASCII format.
- See Chapter 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "cha:Tutorials"
-
-\end_inset
-
- for examples.
-\end_layout
-
-\begin_layout Standard
-PyLith supports linear cells in 1D (Figure 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "fig:1D-linear-elements"
-
-\end_inset
-
-), 2D (Figure 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "fig:2D-linear-elements"
-
-\end_inset
-
-), and 3D (Figure 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "fig:3D-linear-elements"
-
-\end_inset
-
-).
- The vertex ordering must follow the convention shown in Figures 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "fig:1D-linear-elements"
-
-\end_inset
-
--
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "fig:3D-linear-elements"
-
-\end_inset
-
-.
- Quadratic cells are also supported, but at present the only method for
- using these cells in PyLith is using PyLith ASCII format.
- PyLith does not yet support automatic generation of a quadratic mesh from
- the linear meshes created by CUBIT or LaGriT.
-\end_layout
-
-\begin_layout Standard
-The mesh information defines the vertex coordinates and specifies the vertices
- composing each cell in the mesh.
- The mesh information must also define at least one set of vertices for
- which displacement (Dirichlet) boundary conditions will be provided.
- In most realistic problems, there will be several vertex groups, each with
- a unique identifying label.
- For example, one group might define a surface of the mesh where displacement
- (Dirichlet) boundary conditions will be applied, another might define a
- surface where traction (Neumann) boundary conditions will be applied, while
- a third might specify a surface that defines a fault.
- Similarly, the mesh information contains cell labels that define the material
- type for each cell in the mesh.
- For a mesh with a single material type, there will only be a single label
- for every cell in the mesh.
- See Chapters 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "cha:material:models"
-
-\end_inset
-
- and 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "cha:boundary:interface:conditions"
-
-\end_inset
-
- for more detailed discussions of setting the materials and boundary conditions.
-\end_layout
-
-\begin_layout Standard
-\noindent
-\align center
-\begin_inset Float figure
-placement H
-wide false
-sideways false
-status open
-
-\begin_layout Plain Layout
-\noindent
-\align center
-\begin_inset Graphics
-	filename figs/bar2.eps
-
-\end_inset
-
- 
-\end_layout
-
-\begin_layout Plain Layout
-\begin_inset Caption
-
-\begin_layout Plain Layout
-Linear bar cell available for 1D problems.
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Plain Layout
-\begin_inset CommandInset label
-LatexCommand label
-name "fig:1D-linear-elements"
-
-\end_inset
-
- 
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-\noindent
-\align center
-\begin_inset Float figure
-placement H
-wide false
-sideways false
-status open
-
-\begin_layout Plain Layout
-\noindent
-\align center
-\begin_inset Graphics
-	filename figs/tri3.eps
-
-\end_inset
-
-
-\begin_inset ERT
-status open
-
-\begin_layout Plain Layout
-
-
-\backslash
-hspace*{0.5in}
-\end_layout
-
-\end_inset
-
-
-\begin_inset Graphics
-	filename figs/quad4.eps
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Plain Layout
-\begin_inset Caption
-
-\begin_layout Plain Layout
-Linear cells available for 2D problems are the triangle (left) and the quadrilat
-eral (right).
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Plain Layout
-\begin_inset CommandInset label
-LatexCommand label
-name "fig:2D-linear-elements"
-
-\end_inset
-
- 
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-\noindent
-\align center
-\begin_inset Float figure
-placement H
-wide false
-sideways false
-status open
-
-\begin_layout Plain Layout
-\noindent
-\align center
-\begin_inset Graphics
-	filename figs/tet4.eps
-
-\end_inset
-
-
-\begin_inset ERT
-status open
-
-\begin_layout Plain Layout
-
-
-\backslash
-hspace*{0.5in}
-\end_layout
-
-\end_inset
-
-
-\begin_inset Graphics
-	filename figs/hex8.eps
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Plain Layout
-\begin_inset Caption
-
-\begin_layout Plain Layout
-Linear cells available for 3D problems are the tetrahedron (left) and the
- hexahedron (right).
-\begin_inset CommandInset label
-LatexCommand label
-name "fig:3D-linear-elements"
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Subsubsection
-Mesh Importer
-\end_layout
-
-\begin_layout Standard
-The default mesher component is MeshImporter, which provides the capabilities
- of reading the mesh from files.
- The MeshImporter has several properties and facilities:
-\end_layout
-
-\begin_layout Description
-reorder_mesh Reorder the vertices and cells using the reverse Cuthill-McKee
- algorithm (default is False).
-\end_layout
-
-\begin_layout Description
-reader Reader for a given type of mesh (default is MeshIOAscii).
-\end_layout
-
-\begin_layout Description
-distributor Handles distribution of the mesh among processors.
-\end_layout
-
-\begin_layout Description
-refiner Perform global uniform mesh refinement after distribution among
- processors (default is False).
-\end_layout
-
-\begin_layout Standard
-Reordering the mesh so that vertices and cells connected topologically also
- reside close together in memory improves overall performance and can improve
- solver performance as well.
-\end_layout
-
-\begin_layout Quote
-
-\color red
-Note:
-\color inherit
- The coordinate system associated with the mesh must be a Cartesian coordinate
- system.
- This includes generic Cartesian coordinate systems as well as geographic
- projections.
-\end_layout
-
-\begin_layout Subsubsection
-MeshIOAscii
-\end_layout
-
-\begin_layout Standard
-The MeshIOAscii object is intended for reading small, simple ASCII files
- containing a mesh constructed by hand.
- We use this file format extensively in the examples.
- Appendix 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "sec:MeshIOAscii"
-
-\end_inset
-
- describes the format of the files.
- The properties and facilities of the MeshIOAscii object include:
-\end_layout
-
-\begin_layout Description
-filename Name of the mesh file.
-\end_layout
-
-\begin_layout Description
-coordsys Coordinate system associated with the mesh.
-\end_layout
-
-\begin_layout Subsubsection
-\begin_inset CommandInset label
-LatexCommand label
-name "sec:MeshIOCubit"
-
-\end_inset
-
-MeshIOCubit
-\end_layout
-
-\begin_layout Standard
-The MeshIOCubit object reads the NetCDF Exodus II files output from CUBIT.
- Beginning with CUBIT 11.0, the names of the nodesets are included in the
- Exodus II files and PyLith can use these nodeset names or revert to using
- the nodeset ids.
- The properties and facilities associated with the MeshIOCubit object are:
-\end_layout
-
-\begin_layout Description
-filename Name of the Exodus II file.
-\end_layout
-
-\begin_layout Description
-use_nodeset_names Identify nodesets by name rather than id (default is True).
-\end_layout
-
-\begin_layout Description
-coordsys Coordinate system associated with the mesh.
-\end_layout
-
-\begin_layout Subsubsection
-\begin_inset CommandInset label
-LatexCommand label
-name "sec:MeshIOLagrit"
-
-\end_inset
-
-MeshIOLagrit
-\end_layout
-
-\begin_layout Standard
-The MeshIOLagrit object is used to read ASCII and binary GMV and PSET files
- output from LaGriT.
- PyLith will automatically detect whether the files are ASCII or binary.
- We attempt to provide support for experimental 64-bit versions of LaGriT
- via flags indicating whether the FORTRAN code is using 32-bit or 64-bit
- integers.
- The MeshIOLagrit properties and facilities are:
-\end_layout
-
-\begin_layout Description
-filename_gmv Name of GMV file.
-\end_layout
-
-\begin_layout Description
-filename_pset Name of the PSET file.
-\end_layout
-
-\begin_layout Description
-flip_endian Flip the endian of values when reading binary files (default
- is False).
-\end_layout
-
-\begin_layout Description
-io_int32 Flag indicating that PSET files use 32-bit integers (default is
- True).
-\end_layout
-
-\begin_layout Description
-record_header_32bt Flag indicating FORTRAN record header is 32-bit (default
- is True)
-\end_layout
-
-\begin_layout Description
-coordsys Coordinate system associated with mesh.
-\end_layout
-
-\begin_layout Subsubsection
-Distributor
-\end_layout
-
-\begin_layout Standard
-The distributor users a partitioner to compute which cells should be placed
- on each processor, computes the overlap among the processors, and then
- distributes the mesh among the processors.
- The properties and facilities of the Distributor include:
-\end_layout
-
-\begin_layout Description
-partitioner Choice of partitioner (
-\begin_inset Quotes eld
-\end_inset
-
-parmetis
-\begin_inset Quotes erd
-\end_inset
-
- or 
-\begin_inset Quotes eld
-\end_inset
-
-chaco
-\begin_inset Quotes erd
-\end_inset
-
-, default is 
-\begin_inset Quotes eld
-\end_inset
-
-chaco
-\begin_inset Quotes erd
-\end_inset
-
-).
-\end_layout
-
-\begin_layout Description
-writer_partition Flag indicating that the partition information should be
- written to a file (default is False).
-\end_layout
-
-\begin_layout Description
-data_writer Writer for partition information (default is DataWriterVTKMesh
- for VTK output).
-\end_layout
-
-\begin_layout Standard
-ParMETIS is not included in the PyLith binaries due to licensing issues.
-\end_layout
-
-\begin_layout Subsubsection
-Refiner
-\end_layout
-
-\begin_layout Standard
-The refiner is used to decrease node spacing by a factor of two by subdividing
- each cell.
- In a 2-D triangular mesh a node is inserted at the midpoint of each edge,
- splitting each cell into four cells (see Figure 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "fig:uniform:refinement:2x"
-
-\end_inset
-
-).
- In a 2-D quadrilateral mesh a node is inserted at the midpoint of each
- edge and at the centroid of the cell, splitting each cell into four cells.
- In a 3-D tetrahedral mesh a node is inserted at the midpoint of each edge,
- splitting each cell into eight cells.
- In a 3-D hexahedral mesh a node is inserted at the midpoint of each edge,
- the centroid of each face, and at the centroid of the cell, splitting each
- cell into eight cells.
-\end_layout
-
-\begin_layout Standard
-\noindent
-\align center
-\begin_inset Float figure
-placement H
-wide false
-sideways false
-status open
-
-\begin_layout Plain Layout
-\noindent
-\align center
-\begin_inset Graphics
-	filename figs/refinement2x.eps
-	scale 125
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Plain Layout
-\begin_inset Caption
-
-\begin_layout Plain Layout
-Global uniform mesh refinement of 2-D and 3-D linear cells.
- The blue lines and orange circles identify the edges and vertices in the
- original cells.
- The purple lines and green circles identify the new edges and vertices
- added to the original cells to refine the mesh by a factor of two.
-\begin_inset CommandInset label
-LatexCommand label
-name "fig:uniform:refinement:2x"
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-Refinement occurs after distribution of the mesh among processors.
- This allows one to run much larger simulations by (1) permitting the mesh
- generator to construct a mesh with a node spacing twice as large as that
- needed in the simulation and (2) operations performed in serial during
- the simulation setup phase, such as, adjusting the topology to insert cohesive
- cells and distribution of the mesh among processors uses this much smaller
- coarse mesh.
- For 2-D problems the global mesh refinement increases the maximum problem
- size by a factor of four, and for 3-D problems it increases the maximum
- problem size by a factor of eight.
-\end_layout
-
-\begin_layout Subsection
-Problem Specification (
-\family typewriter
-problem
-\family default
-)
-\end_layout
-
-\begin_layout Standard
-The problem component specifies the basic parameters of the simulation,
- including the physical properties, the boundary conditions, and interface
- conditions (faults).
- The current release of PyLith contains two types of problem, 
-\family typewriter
-TimeDependent
-\family default
- for use in static, quasi-static, and dynamic simulations and 
-\family typewriter
-GreensFns
-\family default
- for computing static Green's functions.
- The general facilities include:
-\end_layout
-
-\begin_layout Description
-normalizer Scales used to nondimensionalize the problem (default is NondimElasti
-cQuasistatic).
-\end_layout
-
-\begin_layout Description
-materials Array of materials comprising the domain (default is 
-\family typewriter
-[material]
-\family default
-).
-\end_layout
-
-\begin_layout Description
-bc Array of boundary conditions (default is none).
-\end_layout
-
-\begin_layout Description
-interfaces Array of interface conditions, i.e., faults (default is none).
-\end_layout
-
-\begin_layout Description
-gravity_field Gravity field used to construct body forces (default is none).
-\end_layout
-
-\begin_layout Standard
-The properties for each material group are:
-\end_layout
-
-\begin_layout Description
-dimension Spatial dimension of the problem (default is 3)
-\end_layout
-
-\begin_layout Standard
-An example of setting these parameters in a 
-\family typewriter
-.cfg
-\family default
- file for a problem is:
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.timedependent]
-\end_layout
-
-\begin_layout LyX-Code
-dimension = 3
-\end_layout
-
-\begin_layout LyX-Code
-normalizer = spatialdata.units.NondimElasticQuasistatic
-\end_layout
-
-\begin_layout LyX-Code
-materials = [elastic,viscoelastic]
-\end_layout
-
-\begin_layout LyX-Code
-bc = [boundary_east,boundary_bottom,boundary_west]
-\end_layout
-
-\begin_layout LyX-Code
-interfaces = [SanAndreas,SanJacinto]
-\end_layout
-
-\begin_layout LyX-Code
-gravity_field = spatialdata.spatialdb.GravityField
-\end_layout
-
-\begin_layout Subsubsection
-Nondimensionalization
-\end_layout
-
-\begin_layout Standard
-PyLith nondimensionalizes all parameters provided by the user so that the
- simulation solves the equations using nondimensional quantities.
- This permits application of PyLith to problems across a vast range of spatial
- and temporal scales.
- The scales used to nondimensionalize the problem are length, pressure,
- density, and time.
- PyLith provides two normalizer objects to make it easy to provide reasonable
- scales for the nondimensionalization.
- The 
-\family typewriter
-NondimElasticQuasistatic
-\family default
- normalizer has the following properties:
-\end_layout
-
-\begin_layout Description
-length_scale Length to nondimensionalize length (default is 1.0 km).
-\end_layout
-
-\begin_layout Description
-shear_modulus Shear modulus to nondimensionalize pressure (default is 3.0e+10
- Pa).
-\end_layout
-
-\begin_layout Description
-relaxation_time Relaxation time to nondimensionalize time (default is 1.0
- year).
-\end_layout
-
-\begin_layout Standard
-An example of setting these parameters in a 
-\family typewriter
-.cfg
-\family default
- file for a problem is:
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.timedependent.normalizer]
-\end_layout
-
-\begin_layout LyX-Code
-length_scale = 1.0*km
-\end_layout
-
-\begin_layout LyX-Code
-shear_modules = 3.0e+10*Pa
-\end_layout
-
-\begin_layout LyX-Code
-relaxation_time = 1.0*yr
-\end_layout
-
-\begin_layout Standard
-The 
-\family typewriter
-NondimElasticDynamic
-\family default
- normalizer has the following properties:
-\end_layout
-
-\begin_layout Description
-shear_wave_speed Shear wave speed used to nondimensionalize length and pressure
- (default is 3.0 km/s).
-\end_layout
-
-\begin_layout Description
-mass_density Mass density to nondimensionalize density and pressure (default
- is 3.0e+3 kg/m
-\begin_inset Formula $^{3}$
-\end_inset
-
-).
-\end_layout
-
-\begin_layout Description
-wave_period Period of seismic waves used to nondimensionalize time (default
- is 1.0 s).
-\end_layout
-
-\begin_layout Standard
-An example of setting these parameters in a 
-\family typewriter
-.cfg
-\family default
- file for a problem is:
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.timedependent.normalizer]
-\end_layout
-
-\begin_layout LyX-Code
-shear_wave_speed = 3.0*km/s
-\end_layout
-
-\begin_layout LyX-Code
-mass_density = 3.0e+3*kg/m**3
-\end_layout
-
-\begin_layout LyX-Code
-wave_period = 1.0*s
-\end_layout
-
-\begin_layout Subsection
-Finite-Element Integration Settings
-\end_layout
-
-\begin_layout Standard
-PyLith uses numerical quadrature to evaluate the finite-element integrals
- for the residual and system Jacobian (see Chapter 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "cha:Governing-Equations"
-
-\end_inset
-
-).
- PyLith employs FIAT (finite element automatic tabulator) to compute the
- basis functions and their derivatives at the quadrature points for various
- quadrature schemes and cell shapes.
- The parameters for Lagrange cells (lines, quadrilaterals, hexahedra) are
- specified using the FIATLagrange object, whereas the parameters for Simplex
- cells (lines, triangles, tetrahedra) are specified using the FIATSimplex
- object.
- Both objects use the same set of parameters and PyLith will setup the basis
- functions and quadrature scheme appropriately for the two families of cells.
- The quadrature scheme and basis functions must be set for each material
- and boundary condition involving finite-element integrations (Dirichlet
- boundary conditions are constraints and do not involve integrations).
- Furthermore, the integration schemes can be set independently.
- The current version of PyLith supports basis functions with linear variations
- in the field (P1); support for higher order cells will be added in the
- future.
- The properties for the FIATLagrange and FIATSimplex objects are
-\end_layout
-
-\begin_layout Description
-dimension Dimension of the cell (0,1,2,3; default is 3).
-\end_layout
-
-\begin_layout Description
-degree Degree of the finite-element cell (default is 1).
-\end_layout
-
-\begin_layout Description
-order Order of quadrature rule (default is degree+1); hardwired to be equal
- to degree for faults.
-\end_layout
-
-\begin_layout Description
-collocate_quad Collocate quadrature points with vertices (default is False);
- hardwired to True for faults.
-\end_layout
-
-\begin_layout Standard
-See Section 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "sec:material:parameters"
-
-\end_inset
-
- for an example of setting these properties for a material.
-\end_layout
-
-\begin_layout Subsection
-\begin_inset CommandInset label
-LatexCommand label
-name "sec:petsc:options"
-
-\end_inset
-
-PETSc Settings (
-\family typewriter
-petsc
-\family default
-)
-\end_layout
-
-\begin_layout Standard
-In quasti-static problems with implicit time-stepping, PyLith relies on
- PETSc for the linear algebra computations, including linear Krylov subspace
- solvers and nonlinear solvers.
- For dynamic problems, lumping the mass matrix and using explicit time-stepping
- is much more efficient; this permits solving the linear system with a trivial
- solver so we do not use a PETSc solver in this case (see Section 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "sec:solvers"
-
-\end_inset
-
-).
-\end_layout
-
-\begin_layout Standard
-PETSc options can be set in 
-\family typewriter
-.cfg
-\family default
- files in sections beginning with 
-\family typewriter
-[pylithapp.petsc]
-\family default
-.
- The options of primary interest in the case of PyLith are shown in Table
-\begin_inset space ~
-\end_inset
-
-
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "tab:petsc:options:defaults"
-
-\end_inset
-
-.
- PETSc options are used to control the selection and settings for the solvers
- underlying the SolverLinear and SolverNonlinear objects discussed in Section
- 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "sec:solvers"
-
-\end_inset
-
-.
- A very wide range of elasticity problems in quasi-static simulations can
- be solved with reasonable runtimes by replacing the default Jacobi precondition
-er with the Additive Schwarz Method (ASM) using Incomplete LU (ILU) factorizatio
-n by default (see Table
-\begin_inset space ~
-\end_inset
-
-
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "tab:petsc:options:recommended"
-
-\end_inset
-
-).
- A more advanced set of solver settings that may provide better performance
- in many elasticity problems are given in Table 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "tab:petsc:options:advanced"
-
-\end_inset
-
-.
- These settings are limited to problems where we store the stiffness matrix
- as a nonsymmetric sparse matrix and require additional settings for the
- formulation,
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.timedependent.formulation]
-\end_layout
-
-\begin_layout LyX-Code
-split_fields = True
-\end_layout
-
-\begin_layout LyX-Code
-use_custom_constraint_pc = True ; Use only if problem contains a fault
-\end_layout
-
-\begin_layout LyX-Code
-matrix_type = aij
-\end_layout
-
-\begin_layout Quote
-
-\series bold
-\color red
-Warning:
-\color inherit
- 
-\series default
-\color none
-These settings are only available if you build PETSc with Fortran enabled
- and the ML package.
- These features are included in the PyLith binary packages.
-\end_layout
-
-\begin_layout Quote
-
-\series bold
-\color red
-Warning:
-\color inherit
- 
-\series default
-\color none
-The split fields and algebraic multigrid preconditioning currently fails
- in problems with a nonzero null space.
- This most often occurs when a problem contains multiple faults that extend
- through the entire domain and create subdomains without any Dirichlet boundary
- conditions.
- The current workaround is to use the 
-\color inherit
-Additive Schwarz 
-\color none
-preconditioner without split fields.
- See Section 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "sec:Troubleshooting"
-
-\end_inset
-
- for the error message encountered in this situation.
- 
-\end_layout
-
-\begin_layout Standard
-These more advanced settings allow the displacement fields and Lagrange
- multipliers for fault tractions to be preconditioned separately.
- This usually results in a much stronger preconditioner.
- In simulations with fault slip, the degrees of freedom associated with
- the Lagrange multipliers should be preconditioned with a custom preconditioner
- that uses a diagonal approximation of the Schur complement.
-\end_layout
-
-\begin_layout Standard
-\noindent
-\align center
-\begin_inset Float table
-placement H
-wide false
-sideways false
-status open
-
-\begin_layout Plain Layout
-\align center
-\begin_inset Caption
-
-\begin_layout Plain Layout
-\begin_inset CommandInset label
-LatexCommand label
-name "tab:petsc:options:defaults"
-
-\end_inset
-
-Useful command-line arguments for setting PETSc options.
-\end_layout
-
-\end_inset
-
-
-\begin_inset Tabular
-<lyxtabular version="3" rows="10" columns="3">
-<features tabularvalignment="middle">
-<column alignment="left" valignment="top" width="1.2in">
-<column alignment="center" valignment="middle" width="0.6in">
-<column alignment="left" valignment="top" width="3.8in">
-<row>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\series bold
-Property
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\series bold
-Default Value
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\series bold
-Description
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-log_summary
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\shape italic
-false
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Print logging objects and events.
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-ksp_monitor
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\shape italic
-false
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Dump preconditioned residual norm to stdout.
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-ksp_view
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\shape italic
-false
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Print linear solver parameters.
- 
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-ksp_rtol
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\shape italic
-1.0e-05
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Convergence tolerance for relative decrease in residual norm.
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-snes_monitor
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\shape italic
-false
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Dump residual norm to stdout for each nonlinear solve iteration.
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-snes_view
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\shape italic
-false
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Print nonlinear solver parameters.
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-snes_rtol
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\shape italic
-1.0e-5
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Convergence tolerance for relative decrease in residual norm.
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-pc_type
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\shape italic
-jacobi
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Set preconditioner type.
- See 
-\begin_inset CommandInset href
-LatexCommand href
-name "PETSc documentation"
-target "http://www.mcs.anl.gov/petsc/petsc-as/documentation/linearsolvertable.html"
-
-\end_inset
-
- for a list of all preconditioner types.
- 
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-ksp_type
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\shape italic
-gmres
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Set linear solver type.
- See 
-\begin_inset CommandInset href
-LatexCommand href
-name "PETSc documentation"
-target "http://www.mcs.anl.gov/petsc/petsc-as/documentation/linearsolvertable.html"
-
-\end_inset
-
- for a list of all solver types.
-\end_layout
-
-\end_inset
-</cell>
-</row>
-</lyxtabular>
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\begin_inset Float table
-placement H
-wide false
-sideways false
-status open
-
-\begin_layout Plain Layout
-\align center
-\begin_inset Caption
-
-\begin_layout Plain Layout
-\begin_inset CommandInset label
-LatexCommand label
-name "tab:petsc:options:recommended"
-
-\end_inset
-
-PETSc options that provide moderate performance in a wide range of quasi-static
- elasticity problems.
-\end_layout
-
-\end_inset
-
-
-\begin_inset Tabular
-<lyxtabular version="3" rows="13" columns="3">
-<features tabularvalignment="middle">
-<column alignment="left" valignment="top" width="2in">
-<column alignment="center" valignment="middle" width="0.75in">
-<column alignment="left" valignment="top" width="3in">
-<row>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\series bold
-Property
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\series bold
-Value
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\series bold
-Description
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-pc_type
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\shape italic
-asm
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Additive Schwarz method.
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-ksp_type
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\shape italic
-gmres
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-GMRES method from Saad and Schultz.
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-sub_pc_factor_shift_type
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\emph on
-nonzero
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Turn on nonzero shifting for factorization.
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-ksp_max_it
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\emph on
-100
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Maximum number of iterations permitted in linear solve.
- Depends on problem size.
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-ksp_gmres_restart
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\shape italic
-50
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Number of iterations after which Gram-Schmidt orthogonalization is restarted.
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-ksp_rtol
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\shape italic
-1.0e-08
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Linear solve convergence tolerance for relative decrease in residual norm.
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-ksp_atol
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\shape italic
-\emph on
-1.0e-12
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Linear solve convergence tolerance for absolute value of residual norm.
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-ksp_converged_reason
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\shape italic
-true
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Indicate why iterating stopped in linear solve.
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-snes_max_it
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\shape italic
-100
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Maximum number of iterations permitted in nonlinear solve.
- Depends on how nonlinear the problem is.
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-snes_rtol
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\shape italic
-1.0e-08
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Nonlinear solve convergence tolerance for relative decrease in residual
- norm.
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-snes_atol
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\shape italic
-1.0e-12
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Nonlinear solve convergence tolerance for absolute value of residual norm.
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-snes_converged_reason
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\shape italic
-true
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Indicate why iterating stopped in nonlinear solve.
-\end_layout
-
-\end_inset
-</cell>
-</row>
-</lyxtabular>
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-\noindent
-\align center
-\begin_inset Float table
-placement H
-wide false
-sideways false
-status open
-
-\begin_layout Plain Layout
-\align center
-\begin_inset Caption
-
-\begin_layout Plain Layout
-\begin_inset CommandInset label
-LatexCommand label
-name "tab:petsc:options:advanced"
-
-\end_inset
-
-PETSc options used with split fields algebraic multigrid preconditioning
- that often provide improved performance in quasi-static elasticity problems.
-\end_layout
-
-\end_inset
-
-
-\begin_inset Tabular
-<lyxtabular version="3" rows="8" columns="3">
-<features tabularvalignment="middle">
-<column alignment="left" valignment="top" width="2.25in">
-<column alignment="center" valignment="middle" width="0.75in">
-<column alignment="left" valignment="top" width="3in">
-<row>
-<cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\series bold
-Property
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\series bold
-Value
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\series bold
-Description
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-fs_pc_type
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\shape italic
-field_split
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Precondition fields separately.
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-fs_pc_fieldsplit_real_diagonal
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\shape italic
-true
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Use diagonal blocks from the true operator, rather than the preconditioner.
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-fs_pc_fieldsplit_type
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\shape italic
-multiplicative
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Apply each field preconditioning in sequence, which is stronger than all-at-once
- (additive).
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-fs_fieldsplit_0_pc_type
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\shape italic
-ml
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Multilevel algebraic multigrid preconditioning using Trilinos/ML via PETSc.
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-fs_fieldsplit_1_pc_type
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\shape italic
-jacobi
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Jacobi preconditioning for Lagrange multiplier block (only use if there
- is at least one fault)
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-fs_fieldsplit_0_ksp_type
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\shape italic
-preonly
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Apply only the preconditioner.
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-fs_fieldsplit_1_ksp_type
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\shape italic
-preonly
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Apply only the preconditioner.
-\end_layout
-
-\end_inset
-</cell>
-</row>
-</lyxtabular>
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Subsubsection
-PETSc Solvers and nVidia GPUs
-\end_layout
-
-\begin_layout Standard
-The development version of PETSc contains some support for using PETSc solvers
- and nVidia GPUs via CUDA.
- Building PETSc requires some additional dependencies as described in 
-\begin_inset Flex URL
-status collapsed
-
-\begin_layout Plain Layout
-
-http://www.mcs.anl.gov/petsc/documentation/installation.html#CUDA
-\end_layout
-
-\end_inset
-
-.
- Additionally, PyLith must be configured with the 
-\family typewriter
---enable-cuda
-\family default
- option.
- See the PyLith Installer documentation for how to enable support for CUDA
- when building PETSc and PyLith with the installer (the installer does not
- install CUDA or cusp).
-\end_layout
-
-\begin_layout Quote
-
-\series bold
-\color red
-Warning:
-\color inherit
- 
-\series default
-\color none
-Development of PETSc solvers leveraging nVidia GPUs to accelerate the computatio
-ns is still a work in progress.
- This feature requires building PETSc and PyLith from source after installing
- CUDA and the development version of cusp.
- If your GPU only supports single-precision floating point operations, then
- PETSc must be built with single precision and without support for ML and
- ParMetis/Metis.
-\end_layout
-
-\begin_layout Standard
-Solver and preconditioning options are relatively limited when using CUDA.
- CUDA works with the Additive Schwarz preconditioner and GMRES linear solver.
- Enabling use of CUDA with the PETSc solver involves just one setting:
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.problem.formulation.solver]
-\begin_inset Newline newline
-\end_inset
-
-use_cuda = True
-\end_layout
-
-\begin_layout Standard
-If the matrix type and vector types have not already been set, this will
- set matrix type and vector types to 
-\family typewriter
-aijcusp
-\family default
- and 
-\family typewriter
-cusp
-\family default
-, respectively, to indicate to PETSc that CUDA should be used by the solver.
- If they have already been set to a value, then the values will not be changed
- even if they are incompatible with using CUDA.
-\end_layout
-
-\begin_layout Section
-Time-Dependent Problem
-\end_layout
-
-\begin_layout Standard
-This type of problem applies to transient static, quasi-static, and dynamic
- simulations.
- The time-dependent problem adds the 
-\family typewriter
-formulation
-\family default
- facility to the general-problem.
- The formulation specifies the time-stepping formulation to integrate the
- elasticity equation.
- PyLith provides several alternative formulations, each specific to a different
- type of problem.
-\end_layout
-
-\begin_layout Description
-Implicit Implicit time stepping for static and quasi-static problems with
- infinitesimal strains.
- The implicit formulation neglects inertial terms (see Section 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "eq:elasticity:integral:quasistatic"
-
-\end_inset
-
-).
- 
-\end_layout
-
-\begin_layout Description
-ImplicitLgDeform Implicit time stepping for static and quasi-static problems
- including the effects of rigid body motion and small strains.
- This formulation requires the use of the nonlinear solver, which is selected
- automatically.
-\end_layout
-
-\begin_layout Description
-Explicit Explicit time stepping for dynamic problems with infinitesimal
- strains.
- This formulation uses consistent mass and damping matrices for the system
- Jacobian matrix.
-\end_layout
-
-\begin_layout Description
-ExplicitLgDeform Explicit time stepping for dynamic problems including the
- effects of rigid body motion and small strains.
- This formulation requires the use of the nonlinear solver, which is selected
- automatically.
-\end_layout
-
-\begin_layout Description
-ExplicitLumped Explicit time stepping for dynamic problems with infinitesimal
- strains and lumped system Jacobian.
- The cell matrices are lumped before assembly, permitting use of a vector
- for the diagonal system Jacobian matrix.
- The built-in lumped solver is selected automatically.
-\end_layout
-
-\begin_layout Description
-ExplicitLumpedTri3 Optimized elasticity formulation for linear triangular
- cells with one point quadrature for dynamic problems with infinitesimal
- strains and lumped system Jacobian.
- The built-in lumped solver is selected automatically.
-\end_layout
-
-\begin_layout Description
-ExplicitLumpedTet4 Optimized elasticity formulation for linear tetrahedral
- cells with one point quadrature for dynamic problems with infinitesimal
- strains and lumped system Jacobian.The built-in lumped solver is selected
- automatically.
-\end_layout
-
-\begin_layout Standard
-In many quasi-static simulations it is convenient to compute a static problem
- with elastic deformation prior to computing a transient response.
- Up through PyLith version 1.6 this was hardwired into the Implicit Forumulation
- as advancing from time step 
-\begin_inset Formula $t=-\Delta t$
-\end_inset
-
- to 
-\begin_inset Formula $t=0$
-\end_inset
-
-, and it could not be turned off.
- PyLith now includes a property, 
-\family typewriter
-elastic_prestep
-\family default
- in the TimeDependent component to turn on/off this behavior (the default
- is to retain the previous behavior of computing the elastic deformation).
- 
-\end_layout
-
-\begin_layout Quote
-
-\series bold
-\color red
-Warning:
-\color inherit
- 
-\series default
-\color none
-Turning off the elastic prestep calculation means the model only deforms
- when an 
-\family typewriter
-\shape italic
-\color inherit
-increment
-\family default
-\shape default
-\color none
- in loading or deformation is applied, because we the time-stepping formulation
- is implemented using the increment in displacement.
-\end_layout
-
-\begin_layout Standard
-The TimeDependent properties and facilities include
-\end_layout
-
-\begin_layout Description
-elastic_preset If true, perform a static calculation with elastic behavior
- before time stepping (default is True).
-\end_layout
-
-\begin_layout Description
-formulation Formulation for solving the partial differential equation.
-\end_layout
-
-\begin_layout Standard
-An example of setting the properties and components in a .cfg file is
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.timedependent]
-\end_layout
-
-\begin_layout LyX-Code
-formulation = pylith.problems.Implicit ; default
-\end_layout
-
-\begin_layout LyX-Code
-elastic_preset = True ; default
-\end_layout
-
-\begin_layout Standard
-The formulation value can be set to the other formulations in a similar
- fashion.
- 
-\end_layout
-
-\begin_layout Subsection
-Time-Stepping Formulation
-\end_layout
-
-\begin_layout Standard
-The explicit and implicit time stepping formulations use a common set of
- facilities and properties.
- The facilities include
-\end_layout
-
-\begin_layout Description
-time_step Time step size specification (default is uniform time step).
-\end_layout
-
-\begin_layout Description
-solver Type of solver to use (default is SolverLinear).
-\end_layout
-
-\begin_layout Description
-output Array of output managers for output of the solution (default is [output]).
-\end_layout
-
-\begin_layout Description
-jacobian_viewer Viewer to dump the system Jacobian (sparse matrix) to a
- file for analysis (default is PETSc binary).
-\end_layout
-
-\begin_layout Standard
-The formulation properties include
-\end_layout
-
-\begin_layout Description
-matrix_type Type of PETSc matrix for the system Jacobian (sparse matrix,
- default is symmetric, block matrix with a block size of 1).
-\end_layout
-
-\begin_layout Description
-view_jacobian Flag to indicate if system Jacobian (sparse matrix) should
- be written to a file (default is false).
-\end_layout
-
-\begin_layout Description
-split_fields Split solution field into a displacement portion (fields 0..ndim-1)
- and a Lagrange multiplier portion (field ndim) to permit application of
- sophisticated PETSc preconditioners (default is false).
-\end_layout
-
-\begin_layout Standard
-An example of setting these parameters in a 
-\family typewriter
-.cfg
-\family default
- file is
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.timedependent.formulation]
-\end_layout
-
-\begin_layout LyX-Code
-time_step = pylith.problems.TimeStepUniform
-\end_layout
-
-\begin_layout LyX-Code
-solver = pylith.problems.SolverLinear ; Nonlinear solver is pylith.problems.SolverNo
-nlinear
-\end_layout
-
-\begin_layout LyX-Code
-output = [domain,ground_surface]
-\end_layout
-
-\begin_layout LyX-Code
-matrix_type = sbaij ; To use a non-symmetric sparse matrix, set it to aij
-\end_layout
-
-\begin_layout LyX-Code
-view_jacobian = false
-\end_layout
-
-\begin_layout Subsection
-Numerical Damping in Explicit Time Stepping
-\end_layout
-
-\begin_layout Standard
-In explicit time-stepping formulations for elasticity, boundary conditions
- and fault slip can excite short waveform elastic waves that are not accurately
- resolved by the discretization.
- We use numerical damping via an artificial viscosity
-\begin_inset CommandInset citation
-LatexCommand cite
-key "Knopoff:Ni:2001,Day:Ely:2002"
-
-\end_inset
-
- to reduce these high frequency oscillations.
- In computing the strains for the elasticity term in equation 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "eq:elasticity:integral:dynamic:t"
-
-\end_inset
-
-, we use an adjusted displacement rather than the actual displacement, where
- 
-\begin_inset Formula 
-\begin{equation}
-\vec{u}^{adj}(t)=\vec{u}(t)+\eta^{*}\Delta t\vec{\dot{u}}(t),
-\end{equation}
-
-\end_inset
-
-
-\begin_inset Formula $\vec{u}^{adj}(t)$
-\end_inset
-
- is the adjusted displacement at time t, 
-\begin_inset Formula $\vec{u}(t)$
-\end_inset
-
-is the original displacement at time (t), 
-\begin_inset Formula $\eta^{*}$
-\end_inset
-
-is the normalized artificial viscosity, 
-\begin_inset Formula $\Delta t$
-\end_inset
-
- is the time step, and 
-\begin_inset Formula $\vec{\dot{u}}(t)$
-\end_inset
-
- is the velocity at time 
-\begin_inset Formula $t$
-\end_inset
-
-.
- The default value for the normalized artificial viscosity is 0.1.
- We have found values in the range 0.1-0.4 sufficiently suppress numerical
- noise while not excessively reducing the peak velocity.
- An example of setting the normalized artificial viscosity in a 
-\family typewriter
-.cfg
-\family default
- file is
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.timedependent.formulation]
-\end_layout
-
-\begin_layout LyX-Code
-norm_viscosity = 0.2
-\end_layout
-
-\begin_layout Subsection
-\begin_inset CommandInset label
-LatexCommand label
-name "sec:solvers"
-
-\end_inset
-
-Solvers
-\end_layout
-
-\begin_layout Standard
-PyLith supports three types of solvers.
- The linear solver, SolverLinear, corresponds to the PETSc KSP solver and
- is used in linear problems with linear elastic and viscoelastic bulk constituti
-ve models and kinematic fault ruptures.
- The nonlinear solver, SolverNonlinear, corresponds to the PETSc SNES solver
- and is used in nonlinear problems with nonlinear viscoelastic or elastoplastic
- bulk constitutive models, dynamic fault ruptures, or problems involving
- finite strain (small strain formulation).
- The lumped solver (SolverLumped) is a specialized solver used with the
- lumped system Jacobian matrix.
- The options for the PETSc KSP and SNES solvers are set via the top-level
- PETSc options (see Section 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "sec:petsc:options"
-
-\end_inset
-
- and the PETSc documentation 
-\begin_inset Flex URL
-status collapsed
-
-\begin_layout Plain Layout
-
-www.mcs.anl.gov/petsc/petsc-as/documentation/index.html
-\end_layout
-
-\end_inset
-
-).
-\end_layout
-
-\begin_layout Subsection
-Time Stepping
-\end_layout
-
-\begin_layout Standard
-PyLith provides three choices for controlling the time step in time-dependent
- simulations.
- These include (1) a uniform, user-specified time step (which is the default),
- (2) nonuniform, user-specified time steps, and (3) nonuniform, automatically
- calculated time steps.
- The procedure for automatically selecting time steps requires that the
- material models provide a reasonable estimate of the time step for stable
- time integration.
- In general, quasi-static simulations should use automatically calculated
- time steps and dynamic simulations should use a uniform, user-specified
- time step.
-\end_layout
-
-\begin_layout Standard
-
-\series bold
-\color red
-Warning:
-\series default
-\color none
- 
-\color inherit
-Changing the time step requires recomputing the Jacobian of the system,
- which can greatly increase the runtime if the time-step size changes frequently.
-\end_layout
-
-\begin_layout Subsubsection
-Uniform, User-Specified Time Step
-\end_layout
-
-\begin_layout Standard
-With a uniform, user-specified time step, the user selects the time step
- that is used over the entire duration of the simulation.
- This value is used whether or not it yields a stable solution, so users
- should be careful when selecting the time-step value.
- The properties for the uniform, user-specified time step are:
-\end_layout
-
-\begin_layout Description
-total_time Time duration for simulation (default is 0.0 s).
-\end_layout
-
-\begin_layout Description
-start_time Start time for simulation (default is 0.0 s)
-\end_layout
-
-\begin_layout Description
-dt Time step for simulation.
-\end_layout
-
-\begin_layout Standard
-An example of setting a uniform, user-specified time step in a 
-\family typewriter
-.cfg
-\family default
- file is:
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.problem.formulation]
-\end_layout
-
-\begin_layout LyX-Code
-time_step = pylith.problems.TimeStepUniform ; Default value
-\end_layout
-
-\begin_layout LyX-Code
-
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.problem.formulation.time_step]
-\end_layout
-
-\begin_layout LyX-Code
-total_time = 1000.0*year
-\end_layout
-
-\begin_layout LyX-Code
-dt = 0.5*year
-\end_layout
-
-\begin_layout Subsubsection
-Nonuniform, User-Specified Time Step
-\end_layout
-
-\begin_layout Standard
-The nonuniform, user-specified, time-step implementation allows the user
- to specify the time steps in an ASCII file (see Section 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "sec:FileFormat:TimeStepUser"
-
-\end_inset
-
- for the format specification of the time-step file).
- If the total duration exceeds the time associated with the time steps,
- then a flag determines whether to cycle through the time steps or to use
- the last specified time step for the time remaining.
- The properties for the nonuniform, user-specified time step are:
-\end_layout
-
-\begin_layout Description
-total_time Time duration for simulation.
-\end_layout
-
-\begin_layout Description
-filename Name of file with time-step sizes.
-\end_layout
-
-\begin_layout Description
-loop_steps If true, cycle through time steps, otherwise keep using last
- time-step size for any time remaining.
-\end_layout
-
-\begin_layout Standard
-An example of setting the properties for nonuniform, user-specified time
- steps in a 
-\family typewriter
-.cfg
-\family default
- file is:
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.problem.formulation]
-\end_layout
-
-\begin_layout LyX-Code
-time_step = pylith.problems.TimeStepUser ; Change the time step algorithm
-\end_layout
-
-\begin_layout LyX-Code
-
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.problem.formulation.time_step]
-\end_layout
-
-\begin_layout LyX-Code
-total_time = 1000.0*year
-\end_layout
-
-\begin_layout LyX-Code
-filename = timesteps.txt
-\end_layout
-
-\begin_layout LyX-Code
-loop_steps = false ; Default value
-\end_layout
-
-\begin_layout Subsubsection
-Nonuniform, Automatic Time Step
-\end_layout
-
-\begin_layout Standard
-This time-step implementation automatically calculates a stable time step
- based on the constitutive model and rate of deformation.
- As a result, this choice for choosing the time step relies on accurate
- calculation of a stable time step within each finite-element cell by the
- constitutive models.
- In order to provide some control over the time-step selection, the user
- can control the frequency that a new time step is calculated, the time
- step to use relative to the value determined by the constitutive models,
- and a maximum value for the time step.
- The properties for controlling the automatic time-step selection are:
-\end_layout
-
-\begin_layout Description
-total_time Time duration for simulation.
-\end_layout
-
-\begin_layout Description
-max_dt Maximum time step permitted.
-\end_layout
-
-\begin_layout Description
-adapt_skip Number of time steps to skip between calculating new stable time
- step.
-\end_layout
-
-\begin_layout Description
-stability_factor Safety factor for stable time step (default is 2.0).
-\end_layout
-
-\begin_layout Standard
-An example of setting the properties for the automatic time step in a 
-\family typewriter
-.cfg
-\family default
- file is:
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.problem.formulation]
-\end_layout
-
-\begin_layout LyX-Code
-time_step = pylith.problems.TimeStepAdapt ; Change the time step algorithm
-\end_layout
-
-\begin_layout LyX-Code
-
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.problem.formulation.time_step]
-\end_layout
-
-\begin_layout LyX-Code
-total_time = 1000.0*year
-\end_layout
-
-\begin_layout LyX-Code
-max_dt = 10.0*year
-\end_layout
-
-\begin_layout LyX-Code
-adapt_skip = 10 ; Default value
-\end_layout
-
-\begin_layout LyX-Code
-stability_factor = 2.0 ; Default value
-\end_layout
-
-\begin_layout Section
-Green's Functions Problem
-\end_layout
-
-\begin_layout Standard
-This type of problem applies to computing static Green's functions for elastic
- deformation.
- The 
-\family typewriter
-GreensFns
-\family default
- problem specializes the time-dependent facility to the case of static simulatio
-ns with slip impulses on a fault.
- The default formulation is the Implicit formulation and should not be changed
- as the other formulations are not applicable to static Green's functions.
- In the output files, the deformation at each 
-\begin_inset Quotes eld
-\end_inset
-
-time step
-\begin_inset Quotes erd
-\end_inset
-
- is the deformation for a different slip impulse.
- The properties provide the ability to select which fault to use for slip
- impulses.
- The only fault component available for use with the 
-\family typewriter
-GreensFns
-\family default
- problem is the 
-\family typewriter
-FaultCohesiveImpulses
-\family default
- component discussed in Section 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "sec:fault:cohesive:impulses"
-
-\end_inset
-
-.
- The 
-\family typewriter
-GreensFns
-\family default
- properties include:
-\end_layout
-
-\begin_layout Description
-fault_id Id of fault on which to impose slip impulses.
-\end_layout
-
-\begin_layout Standard
-An example of setting the properties for the GreensFns problem in a 
-\family typewriter
-.cfg
-\family default
- file is:
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp]
-\end_layout
-
-\begin_layout LyX-Code
-problem = pylith.problems.GreensFns ; Change problem type from the default
-\end_layout
-
-\begin_layout LyX-Code
-
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.greensfns]
-\end_layout
-
-\begin_layout LyX-Code
-fault_id = 100 ; Default value
-\end_layout
-
-\begin_layout Standard
-
-\series bold
-\color red
-Warning:
-\series default
-\color none
- 
-\color inherit
-The 
-\family typewriter
-GreensFns
-\family default
- problem generates slip impulses on a fault.
- The current version of PyLith requires that impulses can only be applied
- to a single fault and the fault facility must be set to 
-\family typewriter
-FaultCohesiveImpulses
-\family default
-.
-\end_layout
-
-\begin_layout Section
-\begin_inset CommandInset label
-LatexCommand label
-name "sec:spatial:databases"
-
-\end_inset
-
-Databases for Boundaries, Interfaces, and Material Properties
-\end_layout
-
-\begin_layout Standard
-Once the problem has been defined with PyLith parameters, and the mesh informati
-on has been provided, the final step is to specify the boundary conditions
- and material properties to be used.
- The mesh information provides labels defining sets of vertices to which
- boundary conditions or fault conditions will be applied, as well as cell
- labels that will be used to define the material type of each cell.
- For boundary conditions, the 
-\family typewriter
-.cfg
-\family default
- file is used to associate boundary condition types and spatial databases
- with each vertex group (see Chapter 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "cha:boundary:interface:conditions"
-
-\end_inset
-
-).
- For materials, the 
-\family typewriter
-.cfg
-\family default
- file is used to associate material types and spatial databases with cells
- identified by the material identifier (see Figure 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "fig:Material-models"
-
-\end_inset
-
-).
-\end_layout
-
-\begin_layout Standard
-The spatial databases define how the boundary conditions or material property
- values vary spatially, and they can be arbitrarily complex.
- The simplest example for a material database would be a mesh where all
- the cells of a given type have uniform properties (
-\begin_inset Quotes eld
-\end_inset
-
-point
-\begin_inset Quotes erd
-\end_inset
-
- or 0D variation).
- A slightly more complex case would be a mesh where the cells of a given
- type have properties that vary linearly along a given direction (
-\begin_inset Quotes eld
-\end_inset
-
-line
-\begin_inset Quotes erd
-\end_inset
-
- or 1D variation).
- In more complex models, the material properties might have different values
- at each point in the mesh (
-\begin_inset Quotes eld
-\end_inset
-
-volume
-\begin_inset Quotes erd
-\end_inset
-
- or 3D variation).
- This might be the case, for example, if the material properties are provided
- by a database of seismic velocities and densities.
- For boundary conditions the simplest case would be where all vertices in
- a given group have the same boundary condition parameters (
-\begin_inset Quotes eld
-\end_inset
-
-point
-\begin_inset Quotes erd
-\end_inset
-
- or 0D variation).
- A more complex case might specify a variation in the conditions on a given
- surface (
-\begin_inset Quotes eld
-\end_inset
-
-area
-\begin_inset Quotes erd
-\end_inset
-
- or 2D variation).
- This sort of condition might be used, for example, to specify the variation
- of slip on a fault plane.
- The examples discussed in Chapter 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "cha:Tutorials"
-
-\end_inset
-
- also contain more information regarding the specification and use of the
- spatial database files.
-\end_layout
-
-\begin_layout Subsection
-SimpleDB Spatial Database
-\end_layout
-
-\begin_layout Standard
-In most cases the default type of spatial database for faults, boundary
- conditions, and materials is 
-\family typewriter
-SimpleDB
-\family default
-.
- Spatial database files provide specification of a field over some set of
- points.
- There is no topology associated with the points.
- Although multiple values can be specified at each point with more than
- one value included in a search query, the interpolation of each value will
- be done independently.
- Time dependent variations of a field are not supported in these files.
- Spatial database files can specify spatial variations over zero, one, two,
- and three dimensions.
- Zero dimensional variations correspond to uniform values.
- One-dimensional spatial variations correspond to piecewise linear variations,
- which need not coincide with coordinate axes.
- Likewise, two-dimensional spatial variations correspond to variations on
- a planar surface (which need not coincide with the coordinate axes) and
- three-dimensional spatial variations correspond to variations over a volume.
- In one, two, or three dimensions, queries can use a 
-\begin_inset Quotes eld
-\end_inset
-
-nearest value
-\begin_inset Quotes erd
-\end_inset
-
- search or linear interpolation.
-\end_layout
-
-\begin_layout Standard
-The spatial database files need not provide the data using the same coordinate
- system as the mesh coordinate system, provided the two coordinate systems
- are compatible.
- Examples of compatible coordinate systems include geographic coordinates
- (longitude/latitude/elevation), and projected coordinates (e.g., coordinates
- in a transverse Mercator projection).
- Spatial database queries use the Proj.4 Cartographic Projections library
- 
-\begin_inset Flex URL
-status collapsed
-
-\begin_layout Plain Layout
-
-proj.maptools.org
-\end_layout
-
-\end_inset
-
- to convert between coordinate systems, so a large number of geographic
- projections are available with support for converting between NAD27 and
- WGS84 horizontal datums as well as several other frequently used datums.
- Because the interpolation is done in the coordinate system of the spatial
- database, geographic coordinates should only be used for very simple datasets,
- or undesirable results will occur.
- This is especially true when the spatial database coordinate system combines
- latitude, longitude, and elevation in meters (longitude and latitude in
- degrees are often much smaller than elevations in meters leading to distorted
- 
-\begin_inset Quotes eld
-\end_inset
-
-distance
-\begin_inset Quotes erd
-\end_inset
-
- between locations and interpolation).
-\end_layout
-
-\begin_layout Standard
-SimpleDB uses a simple ASCII file to specify the variation of values (e.g.,
- displacement field, slip field, physical properties) in space.
- The file format is described in Section 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "sec:Spatialdata:SimpleIOAscii"
-
-\end_inset
-
-.
- The tutorials in Chapter 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "cha:Tutorials"
-
-\end_inset
-
- use SimpleDB files to specify the values for the boundary conditions, 
- physical properties, and fault slip.
-\end_layout
-
-\begin_layout Standard
-As in the other Pyre objects, spatial database objects contain parameters
- that can be set from the command line or using 
-\family typewriter
-.cfg or .pml
-\family default
- files.
- The parameters for a spatial database are:
-\end_layout
-
-\begin_layout Description
-label Label for the database, which is used in diagnostic messages.
-\end_layout
-
-\begin_layout Description
-query_type Type of search query to perform.
- Values for this parameter are ``linear'' and ``nearest'' (default).
-\end_layout
-
-\begin_layout Description
-iohandler Database importer.
- Only one importer is implemented, so you do not need to change this setting.
-\end_layout
-
-\begin_layout Description
-iohandler.filename Filename for the spatial database.
-\end_layout
-
-\begin_layout Standard
-An example of setting these parameters in a 
-\family typewriter
-.cfg
-\family default
- file is:
-\end_layout
-
-\begin_layout LyX-Code
-label = Material properties
-\end_layout
-
-\begin_layout LyX-Code
-query_type = linear
-\end_layout
-
-\begin_layout LyX-Code
-iohandler.filename = mydb.spatialdb
-\end_layout
-
-\begin_layout LyX-Code
-
-\end_layout
-
-\begin_layout Subsection
-UniformDB Spatial Database
-\end_layout
-
-\begin_layout Standard
-The SimpleDB spatial database is quite general, but when the values are
- uniform, it is often easier to use the UniformDB spatial database instead.
- With the UniformDB, you specify the values directly either on the command
- line or in a parameter-setting (
-\family typewriter
-.cfg
-\family default
-) file.
- On the other hand, if the values are used in more than one place, it is
- easier to place the values in a SimpleDB file, because they can then be
- referred to using the filename of the spatial database rather than having
- to repeatedly list all of the values on the command line or in a parameter-sett
-ing (
-\family typewriter
-.cfg
-\family default
-) file.
- The Pyre properties for a UniformDB are:
-\end_layout
-
-\begin_layout Description
-values Array of names of values in spatial database
-\end_layout
-
-\begin_layout Description
-data Array of values in spatial database
-\end_layout
-
-\begin_layout Subsubsection
-Example
-\end_layout
-
-\begin_layout Standard
-Specify the physical properties of a linearly elastic, isotropic material
- in a 
-\family typewriter
-pylithapp.cfg
-\family default
- file.
- The data values are dimensioned with the appropriate units using Python
- syntax.
-\end_layout
-
-\begin_layout LyX-Code
-
-\size small
-[pylithapp.timedependent.materials.material]
-\end_layout
-
-\begin_layout LyX-Code
-
-\size small
-db_properties = spatialdata.spatialdb.UniformDB ; Set the db to a UniformDB
-\end_layout
-
-\begin_layout LyX-Code
-
-\size small
-db_properties.values = [vp,vs,density] ; Set the names of the values in the
- database
-\end_layout
-
-\begin_layout LyX-Code
-
-\size small
-db_properties.data = [5773.5*m/s, 3333.3*m/s, 2700.0*kg/m**3] ; Set the values
- in the database
-\end_layout
-
-\begin_layout Subsubsection
-ZeroDispDB
-\end_layout
-
-\begin_layout Standard
-The ZeroDispDB is a a special case of the UniformDB for the Dirichlet boundary
- conditions.
- The values in the database are the ones requested by the Dirichlet boundary
- conditions, 
-\family typewriter
-displacement-x
-\family default
-, 
-\family typewriter
-displacement-y
-\family default
-, and 
-\family typewriter
-displacement-z
-\family default
-, and are all set to zero.
- This makes it trivial to set displacements to zero on a boundary.
- The examples discussed in Chapter 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "cha:Tutorials"
-
-\end_inset
-
- use this database.
-\end_layout
-
-\begin_layout Subsection
-\begin_inset CommandInset label
-LatexCommand label
-name "sub:SCECCVMH-Impl"
-
-\end_inset
-
-SCEC CVM-H Spatial Database
-\end_layout
-
-\begin_layout Standard
-Although the SimpleDB implementation is able to specify arbitrarily complex
- spatial variations, there are existing databases for physical properties,
- and when they are available, it is desirable to access these directly.
- One such database is the SCEC CVM-H database, which provides seismic velocities
- and density information for much of southern California.
- Spatialdata provides a direct interface to this database.
- See Section 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "sec:Tutorial-Two-tet4-geoproj"
-
-\end_inset
-
- for an example of using the SCEC CVM-H database for physical properties
- of an elastic material.
- The interface is known to work with versions 5.2 and 5.3 of the SCEC CVM-H.
- Setting a minimum wave speed can be used to replace water and very soft
- soils that are incompressible or nearly incompressible with stiffer, compressib
-le materials.
- The Pyre properties for the SCEC CVM-H are:
-\end_layout
-
-\begin_layout Description
-data_dir Directory containing the SCEC CVM-H data files
-\end_layout
-
-\begin_layout Description
-min_vs Minimum shear wave speed.
- Corresponding minimum values for the dilatational wave speed (Vp) and density
- are computed.
- Default value is 500 m/s.
-\end_layout
-
-\begin_layout Description
-squash Squash topography/bathymetry to sea level (make the earth's surface
- flat)
-\end_layout
-
-\begin_layout Description
-squash_limit Elevation above which topography is squashed (geometry below
- this elevation remains undistorted)
-\end_layout
-
-\begin_layout Subsubsection
-Example
-\end_layout
-
-\begin_layout Standard
-Specify the physical properties of a linearly elastic, isotropic material
- using the SCEC CVM-H in a 
-\family typewriter
-pylithapp.cfg
-\family default
- file.
-\end_layout
-
-\begin_layout LyX-Code
-
-\size small
-[pylithapp.timedependent.materials.material]
-\end_layout
-
-\begin_layout LyX-Code
-
-\size small
-db_properties = spatialdata.spatialdb.SCECCVMH ; Set the database to the SCEC
- CVM-H
-\end_layout
-
-\begin_layout LyX-Code
-
-\size small
-db_properties.data_dir = /home/johndoe/data/sceccvm-h/vx53 ; Directory containing
-\begin_inset Newline newline
-\end_inset
-
-the database data files
-\end_layout
-
-\begin_layout LyX-Code
-
-\size small
-db_properties.min_vs = 500*m/s
-\end_layout
-
-\begin_layout LyX-Code
-
-\size small
-db_properties.squash = True ; Turn on squashing
-\end_layout
-
-\begin_layout LyX-Code
-
-\size small
-db_properties.squash_limit = -1000.0 ; Only distort the geometry above z =
- -1 km in 
-\begin_inset Newline newline
-\end_inset
-
-flattening the earth
-\end_layout
-
-\begin_layout Subsection
-CompositeDB Spatial Database
-\end_layout
-
-\begin_layout Standard
-For some problems, a boundary condition or material property may have subsets
- with different spatial variations.
- One example would be when we have separate databases to describe the elastic
- and inelastic bulk material properties for a region.
- In this case, it would be useful to have two different spatial databases,
- e.g., a seismic velocity model with Vp, Vs, and density values, and another
- database with the inelastic physical properties.
- We can use the 
-\family typewriter
-CompositeDB
-\family default
- spatial database for these cases.
- An example would be:
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.timedependent.materials.maxwell]
-\end_layout
-
-\begin_layout LyX-Code
-label = Maxwell material
-\end_layout
-
-\begin_layout LyX-Code
-id = 1
-\end_layout
-
-\begin_layout LyX-Code
-db_properties = spatialdata.spatialdb.CompositeDB
-\end_layout
-
-\begin_layout LyX-Code
-db_properties.db_A = spatialdata.spatialdb.SCECCVMH
-\end_layout
-
-\begin_layout LyX-Code
-db_properties.db_B = spatialdata.spatialdb.SimpleDB
-\end_layout
-
-\begin_layout LyX-Code
-quadrature.cell = pylith.feassemble.FIATSimplex
-\end_layout
-
-\begin_layout LyX-Code
-quadrature.cell.dimension = 3
-\end_layout
-
-\begin_layout LyX-Code
- 
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.timedependent.materials.maxwell.db_properties]
-\end_layout
-
-\begin_layout LyX-Code
-values_A = [density,vs,vp]
-\end_layout
-
-\begin_layout LyX-Code
-db_A.label = Elastic properties from CVM-H
-\end_layout
-
-\begin_layout LyX-Code
-db_A.data_dir = /Users/willic3/geoframe/tools/vx53/bin
-\end_layout
-
-\begin_layout LyX-Code
-db_A.squash = False
-\end_layout
-
-\begin_layout LyX-Code
-values_B = [viscosity]
-\end_layout
-
-\begin_layout LyX-Code
-db_B.label = Vertically varying Maxwell material
-\end_layout
-
-\begin_layout LyX-Code
-db_B.iohandler.filename = ../spatialdb/mat_vert_var_maxwell.spatialdb
-\end_layout
-
-\begin_layout Standard
-Here we have specified a 
-\family typewriter
-CompositeDB
-\family default
- where the elastic properties (
-\family typewriter
-density
-\family default
-, 
-\family typewriter
-vs
-\family default
-, 
-\family typewriter
-vp
-\family default
-) are given by the SCEC CVM-H, and 
-\family typewriter
-viscosity
-\family default
- is described by a 
-\family typewriter
-SimpleDB
-\family default
- (
-\family typewriter
-mat_vert_var_maxwell.spatialdb
-\family default
-).
- The user must first specify 
-\family typewriter
-db_properties
-\family default
- as a 
-\family typewriter
-CompositeDB
-\family default
-, and must then give the two components of this database (
-\family typewriter
-SCECCVMH
-\family default
- and 
-\family typewriter
-SimpleDB
-\family default
-).
- The values to query in each of these databases is also required.
- This is followed by the usual parameters for each of the spatial databases.
- The 
-\family typewriter
-CompositeDB
-\family default
- provides a flexible mechanism for specifying material properties or boundary
- conditions where the variations come from two different sources.
-\end_layout
-
-\begin_layout Subsection
-Time History Database
-\end_layout
-
-\begin_layout Standard
-The time history database specifies the temporal variation in the amplitude
- of a field associated with a boundary condition.
- It is used in conjunction with spatial databases to provide spatial and
- temporal variation of parameters for boundary conditions.
- The same time history is applied to all of the locations, but the time
- history may be shifted with a spatial variation in the onset time and scaled
- with a spatial variation in the amplitude.
- The time history database uses a simple ASCII file which is simpler than
- the one used by the SimpleDB spatial database.
- The file format is described in Section 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "sec:Spatialdata:TimeHistoryIO"
-
-\end_inset
-
-.
- 
-\end_layout
-
-\begin_layout Standard
-As in the other Pyre objects, spatial database objects contain parameters
- that can be set from the command line or using 
-\family typewriter
-.cfg or .pml
-\family default
- files.
- The parameters for a spatial database are:
-\end_layout
-
-\begin_layout Description
-label Label for the time history database, which is used in diagnostic messages.
-\end_layout
-
-\begin_layout Description
-filename Filename for the time history database.
-\end_layout
-
-\begin_layout Standard
-An example of setting these parameters in a 
-\family typewriter
-.cfg
-\family default
- file is:
-\end_layout
-
-\begin_layout LyX-Code
-label = Displacement time history
-\end_layout
-
-\begin_layout LyX-Code
-filename = mytimehistory.timedb
-\end_layout
-
-\begin_layout Section
-Labels and Identifiers for Materials, Boundary Conditions, and Faults
-\end_layout
-
-\begin_layout Standard
-For materials, the ``label'' is a string used only for error messages.
- The ``id'' is an integer that corresponds to the material identifier in
- LaGriT (itetclr) and CUBIT (block id).
- The id also tags the cells in the mesh for associating cells with a specific
- material model and quadrature rule.
- For boundary conditions, the ``label'' is a string used to associate groups
- of vertices (psets in LaGriT and nodesets in CUBIT) with a boundary condition.
- Some mesh generators use strings (LaGriT) to identify groups of nodes while
- others (CUBIT) use strings and integers.
- The default behavior in PyLith is to use strings to identify groups for
- both LaGriT and CUBIT meshes, but the behavior for CUBIT meshes can be
- changed to use the nodeset id (see Section 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "sec:MeshIOCubit"
-
-\end_inset
-
-).
- PyLith 1.0 had an ``id'' for boundary conditions, but we removed it from
- subsequent releases because it was not used.
- For faults the ``label'' is used in the same manner as the ``label'' for
- boundary conditions.
- That is, it associates a string with a group of vertices (pset in LaGriT
- and nodeset in CUBIT).
- The fault ``id'' is a integer used to tag the cohesive cells in the mesh
- with a specific fault and quadrature rule.
- Because we use the fault ``id'' to tag cohesive cells in the mesh the same
- way we tag normal cells to materials, it must be unique among the faults
- as well as the materials.
-\end_layout
-
-\begin_layout Section
-PyLith Output
-\end_layout
-
-\begin_layout Standard
-PyLith currently supports output to VTK and HDF5/Xdmf files, which can be
- imported directly into a number of visualization tools, such as ParaView,
- Visit, and MayaVi.
- The HDF5 files can also be directly accessed via Matlab and PyTables.
- PyLith 1.1 significantly expanded the information available for output,
- including fault information and state variables.
- Output of solution information for the domain, faults, materials, and boundary
- conditions is controlled by an output manager for each module.
- This allows the user to tailor the output to the problem.
- By default PyLith will write a number of files.
- Diagnostic information for each fault and material is written into a separate
- file as are the solution and state variables for the domain, each fault,
- and each material.
- For a fault the diagnostic fields include the final slip, the slip initiation
- time, and the fault normal vector.
- For a material the diagnostic fields include the density and the elastic
- constants.
- Additional diagnostic information can be included by setting the appropriate
- output parameters.
- See Chapters 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "cha:material:models"
-
-\end_inset
-
- and 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "cha:boundary:interface:conditions"
-
-\end_inset
-
- for more information on the available fields and the next section for output
- parameters.
- The other files for each fault and material include solution information
- at each time step where output was requested (also customizable by the
- user).
- For a fault the solution information includes the slip and the change in
- tractions on the fault surface.
- For a material the solution information includes the total strain and stress.
- For some materials fields for additional state variables may be available.
- For output via VTK files, each time step is written to a separate file,
- whereas for HDF5 files all of the time steps for a given domain, fault,
- or material are written into the same file.
- A single Xdmf metadata file is created for each HDF5 file.
-\end_layout
-
-\begin_layout Subsection
-Output Manager
-\end_layout
-
-\begin_layout Standard
-The OutputManager object controls the type of files written, the fields
- included in the output, and how often output is written.
- PyLith includes some specialized OutputManagers that prescribe what fields
- are output by default.
- In some cases, additional fields are available but not included by default.
- For example, in 3D problems, the along-strike and up-dip directions over
- the fault surface can be included in the diagnostic information.
- These are not included by default, because 1D problems have neither an
- along-strike nor up-dip direction and 2D problems do not have an up-dip
- direction.
-\end_layout
-
-\begin_layout Subsubsection
-Output Manager Parameters
-\end_layout
-
-\begin_layout Standard
-The parameters for the OutputManager are:
-\end_layout
-
-\begin_layout Description
-output_freq Flag indicating whether to write output based on the time or
- number of time steps since the last output.
- Permissible values are ``time_step'' and ``skip'' (default).
-\end_layout
-
-\begin_layout Description
-time_step Minimum time between output if 
-\family typewriter
-output_freq
-\family default
- is set to ``time_step''.
-\end_layout
-
-\begin_layout Description
-skip Number of time steps between output if 
-\family typewriter
-output_freq
-\family default
- is set to ``skip''.
- A value of 0 means every time step is written.
-\end_layout
-
-\begin_layout Description
-writer Writer for data (VTK writer or HDF5 writer).
-\end_layout
-
-\begin_layout Description
-coordsys Coordinate system for vertex coordinates (currently ignored).
-\end_layout
-
-\begin_layout Description
-vertex_filter Filter to apply to all vertex fields (see Section 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "sub:vertex:field:filters"
-
-\end_inset
-
-).
-\end_layout
-
-\begin_layout Description
-cell_filter Filter to apply to all cell fields (see Section 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "sub:cell:field:filters"
-
-\end_inset
-
-).
-\end_layout
-
-\begin_layout Standard
-An example of setting the output parameters for a material in a 
-\family typewriter
-.cfg
-\family default
- file is
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.timedependent.materials.elastic.output]
-\end_layout
-
-\begin_layout LyX-Code
-output_freq = time_step
-\end_layout
-
-\begin_layout LyX-Code
-time_step = 1.0*yr
-\end_layout
-
-\begin_layout LyX-Code
-cell_filter = pylith.meshio.CellFilterAvgMesh
-\end_layout
-
-\begin_layout LyX-Code
-cell_info_fields = [density] ; limit diagnostic data to density
-\end_layout
-
-\begin_layout LyX-Code
-cell_data_fields = [total-strain,stress] ; default
-\end_layout
-
-\begin_layout LyX-Code
-writer.filename = dislocation-elastic.vtk
-\end_layout
-
-\begin_layout Subsubsection
-Output Over Subdomain
-\end_layout
-
-\begin_layout Standard
-Output of the solution over the entire domain for large problems generates
- very large data files.
- In some cases one is primarily interested in the solution over the ground
- surface.
- PyLith supports output of the solution on any boundary of the domain by
- associating an output manager with a group of vertices corresponding to
- the surface of the boundary.
- As with several of the boundary conditions, the boundary must be a simply-conne
-cted surface.
- The 
-\family typewriter
-OutputSolnSubset
-\family default
- is the specialized OutputManager that implements this feature and, by default,
- includes the displacement field in the output.
- In addition to the 
-\family typewriter
-OutputManager
-\family default
- parameters, the 
-\family typewriter
-OutputSolnSubset
-\family default
- includes:
-\end_layout
-
-\begin_layout Description
-label Label of group of vertices defining boundary surface.
-\end_layout
-
-\begin_layout Description
-vertex_data_fields Names of vertex data fields to output (default is [``displace
-ments'']).
-\end_layout
-
-\begin_layout Subsection
-\begin_inset CommandInset label
-LatexCommand label
-name "sec:output:points"
-
-\end_inset
-
-Output at Arbitrary Points
-\end_layout
-
-\begin_layout Standard
-In many situations with recorded observations, one would like to extract
- the solution at the same locations as the recorded observation.
- Rather than forcing the finite-element discretization to be consistent
- with the observation points, PyLith includes a specialized output manager,
- 
-\family typewriter
-OutputSolnPoints
-\family default
-, to interpolate the solution to arbitrary points.
- By default, the output manager will include the displaceent time histories
- in the output.
- The locations are specified in a text file.
- In addition to the 
-\family typewriter
-OutputManager
-\family default
- parameters, the 
-\family typewriter
-OutputSolnSubset
-\family default
- includes:
-\end_layout
-
-\begin_layout Description
-vertex_data_fields Names of vertex data fields to output (default is [``displace
-ments'']).
-\end_layout
-
-\begin_layout Description
-reader Reader for points list (default is 
-\family typewriter
-PointsList
-\family default
-).
-\end_layout
-
-\begin_layout Description
-writer Writer for output (default is 
-\family typewriter
-DataWriterVTKPoints
-\family default
-).
- In most cases users will want to use the 
-\family typewriter
-DataWriterHDF5Mesh
-\family default
-.
-\end_layout
-
-\begin_layout Subsubsection
-PointsList Reader
-\end_layout
-
-\begin_layout Standard
-This object corresponds to a simple text file containing a list of points
- (one per line) where output is desired.
- The points are specified in the coordinate system specified by OutputSolnPoints.
- The coordinates will be transformed into the coordinate system of the mesh
- prior to interpolation.
- The properties available to customize the behavior of 
-\family typewriter
-PointsList
-\family default
- are:
-\end_layout
-
-\begin_layout Description
-filename Names of file containing list of points.
-\end_layout
-
-\begin_layout Description
-comment_delimiter Delimiter at beginning of line to identify comments (default
- is #).
-\end_layout
-
-\begin_layout Description
-value_delimiter Delimiter used to separate values (default is whitespace).
-\end_layout
-
-\begin_layout Subsection
-Output Field Filters
-\end_layout
-
-\begin_layout Standard
-Output fields may not directly correspond to the information a user desires.
- For example, the default output for the state variables includes the physical
- properties at each quadrature point.
- Most visualization packages cannot handle cell fields with multiple points
- in a cell (the locations of the points within the cell are not included
- in the data file).
- In order to reduce the field to a single point within the cell, we would
- like to average the values.
- This is best done within PyLith before output, because it reduces the file
- size and the quadrature information provides the information necessary
- (the weights of the quadrature points) to compute the appropriate average
- over the cell.
-\end_layout
-
-\begin_layout Subsubsection
-\begin_inset CommandInset label
-LatexCommand label
-name "sub:vertex:field:filters"
-
-\end_inset
-
-Vertex Field Filters
-\end_layout
-
-\begin_layout Standard
-Currently the only filter available for vertex fields computes the magnitude
- of a vector at each location.
- Most visualization packages support this operation, so this filter is not
- very useful.
-\end_layout
-
-\begin_layout Description
-VertexFilterVecNorm Computes the magnitude of a vector field at each location.
-\end_layout
-
-\begin_layout Subsubsection
-\begin_inset CommandInset label
-LatexCommand label
-name "sub:cell:field:filters"
-
-\end_inset
-
-Cell Field Filters
-\end_layout
-
-\begin_layout Standard
-Most users will want to apply a filter to cell fields to average the fields
- over the cell, producing values at one location per cell for visualization.
-\end_layout
-
-\begin_layout Description
-CellFilterAvgMesh Compute the weighted average of the values within a bulk
- cell.
- The weights are determined from the quadrature associated with the cells.
-\end_layout
-
-\begin_layout Description
-CellFilterAvgSubMesh Compute the weighted average of the values for a boundary
- cell.
- The weights are determined from the quadrature associated with the cells.
-\end_layout
-
-\begin_layout Subsection
-VTK Output
-\end_layout
-
-\begin_layout Standard
-PyLith writes legacy (non-XML) VTK files.
- These are simple files with vertex coordinates, the mesh topology, and
- fields over vertices and/or cells.
- Each time step is written to a different file.
- The time stamp is included in the filename with the decimal point removed.
- This allows automatic generation of animations with many visualization
- packages that use VTK files.
- The default time stamp is the time in seconds, but this can be changed
- using the normalization constant to give a time stamp in years, tens of
- years, or any other value.
-\end_layout
-
-\begin_layout Subsubsection
-DataWriterVTK Parameters
-\end_layout
-
-\begin_layout Standard
-The parameters for the VTK writer are:
-\end_layout
-
-\begin_layout Description
-filename Name of VTK file
-\end_layout
-
-\begin_layout Description
-time_format C-style format string for time stamp in filename.
- The decimal point in the time stamp will be removed for compatibility with
- VTK visualization packages that provide seamless animation of data from
- multiple VTK files.
-\end_layout
-
-\begin_layout Description
-time_constant Value used to normalize time stamp in VTK files (default is
- 1.0 s).
-\end_layout
-
-\begin_layout Subsection
-HDF5/Xdmf Output
-\end_layout
-
-\begin_layout Standard
-HDF5 files provide a flexible framework for storing simulation data with
- datasets in groups logically organized in a tree structure analogous to
- files in directories.
- HDF5 output offers parallel, multi-dimensional array output in binary files,
- so it is much faster and more convenient than the VTK output which uses
- ASCII files and separate files for each time step.
- Standards for organizing datasets and groups in HDF5 files do not exist
- for general finite-element software in geodynamics.
- Consequently, PyLith uses its own simple layout show in Figure 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "fig:hdf5:layout"
-
-\end_inset
-
-.
- In order for visualization tools, such as ParaView, to determine which
- datasets to read and where to find them in the hierarchy of groups within
- the HDF5 file, we create an Xdmf (eXtensible Data Model and Format, 
-\begin_inset Flex URL
-status open
-
-\begin_layout Plain Layout
-
-www.xdmf.org
-\end_layout
-
-\end_inset
-
-) metadata file that provides this information.
- This file is written when PyLith closes the HDF5 file at the end of the
- simulation.
- In order to visualize the datasets in an HDF5 file, one simply opens the
- corresponding Xdmf file (the extension is 
-\family typewriter
-.xmf
-\family default
-) in ParaView or Visit.
- The Xdmf file contains the relative path to the HDF5 file so the files
- can be moved but must be located together in the same directory.
- 
-\end_layout
-
-\begin_layout Quote
-
-\series bold
-\color red
-Note:
-\color inherit
- 
-\series default
-The Xdmf format supports representation of two- and three-dimensional coordinate
-s of points, scalar vector field types, and three-dimensional vector and
- tensor vector field types but not two-dimensional vector or tensor vector
- field types.
- As a result, we separate the components of two-dimensional vector and tensor
- vector field objects and add the component as a suffix to the name of the
- field.
- The vector can be reconstructed within ParaView using the Calculator (see
- Section 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "sec:Tutorial-Subduction"
-
-\end_inset
-
- for an example).
- Accessing the datasets in the HDF5 files using tools such as h5py (included
- with the PyLith binary and installed by default with the PyLith Installer)
- and PyTables with visualization through MayaVi circumvents this problem,
- but requires writing Python scripts and a deeper knowledge of the visualization
- interface.
-\end_layout
-
-\begin_layout Standard
-\noindent
-\align center
-\begin_inset Float figure
-placement H
-wide false
-sideways false
-status open
-
-\begin_layout Plain Layout
-\noindent
-\align center
-\begin_inset Graphics
-	filename figs/hdf5layout.eps
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Plain Layout
-\begin_inset Caption
-
-\begin_layout Plain Layout
-Layout of PyLith HDF5 file.
- The orange rectangles with rounded corners identify the groups and the
- blue rectangles with sharp corners identify the datasets.
- The dimensions of the data sets are shown in parentheses.
- Most HDF5 files will contain either 
-\family typewriter
-vertex_fields
-\family default
- or 
-\family typewriter
-cell_fields
-\family default
- but not both.
- 
-\begin_inset CommandInset label
-LatexCommand label
-name "fig:hdf5:layout"
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-HDF5 files do not contain self-correcting features that allow a file to
- be read if part of a dataset is corrupted.
- This type of error can occur if a job terminates abnormally in the middle
- or at the end of a simulation on a large cluster or other parallel machine.
- Fortunately, HDF5 also offers the ability to store datasets in external
- binary files with the locations specified by links in the HDF5 file.
- Note that the use of external data files results in one data file per dataset
- in addition to the HDF5 and Xdmf files.
- The external data files use the name of the HDF5 file with the dataset
- name added to the prefix and the 
-\family typewriter
-.h5
-\family default
- suffix replaced by 
-\family typewriter
-.dat
-\family default
-).
- The HDF5 files include relative paths to the external data files, so these
- files can also be moved, but they, too, must be kept together in the same
- directory.
- This provides a more robust method of output because one can generate an
- HDF5 file associated with the uncorrupted portions of the external data
- files should an error occur.
- Currently, PyLith does not include a utility to do this, but we plan to
- add one in a future release.
- Thus, there are two options when writing PyLith output to HDF5 files: (1)
- including the datasets directly in the HDF5 files themselves or (2) storing
- the datasets in external binary files with just metadata in the HDF5 files.
- Both methods provide similar performance because they will use MPI I/O
- if it is available.
- 
-\end_layout
-
-\begin_layout Quote
-
-\series bold
-\color red
-Warning:
-\color inherit
- 
-\series default
-Storing the datasets within the HDF5 file in a parallel simulation requires
- that the HDF5 library be configured with the 
-\family typewriter
---enable-parallel
-\family default
- option.
- 
-\color none
-The binary PyLith packages include this feature and it is a default setting
- in building HDF5 via the PyLith Installer.
-\end_layout
-
-\begin_layout Standard
-Accessing the datasets for additional analysis or visualization is nearly
- identical in the two methods because the use of external data files is
- completely transparent to the user except for the presence of the additional
- files.
- Note that in order for ParaView to find the HDF5 and external data files,
- it must be run from the same relative location where the simulation was
- run.
- For example, if the simulation was run from a directory called 
-\begin_inset Quotes eld
-\end_inset
-
-work
-\begin_inset Quotes erd
-\end_inset
-
- and the HDF5/Xdmf files were written to 
-\begin_inset Quotes eld
-\end_inset
-
-work/output
-\begin_inset Quotes erd
-\end_inset
-
-, then ParaView should be run from the 
-\begin_inset Quotes eld
-\end_inset
-
-work
-\begin_inset Quotes erd
-\end_inset
-
- directory.
- See Table 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "tab:material:output:components"
-
-\end_inset
-
- in Section 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "sec:material:parameters"
-
-\end_inset
-
-for a table of component values for tensor output.
-\end_layout
-
-\begin_layout Subsubsection
-HDF5 utilities
-\end_layout
-
-\begin_layout Standard
-HDF5 includes several utilities for examining the contents of HDF5 files.
- 
-\family typewriter
-h5dump
-\family default
- is very handy for displaying the hierarchy, dimensions of datasets, attributes,
- and even the dataset values.
- 
-\end_layout
-
-\begin_layout Quote
-Dump the entire HDF5 file to stdout (not practical or useful for large files):
-\end_layout
-
-\begin_deeper
-\begin_layout LyX-Code
-h5dump mydata.h5
-\end_layout
-
-\end_deeper
-\begin_layout Quote
-Dump the hierarchy of an HDF5 file to stdout:
-\end_layout
-
-\begin_deeper
-\begin_layout LyX-Code
-h5dump -n mydata.h5
-\end_layout
-
-\end_deeper
-\begin_layout Quote
-Dump the hierarchy with dataset dimensions and attributes to stdout:
-\end_layout
-
-\begin_deeper
-\begin_layout LyX-Code
-h5dump -H mydata.h5
-\end_layout
-
-\end_deeper
-\begin_layout Quote
-Dump dataset 'vertices' in group '/geometry' to stdout:
-\end_layout
-
-\begin_deeper
-\begin_layout LyX-Code
-h5dump -d /geometry/vertices mydata.h5
-\end_layout
-
-\end_deeper
-\begin_layout Subsubsection
-DataWriterHDF5 Parameters
-\end_layout
-
-\begin_layout Standard
-This HDF5 writer stores the datasets inside the HDF5 file and the parameters
- are:
-\end_layout
-
-\begin_layout Description
-filename Name of HDF5 file (the Xdmf filename is generated from the same
- prefix).
-\end_layout
-
-\begin_layout Subsubsection
-DataWriterHDF5Ext Parameters
-\end_layout
-
-\begin_layout Standard
-This HDF5 writer stores the datasets using external data files (a more robust
- method for parallel runs) and the parameters are:
-\end_layout
-
-\begin_layout Description
-filename Name of HDF5 file (the external dataset filenames and the Xdmf
- filename are generated from the same prefix).
-\end_layout
-
-\begin_layout Standard
-An example of changing the writer from the default VTK writer to the HDF5
- writer with external datasets for output over the domain in a 
-\family typewriter
-.cfg
-\family default
- file is
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.timedependent.domain.output]
-\end_layout
-
-\begin_layout LyX-Code
-output_freq = time_step
-\end_layout
-
-\begin_layout LyX-Code
-time_step = 1.0*yr
-\end_layout
-
-\begin_layout LyX-Code
-cell_data_fields = [displacement,velocity]
-\end_layout
-
-\begin_layout LyX-Code
-writer = pylith.meshio.DataWriterHDF5ExtMesh
-\end_layout
-
-\begin_layout LyX-Code
-writer.filename = dislocation.h5
-\end_layout
-
-\begin_layout Section
-Tips and Hints
-\begin_inset CommandInset label
-LatexCommand label
-name "sec:Tips:Hints"
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Subsection
-Tips and Hints For Running PyLith
-\end_layout
-
-\begin_layout Itemize
-Examine the examples for a problem similar to the one you want to run and
- dissect it in detail.
-\end_layout
-
-\begin_layout Itemize
-Start with a uniform-resolution coarse mesh to debug the problem setup.
- Increase the resolution as necessary to resolve the solution fields of
- interest (resolving stresses/strains may require a higher resolution than
- that for resolving displacements).
-\end_layout
-
-\begin_layout Itemize
-Merge materials using the same material model.
- This will result in only one VTK or HDF5 file for each material model rather
- than several files.
-\end_layout
-
-\begin_layout Itemize
-The rate of convergence in quasi-static (implicit) problems can sometimes
- be improved by renumbering the vertices in the finite-element mesh to reduce
- the bandwidth of the sparse matrix.
- PyLith can use the reverse Cuthill-McKee algorithm to reorder the vertices
- and cells.
-\end_layout
-
-\begin_layout Itemize
-If you encounter errors or warnings, run 
-\family typewriter
-pylithinfo
-\family default
- or use the 
-\family typewriter
---help
-\family default
-, 
-\family typewriter
---help-components
-\family default
-, and 
-\family typewriter
---help-properties
-\family default
- command line arguments when running PyLith to check the parameters to make
- sure PyLith is using the parameters you intended.
-\end_layout
-
-\begin_layout Itemize
-Use the 
-\family typewriter
---petsc.log_summary
-\family default
-, 
-\family typewriter
---petsc.ksp_monitor
-\family default
-, 
-\family typewriter
---petsc.ksp_view
-\family default
-, 
-\family typewriter
---petsc.ksp_converged_reason
-\family default
-, and 
-\family typewriter
---petsc.snes_converged_reason
-\family default
- command line arguments (or set them in a parameter file) to view PyLith
- performance and monitor the convergence.
-\end_layout
-
-\begin_layout Itemize
-Turn on the journals (see the examples) to monitor the progress of the code.
-\end_layout
-
-\begin_layout Subsection
-Troubleshooting
-\begin_inset CommandInset label
-LatexCommand label
-name "sec:Troubleshooting"
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Itemize
-Consult the PyLith FAQ webpage (
-\begin_inset Flex URL
-status open
-
-\begin_layout Plain Layout
-
-http://www.geodynamics.org/cig/community/workinggroups/short/workarea/pylith-wiki
-\end_layout
-
-\end_inset
-
-) which contains a growing list of common problems and their corresponding
- solutions.
-\end_layout
-
-\begin_layout Itemize
-
-\family typewriter
-ImportError: liblapack.so.2: cannot open shared object file: No such file
- or directory
-\end_layout
-
-\begin_layout Quote
-PyLith cannot find one of the libraries.
- You need to set up your environment variables (e.g., PATH, PYTHONPATH, and
- LD_LIBRARY_PATH) to match your installation.
- If you are using the PyLith binary on Linux or Mac OS X, run the command
- 
-\family typewriter
-source setup.sh 
-\family default
-in the directory where you unpacked the distribution.
- This will set up your environment variables for you.
- If you are building PyLith from source, please consult the instructions
- for building from source.
-\end_layout
-
-\begin_layout Itemize
-\paragraph_spacing single
-
-\family typewriter
->> {command line}:: 
-\begin_inset Newline newline
-\end_inset
-
--- pyre.inventory(error) 
-\begin_inset Newline newline
-\end_inset
-
--- p4wd <- 'true' 
-\begin_inset Newline newline
-\end_inset
-
--- unrecognized property 'p4wd' 
-\begin_inset Newline newline
-\end_inset
-
->> {command line}:: 
-\begin_inset Newline newline
-\end_inset
-
--- pyre.inventory(error) 
-\begin_inset Newline newline
-\end_inset
-
--- p4pg <- 'true' 
-\begin_inset Newline newline
-\end_inset
-
--- unrecognized property ' p4pg'
-\end_layout
-
-\begin_layout Quote
-Verify that the `mpirun' command included in the PyLith package is the first
- one on your PATH:
-\end_layout
-
-\begin_layout Quote
-
-\family typewriter
-$ which mpirun
-\end_layout
-
-\begin_layout Quote
-If it is not, adjust your PATH environment variable accordingly.
-\end_layout
-
-\begin_layout Itemize
-
-\family typewriter
-"merlin.DistributionNotFound: Cheetah" error
-\end_layout
-
-\begin_layout Quote
-This error occurs when trying to use the 32-bit linux binary on some 64-bit
- linux systems.
- One of the Python packages PyLith uses does not know how to determine the
- system architecture at runtime.
- The workaround is:
-\end_layout
-
-\begin_layout Enumerate
-Go to the lib/python2.6/site-packages directory.
-\end_layout
-
-\begin_layout Enumerate
-Unzip merlin-1.7-py2.6.egg (if it is a file and not a directory).
-\end_layout
-
-\begin_layout Enumerate
-Go to the merlin directory.
-\end_layout
-
-\begin_layout Enumerate
-Edit __init__.py.
- Replace line 308 plat = get_platform() with plat = "linux-i686"
-\end_layout
-
-\begin_layout Enumerate
-If merlin-1.7-py2.6.egg is a file, rezip merlin.
- Go to the site-packages directory and enter "zip -r merlin-1.7-py2.6.egg merlin".
-\end_layout
-
-\begin_layout Itemize
-
-\family typewriter
--- Solving equations.
-\begin_inset Newline newline
-\end_inset
-
-[0]PETSC ERROR: ---------------- Error Message -------------------------------
- 
-\begin_inset Newline newline
-\end_inset
-
-[0]PETSC ERROR: Detected zero pivot in LU factorization
-\begin_inset Newline newline
-\end_inset
-
- see http://www.mcs.anl.gov/petsc/petsc-as/documentation/faq.html#ZeroPivot!
-\end_layout
-
-\begin_layout Quote
-This usually occurs when the null space of the system Jacobian is nonzero,
- such as the case of a problem without Dirichlet boundary conditions on
- any boundary.
- If this arises when using the split fields and algebraic multigrid precondition
-ing and no additional Dirichlet boundary conditions are desired, then the
- workaround is to revert to using the Additive Schwarz preconditioning without
- split fields as discussed in Section 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "sec:petsc:options"
-
-\end_inset
-
-.
- 
-\end_layout
-
-\begin_layout Itemize
-PyLith crashes with a bus error.
-\end_layout
-
-\begin_layout Quote
-This often indicates that PyLith is using incompatible versions of libraries.
- This can result from changing your environment variables after configuring
- or installing PyLith (when building from source) or errors in setting the
- environment variables (PATH, LD_LIBRARY_PATH, and PYTHONPATH).
- If the former case, simply reconfigure and rebuild PyLith.
- In the latter case, check your environment variables (order matters!) to
- make sure PyLith finds the desired directories before system directories.
- 
-\end_layout
-
-\begin_layout Itemize
-PyLith crashes with a segmentation fault.
-\end_layout
-
-\begin_layout Quote
-A segmentation fault might be caused by an error that wasn't trapped or
- a bug in the code.
- Please report these cases so that we can fix these problems (either trap
- the error and provide the user with an informative error message, or fix
- the bug).
- If this occurs with any of the problems distributed with PyLith, simply
- submit a bug report (see Section 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "sec:Getting-Help-and"
-
-\end_inset
-
-) indicating which problem you ran and your platform.
- If the crash occurs for a problem you created, it is a great help if you
- can try to reproduce the crash with a very simple problem (e.g., adjust the
- boundary conditions or other parameters of one of the examples to reproduce
- the segmentation fault).
- Submit a bug report along with log files showing the backtrace from a debugger
- (e.g., gdb) and the valgrind log file (only available on Linux platforms).
- You can generate a backtrace using the debugger by using the 
-\family typewriter
---petsc.start_in_debugger
-\family default
- command line argument:
-\end_layout
-
-\begin_layout LyX-Code
-pylith [..args..] --petsc.start_in_debugger
-\end_layout
-
-\begin_layout LyX-Code
-(gdb) continue
-\end_layout
-
-\begin_layout LyX-Code
-(gdb) backtrace
-\end_layout
-
-\begin_layout Quote
-To use valgrind to detect the memory error, first go to your working directory
- and run the problem with 
-\family typewriter
---launcher.dry
-\family default
-:
-\end_layout
-
-\begin_layout LyX-Code
-pylith [..args..] --launcher.dry
-\end_layout
-
-\begin_layout Quote
-Instead of actually running the problem, this causes PyLith to dump the
- mpirun/mpiexec command it will execute.
- Copy and paste this command into your shell so you can run it directly.
- Insert the full path to valgrind before the full path to mpinemesis and
- tell valgrind to use a log file:
-\end_layout
-
-\begin_layout LyX-Code
-
-\size small
-mpirun -np 1 /path/to/valgrind --log-file=valgrind-log  /path/to/mpinemesis
- --pyre-start [..lots of junk..]
-\end_layout
-
-\end_body
-\end_document
+#LyX 2.0 created this file. For more info see http://www.lyx.org/
+\lyxformat 413
+\begin_document
+\begin_header
+\textclass book
+\begin_preamble
+
+\end_preamble
+\use_default_options false
+\maintain_unincluded_children false
+\language english
+\language_package default
+\inputencoding latin1
+\fontencoding global
+\font_roman default
+\font_sans default
+\font_typewriter default
+\font_default_family default
+\use_non_tex_fonts false
+\font_sc false
+\font_osf false
+\font_sf_scale 100
+\font_tt_scale 100
+
+\graphics default
+\default_output_format default
+\output_sync 0
+\bibtex_command default
+\index_command default
+\paperfontsize default
+\spacing single
+\use_hyperref false
+\papersize default
+\use_geometry true
+\use_amsmath 1
+\use_esint 0
+\use_mhchem 1
+\use_mathdots 1
+\cite_engine basic
+\use_bibtopic false
+\use_indices false
+\paperorientation portrait
+\suppress_date false
+\use_refstyle 0
+\index Index
+\shortcut idx
+\color #008000
+\end_index
+\leftmargin 1in
+\topmargin 1in
+\rightmargin 1in
+\bottommargin 2in
+\secnumdepth 3
+\tocdepth 3
+\paragraph_separation indent
+\paragraph_indentation default
+\quotes_language english
+\papercolumns 1
+\papersides 2
+\paperpagestyle default
+\tracking_changes false
+\output_changes false
+\html_math_output 0
+\html_css_as_file 0
+\html_be_strict false
+\end_header
+
+\begin_body
+
+\begin_layout Chapter
+Running PyLith
+\end_layout
+
+\begin_layout Standard
+There are essentially three major inputs needed to run a problem with PyLith:
+\end_layout
+
+\begin_layout Enumerate
+A set of parameters describing the problem.
+ These parameters describe the type of problem to be run, solver information,
+ time-stepping information, boundary conditions, materials, etc.
+ This information can be provided from the command-line or by using a 
+\family typewriter
+.cfg
+\family default
+ or 
+\family typewriter
+.pml
+\family default
+ file.
+\end_layout
+
+\begin_layout Enumerate
+Mesh information.
+ This includes the topology of the finite-element mesh (coordinates of vertices
+ and how the vertices are connected into cells), a 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 CommandInset ref
+LatexCommand ref
+reference "cha:Tutorials"
+
+\end_inset
+
+ for examples and Section 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "sec:MeshIOAscii"
+
+\end_inset
+
+ for the format specification) or by importing the information from the
+ LaGriT or CUBIT meshing packages (see Chapter 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "cha:Tutorials"
+
+\end_inset
+
+ for examples).
+\end_layout
+
+\begin_layout Enumerate
+Databases specifying the material property values and boundary condition
+ values to be used.
+ Arbitrarily complex spatial variations in boundary and fault conditions
+ and material properties may be given in the spatial database (see Chapter
+ 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "cha:Tutorials"
+
+\end_inset
+
+ for examples and Appendix 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "sec:Spatialdata:SimpleIOAscii"
+
+\end_inset
+
+ for the format specification).
+\end_layout
+
+\begin_layout Section
+Defining the Simulation
+\end_layout
+
+\begin_layout Standard
+The parameters for PyLith are specified as a hierarchy or tree of modules.
+ The application assembles the hierarchy of modules from user input and
+ then calls the 
+\family typewriter
+main
+\family default
+ function in the top-level module in the same manner as a C or C++ program.
+ The behavior of the application is determined by the modules included in
+ the hierarchy as specified by the user.
+ The Pyre framework provides the interface for defining this hierarchy.
+ Pyre properties correspond to simple settings in the form of strings, integers,
+ and real numbers.
+ Pyre facilities correspond to software modules.
+ Facilities may have their own facilities (branches in the tree) and any
+ number of properties.
+ See Figure 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "fig:Pyre:Architecture"
+
+\end_inset
+
+ for the general concept of Pyre facilities and properties.
+ The top-level object is the PyLith application with three facilities: 
+\family typewriter
+mesher
+\family default
+, 
+\family typewriter
+problem
+\family default
+, and 
+\family typewriter
+petsc
+\family default
+.
+ The 
+\family typewriter
+mesher
+\family default
+ specifies how to import the mesh, the 
+\family typewriter
+problem
+\family default
+ specifies the physical properties, boundary conditions, etc., and 
+\family typewriter
+petsc
+\family default
+ is used to specify PETSc settings.
+ Appendix 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "cha:components"
+
+\end_inset
+
+ contains a list of the components provided by PyLith and spatialdata.
+\end_layout
+
+\begin_layout Subsection
+\begin_inset CommandInset label
+LatexCommand label
+name "sec:setting:parameters"
+
+\end_inset
+
+Setting PyLith Parameters
+\end_layout
+
+\begin_layout Standard
+There are several methods for setting input parameters for the 
+\family typewriter
+pylith
+\family default
+ executable: via the command line or by using a text file in 
+\family typewriter
+.cfg
+\family default
+ or 
+\family typewriter
+.pml
+\family default
+ format.
+ Both facilities and properties have default values provided, so you only
+ need to set values when you want to deviate from the default behavior.
+\end_layout
+
+\begin_layout Subsubsection
+Units
+\end_layout
+
+\begin_layout Standard
+All dimensional parameters require units.
+ The units are specified using Python and FORTRAN syntax, so square meters
+ is m**2.
+ Whitespace is not allowed in the string, for units and dimensioned quantities
+ are multiplied by the units string; for example, two meters per second
+ is 2.0*m/s.
+ Available units are shown in Table 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "tab:pyre:units"
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+\noindent
+\align center
+\begin_inset Float table
+placement H
+wide false
+sideways false
+status open
+
+\begin_layout Plain Layout
+\align center
+\begin_inset Caption
+
+\begin_layout Plain Layout
+\begin_inset CommandInset label
+LatexCommand label
+name "tab:pyre:units"
+
+\end_inset
+
+Pyre supported units.
+ Aliases are in parentheses.
+\end_layout
+
+\end_inset
+
+
+\begin_inset Tabular
+<lyxtabular version="3" rows="5" columns="2">
+<features tabularvalignment="middle">
+<column alignment="left" valignment="top" width="0.9in">
+<column alignment="left" valignment="top" width="4in">
+<row>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\series bold
+Scale
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\series bold
+Available Units
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+length
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+meter (m), micrometer (um, micron), millimeter (mm), centimeter (cm), kilometer
+ (km), inch, foot, yard, mile
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+time
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+second (s), nanosecond (ns), microsecond (us), millisecond (ms), minute,
+ hour, day, year
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+mass
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+kilogram (kg), gram (g), centigram (cg), milligram (mg), ounce, pound, ton
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+pressure
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+pascal (Pa), kPa, MPa, GPa, bar, millibar, atmosphere (atm)
+\end_layout
+
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Subsubsection
+Using the Command Line
+\end_layout
+
+\begin_layout Standard
+Pyre uses the following syntax to change properties from the command line.
+ To change the value of a property of a component, use:
+\end_layout
+
+\begin_layout LyX-Code
+
+\family typewriter
+--[component].[property]=[value]
+\end_layout
+
+\begin_layout Standard
+Each component is attached to a facility, so the option above can also be
+ written as: 
+\end_layout
+
+\begin_layout LyX-Code
+
+\family typewriter
+--[facility].[property]=[value]
+\end_layout
+
+\begin_layout Standard
+Each facility has a default component attached to it.
+ A different component can be attached to a facility by:
+\end_layout
+
+\begin_layout LyX-Code
+
+\family typewriter
+--[facility]=[new_component] 
+\end_layout
+
+\begin_layout Standard
+PyLith's command-line arguments can control Pyre and PyLith properties and
+ facilities, MPI settings, and PETSc settings.
+ You can get more information on the available options by typing
+\end_layout
+
+\begin_layout LyX-Code
+
+\family typewriter
+$ pylith --help
+\end_layout
+
+\begin_layout Standard
+All PyLith-related properties are associated with the 
+\family typewriter
+pylithapp
+\family default
+ component.
+ You can get a list of all of these top-level properties along with a descriptio
+n of what they do by running PyLith with the 
+\family typewriter
+--help-properties
+\family default
+ command-line argument.
+ To get information on user-configurable facilities and components, you
+ can run PyLith with the 
+\family typewriter
+--help-components
+\family default
+ command-line argument.
+ To find out about the properties associated with a given component, you
+ can run PyLith with the 
+\family typewriter
+--[component].help-properties
+\family default
+ flag:
+\end_layout
+
+\begin_layout LyX-Code
+$ pylith --problem.help-properties
+\end_layout
+
+\begin_layout Standard
+Each component may also have sub-components associated with it:
+\end_layout
+
+\begin_layout LyX-Code
+$ pylith -- problem.help-components
+\end_layout
+
+\begin_layout Standard
+By starting at the top-level components, you can determine the components
+ and properties at each level by working down to lower-level components:
+\end_layout
+
+\begin_layout LyX-Code
+$ pylith --problem.bc.help-components
+\end_layout
+
+\begin_layout LyX-Code
+$ pylith --problem.bc.help-properties
+\end_layout
+
+\begin_layout Standard
+Using the 
+\family typewriter
+--help-components
+\family default
+ and 
+\family typewriter
+--help-properties
+\family default
+ flags for the various components and sub-components is a good way to discover
+ potential problems in a simulation.
+\end_layout
+
+\begin_layout Subsubsection
+Using a 
+\family typewriter
+.cfg
+\family default
+ File
+\end_layout
+
+\begin_layout Standard
+Entering all those parameters via the command line involves the risk of
+ typographical errors, which can lead to undesired results.
+ You will generally find it easier to write a brief 
+\family typewriter
+.cfg
+\family default
+ input file that contains the parameters.
+ This file has a format similar to a Windows INI file.
+ The file is composed of one or more sections which are formatted as follows:
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.subcomponent1.subcomponent2]
+\end_layout
+
+\begin_layout LyX-Code
+# this is a comment
+\end_layout
+
+\begin_layout LyX-Code
+property1 = value1
+\end_layout
+
+\begin_layout LyX-Code
+property2 = value2 ; this is another comment
+\end_layout
+
+\begin_layout Standard
+We strongly recommend that you use 
+\family typewriter
+.cfg
+\family default
+ files for your work.
+ The files are syntax-colored in the vim editor.
+\end_layout
+
+\begin_layout Subsubsection
+Using a 
+\family typewriter
+.pml
+\family default
+ File
+\end_layout
+
+\begin_layout Standard
+A 
+\family typewriter
+.pml
+\family default
+ file is an XML file that specifies parameter values in a highly structured
+ format.
+ It is composed of nested sections which are formatted as follows:
+\end_layout
+
+\begin_layout LyX-Code
+<component name='component1'>
+\end_layout
+
+\begin_layout LyX-Code
+    <component name='component2'>
+\end_layout
+
+\begin_layout LyX-Code
+        <property name='property1'>value1</property>
+\end_layout
+
+\begin_layout LyX-Code
+        <property name='property2'>value2</property>
+\end_layout
+
+\begin_layout LyX-Code
+    </component>
+\end_layout
+
+\begin_layout LyX-Code
+</component>
+\end_layout
+
+\begin_layout Standard
+XML files are intended to be read and written by machines, not edited manually
+ by humans.
+ The 
+\family typewriter
+.pml
+\family default
+ file format is intended for applications in which PyLith input files are
+ generated by another program, e.g., a GUI, web application, or a high-level
+ structured editor.
+ This file format will not be discussed further here, but if you are interested
+ in using 
+\family typewriter
+.pml
+\family default
+ files, note that 
+\family typewriter
+.pml
+\family default
+ files and 
+\family typewriter
+.cfg
+\family default
+ files can be used interchangeably; in the following discussion, a file
+ with a 
+\family typewriter
+.pml
+\family default
+ extension can be substituted anywhere a 
+\family typewriter
+.cfg
+\family default
+ file can be used.
+\end_layout
+
+\begin_layout Subsubsection
+Specification and Placement of Configuration Files
+\end_layout
+
+\begin_layout Standard
+Configuration files may be specified on the command line:
+\end_layout
+
+\begin_layout LyX-Code
+$ pylith example.cfg
+\end_layout
+
+\begin_layout Standard
+In addition, the Pyre framework searches for configuration files named 
+\family typewriter
+pylithapp.cfg
+\family default
+ in several predefined locations.
+ You may put settings in any or all of these locations, depending on the
+ scope you want the settings to have:
+\end_layout
+
+\begin_layout Enumerate
+
+\family typewriter
+$PREFIX/etc/pylithapp.cfg
+\family default
+, for system-wide settings;
+\end_layout
+
+\begin_layout Enumerate
+
+\family typewriter
+$HOME/.pyre/pylithapp/pylithapp.cfg
+\family default
+, for user settings and preferences;
+\end_layout
+
+\begin_layout Enumerate
+the current directory (
+\family typewriter
+./pylithapp.cfg
+\family default
+), for local overrides.
+ 
+\end_layout
+
+\begin_layout Standard
+Parameters given directly on the command line will override any input contained
+ in a configuration file.
+ Configuration files given on the command line override all others.
+ The 
+\family typewriter
+pylithapp.cfg
+\family default
+ files placed in (3) will override those in (2), (2) overrides (1), and
+ (1) overrides only the built-in defaults.
+\end_layout
+
+\begin_layout Standard
+All of the example problems are set up using configuration files in the
+ example directory, and specific problems are defined by including the appropria
+te configuration file on the command-line.
+ Referring to the directory 
+\family typewriter
+examples/twocells/twohex8
+\family default
+, the following configuration files are present:
+\end_layout
+
+\begin_layout LyX-Code
+axialdisp.cfg
+\end_layout
+
+\begin_layout LyX-Code
+dislocation.cfg
+\end_layout
+
+\begin_layout LyX-Code
+pylithapp.cfg
+\end_layout
+
+\begin_layout LyX-Code
+sheardisp.cfg
+\end_layout
+
+\begin_layout Standard
+The settings in pylithapp.cfg will be read automatically, and additional
+ settings are included by specifying one of the other files on the command-line:
+\end_layout
+
+\begin_layout LyX-Code
+$ pylith axialdisp.cfg
+\end_layout
+
+\begin_layout Standard
+If you want to see what settings are being used, you can either examine
+ the 
+\family typewriter
+.cfg
+\family default
+ files, or use the help flags as described above:
+\end_layout
+
+\begin_layout LyX-Code
+$ pylith axialdisp.cfg --problem.help-components
+\end_layout
+
+\begin_layout LyX-Code
+$ pylith axialdisp.cfg --problem.help-properties
+\end_layout
+
+\begin_layout LyX-Code
+$ pylith axialdisp.cfg --problem.bc.help-components
+\end_layout
+
+\begin_layout LyX-Code
+$ pylith axialdisp.cfg --problem.bc.help-properties
+\end_layout
+
+\begin_layout Standard
+This is generally a more useful way of determining problem settings, since
+ it includes default values as well as those that have been specified in
+ the 
+\family typewriter
+.cfg
+\family default
+ file.
+\end_layout
+
+\begin_layout Subsubsection
+List of PyLith Parameters (
+\family typewriter
+pylithinfo
+\family default
+)
+\end_layout
+
+\begin_layout Standard
+The Python application 
+\family typewriter
+pylithinfo
+\family default
+ writes all of the current parameters to a text file.
+ The default name of the text file is 
+\family typewriter
+pylith_parameters.txt
+\family default
+.
+ The usage synopsis is
+\end_layout
+
+\begin_layout LyX-Code
+$ pylithinfo [--verbose] [--fileout=pylith_parameters.txt] [PyLith args]
+\end_layout
+
+\begin_layout Standard
+where 
+\family typewriter
+--verbose
+\family default
+ (or 
+\family typewriter
+-v
+\family default
+) turns on printing the descriptions of the properties and components as
+ well as the location where the current value was set, and 
+\family typewriter
+--fileout=pylith_parameters.txt
+\family default
+ (or 
+\family typewriter
+-o pylith_parameters.txt
+\family default
+) sets the name of the output file.
+ The lines in the text file are indented to show the hierarchy of the properties
+ and components.
+ 
+\end_layout
+
+\begin_layout Subsection
+Mesh Information (
+\family typewriter
+mesher
+\family default
+)
+\end_layout
+
+\begin_layout Standard
+Geometrical and topological information for the finite element mesh may
+ be provided by exporting an Exodus II format file from CUBIT, by exporting
+ a GMV file and an accompanying Pset file from LaGriT, or by specifying
+ the information in PyLith mesh ASCII format.
+ See Chapter 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "cha:Tutorials"
+
+\end_inset
+
+ for examples.
+\end_layout
+
+\begin_layout Standard
+PyLith supports linear cells in 1D (Figure 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "fig:1D-linear-elements"
+
+\end_inset
+
+), 2D (Figure 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "fig:2D-linear-elements"
+
+\end_inset
+
+), and 3D (Figure 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "fig:3D-linear-elements"
+
+\end_inset
+
+).
+ The vertex ordering must follow the convention shown in Figures 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "fig:1D-linear-elements"
+
+\end_inset
+
+-
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "fig:3D-linear-elements"
+
+\end_inset
+
+.
+ Quadratic cells are also supported, but at present the only method for
+ using these cells in PyLith is using PyLith ASCII format.
+ PyLith does not yet support automatic generation of a quadratic mesh from
+ the linear meshes created by CUBIT or LaGriT.
+\end_layout
+
+\begin_layout Standard
+The mesh information defines the vertex coordinates and specifies the vertices
+ composing each cell in the mesh.
+ The mesh information must also define at least one set of vertices for
+ which displacement (Dirichlet) boundary conditions will be provided.
+ In most realistic problems, there will be several vertex groups, each with
+ a unique identifying label.
+ For example, one group might define a surface of the mesh where displacement
+ (Dirichlet) boundary conditions will be applied, another might define a
+ surface where traction (Neumann) boundary conditions will be applied, while
+ a third might specify a surface that defines a fault.
+ Similarly, the mesh information contains cell labels that define the material
+ type for each cell in the mesh.
+ For a mesh with a single material type, there will only be a single label
+ for every cell in the mesh.
+ See Chapters 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "cha:material:models"
+
+\end_inset
+
+ and 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "cha:boundary:interface:conditions"
+
+\end_inset
+
+ for more detailed discussions of setting the materials and boundary conditions.
+\end_layout
+
+\begin_layout Standard
+\noindent
+\align center
+\begin_inset Float figure
+placement H
+wide false
+sideways false
+status open
+
+\begin_layout Plain Layout
+\noindent
+\align center
+\begin_inset Graphics
+	filename figs/bar2.eps
+
+\end_inset
+
+ 
+\end_layout
+
+\begin_layout Plain Layout
+\begin_inset Caption
+
+\begin_layout Plain Layout
+Linear bar cell available for 1D problems.
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Plain Layout
+\begin_inset CommandInset label
+LatexCommand label
+name "fig:1D-linear-elements"
+
+\end_inset
+
+ 
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+\noindent
+\align center
+\begin_inset Float figure
+placement H
+wide false
+sideways false
+status open
+
+\begin_layout Plain Layout
+\noindent
+\align center
+\begin_inset Graphics
+	filename figs/tri3.eps
+
+\end_inset
+
+
+\begin_inset ERT
+status open
+
+\begin_layout Plain Layout
+
+
+\backslash
+hspace*{0.5in}
+\end_layout
+
+\end_inset
+
+
+\begin_inset Graphics
+	filename figs/quad4.eps
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Plain Layout
+\begin_inset Caption
+
+\begin_layout Plain Layout
+Linear cells available for 2D problems are the triangle (left) and the quadrilat
+eral (right).
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Plain Layout
+\begin_inset CommandInset label
+LatexCommand label
+name "fig:2D-linear-elements"
+
+\end_inset
+
+ 
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+\noindent
+\align center
+\begin_inset Float figure
+placement H
+wide false
+sideways false
+status open
+
+\begin_layout Plain Layout
+\noindent
+\align center
+\begin_inset Graphics
+	filename figs/tet4.eps
+
+\end_inset
+
+
+\begin_inset ERT
+status open
+
+\begin_layout Plain Layout
+
+
+\backslash
+hspace*{0.5in}
+\end_layout
+
+\end_inset
+
+
+\begin_inset Graphics
+	filename figs/hex8.eps
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Plain Layout
+\begin_inset Caption
+
+\begin_layout Plain Layout
+Linear cells available for 3D problems are the tetrahedron (left) and the
+ hexahedron (right).
+\begin_inset CommandInset label
+LatexCommand label
+name "fig:3D-linear-elements"
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Subsubsection
+Mesh Importer
+\end_layout
+
+\begin_layout Standard
+The default mesher component is MeshImporter, which provides the capabilities
+ of reading the mesh from files.
+ The MeshImporter has several properties and facilities:
+\end_layout
+
+\begin_layout Description
+reorder_mesh Reorder the vertices and cells using the reverse Cuthill-McKee
+ algorithm (default is False).
+\end_layout
+
+\begin_layout Description
+reader Reader for a given type of mesh (default is MeshIOAscii).
+\end_layout
+
+\begin_layout Description
+distributor Handles distribution of the mesh among processors.
+\end_layout
+
+\begin_layout Description
+refiner Perform global uniform mesh refinement after distribution among
+ processors (default is False).
+\end_layout
+
+\begin_layout Standard
+Reordering the mesh so that vertices and cells connected topologically also
+ reside close together in memory improves overall performance and can improve
+ solver performance as well.
+\end_layout
+
+\begin_layout Quote
+
+\color red
+Note:
+\color inherit
+ The coordinate system associated with the mesh must be a Cartesian coordinate
+ system.
+ This includes generic Cartesian coordinate systems as well as geographic
+ projections.
+\end_layout
+
+\begin_layout Subsubsection
+MeshIOAscii
+\end_layout
+
+\begin_layout Standard
+The MeshIOAscii object is intended for reading small, simple ASCII files
+ containing a mesh constructed by hand.
+ We use this file format extensively in the examples.
+ Appendix 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "sec:MeshIOAscii"
+
+\end_inset
+
+ describes the format of the files.
+ The properties and facilities of the MeshIOAscii object include:
+\end_layout
+
+\begin_layout Description
+filename Name of the mesh file.
+\end_layout
+
+\begin_layout Description
+coordsys Coordinate system associated with the mesh.
+\end_layout
+
+\begin_layout Subsubsection
+\begin_inset CommandInset label
+LatexCommand label
+name "sec:MeshIOCubit"
+
+\end_inset
+
+MeshIOCubit
+\end_layout
+
+\begin_layout Standard
+The MeshIOCubit object reads the NetCDF Exodus II files output from CUBIT.
+ Beginning with CUBIT 11.0, the names of the nodesets are included in the
+ Exodus II files and PyLith can use these nodeset names or revert to using
+ the nodeset ids.
+ The properties and facilities associated with the MeshIOCubit object are:
+\end_layout
+
+\begin_layout Description
+filename Name of the Exodus II file.
+\end_layout
+
+\begin_layout Description
+use_nodeset_names Identify nodesets by name rather than id (default is True).
+\end_layout
+
+\begin_layout Description
+coordsys Coordinate system associated with the mesh.
+\end_layout
+
+\begin_layout Subsubsection
+\begin_inset CommandInset label
+LatexCommand label
+name "sec:MeshIOLagrit"
+
+\end_inset
+
+MeshIOLagrit
+\end_layout
+
+\begin_layout Standard
+The MeshIOLagrit object is used to read ASCII and binary GMV and PSET files
+ output from LaGriT.
+ PyLith will automatically detect whether the files are ASCII or binary.
+ We attempt to provide support for experimental 64-bit versions of LaGriT
+ via flags indicating whether the FORTRAN code is using 32-bit or 64-bit
+ integers.
+ The MeshIOLagrit properties and facilities are:
+\end_layout
+
+\begin_layout Description
+filename_gmv Name of GMV file.
+\end_layout
+
+\begin_layout Description
+filename_pset Name of the PSET file.
+\end_layout
+
+\begin_layout Description
+flip_endian Flip the endian of values when reading binary files (default
+ is False).
+\end_layout
+
+\begin_layout Description
+io_int32 Flag indicating that PSET files use 32-bit integers (default is
+ True).
+\end_layout
+
+\begin_layout Description
+record_header_32bt Flag indicating FORTRAN record header is 32-bit (default
+ is True)
+\end_layout
+
+\begin_layout Description
+coordsys Coordinate system associated with mesh.
+\end_layout
+
+\begin_layout Subsubsection
+Distributor
+\end_layout
+
+\begin_layout Standard
+The distributor users a partitioner to compute which cells should be placed
+ on each processor, computes the overlap among the processors, and then
+ distributes the mesh among the processors.
+ The properties and facilities of the Distributor include:
+\end_layout
+
+\begin_layout Description
+partitioner Choice of partitioner (
+\begin_inset Quotes eld
+\end_inset
+
+parmetis
+\begin_inset Quotes erd
+\end_inset
+
+ or 
+\begin_inset Quotes eld
+\end_inset
+
+chaco
+\begin_inset Quotes erd
+\end_inset
+
+, default is 
+\begin_inset Quotes eld
+\end_inset
+
+chaco
+\begin_inset Quotes erd
+\end_inset
+
+).
+\end_layout
+
+\begin_layout Description
+writer_partition Flag indicating that the partition information should be
+ written to a file (default is False).
+\end_layout
+
+\begin_layout Description
+data_writer Writer for partition information (default is DataWriterVTKMesh
+ for VTK output).
+\end_layout
+
+\begin_layout Standard
+ParMETIS is not included in the PyLith binaries due to licensing issues.
+\end_layout
+
+\begin_layout Subsubsection
+Refiner
+\end_layout
+
+\begin_layout Standard
+The refiner is used to decrease node spacing by a factor of two by subdividing
+ each cell.
+ In a 2D triangular mesh a node is inserted at the midpoint of each edge,
+ splitting each cell into four cells (see Figure 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "fig:uniform:refinement:2x"
+
+\end_inset
+
+).
+ In a 2D quadrilateral mesh a node is inserted at the midpoint of each edge
+ and at the centroid of the cell, splitting each cell into four cells.
+ In a 3D tetrahedral mesh a node is inserted at the midpoint of each edge,
+ splitting each cell into eight cells.
+ In a 3D hexahedral mesh a node is inserted at the midpoint of each edge,
+ the centroid of each face, and at the centroid of the cell, splitting each
+ cell into eight cells.
+\end_layout
+
+\begin_layout Standard
+\noindent
+\align center
+\begin_inset Float figure
+placement H
+wide false
+sideways false
+status open
+
+\begin_layout Plain Layout
+\noindent
+\align center
+\begin_inset Graphics
+	filename figs/refinement2x.eps
+	scale 125
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Plain Layout
+\begin_inset Caption
+
+\begin_layout Plain Layout
+Global uniform mesh refinement of 2D and 3D linear cells.
+ The blue lines and orange circles identify the edges and vertices in the
+ original cells.
+ The purple lines and green circles identify the new edges and vertices
+ added to the original cells to refine the mesh by a factor of two.
+\begin_inset CommandInset label
+LatexCommand label
+name "fig:uniform:refinement:2x"
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+Refinement occurs after distribution of the mesh among processors.
+ This allows one to run much larger simulations by (1) permitting the mesh
+ generator to construct a mesh with a node spacing twice as large as that
+ needed in the simulation and (2) operations performed in serial during
+ the simulation setup phase, such as, adjusting the topology to insert cohesive
+ cells and distribution of the mesh among processors uses this much smaller
+ coarse mesh.
+ For 2D problems the global mesh refinement increases the maximum problem
+ size by a factor of four, and for 3D problems it increases the maximum
+ problem size by a factor of eight.
+\end_layout
+
+\begin_layout Subsection
+Problem Specification (
+\family typewriter
+problem
+\family default
+)
+\end_layout
+
+\begin_layout Standard
+The problem component specifies the basic parameters of the simulation,
+ including the physical properties, the boundary conditions, and interface
+ conditions (faults).
+ The current release of PyLith contains two types of problem, 
+\family typewriter
+TimeDependent
+\family default
+ for use in static, quasi-static, and dynamic simulations and 
+\family typewriter
+GreensFns
+\family default
+ for computing static Green's functions.
+ The general facilities include:
+\end_layout
+
+\begin_layout Description
+normalizer Scales used to nondimensionalize the problem (default is NondimElasti
+cQuasistatic).
+\end_layout
+
+\begin_layout Description
+materials Array of materials comprising the domain (default is 
+\family typewriter
+[material]
+\family default
+).
+\end_layout
+
+\begin_layout Description
+bc Array of boundary conditions (default is none).
+\end_layout
+
+\begin_layout Description
+interfaces Array of interface conditions, i.e., faults (default is none).
+\end_layout
+
+\begin_layout Description
+gravity_field Gravity field used to construct body forces (default is none).
+\end_layout
+
+\begin_layout Standard
+The properties for each material group are:
+\end_layout
+
+\begin_layout Description
+dimension Spatial dimension of the problem (default is 3)
+\end_layout
+
+\begin_layout Standard
+An example of setting these parameters in a 
+\family typewriter
+.cfg
+\family default
+ file for a problem is:
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.timedependent]
+\end_layout
+
+\begin_layout LyX-Code
+dimension = 3
+\end_layout
+
+\begin_layout LyX-Code
+normalizer = spatialdata.units.NondimElasticQuasistatic
+\end_layout
+
+\begin_layout LyX-Code
+materials = [elastic,viscoelastic]
+\end_layout
+
+\begin_layout LyX-Code
+bc = [boundary_east,boundary_bottom,boundary_west]
+\end_layout
+
+\begin_layout LyX-Code
+interfaces = [SanAndreas,SanJacinto]
+\end_layout
+
+\begin_layout LyX-Code
+gravity_field = spatialdata.spatialdb.GravityField
+\end_layout
+
+\begin_layout Subsubsection
+Nondimensionalization
+\end_layout
+
+\begin_layout Standard
+PyLith nondimensionalizes all parameters provided by the user so that the
+ simulation solves the equations using nondimensional quantities.
+ This permits application of PyLith to problems across a vast range of spatial
+ and temporal scales.
+ The scales used to nondimensionalize the problem are length, pressure,
+ density, and time.
+ PyLith provides two normalizer objects to make it easy to provide reasonable
+ scales for the nondimensionalization.
+ The 
+\family typewriter
+NondimElasticQuasistatic
+\family default
+ normalizer has the following properties:
+\end_layout
+
+\begin_layout Description
+length_scale Length to nondimensionalize length (default is 1.0 km).
+\end_layout
+
+\begin_layout Description
+shear_modulus Shear modulus to nondimensionalize pressure (default is 3.0e+10
+ Pa).
+\end_layout
+
+\begin_layout Description
+relaxation_time Relaxation time to nondimensionalize time (default is 1.0
+ year).
+\end_layout
+
+\begin_layout Standard
+An example of setting these parameters in a 
+\family typewriter
+.cfg
+\family default
+ file for a problem is:
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.timedependent.normalizer]
+\end_layout
+
+\begin_layout LyX-Code
+length_scale = 1.0*km
+\end_layout
+
+\begin_layout LyX-Code
+shear_modules = 3.0e+10*Pa
+\end_layout
+
+\begin_layout LyX-Code
+relaxation_time = 1.0*yr
+\end_layout
+
+\begin_layout Standard
+The 
+\family typewriter
+NondimElasticDynamic
+\family default
+ normalizer has the following properties:
+\end_layout
+
+\begin_layout Description
+shear_wave_speed Shear wave speed used to nondimensionalize length and pressure
+ (default is 3.0 km/s).
+\end_layout
+
+\begin_layout Description
+mass_density Mass density to nondimensionalize density and pressure (default
+ is 3.0e+3 kg/m
+\begin_inset Formula $^{3}$
+\end_inset
+
+).
+\end_layout
+
+\begin_layout Description
+wave_period Period of seismic waves used to nondimensionalize time (default
+ is 1.0 s).
+\end_layout
+
+\begin_layout Standard
+An example of setting these parameters in a 
+\family typewriter
+.cfg
+\family default
+ file for a problem is:
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.timedependent.normalizer]
+\end_layout
+
+\begin_layout LyX-Code
+shear_wave_speed = 3.0*km/s
+\end_layout
+
+\begin_layout LyX-Code
+mass_density = 3.0e+3*kg/m**3
+\end_layout
+
+\begin_layout LyX-Code
+wave_period = 1.0*s
+\end_layout
+
+\begin_layout Subsection
+Finite-Element Integration Settings
+\end_layout
+
+\begin_layout Standard
+PyLith uses numerical quadrature to evaluate the finite-element integrals
+ for the residual and system Jacobian (see Chapter 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "cha:Governing-Equations"
+
+\end_inset
+
+).
+ PyLith employs FIAT (finite element automatic tabulator) to compute the
+ basis functions and their derivatives at the quadrature points for various
+ quadrature schemes and cell shapes.
+ The parameters for Lagrange cells (lines, quadrilaterals, hexahedra) are
+ specified using the FIATLagrange object, whereas the parameters for Simplex
+ cells (lines, triangles, tetrahedra) are specified using the FIATSimplex
+ object.
+ Both objects use the same set of parameters and PyLith will setup the basis
+ functions and quadrature scheme appropriately for the two families of cells.
+ The quadrature scheme and basis functions must be set for each material
+ and boundary condition involving finite-element integrations (Dirichlet
+ boundary conditions are constraints and do not involve integrations).
+ Furthermore, the integration schemes can be set independently.
+ The current version of PyLith supports basis functions with linear variations
+ in the field (P1); support for higher order cells will be added in the
+ future.
+ The properties for the FIATLagrange and FIATSimplex objects are
+\end_layout
+
+\begin_layout Description
+dimension Dimension of the cell (0,1,2,3; default is 3).
+\end_layout
+
+\begin_layout Description
+degree Degree of the finite-element cell (default is 1).
+\end_layout
+
+\begin_layout Description
+order Order of quadrature rule (default is degree+1); hardwired to be equal
+ to degree for faults.
+\end_layout
+
+\begin_layout Description
+collocate_quad Collocate quadrature points with vertices (default is False);
+ hardwired to True for faults.
+\end_layout
+
+\begin_layout Standard
+See Section 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "sec:material:parameters"
+
+\end_inset
+
+ for an example of setting these properties for a material.
+\end_layout
+
+\begin_layout Subsection
+\begin_inset CommandInset label
+LatexCommand label
+name "sec:petsc:options"
+
+\end_inset
+
+PETSc Settings (
+\family typewriter
+petsc
+\family default
+)
+\end_layout
+
+\begin_layout Standard
+In quasti-static problems with implicit time-stepping, PyLith relies on
+ PETSc for the linear algebra computations, including linear Krylov subspace
+ solvers and nonlinear solvers.
+ For dynamic problems, lumping the mass matrix and using explicit time-stepping
+ is much more efficient; this permits solving the linear system with a trivial
+ solver so we do not use a PETSc solver in this case (see Section 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "sec:solvers"
+
+\end_inset
+
+).
+\end_layout
+
+\begin_layout Standard
+PETSc options can be set in 
+\family typewriter
+.cfg
+\family default
+ files in sections beginning with 
+\family typewriter
+[pylithapp.petsc]
+\family default
+.
+ The options of primary interest in the case of PyLith are shown in Table
+\begin_inset space ~
+\end_inset
+
+
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "tab:petsc:options:defaults"
+
+\end_inset
+
+.
+ PETSc options are used to control the selection and settings for the solvers
+ underlying the SolverLinear and SolverNonlinear objects discussed in Section
+ 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "sec:solvers"
+
+\end_inset
+
+.
+ A very wide range of elasticity problems in quasi-static simulations can
+ be solved with reasonable runtimes by replacing the default Jacobi precondition
+er with the Additive Schwarz Method (ASM) using Incomplete LU (ILU) factorizatio
+n by default (see Table
+\begin_inset space ~
+\end_inset
+
+
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "tab:petsc:options:recommended"
+
+\end_inset
+
+).
+ A more advanced set of solver settings that may provide better performance
+ in many elasticity problems are given in Table 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "tab:petsc:options:advanced"
+
+\end_inset
+
+.
+ These settings are limited to problems where we store the stiffness matrix
+ as a nonsymmetric sparse matrix and require additional settings for the
+ formulation,
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.timedependent.formulation]
+\end_layout
+
+\begin_layout LyX-Code
+split_fields = True
+\end_layout
+
+\begin_layout LyX-Code
+use_custom_constraint_pc = True ; Use only if problem contains a fault
+\end_layout
+
+\begin_layout LyX-Code
+matrix_type = aij
+\end_layout
+
+\begin_layout Quote
+
+\series bold
+\color red
+Warning:
+\color inherit
+ 
+\series default
+\color none
+These settings are only available if you build PETSc with Fortran enabled
+ and the ML package.
+ These features are included in the PyLith binary packages.
+\end_layout
+
+\begin_layout Quote
+
+\series bold
+\color red
+Warning:
+\color inherit
+ 
+\series default
+\color none
+The split fields and algebraic multigrid preconditioning currently fails
+ in problems with a nonzero null space.
+ This most often occurs when a problem contains multiple faults that extend
+ through the entire domain and create subdomains without any Dirichlet boundary
+ conditions.
+ The current workaround is to use the 
+\color inherit
+Additive Schwarz 
+\color none
+preconditioner without split fields.
+ See Section 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "sec:Troubleshooting"
+
+\end_inset
+
+ for the error message encountered in this situation.
+ 
+\end_layout
+
+\begin_layout Standard
+These more advanced settings allow the displacement fields and Lagrange
+ multipliers for fault tractions to be preconditioned separately.
+ This usually results in a much stronger preconditioner.
+ In simulations with fault slip, the degrees of freedom associated with
+ the Lagrange multipliers should be preconditioned with a custom preconditioner
+ that uses a diagonal approximation of the Schur complement.
+\end_layout
+
+\begin_layout Standard
+\noindent
+\align center
+\begin_inset Float table
+placement H
+wide false
+sideways false
+status open
+
+\begin_layout Plain Layout
+\align center
+\begin_inset Caption
+
+\begin_layout Plain Layout
+\begin_inset CommandInset label
+LatexCommand label
+name "tab:petsc:options:defaults"
+
+\end_inset
+
+Useful command-line arguments for setting PETSc options.
+\end_layout
+
+\end_inset
+
+
+\begin_inset Tabular
+<lyxtabular version="3" rows="10" columns="3">
+<features tabularvalignment="middle">
+<column alignment="left" valignment="top" width="1.2in">
+<column alignment="center" valignment="middle" width="0.6in">
+<column alignment="left" valignment="top" width="3.8in">
+<row>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\series bold
+Property
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\series bold
+Default Value
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\series bold
+Description
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+log_summary
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\shape italic
+false
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Print logging objects and events.
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+ksp_monitor
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\shape italic
+false
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Dump preconditioned residual norm to stdout.
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+ksp_view
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\shape italic
+false
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Print linear solver parameters.
+ 
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+ksp_rtol
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\shape italic
+1.0e-05
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Convergence tolerance for relative decrease in residual norm.
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+snes_monitor
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\shape italic
+false
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Dump residual norm to stdout for each nonlinear solve iteration.
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+snes_view
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\shape italic
+false
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Print nonlinear solver parameters.
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+snes_rtol
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\shape italic
+1.0e-5
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Convergence tolerance for relative decrease in residual norm.
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+pc_type
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\shape italic
+jacobi
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Set preconditioner type.
+ See 
+\begin_inset CommandInset href
+LatexCommand href
+name "PETSc documentation"
+target "http://www.mcs.anl.gov/petsc/petsc-as/documentation/linearsolvertable.html"
+
+\end_inset
+
+ for a list of all preconditioner types.
+ 
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+ksp_type
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\shape italic
+gmres
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Set linear solver type.
+ See 
+\begin_inset CommandInset href
+LatexCommand href
+name "PETSc documentation"
+target "http://www.mcs.anl.gov/petsc/petsc-as/documentation/linearsolvertable.html"
+
+\end_inset
+
+ for a list of all solver types.
+\end_layout
+
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\begin_inset Float table
+placement H
+wide false
+sideways false
+status open
+
+\begin_layout Plain Layout
+\align center
+\begin_inset Caption
+
+\begin_layout Plain Layout
+\begin_inset CommandInset label
+LatexCommand label
+name "tab:petsc:options:recommended"
+
+\end_inset
+
+PETSc options that provide moderate performance in a wide range of quasi-static
+ elasticity problems.
+\end_layout
+
+\end_inset
+
+
+\begin_inset Tabular
+<lyxtabular version="3" rows="13" columns="3">
+<features tabularvalignment="middle">
+<column alignment="left" valignment="top" width="2in">
+<column alignment="center" valignment="middle" width="0.75in">
+<column alignment="left" valignment="top" width="3in">
+<row>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\series bold
+Property
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\series bold
+Value
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\series bold
+Description
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+pc_type
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\shape italic
+asm
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Additive Schwarz method.
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+ksp_type
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\shape italic
+gmres
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+GMRES method from Saad and Schultz.
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+sub_pc_factor_shift_type
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\emph on
+nonzero
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Turn on nonzero shifting for factorization.
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+ksp_max_it
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\emph on
+100
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Maximum number of iterations permitted in linear solve.
+ Depends on problem size.
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+ksp_gmres_restart
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\shape italic
+50
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Number of iterations after which Gram-Schmidt orthogonalization is restarted.
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+ksp_rtol
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\shape italic
+1.0e-08
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Linear solve convergence tolerance for relative decrease in residual norm.
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+ksp_atol
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\shape italic
+\emph on
+1.0e-12
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Linear solve convergence tolerance for absolute value of residual norm.
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+ksp_converged_reason
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\shape italic
+true
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Indicate why iterating stopped in linear solve.
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+snes_max_it
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\shape italic
+100
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Maximum number of iterations permitted in nonlinear solve.
+ Depends on how nonlinear the problem is.
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+snes_rtol
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\shape italic
+1.0e-08
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Nonlinear solve convergence tolerance for relative decrease in residual
+ norm.
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+snes_atol
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\shape italic
+1.0e-12
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Nonlinear solve convergence tolerance for absolute value of residual norm.
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+snes_converged_reason
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\shape italic
+true
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Indicate why iterating stopped in nonlinear solve.
+\end_layout
+
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+\noindent
+\align center
+\begin_inset Float table
+placement H
+wide false
+sideways false
+status open
+
+\begin_layout Plain Layout
+\align center
+\begin_inset Caption
+
+\begin_layout Plain Layout
+\begin_inset CommandInset label
+LatexCommand label
+name "tab:petsc:options:advanced"
+
+\end_inset
+
+PETSc options used with split fields algebraic multigrid preconditioning
+ that often provide improved performance in quasi-static elasticity problems.
+\end_layout
+
+\end_inset
+
+
+\begin_inset Tabular
+<lyxtabular version="3" rows="8" columns="3">
+<features tabularvalignment="middle">
+<column alignment="left" valignment="top" width="2.25in">
+<column alignment="center" valignment="middle" width="0.75in">
+<column alignment="left" valignment="top" width="3in">
+<row>
+<cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\series bold
+Property
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\series bold
+Value
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\series bold
+Description
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+fs_pc_type
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\shape italic
+field_split
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Precondition fields separately.
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+fs_pc_fieldsplit_real_diagonal
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\shape italic
+true
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Use diagonal blocks from the true operator, rather than the preconditioner.
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+fs_pc_fieldsplit_type
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\shape italic
+multiplicative
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Apply each field preconditioning in sequence, which is stronger than all-at-once
+ (additive).
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+fs_fieldsplit_0_pc_type
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\shape italic
+ml
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Multilevel algebraic multigrid preconditioning using Trilinos/ML via PETSc.
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+fs_fieldsplit_1_pc_type
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\shape italic
+jacobi
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Jacobi preconditioning for Lagrange multiplier block (only use if there
+ is at least one fault)
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+fs_fieldsplit_0_ksp_type
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\shape italic
+preonly
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Apply only the preconditioner.
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\family typewriter
+fs_fieldsplit_1_ksp_type
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\shape italic
+preonly
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Apply only the preconditioner.
+\end_layout
+
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Subsubsection
+PETSc Solvers and nVidia GPUs
+\end_layout
+
+\begin_layout Standard
+The development version of PETSc contains some support for using PETSc solvers
+ and nVidia GPUs via CUDA.
+ Building PETSc requires some additional dependencies as described in 
+\begin_inset Flex URL
+status collapsed
+
+\begin_layout Plain Layout
+
+http://www.mcs.anl.gov/petsc/documentation/installation.html#CUDA
+\end_layout
+
+\end_inset
+
+.
+ Additionally, PyLith must be configured with the 
+\family typewriter
+--enable-cuda
+\family default
+ option.
+ See the PyLith Installer documentation for how to enable support for CUDA
+ when building PETSc and PyLith with the installer (the installer does not
+ install CUDA or cusp).
+\end_layout
+
+\begin_layout Quote
+
+\series bold
+\color red
+Warning:
+\color inherit
+ 
+\series default
+\color none
+Development of PETSc solvers leveraging nVidia GPUs to accelerate the computatio
+ns is still a work in progress.
+ This feature requires building PETSc and PyLith from source after installing
+ CUDA and the development version of cusp.
+ If your GPU only supports single-precision floating point operations, then
+ PETSc must be built with single precision and without support for ML and
+ ParMetis/Metis.
+\end_layout
+
+\begin_layout Standard
+Solver and preconditioning options are relatively limited when using CUDA.
+ CUDA works with the Additive Schwarz preconditioner and GMRES linear solver.
+ Enabling use of CUDA with the PETSc solver involves just one setting:
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.problem.formulation.solver]
+\begin_inset Newline newline
+\end_inset
+
+use_cuda = True
+\end_layout
+
+\begin_layout Standard
+If the matrix type and vector types have not already been set, this will
+ set matrix type and vector types to 
+\family typewriter
+aijcusp
+\family default
+ and 
+\family typewriter
+cusp
+\family default
+, respectively, to indicate to PETSc that CUDA should be used by the solver.
+ If they have already been set to a value, then the values will not be changed
+ even if they are incompatible with using CUDA.
+\end_layout
+
+\begin_layout Section
+Time-Dependent Problem
+\end_layout
+
+\begin_layout Standard
+This type of problem applies to transient static, quasi-static, and dynamic
+ simulations.
+ The time-dependent problem adds the 
+\family typewriter
+formulation
+\family default
+ facility to the general-problem.
+ The formulation specifies the time-stepping formulation to integrate the
+ elasticity equation.
+ PyLith provides several alternative formulations, each specific to a different
+ type of problem.
+\end_layout
+
+\begin_layout Description
+Implicit Implicit time stepping for static and quasi-static problems with
+ infinitesimal strains.
+ The implicit formulation neglects inertial terms (see Section 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "eq:elasticity:integral:quasistatic"
+
+\end_inset
+
+).
+ 
+\end_layout
+
+\begin_layout Description
+ImplicitLgDeform Implicit time stepping for static and quasi-static problems
+ including the effects of rigid body motion and small strains.
+ This formulation requires the use of the nonlinear solver, which is selected
+ automatically.
+\end_layout
+
+\begin_layout Description
+Explicit Explicit time stepping for dynamic problems with infinitesimal
+ strains.
+ This formulation uses consistent mass and damping matrices for the system
+ Jacobian matrix.
+\end_layout
+
+\begin_layout Description
+ExplicitLgDeform Explicit time stepping for dynamic problems including the
+ effects of rigid body motion and small strains.
+ This formulation requires the use of the nonlinear solver, which is selected
+ automatically.
+\end_layout
+
+\begin_layout Description
+ExplicitLumped Explicit time stepping for dynamic problems with infinitesimal
+ strains and lumped system Jacobian.
+ The cell matrices are lumped before assembly, permitting use of a vector
+ for the diagonal system Jacobian matrix.
+ The built-in lumped solver is selected automatically.
+\end_layout
+
+\begin_layout Description
+ExplicitLumpedTri3 Optimized elasticity formulation for linear triangular
+ cells with one point quadrature for dynamic problems with infinitesimal
+ strains and lumped system Jacobian.
+ The built-in lumped solver is selected automatically.
+\end_layout
+
+\begin_layout Description
+ExplicitLumpedTet4 Optimized elasticity formulation for linear tetrahedral
+ cells with one point quadrature for dynamic problems with infinitesimal
+ strains and lumped system Jacobian.The built-in lumped solver is selected
+ automatically.
+\end_layout
+
+\begin_layout Standard
+In many quasi-static simulations it is convenient to compute a static problem
+ with elastic deformation prior to computing a transient response.
+ Up through PyLith version 1.6 this was hardwired into the Implicit Forumulation
+ as advancing from time step 
+\begin_inset Formula $t=-\Delta t$
+\end_inset
+
+ to 
+\begin_inset Formula $t=0$
+\end_inset
+
+, and it could not be turned off.
+ PyLith now includes a property, 
+\family typewriter
+elastic_prestep
+\family default
+ in the TimeDependent component to turn on/off this behavior (the default
+ is to retain the previous behavior of computing the elastic deformation).
+ 
+\end_layout
+
+\begin_layout Quote
+
+\series bold
+\color red
+Warning:
+\color inherit
+ 
+\series default
+\color none
+Turning off the elastic prestep calculation means the model only deforms
+ when an 
+\family typewriter
+\shape italic
+\color inherit
+increment
+\family default
+\shape default
+\color none
+ in loading or deformation is applied, because we the time-stepping formulation
+ is implemented using the increment in displacement.
+\end_layout
+
+\begin_layout Standard
+The TimeDependent properties and facilities include
+\end_layout
+
+\begin_layout Description
+elastic_preset If true, perform a static calculation with elastic behavior
+ before time stepping (default is True).
+\end_layout
+
+\begin_layout Description
+formulation Formulation for solving the partial differential equation.
+\end_layout
+
+\begin_layout Standard
+An example of setting the properties and components in a .cfg file is
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.timedependent]
+\end_layout
+
+\begin_layout LyX-Code
+formulation = pylith.problems.Implicit ; default
+\end_layout
+
+\begin_layout LyX-Code
+elastic_preset = True ; default
+\end_layout
+
+\begin_layout Standard
+The formulation value can be set to the other formulations in a similar
+ fashion.
+ 
+\end_layout
+
+\begin_layout Subsection
+Time-Stepping Formulation
+\end_layout
+
+\begin_layout Standard
+The explicit and implicit time stepping formulations use a common set of
+ facilities and properties.
+ The facilities include
+\end_layout
+
+\begin_layout Description
+time_step Time step size specification (default is uniform time step).
+\end_layout
+
+\begin_layout Description
+solver Type of solver to use (default is SolverLinear).
+\end_layout
+
+\begin_layout Description
+output Array of output managers for output of the solution (default is [output]).
+\end_layout
+
+\begin_layout Description
+jacobian_viewer Viewer to dump the system Jacobian (sparse matrix) to a
+ file for analysis (default is PETSc binary).
+\end_layout
+
+\begin_layout Standard
+The formulation properties include
+\end_layout
+
+\begin_layout Description
+matrix_type Type of PETSc matrix for the system Jacobian (sparse matrix,
+ default is symmetric, block matrix with a block size of 1).
+\end_layout
+
+\begin_layout Description
+view_jacobian Flag to indicate if system Jacobian (sparse matrix) should
+ be written to a file (default is false).
+\end_layout
+
+\begin_layout Description
+split_fields Split solution field into a displacement portion (fields 0..ndim-1)
+ and a Lagrange multiplier portion (field ndim) to permit application of
+ sophisticated PETSc preconditioners (default is false).
+\end_layout
+
+\begin_layout Standard
+An example of setting these parameters in a 
+\family typewriter
+.cfg
+\family default
+ file is
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.timedependent.formulation]
+\end_layout
+
+\begin_layout LyX-Code
+time_step = pylith.problems.TimeStepUniform
+\end_layout
+
+\begin_layout LyX-Code
+solver = pylith.problems.SolverLinear ; Nonlinear solver is pylith.problems.SolverNo
+nlinear
+\end_layout
+
+\begin_layout LyX-Code
+output = [domain,ground_surface]
+\end_layout
+
+\begin_layout LyX-Code
+matrix_type = sbaij ; To use a non-symmetric sparse matrix, set it to aij
+\end_layout
+
+\begin_layout LyX-Code
+view_jacobian = false
+\end_layout
+
+\begin_layout Subsection
+Numerical Damping in Explicit Time Stepping
+\end_layout
+
+\begin_layout Standard
+In explicit time-stepping formulations for elasticity, boundary conditions
+ and fault slip can excite short waveform elastic waves that are not accurately
+ resolved by the discretization.
+ We use numerical damping via an artificial viscosity
+\begin_inset CommandInset citation
+LatexCommand cite
+key "Knopoff:Ni:2001,Day:Ely:2002"
+
+\end_inset
+
+ to reduce these high frequency oscillations.
+ In computing the strains for the elasticity term in equation 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "eq:elasticity:integral:dynamic:t"
+
+\end_inset
+
+, we use an adjusted displacement rather than the actual displacement, where
+ 
+\begin_inset Formula 
+\begin{equation}
+\vec{u}^{adj}(t)=\vec{u}(t)+\eta^{*}\Delta t\vec{\dot{u}}(t),
+\end{equation}
+
+\end_inset
+
+
+\begin_inset Formula $\vec{u}^{adj}(t)$
+\end_inset
+
+ is the adjusted displacement at time t, 
+\begin_inset Formula $\vec{u}(t)$
+\end_inset
+
+is the original displacement at time (t), 
+\begin_inset Formula $\eta^{*}$
+\end_inset
+
+is the normalized artificial viscosity, 
+\begin_inset Formula $\Delta t$
+\end_inset
+
+ is the time step, and 
+\begin_inset Formula $\vec{\dot{u}}(t)$
+\end_inset
+
+ is the velocity at time 
+\begin_inset Formula $t$
+\end_inset
+
+.
+ The default value for the normalized artificial viscosity is 0.1.
+ We have found values in the range 0.1-0.4 sufficiently suppress numerical
+ noise while not excessively reducing the peak velocity.
+ An example of setting the normalized artificial viscosity in a 
+\family typewriter
+.cfg
+\family default
+ file is
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.timedependent.formulation]
+\end_layout
+
+\begin_layout LyX-Code
+norm_viscosity = 0.2
+\end_layout
+
+\begin_layout Subsection
+\begin_inset CommandInset label
+LatexCommand label
+name "sec:solvers"
+
+\end_inset
+
+Solvers
+\end_layout
+
+\begin_layout Standard
+PyLith supports three types of solvers.
+ The linear solver, SolverLinear, corresponds to the PETSc KSP solver and
+ is used in linear problems with linear elastic and viscoelastic bulk constituti
+ve models and kinematic fault ruptures.
+ The nonlinear solver, SolverNonlinear, corresponds to the PETSc SNES solver
+ and is used in nonlinear problems with nonlinear viscoelastic or elastoplastic
+ bulk constitutive models, dynamic fault ruptures, or problems involving
+ finite strain (small strain formulation).
+ The lumped solver (SolverLumped) is a specialized solver used with the
+ lumped system Jacobian matrix.
+ The options for the PETSc KSP and SNES solvers are set via the top-level
+ PETSc options (see Section 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "sec:petsc:options"
+
+\end_inset
+
+ and the PETSc documentation 
+\begin_inset Flex URL
+status collapsed
+
+\begin_layout Plain Layout
+
+www.mcs.anl.gov/petsc/petsc-as/documentation/index.html
+\end_layout
+
+\end_inset
+
+).
+\end_layout
+
+\begin_layout Subsection
+Time Stepping
+\end_layout
+
+\begin_layout Standard
+PyLith provides three choices for controlling the time step in time-dependent
+ simulations.
+ These include (1) a uniform, user-specified time step (which is the default),
+ (2) nonuniform, user-specified time steps, and (3) nonuniform, automatically
+ calculated time steps.
+ The procedure for automatically selecting time steps requires that the
+ material models provide a reasonable estimate of the time step for stable
+ time integration.
+ In general, quasi-static simulations should use automatically calculated
+ time steps and dynamic simulations should use a uniform, user-specified
+ time step.
+\end_layout
+
+\begin_layout Standard
+
+\series bold
+\color red
+Warning:
+\series default
+\color none
+ 
+\color inherit
+Changing the time step requires recomputing the Jacobian of the system,
+ which can greatly increase the runtime if the time-step size changes frequently.
+\end_layout
+
+\begin_layout Subsubsection
+Uniform, User-Specified Time Step
+\end_layout
+
+\begin_layout Standard
+With a uniform, user-specified time step, the user selects the time step
+ that is used over the entire duration of the simulation.
+ This value is used whether or not it yields a stable solution, so users
+ should be careful when selecting the time-step value.
+ The properties for the uniform, user-specified time step are:
+\end_layout
+
+\begin_layout Description
+total_time Time duration for simulation (default is 0.0 s).
+\end_layout
+
+\begin_layout Description
+start_time Start time for simulation (default is 0.0 s)
+\end_layout
+
+\begin_layout Description
+dt Time step for simulation.
+\end_layout
+
+\begin_layout Standard
+An example of setting a uniform, user-specified time step in a 
+\family typewriter
+.cfg
+\family default
+ file is:
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.problem.formulation]
+\end_layout
+
+\begin_layout LyX-Code
+time_step = pylith.problems.TimeStepUniform ; Default value
+\end_layout
+
+\begin_layout LyX-Code
+
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.problem.formulation.time_step]
+\end_layout
+
+\begin_layout LyX-Code
+total_time = 1000.0*year
+\end_layout
+
+\begin_layout LyX-Code
+dt = 0.5*year
+\end_layout
+
+\begin_layout Subsubsection
+Nonuniform, User-Specified Time Step
+\end_layout
+
+\begin_layout Standard
+The nonuniform, user-specified, time-step implementation allows the user
+ to specify the time steps in an ASCII file (see Section 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "sec:FileFormat:TimeStepUser"
+
+\end_inset
+
+ for the format specification of the time-step file).
+ If the total duration exceeds the time associated with the time steps,
+ then a flag determines whether to cycle through the time steps or to use
+ the last specified time step for the time remaining.
+ The properties for the nonuniform, user-specified time step are:
+\end_layout
+
+\begin_layout Description
+total_time Time duration for simulation.
+\end_layout
+
+\begin_layout Description
+filename Name of file with time-step sizes.
+\end_layout
+
+\begin_layout Description
+loop_steps If true, cycle through time steps, otherwise keep using last
+ time-step size for any time remaining.
+\end_layout
+
+\begin_layout Standard
+An example of setting the properties for nonuniform, user-specified time
+ steps in a 
+\family typewriter
+.cfg
+\family default
+ file is:
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.problem.formulation]
+\end_layout
+
+\begin_layout LyX-Code
+time_step = pylith.problems.TimeStepUser ; Change the time step algorithm
+\end_layout
+
+\begin_layout LyX-Code
+
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.problem.formulation.time_step]
+\end_layout
+
+\begin_layout LyX-Code
+total_time = 1000.0*year
+\end_layout
+
+\begin_layout LyX-Code
+filename = timesteps.txt
+\end_layout
+
+\begin_layout LyX-Code
+loop_steps = false ; Default value
+\end_layout
+
+\begin_layout Subsubsection
+Nonuniform, Automatic Time Step
+\end_layout
+
+\begin_layout Standard
+This time-step implementation automatically calculates a stable time step
+ based on the constitutive model and rate of deformation.
+ As a result, this choice for choosing the time step relies on accurate
+ calculation of a stable time step within each finite-element cell by the
+ constitutive models.
+ In order to provide some control over the time-step selection, the user
+ can control the frequency that a new time step is calculated, the time
+ step to use relative to the value determined by the constitutive models,
+ and a maximum value for the time step.
+ The properties for controlling the automatic time-step selection are:
+\end_layout
+
+\begin_layout Description
+total_time Time duration for simulation.
+\end_layout
+
+\begin_layout Description
+max_dt Maximum time step permitted.
+\end_layout
+
+\begin_layout Description
+adapt_skip Number of time steps to skip between calculating new stable time
+ step.
+\end_layout
+
+\begin_layout Description
+stability_factor Safety factor for stable time step (default is 2.0).
+\end_layout
+
+\begin_layout Standard
+An example of setting the properties for the automatic time step in a 
+\family typewriter
+.cfg
+\family default
+ file is:
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.problem.formulation]
+\end_layout
+
+\begin_layout LyX-Code
+time_step = pylith.problems.TimeStepAdapt ; Change the time step algorithm
+\end_layout
+
+\begin_layout LyX-Code
+
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.problem.formulation.time_step]
+\end_layout
+
+\begin_layout LyX-Code
+total_time = 1000.0*year
+\end_layout
+
+\begin_layout LyX-Code
+max_dt = 10.0*year
+\end_layout
+
+\begin_layout LyX-Code
+adapt_skip = 10 ; Default value
+\end_layout
+
+\begin_layout LyX-Code
+stability_factor = 2.0 ; Default value
+\end_layout
+
+\begin_layout Section
+Green's Functions Problem
+\end_layout
+
+\begin_layout Standard
+This type of problem applies to computing static Green's functions for elastic
+ deformation.
+ The 
+\family typewriter
+GreensFns
+\family default
+ problem specializes the time-dependent facility to the case of static simulatio
+ns with slip impulses on a fault.
+ The default formulation is the Implicit formulation and should not be changed
+ as the other formulations are not applicable to static Green's functions.
+ In the output files, the deformation at each 
+\begin_inset Quotes eld
+\end_inset
+
+time step
+\begin_inset Quotes erd
+\end_inset
+
+ is the deformation for a different slip impulse.
+ The properties provide the ability to select which fault to use for slip
+ impulses.
+ The only fault component available for use with the 
+\family typewriter
+GreensFns
+\family default
+ problem is the 
+\family typewriter
+FaultCohesiveImpulses
+\family default
+ component discussed in Section 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "sec:fault:cohesive:impulses"
+
+\end_inset
+
+.
+ The 
+\family typewriter
+GreensFns
+\family default
+ properties include:
+\end_layout
+
+\begin_layout Description
+fault_id Id of fault on which to impose slip impulses.
+\end_layout
+
+\begin_layout Standard
+An example of setting the properties for the GreensFns problem in a 
+\family typewriter
+.cfg
+\family default
+ file is:
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp]
+\end_layout
+
+\begin_layout LyX-Code
+problem = pylith.problems.GreensFns ; Change problem type from the default
+\end_layout
+
+\begin_layout LyX-Code
+
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.greensfns]
+\end_layout
+
+\begin_layout LyX-Code
+fault_id = 100 ; Default value
+\end_layout
+
+\begin_layout Standard
+
+\series bold
+\color red
+Warning:
+\series default
+\color none
+ 
+\color inherit
+The 
+\family typewriter
+GreensFns
+\family default
+ problem generates slip impulses on a fault.
+ The current version of PyLith requires that impulses can only be applied
+ to a single fault and the fault facility must be set to 
+\family typewriter
+FaultCohesiveImpulses
+\family default
+.
+\end_layout
+
+\begin_layout Section
+\begin_inset CommandInset label
+LatexCommand label
+name "sec:spatial:databases"
+
+\end_inset
+
+Databases for Boundaries, Interfaces, and Material Properties
+\end_layout
+
+\begin_layout Standard
+Once the problem has been defined with PyLith parameters, and the mesh informati
+on has been provided, the final step is to specify the boundary conditions
+ and material properties to be used.
+ The mesh information provides labels defining sets of vertices to which
+ boundary conditions or fault conditions will be applied, as well as cell
+ labels that will be used to define the material type of each cell.
+ For boundary conditions, the 
+\family typewriter
+.cfg
+\family default
+ file is used to associate boundary condition types and spatial databases
+ with each vertex group (see Chapter 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "cha:boundary:interface:conditions"
+
+\end_inset
+
+).
+ For materials, the 
+\family typewriter
+.cfg
+\family default
+ file is used to associate material types and spatial databases with cells
+ identified by the material identifier (see Figure 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "fig:Material-models"
+
+\end_inset
+
+).
+\end_layout
+
+\begin_layout Standard
+The spatial databases define how the boundary conditions or material property
+ values vary spatially, and they can be arbitrarily complex.
+ The simplest example for a material database would be a mesh where all
+ the cells of a given type have uniform properties (
+\begin_inset Quotes eld
+\end_inset
+
+point
+\begin_inset Quotes erd
+\end_inset
+
+ or 0D variation).
+ A slightly more complex case would be a mesh where the cells of a given
+ type have properties that vary linearly along a given direction (
+\begin_inset Quotes eld
+\end_inset
+
+line
+\begin_inset Quotes erd
+\end_inset
+
+ or 1D variation).
+ In more complex models, the material properties might have different values
+ at each point in the mesh (
+\begin_inset Quotes eld
+\end_inset
+
+volume
+\begin_inset Quotes erd
+\end_inset
+
+ or 3D variation).
+ This might be the case, for example, if the material properties are provided
+ by a database of seismic velocities and densities.
+ For boundary conditions the simplest case would be where all vertices in
+ a given group have the same boundary condition parameters (
+\begin_inset Quotes eld
+\end_inset
+
+point
+\begin_inset Quotes erd
+\end_inset
+
+ or 0D variation).
+ A more complex case might specify a variation in the conditions on a given
+ surface (
+\begin_inset Quotes eld
+\end_inset
+
+area
+\begin_inset Quotes erd
+\end_inset
+
+ or 2D variation).
+ This sort of condition might be used, for example, to specify the variation
+ of slip on a fault plane.
+ The examples discussed in Chapter 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "cha:Tutorials"
+
+\end_inset
+
+ also contain more information regarding the specification and use of the
+ spatial database files.
+\end_layout
+
+\begin_layout Subsection
+SimpleDB Spatial Database
+\end_layout
+
+\begin_layout Standard
+In most cases the default type of spatial database for faults, boundary
+ conditions, and materials is 
+\family typewriter
+SimpleDB
+\family default
+.
+ Spatial database files provide specification of a field over some set of
+ points.
+ There is no topology associated with the points.
+ Although multiple values can be specified at each point with more than
+ one value included in a search query, the interpolation of each value will
+ be done independently.
+ Time dependent variations of a field are not supported in these files.
+ Spatial database files can specify spatial variations over zero, one, two,
+ and three dimensions.
+ Zero dimensional variations correspond to uniform values.
+ One-dimensional spatial variations correspond to piecewise linear variations,
+ which need not coincide with coordinate axes.
+ Likewise, two-dimensional spatial variations correspond to variations on
+ a planar surface (which need not coincide with the coordinate axes) and
+ three-dimensional spatial variations correspond to variations over a volume.
+ In one, two, or three dimensions, queries can use a 
+\begin_inset Quotes eld
+\end_inset
+
+nearest value
+\begin_inset Quotes erd
+\end_inset
+
+ search or linear interpolation.
+\end_layout
+
+\begin_layout Standard
+The spatial database files need not provide the data using the same coordinate
+ system as the mesh coordinate system, provided the two coordinate systems
+ are compatible.
+ Examples of compatible coordinate systems include geographic coordinates
+ (longitude/latitude/elevation), and projected coordinates (e.g., coordinates
+ in a transverse Mercator projection).
+ Spatial database queries use the Proj.4 Cartographic Projections library
+ 
+\begin_inset Flex URL
+status collapsed
+
+\begin_layout Plain Layout
+
+proj.maptools.org
+\end_layout
+
+\end_inset
+
+ to convert between coordinate systems, so a large number of geographic
+ projections are available with support for converting between NAD27 and
+ WGS84 horizontal datums as well as several other frequently used datums.
+ Because the interpolation is done in the coordinate system of the spatial
+ database, geographic coordinates should only be used for very simple datasets,
+ or undesirable results will occur.
+ This is especially true when the spatial database coordinate system combines
+ latitude, longitude, and elevation in meters (longitude and latitude in
+ degrees are often much smaller than elevations in meters leading to distorted
+ 
+\begin_inset Quotes eld
+\end_inset
+
+distance
+\begin_inset Quotes erd
+\end_inset
+
+ between locations and interpolation).
+\end_layout
+
+\begin_layout Standard
+SimpleDB uses a simple ASCII file to specify the variation of values (e.g.,
+ displacement field, slip field, physical properties) in space.
+ The file format is described in Section 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "sec:Spatialdata:SimpleIOAscii"
+
+\end_inset
+
+.
+ The tutorials in Chapter 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "cha:Tutorials"
+
+\end_inset
+
+ use SimpleDB files to specify the values for the boundary conditions, 
+ physical properties, and fault slip.
+\end_layout
+
+\begin_layout Standard
+As in the other Pyre objects, spatial database objects contain parameters
+ that can be set from the command line or using 
+\family typewriter
+.cfg or .pml
+\family default
+ files.
+ The parameters for a spatial database are:
+\end_layout
+
+\begin_layout Description
+label Label for the database, which is used in diagnostic messages.
+\end_layout
+
+\begin_layout Description
+query_type Type of search query to perform.
+ Values for this parameter are ``linear'' and ``nearest'' (default).
+\end_layout
+
+\begin_layout Description
+iohandler Database importer.
+ Only one importer is implemented, so you do not need to change this setting.
+\end_layout
+
+\begin_layout Description
+iohandler.filename Filename for the spatial database.
+\end_layout
+
+\begin_layout Standard
+An example of setting these parameters in a 
+\family typewriter
+.cfg
+\family default
+ file is:
+\end_layout
+
+\begin_layout LyX-Code
+label = Material properties
+\end_layout
+
+\begin_layout LyX-Code
+query_type = linear
+\end_layout
+
+\begin_layout LyX-Code
+iohandler.filename = mydb.spatialdb
+\end_layout
+
+\begin_layout LyX-Code
+
+\end_layout
+
+\begin_layout Subsection
+UniformDB Spatial Database
+\end_layout
+
+\begin_layout Standard
+The SimpleDB spatial database is quite general, but when the values are
+ uniform, it is often easier to use the UniformDB spatial database instead.
+ With the UniformDB, you specify the values directly either on the command
+ line or in a parameter-setting (
+\family typewriter
+.cfg
+\family default
+) file.
+ On the other hand, if the values are used in more than one place, it is
+ easier to place the values in a SimpleDB file, because they can then be
+ referred to using the filename of the spatial database rather than having
+ to repeatedly list all of the values on the command line or in a parameter-sett
+ing (
+\family typewriter
+.cfg
+\family default
+) file.
+ The Pyre properties for a UniformDB are:
+\end_layout
+
+\begin_layout Description
+values Array of names of values in spatial database
+\end_layout
+
+\begin_layout Description
+data Array of values in spatial database
+\end_layout
+
+\begin_layout Subsubsection
+Example
+\end_layout
+
+\begin_layout Standard
+Specify the physical properties of a linearly elastic, isotropic material
+ in a 
+\family typewriter
+pylithapp.cfg
+\family default
+ file.
+ The data values are dimensioned with the appropriate units using Python
+ syntax.
+\end_layout
+
+\begin_layout LyX-Code
+
+\size small
+[pylithapp.timedependent.materials.material]
+\end_layout
+
+\begin_layout LyX-Code
+
+\size small
+db_properties = spatialdata.spatialdb.UniformDB ; Set the db to a UniformDB
+\end_layout
+
+\begin_layout LyX-Code
+
+\size small
+db_properties.values = [vp,vs,density] ; Set the names of the values in the
+ database
+\end_layout
+
+\begin_layout LyX-Code
+
+\size small
+db_properties.data = [5773.5*m/s, 3333.3*m/s, 2700.0*kg/m**3] ; Set the values
+ in the database
+\end_layout
+
+\begin_layout Subsubsection
+ZeroDispDB
+\end_layout
+
+\begin_layout Standard
+The ZeroDispDB is a a special case of the UniformDB for the Dirichlet boundary
+ conditions.
+ The values in the database are the ones requested by the Dirichlet boundary
+ conditions, 
+\family typewriter
+displacement-x
+\family default
+, 
+\family typewriter
+displacement-y
+\family default
+, and 
+\family typewriter
+displacement-z
+\family default
+, and are all set to zero.
+ This makes it trivial to set displacements to zero on a boundary.
+ The examples discussed in Chapter 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "cha:Tutorials"
+
+\end_inset
+
+ use this database.
+\end_layout
+
+\begin_layout Subsection
+\begin_inset CommandInset label
+LatexCommand label
+name "sub:SCECCVMH-Impl"
+
+\end_inset
+
+SCEC CVM-H Spatial Database
+\end_layout
+
+\begin_layout Standard
+Although the SimpleDB implementation is able to specify arbitrarily complex
+ spatial variations, there are existing databases for physical properties,
+ and when they are available, it is desirable to access these directly.
+ One such database is the SCEC CVM-H database, which provides seismic velocities
+ and density information for much of southern California.
+ Spatialdata provides a direct interface to this database.
+ See Section 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "sec:Tutorial-Two-tet4-geoproj"
+
+\end_inset
+
+ for an example of using the SCEC CVM-H database for physical properties
+ of an elastic material.
+ The interface is known to work with versions 5.2 and 5.3 of the SCEC CVM-H.
+ Setting a minimum wave speed can be used to replace water and very soft
+ soils that are incompressible or nearly incompressible with stiffer, compressib
+le materials.
+ The Pyre properties for the SCEC CVM-H are:
+\end_layout
+
+\begin_layout Description
+data_dir Directory containing the SCEC CVM-H data files
+\end_layout
+
+\begin_layout Description
+min_vs Minimum shear wave speed.
+ Corresponding minimum values for the dilatational wave speed (Vp) and density
+ are computed.
+ Default value is 500 m/s.
+\end_layout
+
+\begin_layout Description
+squash Squash topography/bathymetry to sea level (make the earth's surface
+ flat)
+\end_layout
+
+\begin_layout Description
+squash_limit Elevation above which topography is squashed (geometry below
+ this elevation remains undistorted)
+\end_layout
+
+\begin_layout Subsubsection
+Example
+\end_layout
+
+\begin_layout Standard
+Specify the physical properties of a linearly elastic, isotropic material
+ using the SCEC CVM-H in a 
+\family typewriter
+pylithapp.cfg
+\family default
+ file.
+\end_layout
+
+\begin_layout LyX-Code
+
+\size small
+[pylithapp.timedependent.materials.material]
+\end_layout
+
+\begin_layout LyX-Code
+
+\size small
+db_properties = spatialdata.spatialdb.SCECCVMH ; Set the database to the SCEC
+ CVM-H
+\end_layout
+
+\begin_layout LyX-Code
+
+\size small
+db_properties.data_dir = /home/johndoe/data/sceccvm-h/vx53 ; Directory containing
+\begin_inset Newline newline
+\end_inset
+
+the database data files
+\end_layout
+
+\begin_layout LyX-Code
+
+\size small
+db_properties.min_vs = 500*m/s
+\end_layout
+
+\begin_layout LyX-Code
+
+\size small
+db_properties.squash = True ; Turn on squashing
+\end_layout
+
+\begin_layout LyX-Code
+
+\size small
+db_properties.squash_limit = -1000.0 ; Only distort the geometry above z =
+ -1 km in 
+\begin_inset Newline newline
+\end_inset
+
+flattening the earth
+\end_layout
+
+\begin_layout Subsection
+CompositeDB Spatial Database
+\end_layout
+
+\begin_layout Standard
+For some problems, a boundary condition or material property may have subsets
+ with different spatial variations.
+ One example would be when we have separate databases to describe the elastic
+ and inelastic bulk material properties for a region.
+ In this case, it would be useful to have two different spatial databases,
+ e.g., a seismic velocity model with Vp, Vs, and density values, and another
+ database with the inelastic physical properties.
+ We can use the 
+\family typewriter
+CompositeDB
+\family default
+ spatial database for these cases.
+ An example would be:
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.timedependent.materials.maxwell]
+\end_layout
+
+\begin_layout LyX-Code
+label = Maxwell material
+\end_layout
+
+\begin_layout LyX-Code
+id = 1
+\end_layout
+
+\begin_layout LyX-Code
+db_properties = spatialdata.spatialdb.CompositeDB
+\end_layout
+
+\begin_layout LyX-Code
+db_properties.db_A = spatialdata.spatialdb.SCECCVMH
+\end_layout
+
+\begin_layout LyX-Code
+db_properties.db_B = spatialdata.spatialdb.SimpleDB
+\end_layout
+
+\begin_layout LyX-Code
+quadrature.cell = pylith.feassemble.FIATSimplex
+\end_layout
+
+\begin_layout LyX-Code
+quadrature.cell.dimension = 3
+\end_layout
+
+\begin_layout LyX-Code
+ 
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.timedependent.materials.maxwell.db_properties]
+\end_layout
+
+\begin_layout LyX-Code
+values_A = [density,vs,vp]
+\end_layout
+
+\begin_layout LyX-Code
+db_A.label = Elastic properties from CVM-H
+\end_layout
+
+\begin_layout LyX-Code
+db_A.data_dir = /Users/willic3/geoframe/tools/vx53/bin
+\end_layout
+
+\begin_layout LyX-Code
+db_A.squash = False
+\end_layout
+
+\begin_layout LyX-Code
+values_B = [viscosity]
+\end_layout
+
+\begin_layout LyX-Code
+db_B.label = Vertically varying Maxwell material
+\end_layout
+
+\begin_layout LyX-Code
+db_B.iohandler.filename = ../spatialdb/mat_vert_var_maxwell.spatialdb
+\end_layout
+
+\begin_layout Standard
+Here we have specified a 
+\family typewriter
+CompositeDB
+\family default
+ where the elastic properties (
+\family typewriter
+density
+\family default
+, 
+\family typewriter
+vs
+\family default
+, 
+\family typewriter
+vp
+\family default
+) are given by the SCEC CVM-H, and 
+\family typewriter
+viscosity
+\family default
+ is described by a 
+\family typewriter
+SimpleDB
+\family default
+ (
+\family typewriter
+mat_vert_var_maxwell.spatialdb
+\family default
+).
+ The user must first specify 
+\family typewriter
+db_properties
+\family default
+ as a 
+\family typewriter
+CompositeDB
+\family default
+, and must then give the two components of this database (
+\family typewriter
+SCECCVMH
+\family default
+ and 
+\family typewriter
+SimpleDB
+\family default
+).
+ The values to query in each of these databases is also required.
+ This is followed by the usual parameters for each of the spatial databases.
+ The 
+\family typewriter
+CompositeDB
+\family default
+ provides a flexible mechanism for specifying material properties or boundary
+ conditions where the variations come from two different sources.
+\end_layout
+
+\begin_layout Subsection
+Time History Database
+\end_layout
+
+\begin_layout Standard
+The time history database specifies the temporal variation in the amplitude
+ of a field associated with a boundary condition.
+ It is used in conjunction with spatial databases to provide spatial and
+ temporal variation of parameters for boundary conditions.
+ The same time history is applied to all of the locations, but the time
+ history may be shifted with a spatial variation in the onset time and scaled
+ with a spatial variation in the amplitude.
+ The time history database uses a simple ASCII file which is simpler than
+ the one used by the SimpleDB spatial database.
+ The file format is described in Section 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "sec:Spatialdata:TimeHistoryIO"
+
+\end_inset
+
+.
+ 
+\end_layout
+
+\begin_layout Standard
+As in the other Pyre objects, spatial database objects contain parameters
+ that can be set from the command line or using 
+\family typewriter
+.cfg or .pml
+\family default
+ files.
+ The parameters for a spatial database are:
+\end_layout
+
+\begin_layout Description
+label Label for the time history database, which is used in diagnostic messages.
+\end_layout
+
+\begin_layout Description
+filename Filename for the time history database.
+\end_layout
+
+\begin_layout Standard
+An example of setting these parameters in a 
+\family typewriter
+.cfg
+\family default
+ file is:
+\end_layout
+
+\begin_layout LyX-Code
+label = Displacement time history
+\end_layout
+
+\begin_layout LyX-Code
+filename = mytimehistory.timedb
+\end_layout
+
+\begin_layout Section
+Labels and Identifiers for Materials, Boundary Conditions, and Faults
+\end_layout
+
+\begin_layout Standard
+For materials, the ``label'' is a string used only for error messages.
+ The ``id'' is an integer that corresponds to the material identifier in
+ LaGriT (itetclr) and CUBIT (block id).
+ The id also tags the cells in the mesh for associating cells with a specific
+ material model and quadrature rule.
+ For boundary conditions, the ``label'' is a string used to associate groups
+ of vertices (psets in LaGriT and nodesets in CUBIT) with a boundary condition.
+ Some mesh generators use strings (LaGriT) to identify groups of nodes while
+ others (CUBIT) use strings and integers.
+ The default behavior in PyLith is to use strings to identify groups for
+ both LaGriT and CUBIT meshes, but the behavior for CUBIT meshes can be
+ changed to use the nodeset id (see Section 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "sec:MeshIOCubit"
+
+\end_inset
+
+).
+ PyLith 1.0 had an ``id'' for boundary conditions, but we removed it from
+ subsequent releases because it was not used.
+ For faults the ``label'' is used in the same manner as the ``label'' for
+ boundary conditions.
+ That is, it associates a string with a group of vertices (pset in LaGriT
+ and nodeset in CUBIT).
+ The fault ``id'' is a integer used to tag the cohesive cells in the mesh
+ with a specific fault and quadrature rule.
+ Because we use the fault ``id'' to tag cohesive cells in the mesh the same
+ way we tag normal cells to materials, it must be unique among the faults
+ as well as the materials.
+\end_layout
+
+\begin_layout Section
+PyLith Output
+\end_layout
+
+\begin_layout Standard
+PyLith currently supports output to VTK and HDF5/Xdmf files, which can be
+ imported directly into a number of visualization tools, such as ParaView,
+ Visit, and MayaVi.
+ The HDF5 files can also be directly accessed via Matlab and PyTables.
+ PyLith 1.1 significantly expanded the information available for output,
+ including fault information and state variables.
+ Output of solution information for the domain, faults, materials, and boundary
+ conditions is controlled by an output manager for each module.
+ This allows the user to tailor the output to the problem.
+ By default PyLith will write a number of files.
+ Diagnostic information for each fault and material is written into a separate
+ file as are the solution and state variables for the domain, each fault,
+ and each material.
+ For a fault the diagnostic fields include the final slip, the slip initiation
+ time, and the fault normal vector.
+ For a material the diagnostic fields include the density and the elastic
+ constants.
+ Additional diagnostic information can be included by setting the appropriate
+ output parameters.
+ See Chapters 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "cha:material:models"
+
+\end_inset
+
+ and 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "cha:boundary:interface:conditions"
+
+\end_inset
+
+ for more information on the available fields and the next section for output
+ parameters.
+ The other files for each fault and material include solution information
+ at each time step where output was requested (also customizable by the
+ user).
+ For a fault the solution information includes the slip and the change in
+ tractions on the fault surface.
+ For a material the solution information includes the total strain and stress.
+ For some materials fields for additional state variables may be available.
+ For output via VTK files, each time step is written to a separate file,
+ whereas for HDF5 files all of the time steps for a given domain, fault,
+ or material are written into the same file.
+ A single Xdmf metadata file is created for each HDF5 file.
+\end_layout
+
+\begin_layout Subsection
+Output Manager
+\end_layout
+
+\begin_layout Standard
+The OutputManager object controls the type of files written, the fields
+ included in the output, and how often output is written.
+ PyLith includes some specialized OutputManagers that prescribe what fields
+ are output by default.
+ In some cases, additional fields are available but not included by default.
+ For example, in 3D problems, the along-strike and up-dip directions over
+ the fault surface can be included in the diagnostic information.
+ These are not included by default, because 1D problems have neither an
+ along-strike nor up-dip direction and 2D problems do not have an up-dip
+ direction.
+\end_layout
+
+\begin_layout Subsubsection
+Output Manager Parameters
+\end_layout
+
+\begin_layout Standard
+The parameters for the OutputManager are:
+\end_layout
+
+\begin_layout Description
+output_freq Flag indicating whether to write output based on the time or
+ number of time steps since the last output.
+ Permissible values are ``time_step'' and ``skip'' (default).
+\end_layout
+
+\begin_layout Description
+time_step Minimum time between output if 
+\family typewriter
+output_freq
+\family default
+ is set to ``time_step''.
+\end_layout
+
+\begin_layout Description
+skip Number of time steps between output if 
+\family typewriter
+output_freq
+\family default
+ is set to ``skip''.
+ A value of 0 means every time step is written.
+\end_layout
+
+\begin_layout Description
+writer Writer for data (VTK writer or HDF5 writer).
+\end_layout
+
+\begin_layout Description
+coordsys Coordinate system for vertex coordinates (currently ignored).
+\end_layout
+
+\begin_layout Description
+vertex_filter Filter to apply to all vertex fields (see Section 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "sub:vertex:field:filters"
+
+\end_inset
+
+).
+\end_layout
+
+\begin_layout Description
+cell_filter Filter to apply to all cell fields (see Section 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "sub:cell:field:filters"
+
+\end_inset
+
+).
+\end_layout
+
+\begin_layout Standard
+An example of setting the output parameters for a material in a 
+\family typewriter
+.cfg
+\family default
+ file is
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.timedependent.materials.elastic.output]
+\end_layout
+
+\begin_layout LyX-Code
+output_freq = time_step
+\end_layout
+
+\begin_layout LyX-Code
+time_step = 1.0*yr
+\end_layout
+
+\begin_layout LyX-Code
+cell_filter = pylith.meshio.CellFilterAvgMesh
+\end_layout
+
+\begin_layout LyX-Code
+cell_info_fields = [density] ; limit diagnostic data to density
+\end_layout
+
+\begin_layout LyX-Code
+cell_data_fields = [total-strain,stress] ; default
+\end_layout
+
+\begin_layout LyX-Code
+writer.filename = dislocation-elastic.vtk
+\end_layout
+
+\begin_layout Subsubsection
+Output Over Subdomain
+\end_layout
+
+\begin_layout Standard
+Output of the solution over the entire domain for large problems generates
+ very large data files.
+ In some cases one is primarily interested in the solution over the ground
+ surface.
+ PyLith supports output of the solution on any boundary of the domain by
+ associating an output manager with a group of vertices corresponding to
+ the surface of the boundary.
+ As with several of the boundary conditions, the boundary must be a simply-conne
+cted surface.
+ The 
+\family typewriter
+OutputSolnSubset
+\family default
+ is the specialized OutputManager that implements this feature and, by default,
+ includes the displacement field in the output.
+ In addition to the 
+\family typewriter
+OutputManager
+\family default
+ parameters, the 
+\family typewriter
+OutputSolnSubset
+\family default
+ includes:
+\end_layout
+
+\begin_layout Description
+label Label of group of vertices defining boundary surface.
+\end_layout
+
+\begin_layout Description
+vertex_data_fields Names of vertex data fields to output (default is [``displace
+ments'']).
+\end_layout
+
+\begin_layout Subsection
+\begin_inset CommandInset label
+LatexCommand label
+name "sec:output:points"
+
+\end_inset
+
+Output at Arbitrary Points
+\end_layout
+
+\begin_layout Standard
+In many situations with recorded observations, one would like to extract
+ the solution at the same locations as the recorded observation.
+ Rather than forcing the finite-element discretization to be consistent
+ with the observation points, PyLith includes a specialized output manager,
+ 
+\family typewriter
+OutputSolnPoints
+\family default
+, to interpolate the solution to arbitrary points.
+ By default, the output manager will include the displaceent time histories
+ in the output.
+ The locations are specified in a text file.
+ In addition to the 
+\family typewriter
+OutputManager
+\family default
+ parameters, the 
+\family typewriter
+OutputSolnSubset
+\family default
+ includes:
+\end_layout
+
+\begin_layout Description
+vertex_data_fields Names of vertex data fields to output (default is [``displace
+ments'']).
+\end_layout
+
+\begin_layout Description
+reader Reader for points list (default is 
+\family typewriter
+PointsList
+\family default
+).
+\end_layout
+
+\begin_layout Description
+writer Writer for output (default is 
+\family typewriter
+DataWriterVTKPoints
+\family default
+).
+ In most cases users will want to use the 
+\family typewriter
+DataWriterHDF5Mesh
+\family default
+.
+\end_layout
+
+\begin_layout Subsubsection
+PointsList Reader
+\end_layout
+
+\begin_layout Standard
+This object corresponds to a simple text file containing a list of points
+ (one per line) where output is desired.
+ The points are specified in the coordinate system specified by OutputSolnPoints.
+ The coordinates will be transformed into the coordinate system of the mesh
+ prior to interpolation.
+ The properties available to customize the behavior of 
+\family typewriter
+PointsList
+\family default
+ are:
+\end_layout
+
+\begin_layout Description
+filename Names of file containing list of points.
+\end_layout
+
+\begin_layout Description
+comment_delimiter Delimiter at beginning of line to identify comments (default
+ is #).
+\end_layout
+
+\begin_layout Description
+value_delimiter Delimiter used to separate values (default is whitespace).
+\end_layout
+
+\begin_layout Subsection
+Output Field Filters
+\end_layout
+
+\begin_layout Standard
+Output fields may not directly correspond to the information a user desires.
+ For example, the default output for the state variables includes the physical
+ properties at each quadrature point.
+ Most visualization packages cannot handle cell fields with multiple points
+ in a cell (the locations of the points within the cell are not included
+ in the data file).
+ In order to reduce the field to a single point within the cell, we would
+ like to average the values.
+ This is best done within PyLith before output, because it reduces the file
+ size and the quadrature information provides the information necessary
+ (the weights of the quadrature points) to compute the appropriate average
+ over the cell.
+\end_layout
+
+\begin_layout Subsubsection
+\begin_inset CommandInset label
+LatexCommand label
+name "sub:vertex:field:filters"
+
+\end_inset
+
+Vertex Field Filters
+\end_layout
+
+\begin_layout Standard
+Currently the only filter available for vertex fields computes the magnitude
+ of a vector at each location.
+ Most visualization packages support this operation, so this filter is not
+ very useful.
+\end_layout
+
+\begin_layout Description
+VertexFilterVecNorm Computes the magnitude of a vector field at each location.
+\end_layout
+
+\begin_layout Subsubsection
+\begin_inset CommandInset label
+LatexCommand label
+name "sub:cell:field:filters"
+
+\end_inset
+
+Cell Field Filters
+\end_layout
+
+\begin_layout Standard
+Most users will want to apply a filter to cell fields to average the fields
+ over the cell, producing values at one location per cell for visualization.
+\end_layout
+
+\begin_layout Description
+CellFilterAvgMesh Compute the weighted average of the values within a bulk
+ cell.
+ The weights are determined from the quadrature associated with the cells.
+\end_layout
+
+\begin_layout Description
+CellFilterAvgSubMesh Compute the weighted average of the values for a boundary
+ cell.
+ The weights are determined from the quadrature associated with the cells.
+\end_layout
+
+\begin_layout Subsection
+VTK Output
+\end_layout
+
+\begin_layout Standard
+PyLith writes legacy (non-XML) VTK files.
+ These are simple files with vertex coordinates, the mesh topology, and
+ fields over vertices and/or cells.
+ Each time step is written to a different file.
+ The time stamp is included in the filename with the decimal point removed.
+ This allows automatic generation of animations with many visualization
+ packages that use VTK files.
+ The default time stamp is the time in seconds, but this can be changed
+ using the normalization constant to give a time stamp in years, tens of
+ years, or any other value.
+\end_layout
+
+\begin_layout Subsubsection
+DataWriterVTK Parameters
+\end_layout
+
+\begin_layout Standard
+The parameters for the VTK writer are:
+\end_layout
+
+\begin_layout Description
+filename Name of VTK file
+\end_layout
+
+\begin_layout Description
+time_format C-style format string for time stamp in filename.
+ The decimal point in the time stamp will be removed for compatibility with
+ VTK visualization packages that provide seamless animation of data from
+ multiple VTK files.
+\end_layout
+
+\begin_layout Description
+time_constant Value used to normalize time stamp in VTK files (default is
+ 1.0 s).
+\end_layout
+
+\begin_layout Subsection
+\begin_inset CommandInset label
+LatexCommand label
+name "sub:HDF5/Xdmf-Output"
+
+\end_inset
+
+HDF5/Xdmf Output
+\end_layout
+
+\begin_layout Standard
+HDF5 files provide a flexible framework for storing simulation data with
+ datasets in groups logically organized in a tree structure analogous to
+ files in directories.
+ HDF5 output offers parallel, multi-dimensional array output in binary files,
+ so it is much faster and more convenient than the VTK output which uses
+ ASCII files and separate files for each time step.
+ Standards for organizing datasets and groups in HDF5 files do not exist
+ for general finite-element software in geodynamics.
+ Consequently, PyLith uses its own simple layout show in Figure 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "fig:hdf5:layout"
+
+\end_inset
+
+.
+ In order for visualization tools, such as ParaView, to determine which
+ datasets to read and where to find them in the hierarchy of groups within
+ the HDF5 file, we create an Xdmf (eXtensible Data Model and Format, 
+\begin_inset Flex URL
+status open
+
+\begin_layout Plain Layout
+
+www.xdmf.org
+\end_layout
+
+\end_inset
+
+) metadata file that provides this information.
+ This file is written when PyLith closes the HDF5 file at the end of the
+ simulation.
+ In order to visualize the datasets in an HDF5 file, one simply opens the
+ corresponding Xdmf file (the extension is 
+\family typewriter
+.xmf
+\family default
+) in ParaView or Visit.
+ The Xdmf file contains the relative path to the HDF5 file so the files
+ can be moved but must be located together in the same directory.
+ 
+\end_layout
+
+\begin_layout Quote
+
+\series bold
+\color red
+Note:
+\color inherit
+ 
+\series default
+The Xdmf format supports representation of two- and three-dimensional coordinate
+s of points, scalar vector field types, and three-dimensional vector and
+ tensor vector field types but not two-dimensional vector or tensor vector
+ field types.
+ As a result, we separate the components of two-dimensional vector and tensor
+ vector field objects and add the component as a suffix to the name of the
+ field.
+ The vector can be reconstructed within ParaView using the Calculator (see
+ Section 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "sec:Tutorial-Subduction"
+
+\end_inset
+
+ for an example).
+ Accessing the datasets in the HDF5 files using tools such as h5py (included
+ with the PyLith binary and installed by default with the PyLith Installer)
+ and PyTables with visualization through MayaVi circumvents this problem,
+ but requires writing Python scripts and a deeper knowledge of the visualization
+ interface.
+\end_layout
+
+\begin_layout Standard
+\noindent
+\align center
+\begin_inset Float figure
+placement H
+wide false
+sideways false
+status open
+
+\begin_layout Plain Layout
+\noindent
+\align center
+\begin_inset Graphics
+	filename figs/hdf5layout.eps
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Plain Layout
+\begin_inset Caption
+
+\begin_layout Plain Layout
+Layout of PyLith HDF5 file.
+ The orange rectangles with rounded corners identify the groups and the
+ blue rectangles with sharp corners identify the datasets.
+ The dimensions of the data sets are shown in parentheses.
+ Most HDF5 files will contain either 
+\family typewriter
+vertex_fields
+\family default
+ or 
+\family typewriter
+cell_fields
+\family default
+ but not both.
+ 
+\begin_inset CommandInset label
+LatexCommand label
+name "fig:hdf5:layout"
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+HDF5 files do not contain self-correcting features that allow a file to
+ be read if part of a dataset is corrupted.
+ This type of error can occur if a job terminates abnormally in the middle
+ or at the end of a simulation on a large cluster or other parallel machine.
+ Fortunately, HDF5 also offers the ability to store datasets in external
+ binary files with the locations specified by links in the HDF5 file.
+ Note that the use of external data files results in one data file per dataset
+ in addition to the HDF5 and Xdmf files.
+ The external data files use the name of the HDF5 file with the dataset
+ name added to the prefix and the 
+\family typewriter
+.h5
+\family default
+ suffix replaced by 
+\family typewriter
+.dat
+\family default
+).
+ The HDF5 files include relative paths to the external data files, so these
+ files can also be moved, but they, too, must be kept together in the same
+ directory.
+ This provides a more robust method of output because one can generate an
+ HDF5 file associated with the uncorrupted portions of the external data
+ files should an error occur.
+ Currently, PyLith does not include a utility to do this, but we plan to
+ add one in a future release.
+ Thus, there are two options when writing PyLith output to HDF5 files: (1)
+ including the datasets directly in the HDF5 files themselves or (2) storing
+ the datasets in external binary files with just metadata in the HDF5 files.
+ Both methods provide similar performance because they will use MPI I/O
+ if it is available.
+ 
+\end_layout
+
+\begin_layout Quote
+
+\series bold
+\color red
+Warning:
+\color inherit
+ 
+\series default
+Storing the datasets within the HDF5 file in a parallel simulation requires
+ that the HDF5 library be configured with the 
+\family typewriter
+--enable-parallel
+\family default
+ option.
+ 
+\color none
+The binary PyLith packages include this feature and it is a default setting
+ in building HDF5 via the PyLith Installer.
+\end_layout
+
+\begin_layout Standard
+Accessing the datasets for additional analysis or visualization is nearly
+ identical in the two methods because the use of external data files is
+ completely transparent to the user except for the presence of the additional
+ files.
+ Note that in order for ParaView to find the HDF5 and external data files,
+ it must be run from the same relative location where the simulation was
+ run.
+ For example, if the simulation was run from a directory called 
+\begin_inset Quotes eld
+\end_inset
+
+work
+\begin_inset Quotes erd
+\end_inset
+
+ and the HDF5/Xdmf files were written to 
+\begin_inset Quotes eld
+\end_inset
+
+work/output
+\begin_inset Quotes erd
+\end_inset
+
+, then ParaView should be run from the 
+\begin_inset Quotes eld
+\end_inset
+
+work
+\begin_inset Quotes erd
+\end_inset
+
+ directory.
+ See Table 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "tab:material:output:components"
+
+\end_inset
+
+ in Section 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "sec:material:parameters"
+
+\end_inset
+
+for a table of component values for tensor output.
+\end_layout
+
+\begin_layout Subsubsection
+HDF5 Utilities
+\end_layout
+
+\begin_layout Standard
+HDF5 includes several utilities for examining the contents of HDF5 files.
+ 
+\family typewriter
+h5dump
+\family default
+ is very handy for displaying the hierarchy, dimensions of datasets, attributes,
+ and even the dataset values.
+ 
+\end_layout
+
+\begin_layout Quote
+Dump the entire HDF5 file to stdout (not practical or useful for large files):
+\end_layout
+
+\begin_deeper
+\begin_layout LyX-Code
+h5dump mydata.h5
+\end_layout
+
+\end_deeper
+\begin_layout Quote
+Dump the hierarchy of an HDF5 file to stdout:
+\end_layout
+
+\begin_deeper
+\begin_layout LyX-Code
+h5dump -n mydata.h5
+\end_layout
+
+\end_deeper
+\begin_layout Quote
+Dump the hierarchy with dataset dimensions and attributes to stdout:
+\end_layout
+
+\begin_deeper
+\begin_layout LyX-Code
+h5dump -H mydata.h5
+\end_layout
+
+\end_deeper
+\begin_layout Quote
+Dump dataset 'vertices' in group '/geometry' to stdout:
+\end_layout
+
+\begin_deeper
+\begin_layout LyX-Code
+h5dump -d /geometry/vertices mydata.h5
+\end_layout
+
+\end_deeper
+\begin_layout Subsubsection
+DataWriterHDF5 Parameters
+\end_layout
+
+\begin_layout Standard
+This HDF5 writer stores the datasets inside the HDF5 file and the parameters
+ are:
+\end_layout
+
+\begin_layout Description
+filename Name of HDF5 file (the Xdmf filename is generated from the same
+ prefix).
+\end_layout
+
+\begin_layout Subsubsection
+DataWriterHDF5Ext Parameters
+\end_layout
+
+\begin_layout Standard
+This HDF5 writer stores the datasets using external data files (a more robust
+ method for parallel runs) and the parameters are:
+\end_layout
+
+\begin_layout Description
+filename Name of HDF5 file (the external dataset filenames and the Xdmf
+ filename are generated from the same prefix).
+\end_layout
+
+\begin_layout Standard
+An example of changing the writer from the default VTK writer to the HDF5
+ writer with external datasets for output over the domain in a 
+\family typewriter
+.cfg
+\family default
+ file is
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.timedependent.domain.output]
+\end_layout
+
+\begin_layout LyX-Code
+output_freq = time_step
+\end_layout
+
+\begin_layout LyX-Code
+time_step = 1.0*yr
+\end_layout
+
+\begin_layout LyX-Code
+cell_data_fields = [displacement,velocity]
+\end_layout
+
+\begin_layout LyX-Code
+writer = pylith.meshio.DataWriterHDF5ExtMesh
+\end_layout
+
+\begin_layout LyX-Code
+writer.filename = dislocation.h5
+\end_layout
+
+\begin_layout Section
+Tips and Hints
+\begin_inset CommandInset label
+LatexCommand label
+name "sec:Tips:Hints"
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Subsection
+Tips and Hints For Running PyLith
+\end_layout
+
+\begin_layout Itemize
+Examine the examples for a problem similar to the one you want to run and
+ dissect it in detail.
+\end_layout
+
+\begin_layout Itemize
+Start with a uniform-resolution coarse mesh to debug the problem setup.
+ Increase the resolution as necessary to resolve the solution fields of
+ interest (resolving stresses/strains may require a higher resolution than
+ that for resolving displacements).
+\end_layout
+
+\begin_layout Itemize
+Merge materials using the same material model.
+ This will result in only one VTK or HDF5 file for each material model rather
+ than several files.
+\end_layout
+
+\begin_layout Itemize
+The rate of convergence in quasi-static (implicit) problems can sometimes
+ be improved by renumbering the vertices in the finite-element mesh to reduce
+ the bandwidth of the sparse matrix.
+ PyLith can use the reverse Cuthill-McKee algorithm to reorder the vertices
+ and cells.
+\end_layout
+
+\begin_layout Itemize
+If you encounter errors or warnings, run 
+\family typewriter
+pylithinfo
+\family default
+ or use the 
+\family typewriter
+--help
+\family default
+, 
+\family typewriter
+--help-components
+\family default
+, and 
+\family typewriter
+--help-properties
+\family default
+ command line arguments when running PyLith to check the parameters to make
+ sure PyLith is using the parameters you intended.
+\end_layout
+
+\begin_layout Itemize
+Use the 
+\family typewriter
+--petsc.log_summary
+\family default
+, 
+\family typewriter
+--petsc.ksp_monitor
+\family default
+, 
+\family typewriter
+--petsc.ksp_view
+\family default
+, 
+\family typewriter
+--petsc.ksp_converged_reason
+\family default
+, and 
+\family typewriter
+--petsc.snes_converged_reason
+\family default
+ command line arguments (or set them in a parameter file) to view PyLith
+ performance and monitor the convergence.
+\end_layout
+
+\begin_layout Itemize
+Turn on the journals (see the examples) to monitor the progress of the code.
+\end_layout
+
+\begin_layout Subsection
+Troubleshooting
+\begin_inset CommandInset label
+LatexCommand label
+name "sec:Troubleshooting"
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Itemize
+Consult the PyLith FAQ webpage (
+\begin_inset Flex URL
+status open
+
+\begin_layout Plain Layout
+
+http://www.geodynamics.org/cig/community/workinggroups/short/workarea/pylith-wiki
+\end_layout
+
+\end_inset
+
+) which contains a growing list of common problems and their corresponding
+ solutions.
+\end_layout
+
+\begin_layout Itemize
+
+\family typewriter
+ImportError: liblapack.so.2: cannot open shared object file: No such file
+ or directory
+\end_layout
+
+\begin_layout Quote
+PyLith cannot find one of the libraries.
+ You need to set up your environment variables (e.g., PATH, PYTHONPATH, and
+ LD_LIBRARY_PATH) to match your installation.
+ If you are using the PyLith binary on Linux or Mac OS X, run the command
+ 
+\family typewriter
+source setup.sh 
+\family default
+in the directory where you unpacked the distribution.
+ This will set up your environment variables for you.
+ If you are building PyLith from source, please consult the instructions
+ for building from source.
+\end_layout
+
+\begin_layout Itemize
+\paragraph_spacing single
+
+\family typewriter
+>> {command line}:: 
+\begin_inset Newline newline
+\end_inset
+
+-- pyre.inventory(error) 
+\begin_inset Newline newline
+\end_inset
+
+-- p4wd <- 'true' 
+\begin_inset Newline newline
+\end_inset
+
+-- unrecognized property 'p4wd' 
+\begin_inset Newline newline
+\end_inset
+
+>> {command line}:: 
+\begin_inset Newline newline
+\end_inset
+
+-- pyre.inventory(error) 
+\begin_inset Newline newline
+\end_inset
+
+-- p4pg <- 'true' 
+\begin_inset Newline newline
+\end_inset
+
+-- unrecognized property ' p4pg'
+\end_layout
+
+\begin_layout Quote
+Verify that the `mpirun' command included in the PyLith package is the first
+ one on your PATH:
+\end_layout
+
+\begin_layout Quote
+
+\family typewriter
+$ which mpirun
+\end_layout
+
+\begin_layout Quote
+If it is not, adjust your PATH environment variable accordingly.
+\end_layout
+
+\begin_layout Itemize
+
+\family typewriter
+"merlin.DistributionNotFound: Cheetah" error
+\end_layout
+
+\begin_layout Quote
+This error occurs when trying to use the 32-bit linux binary on some 64-bit
+ linux systems.
+ One of the Python packages PyLith uses does not know how to determine the
+ system architecture at runtime.
+ The workaround is:
+\end_layout
+
+\begin_layout Enumerate
+Go to the lib/python2.6/site-packages directory.
+\end_layout
+
+\begin_layout Enumerate
+Unzip merlin-1.7-py2.6.egg (if it is a file and not a directory).
+\end_layout
+
+\begin_layout Enumerate
+Go to the merlin directory.
+\end_layout
+
+\begin_layout Enumerate
+Edit __init__.py.
+ Replace line 308 plat = get_platform() with plat = "linux-i686"
+\end_layout
+
+\begin_layout Enumerate
+If merlin-1.7-py2.6.egg is a file, rezip merlin.
+ Go to the site-packages directory and enter "zip -r merlin-1.7-py2.6.egg merlin".
+\end_layout
+
+\begin_layout Itemize
+
+\family typewriter
+-- Solving equations.
+\begin_inset Newline newline
+\end_inset
+
+[0]PETSC ERROR: ---------------- Error Message -------------------------------
+ 
+\begin_inset Newline newline
+\end_inset
+
+[0]PETSC ERROR: Detected zero pivot in LU factorization
+\begin_inset Newline newline
+\end_inset
+
+ see http://www.mcs.anl.gov/petsc/petsc-as/documentation/faq.html#ZeroPivot!
+\end_layout
+
+\begin_layout Quote
+This usually occurs when the null space of the system Jacobian is nonzero,
+ such as the case of a problem without Dirichlet boundary conditions on
+ any boundary.
+ If this arises when using the split fields and algebraic multigrid precondition
+ing and no additional Dirichlet boundary conditions are desired, then the
+ workaround is to revert to using the Additive Schwarz preconditioning without
+ split fields as discussed in Section 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "sec:petsc:options"
+
+\end_inset
+
+.
+ 
+\end_layout
+
+\begin_layout Itemize
+PyLith crashes with a bus error.
+\end_layout
+
+\begin_layout Quote
+This often indicates that PyLith is using incompatible versions of libraries.
+ This can result from changing your environment variables after configuring
+ or installing PyLith (when building from source) or errors in setting the
+ environment variables (PATH, LD_LIBRARY_PATH, and PYTHONPATH).
+ If the former case, simply reconfigure and rebuild PyLith.
+ In the latter case, check your environment variables (order matters!) to
+ make sure PyLith finds the desired directories before system directories.
+ 
+\end_layout
+
+\begin_layout Itemize
+PyLith crashes with a segmentation fault.
+\end_layout
+
+\begin_layout Quote
+A segmentation fault might be caused by an error that wasn't trapped or
+ a bug in the code.
+ Please report these cases so that we can fix these problems (either trap
+ the error and provide the user with an informative error message, or fix
+ the bug).
+ If this occurs with any of the problems distributed with PyLith, simply
+ submit a bug report (see Section 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "sec:Getting-Help-and"
+
+\end_inset
+
+) indicating which problem you ran and your platform.
+ If the crash occurs for a problem you created, it is a great help if you
+ can try to reproduce the crash with a very simple problem (e.g., adjust the
+ boundary conditions or other parameters of one of the examples to reproduce
+ the segmentation fault).
+ Submit a bug report along with log files showing the backtrace from a debugger
+ (e.g., gdb) and the valgrind log file (only available on Linux platforms).
+ You can generate a backtrace using the debugger by using the 
+\family typewriter
+--petsc.start_in_debugger
+\family default
+ command line argument:
+\end_layout
+
+\begin_layout LyX-Code
+pylith [..args..] --petsc.start_in_debugger
+\end_layout
+
+\begin_layout LyX-Code
+(gdb) continue
+\end_layout
+
+\begin_layout LyX-Code
+(gdb) backtrace
+\end_layout
+
+\begin_layout Quote
+To use valgrind to detect the memory error, first go to your working directory
+ and run the problem with 
+\family typewriter
+--launcher.dry
+\family default
+:
+\end_layout
+
+\begin_layout LyX-Code
+pylith [..args..] --launcher.dry
+\end_layout
+
+\begin_layout Quote
+Instead of actually running the problem, this causes PyLith to dump the
+ mpirun/mpiexec command it will execute.
+ Copy and paste this command into your shell so you can run it directly.
+ Insert the full path to valgrind before the full path to mpinemesis and
+ tell valgrind to use a log file:
+\end_layout
+
+\begin_layout LyX-Code
+
+\size small
+mpirun -np 1 /path/to/valgrind --log-file=valgrind-log  /path/to/mpinemesis
+ --pyre-start [..lots of junk..]
+\end_layout
+
+\end_body
+\end_document

Modified: short/3D/PyLith/branches/v1.7-trunk/doc/userguide/tutorials/3dhex8/dike/dike.lyx
===================================================================
--- short/3D/PyLith/branches/v1.7-trunk/doc/userguide/tutorials/3dhex8/dike/dike.lyx	2012-06-25 04:52:47 UTC (rev 20403)
+++ short/3D/PyLith/branches/v1.7-trunk/doc/userguide/tutorials/3dhex8/dike/dike.lyx	2012-06-25 16:38:44 UTC (rev 20404)
@@ -1,286 +1,290 @@
-#LyX 2.0 created this file. For more info see http://www.lyx.org/
-\lyxformat 413
-\begin_document
-\begin_header
-\textclass book
-\begin_preamble
-
-\end_preamble
-\use_default_options false
-\maintain_unincluded_children false
-\language english
-\language_package default
-\inputencoding latin1
-\fontencoding global
-\font_roman default
-\font_sans default
-\font_typewriter default
-\font_default_family default
-\use_non_tex_fonts false
-\font_sc false
-\font_osf false
-\font_sf_scale 100
-\font_tt_scale 100
-
-\graphics default
-\default_output_format default
-\output_sync 0
-\bibtex_command default
-\index_command default
-\paperfontsize default
-\spacing single
-\use_hyperref false
-\papersize default
-\use_geometry true
-\use_amsmath 0
-\use_esint 0
-\use_mhchem 1
-\use_mathdots 1
-\cite_engine basic
-\use_bibtopic false
-\use_indices false
-\paperorientation portrait
-\suppress_date false
-\use_refstyle 0
-\index Index
-\shortcut idx
-\color #008000
-\end_index
-\leftmargin 1in
-\topmargin 1in
-\rightmargin 1in
-\bottommargin 2in
-\secnumdepth 3
-\tocdepth 3
-\paragraph_separation indent
-\paragraph_indentation default
-\quotes_language english
-\papercolumns 1
-\papersides 1
-\paperpagestyle default
-\tracking_changes false
-\output_changes false
-\html_math_output 0
-\html_css_as_file 0
-\html_be_strict false
-\end_header
-
-\begin_body
-
-\begin_layout Subsection
-\begin_inset CommandInset label
-LatexCommand label
-name "sec:Tutorial-3d-hex8-dike"
-
-\end_inset
-
-Dike Intrusion Example
-\end_layout
-
-\begin_layout Standard
-PyLith features discussed in this tutorial:
-\end_layout
-
-\begin_layout Itemize
-Fault opening via prescribed tractions to mimic a dike instrusion
-\end_layout
-
-\begin_layout Itemize
-Dirichlet boundary conditions
-\end_layout
-
-\begin_layout Itemize
-Elastic material
-\end_layout
-
-\begin_layout Itemize
-VTK output
-\end_layout
-
-\begin_layout Subsubsection
-Overview
-\end_layout
-
-\begin_layout Standard
-This set of examples describes a problem where prescribed tensile tractions
- are imposed on a fault to mimic a dike intrusion.
- The example is contained in the directory 
-\family typewriter
-examples/3d/hex8
-\family default
-, and the corresponding 
-\family typewriter
-.cfg
-\family default
- file is 
-\family typewriter
-step20.cfg
-\family default
-.
- The example may be run as follows:
-\end_layout
-
-\begin_layout LyX-Code
-pylith step20.cfg
-\end_layout
-
-\begin_layout Standard
-This will cause PyLith to read the default parameters in 
-\family typewriter
-pylithapp.cfg
-\family default
-, and then override or augment them with the additional parameters in the
- 
-\family typewriter
-step20.cfg
-\family default
- file.
- The 
-\family typewriter
-.cfg
-\family default
- file is extensively documented, to provide detailed information on the
- various parameters.
-\end_layout
-
-\begin_layout Subsubsection
-Step20 - Static dike intrusion
-\end_layout
-
-\begin_layout Standard
-The 
-\family typewriter
-step20.cfg
-\family default
- file defines a problem with spatially varying tensile normal tractions
- on the fault surface associated with a fluid intrusion.
- The lateral sides and bottom of the domain are fixed using Dirichlet (roller)
- boundary conditions.
- As in the other examples, we also setup output for the ground surface.
-\end_layout
-
-\begin_layout Standard
-We use the FaultCohesiveDyn object to impose tractions on the fault surface.
- We must include a fault constitutive model so we choose static friction
- with a coefficient of friction of 0.1.
- The coefficient of friction is irrelevant for the center of the fault where
- we impose uniform tensile tractions (10 MPa) and the fault opens, but it
- facilitates clamping the edges of the fault via compressive normal tractions
- (-100 MPa).
- Note that we must set the property 
-\family typewriter
-open_free_surface
-\family default
- to True in order for the tractions to be imposed when the fault is open;
- the default behavior for fault opening is a free surface (the two sides
- of the fault are completely uncoupled).
- The most important fault parameters for prescribing the tensile fault tractions
- are
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.timedependent.interfaces.fault]
-\end_layout
-
-\begin_layout LyX-Code
-open_free_surface = True
-\begin_inset Newline newline
-\end_inset
-
-
-\end_layout
-
-\begin_layout LyX-Code
-traction_perturbation = pylith.faults.TractPerturbation
-\begin_inset Newline newline
-\end_inset
-
-
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.timedependent.interfaces.fault.traction_perturbation]
-\end_layout
-
-\begin_layout LyX-Code
-db_initial = spatialdata.spatialdb.SimpleDB
-\end_layout
-
-\begin_layout LyX-Code
-db_initial.label = Initial fault tractions
-\end_layout
-
-\begin_layout LyX-Code
-db_initial.iohandler.filename = spatialdb/tractions_opening.spatialdb
-\end_layout
-
-\begin_layout LyX-Code
-db_initial.query_type = nearest 
-\end_layout
-
-\begin_layout Standard
-When we have run the simulation, the output VTK files will be contained
- in 
-\family typewriter
-examples/3d/hex8/output
-\family default
- (all with a prefix of 
-\family typewriter
-step
-\family default
-20).
- Results using ParaView are shown in Figure 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "fig:step20-disp"
-
-\end_inset
-
-.
-\end_layout
-
-\begin_layout Standard
-\begin_inset Float figure
-wide false
-sideways false
-status open
-
-\begin_layout Plain Layout
-\align center
-\begin_inset Graphics
-	filename figs/step20_disp.png
-	lyxscale 50
-	width 10cm
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Plain Layout
-\begin_inset Caption
-
-\begin_layout Plain Layout
-Displacement magnitude for example step20 visualized using ParaView.
- 
-\begin_inset CommandInset label
-LatexCommand label
-name "fig:step20-disp"
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_body
-\end_document
+#LyX 2.0 created this file. For more info see http://www.lyx.org/
+\lyxformat 413
+\begin_document
+\begin_header
+\textclass book
+\begin_preamble
+
+\end_preamble
+\use_default_options false
+\maintain_unincluded_children false
+\language english
+\language_package default
+\inputencoding latin1
+\fontencoding global
+\font_roman default
+\font_sans default
+\font_typewriter default
+\font_default_family default
+\use_non_tex_fonts false
+\font_sc false
+\font_osf false
+\font_sf_scale 100
+\font_tt_scale 100
+
+\graphics default
+\default_output_format default
+\output_sync 0
+\bibtex_command default
+\index_command default
+\paperfontsize default
+\spacing single
+\use_hyperref false
+\papersize default
+\use_geometry true
+\use_amsmath 0
+\use_esint 0
+\use_mhchem 1
+\use_mathdots 1
+\cite_engine basic
+\use_bibtopic false
+\use_indices false
+\paperorientation portrait
+\suppress_date false
+\use_refstyle 0
+\index Index
+\shortcut idx
+\color #008000
+\end_index
+\leftmargin 1in
+\topmargin 1in
+\rightmargin 1in
+\bottommargin 2in
+\secnumdepth 3
+\tocdepth 3
+\paragraph_separation indent
+\paragraph_indentation default
+\quotes_language english
+\papercolumns 1
+\papersides 1
+\paperpagestyle default
+\tracking_changes false
+\output_changes false
+\html_math_output 0
+\html_css_as_file 0
+\html_be_strict false
+\end_header
+
+\begin_body
+
+\begin_layout Subsection
+\begin_inset CommandInset label
+LatexCommand label
+name "sec:Tutorial-3d-hex8-dike"
+
+\end_inset
+
+Dike Intrusion Example
+\end_layout
+
+\begin_layout Standard
+PyLith features discussed in this tutorial:
+\end_layout
+
+\begin_layout Itemize
+Fault opening via prescribed tractions to mimic a dike instrusion
+\end_layout
+
+\begin_layout Itemize
+Dirichlet boundary conditions
+\end_layout
+
+\begin_layout Itemize
+Elastic material
+\end_layout
+
+\begin_layout Itemize
+VTK output
+\end_layout
+
+\begin_layout Subsubsection
+Overview
+\end_layout
+
+\begin_layout Standard
+This set of examples describes a problem where prescribed tensile tractions
+ are imposed on a fault to mimic a dike intrusion.
+ The example is contained in the directory 
+\family typewriter
+examples/3d/hex8
+\family default
+, and the corresponding 
+\family typewriter
+.cfg
+\family default
+ file is 
+\family typewriter
+step20.cfg
+\family default
+.
+ The example may be run as follows:
+\end_layout
+
+\begin_layout LyX-Code
+pylith step20.cfg
+\end_layout
+
+\begin_layout Standard
+This will cause PyLith to read the default parameters in 
+\family typewriter
+pylithapp.cfg
+\family default
+, and then override or augment them with the additional parameters in the
+ 
+\family typewriter
+step20.cfg
+\family default
+ file.
+ The 
+\family typewriter
+.cfg
+\family default
+ file is extensively documented, to provide detailed information on the
+ various parameters.
+\end_layout
+
+\begin_layout Subsubsection
+Step20 - Static Dike Intrusion
+\end_layout
+
+\begin_layout Standard
+The 
+\family typewriter
+step20.cfg
+\family default
+ file defines a problem with spatially varying tensile normal tractions
+ on the fault surface associated with a fluid intrusion.
+ The lateral sides and bottom of the domain are fixed using Dirichlet (roller)
+ boundary conditions.
+ As in the other examples, we also setup output for the ground surface.
+\end_layout
+
+\begin_layout Standard
+We use the FaultCohesiveDyn object to impose tractions on the fault surface.
+ We must include a fault constitutive model so we choose static friction
+ with a coefficient of friction of 0.1.
+ The coefficient of friction is irrelevant for the center of the fault where
+ we impose uniform tensile tractions (10 MPa) and the fault opens, but it
+ facilitates clamping the edges of the fault via compressive normal tractions
+ (-100 MPa).
+ Note that we must set the property 
+\family typewriter
+open_free_surface
+\family default
+ to True in order for the tractions to be imposed when the fault is open;
+ the default behavior for fault opening is a free surface (the two sides
+ of the fault are completely uncoupled).
+ The most important fault parameters for prescribing the tensile fault tractions
+ are
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.timedependent.interfaces.fault]
+\end_layout
+
+\begin_layout LyX-Code
+open_free_surface = True
+\begin_inset Newline newline
+\end_inset
+
+
+\end_layout
+
+\begin_layout LyX-Code
+traction_perturbation = pylith.faults.TractPerturbation
+\begin_inset Newline newline
+\end_inset
+
+
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.timedependent.interfaces.fault.traction_perturbation]
+\end_layout
+
+\begin_layout LyX-Code
+db_initial = spatialdata.spatialdb.SimpleDB
+\end_layout
+
+\begin_layout LyX-Code
+db_initial.label = Initial fault tractions
+\end_layout
+
+\begin_layout LyX-Code
+db_initial.iohandler.filename = spatialdb/tractions_opening.spatialdb
+\end_layout
+
+\begin_layout LyX-Code
+db_initial.query_type = nearest 
+\end_layout
+
+\begin_layout Standard
+When we have run the simulation, the output VTK files will be contained
+ in 
+\family typewriter
+examples/3d/hex8/output
+\family default
+ (all with a prefix of 
+\family typewriter
+step20
+\family default
+).
+ Results using ParaView are shown in Figure 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "fig:step20-disp"
+
+\end_inset
+
+.
+\end_layout
+
+\begin_layout Standard
+\begin_inset Float figure
+wide false
+sideways false
+status open
+
+\begin_layout Plain Layout
+\align center
+\begin_inset Graphics
+	filename figs/step20_disp.png
+	lyxscale 50
+	width 10cm
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Plain Layout
+\begin_inset Caption
+
+\begin_layout Plain Layout
+Displacement magnitude for example 
+\family typewriter
+step20
+\family default
+ visualized using ParaView.
+ 
+\begin_inset CommandInset label
+LatexCommand label
+name "fig:step20-disp"
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\end_body
+\end_document

Modified: short/3D/PyLith/branches/v1.7-trunk/doc/userguide/tutorials/3dhex8/friction/friction.lyx
===================================================================
--- short/3D/PyLith/branches/v1.7-trunk/doc/userguide/tutorials/3dhex8/friction/friction.lyx	2012-06-25 04:52:47 UTC (rev 20403)
+++ short/3D/PyLith/branches/v1.7-trunk/doc/userguide/tutorials/3dhex8/friction/friction.lyx	2012-06-25 16:38:44 UTC (rev 20404)
@@ -1,1192 +1,1199 @@
-#LyX 2.0 created this file. For more info see http://www.lyx.org/
-\lyxformat 413
-\begin_document
-\begin_header
-\textclass book
-\begin_preamble
-
-\end_preamble
-\use_default_options false
-\maintain_unincluded_children false
-\language english
-\language_package default
-\inputencoding latin1
-\fontencoding global
-\font_roman default
-\font_sans default
-\font_typewriter default
-\font_default_family default
-\use_non_tex_fonts false
-\font_sc false
-\font_osf false
-\font_sf_scale 100
-\font_tt_scale 100
-
-\graphics default
-\default_output_format default
-\output_sync 0
-\bibtex_command default
-\index_command default
-\paperfontsize default
-\spacing single
-\use_hyperref false
-\papersize default
-\use_geometry true
-\use_amsmath 0
-\use_esint 0
-\use_mhchem 1
-\use_mathdots 1
-\cite_engine basic
-\use_bibtopic false
-\use_indices false
-\paperorientation portrait
-\suppress_date false
-\use_refstyle 0
-\index Index
-\shortcut idx
-\color #008000
-\end_index
-\leftmargin 1in
-\topmargin 1in
-\rightmargin 1in
-\bottommargin 2in
-\secnumdepth 3
-\tocdepth 3
-\paragraph_separation indent
-\paragraph_indentation default
-\quotes_language english
-\papercolumns 1
-\papersides 1
-\paperpagestyle default
-\tracking_changes false
-\output_changes false
-\html_math_output 0
-\html_css_as_file 0
-\html_be_strict false
-\end_header
-
-\begin_body
-
-\begin_layout Subsection
-\begin_inset CommandInset label
-LatexCommand label
-name "sec:Tutorial-3d-hex8-friction"
-
-\end_inset
-
-Fault Friction Examples
-\end_layout
-
-\begin_layout Standard
-PyLith features discussed in this tutorial:
-\end_layout
-
-\begin_layout Itemize
-Static fault friction
-\end_layout
-
-\begin_layout Itemize
-Slip-weakening fault friction
-\end_layout
-
-\begin_layout Itemize
-Rate-and-state fault friction
-\end_layout
-
-\begin_layout Itemize
-Nonlinear solver
-\end_layout
-
-\begin_layout Subsubsection
-Overview
-\end_layout
-
-\begin_layout Standard
-This set of examples provides an introduction to using fault friction in
- static and quasi-static problems with PyLith.
- Dynamic problems with fault friction are discussed in Section 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "sec:tutorial:shearwave:quad4"
-
-\end_inset
-
-.
- The boundary conditions are all either static or quasi-static Dirichlet
- conditions, and only elastic materials are used.
- In all the fault friction examples we apply axial (x) displacements on
- both the positive and negative x-faces to maintain a compressive normal
- tractions on the fault.
- Otherwise, there would be no frictional resistance.
- Fault friction generates nonlinear behavior, so we use the nonlinear solver.
- All of the examples are contained in the directory 
-\family typewriter
-examples/3d/hex8
-\family default
-, and the corresponding 
-\family typewriter
-.cfg
-\family default
- files are 
-\family typewriter
-step10.cfg
-\family default
-, 
-\family typewriter
-step11.cfg
-\family default
-, 
-\family typewriter
-step12.cfg
-\family default
-, 
-\family typewriter
-step13.cfg
-\family default
-, and 
-\family typewriter
-step14.cfg
-\family default
-.
- Each example may be run as follows:
-\end_layout
-
-\begin_layout LyX-Code
-pylith stepXX.cfg
-\end_layout
-
-\begin_layout Standard
-This will cause PyLith to read the default parameters in 
-\family typewriter
-pylithapp.cfg
-\family default
-, and then override or augment them with the additional parameters in the
- 
-\family typewriter
-stepXX.cfg
-\family default
- file.
- Each 
-\family typewriter
-.cfg
-\family default
- file is extensively documented, to provide detailed information on the
- various parameters.
-\end_layout
-
-\begin_layout Subsubsection
-Step10 - Static Friction (Stick) with Static Dirichlet Boundary Conditions
-\end_layout
-
-\begin_layout Standard
-The 
-\family typewriter
-step10.cfg
-\family default
- file defines a problem that is identical to example step01, except for
- the presence of a vertical fault with static friction.
- In this case, the applied displacements are insufficient to cause the fault
- to slip, so the solution is identical to that in example step01.
- As in previous examples involving faults, we must first provide an array
- defining the fault interfaces:
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.timedependent]
-\end_layout
-
-\begin_layout LyX-Code
-# Set interfaces to an array of 1 fault: 'fault'.
-\end_layout
-
-\begin_layout LyX-Code
-interfaces = [fault]
-\end_layout
-
-\begin_layout Standard
-Since all fault friction models are nonlinear we must also use the nonlinear
- solver:
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.timedependent.implicit]
-\end_layout
-
-\begin_layout LyX-Code
-# Fault friction is a nonlinear problem so we need to use the nonlinear
-\end_layout
-
-\begin_layout LyX-Code
-# solver.
-\end_layout
-
-\begin_layout LyX-Code
-solver = pylith.problems.SolverNonlinear
-\end_layout
-
-\begin_layout Standard
-We need to change the fault interface from the default (
-\family typewriter
-FaultCohesiveKin
-\family default
-) to 
-\family typewriter
-FaultCohesiveDyn
-\family default
- and we set the friction model to use:
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.timedependent.interfaces]
-\end_layout
-
-\begin_layout LyX-Code
-# Change fault to dynamic fault interface.
-\end_layout
-
-\begin_layout LyX-Code
-fault = pylith.faults.FaultCohesiveDyn
-\begin_inset Newline newline
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.timedependent.interfaces.fault]
-\end_layout
-
-\begin_layout LyX-Code
-# Use the static friction model.
-\end_layout
-
-\begin_layout LyX-Code
-friction = pylith.friction.StaticFriction
-\end_layout
-
-\begin_layout Standard
-The 
-\family typewriter
-StaticFriction
-\family default
- model requires values for the coefficient of friction and the cohesion
- (see Section 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "sub:Fault-Constitutive-Models"
-
-\end_inset
-
-).
- We provide both of these using a 
-\family typewriter
-UniformDB
-\family default
-:
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.timedependent.interfaces.fault]
-\end_layout
-
-\begin_layout LyX-Code
-# Set static friction model parameters using a uniform DB.
- Set the
-\end_layout
-
-\begin_layout LyX-Code
-# static coefficient of friction to 0.6 and cohesion to 0.0 Pa.
-\end_layout
-
-\begin_layout LyX-Code
-friction.db_properties = spatialdata.spatialdb.UniformDB
-\end_layout
-
-\begin_layout LyX-Code
-friction.db_properties.label = Static friction
-\end_layout
-
-\begin_layout LyX-Code
-friction.db_properties.values = [friction-coefficient,cohesion]
-\end_layout
-
-\begin_layout LyX-Code
-friction.db_properties.data = [0.6,0.0*Pa]
-\end_layout
-
-\begin_layout Standard
-Fault friction models require additional PETSc settings:
-\end_layout
-
-\begin_layout LyX-Code
-# NOTE: There are additional settings specific to fault friction.
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.petsc]
-\end_layout
-
-\begin_layout LyX-Code
-# Friction sensitivity solve used to compute the increment in slip
-\end_layout
-
-\begin_layout LyX-Code
-# associated with changes in the Lagrange multiplier imposed by the
-\end_layout
-
-\begin_layout LyX-Code
-# fault constitutive model.
-\end_layout
-
-\begin_layout LyX-Code
-friction_pc_type = asm
-\end_layout
-
-\begin_layout LyX-Code
-friction_sub_pc_factor_shift_type = nonzero
-\end_layout
-
-\begin_layout LyX-Code
-friction_ksp_max_it = 25
-\end_layout
-
-\begin_layout LyX-Code
-friction_ksp_gmres_restart = 30
-\end_layout
-
-\begin_layout LyX-Code
-# Uncomment to view details of friction sensitivity solve.
-\end_layout
-
-\begin_layout LyX-Code
-#friction_ksp_monitor = true
-\end_layout
-
-\begin_layout LyX-Code
-#friction_ksp_view = true
-\end_layout
-
-\begin_layout LyX-Code
-friction_ksp_converged_reason = true
-\end_layout
-
-\begin_layout LyX-Code
-
-\end_layout
-
-\begin_layout Standard
-When we have run the simulation, the output VTK files will be contained
- in 
-\family typewriter
-examples/3d/hex8/output
-\family default
- (all with a prefix of 
-\family typewriter
-step10
-\family default
-).
- Results using ParaView are shown in Figure 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "fig:step10-fault-traction-slip"
-
-\end_inset
-
-.
-\end_layout
-
-\begin_layout Standard
-\begin_inset Float figure
-wide false
-sideways false
-status open
-
-\begin_layout Plain Layout
-\align center
-\begin_inset Graphics
-	filename figs/step10-fault-traction-slip.jpg
-	lyxscale 50
-	width 10cm
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Plain Layout
-\begin_inset Caption
-
-\begin_layout Plain Layout
-Magnitude of tractions on the fault for example step10 visualized using
- ParaView.
- 
-\begin_inset CommandInset label
-LatexCommand label
-name "fig:step10-fault-traction-slip"
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Subsubsection
-Step11 - Static Friction (Slip) with Static Dirichlet Boundary Conditions
-\end_layout
-
-\begin_layout Standard
-In step11 we apply twice as much shear displacement as in step10, which
- is sufficient to induce slip on the fault.
- All other settings are identical.
- To change the amount of shear displacement, we change the spatial database
- for the positive and negative x-faces to a 
-\family typewriter
-UniformDB
-\family default
-, and apply the altered values within the 
-\family typewriter
-.cfg
-\family default
- file:
-\end_layout
-
-\begin_layout LyX-Code
-# +x face
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.timedependent.bc.x_pos]
-\end_layout
-
-\begin_layout LyX-Code
-bc_dof = [0, 1]
-\end_layout
-
-\begin_layout LyX-Code
-label = face_xpos
-\end_layout
-
-\begin_layout LyX-Code
-db_initial = spatialdata.spatialdb.UniformDB
-\end_layout
-
-\begin_layout LyX-Code
-db_initial.label = Dirichlet BC on +x
-\end_layout
-
-\begin_layout LyX-Code
-db_initial.values = [displacement-x,displacement-y]
-\end_layout
-
-\begin_layout LyX-Code
-db_initial.data = [-1.0*m,2.0*m]
-\end_layout
-
-\begin_layout LyX-Code
-
-\end_layout
-
-\begin_layout LyX-Code
-# -x face
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.timedependent.bc.x_neg]
-\end_layout
-
-\begin_layout LyX-Code
-bc_dof = [0, 1]
-\end_layout
-
-\begin_layout LyX-Code
-label = face_xneg
-\end_layout
-
-\begin_layout LyX-Code
-db_initial = spatialdata.spatialdb.UniformDB
-\end_layout
-
-\begin_layout LyX-Code
-db_initial.label = Dirichlet BC on -x
-\end_layout
-
-\begin_layout LyX-Code
-db_initial.values = [displacement-x,displacement-y]
-\end_layout
-
-\begin_layout LyX-Code
-db_initial.data = [1.0*m,-2.0*m]
-\end_layout
-
-\begin_layout Standard
-When we have run the simulation, the output VTK files will be contained
- in 
-\family typewriter
-examples/3d/hex8/output
-\family default
- (all with a prefix of 
-\family typewriter
-step11
-\family default
-).
- Results using ParaView are shown in Figure 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "fig:step11-fault-traction-slip"
-
-\end_inset
-
-.
-\end_layout
-
-\begin_layout Standard
-\begin_inset Float figure
-wide false
-sideways false
-status open
-
-\begin_layout Plain Layout
-\align center
-\begin_inset Graphics
-	filename figs/step11-fault-traction-slip.jpg
-	lyxscale 50
-	width 10cm
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Plain Layout
-\begin_inset Caption
-
-\begin_layout Plain Layout
-Magnitude of tractions on the fault for example step10 visualized using
- ParaView.
- Vectors of fault slip are also plotted.
- Note that PyLith outputs slip in the fault coordinate system, so we transform
- them to the global coordinate system using the Calculator in ParaView.
- A more general approach involves outputing the fault coordinate system
- information and using these fields in the Calculator.
- 
-\begin_inset CommandInset label
-LatexCommand label
-name "fig:step11-fault-traction-slip"
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Subsubsection
-Step12 - Static Friction with Quasi-static Dirichlet Boundary Conditions
-\end_layout
-
-\begin_layout Standard
-The 
-\family typewriter
-step12.cfg
-\family default
- file describes a problem that is similar to examples step10 and step11,
- except that we apply velocity boundary conditions and run the simulation
- for 200 years.
- Once fault friction is overcome, the fault slips at a steady rate.
- To prevent convergence problems we set the time step size to a constant
- value of 5 years:
-\end_layout
-
-\begin_layout LyX-Code
-# Change the total simulation time to 200 years, and use a constant time
-\end_layout
-
-\begin_layout LyX-Code
-# step size of 5 years.
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.timedependent.implicit.time_step]
-\end_layout
-
-\begin_layout LyX-Code
-total_time = 200.0*year
-\end_layout
-
-\begin_layout LyX-Code
-dt = 5.0*year
-\end_layout
-
-\begin_layout Standard
-As in the other fault friction examples, we apply initial displacements
- along the x-axis (to maintain a compressive stress on the fault), and we
- apply velocity boundary conditions that yield a left-lateral sense of motion:
-\end_layout
-
-\begin_layout LyX-Code
-# +x face -- Dirichlet
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.timedependent.bc.x_pos]
-\end_layout
-
-\begin_layout LyX-Code
-bc_dof = [0,1]
-\end_layout
-
-\begin_layout LyX-Code
-label = face_xpos
-\end_layout
-
-\begin_layout LyX-Code
-db_initial = spatialdata.spatialdb.UniformDB
-\end_layout
-
-\begin_layout LyX-Code
-db_initial.label = Dirichlet BC on +x
-\end_layout
-
-\begin_layout LyX-Code
-db_initial.values = [displacement-x,displacement-y]
-\end_layout
-
-\begin_layout LyX-Code
-db_initial.data = [-1.0*m,0.0*m]
-\end_layout
-
-\begin_layout LyX-Code
-db_rate = spatialdata.spatialdb.UniformDB
-\end_layout
-
-\begin_layout LyX-Code
-db_rate.label = Dirichlet rate BC on +x
-\end_layout
-
-\begin_layout LyX-Code
-db_rate.values = [displacement-rate-x,displacement-rate-y,rate-start-time]
-\end_layout
-
-\begin_layout LyX-Code
-db_rate.data = [0.0*cm/year,1.0*cm/year,0.0*year]
-\begin_inset Newline newline
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\end_layout
-
-\begin_layout LyX-Code
-# -x face
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.timedependent.bc.x_neg]
-\end_layout
-
-\begin_layout LyX-Code
-bc_dof = [0, 1]
-\end_layout
-
-\begin_layout LyX-Code
-label = face_xneg
-\end_layout
-
-\begin_layout LyX-Code
-db_initial.label = Dirichlet BC on -x
-\end_layout
-
-\begin_layout LyX-Code
-db_rate = spatialdata.spatialdb.UniformDB
-\end_layout
-
-\begin_layout LyX-Code
-db_rate.label = Dirichlet rate BC on -x
-\end_layout
-
-\begin_layout LyX-Code
-db_rate.values = [displacement-rate-x,displacement-rate-y,rate-start-time]
-\end_layout
-
-\begin_layout LyX-Code
-db_rate.data = [0.0*cm/year,-1.0*cm/year,0.0*year]
-\end_layout
-
-\begin_layout Standard
-For this example, we keep the same coefficient of friction as examples step10
- and step11, but we include a cohesion of 2 MPa:
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.timedependent.interfaces.fault]
-\end_layout
-
-\begin_layout LyX-Code
-# Set static friction model parameters using a uniform DB.
- Set the
-\end_layout
-
-\begin_layout LyX-Code
-# static coefficient of friction to 0.6 and cohesion to 2.0 MPa.
-\end_layout
-
-\begin_layout LyX-Code
-friction.db_properties = spatialdata.spatialdb.UniformDB
-\end_layout
-
-\begin_layout LyX-Code
-friction.db_properties.label = Static friction
-\end_layout
-
-\begin_layout LyX-Code
-friction.db_properties.values = [friction-coefficient,cohesion]
-\end_layout
-
-\begin_layout LyX-Code
-friction.db_properties.data = [0.6,2.0*MPa]
-\end_layout
-
-\begin_layout Standard
-When we have run the simulation, the output VTK files will be contained
- in 
-\family typewriter
-examples/3d/hex8/output
-\family default
- (all with a prefix of 
-\family typewriter
-step12
-\family default
-).
- Results using ParaView are shown in Figure 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "fig:step12-displ-t200"
-
-\end_inset
-
-.
-\end_layout
-
-\begin_layout Standard
-\begin_inset Float figure
-wide false
-sideways false
-status open
-
-\begin_layout Plain Layout
-\align center
-\begin_inset Graphics
-	filename figs/step12-displ-t200.jpg
-	lyxscale 50
-	width 10cm
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Plain Layout
-\begin_inset Caption
-
-\begin_layout Plain Layout
-Displacement field for example step12 at t = 200 years visualized using
- ParaView.
- The mesh has been distorted by the computed displacements (magnified by
- 500), and the vectors show the computed displacements.
-\begin_inset CommandInset label
-LatexCommand label
-name "fig:step12-displ-t200"
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Subsubsection
-Step13 - Slip-weakening Friction with Quasi-static Dirichlet Boundary Conditions
-\end_layout
-
-\begin_layout Standard
-In this example we replace the static friction fault constitutive model
- in step12 with a slip-weakening friction fault constitutive model.
- Fault friction is overcome at about t = 80 years, the fault slips in each
- subsequent time step.
- We again use a constant time step size of 5 years and apply the same intial
- displacement and velocity boundary conditions.
-\end_layout
-
-\begin_layout Standard
-We first define the friction model for the simulation:
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.timedependent.interfaces.fault]
-\end_layout
-
-\begin_layout LyX-Code
-# Use the slip-weakening friction model.
-\end_layout
-
-\begin_layout LyX-Code
-friction = pylith.friction.SlipWeakening
-\end_layout
-
-\begin_layout Standard
-The slip-weakening constitutive model requires a static coefficient of friction,
- a dynamic coefficient of friction, a slip weakening parameter, and a cohesion
- (see Section 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "sub:Fault-Constitutive-Models"
-
-\end_inset
-
-):
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.timedependent.interfaces.fault]
-\end_layout
-
-\begin_layout LyX-Code
-# Set slip-weakening friction model parameters using a uniform DB.
- Set the
-\end_layout
-
-\begin_layout LyX-Code
-# parameters as follows:
-\end_layout
-
-\begin_layout LyX-Code
-# static coefficient of friction: 0.6
-\end_layout
-
-\begin_layout LyX-Code
-# dynamic coefficient of friction: 0.5
-\end_layout
-
-\begin_layout LyX-Code
-# slip-weakening parameter: 0.2 m
-\end_layout
-
-\begin_layout LyX-Code
-# cohesion: 0 Pa
-\end_layout
-
-\begin_layout LyX-Code
-friction.db_properties = spatialdata.spatialdb.UniformDB
-\end_layout
-
-\begin_layout LyX-Code
-friction.db_properties.label = Slip weakening
-\end_layout
-
-\begin_layout LyX-Code
-friction.db_properties.values = [static-coefficient,dynamic-coefficient,
-\begin_inset Newline newline
-\end_inset
-
-slip-weakening-parameter,cohesion]
-\end_layout
-
-\begin_layout LyX-Code
-friction.db_properties.data = [0.6,0.5,0.2*m,0.0*Pa]
-\end_layout
-
-\begin_layout Standard
-When we have run the simulation, the output VTK files will be contained
- in 
-\family typewriter
-examples/3d/hex8/output
-\family default
- (all with a prefix of 
-\family typewriter
-step1
-\family default
-3).
- Results using ParaView are shown in Figure 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "fig:step13-displ-t200"
-
-\end_inset
-
-.
-\end_layout
-
-\begin_layout Standard
-\begin_inset Float figure
-wide false
-sideways false
-status open
-
-\begin_layout Plain Layout
-\align center
-\begin_inset Graphics
-	filename figs/step13-displ-t200.jpg
-	lyxscale 50
-	width 10cm
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Plain Layout
-\begin_inset Caption
-
-\begin_layout Plain Layout
-Displacement field for example step13 at t = 200 years visualized using
- ParaView.
- The mesh has been distorted by the computed displacements (magnified by
- 500), and the vectors show the computed displacements.
-\begin_inset CommandInset label
-LatexCommand label
-name "fig:step13-displ-t200"
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Subsubsection
-Step14 - Rate-and-state Friction with Quasi-static Dirichlet Boundary Conditions
-\end_layout
-
-\begin_layout Standard
-In step14 we use a rate-and-state friction model with an ageing law instead
- of a slip-weakening friction model.
- Slip begins to occur at about t = 45 years, and continues in each subsequent
- time step.
- We again use a constant time step size of 5 years and apply the same intial
- displacement and velocity boundary conditions.
-\end_layout
-
-\begin_layout Standard
-We first define the friction model for the simulation:
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.timedependent.interfaces.fault]
-\end_layout
-
-\begin_layout LyX-Code
-# Use the rate-and-state aging friction model.
-\end_layout
-
-\begin_layout LyX-Code
-friction = pylith.friction.RateStateAgeing
-\end_layout
-
-\begin_layout Standard
-The rate-and-state constitutive model requires a reference coefficient of
- friction, a reference slip rate, a slip weakening parameter, an a-value,
- a b-value, and a cohesion (see 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "sub:Fault-Constitutive-Models"
-
-\end_inset
-
-):
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.timedependent.interfaces.fault]
-\end_layout
-
-\begin_layout LyX-Code
-# Set rate-and-state parameters using a UniformDB.
- Set the parameters as
-\end_layout
-
-\begin_layout LyX-Code
-# follows:
-\end_layout
-
-\begin_layout LyX-Code
-# reference coefficient of friction: 0.6
-\end_layout
-
-\begin_layout LyX-Code
-# reference slip rate: 1.0e-06 m/s
-\end_layout
-
-\begin_layout LyX-Code
-# slip-weakening parameter: 0.037 m
-\end_layout
-
-\begin_layout LyX-Code
-# a: 0.0125
-\end_layout
-
-\begin_layout LyX-Code
-# b: 0.0172
-\end_layout
-
-\begin_layout LyX-Code
-# cohesion: 0 Pa
-\end_layout
-
-\begin_layout LyX-Code
-friction.db_properties = spatialdata.spatialdb.UniformDB
-\end_layout
-
-\begin_layout LyX-Code
-friction.db_properties.label = Rate Stete Ageing
-\end_layout
-
-\begin_layout LyX-Code
-friction.db_properties.values = [reference-friction-coefficient,reference-slip-rat
-e,
-\begin_inset Newline newline
-\end_inset
-
-characteristic-slip-distance,constitutive-parameter-a,constitutive-parameter-b,c
-ohesion]
-\end_layout
-
-\begin_layout LyX-Code
-friction.db_properties.data = [0.6,1.0e-6*m/s,0.0370*m,0.0125,0.0172,0.0*Pa]
-\end_layout
-
-\begin_layout Standard
-For this model, we also want to set the initial value of the state variable:
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.timedependent.interfaces.fault]
-\end_layout
-
-\begin_layout LyX-Code
-# Set spatial database for the initial value of the state variable.
-\end_layout
-
-\begin_layout LyX-Code
-friction.db_initial_state = spatialdata.spatialdb.UniformDB
-\end_layout
-
-\begin_layout LyX-Code
-friction.db_initial_state.label = Rate State Ageing State
-\end_layout
-
-\begin_layout LyX-Code
-friction.db_initial_state.values = [state-variable]
-\end_layout
-
-\begin_layout LyX-Code
-friction.db_initial_state.data = [92.7*s]
-\end_layout
-
-\begin_layout Standard
-When we have run the simulation, the output VTK files will be contained
- in 
-\family typewriter
-examples/3d/hex8/output
-\family default
- (all with a prefix of 
-\family typewriter
-step1
-\family default
-4).
- Results using ParaView are shown in Figure 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "fig:step14-displ-t200"
-
-\end_inset
-
-.
-\end_layout
-
-\begin_layout Standard
-\begin_inset Float figure
-wide false
-sideways false
-status open
-
-\begin_layout Plain Layout
-\align center
-\begin_inset Graphics
-	filename figs/step14-displ-t200.jpg
-	lyxscale 50
-	width 10cm
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Plain Layout
-\begin_inset Caption
-
-\begin_layout Plain Layout
-Displacement field for example step14 at t = 200 years visualized using
- ParaView.
- The mesh has been distorted by the computed displacements (magnified by
- 500), and the vectors show the computed displacements.
-\begin_inset CommandInset label
-LatexCommand label
-name "fig:step14-displ-t200"
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_body
-\end_document
+#LyX 2.0 created this file. For more info see http://www.lyx.org/
+\lyxformat 413
+\begin_document
+\begin_header
+\textclass book
+\begin_preamble
+
+\end_preamble
+\use_default_options false
+\maintain_unincluded_children false
+\language english
+\language_package default
+\inputencoding latin1
+\fontencoding global
+\font_roman default
+\font_sans default
+\font_typewriter default
+\font_default_family default
+\use_non_tex_fonts false
+\font_sc false
+\font_osf false
+\font_sf_scale 100
+\font_tt_scale 100
+
+\graphics default
+\default_output_format default
+\output_sync 0
+\bibtex_command default
+\index_command default
+\paperfontsize default
+\spacing single
+\use_hyperref false
+\papersize default
+\use_geometry true
+\use_amsmath 0
+\use_esint 0
+\use_mhchem 1
+\use_mathdots 1
+\cite_engine basic
+\use_bibtopic false
+\use_indices false
+\paperorientation portrait
+\suppress_date false
+\use_refstyle 0
+\index Index
+\shortcut idx
+\color #008000
+\end_index
+\leftmargin 1in
+\topmargin 1in
+\rightmargin 1in
+\bottommargin 2in
+\secnumdepth 3
+\tocdepth 3
+\paragraph_separation indent
+\paragraph_indentation default
+\quotes_language english
+\papercolumns 1
+\papersides 1
+\paperpagestyle default
+\tracking_changes false
+\output_changes false
+\html_math_output 0
+\html_css_as_file 0
+\html_be_strict false
+\end_header
+
+\begin_body
+
+\begin_layout Subsection
+\begin_inset CommandInset label
+LatexCommand label
+name "sec:Tutorial-3d-hex8-friction"
+
+\end_inset
+
+Fault Friction Examples
+\end_layout
+
+\begin_layout Standard
+PyLith features discussed in this tutorial:
+\end_layout
+
+\begin_layout Itemize
+Static fault friction
+\end_layout
+
+\begin_layout Itemize
+Slip-weakening fault friction
+\end_layout
+
+\begin_layout Itemize
+Rate-and-state fault friction
+\end_layout
+
+\begin_layout Itemize
+Nonlinear solver
+\end_layout
+
+\begin_layout Subsubsection
+Overview
+\end_layout
+
+\begin_layout Standard
+This set of examples provides an introduction to using fault friction in
+ static and quasi-static problems with PyLith.
+ Dynamic problems with fault friction are discussed in Section 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "sec:tutorial:shearwave:quad4"
+
+\end_inset
+
+.
+ The boundary conditions are all either static or quasi-static Dirichlet
+ conditions, and only elastic materials are used.
+ In all the fault friction examples we apply axial (x) displacements on
+ both the positive and negative x-faces to maintain a compressive normal
+ tractions on the fault.
+ Otherwise, there would be no frictional resistance.
+ Fault friction generates nonlinear behavior, so we use the nonlinear solver.
+ All of the examples are contained in the directory 
+\family typewriter
+examples/3d/hex8
+\family default
+, and the corresponding 
+\family typewriter
+.cfg
+\family default
+ files are 
+\family typewriter
+step10.cfg
+\family default
+, 
+\family typewriter
+step11.cfg
+\family default
+, 
+\family typewriter
+step12.cfg
+\family default
+, 
+\family typewriter
+step13.cfg
+\family default
+, and 
+\family typewriter
+step14.cfg
+\family default
+.
+ Each example may be run as follows:
+\end_layout
+
+\begin_layout LyX-Code
+pylith stepXX.cfg
+\end_layout
+
+\begin_layout Standard
+This will cause PyLith to read the default parameters in 
+\family typewriter
+pylithapp.cfg
+\family default
+, and then override or augment them with the additional parameters in the
+ 
+\family typewriter
+stepXX.cfg
+\family default
+ file.
+ Each 
+\family typewriter
+.cfg
+\family default
+ file is extensively documented, to provide detailed information on the
+ various parameters.
+\end_layout
+
+\begin_layout Subsubsection
+Step10 - Static Friction (Stick) with Static Dirichlet Boundary Conditions
+\end_layout
+
+\begin_layout Standard
+The 
+\family typewriter
+step10.cfg
+\family default
+ file defines a problem that is identical to example 
+\family typewriter
+step01
+\family default
+, except for the presence of a vertical fault with static friction.
+ In this case, the applied displacements are insufficient to cause the fault
+ to slip, so the solution is identical to that in example 
+\family typewriter
+step01
+\family default
+.
+ As in previous examples involving faults, we must first provide an array
+ defining the fault interfaces:
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.timedependent]
+\end_layout
+
+\begin_layout LyX-Code
+# Set interfaces to an array of 1 fault: 'fault'.
+\end_layout
+
+\begin_layout LyX-Code
+interfaces = [fault]
+\end_layout
+
+\begin_layout Standard
+Since all fault friction models are nonlinear we must also use the nonlinear
+ solver:
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.timedependent.implicit]
+\end_layout
+
+\begin_layout LyX-Code
+# Fault friction is a nonlinear problem so we need to use the nonlinear
+\end_layout
+
+\begin_layout LyX-Code
+# solver.
+\end_layout
+
+\begin_layout LyX-Code
+solver = pylith.problems.SolverNonlinear
+\end_layout
+
+\begin_layout Standard
+We need to change the fault interface from the default (
+\family typewriter
+FaultCohesiveKin
+\family default
+) to 
+\family typewriter
+FaultCohesiveDyn
+\family default
+ and we set the friction model to use:
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.timedependent.interfaces]
+\end_layout
+
+\begin_layout LyX-Code
+# Change fault to dynamic fault interface.
+\end_layout
+
+\begin_layout LyX-Code
+fault = pylith.faults.FaultCohesiveDyn
+\begin_inset Newline newline
+\end_inset
+
+
+\begin_inset Newline newline
+\end_inset
+
+
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.timedependent.interfaces.fault]
+\end_layout
+
+\begin_layout LyX-Code
+# Use the static friction model.
+\end_layout
+
+\begin_layout LyX-Code
+friction = pylith.friction.StaticFriction
+\end_layout
+
+\begin_layout Standard
+The 
+\family typewriter
+StaticFriction
+\family default
+ model requires values for the coefficient of friction and the cohesion
+ (see Section 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "sec:fault:constitutive:models"
+
+\end_inset
+
+).
+ We provide both of these using a 
+\family typewriter
+UniformDB
+\family default
+:
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.timedependent.interfaces.fault]
+\end_layout
+
+\begin_layout LyX-Code
+# Set static friction model parameters using a uniform DB.
+ Set the
+\end_layout
+
+\begin_layout LyX-Code
+# static coefficient of friction to 0.6 and cohesion to 0.0 Pa.
+\end_layout
+
+\begin_layout LyX-Code
+friction.db_properties = spatialdata.spatialdb.UniformDB
+\end_layout
+
+\begin_layout LyX-Code
+friction.db_properties.label = Static friction
+\end_layout
+
+\begin_layout LyX-Code
+friction.db_properties.values = [friction-coefficient,cohesion]
+\end_layout
+
+\begin_layout LyX-Code
+friction.db_properties.data = [0.6,0.0*Pa]
+\end_layout
+
+\begin_layout Standard
+Fault friction models require additional PETSc settings:
+\end_layout
+
+\begin_layout LyX-Code
+# NOTE: There are additional settings specific to fault friction.
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.petsc]
+\end_layout
+
+\begin_layout LyX-Code
+# Friction sensitivity solve used to compute the increment in slip
+\end_layout
+
+\begin_layout LyX-Code
+# associated with changes in the Lagrange multiplier imposed by the
+\end_layout
+
+\begin_layout LyX-Code
+# fault constitutive model.
+\end_layout
+
+\begin_layout LyX-Code
+friction_pc_type = asm
+\end_layout
+
+\begin_layout LyX-Code
+friction_sub_pc_factor_shift_type = nonzero
+\end_layout
+
+\begin_layout LyX-Code
+friction_ksp_max_it = 25
+\end_layout
+
+\begin_layout LyX-Code
+friction_ksp_gmres_restart = 30
+\end_layout
+
+\begin_layout LyX-Code
+# Uncomment to view details of friction sensitivity solve.
+\end_layout
+
+\begin_layout LyX-Code
+#friction_ksp_monitor = true
+\end_layout
+
+\begin_layout LyX-Code
+#friction_ksp_view = true
+\end_layout
+
+\begin_layout LyX-Code
+friction_ksp_converged_reason = true
+\end_layout
+
+\begin_layout LyX-Code
+
+\end_layout
+
+\begin_layout Standard
+When we have run the simulation, the output VTK files will be contained
+ in 
+\family typewriter
+examples/3d/hex8/output
+\family default
+ (all with a prefix of 
+\family typewriter
+step10
+\family default
+).
+ Results using ParaView are shown in Figure 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "fig:step10-fault-traction-slip"
+
+\end_inset
+
+.
+\end_layout
+
+\begin_layout Standard
+\begin_inset Float figure
+wide false
+sideways false
+status open
+
+\begin_layout Plain Layout
+\align center
+\begin_inset Graphics
+	filename figs/step10-fault-traction-slip.jpg
+	lyxscale 50
+	width 10cm
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Plain Layout
+\begin_inset Caption
+
+\begin_layout Plain Layout
+Magnitude of tractions on the fault for example step10 visualized using
+ ParaView.
+ 
+\begin_inset CommandInset label
+LatexCommand label
+name "fig:step10-fault-traction-slip"
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Subsubsection
+Step11 - Static Friction (Slip) with Static Dirichlet Boundary Conditions
+\end_layout
+
+\begin_layout Standard
+In step11 we apply twice as much shear displacement as in step10, which
+ is sufficient to induce slip on the fault.
+ All other settings are identical.
+ To change the amount of shear displacement, we change the spatial database
+ for the positive and negative x-faces to a 
+\family typewriter
+UniformDB
+\family default
+, and apply the altered values within the 
+\family typewriter
+.cfg
+\family default
+ file:
+\end_layout
+
+\begin_layout LyX-Code
+# +x face
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.timedependent.bc.x_pos]
+\end_layout
+
+\begin_layout LyX-Code
+bc_dof = [0, 1]
+\end_layout
+
+\begin_layout LyX-Code
+label = face_xpos
+\end_layout
+
+\begin_layout LyX-Code
+db_initial = spatialdata.spatialdb.UniformDB
+\end_layout
+
+\begin_layout LyX-Code
+db_initial.label = Dirichlet BC on +x
+\end_layout
+
+\begin_layout LyX-Code
+db_initial.values = [displacement-x,displacement-y]
+\end_layout
+
+\begin_layout LyX-Code
+db_initial.data = [-1.0*m,2.0*m]
+\end_layout
+
+\begin_layout LyX-Code
+
+\end_layout
+
+\begin_layout LyX-Code
+# -x face
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.timedependent.bc.x_neg]
+\end_layout
+
+\begin_layout LyX-Code
+bc_dof = [0, 1]
+\end_layout
+
+\begin_layout LyX-Code
+label = face_xneg
+\end_layout
+
+\begin_layout LyX-Code
+db_initial = spatialdata.spatialdb.UniformDB
+\end_layout
+
+\begin_layout LyX-Code
+db_initial.label = Dirichlet BC on -x
+\end_layout
+
+\begin_layout LyX-Code
+db_initial.values = [displacement-x,displacement-y]
+\end_layout
+
+\begin_layout LyX-Code
+db_initial.data = [1.0*m,-2.0*m]
+\end_layout
+
+\begin_layout Standard
+When we have run the simulation, the output VTK files will be contained
+ in 
+\family typewriter
+examples/3d/hex8/output
+\family default
+ (all with a prefix of 
+\family typewriter
+step11
+\family default
+).
+ Results using ParaView are shown in Figure 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "fig:step11-fault-traction-slip"
+
+\end_inset
+
+.
+\end_layout
+
+\begin_layout Standard
+\begin_inset Float figure
+wide false
+sideways false
+status open
+
+\begin_layout Plain Layout
+\align center
+\begin_inset Graphics
+	filename figs/step11-fault-traction-slip.jpg
+	lyxscale 50
+	width 10cm
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Plain Layout
+\begin_inset Caption
+
+\begin_layout Plain Layout
+Magnitude of tractions on the fault for example step10 visualized using
+ ParaView.
+ Vectors of fault slip are also plotted.
+ Note that PyLith outputs slip in the fault coordinate system, so we transform
+ them to the global coordinate system using the Calculator in ParaView.
+ A more general approach involves outputing the fault coordinate system
+ information and using these fields in the Calculator.
+ 
+\begin_inset CommandInset label
+LatexCommand label
+name "fig:step11-fault-traction-slip"
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Subsubsection
+Step12 - Static Friction with Quasi-Static Dirichlet Boundary Conditions
+\end_layout
+
+\begin_layout Standard
+The 
+\family typewriter
+step12.cfg
+\family default
+ file describes a problem that is similar to examples step10 and step11,
+ except that we apply velocity boundary conditions and run the simulation
+ for 200 years.
+ Once fault friction is overcome, the fault slips at a steady rate.
+ To prevent convergence problems we set the time step size to a constant
+ value of 5 years:
+\end_layout
+
+\begin_layout LyX-Code
+# Change the total simulation time to 200 years, and use a constant time
+\end_layout
+
+\begin_layout LyX-Code
+# step size of 5 years.
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.timedependent.implicit.time_step]
+\end_layout
+
+\begin_layout LyX-Code
+total_time = 200.0*year
+\end_layout
+
+\begin_layout LyX-Code
+dt = 5.0*year
+\end_layout
+
+\begin_layout Standard
+As in the other fault friction examples, we apply initial displacements
+ along the x-axis (to maintain a compressive stress on the fault), and we
+ apply velocity boundary conditions that yield a left-lateral sense of motion:
+\end_layout
+
+\begin_layout LyX-Code
+# +x face -- Dirichlet
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.timedependent.bc.x_pos]
+\end_layout
+
+\begin_layout LyX-Code
+bc_dof = [0,1]
+\end_layout
+
+\begin_layout LyX-Code
+label = face_xpos
+\end_layout
+
+\begin_layout LyX-Code
+db_initial = spatialdata.spatialdb.UniformDB
+\end_layout
+
+\begin_layout LyX-Code
+db_initial.label = Dirichlet BC on +x
+\end_layout
+
+\begin_layout LyX-Code
+db_initial.values = [displacement-x,displacement-y]
+\end_layout
+
+\begin_layout LyX-Code
+db_initial.data = [-1.0*m,0.0*m]
+\end_layout
+
+\begin_layout LyX-Code
+db_rate = spatialdata.spatialdb.UniformDB
+\end_layout
+
+\begin_layout LyX-Code
+db_rate.label = Dirichlet rate BC on +x
+\end_layout
+
+\begin_layout LyX-Code
+db_rate.values = [displacement-rate-x,displacement-rate-y,rate-start-time]
+\end_layout
+
+\begin_layout LyX-Code
+db_rate.data = [0.0*cm/year,1.0*cm/year,0.0*year]
+\begin_inset Newline newline
+\end_inset
+
+
+\begin_inset Newline newline
+\end_inset
+
+
+\end_layout
+
+\begin_layout LyX-Code
+# -x face
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.timedependent.bc.x_neg]
+\end_layout
+
+\begin_layout LyX-Code
+bc_dof = [0, 1]
+\end_layout
+
+\begin_layout LyX-Code
+label = face_xneg
+\end_layout
+
+\begin_layout LyX-Code
+db_initial.label = Dirichlet BC on -x
+\end_layout
+
+\begin_layout LyX-Code
+db_rate = spatialdata.spatialdb.UniformDB
+\end_layout
+
+\begin_layout LyX-Code
+db_rate.label = Dirichlet rate BC on -x
+\end_layout
+
+\begin_layout LyX-Code
+db_rate.values = [displacement-rate-x,displacement-rate-y,rate-start-time]
+\end_layout
+
+\begin_layout LyX-Code
+db_rate.data = [0.0*cm/year,-1.0*cm/year,0.0*year]
+\end_layout
+
+\begin_layout Standard
+For this example, we keep the same coefficient of friction as examples step10
+ and step11, but we include a cohesion of 2 MPa:
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.timedependent.interfaces.fault]
+\end_layout
+
+\begin_layout LyX-Code
+# Set static friction model parameters using a uniform DB.
+ Set the
+\end_layout
+
+\begin_layout LyX-Code
+# static coefficient of friction to 0.6 and cohesion to 2.0 MPa.
+\end_layout
+
+\begin_layout LyX-Code
+friction.db_properties = spatialdata.spatialdb.UniformDB
+\end_layout
+
+\begin_layout LyX-Code
+friction.db_properties.label = Static friction
+\end_layout
+
+\begin_layout LyX-Code
+friction.db_properties.values = [friction-coefficient,cohesion]
+\end_layout
+
+\begin_layout LyX-Code
+friction.db_properties.data = [0.6,2.0*MPa]
+\end_layout
+
+\begin_layout Standard
+When we have run the simulation, the output VTK files will be contained
+ in 
+\family typewriter
+examples/3d/hex8/output
+\family default
+ (all with a prefix of 
+\family typewriter
+step12
+\family default
+).
+ Results using ParaView are shown in Figure 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "fig:step12-displ-t200"
+
+\end_inset
+
+.
+\end_layout
+
+\begin_layout Standard
+\begin_inset Float figure
+wide false
+sideways false
+status open
+
+\begin_layout Plain Layout
+\align center
+\begin_inset Graphics
+	filename figs/step12-displ-t200.jpg
+	lyxscale 50
+	width 10cm
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Plain Layout
+\begin_inset Caption
+
+\begin_layout Plain Layout
+Displacement field for example step12 at t = 200 years visualized using
+ ParaView.
+ The mesh has been distorted by the computed displacements (magnified by
+ 500), and the vectors show the computed displacements.
+\begin_inset CommandInset label
+LatexCommand label
+name "fig:step12-displ-t200"
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Subsubsection
+Step13 - Slip-Weakening Friction with Quasi-Static Dirichlet Boundary Conditions
+\end_layout
+
+\begin_layout Standard
+In this example we replace the static friction fault constitutive model
+ in step12 with a slip-weakening friction fault constitutive model.
+ Fault friction is overcome at about t = 80 years, the fault slips in each
+ subsequent time step.
+ We again use a constant time step size of 5 years and apply the same intial
+ displacement and velocity boundary conditions.
+\end_layout
+
+\begin_layout Standard
+We first define the friction model for the simulation:
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.timedependent.interfaces.fault]
+\end_layout
+
+\begin_layout LyX-Code
+# Use the slip-weakening friction model.
+\end_layout
+
+\begin_layout LyX-Code
+friction = pylith.friction.SlipWeakening
+\end_layout
+
+\begin_layout Standard
+The slip-weakening constitutive model requires a static coefficient of friction,
+ a dynamic coefficient of friction, a slip weakening parameter, and a cohesion
+ (see Section 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "sec:fault:constitutive:models"
+
+\end_inset
+
+):
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.timedependent.interfaces.fault]
+\end_layout
+
+\begin_layout LyX-Code
+# Set slip-weakening friction model parameters using a uniform DB.
+ Set the
+\end_layout
+
+\begin_layout LyX-Code
+# parameters as follows:
+\end_layout
+
+\begin_layout LyX-Code
+# static coefficient of friction: 0.6
+\end_layout
+
+\begin_layout LyX-Code
+# dynamic coefficient of friction: 0.5
+\end_layout
+
+\begin_layout LyX-Code
+# slip-weakening parameter: 0.2 m
+\end_layout
+
+\begin_layout LyX-Code
+# cohesion: 0 Pa
+\end_layout
+
+\begin_layout LyX-Code
+friction.db_properties = spatialdata.spatialdb.UniformDB
+\end_layout
+
+\begin_layout LyX-Code
+friction.db_properties.label = Slip weakening
+\end_layout
+
+\begin_layout LyX-Code
+friction.db_properties.values = [static-coefficient,dynamic-coefficient,
+\begin_inset Newline newline
+\end_inset
+
+slip-weakening-parameter,cohesion]
+\end_layout
+
+\begin_layout LyX-Code
+friction.db_properties.data = [0.6,0.5,0.2*m,0.0*Pa]
+\end_layout
+
+\begin_layout Standard
+When we have run the simulation, the output VTK files will be contained
+ in 
+\family typewriter
+examples/3d/hex8/output
+\family default
+ (all with a prefix of 
+\family typewriter
+step1
+\family default
+3).
+ Results using ParaView are shown in Figure 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "fig:step13-displ-t200"
+
+\end_inset
+
+.
+\end_layout
+
+\begin_layout Standard
+\begin_inset Float figure
+wide false
+sideways false
+status open
+
+\begin_layout Plain Layout
+\align center
+\begin_inset Graphics
+	filename figs/step13-displ-t200.jpg
+	lyxscale 50
+	width 10cm
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Plain Layout
+\begin_inset Caption
+
+\begin_layout Plain Layout
+Displacement field for example step13 at t = 200 years visualized using
+ ParaView.
+ The mesh has been distorted by the computed displacements (magnified by
+ 500), and the vectors show the computed displacements.
+\begin_inset CommandInset label
+LatexCommand label
+name "fig:step13-displ-t200"
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Subsubsection
+Step14 - Rate-and-State Friction with Quasi-Static Dirichlet Boundary Conditions
+\end_layout
+
+\begin_layout Standard
+In step14 we use a rate-and-state friction model with an ageing law instead
+ of a slip-weakening friction model.
+ Slip begins to occur at about t = 45 years, and continues in each subsequent
+ time step.
+ We again use a constant time step size of 5 years and apply the same intial
+ displacement and velocity boundary conditions.
+\end_layout
+
+\begin_layout Standard
+We first define the friction model for the simulation:
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.timedependent.interfaces.fault]
+\end_layout
+
+\begin_layout LyX-Code
+# Use the rate-and-state aging friction model.
+\end_layout
+
+\begin_layout LyX-Code
+friction = pylith.friction.RateStateAgeing
+\end_layout
+
+\begin_layout Standard
+The rate-and-state constitutive model requires a reference coefficient of
+ friction, a reference slip rate, a slip weakening parameter, an a-value,
+ a b-value, and a cohesion (see 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "sec:fault:constitutive:models"
+
+\end_inset
+
+):
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.timedependent.interfaces.fault]
+\end_layout
+
+\begin_layout LyX-Code
+# Set rate-and-state parameters using a UniformDB.
+ Set the parameters as
+\end_layout
+
+\begin_layout LyX-Code
+# follows:
+\end_layout
+
+\begin_layout LyX-Code
+# reference coefficient of friction: 0.6
+\end_layout
+
+\begin_layout LyX-Code
+# reference slip rate: 1.0e-06 m/s
+\end_layout
+
+\begin_layout LyX-Code
+# slip-weakening parameter: 0.037 m
+\end_layout
+
+\begin_layout LyX-Code
+# a: 0.0125
+\end_layout
+
+\begin_layout LyX-Code
+# b: 0.0172
+\end_layout
+
+\begin_layout LyX-Code
+# cohesion: 0 Pa
+\end_layout
+
+\begin_layout LyX-Code
+friction.db_properties = spatialdata.spatialdb.UniformDB
+\end_layout
+
+\begin_layout LyX-Code
+friction.db_properties.label = Rate Stete Ageing
+\end_layout
+
+\begin_layout LyX-Code
+friction.db_properties.values = [reference-friction-coefficient,reference-slip-rat
+e,
+\begin_inset Newline newline
+\end_inset
+
+characteristic-slip-distance,constitutive-parameter-a,constitutive-parameter-b,c
+ohesion]
+\end_layout
+
+\begin_layout LyX-Code
+friction.db_properties.data = [0.6,1.0e-6*m/s,0.0370*m,0.0125,0.0172,0.0*Pa]
+\end_layout
+
+\begin_layout Standard
+For this model, we also want to set the initial value of the state variable:
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.timedependent.interfaces.fault]
+\end_layout
+
+\begin_layout LyX-Code
+# Set spatial database for the initial value of the state variable.
+\end_layout
+
+\begin_layout LyX-Code
+friction.db_initial_state = spatialdata.spatialdb.UniformDB
+\end_layout
+
+\begin_layout LyX-Code
+friction.db_initial_state.label = Rate State Ageing State
+\end_layout
+
+\begin_layout LyX-Code
+friction.db_initial_state.values = [state-variable]
+\end_layout
+
+\begin_layout LyX-Code
+friction.db_initial_state.data = [92.7*s]
+\end_layout
+
+\begin_layout Standard
+When we have run the simulation, the output VTK files will be contained
+ in 
+\family typewriter
+examples/3d/hex8/output
+\family default
+ (all with a prefix of 
+\family typewriter
+step1
+\family default
+4).
+ Results using ParaView are shown in Figure 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "fig:step14-displ-t200"
+
+\end_inset
+
+.
+\end_layout
+
+\begin_layout Standard
+\begin_inset Float figure
+wide false
+sideways false
+status open
+
+\begin_layout Plain Layout
+\align center
+\begin_inset Graphics
+	filename figs/step14-displ-t200.jpg
+	lyxscale 50
+	width 10cm
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Plain Layout
+\begin_inset Caption
+
+\begin_layout Plain Layout
+Displacement field for example step14 at t = 200 years visualized using
+ ParaView.
+ The mesh has been distorted by the computed displacements (magnified by
+ 500), and the vectors show the computed displacements.
+\begin_inset CommandInset label
+LatexCommand label
+name "fig:step14-displ-t200"
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\end_body
+\end_document

Modified: short/3D/PyLith/branches/v1.7-trunk/doc/userguide/tutorials/3dhex8/quasistatic/quasistatic.lyx
===================================================================
--- short/3D/PyLith/branches/v1.7-trunk/doc/userguide/tutorials/3dhex8/quasistatic/quasistatic.lyx	2012-06-25 04:52:47 UTC (rev 20403)
+++ short/3D/PyLith/branches/v1.7-trunk/doc/userguide/tutorials/3dhex8/quasistatic/quasistatic.lyx	2012-06-25 16:38:44 UTC (rev 20404)
@@ -1,2492 +1,2526 @@
-#LyX 2.0 created this file. For more info see http://www.lyx.org/
-\lyxformat 413
-\begin_document
-\begin_header
-\textclass book
-\begin_preamble
-
-\end_preamble
-\use_default_options false
-\maintain_unincluded_children false
-\language english
-\language_package default
-\inputencoding latin1
-\fontencoding global
-\font_roman default
-\font_sans default
-\font_typewriter default
-\font_default_family default
-\use_non_tex_fonts false
-\font_sc false
-\font_osf false
-\font_sf_scale 100
-\font_tt_scale 100
-
-\graphics default
-\default_output_format default
-\output_sync 0
-\bibtex_command default
-\index_command default
-\paperfontsize default
-\spacing single
-\use_hyperref false
-\papersize default
-\use_geometry true
-\use_amsmath 0
-\use_esint 0
-\use_mhchem 1
-\use_mathdots 1
-\cite_engine basic
-\use_bibtopic false
-\use_indices false
-\paperorientation portrait
-\suppress_date false
-\use_refstyle 0
-\index Index
-\shortcut idx
-\color #008000
-\end_index
-\leftmargin 1in
-\topmargin 1in
-\rightmargin 1in
-\bottommargin 2in
-\secnumdepth 3
-\tocdepth 3
-\paragraph_separation indent
-\paragraph_indentation default
-\quotes_language english
-\papercolumns 1
-\papersides 1
-\paperpagestyle default
-\tracking_changes false
-\output_changes false
-\html_math_output 0
-\html_css_as_file 0
-\html_be_strict false
-\end_header
-
-\begin_body
-
-\begin_layout Subsection
-\begin_inset CommandInset label
-LatexCommand label
-name "sec:Tutorial-3d-hex8-quasistatic"
-
-\end_inset
-
-Quasi-static Examples
-\end_layout
-
-\begin_layout Standard
-PyLith features discussed in this tutorial:
-\end_layout
-
-\begin_layout Itemize
-Quasi-static solution
-\end_layout
-
-\begin_layout Itemize
-Formatting timestamps of VTK output files
-\end_layout
-
-\begin_layout Itemize
-HDF5 output
-\end_layout
-
-\begin_layout Itemize
-Output of velocity field
-\end_layout
-
-\begin_layout Itemize
-Dirichlet displacement and velocity boundary conditions
-\end_layout
-
-\begin_layout Itemize
-Neumann traction boundary conditions and time-varying tractions
-\end_layout
-
-\begin_layout Itemize
-UniformDB spatial database
-\end_layout
-
-\begin_layout Itemize
-CompositeDB spatial database
-\end_layout
-
-\begin_layout Itemize
-Quasi-static fault rupture and fault creep
-\end_layout
-
-\begin_layout Itemize
-Multiple kinematic fault ruptures
-\end_layout
-
-\begin_layout Itemize
-Specifying more than one material
-\end_layout
-
-\begin_layout Itemize
-Nonlinear solver
-\end_layout
-
-\begin_layout Itemize
-Maxwell linear viscoelastic material
-\end_layout
-
-\begin_layout Itemize
-Power-law viscoelastic material
-\end_layout
-
-\begin_layout Itemize
-Drucker-Prager elastoplastic material
-\end_layout
-
-\begin_layout Itemize
-Adaptive time stepping
-\end_layout
-
-\begin_layout Subsubsection
-Overview
-\end_layout
-
-\begin_layout Standard
-This set of examples describes a set of quasi-static problems for PyLith.
- These quasi-static problems primarily demonstrate the usage of time-dependent
- boundary conditions and fault slip, as well as different rheologies.
- Some of the examples also demonstrate the usage of the nonlinear solver,
- which is required by the nonlinear rheologies (power-law viscoelastic and
- Drucker-Prager elastoplastic).
- Some of the examples also demonstrate the usage of HDF5 output, which is
- an alternative to the default VTK output.
- All of the examples are contained in the directory 
-\family typewriter
-examples/3d/hex8
-\family default
-, and the corresponding 
-\family typewriter
-.cfg
-\family default
- files are 
-\family typewriter
-step04.cfg
-\family default
-, 
-\family typewriter
-step05.cfg
-\family default
-, 
-\family typewriter
-step06.cfg
-\family default
-, 
-\family typewriter
-step07.cfg
-\family default
-, 
-\family typewriter
-step08.cfg
-\family default
-, and 
-\family typewriter
-step09.cfg
-\family default
-.
- Each example may be run as follows:
-\end_layout
-
-\begin_layout LyX-Code
-pylith stepXX.cfg
-\end_layout
-
-\begin_layout Standard
-This will cause PyLith to read the default parameters in 
-\family typewriter
-pylithapp.cfg
-\family default
-, and then override or augment them with the additional parameters in the
- 
-\family typewriter
-stepXX.cfg
-\family default
- file.
- Each 
-\family typewriter
-.cfg
-\family default
- file is extensively documented, to provide detailed information on the
- various parameters.
-\end_layout
-
-\begin_layout Subsubsection
-Step04 - Pure Dirichlet Velocity Boundary Conditions
-\end_layout
-
-\begin_layout Standard
-The 
-\family typewriter
-step04.cfg
-\family default
- file defines a problem with x-displacements fixed at zero on the positive
- and negative x-faces while velocity boundary conditions are applied in
- the y-directions on the same faces, yielding a left-lateral sense of movement.
- The bottom (negative z) boundary is held fixed in the z-direction.
- We also use a Maxwell viscoelastic material for the lower crust, and the
- simulation is run for 200 years using a constant time step size of 20 years.
- The default time stepping behavior is 
-\family typewriter
-TimeStepUniform
-\family default
-.
- We retain that behavior for this problem and provide the total simulation
- time and the time step size:
-\end_layout
-
-\begin_layout LyX-Code
-# Change the total simulation time to 200 years, and use a constant time
-\end_layout
-
-\begin_layout LyX-Code
-# step size of 20 years.
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.timedependent.implicit.time_step]
-\end_layout
-
-\begin_layout LyX-Code
-total_time = 200.0*year
-\end_layout
-
-\begin_layout LyX-Code
-dt = 20.0*year 
-\end_layout
-
-\begin_layout Standard
-We then change the material type of the lower crust, provide a spatial database
- from which to obtain the material properties (using the default 
-\family typewriter
-SimpleDB
-\family default
-), and request additional output information for the material:
-\end_layout
-
-\begin_layout LyX-Code
-# Change material type of lower crust to Maxwell viscoelastic.
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.timedependent]
-\end_layout
-
-\begin_layout LyX-Code
-materials.lower_crust = pylith.materials.MaxwellIsotropic3D
-\begin_inset Newline newline
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\end_layout
-
-\begin_layout LyX-Code
-# Provide a spatial database from which to obtain property values.
-\end_layout
-
-\begin_layout LyX-Code
-# Since there are additional properties and state variables for the Maxwell
-\end_layout
-
-\begin_layout LyX-Code
-# model, we explicitly request that they be output.
- Properties are named in
-\end_layout
-
-\begin_layout LyX-Code
-# cell_info_fields and state variables are named in cell_data_fields.
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.timedependent.materials.lower_crust]
-\end_layout
-
-\begin_layout LyX-Code
-db_properties.iohandler.filename = spatialdb/mat_maxwell.spatialdb
-\end_layout
-
-\begin_layout LyX-Code
-output.cell_info_fields = [density,mu,lambda,maxwell_time]
-\end_layout
-
-\begin_layout LyX-Code
-output.cell_data_fields = [total_strain,stress,viscous_strain]
-\end_layout
-
-\begin_layout Standard
-Note that the default 
-\family typewriter
-output.cell_info_fields
-\family default
- are those corresponding to an elastic material (
-\family typewriter
-density
-\family default
-, 
-\family typewriter
-mu
-\family default
-, 
-\family typewriter
-lambda
-\family default
-), and the default 
-\family typewriter
-output.cell_data_fields
-\family default
- are 
-\family typewriter
-total_strain
-\family default
- and 
-\family typewriter
-stress
-\family default
-.
- For materials other than elastic, there are generally additional material
- properties and state variables, and the appropriate additional fields must
- be specifically requested for each material type.
-\end_layout
-
-\begin_layout Standard
-This example has no displacements in the elastic solution (t = 0), so we
- retain the default 
-\family typewriter
-ZeroDispDB
-\family default
- for all instances of 
-\family typewriter
-db_initial
-\family default
-.
- To apply the velocity boundary conditions, we must specify 
-\family typewriter
-db_rate
-\family default
-, which is zero by default.
- We use a 
-\family typewriter
-UniformDB
-\family default
- to assign the velocities:
-\end_layout
-
-\begin_layout LyX-Code
-# +x face
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.timedependent.bc.x_pos]
-\end_layout
-
-\begin_layout LyX-Code
-bc_dof = [0, 1]
-\end_layout
-
-\begin_layout LyX-Code
-label = face_xpos
-\end_layout
-
-\begin_layout LyX-Code
-db_initial.label = Dirichlet BC on +x
-\end_layout
-
-\begin_layout LyX-Code
-db_rate = spatialdata.spatialdb.UniformDB
-\end_layout
-
-\begin_layout LyX-Code
-db_rate.label = Dirichlet rate BC on +x
-\end_layout
-
-\begin_layout LyX-Code
-db_rate.values = [displacement-rate-x,displacement-rate-y,rate-start-time]
-\end_layout
-
-\begin_layout LyX-Code
-db_rate.data = [0.0*cm/year,1.0*cm/year,0.0*year]
-\begin_inset Newline newline
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\end_layout
-
-\begin_layout LyX-Code
-# -x face
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.timedependent.bc.x_neg]
-\end_layout
-
-\begin_layout LyX-Code
-bc_dof = [0, 1]
-\end_layout
-
-\begin_layout LyX-Code
-label = face_xneg
-\end_layout
-
-\begin_layout LyX-Code
-db_initial.label = Dirichlet BC on -x
-\end_layout
-
-\begin_layout LyX-Code
-db_rate = spatialdata.spatialdb.UniformDB
-\end_layout
-
-\begin_layout LyX-Code
-db_rate.label = Dirichlet rate BC on +x
-\end_layout
-
-\begin_layout LyX-Code
-db_rate.values = [displacement-rate-x,displacement-rate-y,rate-start-time]
-\end_layout
-
-\begin_layout LyX-Code
-db_rate.data = [0.0*cm/year,-1.0*cm/year,0.0*year]
-\end_layout
-
-\begin_layout Standard
-Note that 
-\family typewriter
-db_rate
-\family default
- requires a start time, which allows the condition to be applied at any
- time during the simulation.
- For this example, we start the velocity boundary conditions at t = 0.
-\end_layout
-
-\begin_layout Standard
-Finally, we must provide information on VTK output.
- This is slightly more complicated than the static case, because we must
- decide the frequency with which output occurs for each output manager.
- We also assign a more user-friendly format to the output file time stamp,
- and we request that the time stamp is in units of 1 year (rather than the
- default value of seconds):
-\end_layout
-
-\begin_layout LyX-Code
-# Give basename for VTK domain output of solution over domain.
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.problem.formulation.output.domain]
-\end_layout
-
-\begin_layout LyX-Code
-# We specify that output occurs in terms of a given time frequency, and
-\end_layout
-
-\begin_layout LyX-Code
-# ask for output every 40 years.
- The time stamps of the output files are
-\end_layout
-
-\begin_layout LyX-Code
-# in years (rather than the default of seconds), and we give a format for
-\end_layout
-
-\begin_layout LyX-Code
-# the time stamp.
-\end_layout
-
-\begin_layout LyX-Code
-output_freq = time_step
-\end_layout
-
-\begin_layout LyX-Code
-time_step = 40.0*year
-\end_layout
-
-\begin_layout LyX-Code
-writer.filename = output/step04.vtk
-\end_layout
-
-\begin_layout LyX-Code
-writer.time_format = %04.0f
-\end_layout
-
-\begin_layout LyX-Code
-writer.time_constant = 1.0*year
-\begin_inset Newline newline
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\end_layout
-
-\begin_layout LyX-Code
-# Give basename for VTK domain output of solution over ground surface.
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.problem.formulation.output.subdomain]
-\end_layout
-
-\begin_layout LyX-Code
-# Name of nodeset for ground surface.
-\end_layout
-
-\begin_layout LyX-Code
-label = face_zpos
-\end_layout
-
-\begin_layout LyX-Code
-# We keep the default output frequency behavior (skip every n steps), and
-\end_layout
-
-\begin_layout LyX-Code
-# ask to skip 0 steps between output, so that we get output every time step.
-\end_layout
-
-\begin_layout LyX-Code
-skip = 0
-\end_layout
-
-\begin_layout LyX-Code
-writer.filename = output/step04-groundsurf.vtk
-\end_layout
-
-\begin_layout LyX-Code
-writer.time_format = %04.0f
-\end_layout
-
-\begin_layout LyX-Code
-writer.time_constant = 1.0*year
-\end_layout
-
-\begin_layout Standard
-We provide similar output information for the two materials (
-\family typewriter
-upper_crust
-\family default
- and 
-\family typewriter
-lower_crust
-\family default
-).
- Note that for the domain output, we requested output in terms of a given
- time frequency, while for the subdomain we requested output in terms of
- number of time steps.
- When we have run the simulation, the output VTK files will be contained
- in 
-\family typewriter
-examples/3d/hex8/output
-\family default
- (all with a prefix of 
-\family typewriter
-step04
-\family default
-).
- Results using ParaView are shown in Figure 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "fig:step04-displ-t200"
-
-\end_inset
-
-.
-\end_layout
-
-\begin_layout Standard
-\begin_inset Float figure
-wide false
-sideways false
-status open
-
-\begin_layout Plain Layout
-\align center
-\begin_inset Graphics
-	filename figs/step04-displ-t200.jpg
-	lyxscale 50
-	width 10cm
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Plain Layout
-\begin_inset Caption
-
-\begin_layout Plain Layout
-Displacement field for example step04 at t = 200 years visualized using
- ParaView.
- The mesh has been distorted by the computed displacements (magnified by
- 500), and the vectors show the computed displacements.
-\begin_inset CommandInset label
-LatexCommand label
-name "fig:step04-displ-t200"
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Subsubsection
-Step05 - Time-varying Dirichlet and Neumann Boundary Conditions
-\end_layout
-
-\begin_layout Standard
-The 
-\family typewriter
-step05.cfg
-\family default
- file describes a problem with time-varying Dirichlet and Neumann boundary
- conditions.
- The example is similar to example step04, with a few important differences:
-\end_layout
-
-\begin_layout Itemize
-The Dirichlet boundary conditions on the negative x-face include an initial
- displacement (applied in the elastic solution), as well as a constant velocity.
-\end_layout
-
-\begin_layout Itemize
-Neumann (traction) boundary conditions are applied in the negative x-direction
- on the positive x-face, giving a compressive stress.
- An initial traction is applied in the elastic solution, and then at t =
- 100 years it begins decreasing linearly until it reaches zero at the end
- of the simulation (t = 200 years).
-\end_layout
-
-\begin_layout Standard
-We again use a Maxwell viscoelastic material for the lower crust.
-\end_layout
-
-\begin_layout Standard
-For the boundary conditions, we must first change the boundary condition
- type for the positive x-face from the default Dirichlet to Neumann:
-\end_layout
-
-\begin_layout LyX-Code
-# +x face -- first change bc type to Neumann
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.timedependent.bc]
-\end_layout
-
-\begin_layout LyX-Code
-x_pos = pylith.bc.Neumann 
-\end_layout
-
-\begin_layout Standard
-We provide quadrature information for this face as we did for example step02.
- We then use a 
-\family typewriter
-UniformDB
-\family default
- for both the initial tractions as well as the traction rates.
- We provide a start time of 100 years for the traction rates, and use a
- rate of 0.01 MPa/year, so that by the end of 200 years we have completely
- cancelled the initial traction of -1 MPa:
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.timedependent.bc.x_pos]
-\end_layout
-
-\begin_layout LyX-Code
-# Fist specify a UniformDB for the initial tractions, along with the values.
-\end_layout
-
-\begin_layout LyX-Code
-db_initial = spatialdata.spatialdb.UniformDB
-\end_layout
-
-\begin_layout LyX-Code
-db_initial.label = Neumann BC on +x
-\end_layout
-
-\begin_layout LyX-Code
-db_initial.values = [traction-shear-horiz,traction-shear-vert,traction-normal]
-\end_layout
-
-\begin_layout LyX-Code
-db_initial.data = [0.0*MPa,0.0*MPa,-1.0*MPa]
-\begin_inset Newline newline
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\end_layout
-
-\begin_layout LyX-Code
-# Provide information on traction rates.
-\end_layout
-
-\begin_layout LyX-Code
-db_rate = spatialdata.spatialdb.UniformDB
-\end_layout
-
-\begin_layout LyX-Code
-db_rate.label = Neumann rate BC on +x
-\end_layout
-
-\begin_layout LyX-Code
-db_rate.values = [traction-rate-shear-horiz,traction-rate-shear-vert,traction-rat
-e-normal,
-\begin_inset Newline newline
-\end_inset
-
-rate-start-time]
-\end_layout
-
-\begin_layout LyX-Code
-db_rate.data = [0.0*MPa/year,0.0*MPa/year,0.01*MPa/year,100.0*year]
-\end_layout
-
-\begin_layout Standard
-The boundary conditions on the negative x-face are analogous, but we are
- instead using Dirichlet boundary conditions, and the initial displacement
- is in the same direction as the applied velocities:
-\end_layout
-
-\begin_layout LyX-Code
-# -x face
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.timedependent.bc.x_neg]
-\end_layout
-
-\begin_layout LyX-Code
-bc_dof = [0, 1]
-\end_layout
-
-\begin_layout LyX-Code
-label = face_xneg
-\begin_inset Newline newline
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\end_layout
-
-\begin_layout LyX-Code
-# Initial displacements.
-\end_layout
-
-\begin_layout LyX-Code
-db_initial = spatialdata.spatialdb.UniformDB
-\end_layout
-
-\begin_layout LyX-Code
-db_initial.label = Dirichlet BC on -x
-\end_layout
-
-\begin_layout LyX-Code
-db_initial.values = [displacement-x,displacement-y]
-\end_layout
-
-\begin_layout LyX-Code
-db_initial.data = [0.0*cm,-0.5*cm]
-\begin_inset Newline newline
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\end_layout
-
-\begin_layout LyX-Code
-# Velocities.
-\end_layout
-
-\begin_layout LyX-Code
-db_rate = spatialdata.spatialdb.UniformDB
-\end_layout
-
-\begin_layout LyX-Code
-db_rate.label = Dirichlet rate BC on -x
-\end_layout
-
-\begin_layout LyX-Code
-db_rate.values = [displacement-rate-x,displacement-rate-y,rate-start-time]
-\end_layout
-
-\begin_layout LyX-Code
-db_rate.data = [0.0*cm/year,-1.0*cm/year,0.0*year]
-\end_layout
-
-\begin_layout Standard
-The boundary conditions on the negative z-face are supplied in the same
- manner as for example step04.
- When we have run the simulation, the output VTK files will be contained
- in 
-\family typewriter
-examples/3d/hex8/output
-\family default
- (all with a prefix of 
-\family typewriter
-step05
-\family default
-).
- Results using ParaView are shown in Figure 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "fig:step05-displ-t40"
-
-\end_inset
-
-.
-\begin_inset Float figure
-wide false
-sideways false
-status open
-
-\begin_layout Plain Layout
-\align center
-\begin_inset Graphics
-	filename figs/step05-displ-t40.jpg
-	lyxscale 50
-	width 10cm
-
-\end_inset
-
-
-\begin_inset Caption
-
-\begin_layout Plain Layout
-Displacement field for example step05 at t = 40 years visualized using ParaView.
- The mesh has been distorted by the computed displacements (magnified by
- 500), and the vectors show the computed displacements.
-\begin_inset CommandInset label
-LatexCommand label
-name "fig:step05-displ-t40"
-
-\end_inset
-
-.
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Subsubsection
-Step06 - Dirichlet Boundary Conditions with Time-Dependent Kinematic Fault
- Slip
-\end_layout
-
-\begin_layout Standard
-The 
-\family typewriter
-step06.cfg
-\family default
- file defines a problem with Dirichlet (displacement) boundary conditions
- corresponding to zero x and y-displacements applied on the negative and
- positive x-faces and a vertical fault that includes multiple earthquake
- ruptures as well as steady fault creep.
- The upper (locked) portion of the fault has 4 m of left-lateral slip every
- 200 years, while the lower (creeping) portion of the fault slips at a steady
- rate of 2 cm/year.
- The problem bears some similarity to the strike-slip fault model of Savage
- and Prescott 
-\begin_inset CommandInset citation
-LatexCommand cite
-key "Savage:Prescott:1978"
-
-\end_inset
-
-, except that the fault creep extends through the viscoelastic portion of
- the domain, and the far-field displacement boundary conditions are held
- fixed.
-\end_layout
-
-\begin_layout Standard
-In this example and the remainder of the examples in this section, we change
- the time stepping behavior from the default 
-\family typewriter
-TimeStepUniform
-\family default
- to 
-\family typewriter
-TimeStepAdapt
-\family default
-.
- For adaptive time stepping, we provide the maximum permissible time step
- size, along with a stability factor.
- The stability factor controls the time step size relative to the stable
- time step size provided by the different materials in the model.
- A 
-\family typewriter
-stability_factor
-\family default
- of 1.0 means we should use the stable time step size, while a 
-\family typewriter
-stability_factor
-\family default
- greater than 1.0 means we want to use a smaller time step size.
- A 
-\family typewriter
-stability_factor
-\family default
- less than 1.0 allows time step sizes greater than the stable time step size,
- which may provide inaccurate results.
- The adaptive time stepping information is provided as:
-\end_layout
-
-\begin_layout LyX-Code
-# Change time stepping algorithm from uniform time step, to adaptive
-\end_layout
-
-\begin_layout LyX-Code
-# time stepping.
-\end_layout
-
-\begin_layout LyX-Code
-time_step = pylith.problems.TimeStepAdapt
-\begin_inset Newline newline
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\end_layout
-
-\begin_layout LyX-Code
-# Change the total simulation time to 700 years, and set the maximum time
-\end_layout
-
-\begin_layout LyX-Code
-# step size to 10 years.
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.timedependent.implicit.time_step]
-\end_layout
-
-\begin_layout LyX-Code
-total_time = 700.0*year
-\end_layout
-
-\begin_layout LyX-Code
-max_dt = 10.0*year
-\end_layout
-
-\begin_layout LyX-Code
-stability_factor = 1.0 ; use time step equal to stable value from materials
-\end_layout
-
-\begin_layout Standard
-In this example and the remainder of the examples in this section, we also
- make use of HDF5 output rather than the default VTK output.
- HDF5 output is a new feature beginning with PyLith version 1.6, and it is
- much more efficient with the additional advantage that multiple time steps
- can be contained in a single file.
- PyLith also produces Xdmf files describing the contents of the HDF5 files,
- which allows the files to be read easily by applications such as ParaView.
- Since VTK output is still the default, we must change the value from the
- default.
- Also note that the filename suffix is 
-\family typewriter
-.h5
-\family default
-:
-\end_layout
-
-\begin_layout LyX-Code
-# Give basename for output of solution over domain.
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.problem.formulation.output.domain]
-\end_layout
-
-\begin_layout LyX-Code
-# We specify that output occurs in terms of a given time frequency, and
-\end_layout
-
-\begin_layout LyX-Code
-# ask for output every 50 years.
-\end_layout
-
-\begin_layout LyX-Code
-output_freq = time_step
-\end_layout
-
-\begin_layout LyX-Code
-time_step = 50.0*year
-\begin_inset Newline newline
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\end_layout
-
-\begin_layout LyX-Code
-# We are using HDF5 output so we must change the default writer.
-\end_layout
-
-\begin_layout LyX-Code
-writer = pylith.meshio.DataWriterHDF5Mesh
-\end_layout
-
-\begin_layout LyX-Code
-writer.filename = output/step06.h5  
-\end_layout
-
-\begin_layout Standard
-Note that we no longer need the 
-\family typewriter
-writer.time_format
-\family default
- or 
-\family typewriter
-writer.time_constant
-\family default
- properties, since all time steps are contained in a single file.
- The HDF5 writer does not have these properties, so if we attempt to define
- them an error will result.
-\end_layout
-
-\begin_layout Standard
-We also set the writer for other output as well, since it is not the default.
- For subdomain output we use:
-\end_layout
-
-\begin_layout LyX-Code
-# Give basename for output of solution over ground surface.
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.problem.formulation.output.subdomain]
-\end_layout
-
-\begin_layout LyX-Code
-# Name of nodeset for ground surface.
-\end_layout
-
-\begin_layout LyX-Code
-label = face_zpos
-\begin_inset Newline newline
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\end_layout
-
-\begin_layout LyX-Code
-# We keep the default output frequency behavior (skip every n steps), and
-\end_layout
-
-\begin_layout LyX-Code
-# ask to skip 0 steps between output, so that we get output every time step.
-\end_layout
-
-\begin_layout LyX-Code
-# We again switch the writer to produce HDF5 output.
-\end_layout
-
-\begin_layout LyX-Code
-# Note that we specifically ask for a submesh writer.
-\end_layout
-
-\begin_layout LyX-Code
-skip = 0
-\end_layout
-
-\begin_layout LyX-Code
-writer = pylith.meshio.DataWriterHDF5SubMesh
-\end_layout
-
-\begin_layout LyX-Code
-writer.filename = output/step06-groundsurf.h5  
-\end_layout
-
-\begin_layout Standard
-For fault output we use:
-\end_layout
-
-\begin_layout LyX-Code
-# Give basename for fault rupture output.
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.problem.interfaces.fault.output]
-\end_layout
-
-\begin_layout LyX-Code
-# We keep the default output frequency behavior (skip every n steps), and
-\end_layout
-
-\begin_layout LyX-Code
-# ask to skip 0 steps between output, so that we get output every time step.
-\end_layout
-
-\begin_layout LyX-Code
-# We again switch the writer to produce HDF5 output.
-\end_layout
-
-\begin_layout LyX-Code
-# Note that we specifically ask for a subsubmesh writer.
-\end_layout
-
-\begin_layout LyX-Code
-skip = 0
-\end_layout
-
-\begin_layout LyX-Code
-writer = pylith.meshio.DataWriterHDF5SubSubMesh
-\end_layout
-
-\begin_layout LyX-Code
-writer.filename = output/step06-fault.h5
-\end_layout
-
-\begin_layout Standard
-Note the usage of 
-\family typewriter
-pylith.meshio.DataWriterHDF5SubMesh
-\family default
- for subdomain output and
-\family typewriter
-
-\begin_inset Newline newline
-\end_inset
-
-pylith.meshio.DataWriterHDF5SubSubMesh
-\family default
- for fault output.
-\end_layout
-
-\begin_layout Standard
-Due to the simplicity of the boundary conditions, we are able to use the
- default 
-\family typewriter
-ZeroDispBC
-\family default
- for the positive and negative x-faces, as well as the negative z-face.
- As for example step03, we define a fault interface, we identify the nodeset
- corresponding to the fault, and we provide quadrature information for the
- fault.
- We then define an array of earthquake sources and provide an origin time
- for each:
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.timedependent.interfaces.fault]
-\end_layout
-
-\begin_layout LyX-Code
-# Set earthquake sources to an array consisting of creep and 3 ruptures.
-\end_layout
-
-\begin_layout LyX-Code
-eq_srcs = [creep,one,two,three]
-\end_layout
-
-\begin_layout LyX-Code
-eq_srcs.creep.origin_time = 00.0*year
-\end_layout
-
-\begin_layout LyX-Code
-eq_srcs.one.origin_time = 200.0*year
-\end_layout
-
-\begin_layout LyX-Code
-eq_srcs.two.origin_time = 400.0*year
-\end_layout
-
-\begin_layout LyX-Code
-eq_srcs.three.origin_time = 600.0*year
-\end_layout
-
-\begin_layout Standard
-Note that the creep begins at t = 0 years, while the ruptures (
-\family typewriter
-one
-\family default
-, 
-\family typewriter
-two
-\family default
-, 
-\family typewriter
-three
-\family default
-) occur at regular intervals of 200 years.
- We retain the default 
-\family typewriter
-StepSlipFn
-\family default
- for the ruptures.
- Each of the ruptures has the same amount of slip, and slip occurs simultaneousl
-y for the entire rupture region, so we can use the same 
-\family typewriter
-SimpleDB
-\family default
- files providing slip and slip time for each rupture:
-\end_layout
-
-\begin_layout LyX-Code
-# Define slip and origin time for first rupture.
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.timedependent.interfaces.fault.eq_srcs.one.slip_function]
-\end_layout
-
-\begin_layout LyX-Code
-slip.iohandler.filename = spatialdb/finalslip_rupture.spatialdb
-\end_layout
-
-\begin_layout LyX-Code
-slip_time.iohandler.filename = spatialdb/sliptime.spatialdb
-\begin_inset Newline newline
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\end_layout
-
-\begin_layout LyX-Code
-# Define slip and origin time for second rupture.
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.timedependent.interfaces.fault.eq_srcs.two.slip_function]
-\end_layout
-
-\begin_layout LyX-Code
-slip.iohandler.filename = spatialdb/finalslip_rupture.spatialdb
-\end_layout
-
-\begin_layout LyX-Code
-slip_time.iohandler.filename = spatialdb/sliptime.spatialdb
-\begin_inset Newline newline
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\end_layout
-
-\begin_layout LyX-Code
-# Define slip and origin time for third rupture.
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.timedependent.interfaces.fault.eq_srcs.three.slip_function]
-\end_layout
-
-\begin_layout LyX-Code
-slip.iohandler.filename = spatialdb/finalslip_rupture.spatialdb
-\end_layout
-
-\begin_layout LyX-Code
-slip_time.iohandler.filename = spatialdb/sliptime.spatialdb
-\end_layout
-
-\begin_layout Standard
-For the creep source, we change the slip function to 
-\family typewriter
-ConstRateSlipFn
-\family default
-, and we use a 
-\family typewriter
-SimpleDB
-\family default
- for both the slip time and the slip rate:
-\end_layout
-
-\begin_layout LyX-Code
-# Define slip rate and origin time for fault creep.
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.timedependent.interfaces.fault.eq_srcs.creep]
-\end_layout
-
-\begin_layout LyX-Code
-slip_function = pylith.faults.ConstRateSlipFn
-\end_layout
-
-\begin_layout LyX-Code
-slip_function.slip_rate.iohandler.filename = spatialdb/sliprate_creep.spatialdb
-\end_layout
-
-\begin_layout LyX-Code
-slip_function.slip_time.iohandler.filename = spatialdb/sliptime.spatialdb
-\end_layout
-
-\begin_layout Standard
-For all earthquake sources we provide both an 
-\family typewriter
-origin_time
-\family default
- and a 
-\family typewriter
-slip_function.slip_time
-\family default
-.
- The first provides the starting time for the entire earthquake source,
- while the second provides any spatial variation in the slip time with respect
- to the 
-\family typewriter
-origin_time
-\family default
- (if any).
- Since there are multiple earthquake sources of different types, there are
- a number of additional fault information fields available for output.
- We add these additional fields be output to the fault information file:
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.timedependent.interfaces.fault]
-\end_layout
-
-\begin_layout LyX-Code
-output.vertex_info_fields = [normal_dir,strike_dir,dip_dir,final_slip_creep,
-\begin_inset Newline newline
-\end_inset
-
-final_slip_one,final_slip_two,final_slip_three,slip_time_creep,slip_time_one,
-\begin_inset Newline newline
-\end_inset
-
-slip_time_two,slip_time_three]
-\end_layout
-
-\begin_layout Standard
-This additional information will be contained in file 
-\family typewriter
-step06-fault_info.
-\family default
-h5.
- It will contain final slip information for each earthquake source along
- with slip time information.
- When we have run the simulation, the output HDF5 and Xdmf files will be
- contained in 
-\family typewriter
-examples/3d/hex8/output
-\family default
- (all with a prefix of 
-\family typewriter
-step06
-\family default
-).
- To open the files in ParaView, the Xdmf (
-\family typewriter
-.xmf
-\family default
-) files should be opened, as these files describe the HDF5 data structure.
- Results using ParaView are shown in Figure 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "fig:step06-displ-t300"
-
-\end_inset
-
-.
-\begin_inset Float figure
-wide false
-sideways false
-status open
-
-\begin_layout Plain Layout
-\align center
-\begin_inset Graphics
-	filename figs/step06-displ-t300.jpg
-	lyxscale 50
-	width 10cm
-
-\end_inset
-
-
-\begin_inset Caption
-
-\begin_layout Plain Layout
-Displacement field for example step06 at t = 300 years visualized using
- ParaView.
- The mesh has been distorted by the computed displacements (magnified by
- 500), and the vectors show the computed displacements.
-\begin_inset CommandInset label
-LatexCommand label
-name "fig:step06-displ-t300"
-
-\end_inset
-
-.
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Subsubsection
-Step07 - Dirichlet Velocity Boundary Conditions with Time-Dependent Kinematic
- Fault Slip
-\end_layout
-
-\begin_layout Standard
-In step07 we add velocity boundary conditions in the positive and negative
- y-directions on the positive and negative x-faces, so that the external
- boundaries keep pace with the average fault slip.
- This problem is nearly identical to the strike-slip fault model of Savage
- and Prescott 
-\begin_inset CommandInset citation
-LatexCommand cite
-key "Savage:Prescott:1978"
-
-\end_inset
-
-, except that the fault creep extends through the viscoelastic portion of
- the domain.
-\end_layout
-
-\begin_layout Standard
-We use the default 
-\family typewriter
-ZeroDispBC
-\family default
- for the initial displacements on the positive and negative x-faces, as
- well as the negative z-face.
- For the velocities on the positive and negative x-faces, we use a 
-\family typewriter
-UniformDB
-\family default
-:
-\end_layout
-
-\begin_layout LyX-Code
-# +x face
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.timedependent.bc.x_pos]
-\end_layout
-
-\begin_layout LyX-Code
-bc_dof = [0, 1]
-\end_layout
-
-\begin_layout LyX-Code
-label = face_xpos
-\end_layout
-
-\begin_layout LyX-Code
-db_initial.label = Dirichlet BC on +x
-\end_layout
-
-\begin_layout LyX-Code
-db_rate = spatialdata.spatialdb.UniformDB
-\end_layout
-
-\begin_layout LyX-Code
-db_rate.label = Dirichlet rate BC on +x
-\end_layout
-
-\begin_layout LyX-Code
-db_rate.values = [displacement-rate-x,displacement-rate-y,rate-start-time]
-\end_layout
-
-\begin_layout LyX-Code
-db_rate.data = [0.0*cm/year,1.0*cm/year,0.0*year]
-\begin_inset Newline newline
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\end_layout
-
-\begin_layout LyX-Code
-# -x face
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.timedependent.bc.x_neg]
-\end_layout
-
-\begin_layout LyX-Code
-bc_dof = [0, 1]
-\end_layout
-
-\begin_layout LyX-Code
-label = face_xneg
-\end_layout
-
-\begin_layout LyX-Code
-db_initial.label = Dirichlet BC on -x
-\end_layout
-
-\begin_layout LyX-Code
-db_rate = spatialdata.spatialdb.UniformDB
-\end_layout
-
-\begin_layout LyX-Code
-db_rate.label = Dirichlet rate BC on +x
-\end_layout
-
-\begin_layout LyX-Code
-db_rate.values = [displacement-rate-x,displacement-rate-y,rate-start-time]
-\end_layout
-
-\begin_layout LyX-Code
-db_rate.data = [0.0*cm/year,-1.0*cm/year,0.0*year]
-\end_layout
-
-\begin_layout Standard
-The fault definition information is identical to example step06.
- In previous examples, we have just used the default output for the domain
- and subdomain (ground surface), which includes the displacements.
- In many cases, it is also useful to include the velocities.
- PyLith provides this information, computing the velocities for the current
- time step as the difference between the current displacements and the displacem
-ents from the previous time step, divided by the time step size.
- This is more accurate than computing the velocities from the displacement
- field output that has been decimated in time.
- We can obtain this information by explicitly requesting it in 
-\family typewriter
-vertex_data_fields
-\family default
-:
-\end_layout
-
-\begin_layout LyX-Code
-# Give basename for output of solution over domain.
-\begin_inset Newline newline
-\end_inset
-
-[pylithapp.problem.formulation.output.domain]
-\end_layout
-
-\begin_layout LyX-Code
-# We specify that output occurs in terms of a given time frequency, and
-\end_layout
-
-\begin_layout LyX-Code
-# ask for output every 50 years.
-\end_layout
-
-\begin_layout LyX-Code
-# We also request velocity output in addition to displacements.
-\begin_inset Newline newline
-\end_inset
-
-vertex_data_fields = [displacement,velocity]
-\end_layout
-
-\begin_layout LyX-Code
-output_freq = time_step
-\end_layout
-
-\begin_layout LyX-Code
-time_step = 50.0*year
-\begin_inset Newline newline
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\end_layout
-
-\begin_layout LyX-Code
-# We are using HDF5 output so we must change the default writer.
-\end_layout
-
-\begin_layout LyX-Code
-writer = pylith.meshio.DataWriterHDF5Mesh
-\end_layout
-
-\begin_layout LyX-Code
-writer.filename = output/step07.h5
-\begin_inset Newline newline
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\end_layout
-
-\begin_layout LyX-Code
-# Give basename for output of solution over ground surface.
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.problem.formulation.output.subdomain]
-\end_layout
-
-\begin_layout LyX-Code
-# Name of nodeset for ground surface.
-\end_layout
-
-\begin_layout LyX-Code
-label = face_zpos
-\begin_inset Newline newline
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\end_layout
-
-\begin_layout LyX-Code
-# We also request velocity output in addition to displacements.
-\end_layout
-
-\begin_layout LyX-Code
-vertex_data_fields = [displacement,velocity]
-\end_layout
-
-\begin_layout LyX-Code
-# We keep the default output frequency behavior (skip every n steps), and
-\end_layout
-
-\begin_layout LyX-Code
-# ask to skip 0 steps between output, so that we get output every time step.
-\end_layout
-
-\begin_layout LyX-Code
-skip = 0
-\begin_inset Newline newline
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\end_layout
-
-\begin_layout LyX-Code
-# We again switch the writer to produce HDF5 output.
-\end_layout
-
-\begin_layout LyX-Code
-# Note that we specifically ask for a submesh writer.
-\end_layout
-
-\begin_layout LyX-Code
-writer = pylith.meshio.DataWriterHDF5SubMesh
-\end_layout
-
-\begin_layout LyX-Code
-writer.filename = output/step07-groundsurf.h5
-\end_layout
-
-\begin_layout Standard
-When we have run the simulation, the output HDF5 and Xdmf files will be
- contained in 
-\family typewriter
-examples/3d/hex8/output
-\family default
- (all with a prefix of 
-\family typewriter
-step07
-\family default
-).
- As for example 
-\family typewriter
-step06
-\family default
-, make sure to open the 
-\family typewriter
-.xmf
-\family default
- files rather than the 
-\family typewriter
-.h5
-\family default
- files.
- Results using ParaView are shown in Figure 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "fig:step07-displ-vel-t300"
-
-\end_inset
-
-.
-\begin_inset Float figure
-wide false
-sideways false
-status open
-
-\begin_layout Plain Layout
-\align center
-\begin_inset Graphics
-	filename figs/step07-displ-vel-t300.jpg
-	lyxscale 50
-	width 10cm
-
-\end_inset
-
-
-\begin_inset Caption
-
-\begin_layout Plain Layout
-Displacement field (color contours) and velocity field (vectors) for example
- step07 at t = 300 years visualized using ParaView.
- The mesh has been distorted by the computed displacements (magnified by
- 500), and the vectors show the computed velocities.
-\begin_inset CommandInset label
-LatexCommand label
-name "fig:step07-displ-vel-t300"
-
-\end_inset
-
-.
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Subsubsection
-Step08 - Dirichlet Velocity Boundary Conditions with Time-Dependent Kinematic
- Fault Slip and Power-Law Rheology
-\begin_inset CommandInset label
-LatexCommand label
-name "sub:Tutorial-Step08-Power-law"
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-The 
-\family typewriter
-step08.cfg
-\family default
- file defines a problem that is identical to example step07, except the
- the lower crust is composed of a power-law viscoelastic material.
- Since the material behavior is now nonlinear, we must use the nonlinear
- solver:
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.timedependent]
-\end_layout
-
-\begin_layout LyX-Code
-# For this problem we must switch to a nonlinear solver.
-\end_layout
-
-\begin_layout LyX-Code
-implicit.solver = pylith.problems.SolverNonlinear
-\end_layout
-
-\begin_layout Standard
-Although we have not discussed the PyLith PETSc settings previously, note
- that the use of the nonlinear solver may require additional options if
- we wish to override the defaults.
- These settings are contained in 
-\family typewriter
-pylithapp.cfg
-\family default
-:
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.petsc]
-\end_layout
-
-\begin_layout LyX-Code
-# Nonlinear solver monitoring options.
-\end_layout
-
-\begin_layout LyX-Code
-snes_rtol = 1.0e-8
-\end_layout
-
-\begin_layout LyX-Code
-snes_atol = 1.0e-12
-\end_layout
-
-\begin_layout LyX-Code
-snes_max_it = 100
-\end_layout
-
-\begin_layout LyX-Code
-snes_monitor = true
-\end_layout
-
-\begin_layout LyX-Code
-snes_view = true
-\end_layout
-
-\begin_layout LyX-Code
-snes_converged_reason = true
-\end_layout
-
-\begin_layout Standard
-These settings are ignored unless we are using the nonlinear solver.
-\end_layout
-
-\begin_layout Standard
-When setting the physical properties for the power-law material in PyLith,
- the parameters (see Section 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "sub:Power-Law-Maxwell-Viscoelastic"
-
-\end_inset
-
-) do not generally correspond to the values provided in laboratory results.
- PyLith include a utility code, 
-\family typewriter
-powerlaw_gendb.py
-\family default
-, to simplify the process of using laboratory results with PyLith.
- This utility code is installed in the same location as PyLith.
- An example of how to use it is in 
-\family typewriter
-examples/3d/hex8/spatialdb/powerlaw
-\family default
-.
- The user must provide a spatial database defining the spatial distribution
- of laboratory-derived parameters (contained in 
-\family typewriter
-powerlaw_params.spatialdb
-\family default
-), another spatial database defining the temperature field in degrees K
- (contained in 
-\family typewriter
-temperature.spatialdb
-\family default
-), and a set of points for which values are desired (
-\family typewriter
-powerlaw_points.txt
-\family default
-).
- The parameters for the code are defined in 
-\family typewriter
-powerlaw_gendb.cfg
-\family default
-.
- The properties expected by PyLith are 
-\family typewriter
-reference_strain_rate
-\family default
-, 
-\family typewriter
-reference_stress
-\family default
-, and 
-\family typewriter
-power_law_exponent
-\family default
-.
- The user must specify either 
-\family typewriter
-reference_strain_rate
-\family default
- or 
-\family typewriter
-reference_stress
-\family default
- so that 
-\family typewriter
-powerlaw_gendb.py
-\family default
- can compute the other property.
- Default values of 1.0e-6 1/s and 1 MPa are provided.
- In this example, the same database was used for all parameters, and a separate
- database was used to define the temperature distribution.
- In practice, the user can provide any desired thermal model to provide
- the spatial database for the temperature.
- In this example, a simple 1D (vertically-varying) distribution was used.
- The utility code can be used by simply executing it from the 
-\family typewriter
-examples/3d/hex8/spatialdb/powerlaw
-\family default
- directory:
-\end_layout
-
-\begin_layout LyX-Code
-powerlaw_gendb.py
-\end_layout
-
-\begin_layout Standard
-This code will automatically read the parameters in powerlaw_gendb.cfg in
- creating the file
-\begin_inset Newline newline
-\end_inset
-
- 
-\family typewriter
-examples/3d/hex8/spatialdb/mat_powerlaw.spatialdb
-\family default
-.
-\end_layout
-
-\begin_layout Standard
-We first change the material type of the lower crust to 
-\family typewriter
-PowerLaw3D
-\family default
-:
-\end_layout
-
-\begin_layout LyX-Code
-# Change material type of lower crust to power-law viscoelastic.
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.timedependent]
-\end_layout
-
-\begin_layout LyX-Code
-materials.lower_crust = pylith.materials.PowerLaw3D
-\end_layout
-
-\begin_layout Standard
-In many cases, it is useful to obtain the material properties from two different
- sources.
- For example, the elastic properties may come from a seismic velocity model
- while the viscous properties may be derived from a thermal model.
- In such a case we can use a 
-\family typewriter
-CompositeDB
-\family default
-, which allows a different spatial database to be used for a subset of the
- properties.
- We do this as follows:
-\end_layout
-
-\begin_layout LyX-Code
-# Provide a spatial database from which to obtain property values.
-\end_layout
-
-\begin_layout LyX-Code
-# In this case, we prefer to obtain the power-law properties from one
-\end_layout
-
-\begin_layout LyX-Code
-# database and the elastic properties from another database, so we use
-\end_layout
-
-\begin_layout LyX-Code
-# a CompositeDB.
- Each part of the CompositeDB is a SimpleDB.
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.timedependent.materials.lower_crust]
-\end_layout
-
-\begin_layout LyX-Code
-db_properties = spatialdata.spatialdb.CompositeDB
-\end_layout
-
-\begin_layout LyX-Code
-db_properties.db_A = spatialdata.spatialdb.SimpleDB
-\end_layout
-
-\begin_layout LyX-Code
-db_properties.db_B = spatialdata.spatialdb.SimpleDB
-\end_layout
-
-\begin_layout Standard
-We must define the properties that come from each spatial database and then
- provide the database parameters:
-\end_layout
-
-\begin_layout LyX-Code
-# Provide the values to be obtained from each database and the database
-\end_layout
-
-\begin_layout LyX-Code
-# name.
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.timedependent.materials.lower_crust.db_properties]
-\end_layout
-
-\begin_layout LyX-Code
-values_A = [density,vs,vp]   ; Elastic properties.
-\end_layout
-
-\begin_layout LyX-Code
-db_A.label = Elastic properties
-\end_layout
-
-\begin_layout LyX-Code
-db_A.iohandler.filename = spatialdb/mat_elastic.spatialdb
-\end_layout
-
-\begin_layout LyX-Code
-values_B = [reference-stress,reference-strain-rate,power-law-exponent] 
-  ; Power-law properties.
-\end_layout
-
-\begin_layout LyX-Code
-db_B.label = Power-law properties
-\end_layout
-
-\begin_layout LyX-Code
-db_B.iohandler.filename = spatialdb/mat_powerlaw.spatialdb
-\end_layout
-
-\begin_layout Standard
-The 
-\family typewriter
-PowerLaw3D
-\family default
- material has additional properties and state variables with respect to
- the default 
-\family typewriter
-ElasticIsotropic3D
-\family default
- material, so we request that these properties be written to the 
-\family typewriter
-lower_crust
-\family default
- material files:
-\end_layout
-
-\begin_layout LyX-Code
-# Since there are additional properties and state variables for the
-\end_layout
-
-\begin_layout LyX-Code
-# power-law model, we explicitly request that they be output.
- Properties are
-\end_layout
-
-\begin_layout LyX-Code
-# named in cell_info_fields and state variables are named in
-\end_layout
-
-\begin_layout LyX-Code
-# cell_data_fields.
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.timedependent.materials.lower_crust]
-\end_layout
-
-\begin_layout LyX-Code
-output.cell_info_fields = [density,mu,lambda,reference_strain_rate,reference_stre
-ss,
-\begin_inset Newline newline
-\end_inset
-
-power_law_exponent]
-\end_layout
-
-\begin_layout LyX-Code
-output.cell_data_fields = [total_strain,stress,viscous_strain]
-\end_layout
-
-\begin_layout Standard
-When we have run the simulation, the output HDF5 and Xdmf files will be
- contained in 
-\family typewriter
-examples/3d/hex8/output
-\family default
- (all with a prefix of 
-\family typewriter
-step08
-\family default
-).
- Results using ParaView are shown in Figure 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "fig:step08-strain-displ-t150"
-
-\end_inset
-
-.
-\begin_inset Float figure
-wide false
-sideways false
-status open
-
-\begin_layout Plain Layout
-\align center
-\begin_inset Graphics
-	filename figs/step08-strain-displ-t150.jpg
-	lyxscale 50
-	width 10cm
-
-\end_inset
-
-
-\begin_inset Caption
-
-\begin_layout Plain Layout
-The XY-component of strain (color contours) and displacement field (vectors)
- for example step08 at t = 150 years visualized using ParaView.
- For this visualization, we loaded both the 
-\family typewriter
-step08-lower_crust.xmf
-\family default
- and 
-\family typewriter
-step08-upper_crust.xmf
-\family default
- files to contour the strain field, and superimposed on it the displacement
- field vectors from 
-\family typewriter
-step08.xmf
-\family default
-.
-\begin_inset CommandInset label
-LatexCommand label
-name "fig:step08-strain-displ-t150"
-
-\end_inset
-
-.
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Subsubsection
-Step09 - Dirichlet Velocity Boundary Conditions with Time-Dependent Kinematic
- Fault Slip and Drucker-Prager Elastoplastic Rheology
-\end_layout
-
-\begin_layout Standard
-In this example we use a Drucker-Prager elastoplastic rheology in the lower
- crust.
- As in example step08, the material behavior is nonlinear so we again use
- the nonlinear solver.
- The material is elastoplastic, there is no inherent time-dependent response
- and the stable time step size for the material depends on the loading condition
-s.
- To avoid this, we set the maximum time step size to 5 years rather than
- the value of 10 years used in example step08:
-\end_layout
-
-\begin_layout LyX-Code
-# Change the total simulation time to 700 years, and set the maximum time
-\end_layout
-
-\begin_layout LyX-Code
-# step size to 5 years.
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.timedependent.implicit.time_step]
-\end_layout
-
-\begin_layout LyX-Code
-total_time = 700.0*year
-\end_layout
-
-\begin_layout LyX-Code
-max_dt = 5.0*year
-\end_layout
-
-\begin_layout LyX-Code
-stability_factor = 1.0 ; use time step equal to stable value from materials
-\end_layout
-
-\begin_layout LyX-Code
-# For this problem we set adapt_skip to zero so that the time step size
- is
-\end_layout
-
-\begin_layout LyX-Code
-# readjusted every time step.
-\end_layout
-
-\begin_layout LyX-Code
-adapt_skip = 0
-\end_layout
-
-\begin_layout Standard
-We change the material type of the lower crust to 
-\family typewriter
-DruckerPrager3D
-\family default
-, and we again use a 
-\family typewriter
-CompositeDB
-\family default
- to assign the material properties:
-\end_layout
-
-\begin_layout LyX-Code
-# Change material type of lower crust to Drucker-Prager.
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.timedependent]
-\end_layout
-
-\begin_layout LyX-Code
-materials.lower_crust = pylith.materials.DruckerPrager3D
-\end_layout
-
-\begin_layout LyX-Code
-
-\end_layout
-
-\begin_layout LyX-Code
-# Provide a spatial database from which to obtain property values.
-\end_layout
-
-\begin_layout LyX-Code
-# In this case, we prefer to obtain the Drucker-Prager properties from one
-\end_layout
-
-\begin_layout LyX-Code
-# database and the elastic properties from another database, so we use
-\end_layout
-
-\begin_layout LyX-Code
-# a CompositeDB.
- Each part of the CompositeDB is a SimpleDB.
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.timedependent.materials.lower_crust]
-\end_layout
-
-\begin_layout LyX-Code
-db_properties = spatialdata.spatialdb.CompositeDB
-\end_layout
-
-\begin_layout LyX-Code
-db_properties.db_A = spatialdata.spatialdb.SimpleDB
-\end_layout
-
-\begin_layout LyX-Code
-db_properties.db_B = spatialdata.spatialdb.SimpleDB
-\end_layout
-
-\begin_layout Standard
-As for the step08 example, we first define the properties that come from
- each spatial database and then provide the database filename:
-\end_layout
-
-\begin_layout LyX-Code
-# Provide the values to be obtained from each database and the database
-\end_layout
-
-\begin_layout LyX-Code
-# name.
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.timedependent.materials.lower_crust.db_properties]
-\end_layout
-
-\begin_layout LyX-Code
-values_A = [density,vs,vp]   ; Elastic properties.
-\end_layout
-
-\begin_layout LyX-Code
-db_A.label = Elastic properties
-\end_layout
-
-\begin_layout LyX-Code
-db_A.iohandler.filename = spatialdb/mat_elastic.spatialdb
-\end_layout
-
-\begin_layout LyX-Code
-values_B = [friction-angle,cohesion,dilatation-angle]   ; Drucker-Prager
- properties.
-\end_layout
-
-\begin_layout LyX-Code
-db_B.label = Drucker-Prager properties
-\end_layout
-
-\begin_layout LyX-Code
-db_B.iohandler.filename = spatialdb/mat_druckerprager.spatialdb
-\end_layout
-
-\begin_layout Standard
-We also request output of the properties and state variables that are unique
- to the 
-\family typewriter
-DruckerPrager3D
-\family default
- material:
-\end_layout
-
-\begin_layout LyX-Code
-# Since there are additional properties and state variables for the
-\end_layout
-
-\begin_layout LyX-Code
-# Drucker-Prager model, we explicitly request that they be output.
-\end_layout
-
-\begin_layout LyX-Code
-# Properties are named in cell_info_fields and state variables are named
- in
-\end_layout
-
-\begin_layout LyX-Code
-# cell_data_fields.
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.timedependent.materials.lower_crust]
-\end_layout
-
-\begin_layout LyX-Code
-output.cell_info_fields = [density,mu,lambda,alpha_yield,beta,alpha_flow]
-\end_layout
-
-\begin_layout LyX-Code
-output.cell_data_fields = [total_strain,stress,plastic_strain]
-\end_layout
-
-\begin_layout Standard
-When we have run the simulation, the output HDF5 and Xdmf files will be
- contained in 
-\family typewriter
-examples/3d/hex8/output
-\family default
- (all with a prefix of 
-\family typewriter
-step09
-\family default
-).
- Results using ParaView are shown in Figure 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "fig:step09-strain-displ-t150"
-
-\end_inset
-
-.
-\begin_inset Float figure
-wide false
-sideways false
-status open
-
-\begin_layout Plain Layout
-\align center
-\begin_inset Graphics
-	filename figs/step08-strain-displ-t150.jpg
-	lyxscale 50
-	width 10cm
-
-\end_inset
-
-
-\begin_inset Caption
-
-\begin_layout Plain Layout
-The XY-component of strain (color contours) and displacement field (vectors)
- for example step09 at t = 150 years visualized using ParaView.
- For this visualization, we loaded both the 
-\family typewriter
-step09-lower_crust.xmf
-\family default
- and 
-\family typewriter
-step09-upper_crust.xmf
-\family default
- files to contour the strain field, and superimposed on it the displacement
- field vectors from 
-\family typewriter
-step09.xmf
-\family default
-.
-\begin_inset CommandInset label
-LatexCommand label
-name "fig:step09-strain-displ-t150"
-
-\end_inset
-
-.
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_body
-\end_document
+#LyX 2.0 created this file. For more info see http://www.lyx.org/
+\lyxformat 413
+\begin_document
+\begin_header
+\textclass book
+\begin_preamble
+
+\end_preamble
+\use_default_options false
+\maintain_unincluded_children false
+\language english
+\language_package default
+\inputencoding latin1
+\fontencoding global
+\font_roman default
+\font_sans default
+\font_typewriter default
+\font_default_family default
+\use_non_tex_fonts false
+\font_sc false
+\font_osf false
+\font_sf_scale 100
+\font_tt_scale 100
+
+\graphics default
+\default_output_format default
+\output_sync 0
+\bibtex_command default
+\index_command default
+\paperfontsize default
+\spacing single
+\use_hyperref false
+\papersize default
+\use_geometry true
+\use_amsmath 0
+\use_esint 0
+\use_mhchem 1
+\use_mathdots 1
+\cite_engine basic
+\use_bibtopic false
+\use_indices false
+\paperorientation portrait
+\suppress_date false
+\use_refstyle 0
+\index Index
+\shortcut idx
+\color #008000
+\end_index
+\leftmargin 1in
+\topmargin 1in
+\rightmargin 1in
+\bottommargin 2in
+\secnumdepth 3
+\tocdepth 3
+\paragraph_separation indent
+\paragraph_indentation default
+\quotes_language english
+\papercolumns 1
+\papersides 1
+\paperpagestyle default
+\tracking_changes false
+\output_changes false
+\html_math_output 0
+\html_css_as_file 0
+\html_be_strict false
+\end_header
+
+\begin_body
+
+\begin_layout Subsection
+\begin_inset CommandInset label
+LatexCommand label
+name "sec:Tutorial-3d-hex8-quasistatic"
+
+\end_inset
+
+Quasi-Static Examples
+\end_layout
+
+\begin_layout Standard
+PyLith features discussed in this tutorial:
+\end_layout
+
+\begin_layout Itemize
+Quasi-static solution
+\end_layout
+
+\begin_layout Itemize
+Formatting timestamps of VTK output files
+\end_layout
+
+\begin_layout Itemize
+HDF5 output
+\end_layout
+
+\begin_layout Itemize
+Output of velocity field
+\end_layout
+
+\begin_layout Itemize
+Dirichlet displacement and velocity boundary conditions
+\end_layout
+
+\begin_layout Itemize
+Neumann traction boundary conditions and time-varying tractions
+\end_layout
+
+\begin_layout Itemize
+UniformDB spatial database
+\end_layout
+
+\begin_layout Itemize
+CompositeDB spatial database
+\end_layout
+
+\begin_layout Itemize
+Quasi-static fault rupture and fault creep
+\end_layout
+
+\begin_layout Itemize
+Multiple kinematic fault ruptures
+\end_layout
+
+\begin_layout Itemize
+Specifying more than one material
+\end_layout
+
+\begin_layout Itemize
+Nonlinear solver
+\end_layout
+
+\begin_layout Itemize
+Maxwell linear viscoelastic material
+\end_layout
+
+\begin_layout Itemize
+Power-law viscoelastic material
+\end_layout
+
+\begin_layout Itemize
+Drucker-Prager elastoplastic material
+\end_layout
+
+\begin_layout Itemize
+Adaptive time stepping
+\end_layout
+
+\begin_layout Subsubsection
+Overview
+\end_layout
+
+\begin_layout Standard
+This set of examples describes a set of quasi-static problems for PyLith.
+ These quasi-static problems primarily demonstrate the usage of time-dependent
+ boundary conditions and fault slip, as well as different rheologies.
+ Some of the examples also demonstrate the usage of the nonlinear solver,
+ which is required by the nonlinear rheologies (power-law viscoelastic and
+ Drucker-Prager elastoplastic).
+ Some of the examples also demonstrate the usage of HDF5 output, which is
+ an alternative to the default VTK output.
+ All of the examples are contained in the directory 
+\family typewriter
+examples/3d/hex8
+\family default
+, and the corresponding 
+\family typewriter
+.cfg
+\family default
+ files are 
+\family typewriter
+step04.cfg
+\family default
+, 
+\family typewriter
+step05.cfg
+\family default
+, 
+\family typewriter
+step06.cfg
+\family default
+, 
+\family typewriter
+step07.cfg
+\family default
+, 
+\family typewriter
+step08.cfg
+\family default
+, and 
+\family typewriter
+step09.cfg
+\family default
+.
+ Each example may be run as follows:
+\end_layout
+
+\begin_layout LyX-Code
+pylith stepXX.cfg
+\end_layout
+
+\begin_layout Standard
+This will cause PyLith to read the default parameters in 
+\family typewriter
+pylithapp.cfg
+\family default
+, and then override or augment them with the additional parameters in the
+ 
+\family typewriter
+stepXX.cfg
+\family default
+ file.
+ Each 
+\family typewriter
+.cfg
+\family default
+ file is extensively documented, to provide detailed information on the
+ various parameters.
+\end_layout
+
+\begin_layout Subsubsection
+Step04 - Pure Dirichlet Velocity Boundary Conditions
+\end_layout
+
+\begin_layout Standard
+The 
+\family typewriter
+step04.cfg
+\family default
+ file defines a problem with x-displacements fixed at zero on the positive
+ and negative x-faces while velocity boundary conditions are applied in
+ the y-directions on the same faces, yielding a left-lateral sense of movement.
+ The bottom (negative z) boundary is held fixed in the z-direction.
+ We also use a Maxwell viscoelastic material for the lower crust, and the
+ simulation is run for 200 years using a constant time-step size of 20 years.
+ The default time stepping behavior is 
+\family typewriter
+TimeStepUniform
+\family default
+.
+ We retain that behavior for this problem and provide the total simulation
+ time and the time-step size:
+\end_layout
+
+\begin_layout LyX-Code
+# Change the total simulation time to 200 years, and use a constant time
+\end_layout
+
+\begin_layout LyX-Code
+# step size of 20 years.
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.timedependent.implicit.time_step]
+\end_layout
+
+\begin_layout LyX-Code
+total_time = 200.0*year
+\end_layout
+
+\begin_layout LyX-Code
+dt = 20.0*year 
+\end_layout
+
+\begin_layout Standard
+We then change the material type of the lower crust, provide a spatial database
+ from which to obtain the material properties (using the default 
+\family typewriter
+SimpleDB
+\family default
+), and request additional output information for the material:
+\end_layout
+
+\begin_layout LyX-Code
+# Change material type of lower crust to Maxwell viscoelastic.
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.timedependent]
+\end_layout
+
+\begin_layout LyX-Code
+materials.lower_crust = pylith.materials.MaxwellIsotropic3D
+\begin_inset Newline newline
+\end_inset
+
+
+\begin_inset Newline newline
+\end_inset
+
+
+\end_layout
+
+\begin_layout LyX-Code
+# Provide a spatial database from which to obtain property values.
+\end_layout
+
+\begin_layout LyX-Code
+# Since there are additional properties and state variables for the Maxwell
+\end_layout
+
+\begin_layout LyX-Code
+# model, we explicitly request that they be output.
+ Properties are named in
+\end_layout
+
+\begin_layout LyX-Code
+# cell_info_fields and state variables are named in cell_data_fields.
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.timedependent.materials.lower_crust]
+\end_layout
+
+\begin_layout LyX-Code
+db_properties.iohandler.filename = spatialdb/mat_maxwell.spatialdb
+\end_layout
+
+\begin_layout LyX-Code
+output.cell_info_fields = [density,mu,lambda,maxwell_time]
+\end_layout
+
+\begin_layout LyX-Code
+output.cell_data_fields = [total_strain,stress,viscous_strain]
+\end_layout
+
+\begin_layout Standard
+Note that the default 
+\family typewriter
+output.cell_info_fields
+\family default
+ are those corresponding to an elastic material (
+\family typewriter
+density
+\family default
+, 
+\family typewriter
+mu
+\family default
+, 
+\family typewriter
+lambda
+\family default
+), and the default 
+\family typewriter
+output.cell_data_fields
+\family default
+ are 
+\family typewriter
+total_strain
+\family default
+ and 
+\family typewriter
+stress
+\family default
+.
+ For materials other than elastic, there are generally additional material
+ properties and state variables, and the appropriate additional fields must
+ be specifically requested for each material type.
+\end_layout
+
+\begin_layout Standard
+This example has no displacements in the elastic solution (t = 0), so we
+ retain the default 
+\family typewriter
+ZeroDispDB
+\family default
+ for all instances of 
+\family typewriter
+db_initial
+\family default
+.
+ To apply the velocity boundary conditions, we must specify 
+\family typewriter
+db_rate
+\family default
+, which is zero by default.
+ We use a 
+\family typewriter
+UniformDB
+\family default
+ to assign the velocities:
+\end_layout
+
+\begin_layout LyX-Code
+# +x face
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.timedependent.bc.x_pos]
+\end_layout
+
+\begin_layout LyX-Code
+bc_dof = [0, 1]
+\end_layout
+
+\begin_layout LyX-Code
+label = face_xpos
+\end_layout
+
+\begin_layout LyX-Code
+db_initial.label = Dirichlet BC on +x
+\end_layout
+
+\begin_layout LyX-Code
+db_rate = spatialdata.spatialdb.UniformDB
+\end_layout
+
+\begin_layout LyX-Code
+db_rate.label = Dirichlet rate BC on +x
+\end_layout
+
+\begin_layout LyX-Code
+db_rate.values = [displacement-rate-x,displacement-rate-y,rate-start-time]
+\end_layout
+
+\begin_layout LyX-Code
+db_rate.data = [0.0*cm/year,1.0*cm/year,0.0*year]
+\begin_inset Newline newline
+\end_inset
+
+
+\begin_inset Newline newline
+\end_inset
+
+
+\end_layout
+
+\begin_layout LyX-Code
+# -x face
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.timedependent.bc.x_neg]
+\end_layout
+
+\begin_layout LyX-Code
+bc_dof = [0, 1]
+\end_layout
+
+\begin_layout LyX-Code
+label = face_xneg
+\end_layout
+
+\begin_layout LyX-Code
+db_initial.label = Dirichlet BC on -x
+\end_layout
+
+\begin_layout LyX-Code
+db_rate = spatialdata.spatialdb.UniformDB
+\end_layout
+
+\begin_layout LyX-Code
+db_rate.label = Dirichlet rate BC on +x
+\end_layout
+
+\begin_layout LyX-Code
+db_rate.values = [displacement-rate-x,displacement-rate-y,rate-start-time]
+\end_layout
+
+\begin_layout LyX-Code
+db_rate.data = [0.0*cm/year,-1.0*cm/year,0.0*year]
+\end_layout
+
+\begin_layout Standard
+Note that 
+\family typewriter
+db_rate
+\family default
+ requires a start time, which allows the condition to be applied at any
+ time during the simulation.
+ For this example, we start the velocity boundary conditions at t = 0.
+\end_layout
+
+\begin_layout Standard
+Finally, we must provide information on VTK output.
+ This is slightly more complicated than the static case, because we must
+ decide the frequency with which output occurs for each output manager.
+ We also assign a more user-friendly format to the output file time stamp,
+ and we request that the time stamp is in units of 1 year (rather than the
+ default value of seconds):
+\end_layout
+
+\begin_layout LyX-Code
+# Give basename for VTK domain output of solution over domain.
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.problem.formulation.output.domain]
+\end_layout
+
+\begin_layout LyX-Code
+# We specify that output occurs in terms of a given time frequency, and
+\end_layout
+
+\begin_layout LyX-Code
+# ask for output every 40 years.
+ The time stamps of the output files are
+\end_layout
+
+\begin_layout LyX-Code
+# in years (rather than the default of seconds), and we give a format for
+\end_layout
+
+\begin_layout LyX-Code
+# the time stamp.
+\end_layout
+
+\begin_layout LyX-Code
+output_freq = time_step
+\end_layout
+
+\begin_layout LyX-Code
+time_step = 40.0*year
+\end_layout
+
+\begin_layout LyX-Code
+writer.filename = output/step04.vtk
+\end_layout
+
+\begin_layout LyX-Code
+writer.time_format = %04.0f
+\end_layout
+
+\begin_layout LyX-Code
+writer.time_constant = 1.0*year
+\begin_inset Newline newline
+\end_inset
+
+
+\begin_inset Newline newline
+\end_inset
+
+
+\end_layout
+
+\begin_layout LyX-Code
+# Give basename for VTK domain output of solution over ground surface.
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.problem.formulation.output.subdomain]
+\end_layout
+
+\begin_layout LyX-Code
+# Name of nodeset for ground surface.
+\end_layout
+
+\begin_layout LyX-Code
+label = face_zpos
+\end_layout
+
+\begin_layout LyX-Code
+# We keep the default output frequency behavior (skip every n steps), and
+\end_layout
+
+\begin_layout LyX-Code
+# ask to skip 0 steps between output, so that we get output every time step.
+\end_layout
+
+\begin_layout LyX-Code
+skip = 0
+\end_layout
+
+\begin_layout LyX-Code
+writer.filename = output/step04-groundsurf.vtk
+\end_layout
+
+\begin_layout LyX-Code
+writer.time_format = %04.0f
+\end_layout
+
+\begin_layout LyX-Code
+writer.time_constant = 1.0*year
+\end_layout
+
+\begin_layout Standard
+We provide similar output information for the two materials (
+\family typewriter
+upper_crust
+\family default
+ and 
+\family typewriter
+lower_crust
+\family default
+).
+ Note that for the domain output, we requested output in terms of a given
+ time frequency, while for the subdomain we requested output in terms of
+ number of time steps.
+ When we have run the simulation, the output VTK files will be contained
+ in 
+\family typewriter
+examples/3d/hex8/output
+\family default
+ (all with a prefix of 
+\family typewriter
+step04
+\family default
+).
+ Results using ParaView are shown in Figure 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "fig:step04-displ-t200"
+
+\end_inset
+
+.
+\end_layout
+
+\begin_layout Standard
+\begin_inset Float figure
+wide false
+sideways false
+status open
+
+\begin_layout Plain Layout
+\align center
+\begin_inset Graphics
+	filename figs/step04-displ-t200.jpg
+	lyxscale 50
+	width 10cm
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Plain Layout
+\begin_inset Caption
+
+\begin_layout Plain Layout
+Displacement field for example step04 at t = 200 years visualized using
+ ParaView.
+ The mesh has been distorted by the computed displacements (magnified by
+ 500), and the vectors show the computed displacements.
+\begin_inset CommandInset label
+LatexCommand label
+name "fig:step04-displ-t200"
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Subsubsection
+Step05 - Time-Varying Dirichlet and Neumann Boundary Conditions
+\end_layout
+
+\begin_layout Standard
+The 
+\family typewriter
+step05.cfg
+\family default
+ file describes a problem with time-varying Dirichlet and Neumann boundary
+ conditions.
+ The example is similar to example step04, with a few important differences:
+\end_layout
+
+\begin_layout Itemize
+The Dirichlet boundary conditions on the negative x-face include an initial
+ displacement (applied in the elastic solution), as well as a constant velocity.
+\end_layout
+
+\begin_layout Itemize
+Neumann (traction) boundary conditions are applied in the negative x-direction
+ on the positive x-face, giving a compressive stress.
+ An initial traction is applied in the elastic solution, and then at t =
+ 100 years it begins decreasing linearly until it reaches zero at the end
+ of the simulation (t = 200 years).
+\end_layout
+
+\begin_layout Standard
+We again use a Maxwell viscoelastic material for the lower crust.
+\end_layout
+
+\begin_layout Standard
+For the boundary conditions, we must first change the boundary condition
+ type for the positive x-face from the default Dirichlet to Neumann:
+\end_layout
+
+\begin_layout LyX-Code
+# +x face -- first change bc type to Neumann
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.timedependent.bc]
+\end_layout
+
+\begin_layout LyX-Code
+x_pos = pylith.bc.Neumann 
+\end_layout
+
+\begin_layout Standard
+We provide quadrature information for this face as we did for example step02.
+ We then use a 
+\family typewriter
+UniformDB
+\family default
+ for both the initial tractions as well as the traction rates.
+ We provide a start time of 100 years for the traction rates, and use a
+ rate of 0.01 MPa/year, so that by the end of 200 years we have completely
+ cancelled the initial traction of -1 MPa:
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.timedependent.bc.x_pos]
+\end_layout
+
+\begin_layout LyX-Code
+# First specify a UniformDB for the initial tractions, along with the values.
+\end_layout
+
+\begin_layout LyX-Code
+db_initial = spatialdata.spatialdb.UniformDB
+\end_layout
+
+\begin_layout LyX-Code
+db_initial.label = Neumann BC on +x
+\end_layout
+
+\begin_layout LyX-Code
+db_initial.values = [traction-shear-horiz,traction-shear-vert,traction-normal]
+\end_layout
+
+\begin_layout LyX-Code
+db_initial.data = [0.0*MPa,0.0*MPa,-1.0*MPa]
+\begin_inset Newline newline
+\end_inset
+
+
+\begin_inset Newline newline
+\end_inset
+
+
+\end_layout
+
+\begin_layout LyX-Code
+# Provide information on traction rates.
+\end_layout
+
+\begin_layout LyX-Code
+db_rate = spatialdata.spatialdb.UniformDB
+\end_layout
+
+\begin_layout LyX-Code
+db_rate.label = Neumann rate BC on +x
+\end_layout
+
+\begin_layout LyX-Code
+db_rate.values = [traction-rate-shear-horiz,traction-rate-shear-vert,traction-rat
+e-normal,
+\begin_inset Newline newline
+\end_inset
+
+rate-start-time]
+\end_layout
+
+\begin_layout LyX-Code
+db_rate.data = [0.0*MPa/year,0.0*MPa/year,0.01*MPa/year,100.0*year]
+\end_layout
+
+\begin_layout Standard
+The boundary conditions on the negative x-face are analogous, but we are
+ instead using Dirichlet boundary conditions, and the initial displacement
+ is in the same direction as the applied velocities:
+\end_layout
+
+\begin_layout LyX-Code
+# -x face
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.timedependent.bc.x_neg]
+\end_layout
+
+\begin_layout LyX-Code
+bc_dof = [0, 1]
+\end_layout
+
+\begin_layout LyX-Code
+label = face_xneg
+\begin_inset Newline newline
+\end_inset
+
+
+\begin_inset Newline newline
+\end_inset
+
+
+\end_layout
+
+\begin_layout LyX-Code
+# Initial displacements.
+\end_layout
+
+\begin_layout LyX-Code
+db_initial = spatialdata.spatialdb.UniformDB
+\end_layout
+
+\begin_layout LyX-Code
+db_initial.label = Dirichlet BC on -x
+\end_layout
+
+\begin_layout LyX-Code
+db_initial.values = [displacement-x,displacement-y]
+\end_layout
+
+\begin_layout LyX-Code
+db_initial.data = [0.0*cm,-0.5*cm]
+\begin_inset Newline newline
+\end_inset
+
+
+\begin_inset Newline newline
+\end_inset
+
+
+\end_layout
+
+\begin_layout LyX-Code
+# Velocities.
+\end_layout
+
+\begin_layout LyX-Code
+db_rate = spatialdata.spatialdb.UniformDB
+\end_layout
+
+\begin_layout LyX-Code
+db_rate.label = Dirichlet rate BC on -x
+\end_layout
+
+\begin_layout LyX-Code
+db_rate.values = [displacement-rate-x,displacement-rate-y,rate-start-time]
+\end_layout
+
+\begin_layout LyX-Code
+db_rate.data = [0.0*cm/year,-1.0*cm/year,0.0*year]
+\end_layout
+
+\begin_layout Standard
+The boundary conditions on the negative z-face are supplied in the same
+ manner as for example step04.
+ When we have run the simulation, the output VTK files will be contained
+ in 
+\family typewriter
+examples/3d/hex8/output
+\family default
+ (all with a prefix of 
+\family typewriter
+step05
+\family default
+).
+ Results using ParaView are shown in Figure 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "fig:step05-displ-t40"
+
+\end_inset
+
+.
+\begin_inset Float figure
+wide false
+sideways false
+status open
+
+\begin_layout Plain Layout
+\align center
+\begin_inset Graphics
+	filename figs/step05-displ-t40.jpg
+	lyxscale 50
+	width 10cm
+
+\end_inset
+
+
+\begin_inset Caption
+
+\begin_layout Plain Layout
+Displacement field for example step05 at t = 40 years visualized using ParaView.
+ The mesh has been distorted by the computed displacements (magnified by
+ 500), and the vectors show the computed displacements.
+\begin_inset CommandInset label
+LatexCommand label
+name "fig:step05-displ-t40"
+
+\end_inset
+
+.
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Subsubsection
+Step06 - Dirichlet Boundary Conditions with Time-Dependent Kinematic Fault
+ Slip
+\end_layout
+
+\begin_layout Standard
+The 
+\family typewriter
+step06.cfg
+\family default
+ file defines a problem with Dirichlet (displacement) boundary conditions
+ corresponding to zero x- and y-displacements applied on the negative and
+ positive x-faces and a vertical fault that includes multiple earthquake
+ ruptures as well as steady fault creep.
+ The upper (locked) portion of the fault has 4 m of left-lateral slip every
+ 200 years, while the lower (creeping) portion of the fault slips at a steady
+ rate of 2 cm/year.
+ The problem bears some similarity to the strike-slip fault model of Savage
+ and Prescott 
+\begin_inset CommandInset citation
+LatexCommand cite
+key "Savage:Prescott:1978"
+
+\end_inset
+
+, except that the fault creep extends through the viscoelastic portion of
+ the domain, and the far-field displacement boundary conditions are held
+ fixed.
+\end_layout
+
+\begin_layout Standard
+In this example and the remainder of the examples in this section, we change
+ the time stepping behavior from the default 
+\family typewriter
+TimeStepUniform
+\family default
+ to 
+\family typewriter
+TimeStepAdapt
+\family default
+.
+ For adaptive time stepping, we provide the maximum permissible time-step
+ size, along with a stability factor.
+ The stability factor controls the time-step size relative to the stable
+ time-step size provided by the different materials in the model.
+ A 
+\family typewriter
+stability_factor
+\family default
+ of 1.0 means we should use the stable time-step size, while a 
+\family typewriter
+stability_factor
+\family default
+ greater than 1.0 means we want to use a smaller time-step size.
+ A 
+\family typewriter
+stability_factor
+\family default
+ less than 1.0 allows time-step sizes greater than the stable time-step size,
+ which may provide inaccurate results.
+ The adaptive time stepping information is provided as:
+\end_layout
+
+\begin_layout LyX-Code
+# Change time stepping algorithm from uniform time step, to adaptive
+\end_layout
+
+\begin_layout LyX-Code
+# time stepping.
+\end_layout
+
+\begin_layout LyX-Code
+time_step = pylith.problems.TimeStepAdapt
+\begin_inset Newline newline
+\end_inset
+
+
+\begin_inset Newline newline
+\end_inset
+
+
+\end_layout
+
+\begin_layout LyX-Code
+# Change the total simulation time to 700 years, and set the maximum time
+\end_layout
+
+\begin_layout LyX-Code
+# step size to 10 years.
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.timedependent.implicit.time_step]
+\end_layout
+
+\begin_layout LyX-Code
+total_time = 700.0*year
+\end_layout
+
+\begin_layout LyX-Code
+max_dt = 10.0*year
+\end_layout
+
+\begin_layout LyX-Code
+stability_factor = 1.0 ; use time step equal to stable value from materials
+\end_layout
+
+\begin_layout Standard
+In this example and the remainder of the examples in this section, we also
+ make use of HDF5 output rather than the default VTK output.
+ HDF5 output is a new feature beginning with PyLith version 1.6, and it is
+ much more efficient with the additional advantage that multiple time steps
+ can be contained in a single file.
+ PyLith also produces Xdmf files describing the contents of the HDF5 files,
+ which allows the files to be read easily by applications such as ParaView.
+ Since VTK output is still the default, we must change the value from the
+ default.
+ Also note that the filename suffix is 
+\family typewriter
+.h5
+\family default
+:
+\end_layout
+
+\begin_layout LyX-Code
+# Give basename for output of solution over domain.
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.problem.formulation.output.domain]
+\end_layout
+
+\begin_layout LyX-Code
+# We specify that output occurs in terms of a given time frequency, and
+\end_layout
+
+\begin_layout LyX-Code
+# ask for output every 50 years.
+\end_layout
+
+\begin_layout LyX-Code
+output_freq = time_step
+\end_layout
+
+\begin_layout LyX-Code
+time_step = 50.0*year
+\begin_inset Newline newline
+\end_inset
+
+
+\begin_inset Newline newline
+\end_inset
+
+
+\end_layout
+
+\begin_layout LyX-Code
+# We are using HDF5 output so we must change the default writer.
+\end_layout
+
+\begin_layout LyX-Code
+writer = pylith.meshio.DataWriterHDF5Mesh
+\end_layout
+
+\begin_layout LyX-Code
+writer.filename = output/step06.h5  
+\end_layout
+
+\begin_layout Standard
+Note that we no longer need the 
+\family typewriter
+writer.time_format
+\family default
+ or 
+\family typewriter
+writer.time_constant
+\family default
+ properties, since all time steps are contained in a single file.
+ The HDF5 writer does not have these properties, so if we attempt to define
+ them an error will result.
+\end_layout
+
+\begin_layout Standard
+We also set the writer for other output as well, since it is not the default.
+ For subdomain output we use:
+\end_layout
+
+\begin_layout LyX-Code
+# Give basename for output of solution over ground surface.
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.problem.formulation.output.subdomain]
+\end_layout
+
+\begin_layout LyX-Code
+# Name of nodeset for ground surface.
+\end_layout
+
+\begin_layout LyX-Code
+label = face_zpos
+\begin_inset Newline newline
+\end_inset
+
+
+\begin_inset Newline newline
+\end_inset
+
+
+\end_layout
+
+\begin_layout LyX-Code
+# We keep the default output frequency behavior (skip every n steps), and
+\end_layout
+
+\begin_layout LyX-Code
+# ask to skip 0 steps between output, so that we get output every time step.
+\end_layout
+
+\begin_layout LyX-Code
+# We again switch the writer to produce HDF5 output.
+\end_layout
+
+\begin_layout LyX-Code
+# Note that we specifically ask for a submesh writer.
+\end_layout
+
+\begin_layout LyX-Code
+skip = 0
+\end_layout
+
+\begin_layout LyX-Code
+writer = pylith.meshio.DataWriterHDF5SubMesh
+\end_layout
+
+\begin_layout LyX-Code
+writer.filename = output/step06-groundsurf.h5  
+\end_layout
+
+\begin_layout Standard
+For fault output we use:
+\end_layout
+
+\begin_layout LyX-Code
+# Give basename for fault rupture output.
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.problem.interfaces.fault.output]
+\end_layout
+
+\begin_layout LyX-Code
+# We keep the default output frequency behavior (skip every n steps), and
+\end_layout
+
+\begin_layout LyX-Code
+# ask to skip 0 steps between output, so that we get output every time step.
+\end_layout
+
+\begin_layout LyX-Code
+# We again switch the writer to produce HDF5 output.
+\end_layout
+
+\begin_layout LyX-Code
+# Note that we specifically ask for a subsubmesh writer.
+\end_layout
+
+\begin_layout LyX-Code
+skip = 0
+\end_layout
+
+\begin_layout LyX-Code
+writer = pylith.meshio.DataWriterHDF5SubSubMesh
+\end_layout
+
+\begin_layout LyX-Code
+writer.filename = output/step06-fault.h5
+\end_layout
+
+\begin_layout Standard
+Note the usage of 
+\family typewriter
+pylith.meshio.DataWriterHDF5SubMesh
+\family default
+ for subdomain output and
+\family typewriter
+
+\begin_inset Newline newline
+\end_inset
+
+pylith.meshio.DataWriterHDF5SubSubMesh
+\family default
+ for fault output.
+\end_layout
+
+\begin_layout Standard
+Due to the simplicity of the boundary conditions, we are able to use the
+ default 
+\family typewriter
+ZeroDispBC
+\family default
+ for the positive and negative x-faces, as well as the negative z-face.
+ As for example step03, we define a fault interface, we identify the nodeset
+ corresponding to the fault, and we provide quadrature information for the
+ fault.
+ We then define an array of earthquake sources and provide an origin time
+ for each:
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.timedependent.interfaces.fault]
+\end_layout
+
+\begin_layout LyX-Code
+# Set earthquake sources to an array consisting of creep and 3 ruptures.
+\end_layout
+
+\begin_layout LyX-Code
+eq_srcs = [creep,one,two,three]
+\end_layout
+
+\begin_layout LyX-Code
+eq_srcs.creep.origin_time = 00.0*year
+\end_layout
+
+\begin_layout LyX-Code
+eq_srcs.one.origin_time = 200.0*year
+\end_layout
+
+\begin_layout LyX-Code
+eq_srcs.two.origin_time = 400.0*year
+\end_layout
+
+\begin_layout LyX-Code
+eq_srcs.three.origin_time = 600.0*year
+\end_layout
+
+\begin_layout Standard
+Note that the creep begins at t = 0 years, while the ruptures (
+\family typewriter
+one
+\family default
+, 
+\family typewriter
+two
+\family default
+, 
+\family typewriter
+three
+\family default
+) occur at regular intervals of 200 years.
+ We retain the default 
+\family typewriter
+StepSlipFn
+\family default
+ for the ruptures.
+ Each of the ruptures has the same amount of slip, and slip occurs simultaneousl
+y for the entire rupture region, so we can use the same 
+\family typewriter
+SimpleDB
+\family default
+ files providing slip and slip time for each rupture:
+\end_layout
+
+\begin_layout LyX-Code
+# Define slip and origin time for first rupture.
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.timedependent.interfaces.fault.eq_srcs.one.slip_function]
+\end_layout
+
+\begin_layout LyX-Code
+slip.iohandler.filename = spatialdb/finalslip_rupture.spatialdb
+\end_layout
+
+\begin_layout LyX-Code
+slip_time.iohandler.filename = spatialdb/sliptime.spatialdb
+\begin_inset Newline newline
+\end_inset
+
+
+\begin_inset Newline newline
+\end_inset
+
+
+\end_layout
+
+\begin_layout LyX-Code
+# Define slip and origin time for second rupture.
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.timedependent.interfaces.fault.eq_srcs.two.slip_function]
+\end_layout
+
+\begin_layout LyX-Code
+slip.iohandler.filename = spatialdb/finalslip_rupture.spatialdb
+\end_layout
+
+\begin_layout LyX-Code
+slip_time.iohandler.filename = spatialdb/sliptime.spatialdb
+\begin_inset Newline newline
+\end_inset
+
+
+\begin_inset Newline newline
+\end_inset
+
+
+\end_layout
+
+\begin_layout LyX-Code
+# Define slip and origin time for third rupture.
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.timedependent.interfaces.fault.eq_srcs.three.slip_function]
+\end_layout
+
+\begin_layout LyX-Code
+slip.iohandler.filename = spatialdb/finalslip_rupture.spatialdb
+\end_layout
+
+\begin_layout LyX-Code
+slip_time.iohandler.filename = spatialdb/sliptime.spatialdb
+\end_layout
+
+\begin_layout Standard
+For the creep source, we change the slip function to 
+\family typewriter
+ConstRateSlipFn
+\family default
+, and we use a 
+\family typewriter
+SimpleDB
+\family default
+ for both the slip time and the slip rate:
+\end_layout
+
+\begin_layout LyX-Code
+# Define slip rate and origin time for fault creep.
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.timedependent.interfaces.fault.eq_srcs.creep]
+\end_layout
+
+\begin_layout LyX-Code
+slip_function = pylith.faults.ConstRateSlipFn
+\end_layout
+
+\begin_layout LyX-Code
+slip_function.slip_rate.iohandler.filename = spatialdb/sliprate_creep.spatialdb
+\end_layout
+
+\begin_layout LyX-Code
+slip_function.slip_time.iohandler.filename = spatialdb/sliptime.spatialdb
+\end_layout
+
+\begin_layout Standard
+For all earthquake sources we provide both an 
+\family typewriter
+origin_time
+\family default
+ and a 
+\family typewriter
+slip_function.slip_time
+\family default
+.
+ The first provides the starting time for the entire earthquake source,
+ while the second provides any spatial variation in the slip time with respect
+ to the 
+\family typewriter
+origin_time
+\family default
+ (if any).
+ Since there are multiple earthquake sources of different types, there are
+ a number of additional fault information fields available for output.
+ We add these additional fields' output to the fault information file:
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.timedependent.interfaces.fault]
+\end_layout
+
+\begin_layout LyX-Code
+output.vertex_info_fields = [normal_dir,strike_dir,dip_dir,final_slip_creep,
+\begin_inset Newline newline
+\end_inset
+
+final_slip_one,final_slip_two,final_slip_three,slip_time_creep,slip_time_one,
+\begin_inset Newline newline
+\end_inset
+
+slip_time_two,slip_time_three]
+\end_layout
+
+\begin_layout Standard
+This additional information will be contained in file 
+\family typewriter
+step06-fault_info.h5
+\family default
+.
+ It will contain final slip information for each earthquake source along
+ with slip time information.
+ When we have run the simulation, the output HDF5 and Xdmf files will be
+ contained in 
+\family typewriter
+examples/3d/hex8/output
+\family default
+ (all with a prefix of 
+\family typewriter
+step06
+\family default
+).
+ To open the files in ParaView, the Xdmf (
+\family typewriter
+.xmf
+\family default
+) files should be opened, as these files describe the HDF5 data structure.
+ Results using ParaView are shown in Figure 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "fig:step06-displ-t300"
+
+\end_inset
+
+.
+\begin_inset Float figure
+wide false
+sideways false
+status open
+
+\begin_layout Plain Layout
+\align center
+\begin_inset Graphics
+	filename figs/step06-displ-t300.jpg
+	lyxscale 50
+	width 10cm
+
+\end_inset
+
+
+\begin_inset Caption
+
+\begin_layout Plain Layout
+Displacement field for example step06 at t = 300 years visualized using
+ ParaView.
+ The mesh has been distorted by the computed displacements (magnified by
+ 500), and the vectors show the computed displacements.
+\begin_inset CommandInset label
+LatexCommand label
+name "fig:step06-displ-t300"
+
+\end_inset
+
+.
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Subsubsection
+Step07 - Dirichlet Velocity Boundary Conditions with Time-Dependent Kinematic
+ Fault Slip
+\end_layout
+
+\begin_layout Standard
+In 
+\family typewriter
+step07
+\family default
+ we add velocity boundary conditions in the positive and negative y-directions
+ on the positive and negative x-faces, so that the external boundaries keep
+ pace with the average fault slip.
+ This problem is nearly identical to the strike-slip fault model of Savage
+ and Prescott 
+\begin_inset CommandInset citation
+LatexCommand cite
+key "Savage:Prescott:1978"
+
+\end_inset
+
+, except that the fault creep extends through the viscoelastic portion of
+ the domain.
+\end_layout
+
+\begin_layout Standard
+We use the default 
+\family typewriter
+ZeroDispBC
+\family default
+ for the initial displacements on the positive and negative x-faces, as
+ well as the negative z-face.
+ For the velocities on the positive and negative x-faces, we use a 
+\family typewriter
+UniformDB
+\family default
+:
+\end_layout
+
+\begin_layout LyX-Code
+# +x face
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.timedependent.bc.x_pos]
+\end_layout
+
+\begin_layout LyX-Code
+bc_dof = [0, 1]
+\end_layout
+
+\begin_layout LyX-Code
+label = face_xpos
+\end_layout
+
+\begin_layout LyX-Code
+db_initial.label = Dirichlet BC on +x
+\end_layout
+
+\begin_layout LyX-Code
+db_rate = spatialdata.spatialdb.UniformDB
+\end_layout
+
+\begin_layout LyX-Code
+db_rate.label = Dirichlet rate BC on +x
+\end_layout
+
+\begin_layout LyX-Code
+db_rate.values = [displacement-rate-x,displacement-rate-y,rate-start-time]
+\end_layout
+
+\begin_layout LyX-Code
+db_rate.data = [0.0*cm/year,1.0*cm/year,0.0*year]
+\begin_inset Newline newline
+\end_inset
+
+
+\begin_inset Newline newline
+\end_inset
+
+
+\end_layout
+
+\begin_layout LyX-Code
+# -x face
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.timedependent.bc.x_neg]
+\end_layout
+
+\begin_layout LyX-Code
+bc_dof = [0, 1]
+\end_layout
+
+\begin_layout LyX-Code
+label = face_xneg
+\end_layout
+
+\begin_layout LyX-Code
+db_initial.label = Dirichlet BC on -x
+\end_layout
+
+\begin_layout LyX-Code
+db_rate = spatialdata.spatialdb.UniformDB
+\end_layout
+
+\begin_layout LyX-Code
+db_rate.label = Dirichlet rate BC on +x
+\end_layout
+
+\begin_layout LyX-Code
+db_rate.values = [displacement-rate-x,displacement-rate-y,rate-start-time]
+\end_layout
+
+\begin_layout LyX-Code
+db_rate.data = [0.0*cm/year,-1.0*cm/year,0.0*year]
+\end_layout
+
+\begin_layout Standard
+The fault definition information is identical to example 
+\family typewriter
+step06
+\family default
+.
+ In previous examples, we have just used the default output for the domain
+ and subdomain (ground surface), which includes the displacements.
+ In many cases, it is also useful to include the velocities.
+ PyLith provides this information, computing the velocities for the current
+ time step as the difference between the current displacements and the displacem
+ents from the previous time step, divided by the time-step size.
+ This is more accurate than computing the velocities from the displacement
+ field output that has been decimated in time.
+ We can obtain this information by explicitly requesting it in 
+\family typewriter
+vertex_data_fields
+\family default
+:
+\end_layout
+
+\begin_layout LyX-Code
+# Give basename for output of solution over domain.
+\begin_inset Newline newline
+\end_inset
+
+[pylithapp.problem.formulation.output.domain]
+\end_layout
+
+\begin_layout LyX-Code
+# We specify that output occurs in terms of a given time frequency, and
+\end_layout
+
+\begin_layout LyX-Code
+# ask for output every 50 years.
+\end_layout
+
+\begin_layout LyX-Code
+# We also request velocity output in addition to displacements.
+\begin_inset Newline newline
+\end_inset
+
+vertex_data_fields = [displacement,velocity]
+\end_layout
+
+\begin_layout LyX-Code
+output_freq = time_step
+\end_layout
+
+\begin_layout LyX-Code
+time_step = 50.0*year
+\begin_inset Newline newline
+\end_inset
+
+
+\begin_inset Newline newline
+\end_inset
+
+
+\end_layout
+
+\begin_layout LyX-Code
+# We are using HDF5 output so we must change the default writer.
+\end_layout
+
+\begin_layout LyX-Code
+writer = pylith.meshio.DataWriterHDF5Mesh
+\end_layout
+
+\begin_layout LyX-Code
+writer.filename = output/step07.h5
+\begin_inset Newline newline
+\end_inset
+
+
+\begin_inset Newline newline
+\end_inset
+
+
+\end_layout
+
+\begin_layout LyX-Code
+# Give basename for output of solution over ground surface.
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.problem.formulation.output.subdomain]
+\end_layout
+
+\begin_layout LyX-Code
+# Name of nodeset for ground surface.
+\end_layout
+
+\begin_layout LyX-Code
+label = face_zpos
+\begin_inset Newline newline
+\end_inset
+
+
+\begin_inset Newline newline
+\end_inset
+
+
+\end_layout
+
+\begin_layout LyX-Code
+# We also request velocity output in addition to displacements.
+\end_layout
+
+\begin_layout LyX-Code
+vertex_data_fields = [displacement,velocity]
+\end_layout
+
+\begin_layout LyX-Code
+# We keep the default output frequency behavior (skip every n steps), and
+\end_layout
+
+\begin_layout LyX-Code
+# ask to skip 0 steps between output, so that we get output every time step.
+\end_layout
+
+\begin_layout LyX-Code
+skip = 0
+\begin_inset Newline newline
+\end_inset
+
+
+\begin_inset Newline newline
+\end_inset
+
+
+\end_layout
+
+\begin_layout LyX-Code
+# We again switch the writer to produce HDF5 output.
+\end_layout
+
+\begin_layout LyX-Code
+# Note that we specifically ask for a submesh writer.
+\end_layout
+
+\begin_layout LyX-Code
+writer = pylith.meshio.DataWriterHDF5SubMesh
+\end_layout
+
+\begin_layout LyX-Code
+writer.filename = output/step07-groundsurf.h5
+\end_layout
+
+\begin_layout Standard
+When we have run the simulation, the output HDF5 and Xdmf files will be
+ contained in 
+\family typewriter
+examples/3d/hex8/output
+\family default
+ (all with a prefix of 
+\family typewriter
+step07
+\family default
+).
+ As for example 
+\family typewriter
+step06
+\family default
+, make sure to open the 
+\family typewriter
+.xmf
+\family default
+ files rather than the 
+\family typewriter
+.h5
+\family default
+ files.
+ Results using ParaView are shown in Figure 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "fig:step07-displ-vel-t300"
+
+\end_inset
+
+.
+\begin_inset Float figure
+wide false
+sideways false
+status open
+
+\begin_layout Plain Layout
+\align center
+\begin_inset Graphics
+	filename figs/step07-displ-vel-t300.jpg
+	lyxscale 50
+	width 10cm
+
+\end_inset
+
+
+\begin_inset Caption
+
+\begin_layout Plain Layout
+Displacement field (color contours) and velocity field (vectors) for example
+ 
+\family typewriter
+step07
+\family default
+ at t = 300 years visualized using ParaView.
+ The mesh has been distorted by the computed displacements (magnified by
+ 500), and the vectors show the computed velocities.
+\begin_inset CommandInset label
+LatexCommand label
+name "fig:step07-displ-vel-t300"
+
+\end_inset
+
+.
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Subsubsection
+Step08 - Dirichlet Velocity Boundary Conditions with Time-Dependent Kinematic
+ Fault Slip and Power-Law Rheology
+\begin_inset CommandInset label
+LatexCommand label
+name "sub:Tutorial-Step08-Power-law"
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+The 
+\family typewriter
+step08.cfg
+\family default
+ file defines a problem that is identical to example 
+\family typewriter
+step07
+\family default
+, except the the lower crust is composed of a power-law viscoelastic material.
+ Since the material behavior is now nonlinear, we must use the nonlinear
+ solver:
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.timedependent]
+\end_layout
+
+\begin_layout LyX-Code
+# For this problem we must switch to a nonlinear solver.
+\end_layout
+
+\begin_layout LyX-Code
+implicit.solver = pylith.problems.SolverNonlinear
+\end_layout
+
+\begin_layout Standard
+Although we have not discussed the PyLith PETSc settings previously, note
+ that the use of the nonlinear solver may require additional options if
+ we wish to override the defaults.
+ These settings are contained in 
+\family typewriter
+pylithapp.cfg
+\family default
+:
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.petsc]
+\end_layout
+
+\begin_layout LyX-Code
+# Nonlinear solver monitoring options.
+\end_layout
+
+\begin_layout LyX-Code
+snes_rtol = 1.0e-8
+\end_layout
+
+\begin_layout LyX-Code
+snes_atol = 1.0e-12
+\end_layout
+
+\begin_layout LyX-Code
+snes_max_it = 100
+\end_layout
+
+\begin_layout LyX-Code
+snes_monitor = true
+\end_layout
+
+\begin_layout LyX-Code
+snes_view = true
+\end_layout
+
+\begin_layout LyX-Code
+snes_converged_reason = true
+\end_layout
+
+\begin_layout Standard
+These settings are ignored unless we are using the nonlinear solver.
+\end_layout
+
+\begin_layout Standard
+When setting the physical properties for the power-law material in PyLith,
+ the parameters (see Section 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "sub:Power-Law-Maxwell-Viscoelastic"
+
+\end_inset
+
+) do not generally correspond to the values provided in laboratory results.
+ PyLith includes a utility code, 
+\family typewriter
+powerlaw_gendb.py
+\family default
+, to simplify the process of using laboratory results with PyLith.
+ This utility code is installed in the same location as PyLith.
+ An example of how to use it is in 
+\family typewriter
+examples/3d/hex8/spatialdb/powerlaw
+\family default
+.
+ The user must provide a spatial database defining the spatial distribution
+ of laboratory-derived parameters (contained in 
+\family typewriter
+powerlaw_params.spatialdb
+\family default
+), another spatial database defining the temperature field in degrees K
+ (contained in 
+\family typewriter
+temperature.spatialdb
+\family default
+), and a set of points for which values are desired (
+\family typewriter
+powerlaw_points.txt
+\family default
+).
+ The parameters for the code are defined in 
+\family typewriter
+powerlaw_gendb.cfg
+\family default
+.
+ The properties expected by PyLith are 
+\family typewriter
+reference_strain_rate
+\family default
+, 
+\family typewriter
+reference_stress
+\family default
+, and 
+\family typewriter
+power_law_exponent
+\family default
+.
+ The user must specify either 
+\family typewriter
+reference_strain_rate
+\family default
+ or 
+\family typewriter
+reference_stress
+\family default
+ so that 
+\family typewriter
+powerlaw_gendb.py
+\family default
+ can compute the other property.
+ Default values of 1.0e-6 1/s and 1 MPa are provided.
+ In this example, the same database was used for all parameters, and a separate
+ database was used to define the temperature distribution.
+ In practice, the user can provide any desired thermal model to provide
+ the spatial database for the temperature.
+ In this example, a simple 1D (vertically-varying) distribution was used.
+ The utility code can be used by simply executing it from the 
+\family typewriter
+examples/3d/hex8/spatialdb/powerlaw
+\family default
+ directory:
+\end_layout
+
+\begin_layout LyX-Code
+powerlaw_gendb.py
+\end_layout
+
+\begin_layout Standard
+This code will automatically read the parameters in powerlaw_gendb.cfg in
+ creating the file
+\begin_inset Newline newline
+\end_inset
+
+ 
+\family typewriter
+examples/3d/hex8/spatialdb/mat_powerlaw.spatialdb
+\family default
+.
+\end_layout
+
+\begin_layout Standard
+We first change the material type of the lower crust to 
+\family typewriter
+PowerLaw3D
+\family default
+:
+\end_layout
+
+\begin_layout LyX-Code
+# Change material type of lower crust to power-law viscoelastic.
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.timedependent]
+\end_layout
+
+\begin_layout LyX-Code
+materials.lower_crust = pylith.materials.PowerLaw3D
+\end_layout
+
+\begin_layout Standard
+In many cases, it is useful to obtain the material properties from two different
+ sources.
+ For example, the elastic properties may come from a seismic velocity model
+ while the viscous properties may be derived from a thermal model.
+ In such a case we can use a 
+\family typewriter
+CompositeDB
+\family default
+, which allows a different spatial database to be used for a subset of the
+ properties.
+ We do this as follows:
+\end_layout
+
+\begin_layout LyX-Code
+# Provide a spatial database from which to obtain property values.
+\end_layout
+
+\begin_layout LyX-Code
+# In this case, we prefer to obtain the power-law properties from one
+\end_layout
+
+\begin_layout LyX-Code
+# database and the elastic properties from another database, so we use
+\end_layout
+
+\begin_layout LyX-Code
+# a CompositeDB.
+ Each part of the CompositeDB is a SimpleDB.
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.timedependent.materials.lower_crust]
+\end_layout
+
+\begin_layout LyX-Code
+db_properties = spatialdata.spatialdb.CompositeDB
+\end_layout
+
+\begin_layout LyX-Code
+db_properties.db_A = spatialdata.spatialdb.SimpleDB
+\end_layout
+
+\begin_layout LyX-Code
+db_properties.db_B = spatialdata.spatialdb.SimpleDB
+\end_layout
+
+\begin_layout Standard
+We must define the properties that come from each spatial database and then
+ provide the database parameters:
+\end_layout
+
+\begin_layout LyX-Code
+# Provide the values to be obtained from each database and the database
+\end_layout
+
+\begin_layout LyX-Code
+# name.
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.timedependent.materials.lower_crust.db_properties]
+\end_layout
+
+\begin_layout LyX-Code
+values_A = [density,vs,vp]   ; Elastic properties.
+\end_layout
+
+\begin_layout LyX-Code
+db_A.label = Elastic properties
+\end_layout
+
+\begin_layout LyX-Code
+db_A.iohandler.filename = spatialdb/mat_elastic.spatialdb
+\end_layout
+
+\begin_layout LyX-Code
+values_B = [reference-stress,reference-strain-rate,power-law-exponent] 
+  ; Power-law properties.
+\end_layout
+
+\begin_layout LyX-Code
+db_B.label = Power-law properties
+\end_layout
+
+\begin_layout LyX-Code
+db_B.iohandler.filename = spatialdb/mat_powerlaw.spatialdb
+\end_layout
+
+\begin_layout Standard
+The 
+\family typewriter
+PowerLaw3D
+\family default
+ material has additional properties and state variables with respect to
+ the default 
+\family typewriter
+ElasticIsotropic3D
+\family default
+ material, so we request that these properties be written to the 
+\family typewriter
+lower_crust
+\family default
+ material files:
+\end_layout
+
+\begin_layout LyX-Code
+# Since there are additional properties and state variables for the
+\end_layout
+
+\begin_layout LyX-Code
+# power-law model, we explicitly request that they be output.
+ Properties are
+\end_layout
+
+\begin_layout LyX-Code
+# named in cell_info_fields and state variables are named in
+\end_layout
+
+\begin_layout LyX-Code
+# cell_data_fields.
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.timedependent.materials.lower_crust]
+\end_layout
+
+\begin_layout LyX-Code
+output.cell_info_fields = [density,mu,lambda,reference_strain_rate,reference_stre
+ss,
+\begin_inset Newline newline
+\end_inset
+
+power_law_exponent]
+\end_layout
+
+\begin_layout LyX-Code
+output.cell_data_fields = [total_strain,stress,viscous_strain]
+\end_layout
+
+\begin_layout Standard
+When we have run the simulation, the output HDF5 and Xdmf files will be
+ contained in 
+\family typewriter
+examples/3d/hex8/output
+\family default
+ (all with a prefix of 
+\family typewriter
+step08
+\family default
+).
+ Results using ParaView are shown in Figure 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "fig:step08-strain-displ-t150"
+
+\end_inset
+
+.
+\begin_inset Float figure
+wide false
+sideways false
+status open
+
+\begin_layout Plain Layout
+\align center
+\begin_inset Graphics
+	filename figs/step08-strain-displ-t150.jpg
+	lyxscale 50
+	width 10cm
+
+\end_inset
+
+
+\begin_inset Caption
+
+\begin_layout Plain Layout
+The XY-component of strain (color contours) and displacement field (vectors)
+ for example 
+\family typewriter
+step08
+\family default
+ at t = 150 years visualized using ParaView.
+ For this visualization, we loaded both the 
+\family typewriter
+step08-lower_crust.xmf
+\family default
+ and 
+\family typewriter
+step08-upper_crust.xmf
+\family default
+ files to contour the strain field, and superimposed on it the displacement
+ field vectors from 
+\family typewriter
+step08.xmf
+\family default
+.
+\begin_inset CommandInset label
+LatexCommand label
+name "fig:step08-strain-displ-t150"
+
+\end_inset
+
+.
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Subsubsection
+Step09 - Dirichlet Velocity Boundary Conditions with Time-Dependent Kinematic
+ Fault Slip and Drucker-Prager Elastoplastic Rheology
+\end_layout
+
+\begin_layout Standard
+In this example we use a Drucker-Prager elastoplastic rheology in the lower
+ crust.
+ As in example 
+\family typewriter
+step08
+\family default
+, the material behavior is nonlinear so we again use the nonlinear solver.
+ The material is elastoplastic, there is no inherent time-dependent response
+ and the stable time-step size for the material depends on the loading condition
+s.
+ To avoid this, we set the maximum time-step size to 5 years rather than
+ the value of 10 years used in example 
+\family typewriter
+step08
+\family default
+:
+\end_layout
+
+\begin_layout LyX-Code
+# Change the total simulation time to 700 years, and set the maximum time
+\end_layout
+
+\begin_layout LyX-Code
+# step size to 5 years.
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.timedependent.implicit.time_step]
+\end_layout
+
+\begin_layout LyX-Code
+total_time = 700.0*year
+\end_layout
+
+\begin_layout LyX-Code
+max_dt = 5.0*year
+\end_layout
+
+\begin_layout LyX-Code
+stability_factor = 1.0 ; use time step equal to stable value from materials
+\end_layout
+
+\begin_layout LyX-Code
+# For this problem we set adapt_skip to zero so that the time step size
+ is
+\end_layout
+
+\begin_layout LyX-Code
+# readjusted every time step.
+\end_layout
+
+\begin_layout LyX-Code
+adapt_skip = 0
+\end_layout
+
+\begin_layout Standard
+We change the material type of the lower crust to 
+\family typewriter
+DruckerPrager3D
+\family default
+, and we again use a 
+\family typewriter
+CompositeDB
+\family default
+ to assign the material properties:
+\end_layout
+
+\begin_layout LyX-Code
+# Change material type of lower crust to Drucker-Prager.
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.timedependent]
+\end_layout
+
+\begin_layout LyX-Code
+materials.lower_crust = pylith.materials.DruckerPrager3D
+\end_layout
+
+\begin_layout LyX-Code
+
+\end_layout
+
+\begin_layout LyX-Code
+# Provide a spatial database from which to obtain property values.
+\end_layout
+
+\begin_layout LyX-Code
+# In this case, we prefer to obtain the Drucker-Prager properties from one
+\end_layout
+
+\begin_layout LyX-Code
+# database and the elastic properties from another database, so we use
+\end_layout
+
+\begin_layout LyX-Code
+# a CompositeDB.
+ Each part of the CompositeDB is a SimpleDB.
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.timedependent.materials.lower_crust]
+\end_layout
+
+\begin_layout LyX-Code
+db_properties = spatialdata.spatialdb.CompositeDB
+\end_layout
+
+\begin_layout LyX-Code
+db_properties.db_A = spatialdata.spatialdb.SimpleDB
+\end_layout
+
+\begin_layout LyX-Code
+db_properties.db_B = spatialdata.spatialdb.SimpleDB
+\end_layout
+
+\begin_layout Standard
+As for the 
+\family typewriter
+step08
+\family default
+ example, we first define the properties that come from each spatial database
+ and then provide the database filename:
+\end_layout
+
+\begin_layout LyX-Code
+# Provide the values to be obtained from each database and the database
+\end_layout
+
+\begin_layout LyX-Code
+# name.
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.timedependent.materials.lower_crust.db_properties]
+\end_layout
+
+\begin_layout LyX-Code
+values_A = [density,vs,vp]   ; Elastic properties.
+\end_layout
+
+\begin_layout LyX-Code
+db_A.label = Elastic properties
+\end_layout
+
+\begin_layout LyX-Code
+db_A.iohandler.filename = spatialdb/mat_elastic.spatialdb
+\end_layout
+
+\begin_layout LyX-Code
+values_B = [friction-angle,cohesion,dilatation-angle]   ; Drucker-Prager
+ properties.
+\end_layout
+
+\begin_layout LyX-Code
+db_B.label = Drucker-Prager properties
+\end_layout
+
+\begin_layout LyX-Code
+db_B.iohandler.filename = spatialdb/mat_druckerprager.spatialdb
+\end_layout
+
+\begin_layout Standard
+We also request output of the properties and state variables that are unique
+ to the 
+\family typewriter
+DruckerPrager3D
+\family default
+ material:
+\end_layout
+
+\begin_layout LyX-Code
+# Since there are additional properties and state variables for the
+\end_layout
+
+\begin_layout LyX-Code
+# Drucker-Prager model, we explicitly request that they be output.
+\end_layout
+
+\begin_layout LyX-Code
+# Properties are named in cell_info_fields and state variables are named
+ in
+\end_layout
+
+\begin_layout LyX-Code
+# cell_data_fields.
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.timedependent.materials.lower_crust]
+\end_layout
+
+\begin_layout LyX-Code
+output.cell_info_fields = [density,mu,lambda,alpha_yield,beta,alpha_flow]
+\end_layout
+
+\begin_layout LyX-Code
+output.cell_data_fields = [total_strain,stress,plastic_strain]
+\end_layout
+
+\begin_layout Standard
+When we have run the simulation, the output HDF5 and Xdmf files will be
+ contained in 
+\family typewriter
+examples/3d/hex8/output
+\family default
+ (all with a prefix of 
+\family typewriter
+step09
+\family default
+).
+ Results using ParaView are shown in Figure 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "fig:step09-strain-displ-t150"
+
+\end_inset
+
+.
+\begin_inset Float figure
+wide false
+sideways false
+status open
+
+\begin_layout Plain Layout
+\align center
+\begin_inset Graphics
+	filename figs/step08-strain-displ-t150.jpg
+	lyxscale 50
+	width 10cm
+
+\end_inset
+
+
+\begin_inset Caption
+
+\begin_layout Plain Layout
+The XY-component of strain (color contours) and displacement field (vectors)
+ for example 
+\family typewriter
+step09
+\family default
+ at t = 150 years visualized using ParaView.
+ For this visualization, we loaded both the 
+\family typewriter
+step09-lower_crust.xmf
+\family default
+ and 
+\family typewriter
+step09-upper_crust.xmf
+\family default
+ files to contour the strain field, and superimposed on it the displacement
+ field vectors from 
+\family typewriter
+step09.xmf
+\family default
+.
+\begin_inset CommandInset label
+LatexCommand label
+name "fig:step09-strain-displ-t150"
+
+\end_inset
+
+.
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\end_body
+\end_document

Modified: short/3D/PyLith/branches/v1.7-trunk/doc/userguide/tutorials/3dhex8/surfload/surfload.lyx
===================================================================
--- short/3D/PyLith/branches/v1.7-trunk/doc/userguide/tutorials/3dhex8/surfload/surfload.lyx	2012-06-25 04:52:47 UTC (rev 20403)
+++ short/3D/PyLith/branches/v1.7-trunk/doc/userguide/tutorials/3dhex8/surfload/surfload.lyx	2012-06-25 16:38:44 UTC (rev 20404)
@@ -1,550 +1,562 @@
-#LyX 2.0 created this file. For more info see http://www.lyx.org/
-\lyxformat 413
-\begin_document
-\begin_header
-\textclass book
-\begin_preamble
-
-\end_preamble
-\use_default_options false
-\maintain_unincluded_children false
-\language english
-\language_package default
-\inputencoding latin1
-\fontencoding global
-\font_roman default
-\font_sans default
-\font_typewriter default
-\font_default_family default
-\use_non_tex_fonts false
-\font_sc false
-\font_osf false
-\font_sf_scale 100
-\font_tt_scale 100
-
-\graphics default
-\default_output_format default
-\output_sync 0
-\bibtex_command default
-\index_command default
-\paperfontsize default
-\spacing single
-\use_hyperref false
-\papersize default
-\use_geometry true
-\use_amsmath 0
-\use_esint 0
-\use_mhchem 1
-\use_mathdots 1
-\cite_engine basic
-\use_bibtopic false
-\use_indices false
-\paperorientation portrait
-\suppress_date false
-\use_refstyle 0
-\index Index
-\shortcut idx
-\color #008000
-\end_index
-\leftmargin 1in
-\topmargin 1in
-\rightmargin 1in
-\bottommargin 2in
-\secnumdepth 3
-\tocdepth 3
-\paragraph_separation indent
-\paragraph_indentation default
-\quotes_language english
-\papercolumns 1
-\papersides 1
-\paperpagestyle default
-\tracking_changes false
-\output_changes false
-\html_math_output 0
-\html_css_as_file 0
-\html_be_strict false
-\end_header
-
-\begin_body
-
-\begin_layout Subsection
-\begin_inset CommandInset label
-LatexCommand label
-name "sec:Tutorial-3d-hex8-surfload"
-
-\end_inset
-
-Surface Load Traction Examples
-\end_layout
-
-\begin_layout Standard
-PyLith features discussed in this tutorial:
-\end_layout
-
-\begin_layout Itemize
-Time-dependent Neumann (traction) boundary conditions
-\end_layout
-
-\begin_layout Itemize
-Dirichlet boundary conditions
-\end_layout
-
-\begin_layout Itemize
-Elastic material
-\end_layout
-
-\begin_layout Itemize
-Output of solution at user-defined locations
-\end_layout
-
-\begin_layout Subsubsection
-Overview
-\end_layout
-
-\begin_layout Standard
-This set of examples describes a set of problems for PyLith involving surface
- loading with a Neumann (traction) applied to the ground surface.
- The first example demonstrates the use of a surface load in a static problem,
- and the second example demonstates how to apply a cyclic load in a quasi-static
- problem.
- The second problem also includes output of the solution at user-defined
- locations.
- All of the examples are contained in the directory 
-\family typewriter
-examples/3d/hex8
-\family default
-, and the corresponding 
-\family typewriter
-.cfg
-\family default
- files are 
-\family typewriter
-step18.cfg
-\family default
- and 
-\family typewriter
-step19.cfg
-\family default
-.
- Each example may be run as follows:
-\end_layout
-
-\begin_layout LyX-Code
-pylith stepXX.cfg
-\end_layout
-
-\begin_layout Standard
-This will cause PyLith to read the default parameters in 
-\family typewriter
-pylithapp.cfg
-\family default
-, and then override or augment them with the additional parameters in the
- 
-\family typewriter
-stepXX.cfg
-\family default
- file.
- Each 
-\family typewriter
-.cfg
-\family default
- file is extensively documented, to provide detailed information on the
- various parameters.
-\end_layout
-
-\begin_layout Subsubsection
-Step18 - Static surface load
-\end_layout
-
-\begin_layout Standard
-The 
-\family typewriter
-step18.cfg
-\family default
- file defines a problem with a spatially varying axial surface load applied
- to the top surface with Dirichlet (roller) boundary conditions on the lateral
- and bottom surfaces.
- We first set the array of boundary conditions with one for each surface
- of the domain.
- As in the other examples, we also setup output for the ground surface.
-\end_layout
-
-\begin_layout Standard
-For the Dirichlet boundary conditions we fix the degree of freedom associated
- with motion normal to the boundary while leaving the other degrees of freedom
- free.
- We do not explicitly specify the use of a Dirichlet boundary condition
- because it is the default.
- Similarly, the ZeroDispDB is the default spatial database for the displacements
- in a Dirichlet boundary condition, so all we need to specify is the degree
- of freedom that is constrained, the name of the nodeset from CUBIT, and
- a label used in diagnostic output.
- For the Dirichlet boundary condition on the +x surface we have:
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.timedependent.bc.x_pos]
-\end_layout
-
-\begin_layout LyX-Code
-label = face_xpos
-\end_layout
-
-\begin_layout LyX-Code
-bc_dof = [0]
-\end_layout
-
-\begin_layout LyX-Code
-db_initial.label = Dirichlet BC on +x
-\end_layout
-
-\begin_layout Standard
-On the top surface we apply a Neumann boundary condition for the surface
- load, so we first set the boundary condition type and then specify the
- nodeset in CUBIT associated with this surface.
- For the static surface load, we use a spatial database for the initial
- value and linear interpolation.
- We integrate the surface tractions over the boundary, so we also specify
- the numerical integration scheme to use.
- Finally, we specify a vector for the up direction because the tractions
- are applied to a horizontal surface, resulting in ambiguous shear directions
- for our default orientation convention.
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.timedependent.bc]
-\end_layout
-
-\begin_layout LyX-Code
-z_pos = pylith.bc.Neumann
-\begin_inset Newline newline
-\end_inset
-
-
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.timedependent.bc.z_pos]
-\end_layout
-
-\begin_layout LyX-Code
-label = face_zpos
-\end_layout
-
-\begin_layout LyX-Code
-\begin_inset Newline newline
-\end_inset
-
-db_initial = spatialdata.spatialdb.SimpleDB
-\end_layout
-
-\begin_layout LyX-Code
-db_initial.label = Neumann BC on +z
-\end_layout
-
-\begin_layout LyX-Code
-db_initial.iohandler.filename = spatialdb/tractions_axial_pressure.spatialdb
-\end_layout
-
-\begin_layout LyX-Code
-# Use linear interpolation
-\end_layout
-
-\begin_layout LyX-Code
-db_initial.query_type = linear
-\begin_inset Newline newline
-\end_inset
-
-
-\end_layout
-
-\begin_layout LyX-Code
-# Diagnostic output
-\end_layout
-
-\begin_layout LyX-Code
-output.cell_info_fields = [initial-value]
-\end_layout
-
-\begin_layout LyX-Code
-output.writer.filename = output/step18-traction.vtk
-\end_layout
-
-\begin_layout LyX-Code
-output.cell_filter = pylith.meshio.CellFilterAvgSubMesh
-\begin_inset Newline newline
-\end_inset
-
-
-\end_layout
-
-\begin_layout LyX-Code
-# We must specify quadrature information for the cell faces.
-\end_layout
-
-\begin_layout LyX-Code
-quadrature.cell = pylith.feassemble.FIATLagrange
-\end_layout
-
-\begin_layout LyX-Code
-quadrature.cell.dimension = 2
-\end_layout
-
-\begin_layout LyX-Code
-quadrature.cell.quad_order = 2
-\begin_inset Newline newline
-\end_inset
-
-
-\end_layout
-
-\begin_layout LyX-Code
-# Because normal for +z surface is [0,0,1], the horizontal and
-\end_layout
-
-\begin_layout LyX-Code
-# vertical shear directions are ambiguous.
- We provide a "fake" up
-\end_layout
-
-\begin_layout LyX-Code
-# direction of [0,1,0] so that the horizontal shear direction ("up" x
-\end_layout
-
-\begin_layout LyX-Code
-# normal) is [1,0,0] and the vertical shear direction (normal x horiz
-\end_layout
-
-\begin_layout LyX-Code
-# shear dir) is [0,1,0].
-\end_layout
-
-\begin_layout LyX-Code
-up_dir = [0,1,0]
-\end_layout
-
-\begin_layout Standard
-When we have run the simulation, the output VTK files will be contained
- in 
-\family typewriter
-examples/3d/hex8/output
-\family default
- (all with a prefix of 
-\family typewriter
-step1
-\family default
-8).
- Results using ParaView are shown in Figure 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "fig:step18-displ"
-
-\end_inset
-
-.
-\end_layout
-
-\begin_layout Standard
-\begin_inset Float figure
-wide false
-sideways false
-status open
-
-\begin_layout Plain Layout
-\align center
-\begin_inset Graphics
-	filename figs/step18-displ.jpg
-	lyxscale 50
-	width 10cm
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Plain Layout
-\begin_inset Caption
-
-\begin_layout Plain Layout
-Displacement field for example step18 visualized using ParaView.
- The vectors show the displacement field while the colors in the wireframe
- correspond to the z-component of the displacement field.
-\begin_inset CommandInset label
-LatexCommand label
-name "fig:step18-displ"
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Subsubsection
-Step19 - Time-dependent surface load
-\end_layout
-
-\begin_layout Standard
-The 
-\family typewriter
-step19.cfg
-\family default
- file defines a problem that is identical to example step18, except that
- we vary the amplitude of the surface load as a function of time.
- We use a temporal database (analogous to our spatial databases for specifying
- spatial variations) to prescribe a piecewise linear variation of the amplitude
- with time as given in the file 
-\family typewriter
-spatialdb/loadcycle.timedb
-\family default
-.
- The amplitude begins at zero, progresses to 1.0, then 1.5, before decreasing
- in a symmetric fashion.
- The temporal database can use variable time steps to prescribe arbitrary
- time histories.
- 
-\end_layout
-
-\begin_layout Standard
-Rather than specify a spatial database for the initial value of the Neumann
- boundary condition corresponding to the surface load, we specify a spatial
- database for the change in value and the temporal database:
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.timedependent.bc.z_pos]
-\end_layout
-
-\begin_layout LyX-Code
-label = face_zpos
-\end_layout
-
-\begin_layout LyX-Code
-db_change = spatialdata.spatialdb.SimpleDB
-\end_layout
-
-\begin_layout LyX-Code
-db_change.label = Amplitude of Neumann BC on +z
-\end_layout
-
-\begin_layout LyX-Code
-db_change.iohandler.filename = spatialdb/tractions_axial_pressure.spatialdb
-\end_layout
-
-\begin_layout LyX-Code
-# Use linear interpolation
-\end_layout
-
-\begin_layout LyX-Code
-db_change.query_type = linear
-\begin_inset Newline newline
-\end_inset
-
-
-\end_layout
-
-\begin_layout LyX-Code
-th_change = spatialdata.spatialdb.TimeHistory
-\end_layout
-
-\begin_layout LyX-Code
-th_change.label = Time history for Neumann BC on +z
-\end_layout
-
-\begin_layout LyX-Code
-th_change.filename = spatialdb/loadcycle.timedb
-\end_layout
-
-\begin_layout Standard
-When we have run the simulation, the output VTK files will be contained
- in 
-\family typewriter
-examples/3d/hex8/output
-\family default
- (all with a prefix of 
-\family typewriter
-step1
-\family default
-9).
- Results using ParaView are shown in Figure 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "fig:step19-stress-t200"
-
-\end_inset
-
-.
- We also output the solution at user-defined locations, which are given
- in the file 
-\family typewriter
-output_points.txt.
- See Section 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "sec:output:points"
-
-\end_inset
-
- for a discussion of the output parameters.
- This type of output is designed for comparison against observations and
- inversions and output via HDF5 files (see Section ??).
-\end_layout
-
-\begin_layout Standard
-\begin_inset Float figure
-wide false
-sideways false
-status open
-
-\begin_layout Plain Layout
-\align center
-\begin_inset Graphics
-	filename figs/step19-stress_t200.jpg
-	lyxscale 50
-	width 10cm
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Plain Layout
-\begin_inset Caption
-
-\begin_layout Plain Layout
-Stress field (zz-component) for example step19 at t = 200 years visualized
- using ParaView.
- The stresses appear as 4 layers since we have used 
-\family typewriter
-CellFilterAvgMesh
-\family default
- for material output.
-\begin_inset CommandInset label
-LatexCommand label
-name "fig:step19-stress-t200"
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_body
-\end_document
+#LyX 2.0 created this file. For more info see http://www.lyx.org/
+\lyxformat 413
+\begin_document
+\begin_header
+\textclass book
+\begin_preamble
+
+\end_preamble
+\use_default_options false
+\maintain_unincluded_children false
+\language english
+\language_package default
+\inputencoding latin1
+\fontencoding global
+\font_roman default
+\font_sans default
+\font_typewriter default
+\font_default_family default
+\use_non_tex_fonts false
+\font_sc false
+\font_osf false
+\font_sf_scale 100
+\font_tt_scale 100
+
+\graphics default
+\default_output_format default
+\output_sync 0
+\bibtex_command default
+\index_command default
+\paperfontsize default
+\spacing single
+\use_hyperref false
+\papersize default
+\use_geometry true
+\use_amsmath 0
+\use_esint 0
+\use_mhchem 1
+\use_mathdots 1
+\cite_engine basic
+\use_bibtopic false
+\use_indices false
+\paperorientation portrait
+\suppress_date false
+\use_refstyle 0
+\index Index
+\shortcut idx
+\color #008000
+\end_index
+\leftmargin 1in
+\topmargin 1in
+\rightmargin 1in
+\bottommargin 2in
+\secnumdepth 3
+\tocdepth 3
+\paragraph_separation indent
+\paragraph_indentation default
+\quotes_language english
+\papercolumns 1
+\papersides 1
+\paperpagestyle default
+\tracking_changes false
+\output_changes false
+\html_math_output 0
+\html_css_as_file 0
+\html_be_strict false
+\end_header
+
+\begin_body
+
+\begin_layout Subsection
+\begin_inset CommandInset label
+LatexCommand label
+name "sec:Tutorial-3d-hex8-surfload"
+
+\end_inset
+
+Surface Load Traction Examples
+\end_layout
+
+\begin_layout Standard
+PyLith features discussed in this tutorial:
+\end_layout
+
+\begin_layout Itemize
+Time-dependent Neumann (traction) boundary conditions
+\end_layout
+
+\begin_layout Itemize
+Dirichlet boundary conditions
+\end_layout
+
+\begin_layout Itemize
+Elastic material
+\end_layout
+
+\begin_layout Itemize
+Output of solution at user-defined locations
+\end_layout
+
+\begin_layout Subsubsection
+Overview
+\end_layout
+
+\begin_layout Standard
+This set of examples describes a set of problems for PyLith involving surface
+ loading with a Neumann (traction) applied to the ground surface.
+ The first example demonstrates the use of a surface load in a static problem,
+ and the second example demonstates how to apply a cyclic load in a quasi-static
+ problem.
+ The second problem also includes output of the solution at user-defined
+ locations.
+ All of the examples are contained in the directory 
+\family typewriter
+examples/3d/hex8
+\family default
+, and the corresponding 
+\family typewriter
+.cfg
+\family default
+ files are 
+\family typewriter
+step18.cfg
+\family default
+ and 
+\family typewriter
+step19.cfg
+\family default
+.
+ Each example may be run as follows:
+\end_layout
+
+\begin_layout LyX-Code
+pylith stepXX.cfg
+\end_layout
+
+\begin_layout Standard
+This will cause PyLith to read the default parameters in 
+\family typewriter
+pylithapp.cfg
+\family default
+, and then override or augment them with the additional parameters in the
+ 
+\family typewriter
+stepXX.cfg
+\family default
+ file.
+ Each 
+\family typewriter
+.cfg
+\family default
+ file is extensively documented, to provide detailed information on the
+ various parameters.
+\end_layout
+
+\begin_layout Subsubsection
+Step18 - Static Surface Load
+\end_layout
+
+\begin_layout Standard
+The 
+\family typewriter
+step18.cfg
+\family default
+ file defines a problem with a spatially varying axial surface load applied
+ to the top surface with Dirichlet (roller) boundary conditions on the lateral
+ and bottom surfaces.
+ We first set the array of boundary conditions with one for each surface
+ of the domain.
+ As in the other examples, we also setup output for the ground surface.
+\end_layout
+
+\begin_layout Standard
+For the Dirichlet boundary conditions we fix the degree of freedom associated
+ with motion normal to the boundary while leaving the other degrees of freedom
+ free.
+ We do not explicitly specify the use of a Dirichlet boundary condition
+ because it is the default.
+ Similarly, the ZeroDispDB is the default spatial database for the displacements
+ in a Dirichlet boundary condition, so all we need to specify is the degree
+ of freedom that is constrained, the name of the nodeset from CUBIT, and
+ a label used in diagnostic output.
+ For the Dirichlet boundary condition on the +x surface we have:
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.timedependent.bc.x_pos]
+\end_layout
+
+\begin_layout LyX-Code
+label = face_xpos
+\end_layout
+
+\begin_layout LyX-Code
+bc_dof = [0]
+\end_layout
+
+\begin_layout LyX-Code
+db_initial.label = Dirichlet BC on +x
+\end_layout
+
+\begin_layout Standard
+On the top surface we apply a Neumann boundary condition for the surface
+ load, so we first set the boundary condition type and then specify the
+ nodeset in CUBIT associated with this surface.
+ For the static surface load, we use a spatial database for the initial
+ value and linear interpolation.
+ We integrate the surface tractions over the boundary, so we also specify
+ the numerical integration scheme to use.
+ Finally, we specify a vector for the up direction because the tractions
+ are applied to a horizontal surface, resulting in ambiguous shear directions
+ for our default orientation convention.
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.timedependent.bc]
+\end_layout
+
+\begin_layout LyX-Code
+z_pos = pylith.bc.Neumann
+\begin_inset Newline newline
+\end_inset
+
+
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.timedependent.bc.z_pos]
+\end_layout
+
+\begin_layout LyX-Code
+label = face_zpos
+\end_layout
+
+\begin_layout LyX-Code
+\begin_inset Newline newline
+\end_inset
+
+db_initial = spatialdata.spatialdb.SimpleDB
+\end_layout
+
+\begin_layout LyX-Code
+db_initial.label = Neumann BC on +z
+\end_layout
+
+\begin_layout LyX-Code
+db_initial.iohandler.filename = spatialdb/tractions_axial_pressure.spatialdb
+\end_layout
+
+\begin_layout LyX-Code
+# Use linear interpolation
+\end_layout
+
+\begin_layout LyX-Code
+db_initial.query_type = linear
+\begin_inset Newline newline
+\end_inset
+
+
+\end_layout
+
+\begin_layout LyX-Code
+# Diagnostic output
+\end_layout
+
+\begin_layout LyX-Code
+output.cell_info_fields = [initial-value]
+\end_layout
+
+\begin_layout LyX-Code
+output.writer.filename = output/step18-traction.vtk
+\end_layout
+
+\begin_layout LyX-Code
+output.cell_filter = pylith.meshio.CellFilterAvgSubMesh
+\begin_inset Newline newline
+\end_inset
+
+
+\end_layout
+
+\begin_layout LyX-Code
+# We must specify quadrature information for the cell faces.
+\end_layout
+
+\begin_layout LyX-Code
+quadrature.cell = pylith.feassemble.FIATLagrange
+\end_layout
+
+\begin_layout LyX-Code
+quadrature.cell.dimension = 2
+\end_layout
+
+\begin_layout LyX-Code
+quadrature.cell.quad_order = 2
+\begin_inset Newline newline
+\end_inset
+
+
+\end_layout
+
+\begin_layout LyX-Code
+# Because normal for +z surface is [0,0,1], the horizontal and
+\end_layout
+
+\begin_layout LyX-Code
+# vertical shear directions are ambiguous.
+ We provide a "fake" up
+\end_layout
+
+\begin_layout LyX-Code
+# direction of [0,1,0] so that the horizontal shear direction ("up" x
+\end_layout
+
+\begin_layout LyX-Code
+# normal) is [1,0,0] and the vertical shear direction (normal x horiz
+\end_layout
+
+\begin_layout LyX-Code
+# shear dir) is [0,1,0].
+\end_layout
+
+\begin_layout LyX-Code
+up_dir = [0,1,0]
+\end_layout
+
+\begin_layout Standard
+When we have run the simulation, the output VTK files will be contained
+ in 
+\family typewriter
+examples/3d/hex8/output
+\family default
+ (all with a prefix of 
+\family typewriter
+step1
+\family default
+8).
+ Results using ParaView are shown in Figure 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "fig:step18-displ"
+
+\end_inset
+
+.
+\end_layout
+
+\begin_layout Standard
+\begin_inset Float figure
+wide false
+sideways false
+status open
+
+\begin_layout Plain Layout
+\align center
+\begin_inset Graphics
+	filename figs/step18-displ.jpg
+	lyxscale 50
+	width 10cm
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Plain Layout
+\begin_inset Caption
+
+\begin_layout Plain Layout
+Displacement field for example step18 visualized using ParaView.
+ The vectors show the displacement field while the colors in the wireframe
+ correspond to the z-component of the displacement field.
+\begin_inset CommandInset label
+LatexCommand label
+name "fig:step18-displ"
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Subsubsection
+Step19 - Time-Dependent Surface Load
+\end_layout
+
+\begin_layout Standard
+The 
+\family typewriter
+step19.cfg
+\family default
+ file defines a problem that is identical to example step18, except that
+ we vary the amplitude of the surface load as a function of time.
+ We use a temporal database (analogous to our spatial databases for specifying
+ spatial variations) to prescribe a piecewise linear variation of the amplitude
+ with time as given in the file 
+\family typewriter
+spatialdb/loadcycle.timedb
+\family default
+.
+ The amplitude begins at zero, progresses to 1.0, then 1.5, before decreasing
+ in a symmetric fashion.
+ The temporal database can use variable time steps to prescribe arbitrary
+ time histories.
+ 
+\end_layout
+
+\begin_layout Standard
+Rather than specify a spatial database for the initial value of the Neumann
+ boundary condition corresponding to the surface load, we specify a spatial
+ database for the change in value and the temporal database:
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.timedependent.bc.z_pos]
+\end_layout
+
+\begin_layout LyX-Code
+label = face_zpos
+\end_layout
+
+\begin_layout LyX-Code
+db_change = spatialdata.spatialdb.SimpleDB
+\end_layout
+
+\begin_layout LyX-Code
+db_change.label = Amplitude of Neumann BC on +z
+\end_layout
+
+\begin_layout LyX-Code
+db_change.iohandler.filename = spatialdb/tractions_axial_pressure.spatialdb
+\end_layout
+
+\begin_layout LyX-Code
+# Use linear interpolation
+\end_layout
+
+\begin_layout LyX-Code
+db_change.query_type = linear
+\begin_inset Newline newline
+\end_inset
+
+
+\end_layout
+
+\begin_layout LyX-Code
+th_change = spatialdata.spatialdb.TimeHistory
+\end_layout
+
+\begin_layout LyX-Code
+th_change.label = Time history for Neumann BC on +z
+\end_layout
+
+\begin_layout LyX-Code
+th_change.filename = spatialdb/loadcycle.timedb
+\end_layout
+
+\begin_layout Standard
+When we have run the simulation, the output VTK files will be contained
+ in 
+\family typewriter
+examples/3d/hex8/output
+\family default
+ (all with a prefix of 
+\family typewriter
+step1
+\family default
+9).
+ Results using ParaView are shown in Figure 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "fig:step19-stress-t200"
+
+\end_inset
+
+.
+ We also output the solution at user-defined locations, which are given
+ in the file 
+\family typewriter
+output_points.txt.
+
+\family default
+ See Section 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "sec:output:points"
+
+\end_inset
+
+ for a discussion of the output parameters.
+ This type of output is designed for comparison against observations and
+ inversions and output via HDF5 files (see Section 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "sub:HDF5/Xdmf-Output"
+
+\end_inset
+
+).
+\end_layout
+
+\begin_layout Standard
+\begin_inset Float figure
+wide false
+sideways false
+status open
+
+\begin_layout Plain Layout
+\align center
+\begin_inset Graphics
+	filename figs/step19-stress_t200.jpg
+	lyxscale 50
+	width 10cm
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Plain Layout
+\begin_inset Caption
+
+\begin_layout Plain Layout
+Stress field (zz-component) for example 
+\family typewriter
+step19
+\family default
+ at t = 200 years visualized using ParaView.
+ The stresses appear as 4 layers since we have used 
+\family typewriter
+CellFilterAvgMesh
+\family default
+ for material output.
+\begin_inset CommandInset label
+LatexCommand label
+name "fig:step19-stress-t200"
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\end_body
+\end_document

Modified: short/3D/PyLith/branches/v1.7-trunk/doc/userguide/tutorials/3dtet4/3dtet4.lyx
===================================================================
--- short/3D/PyLith/branches/v1.7-trunk/doc/userguide/tutorials/3dtet4/3dtet4.lyx	2012-06-25 04:52:47 UTC (rev 20403)
+++ short/3D/PyLith/branches/v1.7-trunk/doc/userguide/tutorials/3dtet4/3dtet4.lyx	2012-06-25 16:38:44 UTC (rev 20404)
@@ -1,1954 +1,1954 @@
-#LyX 2.0 created this file. For more info see http://www.lyx.org/
-\lyxformat 413
-\begin_document
-\begin_header
-\textclass book
-\begin_preamble
-
-\end_preamble
-\use_default_options false
-\maintain_unincluded_children false
-\language english
-\language_package default
-\inputencoding latin1
-\fontencoding global
-\font_roman default
-\font_sans default
-\font_typewriter default
-\font_default_family default
-\use_non_tex_fonts false
-\font_sc false
-\font_osf false
-\font_sf_scale 100
-\font_tt_scale 100
-
-\graphics default
-\default_output_format default
-\output_sync 0
-\bibtex_command default
-\index_command default
-\paperfontsize default
-\spacing single
-\use_hyperref false
-\papersize default
-\use_geometry true
-\use_amsmath 0
-\use_esint 0
-\use_mhchem 1
-\use_mathdots 1
-\cite_engine basic
-\use_bibtopic false
-\use_indices false
-\paperorientation portrait
-\suppress_date false
-\use_refstyle 0
-\index Index
-\shortcut idx
-\color #008000
-\end_index
-\leftmargin 1in
-\topmargin 1in
-\rightmargin 1in
-\bottommargin 2in
-\secnumdepth 3
-\tocdepth 3
-\paragraph_separation indent
-\paragraph_indentation default
-\quotes_language english
-\papercolumns 1
-\papersides 1
-\paperpagestyle default
-\tracking_changes false
-\output_changes false
-\html_math_output 0
-\html_css_as_file 0
-\html_be_strict false
-\end_header
-
-\begin_body
-
-\begin_layout Section
-\begin_inset CommandInset label
-LatexCommand label
-name "sec:Tutorial-3d-tet4"
-
-\end_inset
-
-Tutorial Using Tetrahedral Mesh Created by LaGriT
-\end_layout
-
-\begin_layout Standard
-PyLith features discussed in this tutorial:
-\end_layout
-
-\begin_layout Itemize
-Quasi-static solution
-\end_layout
-
-\begin_layout Itemize
-LaGriT mesh format
-\end_layout
-
-\begin_layout Itemize
-Dirichlet boundary conditions
-\end_layout
-
-\begin_layout Itemize
-Kinematic fault interface conditions
-\end_layout
-
-\begin_layout Itemize
-Linearly elastic isotropic material
-\end_layout
-
-\begin_layout Itemize
-Maxwell linear viscoelastic material
-\end_layout
-
-\begin_layout Itemize
-Specifying more than one material
-\end_layout
-
-\begin_layout Itemize
-VTK output
-\end_layout
-
-\begin_layout Itemize
-Linear tetrahedral cells
-\end_layout
-
-\begin_layout Itemize
-SimpleDB spatial database
-\end_layout
-
-\begin_layout Itemize
-ZeroDispDB spatial database
-\end_layout
-
-\begin_layout Itemize
-Custom algebraic multigrid preconditioner with split fields
-\end_layout
-
-\begin_layout Itemize
-Global uniform mesh refinement
-\end_layout
-
-\begin_layout Standard
-All of the files necessary to run the examples are contained in the directory
- 
-\family typewriter
-examples/3d/tet4.
-\end_layout
-
-\begin_layout Subsection
-Overview
-\end_layout
-
-\begin_layout Standard
-This tutorial is a simple 3D example of a quasi-static finite element problem.
- It is a mesh composed of 852 linear tetrahedra subject to displacement
- boundary conditions.
- This example demonstrates the usage of the LaGriT mesh generation package
- 
-\begin_inset Flex URL
-status collapsed
-
-\begin_layout Plain Layout
-
-lagrit.lanl.gov
-\end_layout
-
-\end_inset
-
- to create a mesh, as well as describing how to use a LaGriT-generated mesh
- in PyLith.
- In this tutorial, we will walk through the steps necessary to construct,
- run, and visualize the results for two problems that use the same mesh.
- For each of these problems we also consider a simulation using a custom
- algebraic multigrid preconditioner with a globally uniformly refined mesh
- that reduces the node spacing by a factor of two.
- In addition to this manual, each of the files for the example problems
- includes extensive comments.
-\end_layout
-
-\begin_layout Subsection
-Mesh Generation and Description
-\end_layout
-
-\begin_layout Standard
-The mesh for these examples is a simple rectangular prism (Figure 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "fig:3dtet4-mesh"
-
-\end_inset
-
-).
- This mesh would be quite difficult to generate by hand, so we use the LaGriT
- mesh generation package.
- For this example, we provide a documented command file in 
-\family typewriter
-examples/3d/tet4.
-
-\family default
- Examination of this command file should provide some insight into how to
- use LaGriT with PyLith.
- For more detailed information refer to the LaGriT web site 
-\begin_inset Flex URL
-status collapsed
-
-\begin_layout Plain Layout
-
-lagrit.lanl.gov
-\end_layout
-
-\end_inset
-
-.
- If you have LaGriT installed on your machine, you can use the command file
- to create your own mesh.
- Otherwise, you can use the mesh that has already been created.
-\end_layout
-
-\begin_layout Standard
-There are two ways to use the command file.
- The simplest method is to go to the
-\family sans
- 
-\family default
-examples directory (
-\family typewriter
-examples/3d/tet4
-\family default
-), start LaGriT, and then type:
-\end_layout
-
-\begin_layout LyX-Code
-input mesh_tet4_1000m.lagrit
-\end_layout
-
-\begin_layout Standard
-This will run the commands in that file, which will produce the necessary
- files to run the example.
- This method will create the mesh, but you will gain very little insight
- into what is being done.
- A more informative approach is to input each command directly.
- That way, you will see what each command does.
- You can simply copy and paste the commands from 
-\family typewriter
-mesh_tet4_1000m.lagrit
-\family default
-.
- For example, the first six commands, which define the block shape, are
-\end_layout
-
-\begin_layout LyX-Code
-define / domain_xm / -3.0e+3
-\end_layout
-
-\begin_layout LyX-Code
-define / domain_xp /  3.0e+3
-\end_layout
-
-\begin_layout LyX-Code
-define / domain_ym / -3.0e+3
-\end_layout
-
-\begin_layout LyX-Code
-define / domain_yp /  3.0e+3
-\end_layout
-
-\begin_layout LyX-Code
-define / domain_zm / -4.0e+3
-\end_layout
-
-\begin_layout LyX-Code
-define / domain_zp /  0.0e+3 
-\end_layout
-
-\begin_layout Standard
-Continuing through the remainder of the commands in 
-\family typewriter
-mesh_tet4_1000m.lagrit
-\family default
-, you will eventually end up with the files 
-\family typewriter
-tet4_1000m_binary.gmv
-\family default
-, 
-\family typewriter
-tet4_1000m_ascii.gmv
-\family default
-, 
-\family typewriter
-tet4_1000m_ascii.pset
-\family default
-, and 
-\family typewriter
-tet4_1000m_binary.pset
-\family default
-.
- The ASCII files are not actually needed, but we create them so users can
- see what is contained in the files.
- These files may also be used instead of the binary versions, if desired.
- The 
-\family typewriter
-.gmv
-\family default
- files define the mesh information, and they may be read directly by the
- GMV 
-\begin_inset Flex URL
-status collapsed
-
-\begin_layout Plain Layout
-
-laws.lanl.gov/XCM/gmv/GMVHome.html
-\end_layout
-
-\end_inset
-
- mesh visualization package.
- The 
-\family typewriter
-.pset
-\family default
- files specify the vertices corresponding to each set of vertices on a surface
- used in the problem, including the fault as well as external boundaries
- to which boundary conditions are applied.
-\end_layout
-
-\begin_layout Standard
-\noindent
-\align center
-\begin_inset Float figure
-wide false
-sideways false
-status open
-
-\begin_layout Plain Layout
-\align center
-\begin_inset Graphics
-	filename figs/tet4-mesh.jpg
-	lyxscale 50
-	scale 45
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Plain Layout
-\begin_inset Caption
-
-\begin_layout Plain Layout
-Mesh composed of linear tetrahedral cells generated by LaGriT used for the
- example problems.
- The different colors represent the different materials.
-\begin_inset CommandInset label
-LatexCommand label
-name "fig:3dtet4-mesh"
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Subsection
-Additional Common Information
-\end_layout
-
-\begin_layout Standard
-In addition to the mesh, the example problems share additional information.
- In such cases it is generally useful to create a file named 
-\family typewriter
-pylithapp.cfg
-\family default
- in the run directory, since this file is read automatically every time
- PyLith is run.
- Settings specific to a particular problem may be placed in other 
-\family typewriter
-.cfg
-\family default
- files, as described later, and then those files are placed on the command
- line.
-  The settings contained in 
-\family typewriter
-pylithapp.cfg
-\family default
- for this problem consist of:
-\end_layout
-
-\begin_layout Description
-pylithapp.journal.info Settings that control the verbosity of the output for
- the different components.
-\end_layout
-
-\begin_layout Description
-pylithapp.mesh_generator Settings that control mesh importing, such as the
- importer type, the filenames, and the spatial dimension of the mesh.
-\end_layout
-
-\begin_layout Description
-pylithapp.timedependent Settings that control the problem, such as the total
- time, time step size, and number of entries in the material array.
-\end_layout
-
-\begin_layout Description
-pylithapp.timedependent.materials Settings that control the material type,
- specify which material IDs are to be associated with a particular material
- type, and give the name of the spatial database containing material parameters
- for the mesh.
- The quadrature information is also given.
-\end_layout
-
-\begin_layout Description
-pylithapp.petsc PETSc settings to use for the problem, such as the preconditioner
- type.
-\end_layout
-
-\begin_layout Standard
-Since these examples use a mesh from LaGriT, we set the importer to 
-\family typewriter
-MeshIO
-\family default
-Lagrit:
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.mesh_generator]
-\end_layout
-
-\begin_layout LyX-Code
-reader = pylith.meshio.MeshIOLagrit
-\end_layout
-
-\begin_layout LyX-Code
- 
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.mesh_generator.reader]
-\end_layout
-
-\begin_layout LyX-Code
-filename_gmv = mesh/tet4_1000m_binary.gmv
-\end_layout
-
-\begin_layout LyX-Code
-filename_pset = mesh/tet4_1000m_binary.pset
-\end_layout
-
-\begin_layout LyX-Code
-flip_endian = True
-\end_layout
-
-\begin_layout LyX-Code
-# record_header_32bit = False
-\end_layout
-
-\begin_layout Standard
-Notice that there are a couple of settings pertinent to binary files.
- The first flag (
-\family typewriter
-flip_endian
-\family default
-) is used if the binary files were produced on a machine with a different
- endianness than the machine on which they are being read.
- If you get an error when attempting to run an example, you may need to
- change the setting of this flag.
- The second flag (
-\family typewriter
-record_header_32bit
-\family default
-) may need to be set to 
-\family typewriter
-False
-\family default
- if the version of LaGriT being used has 64-bit Fortran record headers.
- 
-\end_layout
-
-\begin_layout Standard
-This example differs from previous examples, because we specify two material
- groups:
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.timedependent]
-\end_layout
-
-\begin_layout LyX-Code
-materials = [elastic,viscoelastic]
-\end_layout
-
-\begin_layout LyX-Code
- 
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.timedependent.materials.elastic]
-\end_layout
-
-\begin_layout LyX-Code
-label = Elastic material
-\end_layout
-
-\begin_layout LyX-Code
-id = 1
-\end_layout
-
-\begin_layout LyX-Code
-db.iohandler.filename = spatialdb/mat_elastic.spatialdb
-\end_layout
-
-\begin_layout LyX-Code
-quadrature.cell = pylith.feassemble.FIATSimplex
-\end_layout
-
-\begin_layout LyX-Code
-quadrature.cell.shape = tetrahedron
-\end_layout
-
-\begin_layout LyX-Code
- 
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.timedependent.materials.viscoelastic]
-\end_layout
-
-\begin_layout LyX-Code
-label = Viscoelastic material
-\end_layout
-
-\begin_layout LyX-Code
-id = 2
-\end_layout
-
-\begin_layout LyX-Code
-db.iohandler.filename = spatialdb/mat_viscoelastic.spatialdb
-\end_layout
-
-\begin_layout LyX-Code
-quadrature.cell = pylith.feassemble.FIATSimplex
-\end_layout
-
-\begin_layout LyX-Code
-quadrature.cell.shape = tetrahedron
-\end_layout
-
-\begin_layout LyX-Code
-
-\end_layout
-
-\begin_layout LyX-Code
-
-\end_layout
-
-\begin_layout Standard
-The two materials correspond to the two different colors in Figure 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "fig:3dtet4-mesh"
-
-\end_inset
-
-.
- Each material uses a different spatial database because the physical parameters
- are different.
- In generating the mesh within LaGriT, the mesh contains four materials
- as a result of how LaGriT handles materials and interior interfaces.
- Near the end of the LaGriT command file, we merge the materials on each
- side of the fault into a single material to simplify the input and output
- from PyLith.
- For this example, values describing three-dimensional elastic material
- properties are given by the single point in the spatial databases, resulting
- in uniform physical properties within each material.
-\end_layout
-
-\begin_layout Subsection
-Shear Displacement Example
-\end_layout
-
-\begin_layout Standard
-The first example problem is shearing of the mesh along the y-direction,
- with displacement boundary conditions applied on the planes corresponding
- to the minimum and maximum x-values.
- Parameter settings that override or augment those in 
-\family typewriter
-pylithapp.cfg
-\family default
- are contained in the file 
-\family typewriter
-step01.cfg
-\family default
-.
- These settings are:
-\end_layout
-
-\begin_layout Description
-pylithapp.timedependent Specifies an implicit formulation for the problem
- and specifies the array of boundary conditions.
-\end_layout
-
-\begin_layout Description
-pylithapp.timedependent.implicit Specifies an array of two output managers,
- one for the full domain, and another for a subdomain corresponding to the
- ground surface.
-\end_layout
-
-\begin_layout Description
-pylithapp.timedependent.bc.x_pos Specifies the boundary conditions for the
- right side of the mesh, defining which degrees of freedom are being constrained
- (
-\family typewriter
-x
-\family default
- and 
-\family typewriter
-y
-\family default
-), providing the label (defined in 
-\family typewriter
-tet4_1000m_binary.pset
-\family default
-) defining the points desired, assigning a label to the boundary condition
- set, and giving the name of the spatial database defining the boundary
- conditions (
-\family typewriter
-fixeddisp_shear.spatialdb
-\family default
-).
-\end_layout
-
-\begin_layout Description
-pylithapp.timedependent.bc.x_neg Specifies the boundary conditions for the
- left side of the mesh, defining which degrees of freedom are being constrained
- (
-\family typewriter
-x
-\family default
- and 
-\family typewriter
-y
-\family default
-), providing the label (defined in 
-\family typewriter
-tet4_1000m_binary.
-\family default
-pset) defining the points desired, assigning a label to the boundary condition
- set, and giving the name of the spatial database defining the boundary
- conditions (
-\family typewriter
-fixeddisp_shear.spatialdb
-\family default
-).
-\end_layout
-
-\begin_layout Description
-pylithapp.timedependent.bc.z_neg Specifies the boundary conditions for the
- bottom of the mesh, defining which degrees of freedom are being constrained
- (
-\family typewriter
-x
-\family default
- and 
-\family typewriter
-y
-\family default
-), providing the label (defined in 
-\family typewriter
-tet4_1000m_binary.
-\family default
-pset) defining the points desired, assigning a label to the boundary condition
- set, and giving the name of the spatial database defining the boundary
- conditions (
-\family typewriter
-fixeddisp_shear.spatialdb
-\family default
-).
-\end_layout
-
-\begin_layout Description
-pylithapp.problem.formulation.output.domain.writer Gives the base filename for
- VTK output over the entire domain (
-\family typewriter
-shearxy.vtk
-\family default
-).
-\end_layout
-
-\begin_layout Description
-pylithapp.problem.formulation.output.subdomain Gives the label of the nodeset
- defining the subdomain and gives the base filename for VTK output over
- the subdomain corresponding to the ground surface (
-\family typewriter
-step01-groundsurf.vtk
-\family default
-).
-\end_layout
-
-\begin_layout Description
-pylithapp.timedependent.materials.elastic.output Gives the base filename for
- state variable output files for the 
-\family typewriter
-elastic
-\family default
- material set (
-\family typewriter
-step01-elastic.vtk
-\family default
-), and causes state variables to be averaged over all quadrature points
- in each cell.
-\end_layout
-
-\begin_layout Description
-pylithapp.timedependent.materials.viscoelastic.output Gives the base filename
- for state variable output files for the 
-\family typewriter
-viscoelastic
-\family default
- material set (
-\family typewriter
-step01-viscoelastic.vtk
-\family default
-), and causes state variables to be averaged over all quadrature points
- in each cell.
-\end_layout
-
-\begin_layout Standard
-The values for the Dirichlet boundary conditions are described in the file
- 
-\family typewriter
-fixeddisp_shear.spatialdb
-\family default
-, as specified in 
-\family typewriter
-step01.cfg
-\family default
-.
- The format of all spatial database files is similar.
- Because data are being specified using two control points (rather than
- being uniform over the mesh, for example), the data dimension is one.
-\end_layout
-
-\begin_layout Standard
-The files containing common information (
-\family typewriter
-\size small
-tet4_1000m_binary.gmv
-\family default
-, 
-\family typewriter
-tet4_1000m_binary.pset
-\family default
-, 
-\family typewriter
-pylithapp.cfg
-\family default
-, 
-\family typewriter
-mat_elastic.spatialdb
-\family default
-\size default
-, and 
-\family typewriter
-mat_viscoelastic.spatialdb
-\family default
-) along with the problem-specific files (
-\family typewriter
-\size small
-step01.cfg
-\family default
- and 
-\family typewriter
-fixeddisp_shear.spatialdb
-\family default
-\size default
-) provide a complete description of the problem, and we can then run this
- example by typing
-\end_layout
-
-\begin_layout LyX-Code
-pylith step01.cfg
-\end_layout
-
-\begin_layout Standard
-Once the problem has run, six files will be produced.
- The first file is named 
-\family typewriter
-step01_t0000000.vtk
-\family default
-.
- The 
-\family typewriter
-t0000000
-\family default
- indicates that the output is for the first (and only) time step, corresponding
- to an elastic solution.
- This file contains mesh information as well as displacement values at the
- mesh vertices.
- The second file is named 
-\family typewriter
-step01-statevars-elastic_t0000000.vtk
-\family default
-.
- This file contains the state variables for each cell in the material group
- 
-\family typewriter
-elastic
-\family default
-.
- The default fields are the total strain and stress fields.
- These values are computed at each quadrature point in the cell.
- We have requested that the values be averaged over all quadrature points
- for each cell; however, since we only have a single quadrature point for
- each linear tetrahedron, this will have no effect.
- The third file (
-\family typewriter
-step01-statevars-viscoelastic_info.vtk
-\family default
-) gives the material properties used for the 
-\family typewriter
-viscoelastic
-\family default
- material set.
- Since we have not specified which properties to write, the default properties
- (
-\family typewriter
-mu
-\family default
-, 
-\family typewriter
-lambda
-\family default
-, 
-\family typewriter
-density
-\family default
-) are written.
- There are two additional files containing the state variables for each
- of the material sets.
- The final file (
-\family typewriter
-step01-groundsurf_t0000000.vtk
-\family default
-) is analogous to 
-\family typewriter
-step01_t0000000.vtk
-\family default
-, but in this case the results are only given for a subset of the mesh correspon
-ding to the ground surface.
- Also, the cells in this file are one dimension lower than the cells described
- in 
-\family typewriter
-step01_t0000000.vtk
-\family default
-, so they are triangles rather than tetrahedra.
- All of the 
-\family typewriter
-.vtk
-\family default
- files may be used with a number of visualization packages.
- If the problem ran correctly, you should be able to generate a figure such
- as Figure 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "fig:3dtet4-shear"
-
-\end_inset
-
-, which was generated using ParaView.
-\end_layout
-
-\begin_layout Standard
-\align center
-\begin_inset Float figure
-wide false
-sideways false
-status open
-
-\begin_layout Plain Layout
-\align center
-\begin_inset Graphics
-	filename figs/shear.jpg
-	lyxscale 50
-	scale 45
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Plain Layout
-\begin_inset Caption
-
-\begin_layout Plain Layout
-Color contours and vectors of displacement for the axial displacement example
- using a mesh composed of linear tetrahedral cells generated by LaGriT.
-\begin_inset CommandInset label
-LatexCommand label
-name "fig:3dtet4-shear"
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Subsubsection
-Alternative solver and discretization settings
-\end_layout
-
-\begin_layout Standard
-Example 
-\family typewriter
-step01.cfg
-\family default
- uses the additive Schwarz preconditioner in conjunction with a classical
- Gram-Schmidt orthogonalization iterative solver.
- This preconditioner works reasonably well but the number of iterations
- generally scales with problem size.
- Even this small, simple problem requires 24 iterations.
- In this example (
-\family typewriter
-step02.cfg
-\family default
-), we use a more sophisticated preconditioner that preconditions the degrees
- of freedom associated with the three Cartesian coordinates separately while
- using an algebraic multigrid algorithm (see Section 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "sec:petsc:options"
-
-\end_inset
-
- for details).
- Additionally, we illustrate the use of global uniform mesh refinement to
- increase the resolution of the solution by a factor of two.
- Because the mesh is refined in parallel after distribution, this technique
- can be used to run a larger problem than would be possible if the full
- resolution mesh had to be generated by the mesh generator.
- LaGriT runs only in serial and CUBIT has extremely limited parallel mesh
- generation capabilities.
- Table 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "tab:3dtet4:solver:cmp"
-
-\end_inset
-
- shows the improved efficiency of the solver using the split fields with
- the algebraic multigrid preconditioner, especially as the problem size
- becomes larger.
- We have found similar results for other problems.
-\end_layout
-
-\begin_layout Standard
-\noindent
-\align center
-\begin_inset Float table
-placement H
-wide false
-sideways false
-status open
-
-\begin_layout Plain Layout
-\align center
-\begin_inset Caption
-
-\begin_layout Plain Layout
-\begin_inset CommandInset label
-LatexCommand label
-name "tab:3dtet4:solver:cmp"
-
-\end_inset
-
-Number of iterations in linear solve for the Shear Displacement and Kinematic
- Fault Slip problems discussed in this section.
- The preconditioner using split fields and an algebraic multigrid algorithm
- solves the linear system with fewer iterations with only a small to moderate
- increase as the problem size grows.
-\end_layout
-
-\end_inset
-
-
-\begin_inset Tabular
-<lyxtabular version="3" rows="9" columns="4">
-<features tabularvalignment="middle">
-<column alignment="center" valignment="top" width="1.5in">
-<column alignment="center" valignment="middle" width="1.25in">
-<column alignment="center" valignment="top" width="1.5in">
-<column alignment="center" valignment="top" width="1in">
-<row>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\series bold
-Problem
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\series bold
-Preconditioner
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\series bold
-Refinement
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\series bold
-# Iterations in Solve
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell multirow="3" alignment="left" valignment="middle" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Shear Displacement
-\end_layout
-
-\end_inset
-</cell>
-<cell multirow="3" alignment="left" valignment="middle" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-additive Schwarz
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-none (546 DOF)
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-24 (step01)
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell multirow="4" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\end_layout
-
-\end_inset
-</cell>
-<cell multirow="4" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-2x refinement
-\end_layout
-
-\begin_layout Plain Layout
-(3890 DOF)
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-48
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell multirow="4" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\end_layout
-
-\end_inset
-</cell>
-<cell multirow="3" alignment="left" valignment="middle" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-split fields with algebraic multigrid
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-none (546 DOF)
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-12
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell multirow="4" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\end_layout
-
-\end_inset
-</cell>
-<cell multirow="4" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-2x refinement
-\end_layout
-
-\begin_layout Plain Layout
-(3890 DOF)
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-17 (step02)
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell multirow="3" alignment="left" valignment="middle" topline="true" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Kinematic Fault Slip
-\end_layout
-
-\end_inset
-</cell>
-<cell multirow="3" alignment="left" valignment="middle" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-additive Schwarz
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-none (735 DOF)
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-35 (step03)
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell multirow="4" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\end_layout
-
-\end_inset
-</cell>
-<cell multirow="4" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-2x refinement
-\end_layout
-
-\begin_layout Plain Layout
-(4527 DOF)
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-83
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell multirow="4" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\end_layout
-
-\end_inset
-</cell>
-<cell multirow="3" alignment="left" valignment="middle" topline="true" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-split fields with algebraic multigrid
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-none (735 DOF)
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-33
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell multirow="4" alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\end_layout
-
-\end_inset
-</cell>
-<cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-2x refinement
-\end_layout
-
-\begin_layout Plain Layout
-(4527 DOF)
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-53 (step04)
-\end_layout
-
-\end_inset
-</cell>
-</row>
-</lyxtabular>
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-The field splitting and algebraic multigrid preconditioning are setup in
- 
-\family typewriter
-step02.cfg
-\family default
- with the following parameters:
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.timedependent.formulation]
-\end_layout
-
-\begin_layout LyX-Code
-split_fields = True
-\end_layout
-
-\begin_layout LyX-Code
-matrix_type = aij
-\end_layout
-
-\begin_layout LyX-Code
-
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.petsc]
-\end_layout
-
-\begin_layout LyX-Code
-fs_pc_type = fieldsplit
-\end_layout
-
-\begin_layout LyX-Code
-fs_pc_fieldsplit_real_diagonal = 
-\end_layout
-
-\begin_layout LyX-Code
-fs_pc_fieldsplit_type = multiplicative
-\end_layout
-
-\begin_layout LyX-Code
-fs_fieldsplit_0_pc_type = ml
-\end_layout
-
-\begin_layout LyX-Code
-fs_fieldsplit_1_pc_type = ml
-\end_layout
-
-\begin_layout LyX-Code
-fs_fieldsplit_2_pc_type = ml
-\end_layout
-
-\begin_layout LyX-Code
-fs_fieldsplit_0_ksp_type = preonly
-\end_layout
-
-\begin_layout LyX-Code
-fs_fieldsplit_1_ksp_type = preonly
-\end_layout
-
-\begin_layout LyX-Code
-fs_fieldsplit_2_ksp_type = preonly
-\end_layout
-
-\begin_layout Standard
-The uniform global refinement requires changing just a single parameter:
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.mesh_generator]
-\end_layout
-
-\begin_layout LyX-Code
-refiner = pylith.topology.RefineUniform
-\end_layout
-
-\begin_layout Subsection
-Kinematic Fault Slip Example
-\end_layout
-
-\begin_layout Standard
-The next example problem is a right-lateral fault slip applied on the vertical
- fault defined by 
-\family typewriter
-x = 0
-\family default
-.
- The left and right sides of the mesh are fixed in the 
-\family typewriter
-x
-\family default
-, 
-\family typewriter
-y
-\family default
-, and 
-\family typewriter
-z
-\family default
- directions.
- Parameter settings that override or augment those in 
-\family typewriter
-pylithapp.cfg
-\family default
- are contained in the file 
-\family typewriter
-step03.cfg
-\family default
-.
- These settings are:
-\end_layout
-
-\begin_layout Description
-pylithapp.timedependent Specifies an implicit formulation for the problem,
- the array of boundary conditions, and the array of interfaces.
-\end_layout
-
-\begin_layout Description
-pylithapp.timedependent.implicit Specifies an array of two output managers,
- one for the full domain, and another for a subdomain corresponding to the
- ground surface.
-\end_layout
-
-\begin_layout Description
-pylithapp.timedependent.bc.x_pos Specifies the boundary conditions for the
- right side of the mesh, defining which degrees of freedom are being constrained
- (
-\family typewriter
-x
-\family default
-, 
-\family typewriter
-y
-\family default
-, and 
-\family typewriter
-z
-\family default
-), providing the label (defined in 
-\family typewriter
-tet4_1000m_binary.
-\family default
-pset) defining the points desired, and assigning a label to the boundary
- condition set.
- Rather than specifying a spatial database file to define the boundary condition
-s, we use the default spatial database (ZeroDispDB) for the Dirichlet boundary
- condition, which sets the displacements to zero.
-\end_layout
-
-\begin_layout Description
-pylithapp.timedependent.bc.x_neg Specifies the boundary conditions for the
- left side of the mesh, defining which degrees of freedom are being constrained
- (
-\family typewriter
-x
-\family default
-, 
-\family typewriter
-y
-\family default
-, and 
-\family typewriter
-z
-\family default
-), providing the label (defined in 
-\family typewriter
-tet4_1000m_binary.
-\family default
-pset) defining the points desired, and assigning a label to the boundary
- condition set.
- Rather than specifying a spatial database file to define the boundary condition
-s, we use the default spatial database (ZeroDispDB) for the Dirichlet boundary
- condition, which sets the displacements to zero.
-\end_layout
-
-\begin_layout Description
-pylithapp.timedependent.interfaces Gives the label (defined in 
-\family typewriter
-tet4_1000m_binary.
-\family default
-pset) defining the points on the fault, provides quadrature information,
- and then gives database names for material properties (needed for conditioning)
-, fault slip, peak fault slip rate, and fault slip time.
-\end_layout
-
-\begin_layout Description
-pylithapp.problem.formulation.output.output.writer Gives the base filename for
- VTK output over the entire domain (
-\family typewriter
-step03.vtk
-\family default
-).
-\end_layout
-
-\begin_layout Description
-pylithapp.problem.formulation.output.subdomain Gives the label of the nodeset
- defining the subdomain and gives the base filename for VTK output over
- the subdomain corresponding to the ground surface (
-\family typewriter
-step03-groundsurf.vtk
-\family default
-).
-\end_layout
-
-\begin_layout Description
-pylithapp.timedependent.interfaces.fault.output.writer Gives the base filename
- for cohesive cell output files (
-\family typewriter
-step03-fault.vtk
-\family default
-).
-\end_layout
-
-\begin_layout Description
-pylithapp.timedependent.materials.elastic.output Gives the base filename for
- state variable output files for the 
-\family typewriter
-elastic
-\family default
- material set (
-\family typewriter
-step03-statevars-elastic.vtk
-\family default
-), and causes state variables to be averaged over all quadrature points
- in each cell.
-\end_layout
-
-\begin_layout Description
-pylithapp.timedependent.materials.viscoelastic.output Gives the base filename
- for state variable output files for the 
-\family typewriter
-viscoelastic
-\family default
- material set (
-\family typewriter
-step03-statevars-viscoelastic.vtk
-\family default
-), and causes state variables to be averaged over all quadrature points
- in each cell.
-\end_layout
-
-\begin_layout Standard
-The fault example requires three additional database files that were not
- needed for the simple displacement example.
- The first file (
-\family typewriter
-finalslip.spatialdb
-\family default
-) specifies a constant value of 2 m of right-lateral fault slip that then
- tapers linearly to zero from 2 km to 4 km depth, and a linearly-varying
- amount of reverse slip, with a maximum of 0.25 m at the surface, linearly
- tapering to 0 m at 2 km depth.
- The data dimension is one since the data vary linearly along a vertical
- line.
- The default slip time function is a step-function, so we also must provide
- the time at which slip begins.
- The elastic solution is associated with advancing from 
-\begin_inset Formula $t=-dt$
-\end_inset
-
- to 
-\begin_inset Formula $t=0$
-\end_inset
-
-, so we set the slip initiation time for the step-function to 0 in 
-\family typewriter
-dislocation_sliptime.spatialdb
-\family default
-.
-\end_layout
-
-\begin_layout Standard
-The files containing common information (
-\family typewriter
-\size small
-tet4_1000m_binary.gmv
-\family default
-, 
-\family typewriter
-tet4_1000m_binary.pset
-\family default
-, 
-\family typewriter
-pylithapp.cfg
-\family default
-, 
-\family typewriter
-mat_elastic.spatialdb
-\family default
-\size default
-, and 
-\family typewriter
-mat_viscoelastic.spatialdb
-\family default
-) along with the problem-specific files (
-\family typewriter
-\size small
-step03.cfg
-\family default
-, 
-\family typewriter
-finalslip.spatialdb
-\family default
-, and 
-\family typewriter
-sliptime.spatialdb
-\family default
-\size default
-) provide a complete description of the problem, and we can then run this
- example by typing
-\end_layout
-
-\begin_layout LyX-Code
-pylith step03.cfg
-\end_layout
-
-\begin_layout Standard
-Once the problem has run, eight files will be produced.
- The first file is named 
-\family typewriter
-step03_t0000000.vtk
-\family default
-.
- The 
-\family typewriter
-t0000000
-\family default
- indicates that the output is for the first (and only) time step, corresponding
- to an elastic solution.
- This file contains mesh information as well as displacement values at the
- mesh vertices.
- The second file is named 
-\family typewriter
-step03-statevars-elastic_t0000000.vtk
-\family default
-.
- This file contains the state variables for each cell in the material group
- 
-\family typewriter
-elastic
-\family default
-.
- The default fields are the total strain and stress fields.
- We have requested that the values be averaged over all quadrature points
- for each cell; however, since we only have a single quadrature point for
- each linear tetrahedron, this will have no effect.
- The third file (
-\family typewriter
-step03-statevars-viscoelastic_info.vtk
-\family default
-) gives the material properties used for the 
-\family typewriter
-viscoelastic
-\family default
- material set.
- Since we have not specified which properties to write, the default properties
- (
-\family typewriter
-mu
-\family default
-, 
-\family typewriter
-lambda
-\family default
-, 
-\family typewriter
-density
-\family default
-) are written.
- There are two additional files containing the state variables for each
- of the material sets.
- The file 
-\family typewriter
-step03-groundsurf_t0000000.vtk
-\family default
- is analogous to 
-\family typewriter
-step03_t0000000.vtk
-\family default
-, but in this case the results are only given for a subset of the mesh correspon
-ding to the ground surface.
- Also, the cells in this file are one dimension lower than the cells described
- in 
-\family typewriter
-step03_t0000000.vtk
-\family default
-, so they are triangles rather than tetrahedra.
- The file 
-\family typewriter
-step03-fault_t0000000.vtk
-\family default
- gives the specified fault slip for each vertex on the fault, along with
- the computed traction change for the cohesive cell.
- The final file, 
-\family typewriter
-step03-fault_info.vtk
-\family default
-, provides information such as the normal direction, final slip, and slip
- time for each vertex on the fault.
- All of the 
-\family typewriter
-.vtk
-\family default
- files may be used with a number of visualization packages.
- If the problem ran correctly, you should be able to generate a figure such
- as Figure
-\begin_inset CommandInset ref
-LatexCommand vref
-reference "fig:3dtet-disloc"
-
-\end_inset
-
-, which was generated using ParaView.
-\end_layout
-
-\begin_layout Standard
-\noindent
-\align center
-\begin_inset Float figure
-wide false
-sideways false
-status open
-
-\begin_layout Plain Layout
-\align center
-\begin_inset Graphics
-	filename figs/dislocation.jpg
-	lyxscale 50
-	scale 45
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Plain Layout
-\begin_inset Caption
-
-\begin_layout Plain Layout
-Color contours and vectors of displacement for the kinematic fault example
- using a mesh composed of linear tetrahedral cells generated by LaGriT.
-\begin_inset CommandInset label
-LatexCommand label
-name "fig:3dtet-disloc"
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Subsubsection
-Alternative solver and discretization settings
-\end_layout
-
-\begin_layout Standard
-As we did for the Shear Dislocation examples, in 
-\family typewriter
-step04.cfg
-\family default
- we switch to using the splits fields and algebraic multigrid preconditioner
- along with global uniform mesh refinement.
- Because PyLith implements fault slip using Lagrange multipliers, we make
- a few small adjusments to the solver settings.
- As discussed in Section 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "sec:petsc:options"
-
-\end_inset
-
-, we use a custom preconditioner for the Lagrange multiplier degrees of
- freedom when preconditioning with field splitting.
- Within 
-\family typewriter
-step04.cfg
-\family default
- we turn on the use of the custom preconditioner for the Lagrange multiplier
- degrees of freedom and add the corresponding settings for the fourth field
- for the algebraic multigrid algorithm,
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.timedependent.formulation]
-\end_layout
-
-\begin_layout LyX-Code
-split_fields = True
-\end_layout
-
-\begin_layout LyX-Code
-use_custom_constraint_pc = True
-\end_layout
-
-\begin_layout LyX-Code
-matrix_type = aij
-\end_layout
-
-\begin_layout LyX-Code
-
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.petsc]
-\end_layout
-
-\begin_layout LyX-Code
-fs_pc_type = fieldsplit
-\end_layout
-
-\begin_layout LyX-Code
-fs_pc_fieldsplit_real_diagonal =
-\end_layout
-
-\begin_layout LyX-Code
-fs_pc_fieldsplit_type = multiplicative
-\end_layout
-
-\begin_layout LyX-Code
-fs_fieldsplit_0_pc_type = ml
-\end_layout
-
-\begin_layout LyX-Code
-fs_fieldsplit_1_pc_type = ml
-\end_layout
-
-\begin_layout LyX-Code
-fs_fieldsplit_2_pc_type = ml
-\end_layout
-
-\begin_layout LyX-Code
-fs_fieldsplit_3_pc_type = ml
-\end_layout
-
-\begin_layout LyX-Code
-fs_fieldsplit_0_ksp_type = preonly
-\end_layout
-
-\begin_layout LyX-Code
-fs_fieldsplit_1_ksp_type = preonly
-\end_layout
-
-\begin_layout LyX-Code
-fs_fieldsplit_2_ksp_type = preonly
-\end_layout
-
-\begin_layout LyX-Code
-fs_fieldsplit_3_ksp_type = preonly
-\end_layout
-
-\begin_layout Standard
-Table 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "tab:3dtet4:solver:cmp"
-
-\end_inset
-
- shows the improved efficiency of the solver using the split fields with
- the algebraic multigrid preconditioner.
-\end_layout
-
-\end_body
-\end_document
+#LyX 2.0 created this file. For more info see http://www.lyx.org/
+\lyxformat 413
+\begin_document
+\begin_header
+\textclass book
+\begin_preamble
+
+\end_preamble
+\use_default_options false
+\maintain_unincluded_children false
+\language english
+\language_package default
+\inputencoding latin1
+\fontencoding global
+\font_roman default
+\font_sans default
+\font_typewriter default
+\font_default_family default
+\use_non_tex_fonts false
+\font_sc false
+\font_osf false
+\font_sf_scale 100
+\font_tt_scale 100
+
+\graphics default
+\default_output_format default
+\output_sync 0
+\bibtex_command default
+\index_command default
+\paperfontsize default
+\spacing single
+\use_hyperref false
+\papersize default
+\use_geometry true
+\use_amsmath 0
+\use_esint 0
+\use_mhchem 1
+\use_mathdots 1
+\cite_engine basic
+\use_bibtopic false
+\use_indices false
+\paperorientation portrait
+\suppress_date false
+\use_refstyle 0
+\index Index
+\shortcut idx
+\color #008000
+\end_index
+\leftmargin 1in
+\topmargin 1in
+\rightmargin 1in
+\bottommargin 2in
+\secnumdepth 3
+\tocdepth 3
+\paragraph_separation indent
+\paragraph_indentation default
+\quotes_language english
+\papercolumns 1
+\papersides 1
+\paperpagestyle default
+\tracking_changes false
+\output_changes false
+\html_math_output 0
+\html_css_as_file 0
+\html_be_strict false
+\end_header
+
+\begin_body
+
+\begin_layout Section
+\begin_inset CommandInset label
+LatexCommand label
+name "sec:Tutorial-3d-tet4"
+
+\end_inset
+
+Tutorial Using Tetrahedral Mesh Created by LaGriT
+\end_layout
+
+\begin_layout Standard
+PyLith features discussed in this tutorial:
+\end_layout
+
+\begin_layout Itemize
+Quasi-static solution
+\end_layout
+
+\begin_layout Itemize
+LaGriT mesh format
+\end_layout
+
+\begin_layout Itemize
+Dirichlet boundary conditions
+\end_layout
+
+\begin_layout Itemize
+Kinematic fault interface conditions
+\end_layout
+
+\begin_layout Itemize
+Linearly elastic isotropic material
+\end_layout
+
+\begin_layout Itemize
+Maxwell linear viscoelastic material
+\end_layout
+
+\begin_layout Itemize
+Specifying more than one material
+\end_layout
+
+\begin_layout Itemize
+VTK output
+\end_layout
+
+\begin_layout Itemize
+Linear tetrahedral cells
+\end_layout
+
+\begin_layout Itemize
+SimpleDB spatial database
+\end_layout
+
+\begin_layout Itemize
+ZeroDispDB spatial database
+\end_layout
+
+\begin_layout Itemize
+Custom algebraic multigrid preconditioner with split fields
+\end_layout
+
+\begin_layout Itemize
+Global uniform mesh refinement
+\end_layout
+
+\begin_layout Standard
+All of the files necessary to run the examples are contained in the directory
+ 
+\family typewriter
+examples/3d/tet4.
+\end_layout
+
+\begin_layout Subsection
+Overview
+\end_layout
+
+\begin_layout Standard
+This tutorial is a simple 3D example of a quasi-static finite element problem.
+ It is a mesh composed of 852 linear tetrahedra subject to displacement
+ boundary conditions.
+ This example demonstrates the usage of the LaGriT mesh generation package
+ 
+\begin_inset Flex URL
+status collapsed
+
+\begin_layout Plain Layout
+
+lagrit.lanl.gov
+\end_layout
+
+\end_inset
+
+ to create a mesh, as well as describing how to use a LaGriT-generated mesh
+ in PyLith.
+ In this tutorial, we will walk through the steps necessary to construct,
+ run, and visualize the results for two problems that use the same mesh.
+ For each of these problems we also consider a simulation using a custom
+ algebraic multigrid preconditioner with a globally uniformly refined mesh
+ that reduces the node spacing by a factor of two.
+ In addition to this manual, each of the files for the example problems
+ includes extensive comments.
+\end_layout
+
+\begin_layout Subsection
+Mesh Generation and Description
+\end_layout
+
+\begin_layout Standard
+The mesh for these examples is a simple rectangular prism (Figure 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "fig:3dtet4-mesh"
+
+\end_inset
+
+).
+ This mesh would be quite difficult to generate by hand, so we use the LaGriT
+ mesh generation package.
+ For this example, we provide a documented command file in 
+\family typewriter
+examples/3d/tet4.
+
+\family default
+ Examination of this command file should provide some insight into how to
+ use LaGriT with PyLith.
+ For more detailed information refer to the LaGriT website 
+\begin_inset Flex URL
+status collapsed
+
+\begin_layout Plain Layout
+
+lagrit.lanl.gov
+\end_layout
+
+\end_inset
+
+.
+ If you have LaGriT installed on your machine, you can use the command file
+ to create your own mesh.
+ Otherwise, you can use the mesh that has already been created.
+\end_layout
+
+\begin_layout Standard
+There are two ways to use the command file.
+ The simplest method is to go to the
+\family sans
+ 
+\family default
+examples directory (
+\family typewriter
+examples/3d/tet4
+\family default
+), start LaGriT, and then type:
+\end_layout
+
+\begin_layout LyX-Code
+input mesh_tet4_1000m.lagrit
+\end_layout
+
+\begin_layout Standard
+This will run the commands in that file, which will produce the necessary
+ files to run the example.
+ This method will create the mesh, but you will gain very little insight
+ into what is being done.
+ A more informative approach is to input each command directly.
+ That way, you will see what each command does.
+ You can simply copy and paste the commands from 
+\family typewriter
+mesh_tet4_1000m.lagrit
+\family default
+.
+ For example, the first six commands, which define the block shape, are
+\end_layout
+
+\begin_layout LyX-Code
+define / domain_xm / -3.0e+3
+\end_layout
+
+\begin_layout LyX-Code
+define / domain_xp /  3.0e+3
+\end_layout
+
+\begin_layout LyX-Code
+define / domain_ym / -3.0e+3
+\end_layout
+
+\begin_layout LyX-Code
+define / domain_yp /  3.0e+3
+\end_layout
+
+\begin_layout LyX-Code
+define / domain_zm / -4.0e+3
+\end_layout
+
+\begin_layout LyX-Code
+define / domain_zp /  0.0e+3 
+\end_layout
+
+\begin_layout Standard
+Continuing through the remainder of the commands in 
+\family typewriter
+mesh_tet4_1000m.lagrit
+\family default
+, you will eventually end up with the files 
+\family typewriter
+tet4_1000m_binary.gmv
+\family default
+, 
+\family typewriter
+tet4_1000m_ascii.gmv
+\family default
+, 
+\family typewriter
+tet4_1000m_ascii.pset
+\family default
+, and 
+\family typewriter
+tet4_1000m_binary.pset
+\family default
+.
+ The ASCII files are not actually needed, but we create them so users can
+ see what is contained in the files.
+ These files may also be used instead of the binary versions, if desired.
+ The 
+\family typewriter
+.gmv
+\family default
+ files define the mesh information, and they may be read directly by the
+ GMV 
+\begin_inset Flex URL
+status collapsed
+
+\begin_layout Plain Layout
+
+laws.lanl.gov/XCM/gmv/GMVHome.html
+\end_layout
+
+\end_inset
+
+ mesh visualization package.
+ The 
+\family typewriter
+.pset
+\family default
+ files specify the vertices corresponding to each set of vertices on a surface
+ used in the problem, including the fault as well as external boundaries
+ to which boundary conditions are applied.
+\end_layout
+
+\begin_layout Standard
+\noindent
+\align center
+\begin_inset Float figure
+wide false
+sideways false
+status open
+
+\begin_layout Plain Layout
+\align center
+\begin_inset Graphics
+	filename figs/tet4-mesh.jpg
+	lyxscale 50
+	scale 45
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Plain Layout
+\begin_inset Caption
+
+\begin_layout Plain Layout
+Mesh composed of linear tetrahedral cells generated by LaGriT used for the
+ example problems.
+ The different colors represent the different materials.
+\begin_inset CommandInset label
+LatexCommand label
+name "fig:3dtet4-mesh"
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Subsection
+Additional Common Information
+\end_layout
+
+\begin_layout Standard
+In addition to the mesh, the example problems share additional information.
+ In such cases it is generally useful to create a file named 
+\family typewriter
+pylithapp.cfg
+\family default
+ in the run directory, since this file is read automatically every time
+ PyLith is run.
+ Settings specific to a particular problem may be placed in other 
+\family typewriter
+.cfg
+\family default
+ files, as described later, and then those files are placed on the command
+ line.
+  The settings contained in 
+\family typewriter
+pylithapp.cfg
+\family default
+ for this problem consist of:
+\end_layout
+
+\begin_layout Description
+pylithapp.journal.info Settings that control the verbosity of the output for
+ the different components.
+\end_layout
+
+\begin_layout Description
+pylithapp.mesh_generator Settings that control mesh importing, such as the
+ importer type, the filenames, and the spatial dimension of the mesh.
+\end_layout
+
+\begin_layout Description
+pylithapp.timedependent Settings that control the problem, such as the total
+ time, time-step size, and number of entries in the material array.
+\end_layout
+
+\begin_layout Description
+pylithapp.timedependent.materials Settings that control the material type,
+ specify which material IDs are to be associated with a particular material
+ type, and give the name of the spatial database containing material parameters
+ for the mesh.
+ The quadrature information is also given.
+\end_layout
+
+\begin_layout Description
+pylithapp.petsc PETSc settings to use for the problem, such as the preconditioner
+ type.
+\end_layout
+
+\begin_layout Standard
+Since these examples use a mesh from LaGriT, we set the importer to 
+\family typewriter
+MeshIO
+\family default
+Lagrit:
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.mesh_generator]
+\end_layout
+
+\begin_layout LyX-Code
+reader = pylith.meshio.MeshIOLagrit
+\end_layout
+
+\begin_layout LyX-Code
+ 
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.mesh_generator.reader]
+\end_layout
+
+\begin_layout LyX-Code
+filename_gmv = mesh/tet4_1000m_binary.gmv
+\end_layout
+
+\begin_layout LyX-Code
+filename_pset = mesh/tet4_1000m_binary.pset
+\end_layout
+
+\begin_layout LyX-Code
+flip_endian = True
+\end_layout
+
+\begin_layout LyX-Code
+# record_header_32bit = False
+\end_layout
+
+\begin_layout Standard
+Notice that there are a couple of settings pertinent to binary files.
+ The first flag (
+\family typewriter
+flip_endian
+\family default
+) is used if the binary files were produced on a machine with a different
+ endianness than the machine on which they are being read.
+ If you get an error when attempting to run an example, you may need to
+ change the setting of this flag.
+ The second flag (
+\family typewriter
+record_header_32bit
+\family default
+) may need to be set to 
+\family typewriter
+False
+\family default
+ if the version of LaGriT being used has 64-bit Fortran record headers.
+ 
+\end_layout
+
+\begin_layout Standard
+This example differs from previous examples, because we specify two material
+ groups:
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.timedependent]
+\end_layout
+
+\begin_layout LyX-Code
+materials = [elastic,viscoelastic]
+\end_layout
+
+\begin_layout LyX-Code
+ 
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.timedependent.materials.elastic]
+\end_layout
+
+\begin_layout LyX-Code
+label = Elastic material
+\end_layout
+
+\begin_layout LyX-Code
+id = 1
+\end_layout
+
+\begin_layout LyX-Code
+db.iohandler.filename = spatialdb/mat_elastic.spatialdb
+\end_layout
+
+\begin_layout LyX-Code
+quadrature.cell = pylith.feassemble.FIATSimplex
+\end_layout
+
+\begin_layout LyX-Code
+quadrature.cell.shape = tetrahedron
+\end_layout
+
+\begin_layout LyX-Code
+ 
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.timedependent.materials.viscoelastic]
+\end_layout
+
+\begin_layout LyX-Code
+label = Viscoelastic material
+\end_layout
+
+\begin_layout LyX-Code
+id = 2
+\end_layout
+
+\begin_layout LyX-Code
+db.iohandler.filename = spatialdb/mat_viscoelastic.spatialdb
+\end_layout
+
+\begin_layout LyX-Code
+quadrature.cell = pylith.feassemble.FIATSimplex
+\end_layout
+
+\begin_layout LyX-Code
+quadrature.cell.shape = tetrahedron
+\end_layout
+
+\begin_layout LyX-Code
+
+\end_layout
+
+\begin_layout LyX-Code
+
+\end_layout
+
+\begin_layout Standard
+The two materials correspond to the two different colors in Figure 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "fig:3dtet4-mesh"
+
+\end_inset
+
+.
+ Each material uses a different spatial database because the physical parameters
+ are different.
+ In generating the mesh within LaGriT, the mesh contains four materials
+ as a result of how LaGriT handles materials and interior interfaces.
+ Near the end of the LaGriT command file, we merge the materials on each
+ side of the fault into a single material to simplify the input and output
+ from PyLith.
+ For this example, values describing three-dimensional elastic material
+ properties are given by the single point in the spatial databases, resulting
+ in uniform physical properties within each material.
+\end_layout
+
+\begin_layout Subsection
+Shear Displacement Example
+\end_layout
+
+\begin_layout Standard
+The first example problem is shearing of the mesh along the y-direction,
+ with displacement boundary conditions applied on the planes corresponding
+ to the minimum and maximum x-values.
+ Parameter settings that override or augment those in 
+\family typewriter
+pylithapp.cfg
+\family default
+ are contained in the file 
+\family typewriter
+step01.cfg
+\family default
+.
+ These settings are:
+\end_layout
+
+\begin_layout Description
+pylithapp.timedependent Specifies an implicit formulation for the problem
+ and specifies the array of boundary conditions.
+\end_layout
+
+\begin_layout Description
+pylithapp.timedependent.implicit Specifies an array of two output managers,
+ one for the full domain, and another for a subdomain corresponding to the
+ ground surface.
+\end_layout
+
+\begin_layout Description
+pylithapp.timedependent.bc.x_pos Specifies the boundary conditions for the
+ right side of the mesh, defining which degrees of freedom are being constrained
+ (
+\family typewriter
+x
+\family default
+ and 
+\family typewriter
+y
+\family default
+), providing the label (defined in 
+\family typewriter
+tet4_1000m_binary.pset
+\family default
+) defining the points desired, assigning a label to the boundary condition
+ set, and giving the name of the spatial database defining the boundary
+ conditions (
+\family typewriter
+fixeddisp_shear.spatialdb
+\family default
+).
+\end_layout
+
+\begin_layout Description
+pylithapp.timedependent.bc.x_neg Specifies the boundary conditions for the
+ left side of the mesh, defining which degrees of freedom are being constrained
+ (
+\family typewriter
+x
+\family default
+ and 
+\family typewriter
+y
+\family default
+), providing the label (defined in 
+\family typewriter
+tet4_1000m_binary.
+\family default
+pset) defining the points desired, assigning a label to the boundary condition
+ set, and giving the name of the spatial database defining the boundary
+ conditions (
+\family typewriter
+fixeddisp_shear.spatialdb
+\family default
+).
+\end_layout
+
+\begin_layout Description
+pylithapp.timedependent.bc.z_neg Specifies the boundary conditions for the
+ bottom of the mesh, defining which degrees of freedom are being constrained
+ (
+\family typewriter
+x
+\family default
+ and 
+\family typewriter
+y
+\family default
+), providing the label (defined in 
+\family typewriter
+tet4_1000m_binary.
+\family default
+pset) defining the points desired, assigning a label to the boundary condition
+ set, and giving the name of the spatial database defining the boundary
+ conditions (
+\family typewriter
+fixeddisp_shear.spatialdb
+\family default
+).
+\end_layout
+
+\begin_layout Description
+pylithapp.problem.formulation.output.domain.writer Gives the base filename for
+ VTK output over the entire domain (
+\family typewriter
+shearxy.vtk
+\family default
+).
+\end_layout
+
+\begin_layout Description
+pylithapp.problem.formulation.output.subdomain Gives the label of the nodeset
+ defining the subdomain and gives the base filename for VTK output over
+ the subdomain corresponding to the ground surface (
+\family typewriter
+step01-groundsurf.vtk
+\family default
+).
+\end_layout
+
+\begin_layout Description
+pylithapp.timedependent.materials.elastic.output Gives the base filename for
+ state variable output files for the 
+\family typewriter
+elastic
+\family default
+ material set (
+\family typewriter
+step01-elastic.vtk
+\family default
+), and causes state variables to be averaged over all quadrature points
+ in each cell.
+\end_layout
+
+\begin_layout Description
+pylithapp.timedependent.materials.viscoelastic.output Gives the base filename
+ for state variable output files for the 
+\family typewriter
+viscoelastic
+\family default
+ material set (
+\family typewriter
+step01-viscoelastic.vtk
+\family default
+), and causes state variables to be averaged over all quadrature points
+ in each cell.
+\end_layout
+
+\begin_layout Standard
+The values for the Dirichlet boundary conditions are described in the file
+ 
+\family typewriter
+fixeddisp_shear.spatialdb
+\family default
+, as specified in 
+\family typewriter
+step01.cfg
+\family default
+.
+ The format of all spatial database files is similar.
+ Because data are being specified using two control points (rather than
+ being uniform over the mesh, for example), the data dimension is one.
+\end_layout
+
+\begin_layout Standard
+The files containing common information (
+\family typewriter
+\size small
+tet4_1000m_binary.gmv
+\family default
+, 
+\family typewriter
+tet4_1000m_binary.pset
+\family default
+, 
+\family typewriter
+pylithapp.cfg
+\family default
+, 
+\family typewriter
+mat_elastic.spatialdb
+\family default
+\size default
+, and 
+\family typewriter
+mat_viscoelastic.spatialdb
+\family default
+) along with the problem-specific files (
+\family typewriter
+\size small
+step01.cfg
+\family default
+ and 
+\family typewriter
+fixeddisp_shear.spatialdb
+\family default
+\size default
+) provide a complete description of the problem, and we can then run this
+ example by typing
+\end_layout
+
+\begin_layout LyX-Code
+pylith step01.cfg
+\end_layout
+
+\begin_layout Standard
+Once the problem has run, six files will be produced.
+ The first file is named 
+\family typewriter
+step01_t0000000.vtk
+\family default
+.
+ The 
+\family typewriter
+t0000000
+\family default
+ indicates that the output is for the first (and only) time step, corresponding
+ to an elastic solution.
+ This file contains mesh information as well as displacement values at the
+ mesh vertices.
+ The second file is named 
+\family typewriter
+step01-statevars-elastic_t0000000.vtk
+\family default
+.
+ This file contains the state variables for each cell in the material group
+ 
+\family typewriter
+elastic
+\family default
+.
+ The default fields are the total strain and stress fields.
+ These values are computed at each quadrature point in the cell.
+ We have requested that the values be averaged over all quadrature points
+ for each cell; however, since we only have a single quadrature point for
+ each linear tetrahedron, this will have no effect.
+ The third file (
+\family typewriter
+step01-statevars-viscoelastic_info.vtk
+\family default
+) gives the material properties used for the 
+\family typewriter
+viscoelastic
+\family default
+ material set.
+ Since we have not specified which properties to write, the default properties
+ (
+\family typewriter
+mu
+\family default
+, 
+\family typewriter
+lambda
+\family default
+, 
+\family typewriter
+density
+\family default
+) are written.
+ There are two additional files containing the state variables for each
+ of the material sets.
+ The final file (
+\family typewriter
+step01-groundsurf_t0000000.vtk
+\family default
+) is analogous to 
+\family typewriter
+step01_t0000000.vtk
+\family default
+, but in this case the results are only given for a subset of the mesh correspon
+ding to the ground surface.
+ Also, the cells in this file are one dimension lower than the cells described
+ in 
+\family typewriter
+step01_t0000000.vtk
+\family default
+, so they are triangles rather than tetrahedra.
+ All of the 
+\family typewriter
+.vtk
+\family default
+ files may be used with a number of visualization packages.
+ If the problem ran correctly, you should be able to generate a figure such
+ as Figure 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "fig:3dtet4-shear"
+
+\end_inset
+
+, which was generated using ParaView.
+\end_layout
+
+\begin_layout Standard
+\align center
+\begin_inset Float figure
+wide false
+sideways false
+status open
+
+\begin_layout Plain Layout
+\align center
+\begin_inset Graphics
+	filename figs/shear.jpg
+	lyxscale 50
+	scale 45
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Plain Layout
+\begin_inset Caption
+
+\begin_layout Plain Layout
+Color contours and vectors of displacement for the axial displacement example
+ using a mesh composed of linear tetrahedral cells generated by LaGriT.
+\begin_inset CommandInset label
+LatexCommand label
+name "fig:3dtet4-shear"
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Subsubsection
+Alternative Solver and Discretization Settings
+\end_layout
+
+\begin_layout Standard
+Example 
+\family typewriter
+step01.cfg
+\family default
+ uses the additive Schwarz preconditioner in conjunction with a classical
+ Gram-Schmidt orthogonalization iterative solver.
+ This preconditioner works reasonably well but the number of iterations
+ generally scales with problem size.
+ Even this small, simple problem requires 24 iterations.
+ In this example (
+\family typewriter
+step02.cfg
+\family default
+), we use a more sophisticated preconditioner that preconditions the degrees
+ of freedom associated with the three Cartesian coordinates separately while
+ using an algebraic multigrid algorithm (see Section 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "sec:petsc:options"
+
+\end_inset
+
+ for details).
+ Additionally, we illustrate the use of global uniform mesh refinement to
+ increase the resolution of the solution by a factor of two.
+ Because the mesh is refined in parallel after distribution, this technique
+ can be used to run a larger problem than would be possible if the full
+ resolution mesh had to be generated by the mesh generator.
+ LaGriT runs only in serial and CUBIT has extremely limited parallel mesh
+ generation capabilities.
+ Table 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "tab:3dtet4:solver:cmp"
+
+\end_inset
+
+ shows the improved efficiency of the solver using the split fields with
+ the algebraic multigrid preconditioner, especially as the problem size
+ becomes larger.
+ We have found similar results for other problems.
+\end_layout
+
+\begin_layout Standard
+\noindent
+\align center
+\begin_inset Float table
+placement H
+wide false
+sideways false
+status open
+
+\begin_layout Plain Layout
+\align center
+\begin_inset Caption
+
+\begin_layout Plain Layout
+\begin_inset CommandInset label
+LatexCommand label
+name "tab:3dtet4:solver:cmp"
+
+\end_inset
+
+Number of iterations in linear solve for the Shear Displacement and Kinematic
+ Fault Slip problems discussed in this section.
+ The preconditioner using split fields and an algebraic multigrid algorithm
+ solves the linear system with fewer iterations with only a small to moderate
+ increase as the problem size grows.
+\end_layout
+
+\end_inset
+
+
+\begin_inset Tabular
+<lyxtabular version="3" rows="9" columns="4">
+<features tabularvalignment="middle">
+<column alignment="center" valignment="top" width="1.5in">
+<column alignment="center" valignment="middle" width="1.25in">
+<column alignment="center" valignment="top" width="1.5in">
+<column alignment="center" valignment="top" width="1in">
+<row>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\series bold
+Problem
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\series bold
+Preconditioner
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\series bold
+Refinement
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\series bold
+# Iterations in Solve
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell multirow="3" alignment="left" valignment="middle" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Shear Displacement
+\end_layout
+
+\end_inset
+</cell>
+<cell multirow="3" alignment="left" valignment="middle" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+additive Schwarz
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+none (546 DOF)
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+24 (step01)
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell multirow="4" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\end_inset
+</cell>
+<cell multirow="4" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+2x refinement
+\end_layout
+
+\begin_layout Plain Layout
+(3890 DOF)
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+48
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell multirow="4" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\end_inset
+</cell>
+<cell multirow="3" alignment="left" valignment="middle" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+split fields with algebraic multigrid
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+none (546 DOF)
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+12
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell multirow="4" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\end_inset
+</cell>
+<cell multirow="4" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+2x refinement
+\end_layout
+
+\begin_layout Plain Layout
+(3890 DOF)
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+17 (step02)
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell multirow="3" alignment="left" valignment="middle" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Kinematic Fault Slip
+\end_layout
+
+\end_inset
+</cell>
+<cell multirow="3" alignment="left" valignment="middle" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+additive Schwarz
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+none (735 DOF)
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+35 (step03)
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell multirow="4" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\end_inset
+</cell>
+<cell multirow="4" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+2x refinement
+\end_layout
+
+\begin_layout Plain Layout
+(4527 DOF)
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+83
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell multirow="4" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\end_inset
+</cell>
+<cell multirow="3" alignment="left" valignment="middle" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+split fields with algebraic multigrid
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+none (735 DOF)
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+33
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell multirow="4" alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\end_inset
+</cell>
+<cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+2x refinement
+\end_layout
+
+\begin_layout Plain Layout
+(4527 DOF)
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+53 (step04)
+\end_layout
+
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+The field splitting and algebraic multigrid preconditioning are set up in
+ 
+\family typewriter
+step02.cfg
+\family default
+ with the following parameters:
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.timedependent.formulation]
+\end_layout
+
+\begin_layout LyX-Code
+split_fields = True
+\end_layout
+
+\begin_layout LyX-Code
+matrix_type = aij
+\end_layout
+
+\begin_layout LyX-Code
+
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.petsc]
+\end_layout
+
+\begin_layout LyX-Code
+fs_pc_type = fieldsplit
+\end_layout
+
+\begin_layout LyX-Code
+fs_pc_fieldsplit_real_diagonal = 
+\end_layout
+
+\begin_layout LyX-Code
+fs_pc_fieldsplit_type = multiplicative
+\end_layout
+
+\begin_layout LyX-Code
+fs_fieldsplit_0_pc_type = ml
+\end_layout
+
+\begin_layout LyX-Code
+fs_fieldsplit_1_pc_type = ml
+\end_layout
+
+\begin_layout LyX-Code
+fs_fieldsplit_2_pc_type = ml
+\end_layout
+
+\begin_layout LyX-Code
+fs_fieldsplit_0_ksp_type = preonly
+\end_layout
+
+\begin_layout LyX-Code
+fs_fieldsplit_1_ksp_type = preonly
+\end_layout
+
+\begin_layout LyX-Code
+fs_fieldsplit_2_ksp_type = preonly
+\end_layout
+
+\begin_layout Standard
+The uniform global refinement requires changing just a single parameter:
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.mesh_generator]
+\end_layout
+
+\begin_layout LyX-Code
+refiner = pylith.topology.RefineUniform
+\end_layout
+
+\begin_layout Subsection
+Kinematic Fault Slip Example
+\end_layout
+
+\begin_layout Standard
+The next example problem is a right-lateral fault slip applied on the vertical
+ fault defined by 
+\family typewriter
+x = 0
+\family default
+.
+ The left and right sides of the mesh are fixed in the 
+\family typewriter
+x
+\family default
+, 
+\family typewriter
+y
+\family default
+, and 
+\family typewriter
+z
+\family default
+ directions.
+ Parameter settings that override or augment those in 
+\family typewriter
+pylithapp.cfg
+\family default
+ are contained in the file 
+\family typewriter
+step03.cfg
+\family default
+.
+ These settings are:
+\end_layout
+
+\begin_layout Description
+pylithapp.timedependent Specifies an implicit formulation for the problem,
+ the array of boundary conditions, and the array of interfaces.
+\end_layout
+
+\begin_layout Description
+pylithapp.timedependent.implicit Specifies an array of two output managers,
+ one for the full domain, and another for a subdomain corresponding to the
+ ground surface.
+\end_layout
+
+\begin_layout Description
+pylithapp.timedependent.bc.x_pos Specifies the boundary conditions for the
+ right side of the mesh, defining which degrees of freedom are being constrained
+ (
+\family typewriter
+x
+\family default
+, 
+\family typewriter
+y
+\family default
+, and 
+\family typewriter
+z
+\family default
+), providing the label (defined in 
+\family typewriter
+tet4_1000m_binary.pset
+\family default
+) defining the points desired, and assigning a label to the boundary condition
+ set.
+ Rather than specifying a spatial database file to define the boundary condition
+s, we use the default spatial database (ZeroDispDB) for the Dirichlet boundary
+ condition, which sets the displacements to zero.
+\end_layout
+
+\begin_layout Description
+pylithapp.timedependent.bc.x_neg Specifies the boundary conditions for the
+ left side of the mesh, defining which degrees of freedom are being constrained
+ (
+\family typewriter
+x
+\family default
+, 
+\family typewriter
+y
+\family default
+, and 
+\family typewriter
+z
+\family default
+), providing the label (defined in 
+\family typewriter
+tet4_1000m_binary.pset
+\family default
+) defining the points desired, and assigning a label to the boundary condition
+ set.
+ Rather than specifying a spatial database file to define the boundary condition
+s, we use the default spatial database (ZeroDispDB) for the Dirichlet boundary
+ condition, which sets the displacements to zero.
+\end_layout
+
+\begin_layout Description
+pylithapp.timedependent.interfaces Gives the label (defined in 
+\family typewriter
+tet4_1000m_binary.pset
+\family default
+) defining the points on the fault, provides quadrature information, and
+ then gives database names for material properties (needed for conditioning),
+ fault slip, peak fault slip rate, and fault slip time.
+\end_layout
+
+\begin_layout Description
+pylithapp.problem.formulation.output.output.writer Gives the base filename for
+ VTK output over the entire domain (
+\family typewriter
+step03.vtk
+\family default
+).
+\end_layout
+
+\begin_layout Description
+pylithapp.problem.formulation.output.subdomain Gives the label of the nodeset
+ defining the subdomain and gives the base filename for VTK output over
+ the subdomain corresponding to the ground surface (
+\family typewriter
+step03-groundsurf.vtk
+\family default
+).
+\end_layout
+
+\begin_layout Description
+pylithapp.timedependent.interfaces.fault.output.writer Gives the base filename
+ for cohesive cell output files (
+\family typewriter
+step03-fault.vtk
+\family default
+).
+\end_layout
+
+\begin_layout Description
+pylithapp.timedependent.materials.elastic.output Gives the base filename for
+ state variable output files for the 
+\family typewriter
+elastic
+\family default
+ material set (
+\family typewriter
+step03-statevars-elastic.vtk
+\family default
+), and causes state variables to be averaged over all quadrature points
+ in each cell.
+\end_layout
+
+\begin_layout Description
+pylithapp.timedependent.materials.viscoelastic.output Gives the base filename
+ for state variable output files for the 
+\family typewriter
+viscoelastic
+\family default
+ material set (
+\family typewriter
+step03-statevars-viscoelastic.vtk
+\family default
+), and causes state variables to be averaged over all quadrature points
+ in each cell.
+\end_layout
+
+\begin_layout Standard
+The fault example requires three additional database files that were not
+ needed for the simple displacement example.
+ The first file (
+\family typewriter
+finalslip.spatialdb
+\family default
+) specifies a constant value of 2 m of right-lateral fault slip that then
+ tapers linearly to zero from 2 km to 4 km depth, and a linearly-varying
+ amount of reverse slip, with a maximum of 0.25 m at the surface, linearly
+ tapering to 0 m at 2 km depth.
+ The data dimension is one since the data vary linearly along a vertical
+ line.
+ The default slip time function is a step-function, so we also must provide
+ the time at which slip begins.
+ The elastic solution is associated with advancing from 
+\begin_inset Formula $t=-dt$
+\end_inset
+
+ to 
+\begin_inset Formula $t=0$
+\end_inset
+
+, so we set the slip initiation time for the step-function to 0 in 
+\family typewriter
+dislocation_sliptime.spatialdb
+\family default
+.
+\end_layout
+
+\begin_layout Standard
+The files containing common information (
+\family typewriter
+\size small
+tet4_1000m_binary.gmv
+\family default
+, 
+\family typewriter
+tet4_1000m_binary.pset
+\family default
+, 
+\family typewriter
+pylithapp.cfg
+\family default
+, 
+\family typewriter
+mat_elastic.spatialdb
+\family default
+\size default
+, and 
+\family typewriter
+mat_viscoelastic.spatialdb
+\family default
+) along with the problem-specific files (
+\family typewriter
+\size small
+step03.cfg
+\family default
+, 
+\family typewriter
+finalslip.spatialdb
+\family default
+, and 
+\family typewriter
+sliptime.spatialdb
+\family default
+\size default
+) provide a complete description of the problem, and we can then run this
+ example by typing
+\end_layout
+
+\begin_layout LyX-Code
+pylith step03.cfg
+\end_layout
+
+\begin_layout Standard
+Once the problem has run, eight files will be produced.
+ The first file is named 
+\family typewriter
+step03_t0000000.vtk
+\family default
+.
+ The 
+\family typewriter
+t0000000
+\family default
+ indicates that the output is for the first (and only) time step, corresponding
+ to an elastic solution.
+ This file contains mesh information as well as displacement values at the
+ mesh vertices.
+ The second file is named 
+\family typewriter
+step03-statevars-elastic_t0000000.vtk
+\family default
+.
+ This file contains the state variables for each cell in the material group
+ 
+\family typewriter
+elastic
+\family default
+.
+ The default fields are the total strain and stress fields.
+ We have requested that the values be averaged over all quadrature points
+ for each cell; however, since we only have a single quadrature point for
+ each linear tetrahedron, this will have no effect.
+ The third file (
+\family typewriter
+step03-statevars-viscoelastic_info.vtk
+\family default
+) gives the material properties used for the 
+\family typewriter
+viscoelastic
+\family default
+ material set.
+ Since we have not specified which properties to write, the default properties
+ (
+\family typewriter
+mu
+\family default
+, 
+\family typewriter
+lambda
+\family default
+, 
+\family typewriter
+density
+\family default
+) are written.
+ There are two additional files containing the state variables for each
+ of the material sets.
+ The file 
+\family typewriter
+step03-groundsurf_t0000000.vtk
+\family default
+ is analogous to 
+\family typewriter
+step03_t0000000.vtk
+\family default
+, but in this case the results are only given for a subset of the mesh correspon
+ding to the ground surface.
+ Also, the cells in this file are one dimension lower than the cells described
+ in 
+\family typewriter
+step03_t0000000.vtk
+\family default
+, so they are triangles rather than tetrahedra.
+ The file 
+\family typewriter
+step03-fault_t0000000.vtk
+\family default
+ gives the specified fault slip for each vertex on the fault, along with
+ the computed traction change for the cohesive cell.
+ The final file, 
+\family typewriter
+step03-fault_info.vtk
+\family default
+, provides information such as the normal direction, final slip, and slip
+ time for each vertex on the fault.
+ All of the 
+\family typewriter
+.vtk
+\family default
+ files may be used with a number of visualization packages.
+ If the problem ran correctly, you should be able to generate a figure such
+ as Figure
+\begin_inset CommandInset ref
+LatexCommand vref
+reference "fig:3dtet-disloc"
+
+\end_inset
+
+, which was generated using ParaView.
+\end_layout
+
+\begin_layout Standard
+\noindent
+\align center
+\begin_inset Float figure
+wide false
+sideways false
+status open
+
+\begin_layout Plain Layout
+\align center
+\begin_inset Graphics
+	filename figs/dislocation.jpg
+	lyxscale 50
+	scale 45
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Plain Layout
+\begin_inset Caption
+
+\begin_layout Plain Layout
+Color contours and vectors of displacement for the kinematic fault example
+ using a mesh composed of linear tetrahedral cells generated by LaGriT.
+\begin_inset CommandInset label
+LatexCommand label
+name "fig:3dtet-disloc"
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Subsubsection
+Alternative Solver and Discretization Settings
+\end_layout
+
+\begin_layout Standard
+As we did for the Shear Dislocation examples, in 
+\family typewriter
+step04.cfg
+\family default
+ we switch to using the split fields and algebraic multigrid preconditioner
+ along with global uniform mesh refinement.
+ Because PyLith implements fault slip using Lagrange multipliers, we make
+ a few small adjusments to the solver settings.
+ As discussed in Section 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "sec:petsc:options"
+
+\end_inset
+
+, we use a custom preconditioner for the Lagrange multiplier degrees of
+ freedom when preconditioning with field splitting.
+ Within 
+\family typewriter
+step04.cfg
+\family default
+ we turn on the use of the custom preconditioner for the Lagrange multiplier
+ degrees of freedom and add the corresponding settings for the fourth field
+ for the algebraic multigrid algorithm,
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.timedependent.formulation]
+\end_layout
+
+\begin_layout LyX-Code
+split_fields = True
+\end_layout
+
+\begin_layout LyX-Code
+use_custom_constraint_pc = True
+\end_layout
+
+\begin_layout LyX-Code
+matrix_type = aij
+\end_layout
+
+\begin_layout LyX-Code
+
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.petsc]
+\end_layout
+
+\begin_layout LyX-Code
+fs_pc_type = fieldsplit
+\end_layout
+
+\begin_layout LyX-Code
+fs_pc_fieldsplit_real_diagonal =
+\end_layout
+
+\begin_layout LyX-Code
+fs_pc_fieldsplit_type = multiplicative
+\end_layout
+
+\begin_layout LyX-Code
+fs_fieldsplit_0_pc_type = ml
+\end_layout
+
+\begin_layout LyX-Code
+fs_fieldsplit_1_pc_type = ml
+\end_layout
+
+\begin_layout LyX-Code
+fs_fieldsplit_2_pc_type = ml
+\end_layout
+
+\begin_layout LyX-Code
+fs_fieldsplit_3_pc_type = ml
+\end_layout
+
+\begin_layout LyX-Code
+fs_fieldsplit_0_ksp_type = preonly
+\end_layout
+
+\begin_layout LyX-Code
+fs_fieldsplit_1_ksp_type = preonly
+\end_layout
+
+\begin_layout LyX-Code
+fs_fieldsplit_2_ksp_type = preonly
+\end_layout
+
+\begin_layout LyX-Code
+fs_fieldsplit_3_ksp_type = preonly
+\end_layout
+
+\begin_layout Standard
+Table 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "tab:3dtet4:solver:cmp"
+
+\end_inset
+
+ shows the improved efficiency of the solver using the split fields with
+ the algebraic multigrid preconditioner.
+\end_layout
+
+\end_body
+\end_document

Modified: short/3D/PyLith/branches/v1.7-trunk/doc/userguide/tutorials/greensfns2d/greensfns2d.lyx
===================================================================
--- short/3D/PyLith/branches/v1.7-trunk/doc/userguide/tutorials/greensfns2d/greensfns2d.lyx	2012-06-25 04:52:47 UTC (rev 20403)
+++ short/3D/PyLith/branches/v1.7-trunk/doc/userguide/tutorials/greensfns2d/greensfns2d.lyx	2012-06-25 16:38:44 UTC (rev 20404)
@@ -1,1018 +1,1010 @@
-#LyX 2.0 created this file. For more info see http://www.lyx.org/
-\lyxformat 413
-\begin_document
-\begin_header
-\textclass book
-\begin_preamble
-
-\end_preamble
-\use_default_options false
-\maintain_unincluded_children false
-\language english
-\language_package default
-\inputencoding latin1
-\fontencoding global
-\font_roman default
-\font_sans default
-\font_typewriter default
-\font_default_family default
-\use_non_tex_fonts false
-\font_sc false
-\font_osf false
-\font_sf_scale 100
-\font_tt_scale 100
-
-\graphics default
-\default_output_format default
-\output_sync 0
-\bibtex_command default
-\index_command default
-\paperfontsize default
-\spacing single
-\use_hyperref false
-\papersize default
-\use_geometry true
-\use_amsmath 0
-\use_esint 0
-\use_mhchem 1
-\use_mathdots 1
-\cite_engine basic
-\use_bibtopic false
-\use_indices false
-\paperorientation portrait
-\suppress_date false
-\use_refstyle 0
-\index Index
-\shortcut idx
-\color #008000
-\end_index
-\leftmargin 1in
-\topmargin 1in
-\rightmargin 1in
-\bottommargin 1in
-\secnumdepth 3
-\tocdepth 3
-\paragraph_separation indent
-\paragraph_indentation default
-\quotes_language english
-\papercolumns 1
-\papersides 1
-\paperpagestyle default
-\tracking_changes false
-\output_changes false
-\html_math_output 0
-\html_css_as_file 0
-\html_be_strict false
-\end_header
-
-\begin_body
-
-\begin_layout Section
-\begin_inset CommandInset label
-LatexCommand label
-name "sec:Tutorial-Greensfns-2d"
-
-\end_inset
-
-Tutorial Generating and Using Green's Functions in Two Dimensions
-\end_layout
-
-\begin_layout Standard
-PyLith features discussed in this tutorial:
-\end_layout
-
-\begin_layout Itemize
-Green's functions
-\end_layout
-
-\begin_layout Itemize
-HDF5 output
-\end_layout
-
-\begin_layout Itemize
-HDF5 point output
-\end_layout
-
-\begin_layout Itemize
-Reading HDF5 output using h5py
-\end_layout
-
-\begin_layout Itemize
-Simple inversion procedure
-\end_layout
-
-\begin_layout Itemize
-Plotting results using matplotlib
-\end_layout
-
-\begin_layout Itemize
-Cubit mesh generation
-\end_layout
-
-\begin_deeper
-\begin_layout Itemize
-Variable mesh resolution
-\end_layout
-
-\begin_layout Itemize
-APREPRO programming language
-\end_layout
-
-\end_deeper
-\begin_layout Itemize
-Static solution
-\end_layout
-
-\begin_layout Itemize
-Linear triangular cells
-\end_layout
-
-\begin_layout Itemize
-Kinematic fault interface conditions
-\end_layout
-
-\begin_layout Itemize
-Plane strain linearly elastic material
-\end_layout
-
-\begin_layout Itemize
-SimpleDB spatial database
-\end_layout
-
-\begin_layout Itemize
-ZeroDispDB spatial database
-\end_layout
-
-\begin_layout Itemize
-UniformDB spatial database
-\end_layout
-
-\begin_layout Standard
-All of the files necessary to run the examples are contained under the directory
- 
-\family typewriter
-examples/2d/greensfns.
-\end_layout
-
-\begin_layout Subsection
-Overview
-\end_layout
-
-\begin_layout Standard
-This tutorial examines the steps necessary to generate Green's functions
- using PyLith and how they may be used in a linear inversion.
- For simplicity we discuss strike-slip and reverse faulting examples in
- the context of 2-D simulations.
- In each example, we first compute surface displacement at a set of points,
- and these computed displacements provide the 
-\begin_inset Quotes eld
-\end_inset
-
-data
-\begin_inset Quotes erd
-\end_inset
-
- for our inversion.
- Second, we compute a set of Green's functions using the same fault geometries,
- and output the results at the same set of points.
- Third, we perform a simple linear inversion.
- An important aspect for both the forward problem and the Green's function
- problem is that the computed solution is output at a set of user-specified
- points (not necessarily coincident with mesh vertices), rather than over
- a mesh or sub-mesh as for other types of output.
- To do this, PyLith internally performs the necessary interpolation.
- There is a README file in the top-level directory that explains how to
- perform the each step in the two problems.
-\end_layout
-
-\begin_layout Subsection
-Mesh Description
-\end_layout
-
-\begin_layout Standard
-We use linear triangular cells for the meshes in each of the two problems.
- We construct the mesh in CUBIT following the same techniques used in the
- 2-D subduction zone example.
- The main driver is in the journal file 
-\family typewriter
-mesh_tri3.jou
-\family default
-.
- It calls the journal file 
-\family typewriter
-geometry.jou
-\family default
- to construct the geometry.
- It then calls the journal file 
-\family typewriter
-gradient.jou
-\family default
- to set the variable discretization sizes used in this mesh.
- Finally, the 
-\family typewriter
-createbc.jou
-\family default
- file is called to setup the groups associated with boundary conditions
- and materials.
- The mesh used for the strike-slip example is shown in Figure 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "fig:greensfns2d-strikeslip-mesh"
-
-\end_inset
-
- The journal files are documented and describe the various steps outlined
- below.
-\end_layout
-
-\begin_layout Enumerate
-Create the geometry defining the domain.
-\end_layout
-
-\begin_layout Enumerate
-Create fault surface by splitting domain across the given locations.
-\end_layout
-
-\begin_layout Enumerate
-Define meshing scheme and cell size variation.
-\end_layout
-
-\begin_deeper
-\begin_layout Enumerate
-Define cell size along curves near fault.
-\end_layout
-
-\begin_layout Enumerate
-Increase cell size away from fault at a geometric rate (bias).
-\end_layout
-
-\end_deeper
-\begin_layout Enumerate
-Generate mesh.
-\end_layout
-
-\begin_layout Enumerate
-Create blocks for materials and nodesets for boundary conditions.
-\end_layout
-
-\begin_layout Enumerate
-Export mesh.
-\end_layout
-
-\begin_layout Standard
-\begin_inset Float figure
-wide false
-sideways false
-status open
-
-\begin_layout Plain Layout
-\align center
-\begin_inset Graphics
-	filename figs/strikeslip_ydispl2.jpg
-	width 4in
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Plain Layout
-\begin_inset Caption
-
-\begin_layout Plain Layout
-Mesh used for both forward and Green's function computations for strike-slip
- problem.
- Computed y-displacements for the forward problem are shown with the color
- scale.
-\begin_inset CommandInset label
-LatexCommand label
-name "fig:greensfns2d-strikeslip-mesh"
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Subsection
-Additional Common Information
-\end_layout
-
-\begin_layout Standard
-As in the examples discussed in previous sections of these tutorials, we
- place parameters common to the forward model and Green's function computation
- in the 
-\family typewriter
-pylithapp.cfg
-\family default
- file so that we do not have to duplicate them for the two procedures.
- The settings contained in 
-\family typewriter
-pylithapp.cfg
-\family default
- for this problem consist of:
-\end_layout
-
-\begin_layout Description
-pylithapp.journal.info Settings that control the verbosity of the output written
- to stdout for the different components.
-\end_layout
-
-\begin_layout Description
-pylithapp.mesh_generator Settings that control mesh importing, such as the
- importer type, the filename, and the spatial dimension of the mesh.
-\end_layout
-
-\begin_layout Description
-pylithapp.problem Settings that control the problem, such as the total time,
- time step size, and spatial dimension.
-\end_layout
-
-\begin_layout Description
-pylithapp.problem.materials Settings that control the material type, specify
- which material IDs are to be associated with a particular material type,
- and give the name of the spatial database containing the physical  properties
- for the material.
- The quadrature information is also given.
-\end_layout
-
-\begin_layout Description
-pylithapp.problem.bc Settings that control the applied boundary conditions.
-\end_layout
-
-\begin_layout Description
-pylithapp.problem.interfaces Settings that control the specification of faults,
- including quadrature information.
-\end_layout
-
-\begin_layout Description
-pylithapp.problem.formulation.output Settings related to output of the solution
- over the domain and points (surface observation locations).
-\end_layout
-
-\begin_layout Description
-pylithapp.petsc PETSc settings to use for the problem, such as the preconditioner
- type.
-\end_layout
-
-\begin_layout Standard
-One aspect that has not been covered previously is the specification of
- output at discrete points, rather than over a mesh or sub-mesh.
- We do this using the 
-\family typewriter
-OutputSolnPoints
-\family default
- output type:
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.problem.formulation]
-\end_layout
-
-\begin_layout LyX-Code
-output = [domain,points]
-\end_layout
-
-\begin_layout LyX-Code
-output.points = pylith.meshio.OutputSolnPoints
-\end_layout
-
-\begin_layout LyX-Code
-
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.problem.formulation.output.points]
-\end_layout
-
-\begin_layout LyX-Code
-coordsys.space_dim = 2
-\end_layout
-
-\begin_layout LyX-Code
-coordsys.units = km
-\end_layout
-
-\begin_layout LyX-Code
-writer = pylith.meshio.DataWriterHDF5Mesh
-\end_layout
-
-\begin_layout LyX-Code
-reader.filename = output_points.txt
-\end_layout
-
-\begin_layout Standard
-We provide the number of spatial dimensions and the units of the point coordinat
-es, and then the coordinates are given in a simple ASCII file (
-\family typewriter
-output_points.txt
-\family default
-).
- These same points are used for both the forward model computation and the
- generation of the Green's functions.
-\end_layout
-
-\begin_layout Subsection
-Step 1: Solution of the Forward Problem
-\end_layout
-
-\begin_layout Standard
-For both the strike-slip problem and the reverse fault problem, we first
- run a static simulation to generate our synthetic data.
- Parameter settings that augment those in 
-\family typewriter
-pylithapp.cfg
-\family default
- are contained in the file 
-\family typewriter
-eqsim.cfg
-\family default
-.
- These settings are:
-\end_layout
-
-\begin_layout Description
-pylithapp.problem.interfaces Give the type of fault interface condition and
- provide the slip distribution to use.
- Linear interpolation is used for the slip distribution.
-\end_layout
-
-\begin_layout Description
-pylithapp.problem.formulation.output Gives the output file names for domain
- output, fault output, point output, and material output.
- All output uses HDF5 format.
-\end_layout
-
-\begin_layout Standard
-The applied fault slip is given in the file 
-\family typewriter
-eqslip.spatialdb
-\family default
-.
- For both the strike-slip and reverse problems, no fault opening is given,
- so only the left-lateral component is nonzero.
- We run the forward models by typing (in the appropriate directory)
-\end_layout
-
-\begin_layout LyX-Code
-pylith eqsim.cfg
-\end_layout
-
-\begin_layout Standard
-Once the problem has run, four HDF5 files will be produced.
- The file named 
-\family typewriter
-eqsim.h5
-\family default
- (and the associated XDMF file) contains the solution for the entire domain.
- This corresponds to the solution shown in Figure 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "fig:greensfns2d-strikeslip-mesh"
-
-\end_inset
-
-.
- The 
-\family typewriter
-eqsim-fault.h5
-\family default
- file contains the applied fault slip and the change in fault tractions,
- while the 
-\family typewriter
-eqsim-fault_info.h5
-\family default
- file contains the final slip, the fault normal, and the slip time.
- The final file (
-\family typewriter
-eqsim-points.h5
-\family default
-) contains the solution computed at the point locations provided in the
- 
-\family typewriter
-output_points.txt
-\family default
- file.
- These are the results that will be used as synthetic data for our inversion.
- One the problem has run, the results may be viewed with a visualization
- package such as ParaView.
- In Figure 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "fig:greensfns2d-strikeslip-forward"
-
-\end_inset
-
- we show the applied fault slip (from 
-\family typewriter
-eqsim-fault.h5
-\family default
-) and the resulting x-displacements (from 
-\family typewriter
-eqsim-points.h5
-\family default
-) for our strike-slip forward problem.
-\end_layout
-
-\begin_layout Standard
-\noindent
-\align center
-\begin_inset Float figure
-wide false
-sideways false
-status open
-
-\begin_layout Plain Layout
-\align center
-\begin_inset Graphics
-	filename figs/strikeslip_forward_points.jpg
-	lyxscale 50
-	scale 33
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Plain Layout
-\begin_inset Caption
-
-\begin_layout Plain Layout
-Applied fault slip for the strike-slip forward problem as well as computed
- x-displacements at a set of points.
-\begin_inset CommandInset label
-LatexCommand label
-name "fig:greensfns2d-strikeslip-forward"
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Subsection
-Step 2: Generation of Green's Functions
-\end_layout
-
-\begin_layout Standard
-The next step is to generate Green's functions that may be used in an inversion.
- The procedure is similar to that for running the forward problem; however,
- it is necessary to change the problem type from the default 
-\family typewriter
-timedependent
-\family default
- to 
-\family typewriter
-greensfns
-\family default
-.
- This is accomplished by simply typing
-\end_layout
-
-\begin_layout LyX-Code
-pylith --problem=pylith.problems.GreensFns
-\end_layout
-
-\begin_layout Standard
-This changes the problem type and it also causes PyLith to read the file
- 
-\family typewriter
-greensfns.cfg
-\family default
- by default, in addition to 
-\family typewriter
-pylithapp.cfg
-\family default
-.
- These additional parameter settings provide the information necessary to
- generate the Green's functions:
-\end_layout
-
-\begin_layout LyX-Code
-[greensfns]
-\end_layout
-
-\begin_layout LyX-Code
-fault_id = 100
-\end_layout
-
-\begin_layout LyX-Code
-
-\end_layout
-
-\begin_layout LyX-Code
-# Set the type of fault interface condition.
-\end_layout
-
-\begin_layout LyX-Code
-[greensfns.interfaces]
-\end_layout
-
-\begin_layout LyX-Code
-fault = pylith.faults.FaultCohesiveImpulses
-\end_layout
-
-\begin_layout LyX-Code
-
-\end_layout
-
-\begin_layout LyX-Code
-# Set the parameters for the fault interface condition.
-\end_layout
-
-\begin_layout LyX-Code
-[greensfns.interfaces.fault]
-\end_layout
-
-\begin_layout LyX-Code
-# Generate impulses for lateral slip only, no fault opening.
-\end_layout
-
-\begin_layout LyX-Code
-# Fault DOF 0 corresponds to left-lateral slip.
-\end_layout
-
-\begin_layout LyX-Code
-impulse_dof = [0]
-\end_layout
-
-\begin_layout LyX-Code
-
-\end_layout
-
-\begin_layout LyX-Code
-# Set the amplitude of the slip impulses (amplitude is nonzero on only
-\end_layout
-
-\begin_layout LyX-Code
-# a subset of the fault)
-\end_layout
-
-\begin_layout LyX-Code
-db_impulse_amplitude.label = Amplitude of slip impulses
-\end_layout
-
-\begin_layout LyX-Code
-db_impulse_amplitude.iohandler.filename = impulse_amplitude.spatialdb
-\end_layout
-
-\begin_layout LyX-Code
-db_impulse_amplitude.query_type = nearest
-\end_layout
-
-\begin_layout Standard
-Note that the top-level identifier is now 
-\family typewriter
-greensfns
-\family default
- rather than 
-\family typewriter
-pylithapp
-\family default
-.
- We first set the fault interface condition type to 
-\family typewriter
-FaultCohesiveImpulses
-\family default
-, and then specify the slip component to use.
- The amplitude of the fault slip and the fault vertices to use are provided
- in the 
-\family typewriter
-impulse_amplitude.spatialdb
-\family default
- file.
- Fault vertices for which zero slip is specified will not have associated
- Green's functions generated.
- The remainder of the 
-\family typewriter
-greensfns.cfg
-\family default
- file provides output information, which is exactly analogous to the settings
- in 
-\family typewriter
-eqsim.cfg
-\family default
-.
-\end_layout
-
-\begin_layout Standard
-The generation of Green's functions is somewhat similar to the solution
- of a time-dependent problem with multiple time steps.
- In this case, each 'time step' corresponds to the solution computed for
- a slip impulse at a particular fault vertex.
- The output files contain the solution for each separate impulse (slip on
- a single fault vertex).
- The 
-\family typewriter
-greensfns-fault_info.h5
-\family default
- file simply contains the slip amplitude and fault normal.
- In Figure 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "fig:greensfns2d-strikeslip-gf6"
-
-\end_inset
-
- we show the applied impulse (from file 
-\family typewriter
-greensfns-fault.h5
-\family default
-) and associated point responses (from file 
-\family typewriter
-greensfns-points.h5
-\family default
-) for the seventh generated Green's function in the strike-slip example.
- In the next section we will show how to read these Green's functions and
- use them to perform a simple linear inversion.
-\end_layout
-
-\begin_layout Standard
-\noindent
-\align center
-\begin_inset Float figure
-wide false
-sideways false
-status open
-
-\begin_layout Plain Layout
-\align center
-\begin_inset Graphics
-	filename figs/strikeslip_gf6.jpg
-	lyxscale 50
-	scale 33
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Plain Layout
-\begin_inset Caption
-
-\begin_layout Plain Layout
-Applied fault slip and computed responses (at points) for the seventh Green's
- function generated for the strike-slip fault example.
-\begin_inset CommandInset label
-LatexCommand label
-name "fig:greensfns2d-strikeslip-gf6"
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Subsection
-Step 3: Simple Inversion Using PyLith-generated Green's Functions
-\end_layout
-
-\begin_layout Standard
-In the previous two steps we generated a set of synthetic data as well as
- a set of Green's functions.
- Both are stored in HDF5 files.
- To make use of them, we provide a simple Python script that reads the HDF5
- results using the h5py Python package.
- Once we have read the necessary information, we will perform a simple least-squ
-ares inversion using the penalty method.
- We will be solving the equation:
-\begin_inset Formula 
-\begin{equation}
-G_{a}m=d_{a}\:,
-\end{equation}
-
-\end_inset
-
-where 
-\begin_inset Formula $m$
-\end_inset
-
- are the model parameters (slip), 
-\begin_inset Formula $G_{a}$
-\end_inset
-
- is the augmented set of Green's functions, and 
-\begin_inset Formula $d_{a}$
-\end_inset
-
- is the augmented data vector.
- The Green's functions are augmented by the addition of a penalty function:
- 
-\begin_inset Formula 
-\begin{equation}
-G_{a}=\left[\begin{array}{c}
-G\\
-\lambda D
-\end{array}\right]\:,
-\end{equation}
-
-\end_inset
-
-and the data vector is augmented by the addition of the 
-\shape italic
-a priori
-\shape default
- model parameter values:
-\begin_inset Formula 
-\begin{equation}
-d_{a}=\left[\begin{array}{c}
-d\\
-m_{ap}
-\end{array}\right]\:.
-\end{equation}
-
-\end_inset
-
-The matrix 
-\begin_inset Formula $D$
-\end_inset
-
- is the penalty function, and 
-\begin_inset Formula $\lambda$
-\end_inset
-
- is the penalty parameter.
- The solution is obtained using the generalized inverse (e.g., 
-\begin_inset CommandInset citation
-LatexCommand cite
-key "Menke:1984"
-
-\end_inset
-
-):
-\begin_inset Formula 
-\begin{equation}
-G^{-g}=\left(G_{a}^{T}G_{a}\right)^{-1}G_{a}^{T}\:,
-\end{equation}
-
-\end_inset
-
-and the estimated solution is then:
-\begin_inset Formula 
-\begin{equation}
-m_{est}=G^{-g}d_{a}\:.
-\end{equation}
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-The code to read the synthetic data and Green's functions and to perform
- the inversion is contained in the file 
-\family typewriter
-invert_slip.py
-\family default
-, which is contained in the top-level directory.
- For this simple example, we have simply used a diagonal matrix as the penalty
- funtion, and the 
-\shape italic
-a priori
-\shape default
- parameter values are assumed to be zero.
- The solution is performed for a range of values of the penalty parameter,
- which are contained in the file 
-\family typewriter
-penalty_params.txt
-\family default
- within each subdirectory.
- The inversion is performed by running the script in the top-level directory
- from each subdirectory.
- To run an inversion, type:
-\end_layout
-
-\begin_layout LyX-Code
-../invert_slip.py --impulses=output/greensfns-fault.h5 --responses=output/greensfns-
-points.h5 --data=output/eqsim-points.h5 --penalty=penalty_params.txt --output=outpu
-t/slip_inverted.txt
-\end_layout
-
-\begin_layout Standard
-This will produce an ASCII file (
-\family typewriter
-slip_inverted.txt
-\family default
-), which will contain the estimated solution.
-\end_layout
-
-\begin_layout Subsection
-Step 4: Visualization of Estimated and True Solutions
-\end_layout
-
-\begin_layout Standard
-Once we have computed the solution, we would then like to visualize the
- results.
- We do this using another Python script that requires the matplotlib plotting
- package (this package is not included in the PyLith binary).
- We also use the h5py package again to read the applied slip for the forward
- problem.
- The Python code to plot the results is contained in the 
-\family typewriter
-plot_invresults.py
-\family default
- file contained within each subdirectory.
- To plot the results, type:
-\end_layout
-
-\begin_layout LyX-Code
-plot_invresults.py --solution=output/eqsim-fault.h5 --predicted=output/slip_invert
-ed.txt
-\end_layout
-
-\begin_layout Standard
-The script will produce an interactive matplotlib window that shows the
- estimated solution compared to the true solution (Figure 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "fig:greensfns-invresults"
-
-\end_inset
-
-).
- As the penalty parameter is increased, the solution is progressively damped.
- In a real inversion we would also include the effects of data uncertainties,
- and the penalty parameter would represent a factor controlling the tradeoff
- between solution simplicity and fitting the noise in the data.
-\end_layout
-
-\begin_layout Standard
-\noindent
-\align center
-\begin_inset Float figure
-wide false
-sideways false
-status open
-
-\begin_layout Plain Layout
-\align center
-\begin_inset Graphics
-	filename figs/strikeslip_inversion.pdf
-	lyxscale 50
-	width 3in
-
-\end_inset
-
-
-\begin_inset Graphics
-	filename figs/reverse_inversion.pdf
-	width 3in
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Plain Layout
-\begin_inset Caption
-
-\begin_layout Plain Layout
-Inversion results from running Python plotting script.
-\begin_inset CommandInset label
-LatexCommand label
-name "fig:greensfns-invresults"
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_body
-\end_document
+#LyX 2.0 created this file. For more info see http://www.lyx.org/
+\lyxformat 413
+\begin_document
+\begin_header
+\textclass book
+\begin_preamble
+
+\end_preamble
+\use_default_options false
+\maintain_unincluded_children false
+\language english
+\language_package default
+\inputencoding latin1
+\fontencoding global
+\font_roman default
+\font_sans default
+\font_typewriter default
+\font_default_family default
+\use_non_tex_fonts false
+\font_sc false
+\font_osf false
+\font_sf_scale 100
+\font_tt_scale 100
+
+\graphics default
+\default_output_format default
+\output_sync 0
+\bibtex_command default
+\index_command default
+\paperfontsize default
+\spacing single
+\use_hyperref false
+\papersize default
+\use_geometry true
+\use_amsmath 0
+\use_esint 0
+\use_mhchem 1
+\use_mathdots 1
+\cite_engine basic
+\use_bibtopic false
+\use_indices false
+\paperorientation portrait
+\suppress_date false
+\use_refstyle 0
+\index Index
+\shortcut idx
+\color #008000
+\end_index
+\leftmargin 1in
+\topmargin 1in
+\rightmargin 1in
+\bottommargin 1in
+\secnumdepth 3
+\tocdepth 3
+\paragraph_separation indent
+\paragraph_indentation default
+\quotes_language english
+\papercolumns 1
+\papersides 1
+\paperpagestyle default
+\tracking_changes false
+\output_changes false
+\html_math_output 0
+\html_css_as_file 0
+\html_be_strict false
+\end_header
+
+\begin_body
+
+\begin_layout Section
+\begin_inset CommandInset label
+LatexCommand label
+name "sec:Tutorial-Greensfns-2d"
+
+\end_inset
+
+Tutorial Generating and Using Green's Functions in Two Dimensions
+\end_layout
+
+\begin_layout Standard
+PyLith features discussed in this tutorial:
+\end_layout
+
+\begin_layout Itemize
+Green's functions
+\end_layout
+
+\begin_layout Itemize
+HDF5 output
+\end_layout
+
+\begin_layout Itemize
+HDF5 point output
+\end_layout
+
+\begin_layout Itemize
+Reading HDF5 output using h5py
+\end_layout
+
+\begin_layout Itemize
+Simple inversion procedure
+\end_layout
+
+\begin_layout Itemize
+Plotting results using matplotlib
+\end_layout
+
+\begin_layout Itemize
+Cubit mesh generation
+\end_layout
+
+\begin_deeper
+\begin_layout Itemize
+Variable mesh resolution
+\end_layout
+
+\begin_layout Itemize
+APREPRO programming language
+\end_layout
+
+\end_deeper
+\begin_layout Itemize
+Static solution
+\end_layout
+
+\begin_layout Itemize
+Linear triangular cells
+\end_layout
+
+\begin_layout Itemize
+Kinematic fault interface conditions
+\end_layout
+
+\begin_layout Itemize
+Plane strain linearly elastic material
+\end_layout
+
+\begin_layout Itemize
+SimpleDB spatial database
+\end_layout
+
+\begin_layout Itemize
+ZeroDispDB spatial database
+\end_layout
+
+\begin_layout Itemize
+UniformDB spatial database
+\end_layout
+
+\begin_layout Standard
+All of the files necessary to run the examples are contained under the directory
+ 
+\family typewriter
+examples/2d/greensfns.
+\end_layout
+
+\begin_layout Subsection
+Overview
+\end_layout
+
+\begin_layout Standard
+This tutorial examines the steps necessary to generate Green's functions
+ using PyLith and how they may be used in a linear inversion.
+ For simplicity we discuss strike-slip and reverse faulting examples in
+ the context of 2D simulations.
+ In each example, we first compute surface displacement at a set of points,
+ and these computed displacements provide the ``data'' for our inversion.
+ Second, we compute a set of Green's functions using the same fault geometries,
+ and output the results at the same set of points.
+ Third, we perform a simple linear inversion.
+ An important aspect for both the forward problem and the Green's function
+ problem is that the computed solution is output at a set of user-specified
+ points (not necessarily coincident with mesh vertices), rather than over
+ a mesh or sub-mesh as for other types of output.
+ To do this, PyLith internally performs the necessary interpolation.
+ There is a README file in the top-level directory that explains how to
+ perform each step in the two problems.
+\end_layout
+
+\begin_layout Subsection
+Mesh Description
+\end_layout
+
+\begin_layout Standard
+We use linear triangular cells for the meshes in each of the two problems.
+ We construct the mesh in CUBIT following the same techniques used in the
+ 2D subduction zone example.
+ The main driver is in the journal file 
+\family typewriter
+mesh_tri3.jou
+\family default
+.
+ It calls the journal file 
+\family typewriter
+geometry.jou
+\family default
+ to construct the geometry.
+ It then calls the journal file 
+\family typewriter
+gradient.jou
+\family default
+ to set the variable discretization sizes used in this mesh.
+ Finally, the 
+\family typewriter
+createbc.jou
+\family default
+ file is called to set up the groups associated with boundary conditions
+ and materials.
+ The mesh used for the strike-slip example is shown in Figure 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "fig:greensfns2d-strikeslip-mesh"
+
+\end_inset
+
+ The journal files are documented and describe the various steps outlined
+ below.
+\end_layout
+
+\begin_layout Enumerate
+Create the geometry defining the domain.
+\end_layout
+
+\begin_layout Enumerate
+Create fault surface by splitting domain across the given locations.
+\end_layout
+
+\begin_layout Enumerate
+Define meshing scheme and cell size variation.
+\end_layout
+
+\begin_deeper
+\begin_layout Enumerate
+Define cell size along curves near fault.
+\end_layout
+
+\begin_layout Enumerate
+Increase cell size away from fault at a geometric rate (bias).
+\end_layout
+
+\end_deeper
+\begin_layout Enumerate
+Generate mesh.
+\end_layout
+
+\begin_layout Enumerate
+Create blocks for materials and nodesets for boundary conditions.
+\end_layout
+
+\begin_layout Enumerate
+Export mesh.
+\end_layout
+
+\begin_layout Standard
+\begin_inset Float figure
+wide false
+sideways false
+status open
+
+\begin_layout Plain Layout
+\align center
+\begin_inset Graphics
+	filename figs/strikeslip_ydispl2.jpg
+	width 4in
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Plain Layout
+\begin_inset Caption
+
+\begin_layout Plain Layout
+Mesh used for both forward and Green's function computations for the strike-slip
+ problem.
+ Computed y-displacements for the forward problem are shown with the color
+ scale.
+\begin_inset CommandInset label
+LatexCommand label
+name "fig:greensfns2d-strikeslip-mesh"
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Subsection
+Additional Common Information
+\end_layout
+
+\begin_layout Standard
+As in the examples discussed in previous sections of these tutorials, we
+ place parameters common to the forward model and Green's function computation
+ in the 
+\family typewriter
+pylithapp.cfg
+\family default
+ file so that we do not have to duplicate them for the two procedures.
+ The settings contained in 
+\family typewriter
+pylithapp.cfg
+\family default
+ for this problem consist of:
+\end_layout
+
+\begin_layout Description
+pylithapp.journal.info Settings that control the verbosity of the output written
+ to stdout for the different components.
+\end_layout
+
+\begin_layout Description
+pylithapp.mesh_generator Settings that control mesh importing, such as the
+ importer type, the filename, and the spatial dimension of the mesh.
+\end_layout
+
+\begin_layout Description
+pylithapp.problem Settings that control the problem, such as the total time,
+ time-step size, and spatial dimension.
+\end_layout
+
+\begin_layout Description
+pylithapp.problem.materials Settings that control the material type, specify
+ which material IDs are to be associated with a particular material type,
+ and give the name of the spatial database containing the physical properties
+ for the material.
+ The quadrature information is also given.
+\end_layout
+
+\begin_layout Description
+pylithapp.problem.bc Settings that control the applied boundary conditions.
+\end_layout
+
+\begin_layout Description
+pylithapp.problem.interfaces Settings that control the specification of faults,
+ including quadrature information.
+\end_layout
+
+\begin_layout Description
+pylithapp.problem.formulation.output Settings related to output of the solution
+ over the domain and points (surface observation locations).
+\end_layout
+
+\begin_layout Description
+pylithapp.petsc PETSc settings to use for the problem, such as the preconditioner
+ type.
+\end_layout
+
+\begin_layout Standard
+One aspect that has not been covered previously is the specification of
+ output at discrete points, rather than over a mesh or sub-mesh.
+ We do this using the 
+\family typewriter
+OutputSolnPoints
+\family default
+ output type:
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.problem.formulation]
+\end_layout
+
+\begin_layout LyX-Code
+output = [domain,points]
+\end_layout
+
+\begin_layout LyX-Code
+output.points = pylith.meshio.OutputSolnPoints
+\end_layout
+
+\begin_layout LyX-Code
+
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.problem.formulation.output.points]
+\end_layout
+
+\begin_layout LyX-Code
+coordsys.space_dim = 2
+\end_layout
+
+\begin_layout LyX-Code
+coordsys.units = km
+\end_layout
+
+\begin_layout LyX-Code
+writer = pylith.meshio.DataWriterHDF5Mesh
+\end_layout
+
+\begin_layout LyX-Code
+reader.filename = output_points.txt
+\end_layout
+
+\begin_layout Standard
+We provide the number of spatial dimensions and the units of the point coordinat
+es, and then the coordinates are given in a simple ASCII file (
+\family typewriter
+output_points.txt
+\family default
+).
+ These same points are used for both the forward model computation and the
+ generation of the Green's functions.
+\end_layout
+
+\begin_layout Subsection
+Step 1: Solution of the Forward Problem
+\end_layout
+
+\begin_layout Standard
+For both the strike-slip problem and the reverse fault problem, we first
+ run a static simulation to generate our synthetic data.
+ Parameter settings that augment those in 
+\family typewriter
+pylithapp.cfg
+\family default
+ are contained in the file 
+\family typewriter
+eqsim.cfg
+\family default
+.
+ These settings are:
+\end_layout
+
+\begin_layout Description
+pylithapp.problem.interfaces Give the type of fault interface condition and
+ provide the slip distribution to use.
+ Linear interpolation is used for the slip distribution.
+\end_layout
+
+\begin_layout Description
+pylithapp.problem.formulation.output Gives the output filenames for domain
+ output, fault output, point output, and material output.
+ All output uses HDF5 format.
+\end_layout
+
+\begin_layout Standard
+The applied fault slip is given in the file 
+\family typewriter
+eqslip.spatialdb
+\family default
+.
+ For both the strike-slip and reverse problems, no fault opening is given,
+ so only the left-lateral component is nonzero.
+ We run the forward models by typing (in the appropriate directory)
+\end_layout
+
+\begin_layout LyX-Code
+pylith eqsim.cfg
+\end_layout
+
+\begin_layout Standard
+Once the problem has run, four HDF5 files will be produced.
+ The file named 
+\family typewriter
+eqsim.h5
+\family default
+ (and the associated XDMF file) contains the solution for the entire domain.
+ This corresponds to the solution shown in Figure 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "fig:greensfns2d-strikeslip-mesh"
+
+\end_inset
+
+.
+ The 
+\family typewriter
+eqsim-fault.h5
+\family default
+ file contains the applied fault slip and the change in fault tractions,
+ while the 
+\family typewriter
+eqsim-fault_info.h5
+\family default
+ file contains the final slip, the fault normal, and the slip time.
+ The final file (
+\family typewriter
+eqsim-points.h5
+\family default
+) contains the solution computed at the point locations provided in the
+ 
+\family typewriter
+output_points.txt
+\family default
+ file.
+ These are the results that will be used as synthetic data for our inversion.
+ One the problem has run, the results may be viewed with a visualization
+ package such as ParaView.
+ In Figure 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "fig:greensfns2d-strikeslip-forward"
+
+\end_inset
+
+ we show the applied fault slip (from 
+\family typewriter
+eqsim-fault.h5
+\family default
+) and the resulting x-displacements (from 
+\family typewriter
+eqsim-points.h5
+\family default
+) for our strike-slip forward problem.
+\end_layout
+
+\begin_layout Standard
+\noindent
+\align center
+\begin_inset Float figure
+wide false
+sideways false
+status open
+
+\begin_layout Plain Layout
+\align center
+\begin_inset Graphics
+	filename figs/strikeslip_forward_points.jpg
+	lyxscale 50
+	scale 33
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Plain Layout
+\begin_inset Caption
+
+\begin_layout Plain Layout
+Applied fault slip for the strike-slip forward problem as well as computed
+ x-displacements at a set of points.
+\begin_inset CommandInset label
+LatexCommand label
+name "fig:greensfns2d-strikeslip-forward"
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Subsection
+Step 2: Generation of Green's Functions
+\end_layout
+
+\begin_layout Standard
+The next step is to generate Green's functions that may be used in an inversion.
+ The procedure is similar to that for running the forward problem; however,
+ it is necessary to change the problem type from the default 
+\family typewriter
+timedependent
+\family default
+ to 
+\family typewriter
+greensfns
+\family default
+.
+ This is accomplished by simply typing
+\end_layout
+
+\begin_layout LyX-Code
+pylith --problem=pylith.problems.GreensFns
+\end_layout
+
+\begin_layout Standard
+This changes the problem type and it also causes PyLith to read the file
+ 
+\family typewriter
+greensfns.cfg
+\family default
+ by default, in addition to 
+\family typewriter
+pylithapp.cfg
+\family default
+.
+ These additional parameter settings provide the information necessary to
+ generate the Green's functions:
+\end_layout
+
+\begin_layout LyX-Code
+[greensfns]
+\end_layout
+
+\begin_layout LyX-Code
+fault_id = 100
+\end_layout
+
+\begin_layout LyX-Code
+
+\end_layout
+
+\begin_layout LyX-Code
+# Set the type of fault interface condition.
+\end_layout
+
+\begin_layout LyX-Code
+[greensfns.interfaces]
+\end_layout
+
+\begin_layout LyX-Code
+fault = pylith.faults.FaultCohesiveImpulses
+\end_layout
+
+\begin_layout LyX-Code
+
+\end_layout
+
+\begin_layout LyX-Code
+# Set the parameters for the fault interface condition.
+\end_layout
+
+\begin_layout LyX-Code
+[greensfns.interfaces.fault]
+\end_layout
+
+\begin_layout LyX-Code
+# Generate impulses for lateral slip only, no fault opening.
+\end_layout
+
+\begin_layout LyX-Code
+# Fault DOF 0 corresponds to left-lateral slip.
+\end_layout
+
+\begin_layout LyX-Code
+impulse_dof = [0]
+\end_layout
+
+\begin_layout LyX-Code
+
+\end_layout
+
+\begin_layout LyX-Code
+# Set the amplitude of the slip impulses (amplitude is nonzero on only
+\end_layout
+
+\begin_layout LyX-Code
+# a subset of the fault)
+\end_layout
+
+\begin_layout LyX-Code
+db_impulse_amplitude.label = Amplitude of slip impulses
+\end_layout
+
+\begin_layout LyX-Code
+db_impulse_amplitude.iohandler.filename = impulse_amplitude.spatialdb
+\end_layout
+
+\begin_layout LyX-Code
+db_impulse_amplitude.query_type = nearest
+\end_layout
+
+\begin_layout Standard
+Note that the top-level identifier is now 
+\family typewriter
+greensfns
+\family default
+ rather than 
+\family typewriter
+pylithapp
+\family default
+.
+ We first set the fault interface condition type to 
+\family typewriter
+FaultCohesiveImpulses
+\family default
+, and then specify the slip component to use.
+ The amplitude of the fault slip and the fault vertices to use are provided
+ in the 
+\family typewriter
+impulse_amplitude.spatialdb
+\family default
+ file.
+ Fault vertices for which zero slip is specified will not have associated
+ Green's functions generated.
+ The remainder of the 
+\family typewriter
+greensfns.cfg
+\family default
+ file provides output information, which is exactly analogous to the settings
+ in 
+\family typewriter
+eqsim.cfg
+\family default
+.
+\end_layout
+
+\begin_layout Standard
+The generation of Green's functions is somewhat similar to the solution
+ of a time-dependent problem with multiple time steps.
+ In this case, each `time step' corresponds to the solution computed for
+ a slip impulse at a particular fault vertex.
+ The output files contain the solution for each separate impulse (slip on
+ a single fault vertex).
+ The 
+\family typewriter
+greensfns-fault_info.h5
+\family default
+ file simply contains the slip amplitude and fault normal.
+ In Figure 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "fig:greensfns2d-strikeslip-gf6"
+
+\end_inset
+
+ we show the applied impulse (from file 
+\family typewriter
+greensfns-fault.h5
+\family default
+) and associated point responses (from file 
+\family typewriter
+greensfns-points.h5
+\family default
+) for the seventh generated Green's function in the strike-slip example.
+ In the next section we will show how to read these Green's functions and
+ use them to perform a simple linear inversion.
+\end_layout
+
+\begin_layout Standard
+\noindent
+\align center
+\begin_inset Float figure
+wide false
+sideways false
+status open
+
+\begin_layout Plain Layout
+\align center
+\begin_inset Graphics
+	filename figs/strikeslip_gf6.jpg
+	lyxscale 50
+	scale 33
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Plain Layout
+\begin_inset Caption
+
+\begin_layout Plain Layout
+Applied fault slip and computed responses (at points) for the seventh Green's
+ function generated for the strike-slip fault example.
+\begin_inset CommandInset label
+LatexCommand label
+name "fig:greensfns2d-strikeslip-gf6"
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Subsection
+Step 3: Simple Inversion Using PyLith-generated Green's Functions
+\end_layout
+
+\begin_layout Standard
+In the previous two steps we generated a set of synthetic data as well as
+ a set of Green's functions.
+ Both are stored in HDF5 files.
+ To make use of them, we provide a simple Python script that reads the HDF5
+ results using the h5py Python package.
+ Once we have read the necessary information, we will perform a simple least-squ
+ares inversion using the penalty method.
+ We will be solving the equation:
+\begin_inset Formula 
+\begin{equation}
+G_{a}m=d_{a}\:,
+\end{equation}
+
+\end_inset
+
+where 
+\begin_inset Formula $m$
+\end_inset
+
+ are the model parameters (slip), 
+\begin_inset Formula $G_{a}$
+\end_inset
+
+ is the augmented set of Green's functions, and 
+\begin_inset Formula $d_{a}$
+\end_inset
+
+ is the augmented data vector.
+ The Green's functions are augmented by the addition of a penalty function:
+ 
+\begin_inset Formula 
+\begin{equation}
+G_{a}=\left[\begin{array}{c}
+G\\
+\lambda D
+\end{array}\right]\:,
+\end{equation}
+
+\end_inset
+
+and the data vector is augmented by the addition of the 
+\shape italic
+a priori
+\shape default
+ model parameter values:
+\begin_inset Formula 
+\begin{equation}
+d_{a}=\left[\begin{array}{c}
+d\\
+m_{ap}
+\end{array}\right]\:.
+\end{equation}
+
+\end_inset
+
+The matrix 
+\begin_inset Formula $D$
+\end_inset
+
+ is the penalty function, and 
+\begin_inset Formula $\lambda$
+\end_inset
+
+ is the penalty parameter.
+ The solution is obtained using the generalized inverse (e.g., 
+\begin_inset CommandInset citation
+LatexCommand cite
+key "Menke:1984"
+
+\end_inset
+
+):
+\begin_inset Formula 
+\begin{equation}
+G^{-g}=\left(G_{a}^{T}G_{a}\right)^{-1}G_{a}^{T}\:,
+\end{equation}
+
+\end_inset
+
+and the estimated solution is then:
+\begin_inset Formula 
+\begin{equation}
+m_{est}=G^{-g}d_{a}\:.
+\end{equation}
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+The code to read the synthetic data and Green's functions and to perform
+ the inversion is contained in the file 
+\family typewriter
+invert_slip.py
+\family default
+, which is contained in the top-level directory.
+ For this simple example, we have simply used a diagonal matrix as the penalty
+ funtion, and the 
+\shape italic
+a priori
+\shape default
+ parameter values are assumed to be zero.
+ The solution is performed for a range of values of the penalty parameter,
+ which are contained in the file 
+\family typewriter
+penalty_params.txt
+\family default
+ within each subdirectory.
+ The inversion is performed by running the script in the top-level directory
+ from each subdirectory.
+ To run an inversion, type:
+\end_layout
+
+\begin_layout LyX-Code
+../invert_slip.py --impulses=output/greensfns-fault.h5 --responses=output/greensfns-
+points.h5 --data=output/eqsim-points.h5 --penalty=penalty_params.txt --output=outpu
+t/slip_inverted.txt
+\end_layout
+
+\begin_layout Standard
+This will produce an ASCII file (
+\family typewriter
+slip_inverted.txt
+\family default
+), which will contain the estimated solution.
+\end_layout
+
+\begin_layout Subsection
+Step 4: Visualization of Estimated and True Solutions
+\end_layout
+
+\begin_layout Standard
+Once we have computed the solution, we would then like to visualize the
+ results.
+ We do this using another Python script that requires the matplotlib plotting
+ package (this package is not included in the PyLith binary).
+ We also use the h5py package again to read the applied slip for the forward
+ problem.
+ The Python code to plot the results is contained in the 
+\family typewriter
+plot_invresults.py
+\family default
+ file contained within each subdirectory.
+ To plot the results, type:
+\end_layout
+
+\begin_layout LyX-Code
+plot_invresults.py --solution=output/eqsim-fault.h5 --predicted=output/slip_invert
+ed.txt
+\end_layout
+
+\begin_layout Standard
+The script will produce an interactive matplotlib window that shows the
+ estimated solution compared to the true solution (Figure 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "fig:greensfns-invresults"
+
+\end_inset
+
+).
+ As the penalty parameter is increased, the solution is progressively damped.
+ In a real inversion we would also include the effects of data uncertainties,
+ and the penalty parameter would represent a factor controlling the tradeoff
+ between solution simplicity and fitting the noise in the data.
+\end_layout
+
+\begin_layout Standard
+\noindent
+\align center
+\begin_inset Float figure
+wide false
+sideways false
+status open
+
+\begin_layout Plain Layout
+\align center
+\begin_inset Graphics
+	filename figs/strikeslip_inversion.pdf
+	lyxscale 50
+	width 3in
+
+\end_inset
+
+
+\begin_inset Graphics
+	filename figs/reverse_inversion.pdf
+	width 3in
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Plain Layout
+\begin_inset Caption
+
+\begin_layout Plain Layout
+Inversion results from running Python plotting script.
+\begin_inset CommandInset label
+LatexCommand label
+name "fig:greensfns-invresults"
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\end_body
+\end_document

Modified: short/3D/PyLith/branches/v1.7-trunk/doc/userguide/tutorials/shearwave/hex8.lyx
===================================================================
--- short/3D/PyLith/branches/v1.7-trunk/doc/userguide/tutorials/shearwave/hex8.lyx	2012-06-25 04:52:47 UTC (rev 20403)
+++ short/3D/PyLith/branches/v1.7-trunk/doc/userguide/tutorials/shearwave/hex8.lyx	2012-06-25 16:38:44 UTC (rev 20404)
@@ -1,284 +1,288 @@
-#LyX 2.0 created this file. For more info see http://www.lyx.org/
-\lyxformat 413
-\begin_document
-\begin_header
-\textclass book
-\begin_preamble
-
-\end_preamble
-\use_default_options false
-\maintain_unincluded_children false
-\language english
-\language_package default
-\inputencoding latin1
-\fontencoding global
-\font_roman default
-\font_sans default
-\font_typewriter default
-\font_default_family default
-\use_non_tex_fonts false
-\font_sc false
-\font_osf false
-\font_sf_scale 100
-\font_tt_scale 100
-
-\graphics default
-\default_output_format default
-\output_sync 0
-\bibtex_command default
-\index_command default
-\paperfontsize default
-\spacing single
-\use_hyperref false
-\papersize default
-\use_geometry true
-\use_amsmath 0
-\use_esint 0
-\use_mhchem 1
-\use_mathdots 1
-\cite_engine basic
-\use_bibtopic false
-\use_indices false
-\paperorientation portrait
-\suppress_date false
-\use_refstyle 0
-\index Index
-\shortcut idx
-\color #008000
-\end_index
-\leftmargin 1in
-\topmargin 1in
-\rightmargin 1in
-\bottommargin 1in
-\secnumdepth 3
-\tocdepth 3
-\paragraph_separation indent
-\paragraph_indentation default
-\quotes_language english
-\papercolumns 1
-\papersides 1
-\paperpagestyle default
-\tracking_changes false
-\output_changes false
-\html_math_output 0
-\html_css_as_file 0
-\html_be_strict false
-\end_header
-
-\begin_body
-
-\begin_layout Section
-\begin_inset CommandInset label
-LatexCommand label
-name "sec:tutorial:shearwave:hex8"
-
-\end_inset
-
-3-D Bar Discretized with Hexahedra
-\end_layout
-
-\begin_layout Standard
-PyLith features discussed in this tutorial:
-\end_layout
-
-\begin_layout Itemize
-Dynamic solution
-\end_layout
-
-\begin_layout Itemize
-CUBIT mesh format
-\end_layout
-
-\begin_layout Itemize
-Absorbing dampers boundary conditions
-\end_layout
-
-\begin_layout Itemize
-Kinematic fault interface conditions
-\end_layout
-
-\begin_layout Itemize
-Elastic isotropic linearly elastic material
-\end_layout
-
-\begin_layout Itemize
-VTK output
-\end_layout
-
-\begin_layout Itemize
-Linear hexahedral cells
-\end_layout
-
-\begin_layout Itemize
-SimpleDB spatial database
-\end_layout
-
-\begin_layout Itemize
-ZeroDispDB spatial database
-\end_layout
-
-\begin_layout Standard
-All of the files necessary to run the examples are contained in the directory
- 
-\family typewriter
-examples/bar_shearwave/hex8.
-\end_layout
-
-\begin_layout Subsection
-Mesh Generation
-\end_layout
-
-\begin_layout Standard
-The mesh is a simple rectangular prism 8 km by 400 m by 400m (Figure 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "fig:shearwave:hex8:mesh"
-
-\end_inset
-
-).
- This mesh could be generated via a simple script, but it is even easier
- to generate this mesh using CUBIT.
- We provide documented CUBIT journal files in 
-\family typewriter
-examples/bar_shearwave/hex8.
-
-\family default
- We first create the geometry, mesh the domain using hexahedral cells, and
- then create blocks and nodesets associated with the materials and boundary
- conditions.
-\end_layout
-
-\begin_layout Standard
-\noindent
-\align center
-\begin_inset Float figure
-wide false
-sideways false
-status open
-
-\begin_layout Plain Layout
-\align center
-\begin_inset Graphics
-	filename figs/hex8mesh.jpg
-	lyxscale 50
-	scale 50
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Plain Layout
-\begin_inset Caption
-
-\begin_layout Plain Layout
-Mesh composed of hexahedral cells generated by CUBIT used for the example
- problem.
-\begin_inset CommandInset label
-LatexCommand label
-name "fig:shearwave:hex8:mesh"
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Subsection
-Simulation Parameters
-\end_layout
-
-\begin_layout Standard
-The simulation parameters match those in the tri3 and tet4 examples.
- As in the tet4 example, we fix both the longitudinal degree of freedom
- and the out-of-plane transverse degree of freedom.
- Using eight-point quadrature permits use of a time step of 1/20 s, which
- is slightly larger than the time step of 1/30 s used in the tri3 and tet4
- simulations.
- All of the parameters are set in the pylithapp.cfg file.
- To run the problem, simply run PyLith without any command line arguments:
-\end_layout
-
-\begin_layout LyX-Code
-pylith
-\end_layout
-
-\begin_layout Standard
-The VTK files will be written to the 
-\family typewriter
-output
-\family default
- directory.
- The output includes the displacement and velocity fields over the entire
- domain at every other time step (0.10 s), the slip and change in traction
- vectors on the fault surface in along-strike and normal directions at every
- other time step (0.10 s), and the strain and stress tensors for each cell
- at every 20th time step (1.0 s).
- If the problem ran correctly, you should be able to generate a figure such
- as Figure 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "fig:shearwave:hex8:deform"
-
-\end_inset
-
-, which was generated using ParaView.
-\end_layout
-
-\begin_layout Standard
-\noindent
-\align center
-\begin_inset Float figure
-wide false
-sideways false
-status open
-
-\begin_layout Plain Layout
-\align center
-\begin_inset Graphics
-	filename figs/hex8deform30.jpg
-	lyxscale 50
-	scale 50
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Plain Layout
-\begin_inset Caption
-
-\begin_layout Plain Layout
-Displacement field in the bar at 3.0 s.
- Deformation has been exaggerated by a factor of 800.
-\begin_inset CommandInset label
-LatexCommand label
-name "fig:shearwave:hex8:deform"
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_body
-\end_document
+#LyX 2.0 created this file. For more info see http://www.lyx.org/
+\lyxformat 413
+\begin_document
+\begin_header
+\textclass book
+\begin_preamble
+
+\end_preamble
+\use_default_options false
+\maintain_unincluded_children false
+\language english
+\language_package default
+\inputencoding latin1
+\fontencoding global
+\font_roman default
+\font_sans default
+\font_typewriter default
+\font_default_family default
+\use_non_tex_fonts false
+\font_sc false
+\font_osf false
+\font_sf_scale 100
+\font_tt_scale 100
+
+\graphics default
+\default_output_format default
+\output_sync 0
+\bibtex_command default
+\index_command default
+\paperfontsize default
+\spacing single
+\use_hyperref false
+\papersize default
+\use_geometry true
+\use_amsmath 0
+\use_esint 0
+\use_mhchem 1
+\use_mathdots 1
+\cite_engine basic
+\use_bibtopic false
+\use_indices false
+\paperorientation portrait
+\suppress_date false
+\use_refstyle 0
+\index Index
+\shortcut idx
+\color #008000
+\end_index
+\leftmargin 1in
+\topmargin 1in
+\rightmargin 1in
+\bottommargin 1in
+\secnumdepth 3
+\tocdepth 3
+\paragraph_separation indent
+\paragraph_indentation default
+\quotes_language english
+\papercolumns 1
+\papersides 1
+\paperpagestyle default
+\tracking_changes false
+\output_changes false
+\html_math_output 0
+\html_css_as_file 0
+\html_be_strict false
+\end_header
+
+\begin_body
+
+\begin_layout Section
+\begin_inset CommandInset label
+LatexCommand label
+name "sec:tutorial:shearwave:hex8"
+
+\end_inset
+
+3-D Bar Discretized with Hexahedra
+\end_layout
+
+\begin_layout Standard
+PyLith features discussed in this tutorial:
+\end_layout
+
+\begin_layout Itemize
+Dynamic solution
+\end_layout
+
+\begin_layout Itemize
+CUBIT mesh format
+\end_layout
+
+\begin_layout Itemize
+Absorbing dampers boundary conditions
+\end_layout
+
+\begin_layout Itemize
+Kinematic fault interface conditions
+\end_layout
+
+\begin_layout Itemize
+Elastic isotropic linearly elastic material
+\end_layout
+
+\begin_layout Itemize
+VTK output
+\end_layout
+
+\begin_layout Itemize
+Linear hexahedral cells
+\end_layout
+
+\begin_layout Itemize
+SimpleDB spatial database
+\end_layout
+
+\begin_layout Itemize
+ZeroDispDB spatial database
+\end_layout
+
+\begin_layout Standard
+All of the files necessary to run the examples are contained in the directory
+ 
+\family typewriter
+examples/bar_shearwave/hex8.
+\end_layout
+
+\begin_layout Subsection
+Mesh Generation
+\end_layout
+
+\begin_layout Standard
+The mesh is a simple rectangular prism 8 km by 400 m by 400 m (Figure 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "fig:shearwave:hex8:mesh"
+
+\end_inset
+
+).
+ This mesh could be generated via a simple script, but it is even easier
+ to generate this mesh using CUBIT.
+ We provide documented CUBIT journal files in 
+\family typewriter
+examples/bar_shearwave/hex8.
+
+\family default
+ We first create the geometry, mesh the domain using hexahedral cells, and
+ then create blocks and nodesets associated with the materials and boundary
+ conditions.
+\end_layout
+
+\begin_layout Standard
+\noindent
+\align center
+\begin_inset Float figure
+wide false
+sideways false
+status open
+
+\begin_layout Plain Layout
+\align center
+\begin_inset Graphics
+	filename figs/hex8mesh.jpg
+	lyxscale 50
+	scale 50
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Plain Layout
+\begin_inset Caption
+
+\begin_layout Plain Layout
+Mesh composed of hexahedral cells generated by CUBIT used for the example
+ problem.
+\begin_inset CommandInset label
+LatexCommand label
+name "fig:shearwave:hex8:mesh"
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Subsection
+Simulation Parameters
+\end_layout
+
+\begin_layout Standard
+The simulation parameters match those in the tri3 and tet4 examples.
+ As in the tet4 example, we fix both the longitudinal degree of freedom
+ and the out-of-plane transverse degree of freedom.
+ Using eight-point quadrature permits use of a time step of 1/20 s, which
+ is slightly larger than the time step of 1/30 s used in the tri3 and tet4
+ simulations.
+ All of the parameters are set in the 
+\family typewriter
+pylithapp.cfg
+\family default
+ file.
+ To run the problem, simply run PyLith without any command line arguments:
+\end_layout
+
+\begin_layout LyX-Code
+pylith
+\end_layout
+
+\begin_layout Standard
+The VTK files will be written to the 
+\family typewriter
+output
+\family default
+ directory.
+ The output includes the displacement and velocity fields over the entire
+ domain at every other time step (0.10 s), the slip and change in traction
+ vectors on the fault surface in along-strike and normal directions at every
+ other time step (0.10 s), and the strain and stress tensors for each cell
+ at every 20th time step (1.0 s).
+ If the problem ran correctly, you should be able to generate a figure such
+ as Figure 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "fig:shearwave:hex8:deform"
+
+\end_inset
+
+, which was generated using ParaView.
+\end_layout
+
+\begin_layout Standard
+\noindent
+\align center
+\begin_inset Float figure
+wide false
+sideways false
+status open
+
+\begin_layout Plain Layout
+\align center
+\begin_inset Graphics
+	filename figs/hex8deform30.jpg
+	lyxscale 50
+	scale 50
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Plain Layout
+\begin_inset Caption
+
+\begin_layout Plain Layout
+Displacement field in the bar at 3.0 s.
+ Deformation has been exaggerated by a factor of 800.
+\begin_inset CommandInset label
+LatexCommand label
+name "fig:shearwave:hex8:deform"
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\end_body
+\end_document

Modified: short/3D/PyLith/branches/v1.7-trunk/doc/userguide/tutorials/shearwave/quad4.lyx
===================================================================
--- short/3D/PyLith/branches/v1.7-trunk/doc/userguide/tutorials/shearwave/quad4.lyx	2012-06-25 04:52:47 UTC (rev 20403)
+++ short/3D/PyLith/branches/v1.7-trunk/doc/userguide/tutorials/shearwave/quad4.lyx	2012-06-25 16:38:44 UTC (rev 20404)
@@ -1,704 +1,704 @@
-#LyX 2.0 created this file. For more info see http://www.lyx.org/
-\lyxformat 413
-\begin_document
-\begin_header
-\textclass book
-\begin_preamble
-
-\end_preamble
-\use_default_options false
-\maintain_unincluded_children false
-\language english
-\language_package default
-\inputencoding latin1
-\fontencoding global
-\font_roman default
-\font_sans default
-\font_typewriter default
-\font_default_family default
-\use_non_tex_fonts false
-\font_sc false
-\font_osf false
-\font_sf_scale 100
-\font_tt_scale 100
-
-\graphics default
-\default_output_format default
-\output_sync 0
-\bibtex_command default
-\index_command default
-\paperfontsize default
-\spacing single
-\use_hyperref false
-\papersize default
-\use_geometry true
-\use_amsmath 0
-\use_esint 0
-\use_mhchem 1
-\use_mathdots 1
-\cite_engine basic
-\use_bibtopic false
-\use_indices false
-\paperorientation portrait
-\suppress_date false
-\use_refstyle 0
-\index Index
-\shortcut idx
-\color #008000
-\end_index
-\leftmargin 1in
-\topmargin 1in
-\rightmargin 1in
-\bottommargin 1in
-\secnumdepth 3
-\tocdepth 3
-\paragraph_separation indent
-\paragraph_indentation default
-\quotes_language english
-\papercolumns 1
-\papersides 1
-\paperpagestyle default
-\tracking_changes false
-\output_changes false
-\html_math_output 0
-\html_css_as_file 0
-\html_be_strict false
-\end_header
-
-\begin_body
-
-\begin_layout Section
-\begin_inset CommandInset label
-LatexCommand label
-name "sec:tutorial:shearwave:quad4"
-
-\end_inset
-
-3-D Bar Discretized with Quadrilaterals
-\end_layout
-
-\begin_layout Standard
-PyLith features discussed in this tutorial:
-\end_layout
-
-\begin_layout Itemize
-Dynamic solution
-\end_layout
-
-\begin_layout Itemize
-CUBIT mesh format
-\end_layout
-
-\begin_layout Itemize
-Absorbing dampers boundary conditions
-\end_layout
-
-\begin_layout Itemize
-Kinematic fault interface conditions
-\end_layout
-
-\begin_layout Itemize
-Dynamic fault interface conditions
-\end_layout
-
-\begin_layout Itemize
-Plane strain linearly elastic material
-\end_layout
-
-\begin_layout Itemize
-VTK output
-\end_layout
-
-\begin_layout Itemize
-Linear quadrilateral cells
-\end_layout
-
-\begin_layout Itemize
-SimpleDB spatial database
-\end_layout
-
-\begin_layout Itemize
-ZeroDispDB spatial database
-\end_layout
-
-\begin_layout Itemize
-UniformDB spatial database
-\end_layout
-
-\begin_layout Standard
-All of the files necessary to run the examples are contained in the directory
- 
-\family typewriter
-examples/bar_shearwave/quad4.
-\end_layout
-
-\begin_layout Subsection
-Mesh Generation
-\end_layout
-
-\begin_layout Standard
-The mesh is a simple rectangular prism 8 km by 400 m by 400m (Figure 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "fig:shearwave:quad4:mesh"
-
-\end_inset
-
-).
- We provide documented CUBIT journal files in 
-\family typewriter
-examples/bar_shearwave/quad4.
-
-\family default
- We first create the geometry, mesh the domain using quadrilateral cells,
- and then create blocks and nodesets associated with the materials and boundary
- conditions.
-\end_layout
-
-\begin_layout Standard
-\noindent
-\align center
-\begin_inset Float figure
-wide false
-sideways false
-status open
-
-\begin_layout Plain Layout
-\align center
-\begin_inset Graphics
-	filename figs/quad4mesh.jpg
-	lyxscale 50
-	scale 50
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Plain Layout
-\begin_inset Caption
-
-\begin_layout Plain Layout
-Mesh composed of hexahedral cells generated by CUBIT used for the example
- problem.
-\begin_inset CommandInset label
-LatexCommand label
-name "fig:shearwave:quad4:mesh"
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Subsection
-Kinematic Fault
-\end_layout
-
-\begin_layout Standard
-The simulation parameters match those in the tri3, tet4, and hex8 examples.
- Using four-point quadrature permits use of a time step of 1/20 s, which
- is slightly larger than the time step of 1/30 s used in the tri3 and tet4
- simulations.
- In contrast to the tri3, tet4, and hex8 shear wave examples which only
- contained a single simulation in a directory, in this example we consider
- several different simulations.
- Consequently, we separate the parameters into multiple 
-\family typewriter
-.cfg
-\family default
- files.
- The parameters common parameters are placed in 
-\family typewriter
-pylithapp.cfg
-\family default
- with the parameters specific to the kinematic fault example in 
-\family typewriter
-kinematic.cfg
-\family default
-.
- To run the problem, simply run PyLith via:
-\end_layout
-
-\begin_layout LyX-Code
-pylith kinematic.cfg
-\end_layout
-
-\begin_layout Standard
-The VTK files will be written to the 
-\family typewriter
-output
-\family default
- directory with the prefix 
-\family typewriter
-kinematic
-\family default
-.
- The output includes the displacement field over the entire domain at every
- other time step (0.10 s), the slip and traction vectors on the fault surface
- in along-strike and normal directions at every other time step (0.10 s),
- and the strain and stress tensors for each cell at every 20th time step
- (1.0 s).
- If the problem ran correctly, you should be able to generate a figure such
- as Figure 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "fig:shearwave:quad4:kinematic"
-
-\end_inset
-
-, which was generated using ParaView.
-\end_layout
-
-\begin_layout Standard
-\noindent
-\align center
-\begin_inset Float figure
-wide false
-sideways false
-status open
-
-\begin_layout Plain Layout
-\align center
-\begin_inset Graphics
-	filename figs/quad4kinematic30.jpg
-	lyxscale 50
-	scale 50
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Plain Layout
-\begin_inset Caption
-
-\begin_layout Plain Layout
-Displacement field in the bar at 3.0 s.
- Deformation has been exaggerated by a factor of 800.
-\begin_inset CommandInset label
-LatexCommand label
-name "fig:shearwave:quad4:kinematic"
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Subsection
-Dynamic Fault
-\end_layout
-
-\begin_layout Standard
-In this set of examples we replace the kinematic fault interface with the
- dynamic fault interface, resulting in fault slip controlled by a fault-constitu
-tive model.
- See Section 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "sec:fault:constitutive:models"
-
-\end_inset
-
- for detailed information about the fault constitutive models available
- in PyLith.
- Because this is a dynamic simulation we want the generated shear wave to
- continue to be absorbed at the ends of the bar, so we drive the fault by
- imposing initial tractions directly on the fault surface rather than through
- deformation within the bar.
- We employ a UniformDB object to specify 6.1 MPa of right-lateral shear and
- 10.0 MPa of normal compression for the initial fault tractions.
- The parameters common to the dynamic fault simulations are in 
-\family typewriter
-dynamic.cfg
-\family default
-.
- We use the explicit time-stepping with a lumped Jacobian matrix.
- We also request that the fault output include slip, slip rate, and traction
- fields:
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.timedependent.interfaces.fault.output]
-\end_layout
-
-\begin_layout LyX-Code
-vertex_data_fields = [slip,slip_rate,traction]
-\end_layout
-
-\begin_layout Subsubsection
-Dynamic Fault with Static Friction
-\end_layout
-
-\begin_layout Standard
-The parameters specific to this example are related to the use of the static
- friction fault constitutive model.
- We set the fault constitutive model via
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.timedependent.interfaces.fault]
-\end_layout
-
-\begin_layout LyX-Code
-friction = pylith.friction.StaticFriction
-\end_layout
-
-\begin_layout Standard
-and use a UniformDB to set the static friction parameters.
- We use a coefficient of friction of 0.6 and no cohesion (0 MPa).
- The parameters specific to this example are in 
-\family typewriter
-dynamic_staticfriction.cfg
-\family default
-, so we run the problem via:
-\end_layout
-
-\begin_layout LyX-Code
-pylith dynamic.cfg dynamic_staticfriction.cfg
-\end_layout
-
-\begin_layout Standard
-The VTK files will be written to the 
-\family typewriter
-output
-\family default
- directory with the prefix 
-\family typewriter
-staticfriction
-\family default
-.
- The output includes the displacement and velocity fields over the entire
- domain at every other time step (0.10 s), the slip, slip rate, and traction
- vectors on the fault surface in along-strike and normal directions at every
- other time step (0.10 s), and the strain and stress tensors for each cell
- at every 20th time step (1.0 s).
- If the problem ran correctly, you should be able to generate a figure such
- as Figure 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "fig:shearwave:quad4:staticfriction"
-
-\end_inset
-
-, which was generated using ParaView.
- The steady-state solution is a constant slip rate of 0.08 m/s, a shear traction
- of 6.0 MPa on the fault surface, and a uniform shear strain of 2e-5 in the
- bar with uniform, constant velocities in the y-direction of +0.04 m/s and
- -0.04 m/s on the -x and +x sides of the fault, respectively.
-\end_layout
-
-\begin_layout Standard
-\noindent
-\align center
-\begin_inset Float figure
-wide false
-sideways false
-status open
-
-\begin_layout Plain Layout
-\align center
-\begin_inset Graphics
-	filename figs/quad4staticfriction30.jpg
-	lyxscale 50
-	scale 50
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Plain Layout
-\begin_inset Caption
-
-\begin_layout Plain Layout
-Velocity field in the bar at 3.0 s for the static friction fault constitutive
- model.
- Deformation has been exaggerated by a factor of 800.
-\begin_inset CommandInset label
-LatexCommand label
-name "fig:shearwave:quad4:staticfriction"
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Subsubsection
-Dynamic Fault with Slip-Weakening Friction
-\end_layout
-
-\begin_layout Standard
-The parameters specific to this example are related to the use of the slip-weake
-ning friction fault constitutive model (see Section 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "sec:fault:constitutive:models"
-
-\end_inset
-
-).
- We set the fault constitutive model via
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.timedependent.interfaces.fault]
-\end_layout
-
-\begin_layout LyX-Code
-friction = pylith.friction.SlipWeakening
-\end_layout
-
-\begin_layout Standard
-and use a UniformDB to set the slip-weakening friction parameters.
- We use a static coefficient of friction of 0.6, a dynamic coefficient of
- friction of 0.5, a slip-weakening parameter of 0.2 m, and no cohesion (0
- MPa).
- The fault constitutive model is associated with the fault, so we can append
- the fault constitutive model parameters to the vertex information fields
- and the fault constitutive model state variables to the vertex data fields:
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.timedependent.interfaces.fault.output]
-\end_layout
-
-\begin_layout LyX-Code
-vertex_info_fields = [strike_dir,normal_dir,initial_traction,static_coefficient,
-\begin_inset Newline newline
-\end_inset
-
-dynamic_coefficient,slip_weakening_parameter,cohesion]
-\end_layout
-
-\begin_layout LyX-Code
-vertex_data_fields = [slip,traction,cumulative_slip,previous_slip]
-\end_layout
-
-\begin_layout Standard
-The parameters specific to this example are in 
-\family typewriter
-dynamic_slipweakening.cfg
-\family default
-, so we run the problem via:
-\end_layout
-
-\begin_layout LyX-Code
-pylith dynamic.cfg dynamic_slipweakening.cfg
-\end_layout
-
-\begin_layout Standard
-The VTK files will be written to the 
-\family typewriter
-output
-\family default
- directory with the prefix 
-\family typewriter
-slipweakening
-\family default
-.
- If the problem ran correctly, you should be able to generate a figure such
- as Figure 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "fig:shearwave:quad4:slipweakening"
-
-\end_inset
-
-, which was generated using ParaView.
- The steady-state solution is a constant slip rate of 0.88 m/s and shear
- traction of 5.0 MPa on the fault surface, a uniform shear strain of 2.2e-4
- in the bar with uniform, constant velocities in the y-direction of +0.44
- m/s and -0.44 m/s on the -x and +x sides of the fault, respectively.
-\end_layout
-
-\begin_layout Standard
-\noindent
-\align center
-\begin_inset Float figure
-wide false
-sideways false
-status open
-
-\begin_layout Plain Layout
-\align center
-\begin_inset Graphics
-	filename figs/quad4slipweakening30.jpg
-	lyxscale 50
-	scale 50
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Plain Layout
-\begin_inset Caption
-
-\begin_layout Plain Layout
-Velocity field in the bar at 3.0 s for the slip-weakening friction fault
- constitutive model.
- Deformation has been exaggerated by a factor of 800.
-\begin_inset CommandInset label
-LatexCommand label
-name "fig:shearwave:quad4:slipweakening"
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Subsubsection
-Dynamic Fault with Rate-State Friction
-\end_layout
-
-\begin_layout Standard
-The parameters specific to this example are related to the use of the rate-
- and state-friction fault constitutive model (see Section 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "sec:fault:constitutive:models"
-
-\end_inset
-
-).
- The evolution of the state variable uses the ageing law.
- We set the fault constitutive model via
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.timedependent.interfaces.fault]
-\end_layout
-
-\begin_layout LyX-Code
-friction = pylith.friction.RateStateAgeing
-\end_layout
-
-\begin_layout Standard
-and use a UniformDB to set the static friction parameters.
- We use a reference coefficient of friction of 0.6, reference slip rate of
- 1.0e-6 m/s, characteristic slip distance of 0.037 m, coefficients a and b
- of 0.0125 and 0.0172, and no cohesion (0 MPa).
- The parameters specific to this example are in 
-\family typewriter
-dynamic_ratestateageing.cfg
-\family default
-, so we run the problem via:
-\end_layout
-
-\begin_layout LyX-Code
-pylith dynamic.cfg dynamic_ratestateageing.cfg
-\end_layout
-
-\begin_layout Standard
-The VTK files will be written to the 
-\family typewriter
-output
-\family default
- directory with the prefix 
-\family typewriter
-ratestateageing
-\family default
-.
- If the problem ran correctly, you should be able to generate a figure such
- as Figure 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "fig:shearwave:quad4:ratestateageing"
-
-\end_inset
-
-, which was generated using ParaView.
- The steady-state solution is a constant slip rate of 0.572 m/s and shear
- traction of 5.385 MPa on the fault surface, a uniform shear strain of 1.43e-4
- in the bar with uniform, constant velocities in the y-direction of +0.286
- m/s and -0.286 m/s on the -x and +x sides of the fault, respectively.
-\end_layout
-
-\begin_layout Standard
-\noindent
-\align center
-\begin_inset Float figure
-wide false
-sideways false
-status open
-
-\begin_layout Plain Layout
-\align center
-\begin_inset Graphics
-	filename figs/quad4ratestateageing30.jpg
-	lyxscale 50
-	scale 50
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Plain Layout
-\begin_inset Caption
-
-\begin_layout Plain Layout
-Velocity field in the bar at 3.0 s for the rate- and state-friction fault
- constitutive model.
- Deformation has been exaggerated by a factor of 800.
-\begin_inset CommandInset label
-LatexCommand label
-name "fig:shearwave:quad4:ratestateageing"
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_body
-\end_document
+#LyX 2.0 created this file. For more info see http://www.lyx.org/
+\lyxformat 413
+\begin_document
+\begin_header
+\textclass book
+\begin_preamble
+
+\end_preamble
+\use_default_options false
+\maintain_unincluded_children false
+\language english
+\language_package default
+\inputencoding latin1
+\fontencoding global
+\font_roman default
+\font_sans default
+\font_typewriter default
+\font_default_family default
+\use_non_tex_fonts false
+\font_sc false
+\font_osf false
+\font_sf_scale 100
+\font_tt_scale 100
+
+\graphics default
+\default_output_format default
+\output_sync 0
+\bibtex_command default
+\index_command default
+\paperfontsize default
+\spacing single
+\use_hyperref false
+\papersize default
+\use_geometry true
+\use_amsmath 0
+\use_esint 0
+\use_mhchem 1
+\use_mathdots 1
+\cite_engine basic
+\use_bibtopic false
+\use_indices false
+\paperorientation portrait
+\suppress_date false
+\use_refstyle 0
+\index Index
+\shortcut idx
+\color #008000
+\end_index
+\leftmargin 1in
+\topmargin 1in
+\rightmargin 1in
+\bottommargin 1in
+\secnumdepth 3
+\tocdepth 3
+\paragraph_separation indent
+\paragraph_indentation default
+\quotes_language english
+\papercolumns 1
+\papersides 1
+\paperpagestyle default
+\tracking_changes false
+\output_changes false
+\html_math_output 0
+\html_css_as_file 0
+\html_be_strict false
+\end_header
+
+\begin_body
+
+\begin_layout Section
+\begin_inset CommandInset label
+LatexCommand label
+name "sec:tutorial:shearwave:quad4"
+
+\end_inset
+
+3D Bar Discretized with Quadrilaterals
+\end_layout
+
+\begin_layout Standard
+PyLith features discussed in this tutorial:
+\end_layout
+
+\begin_layout Itemize
+Dynamic solution
+\end_layout
+
+\begin_layout Itemize
+CUBIT mesh format
+\end_layout
+
+\begin_layout Itemize
+Absorbing dampers boundary conditions
+\end_layout
+
+\begin_layout Itemize
+Kinematic fault interface conditions
+\end_layout
+
+\begin_layout Itemize
+Dynamic fault interface conditions
+\end_layout
+
+\begin_layout Itemize
+Plane strain linearly elastic material
+\end_layout
+
+\begin_layout Itemize
+VTK output
+\end_layout
+
+\begin_layout Itemize
+Linear quadrilateral cells
+\end_layout
+
+\begin_layout Itemize
+SimpleDB spatial database
+\end_layout
+
+\begin_layout Itemize
+ZeroDispDB spatial database
+\end_layout
+
+\begin_layout Itemize
+UniformDB spatial database
+\end_layout
+
+\begin_layout Standard
+All of the files necessary to run the examples are contained in the directory
+ 
+\family typewriter
+examples/bar_shearwave/quad4.
+\end_layout
+
+\begin_layout Subsection
+Mesh Generation
+\end_layout
+
+\begin_layout Standard
+The mesh is a simple rectangular prism 8 km by 400 m by 400 m (Figure 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "fig:shearwave:quad4:mesh"
+
+\end_inset
+
+).
+ We provide documented CUBIT journal files in 
+\family typewriter
+examples/bar_shearwave/quad4.
+
+\family default
+ We first create the geometry, mesh the domain using quadrilateral cells,
+ and then create blocks and nodesets associated with the materials and boundary
+ conditions.
+\end_layout
+
+\begin_layout Standard
+\noindent
+\align center
+\begin_inset Float figure
+wide false
+sideways false
+status open
+
+\begin_layout Plain Layout
+\align center
+\begin_inset Graphics
+	filename figs/quad4mesh.jpg
+	lyxscale 50
+	scale 50
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Plain Layout
+\begin_inset Caption
+
+\begin_layout Plain Layout
+Mesh composed of hexahedral cells generated by CUBIT used for the example
+ problem.
+\begin_inset CommandInset label
+LatexCommand label
+name "fig:shearwave:quad4:mesh"
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Subsection
+Kinematic Fault
+\end_layout
+
+\begin_layout Standard
+The simulation parameters match those in the tri3, tet4, and hex8 examples.
+ Using four-point quadrature permits use of a time step of 1/20 s, which
+ is slightly larger than the time step of 1/30 s used in the tri3 and tet4
+ simulations.
+ In contrast to the tri3, tet4, and hex8 shear wave examples which only
+ contained a single simulation in a directory, in this example we consider
+ several different simulations.
+ Consequently, we separate the parameters into multiple 
+\family typewriter
+.cfg
+\family default
+ files.
+ The common parameters are placed in 
+\family typewriter
+pylithapp.cfg
+\family default
+ with the parameters specific to the kinematic fault example in 
+\family typewriter
+kinematic.cfg
+\family default
+.
+ To run the problem, simply run PyLith via:
+\end_layout
+
+\begin_layout LyX-Code
+pylith kinematic.cfg
+\end_layout
+
+\begin_layout Standard
+The VTK files will be written to the 
+\family typewriter
+output
+\family default
+ directory with the prefix 
+\family typewriter
+kinematic
+\family default
+.
+ The output includes the displacement field over the entire domain at every
+ other time step (0.10 s), the slip and traction vectors on the fault surface
+ in along-strike and normal directions at every other time step (0.10 s),
+ and the strain and stress tensors for each cell at every 20th time step
+ (1.0 s).
+ If the problem ran correctly, you should be able to generate a figure such
+ as Figure 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "fig:shearwave:quad4:kinematic"
+
+\end_inset
+
+, which was generated using ParaView.
+\end_layout
+
+\begin_layout Standard
+\noindent
+\align center
+\begin_inset Float figure
+wide false
+sideways false
+status open
+
+\begin_layout Plain Layout
+\align center
+\begin_inset Graphics
+	filename figs/quad4kinematic30.jpg
+	lyxscale 50
+	scale 50
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Plain Layout
+\begin_inset Caption
+
+\begin_layout Plain Layout
+Displacement field in the bar at 3.0 s.
+ Deformation has been exaggerated by a factor of 800.
+\begin_inset CommandInset label
+LatexCommand label
+name "fig:shearwave:quad4:kinematic"
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Subsection
+Dynamic Fault
+\end_layout
+
+\begin_layout Standard
+In this set of examples we replace the kinematic fault interface with the
+ dynamic fault interface, resulting in fault slip controlled by a fault-constitu
+tive model.
+ See Section 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "sec:fault:constitutive:models"
+
+\end_inset
+
+ for detailed information about the fault constitutive models available
+ in PyLith.
+ Because this is a dynamic simulation we want the generated shear wave to
+ continue to be absorbed at the ends of the bar, so we drive the fault by
+ imposing initial tractions directly on the fault surface rather than through
+ deformation within the bar.
+ We employ a UniformDB object to specify 6.1 MPa of right-lateral shear and
+ 10.0 MPa of normal compression for the initial fault tractions.
+ The parameters common to the dynamic fault simulations are in 
+\family typewriter
+dynamic.cfg
+\family default
+.
+ We use the explicit time-stepping with a lumped Jacobian matrix.
+ We also request that the fault output include slip, slip rate, and traction
+ fields:
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.timedependent.interfaces.fault.output]
+\end_layout
+
+\begin_layout LyX-Code
+vertex_data_fields = [slip,slip_rate,traction]
+\end_layout
+
+\begin_layout Subsubsection
+Dynamic Fault with Static Friction
+\end_layout
+
+\begin_layout Standard
+The parameters specific to this example are related to the use of the static
+ friction fault constitutive model.
+ We set the fault constitutive model via
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.timedependent.interfaces.fault]
+\end_layout
+
+\begin_layout LyX-Code
+friction = pylith.friction.StaticFriction
+\end_layout
+
+\begin_layout Standard
+and use a UniformDB to set the static friction parameters.
+ We use a coefficient of friction of 0.6 and no cohesion (0 MPa).
+ The parameters specific to this example are in 
+\family typewriter
+dynamic_staticfriction.cfg
+\family default
+, so we run the problem via:
+\end_layout
+
+\begin_layout LyX-Code
+pylith dynamic.cfg dynamic_staticfriction.cfg
+\end_layout
+
+\begin_layout Standard
+The VTK files will be written to the 
+\family typewriter
+output
+\family default
+ directory with the prefix 
+\family typewriter
+staticfriction
+\family default
+.
+ The output includes the displacement and velocity fields over the entire
+ domain at every other time step (0.10 s), the slip, slip rate, and traction
+ vectors on the fault surface in along-strike and normal directions at every
+ other time step (0.10 s), and the strain and stress tensors for each cell
+ at every 20th time step (1.0 s).
+ If the problem ran correctly, you should be able to generate a figure such
+ as Figure 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "fig:shearwave:quad4:staticfriction"
+
+\end_inset
+
+, which was generated using ParaView.
+ The steady-state solution is a constant slip rate of 0.08 m/s, a shear traction
+ of 6.0 MPa on the fault surface, and a uniform shear strain of 2e-5 in the
+ bar with uniform, constant velocities in the y-direction of +0.04 m/s and
+ -0.04 m/s on the -x and +x sides of the fault, respectively.
+\end_layout
+
+\begin_layout Standard
+\noindent
+\align center
+\begin_inset Float figure
+wide false
+sideways false
+status open
+
+\begin_layout Plain Layout
+\align center
+\begin_inset Graphics
+	filename figs/quad4staticfriction30.jpg
+	lyxscale 50
+	scale 50
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Plain Layout
+\begin_inset Caption
+
+\begin_layout Plain Layout
+Velocity field in the bar at 3.0 s for the static friction fault constitutive
+ model.
+ Deformation has been exaggerated by a factor of 800.
+\begin_inset CommandInset label
+LatexCommand label
+name "fig:shearwave:quad4:staticfriction"
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Subsubsection
+Dynamic Fault with Slip-Weakening Friction
+\end_layout
+
+\begin_layout Standard
+The parameters specific to this example are related to the use of the slip-weake
+ning friction fault constitutive model (see Section 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "sec:fault:constitutive:models"
+
+\end_inset
+
+).
+ We set the fault constitutive model via
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.timedependent.interfaces.fault]
+\end_layout
+
+\begin_layout LyX-Code
+friction = pylith.friction.SlipWeakening
+\end_layout
+
+\begin_layout Standard
+and use a UniformDB to set the slip-weakening friction parameters.
+ We use a static coefficient of friction of 0.6, a dynamic coefficient of
+ friction of 0.5, a slip-weakening parameter of 0.2 m, and no cohesion (0
+ MPa).
+ The fault constitutive model is associated with the fault, so we can append
+ the fault constitutive model parameters to the vertex information fields
+ and the fault constitutive model state variables to the vertex data fields:
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.timedependent.interfaces.fault.output]
+\end_layout
+
+\begin_layout LyX-Code
+vertex_info_fields = [strike_dir,normal_dir,initial_traction,static_coefficient,
+\begin_inset Newline newline
+\end_inset
+
+dynamic_coefficient,slip_weakening_parameter,cohesion]
+\end_layout
+
+\begin_layout LyX-Code
+vertex_data_fields = [slip,traction,cumulative_slip,previous_slip]
+\end_layout
+
+\begin_layout Standard
+The parameters specific to this example are in 
+\family typewriter
+dynamic_slipweakening.cfg
+\family default
+, so we run the problem via:
+\end_layout
+
+\begin_layout LyX-Code
+pylith dynamic.cfg dynamic_slipweakening.cfg
+\end_layout
+
+\begin_layout Standard
+The VTK files will be written to the 
+\family typewriter
+output
+\family default
+ directory with the prefix 
+\family typewriter
+slipweakening
+\family default
+.
+ If the problem ran correctly, you should be able to generate a figure such
+ as Figure 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "fig:shearwave:quad4:slipweakening"
+
+\end_inset
+
+, which was generated using ParaView.
+ The steady-state solution is a constant slip rate of 0.88 m/s and shear
+ traction of 5.0 MPa on the fault surface, a uniform shear strain of 2.2e-4
+ in the bar with uniform, constant velocities in the y-direction of +0.44
+ m/s and -0.44 m/s on the -x and +x sides of the fault, respectively.
+\end_layout
+
+\begin_layout Standard
+\noindent
+\align center
+\begin_inset Float figure
+wide false
+sideways false
+status open
+
+\begin_layout Plain Layout
+\align center
+\begin_inset Graphics
+	filename figs/quad4slipweakening30.jpg
+	lyxscale 50
+	scale 50
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Plain Layout
+\begin_inset Caption
+
+\begin_layout Plain Layout
+Velocity field in the bar at 3.0 s for the slip-weakening friction fault
+ constitutive model.
+ Deformation has been exaggerated by a factor of 800.
+\begin_inset CommandInset label
+LatexCommand label
+name "fig:shearwave:quad4:slipweakening"
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Subsubsection
+Dynamic Fault with Rate-State Friction
+\end_layout
+
+\begin_layout Standard
+The parameters specific to this example are related to the use of the rate-
+ and state-friction fault constitutive model (see Section 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "sec:fault:constitutive:models"
+
+\end_inset
+
+).
+ The evolution of the state variable uses the aging law.
+ We set the fault constitutive model via
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.timedependent.interfaces.fault]
+\end_layout
+
+\begin_layout LyX-Code
+friction = pylith.friction.RateStateAgeing
+\end_layout
+
+\begin_layout Standard
+and use a UniformDB to set the static friction parameters.
+ We use a reference coefficient of friction of 0.6, reference slip rate of
+ 1.0e-6 m/s, characteristic slip distance of 0.037 m, coefficients a and b
+ of 0.0125 and 0.0172, and no cohesion (0 MPa).
+ The parameters specific to this example are in 
+\family typewriter
+dynamic_ratestateageing.cfg
+\family default
+, so we run the problem via:
+\end_layout
+
+\begin_layout LyX-Code
+pylith dynamic.cfg dynamic_ratestateageing.cfg
+\end_layout
+
+\begin_layout Standard
+The VTK files will be written to the 
+\family typewriter
+output
+\family default
+ directory with the prefix 
+\family typewriter
+ratestateageing
+\family default
+.
+ If the problem ran correctly, you should be able to generate a figure such
+ as Figure 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "fig:shearwave:quad4:ratestateageing"
+
+\end_inset
+
+, which was generated using ParaView.
+ The steady-state solution is a constant slip rate of 0.572 m/s and shear
+ traction of 5.385 MPa on the fault surface, a uniform shear strain of 1.43e-4
+ in the bar with uniform, constant velocities in the y-direction of +0.286
+ m/s and -0.286 m/s on the -x and +x sides of the fault, respectively.
+\end_layout
+
+\begin_layout Standard
+\noindent
+\align center
+\begin_inset Float figure
+wide false
+sideways false
+status open
+
+\begin_layout Plain Layout
+\align center
+\begin_inset Graphics
+	filename figs/quad4ratestateageing30.jpg
+	lyxscale 50
+	scale 50
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Plain Layout
+\begin_inset Caption
+
+\begin_layout Plain Layout
+Velocity field in the bar at 3.0 s for the rate- and state-friction fault
+ constitutive model.
+ Deformation has been exaggerated by a factor of 800.
+\begin_inset CommandInset label
+LatexCommand label
+name "fig:shearwave:quad4:ratestateageing"
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\end_body
+\end_document

Modified: short/3D/PyLith/branches/v1.7-trunk/doc/userguide/tutorials/shearwave/shearwave.lyx
===================================================================
--- short/3D/PyLith/branches/v1.7-trunk/doc/userguide/tutorials/shearwave/shearwave.lyx	2012-06-25 04:52:47 UTC (rev 20403)
+++ short/3D/PyLith/branches/v1.7-trunk/doc/userguide/tutorials/shearwave/shearwave.lyx	2012-06-25 16:38:44 UTC (rev 20404)
@@ -1,162 +1,180 @@
-#LyX 1.6.5 created this file. For more info see http://www.lyx.org/
-\lyxformat 345
-\begin_document
-\begin_header
-\textclass book
-\begin_preamble
-
-\end_preamble
-\use_default_options false
-\language english
-\inputencoding latin1
-\font_roman default
-\font_sans default
-\font_typewriter default
-\font_default_family default
-\font_sc false
-\font_osf false
-\font_sf_scale 100
-\font_tt_scale 100
-
-\graphics default
-\paperfontsize default
-\spacing single
-\use_hyperref false
-\papersize default
-\use_geometry true
-\use_amsmath 1
-\use_esint 0
-\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
-\author "" 
-\author "" 
-\end_header
-
-\begin_body
-
-\begin_layout Section
-Shear Wave in a Bar
-\end_layout
-
-\begin_layout Standard
-This suite of examples focuses on the dynamics of a shear wave propagating
- down an 8 km long bar with a 400 m wide cross-section.
- Motion is limited to shear deformation by fixing the longitudinal degree
- of freedom.
- For each cell type (tri3, quad4, tet4, and hex8) we generate a shear wave
- using a kinematic fault rupture with simultaneous slip over the fault surface,
- which we place at the center of the bar.
- The discretization size is 200 m in all cases.
- The slip time histories follow the integral of Brune's far-field time function
- with slip initiating at 0.1 s, a left-lateral final slip of 1.0 m, and a
- rise time of 2.0 s.
- The shear wave speed in the bar is 1.0 km/s, so the shear wave reaches each
- end of the bar at 4.1 s.
- Absorbing boundaries on the ends of the bar prevent significant reflections.
- The bar comes to a rest with a static offset.
-\end_layout
-
-\begin_layout Standard
-\begin_inset Float figure
-wide false
-sideways false
-status collapsed
-
-\begin_layout Plain Layout
-\align center
-\begin_inset Graphics
-	filename figs/bar.eps
-	lyxscale 50
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Plain Layout
-\begin_inset Caption
-
-\begin_layout Plain Layout
-Domain for shear wave propagation in a 8.0 km bar with 400 m cross-section.
- We generate a shear wave via slip on a fault located in the middle of the
- bar while limiting deformation to the transverse direction.
-\begin_inset CommandInset label
-LatexCommand label
-name "fig:shearwave:domain"
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-For the bar discretized with quad4 cells we also consider the fault subjected
- to frictional sliding controlled by static friction, linear slip-weakening
- friction, and rate- and state-friction.
- We use initial tractions applied to the fault to drive the dislocation
- and generate the shear wave.
- Because the fault tractions are constant in time, they continue to drive
- the motion even after the shear wave reaches the absorbing boundary, leading
- to a steady state solution with uniform shear deformation in the bar and
- a constant slip rate on the fault.
- 
-\end_layout
-
-\begin_layout Standard
-\begin_inset CommandInset include
-LatexCommand input
-filename "tri3.lyx"
-
-\end_inset
-
-
-\begin_inset CommandInset include
-LatexCommand input
-filename "tet4.lyx"
-
-\end_inset
-
-
-\begin_inset CommandInset include
-LatexCommand input
-filename "hex8.lyx"
-
-\end_inset
-
-
-\begin_inset CommandInset include
-LatexCommand input
-filename "quad4.lyx"
-
-\end_inset
-
-
-\end_layout
-
-\end_body
-\end_document
+#LyX 2.0 created this file. For more info see http://www.lyx.org/
+\lyxformat 413
+\begin_document
+\begin_header
+\textclass book
+\begin_preamble
+
+\end_preamble
+\use_default_options false
+\maintain_unincluded_children false
+\language english
+\language_package default
+\inputencoding latin1
+\fontencoding global
+\font_roman default
+\font_sans default
+\font_typewriter default
+\font_default_family default
+\use_non_tex_fonts false
+\font_sc false
+\font_osf false
+\font_sf_scale 100
+\font_tt_scale 100
+
+\graphics default
+\default_output_format default
+\output_sync 0
+\bibtex_command default
+\index_command default
+\paperfontsize default
+\spacing single
+\use_hyperref false
+\papersize default
+\use_geometry true
+\use_amsmath 1
+\use_esint 0
+\use_mhchem 1
+\use_mathdots 1
+\cite_engine basic
+\use_bibtopic false
+\use_indices false
+\paperorientation portrait
+\suppress_date false
+\use_refstyle 0
+\index Index
+\shortcut idx
+\color #008000
+\end_index
+\leftmargin 1in
+\topmargin 1in
+\rightmargin 1in
+\bottommargin 2in
+\secnumdepth 3
+\tocdepth 3
+\paragraph_separation indent
+\paragraph_indentation default
+\quotes_language english
+\papercolumns 1
+\papersides 2
+\paperpagestyle default
+\tracking_changes false
+\output_changes false
+\html_math_output 0
+\html_css_as_file 0
+\html_be_strict false
+\end_header
+
+\begin_body
+
+\begin_layout Section
+Shear Wave in a Bar
+\end_layout
+
+\begin_layout Standard
+This suite of examples focuses on the dynamics of a shear wave propagating
+ down an 8 km-long bar with a 400 m-wide cross-section.
+ Motion is limited to shear deformation by fixing the longitudinal degree
+ of freedom.
+ For each cell type (tri3, quad4, tet4, and hex8) we generate a shear wave
+ using a kinematic fault rupture with simultaneous slip over the fault surface,
+ which we place at the center of the bar.
+ The discretization size is 200 m in all cases.
+ The slip-time histories follow the integral of Brune's far-field time function
+ with slip initiating at 0.1 s, a left-lateral final slip of 1.0 m, and a
+ rise time of 2.0 s.
+ The shear wave speed in the bar is 1.0 km/s, so the shear wave reaches each
+ end of the bar at 4.1 s.
+ Absorbing boundaries on the ends of the bar prevent significant reflections.
+ The bar comes to a rest with a static offset.
+\end_layout
+
+\begin_layout Standard
+\begin_inset Float figure
+wide false
+sideways false
+status collapsed
+
+\begin_layout Plain Layout
+\align center
+\begin_inset Graphics
+	filename figs/bar.eps
+	lyxscale 50
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Plain Layout
+\begin_inset Caption
+
+\begin_layout Plain Layout
+Domain for shear wave propagation in a 8.0 km bar with 400 m cross-section.
+ We generate a shear wave via slip on a fault located in the middle of the
+ bar while limiting deformation to the transverse direction.
+\begin_inset CommandInset label
+LatexCommand label
+name "fig:shearwave:domain"
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+For the bar discretized with quad4 cells we also consider the fault subjected
+ to frictional sliding controlled by static friction, linear slip-weakening
+ friction, and rate- and state-friction.
+ We use initial tractions applied to the fault to drive the dislocation
+ and generate the shear wave.
+ Because the fault tractions are constant in time, they continue to drive
+ the motion even after the shear wave reaches the absorbing boundary, leading
+ to a steady state solution with uniform shear deformation in the bar and
+ a constant slip rate on the fault.
+ 
+\end_layout
+
+\begin_layout Standard
+\begin_inset CommandInset include
+LatexCommand input
+filename "tri3.lyx"
+
+\end_inset
+
+
+\begin_inset CommandInset include
+LatexCommand input
+filename "tet4.lyx"
+
+\end_inset
+
+
+\begin_inset CommandInset include
+LatexCommand input
+filename "hex8.lyx"
+
+\end_inset
+
+
+\begin_inset CommandInset include
+LatexCommand input
+filename "quad4.lyx"
+
+\end_inset
+
+
+\end_layout
+
+\end_body
+\end_document

Modified: short/3D/PyLith/branches/v1.7-trunk/doc/userguide/tutorials/shearwave/tet4.lyx
===================================================================
--- short/3D/PyLith/branches/v1.7-trunk/doc/userguide/tutorials/shearwave/tet4.lyx	2012-06-25 04:52:47 UTC (rev 20403)
+++ short/3D/PyLith/branches/v1.7-trunk/doc/userguide/tutorials/shearwave/tet4.lyx	2012-06-25 16:38:44 UTC (rev 20404)
@@ -1,284 +1,288 @@
-#LyX 2.0 created this file. For more info see http://www.lyx.org/
-\lyxformat 413
-\begin_document
-\begin_header
-\textclass book
-\begin_preamble
-
-\end_preamble
-\use_default_options false
-\maintain_unincluded_children false
-\language english
-\language_package default
-\inputencoding latin1
-\fontencoding global
-\font_roman default
-\font_sans default
-\font_typewriter default
-\font_default_family default
-\use_non_tex_fonts false
-\font_sc false
-\font_osf false
-\font_sf_scale 100
-\font_tt_scale 100
-
-\graphics default
-\default_output_format default
-\output_sync 0
-\bibtex_command default
-\index_command default
-\paperfontsize default
-\spacing single
-\use_hyperref false
-\papersize default
-\use_geometry true
-\use_amsmath 0
-\use_esint 0
-\use_mhchem 1
-\use_mathdots 1
-\cite_engine basic
-\use_bibtopic false
-\use_indices false
-\paperorientation portrait
-\suppress_date false
-\use_refstyle 0
-\index Index
-\shortcut idx
-\color #008000
-\end_index
-\leftmargin 1in
-\topmargin 1in
-\rightmargin 1in
-\bottommargin 1in
-\secnumdepth 3
-\tocdepth 3
-\paragraph_separation indent
-\paragraph_indentation default
-\quotes_language english
-\papercolumns 1
-\papersides 1
-\paperpagestyle default
-\tracking_changes false
-\output_changes false
-\html_math_output 0
-\html_css_as_file 0
-\html_be_strict false
-\end_header
-
-\begin_body
-
-\begin_layout Section
-\begin_inset CommandInset label
-LatexCommand label
-name "sec:tutorial:shearwave:tet4"
-
-\end_inset
-
-3-D Bar Discretized with Tetrahedra
-\end_layout
-
-\begin_layout Standard
-PyLith features discussed in this tutorial:
-\end_layout
-
-\begin_layout Itemize
-Dynamic solution
-\end_layout
-
-\begin_layout Itemize
-LaGriT mesh format
-\end_layout
-
-\begin_layout Itemize
-Absorbing dampers boundary conditions
-\end_layout
-
-\begin_layout Itemize
-Kinematic fault interface conditions
-\end_layout
-
-\begin_layout Itemize
-Elastic isotropic linearly elastic material
-\end_layout
-
-\begin_layout Itemize
-VTK output
-\end_layout
-
-\begin_layout Itemize
-Linear tetrahedral cells
-\end_layout
-
-\begin_layout Itemize
-SimpleDB spatial database
-\end_layout
-
-\begin_layout Itemize
-ZeroDispDB spatial database
-\end_layout
-
-\begin_layout Standard
-All of the files necessary to run the examples are contained in the directory
- 
-\family typewriter
-examples/bar_shearwave/tet4.
-\end_layout
-
-\begin_layout Subsection
-Mesh Generation
-\end_layout
-
-\begin_layout Standard
-The mesh is a simple rectangular prism 8 km by 400 m by 400m (Figure 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "fig:shearwave:tet4:mesh"
-
-\end_inset
-
-).
- This mesh could be generated via a simple script, but it is even easier
- to generate this mesh using LaGriT.
- We provide documented LaGriT files in 
-\family typewriter
-examples/bar_shearwave/tet4.
-
-\family default
- We first create the geometry, regions, mesh the domain using tetrahedral
- cells, and then create point sets associated with boundary conditions.
-\end_layout
-
-\begin_layout Standard
-\noindent
-\align center
-\begin_inset Float figure
-wide false
-sideways false
-status open
-
-\begin_layout Plain Layout
-\align center
-\begin_inset Graphics
-	filename figs/tet4mesh.jpg
-	lyxscale 50
-	scale 50
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Plain Layout
-\begin_inset Caption
-
-\begin_layout Plain Layout
-Mesh composed of tetrahedral cells generated by LaGriT used for the example
- problem.
-\begin_inset CommandInset label
-LatexCommand label
-name "fig:shearwave:tet4:mesh"
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Subsection
-Simulation Parameters
-\end_layout
-
-\begin_layout Standard
-The simulation parameters match those in the tri3 example with the exception
- of using the LaGriT mesh reader and switching the from a two-dimensional
- problem to a three-dimensional problem.
- In addition to fixing the longitudinal degree of freedom, we also fix the
- out-of-plane transverse degree of freedom.
- Because the fault separates two material regions in LaGriT, we use two
- materials in PyLith.
- All of the parameters are set in the pylithapp.cfg file.
- To run the problem, simply run PyLith without any command line arguments:
-\end_layout
-
-\begin_layout LyX-Code
-pylith
-\end_layout
-
-\begin_layout Standard
-The VTK files will be written to the 
-\family typewriter
-output
-\family default
- directory.
- The output includes the displacement and velocity fields over the entire
- domain at every 3rd time step (0.10 s), the slip and change in traction
- vectors on the fault surface in along-strike and normal directions at every
- 3rd time step (0.10 s), and the strain and stress tensors for each cell
- at every 30th time step (1.0 s).
- If the problem ran correctly, you should be able to generate a figure such
- as Figure 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "fig:shearwave:tet4:deform"
-
-\end_inset
-
-, which was generated using ParaView.
-\end_layout
-
-\begin_layout Standard
-\noindent
-\align center
-\begin_inset Float figure
-wide false
-sideways false
-status open
-
-\begin_layout Plain Layout
-\align center
-\begin_inset Graphics
-	filename figs/tet4deform30.jpg
-	lyxscale 50
-	scale 50
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Plain Layout
-\begin_inset Caption
-
-\begin_layout Plain Layout
-Displacement field in the bar at 3.0 s.
- Deformation has been exaggerated by a factor of 800.
-\begin_inset CommandInset label
-LatexCommand label
-name "fig:shearwave:tet4:deform"
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_body
-\end_document
+#LyX 2.0 created this file. For more info see http://www.lyx.org/
+\lyxformat 413
+\begin_document
+\begin_header
+\textclass book
+\begin_preamble
+
+\end_preamble
+\use_default_options false
+\maintain_unincluded_children false
+\language english
+\language_package default
+\inputencoding latin1
+\fontencoding global
+\font_roman default
+\font_sans default
+\font_typewriter default
+\font_default_family default
+\use_non_tex_fonts false
+\font_sc false
+\font_osf false
+\font_sf_scale 100
+\font_tt_scale 100
+
+\graphics default
+\default_output_format default
+\output_sync 0
+\bibtex_command default
+\index_command default
+\paperfontsize default
+\spacing single
+\use_hyperref false
+\papersize default
+\use_geometry true
+\use_amsmath 0
+\use_esint 0
+\use_mhchem 1
+\use_mathdots 1
+\cite_engine basic
+\use_bibtopic false
+\use_indices false
+\paperorientation portrait
+\suppress_date false
+\use_refstyle 0
+\index Index
+\shortcut idx
+\color #008000
+\end_index
+\leftmargin 1in
+\topmargin 1in
+\rightmargin 1in
+\bottommargin 1in
+\secnumdepth 3
+\tocdepth 3
+\paragraph_separation indent
+\paragraph_indentation default
+\quotes_language english
+\papercolumns 1
+\papersides 1
+\paperpagestyle default
+\tracking_changes false
+\output_changes false
+\html_math_output 0
+\html_css_as_file 0
+\html_be_strict false
+\end_header
+
+\begin_body
+
+\begin_layout Section
+\begin_inset CommandInset label
+LatexCommand label
+name "sec:tutorial:shearwave:tet4"
+
+\end_inset
+
+3D Bar Discretized with Tetrahedra
+\end_layout
+
+\begin_layout Standard
+PyLith features discussed in this tutorial:
+\end_layout
+
+\begin_layout Itemize
+Dynamic solution
+\end_layout
+
+\begin_layout Itemize
+LaGriT mesh format
+\end_layout
+
+\begin_layout Itemize
+Absorbing dampers boundary conditions
+\end_layout
+
+\begin_layout Itemize
+Kinematic fault interface conditions
+\end_layout
+
+\begin_layout Itemize
+Elastic isotropic linearly elastic material
+\end_layout
+
+\begin_layout Itemize
+VTK output
+\end_layout
+
+\begin_layout Itemize
+Linear tetrahedral cells
+\end_layout
+
+\begin_layout Itemize
+SimpleDB spatial database
+\end_layout
+
+\begin_layout Itemize
+ZeroDispDB spatial database
+\end_layout
+
+\begin_layout Standard
+All of the files necessary to run the examples are contained in the directory
+ 
+\family typewriter
+examples/bar_shearwave/tet4.
+\end_layout
+
+\begin_layout Subsection
+Mesh Generation
+\end_layout
+
+\begin_layout Standard
+The mesh is a simple rectangular prism 8 km by 400 m by 400m (Figure 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "fig:shearwave:tet4:mesh"
+
+\end_inset
+
+).
+ This mesh could be generated via a simple script, but it is even easier
+ to generate this mesh using LaGriT.
+ We provide documented LaGriT files in 
+\family typewriter
+examples/bar_shearwave/tet4.
+
+\family default
+ We first create the geometry and regions, mesh the domain using tetrahedral
+ cells, and then create point sets associated with boundary conditions.
+\end_layout
+
+\begin_layout Standard
+\noindent
+\align center
+\begin_inset Float figure
+wide false
+sideways false
+status open
+
+\begin_layout Plain Layout
+\align center
+\begin_inset Graphics
+	filename figs/tet4mesh.jpg
+	lyxscale 50
+	scale 50
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Plain Layout
+\begin_inset Caption
+
+\begin_layout Plain Layout
+Mesh composed of tetrahedral cells generated by LaGriT used for the example
+ problem.
+\begin_inset CommandInset label
+LatexCommand label
+name "fig:shearwave:tet4:mesh"
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Subsection
+Simulation Parameters
+\end_layout
+
+\begin_layout Standard
+The simulation parameters match those in the tri3 example with the exception
+ of using the LaGriT mesh reader and switching from a two-dimensional problem
+ to a three-dimensional problem.
+ In addition to fixing the longitudinal degree of freedom, we also fix the
+ out-of-plane transverse degree of freedom.
+ Because the fault separates two material regions in LaGriT, we use two
+ materials in PyLith.
+ All of the parameters are set in the 
+\family typewriter
+pylithapp.cfg
+\family default
+ file.
+ To run the problem, simply run PyLith without any command line arguments:
+\end_layout
+
+\begin_layout LyX-Code
+pylith
+\end_layout
+
+\begin_layout Standard
+The VTK files will be written to the 
+\family typewriter
+output
+\family default
+ directory.
+ The output includes the displacement and velocity fields over the entire
+ domain at every 3rd time step (0.10 s), the slip and change in traction
+ vectors on the fault surface in along-strike and normal directions at every
+ 3rd time step (0.10 s), and the strain and stress tensors for each cell
+ at every 30th time step (1.0 s).
+ If the problem ran correctly, you should be able to generate a figure such
+ as Figure 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "fig:shearwave:tet4:deform"
+
+\end_inset
+
+, which was generated using ParaView.
+\end_layout
+
+\begin_layout Standard
+\noindent
+\align center
+\begin_inset Float figure
+wide false
+sideways false
+status open
+
+\begin_layout Plain Layout
+\align center
+\begin_inset Graphics
+	filename figs/tet4deform30.jpg
+	lyxscale 50
+	scale 50
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Plain Layout
+\begin_inset Caption
+
+\begin_layout Plain Layout
+Displacement field in the bar at 3.0 s.
+ Deformation has been exaggerated by a factor of 800.
+\begin_inset CommandInset label
+LatexCommand label
+name "fig:shearwave:tet4:deform"
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\end_body
+\end_document

Modified: short/3D/PyLith/branches/v1.7-trunk/doc/userguide/tutorials/shearwave/tri3.lyx
===================================================================
--- short/3D/PyLith/branches/v1.7-trunk/doc/userguide/tutorials/shearwave/tri3.lyx	2012-06-25 04:52:47 UTC (rev 20403)
+++ short/3D/PyLith/branches/v1.7-trunk/doc/userguide/tutorials/shearwave/tri3.lyx	2012-06-25 16:38:44 UTC (rev 20404)
@@ -1,348 +1,352 @@
-#LyX 2.0 created this file. For more info see http://www.lyx.org/
-\lyxformat 413
-\begin_document
-\begin_header
-\textclass book
-\begin_preamble
-
-\end_preamble
-\use_default_options false
-\maintain_unincluded_children false
-\language english
-\language_package default
-\inputencoding latin1
-\fontencoding global
-\font_roman default
-\font_sans default
-\font_typewriter default
-\font_default_family default
-\use_non_tex_fonts false
-\font_sc false
-\font_osf false
-\font_sf_scale 100
-\font_tt_scale 100
-
-\graphics default
-\default_output_format default
-\output_sync 0
-\bibtex_command default
-\index_command default
-\paperfontsize default
-\spacing single
-\use_hyperref false
-\papersize default
-\use_geometry true
-\use_amsmath 0
-\use_esint 0
-\use_mhchem 1
-\use_mathdots 1
-\cite_engine basic
-\use_bibtopic false
-\use_indices false
-\paperorientation portrait
-\suppress_date false
-\use_refstyle 0
-\index Index
-\shortcut idx
-\color #008000
-\end_index
-\leftmargin 1in
-\topmargin 1in
-\rightmargin 1in
-\bottommargin 1in
-\secnumdepth 3
-\tocdepth 3
-\paragraph_separation indent
-\paragraph_indentation default
-\quotes_language english
-\papercolumns 1
-\papersides 1
-\paperpagestyle default
-\tracking_changes false
-\output_changes false
-\html_math_output 0
-\html_css_as_file 0
-\html_be_strict false
-\end_header
-
-\begin_body
-
-\begin_layout Section
-\begin_inset CommandInset label
-LatexCommand label
-name "sec:tutorial:shearwave:tri3"
-
-\end_inset
-
-2-D Bar Discretized with Triangles
-\end_layout
-
-\begin_layout Standard
-PyLith features discussed in this tutorial:
-\end_layout
-
-\begin_layout Itemize
-Dynamic solution
-\end_layout
-
-\begin_layout Itemize
-CUBIT format
-\end_layout
-
-\begin_layout Itemize
-Absorbing dampers boundary conditions
-\end_layout
-
-\begin_layout Itemize
-Kinematic fault interface conditions
-\end_layout
-
-\begin_layout Itemize
-Plane strain linearly elastic material
-\end_layout
-
-\begin_layout Itemize
-VTK output
-\end_layout
-
-\begin_layout Itemize
-Linear triangular cells
-\end_layout
-
-\begin_layout Itemize
-SimpleDB spatial database
-\end_layout
-
-\begin_layout Itemize
-ZeroDispDB spatial database
-\end_layout
-
-\begin_layout Standard
-All of the files necessary to run the examples are contained in the directory
- 
-\family typewriter
-examples/bar_shearwave/tri3.
-\end_layout
-
-\begin_layout Subsection
-Mesh Generation
-\end_layout
-
-\begin_layout Standard
-The mesh is a simple rectangle 8 km by 400 m (Figure 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "fig:shearwave:tet4:mesh"
-
-\end_inset
-
-).
- This mesh could be generated via a simple script, but it is even easier
- to generate this mesh using CUBIT.
- We provide documented journal files in 
-\family typewriter
-examples/bar_shearwave/tri3.
-
-\family default
- We first create the geometry, mesh the domain using triangular cells, and
- then create blocks and nodesets to associated the cells and vertices with
- materials and boundary conditions.
- See Section 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "sec:Tutorial-3d-hex8"
-
-\end_inset
-
- for more information on using CUBIT to generate meshes.
-\end_layout
-
-\begin_layout Standard
-\noindent
-\align center
-\begin_inset Float figure
-wide false
-sideways false
-status open
-
-\begin_layout Plain Layout
-\align center
-\begin_inset Graphics
-	filename figs/tri3mesh.jpg
-	lyxscale 50
-	scale 50
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Plain Layout
-\begin_inset Caption
-
-\begin_layout Plain Layout
-Mesh composed of triangular cells generated by CUBIT used for the example
- problem.
-\begin_inset CommandInset label
-LatexCommand label
-name "fig:shearwave:tri3:mesh"
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Subsection
-Simulation Parameters
-\end_layout
-
-\begin_layout Standard
-All of the parameters are set in the pylithapp.cfg file.
- The structure of the file follows the same pattern as in all of the other
- examples.
- We set the parameters for the journal information followed by the mesh
- reader, problem, materials, boundary conditions, fault, and output.
- We change the time-stepping formulation from the default value of implicit
- time stepping to explicit time stepping by setting the formulation object
- via
-\end_layout
-
-\begin_layout LyX-Code
-formulation = pylith.problems.Explicit
-\end_layout
-
-\begin_layout Standard
-We can switch to explicit time stepping with a lumped Jacobian matrix (rather
- than the full Jacobian matrix) by changing Explicit to ExplicitLumped.
- Using the ExplicitLumped object automatically triggers lumping of the Jacobian
- cell matrices and assembly into a vector rather than a sparse matrix.
- Lumping the Jacobian decouples the equations, so we can use a very simple
- direct solver.
- Use of this simple solver is also triggered by the selection of the ExplicitLum
-ped object.
- 
-\end_layout
-
-\begin_layout Standard
-For dynamic problems we use the NondimElasticDynamic object to nondimensionalize
- the equations.
- This object provides scales associated with wave propagation for nondimensional
-ization, including the minimum wave period, the shear wave speed, and mass
- density.
- In this example we use the default values of a minimum wave period of 1.0
- s, a shear wave speed of 3 km/s, and a mass density of 3000 kg/m
-\begin_inset Formula $^{3}$
-\end_inset
-
-.
- We simulate 12.0 s of motion with a time step of 1/30 s.
- This time step must follow the Courant–Friedrichs–Lewy condition; that
- is, the time step must be smaller than the time it takes the P wave to
- propagate across the shortest edge of a cell.
- 
-\end_layout
-
-\begin_layout Standard
-The boundary conditions include the absorbing dampers at the ends of the
- bar and a Dirichlet boundary condition to prevent longitudinal motion.
- Because we cannot overlap the Dirichlet BC with the fault, we use the nodeset
- associated with all vertices except the fault.
- For the output over the entire domain, we request both displacement and
- velocity fields:
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.timedependent.output]
-\end_layout
-
-\begin_layout LyX-Code
-vertex_data_fields = [displacement,velocity]
-\end_layout
-
-\begin_layout Standard
-To run the problem, simply run PyLith without any command line arguments:
-\end_layout
-
-\begin_layout LyX-Code
-pylith
-\end_layout
-
-\begin_layout Standard
-The VTK files will be written to the 
-\family typewriter
-output
-\family default
- directory.
- The output includes the displacement and velocity fields over the entire
- domain at every 3rd time step (0.10 s), the slip and change in traction
- vectors on the fault surface in along-strike and normal directions at every
- 3rd time step (0.10 s), and the strain and stress tensors for each cell
- at every 30th time step (1.0 s).
- If the problem ran correctly, you should be able to generate a figure such
- as Figure 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "fig:shearwave:tri3:deform"
-
-\end_inset
-
-, which was generated using ParaView.
-\end_layout
-
-\begin_layout Standard
-\noindent
-\align center
-\begin_inset Float figure
-wide false
-sideways false
-status open
-
-\begin_layout Plain Layout
-\align center
-\begin_inset Graphics
-	filename figs/tri3deform30.jpg
-	lyxscale 50
-	scale 50
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Plain Layout
-\begin_inset Caption
-
-\begin_layout Plain Layout
-Displacement field in the bar at 3.0 s.
- Deformation has been exaggerated by a factor of 800.
-\begin_inset CommandInset label
-LatexCommand label
-name "fig:shearwave:tri3:deform"
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_body
-\end_document
+#LyX 2.0 created this file. For more info see http://www.lyx.org/
+\lyxformat 413
+\begin_document
+\begin_header
+\textclass book
+\begin_preamble
+
+\end_preamble
+\use_default_options false
+\maintain_unincluded_children false
+\language english
+\language_package default
+\inputencoding latin1
+\fontencoding global
+\font_roman default
+\font_sans default
+\font_typewriter default
+\font_default_family default
+\use_non_tex_fonts false
+\font_sc false
+\font_osf false
+\font_sf_scale 100
+\font_tt_scale 100
+
+\graphics default
+\default_output_format default
+\output_sync 0
+\bibtex_command default
+\index_command default
+\paperfontsize default
+\spacing single
+\use_hyperref false
+\papersize default
+\use_geometry true
+\use_amsmath 0
+\use_esint 0
+\use_mhchem 1
+\use_mathdots 1
+\cite_engine basic
+\use_bibtopic false
+\use_indices false
+\paperorientation portrait
+\suppress_date false
+\use_refstyle 0
+\index Index
+\shortcut idx
+\color #008000
+\end_index
+\leftmargin 1in
+\topmargin 1in
+\rightmargin 1in
+\bottommargin 1in
+\secnumdepth 3
+\tocdepth 3
+\paragraph_separation indent
+\paragraph_indentation default
+\quotes_language english
+\papercolumns 1
+\papersides 1
+\paperpagestyle default
+\tracking_changes false
+\output_changes false
+\html_math_output 0
+\html_css_as_file 0
+\html_be_strict false
+\end_header
+
+\begin_body
+
+\begin_layout Section
+\begin_inset CommandInset label
+LatexCommand label
+name "sec:tutorial:shearwave:tri3"
+
+\end_inset
+
+2D Bar Discretized with Triangles
+\end_layout
+
+\begin_layout Standard
+PyLith features discussed in this tutorial:
+\end_layout
+
+\begin_layout Itemize
+Dynamic solution
+\end_layout
+
+\begin_layout Itemize
+CUBIT format
+\end_layout
+
+\begin_layout Itemize
+Absorbing dampers boundary conditions
+\end_layout
+
+\begin_layout Itemize
+Kinematic fault interface conditions
+\end_layout
+
+\begin_layout Itemize
+Plane strain linearly elastic material
+\end_layout
+
+\begin_layout Itemize
+VTK output
+\end_layout
+
+\begin_layout Itemize
+Linear triangular cells
+\end_layout
+
+\begin_layout Itemize
+SimpleDB spatial database
+\end_layout
+
+\begin_layout Itemize
+ZeroDispDB spatial database
+\end_layout
+
+\begin_layout Standard
+All of the files necessary to run the examples are contained in the directory
+ 
+\family typewriter
+examples/bar_shearwave/tri3.
+\end_layout
+
+\begin_layout Subsection
+Mesh Generation
+\end_layout
+
+\begin_layout Standard
+The mesh is a simple rectangle 8 km by 400 m (Figure 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "fig:shearwave:tet4:mesh"
+
+\end_inset
+
+).
+ This mesh could be generated via a simple script, but it is even easier
+ to generate this mesh using CUBIT.
+ We provide documented journal files in 
+\family typewriter
+examples/bar_shearwave/tri3.
+
+\family default
+ We first create the geometry, mesh the domain using triangular cells, and
+ then create blocks and nodesets to associate the cells and vertices with
+ materials and boundary conditions.
+ See Section 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "sec:Tutorial-3d-hex8"
+
+\end_inset
+
+ for more information on using CUBIT to generate meshes.
+\end_layout
+
+\begin_layout Standard
+\noindent
+\align center
+\begin_inset Float figure
+wide false
+sideways false
+status open
+
+\begin_layout Plain Layout
+\align center
+\begin_inset Graphics
+	filename figs/tri3mesh.jpg
+	lyxscale 50
+	scale 50
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Plain Layout
+\begin_inset Caption
+
+\begin_layout Plain Layout
+Mesh composed of triangular cells generated by CUBIT used for the example
+ problem.
+\begin_inset CommandInset label
+LatexCommand label
+name "fig:shearwave:tri3:mesh"
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Subsection
+Simulation Parameters
+\end_layout
+
+\begin_layout Standard
+All of the parameters are set in the 
+\family typewriter
+pylithapp.cfg
+\family default
+ file.
+ The structure of the file follows the same pattern as in all of the other
+ examples.
+ We set the parameters for the journal information followed by the mesh
+ reader, problem, materials, boundary conditions, fault, and output.
+ We change the time-stepping formulation from the default value of implicit
+ time stepping to explicit time stepping by setting the formulation object
+ via
+\end_layout
+
+\begin_layout LyX-Code
+formulation = pylith.problems.Explicit
+\end_layout
+
+\begin_layout Standard
+We can switch to explicit time stepping with a lumped Jacobian matrix (rather
+ than the full Jacobian matrix) by changing Explicit to ExplicitLumped.
+ Using the ExplicitLumped object automatically triggers lumping of the Jacobian
+ cell matrices and assembly into a vector rather than a sparse matrix.
+ Lumping the Jacobian decouples the equations, so we can use a very simple
+ direct solver.
+ Use of this simple solver is also triggered by the selection of the ExplicitLum
+ped object.
+ 
+\end_layout
+
+\begin_layout Standard
+For dynamic problems we use the NondimElasticDynamic object to nondimensionalize
+ the equations.
+ This object provides scales associated with wave propagation for nondimensional
+ization, including the minimum wave period, the shear wave speed, and mass
+ density.
+ In this example we use the default values of a minimum wave period of 1.0
+ s, a shear wave speed of 3 km/s, and a mass density of 3000 kg/m
+\begin_inset Formula $^{3}$
+\end_inset
+
+.
+ We simulate 12.0 s of motion with a time step of 1/30 s.
+ This time step must follow the Courant–Friedrichs–Lewy condition; that
+ is, the time step must be smaller than the time it takes the P wave to
+ propagate across the shortest edge of a cell.
+ 
+\end_layout
+
+\begin_layout Standard
+The boundary conditions include the absorbing dampers at the ends of the
+ bar and a Dirichlet boundary condition to prevent longitudinal motion.
+ Because we cannot overlap the Dirichlet BC with the fault, we use the nodeset
+ associated with all vertices except the fault.
+ For the output over the entire domain, we request both displacement and
+ velocity fields:
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.timedependent.output]
+\end_layout
+
+\begin_layout LyX-Code
+vertex_data_fields = [displacement,velocity]
+\end_layout
+
+\begin_layout Standard
+To run the problem, simply run PyLith without any command line arguments:
+\end_layout
+
+\begin_layout LyX-Code
+pylith
+\end_layout
+
+\begin_layout Standard
+The VTK files will be written to the 
+\family typewriter
+output
+\family default
+ directory.
+ The output includes the displacement and velocity fields over the entire
+ domain at every 3rd time step (0.10 s), the slip and change in traction
+ vectors on the fault surface in along-strike and normal directions at every
+ 3rd time step (0.10 s), and the strain and stress tensors for each cell
+ at every 30th time step (1.0 s).
+ If the problem ran correctly, you should be able to generate a figure such
+ as Figure 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "fig:shearwave:tri3:deform"
+
+\end_inset
+
+, which was generated using ParaView.
+\end_layout
+
+\begin_layout Standard
+\noindent
+\align center
+\begin_inset Float figure
+wide false
+sideways false
+status open
+
+\begin_layout Plain Layout
+\align center
+\begin_inset Graphics
+	filename figs/tri3deform30.jpg
+	lyxscale 50
+	scale 50
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Plain Layout
+\begin_inset Caption
+
+\begin_layout Plain Layout
+Displacement field in the bar at 3.0 s.
+ Deformation has been exaggerated by a factor of 800.
+\begin_inset CommandInset label
+LatexCommand label
+name "fig:shearwave:tri3:deform"
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\end_body
+\end_document

Modified: short/3D/PyLith/branches/v1.7-trunk/doc/userguide/tutorials/subduction/subduction.lyx
===================================================================
--- short/3D/PyLith/branches/v1.7-trunk/doc/userguide/tutorials/subduction/subduction.lyx	2012-06-25 04:52:47 UTC (rev 20403)
+++ short/3D/PyLith/branches/v1.7-trunk/doc/userguide/tutorials/subduction/subduction.lyx	2012-06-25 16:38:44 UTC (rev 20404)
@@ -1,1270 +1,1289 @@
-#LyX 2.0 created this file. For more info see http://www.lyx.org/
-\lyxformat 413
-\begin_document
-\begin_header
-\textclass book
-\begin_preamble
-
-\end_preamble
-\use_default_options false
-\maintain_unincluded_children false
-\language english
-\language_package default
-\inputencoding latin1
-\fontencoding global
-\font_roman default
-\font_sans default
-\font_typewriter default
-\font_default_family default
-\use_non_tex_fonts false
-\font_sc false
-\font_osf false
-\font_sf_scale 100
-\font_tt_scale 100
-
-\graphics default
-\default_output_format default
-\output_sync 0
-\bibtex_command default
-\index_command default
-\paperfontsize default
-\spacing single
-\use_hyperref false
-\papersize default
-\use_geometry true
-\use_amsmath 0
-\use_esint 0
-\use_mhchem 1
-\use_mathdots 1
-\cite_engine basic
-\use_bibtopic false
-\use_indices false
-\paperorientation portrait
-\suppress_date false
-\use_refstyle 0
-\index Index
-\shortcut idx
-\color #008000
-\end_index
-\leftmargin 1in
-\topmargin 1in
-\rightmargin 1in
-\bottommargin 1in
-\secnumdepth 3
-\tocdepth 3
-\paragraph_separation indent
-\paragraph_indentation default
-\quotes_language english
-\papercolumns 1
-\papersides 1
-\paperpagestyle default
-\tracking_changes false
-\output_changes false
-\html_math_output 0
-\html_css_as_file 0
-\html_be_strict false
-\end_header
-
-\begin_body
-
-\begin_layout Section
-\begin_inset CommandInset label
-LatexCommand label
-name "sec:Tutorial-Subduction"
-
-\end_inset
-
-Tutorial for Slip on a Subduction Zone
-\end_layout
-
-\begin_layout Standard
-PyLith features discussed in this tutorial:
-\end_layout
-
-\begin_layout Itemize
-Static solution
-\end_layout
-
-\begin_layout Itemize
-Quasi-static solution
-\end_layout
-
-\begin_layout Itemize
-CUBIT mesh generation
-\end_layout
-
-\begin_deeper
-\begin_layout Itemize
-Nonplanar geometry
-\end_layout
-
-\begin_layout Itemize
-Variable mesh resolution
-\end_layout
-
-\begin_layout Itemize
-APREPRO programming language
-\end_layout
-
-\end_deeper
-\begin_layout Itemize
-Linear triangular cells
-\end_layout
-
-\begin_layout Itemize
-HDF5 output
-\end_layout
-
-\begin_layout Itemize
-Dirichlet displacement and velocity boundary conditions
-\end_layout
-
-\begin_layout Itemize
-ZeroDispDB spatial database
-\end_layout
-
-\begin_layout Itemize
-SimpleDB spatial database
-\end_layout
-
-\begin_layout Itemize
-UniformDB spatial database
-\end_layout
-
-\begin_layout Itemize
-Multiple materials
-\end_layout
-
-\begin_layout Itemize
-Nonlinear solver
-\end_layout
-
-\begin_layout Itemize
-Plane strain linearly elastic material
-\end_layout
-
-\begin_layout Itemize
-Plane Maxwell linear viscoelastic material
-\end_layout
-
-\begin_layout Itemize
-Prescribed slip
-\end_layout
-
-\begin_deeper
-\begin_layout Itemize
-Static fault rupture
-\end_layout
-
-\begin_layout Itemize
-Multiple faults
-\end_layout
-
-\begin_layout Itemize
-Spatially variable coseismic slip
-\end_layout
-
-\begin_layout Itemize
-Spatially variable aseismic creep
-\end_layout
-
-\end_deeper
-\begin_layout Itemize
-Afterslip via fault friction
-\end_layout
-
-\begin_deeper
-\begin_layout Itemize
-Static fault rupture
-\end_layout
-
-\begin_layout Itemize
-Static friction
-\end_layout
-
-\end_deeper
-\begin_layout Standard
-All of the files necessary to run the examples are contained in the directory
- 
-\family typewriter
-examples/2d/subduction.
-\end_layout
-
-\begin_layout Subsection
-Overview
-\end_layout
-
-\begin_layout Standard
-This tutorial examines quasi-static interseismic and coseismic deformation
- in 2-D for a subduction zone (see Figure 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "fig:tutorial:subduction:overview"
-
-\end_inset
-
-).
- It is based on the 2011 M9.0 Tohoku earthquake off the east coast of Japan.
- Figure 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "fig:tutorial:subduction:steps"
-
-\end_inset
-
- shows the three steps of increasing complexity.
- Step 1 focuses on the coseismic slip, Step 2 focuses on interseismic deformatio
-n, and Step 3 combines the two into a pseudo-earthquake cycle deformation
- simulation.
- Step 4 focuses on using the change in tractions from Step 1 to construct
- a simulation with afterslip controlled by frictional sliding.
-\end_layout
-
-\begin_layout Standard
-\begin_inset Float figure
-wide false
-sideways false
-status open
-
-\begin_layout Plain Layout
-\align center
-\begin_inset Graphics
-	filename figs/cartoon_general.eps
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Plain Layout
-\begin_inset Caption
-
-\begin_layout Plain Layout
-Cartoon of subduction zone example.
-\begin_inset CommandInset label
-LatexCommand label
-name "fig:tutorial:subduction:overview"
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-\begin_inset Float figure
-wide false
-sideways false
-status open
-
-\begin_layout Plain Layout
-\align center
-\begin_inset Tabular
-<lyxtabular version="3" rows="2" columns="3">
-<features tabularvalignment="middle">
-<column alignment="center" valignment="top" width="0">
-<column alignment="center" valignment="top" width="0">
-<column alignment="center" valignment="top" width="0">
-<row>
-<cell alignment="center" valignment="top" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Step 1
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Step 2
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Step 3
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-\begin_inset Graphics
-	filename figs/step01.eps
-	lyxscale 66
-	width 2in
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-\begin_inset Graphics
-	filename figs/step02.eps
-	lyxscale 66
-	width 2in
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-\begin_inset Graphics
-	filename figs/step03.eps
-	lyxscale 66
-	width 2in
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-</cell>
-</row>
-</lyxtabular>
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Plain Layout
-\begin_inset Caption
-
-\begin_layout Plain Layout
-Diagram of fault slip and boundary conditions for each step in the subduction
- zone tutorial.
-\begin_inset CommandInset label
-LatexCommand label
-name "fig:tutorial:subduction:steps"
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Subsection
-Mesh Description
-\end_layout
-
-\begin_layout Standard
-We construct the mesh in CUBIT by constructing the geometry, prescribing
- the discretization, running the mesher, and then grouping cells and vertices
- for boundary conditions and materials.
- We use the APREPRO programming language within the journal files to enable
- use of units and to set variables for values used many times.
- An appendix in the CUBIT documentation discusses the features available
- with APREPRO in CUBIT.
- The CUBIT commands are in three separate journal files.
- The main driver is in the journal file mesh_tri3.jou.
- It calls the journal file geometry.jou to construct the geometry and createbc.jou
- to setup the groups associated with boundary conditions and materials.
- The journal files are documented and describe the various steps outlined
- below.
-\end_layout
-
-\begin_layout Enumerate
-Create the geometry defining the domain.
-\end_layout
-
-\begin_deeper
-\begin_layout Enumerate
-Create points.
-\end_layout
-
-\begin_layout Enumerate
-Connect points into spline curves.
-\end_layout
-
-\begin_layout Enumerate
-Split curves to separate them into sections bounding surfaces.
- 
-\end_layout
-
-\begin_layout Enumerate
-Connect curves into surfaces.
-\end_layout
-
-\begin_layout Enumerate
-Stitch surfaces together.
-\end_layout
-
-\end_deeper
-\begin_layout Enumerate
-Define meshing scheme and cell size variation.
-\end_layout
-
-\begin_deeper
-\begin_layout Enumerate
-Define cell size along curves near fault.
-\end_layout
-
-\begin_layout Enumerate
-Increase cell size away from fault at a geometric rate (bias).
-\end_layout
-
-\end_deeper
-\begin_layout Enumerate
-Generate mesh.
-\end_layout
-
-\begin_layout Enumerate
-Create blocks for materials and nodesets for boundary conditions.
-\end_layout
-
-\begin_layout Enumerate
-Export mesh.
-\end_layout
-
-\begin_layout Standard
-\begin_inset Float figure
-wide false
-sideways false
-status open
-
-\begin_layout Plain Layout
-\align center
-\begin_inset Graphics
-	filename figs/subduction_tri3.png
-	lyxscale 50
-	width 4.5in
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Plain Layout
-\begin_inset Caption
-
-\begin_layout Plain Layout
-Variable resolution finite-element mesh with triangular cells.
- The nominal cell size increases at a geometric rate of 1.2 away from the
- region of coseismic slip.
-\begin_inset CommandInset label
-LatexCommand label
-name "fig:tutorial:subduction:mesh"
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Subsection
-Common Information
-\end_layout
-
-\begin_layout Standard
-As in the examples discussed in previous sections of these tutorials, we
- place parameters common to the three steps in the 
-\family typewriter
-pylithapp.cfg
-\family default
- file so that we do not have to duplicate them for each step.
- The settings contained in 
-\family typewriter
-pylithapp.cfg
-\family default
- for this problem consist of:
-\end_layout
-
-\begin_layout Description
-pylithapp.journal.info Settings that control the verbosity of the output written
- to stdout for the different components.
-\end_layout
-
-\begin_layout Description
-pylithapp.mesh_generator Settings that control mesh importing, such as the
- importer type, the filename, and the spatial dimension of the mesh.
-\end_layout
-
-\begin_layout Description
-pylithapp.timedependent Settings that control the problem, such as the total
- time, time step size, and spatial dimension.
-\end_layout
-
-\begin_layout Description
-pylithapp.timedependent.materials Settings that control the material type,
- specify which material IDs are to be associated with a particular material
- type, and give the name of the spatial database containing the physical
-  properties for the material.
- The quadrature information is also given.
-\end_layout
-
-\begin_layout Description
-pylithapp.problem.formulation.output Settings related output of the solution
- over the domain and subdomain (ground surface).
-\end_layout
-
-\begin_layout Description
-pylithapp.timedependent.materials.
-\shape italic
-MATERIAL
-\shape default
-.output Settings related to output of the state variables for material 
-\shape italic
-MATERIAL
-\shape default
-.
-\end_layout
-
-\begin_layout Description
-pylithapp.petsc PETSc settings to use for the problem, such as the preconditioner
- type.
-\end_layout
-
-\begin_layout Standard
-The physical properties for each material are specified in spatial database
- files.
- For example, the elastic properties for the continental crust are in mat_concru
-st.spatialdb.
- The provided spatial database files all use just a single point to specify
- uniform physical properties within each material.
- A good exercise is to alter the spatial database files with the physical
- properties to match PREM.
-\end_layout
-
-\begin_layout Subsection
-Step 1: Coseismic Slip Simulation
-\end_layout
-
-\begin_layout Standard
-The first example problem is earthquake rupture involving coseismic slip
- along the interface between the subducting slab and the continental crust
- and upper most portion of the mantle below the continental crust.
- The spatial variation of slip comes from a cross-section of Gavin Hayes'
- finite-source model 
-\begin_inset Flex URL
-status collapsed
-
-\begin_layout Plain Layout
-
-earthquake.usgs.gov/earthquakes/eqinthenews/2011/usc0001xgp/finite_fault.php
-\end_layout
-
-\end_inset
-
-.
- On the lateral and bottom boundaries of the domain, we fix the degrees
- of freedom perpendicular to the boundary as shown in Figure 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "fig:tutorial:subduction:steps"
-
-\end_inset
-
-.
- Parameter settings that augment those in 
-\family typewriter
-pylithapp.cfg
-\family default
- are contained in the file 
-\family typewriter
-step01.cfg
-\family default
-.
- These settings are:
-\end_layout
-
-\begin_layout Description
-pylithapp.timedependent.formulation.time_step Adjust the total simulation time
- to 0 years (static simulation).
-\end_layout
-
-\begin_layout Description
-pylithapp.timedependent Specifies the array of boundary conditions.
-\end_layout
-
-\begin_layout Description
-pylithapp.timedependent.bc.
-\shape italic
-BOUNDARY
-\shape default
- Defines the settings for boundary 
-\shape italic
-BOUNDARY
-\shape default
-, including which degrees of freedom are being constrained (x or y), the
- label (defined in
-\family typewriter
- mesh_tri3.exo
-\family default
-) corresponding to the nodeset in CUBIT, and a label to the boundary condition
- used in any error messages.
-\end_layout
-
-\begin_layout Description
-pylithapp.timedependent.interfaces.fault Specify the coseismic slip along the
- interface between the oceanic crust and continental crust with a small
- amount of slip penetrating into the upper mantle.
-\end_layout
-
-\begin_layout Description
-pylithapp.problem.formulation.output.domain Gives the base filenames for HDF5
- output (
-\family typewriter
-for example, step01.h5
-\family default
-).
-\end_layout
-
-\begin_layout Standard
-We run this example by typing
-\end_layout
-
-\begin_layout LyX-Code
-pylith step01.cfg
-\end_layout
-
-\begin_layout Standard
-The problem will produce twelve pairs of HDF5/Xdmf files.
- The HDF5 files contain the data and the Xdmf files contain the metadata
- required by ParaView and Visit (and possibly other visualization tools
- that use Xdmf files) to access the mesh and data sets in the HDF5 files.
- The files include the solution over the domain and ground surface (two
- pairs of files), physical properties, stress, and strain within each material
- (eight pairs of files), and fault parameters, slip, and traction (two pairs
- of files).
- 
-\end_layout
-
-\begin_layout Standard
-Figure 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "fig:tutorial:subduction:step01"
-
-\end_inset
-
-, which was created using ParaView, displays the magnitude of the displacement
- field with the deformation exaggerated by a factor of 1000.
- We construct a three-dimensional displacement vector from the two-dimensional
- displacement components using the Calculator with the expression
-\end_layout
-
-\begin_layout LyX-Code
-displacement_x*iHat + displacement_y*jHat
-\end_layout
-
-\begin_layout Standard
-where we select the displacement components from the Scalars drop-down menu
- and the iHat, jHat, and kHat values from the Calculator buttons.
-\end_layout
-
-\begin_layout Standard
-\noindent
-\align center
-\begin_inset Float figure
-wide false
-sideways false
-status open
-
-\begin_layout Plain Layout
-\align center
-\begin_inset Graphics
-	filename figs/step01_soln.png
-	lyxscale 50
-	width 4.5in
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Plain Layout
-\begin_inset Caption
-
-\begin_layout Plain Layout
-Solution for Step 1.
- The colors indicate the magnitude of the displacement and the deformation
- is exaggerated by a factor of 1000.
- 
-\begin_inset CommandInset label
-LatexCommand label
-name "fig:tutorial:subduction:step01"
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Subsection
-Step 2: Interseismic Deformation Simulation
-\end_layout
-
-\begin_layout Standard
-In this example we simulate the interseismic deformation associated with
- the oceanic crust subducting beneath the continental crust and into the
- mantle.
- We prescribe steady aseismic slip of 8 cm/yr along the interfaces between
- the oceanic crust and mantle with the interface between the oceanic crust
- and continental crust locked as shown in Figure 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "fig:tutorial:subduction:steps"
-
-\end_inset
-
-.
- We adjust the Dirichlet boundary conditions on the lateral edges and bottom
- of the domain by pinning only the portions of the boundaries in the mantle
- and continental crust (i.e., not part of the oceanic crust).
- Parameter settings that augment those in 
-\family typewriter
-pylithapp.cfg
-\family default
- are contained in the file 
-\family typewriter
-step02.cfg
-\family default
-.
- These settings include:
-\end_layout
-
-\begin_layout Description
-pylithapp.timedependent.formulation.time_step Adjust the total simulation time
- to 100 years.
-\end_layout
-
-\begin_layout Description
-pylithapp.timedependent Specifies the array of boundary conditions.
-\end_layout
-
-\begin_layout Description
-pylithapp.timedependent.bc.
-\shape italic
-BOUNDARY
-\shape default
- Defines the settings for boundary 
-\shape italic
-BOUNDARY
-\shape default
-, including which degrees of freedom are being constrained (x or y), the
- label (defined in
-\family typewriter
- mesh_tri3.exo
-\family default
-) corresponding to the nodeset in CUBIT, and a label to the boundary condition
- used in any error messages.
-\end_layout
-
-\begin_layout Description
-pylithapp.timedependent.interfaces Specify the steady aseismic slip as a constant
- slip rate on the fault surfaces.
- 
-\end_layout
-
-\begin_layout Description
-pylithapp.problem.formulation.output.domain Gives the base filename for HDF5
- output (
-\family typewriter
-for example, step02.h5
-\family default
-).
-\end_layout
-
-\begin_layout Standard
-We run this example by typing
-\end_layout
-
-\begin_layout LyX-Code
-pylith step02.cfg
-\end_layout
-
-\begin_layout Standard
-The simulation will produce pairs of HDF5/Xdmf files with separate files
- for each material and fault interface.
- Figure 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "fig:tutorial:subduction:step02"
-
-\end_inset
-
-, which was created using ParaView, displays the magnitude of the displacement
- field with the deformation exaggerated by a factor of 1000.
- Using the animation features within ParaView or Visit you can illustrate
- how the continental crust near the trench subsides during the interseismic
- deformation.
- 
-\end_layout
-
-\begin_layout Standard
-\noindent
-\align center
-\begin_inset Float figure
-wide false
-sideways false
-status open
-
-\begin_layout Plain Layout
-\align center
-\begin_inset Graphics
-	filename figs/step02_soln.png
-	lyxscale 50
-	width 4.5in
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Plain Layout
-\begin_inset Caption
-
-\begin_layout Plain Layout
-Solution for Step 2 at 100 years.
- The colors indicate the magnitude of the displacement and the deformation
- is exaggerated by a factor of 1000.
-\begin_inset CommandInset label
-LatexCommand label
-name "fig:tutorial:subduction:step02"
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Subsection
-Step 3: Pseudo-earthquake Cycle Model
-\end_layout
-
-\begin_layout Standard
-This simulation combines 300 years of interseismic deformation from Step
- 2 with the coseismic deformation from Step 1 applied at 150 years to create
- a simple model of the earthquake cycle.
- Parameter settings that augment those in 
-\family typewriter
-pylithapp.cfg
-\family default
- are contained in the file 
-\family typewriter
-step03.cfg
-\family default
-.
- These settings include:
-\end_layout
-
-\begin_layout Description
-pylithapp.timedependent.formulation.time_step Adjust the total simulation time
- to 300 years.
-\end_layout
-
-\begin_layout Description
-pylithapp.timedependent Specifies the array of boundary conditions.
-\end_layout
-
-\begin_layout Description
-pylithapp.timedependent.bc.
-\shape italic
-BOUNDARY
-\shape default
- The Dirichlet boundary conditions match those in Step 2.
-\end_layout
-
-\begin_layout Description
-pylithapp.timedependent.interfaces On the interface between the subducting
- oceanic crust and the mantle, we prescribe the same steady, aseismic slip
- as that in Step 2.
- On the interface along the top of the subducting oceanic crust and the
- continental crust and mantle we create two earthquake ruptures, The first
- rupture applies the coseismic slip form Step 1 at 150 years, while the
- second rupture prescribes the same steady, aseismic slip as in Step 2.
-\end_layout
-
-\begin_layout Description
-pylithapp.problem.formulation.output.domain Gives the base filename for HDF5
- output (
-\family typewriter
-for example, step03.h5
-\family default
-).
-\end_layout
-
-\begin_layout Standard
-We run this example by typing
-\end_layout
-
-\begin_layout LyX-Code
-pylith step03.cfg
-\end_layout
-
-\begin_layout Standard
-The simulation will produce pairs of HDF5/Xdmf files with separate files
- for each material and fault interface.
- Figure 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "fig:tutorial:subduction:step03"
-
-\end_inset
-
-, which was created using ParaView, displays the magnitude of the displacement
- field with the deformation exaggerated by a factor of 1000.
- Using the animation features within ParaView or Visit you can illustrate
- how the continental crust near the trench rebounds during the earthquake
- after subsiding during the interseismic deformation.
- 
-\end_layout
-
-\begin_layout Standard
-\noindent
-\align center
-\begin_inset Float figure
-wide false
-sideways false
-status open
-
-\begin_layout Plain Layout
-\align center
-\begin_inset Graphics
-	filename figs/step03_soln.png
-	lyxscale 50
-	width 4.5in
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Plain Layout
-\begin_inset Caption
-
-\begin_layout Plain Layout
-Solution for Step 3 at 150 years (immediately following the earthquake rupture).
- The colors indicate the magnitude of the displacement and the deformation
- is exaggerated by a factor of 1000.
-\begin_inset CommandInset label
-LatexCommand label
-name "fig:tutorial:subduction:step03"
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Subsection
-Step 4: Frictional Afterslip Simulation
-\end_layout
-
-\begin_layout Standard
-This simulation demonstrates how to combine the change in tractions associated
- with coseismic slip with a background stress field to compute afterslip
- controlled by static friction.
- The Python script 
-\family typewriter
-afterslip_tractions.py
-\family default
- will create a spatial database file with initial tractions based on the
- change in tractions from Step 1 and a background stress field.
- The background stress field is simply normal tractions consistent with
- the overburden (lithostatic load) for a uniform half-space and shear tractions
- consistent with a coefficient of friction of 0.6.
- The 
-\family typewriter
-afterslip_tractions.spatialdb
-\family default
- file is provided, so you do not need to run the Python script 
-\family typewriter
-afterslip_tractions.py
-\family default
-; however, you can do so by typing
-\end_layout
-
-\begin_layout LyX-Code
-python afterslip_tractions.py
-\end_layout
-
-\begin_layout Standard
-We provide 2.0 MPa of strength excess associated with the background stress
- field by using a cohesion of 2.0 MPa in the static friction model.
- Slip will occur in regions where the coseismic slip increased the shear
- tractions by more than 2.0 MPa.
- On the lateral and bottom boundaries of the domain, we fix the degrees
- of freedom perpendicular to the boundary as shown in Figure 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "fig:tutorial:subduction:steps"
-
-\end_inset
-
-.
- Parameter settings that augment those in 
-\family typewriter
-pylithapp.cfg
-\family default
- are contained in the file 
-\family typewriter
-step04.cfg
-\family default
-.
- These settings are:
-\end_layout
-
-\begin_layout Description
-pylithapp.timedependent.formulation.time_step Adjust the total simulation time
- to 0 years (static simulation).
-\end_layout
-
-\begin_layout Description
-pylithapp.timedependent Selects the nonlinear solver and specifies the array
- of boundary conditions.
-\end_layout
-
-\begin_layout Description
-pylithapp.timedependent.bc.
-\shape italic
-BOUNDARY
-\shape default
- Defines the settings for boundary 
-\shape italic
-BOUNDARY
-\shape default
-, including which degrees of freedom are being constrained (x or y), the
- label (defined in
-\family typewriter
- mesh_tri3.exo
-\family default
-) corresponding to the nodeset in CUBIT, and a label to the boundary condition
- used in any error messages.
-\end_layout
-
-\begin_layout Description
-pylithapp.timedependent.interfaces.fault Specify a fault with a fault constitutive
- model (static friction) and initial fault tractions.
- 
-\end_layout
-
-\begin_layout Description
-pylithapp.problem.formulation.output.domain Gives the base filenames for HDF5
- output (
-\family typewriter
-for example, step04.h5
-\family default
-).
-\end_layout
-
-\begin_layout Standard
-We run this example by typing
-\end_layout
-
-\begin_layout LyX-Code
-pylith step04.cfg
-\end_layout
-
-\begin_layout Standard
-The problem will produce twelve pairs of HDF5/Xdmf files.
- The HDF5 files contain the data and the Xdmf files contain the metadata
- required by ParaView and Visit (and possibly other visualization tools
- that use Xdmf files) to access the mesh and data sets in the HDF5 files.
- The files include the solution over the domain and ground surface (two
- pairs of files), physical properties, stress, and strain within each material
- (eight pairs of files), and fault parameters, slip, and traction (two pairs
- of files).
- 
-\end_layout
-
-\begin_layout Standard
-Figure 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "fig:tutorial:subduction:step04"
-
-\end_inset
-
-, which was created using ParaView, displays the magnitude of the displacement
- field with the original configuration.
- Slip occurs down-dip from the coseismic slip as well as three areas with
- sharp gradients in slip, including the trench.
- The location of the afterslip can be shifted by changing the spatial variation
- of the coseismic slip and background stress field.
-\end_layout
-
-\begin_layout Standard
-\noindent
-\align center
-\begin_inset Float figure
-wide false
-sideways false
-status open
-
-\begin_layout Plain Layout
-\align center
-\begin_inset Graphics
-	filename figs/step01_soln.png
-	lyxscale 50
-	width 4.5in
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Plain Layout
-\begin_inset Caption
-
-\begin_layout Plain Layout
-Solution for Step 4.
- The colors indicate the magnitude of the displacement 
-\begin_inset CommandInset label
-LatexCommand label
-name "fig:tutorial:subduction:step04"
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Subsection
-Suggested Variations
-\end_layout
-
-\begin_layout Standard
-The list below includes some suggested modifications to the problem that
- will allow you to become more familiar with PyLith while examining some
- interesting physics.
-\end_layout
-
-\begin_layout Itemize
-Change the resolution of the mesh by editing the mesh_tri3.jou journal file.
- Change the resolution and bias factor.
-\end_layout
-
-\begin_layout Itemize
-Add depth dependent viscosity to the mantle and crust.
- This requires using the linear Maxwell plane strain bulk constitutive model
- in the crust as well and creating spatial databases that include viscosity
- for the crust.
- Specifying a depth dependent variation in the parameters will require adding
- points, updating num-locs accordingly, and changing data-dim to 1.
-\end_layout
-
-\begin_layout Itemize
-Modify the spatial database files for the material properties to use depth-depen
-dent elastic properties based on PREM (Dziewonski and Anderson, 1981, 10.1016/003
-1-9201(81)90046-7).
- See 
-\begin_inset Flex URL
-status open
-
-\begin_layout Plain Layout
-
-geophysics.ou.edu/solid_earth/prem.html
-\end_layout
-
-\end_inset
-
- for a simple table of values.
- Add points, update num-locs accordingly, and change data-dim to be 1.
-\end_layout
-
-\begin_layout Itemize
-Modify the CUBIT journal files to use quad4 cells rather than tri3 cells.
- This requires using the pave mesh scheme.
-\end_layout
-
-\begin_layout Itemize
-Create a simulation with multiple earthquake cycles by lengthening the duration
- of the simulation and adding additional earthquake ruptures.
- See 
-\family typewriter
-examples/3d/hex8/step06.cfg
-\family default
- for an example with multiple earthquake ruptures.
- Examine spinup towards a steady-state solution.
-\end_layout
-
-\end_body
-\end_document
+#LyX 2.0 created this file. For more info see http://www.lyx.org/
+\lyxformat 413
+\begin_document
+\begin_header
+\textclass book
+\begin_preamble
+
+\end_preamble
+\use_default_options false
+\maintain_unincluded_children false
+\language english
+\language_package default
+\inputencoding latin1
+\fontencoding global
+\font_roman default
+\font_sans default
+\font_typewriter default
+\font_default_family default
+\use_non_tex_fonts false
+\font_sc false
+\font_osf false
+\font_sf_scale 100
+\font_tt_scale 100
+
+\graphics default
+\default_output_format default
+\output_sync 0
+\bibtex_command default
+\index_command default
+\paperfontsize default
+\spacing single
+\use_hyperref false
+\papersize default
+\use_geometry true
+\use_amsmath 0
+\use_esint 0
+\use_mhchem 1
+\use_mathdots 1
+\cite_engine basic
+\use_bibtopic false
+\use_indices false
+\paperorientation portrait
+\suppress_date false
+\use_refstyle 0
+\index Index
+\shortcut idx
+\color #008000
+\end_index
+\leftmargin 1in
+\topmargin 1in
+\rightmargin 1in
+\bottommargin 1in
+\secnumdepth 3
+\tocdepth 3
+\paragraph_separation indent
+\paragraph_indentation default
+\quotes_language english
+\papercolumns 1
+\papersides 1
+\paperpagestyle default
+\tracking_changes false
+\output_changes false
+\html_math_output 0
+\html_css_as_file 0
+\html_be_strict false
+\end_header
+
+\begin_body
+
+\begin_layout Section
+\begin_inset CommandInset label
+LatexCommand label
+name "sec:Tutorial-Subduction"
+
+\end_inset
+
+Tutorial for Slip on a Subduction Zone
+\end_layout
+
+\begin_layout Standard
+PyLith features discussed in this tutorial:
+\end_layout
+
+\begin_layout Itemize
+Static solution
+\end_layout
+
+\begin_layout Itemize
+Quasi-static solution
+\end_layout
+
+\begin_layout Itemize
+CUBIT mesh generation
+\end_layout
+
+\begin_deeper
+\begin_layout Itemize
+Nonplanar geometry
+\end_layout
+
+\begin_layout Itemize
+Variable mesh resolution
+\end_layout
+
+\begin_layout Itemize
+APREPRO programming language
+\end_layout
+
+\end_deeper
+\begin_layout Itemize
+Linear triangular cells
+\end_layout
+
+\begin_layout Itemize
+HDF5 output
+\end_layout
+
+\begin_layout Itemize
+Dirichlet displacement and velocity boundary conditions
+\end_layout
+
+\begin_layout Itemize
+ZeroDispDB spatial database
+\end_layout
+
+\begin_layout Itemize
+SimpleDB spatial database
+\end_layout
+
+\begin_layout Itemize
+UniformDB spatial database
+\end_layout
+
+\begin_layout Itemize
+Multiple materials
+\end_layout
+
+\begin_layout Itemize
+Nonlinear solver
+\end_layout
+
+\begin_layout Itemize
+Plane strain linearly elastic material
+\end_layout
+
+\begin_layout Itemize
+Plane Maxwell linear viscoelastic material
+\end_layout
+
+\begin_layout Itemize
+Prescribed slip
+\end_layout
+
+\begin_deeper
+\begin_layout Itemize
+Static fault rupture
+\end_layout
+
+\begin_layout Itemize
+Multiple faults
+\end_layout
+
+\begin_layout Itemize
+Spatially variable coseismic slip
+\end_layout
+
+\begin_layout Itemize
+Spatially variable aseismic creep
+\end_layout
+
+\end_deeper
+\begin_layout Itemize
+Afterslip via fault friction
+\end_layout
+
+\begin_deeper
+\begin_layout Itemize
+Static fault rupture
+\end_layout
+
+\begin_layout Itemize
+Static friction
+\end_layout
+
+\end_deeper
+\begin_layout Standard
+All of the files necessary to run the examples are contained in the directory
+ 
+\family typewriter
+examples/2d/subduction.
+\end_layout
+
+\begin_layout Subsection
+Overview
+\end_layout
+
+\begin_layout Standard
+This tutorial examines quasi-static interseismic and coseismic deformation
+ in 2D for a subduction zone (see Figure 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "fig:tutorial:subduction:overview"
+
+\end_inset
+
+).
+ It is based on the 2011 M9.0 Tohoku earthquake off the east coast of Japan.
+ Figure 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "fig:tutorial:subduction:steps"
+
+\end_inset
+
+ shows the three steps of increasing complexity.
+ Step 1 focuses on the coseismic slip, Step 2 focuses on interseismic deformatio
+n, and Step 3 combines the two into a pseudo-earthquake cycle deformation
+ simulation.
+ Step 4 focuses on using the change in tractions from Step 1 to construct
+ a simulation with afterslip controlled by frictional sliding.
+\end_layout
+
+\begin_layout Standard
+\begin_inset Float figure
+wide false
+sideways false
+status open
+
+\begin_layout Plain Layout
+\align center
+\begin_inset Graphics
+	filename figs/cartoon_general.eps
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Plain Layout
+\begin_inset Caption
+
+\begin_layout Plain Layout
+Cartoon of subduction zone example.
+\begin_inset CommandInset label
+LatexCommand label
+name "fig:tutorial:subduction:overview"
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+\begin_inset Float figure
+wide false
+sideways false
+status open
+
+\begin_layout Plain Layout
+\align center
+\begin_inset Tabular
+<lyxtabular version="3" rows="2" columns="3">
+<features tabularvalignment="middle">
+<column alignment="center" valignment="top" width="0">
+<column alignment="center" valignment="top" width="0">
+<column alignment="center" valignment="top" width="0">
+<row>
+<cell alignment="center" valignment="top" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Step 1
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Step 2
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Step 3
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+\begin_inset Graphics
+	filename figs/step01.eps
+	lyxscale 66
+	width 2in
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+\begin_inset Graphics
+	filename figs/step02.eps
+	lyxscale 66
+	width 2in
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+\begin_inset Graphics
+	filename figs/step03.eps
+	lyxscale 66
+	width 2in
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Plain Layout
+\begin_inset Caption
+
+\begin_layout Plain Layout
+Diagram of fault slip and boundary conditions for each step in the subduction
+ zone tutorial.
+\begin_inset CommandInset label
+LatexCommand label
+name "fig:tutorial:subduction:steps"
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Subsection
+Mesh Description
+\end_layout
+
+\begin_layout Standard
+We construct the mesh in CUBIT by constructing the geometry, prescribing
+ the discretization, running the mesher, and then grouping cells and vertices
+ for boundary conditions and materials.
+ We use the APREPRO programming language within the journal files to enable
+ use of units and to set variables for values used many times.
+ An appendix in the CUBIT documentation discusses the features available
+ with APREPRO in CUBIT.
+ The CUBIT commands are in three separate journal files.
+ The main driver is in the journal file 
+\family typewriter
+mesh_tri3.jou
+\family default
+.
+ It calls the journal file 
+\family typewriter
+geometry.jou
+\family default
+ to construct the geometry and 
+\family typewriter
+createbc.jou
+\family default
+ to set up the groups associated with boundary conditions and materials.
+ The journal files are documented and describe the various steps outlined
+ below.
+\end_layout
+
+\begin_layout Enumerate
+Create the geometry defining the domain.
+\end_layout
+
+\begin_deeper
+\begin_layout Enumerate
+Create points.
+\end_layout
+
+\begin_layout Enumerate
+Connect points into spline curves.
+\end_layout
+
+\begin_layout Enumerate
+Split curves to separate them into sections bounding surfaces.
+ 
+\end_layout
+
+\begin_layout Enumerate
+Connect curves into surfaces.
+\end_layout
+
+\begin_layout Enumerate
+Stitch surfaces together.
+\end_layout
+
+\end_deeper
+\begin_layout Enumerate
+Define meshing scheme and cell size variation.
+\end_layout
+
+\begin_deeper
+\begin_layout Enumerate
+Define cell size along curves near fault.
+\end_layout
+
+\begin_layout Enumerate
+Increase cell size away from fault at a geometric rate (bias).
+\end_layout
+
+\end_deeper
+\begin_layout Enumerate
+Generate mesh.
+\end_layout
+
+\begin_layout Enumerate
+Create blocks for materials and nodesets for boundary conditions.
+\end_layout
+
+\begin_layout Enumerate
+Export mesh.
+\end_layout
+
+\begin_layout Standard
+\begin_inset Float figure
+wide false
+sideways false
+status open
+
+\begin_layout Plain Layout
+\align center
+\begin_inset Graphics
+	filename figs/subduction_tri3.png
+	lyxscale 50
+	width 4.5in
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Plain Layout
+\begin_inset Caption
+
+\begin_layout Plain Layout
+Variable resolution finite-element mesh with triangular cells.
+ The nominal cell size increases at a geometric rate of 1.2 away from the
+ region of coseismic slip.
+\begin_inset CommandInset label
+LatexCommand label
+name "fig:tutorial:subduction:mesh"
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Subsection
+Common Information
+\end_layout
+
+\begin_layout Standard
+As in the examples discussed in previous sections of these tutorials, we
+ place parameters common to the three steps in the 
+\family typewriter
+pylithapp.cfg
+\family default
+ file so that we do not have to duplicate them for each step.
+ The settings contained in 
+\family typewriter
+pylithapp.cfg
+\family default
+ for this problem consist of:
+\end_layout
+
+\begin_layout Description
+pylithapp.journal.info Settings that control the verbosity of the output written
+ to stdout for the different components.
+\end_layout
+
+\begin_layout Description
+pylithapp.mesh_generator Settings that control mesh importing, such as the
+ importer type, the filename, and the spatial dimension of the mesh.
+\end_layout
+
+\begin_layout Description
+pylithapp.timedependent Settings that control the problem, such as the total
+ time, time-step size, and spatial dimension.
+\end_layout
+
+\begin_layout Description
+pylithapp.timedependent.materials Settings that control the material type,
+ specify which material IDs are to be associated with a particular material
+ type, and give the name of the spatial database containing the physical
+ properties for the material.
+ The quadrature information is also given.
+\end_layout
+
+\begin_layout Description
+pylithapp.problem.formulation.output Settings related output of the solution
+ over the domain and subdomain (ground surface).
+\end_layout
+
+\begin_layout Description
+pylithapp.timedependent.materials.
+\shape italic
+MATERIAL
+\shape default
+.output Settings related to output of the state variables for material 
+\shape italic
+MATERIAL
+\shape default
+.
+\end_layout
+
+\begin_layout Description
+pylithapp.petsc PETSc settings to use for the problem, such as the preconditioner
+ type.
+\end_layout
+
+\begin_layout Standard
+The physical properties for each material are specified in spatial database
+ files.
+ For example, the elastic properties for the continental crust are in 
+\family typewriter
+mat_concrust.spatialdb
+\family default
+.
+ The provided spatial database files all use just a single point to specify
+ uniform physical properties within each material.
+ A good exercise is to alter the spatial database files with the physical
+ properties to match PREM.
+\end_layout
+
+\begin_layout Subsection
+Step 1: Coseismic Slip Simulation
+\end_layout
+
+\begin_layout Standard
+The first example problem is earthquake rupture involving coseismic slip
+ along the interface between the subducting slab and the continental crust
+ and uppermost portion of the mantle below the continental crust.
+ The spatial variation of slip comes from a cross-section of Gavin Hayes'
+ finite-source model 
+\begin_inset Flex URL
+status collapsed
+
+\begin_layout Plain Layout
+
+earthquake.usgs.gov/earthquakes/eqinthenews/2011/usc0001xgp/finite_fault.php
+\end_layout
+
+\end_inset
+
+.
+ On the lateral and bottom boundaries of the domain, we fix the degrees
+ of freedom perpendicular to the boundary as shown in Figure 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "fig:tutorial:subduction:steps"
+
+\end_inset
+
+.
+ Parameter settings that augment those in 
+\family typewriter
+pylithapp.cfg
+\family default
+ are contained in the file 
+\family typewriter
+step01.cfg
+\family default
+.
+ These settings are:
+\end_layout
+
+\begin_layout Description
+pylithapp.timedependent.formulation.time_step Adjust the total simulation time
+ to 0 years (static simulation).
+\end_layout
+
+\begin_layout Description
+pylithapp.timedependent Specifies the array of boundary conditions.
+\end_layout
+
+\begin_layout Description
+pylithapp.timedependent.bc.
+\shape italic
+BOUNDARY
+\shape default
+ Defines the settings for boundary 
+\shape italic
+BOUNDARY
+\shape default
+, including which degrees of freedom are being constrained (x or y), the
+ label (defined in
+\family typewriter
+ mesh_tri3.exo
+\family default
+) corresponding to the nodeset in CUBIT, and a label to the boundary condition
+ used in any error messages.
+\end_layout
+
+\begin_layout Description
+pylithapp.timedependent.interfaces.fault Specify the coseismic slip along the
+ interface between the oceanic crust and continental crust with a small
+ amount of slip penetrating into the upper mantle.
+\end_layout
+
+\begin_layout Description
+pylithapp.problem.formulation.output.domain Gives the base filenames for HDF5
+ output (for example, 
+\family typewriter
+step01.h5
+\family default
+).
+\end_layout
+
+\begin_layout Standard
+We run this example by typing
+\end_layout
+
+\begin_layout LyX-Code
+pylith step01.cfg
+\end_layout
+
+\begin_layout Standard
+The problem will produce twelve pairs of HDF5/Xdmf files.
+ The HDF5 files contain the data and the Xdmf files contain the metadata
+ required by ParaView and Visit (and possibly other visualization tools
+ that use Xdmf files) to access the mesh and data sets in the HDF5 files.
+ The files include the solution over the domain and ground surface (two
+ pairs of files), physical properties, stress, and strain within each material
+ (eight pairs of files), and fault parameters, slip, and traction (two pairs
+ of files).
+ 
+\end_layout
+
+\begin_layout Standard
+Figure 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "fig:tutorial:subduction:step01"
+
+\end_inset
+
+, which was created using ParaView, displays the magnitude of the displacement
+ field with the deformation exaggerated by a factor of 1000.
+ We construct a three-dimensional displacement vector from the two-dimensional
+ displacement components using the Calculator with the expression
+\end_layout
+
+\begin_layout LyX-Code
+displacement_x*iHat + displacement_y*jHat
+\end_layout
+
+\begin_layout Standard
+where we select the displacement components from the Scalars drop-down menu
+ and the iHat, jHat, and kHat values from the Calculator buttons.
+\end_layout
+
+\begin_layout Standard
+\noindent
+\align center
+\begin_inset Float figure
+wide false
+sideways false
+status open
+
+\begin_layout Plain Layout
+\align center
+\begin_inset Graphics
+	filename figs/step01_soln.png
+	lyxscale 50
+	width 4.5in
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Plain Layout
+\begin_inset Caption
+
+\begin_layout Plain Layout
+Solution for Step 1.
+ The colors indicate the magnitude of the displacement, and the deformation
+ is exaggerated by a factor of 1000.
+ 
+\begin_inset CommandInset label
+LatexCommand label
+name "fig:tutorial:subduction:step01"
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Subsection
+Step 2: Interseismic Deformation Simulation
+\end_layout
+
+\begin_layout Standard
+In this example we simulate the interseismic deformation associated with
+ the oceanic crust subducting beneath the continental crust and into the
+ mantle.
+ We prescribe steady aseismic slip of 8 cm/yr along the interfaces between
+ the oceanic crust and mantle with the interface between the oceanic crust
+ and continental crust locked as shown in Figure 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "fig:tutorial:subduction:steps"
+
+\end_inset
+
+.
+ We adjust the Dirichlet boundary conditions on the lateral edges and bottom
+ of the domain by pinning only the portions of the boundaries in the mantle
+ and continental crust (i.e., not part of the oceanic crust).
+ Parameter settings that augment those in 
+\family typewriter
+pylithapp.cfg
+\family default
+ are contained in the file 
+\family typewriter
+step02.cfg
+\family default
+.
+ These settings include:
+\end_layout
+
+\begin_layout Description
+pylithapp.timedependent.formulation.time_step Adjust the total simulation time
+ to 100 years.
+\end_layout
+
+\begin_layout Description
+pylithapp.timedependent Specifies the array of boundary conditions.
+\end_layout
+
+\begin_layout Description
+pylithapp.timedependent.bc.
+\shape italic
+BOUNDARY
+\shape default
+ Defines the settings for boundary 
+\shape italic
+BOUNDARY
+\shape default
+, including which degrees of freedom are being constrained (x or y), the
+ label (defined in
+\family typewriter
+ mesh_tri3.exo
+\family default
+) corresponding to the nodeset in CUBIT, and a label to the boundary condition
+ used in any error messages.
+\end_layout
+
+\begin_layout Description
+pylithapp.timedependent.interfaces Specify the steady aseismic slip as a constant
+ slip rate on the fault surfaces.
+ 
+\end_layout
+
+\begin_layout Description
+pylithapp.problem.formulation.output.domain Gives the base filename for HDF5
+ output (for example, 
+\family typewriter
+step02.h5
+\family default
+).
+\end_layout
+
+\begin_layout Standard
+We run this example by typing
+\end_layout
+
+\begin_layout LyX-Code
+pylith step02.cfg
+\end_layout
+
+\begin_layout Standard
+The simulation will produce pairs of HDF5/Xdmf files with separate files
+ for each material and fault interface.
+ Figure 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "fig:tutorial:subduction:step02"
+
+\end_inset
+
+, which was created using ParaView, displays the magnitude of the displacement
+ field with the deformation exaggerated by a factor of 1000.
+ Using the animation features within ParaView or Visit you can illustrate
+ how the continental crust near the trench subsides during the interseismic
+ deformation.
+ 
+\end_layout
+
+\begin_layout Standard
+\noindent
+\align center
+\begin_inset Float figure
+wide false
+sideways false
+status open
+
+\begin_layout Plain Layout
+\align center
+\begin_inset Graphics
+	filename figs/step02_soln.png
+	lyxscale 50
+	width 4.5in
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Plain Layout
+\begin_inset Caption
+
+\begin_layout Plain Layout
+Solution for Step 2 at 100 years.
+ The colors indicate the magnitude of the displacement, and the deformation
+ is exaggerated by a factor of 1000.
+\begin_inset CommandInset label
+LatexCommand label
+name "fig:tutorial:subduction:step02"
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Subsection
+Step 3: Pseudo-Earthquake Cycle Model
+\end_layout
+
+\begin_layout Standard
+This simulation combines 300 years of interseismic deformation from Step
+ 2 with the coseismic deformation from Step 1 applied at 150 years to create
+ a simple model of the earthquake cycle.
+ Parameter settings that augment those in 
+\family typewriter
+pylithapp.cfg
+\family default
+ are contained in the file 
+\family typewriter
+step03.cfg
+\family default
+.
+ These settings include:
+\end_layout
+
+\begin_layout Description
+pylithapp.timedependent.formulation.time_step Adjust the total simulation time
+ to 300 years.
+\end_layout
+
+\begin_layout Description
+pylithapp.timedependent Specifies the array of boundary conditions.
+\end_layout
+
+\begin_layout Description
+pylithapp.timedependent.bc.
+\shape italic
+BOUNDARY
+\shape default
+ The Dirichlet boundary conditions match those in Step 2.
+\end_layout
+
+\begin_layout Description
+pylithapp.timedependent.interfaces On the interface between the subducting
+ oceanic crust and the mantle, we prescribe the same steady, aseismic slip
+ as that in Step 2.
+ On the interface along the top of the subducting oceanic crust and the
+ continental crust and mantle we create two earthquake ruptures, The first
+ rupture applies the coseismic slip form Step 1 at 150 years, while the
+ second rupture prescribes the same steady, aseismic slip as in Step 2.
+\end_layout
+
+\begin_layout Description
+pylithapp.problem.formulation.output.domain Gives the base filename for HDF5
+ output (for example, 
+\family typewriter
+step03.h5
+\family default
+).
+\end_layout
+
+\begin_layout Standard
+We run this example by typing
+\end_layout
+
+\begin_layout LyX-Code
+pylith step03.cfg
+\end_layout
+
+\begin_layout Standard
+The simulation will produce pairs of HDF5/Xdmf files with separate files
+ for each material and fault interface.
+ Figure 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "fig:tutorial:subduction:step03"
+
+\end_inset
+
+, which was created using ParaView, displays the magnitude of the displacement
+ field with the deformation exaggerated by a factor of 1000.
+ Using the animation features within ParaView or Visit you can illustrate
+ how the continental crust near the trench rebounds during the earthquake
+ after subsiding during the interseismic deformation.
+ 
+\end_layout
+
+\begin_layout Standard
+\noindent
+\align center
+\begin_inset Float figure
+wide false
+sideways false
+status open
+
+\begin_layout Plain Layout
+\align center
+\begin_inset Graphics
+	filename figs/step03_soln.png
+	lyxscale 50
+	width 4.5in
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Plain Layout
+\begin_inset Caption
+
+\begin_layout Plain Layout
+Solution for Step 3 at 150 years (immediately following the earthquake rupture).
+ The colors indicate the magnitude of the displacement, and the deformation
+ is exaggerated by a factor of 1000.
+\begin_inset CommandInset label
+LatexCommand label
+name "fig:tutorial:subduction:step03"
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Subsection
+Step 4: Frictional Afterslip Simulation
+\end_layout
+
+\begin_layout Standard
+This simulation demonstrates how to combine the change in tractions associated
+ with coseismic slip with a background stress field to compute afterslip
+ controlled by static friction.
+ The Python script 
+\family typewriter
+afterslip_tractions.py
+\family default
+ will create a spatial database file with initial tractions based on the
+ change in tractions from Step 1 and a background stress field.
+ The background stress field is simply normal tractions consistent with
+ the overburden (lithostatic load) for a uniform half-space and shear tractions
+ consistent with a coefficient of friction of 0.6.
+ The 
+\family typewriter
+afterslip_tractions.spatialdb
+\family default
+ file is provided, so you do not need to run the Python script 
+\family typewriter
+afterslip_tractions.py
+\family default
+; however, you can do so by typing
+\end_layout
+
+\begin_layout LyX-Code
+python afterslip_tractions.py
+\end_layout
+
+\begin_layout Standard
+We provide 2.0 MPa of strength excess associated with the background stress
+ field by using a cohesion of 2.0 MPa in the static friction model.
+ Slip will occur in regions where the coseismic slip increased the shear
+ tractions by more than 2.0 MPa.
+ On the lateral and bottom boundaries of the domain, we fix the degrees
+ of freedom perpendicular to the boundary as shown in Figure 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "fig:tutorial:subduction:steps"
+
+\end_inset
+
+.
+ Parameter settings that augment those in 
+\family typewriter
+pylithapp.cfg
+\family default
+ are contained in the file 
+\family typewriter
+step04.cfg
+\family default
+.
+ These settings are:
+\end_layout
+
+\begin_layout Description
+pylithapp.timedependent.formulation.time_step Adjust the total simulation time
+ to 0 years (static simulation).
+\end_layout
+
+\begin_layout Description
+pylithapp.timedependent Selects the nonlinear solver and specifies the array
+ of boundary conditions.
+\end_layout
+
+\begin_layout Description
+pylithapp.timedependent.bc.
+\shape italic
+BOUNDARY
+\shape default
+ Defines the settings for boundary 
+\shape italic
+BOUNDARY
+\shape default
+, including which degrees of freedom are being constrained (x or y), the
+ label (defined in
+\family typewriter
+ mesh_tri3.exo
+\family default
+) corresponding to the nodeset in CUBIT, and a label to the boundary condition
+ used in any error messages.
+\end_layout
+
+\begin_layout Description
+pylithapp.timedependent.interfaces.fault Specify a fault with a fault constitutive
+ model (static friction) and initial fault tractions.
+ 
+\end_layout
+
+\begin_layout Description
+pylithapp.problem.formulation.output.domain Gives the base filenames for HDF5
+ output (for example, 
+\family typewriter
+step04.h5
+\family default
+).
+\end_layout
+
+\begin_layout Standard
+We run this example by typing
+\end_layout
+
+\begin_layout LyX-Code
+pylith step04.cfg
+\end_layout
+
+\begin_layout Standard
+The problem will produce twelve pairs of HDF5/Xdmf files.
+ The HDF5 files contain the data and the Xdmf files contain the metadata
+ required by ParaView and Visit (and possibly other visualization tools
+ that use Xdmf files) to access the mesh and data sets in the HDF5 files.
+ The files include the solution over the domain and ground surface (two
+ pairs of files), physical properties, stress, and strain within each material
+ (eight pairs of files), and fault parameters, slip, and traction (two pairs
+ of files).
+ 
+\end_layout
+
+\begin_layout Standard
+Figure 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "fig:tutorial:subduction:step04"
+
+\end_inset
+
+, which was created using ParaView, displays the magnitude of the displacement
+ field with the original configuration.
+ Slip occurs down-dip from the coseismic slip as well as three areas with
+ sharp gradients in slip, including the trench.
+ The location of the afterslip can be shifted by changing the spatial variation
+ of the coseismic slip and background stress field.
+\end_layout
+
+\begin_layout Standard
+\noindent
+\align center
+\begin_inset Float figure
+wide false
+sideways false
+status open
+
+\begin_layout Plain Layout
+\align center
+\begin_inset Graphics
+	filename figs/step01_soln.png
+	lyxscale 50
+	width 4.5in
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Plain Layout
+\begin_inset Caption
+
+\begin_layout Plain Layout
+Solution for Step 4.
+ The colors indicate the magnitude of the displacement.
+ 
+\begin_inset CommandInset label
+LatexCommand label
+name "fig:tutorial:subduction:step04"
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Subsection
+Suggested Variations
+\end_layout
+
+\begin_layout Standard
+The list below includes some suggested modifications to the problem that
+ will allow you to become more familiar with PyLith while examining some
+ interesting physics.
+\end_layout
+
+\begin_layout Itemize
+Change the resolution of the mesh by editing the 
+\family typewriter
+mesh_tri3.jou
+\family default
+ journal file.
+ Change the resolution and bias factor.
+\end_layout
+
+\begin_layout Itemize
+Add depth dependent viscosity to the mantle and crust.
+ This requires using the linear Maxwell plane strain bulk constitutive model
+ in the crust as well and creating spatial databases that include viscosity
+ for the crust.
+ Specifying a depth dependent variation in the parameters will require adding
+ points, updating num-locs accordingly, and changing data-dim to 1.
+\end_layout
+
+\begin_layout Itemize
+Modify the spatial database files for the material properties to use depth-depen
+dent elastic properties based on PREM (Dziewonski and Anderson, 1981, 10.1016/003
+1-9201(81)90046-7).
+ See 
+\begin_inset Flex URL
+status open
+
+\begin_layout Plain Layout
+
+geophysics.ou.edu/solid_earth/prem.html
+\end_layout
+
+\end_inset
+
+ for a simple table of values.
+ Add points, update num-locs accordingly, and change data-dim to 1.
+\end_layout
+
+\begin_layout Itemize
+Modify the CUBIT journal files to use quad4 cells rather than tri3 cells.
+ This requires using the pave mesh scheme.
+\end_layout
+
+\begin_layout Itemize
+Create a simulation with multiple earthquake cycles by lengthening the duration
+ of the simulation and adding additional earthquake ruptures.
+ See 
+\family typewriter
+examples/3d/hex8/step06.cfg
+\family default
+ for an example with multiple earthquake ruptures.
+ Examine spinup towards a steady-state solution.
+\end_layout
+
+\end_body
+\end_document

Modified: short/3D/PyLith/branches/v1.7-trunk/doc/userguide/tutorials/twohex8/twohex8.lyx
===================================================================
--- short/3D/PyLith/branches/v1.7-trunk/doc/userguide/tutorials/twohex8/twohex8.lyx	2012-06-25 04:52:47 UTC (rev 20403)
+++ short/3D/PyLith/branches/v1.7-trunk/doc/userguide/tutorials/twohex8/twohex8.lyx	2012-06-25 16:38:44 UTC (rev 20404)
@@ -1,855 +1,855 @@
-#LyX 2.0 created this file. For more info see http://www.lyx.org/
-\lyxformat 413
-\begin_document
-\begin_header
-\textclass book
-\begin_preamble
-
-\end_preamble
-\use_default_options false
-\maintain_unincluded_children false
-\language english
-\language_package default
-\inputencoding latin1
-\fontencoding global
-\font_roman default
-\font_sans default
-\font_typewriter default
-\font_default_family default
-\use_non_tex_fonts false
-\font_sc false
-\font_osf false
-\font_sf_scale 100
-\font_tt_scale 100
-
-\graphics default
-\default_output_format default
-\output_sync 0
-\bibtex_command default
-\index_command default
-\paperfontsize default
-\spacing single
-\use_hyperref false
-\papersize default
-\use_geometry true
-\use_amsmath 0
-\use_esint 0
-\use_mhchem 1
-\use_mathdots 1
-\cite_engine basic
-\use_bibtopic false
-\use_indices false
-\paperorientation portrait
-\suppress_date false
-\use_refstyle 0
-\index Index
-\shortcut idx
-\color #008000
-\end_index
-\leftmargin 1in
-\topmargin 1in
-\rightmargin 1in
-\bottommargin 2in
-\secnumdepth 3
-\tocdepth 3
-\paragraph_separation indent
-\paragraph_indentation default
-\quotes_language english
-\papercolumns 1
-\papersides 1
-\paperpagestyle default
-\tracking_changes false
-\output_changes false
-\html_math_output 0
-\html_css_as_file 0
-\html_be_strict false
-\end_header
-
-\begin_body
-
-\begin_layout Section
-\begin_inset CommandInset label
-LatexCommand label
-name "sec:Tutorial-Two-hexahedra"
-
-\end_inset
-
-Tutorial Using Two Hexahedra
-\end_layout
-
-\begin_layout Standard
-PyLith features discussed in this tutorial:
-\end_layout
-
-\begin_layout Itemize
-Quasi-static solution
-\end_layout
-
-\begin_layout Itemize
-Mesh ASCII format
-\end_layout
-
-\begin_layout Itemize
-Dirichlet boundary conditions
-\end_layout
-
-\begin_layout Itemize
-Kinematic fault interface conditions
-\end_layout
-
-\begin_layout Itemize
-Maxwell viscoelastic material
-\end_layout
-
-\begin_layout Itemize
-VTK output
-\end_layout
-
-\begin_layout Itemize
-Trilinear hexahedral cells
-\end_layout
-
-\begin_layout Itemize
-SimpleDB spatial database
-\end_layout
-
-\begin_layout Itemize
-ZeroDispDB spatial database
-\end_layout
-
-\begin_layout Itemize
-UniformDB spatial database
-\end_layout
-
-\begin_layout Itemize
-Filtering of cell output fields
-\end_layout
-
-\begin_layout Standard
-All of the files necessary to run the examples are contained in the directory
- 
-\family typewriter
-examples/twocells/twohex8.
-\end_layout
-
-\begin_layout Subsection
-Overview
-\end_layout
-
-\begin_layout Standard
-This tutorial is a simple 3D example of a quasi-static finite element problem.
- It is a mesh composed of two trilinear hexahedra subject to displacement
- boundary conditions.
- One primary difference between this example and the example with two tetrahedra
- is that we use a Maxwell viscoelastic material model, and run the model
- for 10 time steps of 0.1 year each.
- Due to the simple geometry of the problem, the mesh may be constructed
- by hand, using PyLith mesh ASCII format to describe the mesh.
- In this tutorial, we will walk through the steps necessary to construct,
- run, and view three problems that use the same mesh.
- In addition to this manual, each of the files for the example problems
- includes extensive comments.
-\end_layout
-
-\begin_layout Subsection
-Mesh Description
-\end_layout
-
-\begin_layout Standard
-The mesh consists of two hexahedra forming a rectangular prism (Figure 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "fig:twohex8-mesh"
-
-\end_inset
-
-).
- The mesh geometry and topology are described in the file 
-\family typewriter
-twohex8.mesh
-\family default
-, which is in PyLith mesh ASCII format.
-\end_layout
-
-\begin_layout Standard
-\noindent
-\align center
-\begin_inset Float figure
-wide false
-sideways false
-status open
-
-\begin_layout Plain Layout
-\align center
-\begin_inset Graphics
-	filename figs/twohex8-mesh.eps
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Plain Layout
-\begin_inset Caption
-
-\begin_layout Plain Layout
-Mesh composed of two trilinear hexahedral cells used for the example problems.
-\begin_inset CommandInset label
-LatexCommand label
-name "fig:twohex8-mesh"
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Subsection
-Additional Common Information
-\end_layout
-
-\begin_layout Standard
-In addition to the mesh, the three example problems share additional information
-, which we place in 
-\family typewriter
-pylithapp.cfg
-\family default
-.
- Note that in this example we make use of the UniformDB spatial database,
- rather than the SimpleDB implementation used to specify the physical properties
- in the other example problems.
- For simple distributions of material properties (or boundary conditions),
- this implementation is often easier to use.
- Examining 
-\family typewriter
-pylithapp.cfg
-\family default
-, we specify the material information with the following set of parameters:
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.timedependent.materials]
-\end_layout
-
-\begin_layout LyX-Code
-material = pylith.materials.MaxwellIsotropic3D
-\end_layout
-
-\begin_layout LyX-Code
- 
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.timedependent.materials.material]
-\end_layout
-
-\begin_layout LyX-Code
-label = viscoelastic material
-\end_layout
-
-\begin_layout LyX-Code
-id = 1
-\end_layout
-
-\begin_layout LyX-Code
- 
-\end_layout
-
-\begin_layout LyX-Code
-db = spatialdata.spatialdb.UniformDB
-\end_layout
-
-\begin_layout LyX-Code
-db.values = [vp,vs,density,viscosity]
-\end_layout
-
-\begin_layout LyX-Code
-db.data = [5773.502691896258*m/s, 3333.333333333333*m/s, 2700.0*kg/m**3, 1.0e18*Pa*s]
-\end_layout
-
-\begin_layout LyX-Code
- 
-\end_layout
-
-\begin_layout LyX-Code
-quadrature.cell = pylith.feassemble.FIATLagrange
-\end_layout
-
-\begin_layout LyX-Code
-quadrature.cell.dimension = 3
-\end_layout
-
-\begin_layout Subsection
-Axial Displacement Example
-\end_layout
-
-\begin_layout Standard
-The first example problem is extension of the mesh along the long axis of
- the prism.
- Parameter settings that override or augment those in 
-\family typewriter
-pylithapp.cfg
-\family default
- are contained in the file 
-\family typewriter
-axialdisp.cfg
-\family default
-.
- These settings include:
-\end_layout
-
-\begin_layout Description
-pylithapp.timedependent.bc.x_neg Defines which degrees of freedom are being
- constrained (x, y, and z), gives the label (
-\family typewriter
-x_neg
-\family default
-, defined in 
-\family typewriter
-twohex8.mesh
-\family default
-) defining the points desired, assigns a label to the boundary condition
- set, and gives the name of the spatial database with the values for the
- Dirichlet boundary conditions (
-\family typewriter
-axialdisp.spatialdb
-\family default
-).
-\end_layout
-
-\begin_layout Description
-pylithapp.timedependent.bc.x_pos Defines which degrees of freedom are being
- constrained (x, y, and z), gives the label (
-\family typewriter
-x_
-\family default
-pos, defined in 
-\family typewriter
-twohex8.mesh
-\family default
-) defining the points desired, assigns a label to the boundary condition
- set, and gives the name of the spatial database with the values for the
- Dirichlet boundary conditions (
-\family typewriter
-axialdisp.spatialdb
-\family default
-).
-\end_layout
-
-\begin_layout Description
-pylithapp.timedependent.materials.material.output Defines the filter to be used
- when writing cell state variables (average over the quadrature points of
- the cell), specifies which state variables and properties to output, gives
- the base filename for state variable output files, and defines the format
- to use when defining the output filenames for each time step.
-\end_layout
-
-\begin_layout Standard
-The values for the Dirichlet boundary conditions are given in the file 
-\family typewriter
-axialdisp.spatialdb
-\family default
-, as specified in 
-\family typewriter
-axialdisp.cfg
-\family default
-.
- Since data are being specified using two control points (rather than being
- uniform over the mesh, for example), the data dimension is one.
- Note that since we are using a Maxwell viscoelastic model, we request that
- additional state variables and properties be output:
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.timedependent.materials.material.output]
-\end_layout
-
-\begin_layout LyX-Code
-cell_data_fields = [total_strain,viscous_strain,stress]
-\end_layout
-
-\begin_layout LyX-Code
-cell_info_fields = [mu,lambda,density,maxwell_time]
-\end_layout
-
-\begin_layout Standard
-The files containing common information (
-\family typewriter
-twohex8.mesh
-\family default
-, 
-\family typewriter
-pylithapp.cfg
-\family default
-) along with the problem-specific files (
-\family typewriter
-axialdisp.cfg
-\family default
-, 
-\family typewriter
-axialdisp.spatialdb
-\family default
-) provide a complete description of the problem, and we can then run this
- example by typing
-\end_layout
-
-\begin_layout LyX-Code
-pylith axialdisp.cfg
-\end_layout
-
-\begin_layout Standard
-Once the problem has run, two sets of files will be produced, along with
- one additional file.
- The first set will have filenames such as 
-\family typewriter
-axialdisp_txxxx.vtk
-\family default
-, where 
-\family typewriter
-xxxx
-\family default
- is the time for which output has been produced.
- In 
-\family typewriter
-axialdisp.cfg
-\family default
- we specify that the time stamp should be normalized by a value of 1.0 years
- and the time stamp should be of the form 
-\family typewriter
-xxx.x
-\family default
- (recall that the decimal point is removed in the filename).
- As a result, the filenames contain the time in tenths of a year.
- These files will contain mesh information as well as displacement values
- for the mesh vertices at the given time.
- The second set of files will have names such as 
-\family typewriter
-axialdisp-statevars_txxxx.vtk
-\family default
-, where 
-\family typewriter
-xxxx
-\family default
- is the time in tenths of a year (as above) for which output has been produced.
- These files contain the state variables for each cell at the given time.
- The default fields are the total strain and stress fields; however, we
- have also requested the viscous strains.
- As specified in 
-\family typewriter
-axialdisp.cfg
-\family default
-, these values are averaged over each cell.
- The final file (
-\family typewriter
-axialdisp-statevars_info.vtk
-\family default
-) gives the material properties used for the problem.
- We have requested all of the properties available for this material model
- (
-\family typewriter
-mu
-\family default
-, 
-\family typewriter
-lambda
-\family default
-, 
-\family typewriter
-density
-\family default
-, 
-\family typewriter
-maxwell_time
-\family default
-).
- If the problem ran correctly, you should be able to generate a figure such
- as Figure 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "fig:twohex8-axial"
-
-\end_inset
-
-, which was generated using ParaView.
-\end_layout
-
-\begin_layout Standard
-\begin_inset Float figure
-wide false
-sideways false
-status open
-
-\begin_layout Plain Layout
-\align center
-\begin_inset Graphics
-	filename figs/axialdisp.jpg
-	lyxscale 50
-	scale 33
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Plain Layout
-\begin_inset Caption
-
-\begin_layout Plain Layout
-Color contours and vectors of displacement for the axial displacement example
- using a mesh composed of two trilinear hexahedral cells.
-\begin_inset CommandInset label
-LatexCommand label
-name "fig:twohex8-axial"
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Subsection
-Shear Displacement Example
-\end_layout
-
-\begin_layout Standard
-The second example problem is shearing of the mesh in the y direction.
- Parameter settings that override or augment those in 
-\family typewriter
-pylithapp.cfg
-\family default
- are contained in the file 
-\family typewriter
-sheardisp.cfg
-\family default
-.
- These settings include:
-\end_layout
-
-\begin_layout Description
-pylithapp.timedependent.bc.x_neg Defines which degrees of freedom are being
- constrained (x, y, and z), gives the label (
-\family typewriter
-x_neg
-\family default
-, defined in 
-\family typewriter
-twohex8.mesh
-\family default
-) defining the points desired, assigns a label to the boundary condition
- set, and gives the name of the spatial database with the values for the
- Dirichlet boundary conditions (
-\family typewriter
-sheardisp.spatialdb
-\family default
-).
-\end_layout
-
-\begin_layout Description
-pylithapp.timedependent.bc.x_pos Defines which degrees of freedom are being
- constrained (x, y, and z), gives the label (
-\family typewriter
-x_
-\family default
-pos, defined in 
-\family typewriter
-twohex8.mesh
-\family default
-) defining the points desired, assigns a label to the boundary condition
- set, and gives the name of the spatial database with the values for the
- Dirichlet boundary conditions (
-\family typewriter
-sheardisp.spatialdb
-\family default
-).
-\end_layout
-
-\begin_layout Standard
-The values for the Dirichlet boundary conditions are given in the file 
-\family typewriter
-sheardisp.spatialdb
-\family default
-, as specified in 
-\family typewriter
-sheardisp.cfg
-\family default
-.
- Data are being specified at two control points (rather than being uniform
- over the mesh, for example), so the data dimension is one.
- The files containing common information (
-\family typewriter
-twohex8.mesh
-\family default
-, 
-\family typewriter
-pylithapp.cfg
-\family default
-) along with the problem-specific files (
-\family typewriter
-sheardisp.cfg
-\family default
-, 
-\family typewriter
-sheardisp.spatialdb
-\family default
-) provide a complete description of the problem, and we can then run this
- example by typing
-\end_layout
-
-\begin_layout LyX-Code
-pylith sheardisp.cfg
-\end_layout
-
-\begin_layout Standard
-If the problem ran correctly, you should be able to generate a figure such
- as Figure 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "fig:twohex8-shear"
-
-\end_inset
-
-, which was generated using ParaView.
-\end_layout
-
-\begin_layout Standard
-\begin_inset Float figure
-wide false
-sideways false
-status open
-
-\begin_layout Plain Layout
-\align center
-\begin_inset Graphics
-	filename figs/sheardisp.jpg
-	lyxscale 50
-	scale 33
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Plain Layout
-\begin_inset Caption
-
-\begin_layout Plain Layout
-Color contours and vectors of displacement for the shear displacement example
- using a mesh composed of two trilinear hexahedral cells.
-\begin_inset CommandInset label
-LatexCommand label
-name "fig:twohex8-shear"
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Plain Layout
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Subsection
-Kinematic Fault Slip Example
-\end_layout
-
-\begin_layout Standard
-The next example problem is left-lateral fault slip applied between the
- two hexahedral cells using kinematic cohesive cells.
- The vertices away from the fault are held fixed in the x, y, and z directions.
- Parameter settings that override or augment those in 
-\family typewriter
-pylithapp.cfg
-\family default
- are contained in the file 
-\family typewriter
-dislocation.cfg
-\family default
-.
- These settings include:
-\end_layout
-
-\begin_layout Description
-pylithapp.timedependent.bc.x_neg Defines which degrees of freedom are being
- constrained (x, y, and z), gives the label (
-\family typewriter
-x_neg
-\family default
-, defined in 
-\family typewriter
-twohex8.mesh
-\family default
-) defining the points desired, and assigns a label to the boundary condition
- set.
- In this case, we use the default spatial database (ZeroDispDB) for the
- Dirichlet boundary condition, which sets the displacements to zero.
-\end_layout
-
-\begin_layout Description
-pylithapp.timedependent.bc.x_pos Defines which degrees of freedom are being
- constrained (x, y, and z), gives the label (
-\family typewriter
-x_
-\family default
-pos, defined in 
-\family typewriter
-twohex8.mesh
-\family default
-) defining the points desired, and assigns a label to the boundary condition
- set.
-\end_layout
-
-\begin_layout Description
-pylithapp.timedependent.interfaces Gives the label (defined in 
-\family typewriter
-twohex8.mesh
-\family default
-) defining the points on the fault, provides quadrature information, and
- then gives database names for material properties (needed for conditioning),
- fault slip, peak fault slip rate, and fault slip time.
-\end_layout
-
-\begin_layout Standard
-The fault example requires three additional database files that were not
- needed for the simple displacement examples.
- The first file (
-\family typewriter
-dislocation_slip.spatialdb
-\family default
-) specifies 0.01 m of left-lateral fault slip for the entire fault.
- The data dimension is zero since the same data are applied to all points
- in the set.
- The default slip time function is a step-function, so we also must provide
- the time at which slip begins.
- The elastic solution is associated with advancing from 
-\begin_inset Formula $t=-dt$
-\end_inset
-
- to 
-\begin_inset Formula $t=0$
-\end_inset
-
-, so we set the slip initiation time for the step-function to 0 in 
-\family typewriter
-dislocation_sliptime.spatialdb
-\family default
-.
- The files containing common information (
-\family typewriter
-\size small
-twohex8.mesh
-\family default
-, 
-\family typewriter
-pylithapp.cfg
-\family default
-\size default
-) along with the problem-specific files (
-\family typewriter
-\size small
-dislocation.cfg
-\family default
-, 
-\family typewriter
-dislocation_slip.spatialdb
-\family default
-, 
-\family typewriter
-dislocation_sliptime.spatialdb
-\family default
-\size default
-) provide a complete description of the problem, and we can then run this
- example by typing
-\end_layout
-
-\begin_layout LyX-Code
-pylith dislocation.cfg
-\end_layout
-
-\begin_layout Standard
-If the problem ran correctly, you should be able to generate a figure such
- as Figure 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "fig:twohex8-disloc"
-
-\end_inset
-
-, which was generated using ParaView.
-\end_layout
-
-\begin_layout Standard
-\noindent
-\align center
-\begin_inset Float figure
-wide false
-sideways false
-status open
-
-\begin_layout Plain Layout
-\noindent
-\align center
-\begin_inset Graphics
-	filename figs/dislocation.jpg
-	lyxscale 50
-	scale 33
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Plain Layout
-\begin_inset Caption
-
-\begin_layout Plain Layout
-Color contours and vectors of displacement for the kinematic fault example
- using a mesh composed of two trilinear hexahedral cells.
-\begin_inset CommandInset label
-LatexCommand label
-name "fig:twohex8-disloc"
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_body
-\end_document
+#LyX 2.0 created this file. For more info see http://www.lyx.org/
+\lyxformat 413
+\begin_document
+\begin_header
+\textclass book
+\begin_preamble
+
+\end_preamble
+\use_default_options false
+\maintain_unincluded_children false
+\language english
+\language_package default
+\inputencoding latin1
+\fontencoding global
+\font_roman default
+\font_sans default
+\font_typewriter default
+\font_default_family default
+\use_non_tex_fonts false
+\font_sc false
+\font_osf false
+\font_sf_scale 100
+\font_tt_scale 100
+
+\graphics default
+\default_output_format default
+\output_sync 0
+\bibtex_command default
+\index_command default
+\paperfontsize default
+\spacing single
+\use_hyperref false
+\papersize default
+\use_geometry true
+\use_amsmath 0
+\use_esint 0
+\use_mhchem 1
+\use_mathdots 1
+\cite_engine basic
+\use_bibtopic false
+\use_indices false
+\paperorientation portrait
+\suppress_date false
+\use_refstyle 0
+\index Index
+\shortcut idx
+\color #008000
+\end_index
+\leftmargin 1in
+\topmargin 1in
+\rightmargin 1in
+\bottommargin 2in
+\secnumdepth 3
+\tocdepth 3
+\paragraph_separation indent
+\paragraph_indentation default
+\quotes_language english
+\papercolumns 1
+\papersides 1
+\paperpagestyle default
+\tracking_changes false
+\output_changes false
+\html_math_output 0
+\html_css_as_file 0
+\html_be_strict false
+\end_header
+
+\begin_body
+
+\begin_layout Section
+\begin_inset CommandInset label
+LatexCommand label
+name "sec:Tutorial-Two-hexahedra"
+
+\end_inset
+
+Tutorial Using Two Hexahedra
+\end_layout
+
+\begin_layout Standard
+PyLith features discussed in this tutorial:
+\end_layout
+
+\begin_layout Itemize
+Quasi-static solution
+\end_layout
+
+\begin_layout Itemize
+Mesh ASCII format
+\end_layout
+
+\begin_layout Itemize
+Dirichlet boundary conditions
+\end_layout
+
+\begin_layout Itemize
+Kinematic fault interface conditions
+\end_layout
+
+\begin_layout Itemize
+Maxwell viscoelastic material
+\end_layout
+
+\begin_layout Itemize
+VTK output
+\end_layout
+
+\begin_layout Itemize
+Trilinear hexahedral cells
+\end_layout
+
+\begin_layout Itemize
+SimpleDB spatial database
+\end_layout
+
+\begin_layout Itemize
+ZeroDispDB spatial database
+\end_layout
+
+\begin_layout Itemize
+UniformDB spatial database
+\end_layout
+
+\begin_layout Itemize
+Filtering of cell output fields
+\end_layout
+
+\begin_layout Standard
+All of the files necessary to run the examples are contained in the directory
+ 
+\family typewriter
+examples/twocells/twohex8.
+\end_layout
+
+\begin_layout Subsection
+Overview
+\end_layout
+
+\begin_layout Standard
+This tutorial is a simple 3D example of a quasi-static finite element problem.
+ It is a mesh composed of two trilinear hexahedra subject to displacement
+ boundary conditions.
+ One primary difference between this example and the example with two tetrahedra
+ is that we use a Maxwell viscoelastic material model, and run the model
+ for 10 time steps of 0.1 year each.
+ Due to the simple geometry of the problem, the mesh may be constructed
+ by hand, using PyLith mesh ASCII format to describe the mesh.
+ In this tutorial, we will walk through the steps necessary to construct,
+ run, and view three problems that use the same mesh.
+ In addition to this manual, each of the files for the example problems
+ includes extensive comments.
+\end_layout
+
+\begin_layout Subsection
+Mesh Description
+\end_layout
+
+\begin_layout Standard
+The mesh consists of two hexahedra forming a rectangular prism (Figure 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "fig:twohex8-mesh"
+
+\end_inset
+
+).
+ The mesh geometry and topology are described in the file 
+\family typewriter
+twohex8.mesh
+\family default
+, which is in PyLith mesh ASCII format.
+\end_layout
+
+\begin_layout Standard
+\noindent
+\align center
+\begin_inset Float figure
+wide false
+sideways false
+status open
+
+\begin_layout Plain Layout
+\align center
+\begin_inset Graphics
+	filename figs/twohex8-mesh.eps
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Plain Layout
+\begin_inset Caption
+
+\begin_layout Plain Layout
+Mesh composed of two trilinear hexahedral cells used for the example problems.
+\begin_inset CommandInset label
+LatexCommand label
+name "fig:twohex8-mesh"
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Subsection
+Additional Common Information
+\end_layout
+
+\begin_layout Standard
+In addition to the mesh, the three example problems share additional information
+, which we place in 
+\family typewriter
+pylithapp.cfg
+\family default
+.
+ Note that in this example we make use of the UniformDB spatial database,
+ rather than the SimpleDB implementation used to specify the physical properties
+ in the other example problems.
+ For simple distributions of material properties (or boundary conditions),
+ this implementation is often easier to use.
+ Examining 
+\family typewriter
+pylithapp.cfg
+\family default
+, we specify the material information with the following set of parameters:
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.timedependent.materials]
+\end_layout
+
+\begin_layout LyX-Code
+material = pylith.materials.MaxwellIsotropic3D
+\end_layout
+
+\begin_layout LyX-Code
+ 
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.timedependent.materials.material]
+\end_layout
+
+\begin_layout LyX-Code
+label = viscoelastic material
+\end_layout
+
+\begin_layout LyX-Code
+id = 1
+\end_layout
+
+\begin_layout LyX-Code
+ 
+\end_layout
+
+\begin_layout LyX-Code
+db = spatialdata.spatialdb.UniformDB
+\end_layout
+
+\begin_layout LyX-Code
+db.values = [vp,vs,density,viscosity]
+\end_layout
+
+\begin_layout LyX-Code
+db.data = [5773.502691896258*m/s, 3333.333333333333*m/s, 2700.0*kg/m**3, 1.0e18*Pa*s]
+\end_layout
+
+\begin_layout LyX-Code
+ 
+\end_layout
+
+\begin_layout LyX-Code
+quadrature.cell = pylith.feassemble.FIATLagrange
+\end_layout
+
+\begin_layout LyX-Code
+quadrature.cell.dimension = 3
+\end_layout
+
+\begin_layout Subsection
+Axial Displacement Example
+\end_layout
+
+\begin_layout Standard
+The first example problem is extension of the mesh along the long axis of
+ the prism.
+ Parameter settings that override or augment those in 
+\family typewriter
+pylithapp.cfg
+\family default
+ are contained in the file 
+\family typewriter
+axialdisp.cfg
+\family default
+.
+ These settings include:
+\end_layout
+
+\begin_layout Description
+pylithapp.timedependent.bc.x_neg Defines which degrees of freedom are being
+ constrained (x, y, and z), gives the label (
+\family typewriter
+x_neg
+\family default
+, defined in 
+\family typewriter
+twohex8.mesh
+\family default
+) defining the points desired, assigns a label to the boundary condition
+ set, and gives the name of the spatial database with the values for the
+ Dirichlet boundary conditions (
+\family typewriter
+axialdisp.spatialdb
+\family default
+).
+\end_layout
+
+\begin_layout Description
+pylithapp.timedependent.bc.x_pos Defines which degrees of freedom are being
+ constrained (x, y, and z), gives the label (
+\family typewriter
+x_pos
+\family default
+, defined in 
+\family typewriter
+twohex8.mesh
+\family default
+) defining the points desired, assigns a label to the boundary condition
+ set, and gives the name of the spatial database with the values for the
+ Dirichlet boundary conditions (
+\family typewriter
+axialdisp.spatialdb
+\family default
+).
+\end_layout
+
+\begin_layout Description
+pylithapp.timedependent.materials.material.output Defines the filter to be used
+ when writing cell state variables (average over the quadrature points of
+ the cell), specifies which state variables and properties to output, gives
+ the base filename for state variable output files, and defines the format
+ to use when defining the output filenames for each time step.
+\end_layout
+
+\begin_layout Standard
+The values for the Dirichlet boundary conditions are given in the file 
+\family typewriter
+axialdisp.spatialdb
+\family default
+, as specified in 
+\family typewriter
+axialdisp.cfg
+\family default
+.
+ Since data are being specified using two control points (rather than being
+ uniform over the mesh, for example), the data dimension is one.
+ Note that since we are using a Maxwell viscoelastic model, we request that
+ additional state variables and properties be output:
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.timedependent.materials.material.output]
+\end_layout
+
+\begin_layout LyX-Code
+cell_data_fields = [total_strain,viscous_strain,stress]
+\end_layout
+
+\begin_layout LyX-Code
+cell_info_fields = [mu,lambda,density,maxwell_time]
+\end_layout
+
+\begin_layout Standard
+The files containing common information (
+\family typewriter
+twohex8.mesh
+\family default
+, 
+\family typewriter
+pylithapp.cfg
+\family default
+) along with the problem-specific files (
+\family typewriter
+axialdisp.cfg
+\family default
+, 
+\family typewriter
+axialdisp.spatialdb
+\family default
+) provide a complete description of the problem, and we can then run this
+ example by typing
+\end_layout
+
+\begin_layout LyX-Code
+pylith axialdisp.cfg
+\end_layout
+
+\begin_layout Standard
+Once the problem has run, two sets of files will be produced, along with
+ one additional file.
+ The first set will have filenames such as 
+\family typewriter
+axialdisp_txxxx.vtk
+\family default
+, where 
+\family typewriter
+xxxx
+\family default
+ is the time for which output has been produced.
+ In 
+\family typewriter
+axialdisp.cfg
+\family default
+ we specify that the time stamp should be normalized by a value of 1.0 years
+ and the time stamp should be of the form 
+\family typewriter
+xxx.x
+\family default
+ (recall that the decimal point is removed in the filename).
+ As a result, the filenames contain the time in tenths of a year.
+ These files will contain mesh information as well as displacement values
+ for the mesh vertices at the given time.
+ The second set of files will have names such as 
+\family typewriter
+axialdisp-statevars_txxxx.vtk
+\family default
+, where 
+\family typewriter
+xxxx
+\family default
+ is the time in tenths of a year (as above) for which output has been produced.
+ These files contain the state variables for each cell at the given time.
+ The default fields are the total strain and stress fields; however, we
+ have also requested the viscous strains.
+ As specified in 
+\family typewriter
+axialdisp.cfg
+\family default
+, these values are averaged over each cell.
+ The final file (
+\family typewriter
+axialdisp-statevars_info.vtk
+\family default
+) gives the material properties used for the problem.
+ We have requested all of the properties available for this material model
+ (
+\family typewriter
+mu
+\family default
+, 
+\family typewriter
+lambda
+\family default
+, 
+\family typewriter
+density
+\family default
+, 
+\family typewriter
+maxwell_time
+\family default
+).
+ If the problem ran correctly, you should be able to produce a figure such
+ as Figure 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "fig:twohex8-axial"
+
+\end_inset
+
+, which was generated using ParaView.
+\end_layout
+
+\begin_layout Standard
+\begin_inset Float figure
+wide false
+sideways false
+status open
+
+\begin_layout Plain Layout
+\align center
+\begin_inset Graphics
+	filename figs/axialdisp.jpg
+	lyxscale 50
+	scale 33
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Plain Layout
+\begin_inset Caption
+
+\begin_layout Plain Layout
+Color contours and vectors of displacement for the axial displacement example
+ using a mesh composed of two trilinear hexahedral cells.
+\begin_inset CommandInset label
+LatexCommand label
+name "fig:twohex8-axial"
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Subsection
+Shear Displacement Example
+\end_layout
+
+\begin_layout Standard
+The second example problem is shearing of the mesh in the y direction.
+ Parameter settings that override or augment those in 
+\family typewriter
+pylithapp.cfg
+\family default
+ are contained in the file 
+\family typewriter
+sheardisp.cfg
+\family default
+.
+ These settings include:
+\end_layout
+
+\begin_layout Description
+pylithapp.timedependent.bc.x_neg Defines which degrees of freedom are being
+ constrained (x, y, and z), gives the label (
+\family typewriter
+x_neg
+\family default
+, defined in 
+\family typewriter
+twohex8.mesh
+\family default
+) defining the points desired, assigns a label to the boundary condition
+ set, and gives the name of the spatial database with the values for the
+ Dirichlet boundary conditions (
+\family typewriter
+sheardisp.spatialdb
+\family default
+).
+\end_layout
+
+\begin_layout Description
+pylithapp.timedependent.bc.x_pos Defines which degrees of freedom are being
+ constrained (x, y, and z), gives the label (
+\family typewriter
+x_pos
+\family default
+, defined in 
+\family typewriter
+twohex8.mesh
+\family default
+) defining the points desired, assigns a label to the boundary condition
+ set, and gives the name of the spatial database with the values for the
+ Dirichlet boundary conditions (
+\family typewriter
+sheardisp.spatialdb
+\family default
+).
+\end_layout
+
+\begin_layout Standard
+The values for the Dirichlet boundary conditions are given in the file 
+\family typewriter
+sheardisp.spatialdb
+\family default
+, as specified in 
+\family typewriter
+sheardisp.cfg
+\family default
+.
+ Data are being specified at two control points (rather than being uniform
+ over the mesh, for example), so the data dimension is one.
+ The files containing common information (
+\family typewriter
+twohex8.mesh
+\family default
+, 
+\family typewriter
+pylithapp.cfg
+\family default
+) along with the problem-specific files (
+\family typewriter
+sheardisp.cfg
+\family default
+, 
+\family typewriter
+sheardisp.spatialdb
+\family default
+) provide a complete description of the problem, and we can then run this
+ example by typing
+\end_layout
+
+\begin_layout LyX-Code
+pylith sheardisp.cfg
+\end_layout
+
+\begin_layout Standard
+If the problem ran correctly, you should be able to generate a figure such
+ as Figure 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "fig:twohex8-shear"
+
+\end_inset
+
+, which was generated using ParaView.
+\end_layout
+
+\begin_layout Standard
+\begin_inset Float figure
+wide false
+sideways false
+status open
+
+\begin_layout Plain Layout
+\align center
+\begin_inset Graphics
+	filename figs/sheardisp.jpg
+	lyxscale 50
+	scale 33
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Plain Layout
+\begin_inset Caption
+
+\begin_layout Plain Layout
+Color contours and vectors of displacement for the shear displacement example
+ using a mesh composed of two trilinear hexahedral cells.
+\begin_inset CommandInset label
+LatexCommand label
+name "fig:twohex8-shear"
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Subsection
+Kinematic Fault Slip Example
+\end_layout
+
+\begin_layout Standard
+The next example problem is left-lateral fault slip applied between the
+ two hexahedral cells using kinematic cohesive cells.
+ The vertices away from the fault are held fixed in the x, y, and z directions.
+ Parameter settings that override or augment those in 
+\family typewriter
+pylithapp.cfg
+\family default
+ are contained in the file 
+\family typewriter
+dislocation.cfg
+\family default
+.
+ These settings include:
+\end_layout
+
+\begin_layout Description
+pylithapp.timedependent.bc.x_neg Defines which degrees of freedom are being
+ constrained (x, y, and z), gives the label (
+\family typewriter
+x_neg
+\family default
+, defined in 
+\family typewriter
+twohex8.mesh
+\family default
+) defining the points desired, and assigns a label to the boundary condition
+ set.
+ In this case, we use the default spatial database (ZeroDispDB) for the
+ Dirichlet boundary condition, which sets the displacements to zero.
+\end_layout
+
+\begin_layout Description
+pylithapp.timedependent.bc.x_pos Defines which degrees of freedom are being
+ constrained (x, y, and z), gives the label (
+\family typewriter
+x_pos
+\family default
+, defined in 
+\family typewriter
+twohex8.mesh
+\family default
+) defining the points desired, and assigns a label to the boundary condition
+ set.
+\end_layout
+
+\begin_layout Description
+pylithapp.timedependent.interfaces Gives the label (defined in 
+\family typewriter
+twohex8.mesh
+\family default
+) defining the points on the fault, provides quadrature information, and
+ then gives database names for material properties (needed for conditioning),
+ fault slip, peak fault slip rate, and fault slip time.
+\end_layout
+
+\begin_layout Standard
+The fault example requires three additional database files that were not
+ needed for the simple displacement examples.
+ The first file (
+\family typewriter
+dislocation_slip.spatialdb
+\family default
+) specifies 0.01 m of left-lateral fault slip for the entire fault.
+ The data dimension is zero since the same data are applied to all points
+ in the set.
+ The default slip time function is a step-function, so we also must provide
+ the time at which slip begins.
+ The elastic solution is associated with advancing from 
+\begin_inset Formula $t=-dt$
+\end_inset
+
+ to 
+\begin_inset Formula $t=0$
+\end_inset
+
+, so we set the slip initiation time for the step-function to 0 in 
+\family typewriter
+dislocation_sliptime.spatialdb
+\family default
+.
+ The files containing common information (
+\family typewriter
+\size small
+twohex8.mesh
+\family default
+, 
+\family typewriter
+pylithapp.cfg
+\family default
+\size default
+) along with the problem-specific files (
+\family typewriter
+\size small
+dislocation.cfg
+\family default
+, 
+\family typewriter
+dislocation_slip.spatialdb
+\family default
+, 
+\family typewriter
+dislocation_sliptime.spatialdb
+\family default
+\size default
+) provide a complete description of the problem, and we can then run this
+ example by typing
+\end_layout
+
+\begin_layout LyX-Code
+pylith dislocation.cfg
+\end_layout
+
+\begin_layout Standard
+If the problem ran correctly, you should be able to generate a figure such
+ as Figure 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "fig:twohex8-disloc"
+
+\end_inset
+
+, which was generated using ParaView.
+\end_layout
+
+\begin_layout Standard
+\noindent
+\align center
+\begin_inset Float figure
+wide false
+sideways false
+status open
+
+\begin_layout Plain Layout
+\noindent
+\align center
+\begin_inset Graphics
+	filename figs/dislocation.jpg
+	lyxscale 50
+	scale 33
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Plain Layout
+\begin_inset Caption
+
+\begin_layout Plain Layout
+Color contours and vectors of displacement for the kinematic fault example
+ using a mesh composed of two trilinear hexahedral cells.
+\begin_inset CommandInset label
+LatexCommand label
+name "fig:twohex8-disloc"
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\end_body
+\end_document

Modified: short/3D/PyLith/branches/v1.7-trunk/doc/userguide/tutorials/twoquad4/twoquad4.lyx
===================================================================
--- short/3D/PyLith/branches/v1.7-trunk/doc/userguide/tutorials/twoquad4/twoquad4.lyx	2012-06-25 04:52:47 UTC (rev 20403)
+++ short/3D/PyLith/branches/v1.7-trunk/doc/userguide/tutorials/twoquad4/twoquad4.lyx	2012-06-25 16:38:44 UTC (rev 20404)
@@ -1,1001 +1,1001 @@
-#LyX 2.0 created this file. For more info see http://www.lyx.org/
-\lyxformat 413
-\begin_document
-\begin_header
-\textclass book
-\begin_preamble
-
-\end_preamble
-\use_default_options false
-\maintain_unincluded_children false
-\language english
-\language_package default
-\inputencoding latin1
-\fontencoding global
-\font_roman default
-\font_sans default
-\font_typewriter default
-\font_default_family default
-\use_non_tex_fonts false
-\font_sc false
-\font_osf false
-\font_sf_scale 100
-\font_tt_scale 100
-
-\graphics default
-\default_output_format default
-\output_sync 0
-\bibtex_command default
-\index_command default
-\paperfontsize default
-\spacing single
-\use_hyperref false
-\papersize default
-\use_geometry true
-\use_amsmath 0
-\use_esint 0
-\use_mhchem 1
-\use_mathdots 1
-\cite_engine basic
-\use_bibtopic false
-\use_indices false
-\paperorientation portrait
-\suppress_date false
-\use_refstyle 0
-\index Index
-\shortcut idx
-\color #008000
-\end_index
-\leftmargin 1in
-\topmargin 1in
-\rightmargin 1in
-\bottommargin 1in
-\secnumdepth 3
-\tocdepth 3
-\paragraph_separation indent
-\paragraph_indentation default
-\quotes_language english
-\papercolumns 1
-\papersides 1
-\paperpagestyle default
-\tracking_changes false
-\output_changes false
-\html_math_output 0
-\html_css_as_file 0
-\html_be_strict false
-\end_header
-
-\begin_body
-
-\begin_layout Section
-\begin_inset CommandInset label
-LatexCommand label
-name "sec:Tutorial-Two-quad4"
-
-\end_inset
-
-Tutorial Using Two Quadrilaterals
-\end_layout
-
-\begin_layout Standard
-PyLith features discussed in this tutorial:
-\end_layout
-
-\begin_layout Itemize
-Quasi-static solution
-\end_layout
-
-\begin_layout Itemize
-Mesh ASCII format
-\end_layout
-
-\begin_layout Itemize
-Dirichlet boundary conditions
-\end_layout
-
-\begin_layout Itemize
-Neumann boundary conditions
-\end_layout
-
-\begin_layout Itemize
-Kinematic fault interface conditions
-\end_layout
-
-\begin_layout Itemize
-Plane strain linearly elastic material
-\end_layout
-
-\begin_layout Itemize
-VTK output
-\end_layout
-
-\begin_layout Itemize
-Bilinear quadrilateral cells
-\end_layout
-
-\begin_layout Itemize
-SimpleDB spatial database
-\end_layout
-
-\begin_layout Itemize
-ZeroDispDB spatial database
-\end_layout
-
-\begin_layout Standard
-All of the files necessary to run the examples are contained in the directory
- 
-\family typewriter
-examples/twocells/twoquad4.
-\end_layout
-
-\begin_layout Subsection
-Overview
-\end_layout
-
-\begin_layout Standard
-This tutorial is another simple 2D example of a quasi-static finite element
- problem.
- It is a mesh composed of two bilinear quadrilaterals subject to displacement
- or traction boundary conditions, assuming plane-strain linear elastic behavior.
- Due to the simple geometry of the problem, the mesh may be constructed
- by hand, using PyLith mesh ASCII format to describe the mesh.
- In this tutorial, we will walk through the steps necessary to construct,
- run, and view four problems that use the same mesh.
- In addition to this manual, each of the files for the example problem includes
- extensive comments.
-\end_layout
-
-\begin_layout Subsection
-Mesh Description
-\end_layout
-
-\begin_layout Standard
-The mesh consists of two square cells with edge lengths of one unit forming
- a regular region (Figure 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "fig:twoquad4-mesh"
-
-\end_inset
-
-).
- The mesh geometry and topology are described in the file 
-\family typewriter
-twoquad4.mesh
-\family default
-, which is in PyLith mesh ASCII format.
- This file describes the dimensionality of the problem (in this case 2D),
- the coordinates of the vertices (nodes), the vertices composing each cell
- (element), the material ID to be associated with each cell, and then provides
- groups of vertices that may be used to define faults or surfaces to which
- boundary conditions may be applied.
-\end_layout
-
-\begin_layout Standard
-\noindent
-\align center
-\begin_inset Float figure
-wide false
-sideways false
-status open
-
-\begin_layout Plain Layout
-\align center
-\begin_inset Graphics
-	filename figs/twoquad4-mesh.eps
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Plain Layout
-\begin_inset Caption
-
-\begin_layout Plain Layout
-Mesh composed of two bilinear quadrilateral cells used for the example problems.
-\begin_inset CommandInset label
-LatexCommand label
-name "fig:twoquad4-mesh"
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Subsection
-Additional Common Information
-\end_layout
-
-\begin_layout Standard
-In addition to the mesh, the four example problems share additional information.
- As in the previous examples, we place this information in 
-\family typewriter
-pylithapp.cfg
-\family default
-, since this file is read automatically every time PyLith is run.
- Settings specific to a particular problem may be placed in other 
-\family typewriter
-.cfg
-\family default
- files, as described later, and then those files are placed on the command
- line.
-\end_layout
-
-\begin_layout Subsection
-Axial Displacement Example
-\end_layout
-
-\begin_layout Standard
-The first example problem is extension of the mesh along the x axis.
- Parameter settings that override or augment those in 
-\family typewriter
-pylithapp.cfg
-\family default
- are contained in the file 
-\family typewriter
-axialdisp.cfg
-\family default
-.
- These include:
-\end_layout
-
-\begin_layout Description
-pylithapp.timedependent.bc.x_neg Specifies the boundary conditions for the
- left side of the mesh, defining which degrees of freedom are being constrained
- (x), giving the label (defined in 
-\family typewriter
-twoquad4.mesh
-\family default
-) defining the points desired, assigning a label to the boundary condition
- set, and giving the name of the spatial database with the values for the
- Dirichlet boundary condition (
-\family typewriter
-axialdisp.spatialdb
-\family default
-).
-\end_layout
-
-\begin_layout Description
-pylithapp.timedependent.bc.x_pos Specifies the boundary conditions for the
- right side of the mesh, defining which degrees of freedom are being constrained
- (x), giving the label (defined in 
-\family typewriter
-twoquad4.mesh
-\family default
-) defining the points desired, assigning a label to the boundary condition
- set, and giving the name of the spatial database defining the boundary
- conditions (
-\family typewriter
-axialdisp.spatialdb
-\family default
-).
-\end_layout
-
-\begin_layout Description
-pylithapp.timedependent.bc.y_neg Specifies the boundary conditions for the
- bottom two corners of the mesh, defining which degrees of freedom are being
- constrained (y), giving the label (defined in 
-\family typewriter
-twoquad4.mesh
-\family default
-) defining the points desired, assigning a label to the boundary condition
- set, and giving the name of the spatial database with the values for the
- Dirichlet boundary condition (
-\family typewriter
-axialdisp.spatialdb
-\family default
-).
-\end_layout
-
-\begin_layout Standard
-The values for the Dirichlet boundary condition are given in the file 
-\family typewriter
-axialdisp.spatialdb
-\family default
-, as specified in 
-\family typewriter
-axialdisp.cfg
-\family default
-.
- Because the data are being specified using two control points with a linear
- variation in the values between the two (rather than being uniform over
- the mesh, for example), the data dimension is one.
-\end_layout
-
-\begin_layout Standard
-The files containing common information (
-\family typewriter
-twoquad4.mesh
-\family default
-, 
-\family typewriter
-pylithapp.cfg
-\family default
-, 
-\family typewriter
-matprops.spatialdb
-\family default
-) along with the problem-specific files (
-\family typewriter
-axialdisp.cfg
-\family default
-, 
-\family typewriter
-axialdisp.spatialdb
-\family default
-) provide a complete description of the problem, and we can then run this
- example by typing
-\end_layout
-
-\begin_layout LyX-Code
-pylith axialdisp.cfg
-\end_layout
-
-\begin_layout Standard
-As in the two triangle axial displacement example, three files will be produced.
- If the problem ran correctly, you should be able to generate a figure such
- as Figure 
-\begin_inset CommandInset ref
-LatexCommand vref
-reference "fig:twoquad4-axial"
-
-\end_inset
-
-, which was generated using ParaView.
-\end_layout
-
-\begin_layout Standard
-\noindent
-\align center
-\begin_inset Float figure
-placement t
-wide false
-sideways false
-status open
-
-\begin_layout Plain Layout
-\align center
-\begin_inset Graphics
-	filename figs/axialdisp.jpg
-	lyxscale 50
-	scale 33
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Plain Layout
-\begin_inset Caption
-
-\begin_layout Plain Layout
-Color contours and vectors of displacement for the axial displacement example
- using a mesh composed of two bilinear quadrilateral cells.
-\begin_inset CommandInset label
-LatexCommand label
-name "fig:twoquad4-axial"
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Subsection
-Shear Displacement Example
-\end_layout
-
-\begin_layout Standard
-The next example problem is shearing of the mesh in the y direction using
- displacements applied along the positive and negative x boundaries.
- Parameter settings that override or augment those in 
-\family typewriter
-pylithapp.cfg
-\family default
- are contained in the file 
-\family typewriter
-sheardisp.cfg
-\family default
-.
- These include:
-\end_layout
-
-\begin_layout Description
-pylithapp.timedependent.bc.x_neg Specifies the boundary conditions for the
- left side of the mesh, defining which degrees of freedom are being constrained
- (x and y), giving the label (
-\family typewriter
-x_neg
-\family default
-, defined in 
-\family typewriter
-twoquad4.mesh
-\family default
-) defining the points desired, assigning a label to the boundary condition
- set, and giving the name of the spatial database with the values for the
- Dirichlet boundary condition (
-\family typewriter
-sheardisp.spatialdb
-\family default
-).
-\end_layout
-
-\begin_layout Description
-pylithapp.timedependent.bc.x_pos Specifies the boundary conditions for the
- left side of the mesh, defining which degrees of freedom are being constrained
- (y only), giving the label (
-\family typewriter
-x_
-\family default
-pos, defined in 
-\family typewriter
-twoquad4.mesh
-\family default
-) defining the points desired, assigning a label to the boundary condition
- set, and giving the name of the spatial database with the values for the
- Dirichlet boundary condition (
-\family typewriter
-sheardisp.spatialdb
-\family default
-).
-\end_layout
-
-\begin_layout Standard
-The values for the Dirichlet boundary conditions are described in the file
- 
-\family typewriter
-sheardisp.spatialdb
-\family default
-, as specified in 
-\family typewriter
-sheardisp.cfg
-\family default
-.
- In this case, the desired displacement values are given at two control
- points, corresponding to the two edges we want to constrain.
- Since data are being specified at two points with a linear variations in
- the values between the points (rather than being uniform over the mesh,
- for example), the data dimension is one.
-\end_layout
-
-\begin_layout Standard
-The files containing common information (
-\family typewriter
-twoquad4.mesh
-\family default
-, 
-\family typewriter
-pylithapp.cfg
-\family default
-, 
-\family typewriter
-matprops.spatialdb
-\family default
-) along with the problem-specific files (
-\family typewriter
-sheardisp.cfg
-\family default
-, 
-\family typewriter
-sheardisp.spatialdb
-\family default
-) provide a complete description of the problem, and we can then run this
- example by typing
-\end_layout
-
-\begin_layout LyX-Code
-pylith sheardisp.cfg
-\end_layout
-
-\begin_layout Standard
-As in the previous example, three files will be produced.
- If the problem ran correctly, you should be able to generate a figure such
- as Figure 
-\begin_inset CommandInset ref
-LatexCommand vref
-reference "fig:twoquad4-shear"
-
-\end_inset
-
-, which was generated using ParaView.
-\end_layout
-
-\begin_layout Standard
-\begin_inset Float figure
-wide false
-sideways false
-status open
-
-\begin_layout Plain Layout
-\align center
-\begin_inset Graphics
-	filename figs/sheardispl.jpg
-	lyxscale 50
-	scale 33
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Plain Layout
-\begin_inset Caption
-
-\begin_layout Plain Layout
-Color contours and vectors of displacement for the shear displacement example
- using a mesh composed of two bilinear quadrilateral cells.
-\begin_inset CommandInset label
-LatexCommand label
-name "fig:twoquad4-shear"
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Subsection
-Kinematic Fault Slip Example
-\end_layout
-
-\begin_layout Standard
-The next example problem is a left-lateral fault slip applied between the
- two square cells using kinematic cohesive cells.
- The left and right boundaries are held fixed in the x and y directions.
- Parameter settings that override or augment those in 
-\family typewriter
-pylithapp.cfg
-\family default
- are contained in the file 
-\family typewriter
-dislocation.cfg
-\family default
-.
- These settings include:
-\end_layout
-
-\begin_layout Description
-pylithapp.timedependent.bc.x_neg Specifies the boundary conditions for the
- left side of the mesh, defining which degrees of freedom are being constrained
- (x and y), giving the label (
-\family typewriter
-x_neg
-\family default
-, defined in 
-\family typewriter
-twoquad4.mesh
-\family default
-) defining the points desired, and assigning a label to the boundary condition
- set.
- Instead of specifying a spatial database file for the values of the Dirichlet
- boundary condition, we use the default spatial database (ZeroDispDB) for
- the Dirichlet boundary condition, which sets the displacements to zero
- for all time.
-\end_layout
-
-\begin_layout Description
-pylithapp.timedependent.bc.x_pos Specifies the boundary conditions for the
- right side of the mesh, defining which degrees of freedom are being constrained
- (x and y), giving the label (
-\family typewriter
-x_neg
-\family default
-, defined in 
-\family typewriter
-twoquad4.mesh
-\family default
-) defining the points desired, and assigning a label to the boundary condition
- set.
- We use the ZeroDispDB for this boundary condition as well, which sets the
- displacements to zero for all time.
-\end_layout
-
-\begin_layout Description
-pylithapp.timedependent.interfaces Gives the label (defined in 
-\family typewriter
-twoquad4.mesh
-\family default
-) defining the points on the fault, provides quadrature information, and
- then gives database names for material properties (needed for conditioning),
- fault slip, peak fault slip rate, and fault slip time.
-\end_layout
-
-\begin_layout Standard
-The fault example requires three additional database files that were not
- needed for the simple displacement examples.
- The first file (
-\family typewriter
-dislocation_slip.spatialdb
-\family default
-) specifies 0.01 m of left-lateral fault slip for the entire fault.
- The data dimension is zero since the same data are applied to all points
- in the set.
- The default slip time function is a step-function, so we also must provide
- the time at which slip begins.
- The elastic solution is associated with advancing from 
-\begin_inset Formula $t=-dt$
-\end_inset
-
- to 
-\begin_inset Formula $t=0$
-\end_inset
-
-, so we set the slip initiation time for the step-function to 0 in 
-\family typewriter
-dislocation_sliptime.spatialdb
-\family default
-.
-\end_layout
-
-\begin_layout Standard
-The files containing common information (
-\family typewriter
-twoquad4.mesh
-\family default
-, 
-\family typewriter
-pylithapp.cfg
-\family default
-, 
-\family typewriter
-matprops.spatialdb
-\family default
-) along with the problem-specific files (
-\family typewriter
-\size small
-dislocation.cfg
-\family default
-, 
-\family typewriter
-dislocation_slip.spatialdb
-\family default
-, 
-\family typewriter
-dislocation_sliptime.spatialdb
-\family default
-\size default
-) provide a complete description of the problem, and we can then run this
- example by typing
-\end_layout
-
-\begin_layout LyX-Code
-pylith dislocation.cfg
-\end_layout
-
-\begin_layout Standard
-The additional of a fault results in two additional output files (as in
- the two triangle fault example), 
-\family typewriter
-dislocation-fault_t0000000.vtk
-\family default
- and 
-\family typewriter
-dislocation-fault_info.vtk
-\family default
-.
- These files provide output of fault slip, change in tractions, and diagnostic
- information such as the normal direction, final slip, and slip time for
- each vertex on the fault.
- If the problem ran correctly, you should be able to generate a figure such
- as Figure 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "fig:twoquad4-disloc"
-
-\end_inset
-
-, which was generated using ParaView.
-\end_layout
-
-\begin_layout Standard
-\begin_inset Float figure
-wide false
-sideways false
-status open
-
-\begin_layout Plain Layout
-\align center
-\begin_inset Graphics
-	filename figs/dislocation.jpg
-	lyxscale 50
-	scale 33
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Plain Layout
-\begin_inset Caption
-
-\begin_layout Plain Layout
-Color contours and vectors of displacement for the kinematic fault example
- using a mesh composed of two bilinear quadrilateral cells.
-\begin_inset CommandInset label
-LatexCommand label
-name "fig:twoquad4-disloc"
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Subsection
-\begin_inset CommandInset label
-LatexCommand label
-name "sub:Tutorial-twoquad4-traction"
-
-\end_inset
-
-Axial Traction Example
-\end_layout
-
-\begin_layout Standard
-The fourth example demonstrates the use of Neumann (traction) boundary condition
-s.
- Constant tractions are applied to the right edge of the mesh, while displacemen
-ts normal to the boundaries are held fixed along the left and bottom edges
- of the mesh.
- Parameter settings that override or augment those in 
-\family typewriter
-pylithapp.cfg
-\family default
- are contained in the file 
-\family typewriter
-axialtract.cfg
-\family default
-.
- These settings include:
-\end_layout
-
-\begin_layout Description
-pylithapp.timedependent Specifies an implicit formulation for the problem
- and specifies the array of boundary conditions.
- The boundary condition type for 
-\family typewriter
-x_pos
-\family default
- is explicitly set to 
-\family typewriter
-Neumann
-\family default
-, since the default boundary condition type is 
-\family typewriter
-Dirichlet
-\family default
-.
-\end_layout
-
-\begin_layout Description
-pylithapp.timedependent.bc.x_neg Specifies the boundary conditions for the
- left side of the mesh, defining which degrees of freedom are being constrained
- (x) and giving the label (defined in 
-\family typewriter
-twoquad4.mesh
-\family default
-) defining the points desired.
- In this case, rather than specifying a spatial database file with values
- for the Dirichlet boundary conditions, we use the default spatial database
- (ZeroDispDB) for the Dirichlet boundary condition, which sets the displacements
- to zero for all time.
-\end_layout
-
-\begin_layout Description
-pylithapp.timedependent.bc.x_pos Specifies the Neumann boundary conditions
- for the right side of the mesh, giving the label (defined in 
-\family typewriter
-twoquad4.mesh
-\family default
-) defining the points desired, assigning a label to the boundary condition
- set, and giving the name of the spatial database with the traction vectors
- for the Neumann boundary condition (
-\family typewriter
-axialtract.spatialdb
-\family default
-).
-\end_layout
-
-\begin_layout Description
-pylithapp.timedependent.bc.y_neg Specifies the boundary conditions for the
- bottom two corners of the mesh, defining which degrees of freedom are being
- constrained (y) and giving the label (defined in 
-\family typewriter
-twoquad4.mesh
-\family default
-) defining the points desired.
- In this case, we again use the ZeroDispDB, which sets the displacements
- to zero for all time.
-\end_layout
-
-\begin_layout Description
-pylithapp.problem.formulation.output.output.writer Gives the base filename for
- VTK output 
-\begin_inset Newline newline
-\end_inset
-
-(
-\family typewriter
-axialtract.vtk
-\family default
-).
-\end_layout
-
-\begin_layout Description
-pylithapp.timedependent.bc.x_pos.output Gives the field to be output for the
- 
-\family typewriter
-x_pos
-\family default
- boundary (
-\family typewriter
-tractions
-\family default
-), and gives the base filename for 
-\family typewriter
-x_pos
-\family default
- boundary output (
-\family typewriter
-axialtract-tractions.vtk
-\family default
-).
-\end_layout
-
-\begin_layout Standard
-The traction vectors for the Neumann boundary conditions are given in the
- file 
-\family typewriter
-axialtract.spatialdb
-\family default
-, as specified in 
-\family typewriter
-axialtract.cfg
-\family default
-.
- The files containing common information (
-\family typewriter
-twoquad4.mesh
-\family default
-, 
-\family typewriter
-pylithapp.cfg
-\family default
-, 
-\family typewriter
-matprops.spatialdb
-\family default
-) along with the problem-specific files (
-\family typewriter
-axialtract.cfg
-\family default
-, 
-\family typewriter
-axialtract.spatialdb
-\family default
-) provide a complete description of the problem, and we can then run this
- example by typing
-\end_layout
-
-\begin_layout LyX-Code
-pylith axialtract.cfg
-\end_layout
-
-\begin_layout Standard
-Once the problem has run, six files will be produced.
- This includes the five files as in the previous example plus 
-\family typewriter
-axialtract-tractions_info.vtk
-\family default
-, which gives the 
-\family typewriter
-x
-\family default
- and 
-\family typewriter
-y
-\family default
- components of traction applied at each integration point.
- If the problem ran correctly, you should be able to generate a figure such
- as Figure 
-\begin_inset CommandInset ref
-LatexCommand vref
-reference "fig:twoquad4-axialtract"
-
-\end_inset
-
-, which was generated using ParaView.
- The results may be compared against the analytical solution derived in
- Section 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "sub:Analytical-Constant-Traction"
-
-\end_inset
-
-.
-\end_layout
-
-\begin_layout Standard
-\begin_inset Float figure
-wide false
-sideways false
-status open
-
-\begin_layout Plain Layout
-\align center
-\begin_inset Graphics
-	filename figs/axialtract.jpg
-	lyxscale 50
-	scale 33
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Plain Layout
-\begin_inset Caption
-
-\begin_layout Plain Layout
-Color contours and vectors of displacement for the axial traction example
- using a mesh composed of two bilinear quadrilateral cells.
-\begin_inset CommandInset label
-LatexCommand label
-name "fig:twoquad4-axialtract"
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_body
-\end_document
+#LyX 2.0 created this file. For more info see http://www.lyx.org/
+\lyxformat 413
+\begin_document
+\begin_header
+\textclass book
+\begin_preamble
+
+\end_preamble
+\use_default_options false
+\maintain_unincluded_children false
+\language english
+\language_package default
+\inputencoding latin1
+\fontencoding global
+\font_roman default
+\font_sans default
+\font_typewriter default
+\font_default_family default
+\use_non_tex_fonts false
+\font_sc false
+\font_osf false
+\font_sf_scale 100
+\font_tt_scale 100
+
+\graphics default
+\default_output_format default
+\output_sync 0
+\bibtex_command default
+\index_command default
+\paperfontsize default
+\spacing single
+\use_hyperref false
+\papersize default
+\use_geometry true
+\use_amsmath 0
+\use_esint 0
+\use_mhchem 1
+\use_mathdots 1
+\cite_engine basic
+\use_bibtopic false
+\use_indices false
+\paperorientation portrait
+\suppress_date false
+\use_refstyle 0
+\index Index
+\shortcut idx
+\color #008000
+\end_index
+\leftmargin 1in
+\topmargin 1in
+\rightmargin 1in
+\bottommargin 1in
+\secnumdepth 3
+\tocdepth 3
+\paragraph_separation indent
+\paragraph_indentation default
+\quotes_language english
+\papercolumns 1
+\papersides 1
+\paperpagestyle default
+\tracking_changes false
+\output_changes false
+\html_math_output 0
+\html_css_as_file 0
+\html_be_strict false
+\end_header
+
+\begin_body
+
+\begin_layout Section
+\begin_inset CommandInset label
+LatexCommand label
+name "sec:Tutorial-Two-quad4"
+
+\end_inset
+
+Tutorial Using Two Quadrilaterals
+\end_layout
+
+\begin_layout Standard
+PyLith features discussed in this tutorial:
+\end_layout
+
+\begin_layout Itemize
+Quasi-static solution
+\end_layout
+
+\begin_layout Itemize
+Mesh ASCII format
+\end_layout
+
+\begin_layout Itemize
+Dirichlet boundary conditions
+\end_layout
+
+\begin_layout Itemize
+Neumann boundary conditions
+\end_layout
+
+\begin_layout Itemize
+Kinematic fault interface conditions
+\end_layout
+
+\begin_layout Itemize
+Plane strain linearly elastic material
+\end_layout
+
+\begin_layout Itemize
+VTK output
+\end_layout
+
+\begin_layout Itemize
+Bilinear quadrilateral cells
+\end_layout
+
+\begin_layout Itemize
+SimpleDB spatial database
+\end_layout
+
+\begin_layout Itemize
+ZeroDispDB spatial database
+\end_layout
+
+\begin_layout Standard
+All of the files necessary to run the examples are contained in the directory
+ 
+\family typewriter
+examples/twocells/twoquad4.
+\end_layout
+
+\begin_layout Subsection
+Overview
+\end_layout
+
+\begin_layout Standard
+This tutorial is another simple 2D example of a quasi-static finite element
+ problem.
+ It is a mesh composed of two bilinear quadrilaterals subject to displacement
+ or traction boundary conditions, assuming plane-strain linear elastic behavior.
+ Due to the simple geometry of the problem, the mesh may be constructed
+ by hand, using PyLith mesh ASCII format to describe the mesh.
+ In this tutorial, we will walk through the steps necessary to construct,
+ run, and view four problems that use the same mesh.
+ In addition to this manual, each of the files for the example problem includes
+ extensive comments.
+\end_layout
+
+\begin_layout Subsection
+Mesh Description
+\end_layout
+
+\begin_layout Standard
+The mesh consists of two square cells with edge lengths of one unit forming
+ a regular region (Figure 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "fig:twoquad4-mesh"
+
+\end_inset
+
+).
+ The mesh geometry and topology are described in the file 
+\family typewriter
+twoquad4.mesh
+\family default
+, which is in PyLith mesh ASCII format.
+ This file describes the dimensionality of the problem (in this case 2D),
+ the coordinates of the vertices (nodes), the vertices composing each cell
+ (element), the material ID to be associated with each cell, and then provides
+ groups of vertices that may be used to define faults or surfaces to which
+ boundary conditions may be applied.
+\end_layout
+
+\begin_layout Standard
+\noindent
+\align center
+\begin_inset Float figure
+wide false
+sideways false
+status open
+
+\begin_layout Plain Layout
+\align center
+\begin_inset Graphics
+	filename figs/twoquad4-mesh.eps
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Plain Layout
+\begin_inset Caption
+
+\begin_layout Plain Layout
+Mesh composed of two bilinear quadrilateral cells used for the example problems.
+\begin_inset CommandInset label
+LatexCommand label
+name "fig:twoquad4-mesh"
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Subsection
+Additional Common Information
+\end_layout
+
+\begin_layout Standard
+In addition to the mesh, the four example problems share additional information.
+ As in the previous examples, we place this information in 
+\family typewriter
+pylithapp.cfg
+\family default
+, since this file is read automatically every time PyLith is run.
+ Settings specific to a particular problem may be placed in other 
+\family typewriter
+.cfg
+\family default
+ files, as described later, and then those files are placed on the command
+ line.
+\end_layout
+
+\begin_layout Subsection
+Axial Displacement Example
+\end_layout
+
+\begin_layout Standard
+The first example problem is extension of the mesh along the x axis.
+ Parameter settings that override or augment those in 
+\family typewriter
+pylithapp.cfg
+\family default
+ are contained in the file 
+\family typewriter
+axialdisp.cfg
+\family default
+.
+ These include:
+\end_layout
+
+\begin_layout Description
+pylithapp.timedependent.bc.x_neg Specifies the boundary conditions for the
+ left side of the mesh, defining which degrees of freedom are being constrained
+ (x), giving the label (defined in 
+\family typewriter
+twoquad4.mesh
+\family default
+) defining the points desired, assigning a label to the boundary condition
+ set, and giving the name of the spatial database with the values for the
+ Dirichlet boundary condition (
+\family typewriter
+axialdisp.spatialdb
+\family default
+).
+\end_layout
+
+\begin_layout Description
+pylithapp.timedependent.bc.x_pos Specifies the boundary conditions for the
+ right side of the mesh, defining which degrees of freedom are being constrained
+ (x), giving the label (defined in 
+\family typewriter
+twoquad4.mesh
+\family default
+) defining the points desired, assigning a label to the boundary condition
+ set, and giving the name of the spatial database defining the boundary
+ conditions (
+\family typewriter
+axialdisp.spatialdb
+\family default
+).
+\end_layout
+
+\begin_layout Description
+pylithapp.timedependent.bc.y_neg Specifies the boundary conditions for the
+ bottom two corners of the mesh, defining which degrees of freedom are being
+ constrained (y), giving the label (defined in 
+\family typewriter
+twoquad4.mesh
+\family default
+) defining the points desired, assigning a label to the boundary condition
+ set, and giving the name of the spatial database with the values for the
+ Dirichlet boundary condition (
+\family typewriter
+axialdisp.spatialdb
+\family default
+).
+\end_layout
+
+\begin_layout Standard
+The values for the Dirichlet boundary condition are given in the file 
+\family typewriter
+axialdisp.spatialdb
+\family default
+, as specified in 
+\family typewriter
+axialdisp.cfg
+\family default
+.
+ Because the data are being specified using two control points with a linear
+ variation in the values between the two (rather than being uniform over
+ the mesh, for example), the data dimension is one.
+\end_layout
+
+\begin_layout Standard
+The files containing common information (
+\family typewriter
+twoquad4.mesh
+\family default
+, 
+\family typewriter
+pylithapp.cfg
+\family default
+, 
+\family typewriter
+matprops.spatialdb
+\family default
+) along with the problem-specific files (
+\family typewriter
+axialdisp.cfg
+\family default
+, 
+\family typewriter
+axialdisp.spatialdb
+\family default
+) provide a complete description of the problem, and we can then run this
+ example by typing
+\end_layout
+
+\begin_layout LyX-Code
+pylith axialdisp.cfg
+\end_layout
+
+\begin_layout Standard
+As in the two triangle axial displacement example, three files will be produced.
+ If the problem ran correctly, you should be able to produce a figure such
+ as Figure 
+\begin_inset CommandInset ref
+LatexCommand vref
+reference "fig:twoquad4-axial"
+
+\end_inset
+
+, which was generated using ParaView.
+\end_layout
+
+\begin_layout Standard
+\noindent
+\align center
+\begin_inset Float figure
+placement t
+wide false
+sideways false
+status open
+
+\begin_layout Plain Layout
+\align center
+\begin_inset Graphics
+	filename figs/axialdisp.jpg
+	lyxscale 50
+	scale 33
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Plain Layout
+\begin_inset Caption
+
+\begin_layout Plain Layout
+Color contours and vectors of displacement for the axial displacement example
+ using a mesh composed of two bilinear quadrilateral cells.
+\begin_inset CommandInset label
+LatexCommand label
+name "fig:twoquad4-axial"
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Subsection
+Shear Displacement Example
+\end_layout
+
+\begin_layout Standard
+The next example problem is shearing of the mesh in the y direction using
+ displacements applied along the positive and negative x boundaries.
+ Parameter settings that override or augment those in 
+\family typewriter
+pylithapp.cfg
+\family default
+ are contained in the file 
+\family typewriter
+sheardisp.cfg
+\family default
+.
+ These include:
+\end_layout
+
+\begin_layout Description
+pylithapp.timedependent.bc.x_neg Specifies the boundary conditions for the
+ left side of the mesh, defining which degrees of freedom are being constrained
+ (x and y), giving the label (
+\family typewriter
+x_neg
+\family default
+, defined in 
+\family typewriter
+twoquad4.mesh
+\family default
+) defining the points desired, assigning a label to the boundary condition
+ set, and giving the name of the spatial database with the values for the
+ Dirichlet boundary condition (
+\family typewriter
+sheardisp.spatialdb
+\family default
+).
+\end_layout
+
+\begin_layout Description
+pylithapp.timedependent.bc.x_pos Specifies the boundary conditions for the
+ left side of the mesh, defining which degrees of freedom are being constrained
+ (y only), giving the label (
+\family typewriter
+x_
+\family default
+pos, defined in 
+\family typewriter
+twoquad4.mesh
+\family default
+) defining the points desired, assigning a label to the boundary condition
+ set, and giving the name of the spatial database with the values for the
+ Dirichlet boundary condition (
+\family typewriter
+sheardisp.spatialdb
+\family default
+).
+\end_layout
+
+\begin_layout Standard
+The values for the Dirichlet boundary conditions are described in the file
+ 
+\family typewriter
+sheardisp.spatialdb
+\family default
+, as specified in 
+\family typewriter
+sheardisp.cfg
+\family default
+.
+ In this case, the desired displacement values are given at two control
+ points, corresponding to the two edges we want to constrain.
+ Since data are being specified at two points with a linear variations in
+ the values between the points (rather than being uniform over the mesh,
+ for example), the data dimension is one.
+\end_layout
+
+\begin_layout Standard
+The files containing common information (
+\family typewriter
+twoquad4.mesh
+\family default
+, 
+\family typewriter
+pylithapp.cfg
+\family default
+, 
+\family typewriter
+matprops.spatialdb
+\family default
+) along with the problem-specific files (
+\family typewriter
+sheardisp.cfg
+\family default
+, 
+\family typewriter
+sheardisp.spatialdb
+\family default
+) provide a complete description of the problem, and we can then run this
+ example by typing
+\end_layout
+
+\begin_layout LyX-Code
+pylith sheardisp.cfg
+\end_layout
+
+\begin_layout Standard
+As in the previous example, three files will be produced.
+ If the problem ran correctly, you should be able to produce a figure such
+ as Figure 
+\begin_inset CommandInset ref
+LatexCommand vref
+reference "fig:twoquad4-shear"
+
+\end_inset
+
+, which was generated using ParaView.
+\end_layout
+
+\begin_layout Standard
+\begin_inset Float figure
+wide false
+sideways false
+status open
+
+\begin_layout Plain Layout
+\align center
+\begin_inset Graphics
+	filename figs/sheardispl.jpg
+	lyxscale 50
+	scale 33
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Plain Layout
+\begin_inset Caption
+
+\begin_layout Plain Layout
+Color contours and vectors of displacement for the shear displacement example
+ using a mesh composed of two bilinear quadrilateral cells.
+\begin_inset CommandInset label
+LatexCommand label
+name "fig:twoquad4-shear"
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Subsection
+Kinematic Fault Slip Example
+\end_layout
+
+\begin_layout Standard
+The next example problem is a left-lateral fault slip applied between the
+ two square cells using kinematic cohesive cells.
+ The left and right boundaries are held fixed in the x and y directions.
+ Parameter settings that override or augment those in 
+\family typewriter
+pylithapp.cfg
+\family default
+ are contained in the file 
+\family typewriter
+dislocation.cfg
+\family default
+.
+ These settings include:
+\end_layout
+
+\begin_layout Description
+pylithapp.timedependent.bc.x_neg Specifies the boundary conditions for the
+ left side of the mesh, defining which degrees of freedom are being constrained
+ (x and y), giving the label (
+\family typewriter
+x_neg
+\family default
+, defined in 
+\family typewriter
+twoquad4.mesh
+\family default
+) defining the points desired, and assigning a label to the boundary condition
+ set.
+ Instead of specifying a spatial database file for the values of the Dirichlet
+ boundary condition, we use the default spatial database (ZeroDispDB) for
+ the Dirichlet boundary condition, which sets the displacements to zero
+ for all time.
+\end_layout
+
+\begin_layout Description
+pylithapp.timedependent.bc.x_pos Specifies the boundary conditions for the
+ right side of the mesh, defining which degrees of freedom are being constrained
+ (x and y), giving the label (
+\family typewriter
+x_neg
+\family default
+, defined in 
+\family typewriter
+twoquad4.mesh
+\family default
+) defining the points desired, and assigning a label to the boundary condition
+ set.
+ We use the ZeroDispDB for this boundary condition as well, which sets the
+ displacements to zero for all time.
+\end_layout
+
+\begin_layout Description
+pylithapp.timedependent.interfaces Gives the label (defined in 
+\family typewriter
+twoquad4.mesh
+\family default
+) defining the points on the fault, provides quadrature information, and
+ then gives database names for material properties (needed for conditioning),
+ fault slip, peak fault slip rate, and fault slip time.
+\end_layout
+
+\begin_layout Standard
+The fault example requires three additional database files that were not
+ needed for the simple displacement examples.
+ The first file (
+\family typewriter
+dislocation_slip.spatialdb
+\family default
+) specifies 0.01 m of left-lateral fault slip for the entire fault.
+ The data dimension is zero since the same data are applied to all points
+ in the set.
+ The default slip time function is a step-function, so we also must provide
+ the time at which slip begins.
+ The elastic solution is associated with advancing from 
+\begin_inset Formula $t=-dt$
+\end_inset
+
+ to 
+\begin_inset Formula $t=0$
+\end_inset
+
+, so we set the slip initiation time for the step-function to 0 in 
+\family typewriter
+dislocation_sliptime.spatialdb
+\family default
+.
+\end_layout
+
+\begin_layout Standard
+The files containing common information (
+\family typewriter
+twoquad4.mesh
+\family default
+, 
+\family typewriter
+pylithapp.cfg
+\family default
+, 
+\family typewriter
+matprops.spatialdb
+\family default
+) along with the problem-specific files (
+\family typewriter
+\size small
+dislocation.cfg
+\family default
+, 
+\family typewriter
+dislocation_slip.spatialdb
+\family default
+, 
+\family typewriter
+dislocation_sliptime.spatialdb
+\family default
+\size default
+) provide a complete description of the problem, and we can then run this
+ example by typing
+\end_layout
+
+\begin_layout LyX-Code
+pylith dislocation.cfg
+\end_layout
+
+\begin_layout Standard
+The addition of a fault results in two additional output files (as in the
+ two triangle fault example), 
+\family typewriter
+dislocation-fault_t0000000.vtk
+\family default
+ and 
+\family typewriter
+dislocation-fault_info.vtk
+\family default
+.
+ These files provide output of fault slip, change in tractions, and diagnostic
+ information such as the normal direction, final slip, and slip time for
+ each vertex on the fault.
+ If the problem ran correctly, you should be able to produce a figure such
+ as Figure 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "fig:twoquad4-disloc"
+
+\end_inset
+
+, which was generated using ParaView.
+\end_layout
+
+\begin_layout Standard
+\begin_inset Float figure
+wide false
+sideways false
+status open
+
+\begin_layout Plain Layout
+\align center
+\begin_inset Graphics
+	filename figs/dislocation.jpg
+	lyxscale 50
+	scale 33
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Plain Layout
+\begin_inset Caption
+
+\begin_layout Plain Layout
+Color contours and vectors of displacement for the kinematic fault example
+ using a mesh composed of two bilinear quadrilateral cells.
+\begin_inset CommandInset label
+LatexCommand label
+name "fig:twoquad4-disloc"
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Subsection
+\begin_inset CommandInset label
+LatexCommand label
+name "sub:Tutorial-twoquad4-traction"
+
+\end_inset
+
+Axial Traction Example
+\end_layout
+
+\begin_layout Standard
+The fourth example demonstrates the use of Neumann (traction) boundary condition
+s.
+ Constant tractions are applied to the right edge of the mesh, while displacemen
+ts normal to the boundaries are held fixed along the left and bottom edges
+ of the mesh.
+ Parameter settings that override or augment those in 
+\family typewriter
+pylithapp.cfg
+\family default
+ are contained in the file 
+\family typewriter
+axialtract.cfg
+\family default
+.
+ These settings include:
+\end_layout
+
+\begin_layout Description
+pylithapp.timedependent Specifies an implicit formulation for the problem
+ and specifies the array of boundary conditions.
+ The boundary condition type for 
+\family typewriter
+x_pos
+\family default
+ is explicitly set to 
+\family typewriter
+Neumann
+\family default
+, since the default boundary condition type is 
+\family typewriter
+Dirichlet
+\family default
+.
+\end_layout
+
+\begin_layout Description
+pylithapp.timedependent.bc.x_neg Specifies the boundary conditions for the
+ left side of the mesh, defining which degrees of freedom are being constrained
+ (x) and giving the label (defined in 
+\family typewriter
+twoquad4.mesh
+\family default
+) defining the points desired.
+ In this case, rather than specifying a spatial database file with values
+ for the Dirichlet boundary conditions, we use the default spatial database
+ (ZeroDispDB) for the Dirichlet boundary condition, which sets the displacements
+ to zero for all time.
+\end_layout
+
+\begin_layout Description
+pylithapp.timedependent.bc.x_pos Specifies the Neumann boundary conditions
+ for the right side of the mesh, giving the label (defined in 
+\family typewriter
+twoquad4.mesh
+\family default
+) defining the points desired, assigning a label to the boundary condition
+ set, and giving the name of the spatial database with the traction vectors
+ for the Neumann boundary condition (
+\family typewriter
+axialtract.spatialdb
+\family default
+).
+\end_layout
+
+\begin_layout Description
+pylithapp.timedependent.bc.y_neg Specifies the boundary conditions for the
+ bottom two corners of the mesh, defining which degrees of freedom are being
+ constrained (y) and giving the label (defined in 
+\family typewriter
+twoquad4.mesh
+\family default
+) defining the points desired.
+ In this case, we again use the ZeroDispDB, which sets the displacements
+ to zero for all time.
+\end_layout
+
+\begin_layout Description
+pylithapp.problem.formulation.output.output.writer Gives the base filename for
+ VTK output 
+\begin_inset Newline newline
+\end_inset
+
+(
+\family typewriter
+axialtract.vtk
+\family default
+).
+\end_layout
+
+\begin_layout Description
+pylithapp.timedependent.bc.x_pos.output Gives the field to be output for the
+ 
+\family typewriter
+x_pos
+\family default
+ boundary (
+\family typewriter
+tractions
+\family default
+), and gives the base filename for 
+\family typewriter
+x_pos
+\family default
+ boundary output (
+\family typewriter
+axialtract-tractions.vtk
+\family default
+).
+\end_layout
+
+\begin_layout Standard
+The traction vectors for the Neumann boundary conditions are given in the
+ file 
+\family typewriter
+axialtract.spatialdb
+\family default
+, as specified in 
+\family typewriter
+axialtract.cfg
+\family default
+.
+ The files containing common information (
+\family typewriter
+twoquad4.mesh
+\family default
+, 
+\family typewriter
+pylithapp.cfg
+\family default
+, 
+\family typewriter
+matprops.spatialdb
+\family default
+) along with the problem-specific files (
+\family typewriter
+axialtract.cfg
+\family default
+, 
+\family typewriter
+axialtract.spatialdb
+\family default
+) provide a complete description of the problem, and we can then run this
+ example by typing
+\end_layout
+
+\begin_layout LyX-Code
+pylith axialtract.cfg
+\end_layout
+
+\begin_layout Standard
+Once the problem has run, six files will be produced.
+ This includes the five files as in the previous example plus 
+\family typewriter
+axialtract-tractions_info.vtk
+\family default
+, which gives the 
+\family typewriter
+x
+\family default
+ and 
+\family typewriter
+y
+\family default
+ components of traction applied at each integration point.
+ If the problem ran correctly, you should be able to produce a figure such
+ as Figure 
+\begin_inset CommandInset ref
+LatexCommand vref
+reference "fig:twoquad4-axialtract"
+
+\end_inset
+
+, which was generated using ParaView.
+ The results may be compared against the analytical solution derived in
+ Section 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "sub:Analytical-Constant-Traction"
+
+\end_inset
+
+.
+\end_layout
+
+\begin_layout Standard
+\begin_inset Float figure
+wide false
+sideways false
+status open
+
+\begin_layout Plain Layout
+\align center
+\begin_inset Graphics
+	filename figs/axialtract.jpg
+	lyxscale 50
+	scale 33
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Plain Layout
+\begin_inset Caption
+
+\begin_layout Plain Layout
+Color contours and vectors of displacement for the axial traction example
+ using a mesh composed of two bilinear quadrilateral cells.
+\begin_inset CommandInset label
+LatexCommand label
+name "fig:twoquad4-axialtract"
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\end_body
+\end_document

Modified: short/3D/PyLith/branches/v1.7-trunk/doc/userguide/tutorials/twotet4/twotet4.lyx
===================================================================
--- short/3D/PyLith/branches/v1.7-trunk/doc/userguide/tutorials/twotet4/twotet4.lyx	2012-06-25 04:52:47 UTC (rev 20403)
+++ short/3D/PyLith/branches/v1.7-trunk/doc/userguide/tutorials/twotet4/twotet4.lyx	2012-06-25 16:38:44 UTC (rev 20404)
@@ -1,549 +1,549 @@
-#LyX 2.0 created this file. For more info see http://www.lyx.org/
-\lyxformat 413
-\begin_document
-\begin_header
-\textclass book
-\begin_preamble
-
-\end_preamble
-\use_default_options false
-\maintain_unincluded_children false
-\language english
-\language_package default
-\inputencoding latin1
-\fontencoding global
-\font_roman default
-\font_sans default
-\font_typewriter default
-\font_default_family default
-\use_non_tex_fonts false
-\font_sc false
-\font_osf false
-\font_sf_scale 100
-\font_tt_scale 100
-
-\graphics default
-\default_output_format default
-\output_sync 0
-\bibtex_command default
-\index_command default
-\paperfontsize default
-\spacing single
-\use_hyperref false
-\papersize default
-\use_geometry true
-\use_amsmath 0
-\use_esint 0
-\use_mhchem 1
-\use_mathdots 1
-\cite_engine basic
-\use_bibtopic false
-\use_indices false
-\paperorientation portrait
-\suppress_date false
-\use_refstyle 0
-\index Index
-\shortcut idx
-\color #008000
-\end_index
-\leftmargin 1in
-\topmargin 1in
-\rightmargin 1in
-\bottommargin 2in
-\secnumdepth 3
-\tocdepth 3
-\paragraph_separation indent
-\paragraph_indentation default
-\quotes_language english
-\papercolumns 1
-\papersides 1
-\paperpagestyle default
-\tracking_changes false
-\output_changes false
-\html_math_output 0
-\html_css_as_file 0
-\html_be_strict false
-\end_header
-
-\begin_body
-
-\begin_layout Section
-\begin_inset CommandInset label
-LatexCommand label
-name "sec:Tutorial-Two-tet4"
-
-\end_inset
-
-Tutorial Using Two Tetrahedra
-\end_layout
-
-\begin_layout Standard
-PyLith features discussed in this tutorial:
-\end_layout
-
-\begin_layout Itemize
-Quasi-static solution
-\end_layout
-
-\begin_layout Itemize
-Mesh ASCII format
-\end_layout
-
-\begin_layout Itemize
-Dirichlet boundary conditions
-\end_layout
-
-\begin_layout Itemize
-Kinematic fault interface conditions
-\end_layout
-
-\begin_layout Itemize
-Linearly elastic isotropic material
-\end_layout
-
-\begin_layout Itemize
-VTK output
-\end_layout
-
-\begin_layout Itemize
-Linear tetrahedral cells
-\end_layout
-
-\begin_layout Itemize
-SimpleDB spatial database
-\end_layout
-
-\begin_layout Itemize
-ZeroDispDB spatial database
-\end_layout
-
-\begin_layout Standard
-All of the files necessary to run the examples are contained in the directory
- 
-\family typewriter
-examples/twocells/twotet4.
-\end_layout
-
-\begin_layout Subsection
-Overview
-\end_layout
-
-\begin_layout Standard
-This tutorial is a simple 3D example of a quasi-static finite element problem.
- It is a mesh composed of two linear tetrahedra subject to displacement
- boundary conditions, and is probably the simplest example of a 3D elastic
- problem.
- Due to the simple geometry of the problem, the mesh may be constructed
- by hand, using PyLith mesh ASCII format.
- In this tutorial, we will walk through the steps necessary to construct,
- run, and view two problems that use the same mesh.
- In addition to this manual, each of the files for the example problem includes
- extensive comments.
-\end_layout
-
-\begin_layout Subsection
-Mesh Description
-\end_layout
-
-\begin_layout Standard
-The mesh consists of two tetrahedra forming a pyramid shape (Figure 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "fig:twotet4-mesh"
-
-\end_inset
-
-).
- The mesh geometry and topology is described in the file 
-\family typewriter
-twotet4.mesh
-\family default
-, which is in PyLith mesh ASCII format.
-\end_layout
-
-\begin_layout Standard
-\noindent
-\align center
-\begin_inset Float figure
-wide false
-sideways false
-status open
-
-\begin_layout Plain Layout
-\align center
-\begin_inset Graphics
-	filename figs/twotet4-mesh.eps
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Plain Layout
-\begin_inset Caption
-
-\begin_layout Plain Layout
-Mesh composed of two linear tetrahedral cells used for example problems.
-\begin_inset CommandInset label
-LatexCommand label
-name "fig:twotet4-mesh"
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Subsection
-Additional Common Information
-\end_layout
-
-\begin_layout Standard
-In addition to the mesh, the two example problems share additional information,
- which we place in 
-\family typewriter
-pylithapp.cfg
-\family default
-.
-\end_layout
-
-\begin_layout Subsection
-Axial Displacement Example
-\end_layout
-
-\begin_layout Standard
-The first example problem is extension of the mesh along the diagonal, extending
- along the base of the pyramid between two opposing vertices.
- Parameter settings that override or augment those in 
-\family typewriter
-pylithapp.cfg
-\family default
- are contained in the file 
-\family typewriter
-axialdisp.cfg
-\family default
-.
- These settings include:
-\end_layout
-
-\begin_layout Description
-pylithapp.timedependent.bc.bc Defines which degrees of freedom are being constraine
-d (
-\family typewriter
-x
-\family default
-, 
-\family typewriter
-y
-\family default
-, and 
-\family typewriter
-z
-\family default
-), gives the label (defined in 
-\family typewriter
-twotet4.mesh
-\family default
-) defining the points desired, assigns a label to the boundary condition
- set, and gives the name of the spatial database defining the boundary condition
-s (
-\family typewriter
-axialdisp.spatialdb
-\family default
-).
-\end_layout
-
-\begin_layout Standard
-The values for the Dirichlet boundary conditions are described in the file
- 
-\family typewriter
-axialdisp.spatialdb
-\family default
-, as specified in 
-\family typewriter
-axialdisp.cfg
-\family default
-.
- Because data are being specified using two control points (rather than
- being uniform over the mesh), the data dimension is one.
-\end_layout
-
-\begin_layout Standard
-The files containing common information (
-\family typewriter
-twotet4.mesh
-\family default
-, 
-\family typewriter
-pylithapp.cfg
-\family default
-, 
-\family typewriter
-matprops.spatialdb
-\family default
-) along with the problem-specific files (
-\family typewriter
-axialdisp.cfg
-\family default
-, 
-\family typewriter
-axialdisp.spatialdb
-\family default
-) provide a complete description of the problem, and we can then run this
- example by typing
-\end_layout
-
-\begin_layout LyX-Code
-pylith axialdisp.cfg
-\end_layout
-
-\begin_layout Standard
-If the problem ran correctly, you should be able to generate a figure such
- as Figure 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "fig:twotet4-axial"
-
-\end_inset
-
-, which was generated using ParaView.
-\end_layout
-
-\begin_layout Standard
-\begin_inset Float figure
-wide false
-sideways false
-status open
-
-\begin_layout Plain Layout
-\align center
-\begin_inset Graphics
-	filename figs/axialdisp.jpg
-	lyxscale 50
-	scale 33
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Plain Layout
-\begin_inset Caption
-
-\begin_layout Plain Layout
-Color contours and vectors of displacement for the axial displacement example
- using a mesh composed of two linear tetrahedral cells.
-\begin_inset CommandInset label
-LatexCommand label
-name "fig:twotet4-axial"
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Subsection
-Kinematic Fault Slip Example
-\end_layout
-
-\begin_layout Standard
-The next example problem is a left-lateral fault slip applied between the
- two tetrahedral cells using kinematic cohesive cells.
- The vertices away from the fault are held fixed in the 
-\family typewriter
-x
-\family default
-, 
-\family typewriter
-y
-\family default
-, and 
-\family typewriter
-z
-\family default
- directions.
- Parameter settings that override or augment those in 
-\family typewriter
-pylithapp.cfg
-\family default
- are contained in the file 
-\family typewriter
-dislocation.cfg
-\family default
-.
- These settings include:
-\end_layout
-
-\begin_layout Description
-pylithapp.timedependent.bc.bc Defines which degrees of freedom are being constraine
-d (
-\family typewriter
-x
-\family default
-, 
-\family typewriter
-y
-\family default
-, and 
-\family typewriter
-z
-\family default
-), gives the label (defined in 
-\family typewriter
-twotet4.mesh
-\family default
-) defining the points desired, and assigns a label to the boundary condition
- set.
- Rather than specifying a spatial database file to define the boundary condition
-s, we use the default spatial database (ZeroDispDB) for  the Dirichlet boundary
- condition, which sets the displacements to zero.
-\end_layout
-
-\begin_layout Description
-pylithapp.timedependent.interfaces Gives the label (defined in 
-\family typewriter
-twotet4.mesh
-\family default
-) defining the points on the fault, provides quadrature information, and
- then gives database names for material properties (needed for conditioning),
- fault slip, peak fault slip rate, and fault slip time.
-\end_layout
-
-\begin_layout Standard
-The fault example requires three additional database files that were not
- needed for the simple displacement examples.
- The first file (
-\family typewriter
-dislocation_slip.spatialdb
-\family default
-) specifies 0.01 m of left-lateral fault slip for the entire fault.
- The data dimension is zero since the same data are applied to all points
- in the set.
- The default slip time function is a step-function, so we also must provide
- the time at which slip begins.
- The elastic solution is associated with advancing from 
-\begin_inset Formula $t=-dt$
-\end_inset
-
- to 
-\begin_inset Formula $t=0$
-\end_inset
-
-, so we set the slip initiation time for the step-function to 0 in 
-\family typewriter
-dislocation_sliptime.spatialdb
-\family default
-.
-\end_layout
-
-\begin_layout Standard
-The files containing common information (
-\family typewriter
-twotet4.mesh
-\family default
-, 
-\family typewriter
-pylithapp.cfg
-\family default
-, 
-\family typewriter
-matprops.spatialdb
-\family default
-) along with the problem-specific files (
-\family typewriter
-\size small
-dislocation.cfg
-\family default
-, 
-\family typewriter
-dislocation_slip.spatialdb
-\family default
-, 
-\family typewriter
-dislocation_sliptime.spatialdb
-\family default
-\size default
-) provide a complete description of the problem, and we can then run this
- example by typing
-\end_layout
-
-\begin_layout LyX-Code
-pylith dislocation.cfg
-\end_layout
-
-\begin_layout Standard
-If the problem ran correctly, you should be able to generate a figure such
- as Figure 
-\begin_inset CommandInset ref
-LatexCommand vref
-reference "fig:twotet4-disloc"
-
-\end_inset
-
-, which was generated using ParaView.
-\end_layout
-
-\begin_layout Standard
-\begin_inset Float figure
-wide false
-sideways false
-status open
-
-\begin_layout Plain Layout
-\align center
-\begin_inset Graphics
-	filename figs/dislocation.jpg
-	lyxscale 50
-	scale 33
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Plain Layout
-\begin_inset Caption
-
-\begin_layout Plain Layout
-Color contours and vectors of displacement for the kinematic fault example
- using a mesh composed of two linear tetrahedral cells.
-\begin_inset CommandInset label
-LatexCommand label
-name "fig:twotet4-disloc"
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_body
-\end_document
+#LyX 2.0 created this file. For more info see http://www.lyx.org/
+\lyxformat 413
+\begin_document
+\begin_header
+\textclass book
+\begin_preamble
+
+\end_preamble
+\use_default_options false
+\maintain_unincluded_children false
+\language english
+\language_package default
+\inputencoding latin1
+\fontencoding global
+\font_roman default
+\font_sans default
+\font_typewriter default
+\font_default_family default
+\use_non_tex_fonts false
+\font_sc false
+\font_osf false
+\font_sf_scale 100
+\font_tt_scale 100
+
+\graphics default
+\default_output_format default
+\output_sync 0
+\bibtex_command default
+\index_command default
+\paperfontsize default
+\spacing single
+\use_hyperref false
+\papersize default
+\use_geometry true
+\use_amsmath 0
+\use_esint 0
+\use_mhchem 1
+\use_mathdots 1
+\cite_engine basic
+\use_bibtopic false
+\use_indices false
+\paperorientation portrait
+\suppress_date false
+\use_refstyle 0
+\index Index
+\shortcut idx
+\color #008000
+\end_index
+\leftmargin 1in
+\topmargin 1in
+\rightmargin 1in
+\bottommargin 2in
+\secnumdepth 3
+\tocdepth 3
+\paragraph_separation indent
+\paragraph_indentation default
+\quotes_language english
+\papercolumns 1
+\papersides 1
+\paperpagestyle default
+\tracking_changes false
+\output_changes false
+\html_math_output 0
+\html_css_as_file 0
+\html_be_strict false
+\end_header
+
+\begin_body
+
+\begin_layout Section
+\begin_inset CommandInset label
+LatexCommand label
+name "sec:Tutorial-Two-tet4"
+
+\end_inset
+
+Tutorial Using Two Tetrahedra
+\end_layout
+
+\begin_layout Standard
+PyLith features discussed in this tutorial:
+\end_layout
+
+\begin_layout Itemize
+Quasi-static solution
+\end_layout
+
+\begin_layout Itemize
+Mesh ASCII format
+\end_layout
+
+\begin_layout Itemize
+Dirichlet boundary conditions
+\end_layout
+
+\begin_layout Itemize
+Kinematic fault interface conditions
+\end_layout
+
+\begin_layout Itemize
+Linearly elastic isotropic material
+\end_layout
+
+\begin_layout Itemize
+VTK output
+\end_layout
+
+\begin_layout Itemize
+Linear tetrahedral cells
+\end_layout
+
+\begin_layout Itemize
+SimpleDB spatial database
+\end_layout
+
+\begin_layout Itemize
+ZeroDispDB spatial database
+\end_layout
+
+\begin_layout Standard
+All of the files necessary to run the examples are contained in the directory
+ 
+\family typewriter
+examples/twocells/twotet4.
+\end_layout
+
+\begin_layout Subsection
+Overview
+\end_layout
+
+\begin_layout Standard
+This tutorial is a simple 3D example of a quasi-static finite element problem.
+ It is a mesh composed of two linear tetrahedra subject to displacement
+ boundary conditions, and is probably the simplest example of a 3D elastic
+ problem.
+ Due to the simple geometry of the problem, the mesh may be constructed
+ by hand, using PyLith mesh ASCII format.
+ In this tutorial, we will walk through the steps necessary to construct,
+ run, and view two problems that use the same mesh.
+ In addition to this manual, each of the files for the example problem includes
+ extensive comments.
+\end_layout
+
+\begin_layout Subsection
+Mesh Description
+\end_layout
+
+\begin_layout Standard
+The mesh consists of two tetrahedra forming a pyramid shape (Figure 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "fig:twotet4-mesh"
+
+\end_inset
+
+).
+ The mesh geometry and topology is described in the file 
+\family typewriter
+twotet4.mesh
+\family default
+, which is in PyLith mesh ASCII format.
+\end_layout
+
+\begin_layout Standard
+\noindent
+\align center
+\begin_inset Float figure
+wide false
+sideways false
+status open
+
+\begin_layout Plain Layout
+\align center
+\begin_inset Graphics
+	filename figs/twotet4-mesh.eps
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Plain Layout
+\begin_inset Caption
+
+\begin_layout Plain Layout
+Mesh composed of two linear tetrahedral cells used for example problems.
+\begin_inset CommandInset label
+LatexCommand label
+name "fig:twotet4-mesh"
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Subsection
+Additional Common Information
+\end_layout
+
+\begin_layout Standard
+In addition to the mesh, the two example problems share additional information,
+ which we place in 
+\family typewriter
+pylithapp.cfg
+\family default
+.
+\end_layout
+
+\begin_layout Subsection
+Axial Displacement Example
+\end_layout
+
+\begin_layout Standard
+The first example problem is extension of the mesh along the diagonal, extending
+ along the base of the pyramid between two opposing vertices.
+ Parameter settings that override or augment those in 
+\family typewriter
+pylithapp.cfg
+\family default
+ are contained in the file 
+\family typewriter
+axialdisp.cfg
+\family default
+.
+ These settings include:
+\end_layout
+
+\begin_layout Description
+pylithapp.timedependent.bc.bc Defines which degrees of freedom are being constraine
+d (
+\family typewriter
+x
+\family default
+, 
+\family typewriter
+y
+\family default
+, and 
+\family typewriter
+z
+\family default
+), gives the label (defined in 
+\family typewriter
+twotet4.mesh
+\family default
+) defining the points desired, assigns a label to the boundary condition
+ set, and gives the name of the spatial database defining the boundary condition
+s (
+\family typewriter
+axialdisp.spatialdb
+\family default
+).
+\end_layout
+
+\begin_layout Standard
+The values for the Dirichlet boundary conditions are described in the file
+ 
+\family typewriter
+axialdisp.spatialdb
+\family default
+, as specified in 
+\family typewriter
+axialdisp.cfg
+\family default
+.
+ Because data are being specified using two control points (rather than
+ being uniform over the mesh), the data dimension is one.
+\end_layout
+
+\begin_layout Standard
+The files containing common information (
+\family typewriter
+twotet4.mesh
+\family default
+, 
+\family typewriter
+pylithapp.cfg
+\family default
+, 
+\family typewriter
+matprops.spatialdb
+\family default
+) along with the problem-specific files (
+\family typewriter
+axialdisp.cfg
+\family default
+, 
+\family typewriter
+axialdisp.spatialdb
+\family default
+) provide a complete description of the problem, and we can then run this
+ example by typing
+\end_layout
+
+\begin_layout LyX-Code
+pylith axialdisp.cfg
+\end_layout
+
+\begin_layout Standard
+If the problem ran correctly, you should be able to produce a figure such
+ as Figure 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "fig:twotet4-axial"
+
+\end_inset
+
+, which was generated using ParaView.
+\end_layout
+
+\begin_layout Standard
+\begin_inset Float figure
+wide false
+sideways false
+status open
+
+\begin_layout Plain Layout
+\align center
+\begin_inset Graphics
+	filename figs/axialdisp.jpg
+	lyxscale 50
+	scale 33
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Plain Layout
+\begin_inset Caption
+
+\begin_layout Plain Layout
+Color contours and vectors of displacement for the axial displacement example
+ using a mesh composed of two linear tetrahedral cells.
+\begin_inset CommandInset label
+LatexCommand label
+name "fig:twotet4-axial"
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Subsection
+Kinematic Fault Slip Example
+\end_layout
+
+\begin_layout Standard
+The next example problem is a left-lateral fault slip applied between the
+ two tetrahedral cells using kinematic cohesive cells.
+ The vertices away from the fault are held fixed in the 
+\family typewriter
+x
+\family default
+, 
+\family typewriter
+y
+\family default
+, and 
+\family typewriter
+z
+\family default
+ directions.
+ Parameter settings that override or augment those in 
+\family typewriter
+pylithapp.cfg
+\family default
+ are contained in the file 
+\family typewriter
+dislocation.cfg
+\family default
+.
+ These settings include:
+\end_layout
+
+\begin_layout Description
+pylithapp.timedependent.bc.bc Defines which degrees of freedom are being constraine
+d (
+\family typewriter
+x
+\family default
+, 
+\family typewriter
+y
+\family default
+, and 
+\family typewriter
+z
+\family default
+), gives the label (defined in 
+\family typewriter
+twotet4.mesh
+\family default
+) defining the points desired, and assigns a label to the boundary condition
+ set.
+ Rather than specifying a spatial database file to define the boundary condition
+s, we use the default spatial database (ZeroDispDB) for the Dirichlet boundary
+ condition, which sets the displacements to zero.
+\end_layout
+
+\begin_layout Description
+pylithapp.timedependent.interfaces Gives the label (defined in 
+\family typewriter
+twotet4.mesh
+\family default
+) defining the points on the fault, provides quadrature information, and
+ then gives database names for material properties (needed for conditioning),
+ fault slip, peak fault slip rate, and fault slip time.
+\end_layout
+
+\begin_layout Standard
+The fault example requires three additional database files that were not
+ needed for the simple displacement examples.
+ The first file (
+\family typewriter
+dislocation_slip.spatialdb
+\family default
+) specifies 0.01 m of left-lateral fault slip for the entire fault.
+ The data dimension is zero since the same data are applied to all points
+ in the set.
+ The default slip time function is a step-function, so we also must provide
+ the time at which slip begins.
+ The elastic solution is associated with advancing from 
+\begin_inset Formula $t=-dt$
+\end_inset
+
+ to 
+\begin_inset Formula $t=0$
+\end_inset
+
+, so we set the slip initiation time for the step-function to 0 in 
+\family typewriter
+dislocation_sliptime.spatialdb
+\family default
+.
+\end_layout
+
+\begin_layout Standard
+The files containing common information (
+\family typewriter
+twotet4.mesh
+\family default
+, 
+\family typewriter
+pylithapp.cfg
+\family default
+, 
+\family typewriter
+matprops.spatialdb
+\family default
+) along with the problem-specific files (
+\family typewriter
+\size small
+dislocation.cfg
+\family default
+, 
+\family typewriter
+dislocation_slip.spatialdb
+\family default
+, 
+\family typewriter
+dislocation_sliptime.spatialdb
+\family default
+\size default
+) provide a complete description of the problem, and we can then run this
+ example by typing
+\end_layout
+
+\begin_layout LyX-Code
+pylith dislocation.cfg
+\end_layout
+
+\begin_layout Standard
+If the problem ran correctly, you should be able to generate a figure such
+ as Figure 
+\begin_inset CommandInset ref
+LatexCommand vref
+reference "fig:twotet4-disloc"
+
+\end_inset
+
+, which was generated using ParaView.
+\end_layout
+
+\begin_layout Standard
+\begin_inset Float figure
+wide false
+sideways false
+status open
+
+\begin_layout Plain Layout
+\align center
+\begin_inset Graphics
+	filename figs/dislocation.jpg
+	lyxscale 50
+	scale 33
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Plain Layout
+\begin_inset Caption
+
+\begin_layout Plain Layout
+Color contours and vectors of displacement for the kinematic fault example
+ using a mesh composed of two linear tetrahedral cells.
+\begin_inset CommandInset label
+LatexCommand label
+name "fig:twotet4-disloc"
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\end_body
+\end_document

Modified: short/3D/PyLith/branches/v1.7-trunk/doc/userguide/tutorials/twotet4-geoproj/twotet4-geoproj.lyx
===================================================================
--- short/3D/PyLith/branches/v1.7-trunk/doc/userguide/tutorials/twotet4-geoproj/twotet4-geoproj.lyx	2012-06-25 04:52:47 UTC (rev 20403)
+++ short/3D/PyLith/branches/v1.7-trunk/doc/userguide/tutorials/twotet4-geoproj/twotet4-geoproj.lyx	2012-06-25 16:38:44 UTC (rev 20404)
@@ -1,577 +1,577 @@
-#LyX 2.0 created this file. For more info see http://www.lyx.org/
-\lyxformat 413
-\begin_document
-\begin_header
-\textclass book
-\begin_preamble
-
-\end_preamble
-\use_default_options false
-\maintain_unincluded_children false
-\language english
-\language_package default
-\inputencoding latin1
-\fontencoding global
-\font_roman default
-\font_sans default
-\font_typewriter default
-\font_default_family default
-\use_non_tex_fonts false
-\font_sc false
-\font_osf false
-\font_sf_scale 100
-\font_tt_scale 100
-
-\graphics default
-\default_output_format default
-\output_sync 0
-\bibtex_command default
-\index_command default
-\paperfontsize default
-\spacing single
-\use_hyperref false
-\papersize default
-\use_geometry true
-\use_amsmath 0
-\use_esint 0
-\use_mhchem 1
-\use_mathdots 1
-\cite_engine basic
-\use_bibtopic false
-\use_indices false
-\paperorientation portrait
-\suppress_date false
-\use_refstyle 0
-\index Index
-\shortcut idx
-\color #008000
-\end_index
-\leftmargin 1in
-\topmargin 1in
-\rightmargin 1in
-\bottommargin 2in
-\secnumdepth 3
-\tocdepth 3
-\paragraph_separation indent
-\paragraph_indentation default
-\quotes_language english
-\papercolumns 1
-\papersides 1
-\paperpagestyle default
-\tracking_changes false
-\output_changes false
-\html_math_output 0
-\html_css_as_file 0
-\html_be_strict false
-\end_header
-
-\begin_body
-
-\begin_layout Section
-\begin_inset CommandInset label
-LatexCommand label
-name "sec:Tutorial-Two-tet4-geoproj"
-
-\end_inset
-
-Tutorial Using Two Tetrahedra with Georeferenced Coordinate System Mesh
-\end_layout
-
-\begin_layout Standard
-PyLith features discussed in this tutorial:
-\end_layout
-
-\begin_layout Itemize
-Quasi-static solution
-\end_layout
-
-\begin_layout Itemize
-Mesh ASCII format
-\end_layout
-
-\begin_layout Itemize
-Dirichlet boundary conditions
-\end_layout
-
-\begin_layout Itemize
-Kinematic fault interface conditions
-\end_layout
-
-\begin_layout Itemize
-Linearly elastic isotropic material
-\end_layout
-
-\begin_layout Itemize
-VTK output
-\end_layout
-
-\begin_layout Itemize
-Linear tetrahedral cells
-\end_layout
-
-\begin_layout Itemize
-SimpleDB spatial database with geographic coordinates
-\end_layout
-
-\begin_layout Itemize
-SCEC CVM-H spatial database
-\end_layout
-
-\begin_layout Itemize
-ZeroDispDB spatial database
-\end_layout
-
-\begin_layout Standard
-All of the files necessary to run the examples are contained in the directory
- 
-\family typewriter
-examples/twocells/twotet4-geoproj.
-\end_layout
-
-\begin_layout Subsection
-Overview
-\end_layout
-
-\begin_layout Standard
-This tutorial is virtually identical to the other tutorial using two linear
- tetrahedra (See Section 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "sec:Tutorial-Two-tet4"
-
-\end_inset
-
-).
- The primary difference is in how the material properties are assigned.
- For this tutorial, the physical properties come from the SCEC CVM-H database
- (described in Section 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "sub:SCECCVMH-Impl"
-
-\end_inset
-
-).
- Using the SCEC CVM-H database is straightforward, requiring only a few
- modifications to 
-\family typewriter
-pylithapp.cfg
-\family default
-.
- Because the SCEC CVM-H database uses geographic coordinates, we must also
- use geographic coordinates in the PyLith mesh ASCII file and other spatial
- databases.
- Note that all of these geographic coordinate systems do not need to be
- the same.
- PyLith will automatically transform from one geographic coordinate system
- to another using the spatialdata package.
- The spatial databases should all use a georeferenced Cartesian coordinate
- system, such as a geographic projection to insure interpolation is performed
- properly.
- Since all aspects of this problem other than the material database and
- the coordinate system are identical to the examples in Section 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "sec:Tutorial-Two-tet4"
-
-\end_inset
-
-, we only describe the kinematic fault problem in this tutorial.
-\end_layout
-
-\begin_layout Subsection
-Mesh Description
-\end_layout
-
-\begin_layout Standard
-The mesh consists of two tetrahedra forming a pyramid shape (Figure 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "fig:twotet4-geoproj-mesh"
-
-\end_inset
-
-).
- The mesh geometry and topology are described in the file 
-\family typewriter
-twotet4.mesh
-\family default
-, which is in PyLith mesh ASCII format.
- If you compare this mesh against the one used in 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "sec:Tutorial-Two-tet4"
-
-\end_inset
-
-, you will notice that, although the mesh topology is the same, the vertex
- coordinates are significantly different.
- We use zone 11 UTM coordinates with the NAD27 datum for the mesh.
- Although we used the same coordinate system as the SCEC CVM-H, we could
- have also used any another geographic projection supported by spatialdata
- and Proj.4.
- See Appendix 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "sec:Spatialdata:SimpleIOAscii"
-
-\end_inset
-
- for other examples of using geographic coordinates.
- 
-\end_layout
-
-\begin_layout Standard
-\noindent
-\align center
-\begin_inset Float figure
-wide false
-sideways false
-status open
-
-\begin_layout Plain Layout
-\align center
-\begin_inset Graphics
-	filename figs/twotet4-mesh.eps
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Plain Layout
-\begin_inset Caption
-
-\begin_layout Plain Layout
-Mesh composed of two linear tetrahedral cells in a georeferenced coordinate
- system used for the example problems.
-\begin_inset CommandInset label
-LatexCommand label
-name "fig:twotet4-geoproj-mesh"
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Subsection
-Additional Common Information
-\end_layout
-
-\begin_layout Standard
-This problem has some unique aspects compared to the other tutorials.
- First, all of the other tutorials use a Cartesian coordinate system, while
- this one uses a geographic coordinate system.
- In addition to using different vertex coordinates, we also define the coordinat
-e system for the mesh in 
-\family typewriter
-pylithapp.cfg
-\family default
-:
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.mesh_generator.importer]
-\end_layout
-
-\begin_layout LyX-Code
-coordsys = spatialdata.geocoords.CSGeoProj
-\end_layout
-
-\begin_layout LyX-Code
-filename = twotet4.mesh
-\end_layout
-
-\begin_layout LyX-Code
-coordsys.space_dim = 3
-\end_layout
-
-\begin_layout LyX-Code
- 
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.mesh_generator.importer.coordsys]
-\end_layout
-
-\begin_layout LyX-Code
-datum_horiz = NAD27
-\end_layout
-
-\begin_layout LyX-Code
-datum_vert = mean sea level
-\end_layout
-
-\begin_layout LyX-Code
-ellipsoid = clrk66
-\end_layout
-
-\begin_layout LyX-Code
- 
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.mesh_generator.importer.coordsys.projector]
-\end_layout
-
-\begin_layout LyX-Code
-projection = utm
-\end_layout
-
-\begin_layout LyX-Code
-proj-options = +zone=11 
-\end_layout
-
-\begin_layout Standard
-At the top level, we define the type of coordinate system, give the file
- describing the mesh, and give the number of spatial dimensions for the
- coordinate system.
- We then provide the horizontal datum and vertical datum for the coordinate
- system, along with the ellipsoid to be used.
- Finally, we specify a UTM projection, and specify zone 11 as the zone to
- be used.
-\end_layout
-
-\begin_layout Standard
-In addition to the usual material information, we must specify that we want
- to use the 
-\family typewriter
-SCECCVMH
-\family default
- database implementation:
-\end_layout
-
-\begin_layout LyX-Code
-[pylithapp.timedependent.materials.material]
-\end_layout
-
-\begin_layout LyX-Code
-db = spatialdata.spatialdb.SCECCVMH
-\end_layout
-
-\begin_layout LyX-Code
-db.data_dir = /home/brad/data/sceccvm-h/vx53/bin
-\end_layout
-
-\begin_layout Standard
-The first 
-\family typewriter
-db
-\family default
- option defines 
-\family typewriter
-SCECCVMH
-\family default
- as the spatial database to be used.
- The next line defines the location of the 
-\family typewriter
-vx53
-\family default
- data files, and must be changed to the location specified by the user when
- the package is installed.
- The package may be obtained from Harvard's Structural Geology and Tectonics
- 
-\begin_inset Flex URL
-status collapsed
-
-\begin_layout Plain Layout
-
-structure.harvard.edu/cvm-h
-\end_layout
-
-\end_inset
-
-.
-\end_layout
-
-\begin_layout Standard
-The final difference with the other examples is in the description of the
- spatial databases.
- They must also use geographic coordinates.
- Examining 
-\family typewriter
-dislocation_slip.spatialdb
-\family default
-, we find:
-\end_layout
-
-\begin_layout LyX-Code
-// We are specifying the data in a projected geographic coordinate system.
-\end_layout
-
-\begin_layout LyX-Code
-cs-data = geo-projected {
-\end_layout
-
-\begin_layout LyX-Code
-  to-meters = 1.0
-\end_layout
-
-\begin_layout LyX-Code
-  ellipsoid = clrk66
-\end_layout
-
-\begin_layout LyX-Code
-  datum-horiz = NAD27
-\end_layout
-
-\begin_layout LyX-Code
-  datum-vert = mean sea level
-\end_layout
-
-\begin_layout LyX-Code
-  projector = projection {
-\end_layout
-
-\begin_layout LyX-Code
-    projection = utm
-\end_layout
-
-\begin_layout LyX-Code
-    units = m
-\end_layout
-
-\begin_layout LyX-Code
-    proj-options = +zone=11
-\end_layout
-
-\begin_layout LyX-Code
-  }
-\end_layout
-
-\begin_layout LyX-Code
-}
-\end_layout
-
-\begin_layout Subsection
-Kinematic Fault Slip Example
-\end_layout
-
-\begin_layout Standard
-This example problem is a left-lateral fault slip applied between the two
- tetrahedral cells using kinematic cohesive cells.
- Note that we vary the amount of fault slip for each vertex with this example,
- as described in 
-\family typewriter
-dislocation_slip.spatialdb
-\family default
-.
- The vertices away from the fault are held fixed in the x, y, and z directions.
- Parameter settings that override or augment those in 
-\family typewriter
-pylithapp.cfg
-\family default
- are contained in the file 
-\family typewriter
-dislocation.cfg
-\family default
-.
-\end_layout
-
-\begin_layout Standard
-Recall that we condition problems with the kinematic fault interface using
- the material properties.
- Since the material properties are being defined using the SCEC CVM-H database,
- this same database should be used as the material database for the faults.
- This also applies to the AbsorbingDampers boundary condition.
-\end_layout
-
-\begin_layout Standard
-The files containing common information (
-\family typewriter
-twotet4.mesh
-\family default
-, 
-\family typewriter
-pylithapp.cfg
-\family default
-) along with the problem-specific files (
-\family typewriter
-\size small
-dislocation.cfg
-\family default
-, 
-\family typewriter
-dislocation_slip.spatialdb
-\family default
-, 
-\family typewriter
-dislocation_sliptime.spatialdb
-\family default
-\size default
-) provide a complete description of the problem, and we can then run this
- example by typing
-\end_layout
-
-\begin_layout LyX-Code
-pylith dislocation.cfg
-\end_layout
-
-\begin_layout Standard
-If the problem ran correctly, you should be able to generate a figure such
- as Figure 
-\begin_inset CommandInset ref
-LatexCommand vref
-reference "fig:twotet4-geoproj-disloc"
-
-\end_inset
-
-, which was generated using ParaView.
-\end_layout
-
-\begin_layout Standard
-\begin_inset Float figure
-wide false
-sideways false
-status open
-
-\begin_layout Plain Layout
-\align center
-\begin_inset Graphics
-	filename figs/dislocation.jpg
-	lyxscale 50
-	scale 33
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Plain Layout
-\begin_inset Caption
-
-\begin_layout Plain Layout
-Color contours and vectors of displacement for the kinematic fault example
- using a mesh composed of two linear tetrahedral cells in a georeferenced
- coordinate system.
-\begin_inset CommandInset label
-LatexCommand label
-name "fig:twotet4-geoproj-disloc"
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_body
-\end_document
+#LyX 2.0 created this file. For more info see http://www.lyx.org/
+\lyxformat 413
+\begin_document
+\begin_header
+\textclass book
+\begin_preamble
+
+\end_preamble
+\use_default_options false
+\maintain_unincluded_children false
+\language english
+\language_package default
+\inputencoding latin1
+\fontencoding global
+\font_roman default
+\font_sans default
+\font_typewriter default
+\font_default_family default
+\use_non_tex_fonts false
+\font_sc false
+\font_osf false
+\font_sf_scale 100
+\font_tt_scale 100
+
+\graphics default
+\default_output_format default
+\output_sync 0
+\bibtex_command default
+\index_command default
+\paperfontsize default
+\spacing single
+\use_hyperref false
+\papersize default
+\use_geometry true
+\use_amsmath 0
+\use_esint 0
+\use_mhchem 1
+\use_mathdots 1
+\cite_engine basic
+\use_bibtopic false
+\use_indices false
+\paperorientation portrait
+\suppress_date false
+\use_refstyle 0
+\index Index
+\shortcut idx
+\color #008000
+\end_index
+\leftmargin 1in
+\topmargin 1in
+\rightmargin 1in
+\bottommargin 2in
+\secnumdepth 3
+\tocdepth 3
+\paragraph_separation indent
+\paragraph_indentation default
+\quotes_language english
+\papercolumns 1
+\papersides 1
+\paperpagestyle default
+\tracking_changes false
+\output_changes false
+\html_math_output 0
+\html_css_as_file 0
+\html_be_strict false
+\end_header
+
+\begin_body
+
+\begin_layout Section
+\begin_inset CommandInset label
+LatexCommand label
+name "sec:Tutorial-Two-tet4-geoproj"
+
+\end_inset
+
+Tutorial Using Two Tetrahedra with Georeferenced Coordinate System Mesh
+\end_layout
+
+\begin_layout Standard
+PyLith features discussed in this tutorial:
+\end_layout
+
+\begin_layout Itemize
+Quasi-static solution
+\end_layout
+
+\begin_layout Itemize
+Mesh ASCII format
+\end_layout
+
+\begin_layout Itemize
+Dirichlet boundary conditions
+\end_layout
+
+\begin_layout Itemize
+Kinematic fault interface conditions
+\end_layout
+
+\begin_layout Itemize
+Linearly elastic isotropic material
+\end_layout
+
+\begin_layout Itemize
+VTK output
+\end_layout
+
+\begin_layout Itemize
+Linear tetrahedral cells
+\end_layout
+
+\begin_layout Itemize
+SimpleDB spatial database with geographic coordinates
+\end_layout
+
+\begin_layout Itemize
+SCEC CVM-H spatial database
+\end_layout
+
+\begin_layout Itemize
+ZeroDispDB spatial database
+\end_layout
+
+\begin_layout Standard
+All of the files necessary to run the examples are contained in the directory
+ 
+\family typewriter
+examples/twocells/twotet4-geoproj.
+\end_layout
+
+\begin_layout Subsection
+Overview
+\end_layout
+
+\begin_layout Standard
+This tutorial is virtually identical to the other tutorial using two linear
+ tetrahedra (See Section 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "sec:Tutorial-Two-tet4"
+
+\end_inset
+
+).
+ The primary difference is in how the material properties are assigned.
+ For this tutorial, the physical properties come from the SCEC CVM-H database
+ (described in Section 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "sub:SCECCVMH-Impl"
+
+\end_inset
+
+).
+ Using the SCEC CVM-H database is straightforward, requiring only a few
+ modifications to 
+\family typewriter
+pylithapp.cfg
+\family default
+.
+ Because the SCEC CVM-H database uses geographic coordinates, we must also
+ use geographic coordinates in the PyLith mesh ASCII file and other spatial
+ databases.
+ Note that all of these geographic coordinate systems do not need to be
+ the same.
+ PyLith will automatically transform from one geographic coordinate system
+ to another using the spatialdata package.
+ The spatial databases should all use a georeferenced Cartesian coordinate
+ system, such as a geographic projection to insure interpolation is performed
+ properly.
+ Since all aspects of this problem other than the material database and
+ the coordinate system are identical to the examples in Section 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "sec:Tutorial-Two-tet4"
+
+\end_inset
+
+, we only describe the kinematic fault problem in this tutorial.
+\end_layout
+
+\begin_layout Subsection
+Mesh Description
+\end_layout
+
+\begin_layout Standard
+The mesh consists of two tetrahedra forming a pyramid shape (Figure 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "fig:twotet4-geoproj-mesh"
+
+\end_inset
+
+).
+ The mesh geometry and topology are described in the file 
+\family typewriter
+twotet4.mesh
+\family default
+, which is in PyLith mesh ASCII format.
+ If you compare this mesh against the one used in 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "sec:Tutorial-Two-tet4"
+
+\end_inset
+
+, you will notice that, although the mesh topology is the same, the vertex
+ coordinates are significantly different.
+ We use zone 11 UTM coordinates with the NAD27 datum for the mesh.
+ Although we used the same coordinate system as the SCEC CVM-H, we could
+ have also used any other geographic projection supported by spatialdata
+ and Proj.4.
+ See Appendix 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "sec:Spatialdata:SimpleIOAscii"
+
+\end_inset
+
+ for other examples of using geographic coordinates.
+ 
+\end_layout
+
+\begin_layout Standard
+\noindent
+\align center
+\begin_inset Float figure
+wide false
+sideways false
+status open
+
+\begin_layout Plain Layout
+\align center
+\begin_inset Graphics
+	filename figs/twotet4-mesh.eps
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Plain Layout
+\begin_inset Caption
+
+\begin_layout Plain Layout
+Mesh composed of two linear tetrahedral cells in a georeferenced coordinate
+ system used for the example problems.
+\begin_inset CommandInset label
+LatexCommand label
+name "fig:twotet4-geoproj-mesh"
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Subsection
+Additional Common Information
+\end_layout
+
+\begin_layout Standard
+This problem has some unique aspects compared to the other tutorials.
+ First, all of the other tutorials use a Cartesian coordinate system, while
+ this one uses a geographic coordinate system.
+ In addition to using different vertex coordinates, we also define the coordinat
+e system for the mesh in 
+\family typewriter
+pylithapp.cfg
+\family default
+:
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.mesh_generator.importer]
+\end_layout
+
+\begin_layout LyX-Code
+coordsys = spatialdata.geocoords.CSGeoProj
+\end_layout
+
+\begin_layout LyX-Code
+filename = twotet4.mesh
+\end_layout
+
+\begin_layout LyX-Code
+coordsys.space_dim = 3
+\end_layout
+
+\begin_layout LyX-Code
+ 
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.mesh_generator.importer.coordsys]
+\end_layout
+
+\begin_layout LyX-Code
+datum_horiz = NAD27
+\end_layout
+
+\begin_layout LyX-Code
+datum_vert = mean sea level
+\end_layout
+
+\begin_layout LyX-Code
+ellipsoid = clrk66
+\end_layout
+
+\begin_layout LyX-Code
+ 
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.mesh_generator.importer.coordsys.projector]
+\end_layout
+
+\begin_layout LyX-Code
+projection = utm
+\end_layout
+
+\begin_layout LyX-Code
+proj-options = +zone=11 
+\end_layout
+
+\begin_layout Standard
+At the top level, we define the type of coordinate system, give the file
+ describing the mesh, and give the number of spatial dimensions for the
+ coordinate system.
+ We then provide the horizontal datum and vertical datum for the coordinate
+ system, along with the ellipsoid to be used.
+ Finally, we specify a UTM projection, and specify zone 11 as the zone to
+ be used.
+\end_layout
+
+\begin_layout Standard
+In addition to the usual material information, we must specify that we want
+ to use the 
+\family typewriter
+SCECCVMH
+\family default
+ database implementation:
+\end_layout
+
+\begin_layout LyX-Code
+[pylithapp.timedependent.materials.material]
+\end_layout
+
+\begin_layout LyX-Code
+db = spatialdata.spatialdb.SCECCVMH
+\end_layout
+
+\begin_layout LyX-Code
+db.data_dir = /home/brad/data/sceccvm-h/vx53/bin
+\end_layout
+
+\begin_layout Standard
+The first 
+\family typewriter
+db
+\family default
+ option defines 
+\family typewriter
+SCECCVMH
+\family default
+ as the spatial database to be used.
+ The next line defines the location of the 
+\family typewriter
+vx53
+\family default
+ data files, and must be changed to the location specified by the user when
+ the package is installed.
+ The package may be obtained from Harvard's Structural Geology and Tectonics
+ 
+\begin_inset Flex URL
+status collapsed
+
+\begin_layout Plain Layout
+
+structure.harvard.edu/cvm-h
+\end_layout
+
+\end_inset
+
+.
+\end_layout
+
+\begin_layout Standard
+The final difference with the other examples is in the description of the
+ spatial databases.
+ They must also use geographic coordinates.
+ Examining 
+\family typewriter
+dislocation_slip.spatialdb
+\family default
+, we find:
+\end_layout
+
+\begin_layout LyX-Code
+// We are specifying the data in a projected geographic coordinate system.
+\end_layout
+
+\begin_layout LyX-Code
+cs-data = geo-projected {
+\end_layout
+
+\begin_layout LyX-Code
+  to-meters = 1.0
+\end_layout
+
+\begin_layout LyX-Code
+  ellipsoid = clrk66
+\end_layout
+
+\begin_layout LyX-Code
+  datum-horiz = NAD27
+\end_layout
+
+\begin_layout LyX-Code
+  datum-vert = mean sea level
+\end_layout
+
+\begin_layout LyX-Code
+  projector = projection {
+\end_layout
+
+\begin_layout LyX-Code
+    projection = utm
+\end_layout
+
+\begin_layout LyX-Code
+    units = m
+\end_layout
+
+\begin_layout LyX-Code
+    proj-options = +zone=11
+\end_layout
+
+\begin_layout LyX-Code
+  }
+\end_layout
+
+\begin_layout LyX-Code
+}
+\end_layout
+
+\begin_layout Subsection
+Kinematic Fault Slip Example
+\end_layout
+
+\begin_layout Standard
+This example problem is a left-lateral fault slip applied between the two
+ tetrahedral cells using kinematic cohesive cells.
+ Note that we vary the amount of fault slip for each vertex with this example,
+ as described in 
+\family typewriter
+dislocation_slip.spatialdb
+\family default
+.
+ The vertices away from the fault are held fixed in the x, y, and z directions.
+ Parameter settings that override or augment those in 
+\family typewriter
+pylithapp.cfg
+\family default
+ are contained in the file 
+\family typewriter
+dislocation.cfg
+\family default
+.
+\end_layout
+
+\begin_layout Standard
+Recall that we condition problems with the kinematic fault interface using
+ the material properties.
+ Since the material properties are being defined using the SCEC CVM-H database,
+ this same database should be used as the material database for the faults.
+ This also applies to the AbsorbingDampers boundary condition.
+\end_layout
+
+\begin_layout Standard
+The files containing common information (
+\family typewriter
+twotet4.mesh
+\family default
+, 
+\family typewriter
+pylithapp.cfg
+\family default
+) along with the problem-specific files (
+\family typewriter
+\size small
+dislocation.cfg
+\family default
+, 
+\family typewriter
+dislocation_slip.spatialdb
+\family default
+, 
+\family typewriter
+dislocation_sliptime.spatialdb
+\family default
+\size default
+) provide a complete description of the problem, and we can then run this
+ example by typing
+\end_layout
+
+\begin_layout LyX-Code
+pylith dislocation.cfg
+\end_layout
+
+\begin_layout Standard
+If the problem ran correctly, you should be able to generate a figure such
+ as Figure 
+\begin_inset CommandInset ref
+LatexCommand vref
+reference "fig:twotet4-geoproj-disloc"
+
+\end_inset
+
+, which was generated using ParaView.
+\end_layout
+
+\begin_layout Standard
+\begin_inset Float figure
+wide false
+sideways false
+status open
+
+\begin_layout Plain Layout
+\align center
+\begin_inset Graphics
+	filename figs/dislocation.jpg
+	lyxscale 50
+	scale 33
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Plain Layout
+\begin_inset Caption
+
+\begin_layout Plain Layout
+Color contours and vectors of displacement for the kinematic fault example
+ using a mesh composed of two linear tetrahedral cells in a georeferenced
+ coordinate system.
+\begin_inset CommandInset label
+LatexCommand label
+name "fig:twotet4-geoproj-disloc"
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\end_body
+\end_document

Modified: short/3D/PyLith/branches/v1.7-trunk/doc/userguide/tutorials/twotri3/twotri3.lyx
===================================================================
--- short/3D/PyLith/branches/v1.7-trunk/doc/userguide/tutorials/twotri3/twotri3.lyx	2012-06-25 04:52:47 UTC (rev 20403)
+++ short/3D/PyLith/branches/v1.7-trunk/doc/userguide/tutorials/twotri3/twotri3.lyx	2012-06-25 16:38:44 UTC (rev 20404)
@@ -1,870 +1,870 @@
-#LyX 2.0 created this file. For more info see http://www.lyx.org/
-\lyxformat 413
-\begin_document
-\begin_header
-\textclass book
-\begin_preamble
-
-\end_preamble
-\use_default_options false
-\maintain_unincluded_children false
-\language english
-\language_package default
-\inputencoding latin1
-\fontencoding global
-\font_roman default
-\font_sans default
-\font_typewriter default
-\font_default_family default
-\use_non_tex_fonts false
-\font_sc false
-\font_osf false
-\font_sf_scale 100
-\font_tt_scale 100
-
-\graphics default
-\default_output_format default
-\output_sync 0
-\bibtex_command default
-\index_command default
-\paperfontsize default
-\spacing single
-\use_hyperref false
-\papersize default
-\use_geometry true
-\use_amsmath 0
-\use_esint 0
-\use_mhchem 1
-\use_mathdots 1
-\cite_engine basic
-\use_bibtopic false
-\use_indices false
-\paperorientation portrait
-\suppress_date false
-\use_refstyle 0
-\index Index
-\shortcut idx
-\color #008000
-\end_index
-\leftmargin 1in
-\topmargin 1in
-\rightmargin 1in
-\bottommargin 1in
-\secnumdepth 3
-\tocdepth 3
-\paragraph_separation indent
-\paragraph_indentation default
-\quotes_language english
-\papercolumns 1
-\papersides 1
-\paperpagestyle default
-\tracking_changes false
-\output_changes false
-\html_math_output 0
-\html_css_as_file 0
-\html_be_strict false
-\end_header
-
-\begin_body
-
-\begin_layout Section
-\begin_inset CommandInset label
-LatexCommand label
-name "sec:Tutorial-Two-triangle"
-
-\end_inset
-
-Tutorial Using Two Triangles
-\end_layout
-
-\begin_layout Standard
-PyLith features discussed in this tutorial:
-\end_layout
-
-\begin_layout Itemize
-Quasi-static solution
-\end_layout
-
-\begin_layout Itemize
-Mesh ASCII format
-\end_layout
-
-\begin_layout Itemize
-Dirichlet boundary conditions
-\end_layout
-
-\begin_layout Itemize
-Kinematic fault interface conditions
-\end_layout
-
-\begin_layout Itemize
-Plane strain linearly elastic material
-\end_layout
-
-\begin_layout Itemize
-VTK output
-\end_layout
-
-\begin_layout Itemize
-Linear triangular cells
-\end_layout
-
-\begin_layout Itemize
-SimpleDB spatial database
-\end_layout
-
-\begin_layout Itemize
-ZeroDispDB spatial database
-\end_layout
-
-\begin_layout Standard
-All of the files necessary to run the examples are contained in the directory
- 
-\family typewriter
-examples/twocells/twotri3.
-\end_layout
-
-\begin_layout Subsection
-Overview
-\end_layout
-
-\begin_layout Standard
-This tutorial is the simplest 2D example of a quasi-static finite element
- problem (a simpler problem would consist of a 1D bar).
- It is a mesh composed of two linear triangles subject to displacement boundary
- conditions, assuming plane-strain linear elastic behavior.
- Due to the simple geometry of the problem, the mesh may be constructed
- by hand, using PyLith mesh ASCII format.
- In this tutorial, we will walk through the steps necessary to construct,
- run, and view three problems that use the same mesh.
- In addition to this manual, each of the files for the example problem includes
- extensive comments.
-\end_layout
-
-\begin_layout Subsection
-Mesh Description
-\end_layout
-
-\begin_layout Standard
-The mesh consists of two triangles forming a square with edge lengths of
- one unit (Figure 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "fig:twotri3-mesh"
-
-\end_inset
-
-).
- The mesh geometry and topology are described in the file 
-\family typewriter
-twotri3.mesh
-\family default
-, which is in PyLith mesh ASCII format.
- This file format is described in Appendix 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "cha:File-Formats"
-
-\end_inset
-
-.
- This file describes the dimensionality of the problem (1D, 2D, or 3D),
- the coordinates of the vertices (nodes), the vertices composing each cell
- (element), the material ID to be associated with each cell, and groups
- of vertices that may be used to define faults or surfaces to which boundary
- conditions may be applied.
-\end_layout
-
-\begin_layout Standard
-\begin_inset Float figure
-wide false
-sideways false
-status open
-
-\begin_layout Plain Layout
-\align center
-\begin_inset Graphics
-	filename figs/twotri3-mesh.eps
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Plain Layout
-\begin_inset Caption
-
-\begin_layout Plain Layout
-Mesh composed of two linear triangular cells used in the example problems.
-\begin_inset CommandInset label
-LatexCommand label
-name "fig:twotri3-mesh"
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Subsection
-Additional Common Information
-\end_layout
-
-\begin_layout Standard
-In addition to the mesh, the three example problems share additional information.
- For problems of this type, it is generally useful to create a file named
- 
-\family typewriter
-pylithapp.cfg
-\family default
- in the working directory, since this file is read automatically every time
- PyLith is run.
- Settings specific to a particular problem may be placed in other 
-\family typewriter
-.cfg
-\family default
- files, as described later, and then those files are placed on the command
- line.
- The settings contained in 
-\family typewriter
-pylithapp.cfg
-\family default
- for this problem consist of:
-\end_layout
-
-\begin_layout Description
-pylithapp.journal.info Settings that control the verbosity of the output for
- the different components.
-\end_layout
-
-\begin_layout Description
-pylithapp.mesh_generator Settings that control mesh importing, such as the
- importer type, the filename, and the spatial dimension of the mesh.
-\end_layout
-
-\begin_layout Description
-pylithapp.timedependent Settings that control the problem, such as the total
- time, time step size, and spatial dimension.
-\end_layout
-
-\begin_layout Description
-pylithapp.timedependent.materials Settings that control the material type,
- specify which material IDs are to be associated with a particular material
- type, and give the name of the spatial database containing the physical
-  properties for the material.
- The quadrature information is also given.
-\end_layout
-
-\begin_layout Description
-pylithapp.petsc PETSc settings to use for the problem, such as the preconditioner
- type.
-\end_layout
-
-\begin_layout Standard
-All of the problems in this directory use the same material database, as
- specified under 
-\end_layout
-
-\begin_layout LyX-Code
-
-\family typewriter
-pylithapp.timedependent.materials
-\family default
- 
-\end_layout
-
-\begin_layout Standard
-in 
-\family typewriter
-pylithapp.cfg
-\family default
-.
- This information is contained in the file 
-\family typewriter
-matprops.spatialdb
-\family default
-.
- Although the material model is specified in 
-\family typewriter
-pylithapp.cfg
-\family default
-, the values for the physical properties of the material are given in 
-\family typewriter
-matprops.spatialdb
-\family default
-.
- For this example, values describing elastic plane strain material properties
- are given at a single point, resulting in uniform material properties.
-\end_layout
-
-\begin_layout Subsection
-Axial Displacement Example
-\end_layout
-
-\begin_layout Standard
-The first example problem is extension of the mesh along the diagonal extending
- from the lower left to the upper right of the square mesh.
- Parameter settings that augment those in 
-\family typewriter
-pylithapp.cfg
-\family default
- are contained in the file 
-\family typewriter
-axialdisp.cfg
-\family default
-.
- These settings are:
-\end_layout
-
-\begin_layout Description
-pylithapp.timedependent Specifies an implicit formulation for the problem
- and specifies the array of boundary conditions.
-\end_layout
-
-\begin_layout Description
-pylithapp.timedependent.bc.bc Defines which degrees of freedom are being constraine
-d (x and y), gives the label (defined in 
-\family typewriter
-twotri3.mesh
-\family default
-) defining the points desired, assigns a label to the boundary condition
- set, and gives the name of the spatial database with the values for the
- Dirichlet boundary condition (
-\family typewriter
-axialdisp.spatialdb
-\family default
-).
-\end_layout
-
-\begin_layout Description
-pylithapp.problem.formulation.output.output.writer Gives the base filename for
- VTK output 
-\begin_inset Newline newline
-\end_inset
-
-(
-\family typewriter
-axialdisp.vtk
-\family default
-).
-\end_layout
-
-\begin_layout Description
-pylithapp.timedependent.materials.material.output Gives the base filename for
- state variable output files (
-\family typewriter
-axialdisp-statevars.vtk
-\family default
-).
-\end_layout
-
-\begin_layout Standard
-The values for the Dirichlet boundary condition are given in the file 
-\family typewriter
-axialdisp.spatialdb
-\family default
-, as specified in 
-\family typewriter
-axialdisp.cfg
-\family default
-.
- The format of all spatial database files is similar.
- In this case, the desired displacement values are given at two points (lower
- left and upper right).
- Since data are being specified at points (rather than being uniform over
- the mesh, for example), the data dimension is one.
-\end_layout
-
-\begin_layout Standard
-The files containing common information (
-\family typewriter
-twotri3.mesh
-\family default
-, 
-\family typewriter
-pylithapp.cfg
-\family default
-, 
-\family typewriter
-matprops.spatialdb
-\family default
-) along with the problem-specific files (
-\family typewriter
-axialdisp.cfg
-\family default
-, 
-\family typewriter
-axialdisp.spatialdb
-\family default
-) provide a complete description of the problem, and we can then run this
- example by typing
-\end_layout
-
-\begin_layout LyX-Code
-pylith axialdisp.cfg
-\end_layout
-
-\begin_layout Standard
-Once the problem has run, three files will be produced.
- The first file is named 
-\family typewriter
-axialdisp_t0000000.vtk
-\family default
-.
- The 
-\family typewriter
-t0000000
-\family default
- indicates that the output is for the first (and only) time step, corresponding
- to an elastic solution.
- This file contains mesh information as well as displacement values at the
- mesh vertices.
- The second file is named 
-\family typewriter
-axialdisp-statevars_t0000000.vtk
-\family default
-.
- This file contains the state variables for each cell.
- The default fields are the total strain and stress fields.
- Since the cells are linear triangles, there is a single quadrature point
- for each cell and thus a single set of stress and strain values for each
- cell.
- The final file (
-\family typewriter
-axialdisp-statevars_info.vtk
-\family default
-) gives the material properties used for the problem.
- Since we have not specified which properties to write, the default properties
- (
-\family typewriter
-mu
-\family default
-, 
-\family typewriter
-lambda
-\family default
-, 
-\family typewriter
-density
-\family default
-) are written.
- All of the 
-\family typewriter
-.vtk
-\family default
- files may be used with a number of visualization packages.
- If the problem ran correctly, you should be able to generate a figure such
- as Figure 
-\begin_inset CommandInset ref
-LatexCommand vref
-reference "fig:twotri3-axial"
-
-\end_inset
-
-, which was generated using ParaView.
-\end_layout
-
-\begin_layout Standard
-\noindent
-\align center
-\begin_inset Float figure
-wide false
-sideways false
-status open
-
-\begin_layout Plain Layout
-\align center
-\begin_inset Graphics
-	filename figs/axialdisp.jpg
-	lyxscale 50
-	scale 33
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Plain Layout
-\begin_inset Caption
-
-\begin_layout Plain Layout
-Color contours and vectors of displacement for the axial displacement example
- using a mesh composed of two linear triangular cells.
-\begin_inset CommandInset label
-LatexCommand label
-name "fig:twotri3-axial"
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Subsection
-Shear Displacement Example
-\end_layout
-
-\begin_layout Standard
-The next example problem is shearing of the mesh in the y direction using
- displacements applied along the positive and negative x boundaries.
- Parameter settings that augment those in 
-\family typewriter
-pylithapp.cfg
-\family default
- are contained in the file 
-\family typewriter
-sheardisp.cfg
-\family default
-.
- These settings include:
-\end_layout
-
-\begin_layout Description
-pylithapp.timedependent.bc.x_neg Specifies the boundary conditions for the
- left side of the mesh, defining which degrees of freedom are being constrained
- (x and y), giving the label (
-\family typewriter
-x_neg
-\family default
-, defined in 
-\family typewriter
-twotri3.mesh
-\family default
-) defining the points desired, assigning a label to the boundary condition
- set, and giving the name of the spatial database with the values for the
- Dirichlet boundary condition (
-\family typewriter
-sheardisp.spatialdb
-\family default
-).
-\end_layout
-
-\begin_layout Description
-pylithapp.timedependent.bc.x_pos Specifies the boundary conditions for the
- left side of the mesh, defining which degrees of freedom are being constrained
- (y only), giving the label (
-\family typewriter
-x_
-\family default
-pos, defined in 
-\family typewriter
-twotri3.mesh
-\family default
-) defining the points desired, assigning a label to the boundary condition
- set, and giving the name of the spatial database with the values for the
- Dirichlet boundary condition (
-\family typewriter
-sheardisp.spatialdb
-\family default
-).
-\end_layout
-
-\begin_layout Standard
-The files containing common information (
-\family typewriter
-twotri3.mesh
-\family default
-, 
-\family typewriter
-pylithapp.cfg
-\family default
-, 
-\family typewriter
-matprops.spatialdb
-\family default
-) along with the problem-specific files (
-\family typewriter
-sheardisp.cfg
-\family default
-, 
-\family typewriter
-sheardisp.spatialdb
-\family default
-) provide a complete description of the problem, and we can then run this
- example by typing
-\end_layout
-
-\begin_layout LyX-Code
-pylith sheardisp.cfg
-\end_layout
-
-\begin_layout Standard
-Once the problem has run, three files will be produced as in the previous
- example.
- If the problem ran correctly, you should be able to generate a figure such
- as Figure 
-\begin_inset CommandInset ref
-LatexCommand vref
-reference "fig:twotri-shear"
-
-\end_inset
-
-, which was generated using ParaView.
-\end_layout
-
-\begin_layout Standard
-\noindent
-\align center
-\begin_inset Float figure
-wide false
-sideways false
-status open
-
-\begin_layout Plain Layout
-\align center
-\begin_inset Graphics
-	filename figs/sheardisp.jpg
-	lyxscale 50
-	scale 33
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Plain Layout
-\begin_inset Caption
-
-\begin_layout Plain Layout
-Color contours and vectors of displacement for the shear displacement example
- using a mesh composed of two linear triangular cells.
-\begin_inset CommandInset label
-LatexCommand label
-name "fig:twotri-shear"
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Subsection
-Kinematic Fault Slip Example
-\end_layout
-
-\begin_layout Standard
-The next example problem is left-lateral fault slip applied between the
- two triangular cells using kinematic cohesive cells.
- The lower left and upper right boundaries are held fixed in the x and y
- directions.
- Parameter settings that augment those in 
-\family typewriter
-pylithapp.cfg
-\family default
- are contained in the file 
-\family typewriter
-dislocation.cfg
-\family default
-.
- The solution corresponds to rigid body rotation of each triangular cell.
- As a result, the tractions on the fault are zero.
- These settings include:
-\end_layout
-
-\begin_layout Description
-pylithapp.journal.info Turns on journaling for 1D quadrature (used for 2D
- faults) and for cohesive kinematic faults.
-\end_layout
-
-\begin_layout Description
-pylithapp.timedependent.bc.bc Defines which degrees of freedom are being constraine
-d (x and y), gives the label (defined in 
-\family typewriter
-twotri3.mesh
-\family default
-) defining the points desired, and assigns a label to the boundary condition
- set.
- In this case, rather than specifying a spatial database file with the values
- for the Dirichlet boundary condition.
- The default database (ZeroDispDB) for Dirichlet boundary conditions is
- used, which sets the displacements to zero.
-\end_layout
-
-\begin_layout Description
-pylithapp.timedependent.interfaces Gives the label (defined in 
-\family typewriter
-twotri3.mesh
-\family default
-) defining the points on the fault, provides quadrature information, and
- then gives database names for material properties (needed for conditioning),
- fault slip, peak fault slip rate, and fault slip time.
-\end_layout
-
-\begin_layout Description
-pylithapp.timedependent.interfaces.fault.output.writer Gives the base filename
- for cohesive cell output files (
-\family typewriter
-dislocation-fault.vtk
-\family default
-).
-\end_layout
-
-\begin_layout Standard
-Rather than specifying the displacement boundary conditions in a spatial
- database file, we use the default behavior for Dirichlet boundary conditions,
- which is a uniform, constant displacement of zero.
-\end_layout
-
-\begin_layout Standard
-The fault example requires three additional database files that were not
- needed for the simple displacement examples.
- The first file (
-\family typewriter
-dislocation_slip.spatialdb
-\family default
-) specifies 0.01 m of left-lateral fault slip for the entire fault.
- The data dimension is zero since the same data are applied to all points
- in the set.
- The default slip time function is a step-function, so we also must provide
- the time at which slip begins.
- The elastic solution is associated with advancing from 
-\begin_inset Formula $t=-dt$
-\end_inset
-
- to 
-\begin_inset Formula $t=0$
-\end_inset
-
-, so we set the slip initiation time for the step-function to 0 in 
-\family typewriter
-dislocation_sliptime.spatialdb
-\family default
-.
-\end_layout
-
-\begin_layout Standard
-The files containing common information (
-\family typewriter
-twotri3.mesh
-\family default
-, 
-\family typewriter
-pylithapp.cfg
-\family default
-, 
-\family typewriter
-matprops.spatialdb
-\family default
-) along with the problem-specific files (
-\family typewriter
-\size small
-dislocation.cfg
-\family default
-, 
-\family typewriter
-dislocation_slip.spatialdb
-\family default
-, 
-\family typewriter
-dislocation_sliptime.spatialdb
-\family default
-\size default
-) provide a complete description of the problem, and we can then run this
- example by typing
-\end_layout
-
-\begin_layout LyX-Code
-pylith dislocation.cfg
-\end_layout
-
-\begin_layout Standard
-Once the problem has run, five files are produced.
- In addition to the files produced in the previous two examples, this example
- produces two files associated with the fault interface.
- The file 
-\family typewriter
-dislocation-fault_t0000000.vtk
-\family default
- gives the fault slip for each vertex on the fault along with the computed
- traction change for the cohesive cell.
- The file 
-\family typewriter
-dislocation-fault_info.vtk
-\family default
- provides information such as the normal direction, final slip, and slip
- time for each vertex on the fault.
- If the problem ran correctly, you should be able to generate a figure such
- as Figure 
-\begin_inset CommandInset ref
-LatexCommand vref
-reference "fig:twotri-disloc"
-
-\end_inset
-
-, which was generated using ParaView.
-\end_layout
-
-\begin_layout Standard
-\noindent
-\align center
-\begin_inset Float figure
-wide false
-sideways false
-status open
-
-\begin_layout Plain Layout
-\align center
-\begin_inset Graphics
-	filename figs/dislocation.jpg
-	lyxscale 50
-	scale 33
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Plain Layout
-\begin_inset Caption
-
-\begin_layout Plain Layout
-Color contours and vectors of displacement for the kinematic fault example
- using a mesh composed of two linear triangular cells.
-\begin_inset CommandInset label
-LatexCommand label
-name "fig:twotri-disloc"
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_body
-\end_document
+#LyX 2.0 created this file. For more info see http://www.lyx.org/
+\lyxformat 413
+\begin_document
+\begin_header
+\textclass book
+\begin_preamble
+
+\end_preamble
+\use_default_options false
+\maintain_unincluded_children false
+\language english
+\language_package default
+\inputencoding latin1
+\fontencoding global
+\font_roman default
+\font_sans default
+\font_typewriter default
+\font_default_family default
+\use_non_tex_fonts false
+\font_sc false
+\font_osf false
+\font_sf_scale 100
+\font_tt_scale 100
+
+\graphics default
+\default_output_format default
+\output_sync 0
+\bibtex_command default
+\index_command default
+\paperfontsize default
+\spacing single
+\use_hyperref false
+\papersize default
+\use_geometry true
+\use_amsmath 0
+\use_esint 0
+\use_mhchem 1
+\use_mathdots 1
+\cite_engine basic
+\use_bibtopic false
+\use_indices false
+\paperorientation portrait
+\suppress_date false
+\use_refstyle 0
+\index Index
+\shortcut idx
+\color #008000
+\end_index
+\leftmargin 1in
+\topmargin 1in
+\rightmargin 1in
+\bottommargin 1in
+\secnumdepth 3
+\tocdepth 3
+\paragraph_separation indent
+\paragraph_indentation default
+\quotes_language english
+\papercolumns 1
+\papersides 1
+\paperpagestyle default
+\tracking_changes false
+\output_changes false
+\html_math_output 0
+\html_css_as_file 0
+\html_be_strict false
+\end_header
+
+\begin_body
+
+\begin_layout Section
+\begin_inset CommandInset label
+LatexCommand label
+name "sec:Tutorial-Two-triangle"
+
+\end_inset
+
+Tutorial Using Two Triangles
+\end_layout
+
+\begin_layout Standard
+PyLith features discussed in this tutorial:
+\end_layout
+
+\begin_layout Itemize
+Quasi-static solution
+\end_layout
+
+\begin_layout Itemize
+Mesh ASCII format
+\end_layout
+
+\begin_layout Itemize
+Dirichlet boundary conditions
+\end_layout
+
+\begin_layout Itemize
+Kinematic fault interface conditions
+\end_layout
+
+\begin_layout Itemize
+Plane strain linearly elastic material
+\end_layout
+
+\begin_layout Itemize
+VTK output
+\end_layout
+
+\begin_layout Itemize
+Linear triangular cells
+\end_layout
+
+\begin_layout Itemize
+SimpleDB spatial database
+\end_layout
+
+\begin_layout Itemize
+ZeroDispDB spatial database
+\end_layout
+
+\begin_layout Standard
+All of the files necessary to run the examples are contained in the directory
+ 
+\family typewriter
+examples/twocells/twotri3.
+\end_layout
+
+\begin_layout Subsection
+Overview
+\end_layout
+
+\begin_layout Standard
+This tutorial is the simplest 2D example of a quasi-static finite element
+ problem (a simpler problem would consist of a 1D bar).
+ It is a mesh composed of two linear triangles subject to displacement boundary
+ conditions, assuming plane-strain linear elastic behavior.
+ Due to the simple geometry of the problem, the mesh may be constructed
+ by hand, using PyLith mesh ASCII format.
+ In this tutorial, we will walk through the steps necessary to construct,
+ run, and view three problems that use the same mesh.
+ In addition to this manual, each of the files for the example problem includes
+ extensive comments.
+\end_layout
+
+\begin_layout Subsection
+Mesh Description
+\end_layout
+
+\begin_layout Standard
+The mesh consists of two triangles forming a square with edge lengths of
+ one unit (Figure 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "fig:twotri3-mesh"
+
+\end_inset
+
+).
+ The mesh geometry and topology are described in the file 
+\family typewriter
+twotri3.mesh
+\family default
+, which is in PyLith mesh ASCII format.
+ This file format is described in Appendix 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "cha:File-Formats"
+
+\end_inset
+
+.
+ This file describes the dimensionality of the problem (1D, 2D, or 3D),
+ the coordinates of the vertices (nodes), the vertices composing each cell
+ (element), the material ID to be associated with each cell, and groups
+ of vertices that may be used to define faults or surfaces to which boundary
+ conditions may be applied.
+\end_layout
+
+\begin_layout Standard
+\begin_inset Float figure
+wide false
+sideways false
+status open
+
+\begin_layout Plain Layout
+\align center
+\begin_inset Graphics
+	filename figs/twotri3-mesh.eps
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Plain Layout
+\begin_inset Caption
+
+\begin_layout Plain Layout
+Mesh composed of two linear triangular cells used in the example problems.
+\begin_inset CommandInset label
+LatexCommand label
+name "fig:twotri3-mesh"
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Subsection
+Additional Common Information
+\end_layout
+
+\begin_layout Standard
+In addition to the mesh, the three example problems share additional information.
+ For problems of this type, it is generally useful to create a file named
+ 
+\family typewriter
+pylithapp.cfg
+\family default
+ in the working directory, since this file is read automatically every time
+ PyLith is run.
+ Settings specific to a particular problem may be placed in other 
+\family typewriter
+.cfg
+\family default
+ files, as described later, and then those files are placed on the command
+ line.
+ The settings contained in 
+\family typewriter
+pylithapp.cfg
+\family default
+ for this problem consist of:
+\end_layout
+
+\begin_layout Description
+pylithapp.journal.info Settings that control the verbosity of the output for
+ the different components.
+\end_layout
+
+\begin_layout Description
+pylithapp.mesh_generator Settings that control mesh importing, such as the
+ importer type, the filename, and the spatial dimension of the mesh.
+\end_layout
+
+\begin_layout Description
+pylithapp.timedependent Settings that control the problem, such as the total
+ time, time step size, and spatial dimension.
+\end_layout
+
+\begin_layout Description
+pylithapp.timedependent.materials Settings that control the material type,
+ specify which material IDs are to be associated with a particular material
+ type, and give the name of the spatial database containing the physical
+  properties for the material.
+ The quadrature information is also given.
+\end_layout
+
+\begin_layout Description
+pylithapp.petsc PETSc settings to use for the problem, such as the preconditioner
+ type.
+\end_layout
+
+\begin_layout Standard
+All of the problems in this directory use the same material database, as
+ specified under 
+\end_layout
+
+\begin_layout LyX-Code
+
+\family typewriter
+pylithapp.timedependent.materials
+\family default
+ 
+\end_layout
+
+\begin_layout Standard
+in 
+\family typewriter
+pylithapp.cfg
+\family default
+.
+ This information is contained in the file 
+\family typewriter
+matprops.spatialdb
+\family default
+.
+ Although the material model is specified in 
+\family typewriter
+pylithapp.cfg
+\family default
+, the values for the physical properties of the material are given in 
+\family typewriter
+matprops.spatialdb
+\family default
+.
+ For this example, values describing elastic plane strain material properties
+ are given at a single point, resulting in uniform material properties.
+\end_layout
+
+\begin_layout Subsection
+Axial Displacement Example
+\end_layout
+
+\begin_layout Standard
+The first example problem is extension of the mesh along the diagonal extending
+ from the lower left to the upper right of the square mesh.
+ Parameter settings that augment those in 
+\family typewriter
+pylithapp.cfg
+\family default
+ are contained in the file 
+\family typewriter
+axialdisp.cfg
+\family default
+.
+ These settings are:
+\end_layout
+
+\begin_layout Description
+pylithapp.timedependent Specifies an implicit formulation for the problem
+ and specifies the array of boundary conditions.
+\end_layout
+
+\begin_layout Description
+pylithapp.timedependent.bc.bc Defines which degrees of freedom are being constraine
+d (x and y), gives the label (defined in 
+\family typewriter
+twotri3.mesh
+\family default
+) defining the points desired, assigns a label to the boundary condition
+ set, and gives the name of the spatial database with the values for the
+ Dirichlet boundary condition (
+\family typewriter
+axialdisp.spatialdb
+\family default
+).
+\end_layout
+
+\begin_layout Description
+pylithapp.problem.formulation.output.output.writer Gives the base filename for
+ VTK output 
+\begin_inset Newline newline
+\end_inset
+
+(
+\family typewriter
+axialdisp.vtk
+\family default
+).
+\end_layout
+
+\begin_layout Description
+pylithapp.timedependent.materials.material.output Gives the base filename for
+ state variable output files (
+\family typewriter
+axialdisp-statevars.vtk
+\family default
+).
+\end_layout
+
+\begin_layout Standard
+The values for the Dirichlet boundary condition are given in the file 
+\family typewriter
+axialdisp.spatialdb
+\family default
+, as specified in 
+\family typewriter
+axialdisp.cfg
+\family default
+.
+ The format of all spatial database files is similar.
+ In this case, the desired displacement values are given at two points (lower
+ left and upper right).
+ Since data are being specified at points (rather than being uniform over
+ the mesh, for example), the data dimension is one.
+\end_layout
+
+\begin_layout Standard
+The files containing common information (
+\family typewriter
+twotri3.mesh
+\family default
+, 
+\family typewriter
+pylithapp.cfg
+\family default
+, 
+\family typewriter
+matprops.spatialdb
+\family default
+) along with the problem-specific files (
+\family typewriter
+axialdisp.cfg
+\family default
+, 
+\family typewriter
+axialdisp.spatialdb
+\family default
+) provide a complete description of the problem, and we can then run this
+ example by typing
+\end_layout
+
+\begin_layout LyX-Code
+pylith axialdisp.cfg
+\end_layout
+
+\begin_layout Standard
+Once the problem has run, three files will be produced.
+ The first file is named 
+\family typewriter
+axialdisp_t0000000.vtk
+\family default
+.
+ The 
+\family typewriter
+t0000000
+\family default
+ indicates that the output is for the first (and only) time step, corresponding
+ to an elastic solution.
+ This file contains mesh information as well as displacement values at the
+ mesh vertices.
+ The second file is named 
+\family typewriter
+axialdisp-statevars_t0000000.vtk
+\family default
+.
+ This file contains the state variables for each cell.
+ The default fields are the total strain and stress fields.
+ Since the cells are linear triangles, there is a single quadrature point
+ for each cell and thus a single set of stress and strain values for each
+ cell.
+ The final file (
+\family typewriter
+axialdisp-statevars_info.vtk
+\family default
+) gives the material properties used for the problem.
+ Since we have not specified which properties to write, the default properties
+ (
+\family typewriter
+mu
+\family default
+, 
+\family typewriter
+lambda
+\family default
+, 
+\family typewriter
+density
+\family default
+) are written.
+ All of the 
+\family typewriter
+.vtk
+\family default
+ files may be used with a number of visualization packages.
+ If the problem ran correctly, you should be able to generate a figure such
+ as Figure 
+\begin_inset CommandInset ref
+LatexCommand vref
+reference "fig:twotri3-axial"
+
+\end_inset
+
+, which was generated using ParaView.
+\end_layout
+
+\begin_layout Standard
+\noindent
+\align center
+\begin_inset Float figure
+wide false
+sideways false
+status open
+
+\begin_layout Plain Layout
+\align center
+\begin_inset Graphics
+	filename figs/axialdisp.jpg
+	lyxscale 50
+	scale 33
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Plain Layout
+\begin_inset Caption
+
+\begin_layout Plain Layout
+Color contours and vectors of displacement for the axial displacement example
+ using a mesh composed of two linear triangular cells.
+\begin_inset CommandInset label
+LatexCommand label
+name "fig:twotri3-axial"
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Subsection
+Shear Displacement Example
+\end_layout
+
+\begin_layout Standard
+The next example problem is shearing of the mesh in the y direction using
+ displacements applied along the positive and negative x boundaries.
+ Parameter settings that augment those in 
+\family typewriter
+pylithapp.cfg
+\family default
+ are contained in the file 
+\family typewriter
+sheardisp.cfg
+\family default
+.
+ These settings include:
+\end_layout
+
+\begin_layout Description
+pylithapp.timedependent.bc.x_neg Specifies the boundary conditions for the
+ left side of the mesh, defining which degrees of freedom are being constrained
+ (x and y), giving the label (
+\family typewriter
+x_neg
+\family default
+, defined in 
+\family typewriter
+twotri3.mesh
+\family default
+) defining the points desired, assigning a label to the boundary condition
+ set, and giving the name of the spatial database with the values for the
+ Dirichlet boundary condition (
+\family typewriter
+sheardisp.spatialdb
+\family default
+).
+\end_layout
+
+\begin_layout Description
+pylithapp.timedependent.bc.x_pos Specifies the boundary conditions for the
+ left side of the mesh, defining which degrees of freedom are being constrained
+ (y only), giving the label (
+\family typewriter
+x_
+\family default
+pos, defined in 
+\family typewriter
+twotri3.mesh
+\family default
+) defining the points desired, assigning a label to the boundary condition
+ set, and giving the name of the spatial database with the values for the
+ Dirichlet boundary condition (
+\family typewriter
+sheardisp.spatialdb
+\family default
+).
+\end_layout
+
+\begin_layout Standard
+The files containing common information (
+\family typewriter
+twotri3.mesh
+\family default
+, 
+\family typewriter
+pylithapp.cfg
+\family default
+, 
+\family typewriter
+matprops.spatialdb
+\family default
+) along with the problem-specific files (
+\family typewriter
+sheardisp.cfg
+\family default
+, 
+\family typewriter
+sheardisp.spatialdb
+\family default
+) provide a complete description of the problem, and we can then run this
+ example by typing
+\end_layout
+
+\begin_layout LyX-Code
+pylith sheardisp.cfg
+\end_layout
+
+\begin_layout Standard
+Once the problem has run, three files will be produced as in the previous
+ example.
+ If the problem ran correctly, you should be able to generate a figure such
+ as Figure 
+\begin_inset CommandInset ref
+LatexCommand vref
+reference "fig:twotri-shear"
+
+\end_inset
+
+, which was generated using ParaView.
+\end_layout
+
+\begin_layout Standard
+\noindent
+\align center
+\begin_inset Float figure
+wide false
+sideways false
+status open
+
+\begin_layout Plain Layout
+\align center
+\begin_inset Graphics
+	filename figs/sheardisp.jpg
+	lyxscale 50
+	scale 33
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Plain Layout
+\begin_inset Caption
+
+\begin_layout Plain Layout
+Color contours and vectors of displacement for the shear displacement example
+ using a mesh composed of two linear triangular cells.
+\begin_inset CommandInset label
+LatexCommand label
+name "fig:twotri-shear"
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Subsection
+Kinematic Fault Slip Example
+\end_layout
+
+\begin_layout Standard
+The next example problem is left-lateral fault slip applied between the
+ two triangular cells using kinematic cohesive cells.
+ The lower left and upper right boundaries are held fixed in the x and y
+ directions.
+ Parameter settings that augment those in 
+\family typewriter
+pylithapp.cfg
+\family default
+ are contained in the file 
+\family typewriter
+dislocation.cfg
+\family default
+.
+ The solution corresponds to rigid body rotation of each triangular cell.
+ As a result, the tractions on the fault are zero.
+ These settings include:
+\end_layout
+
+\begin_layout Description
+pylithapp.journal.info Turns on journaling for 1D quadrature (used for 2D
+ faults) and for cohesive kinematic faults.
+\end_layout
+
+\begin_layout Description
+pylithapp.timedependent.bc.bc Defines which degrees of freedom are being constraine
+d (x and y), gives the label (defined in 
+\family typewriter
+twotri3.mesh
+\family default
+) defining the points desired, and assigns a label to the boundary condition
+ set.
+ In this case, rather than specifying a spatial database file with the values
+ for the Dirichlet boundary condition, the default database (ZeroDispDB)
+ for Dirichlet boundary conditions is used, which sets the displacements
+ to zero.
+\end_layout
+
+\begin_layout Description
+pylithapp.timedependent.interfaces Gives the label (defined in 
+\family typewriter
+twotri3.mesh
+\family default
+) defining the points on the fault, provides quadrature information, and
+ then gives database names for material properties (needed for conditioning),
+ fault slip, peak fault slip rate, and fault slip time.
+\end_layout
+
+\begin_layout Description
+pylithapp.timedependent.interfaces.fault.output.writer Gives the base filename
+ for cohesive cell output files (
+\family typewriter
+dislocation-fault.vtk
+\family default
+).
+\end_layout
+
+\begin_layout Standard
+Rather than specifying the displacement boundary conditions in a spatial
+ database file, we use the default behavior for Dirichlet boundary conditions,
+ which is a uniform, constant displacement of zero.
+\end_layout
+
+\begin_layout Standard
+The fault example requires three additional database files that were not
+ needed for the simple displacement examples.
+ The first file (
+\family typewriter
+dislocation_slip.spatialdb
+\family default
+) specifies 0.01 m of left-lateral fault slip for the entire fault.
+ The data dimension is zero since the same data are applied to all points
+ in the set.
+ The default slip time function is a step-function, so we also must provide
+ the time at which slip begins.
+ The elastic solution is associated with advancing from 
+\begin_inset Formula $t=-dt$
+\end_inset
+
+ to 
+\begin_inset Formula $t=0$
+\end_inset
+
+, so we set the slip initiation time for the step-function to 0 in 
+\family typewriter
+dislocation_sliptime.spatialdb
+\family default
+.
+\end_layout
+
+\begin_layout Standard
+The files containing common information (
+\family typewriter
+twotri3.mesh
+\family default
+, 
+\family typewriter
+pylithapp.cfg
+\family default
+, 
+\family typewriter
+matprops.spatialdb
+\family default
+) along with the problem-specific files (
+\family typewriter
+\size small
+dislocation.cfg
+\family default
+, 
+\family typewriter
+dislocation_slip.spatialdb
+\family default
+, 
+\family typewriter
+dislocation_sliptime.spatialdb
+\family default
+\size default
+) provide a complete description of the problem, and we can then run this
+ example by typing
+\end_layout
+
+\begin_layout LyX-Code
+pylith dislocation.cfg
+\end_layout
+
+\begin_layout Standard
+Once the problem has run, five files are produced.
+ In addition to the files produced in the previous two examples, this example
+ produces two files associated with the fault interface.
+ The file 
+\family typewriter
+dislocation-fault_t0000000.vtk
+\family default
+ gives the fault slip for each vertex on the fault along with the computed
+ traction change for the cohesive cell.
+ The file 
+\family typewriter
+dislocation-fault_info.vtk
+\family default
+ provides information such as the normal direction, final slip, and slip
+ time for each vertex on the fault.
+ If the problem ran correctly, you should be able to generate a figure such
+ as Figure 
+\begin_inset CommandInset ref
+LatexCommand vref
+reference "fig:twotri-disloc"
+
+\end_inset
+
+, which was generated using ParaView.
+\end_layout
+
+\begin_layout Standard
+\noindent
+\align center
+\begin_inset Float figure
+wide false
+sideways false
+status open
+
+\begin_layout Plain Layout
+\align center
+\begin_inset Graphics
+	filename figs/dislocation.jpg
+	lyxscale 50
+	scale 33
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Plain Layout
+\begin_inset Caption
+
+\begin_layout Plain Layout
+Color contours and vectors of displacement for the kinematic fault example
+ using a mesh composed of two linear triangular cells.
+\begin_inset CommandInset label
+LatexCommand label
+name "fig:twotri-disloc"
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\end_body
+\end_document

Modified: short/3D/PyLith/branches/v1.7-trunk/doc/userguide/userguide.lyx
===================================================================
--- short/3D/PyLith/branches/v1.7-trunk/doc/userguide/userguide.lyx	2012-06-25 04:52:47 UTC (rev 20403)
+++ short/3D/PyLith/branches/v1.7-trunk/doc/userguide/userguide.lyx	2012-06-25 16:38:44 UTC (rev 20404)
@@ -1,886 +1,886 @@
-#LyX 2.0 created this file. For more info see http://www.lyx.org/
-\lyxformat 413
-\begin_document
-\begin_header
-\textclass book
-\begin_preamble
-%\usepackage{hyperref}
-
-%\let\myUrl\url
-%\renewcommand{\url}[1]{(\myUrl{#1})}
-%\newcommand\Prefix[3]{\vphantom{#3}#1#2#3}
-\end_preamble
-\use_default_options false
-\maintain_unincluded_children false
-\language english
-\language_package default
-\inputencoding latin1
-\fontencoding T1
-\font_roman times
-\font_sans helvet
-\font_typewriter courier
-\font_default_family default
-\use_non_tex_fonts false
-\font_sc false
-\font_osf false
-\font_sf_scale 100
-\font_tt_scale 100
-
-\graphics default
-\default_output_format default
-\output_sync 0
-\bibtex_command default
-\index_command default
-\float_placement tbph
-\paperfontsize default
-\spacing single
-\use_hyperref true
-\pdf_bookmarks true
-\pdf_bookmarksnumbered false
-\pdf_bookmarksopen false
-\pdf_bookmarksopenlevel 1
-\pdf_breaklinks true
-\pdf_pdfborder true
-\pdf_colorlinks true
-\pdf_backref false
-\pdf_pdfusetitle true
-\papersize default
-\use_geometry true
-\use_amsmath 1
-\use_esint 0
-\use_mhchem 1
-\use_mathdots 1
-\cite_engine basic
-\use_bibtopic false
-\use_indices false
-\paperorientation portrait
-\suppress_date false
-\use_refstyle 0
-\index Index
-\shortcut idx
-\color #008000
-\end_index
-\leftmargin 1in
-\topmargin 1in
-\rightmargin 1in
-\bottommargin 1in
-\secnumdepth 3
-\tocdepth 3
-\paragraph_separation indent
-\paragraph_indentation default
-\quotes_language english
-\papercolumns 1
-\papersides 2
-\paperpagestyle plain
-\tracking_changes false
-\output_changes false
-\html_math_output 0
-\html_css_as_file 0
-\html_be_strict false
-\end_header
-
-\begin_body
-
-\begin_layout Standard
-\noindent
-\align center
-\begin_inset Float figure
-placement H
-wide false
-sideways false
-status open
-
-\begin_layout Plain Layout
-\noindent
-\align center
-\begin_inset Graphics
-	filename cover/cover.pdf
-	width 75page%
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-\begin_inset ERT
-status open
-
-\begin_layout Plain Layout
-
-
-\backslash
-thispagestyle{empty}
-\end_layout
-
-\begin_layout Plain Layout
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Title
-PyLith User Manual
-\end_layout
-
-\begin_layout Author
-© University of California, Davis
-\begin_inset Newline newline
-\end_inset
-
-Version 1.7.1
-\end_layout
-
-\begin_layout Date
-\noindent
-\begin_inset ERT
-status collapsed
-
-\begin_layout Plain Layout
-
-
-\backslash
-today
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-\begin_inset ERT
-status open
-
-\begin_layout Plain Layout
-
-
-\backslash
-frontmatter
-\end_layout
-
-\end_inset
-
-
-\begin_inset CommandInset toc
-LatexCommand tableofcontents
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-\begin_inset FloatList figure
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-\begin_inset FloatList table
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-\begin_inset CommandInset include
-LatexCommand input
-filename "preface.lyx"
-
-\end_inset
-
-
-\begin_inset ERT
-status collapsed
-
-\begin_layout Plain Layout
-
-
-\backslash
-mainmatter
-\end_layout
-
-\end_inset
-
-
-\begin_inset ERT
-status collapsed
-
-\begin_layout Plain Layout
-
-
-\backslash
-raggedbottom
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-\begin_inset CommandInset include
-LatexCommand input
-filename "intro/intro.lyx"
-
-\end_inset
-
-
-\begin_inset CommandInset include
-LatexCommand input
-filename "governingeqns/governingeqns.lyx"
-
-\end_inset
-
-
-\begin_inset CommandInset include
-LatexCommand input
-filename "install/install.lyx"
-
-\end_inset
-
-
-\begin_inset CommandInset include
-LatexCommand input
-filename "runpylith/runpylith.lyx"
-
-\end_inset
-
-
-\begin_inset CommandInset include
-LatexCommand input
-filename "materials/materials.lyx"
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-\begin_inset CommandInset include
-LatexCommand input
-filename "boundaryconditions/boundaryconditions.lyx"
-
-\end_inset
-
- 
-\begin_inset CommandInset include
-LatexCommand input
-filename "tutorials/tutorials.lyx"
-
-\end_inset
-
-
-\begin_inset CommandInset include
-LatexCommand input
-filename "benchmarks/benchmarks.lyx"
-
-\end_inset
-
-
-\begin_inset CommandInset include
-LatexCommand input
-filename "extending/extending.lyx"
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-\start_of_appendix
-\begin_inset ERT
-status collapsed
-
-\begin_layout Plain Layout
-
-%dummy comment inserted by tex2lyx to ensure that this paragraph is not
- empty
-\end_layout
-
-\begin_layout Plain Layout
-
-\end_layout
-
-\end_inset
-
-
-\begin_inset CommandInset include
-LatexCommand input
-filename "glossary.lyx"
-
-\end_inset
-
-
-\begin_inset CommandInset include
-LatexCommand input
-filename "components.lyx"
-
-\end_inset
-
-
-\begin_inset CommandInset include
-LatexCommand input
-filename "fileformats/fileformats.lyx"
-
-\end_inset
-
-
-\begin_inset CommandInset include
-LatexCommand include
-filename "materials/altformulations.lyx"
-
-\end_inset
-
-
-\begin_inset CommandInset include
-LatexCommand input
-filename "analyticalsolns/analyticalsolns.lyx"
-
-\end_inset
-
-
-\begin_inset CommandInset include
-LatexCommand input
-filename "license.lyx"
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Bibliography
-\labelwidthstring Bibliography
-\begin_inset CommandInset bibitem
-LatexCommand bibitem
-label "Aagaard et al., 2001a"
-key "Aagaard:etal:2001a"
-
-\end_inset
-
-Aagaard, B.T., J.F.
- Hall, and T.H.
- Heaton (2001), Characterization of near-source ground motions with earthquake
- simulations, 
-\emph on
-Earthquake Spectra, 17
-\emph default
-(2), 177-207.
-\end_layout
-
-\begin_layout Bibliography
-\labelwidthstring Bibliography
-\begin_inset CommandInset bibitem
-LatexCommand bibitem
-label "Aagaard et al., 2001b"
-key "Aagaard:etal:2001b"
-
-\end_inset
-
-Aagaard, B.T., T.H.
- Heaton, and J.F.
- Hall (2001), Dynamic earthquake ruptures in the presence of lithostatic
- normal stresses: Implications for friction models and heat production,
- 
-\emph on
-Bulletin of the Seismological Society of America, 91
-\emph default
-(6), 1765-1796.
-\end_layout
-
-\begin_layout Bibliography
-\labelwidthstring Bibliography
-\begin_inset CommandInset bibitem
-LatexCommand bibitem
-label "Aagaard et al., 2007"
-key "Aagaard:etal:2007"
-
-\end_inset
-
-Aagaard, B., C.
- Williams, and M.
- Knepley (2007), PyLith: A finite-element code for modeling quasi-static
- and dynamic crustal deformation, 
-\emph on
-Eos Trans.
- AGU, 88
-\emph default
-(52), Fall Meet.
- Suppl., Abstract T21B-0592.
-\end_layout
-
-\begin_layout Bibliography
-\labelwidthstring Bibliography
-\begin_inset CommandInset bibitem
-LatexCommand bibitem
-label "Aagaard et al., 2008"
-key "Aagaard:etal:2008"
-
-\end_inset
-
-Aagaard, B., C.
- Williams, and M.
- Knepley (2008), PyLith: A finite-element code for modeling quasi-static
- and dynamic crustal deformation, 
-\emph on
-Eos Trans.
- AGU
-\emph default
-, 
-\emph on
-89(
-\emph default
-53), Fall Meet.
- Suppl., Abstract T41A-1925.
-\end_layout
-
-\begin_layout Bibliography
-\labelwidthstring Bibliography
-\begin_inset CommandInset bibitem
-LatexCommand bibitem
-label "Bathe, 1995"
-key "Bathe:1995"
-
-\end_inset
-
-Bathe, K.-J.
- (1995), 
-\shape italic
-Finite-Element Procedures
-\shape default
-, Prentice Hall, Upper Saddle River, New Jersey, 1037 pp.
-\end_layout
-
-\begin_layout Bibliography
-\labelwidthstring Bibliography
-\begin_inset CommandInset bibitem
-LatexCommand bibitem
-label "Ben-Zion and Rice, 1997"
-key "BenZion:Rice:1997"
-
-\end_inset
-
-Ben-Zion, Y.
- and J.R.
- Rice (1997), Dynamic simulations of slip on a smooth fault in an elastic
- solid, J.
- Geophys.
- Res., 102, 17,771–17,784.
-\end_layout
-
-\begin_layout Bibliography
-\labelwidthstring Bibliography
-\begin_inset CommandInset bibitem
-LatexCommand bibitem
-label "Brune, 1970"
-key "Brune:1970"
-
-\end_inset
-
-Brune, J.N.
- (1970), Tectonic stress and spectra of seismic shear waves from earthquakes,
- 
-\emph on
-Journal of Geophysical Research, 75
-\emph default
-, 4997-5009.
-\end_layout
-
-\begin_layout Bibliography
-\labelwidthstring Bibliography
-\begin_inset CommandInset bibitem
-LatexCommand bibitem
-label "Day and Ely, 2002"
-key "Day:Ely:2002"
-
-\end_inset
-
-Day, S.M.
- and G.P.
- Ely (2002), Effct of a shallow weak zone on fault rupture: Numerical simulation
- of scale-model experiments, 
-\shape italic
-Bull.
- Seismol.
- Soc.
- Am.
-\shape default
-, 92(8), 3022-3041, doi: 10.1785/0120010273.
-\end_layout
-
-\begin_layout Bibliography
-\labelwidthstring Bibliography
-\begin_inset CommandInset bibitem
-LatexCommand bibitem
-label "Drucker and Prager, 1952"
-key "Drucker:Prager:1952"
-
-\end_inset
-
-Drucker, D.
- C.
- and Prager, W.
- (1952).
- Soil mechanics and plastic analysis for limit design, 
-\shape italic
-Quarterly of Applied Mathematics
-\shape default
-, 
-\shape italic
-10
-\shape default
-, 157–165.
-\end_layout
-
-\begin_layout Bibliography
-\labelwidthstring Bibliography
-\begin_inset CommandInset bibitem
-LatexCommand bibitem
-label "Liu et al., 2006"
-key "Liu:etal:2006"
-
-\end_inset
-
-Liu, P., R.J.
- Archuleta, S.H.
- Hartzell (2006), Prediction of broadband ground-motion time histories:
- Hybrid low/high-frequency method with correlated random source parameters,
- 
-\shape italic
-Bull.
- Seismol.
- Soc.
- Am.
-\shape default
-, 96, 2118-2130.
-\end_layout
-
-\begin_layout Bibliography
-\labelwidthstring Bibliography
-\begin_inset CommandInset bibitem
-LatexCommand bibitem
-label "Kaneko et al., 2008"
-key "Kaneko:etal:2008"
-
-\end_inset
-
-Kaneko, Y., N.
- Lapusta, and J.-P.
- Ampuero (2008), Spectral element modeling of spontaneous earthquake rupture
- on rate and state faults: Effect of velocity-strengthening friction at
- shallow depths, 
-\shape italic
-Journal of Geophysical Research
-\shape default
-, 113, B09317, doi:10.1029/2007JB005553.
-\end_layout
-
-\begin_layout Bibliography
-\labelwidthstring Bibliography
-\begin_inset CommandInset bibitem
-LatexCommand bibitem
-label "Kirby and Kronenberg, 1987"
-key "Kirby:Kronenberg:1987"
-
-\end_inset
-
-Kirby, S.
- H.
- and A.
- K.
- Kronenberg (1987), Rheology of the lithosphere: Selected topics, 
-\shape italic
-Reviews of Geophysics, 25
-\shape default
-, 1219-1244.
-\end_layout
-
-\begin_layout Bibliography
-\labelwidthstring Bibliography
-\begin_inset CommandInset bibitem
-LatexCommand bibitem
-label "Knopoff and Ni, 2001"
-key "Knopoff:Ni:2001"
-
-\end_inset
-
-Knopoff, L.
- and X.X.
- Ni (2001), Numerical instability at the edge of a dynamic fracture, 
-\emph on
-Geophysical Journal International, 
-\emph default
-147(3), 1-6, doi: 10.1046/j.1365-246x.2001.01567.x.
-\end_layout
-
-\begin_layout Bibliography
-\labelwidthstring Bibliography
-\begin_inset CommandInset bibitem
-LatexCommand bibitem
-label "Kojic and Bathe, 1987"
-key "Kojic:Bathe:1987"
-
-\end_inset
-
-Kojic, M.
- and K.-J.
- Bathe (1987), The `Effective Stress-Function' Algorithm for Thermo-Elasto-Plast
-icity and Creep, 
-\emph on
-Int.
- J.
- Num.
- Meth.
- Eng
-\emph default
-.
-\emph on
-, 24
-\emph default
-, 1509-1532.
-\end_layout
-
-\begin_layout Bibliography
-\labelwidthstring Bibliography
-\begin_inset CommandInset bibitem
-LatexCommand bibitem
-label "McGarr, 1988"
-key "McGarr:1988"
-
-\end_inset
-
-McGarr, A.
- (1988), On the state of lithospheric stress in the absence of applied tectonic
- forces, 
-\shape italic
-Journal of Geophysical Research
-\shape default
-, 
-\shape italic
-93
-\shape default
-, 13,609-13,617.
-\end_layout
-
-\begin_layout Bibliography
-\labelwidthstring Bibliography
-\begin_inset CommandInset bibitem
-LatexCommand bibitem
-label "Menke, 1984"
-key "Menke:1984"
-
-\end_inset
-
-Menke, W.
- (1984), 
-\shape italic
-Geophysical Data Analysis: Discrete Inverse Theory
-\shape default
-, Academic Press, Inc., Orlando, 260 pp.
-\end_layout
-
-\begin_layout Bibliography
-\labelwidthstring Bibliography
-\begin_inset CommandInset bibitem
-LatexCommand bibitem
-label "Okada, 1992"
-key "Okada:1992"
-
-\end_inset
-
-Okada, Y., Internal deformation due to shear and tensile faults in a half-space
- (1992), 
-\shape italic
-Bull.
- Seismol.
- Soc.
- Am.
-\shape default
-, 
-\shape italic
-83
-\shape default
-, 1018-1040.
-\end_layout
-
-\begin_layout Bibliography
-\labelwidthstring Bibliography
-\begin_inset CommandInset bibitem
-LatexCommand bibitem
-label "Paterson, 1994"
-key "Paterson:1994"
-
-\end_inset
-
-Paterson, W.
- S.
- B.
- (1994), 
-\shape italic
-The Physics of Glaciers, Third Edition
-\shape default
-, Elsevier Science Ltd., Oxford, 480 pp.
-\end_layout
-
-\begin_layout Bibliography
-\labelwidthstring Bibliography
-\begin_inset CommandInset bibitem
-LatexCommand bibitem
-label "Prentice, 1968"
-key "Prentice:1968"
-
-\end_inset
-
-Prentice, J.
- H, (1968), Dimensional problem of the power law in rheology, 
-\shape italic
-Nature
-\shape default
-, 
-\shape italic
-217
-\shape default
-, 157.
-\end_layout
-
-\begin_layout Bibliography
-\labelwidthstring Bibliography
-\begin_inset CommandInset bibitem
-LatexCommand bibitem
-label "Savage and Prescott, 1978"
-key "Savage:Prescott:1978"
-
-\end_inset
-
-Savage, J.
- C.
- and W.
- H.
- Prescott (1978), Asthenosphere readjustment and the earthquake cycle, 
-\shape italic
-Journal of Geophysical
-\shape default
- 
-\shape italic
-Research
-\shape default
-\emph on
-, 83
-\emph default
-, 3369-3376.
-\end_layout
-
-\begin_layout Bibliography
-\labelwidthstring Bibliography
-\begin_inset CommandInset bibitem
-LatexCommand bibitem
-label "Taylor, 2003"
-key "Taylor:2003"
-
-\end_inset
-
-Taylor, R.L.
- (2003), `FEAP--A Finite Element Analysis Program', 
-\shape italic
-Version 7.5 Theory Manual
-\shape default
-, 154 pp.
-\end_layout
-
-\begin_layout Bibliography
-\labelwidthstring Bibliography
-\begin_inset CommandInset bibitem
-LatexCommand bibitem
-label "Timoshenko and Goodier, 1987"
-key "Timoshenko:Goodier:1987"
-
-\end_inset
-
-Timoshenko, S.P.
- and J.N.
- Goodier (1987), 
-\shape italic
-Theory of Elasticity, Third Edition
-\shape default
-, McGraw-Hill, New York, 567 pp.
-\end_layout
-
-\begin_layout Bibliography
-\labelwidthstring Bibliography
-\begin_inset CommandInset bibitem
-LatexCommand bibitem
-label "Williams et al., 2005"
-key "Williams:etal:2005"
-
-\end_inset
-
-Williams, C.A., B.
- Aagaard, and M.G.
- Knepley (2005), Development of software for studying earthquakes across
- multiple spatial and temporal scales by coupling quasi-static and dynamic
- simulations, 
-\emph on
-Eos Trans.
- AGU, 86
-\emph default
-(52), Fall Meet.
- Suppl., Abstract S53A-1072.
-\end_layout
-
-\begin_layout Bibliography
-\labelwidthstring Bibliography
-\begin_inset CommandInset bibitem
-LatexCommand bibitem
-label "Williams, 2006"
-key "Williams:2006"
-
-\end_inset
-
-Williams, C.A.
- (2006), Development of a package for modeling stress in the lithosphere,
- 
-\emph on
-Eos Trans.
- AGU,
-\emph default
- 
-\emph on
-87
-\emph default
-(36), Jt.
- Assem.
- Suppl., Abstract T24A-01 Invited.
-\end_layout
-
-\begin_layout Bibliography
-\labelwidthstring Bibliography
-\begin_inset CommandInset bibitem
-LatexCommand bibitem
-label "Zienkiewicz and Taylor, 2000"
-key "Zienkiewicz:Taylor:2000"
-
-\end_inset
-
-Zienkiewicz, O.C.
- and R.L.
- Taylor (2000), 
-\shape italic
-The Finite Element Method, Fifth Edition, Volume 2: Solid Mechanics
-\shape default
-, Butterworth-Heinemann, Oxford, 459 pp.125
-\end_layout
-
-\end_body
-\end_document
+#LyX 2.0 created this file. For more info see http://www.lyx.org/
+\lyxformat 413
+\begin_document
+\begin_header
+\textclass book
+\begin_preamble
+%\usepackage{hyperref}
+
+%\let\myUrl\url
+%\renewcommand{\url}[1]{(\myUrl{#1})}
+%\newcommand\Prefix[3]{\vphantom{#3}#1#2#3}
+\end_preamble
+\use_default_options false
+\maintain_unincluded_children false
+\language english
+\language_package default
+\inputencoding latin1
+\fontencoding T1
+\font_roman times
+\font_sans helvet
+\font_typewriter courier
+\font_default_family default
+\use_non_tex_fonts false
+\font_sc false
+\font_osf false
+\font_sf_scale 100
+\font_tt_scale 100
+
+\graphics default
+\default_output_format default
+\output_sync 0
+\bibtex_command default
+\index_command default
+\float_placement tbph
+\paperfontsize default
+\spacing single
+\use_hyperref true
+\pdf_bookmarks true
+\pdf_bookmarksnumbered false
+\pdf_bookmarksopen false
+\pdf_bookmarksopenlevel 1
+\pdf_breaklinks true
+\pdf_pdfborder true
+\pdf_colorlinks true
+\pdf_backref false
+\pdf_pdfusetitle true
+\papersize default
+\use_geometry true
+\use_amsmath 1
+\use_esint 0
+\use_mhchem 1
+\use_mathdots 1
+\cite_engine basic
+\use_bibtopic false
+\use_indices false
+\paperorientation portrait
+\suppress_date false
+\use_refstyle 0
+\index Index
+\shortcut idx
+\color #008000
+\end_index
+\leftmargin 1in
+\topmargin 1in
+\rightmargin 1in
+\bottommargin 1in
+\secnumdepth 3
+\tocdepth 3
+\paragraph_separation indent
+\paragraph_indentation default
+\quotes_language english
+\papercolumns 1
+\papersides 2
+\paperpagestyle plain
+\tracking_changes false
+\output_changes false
+\html_math_output 0
+\html_css_as_file 0
+\html_be_strict false
+\end_header
+
+\begin_body
+
+\begin_layout Standard
+\noindent
+\align center
+\begin_inset Float figure
+placement H
+wide false
+sideways false
+status open
+
+\begin_layout Plain Layout
+\noindent
+\align center
+\begin_inset Graphics
+	filename cover/cover.pdf
+	width 75page%
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+\begin_inset ERT
+status open
+
+\begin_layout Plain Layout
+
+
+\backslash
+thispagestyle{empty}
+\end_layout
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Title
+PyLith User Manual
+\end_layout
+
+\begin_layout Author
+© University of California, Davis
+\begin_inset Newline newline
+\end_inset
+
+Version 1.7.1
+\end_layout
+
+\begin_layout Date
+\noindent
+\begin_inset ERT
+status collapsed
+
+\begin_layout Plain Layout
+
+
+\backslash
+today
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+\begin_inset ERT
+status open
+
+\begin_layout Plain Layout
+
+
+\backslash
+frontmatter
+\end_layout
+
+\end_inset
+
+
+\begin_inset CommandInset toc
+LatexCommand tableofcontents
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+\begin_inset FloatList figure
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+\begin_inset FloatList table
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+\begin_inset CommandInset include
+LatexCommand input
+filename "preface.lyx"
+
+\end_inset
+
+
+\begin_inset ERT
+status collapsed
+
+\begin_layout Plain Layout
+
+
+\backslash
+mainmatter
+\end_layout
+
+\end_inset
+
+
+\begin_inset ERT
+status collapsed
+
+\begin_layout Plain Layout
+
+
+\backslash
+raggedbottom
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+\begin_inset CommandInset include
+LatexCommand input
+filename "intro/intro.lyx"
+
+\end_inset
+
+
+\begin_inset CommandInset include
+LatexCommand input
+filename "governingeqns/governingeqns.lyx"
+
+\end_inset
+
+
+\begin_inset CommandInset include
+LatexCommand input
+filename "install/install.lyx"
+
+\end_inset
+
+
+\begin_inset CommandInset include
+LatexCommand input
+filename "runpylith/runpylith.lyx"
+
+\end_inset
+
+
+\begin_inset CommandInset include
+LatexCommand input
+filename "materials/materials.lyx"
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+\begin_inset CommandInset include
+LatexCommand input
+filename "boundaryconditions/boundaryconditions.lyx"
+
+\end_inset
+
+ 
+\begin_inset CommandInset include
+LatexCommand input
+filename "tutorials/tutorials.lyx"
+
+\end_inset
+
+
+\begin_inset CommandInset include
+LatexCommand input
+filename "benchmarks/benchmarks.lyx"
+
+\end_inset
+
+
+\begin_inset CommandInset include
+LatexCommand input
+filename "extending/extending.lyx"
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+\start_of_appendix
+\begin_inset ERT
+status collapsed
+
+\begin_layout Plain Layout
+
+%dummy comment inserted by tex2lyx to ensure that this paragraph is not
+ empty
+\end_layout
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\end_inset
+
+
+\begin_inset CommandInset include
+LatexCommand input
+filename "glossary.lyx"
+
+\end_inset
+
+
+\begin_inset CommandInset include
+LatexCommand input
+filename "components.lyx"
+
+\end_inset
+
+
+\begin_inset CommandInset include
+LatexCommand input
+filename "fileformats/fileformats.lyx"
+
+\end_inset
+
+
+\begin_inset CommandInset include
+LatexCommand include
+filename "materials/altformulations.lyx"
+
+\end_inset
+
+
+\begin_inset CommandInset include
+LatexCommand input
+filename "analyticalsolns/analyticalsolns.lyx"
+
+\end_inset
+
+
+\begin_inset CommandInset include
+LatexCommand input
+filename "license.lyx"
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Bibliography
+\labelwidthstring Bibliography
+\begin_inset CommandInset bibitem
+LatexCommand bibitem
+label "Aagaard et al., 2001a"
+key "Aagaard:etal:2001a"
+
+\end_inset
+
+Aagaard, B.T., J.F.
+ Hall, and T.H.
+ Heaton (2001), Characterization of near-source ground motions with earthquake
+ simulations, 
+\emph on
+Earthquake Spectra, 17
+\emph default
+(2), 177-207.
+\end_layout
+
+\begin_layout Bibliography
+\labelwidthstring Bibliography
+\begin_inset CommandInset bibitem
+LatexCommand bibitem
+label "Aagaard et al., 2001b"
+key "Aagaard:etal:2001b"
+
+\end_inset
+
+Aagaard, B.T., T.H.
+ Heaton, and J.F.
+ Hall (2001), Dynamic earthquake ruptures in the presence of lithostatic
+ normal stresses: Implications for friction models and heat production,
+ 
+\emph on
+Bulletin of the Seismological Society of America, 91
+\emph default
+(6), 1765-1796.
+\end_layout
+
+\begin_layout Bibliography
+\labelwidthstring Bibliography
+\begin_inset CommandInset bibitem
+LatexCommand bibitem
+label "Aagaard et al., 2007"
+key "Aagaard:etal:2007"
+
+\end_inset
+
+Aagaard, B., C.
+ Williams, and M.
+ Knepley (2007), PyLith: A finite-element code for modeling quasi-static
+ and dynamic crustal deformation, 
+\emph on
+Eos Trans.
+ AGU, 88
+\emph default
+(52), Fall Meet.
+ Suppl., Abstract T21B-0592.
+\end_layout
+
+\begin_layout Bibliography
+\labelwidthstring Bibliography
+\begin_inset CommandInset bibitem
+LatexCommand bibitem
+label "Aagaard et al., 2008"
+key "Aagaard:etal:2008"
+
+\end_inset
+
+Aagaard, B., C.
+ Williams, and M.
+ Knepley (2008), PyLith: A finite-element code for modeling quasi-static
+ and dynamic crustal deformation, 
+\emph on
+Eos Trans.
+ AGU
+\emph default
+, 
+\emph on
+89(
+\emph default
+53), Fall Meet.
+ Suppl., Abstract T41A-1925.
+\end_layout
+
+\begin_layout Bibliography
+\labelwidthstring Bibliography
+\begin_inset CommandInset bibitem
+LatexCommand bibitem
+label "Bathe, 1995"
+key "Bathe:1995"
+
+\end_inset
+
+Bathe, K.-J.
+ (1995), 
+\shape italic
+Finite-Element Procedures
+\shape default
+, Prentice Hall, Upper Saddle River, New Jersey, 1037 pp.
+\end_layout
+
+\begin_layout Bibliography
+\labelwidthstring Bibliography
+\begin_inset CommandInset bibitem
+LatexCommand bibitem
+label "Ben-Zion and Rice, 1997"
+key "BenZion:Rice:1997"
+
+\end_inset
+
+Ben-Zion, Y.
+ and J.R.
+ Rice (1997), Dynamic simulations of slip on a smooth fault in an elastic
+ solid, J.
+ Geophys.
+ Res., 102, 17,771–17,784.
+\end_layout
+
+\begin_layout Bibliography
+\labelwidthstring Bibliography
+\begin_inset CommandInset bibitem
+LatexCommand bibitem
+label "Brune, 1970"
+key "Brune:1970"
+
+\end_inset
+
+Brune, J.N.
+ (1970), Tectonic stress and spectra of seismic shear waves from earthquakes,
+ 
+\emph on
+Journal of Geophysical Research, 75
+\emph default
+, 4997-5009.
+\end_layout
+
+\begin_layout Bibliography
+\labelwidthstring Bibliography
+\begin_inset CommandInset bibitem
+LatexCommand bibitem
+label "Day and Ely, 2002"
+key "Day:Ely:2002"
+
+\end_inset
+
+Day, S.M.
+ and G.P.
+ Ely (2002), Effct of a shallow weak zone on fault rupture: Numerical simulation
+ of scale-model experiments, 
+\shape italic
+Bull.
+ Seismol.
+ Soc.
+ Am.
+\shape default
+, 92(8), 3022-3041, doi: 10.1785/0120010273.
+\end_layout
+
+\begin_layout Bibliography
+\labelwidthstring Bibliography
+\begin_inset CommandInset bibitem
+LatexCommand bibitem
+label "Drucker and Prager, 1952"
+key "Drucker:Prager:1952"
+
+\end_inset
+
+Drucker, D.
+ C.
+ and Prager, W.
+ (1952).
+ Soil mechanics and plastic analysis for limit design, 
+\shape italic
+Quarterly of Applied Mathematics
+\shape default
+, 
+\shape italic
+10
+\shape default
+, 157–165.
+\end_layout
+
+\begin_layout Bibliography
+\labelwidthstring Bibliography
+\begin_inset CommandInset bibitem
+LatexCommand bibitem
+label "Liu et al., 2006"
+key "Liu:etal:2006"
+
+\end_inset
+
+Liu, P., R.J.
+ Archuleta, S.H.
+ Hartzell (2006), Prediction of broadband ground-motion time histories:
+ Hybrid low/high-frequency method with correlated random source parameters,
+ 
+\shape italic
+Bull.
+ Seismol.
+ Soc.
+ Am.
+\shape default
+, 96, 2118-2130.
+\end_layout
+
+\begin_layout Bibliography
+\labelwidthstring Bibliography
+\begin_inset CommandInset bibitem
+LatexCommand bibitem
+label "Kaneko et al., 2008"
+key "Kaneko:etal:2008"
+
+\end_inset
+
+Kaneko, Y., N.
+ Lapusta, and J.-P.
+ Ampuero (2008), Spectral element modeling of spontaneous earthquake rupture
+ on rate and state faults: Effect of velocity-strengthening friction at
+ shallow depths, 
+\shape italic
+Journal of Geophysical Research
+\shape default
+, 113, B09317, doi:10.1029/2007JB005553.
+\end_layout
+
+\begin_layout Bibliography
+\labelwidthstring Bibliography
+\begin_inset CommandInset bibitem
+LatexCommand bibitem
+label "Kirby and Kronenberg, 1987"
+key "Kirby:Kronenberg:1987"
+
+\end_inset
+
+Kirby, S.
+ H.
+ and A.
+ K.
+ Kronenberg (1987), Rheology of the lithosphere: Selected topics, 
+\shape italic
+Reviews of Geophysics, 25
+\shape default
+, 1219-1244.
+\end_layout
+
+\begin_layout Bibliography
+\labelwidthstring Bibliography
+\begin_inset CommandInset bibitem
+LatexCommand bibitem
+label "Knopoff and Ni, 2001"
+key "Knopoff:Ni:2001"
+
+\end_inset
+
+Knopoff, L.
+ and X.X.
+ Ni (2001), Numerical instability at the edge of a dynamic fracture, 
+\emph on
+Geophysical Journal International, 
+\emph default
+147(3), 1-6, doi: 10.1046/j.1365-246x.2001.01567.x.
+\end_layout
+
+\begin_layout Bibliography
+\labelwidthstring Bibliography
+\begin_inset CommandInset bibitem
+LatexCommand bibitem
+label "Kojic and Bathe, 1987"
+key "Kojic:Bathe:1987"
+
+\end_inset
+
+Kojic, M.
+ and K.-J.
+ Bathe (1987), The `Effective Stress-Function' Algorithm for Thermo-Elasto-Plast
+icity and Creep, 
+\emph on
+Int.
+ J.
+ Num.
+ Meth.
+ Eng
+\emph default
+.
+\emph on
+, 24
+\emph default
+, 1509-1532.
+\end_layout
+
+\begin_layout Bibliography
+\labelwidthstring Bibliography
+\begin_inset CommandInset bibitem
+LatexCommand bibitem
+label "McGarr, 1988"
+key "McGarr:1988"
+
+\end_inset
+
+McGarr, A.
+ (1988), On the state of lithospheric stress in the absence of applied tectonic
+ forces, 
+\shape italic
+Journal of Geophysical Research
+\shape default
+, 
+\shape italic
+93
+\shape default
+, 13,609-13,617.
+\end_layout
+
+\begin_layout Bibliography
+\labelwidthstring Bibliography
+\begin_inset CommandInset bibitem
+LatexCommand bibitem
+label "Menke, 1984"
+key "Menke:1984"
+
+\end_inset
+
+Menke, W.
+ (1984), 
+\shape italic
+Geophysical Data Analysis: Discrete Inverse Theory
+\shape default
+, Academic Press, Inc., Orlando, 260 pp.
+\end_layout
+
+\begin_layout Bibliography
+\labelwidthstring Bibliography
+\begin_inset CommandInset bibitem
+LatexCommand bibitem
+label "Okada, 1992"
+key "Okada:1992"
+
+\end_inset
+
+Okada, Y., Internal deformation due to shear and tensile faults in a half-space
+ (1992), 
+\shape italic
+Bull.
+ Seismol.
+ Soc.
+ Am.
+\shape default
+, 
+\shape italic
+83
+\shape default
+, 1018-1040.
+\end_layout
+
+\begin_layout Bibliography
+\labelwidthstring Bibliography
+\begin_inset CommandInset bibitem
+LatexCommand bibitem
+label "Paterson, 1994"
+key "Paterson:1994"
+
+\end_inset
+
+Paterson, W.
+ S.
+ B.
+ (1994), 
+\shape italic
+The Physics of Glaciers, Third Edition
+\shape default
+, Elsevier Science Ltd., Oxford, 480 pp.
+\end_layout
+
+\begin_layout Bibliography
+\labelwidthstring Bibliography
+\begin_inset CommandInset bibitem
+LatexCommand bibitem
+label "Prentice, 1968"
+key "Prentice:1968"
+
+\end_inset
+
+Prentice, J.
+ H, (1968), Dimensional problem of the power law in rheology, 
+\shape italic
+Nature
+\shape default
+, 
+\shape italic
+217
+\shape default
+, 157.
+\end_layout
+
+\begin_layout Bibliography
+\labelwidthstring Bibliography
+\begin_inset CommandInset bibitem
+LatexCommand bibitem
+label "Savage and Prescott, 1978"
+key "Savage:Prescott:1978"
+
+\end_inset
+
+Savage, J.
+ C.
+ and W.
+ H.
+ Prescott (1978), Asthenosphere readjustment and the earthquake cycle, 
+\shape italic
+Journal of Geophysical
+\shape default
+ 
+\shape italic
+Research
+\shape default
+\emph on
+, 83
+\emph default
+, 3369-3376.
+\end_layout
+
+\begin_layout Bibliography
+\labelwidthstring Bibliography
+\begin_inset CommandInset bibitem
+LatexCommand bibitem
+label "Taylor, 2003"
+key "Taylor:2003"
+
+\end_inset
+
+Taylor, R.L.
+ (2003), `FEAP--A Finite Element Analysis Program', 
+\shape italic
+Version 7.5 Theory Manual
+\shape default
+, 154 pp.
+\end_layout
+
+\begin_layout Bibliography
+\labelwidthstring Bibliography
+\begin_inset CommandInset bibitem
+LatexCommand bibitem
+label "Timoshenko and Goodier, 1987"
+key "Timoshenko:Goodier:1987"
+
+\end_inset
+
+Timoshenko, S.P.
+ and J.N.
+ Goodier (1987), 
+\shape italic
+Theory of Elasticity, Third Edition
+\shape default
+, McGraw-Hill, New York, 567 pp.
+\end_layout
+
+\begin_layout Bibliography
+\labelwidthstring Bibliography
+\begin_inset CommandInset bibitem
+LatexCommand bibitem
+label "Williams et al., 2005"
+key "Williams:etal:2005"
+
+\end_inset
+
+Williams, C.A., B.
+ Aagaard, and M.G.
+ Knepley (2005), Development of software for studying earthquakes across
+ multiple spatial and temporal scales by coupling quasi-static and dynamic
+ simulations, 
+\emph on
+Eos Trans.
+ AGU, 86
+\emph default
+(52), Fall Meet.
+ Suppl., Abstract S53A-1072.
+\end_layout
+
+\begin_layout Bibliography
+\labelwidthstring Bibliography
+\begin_inset CommandInset bibitem
+LatexCommand bibitem
+label "Williams, 2006"
+key "Williams:2006"
+
+\end_inset
+
+Williams, C.A.
+ (2006), Development of a package for modeling stress in the lithosphere,
+ 
+\emph on
+Eos Trans.
+ AGU,
+\emph default
+ 
+\emph on
+87
+\emph default
+(36), Jt.
+ Assem.
+ Suppl., Abstract T24A-01 Invited.
+\end_layout
+
+\begin_layout Bibliography
+\labelwidthstring Bibliography
+\begin_inset CommandInset bibitem
+LatexCommand bibitem
+label "Zienkiewicz and Taylor, 2000"
+key "Zienkiewicz:Taylor:2000"
+
+\end_inset
+
+Zienkiewicz, O.C.
+ and R.L.
+ Taylor (2000), 
+\shape italic
+The Finite Element Method, Fifth Edition, Volume 2: Solid Mechanics
+\shape default
+, Butterworth-Heinemann, Oxford, 459 pp.125
+\end_layout
+
+\end_body
+\end_document

Modified: short/3D/PyLith/branches/v1.7-trunk/examples/2d/greensfns/strikeslip/greensfns.cfg
===================================================================
--- short/3D/PyLith/branches/v1.7-trunk/examples/2d/greensfns/strikeslip/greensfns.cfg	2012-06-25 04:52:47 UTC (rev 20403)
+++ short/3D/PyLith/branches/v1.7-trunk/examples/2d/greensfns/strikeslip/greensfns.cfg	2012-06-25 16:38:44 UTC (rev 20404)
@@ -64,6 +64,7 @@
 # Fault
 [greensfns.interfaces.fault.output]
 writer.filename = output/greensfns-fault.h5
+vertex_info_fields = [area]
 
 # Materials
 [greensfns.materials.elastic.output]

Modified: short/3D/PyLith/branches/v1.7-trunk/examples/3d/hex8/step05.cfg
===================================================================
--- short/3D/PyLith/branches/v1.7-trunk/examples/3d/hex8/step05.cfg	2012-06-25 04:52:47 UTC (rev 20403)
+++ short/3D/PyLith/branches/v1.7-trunk/examples/3d/hex8/step05.cfg	2012-06-25 16:38:44 UTC (rev 20404)
@@ -106,7 +106,7 @@
 quadrature.cell.dimension = 2
 quadrature.cell.quad_order = 2
 
-# Fist specify a UniformDB for the initial tractions, along with the values.
+# First specify a UniformDB for the initial tractions, along with the values.
 db_initial = spatialdata.spatialdb.UniformDB
 db_initial.label = Neumann BC on +x
 db_initial.values = [traction-shear-horiz,traction-shear-vert,traction-normal]

Modified: short/3D/PyLith/branches/v1.7-trunk/examples/meshing/surface_nurbs/triangles/mkfacets.py
===================================================================
--- short/3D/PyLith/branches/v1.7-trunk/examples/meshing/surface_nurbs/triangles/mkfacets.py	2012-06-25 04:52:47 UTC (rev 20403)
+++ short/3D/PyLith/branches/v1.7-trunk/examples/meshing/surface_nurbs/triangles/mkfacets.py	2012-06-25 16:38:44 UTC (rev 20404)
@@ -5,8 +5,8 @@
 # meshing package if you have installed it.
 
 # Import necessary packages.
-import subprocess
 import os
+import os
 # import pdb
 # pdb.set_trace()
 
@@ -16,10 +16,6 @@
 facetsOut = "ruapehu-nzmg-1km.fac"
 
 # Triangulate the points to get connectivities.
-# c = open(connectFile, 'w')
-# triCall = ["triangulate", vertexFile, "-V"]
-# retCode = subprocess.Popen(triCall, stdout=c)
-# c.close()
 os.system('triangulate '+vertexFile+' > '+connectFile)
 
 # Read connectivities and vertices.

Modified: short/3D/PyLith/branches/v1.7-trunk/examples/twocells/twohex8/dislocation_sliptime.spatialdb
===================================================================
--- short/3D/PyLith/branches/v1.7-trunk/examples/twocells/twohex8/dislocation_sliptime.spatialdb	2012-06-25 04:52:47 UTC (rev 20403)
+++ short/3D/PyLith/branches/v1.7-trunk/examples/twocells/twohex8/dislocation_sliptime.spatialdb	2012-06-25 16:38:44 UTC (rev 20404)
@@ -9,7 +9,7 @@
   num-values = 1
   value-names =  slip-time
 
-  // The fault slip time has units of meters.
+  // The fault slip time has units of seconds.
   value-units =  s
 
   // The value is specified at one spatial location.

Modified: short/3D/PyLith/branches/v1.7-trunk/examples/twocells/twoquad4/dislocation_sliptime.spatialdb
===================================================================
--- short/3D/PyLith/branches/v1.7-trunk/examples/twocells/twoquad4/dislocation_sliptime.spatialdb	2012-06-25 04:52:47 UTC (rev 20403)
+++ short/3D/PyLith/branches/v1.7-trunk/examples/twocells/twoquad4/dislocation_sliptime.spatialdb	2012-06-25 16:38:44 UTC (rev 20404)
@@ -9,7 +9,7 @@
   num-values = 1
   value-names =  slip-time
 
-  // The fault slip time has units of meters.
+  // The fault slip time has units of seconds.
   value-units =  s
 
   // The value is specified at one spatial location.

Modified: short/3D/PyLith/branches/v1.7-trunk/examples/twocells/twotet4/dislocation_sliptime.spatialdb
===================================================================
--- short/3D/PyLith/branches/v1.7-trunk/examples/twocells/twotet4/dislocation_sliptime.spatialdb	2012-06-25 04:52:47 UTC (rev 20403)
+++ short/3D/PyLith/branches/v1.7-trunk/examples/twocells/twotet4/dislocation_sliptime.spatialdb	2012-06-25 16:38:44 UTC (rev 20404)
@@ -9,7 +9,7 @@
   num-values = 1
   value-names =  slip-time
 
-  // The fault slip time has units of meters.
+  // The fault slip time has units of seconds.
   value-units =  s
 
   // The value is specified at one spatial location.

Modified: short/3D/PyLith/branches/v1.7-trunk/examples/twocells/twotet4-geoproj/dislocation_sliptime.spatialdb
===================================================================
--- short/3D/PyLith/branches/v1.7-trunk/examples/twocells/twotet4-geoproj/dislocation_sliptime.spatialdb	2012-06-25 04:52:47 UTC (rev 20403)
+++ short/3D/PyLith/branches/v1.7-trunk/examples/twocells/twotet4-geoproj/dislocation_sliptime.spatialdb	2012-06-25 16:38:44 UTC (rev 20404)
@@ -9,7 +9,7 @@
   num-values = 1
   value-names =  slip-time
 
-  // The fault slip time has units of meters.
+  // The fault slip time has units of seconds.
   value-units =  s
 
   // The value is specified at one spatial location.

Modified: short/3D/PyLith/branches/v1.7-trunk/examples/twocells/twotri3/dislocation_sliptime.spatialdb
===================================================================
--- short/3D/PyLith/branches/v1.7-trunk/examples/twocells/twotri3/dislocation_sliptime.spatialdb	2012-06-25 04:52:47 UTC (rev 20403)
+++ short/3D/PyLith/branches/v1.7-trunk/examples/twocells/twotri3/dislocation_sliptime.spatialdb	2012-06-25 16:38:44 UTC (rev 20404)
@@ -9,7 +9,7 @@
   num-values = 1
   value-names =  slip-time
 
-  // The fault slip time has units of meters.
+  // The fault slip time has units of slip time.
   value-units =  s
 
   // The value is specified at one spatial location.

Modified: short/3D/PyLith/branches/v1.7-trunk/libsrc/pylith/faults/FaultCohesiveImpulses.cc
===================================================================
--- short/3D/PyLith/branches/v1.7-trunk/libsrc/pylith/faults/FaultCohesiveImpulses.cc	2012-06-25 04:52:47 UTC (rev 20403)
+++ short/3D/PyLith/branches/v1.7-trunk/libsrc/pylith/faults/FaultCohesiveImpulses.cc	2012-06-25 16:38:44 UTC (rev 20404)
@@ -256,6 +256,10 @@
         _fields->get("impulse amplitude");
     return amplitude;
 
+  } else if (0 == strcasecmp("area", name)) {
+    topology::Field<topology::SubMesh>& area = _fields->get("area");
+    return area;
+
   } else if (0 == strcasecmp("traction_change", name)) {
     assert(fields);
     const topology::Field<topology::Mesh>& dispT = fields->get("disp(t)");

Modified: short/3D/PyLith/branches/v1.7-trunk/libsrc/pylith/faults/FaultCohesiveLagrange.cc
===================================================================
--- short/3D/PyLith/branches/v1.7-trunk/libsrc/pylith/faults/FaultCohesiveLagrange.cc	2012-06-25 04:52:47 UTC (rev 20403)
+++ short/3D/PyLith/branches/v1.7-trunk/libsrc/pylith/faults/FaultCohesiveLagrange.cc	2012-06-25 16:38:44 UTC (rev 20404)
@@ -1535,8 +1535,9 @@
 void
 pylith::faults::FaultCohesiveLagrange::_calcArea(void)
 { // _calcArea
-  assert(0 != _faultMesh);
-  assert(0 != _fields);
+  assert(_faultMesh);
+  assert(_fields);
+  assert(_normalizer);
 
   // Containers for area information
   const int cellDim = _quadrature->cellDim();
@@ -1569,6 +1570,8 @@
   area.newSection(dispRel, 1);
   area.allocate();
   area.vectorFieldType(topology::FieldBase::SCALAR);
+  const PylithScalar lengthScale = _normalizer->lengthScale();
+  area.scale(pow(lengthScale, (spaceDim-1)));
   area.zero();
   const ALE::Obj<RealSection>& areaSection = area.section();
   assert(!areaSection.isNull());

Modified: short/3D/PyLith/branches/v1.7-trunk/pylith/faults/FaultCohesiveImpulses.py
===================================================================
--- short/3D/PyLith/branches/v1.7-trunk/pylith/faults/FaultCohesiveImpulses.py	2012-06-25 04:52:47 UTC (rev 20403)
+++ short/3D/PyLith/branches/v1.7-trunk/pylith/faults/FaultCohesiveImpulses.py	2012-06-25 16:38:44 UTC (rev 20404)
@@ -101,7 +101,8 @@
     self.availableFields = \
         {'vertex': \
            {'info': ["normal_dir",
-                     "impulse_amplitude"],
+                     "impulse_amplitude",
+                     "area",],
             'data': ["slip",
                      "traction_change"]},
          'cell': \

Added: short/3D/PyLith/branches/v1.7-trunk/tests/runtests.sh
===================================================================
--- short/3D/PyLith/branches/v1.7-trunk/tests/runtests.sh	                        (rev 0)
+++ short/3D/PyLith/branches/v1.7-trunk/tests/runtests.sh	2012-06-25 16:38:44 UTC (rev 20404)
@@ -0,0 +1,53 @@
+#!/bin/bash
+
+# Run several full-scale tests. Execute this script from the tests
+# directory.
+
+tests_dir=`pwd`
+
+# Clean output directory
+clean_output() {
+  cd ${tests_dir}/${dir}
+  if [ -d output ]; then rm output/*.vtk output/*.h5 output/*.xmf; fi
+}
+
+# ----------------------------------------------------------------------
+# 2d/frictionslide
+dir="2d/frictionslide"
+clean_output
+
+echo "RUNNING $dir tension"
+pylith tension.cfg --nodes=1 >& tension_np1.log
+pylith tension.cfg --nodes=2 >& tension_np2.log
+pylith tension.cfg --nodes=3 >& tension_np3.log
+
+echo "RUNNING $dir ratestate_weak"
+pylith ratestate.cfg ratestate_weak.cfg --nodes=1 >& weak_np1.log
+pylith ratestate.cfg ratestate_weak.cfg --nodes=2 >& weak_np2.log
+pylith ratestate.cfg ratestate_weak.cfg --nodes=3 >& weak_np3.log
+
+echo "RUNNING $dir ratestate_stable"
+pylith ratestate.cfg ratestate_stable.cfg --nodes=1 >& stable_np1.log
+pylith ratestate.cfg ratestate_stable.cfg --nodes=2 >& stable_np2.log
+pylith ratestate.cfg ratestate_stable.cfg --nodes=3 >& stable_np3.log
+
+# ----------------------------------------------------------------------
+# 3d/cyclicfriction
+dir="3d/cyclicfriction"
+clean_output
+
+echo "RUNNING $dir ASM"
+pylith --nodes=1 >& asm_np1.log
+pylith --nodes=2 >& asm_np2.log
+pylith --nodes=5 >& asm_np5.log
+
+echo "RUNNING $dir fieldsplit"
+pylith fieldsplit.cfg --nodes=1 >& fieldsplit_np1.log
+pylith fieldsplit.cfg --nodes=2 >& fieldsplit_np2.log
+pylith fieldsplit.cfg --nodes=5 >& fielssplit_np5.log
+
+# ----------------------------------------------------------------------
+# Return to examples dir
+cd ${tests_dir}
+  
+exit 0

