[cig-commits] r20701 - in short/3D/PyLith/branches/v1.7-trunk: . doc/userguide/runpylith examples/meshing examples/meshing/surface_nurbs libsrc/pylith/faults libsrc/pylith/friction pylith/problems
brad at geodynamics.org
brad at geodynamics.org
Fri Sep 7 08:42:20 PDT 2012
Author: brad
Date: 2012-09-07 08:42:19 -0700 (Fri, 07 Sep 2012)
New Revision: 20701
Added:
short/3D/PyLith/branches/v1.7-trunk/examples/meshing/cubit_cellsize/
short/3D/PyLith/branches/v1.7-trunk/examples/meshing/surface_nurbs/merge_surfs/
Modified:
short/3D/PyLith/branches/v1.7-trunk/configure.ac
short/3D/PyLith/branches/v1.7-trunk/doc/userguide/runpylith/runpylith.lyx
short/3D/PyLith/branches/v1.7-trunk/examples/meshing/Makefile.am
short/3D/PyLith/branches/v1.7-trunk/examples/meshing/surface_nurbs/Makefile.am
short/3D/PyLith/branches/v1.7-trunk/libsrc/pylith/faults/TopologyOps.cc
short/3D/PyLith/branches/v1.7-trunk/libsrc/pylith/friction/FrictionModel.cc
short/3D/PyLith/branches/v1.7-trunk/libsrc/pylith/friction/RateStateAgeing.cc
short/3D/PyLith/branches/v1.7-trunk/pylith/problems/TimeStep.py
Log:
Merge from stable.
Modified: short/3D/PyLith/branches/v1.7-trunk/configure.ac
===================================================================
--- short/3D/PyLith/branches/v1.7-trunk/configure.ac 2012-09-07 15:37:18 UTC (rev 20700)
+++ short/3D/PyLith/branches/v1.7-trunk/configure.ac 2012-09-07 15:42:19 UTC (rev 20701)
@@ -382,6 +382,8 @@
examples/meshing/surface_nurbs/dem/ulines/Makefile
examples/meshing/surface_nurbs/dem/vlines/Makefile
examples/meshing/surface_nurbs/triangles/Makefile
+ examples/meshing/surface_nurbs/merge_surfs/Makefile
+ examples/meshing/cubit_cellsize/Makefile
templates/Makefile
share/Makefile
])
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-09-07 15:37:18 UTC (rev 20700)
+++ short/3D/PyLith/branches/v1.7-trunk/doc/userguide/runpylith/runpylith.lyx 2012-09-07 15:42:19 UTC (rev 20701)
@@ -1,5652 +1,5738 @@
-#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
-
-\family typewriter
-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
-\size footnotesize
-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
-\size footnotesize
-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
-\size footnotesize
-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
-\size footnotesize
-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
-\size footnotesize
-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
-\size footnotesize
-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
-\size footnotesize
-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 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
-
-\size footnotesize
-[pylithapp.timedependent.formulation]
-\end_layout
-
-\begin_layout LyX-Code
-
-\size footnotesize
-time_step = pylith.problems.TimeStepUniform
-\end_layout
-
-\begin_layout LyX-Code
-
-\size footnotesize
-solver = pylith.problems.SolverLinear ; Nonlinear solver is pylith.problems.SolverNo
-nlinear
-\end_layout
-
-\begin_layout LyX-Code
-
-\size footnotesize
-output = [domain,ground_surface]
-\end_layout
-
-\begin_layout LyX-Code
-
-\size footnotesize
-matrix_type = sbaij ; To use a non-symmetric sparse matrix, set it to aij
-\end_layout
-
-\begin_layout LyX-Code
-
-\size footnotesize
-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 footnotesize
-[pylithapp.timedependent.materials.material]
-\end_layout
-
-\begin_layout LyX-Code
-
-\size footnotesize
-db_properties = spatialdata.spatialdb.UniformDB ; Set the db to a UniformDB
-\end_layout
-
-\begin_layout LyX-Code
-
-\size footnotesize
-db_properties.values = [vp,vs,density] ; Set the names of the values in the
- database
-\end_layout
-
-\begin_layout LyX-Code
-
-\size footnotesize
-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
-
-\begin_inset Newline linebreak
-\end_inset
-
-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
-
-\begin_inset Newline newline
-\end_inset
-
---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_deeper
-\begin_layout Enumerate
-Go to the
-\family typewriter
-lib/python2.6/site-packages
-\family default
- directory.
-\end_layout
-
-\begin_layout Enumerate
-Unzip
-\family typewriter
-merlin-1.7-py2.6.egg
-\family default
- (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
-\family typewriter
-__init__.py
-\family default
-.
- Replace line 308 plat = get_platform() with plat = "linux-i686"
-\end_layout
-
-\begin_layout Enumerate
-If
-\family typewriter
-merlin-1.7-py2.6.egg
-\family default
- is a file, rezip merlin.
- Go to the site-packages directory and enter "
-\family typewriter
-zip -r merlin-1.7-py2.6.egg merlin
-\family default
-".
-\end_layout
-
-\end_deeper
-\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 from 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 footnotesize
-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
+
+\family typewriter
+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
+\size footnotesize
+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
+\size footnotesize
+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
+\size footnotesize
+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
+\size footnotesize
+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
+\size footnotesize
+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
+\size footnotesize
+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
+\size footnotesize
+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
+Model Verification with PETSc Direct Solvers
+\end_layout
+
+\begin_layout Standard
+It is often useful to apply a direct solver so that solver convergence is
+ decoupled from model verification for the purposes of testing.
+ Unfortunately, the traditional LU factorization solvers cannot be directly
+ applied in PyLith due to the saddle-point formulation used to accomodate
+ the fault slip constraints.
+ However, we can combine an LU factorization of the displacement sub-block
+ with a full Schur complement factorization using the PETSc FieldSplit precondit
+ioner.
+ If the solver for the Schur complement S is given a very low tolerance,
+ this is effectively a direct solver.
+ The options given below will construct this solver in PyLith.
+\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
+use_custom_constraint_pc = True
+\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_type = schur
+\end_layout
+
+\begin_layout LyX-Code
+fs_pc_fieldsplit_schur_precondition = user
+\end_layout
+
+\begin_layout LyX-Code
+fs_pc_fieldsplit_schur_factorization_type = full
+\end_layout
+
+\begin_layout LyX-Code
+fs_pc_fieldsplit_real_diagonal = true
+\end_layout
+
+\begin_layout LyX-Code
+fs_fieldsplit_0_pc_type = lu
+\end_layout
+
+\begin_layout LyX-Code
+fs_fieldsplit_0_ksp_type = gmres
+\end_layout
+
+\begin_layout LyX-Code
+fs_fieldsplit_0_ksp_rtol = 1.0e-10
+\end_layout
+
+\begin_layout LyX-Code
+fs_fieldsplit_1_pc_type = jacobi
+\end_layout
+
+\begin_layout LyX-Code
+fs_fieldsplit_1_ksp_type = gmres
+\end_layout
+
+\begin_layout LyX-Code
+fs_fieldsplit_1_ksp_rtol = 1.0e-10
+\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 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
+
+\size footnotesize
+[pylithapp.timedependent.formulation]
+\end_layout
+
+\begin_layout LyX-Code
+
+\size footnotesize
+time_step = pylith.problems.TimeStepUniform
+\end_layout
+
+\begin_layout LyX-Code
+
+\size footnotesize
+solver = pylith.problems.SolverLinear ; Nonlinear solver is pylith.problems.SolverNo
+nlinear
+\end_layout
+
+\begin_layout LyX-Code
+
+\size footnotesize
+output = [domain,ground_surface]
+\end_layout
+
+\begin_layout LyX-Code
+
+\size footnotesize
+matrix_type = sbaij ; To use a non-symmetric sparse matrix, set it to aij
+\end_layout
+
+\begin_layout LyX-Code
+
+\size footnotesize
+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 footnotesize
+[pylithapp.timedependent.materials.material]
+\end_layout
+
+\begin_layout LyX-Code
+
+\size footnotesize
+db_properties = spatialdata.spatialdb.UniformDB ; Set the db to a UniformDB
+\end_layout
+
+\begin_layout LyX-Code
+
+\size footnotesize
+db_properties.values = [vp,vs,density] ; Set the names of the values in the
+ database
+\end_layout
+
+\begin_layout LyX-Code
+
+\size footnotesize
+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
+
+\begin_inset Newline linebreak
+\end_inset
+
+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
+
+\begin_inset Newline newline
+\end_inset
+
+--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_deeper
+\begin_layout Enumerate
+Go to the
+\family typewriter
+lib/python2.6/site-packages
+\family default
+ directory.
+\end_layout
+
+\begin_layout Enumerate
+Unzip
+\family typewriter
+merlin-1.7-py2.6.egg
+\family default
+ (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
+\family typewriter
+__init__.py
+\family default
+.
+ Replace line 308 plat = get_platform() with plat = "linux-i686"
+\end_layout
+
+\begin_layout Enumerate
+If
+\family typewriter
+merlin-1.7-py2.6.egg
+\family default
+ is a file, rezip merlin.
+ Go to the site-packages directory and enter "
+\family typewriter
+zip -r merlin-1.7-py2.6.egg merlin
+\family default
+".
+\end_layout
+
+\end_deeper
+\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 from 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 footnotesize
+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/examples/meshing/Makefile.am
===================================================================
--- short/3D/PyLith/branches/v1.7-trunk/examples/meshing/Makefile.am 2012-09-07 15:37:18 UTC (rev 20700)
+++ short/3D/PyLith/branches/v1.7-trunk/examples/meshing/Makefile.am 2012-09-07 15:42:19 UTC (rev 20701)
@@ -17,7 +17,8 @@
#
SUBDIRS = \
- surface_nurbs
+ surface_nurbs \
+ cubit_cellsize
# End of file
Copied: short/3D/PyLith/branches/v1.7-trunk/examples/meshing/cubit_cellsize (from rev 20700, short/3D/PyLith/branches/v1.7-stable/examples/meshing/cubit_cellsize)
Modified: short/3D/PyLith/branches/v1.7-trunk/examples/meshing/surface_nurbs/Makefile.am
===================================================================
--- short/3D/PyLith/branches/v1.7-trunk/examples/meshing/surface_nurbs/Makefile.am 2012-09-07 15:37:18 UTC (rev 20700)
+++ short/3D/PyLith/branches/v1.7-trunk/examples/meshing/surface_nurbs/Makefile.am 2012-09-07 15:42:19 UTC (rev 20701)
@@ -19,7 +19,8 @@
SUBDIRS = \
contours \
dem \
- triangles
+ triangles \
+ merge_surfs
dist_noinst_DATA = \
Copied: short/3D/PyLith/branches/v1.7-trunk/examples/meshing/surface_nurbs/merge_surfs (from rev 20700, short/3D/PyLith/branches/v1.7-stable/examples/meshing/surface_nurbs/merge_surfs)
Modified: short/3D/PyLith/branches/v1.7-trunk/libsrc/pylith/faults/TopologyOps.cc
===================================================================
--- short/3D/PyLith/branches/v1.7-trunk/libsrc/pylith/faults/TopologyOps.cc 2012-09-07 15:37:18 UTC (rev 20700)
+++ short/3D/PyLith/branches/v1.7-trunk/libsrc/pylith/faults/TopologyOps.cc 2012-09-07 15:42:19 UTC (rev 20701)
@@ -116,7 +116,12 @@
}
assert(classifySize < vReplaceCells.size() + vNoReplaceCells.size());
classifySize = vReplaceCells.size() + vNoReplaceCells.size();
- assert(classifySize <= classifyTotal);
+ if (classifySize > classifyTotal) {
+ std::ostringstream msg;
+ msg << "Error classifying cells during creation of cohesive cells.\n"
+ << " classifySize: " << classifySize << ", classifyTotal: " << classifyTotal;
+ throw std::logic_error(msg.str());
+ } // if
}
replaceCells.insert(vReplaceCells.begin(), vReplaceCells.end());
// More checking
Modified: short/3D/PyLith/branches/v1.7-trunk/libsrc/pylith/friction/FrictionModel.cc
===================================================================
--- short/3D/PyLith/branches/v1.7-trunk/libsrc/pylith/friction/FrictionModel.cc 2012-09-07 15:37:18 UTC (rev 20700)
+++ short/3D/PyLith/branches/v1.7-trunk/libsrc/pylith/friction/FrictionModel.cc 2012-09-07 15:42:19 UTC (rev 20701)
@@ -234,7 +234,9 @@
} // for
// Close database
_dbInitialState->close();
- } // if
+ } else if (_metadata.numDBStateVars()) {
+ std::cerr << "WARNING: No initial state given for friction model '" << label() << "'. Using default value of zero." << std::endl;
+ } // if/else
// Setup buffers for restrict/update of properties and state variables.
_propsStateVarsVertex.resize(fieldsFiberDim);
Modified: short/3D/PyLith/branches/v1.7-trunk/libsrc/pylith/friction/RateStateAgeing.cc
===================================================================
--- short/3D/PyLith/branches/v1.7-trunk/libsrc/pylith/friction/RateStateAgeing.cc 2012-09-07 15:37:18 UTC (rev 20700)
+++ short/3D/PyLith/branches/v1.7-trunk/libsrc/pylith/friction/RateStateAgeing.cc 2012-09-07 15:42:19 UTC (rev 20701)
@@ -318,8 +318,10 @@
const PylithScalar b = properties[p_b];
const PylithScalar L = properties[p_L];
const PylithScalar slipRate0 = properties[p_slipRate0];
- const PylithScalar theta = stateVars[s_state];
+ // Prevent zero value for theta, reasonable value is L / slipRate0
+ const PylithScalar theta = (stateVars[s_state] > 0.0) ? stateVars[s_state] : L / slipRate0;
+
if (slipRate >= slipRateLinear) {
mu_f = f0 + a*log(slipRate / slipRate0) + b*log(slipRate0*theta/L);
} else {
@@ -376,7 +378,7 @@
// Since regulatized friction -> 0 as slipRate -> 0, limit slip
// rate to some minimum value
- const PylithScalar slipRateEff = std::max(_linearSlipRate, slipRate);
+ const PylithScalar slipRateEff = std::max(1.0e-2*_linearSlipRate, slipRate);
const PylithScalar dt = _dt;
const PylithScalar thetaTVertex = stateVars[s_state];
Modified: short/3D/PyLith/branches/v1.7-trunk/pylith/problems/TimeStep.py
===================================================================
--- short/3D/PyLith/branches/v1.7-trunk/pylith/problems/TimeStep.py 2012-09-07 15:37:18 UTC (rev 20700)
+++ short/3D/PyLith/branches/v1.7-trunk/pylith/problems/TimeStep.py 2012-09-07 15:42:19 UTC (rev 20701)
@@ -189,7 +189,7 @@
import pylith.mpi.mpi as mpi
comm = mesh.getComm()
dtStableAll = mpi.allreduce_scalar_double(dtStable, mpi.mpi_min(), comm.handle)
- return dtStable
+ return dtStableAll
More information about the CIG-COMMITS
mailing list