[cig-commits] r20401 - in short/3D/PyLith/branches/v1.7-stable: doc/userguide/tutorials/3dtet4 examples/3d/hex8

[brad at geodynamics.org]

Author: brad
Date: 2012-06-24 11:07:08 -0700 (Sun, 24 Jun 2012)
New Revision: 20401

Modified:
   short/3D/PyLith/branches/v1.7-stable/doc/userguide/tutorials/3dtet4/3dtet4.lyx
   short/3D/PyLith/branches/v1.7-stable/examples/3d/hex8/step05.cfg
Log:
Fixed typos found by Sue.

Modified: short/3D/PyLith/branches/v1.7-stable/doc/userguide/tutorials/3dtet4/3dtet4.lyx
===================================================================
--- short/3D/PyLith/branches/v1.7-stable/doc/userguide/tutorials/3dtet4/3dtet4.lyx	2012-06-23 04:42:41 UTC (rev 20400)
+++ short/3D/PyLith/branches/v1.7-stable/doc/userguide/tutorials/3dtet4/3dtet4.lyx	2012-06-24 18:07:08 UTC (rev 20401)
@@ -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 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.
-\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 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
+#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 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.
+\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.domain.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-stable/examples/3d/hex8/step05.cfg
===================================================================
--- short/3D/PyLith/branches/v1.7-stable/examples/3d/hex8/step05.cfg	2012-06-23 04:42:41 UTC (rev 20400)
+++ short/3D/PyLith/branches/v1.7-stable/examples/3d/hex8/step05.cfg	2012-06-24 18:07:08 UTC (rev 20401)
@@ -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]