Pylith-2.2.0 Manual

COMPUTATIONAL INFRASTRUCTURE FOR GEODYNAMICS (CIG)
PyLith
User Manual
Version 2.2.0
Brad Aagaard
Matthew Knepley
Charles Williams
www.geodynamics.org
2
PyLith User Manual
©University of California, Davis

Version 2.2.0
March 31, 2017

2
Contents
Preface xxi
0.1 About This Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxi
0.2 Who Will Use This Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxi
0.3 Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxi
0.3.1 Command Line Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxi
0.3.2 Filenames and Directories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxii
0.3.3 Unix Shell Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxii
0.3.4 Excerpts of cfg Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxii
0.4 Citation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxii
0.5 Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxii
0.6 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxiii
0.7 Request for Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxiii
1 Introduction 1
1.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
1.2 New in PyLith Version 2.2.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
1.3 History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
1.4 PyLith Workflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.5 PyLith Design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.5.1 Pyre . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.5.2 PETSc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
2 Governing Equations 7
2.1 Derivation of Elasticity Equation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
2.1.1 Index Notation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
2.1.2 Vector Notation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.2 Finite-Element Formulation of Elasticity Equation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
2.2.1 Index Notation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
i
ii CONTENTS
2.2.2 Vector Notation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
2.3 Solution Method for Quasi-Static Problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
2.4 Solution Method for Dynamic Problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
2.5 Small (Finite) Strain Formulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
2.5.1 Quasi-static Problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
2.5.2 Dynamic Problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
3 Installation and Getting Help 17

3.1 Getting Help and Reporting Bugs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
3.2 Installation of Binary Executable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
3.2.1 Linux and Max OS X . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
3.2.2 Extending PyLith and/or Integrating Other Software Into PyLith . . . . . . . . . . . . . . . . . . . . . . . 18
3.3 Installation of PyLith Docker Container . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
3.3.1 Setup (first time only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
3.3.2 Run Unix shell within Docker to use PyLith. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
3.3.2.1 Using Docker containers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
3.3.3 Copy data to/from persistent storage volume. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
3.3.4 Docker Quick Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
3.4 Installation from Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
3.5 Verifying PyLith is Installed Correctly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
3.6 Configuration on a Cluster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
3.6.1 Launchers and Schedulers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
3.6.2 Running without a Batch System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
3.6.3 Using a Batch System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
3.6.3.1 LSF Batch System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
3.6.3.2 PBS Batch System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
4 Running PyLith 25
4.1 Defining the Simulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
4.1.1 Setting PyLith Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
4.1.1.1 Units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
4.1.1.2 Using the Command Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
4.1.1.3 Using a .cfg File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
4.1.1.4 Using a .pml File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
4.1.1.5 Specification and Placement of Configuration Files . . . . . . . . . . . . . . . . . . . . . . . . . 27
4.1.1.6 List of PyLith Parameters (pylithinfo) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
4.1.2 Mesh Information (mesher) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
CONTENTS iii
4.1.2.1 Mesh Importer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
4.1.2.2 MeshIOAscii . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
4.1.2.3 MeshIOCubit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
4.1.2.4 MeshIOLagrit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
4.1.2.5 Distributor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
4.1.2.6 Refiner . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
4.1.3 Problem Specification (problem) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
4.1.3.1 Nondimensionalization (normalizer) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
4.1.4 Finite-Element Integration Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
4.1.5 PETSc Settings (petsc) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
4.1.5.1 Model Verification with PETSc Direct Solvers . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
4.2 Time-Dependent Problem (formulation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
4.2.1 Time-Stepping Formulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
4.2.2 Numerical Damping in Explicit Time Stepping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
4.2.3 Solvers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
4.2.4 Time Stepping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
4.2.4.1 Uniform, User-Specified Time Step (TimeStepUniform) . . . . . . . . . . . . . . . . . . . . . 38
4.2.4.2 Nonuniform, User-Specified Time Step (TimeStepUser) . . . . . . . . . . . . . . . . . . . . . 39
4.2.4.3 Nonuniform, Automatic Time Step (TimeStepAdapt) . . . . . . . . . . . . . . . . . . . . . . . 39
4.3 Green’s Functions Problem (GreensFns) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
4.4 Progress Monitors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
4.4.1 ProgressMonitorTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
4.4.2 ProgressMonitorStep . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
4.5 Databases for Boundaries, Interfaces, and Material Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
4.5.1 SimpleDB Spatial Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
4.5.2 UniformDB Spatial Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
4.5.2.1 ZeroDispDB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
4.5.3 SimpleGridDB Spatial Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
4.5.4 SCEC CVM-H Spatial Database (SCECCVMH) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
4.5.5 CompositeDB Spatial Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
4.5.6 TimeHistory Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
4.6 Labels and Identifiers for Materials, Boundary Conditions, and Faults . . . . . . . . . . . . . . . . . . . . . . . . . 44
4.7 PyLith Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
4.7.1 Output Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
4.7.1.1 Output Over Subdomain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
4.7.2 Output at Arbitrary Points . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
iv CONTENTS
4.7.2.1 PointsList Reader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
4.7.3 Output Field Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
4.7.3.1 Vertex Field Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
4.7.3.2 Cell Field Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
4.7.4 VTK Output (DataWriterVTK) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
4.7.5 HDF5/Xdmf Output (DataWriterHDF5, DataWriterHDF5Ext) . . . . . . . . . . . . . . . . . . . . . . . 47
4.7.5.1 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
4.7.5.2 HDF5 Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
4.8 Tips and Hints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
4.8.1 Tips and Hints For Running PyLith . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
4.8.2 Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
4.8.2.1 Import Error and Missing Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
4.8.2.2 Unrecognized Property ’p4wd’ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
4.8.2.3 Detected zero pivor in LU factorization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
4.8.2.4 Bus Error . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
4.8.2.5 Segmentation Fault . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
4.9 Post-Processing Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
4.9.1 pylith_eqinfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
4.9.2 pylith_genxdmf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
4.10 PyLith Parameter Viewer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
4.11 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
4.12 Running the Parameter Viewer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
4.12.1 Generate the parameter JSON file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
4.12.2 Start the web server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
4.13 Using the Parameter Viewer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
4.13.1 Version Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
4.13.2 Parameter Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
5 Material Models 59
5.1 Specifying Material Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
5.1.1 Setting the Material Identifier . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
5.1.2 Material Property Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
5.1.3 Material Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
5.1.4 Initial State Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
5.1.4.1 Specification of Initial State Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
5.1.5 Cauchy Stress Tensor and Second Piola-Kirchoff Stress Tensor . . . . . . . . . . . . . . . . . . . . . . . . 63
5.1.6 Stable time step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
CONTENTS v
5.2 Elastic Material Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
5.2.1 2D Elastic Material Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
5.2.1.1 Elastic Plane Strain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
5.2.1.2 Elastic Plane Stress . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
5.2.2 3D Elastic Material Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
5.2.2.1 Isotropic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
5.3 Viscoelastic Materials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
5.3.1 Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
5.3.2 Linear Viscoelastic Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
5.3.3 Formulation for Generalized Maxwell Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
5.3.4 Effective Stress Formulations for Viscoelastic Materials . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
5.3.4.1 Power-Law Maxwell Viscoelastic Material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
5.4 Elastoplastic Materials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
5.4.1 General Elastoplasticity Formulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
5.4.2 Drucker-Prager Elastoplastic Material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
5.4.2.1 Drucker-Prager Elastoplastic With No Hardening (Perfectly Plastic) . . . . . . . . . . . . . . . 79
6 Boundary and Interface Conditions 83

6.1 Assigning Boundary Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
6.1.1 Creating Sets of Vertices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
6.1.2 Arrays of Boundary Condition Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
6.2 Time-Dependent Boundary Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
6.2.1 Dirichlet Boundary Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
6.2.1.1 Dirichlet Boundary Condition Spatial Database Files . . . . . . . . . . . . . . . . . . . . . . . . 85
6.2.2 Neumann Boundary Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
6.2.2.1 Neumann Boundary Condition Spatial Database Files . . . . . . . . . . . . . . . . . . . . . . . 86
6.2.3 Point Force Boundary Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
6.2.3.1 Point Force Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
6.2.3.2 Point Force Spatial Database Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
6.3 Absorbing Boundary Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
6.3.1 Finite-Element Implementation of Absorbing Boundary . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
6.4 Fault Interface Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
6.4.1 Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
6.4.2 Fault Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
6.4.3 Fault Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
6.4.4 Kinematic Earthquake Rupture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
6.4.4.1 Governing Equations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
vi CONTENTS
6.4.4.2 Arrays of Kinematic Rupture Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
6.4.4.3 Kinematic Rupture Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
6.4.4.4 Slip Time Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
6.4.5 Dynamic Earthquake Rupture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
6.4.5.1 Governing Equations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
6.4.5.2 Dynamic Rupture Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
6.4.5.3 Fault Constitutive Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
6.4.6 Slip Impulses for Green’s Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
6.5 Gravitational Body Forces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
7 Examples 109
7.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
7.1.1 Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
7.1.1.1 Input Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
7.2 Examples Using Two Triangles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
7.2.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
7.2.2 Mesh Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
7.2.3 Additional Common Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
7.2.4 Axial Displacement Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
7.2.5 Shear Displacement Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
7.2.6 Kinematic Fault Slip Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
7.3 Example Using Two Quadrilaterals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
7.3.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
7.3.7 Axial Traction Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
7.4 Example Using Two Tetrahedra . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
7.4.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
7.5 Example Using Two Hexahedra . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
7.5.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
CONTENTS vii
7.6 Example Using Two Tetrahedra with Georeferenced Coordinate System Mesh . . . . . . . . . . . . . . . . . . . . 125
7.6.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
7.7 Example Using Tetrahedral Mesh Created by LaGriT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
7.7.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
7.7.2 Mesh Generation and Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
7.7.4.1 Alternative Solver and Discretization Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
7.7.5.1 Alternative Solver and Discretization Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
7.8 Examples Using Hexahedral Mesh Created by CUBIT/Trelis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
7.8.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
7.8.2 Mesh Generation and Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
7.8.4 Example Problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
7.8.5 Static Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
7.8.5.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
7.8.5.2 Step01 - Pure Dirichlet Boundary Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
7.8.5.3 Step02 - Dirichlet and Neumann Boundary Conditions . . . . . . . . . . . . . . . . . . . . . . . 140
7.8.5.4 Step03 - Dirichlet Boundary Conditions with Kinematic Fault Slip . . . . . . . . . . . . . . . . 141
7.8.6 Quasi-Static Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
7.8.6.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
7.8.6.2 Step04 - Pure Dirichlet Velocity Boundary Conditions . . . . . . . . . . . . . . . . . . . . . . . 143
7.8.6.3 Step05 - Time-Varying Dirichlet and Neumann Boundary Conditions . . . . . . . . . . . . . . 145
7.8.6.4 Step06 - Dirichlet Boundary Conditions with Time-Dependent Kinematic Fault Slip . . . . . . 146
7.8.6.5 Step07 - Dirichlet Velocity Boundary Conditions with Time-Dependent Kinematic Fault Slip . 149
7.8.6.6 Step08 - Dirichlet Velocity Boundary Conditions with Time-Dependent Kinematic Fault Slip
and Power-Law Rheology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
viii CONTENTS
and Drucker-Prager Elastoplastic Rheology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
7.8.7 Fault Friction Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
7.8.7.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
7.8.7.2 Step10 - Static Friction (Stick) with Static Dirichlet Boundary Conditions . . . . . . . . . . . . 154
7.8.7.3 Step11 - Static Friction (Slip) with Static Dirichlet Boundary Conditions . . . . . . . . . . . . 155
7.8.7.4 Step12 - Static Friction with Quasi-Static Dirichlet Boundary Conditions . . . . . . . . . . . . 156
7.8.7.5 Step13 - Slip-Weakening Friction with Quasi-Static Dirichlet Boundary Conditions . . . . . . 157
7.8.7.6 Step14 - Rate-and-State Friction with Quasi-Static Dirichlet Boundary Conditions . . . . . . . 158
7.8.8 Gravitational Body Force Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
7.8.8.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
7.8.8.2 Step15 - Gravitational Body Forces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
7.8.8.3 Step16 - Gravitational Body Forces with Initial Stresses . . . . . . . . . . . . . . . . . . . . . . 161
7.8.8.4 Step17 - Gravitational Body Forces with Small Strain . . . . . . . . . . . . . . . . . . . . . . . 162
7.8.9 Surface Load Traction Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
7.8.9.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
7.8.9.2 Step18 - Static Surface Load . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
7.8.9.3 Step19 - Time-Dependent Surface Load . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
7.8.10 Dike Intrusion Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
7.8.10.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
7.8.10.2 Step20 - Static Dike Intrusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
7.8.11 Green’s Functions Generation Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
7.8.11.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
7.8.11.2 Step21 - Green’s Function Generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
7.9 Example for Slip on a Subduction Zone . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
7.9.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
7.9.3 Common Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
7.9.4 Step 1: Coseismic Slip Simulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
7.9.5 Step 2: Interseismic Deformation Simulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
7.9.6 Step 3: Pseudo-Earthquake Cycle Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
7.9.7 Step 4: Frictional Afterslip Simulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
7.9.8 Suggested Variations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
7.10 Shear Wave in a Bar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
7.11 2D Bar Discretized with Triangles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
7.11.1 Mesh Generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
CONTENTS ix
7.11.2 Simulation Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
7.12 3D Bar Discretized with Quadrilaterals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
7.12.1 Mesh Generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
7.12.2 Kinematic Fault (Prescribed Slip) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
7.12.3 Dynamic Fault (Spontaneous Rupture) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
7.12.3.1 Dynamic Fault with Static Friction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
7.12.3.2 Dynamic Fault with Slip-Weakening Friction . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
7.12.3.3 Dynamic Fault with Rate-State Friction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
7.13 3D Bar Discretized with Tetrahedra . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
7.13.1 Mesh Generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
7.14 3D Bar Discretized with Hexahedra . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
7.14.1 Mesh Generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
7.15 Example Generating and Using Green’s Functions in Two Dimensions . . . . . . . . . . . . . . . . . . . . . . . . 183
7.15.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
7.15.4 Step 1: Solution of the Forward Problem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
7.15.5 Step 2: Generation of Green’s Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
7.15.6 Step 3: Simple Inversion Using PyLith-generated Green’s Functions . . . . . . . . . . . . . . . . . . . . . 187
7.15.7 Step 4: Visualization of Estimated and True Solutions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
7.16 Example Using Gravity and Finite Strain in Two Dimensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
7.16.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
7.16.2 Problem Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
7.16.4 Step 1: Gravitational Body Forces and Infinitesimal Strain . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
7.16.5 Step 2: Gravitational Body Forces, Infinitesimal Strain, and Initial Stresses . . . . . . . . . . . . . . . . . 192
7.16.6 Step 3: Infinitesimal Strain Simulation with Initial Stresses and a Local Density Variation . . . . . . . . 192
7.16.7 Step 4: Postseismic Relaxation with Infinitesimal Strain . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
7.16.8 Step 5: Postseismic Relaxation with Finite Strain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
7.16.9 Step 6: Postseismic Relaxation with Infinitesimal Strain and Gravitational Body Forces . . . . . . . . . . 194
7.16.10 Step 7: Postseismic Relaxation with Finite Strain and Gravitational Body Forces . . . . . . . . . . . . . . 194
7.16.11 Step 8: Postseismic Relaxation with Finite Strain, Gravitational Body Forces, and Variable Density . . . 195
7.16.12 Exercises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
7.17 Additional Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
x CONTENTS
7.17.1 CUBIT Meshing Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
7.17.2 Debugging Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
7.17.3 Code Verification Benchmarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
8 Benchmarks 197
8.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
8.2 Strike-Slip Benchmark . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
8.2.2 Running the Benchmark . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
8.2.3 Benchmark Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
8.2.3.1 Solution Accuracy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
8.2.3.2 Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
8.3 Savage and Prescott Benchmark . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
8.3.2 Running the Benchmark . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
8.3.3 Benchmark Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
8.4 SCEC Dynamic Rupture Benchmarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
9 Extending PyLith 209

9.1 Spatial Databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
9.2 Bulk Constitutive Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211
9.3 Fault Constitutive Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
A Glossary 215
A.1 Pyre . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
A.2 DMPlex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
B PyLith and Spatialdata Components 217

B.1 Application components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
B.1.1 Problem Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
B.1.2 Utility Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
B.1.3 Topology Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
B.1.4 Material Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
B.1.5 Boundary Condition Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
B.1.6 Fault Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
B.1.7 Friction Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
B.1.8 Discretization Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
B.1.9 Output Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
CONTENTS xi
B.2 Spatialdata Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
B.2.1 Coordinate System Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
B.2.2 Spatial database Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
B.2.3 Nondimensionalization components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
C File Formats 223

C.1 PyLith Mesh ASCII Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
C.2 SimpleDB Spatial Database Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224
C.2.1 Spatial Database Coordinate Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
C.2.1.1 Cartesian . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
C.2.1.2 Geographic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226
C.2.1.3 Geographic Projection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226
C.2.1.4 Geographic Local Cartesian . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
C.3 SimpleGridDB Spatial Database Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
C.4 TimeHistory Database Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228
C.5 User-Specified Time-Step File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229
C.6 PointsList File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229
D Alternative Material Model Formulations 231

D.1 Viscoelastic Formulations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
D.1.1 Effective Stress Formulation for a Linear Maxwell Viscoelastic Material . . . . . . . . . . . . . . . . . . 231
E Analytical Solutions 233

E.1 Traction Problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
E.1.1 Solutions Using Polynomial Stress Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
E.1.2 Constant Traction Applied to a Rectangular Region . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
F PyLith Software License 237

xii CONTENTS
List of Figures
1.1 Workflow involved in going from geologic structure to problem analysis. . . . . . . . . . . . . . . . . . . . . . . . 2

1.2 PyLith dependencies. PyLith makes direct use of several other packages, some of which have their own depen-
dencies. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.3 Pyre Architecture. The integration framework is a set of cooperating abstract services. . . . . . . . . . . . . . . . 4
4.1 PyLith requires a finite-element mesh (three different mechanisms for generating a mesh are currently sup-
ported), simulation parameters, and spatial databases (defining the spatial variation of various parameters).
PyLith writes the solution output to either VTK or HDF5/Xdmf files, which can be visualized with ParaView
or Visit. Post-processing is generally done using the HDF5 files with Python or Matlab scripts. . . . . . . . . . . 26
4.2 Linear cells available for 2D problems are the triangle (left) and the quadrilateral (right). . . . . . . . . . . . . . . 29
4.3 Linear cells available for 3D problems are the tetrahedron (left) and the hexahedron (right). . . . . . . . . . . . . 30
4.4 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. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
4.5 General layout of a 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 vertex_fields or cell_fields but not both. . . . . . . 48
4.6 Screenshot of PyLith Parameter Viewer in web browser upon startup. . . . . . . . . . . . . . . . . . . . . . . . . . 54
4.7 Screenshot of Version tab of the PyLith Parameter Viewer with sample JSON parameter file. . . . . . . . . . . . 55
4.8 Screenshot of Parameters tab of the PyLith Parameter Viewer with sample JSON parameter file before select-
ing a component in the left panel. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
4.9 Screenshot of Parameters tab of the PyLith Parameter Viewer with sample JSON parameter file with the
z_neg facility selected. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
5.1 Spring-dashpot 1D representations of the available 3D elastic and 2D/3D viscoelastic material models for
PyLith. The top model is a linear elastic model, the middle model is a Maxwell model, and the bottom model
is a generalized Maxwell model. For the generalized Maxwell model, λ and µt ot are specified for the entire
model, and then the ratio µi /µt ot is specified for each Maxwell model. For the power-law model, the linear
dashpot in the Maxwell model is replaced by a nonlinear dashpot obeying a power-law. . . . . . . . . . . . . . . 67
6.1 Orientation of a fault surface in 3D, where φ denotes the angle of the fault strike, δ denotes the angle of the
fault dip, and λ the rake angle. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
6.2 Sign conventions associated with fault slip. Positive values are associated with left-lateral, reverse, and fault
opening motions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
xiii
xiv LIST OF FIGURES
6.3 Example of cohesive cells inserted into a mesh of triangular cells. The zero thickness cohesive cells control slip
on the fault via the relative motion between the vertices on the positive and negative sides of the fault. . . . . . . 92
6.4 Example of how faults with buried edges must be described with two sets of vertices. All of the vertices on
the fault are included in the fault group; the subset of vertices along the buried edges are included in the
fault_edge group. In 2-D the fault edges are just a single vertex as shown in Figure 6.3 on page 92(a). . . . . 92
7.1 Mesh composed of two linear triangular cells used in the example problems. . . . . . . . . . . . . . . . . . . . . . 110
7.2 Color contours and vectors of displacement for the axial displacement example using a mesh composed of two
linear triangular cells. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
7.3 Color contours and vectors of displacement for the shear displacement example using a mesh composed of two
7.4 Color contours and vectors of displacement for the kinematic fault example using a mesh composed of two
7.5 Mesh composed of two bilinear quadrilateral cells used for the example problems. . . . . . . . . . . . . . . . . . 114
bilinear quadrilateral cells. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
7.9 Color contours and vectors of displacement for the axial traction example using a mesh composed of two
7.10 Mesh composed of two linear tetrahedral cells used for example problems. . . . . . . . . . . . . . . . . . . . . . . 119
linear tetrahedral cells. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
linear tetrahedral cells. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
7.13 Mesh composed of two trilinear hexahedral cells used for the example problems. . . . . . . . . . . . . . . . . . . 122
trilinear hexahedral cells. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
7.17 Mesh composed of two linear tetrahedral cells in a georeferenced coordinate system used for the example
problems. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
linear tetrahedral cells in a georeferenced coordinate system. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
7.19 Mesh composed of linear tetrahedral cells generated by LaGriT used for the example problems. The different
colors represent the different materials. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
7.20 Color contours and vectors of displacement for the axial displacement example using a mesh composed of
linear tetrahedral cells generated by LaGriT. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
LIST OF FIGURES xv
7.21 Color contours and vectors of displacement for the kinematic fault example using a mesh composed of linear
tetrahedral cells generated by LaGriT. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
7.22 Mesh composed of trilinear hexahedral cells generated by CUBIT used for the suite of example problems. The
different colors represent the two different materials. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
7.23 Displacement field for example step01 visualized using ParaView. The mesh has been distorted by the computed
displacements (magnified by 500), and the vectors show the computed displacements. . . . . . . . . . . . . . . . 140
7.26 Displacement field for example step04 at t = 200 years visualized using ParaView. The mesh has been distorted
by the computed displacements (magnified by 500), and the vectors show the computed displacements. . . . . . 145
7.29 Displacement field (color contours) and velocity field (vectors) for example step07 at t = 300 years visualized
using ParaView. The mesh has been distorted by the computed displacements (magnified by 500), and the
vectors show the computed velocities. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
7.30 The XY-component of strain (color contours) and displacement field (vectors) for example step08 at t = 150
years visualized using ParaView. For this visualization, we loaded both the step08-lower_crust.xmf
and step08-upper_crust.xmf files to contour the strain field, and superimposed on it the displacement
field vectors from step08.xmf. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
7.31 The XY-component of strain (color contours) and displacement field (vectors) for example step09 at t = 150
years visualized using ParaView. For this visualization, we loaded both the step09-lower_crust.xmf
and step09-upper_crust.xmf files to contour the strain field, and superimposed on it the displacement
field vectors from step09.xmf. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
7.32 Magnitude of tractions on the fault for example step10 visualized using ParaView. . . . . . . . . . . . . . . . . . 156
7.33 Magnitude of tractions on the fault for example step10 visualized using ParaView. Vectors of fault slip are
also plotted. Note that PyLith outputs slip in the fault coordinate system, so we transform them to the global
coordinate system using the Calculator in ParaView. A more general approach involves outputing the fault
coordinate system information and using these fields in the Calculator. . . . . . . . . . . . . . . . . . . . . . . . . 157
7.37 Displacement field for example step15 at t = 200 years visualized using ParaView. The z-component of the
displacement field is shown with the color contours, and the vectors show the computed displacements. . . . . . 161
7.38 Stress field (xx-component) for example step16 at t = 200 years visualized using ParaView. Note that for this
example, Stress_xx = Stress_yy = Stress_zz, and there is no vertical displacement throughout the simulation.
Also note that the stresses appear as four layers since we have used CellFilterAvg for material output. . . . . . . 162
xvi LIST OF FIGURES
7.39 Displacement field for example step17 at t = 200 years visualized using ParaView. The z-component of the
displacement field is shown with the color contours, and the vectors show the computed displacements. Note
the larger displacements compared with example step15. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
7.40 Displacement field for example step18 visualized using ParaView. The vectors show the displacement field
while the colors in the wireframe correspond to the z-component of the displacement field. . . . . . . . . . . . . 165
7.41 Stress field (zz-component) for example step19 at t = 200 years visualized using ParaView. The stresses appear
as four layers since we have used CellFilterAvg for material output. . . . . . . . . . . . . . . . . . . . . . . . . . . 166
7.42 Displacement magnitude for example step20 visualized using ParaView. . . . . . . . . . . . . . . . . . . . . . . . 167
7.43 A slip impulse and the resulting point displacement responses visualized using ParaView. . . . . . . . . . . . . . 169
7.44 Cartoon of subduction zone example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
7.45 Diagram of fault slip and boundary conditions for each step in the subduction zone example. . . . . . . . . . . . 170
7.46 Variable resolution finite-element mesh with triangular cells. The nominal cell size increases at a geometric
rate of 1.2 away from the region of coseismic slip. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
7.47 Solution for Step 1. The colors indicate the magnitude of the displacement, and the deformation is exaggerated
by a factor of 1000. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
7.48 Solution for Step 2 at 100 years. The colors indicate the magnitude of the displacement, and the deformation is
exaggerated by a factor of 1000. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
7.49 Solution for Step 3 at 150 years (immediately following the earthquake rupture). The colors indicate the mag-
nitude of the displacement, and the deformation is exaggerated by a factor of 1000. . . . . . . . . . . . . . . . . . 173
7.50 Solution for Step 4. The colors indicate the magnitude of the displacement. . . . . . . . . . . . . . . . . . . . . . 174
7.51 Domain for shear wave propagation in a 8.0 km bar with 400 m cross-section. We generate a shear wave via
slip on a fault located in the middle of the bar while limiting deformation to the transverse direction. . . . . . . . 175
7.52 Mesh composed of triangular cells generated by CUBIT used for the example problem. . . . . . . . . . . . . . . 176
7.53 Displacement field in the bar at 3.0 s. Deformation has been exaggerated by a factor of 800. . . . . . . . . . . . . 177
7.54 Mesh composed of hexahedral cells generated by CUBIT used for the example problem. . . . . . . . . . . . . . . 178
7.56 Velocity field in the bar at 3.0 s for the static friction fault constitutive model. Deformation has been exaggerated
by a factor of 20. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
7.57 Velocity field in the bar at 3.0 s for the slip-weakening friction fault constitutive model. Deformation has been
exaggerated by a factor of 20. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
7.58 Velocity field in the bar at 3.0 s for the rate- and state-friction fault constitutive model. Deformation has been
exaggerated by a factor of 20. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
7.59 Mesh composed of tetrahedral cells generated by LaGriT used for the example problem. . . . . . . . . . . . . . . 182
7.61 Mesh composed of hexahedral cells generated by CUBIT used for the example problem. . . . . . . . . . . . . . . 183
7.63 Mesh used for both forward and Green’s function computations for the strike-slip problem. Computed y-
displacements for the forward problem are shown with the color scale. . . . . . . . . . . . . . . . . . . . . . . . . 185
7.64 Applied fault slip for the strike-slip forward problem as well as computed x-displacements at a set of points. . . 187
7.65 Applied fault slip and computed responses (at points) for the seventh Green’s function generated for the strike-
slip fault example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
LIST OF FIGURES xvii
7.66 Inversion results from running Python plotting script. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
7.67 Mesh used for 2d gravity simulations with a 30 km thick elastic crust over a 70 km thick linear Maxwell
viscoelastic layer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
7.68 Spatial variation in density in the finite element mesh. The mantle has a uniform density of 3400 kg/m3 and the
crust has a uniform density of 2500 kg/m3 except near the origin where we impose a low density semi-circular
region. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
7.69 Shear stress in the crust (linearly elastic) and mantle (linear Maxwell viscoelastic) associated gravitational body
forces and a low density region forces. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
7.70 Vertical displacement at the end of the postseismic deformation simulation (t=4000 years). . . . . . . . . . . . . 193
7.71 Displacement field on the ground surface after 2550 years of postseismic deformation in Step 4 (Infinitesimal
strain without gravity), Step 5 (Finite strain without gravity), Step 6 (Infinitesimal strain with gravity), and 7
(Finite strain with gravity). The displacement fields for Steps 4-6 are essentially identical. . . . . . . . . . . . . . 194
7.72 Cauchy shear stress at the end of the simulation of postseismic deformation with variable density in the crust.
We saturate the color scale at ±1 MPa to show the evidence of viscoelastic relaxation (near zero shear stress) in
the mantle. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
8.1 Geometry of strike-slip benchmark problem. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198

8.2 Displacement field for strike-slip benchmark problem. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
8.3 Local error for strike-slip benchmark problem with tetrahedral cells and linear basis functions with a uniform
discretization size of 1000 m. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
8.4 Local error for strike-slip benchmark problem with hexahedral cells and trilinear basis functions with a uniform
discretization size of 1000 m. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
discretization size of 500 m. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
8.9 Convergence rate for the strike-slip benchmark problem with tetrahedral cells and linear basis functions and
with hexahedral cells with trilinear basis functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
8.10 Summary of performance of PyLith for the six simulations of the strike-slip benchmark. For a given dis-
cretization size, hexahedral cells with trilinear basis functions provide greater accuracy with a shorter runtime
compared with tetrahedral cells and linear basis functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
8.11 Parallel performance of PyLith for the strike-slip benchmark problem with tetrahedral cells and linear basis
functions with a uniform discretization size of 500 m. The total runtime (total) and the runtime to compute the
Jacobian and residual and solve the system (compute) are shown. The compute runtime decreases with a slope
of about 0.7; a linear decrease with a slope of 1 would indicate strong scaling, which is rarely achieved in any
real application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
8.12 Problem description for the Savage and Prescott strike-slip benchmark problem. . . . . . . . . . . . . . . . . . . . 206
8.13 Displacement profiles perpendicular to the fault for a PyLith simulation with hex8 cells and the analytical
solution for earthquake cycle 10. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
xviii LIST OF FIGURES
C.1 Diagram of mesh specified in the MeshIOAscii file. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
E.1 Problem with constant traction boundary conditions applied along right edge. . . . . . . . . . . . . . . . . . . . . 234
List of Tables
2.1 Mathematical notation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
4.1 Pyre supported units. Aliases are in parentheses. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

4.2 Useful command-line arguments for setting PETSc options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
4.3 PETSc options that provide moderate performance in a wide range of quasi-static elasticity problems. . . . . . . 35
4.4 PETSc options used with split fields algebraic multigrid preconditioning that often provide improved perfor-
mance in quasi-static elasticity problems with faults. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
5.1 Properties and state variables available for output for existing material models. Physical properties are available
for output as cell_info_fields and state variables are available for output as cell_data_fields. . . 61
5.2 Order of components in tensor state-variables for material models. . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
5.3 Values in spatial database for initial state variables for 3D problems. 2D problems use only the relevant values.
Note that initial stress and strain are available for all material models. Some models have additional state
variables (Table 5.1 on page 61) and initial values for these may also be provided. . . . . . . . . . . . . . . . . . . 63
5.4 Values in spatial databases for the elastic material constitutive models. . . . . . . . . . . . . . . . . . . . . . . . . 65
5.5 Available viscoelastic materials for PyLith. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
5.6 Values in spatial databases for the linear Maxwell viscoelastic material constitutive model. . . . . . . . . . . . . . 71
5.7 Values in spatial database used as parameters in the generalized linear Maxwell viscoelastic material constitutive
model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
5.8 Values in spatial database used as parameters in the nonlinear power-law viscoelastic material constitutive model. 77
5.9 Options for fitting the Drucker-Prager plastic parameters to a Mohr-Coulomb model using fit_mohr_coulomb. 78
5.10 Values in spatial database used as parameters in the Drucker-Prager elastoplastic model with perfect plasticity. . 81
6.1 Fields available in output of DirichletBoundary boundary condition information. . . . . . . . . . . . . . . . . . . 85

6.2 Values in the spatial databases used for Dirichlet boundary conditions. . . . . . . . . . . . . . . . . . . . . . . . . 85
6.3 Fields available in output of Neumann boundary condition information. . . . . . . . . . . . . . . . . . . . . . . . 86
6.4 Values in the spatial databases used for Dirichlet boundary conditions in three dimensions. In one- and two-
dimensional problems, the names of the components are slightly different as described earlier in this section. . . 87
6.5 Values in the spatial databases used for point force boundary conditions. . . . . . . . . . . . . . . . . . . . . . . . 88
6.6 Fields available in output of fault information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
6.7 Values in spatial database used as parameters in the step function slip time function. . . . . . . . . . . . . . . . . 97
xix
xx LIST OF TABLES
6.8 Values in spatial database used as parameters in the constant slip rate slip time function. . . . . . . . . . . . . . . 97
6.9 Values in spatial database used as parameters in the Brune slip time function. . . . . . . . . . . . . . . . . . . . . 98
6.10 Values in spatial database used as parameters in the time history slip time function. . . . . . . . . . . . . . . . . . 99
6.11 Values in spatial databases for prescribed tractions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
6.12 Fields available in output of fault information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
6.13 Values in the spatial database for constant friction parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
6.14 Values in spatial databases for slip-weakening friction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
6.15 Values in spatial databases for time-weakening friction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
6.16 Values in spatial databases for a simple slip- and time-weakening friction model. . . . . . . . . . . . . . . . . . . 104
6.17 Values in spatial databases for a second slip- and time-weakening friction model. . . . . . . . . . . . . . . . . . . 105
6.18 Values in spatial databases for Dieterich-Ruina rate-state friction. . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
7.1 Number of iterations in linear solve for the Shear Displacement and Kinematic Fault Slip problems discussed in
this section. The preconditioner using split fields and an algebraic multigrid algorithm solves the linear system
with fewer iterations with only a small to moderate increase as the problem size grows. . . . . . . . . . . . . . . . 133
Preface
0.1 About This Document

This document is organized into two parts. The first part begins with an introduction to PyLith and discusses the types of
problems that PyLith can solve and how to run the software; the second part provides appendices and references.
0.2 Who Will Use This Documentation

This documentation is aimed at two categories of users: scientists who prefer to use prepackaged and specialized analysis tools,
and experienced computational Earth scientists. Of the latter, there are likely to be two classes of users: those who just run
models, and those who modify the source code. Users who modify the source are likely to have familiarity with scripting,
software installation, and programming, but are not necessarily professional programmers.
0.3 Conventions
L Warning
This is a warning.
B Important
This is something important.
H Tip
This is a tip, helpful hint, or suggestion.
For features recently added to PyLith, we show the version number when they were added. New in v2.2.0
0.3.1 Command Line Arguments
Exmaple of a command line argument: --help.
xxi
xxii PREFACE
0.3.2 Filenames and Directories
Example of filenames and directories: pylith, /usr/local.
0.3.3 Unix Shell Commands
Commands entered into a Unix shell (i.e., terminal) are shown in a box. Comments are delimited by the # character. We use
$$ to indicate the bash shell prompt.
# This is a comment.
$$ ls -l
0.3.4 Excerpts of cfg Files
Example of an excerpt from a .cfg file:

[pylithapp.problem]
timestep = 2.0*s ; Time step comment.
bc = [x_pos, x_neg]
0.4 Citation
The Computational Infrastructure for Geodynamics (CIG) (geodynamics.org) is making this source code available to you
at no cost in hopes that the software will enhance your research in geophysics. A number of individuals have contributed a
significant portion of their careers toward the development of this software. It is essential that you recognize these individuals in
the normal scientific practice by citing the appropriate peer-reviewed papers and making appropriate acknowledgments in talks
and publications. The preferred way to generate the list of publications (in BibTEX format) to cite is to run your simulations
with the --include-citations command line argument, or equivalently, the --petsc.citations command line
argument. The --help-citations command line argument will generate the BibTEX entries for the references mentioned
below.
The following peer-reviewed paper discussed the development of PyLith:
• Aagaard, B. T., M. G. Knepley, and C. A. Williams (2013). A domain decomposition approach to implementing fault
slip in finite-element models of quasi-static and dynamic crustal deformation, Journal of Geophysical Research: Solid
Earth, 118, doi: 10.1002/jgrb.50217.
To cite the software and manual, use:
• Aagaard, B., M. Knepley, C. Williams (2017), PyLith v2.2.0. Davis, CA: Computational Infrastructure of Geodynamics.
DOI: 10.5281/zenodo.438705.
• Aagaard, B., M. Knepley, C. Williams (2017), PyLith User Manual, Version 2.2.0. Davis, CA: Computational Infrastruc-
ture of Geodynamics. URL: geodynamics.org/cig/software/github/pylith/v2.2.0/pylith-2.2.0_manual.pdf
0.5 Support
Current PyLith development is supported by the CIG, and internal GNS Science www.gns.cri.nz and U.S. Geological
Survey www.usgs.gov funding. Pyre development was funded by the Department of Energy’s www.doe.gov/engine/
0.6. ACKNOWLEDGMENTS xxiii
content.do Advanced Simulation and Computing program and the National Science Foundation’s Information Technology
Research (ITR) program.
This material is based upon work supported by the National Science Foundation under Grants No. 0313238, 0745391,
and EAR-0949446. Any opinions, findings, and conclusions or recommendations expressed in this material are those of the
author(s) and do not necessarily reflect the views of the National Science Foundation.
0.6 Acknowledgments
Many members of the community contribute to PyLith through reporting bugs, suggesting new features and improvements,
running benchmarks, and asking questions about the software. In particular, we thank Surendra Somala for contributing to the
development of the fault friction implementation.
0.7 Request for Comments

Your suggestions and corrections can only improve this documentation. Please report any errors, inaccuracies, or typos to the
CIG Short-Term Tectonics email list [email protected].
xxiv PREFACE
Chapter 1
Introduction
1.1 Overview
PyLith is is portable, scalable software for simulation of crustal deformation across spatial scales ranging from meters to
hundreds of kilometers and temporal scales ranging from milliseconds to thousands of years. Its primary applications are
quasi-static and dynamic modeling of earthquake faulting.
1.2 New in PyLith Version 2.2.0

• Added a browser-based parameter viewer for interactive viewing of all PyLith parameters and version information. See
Section 4.10.
• Converted the user manual from Lyx to LaTeX and added syntax highlighting of parameter and spatial database files.
Fixed several typos.
• Fixed bug that sometimes resulted in an inconsistent fault orientation when running in parallel. The bug appears to have
been introduced in v2.0.
• Fixed two bugs in output of solution at points that sometimes happened in parallel simulations. The errors include:
– The order of the station names does not match the order of the points. The point data is written in parallel by process
order, so the points for process 0 are written first, then those for process 1, etc. This often results in reordering of
the points. The station names were written in the original order.
– The output values for some points are incorrect. The wrong cells were being used in the interpolation.
• Updated PETSc to v3.7.5.
The CHANGES file in the top-level source directory contains a summary of features and bugfixes for each release.
1.3 History
PyLith 1.0 was the first version to allow the solution of both implicit (quasi-static) and explicit (dynamic) problems and was a
complete rewrite of the original PyLith (version 0.8). PyLith 1.0 combines the functionality of EqSim [Aagaard et al., 2001a,
Aagaard et al., 2001b] and PyLith 0.8. PyLith 0.8 was a direct descendant of LithoMop and was the first version that ran in
parallel, as well as providing several other improvements over LithoMop. LithoMop was the product of major reengineering
of Tecton, a finite-element code for simulating static and quasi-static crustal deformation. The major new features present in
LithoMop included dynamic memory allocation and the use of the Pyre simulation framework and PETSc solvers. EqSim
was written by Brad Aagaard to solve problems in earthquake dynamics, including rupture propagation and seismic wave
propagation.
1
2 CHAPTER 1. INTRODUCTION
The release of PyLith 1.0 has been followed by additional releases that expand the number of features as well as improve
performance. The PyLith 1.x series of releases allows the solution of both quasi-static and dynamic problems in one, two,
or three dimensions. The code runs in either serial or parallel, and the design allows for relatively easy scripting using the
Python programming language. Material properties and values for boundary and fault conditions are specified using spatial
databases, which permit easy prescription of complex spatial variations of properties and parameters. Simulation parameters
are generally specified through the use of simple ASCII files or the command line. At present, mesh information may be pro-
vided using a simple ASCII file (PyLith mesh ASCII format) or imported from CUBIT or LaGriT, two widely-used meshing
packages. The elements currently available include a linear bar in 1D, linear triangles and quadrilaterals in 2D, and linear
tetrahedra and hexahedra in 3D. Materials presently available include isotropic elastic, linear Maxwell viscoelastic, general-
ized Maxwell viscoelastic, power-law viscoelastic, and Drucker-Prager elastoplastic. Boundary conditions include Dirichlet
(prescribed displacements and velocities), Neumann (traction), point forces, and absorbing boundaries. Cohesive elements are
used to implement slip across interior surfaces (faults) with both kinematically-specified fault slip and slip governed by fault
constitutive models. PyLith also includes an interface for computing static Green’s functions for fault slip.
PyLith 2.0 replaces the finite-element data structures provided by the C++ Sieve implementation with those provided by
the C DMPlex implementation. The newly developed DMPlex implementation by the PETSc developers conforms to the
PETSc data manager (DM) interface, thereby providing tighter integration with other PETSc data structures, such as vectors
and matrices. Other improvements include significantly reduced memory use and memory balancing.
PyLith is under active development and we expect a number of additions and improvements in the near future. Likely
enhancements will include additional bulk and fault constitutive models, coupled quasi-static and dynamic simulations for
earthquake cycle modeling, and coupling between elasticity, heat flow, and/or fluid flow.
1.4 PyLith Workflow

PyLith is one component in the process of investigating problems in tectonics (Figure 1.1). Given a geological problem of
interest, a scientist must first provide a geometrical representation of the desired structure. Once the structure has been defined,
a computational mesh must be created. PyLith presently provides three mesh importing options: CUBIT Exodus format,
LaGriT GMV and Pset files, and PyLith mesh ASCII format. The modeling of the physical processes of interest is performed
by a code such as PyLith. Present output consists of VTK or HDF5/Xdmf files which can be used by a number of visualization
codes (e.g., ParaView, Visit, and Matlab).
Geologic Mesh
Physics Code Visualization
Structure Generation
Gocad CUBIT PyLith ParaView
Earth Vision LaGriT Relax Visit
TetGen GeoFEST Matlab
Gmsh Abaqus Matplotlib
GMT
CIG Free Available
Open Source Commercial Planned
Figure 1.1: Workflow involved in going from geologic structure to problem analysis.
1.5. PYLITH DESIGN 3
1.5 PyLith Design
PyLith is separated into modules to encapsulate behavior and facilitate use across multiple applications. This allows expert
users to replace functionality of a wide variety of components without recompiling or polluting the main code. PyLith employs
external packages (see Figure 1.2) to reduce development time and enhance computational efficiency; for example, PyLith 0.8
ran two times faster when the PETSc linear solver was used.
PyLith
PETSc spatialdata FIAT
NetCDF HDF5 Proj.4 Pyre numpy
BLAS/LAPACK MPI
Figure 1.2: PyLith dependencies. PyLith makes direct use of several other packages, some of which have their own dependen-
cies.
PyLith is written in two programming languages. High-level code is written in Python; this rich, expressive interpreted
language with dynamic typing reduces development time and permits flexible addition of user-contributed modules. This high-
level code makes use of Pyre, a science-neutral simulation framework developed at Caltech, to link the modules together at
runtime and gather user-input. Low-level code is written in C++, providing fast execution while still allowing an object-oriented
implementation. This low-level code relies on PETSc to perform operations on matrices and vectors in parallel. We also make
extensive use of two Python packages. SWIG is a package that simplifies the task of adding C++ extensions to Python code,
and FIAT provides tabulated basis functions and numerical quadrature points.
In writing PyLith 1.0, the code was designed to be object-oriented and modular. Each type of module is accessed through
a specified interface (set of functions). This permits adding, replacing, and rewriting modules without affecting other parts of
the code. This code structure simplifies code maintenance and development. Extending the set of code features is also easier,
since developers can create new modules derived from the existing ones.
The current code design leverages Pyre and PETSc extensively. Pyre glues together the various modules used to construct
a simulation and specify the parameters. PETSc provides the finite-element data structures and handles the creation and manip-
ulation of matrices and vectors. As a result, most of the PyLith source code pertains to implementing the geodynamics, such as
bulk rheology, boundary conditions, and slip on faults.
PyLith also uses FIAT to tabulate the finite-element basis functions at the numerical integration (quadrature) points. Neme-
sis allows PyLith to run Python using the Message Passing Interface (MPI) for parallel processing. Additional, indirect depen-
dencies (see Figure 1.2) include numpy (efficient operations on numerical arrays in Python), Proj.4 (geographic projections),
and SWIG (calling C++ functions from Python).
During development, tests were constructed for nearly every module function. These unit tests are distributed with the
source code. These tests are run throughout the development cycle to expose bugs and isolate their origin. As additional
changes are made to the code, the tests are rerun to help prevent introduction of new bugs. A number of simple, full-scale
tests, such as axial compression and extension, simple shear, and slip on through-going faults, have been used to test the code.
Additionally, we have run the Southern California Earthquake Center crustal deformation and several of the spontaneous rupture
benchmarks for strike-slip and reverse-slip to determine the relative local and global error (see Chapter 8 on page 197).
1.5.1 Pyre
Pyre is an object-oriented environment capable of specifying and launching numerical simulations on multiple platforms, in-
cluding Beowulf-class parallel computers and grid computing systems. Pyre allows the binding of multiple components such
as solid and fluid models used in Earth science simulations, and different meshers. The Pyre framework enables the elegant
setup, modification and launching of massively parallel solver applications.
service
component
component
python
python
bindings
bindings
package
package
framework custom
custom code
code
facility
facility facility
facility
facility
facility facility
facility
core extension
component
component component
component
requirement
requirement bindings
bindings
bindings
bindings
custom library
library
custom code
code implementation
implementation
FORTRAN/C/C++
FORTRAN/C/C++
Figure 1.3: Pyre Architecture. The integration framework is a set of cooperating abstract services.
Pyre is a framework, a combination of software and design philosophy that promotes the reuse of code. In their canonical
software design book, Design Patterns, Erich Gamma et al. condense the concept of a framework concept down to, “When
you use a framework, you reuse the main body and write the code it calls.” In the context of frameworks and object-oriented
programming, Pyre can be thought of as a collection of classes and the way their instances interact. Programming applications
based on Pyre will look similar to those written in any other object-oriented language. The Pyre framework contains a subset
of parts that make up the overall framework. Each of those parts is designed to solve a specific problem.
The framework approach to computation offers many advantages. It permits the exchange of codes and promotes the reuse
of standardized software while preserving efficiency. Frameworks are also an efficient way to handle changes in computer
architecture. They present programmers and scientists with a unified and well-defined task and allow for shared costs of
the housekeeping aspects of software development. They provide greater institutional continuity to model development than
piecemeal approaches.
The Pyre framework incorporates features aimed at enabling the scientific non-expert to perform tasks easily without
hindering the expert. Target features for end users allow complete and intuitive simulation specification, reasonable defaults,
consistency checks of input, good diagnostics, easy access to remote facilities, and status monitoring. Target features for
developers include easy access to user input, a shorter development cycle, and good debugging support.
1.5.2 PETSc
PyLith 2.x makes use of a set of data structures and routines in PETSc called DMPlex, which is still under active development.
DMPlex provides data structures and routines for for representing and manipulating computational meshes, and it greatly
simplifies finite-element computations.DMPlex represents the topology of the domain. Zero volume elements are inserted along
all fault surfaces to implement kinematic (prescribed) or dynamic (constitutive model) implementations of fault slip. Material
properties and other parameters are represented as scalar and vector fields over the mesh using vectors to store the values and
sections to map vertices, edges, faces, and cells to indices in the vector. For each problem, functions are provided to calculate
the residual and its Jacobian. All numerical integration is done in these functions, and parallel assembly is accomplished using
the get/set closure paradigm of the DMPlex framework. We assemble into PETSc linear algebra objects and then call PETSc
solvers.
PETSc www-unix.mcs.anl.gov/petsc/petsc-as, the Portable, Extensible Toolkit for Scientific computation,
provides a suite of routines for parallel, numerical solution of partial differential equations for linear and nonlinear systems with
large, sparse systems of equations. PETSc includes solvers that implement a variety of Newton and Krylov subspace methods.
It can also interface with many external packages, including ESSL, MUMPS, Matlab, ParMETIS, PVODE, and Hypre, thereby
1.5. PYLITH DESIGN 5
providing additional solvers and interaction with other software packages.
PETSc includes interfaces for FORTRAN 77/90, C, C++, and Python for nearly all of the routines, and PETSc can be
installed on most Unix systems. PETSc can be built with user-supplied, highly optimized linear algebra routines (e.g., ATLAS
and commercial versions of BLAS/LAPACK), thereby improving application performance. Users can use PETSc parallel
matrices, vectors, and other data structures for most parallel operations, eliminating the need for explicit calls to Message
Passing Interface (MPI) routines. Many settings and options can be controlled with PETSc-specific command-line arguments,
including selection of preconditions, solvers, and generation of performance logs.
Chapter 2
Governing Equations
We present here a brief derivation of the equations for both quasi-static and dynamic computations. Since the general equations
are the same (except for the absence of inertial terms in the quasi-static case), we first derive these equations. We then present
solution methods for each specific case. In all of our derivations, we use the notation described in Table 2.1 for both index and
vector notation. When using index notation, we use the common convention that repeated indices indicate summation over the
range of the index.
Table 2.1: Mathematical notation

Symbol Description
Index notation Vector Notation
ai →
−
a Vector field a
ai j a Second order tensor field a
ui →
−
u Displacement vector field
di d~ Fault slip vector field
→
−
fi f Body force vector field
→
−
Ti T Traction vector field
σi j σ Stress tensor field
ni →
−
n Normal vector field
ρ ρ Mass density scalar field
2.1 Derivation of Elasticity Equation
2.1.1 Index Notation
Consider volume V bounded by surface S . Applying a Lagrangian description of the conservation of momentum gives
∂ ∂u i
Z Z Z
ρ dV = f i dV + Ti d S. (2.1)
∂t V ∂t V S
The traction vector field is related to the stress tensor through
Ti = σi j n j , (2.2)
where n j is the vector normal to S . Substituting into equation 2.1 yields
∂ ∂u i
Z Z Z
ρ dV = f i dV + σi j n j d S. (2.3)
∂t V ∂t V S
7
8 CHAPTER 2. GOVERNING EQUATIONS
Applying the divergence theorem, Z Z
a i , j dV = a j n j d S, (2.4)
V S
to the surface integral results in
∂ ∂u i
Z Z Z
ρ dV = f i dV + σi j , j dV, (2.5)
∂t V ∂t V V
which we can rewrite as Z µ 2
∂ ui
¶
ρ 2 − f i − σi j , j dV = 0. (2.6)
V ∂t
Because the volume V is arbitrary, the integrand must be zero at every location in the volume, so that we end up with
∂2 u i
ρ − f i − σi j , j = 0 in V, (2.7)
∂t 2
σi j n j = Ti on S T , (2.8)
u i = u io on S u , and (2.9)
R ki (u i+ − u i− ) = d k on S f . (2.10)
We specify tractions, Ti , on surface S f , displacements, u io , on surface S u , and slip, dk , on fault surface S f (we will consider
the case of fault constitutive models in Section 6.4 on page 90). The rotation matrix R ki transforms vectors from the global
coordinate system to the fault coordinate system. Note that since both Ti and u i are vector quantities, there can be some spatial
overlap of the surfaces S T and S u ; however, the same degree of freedom cannot simultaneously have both types of boundary
conditions.
2.1.2 Vector Notation
Consider volume V bounded by surface S . Applying a Lagrangian description of the conservation of momentum gives
∂ ∂~
u →
−
Z Z Z
→
−
ρ dV = f dV + T d S. (2.11)
∂t V ∂t V S
The traction vector field is related to the stress tensor through

→
−
T = σ·→
−
n, (2.12)
where →
−
n is the vector normal to S . Substituting into equation 2.11 yields
∂ ∂→
−u →
−
Z Z Z
ρ dV = f dV + σ · →
−
n d S. (2.13)
∂t V ∂t V S
Applying the divergence theorem, Z Z

∇·→
−
a dV = →
−
a ·→
−
n d S, (2.14)
V S
to the surface integral results in
∂ ∂→
−
u →
−
Z Z Z
ρ dV = f dV + ∇ · σ dV, (2.15)
∂t V ∂t V V
which we can rewrite as Z µ 2→
∂ −
u →
¶
−
ρ 2 − f −∇·→
−
σ dV =~0. (2.16)
V ∂t
Because the volume V is arbitrary, the integrand must be the zero vector at every location in the volume, so that we end up with
∂2 →
−
u →−
ρ − f −∇·→
−σ =~0 in V, (2.17)
∂t 2
→
−
σ·→
−
n = T on S , T (2.18)
→
− −
→
u = u o on S u , and (2.19)
R · (u~+ − u~− ) = d~ on S f . (2.20)
2.2. FINITE-ELEMENT FORMULATION OF ELASTICITY EQUATION 9
−
→
~ , on surface S f , displacements, u o , on surface S u , and slip, d~, on fault surface S f (we will consider
We specify tractions, T
the case of fault constitutive models in Section 6.4 on page 90). The rotation matrix R transforms vectors from the global
→
−
coordinate system to the fault coordinate system. Note that since both T and → −
u are vector quantities, there can be some spatial
overlap of the surfaces S T and S u ; however, the same degree of freedom cannot simultaneously have both types of boundary
conditions.
2.2 Finite-Element Formulation of Elasticity Equation

We formulate a set of algebraic equations using Galerkin’s method. We consider (1) a trial solution, ~ u , that is a piecewise
differentiable vector field and satisfies the Dirichlet boundary conditions on S u , and (2) a weighting function, φ ~ , that is a
piecewise differentiable vector field and is zero on S u .
2.2.1 Index Notation
We start with the wave equation (strong form),

σi j , j + f i = ρ u¨i in V, (2.21)
σi j n j = Ti on S T , (2.22)
u i = u io on S u , (2.23)
R ki (u i+ − u i− ) = d k on S f , and (2.24)
σi j = σ j i (symmetric). (2.25)
We construct the weak form by computing the dot product of the wave equation and weighting function and setting the integral
over the domain to zero:
Z
σi j , j + f i − ρ ü i φi dV = 0, or
¡ ¢
(2.26)
V
Z Z Z
σi j , j φi dV + f i φi dV − ρ ü i φi dV = 0. (2.27)
V V V
Consider the divergence theorem applied to the dot product of the stress tensor and the weighting function, σi j φi ,
Z Z
(σi j φi ), j dV = (σi j φi )n i d S. (2.28)
V S
Expanding the left-hand side yields

Z Z Z
σi j , j φi dV +
σi j φi , j dV = σi j φi n i d S, or (2.29)
ZV V
Z S
Z
σi j , j φi dV = − σi j φi , j dV + σi j φi n i d S. (2.30)
V V S
Substituting into the weak form gives

Z Z Z Z
− σi j φi , j dV + σi j φi n i d S + f i φi dV − ρ ü i φi dV = 0. (2.31)
V S V V
Turning our attention to the second term, we separate the integration over S into integration over S T and S u (we will consider
tractions over the fault surface, S f , associated with the fault constitutive model in Section 6.4 on page 90),
Z Z Z Z Z
− σi j φi , j dV + σi j φi n i d S + σi j φi n i d S + f i φi dV − ρ ü i φi dV = 0, (2.32)
V ST Su V V
and recognize that

σi j n i = Ti on S T and (2.33)
φi = 0 on S u , (2.34)
so that the equation reduces to
Z Z Z Z
− σi j φi , j dV + Ti φi d S + f i φi dV − ρ ü i φi dV = 0. (2.35)
V ST V V
We express the trial solution and weighting function as linear combinations of basis functions,
a im N m ,
X
ui = (2.36)
m
φi = c in N n .
X
(2.37)
n
Note that because the trial solution satisfies the Dirichlet boundary condition, the number of basis functions for u is generally
greater than the number of basis functions for φ, i.e., m > n . Substituting in the expressions for the trial solution and weighting
function yields
Z Z Z Z
σi j c in N,nj dV + Ti c in N n d S + f i c in N n dV − ρ ä im N m c in N n dV = 0, or
X X X X X
− (2.38)
V n ST n V n V m n
X n Z n
Z
n
Z
n
Z X m m n
c i (− σi j N, j dV + Ti N d S + f i N dV − ρ ä i N N dV ) = 0. (2.39)
n V ST V V m
Because the weighting function is arbitrary, this equation must hold for all c in , so that the quantity in parenthesis is zero for
each c in Z Z Z Z
− σi j N,nj dV + Ti N n d S + f i N n dV − ρ ä im N m N n dV =~0.
X
(2.40)
V ST V V m
We want to solve this equation for the unknown coefficients a im subject to
u i = u io on S u , and (2.41)
R ki (u i+ − u i− ) = d k on S f , (2.42)
2.2.2 Vector Notation
We start with the wave equation (strong form),
→
− ∂2 →
−
u
∇ · σ + f = ρ 2 in V, (2.43)
∂t
→
−
σ·→ −
n = T on S T , (2.44)
→
− −
→
u = u o on S u , (2.45)
−→ −→
R · (u + − u − ) = d~ on S f (2.46)
T
σ = σ (symmetric). (2.47)
We construct the weak form by multiplying the wave equation by a weighting function and setting the integral over the domain
→
− →
−
to zero. The weighting function is a piecewise differential vector field, φ , where φ = 0 on S u . Hence our weak form is
∂2 →
−
u →
Z µ ¶
→− −
∇ · σ + f − ρ 2 · φ dV = 0, or (2.48)
V ∂t
→
− → ∂2 →
−
u →
Z Z Z
→
− − −
(∇ · σ) · φ dV + f · φ dV − ρ 2 · φ dV = 0. (2.49)
V V V ∂t
→
−
Consider the divergence theorem applied to the dot product of the stress tensor and the trial function, σ · φ ,
Z Z
→
− →
− −
∇ · (σ · φ ) dV = (σ · φ ) · →
n d S. (2.50)
V S
2.2. FINITE-ELEMENT FORMULATION OF ELASTICITY EQUATION 11
Expanding the left-hand side yields
Z Z Z
→
− →
− →
− −
(∇ · σ) · φ dV + σ : ∇ φ dV = (σ · φ ) · →
n d S, or (2.51)
V V S
Z Z Z
→
− →
− →
−
(∇ · σ) · φ dV = − σ : ∇ φ dV + σ·→
−
n · φ d S. (2.52)
V V S
Substituting into the weak form gives
→
− → ∂2 →
−
u →
Z Z Z Z
→
− →
− − −
− σ : ∇ φ dV + σ·→
−
n · φ dS + f · φ dV − ρ · φ dV = 0. (2.53)
V S V V ∂t 2
We separate the integration over S into integration over S T and S u ,
→
− → ∂2 →
−
u
Z Z Z Z Z
→
− →
− →
− − →
−
− σ : ∇ φ dV + σ · →
−
n · φ dS + σ · →
−
n · φ dS + f · φ dV − ρ · φ dV = 0, (2.54)
V ST Su V V ∂t 2
and recognize that

→
−
σ·→
−
n = T on S T and (2.55)
→
−
φ = 0 on S u , (2.56)
so that the equation reduces to
→
− → ∂2 →
−
u →
Z Z Z Z
→
− →
− →− − −
− σ : ∇ φ dV + T · φ dS + f · φ dV − ρ · φ dV = 0. (2.57)
V ST V V ∂t 2
We express the trial solution and weighting function as linear combinations of basis functions,
X −→
~
u= am N m , (2.58)
m
X−
→
~=
φ cn N n. (2.59)
n
Note that because the weighting function is zero on S u , the number of basis functions for ~ u is generally greater than the number
~ , i.e., m > n . Substituting in the expressions for the trial solution and weighting function yields
of basis functions for φ
Z X−
→
Z X−
→
Z X−
→
− σ: c n ∇N,n dV + ~·
T cn N n dS + ~f · c n N n dV
V n ST n V n
−→
Z X ∂2 a m X−
→
− ρ Nm · c n N n dV = 0. (2.60)
V m ∂t 2 n
−
→
Because the weighting function is arbitrary, this equation must hold for all c n , so that
−→
Z Z Z Z X ∂2 a m
− σ : ∇N n dV + ~Nn dS +
T ~
f N n dV − ρ N m N n dV =~0. (2.61)
V ST V V m ∂t 2
−→
We want to solve this equation for the unknown coefficients a m subject to
u = uo →
~ − on S u , and (2.62)
−→ −→
R(u + − u − ) = d~ on S f , (2.63)
2.3 Solution Method for Quasi-Static Problems
For brevity we outline the solution method for quasi-static problems using only index notation. In quasi-static problems we
neglect the inertial terms, so equation (2.40) reduces to
Z Z Z
− σi j N,nj dV + n
Ti N d S + f i N n dV =~0. (2.64)
V ST V
As a result, time-dependence only enters through the constitutive relationships and the loading conditions. We consider the
deformation at time t + ∆t ,
Z Z Z
− σi j (t + ∆t )N,nj dV + Ti (t + ∆t )N n d S + f i (t + ∆t )N n dV =~0. (2.65)
V ST V
We solve this equation through formulation of a linear algebraic system of equations ( Au = b ), involving the residual (r =
b − Au ) and Jacobian ( A ). The residual is simply
Z Z Z
r in = − σi j (t + ∆t )N,nj dV + Ti (t + ∆t )N n d S + f i (t + ∆t )N n dV. (2.66)
V ST V
We employ numerical quadrature in the finite-element discretization and replace the integrals with sums over the cells and
quadrature points,
r in = − σi j (x q , t + ∆t )N,nj (x q ) w q |J cel l (x q )| + f i (x q , t + ∆t )N n (x q ) w q |J cel l (x q )|

X X X X
vol cells quad pts vol cells quad pts
Ti (x q , t + ∆t )N n (x q ) w q |J cel l (x q )|,
X X
+ (2.67)
tract cells quad pts
where r in is an nd vector (d is the dimension of the vector space) and i is a vector space component, x q are the coordinates
of the quadrature points, w q are the weights of the quadrature points, and |J cel l (x q )| is the determinant of the Jacobian matrix
evaluated at the quadrature points associated with mapping the reference cell to the actual cell. The quadrature scheme for the
integral over the tractions is one dimension lower than the one used in integrating the terms for the volume cells.
In order to find the Jacobian of the system, we let
σi j (t + ∆t ) = σi j (t ) + d σi j (t ). (2.68)
Isolating the term associated with the increment in stresses yields

Z Z Z Z
d σi j (t )N jn dV = − σi j (t )N,nj dV + Ti (t + ∆t )N n d S + f i (t + ∆t )N n dV (2.69)
V V ST V
We associate the term on the left-hand-side with the action of the system Jacobian on the increment of the displacement field.
We approximate the increment in stresses using linear elasticity and infinitesimal strains,
d σi j (t ) = C i j kl (t )d εkl (t ) (2.70)
1
d σi j (t ) = C i j kl (t )(d u k.l (t ) + d u l ,k (t )) (2.71)
2
1 X m
d σi j (t ) = C i j kl (t )( d a k,l (t )N m + d a lm,k (t )N m )
X
(2.72)
2 m m
Now, d σi j φi , j is a scalar, so it is symmetric,

d σi j φi , j = d σ j i φ j ,i , (2.73)
and we know that d σi j is symmetric, so
d σi j φi , j = d σi j φ j ,i , (2.74)
2.4. SOLUTION METHOD FOR DYNAMIC PROBLEMS 13
which means
φi , j = φ j ,i , (2.75)
which we can write as
1
φi , j = (φi , j + φ j ,i ). (2.76)
2
In terms of the basis functions, we have
1 X
c in N,nj = ( c in N,nj + c nj N,in ).
X X
(2.77)
n 2 n n
Combining these expressions for the increment in stresses and making use of the symmetry of the weighting functions, we find
the system Jacobian is
1
Z
A nm
ij = C i j kl (N,lm + N,k
m
)(N,nj + N,in ) dV. (2.78)
V 4
We employ numerical quadrature in the finite-element discretization and replace the integral with a sum over the cells and
quadrature points,
1
A nm m
C i j kl (N,lm (x q ) + N,k (x q ))(N,nj (x q ) + N,in (x q ))w q |J cel l (x q ).
X X
ij = (2.79)
vol cells quad pts 4
2.4 Solution Method for Dynamic Problems

For brevity we outline the solution method for dynamic problems using only index notation. Time-dependence enters through
the constitutive relationships, loading conditions, and the inertial terms. We consider the deformation at time t ,
Z Z Z Z
σi j (t )N,nj dV + Ti (t )N n d S + f i (t )N n dV − ρ ä im (t )N m N n dV =~0.
X
− (2.80)
V ST V V m
We solve this equation through formulation of a linear algebraic system of equations ( Au = b ), involving the residual (r =
b − Au ) and Jacobian ( A ). The residual is simply
Z Z Z Z
r in = − σi j (t )N,nj dV + Ti (t )N n d S + f i (t )N n dV − ρ ä im (t )N m N n dV.
X
(2.81)
V ST V V m
We employ numerical quadrature in the finite-element discretization and replace the integrals with sums over the cells and
quadrature points,
r in = − σi j (x q , t )N n (x q ) w q |J cel l (x q )| + f i (x q , t )N n (x q ) w q |J cel l (x q )|
X X X X
vol cells quad pts vol cells quad pts
Ti (x q , t )N n (x q ) w q |J cel l (x q )| − ρ ä im (t )N m N n w q|J cel l (x q ) ,
X X X X X
+ (2.82)
tract cells quad pts vol cells quad pts m
where x q are the coordinates of the quadrature points, w q are the weights of the quadrature points, and |J cel l (x q )| is the
determinant of the Jacobian matrix evaluated at the quadrature points associated with mapping the reference cell to the actual
cell. The quadrature scheme for the integral over the tractions is one dimension lower than the one used in integrating the terms
for the volume cells.
We find the system Jacobian matrix by making use of the temporal discretization and isolating the term for the increment
in the displacement field at time t . Using the central difference method to approximate the acceleration (and velocity),
1
ü i (t ) = (u i (t + ∆t ) − 2u i (t ) + u i (t − ∆t )) (2.83)
∆t 2
1
u̇ i (t ) = (u i (t + ∆t ) − u i (t − ∆t )) (2.84)
2∆t
and writing the displacement at time t + ∆t in terms of the displacement at t (for consistency with the displacement increment
quasi-static formulation),
u i (t + ∆t ) = u i (t ) + d u i (t ), (2.85)
1
ü i (t ) = 2 (d u i (t ) − u i (t ) + u i (t − ∆t )) , (2.86)
∆t
1
u̇ i (t ) = (d u i (t ) + u i (t ) − u i (t − ∆t )) . (2.87)
2∆t
Substituting into equation (2.80) yields
1
Z Z Z Z
ρ d a im (t )N m N n dV = − σi j N,nj dV + Ti N n d S + f i N n dV
X
∆t 2 V m V ST V
1
Z
ρ (a im (t ) − a im (t − ∆t ))N m N n dV.
X
− 2 (2.88)
∆t V m
Thus, the Jacobian for the system is

1
Z
A nm
i j = δi j ρN m N n dV, (2.89)
∆t 2 V
and using numerical quadrature in the finite-element discretization to replace the integrals with sums over the cells and quadra-
ture points,
1
A nm
i j = δi j ρ(x q )N m (x q )N n (x q ),
X X
(2.90)
∆t 2 vol cells quad pts
where A mn
ij
is a nd by md matrix (d is the dimension of the vector space), m and n refer to the basis functions and i and j are
vector space components. We consider the contributions associated with the fault in section 6.4 on page 90 and with absorbing
boundaries is section 6.3 on page 88.
2.5 Small (Finite) Strain Formulation

In some crustal deformation problems sufficient deformation may occur that the assumptions associated with infinitesimal
strains no longer hold. This is often the case for problems when one wants to include the effects of gravitational body forces on
vertical deformation. In such cases we want to account for both rigid body motion and small strains. We use a total Lagrangian
formulation (quantities are associated with the undeformed configuration) based on the one presented by Bathe [Bathe, 1995].
Starting from the governing equation, written for the deformed configuration (denoted by the subscript t ), we have
→
− → ∂2 →
−
u →
Z Z Z
~ dVt + − −
(∇t · σ) · φ f t · φ dVt − ρt · φ dVt = 0. (2.91)
Vt Vt ∂t 2
For the total Lagrangian formulation we want to transform these integrals over the deformed configuration to integrals over
the undeformed configuration. We require that the deformed and undeformed configurations use the same coordinate system
(origin and orientation). Conservation of mass requires that ρ dVt = ρ 0 dV0 . We define the body force as a force per unit volume
that does not depend on the configuration, which leads to ~f t dVt = ~
f 0 dV0 .
The Green-Lagrange strain provides a measure of the strain relative to the original, undeformed configuration.
1
² = (∇u i , j + (∇u)T + u k,i u k, j ), or (2.92)
2
² = X T0 X 0 − I , where (2.93)
∂
X0 = x (0) + ~
(~ u (t )), (2.94)
∂x j
2.5. SMALL (FINITE) STRAIN FORMULATION 15
and X is the deformation gradient tensor. The second Piola-Kirchhoff stress tensor, S , is the work conjugate of the Green-
Lagrange strain tensor. As a result, they are related through the elasticity constants,
S = C ε, (2.95)
in the same manner as the Cauchy stress is related to the infinitesimal strain. The Cauchy stress is related to the second
Piola-Kirchoff stress through the deformation gradient tensor,
1
σ= X S X T0 , (2.96)
|X 0 | 0
where det(X 0 ) = |X 0 |. Additionally, the first Piola-Kirhoff stress is define to be
P = S X T0 . (2.97)
Applying the divergence theorem, making use of the fact that dVt = |X 0 | dV0 , and recognizing that the gradient in the
deformed configuration is related to the gradient in the undeformed configuration through the deformation gradient tensor, we
can show that Z Z Z
~ dVt = − →
− −
→ → −
∇t · σ · φ P : ∇ φ dV0 + T0 · φ d S 0 , (2.98)
Vt V0 S0
where we assume the the tractions on the boundary do not depend on the configuration. That is, the normal and share traction
components are defined in terms of the undeformed configuration. Incorporating the other relationships between the under-
formed and deformed configurations allows us to rewrite Equation 2.91 on the facing page in the undeformed configuration,
→
− → ∂2 →
−
u →
Z Z Z Z
→
− −
→ → − − −
− P : ∇ φ dV0 + T0 · φ d S 0 + f 0 · φ dV0 − ρ0 · φ dV0 = 0. (2.99)
V0 S0 V0 V0 ∂t 2
2.5.1 Quasi-static Problems
The system Jacobian for quasi-static problems includes terms associated with elasticity. For the small strain formulation, we
write the elasticity term at time t + ∆t and consider the first terms of the Taylor series expansion,
Z Z
S i j (t + ∆t )δεi j (t + ∆t ) dV = (S i j (t )δεi j (t ) + d S i j (t )δεi j (t ) + S i j (t )d δεi j (t )) dV. (2.100)
v V
We approximate the increment in the stress tensor using the elastic constants,
d S i j = C i j kl d εkl , (2.101)
and the increment in the “virtual” strain via

1
d δεi j = (d u k,i δu k, j + d u k, j δu k,i ). (2.102)
2
We associate the system Jacobian with the terms involving the increment in displacements. After substituting in the expressions
for the increment in the stresses and the increment in the “virtual” strains, we have
1 1
Z
A nm m
+ ( a pr N,lr )N,k
m
)(N,in + ( a pr N,rj )N,in ) + S kl N,lm N,ln δi j dV.
X X
ij = C i j kl (N,k (2.103)
V 4 r r 2
The small strain formulation produces additional terms associated with the elastic constants and a new term associated with the
stress tensor.
2.5.2 Dynamic Problems
The system Jacobian matrix in dynamic problems does not include any terms associated with elasticity, so the system Jacobian
matrix in the small strain formulation matches the one used in the infinitesimal strain formulation.
Chapter 3
Installation and Getting Help
Installation of PyLith on a desktop or laptop machine is, in most cases, very easy. Binary packages have been created for Linux
and Mac OS X platforms. You can also run PyLith inside a Docker container, which provides a virtual Linux environment on
any platform that Docker supports, including Linux, Mac OS X, and Windows. Installation of PyLith on other operating systems
– or installation on a cluster – requires building the software from the source code, which can be difficult for inexperienced
users. We have created a small utility called PyLith Installer that makes installing PyLith and all of its dependencies from
source much easier. Help is available from both a CIG mailing list and the GitHub issue tracking system https://github.
com/geodynamics/pylith/issues.
3.1 Getting Help and Reporting Bugs

The CIG Short-Term Crustal Dynamics Mailing List [email protected] is dedicated to CIG issues associated
with short-term crustal dynamics, including the use of PyLith. You can subscribe to the mailing list and view messages at cig-
short Mailing List geodynamics.org/cig/lists/cig-short.
CIG uses GitHub for source control and bug tracking. If you find a bug in PyLith, please submit a bug report to the GitHub
issue tracking system for PyLith https://github.com/geodynamics/pylith/issues. Of course, it is helpful to
first check to see if someone else already submitted a report related to the issue; one of the CIG developers may have posted a
work around to the problem. You can reply to a current issue by clicking on the issue title. To submit a new issue, click on the
New Issue button.
3.2 Installation of Binary Executable

Binary executables are available for Linux and Mac OS X (Intel 10.10+) from the PyLith web page geodynamics.org/
cig/software/packages/short/pylith/.
3.2.1 Linux and Max OS X
1. Open a terminal window and change to the directory where you want to place the distribution.
$$ cd $HOME
$$ mkdir pylith
$$ cd pylith
2. Download the Linux or Mac OS X tarball from the PyLith web page geodynamics.org/cig/software/packages/
short/pylith/, and save it to the desired location, e.g., $HOME/pylith.
17
18 CHAPTER 3. INSTALLATION AND GETTING HELP
3. Unpack the tarball.
# Linux 32-bit
$$ tar -xzf pylith-2.2.0-linux-i686.tgz
# Linux 64-bit
$$ tar -xzf pylith-2.2.0-linux-x86_64.tgz
# Mac OS X
$$ tar -xzf pylith-2.2.0-darwin-10.11.6.tgz
4. Set environment variables. The provided setup.sh script only works if you are using bash shell. If you are using a
different shell, you will need to alter how the environment variables are set in setup.sh.
$$ source setup.sh
L Warning
The binary distribution contains PyLith and all of its dependencies. If you have any
of this software already installed on your system, you need to be careful in setting up
your environment so that preexisting software does not conflict with the PyLith binary.
By default the setup.sh script will prepend to the PATH and PYTHONPATH (for
Darwin and Linux) and LD_LIBRARY_PATH (for Linux) environment variables. This
will prevent most conflicts.
B Important
The PyLith binary distribution for Darwin systems is built using the system clang
compiler suite and the system Python. This means the system Python must be in your
path to use the PyLith binary executable; ensure /bin and /usr/bin are at the be-
ginning of the PATH environment variable before sourcing setup.sh.
3.2.2 Extending PyLith and/or Integrating Other Software Into PyLith
New in v.2.2.0
We have constructed the binary package so that you can extend PyLith and/or build additional software for integration with
PyLith using the binary distribution.
Darwin The binary package includes the header files for PyLith and all of its dependencies. Use the clang compiler and Python
provided with the operating system. You will need to install XTools.
Linux The binary package includes the GNU compilers, Python, as well as header files for PyLith and all of its dependencies.
H Tip
We encourage anyone extending PyLith to fork the PyLith repository and build from
source using the PyLith Installer Utility to facilitate contributing these features back
into the CIG repository via pull requests.
3.3. INSTALLATION OF PYLITH DOCKER CONTAINER 19
3.3 Installation of PyLith Docker Container
Docker containers provide a self-contained virtual environment that are a smaller, simpler alternative to a virtual machine. The
PyLith Docker container provides a Debian Linux environment with a pre-built PyLith executable, vim text editor, iceweasel
(GNU version of Firefox) web-browser, and the matplotlib Python module.
3.3.1 Setup (first time only)
1. Install Docker (See https://www.docker.com/products/docker)

2. Create a container to store persistent user data
This container, called pylith-data, will hold a directory where all your user data can be stored for use with PyLith within
Docker. The data can persist for different versions of PyLith; that is, you can update to a newer version of PyLith and
your user data will still be available. This directory is not directly accessible from your host computer. However, you can
copy files to/from your host filesystem using “docker cp” (see below).
# Create the container

$$ docker create --name pylith-data geodynamics/pylith-data
# Run the docker container and copy examples to the persistent storage.
$$ docker run -ti --volumes-from pylith-data geodynamics/pylith
$$ cp -R $HOME/pylith-VERSION/examples $HOME/data
3.3.2 Run Unix shell within Docker to use PyLith.
To run the container with a text only interface:

$$ docker run -ti --volumes-from pylith-data geodynamics/pylith
To run the container and allow display of windows on the host computer:
# Darwin: Allow X connections
$$ xhost +YOUR_IP_ADDRESS; DISPLAY=YOUR_IP_ADDRESS:0
# Linux: Allow X connections
$$ xhost +local:root
# For Linux and Darwin, continue with the follow lines.
$$ XSOCK=/tmp/.X11-unix
$$ docker run -ti --volumes-from pylith-data \
-e DISPLAY=$DISPLAY -v $XSOCK:$XSOCK geodynamics/pylith
In addition to a minimalist Debian Linux distribution and PyLith and all of its depenencies, the container includes the
following useful utilities:
vim Lightweight text editor

matplotlib Python plotting module
iceweasel GNU version of Firefox
B Important
We do not yet include ParaView due to difficulties associated with setting up rendering
on the host display outside the container.
3.3.2.1 Using Docker containers
• To “pause” a container: Control-p Control-q
• To attach to a “paused” or “running” container.
# Get the container id.
$$ docker ps
# Attach to the container
$$ docker attach CONTAINER_ID
• To restart an existing container after it exited.

# Get the container id.
$$ docker ps -a
# Start and then attach to the container
$$ docker run CONTAINER_ID
$$ docker attach CONTAINER_ID
3.3.3 Copy data to/from persistent storage volume.
These commands are run on the local host outside the container, not inside the Docker container.
# Copy data FROM persistent storage volume TO local host
$$ docker cp pylith-data:/data/pylith-user/PATH/FILENAME LOCAL_PATH
# Copy data FROM local host TO persistent storage volume
$$ docker cp LOCAL_PATH pylith-data:/data/pylith-user/PATH/
3.3.4 Docker Quick Reference
# List local docker images.

$$ docker images
# List all docker containers.
$$ docker ps -a
# List running docker containers.
$$ docker ps
# Remove docker container
$$ docker rm CONTAINER_ID
# Remove docker image
$$ docker rmi IMAGE_ID
3.4 Installation from Source

PyLith depends on a number of other packages (see Figure 1.2 on page 3). This complicates building the software from the
source code. In many cases some of the packages required by PyLith are available as binary packages. On the one hand, using
the binary packages removes the burden of configuring, building, and installing these packages, but that can come with its own
host of complications if consistent compiler and configuration settings are not used across all of the packages on which PyLith
depends. This is usually not an issue with Linux distributions, such as Fedora, Ubuntu, and Debian that have good quality
control; it can be an issue with Darwin package managers, such as Fink, MacPorts, and Homebrew, where there is limited
enforcement of consistency across packages. Nevertheless, PyLith can be built on most systems provided the instructions are
followed carefully. PyLith is developed and tested on Linux and Mac OS X.
A small utility, PyLith Installer, removes most of the obstacles in building PyLith and its dependencies from source. For
each package this utility downloads the source code, configures it, builds it, and installs it. This insures that the versions of
the dependencies are consistent with PyLith and that the proper configure arguments are used. The minimum requirements for
3.5. VERIFYING PYLITH IS INSTALLED CORRECTLY 21
using the PyLith installer are a C compiler, tar, and wget or curl. Detailed instructions for how to install PyLith using the
installer are included in the installer distribution, which is available from the PyLith web page geodynamics.org/cig/
software/packages/short/pylith/.
3.5 Verifying PyLith is Installed Correctly

The easiest way to verify that PyLith has been installed correctly is to run one or more of the examples supplied with the
binary and source code. In the binary distribution, the examples are located in src/pylith-2.2.0/examples while in
the source distribution, they are located in pylith-2.2.0/examples. Chapter 7 on page 109 discusses how to run and
visualize the results for the examples. To run the example discussed in Section 7.8.5 on page 138:
$$ cd examples/3d/hex8
$$ pylith step01.cfg
If you run PyLith in a directory without any input, you will get the error message:
$$ pylith
>> {default}::
-- pyre.inventory(error)
-- meshimporter.meshioascii.filename <- ’’
-- Filename for ASCII input mesh not specified.
To test PyLith, run an example as discussed in the manual.
>> {default}::
-- timedependent.homogeneous.elasticisotropic3d.label <- ’’
-- Descriptive label for material not specified.
>> {default}::
-- timedependent.homogeneous.elasticisotropic3d.simpledb.label <- ’’
-- Descriptive label for spatial database not specified.
>> {default}::
-- timedependent.homogeneous.elasticisotropic3d.simpledb.simpleioascii.filename <- ’’
-- Filename for spatial database not specified.
pylithapp: configuration error(s)
This indicates that a number of default settings must be set in order to run PyLith, including setting the filename for the
finite-element mesh.
3.6 Configuration on a Cluster

If you are installing PyLith on a cluster with a batch system, you can configure Pyre such that the pylith command automat-
ically submits jobs to the batch queue. Pyre contains support for the LSF, PBS, SGE, and Globus batch systems.
The command to submit a batch job depends upon the particular batch system used. Further, the command used in a batch
script to launch an MPI program varies from one cluster to the next. This command can vary between two clusters, even if the
clusters use the same batch system! On some systems, mpirun is invoked directly from the batch script. On others, a special
wrapper is used instead.
Properly configured, Pyre can handle job submissions automatically, insulating users from the details of the batch system
and the site configuration. This feature has the most value when the system administrator installs a global Pyre configuration
file on the cluster (under /etc/pythia-0.8), for the benefit of all users and all Pyre-based applications.
3.6.1 Launchers and Schedulers
If you have used one of the batch systems, you will know that the batch system requires you to write a script to launch a job.
Fortunately, launching a parallel PyLith job is simplified by Pyre’s launcher and scheduler facilities. Many properties
associated with launcher and scheduler are pertinent to the cluster you are on, and are best customized in a configuration
file. Your personal PyLith configuration file ($HOME/.pyre/pylithapp/pylithapp.cfg) is suitable for this purpose.
On a cluster, the ideal setup is to install a system-wide configuration file under /etc/pythia-0.8, for the benefit of all
users.
Pyre’s scheduler facility is used to specify the type of batch system you are using (if any):
[pylithapp]
# The valid values for scheduler are ’lsf", ’pbs’, ’globus’, and ’none.
scheduler = lsf
# Pyre’s launcher facility is used to specify the MPI implementation.
# The valid values for launcher include ’mpich’ and ’lam-mpi’.
launcher = mpich
You may find the ’dry’ option useful while debugging the launcher and scheduler configuration. This option causes
PyLith to perform a “dry run,” dumping the batch script or mpirun command to the console, instead of actually submitting it
for execution (the output is only meaningful if you’re using a batch system).
# Display the bash script that would be submitted.
$$ pylith --scheduler.dry
# Display the mpirun command.
$$ pylith --launcher.dry
3.6.2 Running without a Batch System
On a cluster without a batch system, you need to explicitly specify the machines on which the job will run. Supposing the
machines on your cluster are named n001, n002, . . . , etc., but you want to run the job on machines n001, n003, n004, and
n005 (maybe n002 is down for the moment). To run an example, create a file named mymachines.cfg which specifies the
machines to use:
[pylithapp.launcher]
nodegen = n%03d
nodelist = [1,3-5]
The nodegen property is a printf-style format string, used in conjunction with nodelist to generate the list of machine
names. The nodelist property is a comma-separated list of machine names in square brackets.
Now, invoke the following:
$$ pylith example.cfg mymachines.cfg
This strategy gives you the flexibility to create an assortment of .cfg files (with one .cfg file for each machine list) which
can be easily paired with different parameter files.
If your machine list does not change often, you may find it more convenient to specify default values for nodegen
and nodelist in $HOME/.pyre/pylithapp/pylithapp.cfg (which is read automatically). Then, you can run any
simulation with no additional arguments:
$$ pylith example.cfg
3.6. CONFIGURATION ON A CLUSTER 23
L Warning
This assumes your machine list has enough nodes for the simulation in question.
You will notice that a machine file mpirun.nodes is generated. It will contain a list of the nodes where PyLith has run.
3.6.3 Using a Batch System
Many clusters use some implementation of a PBS (e.g., TORQUE/Maui) or LSF batch system. The examples below illustrate
use of some of the more important settings. You may need to make use of more options or adjust these to submit jobs on
various cluster. These settings are usually placed in $HOME/.pyre/pylithapp/pylithapp.cfg or in a system-wide
configuration file. They can be overridden on the command line, where one typically specifies the number of compute nodes
and number of processes per compute node, the job name, and the allotted time for the job:
$$ pylith example1.cfg \
--job.queue=debug \
--job.name=example1 \
--job.stdout=example1.log \
--job.stderr=example1.err \
--job.walltime=5*minute \
--nodes=4
B Important
The value for nodes is equal to the number of compute nodes times the number
of processes (usually the number of cores) requested per compute node. Specify-
ing the number of processes per compute node depends on the batch system. For
more information on configuring Pyre for your batch system, see CIG’s Pythia page
geodynamics.org/cig/software/packages/cs/pythia.
3.6.3.1 LSF Batch System
[pylithapp]
scheduler = lsf ; the type of batch system
[pylithapp.lsf]
bsub-options = [-a mpich_gm] ; special options for ’bsub’
command = mpirun.lsf ; ’mpirun’ command to use on our cluster
[pylithapp.job]
queue = normal ; default queue for jobs
3.6.3.2 PBS Batch System
[pylithapp]
scheduler = pbs ; the type of batch system
[pylithapp.pbs]
shell = /bin/bash ; submit the job using a bash shell script
# Export all environment variables to the batch job

# Send email to [email protected] when the job begins, ends, or aborts
qsub-options = -V -m bea -M [email protected]
command = mpirun -np ${nodes} -machinefile ${PBS_NODEFILE}
For most PBS batch systems you can specify N processes per compute node via the command line argument --scheduler.ppn=N.
Chapter 4
Running PyLith
Figure 4.1 on the following page shows the workflow for running PyLith. There are essentially three main inputs needed to run
a problem with PyLith:
1. 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 7 on page 109 for examples and Section C.1 on page 223 for the format specification) or by importing the
information from the LaGriT or CUBIT meshing packages (see Chapter 7 on page 109 for examples).
2. 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 .cfg.
3. 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 7
on page 109 for examples and Appendix C.2 on page 224 for the format specification).
PyLith writes solution information, such as solution fields and state variables, to either VTK files or HDF5/Xdmf files. ParaView
and Visit can read both types of files. Post-processing of output is generally performed using HDF5 files accessed via a Python
script and the h5py package or a Matlab script.
4.1 Defining the Simulation

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 main 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 1.3 on page 4 for the general concept of Pyre facilities and properties. The
top-level object is the PyLith application with three facilities: mesher, problem, and petsc. The mesher specifies how
to import the mesh, the problem specifies the physical properties, boundary conditions, etc., and petsc is used to specify
PETSc settings. Appendix B on page 217 contains a list of the components provided by PyLith and spatialdata.
4.1.1 Setting PyLith Parameters
There are several methods for setting input parameters for the pylith executable: via the command line or by using a text file
in .cfg or .pml format. Both facilities and properties have default values provided, so you only need to set values when you
25
26 CHAPTER 4. RUNNING PYLITH
Mesh Generator Simulation Parameters
CUBIT
/ Trelis LaGriT Text Editor Text Editor
GMV File
Parameter Spatial
Exodus file [.gmv] ASCII File
File(s) Database(s)
[.exo] Pset File [.mesh]
[.cfg] [.spatialdb]
[.pset]
PyLith
HDF5 File(s)
VTK File(s) [.h5] Python
[.vtk] Xdmf File(s) w/h5py
[.xmf]
Matlab
ParaView Visit
Post-processing
Visualization
Figure 4.1: PyLith requires a finite-element mesh (three different mechanisms for generating a mesh are currently supported),
simulation parameters, and spatial databases (defining the spatial variation of various parameters). PyLith writes the solution
output to either VTK or HDF5/Xdmf files, which can be visualized with ParaView or Visit. Post-processing is generally done
using the HDF5 files with Python or Matlab scripts.
want to deviate from the default behavior.
4.1.1.1 Units
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 4.1
Table 4.1: Pyre supported units. Aliases are in parentheses.

Scale Available Units
length meter (m), micrometer (um, micron), millimeter (mm), centimeter (cm), kilometer (km),
inch, foot, yard, mile
time second (s), nanosecond (ns), microsecond (us), millisecond (ms), minute, hour, day, year
mass kilogram (kg), gram (g), centigram (cg), milligram (mg), ounce, pound, ton
pressure pascal (Pa), kPa, MPa, GPa, bar, millibar, atmosphere (atm)
4.1.1.2 Using the Command Line
The --help command line argument displays links to useful resources for learning PyLith.
Pyre uses the following syntax to change properties from the command line. To change the value of a property of a
component, use --COMPONENT.PROPERTY=VALUE. Each component is attached to a facility, so the option above can also
be written as --FACILITY.PROPERTY=VALUE. Each facility has a default component attached to it. A different component
can be attached to a facility by --FACILITY=NEW_COMPONENT.
PyLith’s command-line arguments can control Pyre and PyLith properties and facilities, MPI settings, and PETSc settings.
All PyLith-related properties are associated with the pylithapp component. You can get a list of all of these top-level prop-
erties along with a description of what they do by running PyLith with the --help-properties command-line argument.
4.1. DEFINING THE SIMULATION 27
To get information on user-configurable facilities and components, you can run PyLith with the --help-components
command-line argument. To find out about the properties associated with a given component, you can run PyLith with the
--COMPONENT.help-properties flag:
$$ pylith --problem.help-properties
# Show problem components.
$$ pylith --problem.help-components
# Show bc components (bc is a component of problem).
$$ pylith --problem.bc.help-components
# Show bc properties.
$$ pylith --problem.bc.help-properties
4.1.1.3 Using a .cfg File
Entering all those parameters via the command line involves the risk of typographical errors. You will generally find it easier
to collect parameters into a .cfg file. The file is composed of one or more sections which are formatted as follows:
[pylithapp.COMPONENT1.COMPONENT2]
FACILITY3 = COMPONENT3
PROPERTY1 = VALUE1
PROPERTY2 = VALUE2 ; this is another comment
H Tip
We strongly recommend that you use .cfg files for your work. The files are syntax-
highlighted in the vim editor.
4.1.1.4 Using a .pml File
A .pml 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:
<component~name="COMPONENT1">
<component~name="COMPONENT2">
<property~name="PROPERTY1">VALUE1</property>
<property~name="PROPERTY2">VALUE2</property>
</component>
</component>
XML files are intended to be read and written by machines, not edited manually by humans. The .pml 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 .pml files, note that
.pml files and .cfg files can be used interchangeably; in the following discussion, a file with a .pml extension can be
substituted anywhere a .cfg file can be used.
4.1.1.5 Specification and Placement of Configuration Files
Configuration files may be specified on the command line:

$$ pylith example.cfg
In addition, the Pyre framework searches for configuration files named pylithapp.cfg 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:
1. $PREFIX/etc/pylithapp.cfg, for system-wide settings;

2. $HOME/.pyre/pylithapp/pylithapp.cfg, for user settings and preferences;
3. the current directory (./pylithapp.cfg), for local overrides.
B Important
The Pyre framework will search these directories for .cfg files matching the names
of components (for example, timedependent.cfg, faultcohesivekin.cfg,
greensfns.cfg, pointforce.cfg, etc) and will attempt to assign all parameters
in those files to the respective component.
B Important
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 pylithapp.cfg files placed in (3) will override those in (2), (2) overrides (1),
and (1) overrides only the built-in defaults.
All of the example problems are set up using configuration files and specific problems are defined by including the ap-
propriate configuration file on the command-line. Referring to the directory examples/twocells/twohex8, we have the
following.
$$ ls -1 *.cfg
axialdisp.cfg
dislocation.cfg
pylithapp.cfg
sheardisp.cfg
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:
$$ pylith axialdisp.cfg
If you want to see what settings are being used, you can either examine the .cfg files, or use the help flags as described above:
# Show components for the ’problem’ facility.
$$ pylith axialdisp.cfg --problem.help-components
# Show properties for the ’problem’ facility.
$$ pylith axialdisp.cfg --problem.help-properties
# Show components for the ’bc’ facility.
$$ pylith axialdisp.cfg --problem.bc.help-components
# Show properties for the ’bc’ facility.
$$ pylith axialdisp.cfg --problem.bc.help-properties
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 .cfg file.
4.1.1.6 List of PyLith Parameters (pylithinfo)
The Python application pylithinfo writes all of the current parameters to a text file or JSON file (default). The default
name of the JSON is pylith_parameters.json. The usage synopsis is
$$ pylithinfo [--verbose-false] [--format={ascii,json} [--filename=pylith_parameters.json] PYLITH_ARGS
where --verbose-false turns off printing the descriptions of the properties and components as well as the location where
the current value was set, --format=ascii changes the output format to a simple ASCII file, and --filename=pylith_parameters
sets the name of the output file. The PyLith Parameter Viewer (see Section 4.10) provides a graphic user interface for examining
the JSON parameter file.
4.1.2 Mesh Information (mesher)
Geometrical and topological information for the finite element mesh may be provided by exporting an Exodus II format file
from CUBIT/Trelis, by exporting a GMV file and an accompanying Pset file from LaGriT, or by specifying the information in
PyLith mesh ASCII format. See Chapter 7 on page 109 for examples.
PyLith supports linear cells in 2D (Figure 4.2), and 3D (Figure 4.3 on the next page). The vertex ordering must follow
the convention shown in Figures 4.2- 4.3 on the next page. PyLith no longer supports use of quadratic cells using the PyLith
ASCII mesh format. In the next release, we plan to support higher order discretizations via PETSc finite-element features from
meshes with linear cells as input.
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 5 on page 59
and 6 on page 83 for more detailed discussions of setting the materials and boundary conditions.
2 3
2
0 1 0 1
Figure 4.2: Linear cells available for 2D problems are the triangle (left) and the quadrilateral (right).
4.1.2.1 Mesh Importer
The default mesher component is MeshImporter, which provides the capabilities of reading the mesh from files. The MeshIm-
porter has several properties and facilities:
reorder_mesh Reorder the vertices and cells using the reverse Cuthill-McKee algorithm (default is False)
reader Reader for a given type of mesh (default is MeshIOAscii).
distributor Handles distribution of the mesh among processors.
refiner Perform global uniform mesh refinement after distribution among processors (default is no refinement).
Figure 4.3: Linear cells available for 3D problems are the tetrahedron (left) and the hexahedron (right).
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.
L Warning
The coordinate system associated with the mesh must be a Cartesian coordinate system,
such as a generic Cartesian coordinate system or a geographic projection.
4.1.2.2 MeshIOAscii
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 C.1 on page 223 describes the format of the files. The properties and
facilities of the MeshIOAscii object include:
filename Name of the mesh file.
coordsys Coordinate system associated with the mesh.
4.1.2.3 MeshIOCubit
The MeshIOCubit object reads the NetCDF Exodus II files output from CUBIT/Trelis. 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:
filename Name of the Exodus II file.
use_nodeset_names Identify nodesets by name rather than id (default is True).
coordsys Coordinate system associated with the mesh.
4.1.2.4 MeshIOLagrit
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:
filename_gmv Name of GMV file.
filename_pset Name of the PSET file.
flip_endian Flip the endian of values when reading binary files (default is False).
io_int32 Flag indicating that PSET files use 32-bit integers (default is True).
record_header_32bt Flag indicating FORTRAN record header is 32-bit (default is True).
coordsys Coordinate system associated with mesh.
L Warning
The PyLith developers have not used LaGriT since around 2008 and the most recent
release appears to have been in 2010.
4.1.2.5 Distributor
The distributor uses 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 type of partitioner is set via PETSc settings. The properties
and facilities of the Distributor include:
partitioner Name of mesh partitioner [’chaco’,’parmetis’].
write_partition Flag indicating that the partition information should be written to a file (default is False).
data_writer Writer for partition information (default is DataWriterVTK for VTK output).
An example of setting the partitioner in a pylithapp.cfg file is:
[pylithapp.mesh_generator.distributor]
partitioner = chaco ; Options are ’chaco’ (default) and ’parmetis’.
METIS/ParMETIS are not included in the PyLith binaries due to licensing issues.
4.1.2.6 Refiner
The refiner is used to decrease node spacing by a power of two by recursively subdividing each cell by a factor of two. In a 2D
triangular mesh a node is inserted at the midpoint of each edge, splitting each cell into four cells (see Figure 4.4 on the next
page). 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.
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 largeer than 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 4n , and for 3D problems it increases the maximum problem size by a
factor of 8n , where n is the number of recursive refinement levels. For a tetrahedral mesh, the element quality decreases with
refinement so n should be limited to 1-2.
4.1.3 Problem Specification (problem)
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 problems, TimeDependent
for use in static, quasi-static, and dynamic simulations and GreensFns for computing static Green’s functions. The general
properties facilities include:
dimension Spatial dimension of problem space.
Figure 4.4: 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.
normalizer Scales used to nondimensionalize the problem (default is NondimElasticQuasistatic).

materials Array of materials comprising the domain (default is [material]).
bc Array of boundary conditions (default is none).
interfaces Array of interface conditions, i.e., faults (default is none).
gravity_field Gravity field used to construct body forces (default is none).
progress_ monitor Show progress of running simulation.
An example of setting these parameters in a .cfg file for a problem is:
[pylithapp.timedependent]
dimension = 3
normalizer = spatialdata.units.NondimElasticQuasistatic
materials = [elastic, viscoelastic]
bc = [boundary_east, boundary_bottom, boundary_west]
interfaces = [SanAndreas, SanJacinto]
gravity_field = spatialdata.spatialdb.GravityField
4.1.3.1 Nondimensionalization (normalizer)
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 NondimElasticQuasistatic normalizer (which is the default)
has the following properties:
length_scale Distance to nondimensionalize length (default is 1.0 km).
shear_modulus Shear modulus to nondimensionalize pressure (default is 3.0e+10 Pa).
relaxation_time Relaxation time to nondimensionalize time (default is 1.0 year).
[pylithapp.timedependent.normalizer]
length_scale = 1.0*km
shear_modulus = 3.0e+10*Pa
relaxation_time = 1.0*yr
The NondimElasticDynamic normalizer has the following properties:

shear_wave_speed Shear wave speed used to nondimensionalize length and pressure (default is 3.0 km/s).
mass_density Mass density to nondimensionalize density and pressure (default is 3.0e+3 kg/m3 ).
wave_period Period of seismic waves used to nondimensionalize time (default is 1.0 s).
[pylithapp.timedependent.normalizer]
shear_wave_speed = 3.0*km/s
mass_density = 3.0e+3*kg/m**3
wave_period = 1.0*s
B Important
The default nondimensionalization is reasonable for many problems; however, it may
be necessary to change the default values in some cases. When doing this, keep in
mind that the nondimensionalization generally applies to the minimum values en-
countered for a problem. For example, in a quasistatic problem, the length_scale
should be on the order of the minimum cell size. Similarly, the relaxation_time
should be on the order of the minimum relaxation time.
4.1.4 Finite-Element Integration Settings
PyLith uses numerical quadrature to evaluate the finite-element integrals for the residual and system Jacobian (see Chapter 2
on page 7). 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 FIATSimplexx 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
dimension Dimension of the cell (0,1,2,3; default is 3).
degree Degree of the finite-element cell (default is 1).
order Order of quadrature rule (default is degree+1); hardwired to be equal to degree for faults.
collocate_quad Collocate quadrature points with vertices (default is False); hardwired to True for faults.
See Section 5.1.3 on page 60 for an example of setting these properties for a material.
4.1.5 PETSc Settings (petsc)
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 4.2.3 on page 38).
PETSc options can be set in .cfg files in sections beginning with [pylithapp.petsc]. The options of primary in-
terest in the case of PyLith are shown in Table 4.2. PETSc options are used to control the selection and settings for the solvers
underlying the SolverLinear and SolverNonlinear objects discussed in Section 4.2.3 on page 38. A very wide range of elasticity
problems in quasi-static simulations can be solved with reasonable runtimes by replacing the default Jacobi preconditioner with
the Additive Schwarz Method (ASM) using Incomplete LU (ILU) factorization by default (see Table 4.3 on the next page). A
more advanced set of solver settings that may provide better performance in many elasticity problems are given in Table 4.4
on the facing page. These are available in $PYLITH_DIR/share/settings/solver_fault_fieldsplit.cfg.
These settings are limited to problems where we store the stiffness matrix as a nonsymmetric sparse matrix and require addi-
tional settings for the formulation,
[pylithapp.timedependent.formulation]
split_fields = True
use_custom_constraint_pc = True ; Use only if problem contains a fault
matrix_type = aij
B Important
These settings are only available if you build PETSc with the ML package. These fea-
tures are included in the PyLith binary packages.
L Warning
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 Additive Schwarz precondi-
tioner without split fields. See Section 4.8.2 on page 50 for the error message encoun-
tered in this situation.
These more advanced settings allow the displacement fields and Lagrange multipliers for fault tractions to be precondi-
tioned 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 approxi-
mation of the Schur complement.
Table 4.2: Useful command-line arguments for setting PETSc options.

Property Default Value Description
log_view false Print logging objects and events.
ksp_monitor false Dump preconditioned residual norm to stdout.
ksp_view false Print linear solver parameters.
ksp_rtol 1.0e-05 Convergence tolerance for relative decrease in residual norm.
snes_monitor false Dump residual norm to stdout for each nonlinear solve iteration.
snes_view false Print nonlinear solver parameters.
snes_rtol 1.0e-5 Convergence tolerance for relative decrease in residual norm.
pc_type jacobi Set preconditioner type. See PETSc documentation for a list of all preconditioner
types.
ksp_type gmres Set linear solver type. See PETSc documentation for a list of all solver types.
Table 4.3: PETSc options that provide moderate performance in a wide range of quasi-static elasticity problems.
Property Value Description
pc_type asm Additive Schwarz method.
ksp_type gmres GMRES method from Saad and Schultz.
sub_pc_factor_shift_type nonzero Turn on nonzero shifting for factorization.
ksp_max_it 100 Maximum number of iterations permitted in linear solve. De-
pends on problem size.
ksp_gmres_restart 50 Number of iterations after which Gram-Schmidt orthogonaliza-
tion is restarted.
ksp_rtol 1.0e-08 Linear solve convergence tolerance for relative decrease in
residual norm.
ksp_atol 1.0e-12 Linear solve convergence tolerance for absolute value of resid-
ual norm.
ksp_converged_reason true Indicate why iterating stopped in linear solve.
snes_max_it 100 Maximum number of iterations permitted in nonlinear solve.
Depends on how nonlinear the problem is.
snes_rtol 1.0e-08 Nonlinear solve convergence tolerance for relative decrease in
residual norm.
snes_atol 1.0e-12 Nonlinear solve convergence tolerance for absolute value of
residual norm.
snes_converged_reason true Indicate why iterating stopped in nonlinear solve.
Table 4.4: PETSc options used with split fields algebraic multigrid preconditioning that often provide improved performance
in quasi-static elasticity problems with faults.
Property Value Description
fs_pc_type field_split Precondition fields separately.
fs_pc_use_amat true Use diagonal blocks from the true operator,
rather than the preconditioner.
fs_pc_fieldsplit_type multiplicative Apply each field preconditioning in se-
quence, which is stronger than all-at-once
(additive).
fs_fieldsplit_displacement_pc_type ml Multilevel algebraic multigrid precondition-
ing using Trilinos/ML via PETSc.
fs_fieldsplit_lagrange_multiplier_pc_type jacobi Jacobi preconditioning for Lagrange multi-
plier block
fs_fieldsplit_displacement_ksp_type preonly Apply only the preconditioner.
fs_fieldsplit_lagrange_multiplier_ksp_type preonly Apply only the preconditioner.
4.1.5.1 Model Verification with PETSc Direct Solvers
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 preconditioner. 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. These settings are available in $PYLITH_DIR/share/settings/solver_fault_exact.cfg.
split_fields = True
matrix_type = aij
[pylithapp.petsc]
fs_pc_type = fieldsplit
fs_pc_use_amat = True
fs_pc_fieldsplit_type = schur
fs_pc_fieldsplit_schur_factorization_type = full
fs_fieldsplit_displacement_ksp_type = preonly
fs_fieldsplit_displacement_pc_type = lu
fs_fieldsplit_lagrange_multiplier_pc_type = jacobi
fs_fieldsplit_lagrange_multiplier_ksp_type = gmres
fs_fieldsplit_lagrange_multiplier_ksp_rtol = 1.0e-11
4.2 Time-Dependent Problem (formulation)

This type of problem applies to transient static, quasi-static, and dynamic simulations. The time-dependent problem adds
the formulation 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.
Implicit Implicit time stepping for static and quasi-static problems with infinitesimal strains. The implicit formulation neglects
inertial terms (see Section 2.65 on page 12).
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.
Explicit 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.
ExplicitLgDeform Explicit time stepping for dynamic problems including the effects of rigid body motion and small strains.
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.
ExplicitTri3 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.
ExplicitTet4 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.
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 t = −∆t to t = 0, and it could not be turned off. PyLith now includes a property, elastic_prestep in the
TimeDependent component to turn on/off this behavior (the default is to retain the previous behavior of computing the elastic
deformation).
4.2. TIME-DEPENDENT PROBLEM (FORMULATION) 37
L Warning
Turning off the elastic prestep calculation means the model only deforms when an in-
crement in loading or deformation is applied, because the time-stepping formulation is
implemented using the increment in displacement.
The TimeDependent properties and facilities include

elastic_preset If true, perform a static calculation with elastic behavior before time stepping (default is True).
formulation Formulation for solving the partial differential equation.
An example of setting the properties and components in a .cfg file is
formulation = pylith.problems.Implicit ; default
progres_monitor = pylith.problems.ProgressMonitorTime ; default
elastic_preset = True ; default
The formulation value can be set to the other formulations in a similar fashion.
4.2.1 Time-Stepping Formulation
The explicit and implicit time stepping formulations use a common set of facilities and properties. The properties and facilities
include
matrix_type Type of PETSc matrix for the system Jacobian (sparse matrix, default is symmetric, block matrix with a
block size of 1).
view_jacobian Flag to indicate if system Jacobian (sparse matrix) should be written to a file (default is false).
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).
time_step Time step size specification (default is TimeStepUniform (uniform time step).
solver Type of solver to use (default is SolverLinear).
output Array of output managers for output of the solution (default is [output]).
jacobian_viewer Viewer to dump the system Jacobian (sparse matrix) to a file for analysis (default is PETSc binary).
An example of setting these parameters in a .cfg file is
matrix_type = sbaij ; Non-symmetric sparse matrix is ’aij’
view_jacobian = false
# Nonlinear solver is pylith.problems.SolverNonlinear

solver = pylith.problems.SolverLinear
output = [domain, ground_surface]
time_step = pylith.problems.TimeStepUniform
4.2.2 Numerical Damping in Explicit Time Stepping
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[Knopoff and Ni, 2001,
Day and Ely, 2002] to reduce these high frequency oscillations. In computing the strains for the elasticity term in equation 2.80
on page 13, we use an adjusted displacement rather than the actual displacement, where
~ u (t ) + η∗ ∆t ~
u ad j (t ) = ~ u̇(t ), (4.1)
~
u ad j (t ) is the adjusted displacement at time t, ~ u (t )is the original displacement at time (t), η∗ is the normalized artificial viscosity,
∆t is the time step, and ~ u̇(t ) is the velocity at time t . 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 .cfg file is
norm_viscosity = 0.2
4.2.3 Solvers
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 constitutive 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 4.1.5 on page 33 and the PETSc
documentation www.mcs.anl.gov/petsc/petsc-as/documentation/index.html).
4.2.4 Time Stepping
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) user-specified time steps (potentially nonuniform), and (3) automatically calculated
(potentially nonuniform) 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 with viscoelastic
materials should use automatically calculated time steps and dynamic simulations should use a uniform, user-specified time
step. Note that all three of the time stepping schemes make use of the computed stable time step (see 5.1.6 on page 63). When
using user-specified time steps, the value is checked against the computed stable time step. The automatically calculated time
step comes from the computed stable time step.
L Warning
Varying the time step within a simulation requires recomputing the Jacobian of the
system whenever the time step changes, which can greatly increase the runtime if the
time-step size changes frequently.
4.2.4.1 Uniform, User-Specified Time Step (TimeStepUniform)
With a uniform, user-specified time step, the user selects the time step that is used over the entire duration of the simulation.
If this value exceeds the computed stable time step at any time, PyLith will terminate with an error. The properties for the
uniform, user-specified time step are:
total_time Time duration for simulation (default is 0.0 s).
start_time Start time for simulation (default is 0.0 s).
dt Time step for simulation.
An example of setting a uniform, user-specified time step in a .cfg file is:
[pylithapp.problem.formulation]
time_step = pylith.problems.TimeStepUniform ; Default value
[pylithapp.problem.formulation.time_step]
4.2. TIME-DEPENDENT PROBLEM (FORMULATION) 39
total_time = 1000.0*year
dt = 0.5*year
4.2.4.2 Nonuniform, User-Specified Time Step (TimeStepUser)
The nonuniform, user-specified, time-step implementation allows the user to specify the time steps in an ASCII file (see Sec-
tion C.5 on page 229 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. Similar to the uniform time step, if the user-specified time step size exceeds the computed stable time step at any
time, PyLith will terminate with an error. The properties for the nonuniform, user-specified time step are:
total_time Time duration for simulation.
filename Name of file with time-step sizes.
loop_steps If true, cycle through time steps, otherwise keep using last time-step size for any time remaining.
An example of setting the properties for nonuniform, user-specified time steps in a .cfg file is:
time_step = pylith.problems.TimeStepUser ; Change the time step algorithm
filename = timesteps.txt
loop_steps = false ; Default value
4.2.4.3 Nonuniform, Automatic Time Step (TimeStepAdapt)
This time-step implementation automatically calculates a time step size 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. To provide some control over the time-step selection, the user can control the frequency with
which 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. Note that the stability factor allows the computed time step size to exceed the computed
stable time step. A stability factor of 1.0 would provide a time step size equal to the stable time step, while a value of 2.0 (default
value) would provide a time step size equal to 1/2 the stable time step. Caution should be used when adjusting the stability
factor to values less than 1.0, as the large time step size may result in inaccurate solutions. The properties for controlling the
automatic time-step selection are:
total_time Time duration for simulation.
max_dt Maximum time step permitted.
adapt_skip Number of time steps to skip between calculating new stable time step.
stability_factor Safety factor for stable time step (default is 2.0).
An example of setting the properties for the automatic time step in a .cfg file is:
time_step = pylith.problems.TimeStepAdapt ; Change the time step algorithm
max_dt = 10.0*year
adapt_skip = 10 ; Default value
stability_factor = 2.0 ; Default value
4.3 Green’s Functions Problem (GreensFns)
This type of problem applies to computing static Green’s functions for elastic deformation. The GreensFns problem special-
izes the time-dependent facility to the case of static simulations 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 “time step” 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 GreensFns problem
is the FaultCohesiveImpulses component discussed in Section 6.4.6 on page 106. The GreensFns properties amd facilities
include:
fault_id Id of fault on which to impose slip impulses.
formulation Formulation for solving the partial differential equation.
progress_monitor Simple progress monitor via text file.
An example of setting the properties for the GreensFns problem in a .cfg file is:
[pylithapp]
problem = pylith.problems.GreensFns ; Change problem type from the default
[pylithapp.greensfns]
fault_id = 100 ; Default value
formulation = pylith.problems.Implicit ; default
progres_monitor = pylith.problems.ProgressMonitorTime ; default
L Warning
The GreensFns 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 FaultCohesiveImpulses.
4.4 Progress Monitors
New in v2.1.0
The progress monitors make it easy to monitor the general progress of long simulations, especially on clusters where stdout
is not always easily accessible. The progress monitors update a simulation’s current progress by writing information to a text
file. The information includes time stamps, percent completed, and an estimate of when the simulation will finish.
4.4.1 ProgressMonitorTime
This is the default progress monitor for time-stepping problems. The monitor calculates the percent completed based on the
time at the current time step and the total simulated time of the simulation, not the total number of time steps (which may be
unknown in simulations with adaptive time stepping). The ProgressMonitorTime properties include:
update_percent Frequency (in percent) of progress updates.
filename Name of output file.
t_units Units for simulation time in output.
An example of setting the properties in a .cfg file is:
[pylithapp.problem.progressmonitor]
update_percent = 5.0 ; default
4.5. DATABASES FOR BOUNDARIES, INTERFACES, AND MATERIAL PROPERTIES 41
filename = progress.txt ; default
t_units = year ; default
4.4.2 ProgressMonitorStep
This is the default progress monitor for problems with a specified number of steps, such as Green’s function problems. The
monitor calculates the percent completed based on the number of steps (e.g., Green’s function impulses completed). The
ProgressMonitorStep propertiles include:
update_percent Frequency (in percent) of progress updates.
filename Name of output file.
An example of setting the properties in a .cfg file is:
[pylithapp.problem.progressmonitor]
update_percent = 5.0 ; default
filename = progress.txt ; default
4.5 Databases for Boundaries, Interfaces, and Material Properties

Once the problem has been defined with PyLith parameters, and the mesh information 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 .cfg file is used to associate boundary condition types and spatial
databases with each vertex group (see Chapter 6 on page 83). For materials, the .cfg file is used to associate material types
and spatial databases with cells identified by the material identifier (see Figure 5.1 on page 67).
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 (“point” 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 (“line” or 1D variation). In more complex models, the material properties
might have different values at each point in the mesh (“volume” 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 (“point” or 0D variation). A more
complex case might specify a variation in the conditions on a given surface (“area” 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 7 on page 109
also contain more information regarding the specification and use of the spatial database files.
4.5.1 SimpleDB Spatial Database
In most cases the default type of spatial database for faults, boundary conditions, and materials is SimpleDB. 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 “nearest value” search or linear interpolation.
The spatial database files need not provide the data using the same coordinate system as the mesh coordinate system, pro-
vided 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 proj.maptools.org 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 “distance” between locations and
interpolation).
SimpleDB uses a simple ASCII file to specify the variation of values (e.g., displacement field, slip field, physical proper-
ties) in space. The file format is described in Section C.2 on page 224. The examples in Chapter 7 on page 109 use SimpleDB
files to specify the values for the boundary conditions, physical properties, and fault slip.
As in the other Pyre objects, spatial database objects contain parameters that can be set from the command line or using
.cfg files. The properties and facilities for a spatial database are:
label Label for the database, which is used in diagnostic messages.
query_type Type of search query to perform. Values for this parameter are “linear” and “nearest” (default).
iohandler Database importer. Only one importer is implemented, so you do not need to change this setting.
iohandler.filename Filename for the spatial database.
An example of setting these in a .cfg file is:
label = Material properties
query_type = linear
iohandler.filename = mydb.spatialdb
4.5.2 UniformDB Spatial Database
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
(.cfg) 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-setting (.cfg) file. The properties for a UniformDB are:
values Array of names of values in spatial database.
data Array of values in spatial database.
Specify the physical properties of a linearly elastic, isotropic material in a .cfg file. The data values are dimensioned
with the appropriate units using Python syntax.
[pylithapp.timedependent.materials.material]
db_properties = spatialdata.spatialdb.UniformDB ; Set the db to a UniformDB
db_properties.values = [vp, vs, density] ; Set the names of the values in the database
db_properties.data = [5773.5*m/s, 3333.3*m/s, 2700.0*kg/m**3] ; Set the values in the database}
4.5.2.1 ZeroDispDB
The ZeroDispDB is 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, displacement-x, displacement-y, and displacement-z,
and are all set to zero. This makes it trivial to set displacements to zero on a boundary. The examples discussed in Chapter 7
on page 109 use this database.
4.5. DATABASES FOR BOUNDARIES, INTERFACES, AND MATERIAL PROPERTIES 43
4.5.3 SimpleGridDB Spatial Database
The SimpleGridDB object provides a much more efficient query algorithm than SimpleDB in cases with a orthogonal grid.
The points do not need to be uniformly spaced along each coordinate direction. Thus, in contrast to the SimpleDB there is
an implicit topology. Nevertheless, the points can be specified in any order, as well as over a lower-dimension than the spatial
dimension. For example, one can specify a 2-D grid in 3-D space provided that the 2-D grid is aligned with one of the coordinate
axes.
SimpleGridDB 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 C.3 on page 227.
.cfg files. The parameters for a spatial database are:
label Label for the database, which is used in diagnostic messages.
query_type Type of search query to perform. Values for this parameter are “linear” and “nearest” (default).
filename Filename for the spatial database.
An example of setting these parameters in a .cfg file is:
label = Material properties
query_type = linear
filename = mydb_grid.spatialdb
4.5.4 SCEC CVM-H Spatial Database (SCECCVMH)
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 7.6 on page 125 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, compressible materials. The Pyre properties for the SCEC CVM-H are:
data_dir Directory containing the SCEC CVM-H data files.
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.
squash Squash topography/bathymetry to sea level (make the earth’s surface flat).
squash_limit Elevation above which topography is squashed (geometry below this elevation remains undistorted).
Specify the physical properties of a linearly elastic, isotropic material using the SCEC CVM-H in a .cfg file.
db_properties = spatialdata.spatialdb.SCECCVMH ; Set the database to the SCEC CVM-H
# Directory containing the database data files.

db_properties.data_dir = /home/johndoe/data/sceccvm-h/vx53
db_properties.min_vs = 500*m/s ; Default value

db_properties.squash = True ; Turn on squashing
# Only distort the geometry above z=-1km in flattening the earth

db_properties.squash_limit = -1000.0
4.5.5 CompositeDB Spatial Database
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 CompositeDB spatial database for these cases. An
example would be:
[pylithapp.timedependent.materials.maxwell]
label = Maxwell material
id = 1
db_properties = spatialdata.spatialdb.CompositeDB
db_properties.db_A = spatialdata.spatialdb.SCECCVMH
db_properties.db_B = spatialdata.spatialdb.SimpleDB
quadrature.cell = pylith.feassemble.FIATSimplex
quadrature.cell.dimension = 3
[pylithapp.timedependent.materials.maxwell.db_properties]
values_A = [density, vs, vp]
db_A.label = Elastic properties from CVM-H
db_A.data_dir = /home/john/tools/vx53/bin
db_A.squash = False
values_B = [viscosity]
db_B.label = Vertically varying Maxwell material
db_B.iohandler.filename = ../spatialdb/mat_maxwell.spatialdb
Here we have specified a CompositeDB where the elastic properties (density, vs, vp) are given by the SCEC CVM-H, and
viscosity is described by a SimpleDB (mat_maxwell.spatialdb). The user must first specify db_properties as a
CompositeDB, and must then give the two components of this database (in this case, SCECCVMH and SimpleDB). 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 CompositeDB provides a flexible mechanism for specifying material properties or boundary conditions where
the variations come from two different sources.
4.5.6 TimeHistory Database
The TimeHistory 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 C.4 on page 228.
.cfg files. The parameters for a spatial database are:
label Label for the time history database, which is used in diagnostic messages.
filename Filename for the time history database.
label = Displacement time history
filename = mytimehistory.timedb
4.6 Labels and Identifiers for Materials, Boundary Conditions, and Faults
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/Trelis (block id). The id also tags the cells in the mesh for associating cells with a
4.7. PYLITH OUTPUT 45
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/Trelis) with a boundary condition. Some mesh generators use strings (LaGriT) to
identify groups of nodes while others (CUBIT/Trelis) use strings and integers. The default behavior in PyLith is to use strings
to identify groups for both LaGriT and CUBIT/Trelis meshes, but the behavior for CUBIT/Trelis meshes can be changed to
use the nodeset id (see Section 4.1.2.3 on page 30). 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/Trelis). 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.
4.7 PyLith Output

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 v1.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 5 on page 59 and 6 on page 83 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.
4.7.1 Output Manager
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.
The parameters for the OutputManager are:
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).
time_step Minimum time between output if output_freq is set to “time_step”.
skip Number of time steps between output if output_freq is set to “skip”. A value of 0 means every time
step is written.
writer Writer for data (VTK writer or HDF5 writer).
coordsys Coordinate system for vertex coordinates (currently ignored).
vertex_filter Filter to apply to all vertex fields (see Section 4.7.3.1 on page 47).
cell_filter Filter to apply to all cell fields (see Section 4.7.3.2 on page 47).
An example of setting the output parameters for a material in a .cfg file is
[pylithapp.timedependent.materials.elastic.output]
output_freq = time_step
time_step = 1.0*yr
cell_filter = pylith.meshio.CellFilterAvg
cell_info_fields = [density] ; limit diagnostic data to density
cell_data_fields = [total-strain, stress] ; default
writer.filename = dislocation-elastic.vtk
4.7.1.1 Output Over Subdomain
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-connected surface. The OutputSolnSubset is the specialized
OutputManager that implements this feature and, by default, includes the displacement field in the output. In addition to the
OutputManager parameters, the OutputSolnSubset includes:
label Label of group of vertices defining boundary surface.
vertex_data_fields Names of vertex data fields to output (default is [displacement]).
4.7.2 Output at Arbitrary Points
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, OutputSolnPoints, to interpolate the solution to arbitrary points. By default, the output man-
ager will include the displaceent time histories in the output. The locations are specified in a text file. In addition to the
OutputManager parameters, the OutputSolnSubset includes:
vertex_data_fields Names of vertex data fields to output (default is [displacement]).
reader Reader for points list (default is PointsList).
writer Writer for output (default is DataWriterVTKPoints). In most cases users will want to use the DataWriter-
HDF5.
4.7.2.1 PointsList Reader
This object corresponds to a simple text file containing a list of points (one per line) where output is desired. See C.6 on
page 229 for file format specifications. 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 PointsList are:
filename Names of file containing list of points.
comment_delimiter Delimiter at beginning of line to identify comments (default is #).
value_delimiter Delimiter used to separate values (default is whitespace).
4.7.3 Output Field Filters
Output fields may not directly correspond to the information a user desires. For example, the default output for the state
variables includes the values 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.
4.7.3.1 Vertex Field Filters
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 used very often.
VertexFilterVecNorm Computes the magnitude of a vector field at each location.
4.7.3.2 Cell Field Filters
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.
CellFilterAvg Compute the weighted average of the values within a cell. The weights are determined from the quadrature
associated with the cells.
4.7.4 VTK Output (DataWriterVTK)
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.
The parameters for the VTK writer are:
filename Name of VTK file.
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.
time_constant Value used to normalize time stamp in VTK files (default is 1.0 s).
4.7.5 HDF5/Xdmf Output (DataWriterHDF5, DataWriterHDF5Ext)
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 4.5 on the next page. 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, www.xdmf.org) 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 .xmf) 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.
B Important
The Xdmf format supports representation of two- and three-dimensional coordinates
of points, scalar fields, and three-dimensional vector and tensor fields but not two-
dimensional vector or tensor fields. Consequently, for two-dimensional vector fields
we build a three-component vector from the two-component vector (x and y compo-
nents) and a separate zero scalar field (z component). For tensor fields, we create a
scalar field for each of the tensor components, adding the component as a suffix to the
name of the field.
vertices
/ geometry
[nvertices, dim]
cells
topology
[ncells, ncorners]
displacement
vertex fields [ntsteps, nvertices, dim]
velocity
[ntsteps, nvertices, dim]
stress
cell fields [ntsteps, ncells, tensorsize]
strain
[ntsteps, ncells, tensorsize]
time
[ntsteps]
stations
[nvertices, maxstrlen]
Figure 4.5: General layout of a 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 vertex_fields or cell_fields but not both.
See Table 5.2 on page 61 in Section 5.1.3 on page 60 for a table of component values for tensor output in HDF5 files. To
avoid confusion about the ordering of components for tensor data, we separate the components in the Xdmf file.
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 .h5 suffix
replaced by .dat. 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 using the DataWriterHDF5 object or (2) storing
the datasets in external binary files with just metadata in the HDF5 files using the DataWriterHDF5Ext object. Both methods
provide similar performance because they will use MPI I/O if it is available.
L Warning
Storing the datasets within the HDF5 file in a parallel simulation requires that the
HDF5 library be configured with the --enable-parallel option. The binary
PyLith packages include this feature and it is a default setting in building HDF5 via
the PyLith Installer.
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 “work” and the HDF5/Xdmf files were written to “work/output”,
then ParaView should be run from the “work” directory. See Table 5.2 on page 61 in Section 5.1.3 on page 60 for a table of
component values for tensor output.
4.7.5.1 Parameters
The parametesr for the DataWriterHDF5 and DataWriterHDF5Ext objects is identical:

filename Name of HDF5 file (the Xdmf filename is generated from the same prefix).
An example of changing the writer from the default VTK writer to the HDF5 writer with external datasets (DataWriter-
HDF5Ext) for output over the domain in a .cfg file is
[pylithapp.timedependent.domain.output]
time_step = 1.0*yr
cell_data_fields = [displacement, velocity]
writer = pylith.meshio.DataWriterHDF5Ext
writer.filename = dislocation.h5
4.7.5.2 HDF5 Utilities
HDF5 includes several utilities for examining the contents of HDF5 files. h5dump is very handy for dumping the hierarchy,
dimensions of datasets, attributes, and even the dataset values to stdout.
# Dump the entire HDF5 file (not useful for large files).
$$ h5dump mydata.h5
# Dump the hierarchy of an HDF5 file.
$$ h5dump -n mydata.h5
# Dump the hierarchy with dataset dimensions and attributes.
$$ h5dump -H mydata.h5
# Dump dataset ’vertices’ in group ’/geometry’ to stdout.
$$ h5dump -d /geometry/vertices mydata.h5
We have also include a utility pylith_genxdmf (see Section 4.9.2 on page 52) that generates an appropriate Xdmf file from
a PyLith HDF5 file. This is very useful if you add fields to HDF5 files in post-processing and wish to view the results in
ParaView or Visit.
4.8 Tips and Hints
4.8.1 Tips and Hints For Running PyLith

• Examine the examples for a problem similar to the one you want to run and dissect it in detail.
• 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 displace-
ments).
• 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.
• 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.
• If you encounter errors or warnings, run pylithinfo or use the --help, --help-components, and --help-properties
command-line arguments when running PyLith to check the parameters to make sure PyLith is using the parameters you
intended.
• Use the --petsc.log_view, --petsc.ksp_monitor, --petsc.ksp_view, --petsc.ksp_converged_reason,
and --petsc.snes_converged_reason command-line arguments (or set them in a parameter file) to view PyLith
performance and monitor the convergence.
• Turn on the journals (see the examples) to monitor the progress of the code.
4.8.2 Troubleshooting
Consult the PyLith FAQ webpage (http://www.geodynamics.org/cig/community/workinggroups/short/

workarea/pylith-wiki) which contains a growing list of common problems and their corresponding solutions.
4.8.2.1 Import Error and Missing Library
ImportError: liblapack.so.2: cannot open shared object file: No such file or directory
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
source setup.sh 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.
4.8.2.2 Unrecognized Property ’p4wd’
-- pyre.inventory(error) } \\
-- p4wd <- ’true’ } \\
-- unrecognized property ’p4wd’ } \\
>> command line:: } \\
-- pyre.inventory(error) } \\
-- p4pg <- ’true’ } \\
-- unrecognized property ’ p4pg’}
Verify that the filenamempirun command included in the PyLith package is the first one on your PATH: which mpirun. If it
is not, adjust your PATH environment variable accordingly.
4.9. POST-PROCESSING UTILITIES 51
4.8.2.3 Detected zero pivor in LU factorization
-- Solving equations.
[0] PETSC ERROR: ----------------
Error Message -------------------------------
[0] PETSC ERROR: Detected zero pivot in LU factorization
see http://www.mcs.anl.gov/petsc/petsc-as/documentation/faq.html\#ZeroPivot!
This usually occurs when the null space of the system Jacobian is nonzero, such as the case of a problem without Dirich-
let boundary conditions on any boundary. If this arises when using the split fields and algebraic multigrid preconditioning,
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 4.1.5 on page 33.
4.8.2.4 Bus Error
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.
4.8.2.5 Segmentation Fault
A segmentation fault usually results from an invalid read/write to memory. It 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 3.1 on page 17) 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 --petsc.start_in_debugger command-line argument:
$$ pylith [..args..] --petsc.start_in_debugger
(gdb) continue
(gdb) backtrace
To use valgrind to detect the memory error, first go to your working directory and run the problem with --launcher.dry:
$$ pylith [..args..] --launcher.dry
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:
$$ mpirun /path/to/valgrind --log-file=valgrind-log /path/to/mpinemesis --pyre-start
[..lots of junk..]
4.9 Post-Processing Utilities

The PyLith distribution includes a few post-processing utilities. These are Python scripts that are installed into the same bin
directory as the pylith executable.
4.9.1 pylith_eqinfo
This utility computes the moment magnitude, seismic moment, seismic potency, and average slip at user-specified time snap-
shots from PyLith fault HDF5 output. The utility works with output from simulations with either prescribed slip and/or sponta-
neous rupture. Currently, we compute the shear modulus from a user-specified spatial database at the centroid of the fault cells.
In the future we plan to account for lateral variations in shear modulus across the fault when calculating the seismic moment.
The Python script is a Pyre application, so its parameters can be specified using .cfg and command line arguments just like
PyLith. The Pyre properties and facilities include:
output_filename Filename for output of slip information.
faults Array of fault names.
filename_pattern Filename pattern in C/Python format for creating filename for each fault. Default is output/fault_%s.h5.
snapshots Array of timestamps for slip snapshosts ([-1] means use last time step in file, which is the default).
snapshot_units Units for timestamps in array of snapshots.
db_properties Spatial database for elastic properties.
coordsys Coordinate system associated with mesh in simulation.
4.9.2 pylith_genxdmf
This utility generates Xdmf files from HDF5 files that conform to the layout used by PyLith. It is a simple Python script with a
single command line argument, the HDF5 file for input. Typically, it is used to regenerate Xdmf files that get corrupted or lost
due to renaming and moving. It is also useful in updating Xdmf files when users add fields to HDF5 files during post-processing.
$$ pylith_genxdmf --file=PYLITH_HDF5_FILE
L Warning
If the HDF5 files contain external datasets, then this utility should be run from the
same relative path to the HDF5 files as when they were created. For example, if a
PyLith simulation was run from directory work and HDF5 files were generated in
output/work, then the utility should be run from the directory work. Furthermore,
a visualization tool, such as ParaView, should also be started from the working direc-
tory work.
4.10 PyLith Parameter Viewer
New in v2.2.0
The PyLith Parameter Viewer provides a graphical user interface for viewing the parameters associated with a PyLith
simulation and the version information for PyLith and its dependencies. This viewer is an updated and interactive interface to
the information generated by the pylithinfo script. It displays the hiearchy of components and the parameters for each one,
including default values.
4.11 Installation
The PyLith Parameter Viewer is included in the PyLith binary distributions and PyLith Docker container for versions 2.1.5 and
later. Additionally, the PyLith Installer will install the Parameter Viewer by default. For manual installation you can download
4.12. RUNNING THE PARAMETER VIEWER 53
the PyLith Parameter Viewer tarball from the PyLith software page (https://geodynamics.org/cig/software/
pylith/). After downloading the tarball, unpack it. We recommend unpacking the tarball in the top-level PyLith directory.
$$ tar -xvf pylith_parameters-1.0.0.tgz
4.12 Running the Parameter Viewer

The steps to run the parameter viewer are:
1. Generate the parameter JSON file.

2. Start the web server (if not already running).
3. Load the parameter JSON file.
4.12.1 Generate the parameter JSON file
The parameter viewer uses a JSON file with all of the parameters collected from .cfg files, command line arguments, etc
as input. This file can be generated using pylithinfo (see Section 4.1.1.6) and, by default, it will be generated whenever
a pylith simulation is run. When using pylithinfo, the name of the parameter file can be set via a command line
argument. When using pylith, the DumpParametersJSON component contains a property for the name of the file. You can
set the filename on the command line
$$ pylith --dump_parameters.filename=FILENAME.json
or within a .cfg file

[pylithapp.dump_parameters]
filename = FILENAME.json
Currently, the JSON parameter file cannot be used to run a PyLith simulation. This feature will be added in an upcoming
release.
4.12.2 Start the web server
Change to the directory containing the pylith_paramviewer script (usually the parametersgui directory under the
top-level pylith directory), and run the pylith_paramviewer script. This will start a simple Python-based web server
on your local computer.
$$ cd parametersgui
$$ ./pylith\_paramviewer
The script will instruct you to point your web browswer to a local port on your computer. The default is http://127.0.0.
1:9000. You can change the default port using the --port command line argument to the pylith_paramviewer script.
4.13 Using the Parameter Viewer

When you point your web browser to the correct port, you should see the PyLith Parameter Viewer as shown in Figure 4.6.
Click the Choose File button and navigate to the desired JSON parameter file. The viewer tarball includes a sample parameter
file sample_parameters.json. Click the Reload button to reload the same JSON parameter file if you regenerate it. To
select a new JSON parameter file, click the Choose File button and navigate to the desired file.
Figure 4.6: Screenshot of PyLith Parameter Viewer in web browser upon startup.
4.13. USING THE PARAMETER VIEWER 55
4.13.1 Version Information
Click on the Version tab to examine the version information. This tab displays the same version information shown with the
--version command line argument to pylith in an easy to read layout. This includes information about the platform on
which pylith or pylithinfo was run, the PyLith version, and versions of the dependencies, as shown in Figure 4.7.
Figure 4.7: Screenshot of Version tab of the PyLith Parameter Viewer with sample JSON parameter file.
4.13.2 Parameter Information
Click on the Parameters tab to examine the hiearchy of components and the parameters for each. You can expand/collapse
the Component Hierarchy tree in the left panel by clicking on the triangles or facility name in blue to the left of the equals
sign (Figure 4.8). Clicking on the component in red to the right of the equals sign will show its parameters in the right panel
(Figure 4.8). The selected facility in the left panel whose parameters are shown in the right panel will be highlighted via a gray
background (Figure 4.9).
Figure 4.8: Screenshot of Parameters tab of the PyLith Parameter Viewer with sample JSON parameter file before selecting a
component in the left panel.
4.13. USING THE PARAMETER VIEWER 57
Figure 4.9: Screenshot of Parameters tab of the PyLith Parameter Viewer with sample JSON parameter file with the z_neg
facility selected.
Chapter 5
Material Models
5.1 Specifying Material Properties

Associating material properties with a given cell involves several steps.
1. In the mesh generation process, assign a material identifier to each cell.

2. Define material property groups corresponding to each material identifier.
3. Set the parameters for each material group using .cfg and/or command-line arguments.
4. Specify the spatial variation in material property parameters using a spatial database file.
5.1.1 Setting the Material Identifier
Each cell in the finite-element mesh must have a material identifier. This integer value is associated with a bulk material model.
The parameters of the material model need not be uniform for cells with the same material identifier. The bulk constitutive
model and numerical integration (quadrature) scheme will, however, be the same for all cells with the same material identifier
value. The material identifier is set during the mesh generation process. The procedure for assigning this integer value to a
cell depends on the mesh generator. For example, in the PyLith mesh ASCII format, the identifiers are listed in the cells group
using the material-id data; in CUBIT materials are defined using blocks; in LaGriT materials are defined by the attribute imt1
and the mregion command.
5.1.2 Material Property Groups
The material property group associates a material model (label for the material, a bulk constitutive model, and parameters for
the constitutive model) with a material identifier. In previous versions of PyLith it was necessary to specify containers that
defined the number of groups and associated information for each group. This was necessary because previous versions of Pyre
did not support dynamic arrays of components, and it was necessary to predefine these arrays. More recent versions of Pythia
do support this, however, and it is now possible to define material property groups using a .cfg file or on the command-line.
User-defined containers are no longer necessary, and the predefined containers are no longer available (or necessary). If a set
of material groups is not specified, a single material model is used for the entire problem. See Sections 7.8 on page 136 and 7.7
on page 128 for examples that demonstrate how to specify more than one material model.
59
60 CHAPTER 5. MATERIAL MODELS
5.1.3 Material Parameters
For each material group, there is a single component defining the material model to be used. The default material model is
ElasticIsotropic3D. For each material model, the available properties and facilities are:
id This is the material identifier that matches the integer value assigned to each cell in the mesh generation
process.
label Name or label for the material. This is used in error and diagnostic reports.
db_properties Spatial database specifying the spatial variation in the parameters of the bulk constitutive model (default
is a SimpleDB).
db_initial_stress Spatial database specifying the spatial variation in the initial stress (default is none).
db_initial_strain Spatial database specifying the spatial variation in the initial strain (default is none).
db_initial_state Spatial database specifying the spatial variation in the other initial state variables (default is none).
output The output manager used for outputting material information.
quadrature Numerical integration scheme used in integrating fields over each cell.
An example of setting these parameters in a .cfg file for a problem with two material groups is:
materials = [elastic,viscoelastic]
[pylithapp.timedependent.materials.elastic]
label = Elastic material
id = 1
db_properties.iohandler.filename = mat\_elastic.spatialdb
quadrature.cell = pylith.feassemble.FIATLagrange
[pylithapp.timedependent.materials.viscoelastic]
label = Viscoelastic material
id = 2
db_properties.iohandler.filename = mat_viscoelastic.spatialdb
These settings correspond to the the problem in Section 7.8 on page 136. The parameters for the bulk constitutive models
are specified using the spatial databases mat_elastic.spatialdb and mat_viscoelastic.spatialdb. Refer to
the discussion of each material model to find the parameters that must be specified in the spatial database. Appendix C.2 on
page 224 describes the format of the SimpleDB spatial database files. In a more realistic problem, a different spatial database,
and possibly a different material model, would be used for each material group.
In general, we average the output over the quadrature points within a cell and specify the name of the output files for each
material group:
[pylithapp.timedependent.materials.elastic.output]
writer.filename = dislocation-elastic.vtk
[pylithapp.timedependent.materials.viscoelastic.output]
writer.filename = dislocation-viscoelastic.vtk
These settings again correspond to the problem in Section 7.8 on page 136. The specification of a state variable base
filename (writer.filename settings) will cause two files to be created for each material group: an info file, which describes
the material property parameters used in the model, and a state variables file, which contains the state variable information. Note
that the material property parameters described by the info file are the parameters used internally by PyLith. In some cases they
are parameters convenient for use in the constitutive models and are derived from the parameters specified by the user via the
spatial database. If the problem has more than one time step, a state variable output file will be created for each requested time
step. We have requested that the values be averaged over each cell. Otherwise, output would be produced for each quadrature
5.1. SPECIFYING MATERIAL PROPERTIES 61
point, which can cause problems with some visualization packages. For this example problem, the material is three-dimensional
isotropic elastic, and is thus described by three parameters (λ, µ, ρ ), as described below. These properties are output by default.
Other material models require additional parameters, and if users want these to be output, they must be specified. Similarly,
other material models require state variables in addition to the default stress and strain variables that are used by all material
models. Additional output may be requested for a material model, as in this example (see Section 7.5 on page 121):
[pylithapp.timedependent.materials.material.output]
cell_data_fields = [total_strain, viscous_strain, stress]
cell_info_fields = [mu, lambda, density, maxwell_time]
The properties and state variables available for output in each material model are listed in Table 5.1. The order of the
state variables in the output arrays is given in Table 5.2. For the generalized Maxwell model, values of shear_ratio and
maxwell_time are given for each Maxwell element in the model (there are presently three, as described below). Similarly,
there are three sets of viscous_strain values for the generalized Maxwell model.
Table 5.1: Properties and state variables available for output for existing material models. Physical properties are available for
output as cell_info_fields and state variables are available for output as cell_data_fields.
Model Physical Properties State Variables Requires nonlin-
ear solver?
Elastic mu, lambda, density total_strain, No
stress,
cauchy_stress
Maxwell Viscoelastic mu, lambda, density, total_strain, No
maxwell_time stress,
cauchy_stress,
viscous_strain
Generalized Maxwell Vis- mu, lambda, density, total_strain, No
coelastic shear_ratio, stress,
maxwell_time cauchy_stress,
viscous_strain_1,
viscous_strain_2,
viscous_strain_3
Power-law Viscoelastic mu, lambda, density, total_strain, Yes
reference_strain_rate, stress,
reference_stress, cauchy_stress,
power_law_exponent viscous_strain
Drucker-Prager Elastoplas- mu, lambda, density, total_strain, Yes
tic alpha_yield, beta, stress,
alpha_flow cauchy_stress,
plastic_strain
Table 5.2: Order of components in tensor state-variables for material models.

State Variable 2D 3D
total_strain ²xx , ² y y , ²x y ²xx , ² y y , ²zz , ²x y , ² y z , ²xz
stress, cauchy_stress σxx , σ y y , σx y σxx , σ y y , σzz , σx y , σ y z , σxz
viscous_strain, plastic_strain ²xx , ² y y , ²zz , ²x y ²xx , ² y y , ²zz , ²x y , ² y z , ²xz
stress4 σxx , σ y y , σzz , σx y
5.1.4 Initial State Variables
In many problems of interest, the state variables describing a material model may already have nonzero values prior to the
application of any boundary conditions. For problems in geophysics, the most common example is a problem that includes the
effects of gravitational body forces. In the real earth, rocks were emplaced and formed under the influence of gravity. When
performing numerical simulations, however, it is not possible to represent the entire time history of rock emplacement. Instead,
gravity must be “turned on” at the beginning of the simulation. Unfortunately, this results in unrealistic amounts of deformation
at the beginning of a simulation. An alternative is to provide initial state variables for the region under consideration. This
allows the specification of a set of state variables that is consistent with the prior application of gravitational body forces. In a
more general sense, initial values for state variables may be used to provide values that are consistent with any set of conditions
that occurred prior to the beginning of a simulation. The current release of PyLith allows the specification of initial stresses,
strains, and state variables for all materials; however, not all of the initial state variables are presently used. For example,
cauchy_stress is available as a state variable for all materials, but specifying an initial value would not make sense for
most problems.
5.1.4.1 Specification of Initial State Variables
State variables are specific to a given material, so initial values for state variables are specified as part of the material description.
The default is that no initial state variables are specified. In computing the elastic prestep, appropriate values for the state
variables are set; otherwise the state variables are set to zero. To override this behavior, specify a spatial database for the initial
stress, strain, and/or state variables as in the example from the example in Section 7.8 on page 136:
db_initial_stress = spatialdata.spatialdb.SimpleDB
db_initial_stress.iohandler.filename = initial\_stress.spatialdb
L Warning
Using the elastic prestep with initial state variables will generally lead to the state vari-
ables being ignored (the initial out of plane stress is the exception), because the elastic
prestep will set the state variables based on the elastic solution.
L Warning
Currently, PyLith assumes initial displacements and velocities of zero, so any initial
strain and state variables should be consistent with these initial conditions. This limita-
tion will be removed in future releases.
As mentioned in section D.1 on page 231, plane strain problems do not include the out-of-plane stress component (σzz ),
and an additional state variable (stress-zz-initial) is provided for all two-dimensional viscoelastic and elastoplastic
models. To completely specify the initial stresses, the user must provide two spatial databases: an initial stress database that
includes the three 2D stress components (σxx , σ y y , and σx y ) and an additional database containing the out of plane stress and
initial values for all other state variables for the given material. The complete initial stress field may then be defined in the
.cfg file as:
[pylithapp.problem.materials.powerlaw]
# First specify initial 2D stresses
db_initial_stress.label = 2D initial stress
db_initial_stress.iohandler.filename = inititial_stress_2d.spatialdb
# Now specify out-of-plane initial stresses (and all other state variables)
db_initial_state = spatialdata.spatialdb.SimpleDB
db_initial_state.label = Out of plane strain initial stress
db_initial_state.iohandler.filename = initial_state_2d.spatialdb
5.1. SPECIFYING MATERIAL PROPERTIES 63
Table 5.3: Values in spatial database for initial state variables for 3D problems. 2D problems use only the relevant values. Note
that initial stress and strain are available for all material models. Some models have additional state variables (Table 5.1 on
page 61) and initial values for these may also be provided.
State Variable Values in Spatial Database
initial stress stress-xx, stress-yy, stress-zz, stress-xy, stress-yz,
stress-xz
initial strain total-strain-xx, total-strain-yy, total-strain-zz,
total-strain-xy, total-strain-yz, total-strain-xz
5.1.5 Cauchy Stress Tensor and Second Piola-Kirchoff Stress Tensor
In outputting the stress tensor (see Tables 5.1 on page 61 and 5.2 on page 61), the tensor used internally in the formulation of the
governing equation is the stress field available for output. For the infinitesimal strain formulation this is the Cauchy stress
tensor; for the finite strain formulation, this is the second Piola-Kirchoff stress tensor. The user may also explicitly request
output of the Cauchy stress tensor (cauchy_stress field). Obviously, this is identical to the stress field when using the
infinitesimal strain formulation. See section 2.5 on page 14 for a discussion of the relationship between the Cauchy stress tensor
and the second Piola-Kirchhoff stress tensor.
B Important
Although the second Piola-Kirchoff stress tensor has little physical meaning, the second
Piola-Kirchoff stress tensor (not the Cauchy stress tensor) values should be specified in
the initial stress database when using the finite strain formulation.
5.1.6 Stable time step
PyLith computes the stable time step in both quasi-static and dynamic simulations. In quasi-static simulations the stability
of the implicit time stepping scheme does not depend on the time step; instead, the stable time step is associated with the
accuracy of the solution. For viscoelastic materials the stable time step uses 1/5 of the minimum viscoelastic relaxation time.
In purely elastic materials, the accuracy is independent of the time step, so the stable time step is infinite. The same is true
for elastoplastic materials, since there is no inherent time scale for these problems. Depending on the loading rate, however,
it is possible to impose a load increment that is large enough so that the resulting solution may be inaccurate or divergent. In
quasi-static simulations we recompute the stable time step at every time step.
L Warning
Caution must be used in assigning time step sizes for elastoplastic problems, and the
linear and nonlinear convergence should be monitored closely.
In dynamic simulations the stability of the explicit time-stepping scheme integration does depend on the time step via the
Courant-Friderichs-Lewy condition [Courant et al., 1967]. This condition states that the critical time step is the time it takes for
the P wave to travel across the shortest dimension of a cell. In most cases this is the shortest edge length. However, distorted
cells which have relatively small areas in 2-D or relatively small volumes in 3-D for the given edge lengths also require small
time steps due to the artificially high stiffness associated with the distorted shape. As a result, we set the stable time step to be
the smaller of the shortest edge length and a scaling factor times the radius of an inscribed circle (in 2-D),
d t = min(e min , 3.0r i nscr i bed ) (5.1)

s
k(k − e 0 )(k − e 1 )(k − e 2 )
r i nscr i bed = (5.2)
k
1
k = (e 0 + e 1 + e 2 ) (5.3)
2
and sphere (in 3-D),
d t = min(e min , 6.38r i nscr i bed ) (5.4)

r i nscr i bed = 3V /(A 0 + A 1 + A 2 + A 3 ), (5.5)
where e i denotes the length of edge i , A i denotes the area of face i , and V is the volume of the cell. We determined the scaling
factoring empirically using several benchmarks. In dynamic simulations we check the stable time step only at the beginning
of the simulation. That is, we assume the elastic properties and mesh do not change, so that the stable time step is constant
throughout the simulation.
The stable time step is used in all three of the time stepping schemes used by PyLith (see section 4.2.4 on page 38). In
general, an error is generated if the user attempts to use a time step size larger than the stable time step. The stable time
steps for each cell can be included in the output with the other cell_info_fields. For implicit time stepping the field is
stable_dt_implicit and for explicit time stepping the field is stable_dt_explicit.
5.2 Elastic Material Models

The generalized form of Hooke’s law relating stress and strain for linear elastic materials is
I
σi j = C i j kl ²kl − ²kl + σiI j ,
¡ ¢
(5.6)
where we have included both initial strains and initial stresses, denoted with the superscript I. Due to symmetry considerations,
however, the 81 components of the elasticity matrix are reduced to 21 independent components for the most general case of
anisotropic elasticity. Representing the stress and strain in terms of vectors, the constitutive relation may be written
→
−
σ = C ~² −~²I +~
¡ ¢
σI , (5.7)
where
 
C 1111 C 1122 C 1133 C 1112 C 1123 C 1113

 C 1122 C 2222 C 2233 C 2212 C 2223 C 2213 

C 1133 C 2233 C 3333 C 3312 C 3323 C 3313
 
C = . (5.8)
 
 C 1112 C 2212 C 3312 C 1212 C 1223 C 1213 
 
 C 1123 C 2223 C 3323 C 1223 C 2323 C 2313 
C 1113 C 2213 C 3313 C 1213 C 2313 C 1313
For the case of isotropic elasticity, the number of independent components reduces to two, and the model can be characterized
by two parameters, Lame’s constants µ and λ. Lame’s constants are related to the density (ρ ), shear wave speed (v s ), and
compressional wave speed (v p ) via
µ =ρv s2
(5.9)
λ =ρv p2 − 2µ
5.2. ELASTIC MATERIAL MODELS 65
Table 5.4: Values in spatial databases for the elastic material constitutive models.
Spatial database Value Description
db_properties vp Compressional wave speed, v p
vs Shear wave speed, v s
density Density, ρ
db_initial_stress stress-xx, . . . Initial stress components
db_initial_strain total-strain-xx, . . . Initial strain components
5.2.1 2D Elastic Material Models
In 2D we can write Hooke’s law as

I   I 
σ11 ²11 − ²11 σ11
   
C 1111 C 1122 C 1112
 σ22  =  C 1122 I I 
C 2222 C 2212   ²22 − ²22  +  σ22 . (5.10)
σ12 C 1112 C 2212 C 1212 I
²12 − ²12 I
σ12
5.2.1.1 Elastic Plane Strain
If the gradient in deformation with respect to the x 3 axis is zero, then ²33 = ²13 = ²23 = 0 and plane strain conditions apply, so
we have
I   I 
σ11 λ + 2µ λ ²11 − ²11 σ11
   
0
 σ22  =  I I 
λ λ + 2µ 0   ²22 − ²22  +  σ22 . (5.11)
σ12 0 0 2µ I
²12 − ²12 I
σ12
5.2.1.2 Elastic Plane Stress
If the x 1 x 2 plane is traction free, then σ33 = σ13 = σ23 = 0 and plane stress conditions apply, so we have
  4µ(λ+µ) 2µλ 
I   I 
σ11 0 ²11 − ²11 σ11

λ+2µ λ+2µ
 σ22  =  I I
0  ²22 − ²22  +  σ22  ,
2µλ 4µ(λ+µ) 
(5.12)
λ+2 λ+2µ

σ12 0 0 2µ
I
²12 − ²12 I
σ12
where
λ I
²33 = − (²11 + ²22 ) + ²33
λ + 2µ (5.13)
²13 = ²23 = 0 .
5.2.2 3D Elastic Material Models
5.2.2.1 Isotropic
For this case the stress-strain matrix, C , becomes
λ + 2µ λ λ
 
0 0 0

 λ λ + 2µ λ 0 0 0 

λ λ λ + 2µ 0 0 0
 
C = . (5.14)
 
 0 0 0 2µ 0 0 
 
 0 0 0 0 2µ 0 
0 0 0 0 0 2µ
5.3 Viscoelastic Materials
At present, there are six viscoelastic material models available in PyLith (Table 5.5 and Figure 5.1 on the facing page). Future
code versions may include alternative formulations for the various material models (Appendix D on page 231), so that users
may use the most efficient formulation for a particular problem. Note that both 2D and 3D viscoelastic models are described,
but we present below only the 3D formulations. The 2D formulations are easily obtained from the plane strain definition. The
one aspect of the 2D formulations that is different is the specification of initial stresses. Since 2D models only have three
tensor components, it is not possible to specify the normal stress in the out-of-plane direction (σ33 ), which is generally nonzero,
using the same method as the other tensor components. To allow for the specification of this initial stress component, an
I
additional state variable corresponding to σ33 is provided (stress_zz_initial). This state variable is provided for all of
the viscoelastic material models as well as the plane strain Drucker-Prager elastoplastic model. See section 5.1.4 on page 61
for additional information on specifying initial stresses for plane strain problems. For the PowerLawPlaneStrain model, all four
of the stress components are needed, so a 4-component stress state variable (stress4) is provided in addition to the normal
3-component stress state variable (see Table 5.1 on page 61).
Table 5.5: Available viscoelastic materials for PyLith.

Model Name Description
MaxwellPlaneStrain Plane strain Maxwell material with linear viscous rheology
GenMaxwellPlaneStrain Plane strain generalized Maxwell material (3 Maxwell models in parallel)
PowerLawPlaneStrain Plane strain Maxwell material with power-law viscous rheology
MaxwellIsotropic3D Isotropic Maxwell material with linear viscous rheology
GenMaxwellIsotropic3D Generalized model consisting of 3 Maxwell models in parallel
PowerLaw3D Isotropic Maxwell material with power-law viscous rheology
5.3.1 Definitions
In the following sections, we use a combination of vector and index notation (our notation conventions are shown in Table 2.1
on page 7). When using index notation, we use the common convention where repeated indices indicate summation over the
range of the index. We also make frequent use of the scalar inner product. The scalar inner product of two second-order tensors
may be written
a · b = ai j bi j . (5.15)
Although the general constitutive relations are formulated in terms of the stress and strain, we frequently make use of the
deviatoric stress and strain in our formulation. We first define the mean stress, P , and mean strain, θ :
σi i ²i i
P= , θ= , (5.16)
3 3
where the σi i and ²i i represent the trace of the stress and strain tensors, respectively. We then define the deviatoric components
of stress and strain as
S i j = σi j − P δi j , e i j = ²i j − θδi j , (5.17)
where δi j is the Kronecker delta. Using the deviatoric components, we define the effective stress, σ, the second deviatoric
stress invariant, J 20 , the effective deviatoric strain, e , and the second deviatoric strain invariant, L 02 , as
r
3
σ= S ·S
2
1
J 20 = S · S . (5.18)
2
r
2
e= e ·e
3
1
L 02 = e · e
2
5.3. VISCOELASTIC MATERIALS 67
Figure 5.1: Spring-dashpot 1D representations of the available 3D elastic and 2D/3D viscoelastic material models for PyLith.
The top model is a linear elastic model, the middle model is a Maxwell model, and the bottom model is a generalized Maxwell
model. For the generalized Maxwell model, λ and µt ot are specified for the entire model, and then the ratio µi /µt ot is specified
for each Maxwell model. For the power-law model, the linear dashpot in the Maxwell model is replaced by a nonlinear dashpot
obeying a power-law.
Due to the symmetry of the stress and strain tensors, it is sometimes convenient to represent them as vectors:
−→ £
σT = σ11 σ22 σ33 σ12 σ23 σ31
¤
(5.19)
−
→ £
²T = ²11 ²22 ²33 ²12 ²23 ²31
¤
.
Note that when taking the scalar inner product of two tensors represented as vectors, it is necessary to double the products
representing off-diagonal terms.
For quantities evaluated over a specific time period, we represent the initial time as a prefixed subscript and the end time
as a prefixed superscript. In cases where the initial time does not appear, it is understood to be −∞.
5.3.2 Linear Viscoelastic Models
Linear viscoelastic models are obtained by various combinations of a linear elastic spring and a linear viscous dashpot in series
or parallel. The simplest example is probably the linear Maxwell model, which consists of a spring in series with a dashpot, as
shown in Figure 5.1 on the previous page. For a one-dimensional model, the response is given by
d ²Tot al d ²D d ²S σ 1 d σ
= + = + , (5.20)
dt dt dt η E dt
where ²Tot al is the total strain, ²D is the strain in the dashpot, ²S is the strain in the spring, σ is the stress, η is the viscosity of the
dashpot, and E is the spring constant. When a Maxwell material is subjected to constant strain, the stresses relax exponentially
with time. When a Maxwell material is subjected to a constant stress, there is an immediate elastic strain, corresponding to
the response of the spring, and a viscous strain that increases linearly with time. Since the strain response is unbounded, the
Maxwell model actually represents a fluid.
Another simple model is the Kelvin-Voigt model, which consists of a spring in parallel with a dashpot. In this case, the
one-dimensional response is given by
d ² (t )
σ (t ) = E ² (t ) + η . (5.21)
dt
As opposed to the Maxwell model, which represents a fluid, the Kelvin-Voigt model represents a solid undergoing reversible,
viscoelastic strain. If the material is subjected to a constant stress, it deforms at a decreasing rate, gradually approaching the
strain that would occur for a purely elastic material. When the stress is released, the material gradually relaxes back to its
undeformed state.
The most general form of linear viscoelastic model is the generalized Maxwell model, which consists of a spring in parallel
with a number of Maxwell models (see Figure 5.1 on the preceding page). Using this model, it is possible to represent a number
of simpler viscoelastic models. For example, a simple Maxwell model is obtained by setting the elastic constants of all springs
to zero, with the exception of the spring contained in the first Maxwell model (µ1 ). Similarly, the Kelvin-Voigt model may be
obtained by setting the elastic constants µ2 = µ3 = 0, and setting µ1 = ∞ (or a very large number).
5.3.3 Formulation for Generalized Maxwell Models
As described above, the generalized Maxwell viscoelastic model consists of a number of Maxwell linear viscoelastic models
in parallel with a spring, as shown in Figure 5.1 on the previous page. PyLith includes the specific case of a spring in parallel
with three Maxwell models. As described in the previous paragraph, a number of common material models may be obtained
from this model by setting the shear moduli of various springs to zero or infinity (or a large number), such as the Maxwell
model, the Kelvin model, and the standard linear solid. We follow formulations similar to those used by Zienkiewicz and
Taylor [Zienkiewicz and Taylor, 2000] and Taylor [Taylor, 2003]. In this formulation, we specify the total shear modulus of
the model (µt ot ) and Lame’s constant (λ). We then provide the fractional shear modulus for each Maxwell element spring in
the model. It is not necessary to specify the fractional modulus for µ0 , since this is obtained by subtracting the sum of the
other ratios from 1. Note that the sum of all these fractions must equal 1. We use a similar formulation for our linear Maxwell
viscoelastic model, but in that case µ0 is always zero and we only use a single Maxwell model. The parameters defining the
standard Maxwell model are shown in Table 5.6 on page 71, and those defining the generalized Maxwell model are shown in
Table 5.7 on page 71.
As for all our viscoelastic models, the volumetric strain is completely elastic, and the viscoelastic deformation may be
expressed purely in terms of the deviatoric components:
" #
N
i I
S = 2µt ot µ0 e + µi q − e + S I ; P = 3K θ − θ I + P I ,
X ¡ ¢
(5.22)
i =1
where K is the bulk modulus, N is the number of Maxwell models, and the variable q i follows the evolution equations
1 i
q̇ i + q = ė. (5.23)
τi
The τi are the relaxation times for each Maxwell model:
ηi
τi = . (5.24)
µt ot µi
An alternative to the differential equation form above is an integral equation form expressed in terms of the relaxation
modulus function. This function is defined in terms of an idealized experiment in which, at time labeled zero (t = 0), a
specimen is subjected to a constant strain, e 0 , and the stress response, S (t ), is measured. For a linear material we obtain:
S (t ) = 2µ (t ) e 0 − e I + S I ,
¡ ¢
(5.25)
where µ (t ) is the shear relaxation modulus function. Using linearity and superposition for an arbitrary state of strain yields an
integral equation:
Zt
S (t ) = µ (t − T ) ė d T . (5.26)
−∞
If we assume the modulus function in Prony series form we obtain

Ã !
N −t
µ (t ) = µt ot µ0 + µi exp
X
, (5.27)
i =1 τi
where
N
µ0 + µi = 1 .
X
(5.28)
i =1
With the form in Equation 5.27, the integral equation form is identical to the differential equation form.
If we assume the material is undisturbed until a strain is suddenly applied at time zero, we can divide the integral into
Zt Z0− Z0+ Zt
(·) d T = (·) d T + (·) d T + (·) d T . (5.29)
−∞ −∞ 0− 0+
The first term is zero, the second term includes a jump term associated with e 0 at time zero, and the last term covers the
subsequent history of strain. Applying this separation to Equation 5.26,
Z t
S (t ) = 2µ (t ) e 0 − e I + S I + 2 µ (t − T ) ė (T ) d T ,
¡ ¢
(5.30)
0
where we have left the sign off of the lower limit on the integral.
Substituting Equation 5.27 into 5.30, we obtain
Zt
    
 N −t t 
S (t ) = 2µt ot µ0 e (t ) + µi exp e + exp ė (T ) d T  − e I + S I .
X
0 (5.31)
 i =1 τi τi 
0
We then split each integral into two ranges: from 0 to t n , and from t n to t , and define each integral as
Zt
T
i 1i (t ) = exp ė (T ) d T . (5.32)
τi
0
The integral then becomes

Zt
T
i 1i (t ) = i 1i (t n ) + exp ė (T ) d T . (5.33)
τi
tn
Including the negative exponential multiplier:

−t 1
h 1i (t ) = exp i . (5.34)
τi i
Then
−∆t 1
h 1i (t ) = exp h (t n ) + ∆h i , (5.35)
τi i
where
Zt
−t T
∆h i = exp exp ė (T ) d T . (5.36)
τi τi
tn
Approximating the strain rate as constant over each time step, the solution may be found as
τi
µ ¶
−∆t ¡
∆h i = e − e n = ∆h i e − e n .
¢ ¡ ¢
1 − exp (5.37)
∆t τi
The approximation is singular for zero time steps, but a series expansion may be used for small time-step sizes:
1 ∆t 1 ∆t 2 1 ∆t 3
µ ¶ µ ¶ µ ¶
∆h i ≈ 1 − + − +··· . (5.38)
2 τi 3! τi 4! τi
This converges with only a few terms. With this formulation, the constitutive relation now has the simple form:
Ã !
N
S (t ) = 2µt ot µ0 e (t ) + µi h 1i (t ) − e I + SI .
X
(5.39)
i =1
We need to compute the tangent constitutive matrix when forming the stiffness matrix. In addition to the volumetric
contribution to the tangent constitutive matrix, we require the deviatoric part:
∂S ∂S ∂e
= , (5.40)
∂² ∂e ∂²
where the second derivative on the right may be easily deduced from Equation 5.17 on page 66. The other derivative is given
by
∂h 1i
" #
∂S N
= 2µt ot µ0 I + µi
X
, (5.41)
∂e i =1 ∂e
where I is the identity matrix. From Equations 5.35 through 5.37, the derivative inside the brackets is
∂h 1i
= ∆h i (∆t ) I . (5.42)
∂e
The complete deviatoric tangent relation is then
" #
∂S N ∂e
= 2µt ot µ0 + µi ∆h i (∆t )
X
. (5.43)
∂² i =1 ∂²
We use this formulation for both our Maxwell and generalized Maxwell viscoelastic models. For the Maxwell model,
µ0 = 0 and N = 1. For the generalized Maxwell model, N = 3. The stable time step is equal to 1/5 of the minimum relaxation
time for all of the Maxwell models (equation 5.24 on the previous page).
Table 5.6: Values in spatial databases for the linear Maxwell viscoelastic material constitutive model.
density Density, ρ
viscosity Viscosity, η
db_initial_state viscous-strain-xx, . . . Initial viscous strain components
stress-zz-initial Initial out-of-plane stress (2D only)
Table 5.7: Values in spatial database used as parameters in the generalized linear Maxwell viscoelastic material constitutive
model.
density Density, ρ
shear-ratio-1 Shear ratio for Maxwell model 1, µ1 /µt ot
viscosity-1 Viscosity for Maxwell model 1, η 1
db_initial_state viscous-strain-1-xx, . . . Initial viscous strain components for Maxwell model 1
viscous-strain-2-xx, . . . Initial viscous strain components for Maxwell model 2
viscous-strain-3-xx, . . . Initial viscous strain components for Maxwell model 3
5.3.4 Effective Stress Formulations for Viscoelastic Materials
As an alternative to the approach outlined above, an effective stress function formulation [Kojic and Bathe, 1987] may be
employed for both a linear Maxwell model and a power-law Maxwell model. Note that this formulation is not presently
employed for linear viscoelastic models (see Appendix D on page 231), but it is used for power-law viscoelastic materials. For
the viscoelastic materials considered here, the viscous volumetric strains are zero (incompressible flow), and it is convenient to
separate the general stress-strain relationship at time t + ∆t into deviatoric and volumetric parts:
t +∆t E ¡t +∆t 1 ¡t +∆t

e − t +∆t e C − e I + S I = e − t +∆t e C − e I
¢ ¢
S= (5.44)
1+ν aE
t +∆t E ¡t +∆t 1 ¡t +∆t
θ − θI + P I = θ − θI ,
¢ ¢
P=
1 − 2ν am
where t +∆t e is the total deviatoric strain, t +∆t e C is the total viscous strain, e I is the initial deviatoric strain, t +∆t P is the pressure,
t +∆t
θ is the mean strain evaluated at time t +∆t , and θ I is the initial mean strain. The initial deviatoric stress and initial pressure
are given by S I and P I , respectively. The topmost equation in Equation 5.44 may also be written as
t +∆t 1 t +∆t 0
S= ( e − ∆e C ) + S I , (5.45)
aE
where
t +∆t 0
e = t +∆t e − t e C − e I , ∆e C = t +∆t e C − t e C . (5.46)
The creep strain increment is approximated using
∆e C = ∆t τ γτ S , (5.47)
where, using the α-method of time integration,

τ
S = (1 − α)tI S + αtI +∆t S + S I = (1 − α)t S + αt +∆t S , (5.48)
and
τ 3∆e C
γ= , (5.49)
2∆t τ σ
where
r
C 2 C
∆e = ∆e · ∆e C (5.50)
3
and
q
τ
σ = (1 − α)tI σ + αtI +∆t σ + σI = 3τ J 20 . (5.51)
To form the global stiffness matrix, it is necessary to provide a relationship for the viscoelastic tangent material matrix
relating stress and strain. If we use vectors composed of the stresses and tensor strains, this relationship is
∂t +∆t →−
σ
CV E = →
− . (5.52)
∂ t +∆t ²
In terms of the vectors, we have
t +∆t
σi = t +∆t S i + t +∆t P ; i = 1, 2, 3 (5.53)
t +∆t
σi = t +∆t S i ; i = 4, 5, 6
Therefore,
1
C iVj E = C i0 j + ; 1 ≤ i, j ≤ 3 . (5.54)
3a m
C iVj E = C i0 j ; otherwise
Using the chain rule,
t +∆t 0 t +∆t
∂t +∆t S i ∂t +∆t S i ∂ ek ∂ el
C i0 j = = . (5.55)
∂t +∆t ² j ∂t +∆t e k0 ∂t +∆t e l ∂t +∆t ² j
From Equation 5.46 on the facing page, we obtain

∂t +∆t e k0
= δkl , (5.56)
∂t +∆t e l
and from Equation 5.17 on page 66:
 
2 −1 −1
∂t +∆t e l 1
= −1 2 −1  ; 1 ≤ l , j ≤ 3 (5.57)
∂t +∆t ² j 3
−1 −1 2
∂t +∆t e l
= δl j ; otherwise.
∂t +∆t ² j
The first term of Equation 5.55 depends on the particular constitutive relationship, and the complete tangent matrix may then
be obtained from Equation 5.54.
5.3.4.1 Power-Law Maxwell Viscoelastic Material
Laboratory results on rock rheology are typically performed using a triaxial experiment, and the creep data are fit to a power-law
equation of the form (e.g., [Kirby and Kronenberg, 1987]):
µ ¶ µ ¶
−Q −Q n
²̇C11 = A E exp (σ1 − σ3 )n = A E exp σd , (5.58)
RT RT
where ²̇C11 is the strain rate in the direction of the maximum principal stress (σ1 ), A E is the experimentally-derived pre-
exponential constant, Q is the activation enthalpy, R is the universal gas constant, T is the absolute temperature, n is the
power-law exponent, σ3 (= σ2 ) is equal to the confining pressure, and σd is the differential stress. To properly formulate the
flow law, it must be generalized so that the results are not influenced by the experiment type or the choice of coordinate systems
(e.g., [Paterson, 1994]). The flow law may then be generalized in terms of the deviatoric stress and strain rate invariants:
−Q q 0 n
q µ ¶
L̇ 0C
2 = A M exp J2 , (5.59)
RT
where A M is now a pre-exponential constant used in the formulation for modeling. In practice, it is necessary to compute each
strain rate component using the flow law. This is accomplished using:
−Q q 0 n−1
µ ¶
ė Cij = A M exp J2 Si j . (5.60)
RT
Note that Equations 5.59 and 5.60 are consistent, since Equation 5.59 may be obtained from Equation 5.60 by taking the scalar
inner product of both sides, multiplying by 1/2, and taking the square root.
In a triaxial experiment with confining pressure P c , we have
σ2 = σ3 = P c
app
σ1 = σ1 (5.61)
σ1 + 2P c
P= ,
3
app
where σ1 is the applied load. The deviatoric stresses are then:
2
S1 = (σ1 − P c )
3
1
S 2 = S 3 = − (σ1 − P c ) . (5.62)
3
This gives
2 2
S1 = (σ1 − σ3 ) = σd
3 3
1 1
S 2 = S 3 = − (σ1 − σ3 ) = − σd . (5.63)
3 3
In terms of the second deviatoric stress invariant, we then have
q σd
J 20 = p . (5.64)
3
Under the assumption that the creep measured in the laboratory experiments is incompressible, we have
ė C11 = ²̇11
1
ė C22 = ė C33 = − ²̇11 . (5.65)
2
In terms of the second deviatoric strain rate invariant we then have
p
3
q
0C
L̇ 2 = ²̇11 . (5.66)
2
Substituting Equations 5.64 and 5.66 into Equation 5.58 on the preceding page, we obtain
p n+1
−Q q 0 n
µ ¶
3
q
L̇ 0C
2 = A E exp J2 , (5.67)
2 RT
and therefore,
p n+1
3
AM = AE . (5.68)
2
When the exponential factor is included, we define a new parameter:
µ ¶ p n+1 µ ¶
−Q 3 −Q
A T = A M exp = A E exp . (5.69)
RT 2 RT
There is a problem with the usage of parameters A E , A M , and A T . Since the dimensions of these parameters are depen-
dent on the value of the power-law exponent, they are not really constants. In addition to being logically inconsistent, this
presents problems when specifying parameters for PyLith, since the power-law exponent must be known before the units can
be determined. An alternative way of writing the flow rule is (e.g., [Prentice, 1968]):
q q n
L̇ 0C
2
J 20
=  , (5.70)
 
ė 0 S0
where ė 0 and S 0 are reference values for the strain rate and deviatoric stress. This means that
ė 0
= AT . (5.71)
S 0n
Users must therefore specify three parameters for a power-law material. The properties reference-strain-rate, reference-stres
and power-law-exponent in Table 5.8 on page 77 refer to ė 0 , S 0 , and n , respectively. To specify the power-law properties
for PyLith using laboratory results, the user must first compute A T using Equation 5.69 on the facing page. Then, values for ė 0
and S 0 must be provided. The simplest method is probably to assume a reasonable value for the reference strain rate, and then
compute S 0 as
¶1
ė 0
µ
n
S0 = . (5.72)
AT
A utility code (powerlaw_gendb.py) is provided to convert laboratory results to the properties used by PyLith. To use
the code, users must specify the spatial variation of A E , Q , n , and T . An additional parameter is given to define the units of A E .
The user then specifies either a reference stress or a reference strain rate, and a database suitable for PyLith is generated. This
utility is described more fully in Section 7.8.6.6 on page 150.
The flow law in component form is
q n−1
ė 0 J 20 Si j
ė Cij = , (5.73)
S 0n
and the creep strain increment is approximated as
q n−1
τJ0 τ
∆t ė 0 2 S ∆t ė 0 τ σn−1 τ S
C
∆e ≈ = p n . (5.74)
S 0n 3S 0
Therefore,
q n q n−1
2∆t ė 0 τ J 20 2∆t ė τ n
σ ė 0 τ J 20
, and τ γ =
0
∆ē C ≈ p n = p n+1 . (5.75)
3S 0 3 S 0n S 0n
substituting Equations 5.48 on page 72, 5.74, and 5.75 into 5.45 on page 72, we obtain:
1 ©t +∆t 0
t +∆t
e − ∆t τ γ (1 − α)t S + αt +∆t S + S I ,
£ ¤ª
S= (5.76)
aE
which may be rewritten:
t +∆t
S a E + α∆t τ γ = t +∆t e 0 − ∆t τ γ (1 − α)t S + a E S I .
¡ ¢
(5.77)
Taking the scalar inner product of both sides we obtain:
a 2 t +∆t J 20 − b + c τ γ − d 2 τ γ2 = F = 0 , (5.78)
where
a = a E + α∆t τ γ
1 t +∆t 0 t +∆t 0
b= e · e + a E t +∆t e 0 · S I + a E2 I J 20 . (5.79)
2
c = ∆t (1 − α) t +∆t e 0 ·t S + ∆t (1 − α) a E t S · S I
q
d = ∆t (1 − α) t J 20
Equation 5.78 is a function of a single unknown – the square root of the second deviatoric stress invariant at time t + ∆t – and
may be solved by bisection or by Newton’s method. Once this parameter has been found, the deviatoric stresses for the current
time step may be found from Equations 5.51 on page 72, 5.75, and 5.76, and the total stresses may be found by combining the
deviatoric and volumetric components from Equation 5.44 on page 72.
Once the stresses are computed for the current time step, we can compute the relaxation time (used in computing the stable
time step) by first computing the effective viscous strain rate from Equation 5.73:
³ ´n
2ė 0 pσ̄
3
ē˙C = p n . (5.80)
3S 0
Similarly, the effective elastic strain is computed as:
σ̄
ē E = . (5.81)
3µ
The relaxation time is then the ratio between these two:
 n−1
E
ē  S0  S0
τ= = q  . (5.82)
ė¯C J0 6µė 0
2
The stable time step returned by PyLith is 1/5 of the value computed from Equation 5.82.
To compute the tangent stress-strain relation, we need to compute the first term in Equation 5.55 on page 73. We begin by
rewriting Equation 5.77 on the preceding page as
F =t +∆t S i a E + α∆t τ γ − t +∆t e i0 + ∆t τ γ (1 − α)t S i − a E S iI = 0 .
¡ ¢
(5.83)
The derivative of this function with respect to t +∆t e k00 is

∂F
= −δi k , (5.84)
∂t +∆t e k0
and the derivative with respect to t +∆t S i is

∂F ∂τ γ
= a E + α∆t τ γ + ∆t αt +∆t S i + (1 − α)t S i .
£ ¤
(5.85)
∂t +∆t S i ∂t +∆t S i
From Equation 5.75 on the previous page and Equation 5.51 on page 72,
ė 0 h qt +∆t 0 q in−1
τ
γ= α J + (1 − α) t J0 . (5.86)
S 0n 2 2
Then
q
∂τ γ ∂τ γ ∂ t +∆t J 20
= q (5.87)
∂t +∆t S i ∂ t +∆t J 0 ∂t +∆t S l
2
q n−2
ė 0 α (n − 1) τ J 20 t +∆t
Ti
= ,
2S 0n
where
t +∆t
Ti = t +∆t S i ; 1 ≤ i ≤ 3 (5.88)
t +∆t t +∆t
Ti = 2 S i ; otherwise.
Then using Equations 5.84, 5.85, 5.87, and the quotient rule for derivatives of an implicit function,
∂t +∆t S i δi k
= pτ #. (5.89)
∂t +∆t e k0
"
n−2
ė 0 τS t +∆t T J 20
τγ + i (n−1) i
a E + α∆t q
2 t +∆t J 0 S n
2 0
Note that for a linear material (n = 1), this equation is identical to the linear formulation in Section D.1.1 on page 231 (making
the appropriate substitution for τ γ). Then, using Equations 5.54 on page 73 through 5.57 on page 73,
   
1 1 1 0 0 0 2 −1 −1 0 0 0

 1 1 1 0 0 0 


 −1 2 −1 0 0 0 

1  1 ∂t +∆t S
1 1 1 0 0 0 −1 −1 2 0 0 0
  
i
C iVj E = + . (5.90)
   
0 0 0 0 0 0  3 ∂t +∆t e 0 0 0 0 3 0 0
 
3a m 
  k




 0 0 0 0 0 0   0 0 0 0 3 0 
0 0 0 0 0 0 0 0 0 0 0 3
5.4. ELASTOPLASTIC MATERIALS 77
Note that if there are no deviatoric stresses at the beginning and end of a time step (or if ė 0/S 0n approaches zero), Equations 5.89
on the preceding page and 5.90 on the facing page reduce to the elastic constitutive matrix, as expected.
To compute the zero of the effective stress function using Newton’s method, we require the derivative of Equation 5.78 on
page 75, which may be written:
q n−2
ė 0 α (n − 1) τJ0
∂F q 2
= 2a 2 t +∆t J 0 + 2aα∆t t +∆t J 20 + c − 2d 2 τ γ .
¡ ¢
(5.91)
2
S 0n
q
∂ t +∆t J 2
0
Table 5.8: Values in spatial database used as parameters in the nonlinear power-law viscoelastic material constitutive model.
density Density, ρ
reference-strain-rate Reference strain rate, ė 0
reference-stress Reference stress, S 0
power-law-exponent Power-law exponent, n
db_initial_state viscous-strain-xx, . . . Initial viscous strain components
5.4 Elastoplastic Materials

PyLith presently contains just a single elastoplastic material that implements the Drucker-Prager yield criterion. Future releases
of PyLith may contain additional elastoplastic materials, such as Drucker-Prager with hardening/softening.
5.4.1 General Elastoplasticity Formulation
The elastoplasticity formulation in PyLith is based on an additive decomposition of the total strain into elastic and plastic parts:
d ²i j = d ²Eij + d ²Pij . (5.92)

The stress increment is then given by
d σi j = C iEj r s d ²r s − d ²Prs ,
¡ ¢
(5.93)
where C iEj r s are the components of the elastic constitutive tensor. To completely specify an elastoplastic problem, three com-
ponents are needed. We first require a yield condition, which specifies the state of stress at which plastic flow initiates. This is
generally given in the form:
f σ, k = 0 ,
¡ ¢
(5.94)
where k is an internal state parameter. It is then necessary to specify a flow rule, which describes the relationship between
plastic strain and stress. The flow rule is given in the form:
g σ, k = 0 .
¡ ¢
(5.95)
The plastic strain increment is then given as

∂g
d ²Pij = d λ , (5.96)
∂σi j
where d λ is the scalar plastic multiplier. When the flow rule is identical to the yield criterion ( f ≡ g ), the plasticity is described
as associated. Otherwise, it is non-associated. The final component needed is a hardening hypothesis, which describes how the
Table 5.9: Options for fitting the Drucker-Prager plastic parameters to a Mohr-Coulomb model using fit_mohr_coulomb.
Parameter Value αf β αg
2 sin φ(k) 6c̄(k) cos φ0 2 sin ψ(k)
inscribed p
3(3−sin φ(k))
p
3(3−sin φ0 )
p
3(3−sin ψ(k))
sin φ(k) sin ψ(k)
c̄ (k) cos φ0
¡ ¢
middle 3 3
2 sin φ(k) 6c̄(k) cos φ0 2 sin ψ(k)
circumscribed p
3(3+sin φ(k))
p
3(3+sin φ0 )
p
3(3+sin ψ(k))
yield condition and flow rule are modified during plastic flow. When the yield condition and flow rule remain constant during
plastic flow (e.g., no hardening), the material is referred to as perfectly plastic.
To perform the solution, the yield condition (Equation 5.94 on the preceding page) is first evaluated under the assumption
of elastic behavior. If t +∆t f < 0, the material behavior is elastic and no plastic flow occurs. Otherwise, the behavior is plastic
and a plastic strain increment must be computed to return the stress state to the yield envelope. This procedure is known as an
elastic predictor-plastic corrector algorithm.
5.4.2 Drucker-Prager Elastoplastic Material
PyLith includes an elastoplastic implementation of the Drucker-Prager yield criterion [Drucker and Prager, 1952]. This crite-
rion was originally devised to model plastic deformation of soils, and it has also been used to model rock deformation. It is
intended to be a smooth approximation of the Mohr-Coulomb yield criterion. The implementation used in PyLith includes
non-associated plastic flow, which allows control over the unreasonable amounts of dilatation that are sometimes predicted by
the associated model. The model is described by the following yield condition:
q
f σ, k = α f I 1 + J 20 − β ,
¡ ¢
(5.97)
and a flow rule given by:
¢ q
g σ, k = J 20 + αg I 1 .
¡
(5.98)
The yield surface represents a circular cone in principal stress space, and the parameters can be related to the friction
angle, φ, and the cohesion, c̄ , of the Mohr-Coulomb model. The yield surface in Haigh-Westergaard space (ζ = p13 I 1 , p =
p p
3 3 J3
2J 2 , cos(3θ) = 2 J 3/2 ) is
2
³p ³ π´ ³ π ´´ p p
3 sin θ + − sin φ cos θ + p − 2 sin φζ = 6c cos θ. (5.99)
3 3
The yield surface can be fit to the Mohr-Coulomb model in several different ways. The yield surface can touch the outer apices
(θ = π/3) of the Mohr-Coulomb model (inscribed version), the inner apices (θ = 0) of the Mohr-Coulomb model (circumscribed
version), or halfway between the two (θ = pi /6,middle version). Substituting these values for θ into Equation ( 5.99) and casting
it into the same form as Equation ( 5.98) yields the values of α f , β, and αg given in Table 5.9, where φ0 refers to the initial
friction angle. Similarly, the flow rule can be related to the dilatation angle, ψ, of a Mohr-Coulomb model. It is also possible
for the Mohr-Coulomb parameters to be functions of the internal state parameter, k . In PyLith, the fit to the Mohr-Coulomb
yield surface and flow rule is controlled by the fit_mohr_coulomb property.
As for the viscoelastic models, it is convenient to separate the deformation into deviatoric and volumetric parts:
t +∆t 1 ³t +∆t ´ 1 ³t +∆t 0 ´
Si j = e i j − t +∆t e iPj − e iI j + S iI j = e i j − ∆e iPj + S iI j (5.100)
aE aE
t +∆t 1 t +∆t 1
θ − t +∆t θ P − θ I + P I =
¡t +∆t 0
θ − ∆θ P + P I ,
¡ ¢ ¢
P=
am am
where
t +∆t 0
ei j = t +∆t e i j − t e iPj − e iI j
∆e iPj = t +∆t e iPj − t e iPj
t +∆t 0
θ = t +∆t θ − t θ P − θ I
∆θ P = t +∆t θ P − t θ P . (5.101)
Since the plasticity is pressure-dependent, there are volumetric plastic strains, unlike the viscous strains in the previous section.
From Equation 5.96 on page 77, the plastic strain increment is
t +∆t
∂t +∆t g Si j
∆²Pij = λ = λαg δi j + λ q . (5.102)
∂t +∆t σi j 2 t +∆t J 20
The volumetric part is

1
∆θ P = ∆²Pii = λαg , (5.103)
3
and the deviatoric part is
t +∆t
Si j
∆e iPj = ∆²Pij − ∆²Pm δi j = λ q . (5.104)
2 t +∆t J 20
The problem is reduced to solving for λ. The procedure is different depending on whether hardening is included.
5.4.2.1 Drucker-Prager Elastoplastic With No Hardening (Perfectly Plastic)
When there is no hardening (perfect plasticity), the Drucker-Prager elastoplastic model may be parameterized with just three pa-
rameters, in addition to the normal elasticity parameters. The parameters friction-angle, cohesion, and dilatation-angle
in Table 5.10 on page 81 refer respectively to φ, c̄ , and ψ in Table 5.9 on the facing page. These are then converted to the prop-
erties α f (alpha-yield), β (beta), and αg (alpha-flow), as shown in Table 5.1 on page 61.
For perfect plasticity the yield and flow functions do not vary, and we can solve for λ by substituting Equation 5.104 into
Equation 5.100 on the preceding page and taking the scalar inner product of both sides:
p t +∆t q
λ= 2 d − 2a E t +∆t J 20 , (5.105)
where
t +∆t
d 2 = 2a E2 J 20I + 2a E S iI j t +∆t e i0 j + t +∆t e i0 j t +∆t e i0 j . (5.106)
The second deviatoric stress invariant is therefore
p t +∆t
q
t +∆t J 0
2 d −λ
2 = , (5.107)
2a E
and the pressure is computed from Equations 5.100 on the facing page and 5.103 as:
t +∆t
t +∆t I1 1 ¡t +∆t 0
θ − λαg + P I .
¢
P= = (5.108)
3 am
We then use the yield condition (t +∆t f = 0) and substitute for the stress invariants at t + ∆t to obtain:
³ 3α t +∆t d
´
f t +∆t 0
2a E a m am θ +p − β + 3α f P I
2a E
λ= . (5.109)
6α f αg a E + a m
Since λ is now known, we can substitute 5.107 into 5.104 to obtain
∆e iPj
¡p t +∆t
d −λ
¢
2
t +∆t
Si j = . (5.110)
λa E
Substituting this into Equation 5.100 on the facing page, we obtain the deviatoric plastic strain increment:
λ ³ ´
∆e iPj = p t +∆t 0
e i j + a E S iI j . (5.111)
2 t +∆t d
We then use Equation 5.103 on the previous page and the second line of Equation 5.100 on page 78 to obtain the volumetric
plastic strains and the pressure, and we use 5.111 on the previous page and the first line of Equation 5.100 on page 78 to obtain
the deviatoric plastic strains and the deviatoric stresses.
In certain cases where the mean stress is tensile, it is possible that the flow rule will not allow the stresses to project back to
the yield surface, since they would project beyond the tip of the cone. Although this stress state is not likely to be encountered
for quasi-static tectonic problems, it can occur for dynamic problems. One simple solution is to redefine the plastic multiplier,
λ. We do this by taking the smaller of the values yielded by Equation 5.109 on the previous page or by the following relation:
p t +∆t
λ= 2 d. (5.112)
This is equivalent to setting the second deviatoric stress invariant to zero in Equation 5.105 on the preceding page. By default,
PyLith does not allow such tensile yield, since this would generally represent an error in problem setup for tectonic problems;
however, for cases where such behavior is necessary, the material flag allow_tensile_yield may be set to True. This
same criterion is used to determine whether a feasible stress state is attainable in cases where allow_tensile_yield
q is
t +∆t 0
False. If Equation 5.109 on the previous page yields a smaller value than Equation 5.112, this implies J 2 < 0, which is
not a feasible stress state (see Equation 5.105 on the previous page).
To compute the elastoplastic tangent matrix we begin by writing Equation 5.100 on page 78 as a single expression in terms
of stress and strain vectors:
t +∆t 1 ¡t +∆t 0 R i ¡t +∆t 0
σi = e i − ∆e iP + S iI + θ − ∆θ P + R i P I
¢ ¢
(5.113)
aE am
where
R i = 1 ; i = 1, 2, 3 (5.114)
R i = 0 ; i = 4, 5, 6 .
The elastoplastic tangent matrix is then given by

Ã t +∆t 0
1 ∂ ∂∆e iP
!
∂t +∆t σi ei R i ∂t +∆t θ 0 ∂∆θ P
µ ¶
C iEjP = t +∆t = − + − . (5.115)
∂ ²j a E ∂t +∆t ² j ∂t +∆t ² j a m ∂t +∆t ² j ∂t +∆t ² j
From Equations 5.17 on page 66 and 5.101 on page 78, we have

 
2 −1 −1 0 0 0
 −1 2 −1 0 0 0 
∂t +∆t e i0
 
1 −1 −1 2 0 0 0

=  , (5.116)
 
∂t +∆t ² j 3

0 0 0 3 0 0 

 0 0 0 0 3 0 
0 0 0 0 0 3
and from Equations 5.16 on page 66 and 5.101 on page 78 we have
∂t +∆t θ 0 Rj
= . (5.117)
∂t +∆t ² j 3
From Equation 5.111 on the previous page we have
∂∆e iP ∂t +∆t e i0
" #
∂λ λ ∂t +∆t d
µ ¶
1 ¡t +∆t
e i0 + a E S iI +λ
¢
=p − t +∆t . (5.118)
∂t +∆t ² j 2 t +∆t d ∂t +∆t ² j d ∂t +∆t ² j ∂t +∆t ² j
The derivative of t +∆t d is

∂t +∆t d a E T jI + t +∆t E j
= , (5.119)
∂t +∆t ² j t +∆t d
where
T jI = S Ij and t +∆t E j = t +∆t e 0j ; j = 1, 2, 3

T jI = 2S Ij and t +∆t E j = 2t +∆t e 0j ; j = 4, 5, 6 . (5.120)
The derivative of t +∆t λ is a function of derivatives already computed:
∂λ 2a E a m 3α f ∂t +∆t θ 0 1 ∂t +∆t d
µ ¶
= + p
∂t +∆t ² j 6α f αg a E + a m a m ∂t +∆t ² j 2a E ∂t +∆t ² j
I t +∆t
α f R j aE T j + Ej
Ã !
2a E a m
= + p . (5.121)
6α f αg a E + a m a m 2a E t +∆t d
Finally, from Equation 5.103 on page 79, the derivative of the volumetric plastic strain increment is:
∂∆θ P ∂λ
= αg . (5.122)
∂t +∆t ² j ∂t +∆t ² j
Table 5.10: Values in spatial database used as parameters in the Drucker-Prager elastoplastic model with perfect plasticity.
density Density, ρ
friction-angle Friction angle, φ
cohesion Cohesion, c̄
dilatation-angle Dilatation angle, ψ
db_initial_state plastic-strain-xx, . . . Initial plastic strain components
In addition to the properties available for every material, the properties for the Drucker-Prager model also includes:
fit_mohr_coulomb Fit to the yield surface to the Mohr-Coulomb model (default is inscribed).
allow_tensile_yieldIf true, allow yield beyond tensile strength; otherwise an error message will occur when
the model fails beyond the tensile strength (default is false).
materials = [plastic]
materials.plastic = pylith.materials.DruckerPrager3D
[pylithapp.timedependent.materials.plastic]
fit_mohr_coulomb = inscribed ; default
allow_tensile_yield = False ; default
Chapter 6
Boundary and Interface Conditions
6.1 Assigning Boundary Conditions

There are four basic steps in assigning a specific boundary condition to a portion of the domain.
1. Create sets of vertices in the mesh generation process for each boundary condition.
2. Define boundary condition groups corresponding to the vertex sets.
3. Set the parameters for each boundary condition group using .cfg files and/or command line arguments.
4. Specify the spatial variation in parameters for the boundary condition using a spatial database file.
6.1.1 Creating Sets of Vertices
The procedure for creating sets of vertices differs depending on the mesh generator. For meshes specified using the PyLith mesh
ASCII format, the sets of vertices are specified using groups (see Appendix C.1 on page 223). In CUBIT/Trelis the groups of
vertices are created using nodesets. Similarly, in LaGriT, psets are used. Note that we chose to associate boundary conditions
with groups of vertices because nearly every mesh generation package supports associating a string or integer with groups of
vertices. Note also that we currently associate boundary conditions with string identifiers, so even if the mesh generator uses
integers, the name is specified as the digits of the integer value. Finally, note that every vertex set that ultimately is associated
with a boundary condition on a cell face (e.g., Neumann boundary conditions and fault interface conditions) must correspond
to a simply-connected surface.
6.1.2 Arrays of Boundary Condition Components
A dynamic array of boundary condition components associates a name (string) with each boundary condition. This dynamic
array of boundary conditions replaces the boundary condition container in PyLith v1.0. User-defined containers are no longer
necessary, and the predefined containers are no longer available (or necessary). The default boundary condition for each
component in the array is the DirichletBC object. Other boundary conditions can be bound to the named items in the array via
a .cfg file, .pml file, or the command line. The parameters for the boundary condition are set using the name of the boundary
condition. An example of setting the array of boundary condition components and changing the types of boundary conditions
in a .cfg file:
[pylithapp.problem]
bc = [x_neg, x_pos, y_pos, z_neg] ; Array of boundary conditions
# Default boundary condition is DirichletBC
83
84 CHAPTER 6. BOUNDARY AND INTERFACE CONDITIONS
# Keep default value for bc.x_neg
bc.x_pos = pylith.bc.DirichletBoundary ; change BC type to DirichletBoundary
bc.y_pos = pylith.bc.AbsorbingDampers ; change BC type to AbsorbingDampers
bc.z_neg = pylith.bc.Neumann ; change BC type to Neumann (traction)
6.2 Time-Dependent Boundary Conditions

Several boundary conditions use a common formulation for the spatial and temporal variation of the boundary condition pa-
rameters,
f (~ x ) + f˙0 (~
x ) = f 0 (~ x )(t − t 0 (~
x )) + f 1 (~
x )a(t − t 1 (~
x )), (6.1)
where f (~ x ) is a constant value, f˙0 (~
x ) may be a scalar or vector parameter, f 0 (~ x ) is a constant rate of change in the value, t 0 (~
x)
is the onset time for the constant rate of change, f 1 (~ x ) is the amplitude for the temporal modulation, a(t ) is the variation in
x ) is the onset time for the temporal modulation, and ~
amplitude with time, t 1 (~ x is the position of a location in space. This
common formulation permits easy specification of a scalar or vector with a constant value, constant rate of change of a value,
and/or modulation of a value in time. One can specify just the initial value, just the rate of change of the value (along with
the corresponding onset time), or just the modulation in amplitude (along with the corresponding temporal variation and onset
time), or any combination of the three. The facilities associated with this formulation are:
db_initial Spatial database specifying the spatial variation in the initial value (default is none).
db_rate Spatial database specifying rate of change in the value (default is none).
db_change Spatial database specifying the amplitude of the temporal modulation (default is none).
th_change Time history database specifying the temporal change in amplitude (default is none).
6.2.1 Dirichlet Boundary Conditions
Dirichlet boundary conditions in PyLith prescribe the displacement of a subset of the vertices of the finite-element mesh. While
Dirichlet boundary conditions can be applied to any vertex, usually they are applied to vertices on the lateral and bottom
boundaries of the domain. There are two types of Dirichlet boundary conditions, DirichletBC and DirichletBoundary. Both
provide identical constraints on the solution, but DirichletBoundary is limited to vertices of a simply-connected surface, which
allows diagnostic output of the prescribed displacements. DirichletBC can be applied to a set of unconnected vertices.
The properties and components common to both the DirichletBC and DirichletBoundary boundary conditions are:
label Label of the group of vertices associated with the boundary condition.
bc_dof Array of degrees of freedom to be fixed (first degree of freedom is 0).
DirichletBoundary contains an additional component:
output Manager for output of displacements on boundary with specified displacements.
By default the output manager does not output any information. The specified displacements and velocities can be output by
including “displacement” and “velocity” in the output manager’s vertex_info_fields array parameter. An example of
setting the Dirichlet boundary condition parameters in a .cfg file is:
[pylithapp.problem]
bc = [mybc]
[pylithapp.problem.bc.mybc]
label = group A
bc_dof = [2] ; fixed displacement in z direction
db_initial = spatialdata.spatialdb.SimpleDB
db_initial.iohandler.filename = disp_A.spatialdb
db_initial.query_type = nearest ; change query type to nearest point algorithm
db_rate = spatialdata.spatialdb.UniformDB
db_rate.values = [displacement-rate-z]
db_rate.data = [1.0e-06*m/s] ; velocity is 1.0e-06 m/s
6.2. TIME-DEPENDENT BOUNDARY CONDITIONS 85
We have created an array with one boundary condition, mybc. The group of vertices associated with the boundary condition is
group A. For the database associated with the constant displacement, we use a SimpleDB. We set the filename and query type
for the database. For the rate of change of values, we use a UniformDB and specify the velocity in the z-direction to be 1.0e-06
m/s. See Section 4.5 on page 41 for a discussion of the different types of spatial databases available.
Table 6.1: Fields available in output of DirichletBoundary boundary condition information.

Field Type Field Description
vertex_info_fields displacement_initial Initial displacement field in global coordinate system
velocity Rate of change of displacement field in global coordi-
nate system
velocity_start_time Onset time in seconds for rate of change in displace-
ment field
displacement_change Amplitude of change in displacement field in global
coordinate system
change_start_time Onset time in seconds for the amplitude change in the
displacement field
6.2.1.1 Dirichlet Boundary Condition Spatial Database Files
The spatial database files for the Dirichlet boundary condition specify the fixed displacements. The spatial database file may
contain displacements at more degrees of freedom than those specified in the Dirichlet boundary condition settings using the
bc_dof setting. Only those listed in bc_dof will be used. This permits using the same spatial database file for multiple
Dirichlet boundary conditions with the same displacement field.
Table 6.2: Values in the spatial databases used for Dirichlet boundary conditions.
Spatial database Name in Spatial Database
db_initial displacement-x, displacement-y, displacement-z
db_rate displacement-rate-x, displacement-rate-y,
displacement-rate-z, rate-start-time
db_change displacement-x, displacement-y, displacement-z,
change-start-time
6.2.2 Neumann Boundary Conditions
Neumann boundary conditions are surface tractions applied over a subset of the mesh. As with the DirichletBoundary condition,
each Neumann boundary condition can only be applied to a simply-connected surface. The surface over which the tractions
are applied always has a spatial dimension that is one less than the dimension of the finite-element mesh. Traction values are
computed at the integration points of each cell on the surface, using values from a spatial database. The tractions are integrated
over each cell and assembled to obtain the forces applied at the vertices. See Section 7.3.7 on page 117 for a example that uses
Neumann boundary conditions.
B Important
In the small (finite) strain formulation, we assume that the normal and shear tractions
are prescribed in terms of the undeformed configuration as described in section 2.5 on
page 14.
The Neumann boundary condition properties and components are:

label Name of the group of vertices defining the mesh boundary for the Neumann boundary condition.
up_dir This is a 3-vector that provides a hint for the direction perpendicular to the horizontal tangent direction that
is not collinear with the direction normal to the surface. The default value is (0,0,1), which assumes that
the z-axis is positive upward. This vector is only needed for three-dimensional problems where the positive
upward direction differs from the default.
output The output manager associated with diagnostic output (traction vector).
quadrature The quadrature object to be used for numerical integration. Since we are integrating over a surface that is one
dimension lower than the problem domain, this would typically be set to something like Quadrature2Din3D
(for a three-dimensional problem).
By default the output manager does not output any information. The specified tractions can be output in global coordinates by
including “tractions” in the output manager’s cell_info_fields array parameter. An example of setting these parameters
in a .cfg file is:
pylithapp.timedependent]
bc = [x_neg, x_pos, y_neg]
bc.x_pos = pylith.bc.Neumann ; Change BC type to Neumann
[pylithapp.timedependent.bc.x_pos]
label = x_pos ; Name of group of vertices for +x boundary
db_initial.label = Neumann BC +x edge
db_initial.iohandler.filename = axialtract.spatialdb
db_initial.query_type = nearest
quadrature.cell.quad_order = 2
These settings correspond to the example problem described in Section 7.3.7 on page 117. It is necessary to set the boundary
condition type to pylith.bc.Neumann, since the default value is DirichletBC. Constant tractions are used for this particular
problem, so a quadrature order of one would have been sufficient; however, for problems involving more complex variations
(e.g., a linear variation), a quadrature order of two will provide more accurate results. Note that there is no advantage to
specifying an integration order higher than two, since linear elements are being used for this problem.
Table 6.3: Fields available in output of Neumann boundary condition information.

cell_info_fields tracton_initial Initial traction field in global coordinate system
traction_rate Rate of change of traction field in global coordinate
system
rate_start_time Onset time in seconds for rate of change in traction
field
traction_change Amplitude of change in traction field in global coordi-
nate system
change_start_time Onset time in seconds for the amplitude change in the
traction field
6.2.2.1 Neumann Boundary Condition Spatial Database Files
The spatial database files for the Neumann boundary condition specify the applied tractions. The number of traction components
is equal to the spatial dimension for the problem. The tractions are specified in a local coordinate system for the boundary. The
names of the components of the traction vector are:
one-dimensional normal
two-dimensional shear, normal

6.2. TIME-DEPENDENT BOUNDARY CONDITIONS 87
three-dimensional horiz-shear, vert-shear, normal
Ambiguities in specifying the shear tractions in 3D problems are resolved using the up_dir parameter. In the case of a
horizontal surface, users will need to pick an alternative vector, as the default up_dir would coincide with the normal direction.
In this case, the orientation for the vert-shear-traction component will correspond to whatever the user specifies for
up_dir, rather than the actual vertical direction.
Table 6.4: Values in the spatial databases used for Dirichlet boundary conditions in three dimensions. In one- and two-
dimensional problems, the names of the components are slightly different as described earlier in this section.
db_initial traction-shear-horiz, traction-shear-vert,
traction-normal
db_rate traction-rate-horiz-shear, traction-rate-vert-shear,
traction-rate-normal,rate-start-time
db_change traction-horiz-shear, traction-vert-shear,
traction-normal,change-start-time
6.2.3 Point Force Boundary Conditions
Point force boundary conditions in PyLith prescribe the application of point forces to a subset of the vertices of the finite-
element mesh. While point force boundary conditions can be applied to any vertex, usually they are applied to vertices on the
lateral, top, and bottom boundaries of the domain.
6.2.3.1 Point Force Parameters
The properties and components for the PointForce boundary condition are:
label Label of the group of vertices associated with the boundary condition.
bc_dof Array of degrees of freedom to which forces are applied (first degree of freedom is 0).
An example of setting the point force boundary condition parameters in a .cfg file is:
[pylithapp.problem]
bc = [mybc]
bc.mybc = pylith.bc.PointForce
<h<[pylithapp.problem.bc.mybc]</h>
label = group A
bc_dof = [2] ; force in z direction
db_initial.iohandler.filename = force\_A.spatialdb
db_initial.query_type = nearest ; change query type to nearest point algorithm
db_rate.values = [force-rate-z]
db_rate.data = [1.0e+5*newton/s]
We have created an array with one boundary condition, mybc. The group of vertices associated with the boundary condition
is group A. For the database associated with the constant force, we use a SimpleDB. We set the filename and query type for
the database. For the rate of change of values, we use a UniformDB and specify the rate of change in the force to be 1.0e+5
Newton/s. See Section 4.5 on page 41 for a discussion of the different types of spatial databases available.
6.2.3.2 Point Force Spatial Database Files
The spatial database files for the point force boundary condition specify the forces applied.
Table 6.5: Values in the spatial databases used for point force boundary conditions.
db_initial force-x, force-y, force-z
db_rate force-rate-x, force-rate-y, force-rate-z,
rate-start-time
db_change force-x, force-y, force-z, change-start-time
6.3 Absorbing Boundary Conditions

This AbsorbingDampers boundary condition attempts to prevent seismic waves reflecting off of a boundary by placing simple
dashpots on the boundary. Normally incident dilatational and shear waves are perfectly absorbed. Waves incident at other angles
are only partially absorbed. This boundary condition is simpler than a perfectly matched layer (PML) boundary condition but
does not perform quite as well, especially for surface waves. If the waves arriving at the absorbing boundary are relatively small
in amplitude compared to the amplitudes of primary interest, this boundary condition gives reasonable results.
The AbsorbingDampers boundary condition properties and components are:
label Name of the group of vertices defining the mesh boundary for the absorbing boundary condition.
up_dir This is a 3-vector that provides a hint for the direction perpendicular to the horizontal tangent direction that
is not collinear with the direction normal to the surface. The default value is (0,0,1), which assumes that
the z-axis is positive upward. This vector is only needed for three-dimensional problems where the positive
upward direction differs from the default.
db The spatial database specifying the material properties for the seismic velocities.
quadrature The quadrature object to be used for numerical integration. Since we are integrating over a surface that is one
dimension lower than the problem domain, this would typically be set to something like Quadrature2Din3D
(for a three-dimensional problem).
6.3.1 Finite-Element Implementation of Absorbing Boundary
Consider a plane wave propagating at a velocity c . We can write the displacement field as
~
u (~ ~t (t − ~
x, t ) = u
x
), (6.2)
c
where ~ ~t is the shape of the propagating wave. For an absorbing boundary we want the traction on
x is position, t is time, and u
the boundary to be equal to the traction associated with the wave propagating out of the domain. Starting with the expression for
the traction on a boundary, Ti = σi j n j , and using the local coordinate system for the boundary s h s v n, where ~
n is the direction
normal to the boundary, → −s is the horizontal direction tangent to the boundary, and →
h
−s is the vertical direction tangent to the
v
boundary, the tractions on the boundary are
T s h = σs h n (6.3)
T s v = σs v n (6.4)
Tn = σnn . (6.5)
In the case of a horizontal boundary, we can define an auxiliary direction in order to assign unique tangential directions. For a
linear elastic isotropic material, σi j = λ²kk δi j + 2µ²i j , and we can write the tractions as
T sh = 2µ²sh n (6.6)
T s v = 2²s v n (6.7)
Tn = (λ + 2µ)²nn + λ(²sh sh + ²s v s v ). (6.8)
6.3. ABSORBING BOUNDARY CONDITIONS 89
For infinitesimal strains, ²i j = 21 (u i , j + u j ,i ) and we have
1
²sh n = (u sh ,n + u n,sh ) (6.9)
2
1
²s v n = (u s v ,n + u n,s v ) (6.10)
2
²nn = u n,n . (6.11)
For our propagating plane wave, we recognize that
~t (t − ~x )
∂u ~t (t − ~x )
1 ∂u
c c
=− , (6.12)
∂x i c ∂t
so that our expressions for the tractions become

~
x ~
Ã t
µ ∂u sh (t − c ) ∂u n (t − c )
t x
!
T sh =− + , (6.13)
c ∂t ∂t
~
x ~
x
Ã t
µ ∂u s v (t − c ) ∂u n (t − c )
t
!
Tsv =− + . (6.14)
c ∂t ∂t
For the normal traction, consider a dilatational wave propagating normal to the boundary at speed v p ; in this case u sh = u s v = 0
and c = v p . For the shear tractions, consider a shear wave propagating normal to the boundary at speed v s ; we can decompose
this into one case where u n = u s v = 0 and another case where u n = u sh = 0, with c = v s in both cases. We also recognize that
µ = ρv s2 and λ + 2µ = ρv p2 . This leads to the following expressions for the tractions:
∂u st h (t − ~xc )
T sh = −ρv s (6.15)
∂t
∂u vt (t − ~xc )
T s v = −ρv s (6.16)
∂t
∂u nt (t − ~xc )
Tn = −ρv p (6.17)
∂t
We write the weak form of the boundary condition as
∂u i
Z Z
Ti φi d S = −ρc i φi d S,
ST ST ∂t
where c i equals v p for the normal traction and v s for the shear tractions, and φi is our weighting function. We express the trial
solution and weighting function as linear combinations of basis functions,
a im N m ,
X
ui = (6.18)
m
φi = c in N n .
X
(6.19)
n
Substituting into our integral over the absorbing boundaries yields

Z Z
Ti φi d S = ȧ im N m c in N n d S.
X X
−ρc i (6.20)
ST ST m n
In the derivation of the governing equations, we recognized that the weighting function is arbitrary, so we form the residual by
setting the terms associated with the coefficients c in to zero,
r in = ȧ im N m (x q )N n (x q )w q |J cel l (x q )|,
X X X
−ρ(x q )c i (x q ) (6.21)
tract cells quad pts m
where x q are the coordinates of the quadrature points, w q are the weights of the quadrature points, and |J cel l (x q )| is the
determinant of the Jacobian matrix evaluated at the quadrature points associated with mapping the reference cell to the actual
cell.
The appearance of velocity in the expression for the residual means that the absorbing dampers also contribute to the
system Jacobian matrix. Using the central difference method, the velocity is written in terms of the displacements,
1
u̇ i (t ) = (u i (t + ∆t ) − u i (t − ∆t )). (6.22)
2∆t
Expressing the displacement at time t + ∆t in terms of the displacement at time t (u i (t )) and the increment in the displacement
at time t (d u i (t )) leads to
1
u̇ i (t ) = (d u i (t ) + u i (t ) − u i (t − ∆t )) (6.23)
2∆t
The terms contributing to the system Jacobian are associated with the increment in the displacement at time t . Substituting into
the governing equations and isolating the term associated with the increment in the displacement at time t yields
1
A nm δi j ρ(x q )v i (x q )N m (x q )N n (x q )w q |J cel l s (x q )|,
X X
ij = (6.24)
tract cells quad pts 2∆t
where A mn
ij
is an nd by md matrix (d is the dimension of the vector space), m and n refer to the basis functions and i and j
are vector space components.
6.4 Fault Interface Conditions

Fault interfaces are used to create dislocations (jumps in the displacement field) in the model. The dislocations arise from slip
across a fault surface. Both shear and tensile dislocations are supported. For fault interfaces, dislocations in 1D correspond to
fault-opening (and closing), in 2D lateral-slip and fault opening, and in 3D lateral-slip, reverse-slip, and fault opening. PyLith
supports kinematic (prescribed) slip and dynamic (spontaneous) rupture simulations.
6.4.1 Conventions
Slip corresponds to relative motion across a fault surface. Figure 6.1 on the next page shows the orientation of the slip vector in
3D with respect to the fault surface and coordinate axes. PyLith automatically determines the orientation of the fault surface.
This alleviates the user from having to compute the strike, dip, and rake angles over potentially complex, nonplanar fault
surfaces. Instead, the user specifies fault parameters in terms of lateral motion, reverse motion, and fault opening as shown in
Figure 6.2 on the facing page.
6.4.2 Fault Implementation
In order to create relative motion across the fault surface in the finite-element mesh, additional degrees of freedom are added
along with adjustment of the topology of the mesh. These additional degrees of freedom are associated with cohesive cells.
These zero-volume cells allow control of the relative motion between vertices on the two sides of the fault. PyLith automatically
adds cohesive cells for each fault surface. Figure 6.3 on page 92 illustrates the results of inserting cohesive cells in a mesh
consisting of triangular cells. This example also shows the distinction between how buried fault edges are handled differently
than fault edges that reach the edge of the domain, such as the ground surface.
For faults that have buried edges, splitting the mesh apart and inserting the cohesive cells becomes complex at the buried
edges due to the ambiguity of defining where the fault ends and how to insert the cohesive cell. In PyLith v2.0.0 we have
changed how the buried edges of the fault are managed. An additional group of fault nodes is specified (e.g., via a nodeset from
CUBIT) that marks the buried edges of the fault (see Figure 6.4 on page 92). This allows the cohesive cell insertion algorithm
to adjust the topology so that cohseive cells are inserted up to the buried edge of the fault but no additional degrees of freedom
are added on the fault edge. This naturally forces slip to zero along the buried edges.
6.4. FAULT INTERFACE CONDITIONS 91
Up, z
t
s r North, y
Slip φ
δ λ r0
East, x
Figure 6.1: Orientation of a fault surface in 3D, where φ denotes the angle of the fault strike, δ denotes the angle of the fault
dip, and λ the rake angle.
left−lateral slip
fault opening
reverse slip
Figure 6.2: Sign conventions associated with fault slip. Positive values are associated with left-lateral, reverse, and fault opening
motions.
(d) Classify cells and

(a) Original mesh (b) Add colocated (c) Update cells with
update remaining
vertices fault faces
cells
- +
Sf − Sf + - + - +
fault vertex
- +
n - + - +
- +
- + - +
Original fault vertex

(negative side)
Add Lagrange Cell on Cell on

multiplier edge negative positive
fault edge vertex side side
Add vertex on
positive side
Figure 6.3: Example of cohesive cells inserted into a mesh of triangular cells. The zero thickness cohesive cells control slip on
the fault via the relative motion between the vertices on the positive and negative sides of the fault.
fault
fault_edge
Figure 6.4: Example of how faults with buried edges must be described with two sets of vertices. All of the vertices on the fault
are included in the fault group; the subset of vertices along the buried edges are included in the fault_edge group. In
2-D the fault edges are just a single vertex as shown in Figure 6.3(a).
6.4.3 Fault Parameters
The principal parameters for fault interface conditions are:

id This is an integer identifier for the fault surface. It is used to specify the material-id of the cohesive
cells in the mesh. Material identifiers must be unique so this value cannot be the same as any of the material
models or any other fault.
label Name of group of vertices associated with the fault surface. This label is also used in error and diagnostic
reports.
edge Name of group of vertices marking the buried edges of the fault.
up_dir Up-dir or up direction (used in 2D and 3D simulations). In 2D the default in-plane slip is left-lateral, so
we use the up-direction to resolve the ambiguity in specifying reverse slip. In 3D the up-direction is used
to resolve the ambiguity in the along-strike and dip-dir directions. If the fault plane is horizontal, then the
up-dir corresponds to the reverse-motion on the +z side of the fault. The only requirement for this direction
is that it not be collinear with the fault normal direction. The default value of [0, 0, 1] is appropriate for
most 3D problems.
quadrature Quadrature object used in integrating fault quantities.
output Manager for output of diagnostic and data fields for the fault.
By default the output manager outputs both diagnostic information (e.g., fault normal direction) and the slip at each time step.
Tables 6.6 on page 95 and 6.12 on page 102 list the fields available for output for a fault with kinematic (prescribed) earthquake
rupture and a fault with dynamic rupture, respectively. The fault coordinate system is shown in Figure 6.2 on page 91. The
vectors in the fault coordinate system can be transformed to the global coordinate system using the direction vectors in the
diagnostic output. An example of setting these parameters in a .cfg file is:
<h?[pylithapp.problem]</h>
interfaces = [fault]
[pylithapp.problem.interfaces]
fault = pylith.faults.FaultCohesiveKin ; default
label = fault_A ; Group of vertices defining the fault surface
edge = fault_edge ; Group of vertices defining the buried edges
id = 100 ; Value for material identifier associated with fault’s cohesive cells
up_dir = [0, 0, 1] ; default
The group of vertices has the label “fault A.” We replicate the default values for the fault “up” direction. These settings apply
to a 2D fault surface embedded within a 3D mesh, so we use 2D Lagrange reference cells. The spatial database for elastic
properties is used to determine the approximate shear modulus and condition the equations for faster convergence rates.
6.4.4 Kinematic Earthquake Rupture
Kinematic earthquake ruptures use the FaultCohesiveKin object to specify the slip as a function of time on the fault surface.
Slip may evolve simultaneously over the fault surface instantaneously in a single time step (as is usually done in quasi-static
simulations) or propagate over the fault surface over hundreds and up to thousands of time steps (as is usually done in a dynamic
simulation).
6.4.4.1 Governing Equations
The insertion of cohesive cells into the finite-element mesh has the effect of decoupling the motion of the two sides of the fault
surface. In order to impose the desired relative motion, we must adjust the governing equations. PyLith employs Lagrange
multiplier constraints to enforce the constraint of the relative motion in the strong sense. That is, we enforce the slip across the
fault at each degree of freedom.
In conventional implementations the additional degrees of freedom associated with the Lagrange multipliers result in
a complex implementation. However, the use of Lagrange multiplier constraints with cohesive cells provides for a simple
formulation; we simply add the additional degrees of freedom associated with the Lagrange multipliers to the cohesive cells as
shown in Figure 6.3 on page 92. As a result, the fault implementation is completely confined to the cohesive cell. Furthermore,
the Lagrange multiplier constraints correspond to forces required to impose the relative motions, so they are related to the
change in stress on the fault surface associated with fault slip. If we write the algebraic system of equations associated with
elasticity in the form
→
−
A→
−u=b, (6.25)
then adding in the Lagrange multiplier constraints associated with fault slip leads to a new system of equations of the form
¸" →
− # " →
− #
CT u
·
A b
→
− = →
− , (6.26)
C 0 l d
→
−
where l is the vector of Lagrange multipliers and C is composed of rotation submatrices, R , associated with the direction
→
−
cosines relating the relative displacements across the fault to the vector of fault slip, d . Note that by using the direction cosines
to relate the relative motion across the fault, the slip vector and Lagrange multipliers (forces required to impose the slip) are in
the local fault coordinate system (lateral motion, reverse motion, and fault opening).
Non-diagonal A The Lagrange multipliers contribute to both the system Jacobian matrix and the residual. Because we
enforce the constraints in a strong sense, the terms do not involve integrals over the fault surface. The additional terms in the
residual are
pn p
r in = −C j i l j , (6.27)
p p pn
ri = di −C i j u nj , (6.28)
where n denotes a conventional degree of freedom and p denotes a degree of freedom associated with a Lagrange multiplier.
The additional terms in the system Jacobian matrix are simply the direction cosines,
np pn
Ji j = C j i , (6.29)
pn pn
Ji j = Ci j . (6.30)
Diagonal A When we use a lumped system Jacobian matrix, we cannot lump the terms associated with the Lagrange multi-
pliers. Instead, we formulate the Jacobian ignoring the contributions from the Lagrange multipliers, and then adjust the solution
after the solve to account for their presence. Including the Lagrange multipliers in the general expression for the residual at
time t + ∆t , we have
pn p p
r in (t + ∆t ) = A nm m m
i j (u j (t ) + d u j (t )) +C ki (l k (t ) + d l k (t )), (6.31)
where we have written the displacements and Lagrange multipliers at time t + ∆t in terms of the values at time t and the
increment from time t to t + ∆t . When we solve the lumped system ignoring the Lagrange multipliers contributions to the
p
Jacobian, we formulate the residual assuming the values d u in (t) and d l k (t ) are zero. So our task is to determine the increment
p
in the Lagrange multiplier, d l k , and the correction to the displacement increment, d u in , and by setting the residual with all
terms included to zero; thus, we have
pn p p
A nm m m
i j (u j (t ) + d u j (t )) +C ki (l k (t ) + d l k (t )) = 0 subject to (6.32)
pn p
C i j (u nj (t ) + d u nj (t )) = d i . (6.33)
p
Making use of the residual computed with d u in (t ) = 0 and d l k (t ) = 0,
pn p
r in + A nm m
i j d u j +C ki d l k = 0 subject to (6.34)
pn p
C i j (u nj (t ) + d u nj (t )) = d i . (6.35)
Explicitly writing the equations for the vertices on the negative and positive sides of the fault yields
pn p
r in− + A nm−
ij d u m−
j + R ki d l k = 0, (6.36)
pn p
r in+ + A nm+
ij d u m+
j + R ki d l k = 0, (6.37)
pn p
R i j (u n+ n+ n− n−
j + d u j − u j − d u j ) = di . (6.38)
Solving the first two equations for d u m−

j
and d u m+
j
and combining them using the third equation leads to
³ ´
pn pn p p pn
Ri j (A inm+
j )−1 + (A nm+
ij )−1 R ki d l k = d i − R i j (u n+ n−
j −uj )
³ ´
pn
+ Ri j (A nm+
ij )−1 r in+ − (A nm−
ij )−1 r in− . (6.39)
We do not allow overlap between the fault interface and the absorbing boundary, so A nm
ij
is the same for all components at a
vertex. As a result the matrix on the left hand side simplifies to
µ ¶
pn 1 1
S i k = δi k + , (6.40)
A nm+ A nm−
and ³ ³ ´´
p pn p pn pn
d l k = (S i k )−1 d i − R i j (u n+ n−
j − u j ) + R i j (A i j ) r i − (A nm−
nm+ −1 n+
ij )−1 r in− . (6.41)
Now that we know the value of the increment in the Lagrange multiplier from time t to time t + ∆t , we can correct the value
for the displacement increment from time t to t + ∆t using
pn p
∆d u n− nm− −1
j = (A i j ) C ki d l k and (6.42)
nm+ −1 pn p
∆d u n+
j = −(A i j ) C ki d l k . (6.43)
6.4.4.2 Arrays of Kinematic Rupture Components
Multiple earthquake ruptures can be specified on a single fault surface. This permits repeatedly rupturing the same portion of
a fault or combining earthquake rupture on one subset of the fault surface with steady aseismic slip on another subset (the two
subsets may overlap in both time and space). A dynamic array of kinematic earthquake rupture components associates a name
(string) with each kinematic rupture. The default dynamic array contains a single earthquake rupture, “rupture”. The eq_srcs
is the FaultCohesiveKin facility for this dynamic array. An example of setting the array of kinematic rupture components in a
.cfg file:
<h<[pylithapp.problem.interfaces.fault]</h>
eq_srcs = [earthquake,creep]
The output manager includes generic fault information (orientation) as well as the final slip or slip rate (as in the case of the
constant slip rate slip time function) and slip initiation time for each kinematic rupture. The name of the slip and slip initiation
time vertex fields are of the form final_slip_NAME and slip_time_NAME, respectively, where NAME refers to the name
used in the dynamic array of kinematic ruptures, eq_srcs.
Table 6.6: Fields available in output of fault information.

vertex_info_fields normal_dir Direction of fault normal in global coordinate system
strike_dir Direction of fault strike in global coordinate system
dip_dir Up-dip direction on hanging wall in global coordinate system
final_slip_NAME Vector of final slip (in fault coordinate system) in meters
slip_time_NAME Time at which slip begins in seconds
vertex_data_fields slip Slip vector at time step (in fault coordinate system) in meters
traction_change Change in fault tractions (in fault coordinate system) in Pa
6.4.4.3 Kinematic Rupture Parameters
The kinematic rupture parameters include the origin time and slip time function. The slip initiation time in the slip time function
is relative to the origin time (default is 0). This means that slip initiates at a point at a time corresponding to the sum of the
kinematic rupture’s origin time and the slip initiation time for that point. An example of specifying the kinematic earthquake
rupture properties and components in a .cfg file:
[pylithapp.problem.interfaces.fault]
eq_srcs = [earthquake,creep]
[pylithapp.problem.interfaces.fault.eq_srcs.earthquake]
origin_time = 0.0*s ; default origin time
slip_function = pylith.faults.StepSlipFn ; default slip time function
[pylithapp.problem.interfaces.fault.eq_srcs.creep]
origin_time = 10.0*year ; start creep at 10.0 years
slip_function = pylith.faults.ConstRateSlipFn ; switch to constant slip rate slip function
6.4.4.4 Slip Time Function
The current release of PyLith supports specification of the evolution of fault slip using analytical expressions for the slip time
history at each point, where the parameters for the slip time function may vary over the fault surface. Currently, three slip
time functions are available: (1) a step-function for quasi-static modeling of earthquake rupture, (2) a constant slip rate time
function for modeling steady aseismic slip, and (3) the integral of Brune’s far-field time function [Brune, 1970] for modeling
the dynamics of earthquake rupture. Additional slip time functions will likely be available in future releases. The default slip
time function is the step-function slip function.
Step-Function Slip Time Function This slip function prescribes a step in slip at a given time at a point:
½
0 0 ≤ t < tr
D(t ) = , (6.44)
D f i nal t ≥ tr
where D(t ) is slip at time t , D f i nal is the final slip, and t r is the slip initiation time (time when rupture reaches the location).
The slip is specified independently for each of the components of slip, and the slip and slip starting time may vary over the fault
surface.
final_slip Spatial database of slip (D f i nal ).
slip_time Spatial database of slip initiation times (t r ).
[pylithapp.problem.interfaces.fault.eq_srcs.rupture]
slip_function = pylith.faults.StepSlipFn
[pylithapp.problem.interfaces.fault.eq_srcs.rupture.slip_function]
final_slip.iohandler.filename = final_slip.spatialdb
slip_time.iohandler.filename = sliptime.spatialdb
The spatial database files for the slip time function specify the spatial variation in the parameters for the slip time function, as
shown in Table 6.7 on the next page.
Constant Slip Rate Slip Time Function This slip function prescribes a constant slip rate for the evolution of slip at a point:
½
0 0 ≤ t < tr
D(t ) = , (6.45)
V (t − t r ) t ≥ tr
Table 6.7: Values in spatial database used as parameters in the step function slip time function.
final_slip left-lateral-slip Amount of left-lateral final slip in meters.
Use negative values for right-lateral slip.
reverse-slip Amount of reverse slip in meters. Use nega-
tive values for normal slip.
fault-opening Amount of fault opening in meters. Negative
values imply penetration.
slip_time slip-time Slip initiation time (t t ) in seconds.
where D(t ) is slip at time t , V is the slip rate, and t r is the slip initiation time (time when rupture reaches the location). The
slip rate is specified independently for each of the components of slip, and the slip rate and slip starting time may vary over the
fault surface.
slip_rate Spatial database of slip rate (V ).
[pylithapp.problem.interfaces.fault.eq_srcs.ruptures]
slip_function = pylith.faults.ConstRateSlipFn
[pylithapp.problem.interfaces.fault.eq_srcs.ruptures.slip_function]
slip_rate.iohandler.filename = slip_rate.spatialdb
shown in Table 6.8.
Table 6.8: Values in spatial database used as parameters in the constant slip rate slip time function.
slip_rate left-lateral-slip Slip rate for left-lateral final slip in meters per
second. Use negative values for right-lateral
slip.
reverse-slip Slip rate for reverse slip in meters per second.
Use negative values for normal slip.
fault-opening Slip rate for fault opening in meters per sec-
ond. Negative values imply penetration.
slip_time slip-time Slip initiation time (t t ) in seconds.
Brune Slip Time Function We use an integral of Brune’s far-field time function [Brune, 1970] to describe the evolution in
time of slip at a point:
(
³0 0 ≤ t < tr
D(t ) = ³ ´³ ´´ , (6.46)
D f i nal 1 − exp − t −t
t0
r
1 + t −t r
t0 t ≥ tr
t 0 = 0.6195t rise , (6.47)
where D(t ) is slip at time t , D f i nal is the final slip at the location, t r is the slip initiation time (time when rupture reaches the
location), and t rise is the rise time.
slip Spatial database of final slip distribution (D f i nal ).
rise_time Spatial database for rise time (t rise ).
slip_function = pylith.faults.BruneSlipFn
slip.iohandler.filename = finalslip.spatialdb
rise_time.iohandler.filename = risetime.spatialdb
shown in Table 6.9.
Table 6.9: Values in spatial database used as parameters in the Brune slip time function.
slip left-lateral-slip Amount of left-lateral final slip in meters.
rise_time rise-time Rise time (t r ) in seconds.
slip_time slip-time Slip initiation time (t t ) in meters.
Liu-Cosine Slip Time Function This slip time function, proposed by Liu, Archuleta, and Hartzell for use in ground-motion
modeling[Liu et al., 2006], combines several cosine and sine functions together to create a slip time history with a sharp rise
and gradual termination with a finite duration of slip. The evolution of slip at a point follows:
 ³ ³ ´´


 D final C n 0.7t − 0.7 tπ1 sin πt
t1 − 1.2 t1
π cos πt
2t 1 − 1 0 ≤ t < t1

π(t −t 1)
³ ´
D(t ) = D final C n 1.0t − 0.7 tπ1 sin πt
t 1
+ 0.3 t2
π sin t 2
+ 1.2
π t 1 − 0.3t 1 t 1 ≤ t < 2t 1 , (6.48)
 ³ ´
D final C n 0.7 − 0.7 cos πt πt

t 1 + 0.6 sin 2t 1 2t 1 ≤ t ≤ t 0


π
Cn = , (6.49)
1.4πt 1 + 1.2t 1 + 0.3πt 2
t 0 = 1.525t rise , (6.50)
t 1 = 0.13t 0 , (6.51)
t2 = t0 − t1 , (6.52)
where D(t ) is slip at time t , D f i nal is the final slip at the location, t r is the slip initiation time (time when rupture reaches the
location), and t rise is the rise time.
rise_time Spatial database for rise time (t rise ).
The spatial database files for the slip time function use the same parameters for the slip time function as the Brune slip time
function shown in Table 6.9.
Time-History Slip Time Function This slip time function reads the slip time function from a data file, so it can have an
arbitrary shape. The slip and slip initiation times are specified using spatial databases, so the slip time function, in general, will
use a normalized amplitude.
time_history Temporal database for slip evolution.
slip_function = pylith.faults.TimeHistorySlipFn
slip.iohandler.filename = finalslip.spatialdb
time_history.iohandler.filename = myfunction.timedb
shown in Table 6.10.
Table 6.10: Values in spatial database used as parameters in the time history slip time function.
slip left-lateral-slip Amount of left-lateral final slip in meters.
rise_time rise-time Rise time (t r ) in seconds.
slip_time slip-time Slip initiation time (t t ) in meters.
6.4.5 Dynamic Earthquake Rupture
Dynamic fault interfaces use the FaultCohesiveDyn object to specify a fault constitutive model to govern the fault tractions
(friction) and the resulting slip. When friction is large enough such that there is no sliding on the fault, the fault is locked
(slip is zero) and the Lagrange multipliers assume their values just as they do in kinematic ruptures. In this case, the Lagrange
multipliers correspond to the forces necessary to keep the slip zero. When the driving forces exceed those allowed by friction,
we reduce the values of the Lagrange multipliers to those consistent with friction from the fault constitutive model. When we
reduce the Lagrange multipliers, we must increment the slip accordingly to maintain consistency in the algebraic system of
equations.
6.4.5.1 Governing Equations
The algebraic systems of equations for dynamic earthquake rupture are the same as those for kinematic rupture
¸" →
− # " →
− #
CT u
·
A b
→
− = − .
→ (6.53)
C 0 l d
Enforcing the limits imposed on the Lagrange multipliers by the fault constitutive model requires determining the increment
in slip for an increment in the Lagrange multipliers. The increment in the Lagrange multipliers is the difference between the
value computed for the current slip (either zero or the slip at the previous time step) and the value computed from the fault
constitutive model. Starting from our system of algebraic equations,
pn p
A nm m n
i j u j +C j i l j = b i , (6.54)
we compute the sensitivity for the given loading and boundary conditions,
pn p
A nm m
i j ∂u j = −C j i ∂l j . (6.55)
Computing the increment in the slip requires computing the increment in the displacements. Solving this equation rigorously
would require inverting the system Jacobian, which we do not want to do unless it is diagonal (as it is in the case of the lumped
formulations).
Non-Diagonal A In general A is a sparse matrix with off-diagonal terms of the form
 
A0 A1 A2
A =  A3 A n− 0 , (6.56)
A4 0 A n+
where the degrees of freedom on either side of the fault are uncoupled. We formulate two small linear systems involving just
the degrees of freedom associated with vertices on either the positive or negative sides of the fault,
pn p
A nm−
ij ∂u m−
j = −R i j ∂l j , (6.57)
pn p
A nm+
ij ∂u m+
j = R i j ∂l j , (6.58)
where we have replaced C with R to denote the explicit inclusion of the signs for the terms in C associated with the positive
(n + ) and negative (n − ) sides of the fault. After solving these two linear systems of equations, we compute the increment in slip
using
p pn
∂d i = R i j (∂u n+ n−
j − ∂u j ). (6.59)
The solution of these two linear systems gives the increment in slip assuming all the degrees of freedom except those imme-
diately adjacent to the fault remain fixed. In real applications where the deformation associated with fault slip is localized
around the fault, this provides good enough approximations so that the nonlinear solver converges quickly. In problems where
deformation associated with slip on the fault is not localized (as in the case in some of the example problems), the increment in
slip computed by solving these two linear systems is not a good approximation and the nonlinear solve requires a large number
of iterations.
We use the PETSc Krylov subspace solver (KSP) to solve these two linear systems. The PETSc settings for the KSP
object are set in the same manner as the main solver, except we use the prefix friction_ in all of the settings related to the
KSP solver for these two linear systems. For example, to use the recommended additive Schwarz preconditioner in the friction
sensitivity solves, the settings in a .cfg file are:
[pylithapp.petsc]
friction_pc_type = asm
See the examples in Sections 7.8.7 on page 154 and 7.12 on page 177 for details.
Diagonal A With a lumped Jacobian matrix, we can solve for the increment in slip directly,
p pn pm p
∂d i = −C i j (A nm −1
j k ) C l k ∂l l . (6.60)
By not allowing the fault interface to overlap with the absorbing boundary, the terms in A for a given vertex are identical and
the expression on the right-hand side reduces to
µ ¶
p 1 1 p
∂d i = − + ∂l i . (6.61)
A n+ A n−
6.4.5.2 Dynamic Rupture Parameters
The properties and facilities of the FaultCohesiveDyn object include

open_free_surface If true, enforce traction free surface when the fault opens, otherwise apply prescribed tractions even
when the fault opens (default is true); to mimic a dike opening, use false.
zero_tolerance Tolerance for detecting zero values (default is 1.0e-10); should be larger than absolute tolerance in KSP
solves.
traction_perturbation Prescribed tractions on fault surface (generally used for nucleating earthquake ruptures; default
is none).
friction Fault constitutive model.
An example of specifying the dynamic earthquake rupture properties and components in a .cfg file:
open_free_surface = True ; default
traction_perturbation = pylith.faults.TractPerturbation ; not default

traction_perturbation.db_initial = spatialdata.spatialdb.SimpleDB
traction_perturbation.db_initial.iohandler.filename = tractions.spatialdb
friction<f> = pylith.friction.StaticFriction
<f>friction.db_properties = spatialdata.spatialdb.SimpleDB
friction.db_properties.iohandler.filename = friction.spatialdb
L Warning
Use of the dynamic rupture implementation in a quasi-static simulations requires use of
the nonlinear solver.
B Important
The dynamic rupture implementation requires careful selection of linear and nonlin-
ear solver tolerances. A key issue is making sure the linear solver toleance is tighter
(smaller) than the tolerance used to detect slip (fault zero_toelerance). As a re-
sult, the linear and solver absolute tolerances should be used to for convergence, not
the relative tolerances. The settings below illustrates the relevant parameters and exam-
ple values. The values can be scaled to change the overall desired tolerances.
zero_tolerance = 1.0e-11
[pylithapp.petsc]
# Linear solver tolerances
ksp_rtol = 1.0e-20
ksp_atol = 1.0e-12
# Nonlinear solver tolerances

snes_rtol = 1.0e-20
snes_atol = 1.0e-10
# Set preconditioner for friction sensitivity solve

friction_sub_pc_factor_shift_type = nonzero
The prescribed traction perturbation is specified using the same fault coordinate system as the slip directions in the kine-
matic ruptures. The perurbation has the same functional form as the time-dependent boundary conditions (and same spatial
databases). Table 6.11 on the following page gives the values in the spatial database for the prescribed tractions. Table 6.12 on
the next page shows the fields available for output. Additional fields are available depending on the fault constitutive model.
6.4.5.3 Fault Constitutive Models
PyLith provides four fault constitutive models. Future releases may contain additional models, and a template is provided for
you to construct your own (see Section 9.3 on page 212). The fault constitutive model implementations are independent of
Table 6.11: Values in spatial databases for prescribed tractions.

Spatial database Dimension Value Description
db_initial 2D traction-shear Left-lateral shear traction (reverse shear for
dipping faults)
traction-normal Normal traction (tension is positive)
3D traction-shear-leftlateral Left-lateral shear traction
traction-shear-updip Reverse shear traction
traction-normal Normal traction (tension is positive)
db_rate 2D traction-rate-shear Rate of change of left-lateral shear traction
(reverse shear for dipping faults)
traction-rate-normal Rate of change of normal traction (tension is
positive)
3D traction-rate-leftlateral Rate of change of left-lateral shear traction
traction-rate-shear-updip Rate of change of reverse shear traction
traction-rate-normal Rate of change of normal traction (tension is
positive)
all rate-start-time Time at which rate of change begins
db_change 2D traction-shear Change in left-lateral shear traction (reverse
shear for dipping faults)
traction-normal Change in normal traction (tension is posi-
tive)
3D traction-leftlateral Change in left-lateral shear traction
traction-shear-updip Change in reverse shear traction
traction-normal Change in normal traction (tension is posi-
tive)
all change-start-time Time at which change begins
th_change all None Time history for change
Table 6.12: Fields available in output of fault information.

vertex_info_fields normal_dir Direction of fault normal in global coordinate system
strike_dir Direction of fault strike in global coordinate system
dip_dir Up-dip direction on hanging wall in global coordinate system
traction_initial Initial tractions (if specified) in fault coordinate system
traction_rate Rate of change in tractions (if specified) in fault coordinate sys-
tem
rate_start_time Time at which rate of change begins (if specified)
traction_change Change in tractions (if specified) in fault coordinate system
change_start_time Time at which change occurs (if specified)
vertex_data_fields slip Slip vector at time step (in fault coordinate system) in meters
traction Fault tractions (in fault coordinate system) in Pa
dimension and work in both 2D and 3D. In solving the governing equations, PyLith will use a scalar representation of the shear
traction in 2D and a vector representation of the shear traction in 3D, with the shear traction resolved in the direction of current
slip. The fault constitutive models contain a common set of properties and components:
label Name of the friction model.
db_properties Spatial database of the friction model parameters (default is SimpleDB).
db_initial_state Spatial database for initial state variables. A warning will be given when a spatial database for the
initial state is not specified. The default is none which results in initial state values of 0.0. For some friction
models, we provide more meaningful values for default values.
Static Friction The static friction model produces shear tractions proportional to the fault normal traction plus a cohesive
stress, (
Tc − µ f Tn Tn ≤ 0
Tf = . (6.62)
0 Tn > 0
The spatial database file for the static friction model properties specifies the spatial variation of the parameters given in Ta-
ble 6.13.
Table 6.13: Values in the spatial database for constant friction parameters.
Value Description
friction-coefficient Coefficient of friction, µ f
cohesion Cohesive stress, Tc
Slip-Weakening Friction The linear slip-weakening friction model produces shear tractions equal to the cohesive stress plus
a contribution proportional to the fault normal traction that decreases from a static value to a dynamic value as slip progresses,
d
Tc − (µs − (µs − µd ) d0 )Tn

 d ≤ d 0 and Tn ≤ 0
T f = Tc − µd Tn d > d 0 and Tn ≤ 0 (6.63)

0 Tn > 0

The spatial database files for the slip-weakening friction model properties and state variables specify the spatial variation
of the fault constitutive model parameters given in Table 6.14 on the following page. As long as the fault is locked, the
initial state variables are zero, so specifying the initial state variables for slip-weakening friction is rare. The slip-weakening
friction also includes a parameter, force_healing, to control healing. In quasi-static simulations, one usually wants slip
confined to a single time step (force_healing = True), whereas in a dynamic simulation slip occurs over many time steps
(force_healing = False; default behavior) and fault healing is often neglected. The properties include:
force_healing Flag indicating whether healing (cumalative slip state variable reset to zero) is forced after every time step.
An example of setting the properties for the slip-weakening friction component in a .cfg file is:
friction = pylith.friction.SlipWeakening ; Change from the default
friction.force_healing = False ; default value
Time-Weakening Friction The linear time-weakening friction model is analogous to the linear slip-weakening friction model
with time replacing slip. It produces shear tractions equal to the cohesive stress plus a contribution proportional to the fault
normal traction that decreases from a static value to a dynamic value as time progresses,
t
Tc − (µs − (µs − µd ) t0 )Tn

 t ≤ t 0 and Tn ≤ 0
T f = Tc − µd Tn t > t 0 and Tn ≤ 0 (6.64)

0 Tn > 0

Table 6.14: Values in spatial databases for slip-weakening friction.
db_properties static-coefficient Static coefficient of friction, µs
dynamic-coefficient Dynamic coefficient of friction, µd
slip-weakening-parameter Slip-weakening parameter, d0
db_initial_state cumulative-slip Cumulative slip, d
previous-slip Slip at previous time step, d (t − ∆t )
The spatial database files for the time-weakening friction model properties and state variables specify the spatial variation of
the fault constitutive model parameters given in Table 6.15. As long as the fault is locked, the initial state variable is zero, so
specifying the initial state variable for time-weakening friction is rare.
Table 6.15: Values in spatial databases for time-weakening friction.

Database Value Description
time-weakening-parameter Time-weakening parameter, t 0
db_initial_state elapsed-time Elasped time of slip, t
Slip- and Time-Weakening Friction I This friction model, used in a few SCEC Spontaneous Rupture benchmarks, combines
characteristics of slip-weakening and time-weakening friction. The time-weakening portion is generally used to force nucleation
of the rupture. The model produces shear tractions equal to the cohesive stress plus a contribution proportional to the fault
normal traction that decreases from a static value to a dynamic value as slip progresses or when a weakening time is reached,
d
Tc − (µs − (µs − µd ) d0 )Tn

 d ≤ d 0 and t < t w and Tn ≤ 0
T f = Tc − µd Tn (d > d 0 or t ≥ t w ) and Tn ≤ 0 (6.65)

0 Tn > 0

The spatial database files for the slip- and time-weakening friction model properties and state variables specify the spatial
variation of the fault constitutive model parameters given in Table 6.16. As long as the fault is locked, the initial state variables
are zero, so specifying the initial state variables for slip-weakening friction is rare. This variation of slip-weakening friction
does not include the force_healing parameter, because this friction model was developed for dynamic simulations.
An example of setting the properties for the slip- and time-weakening friction component in a .cfg file is:
friction = pylith.friction.SlipWeakeningTime ; Change from the default
Table 6.16: Values in spatial databases for a simple slip- and time-weakening friction model.
weakening-time Weakening time, t w
Slip- and Time-Weakening Friction II This friction model, used in a few SCEC Spontaneous Rupture benchmarks, merges
features of slip-weakening and time-weakening to provide a more numerically stable version of the Slip- and Time-Weakening
Friction I model. Rather than an instantaneous drop in the coefficient of friction from the static value to the dynamic value when
the weakening time is reached, the weakening progresses linearly with time. As in the other slip- and time-weakening friction
model, the time-weakening portion is generally used to force nucleation of the rupture. The model produces shear tractions
equal to the cohesive stress plus a contribution proportional to the fault normal traction that decreases from a static value to a
dynamic value as slip and time progress,
(
Tc − (µs − (µs − µd )max( f 1 , f 2 ))Tn Tn ≤ 0
Tf = (6.66)
0 Tn > 0
(
d /d 0 d ≤ d0
f1 = (6.67)
1 d ≥ d0

0
 t ≤ tw
f2 = (t − t w )/t 0 t w < t ≤ t w + t0 (6.68)

1 t > t w + t0

The spatial database files for the slip- and time-weakening friction model properties and state variables specify the spatial
variation of the fault constitutive model parameters given in Table 6.17. As long as the fault is locked, the initial state variables
are zero, so specifying the initial state variables for slip-weakening friction is rare. This variation of slip-weakening friction
does not include the force_healing parameter, because this friction model was developed for dynamic simulations.
An example of setting the properties for this slip- and time-weakening friction component in a .cfg file is:
friction = pylith.friction.SlipWeakeningTimeStable ; Change from the default
Table 6.17: Values in spatial databases for a second slip- and time-weakening friction model.
time-weakening-time Weakening time, t w
time-weakening-parameter Time-weakening parameter, t 0
Rate- and State-Friction with Ageing Law The Dieterich-Ruina rate and state friction model produces shear tractions equal
to the cohesive stress plus a contribution proportional to the fault normal traction that depends on a state variable,
(
Tc − µ f Tn Tn ≤ 0
Tf = (6.69)
0 Tn > 0

µ0 + a ln V + b ln V0 θ
³ ´ ³´
V L V ≥ Vlinear
µf = ³ 0 (6.70)
µ0 + a ln Vl i near + b ln V0 θ − a 1 −
´ ³ ´ ³ ´
V
V0 L V V < Vl i near
l i near
dθ Vθ
= 1− (6.71)
dt L
where V is slip rate, Vl i near is a cutoff for a linear slip rate dependence, a and b are coefficients, L is the characteristic slip
distance, θ is a state variable. With an interative solver in quasi-static simulations with its small, but nonzero residual tolerance
we never encounter zero slip rates in quasi-static simulations. Instead we want to avoid significant variations in the coefficient
of friction for slip rates on the same order as our residual tolerance. We regularize the rate and state friction model by imposing
a linearization of the variation of the coefficient of friction with slip rate when the slip rate drops below a cutoff slip rate,
Vl i near (linear_slip_rate property with a default value of 1.0e-12). Note that this is different than the popular inverse
hyperbolic sine regularization proposed by Ben-Zion and Rice [Ben-Zion and Rice, 1997] to permit zero slip rates. Following
Kaneko et al. [Kaneko et al., 2008], we integrate the evolution equation for the state variable, keeping slip rate constant, to get
L V (t )∆t
µ ¶ µ µ ¶¶
−V (t )∆t
θ(t + ∆t ) = θ(t ) exp + 1 − exp − . (6.72)
L V (t ) L
As the slip rate approaches zero, the first exponential term approaches 1. Using the first three terms of the Taylor series
expansion of the second exponential yields

θ(t ) exp − V (t )∆t + ∆t − 1 V (t )∆t 2
³ ´
V (t )∆t
L < 0.00001
θ(t + ∆t ) = ³ ´ ³2 L ³ ´´ L
(6.73)
θ(t ) exp − V (t )∆t + L 1 − exp − V (t )∆t V (t )∆t
≥ 0.00001
L V (t ) L L
A zero value for the initial state results in infinite values for the coefficient of friction. To avoid such behavior when the
user fails to provide nonzero values for the initial state, we set the state variable to L/V0 .
The properties include:
linear_slip_rate Nondimensional slip rate at which linearization occurs, Vl i near . In quasi-static simulations it should
be about one order of magnitude larger than absolute tolerance in solve.
An example of setting the properties for the rate- and state-friction component in a .cfg file is:
friction = pylith.friction.RateStateAgeing ; Change from the default
friction.linear_slip_rate = 1.0e-12 ; default value
The spatial database files for the rate- and state-friction model properties and state variables specify the spatial variation of the
fault constitutive model parameters given in Table 6.18.
Table 6.18: Values in spatial databases for Dieterich-Ruina rate-state friction.

Database Value Description
db_properties reference-friction-coefficient Steady-state coefficient of friction at slip rate
V0 , µ s
reference-slip-rate Reference slip rate, V0
characteristic-slip-distance Slip-weakening parameter, L
constitutive-parameter-a Coefficient for the ln slip rate term, a
constitutive-parameter-b Coefficient for the ln state variable term, b
db_initial_state state-variable State variable, θ
6.4.6 Slip Impulses for Green’s Functions
Computing static Green’s functions using the GreensFns problem requires a specialized fault implementation, FaultCohe-
siveImpulses, to set up the slip impulses. The parameters controlling the slip impulses include the components involved
(lateral, reverse, and/or fault opening) and the amplitude of the pulses (e.g., selecting a subset of a fault or including a spatial
variation). The FaultCohesiveImpulses properties and facilities include:
threshold Threshold for non-zero amplitude; impulses will only be generated at locations on the fault where the
amplitude exceeds this threshold.
impulse_dof Array of components associated with impulses, e.g., [0, 1] for slip involving the lateral and up-dip compo-
nents.
db_impulse_amplitude Spatial database for amplitude of slip impulse (scalar field). Default is SimpleDB.
An example of setting the properties and facilities for FaultCohesiveImpulses in a .cfg file is:
6.5. GRAVITATIONAL BODY FORCES 107
[pylithapp.problem.interfaces]
fault = pylith.faults.FaultCohesiveImpulses ; Change from the default
threshold = 1.0e-6*m ; default
impulse_dof = [0] ; lateral slip-only
db_impulse_amplitude.iohandler.filename = myimpulse.spatialdb
db_impulse_amplitude.label = Impulse amplitude
6.5 Gravitational Body Forces

Many problems in geophysics require the consideration of gravitational body forces. For example, it is often important to
include the effects of the lithostatic (overburden) pressure. In future releases of PyLith that permit nonlinear bulk rheologies,
body forces will affect plastic yield criteria and the deformation field for large deformation/finite strain problems. As described
in Chapter 2 on page 7, the body forces contribute to the residual,
Z
r in = f i N n dV. (6.74)
V
For gravitational body forces, the body force per unit volume, f i , is given as the product of the mass density, ρ , the scalar
gravitational acceleration value, g , and the gravitational acceleration orientation vector, ai :
f i = ρg a i . (6.75)
The mass density is a property of every material model, and is thus included in the spatial database with the physical properties
for each material. The gravitational acceleration is assumed to be uniform and constant for a given problem, with a default
value of 9.80665 m/s2 . The orientation vector will depend on the dimension of the problem as well as the coordinate system
being used. The default orientation vector has components (0, 0, -1). This is appropriate for three-dimensional problems where
the gravity vector is aligned with the negative z-axis, as would be the case in a geographic-projected coordinate system or
a generic Cartesian coordinate system. For cases in which the curvature of the earth should be considered, the spatialdata
package provides an earth-centered, earth-fixed (ECEF) coordinate system and a local georeferenced Cartesian system; in each
of these cases the orientation vector is computed automatically, although this feature has not been tested. For problems in one
or two dimensions where the orientation vector is constant, the vector will need to be explicitly specified. For example, in a
two-dimensional problem, the vector might be specified as (0, -1, 0). The vector still has three components, although the extra
component is not used.
Gravity is turned off by default. To include gravitational effects in a simulation, you can turn it on as follows:
By simply adding this flag, the default gravity field values will be used and a gravity_field component will be assigned
for the problem. The default values may be changed by altering the properties of gravity_field:
[pylithapp.timedependent.gravity_field]
acceleration = 100.0*m*s**-2
gravity_dir = [0, -1, 0]
Examples using gravity are described in Sections 7.8.8 on page 159 and 7.16 on page 189.
Chapter 7
Examples
7.1 Overview
Each example is a self-contained lesson in how to use PyLith. The examples increase in degree of complexity from one to the
next.
7.1.1 Prerequisites
Before you begin any of the examples, you will need to install PyLith following the instructions in Chapter 3 on page 17. For
more complex examples, you will also need either CUBIT cubit.sandia.gov or LaGriT meshing.lanl.gov mesh
generation software to create the meshes. If you do not wish to create your own mesh at this time, the meshes are also provided
as part of the example. The ParaView www.paraview.org visualization package may be used to view simulation results.
ParaView 3 includes built-in documentation that is accessed by clicking on the Help menu item. Some additional documentation
is available on the ParaView Wiki site paraview.org/Wiki/ParaView. You may use other visualization software, but
some adaption from what is described here will be necessary. Furthermore, you can complete a subset of the example using
files provided (as described below), skipping the steps for which you do not have the proper software packages installed.
7.1.1.1 Input Files
The files needed to work through the examples are found in the examples directory under the top-level PyLith directory. There
are five examples in examples/twocells, each consisting of just two cells (elements). These very simple examples make
use of PyLith mesh ASCII format to define the mesh. This format is useful for understanding the basics of how PyLith works,
since it is easy to create these files by hand. More complex problems, such as those found in examples/3d, use external
mesh generation software to create the meshes. All of the files used in the example problems are extensively documented with
comments.
7.2 Examples Using Two Triangles

PyLith features discussed in this example:
• Quasi-static solution
• Mesh ASCII format
• Dirichlet boundary conditions
• Kinematic fault interface conditions
109
110 CHAPTER 7. EXAMPLES
2
3
0 1
Figure 7.1: Mesh composed of two linear triangular cells used in the example problems.
• Plane strain linearly elastic material

• VTK output
• Linear triangular cells
• SimpleDB spatial database
• ZeroDispDB spatial database
All of the files necessary to run the examples are contained in the directory examples/twocells/twotri3.
7.2.1 Overview
This example is the simplest 2D example of a quasi-static finite element problem (a simpler problem would consist of a 1D
bar). It is a mesh composed of two linear triangles subject to displacement boundary conditions, assuming plane-strain linear
elastic behavior. Due to the simple geometry of the problem, the mesh may be constructed by hand, using PyLith mesh ASCII
format. In this example, we will walk through the steps necessary to construct, run, and view three problems that use the same
mesh. In addition to this manual, each of the files for the example problem includes extensive comments.
7.2.2 Mesh Description
The mesh consists of two triangles forming a square with edge lengths of one unit (Figure 7.1). The mesh geometry and
topology are described in the file twotri3.mesh, which is in PyLith mesh ASCII format. This file format is described in
Appendix C on page 223. This file describes the dimensionality of the problem (1D, 2D, or 3D), the coordinates of the vertices
(nodes), the vertices composing each cell (element), the material ID to be associated with each cell, and groups of vertices that
may be used to define faults or surfaces to which boundary conditions may be applied.
7.2.3 Additional Common Information
In addition to the mesh, the three example problems share additional information. For problems of this type, it is generally
useful to create a file named pylithapp.cfg in the working directory, since this file is read automatically every time PyLith
is run. Settings specific to a particular problem may be placed in other .cfg files, as described later, and then those files are
placed on the command line. The settings contained in pylithapp.cfg for this problem consist of:
pylithapp.journal.info Settings that control the verbosity of the output for the different components.
pylithapp.mesh_generator Settings that control mesh importing, such as the importer type, the filename, and the
spatial dimension of the mesh.
pylithapp.timedependent Settings that control the problem, such as the total time, time step size, and spatial dimen-
sion.
pylithapp.timedependent.materials Settings that control the material type, specify which material IDs are to be
associated with a particular material type, and give the name of the spatial database containing the physical
properties for the material. The quadrature information is also given.
pylithapp.petsc PETSc settings to use for the problem, such as the preconditioner type.
7.2. EXAMPLES USING TWO TRIANGLES 111
All of the problems in this directory use the same material database, as specified under
[pylithapp.timedependent.materials]
in pylithapp.cfg. This information is contained in the file matprops.spatialdb. Although the material model is
specified in pylithapp.cfg, the values for the physical properties of the material are given in matprops.spatialdb.
For this example, values describing elastic plane strain material properties are given at a single point, resulting in uniform
material properties.
7.2.4 Axial Displacement Example
The first example problem is extension of the mesh along the diagonal extending from the lower left to the upper right of the
square mesh. Parameter settings that augment those in pylithapp.cfg are contained in the file axialdisp.cfg. These
settings are:
pylithapp.timedependent Specifies an implicit formulation for the problem and specifies the array of boundary con-
ditions.
pylithapp.timedependent.bc.bc Defines which degrees of freedom are being constrained (x and y), gives the
label (defined in twotri3.mesh) defining the points desired, assigns a label to the boundary condi-
tion set, and gives the name of the spatial database with the values for the Dirichlet boundary condition
(axialdisp.spatialdb).
pylithapp.problem.formulation.output.output.writer Gives the base filename for VTK output (axialdisp.vtk).
pylithapp.timedependent.materials.material.output Gives the base filename for state variable output files
(axialdisp-statevars.vtk).
The values for the Dirichlet boundary condition are given in the file axialdisp.spatialdb, as specified in axialdisp.cfg.
The format of all spatial database files is similar. In this case, the desired displacement values are given at two points (lower
left and upper right). Since data are being specified at points (rather than being uniform over the mesh, for example), the data
dimension is one.
The files containing common information (twotri3.mesh, pylithapp.cfg, matprops.spatialdb) along with
the problem-specific files (axialdisp.cfg, axialdisp.spatialdb) provide a complete description of the problem,
and we can then run this example by typing
Once the problem has run, three files will be produced. The first file is named axialdisp_t0000000.vtk. The t0000000
indicates that the output is for the first (and only) time step, corresponding to an elastic solution. This file contains mesh informa-
tion as well as displacement values at the mesh vertices. The second file is named axialdisp-statevars_t0000000.vtk.
This file contains the state variables for each cell. The default fields are the total strain and stress fields. Since the cells are
linear triangles, there is a single quadrature point for each cell and thus a single set of stress and strain values for each cell.
The final file (axialdisp-statevars_info.vtk) gives the material properties used for the problem. Since we have not
specified which properties to write, the default properties (mu, lambda, density) are written. All of the .vtk files may
be used with a number of visualization packages. If the problem ran correctly, you should be able to generate a figure such as
Figure 7.2 on the next page, which was generated using ParaView.
7.2.5 Shear Displacement Example
The next example problem is shearing of the mesh in the y direction using displacements applied along the positive and negative
x boundaries. Parameter settings that augment those in pylithapp.cfg are contained in the file sheardisp.cfg. These
settings include:
pylithapp.timedependent.bc.x_neg Specifies the boundary conditions for the left side of the mesh, defining which
degrees of freedom are being constrained (x and y), giving the label (x_neg, defined in twotri3.mesh)
Figure 7.2: Color contours and vectors of displacement for the axial displacement example using a mesh composed of two
linear triangular cells.
Figure 7.3: Color contours and vectors of displacement for the shear displacement example using a mesh composed of two
linear triangular cells.
defining the points desired, assigning a label to the boundary condition set, and giving the name of the
spatial database with the values for the Dirichlet boundary condition (sheardisp.spatialdb).
pylithapp.timedependent.bc.x_pos Specifies the boundary conditions for the left side of the mesh, defining which
degrees of freedom are being constrained (y only), giving the label (x_pos, defined in twotri3.mesh)
The files containing common information (twotri3.mesh, pylithapp.cfg, matprops.spatialdb) along with the
problem-specific files (sheardisp.cfg, sheardisp.spatialdb) provide a complete description of the problem, and
we can then run this example by typing
$$ pylith sheardisp.cfg
Once the problem has run, three files will be produced as in the previous example. If the problem ran correctly, you should be
able to generate a figure such as Figure 7.3, which was generated using ParaView.
7.3. EXAMPLE USING TWO QUADRILATERALS 113
7.2.6 Kinematic Fault Slip Example
The next example problem is left-lateral fault slip applied between the two triangular cells using kinematic cohesive cells.
The lower left and upper right boundaries are held fixed in the x and y directions. Parameter settings that augment those in
pylithapp.cfg are contained in the file dislocation.cfg. The solution corresponds to rigid body rotation of each
triangular cell. As a result, the tractions on the fault are zero. These settings include:
pylithapp.journal.info Turns on journaling for 1D quadrature (used for 2D faults) and for cohesive kinematic faults.
pylithapp.timedependent.bc.bc Defines which degrees of freedom are being constrained (x and y), gives the label
(defined in twotri3.mesh) defining the points desired, and assigns a label to the boundary condition set.
In this case, rather than specifying a spatial database file with the values for the Dirichlet boundary condition,
the default database (ZeroDispDB) for Dirichlet boundary conditions is used, which sets the displacements
to zero.
pylithapp.timedependent.interfaces Gives the label (defined in twotri3.mesh) defining the points on the
fault, provides quadrature information, and then gives database names for material properties (needed for
conditioning), fault slip, peak fault slip rate, and fault slip time.
pylithapp.timedependent.interfaces.fault.output.writer Gives the base filename for cohesive cell out-
put files (dislocation-fault.vtk).
Rather than specifying the displacement boundary conditions in a spatial database file, we use the default behavior for Dirichlet
boundary conditions, which is a uniform, constant displacement of zero.
The fault example requires three additional database files that were not needed for the simple displacement examples.
The first file (dislocation_slip.spatialdb) specifies 0.01 m of left-lateral fault slip for the entire fault. The data
dimension is zero since the same data are applied to all points in the set. The default slip time function is a step-function, so we
also must provide the time at which slip begins. The elastic solution is associated with advancing from t = −d t to t = 0, so we
set the slip initiation time for the step-function to 0 in dislocation_sliptime.spatialdb.
The files containing common information (twotri3.mesh, pylithapp.cfg, matprops.spatialdb) along with
the problem-specific files (dislocation.cfg, dislocation_slip.spatialdb, dislocation_sliptime.spatialdb)
provide a complete description of the problem, and we can then run this example by typing
$$ pylith dislocation.cfg
Once the problem has run, five files are produced. In addition to the files produced in the previous two examples, this example
produces two files associated with the fault interface. The file dislocation-fault_t0000000.vtk gives the fault slip
for each vertex on the fault along with the computed traction change for the cohesive cell. The file dislocation-fault_info.vtk
provides information such as the normal direction, final slip, and slip time for each vertex on the fault. If the problem ran cor-
rectly, you should be able to generate a figure such as Figure 7.4 on the next page, which was generated using ParaView.
7.3 Example Using Two Quadrilaterals

• Neumann boundary conditions
• VTK output
• Bilinear quadrilateral cells
Figure 7.4: Color contours and vectors of displacement for the kinematic fault example using a mesh composed of two linear
triangular cells.
1 3 5
0 2 4
Figure 7.5: Mesh composed of two bilinear quadrilateral cells used for the example problems.
All of the files necessary to run the examples are contained in the directory examples/twocells/twoquad4.
7.3.1 Overview
This example is another simple 2D example of a quasi-static finite element problem. It is a mesh composed of two bilinear
quadrilaterals subject to displacement or traction boundary conditions, assuming plane-strain linear elastic behavior. Due to the
simple geometry of the problem, the mesh may be constructed by hand, using PyLith mesh ASCII format to describe the mesh.
In this example, we will walk through the steps necessary to construct, run, and view four problems that use the same mesh. In
addition to this manual, each of the files for the example problem includes extensive comments.
The mesh consists of two square cells with edge lengths of one unit forming a regular region (Figure 7.5). The mesh geometry
and topology are described in the file twoquad4.mesh, which is in PyLith mesh ASCII format. This file describes the
dimensionality of the problem (in this case 2D), the coordinates of the vertices (nodes), the vertices composing each cell
(element), the material ID to be associated with each cell, and then provides groups of vertices that may be used to define faults
or surfaces to which boundary conditions may be applied.
In addition to the mesh, the four example problems share additional information. As in the previous examples, we place this
information in pylithapp.cfg, since this file is read automatically every time PyLith is run. Settings specific to a particular
problem may be placed in other .cfg files, as described later, and then those files are placed on the command line.
The first example problem is extension of the mesh along the x axis. Parameter settings that override or augment those in
pylithapp.cfg are contained in the file axialdisp.cfg. These include:
degrees of freedom are being constrained (x), giving the label (defined in twoquad4.mesh) defining the
points desired, assigning a label to the boundary condition set, and giving the name of the spatial database
with the values for the Dirichlet boundary condition (axialdisp.spatialdb).
pylithapp.timedependent.bc.x_pos Specifies the boundary conditions for the right side of the mesh, defining
which degrees of freedom are being constrained (x), giving the label (defined in twoquad4.mesh) defin-
ing the points desired, assigning a label to the boundary condition set, and giving the name of the spatial
database defining the boundary conditions (axialdisp.spatialdb).
pylithapp.timedependent.bc.y_neg Specifies the boundary conditions for the bottom two corners of the mesh,
defining which degrees of freedom are being constrained (y), giving the label (defined in twoquad4.mesh)
defining the points desired, assigning a label to the boundary condition set, and giving the name of the spatial
database with the values for the Dirichlet boundary condition (axialdisp.spatialdb).
The values for the Dirichlet boundary condition are given in the file axialdisp.spatialdb, as specified in axialdisp.cfg.
Because the data are being specified using two control points with a linear variation in the values between the two (rather than
being uniform over the mesh, for example), the data dimension is one.
The files containing common information (twoquad4.mesh, pylithapp.cfg, matprops.spatialdb) along
with the problem-specific files (axialdisp.cfg, axialdisp.spatialdb) provide a complete description of the prob-
lem, and we can then run this example by typing
As in the two triangle axial displacement example, three files will be produced. If the problem ran correctly, you should be able
to produce a figure such as Figure 7.6 on the next page, which was generated using ParaView.
The next example problem is shearing of the mesh in the y direction using displacements applied along the positive and
negative x boundaries. Parameter settings that override or augment those in pylithapp.cfg are contained in the file
sheardisp.cfg. These include:
degrees of freedom are being constrained (x and y), giving the label (x_neg, defined in twoquad4.mesh)
database with the values for the Dirichlet boundary condition (sheardisp.spatialdb).
pylithapp.timedependent.bc.x_pos Specifies the boundary conditions for the left side of the mesh, defining which
degrees of freedom are being constrained (y only), giving the label (x_pos, defined in twoquad4.mesh)
The values for the Dirichlet boundary conditions are described in the file sheardisp.spatialdb, as specified in sheardisp.cfg.
In this case, the desired displacement values are given at two control points, corresponding to the two edges we want to con-
bilinear quadrilateral cells.
bilinear quadrilateral cells.
strain. Since data are being specified at two points with a linear variations in the values between the points (rather than being
uniform over the mesh, for example), the data dimension is one.
with the problem-specific files (sheardisp.cfg, sheardisp.spatialdb) provide a complete description of the prob-
lem, and we can then run this example by typing
As in the previous example, three files will be produced. If the problem ran correctly, you should be able to produce a figure
such as Figure 7.7, which was generated using ParaView.
The next example problem is a left-lateral fault slip applied between the two square cells using kinematic cohesive cells.
The left and right boundaries are held fixed in the x and y directions. Parameter settings that override or augment those in
Figure 7.8: Color contours and vectors of displacement for the kinematic fault example using a mesh composed of two bilinear
quadrilateral cells.
pylithapp.cfg are contained in the file dislocation.cfg. These settings include:

degrees of freedom are being constrained (x and y), giving the label (x_neg, defined in twoquad4.mesh)
defining the points desired, and assigning a label to the boundary condition set. Instead of specifying a
spatial database file for the values of the Dirichlet boundary condition, we use the default spatial database
(ZeroDispDB) for the Dirichlet boundary condition, which sets the displacements to zero for all time.
which degrees of freedom are being constrained (x and y), giving the label (x_neg, defined in twoquad4.mesh)
defining the points desired, and assigning a label to the boundary condition set. We use the ZeroDispDB for
this boundary condition as well, which sets the displacements to zero for all time.
pylithapp.timedependent.interfaces Gives the label (defined in twoquad4.mesh) defining the points on the
The fault example requires three additional database files that were not needed for the simple displacement examples. The first
file (dislocation_slip.spatialdb) specifies 0.01 m of left-lateral fault slip for the entire fault. The data dimension is
zero since the same data are applied to all points in the set. The default slip time function is a step-function, so we also must
provide the time at which slip begins. The elastic solution is associated with advancing from t = −d t to t = 0, so we set the slip
initiation time for the step-function to 0 in dislocation_sliptime.spatialdb.
with the problem-specific files (dislocation.cfg, dislocation_slip.spatialdb, dislocation_sliptime.spatialdb)
The addition of a fault results in two additional output files (as in the two triangle fault example), dislocation-fault_t0000000.vtk
and dislocation-fault_info.vtk. These files provide output of fault slip, change in tractions, and diagnostic infor-
mation such as the normal direction, final slip, and slip time for each vertex on the fault. If the problem ran correctly, you
should be able to produce a figure such as Figure 7.8, which was generated using ParaView.
7.3.7 Axial Traction Example
The fourth example demonstrates the use of Neumann (traction) boundary conditions. Constant tractions are applied to the
right edge of the mesh, while displacements normal to the boundaries are held fixed along the left and bottom edges of the
Figure 7.9: Color contours and vectors of displacement for the axial traction example using a mesh composed of two bilinear
quadrilateral cells.
mesh. Parameter settings that override or augment those in pylithapp.cfg are contained in the file axialtract.cfg.
These settings include:
ditions. The boundary condition type for x_pos is explicitly set to Neumann, since the default boundary
condition type is DirichletBC.
degrees of freedom are being constrained (x) and giving the label (defined in twoquad4.mesh) defining
the points desired. In this case, rather than specifying a spatial database file with values for the Dirichlet
boundary conditions, we use the default spatial database (ZeroDispDB) for the Dirichlet boundary condition,
which sets the displacements to zero for all time.
pylithapp.timedependent.bc.x_pos Specifies the Neumann boundary conditions for the right side of the mesh,
giving the label (defined in twoquad4.mesh) defining the points desired, assigning a label to the boundary
condition set, and giving the name of the spatial database with the traction vectors for the Neumann boundary
condition (axialtract.spatialdb).
pylithapp.timedependent.bc.y_neg Specifies the boundary conditions for the bottom two corners of the mesh,
defining which degrees of freedom are being constrained (y) and giving the label (defined in twoquad4.mesh)
defining the points desired. In this case, we again use the ZeroDispDB, which sets the displacements to zero
for all time.
pylithapp.problem.formulation.output.output.writer Gives the base filename for VTK output (axialtract.vtk).
pylithapp.timedependent.bc.x_pos.output Gives the field to be output for the x_pos boundary (tractions),
and gives the base filename for x_pos boundary output (axialtract-tractions.vtk).
The traction vectors for the Neumann boundary conditions are given in the file axialtract.spatialdb, as specified in
axialtract.cfg. The files containing common information (twoquad4.mesh, pylithapp.cfg, matprops.spatialdb)
along with the problem-specific files (axialtract.cfg, axialtract.spatialdb) provide a complete description of
the problem, and we can then run this example by typing
$$ pylith axialtract.cfg
Once the problem has run, six files will be produced. This includes the five files as in the previous example plus axialtract-tractions_
which gives the x and y components of traction applied at each integration point. If the problem ran correctly, you should be
able to produce a figure such as Figure 7.9, which was generated using ParaView. The results may be compared against the
analytical solution derived in Section E.1.2 on page 234.
7.4. EXAMPLE USING TWO TETRAHEDRA 119
2
0 4
1
Figure 7.10: Mesh composed of two linear tetrahedral cells used for example problems.
7.4 Example Using Two Tetrahedra

• Linearly elastic isotropic material
• VTK output
• Linear tetrahedral cells
All of the files necessary to run the examples are contained in the directory examples/twocells/twotet4.
7.4.1 Overview
This example is a simple 3D example of a quasi-static finite element problem. It is a mesh composed of two linear tetrahedra
subject to displacement boundary conditions, and is probably the simplest example of a 3D elastic problem. Due to the simple
geometry of the problem, the mesh may be constructed by hand, using PyLith mesh ASCII format. In this example, we will
walk through the steps necessary to construct, run, and view two problems that use the same mesh. In addition to this manual,
each of the files for the example problem includes extensive comments.
The mesh consists of two tetrahedra forming a pyramid shape (Figure 7.10). The mesh geometry and topology is described in
the file twotet4.mesh, which is in PyLith mesh ASCII format.
In addition to the mesh, the two example problems share additional information, which we place in pylithapp.cfg.
linear tetrahedral cells.
The first example problem is extension of the mesh along the diagonal, extending along the base of the pyramid between
two opposing vertices. Parameter settings that override or augment those in pylithapp.cfg are contained in the file
axialdisp.cfg. These settings include:
pylithapp.timedependent.bc.bc Defines which degrees of freedom are being constrained (x, y, and z), gives the
label (defined in twotet4.mesh) defining the points desired, assigns a label to the boundary condition set,
and gives the name of the spatial database defining the boundary conditions (axialdisp.spatialdb).
The values for the Dirichlet boundary conditions are described in the file axialdisp.spatialdb, as specified in axialdisp.cfg.
Because data are being specified using two control points (rather than being uniform over the mesh), the data dimension is one.
The files containing common information (twotet4.mesh, pylithapp.cfg, matprops.spatialdb) along with
the problem-specific files (axialdisp.cfg, axialdisp.spatialdb) provide a complete description of the problem,
and we can then run this example by typing
If the problem ran correctly, you should be able to produce a figure such as Figure 7.11, which was generated using ParaView.
The next example problem is a left-lateral fault slip applied between the two tetrahedral cells using kinematic cohesive cells.
The vertices away from the fault are held fixed in the x, y, and z directions. Parameter settings that override or augment those
in pylithapp.cfg are contained in the file dislocation.cfg. These settings include:
pylithapp.timedependent.bc.bc Defines which degrees of freedom are being constrained (x, y, and z), gives the
label (defined in twotet4.mesh) defining the points desired, and assigns a label to the boundary condition
set. Rather than specifying a spatial database file to define the boundary conditions, we use the default spatial
database (ZeroDispDB) for the Dirichlet boundary condition, which sets the displacements to zero.
pylithapp.timedependent.interfaces Gives the label (defined in twotet4.mesh) defining the points on the
file (dislocation_slip.spatialdb) specifies 0.01 m of left-lateral fault slip for the entire fault. The data dimension is
7.5. EXAMPLE USING TWO HEXAHEDRA 121
tetrahedral cells.
zero since the same data are applied to all points in the set. The default slip time function is a step-function, so we also must
provide the time at which slip begins. The elastic solution is associated with advancing from t = −d t to t = 0, so we set the slip
initiation time for the step-function to 0 in dislocation_sliptime.spatialdb.
The files containing common information (twotet4.mesh, pylithapp.cfg, matprops.spatialdb) along with
the problem-specific files (dislocation.cfg, dislocation_slip.spatialdb, dislocation_sliptime.spatialdb)
If the problem ran correctly, you should be able to generate a figure such as Figure 7.12, which was generated using ParaView.
7.5 Example Using Two Hexahedra

• Maxwell viscoelastic material
• VTK output
• Trilinear hexahedral cells
• UniformDB spatial database
• Filtering of cell output fields
All of the files necessary to run the examples are contained in the directory examples/twocells/twohex8.
7 9
11
6
8 10
1 3
5
0 2 4
Figure 7.13: Mesh composed of two trilinear hexahedral cells used for the example problems.
7.5.1 Overview
This example is a simple 3D example of a quasi-static finite element problem. It is a mesh composed of two trilinear hexahedra
subject to displacement boundary conditions. One primary difference between this example and the example with two tetrahedra
is that we use a Maxwell viscoelastic material model, and run the model for 10 time steps of 0.1 year each. Due to the simple
geometry of the problem, the mesh may be constructed by hand, using PyLith mesh ASCII format to describe the mesh. In
this example, we will walk through the steps necessary to construct, run, and view three problems that use the same mesh. In
addition to this manual, each of the files for the example problems includes extensive comments.
The mesh consists of two hexahedra forming a rectangular prism (Figure 7.13). The mesh geometry and topology are described
in the file twohex8.mesh, which is in PyLith mesh ASCII format.
In addition to the mesh, the three example problems share additional information, which we place in pylithapp.cfg.
Note that in this example we make use of the UniformDB spatial database, rather than the SimpleDB implementation used
to specify the physical properties in the other example problems. For simple distributions of material properties (or boundary
conditions), this implementation is often easier to use. Examining pylithapp.cfg, we specify the material information
with the following set of parameters:
[pylithapp.timedependent.materials]
material = pylith.materials.MaxwellIsotropic3D
label = viscoelastic material
id = 1
db</pf> = spatialdata.spatialdb.UniformDB
db.values = [vp, vs, density, viscosity]
db.data = [5773.502691896258*m/s, 3333.333333333333*m/s, 2700.0*kg/m**3, 1.0e18*Pa*s]
<f>quadrature.cell = pylith.feassemble.FIATLagrange
The first example problem is extension of the mesh along the long axis of the prism. Parameter settings that override or augment
those in pylithapp.cfg are contained in the file axialdisp.cfg. These settings include:
7.5. EXAMPLE USING TWO HEXAHEDRA 123
pylithapp.timedependent.bc.x_neg Defines which degrees of freedom are being constrained (x, y, and z), gives
the label (x_neg, defined in twohex8.mesh) defining the points desired, assigns a label to the boundary
condition set, and gives the name of the spatial database with the values for the Dirichlet boundary conditions
pylithapp.timedependent.bc.x_pos Defines which degrees of freedom are being constrained (x, y, and z), gives
the label (x_pos, defined in twohex8.mesh) defining the points desired, assigns a label to the boundary
pylithapp.timedependent.materials.material.output Defines the filter to be used when writing cell state
variables (average over the quadrature points of the cell), specifies which state variables and properties to
output, gives the base filename for state variable output files, and defines the format to use when defining
the output filenames for each time step.
The values for the Dirichlet boundary conditions are given in the file axialdisp.spatialdb, as specified in axialdisp.cfg.
Since data are being specified using two control points (rather than being uniform over the mesh, for example), the data dimen-
sion is one. Note that since we are using a Maxwell viscoelastic model, we request that additional state variables and properties
be output:
[pylithapp.timedependent.materials.material.output]
cell_data_fields = [total_strain, viscous_strain, stress]
cell_info_fields = [mu, lambda, density, maxwell_time]
The files containing common information (twohex8.mesh, pylithapp.cfg) along with the problem-specific files (axialdisp.cfg,
axialdisp.spatialdb) provide a complete description of the problem, and we can then run this example by typing
Once the problem has run, two sets of files will be produced, along with one additional file. The first set will have filenames
such as axialdisp_txxxx.vtk, where xxxx is the time for which output has been produced. In axialdisp.cfg we
specify that the time stamp should be normalized by a value of 1.0 years and the time stamp should be of the form xxx.x
(recall that the decimal point is removed in the filename). As a result, the filenames contain the time in tenths of a year. These
files will contain mesh information as well as displacement values for the mesh vertices at the given time. The second set of
files will have names such as axialdisp-statevars_txxxx.vtk, where xxxx is the time in tenths of a year (as above)
for which output has been produced. These files contain the state variables for each cell at the given time. The default fields
are the total strain and stress fields; however, we have also requested the viscous strains. As specified in axialdisp.cfg,
these values are averaged over each cell. The final file (axialdisp-statevars_info.vtk) gives the material properties
used for the problem. We have requested all of the properties available for this material model (mu, lambda, density,
maxwell_time). If the problem ran correctly, you should be able to produce a figure such as Figure 7.14 on the following
page, which was generated using ParaView.
The second example problem is shearing of the mesh in the y direction. Parameter settings that override or augment those in
pylithapp.cfg are contained in the file sheardisp.cfg. These settings include:
pylithapp.timedependent.bc.x_neg Defines which degrees of freedom are being constrained (x, y, and z), gives
the label (x_neg, defined in twohex8.mesh) defining the points desired, assigns a label to the boundary
(sheardisp.spatialdb).
pylithapp.timedependent.bc.x_pos Defines which degrees of freedom are being constrained (x, y, and z), gives
the label (x_pos, defined in twohex8.mesh) defining the points desired, assigns a label to the boundary
(sheardisp.spatialdb).
The values for the Dirichlet boundary conditions are given in the file sheardisp.spatialdb, as specified in sheardisp.cfg.
Data are being specified at two control points (rather than being uniform over the mesh, for example), so the data dimension is
trilinear hexahedral cells.
trilinear hexahedral cells.
one. The files containing common information (twohex8.mesh, pylithapp.cfg) along with the problem-specific files
(sheardisp.cfg, sheardisp.spatialdb) provide a complete description of the problem, and we can then run this
example by typing
The next example problem is left-lateral fault slip applied between the two hexahedral cells using kinematic cohesive cells. The
vertices away from the fault are held fixed in the x, y, and z directions. Parameter settings that override or augment those in
pylithapp.cfg are contained in the file dislocation.cfg. These settings include:
pylithapp.timedependent.bc.x_neg Defines which degrees of freedom are being constrained (x, y, and z), gives the
label (x_neg, defined in twohex8.mesh) defining the points desired, and assigns a label to the boundary
7.6. EXAMPLE USING TWO TETRAHEDRA WITH GEOREFERENCED COORDINATE SYSTEM MESH 125
Figure 7.16: Color contours and vectors of displacement for the kinematic fault example using a mesh composed of two trilinear
hexahedral cells.
condition set. In this case, we use the default spatial database (ZeroDispDB) for the Dirichlet boundary
condition, which sets the displacements to zero.
pylithapp.timedependent.bc.x_pos Defines which degrees of freedom are being constrained (x, y, and z), gives the
label (x_pos, defined in twohex8.mesh) defining the points desired, and assigns a label to the boundary
condition set.
pylithapp.timedependent.interfaces Gives the label (defined in twohex8.mesh) defining the points on the
file (dislocation_slip.spatialdb) specifies 0.01 m of left-lateral fault slip for the entire fault. The data dimension
is zero since the same data are applied to all points in the set. The default slip time function is a step-function, so we also
must provide the time at which slip begins. The elastic solution is associated with advancing from t = −d t to t = 0, so
we set the slip initiation time for the step-function to 0 in dislocation_sliptime.spatialdb. The files containing
common information (twohex8.mesh, pylithapp.cfg) along with the problem-specific files (dislocation.cfg,
dislocation_slip.spatialdb, dislocation_sliptime.spatialdb) provide a complete description of the
problem, and we can then run this example by typing
7.6 Example Using Two Tetrahedra with Georeferenced Coordinate System Mesh
• VTK output
• SimpleDB spatial database with geographic coordinates
2
0 4
1
Figure 7.17: Mesh composed of two linear tetrahedral cells in a georeferenced coordinate system used for the example problems.
• SCEC CVM-H spatial database

All of the files necessary to run the examples are contained in the directory examples/twocells/twotet4-geoproj.
7.6.1 Overview
This example is virtually identical to the other example using two linear tetrahedra (See Section 7.4 on page 119). The primary
difference is in how the material properties are assigned. For this example, the physical properties come from the SCEC CVM-
H database (described in Section 4.5.4 on page 43). Using the SCEC CVM-H database is straightforward, requiring only a
few modifications to pylithapp.cfg. Because the SCEC CVM-H database uses geographic coordinates, we must also use
geographic coordinates in the PyLith mesh ASCII file and other spatial databases. Note that all of these geographic coordinate
systems do not need to be the same. PyLith will automatically transform from one geographic coordinate system to another
using the spatialdata package. The spatial databases should all use a georeferenced Cartesian coordinate system, such as a
geographic projection to insure interpolation is performed properly. Since all aspects of this problem other than the material
database and the coordinate system are identical to the examples in Section 7.4 on page 119, we only describe the kinematic
fault problem in this example.
The mesh consists of two tetrahedra forming a pyramid shape (Figure 7.17). The mesh geometry and topology are described
in the file twotet4.mesh, which is in PyLith mesh ASCII format. If you compare this mesh against the one used in 7.4 on
page 119, you will notice that, although the mesh topology is the same, the vertex coordinates are significantly different. We
use zone 11 UTM coordinates with the NAD27 datum for the mesh. Although we used the same coordinate system as the SCEC
CVM-H, we could have also used any other geographic projection supported by spatialdata and Proj.4. See Appendix C.2 on
page 224 for other examples of using geographic coordinates.
This problem has some unique aspects compared to the other examples. First, all of the other examples use a Cartesian
coordinate system, while this one uses a geographic coordinate system. In addition to using different vertex coordinates, we
also define the coordinate system for the mesh in pylithapp.cfg:
pylithapp.mesh_generator.importer]
coordsys = spatialdata.geocoords.CSGeoProj
filename = twotet4.mesh
coordsys.space_dim = 3
7.6. EXAMPLE USING TWO TETRAHEDRA WITH GEOREFERENCED COORDINATE SYSTEM MESH 127
[pylithapp.mesh_generator.importer.coordsys]
datum_horiz = NAD27
datum_vert = mean sea level
ellipsoid = clrk66
[pylithapp.mesh\_generator.importer.coordsys.projector]
projection = utm
proj-options = +zone=11
At the top level, we define the type of coordinate system, give the file describing the mesh, and give the number of spatial
dimensions for the coordinate system. We then provide the horizontal datum and vertical datum for the coordinate system,
along with the ellipsoid to be used. Finally, we specify a UTM projection, and specify zone 11 as the zone to be used.
In addition to the usual material information, we must specify that we want to use the SCECCVMH database implemen-
tation:
db = spatialdata.spatialdb.SCECCVMH
db.data_dir = /home/john/data/sceccvm-h/vx53/bin
The first db option defines SCECCVMH as the spatial database to be used. The next line defines the location of the vx53 data
files, and must be changed to the location specified by the user when the package is installed. The package may be obtained
from Harvard’s Structural Geology and Tectonics structure.harvard.edu/cvm-h.
The final difference with the other examples is in the description of the spatial databases. They must also use geographic
coordinates. Examining dislocation_slip.spatialdb, we find:
// We are specifying the data in a projected geographic coordinate system.
cs-data = geo-projected {
to-meters = 1.0
ellipsoid = clrk66
datum-horiz = NAD27
datum-vert = mean sea level
projector = projection {
projection = utm
units = m
}
}
This example problem is a left-lateral fault slip applied between the two tetrahedral cells using kinematic cohesive cells. Note
that we vary the amount of fault slip for each vertex with this example, as described in dislocation_slip.spatialdb.
The vertices away from the fault are held fixed in the x, y, and z directions. Parameter settings that override or augment those
in pylithapp.cfg are contained in the file dislocation.cfg.
Recall that we condition problems with the kinematic fault interface using the material properties. Since the material
properties are being defined using the SCEC CVM-H database, this same database should be used as the material database for
the faults. This also applies to the AbsorbingDampers boundary condition.
The files containing common information (twotet4.mesh, pylithapp.cfg) along with the problem-specific files
(dislocation.cfg, dislocation_slip.spatialdb, dislocation_sliptime.spatialdb) provide a com-
plete description of the problem, and we can then run this example by typing
If the problem ran correctly, you should be able to generate a figure such as Figure 7.18 on the next page, which was generated
using ParaView.
tetrahedral cells in a georeferenced coordinate system.
7.7 Example Using Tetrahedral Mesh Created by LaGriT

• LaGriT mesh format
• Maxwell linear viscoelastic material
• Specifying more than one material
• VTK output
• Custom algebraic multigrid preconditioner with split fields
• Global uniform mesh refinement
All of the files necessary to run the examples are contained in the directory examples/3d/tet4.
7.7.1 Overview
This example is a simple 3D example of a quasi-static finite element problem. It is a mesh composed of 852 linear tetrahedra
subject to displacement boundary conditions. This example demonstrates the usage of the LaGriT mesh generation package
lagrit.lanl.gov to create a mesh, as well as describing how to use a LaGriT-generated mesh in PyLith. In this example
we will walk through the steps necessary to construct, run, and visualize the results for two problems that use the same mesh.
For each of these problems we also consider a simulation using a custom algebraic multigrid preconditioner with a globally
uniformly refined mesh that reduces the node spacing by a factor of two. In addition to this manual, each of the files for the
example problems includes extensive comments.
7.7. EXAMPLE USING TETRAHEDRAL MESH CREATED BY LAGRIT 129
7.7.2 Mesh Generation and Description
The mesh for these examples is a simple rectangular prism (Figure 7.19 on the following page). This mesh would be quite
difficult to generate by hand, so we use the LaGriT mesh generation package. For this example, we provide a documented
command file in examples/3d/tet4. Examination of this command file should provide some insight into how to use
LaGriT with PyLith. For more detailed information refer to the LaGriT website lagrit.lanl.gov. If you have LaGriT
installed on your machine, you can use the command file to create your own mesh. Otherwise, you can use the mesh that has
already been created.
There are two ways to use the command file. The simplest method is to go to the examples/3d/tet4 directory, start
LaGriT, and then type:
input mesh_tet4_1000m.lagrit
This will run the commands in that file, which will produce the necessary files to run the example. This method will cre-
ate the mesh, but you will gain very little insight into what is being done. A more informative approach is to input each
command directly. That way, you will see what each command does. You can simply copy and paste the commands from
mesh_tet4_1000m.lagrit. For example, the first six commands, which define the block shape, are
define / domain_xm / -3.0e+3
define / domain_xp / 3.0e+3
define / domain_ym / -3.0e+3
define / domain_yp / 3.0e+3
define / domain_zm / -4.0e+3
define / domain_zp / 0.0e+3
Continuing through the remainder of the commands in mesh_tet4_1000m.lagrit, you will eventually end up with the
files tet4_1000m_binary.gmv, tet4_1000m_ascii.gmv, tet4_1000m_ascii.pset, and tet4_1000m_binary.pset.
The ASCII files are not actually needed, but we create them so users can see what is contained in the files. These files may also
be used instead of the binary versions, if desired. The .gmv files define the mesh information, and they may be read directly
by the GMV laws.lanl.gov/XCM/gmv/GMVHome.html mesh visualization package. The .pset files specify the ver-
tices corresponding to each set of vertices on a surface used in the problem, including the fault as well as external boundaries
to which boundary conditions are applied.
In addition to the mesh, the example problems share additional information. In such cases it is generally useful to create a file
named pylithapp.cfg in the run directory, since this file is read automatically every time PyLith is run. Settings specific
to a particular problem may be placed in other .cfg files, as described later, and then those files are placed on the command
line. The settings contained in pylithapp.cfg for this problem consist of:
pylithapp.journal.info Settings that control the verbosity of the output for the different components.
pylithapp.mesh_generator Settings that control mesh importing, such as the importer type, the filenames, and the
pylithapp.timedependent Settings that control the problem, such as the total time, time-step size, and number of
entries in the material array.
associated with a particular material type, and give the name of the spatial database containing material
parameters for the mesh. The quadrature information is also given.
Since these examples use a mesh from LaGriT, we set the importer to MeshIOLagrit:
[pylithapp.mesh_generator]
reader = pylith.meshio.MeshIOLagrit
[pylithapp.mesh_generator.reader]
Figure 7.19: Mesh composed of linear tetrahedral cells generated by LaGriT used for the example problems. The different
colors represent the different materials.
filename_gmv = mesh/tet4_1000m_binary.gmv
filename_pset = mesh/tet4_1000m_binary.pset
flip_endian = True
# record_header_32bit = False
Notice that there are a couple of settings pertinent to binary files. The first flag (flip_endian) is used if the binary files were
produced on a machine with a different endianness than the machine on which they are being read. If you get an error when
attempting to run an example, you may need to change the setting of this flag. The second flag (record_header_32bit)
may need to be set to False if the version of LaGriT being used has 64-bit Fortran record headers.
This example differs from previous examples, because we specify two material groups:
materials = [elastic, viscoelastic]
label = Elastic material
id = 1
db.iohandler.filename = spatialdb/mat_elastic.spatialdb
[pylithapp.timedependent.materials.viscoelastic]
label = Viscoelastic material
id = 2
db.iohandler.filename = spatialdb/mat_viscoelastic.spatialdb
The two materials correspond to the two different colors in Figure 7.19 on the preceding page. Each material uses a different
spatial database because the physical parameters are different. In generating the mesh within LaGriT, the mesh contains four
materials as a result of how LaGriT handles materials and interior interfaces. Near the end of the LaGriT command file, we
merge the materials on each side of the fault into a single material to simplify the input and output from PyLith. For this
example, values describing three-dimensional elastic material properties are given by the single point in the spatial databases,
resulting in uniform physical properties within each material.
The first example problem is shearing of the mesh along the y-direction, with displacement boundary conditions applied
on the planes corresponding to the minimum and maximum x-values. Parameter settings that override or augment those in
pylithapp.cfg are contained in the file step01.cfg. These settings are:
ditions.
pylithapp.timedependent.implicit Specifies an array of two output managers, one for the full domain, and an-
other for a subdomain corresponding to the ground surface.
which degrees of freedom are being constrained (x and y), providing the label (defined in tet4_1000m_binary.pset
database defining the boundary conditions (fixeddisp_shear.spatialdb).
degrees of freedom are being constrained (x and y), providing the label (defined in tet4_1000m_binary.pset)
pylithapp.timedependent.bc.z_neg Specifies the boundary conditions for the bottom of the mesh, defining which
degrees of freedom are being constrained (x and y), providing the label (defined in tet4_1000m_binary.pset)
pylithapp.problem.formulation.output.domain.writer Gives the base filename for VTK output over the
entire domain (shearxy.vtk).
pylithapp.problem.formulation.output.subdomain Gives the label of the nodeset defining the subdomain
and gives the base filename for VTK output over the subdomain corresponding to the ground surface
(step01-groundsurf.vtk).
pylithapp.timedependent.materials.elastic.output Gives the base filename for state variable output files
for the elastic material set (step01-elastic.vtk), and causes state variables to be averaged over
all quadrature points in each cell.
pylithapp.timedependent.materials.viscoelastic.output Gives the base filename for state variable out-
put files for the viscoelastic material set (step01-viscoelastic.vtk), and causes state vari-
ables to be averaged over all quadrature points in each cell.
The values for the Dirichlet boundary conditions are described in the file fixeddisp_shear.spatialdb, as specified in
step01.cfg. The format of all spatial database files is similar. Because data are being specified using two control points
(rather than being uniform over the mesh, for example), the data dimension is one.
The files containing common information (tet4_1000m_binary.gmv, tet4_1000m_binary.pset, pylithapp.cfg,
mat_elastic.spatialdb, and mat_viscoelastic.spatialdb) along with the problem-specific files (step01.cfg
and fixeddisp_shear.spatialdb) provide a complete description of the problem, and we can then run this example by
typing
Once the problem has run, six files will be produced. The first file is named step01_t0000000.vtk. The t0000000 indi-
cates that the output is for the first (and only) time step, corresponding to an elastic solution. This file contains mesh information
as well as displacement values at the mesh vertices. The second file is named step01-statevars-elastic_t0000000.vtk.
This file contains the state variables for each cell in the material group elastic. The default fields are the total strain and
stress fields. These values are computed at each quadrature point in the cell. We have requested that the values be averaged over
all quadrature points for each cell; however, since we only have a single quadrature point for each linear tetrahedron, this will
have no effect. The third file (step01-statevars-viscoelastic_info.vtk) gives the material properties used for
the viscoelastic material set. Since we have not specified which properties to write, the default properties (mu, lambda,
density) are written. There are two additional files containing the state variables for each of the material sets. The final file
(step01-groundsurf_t0000000.vtk) is analogous to step01_t0000000.vtk, but in this case the results are only
given for a subset of the mesh corresponding to the ground surface. Also, the cells in this file are one dimension lower than
the cells described in step01_t0000000.vtk, so they are triangles rather than tetrahedra. All of the .vtk files may be
used with a number of visualization packages. If the problem ran correctly, you should be able to generate a figure such as
Figure 7.20 on the facing page, which was generated using ParaView.
7.7.4.1 Alternative Solver and Discretization Settings
Example step01.cfg uses the additive Schwarz preconditioner in conjunction with a classical Gram-Schmidt orthogonal-
ization iterative solver. This preconditioner works reasonably well but the number of iterations generally scales with problem
size. Even this small, simple problem requires 24 iterations. In this example (step02.cfg), we use a more sophisticated
preconditioner that preconditions the degrees of freedom associated with the displacement field with an algebraic multigrid
algorithm (see Section 4.1.5 on page 33 for details). Additionally, we illustrate the use of global uniform mesh refinement to
increase the resolution of the solution by a factor of two. Because the mesh is refined in parallel after distribution, this technique
can be used to run a larger problem than would be possible if the full resolution mesh had to be generated by the mesh generator.
LaGriT runs only in serial and CUBIT has extremely limited parallel mesh generation capabilities. Table 7.1 on the facing page
shows the improved efficiency of the solver using the split fields with the algebraic multigrid preconditioner, especially as the
problem size becomes larger. We have found similar results for other problems.
The field splitting and algebraic multigrid preconditioning are set up in step02.cfg with the following parameters:
Figure 7.20: Color contours and vectors of displacement for the axial displacement example using a mesh composed of linear
tetrahedral cells generated by LaGriT.
Table 7.1: Number of iterations in linear solve for the Shear Displacement and Kinematic Fault Slip problems discussed in this
section. The preconditioner using split fields and an algebraic multigrid algorithm solves the linear system with fewer iterations
with only a small to moderate increase as the problem size grows.
Problem Preconditioner Refinement # DOF # Solve Iterations
Shear Displacement additive Schwarz none 546 24 (step01)
2x 3890 47
split fields with algebraic multigrid none 546 13
2x 3890 28 (step02)
Kinematic Fault Slip additive Schwarz none 735 28 (step03)
2x 4527 63
split fields with algebraic multigrid none 735 28
2x 4527 38 (step04)
matrix_type = aij
[pylithapp.petsc]
pc_type = ml
The uniform global refinement requires changing just a single parameter:

refiner = pylith.topology.RefineUniform
The next example problem is a right-lateral fault slip applied on the vertical fault defined by x = 0. The left and right sides
of the mesh are fixed in the x, y, and z directions. Parameter settings that override or augment those in pylithapp.cfg are
contained in the file step03.cfg. These settings are:
pylithapp.timedependent Specifies an implicit formulation for the problem, the array of boundary conditions, and the
array of interfaces.
pylithapp.timedependent.implicit Specifies an array of two output managers, one for the full domain, and an-
other for a subdomain corresponding to the ground surface.
which degrees of freedom are being constrained (x, y, and z), providing the label (defined in tet4_1000m_binary.ps
defining the points desired, and assigning a label to the boundary condition set. Rather than specifying a
spatial database file to define the boundary conditions, we use the default spatial database (ZeroDispDB) for
the Dirichlet boundary condition, which sets the displacements to zero.
degrees of freedom are being constrained (x, y, and z), providing the label (defined in tet4_1000m_binary.pset)
defining the points desired, and assigning a label to the boundary condition set. Rather than specifying a
spatial database file to define the boundary conditions, we use the default spatial database (ZeroDispDB) for
the Dirichlet boundary condition, which sets the displacements to zero.
pylithapp.timedependent.interfaces Gives the label (defined in tet4_1000m_binary.pset) defining the
points on the fault, provides quadrature information, and then gives database names for material properties
(needed for conditioning), fault slip, peak fault slip rate, and fault slip time.
pylithapp.problem.formulation.output.output.writer Gives the base filename for VTK output over the
entire domain (step03.vtk).
pylithapp.problem.formulation.output.subdomain Gives the label of the nodeset defining the subdomain
and gives the base filename for VTK output over the subdomain corresponding to the ground surface
(step03-groundsurf.vtk).
pylithapp.timedependent.interfaces.fault.output.writer Gives the base filename for cohesive cell out-
put files (step03-fault.vtk).
pylithapp.timedependent.materials.elastic.output Gives the base filename for state variable output files
for the elastic material set (step03-statevars-elastic.vtk), and causes state variables to be
averaged over all quadrature points in each cell.
pylithapp.timedependent.materials.viscoelastic.output Gives the base filename for state variable out-
put files for the viscoelastic material set (step03-statevars-viscoelastic.vtk), and causes
state variables to be averaged over all quadrature points in each cell.
The fault example requires three additional database files that were not needed for the simple displacement example. The first
file (finalslip.spatialdb) specifies a constant value of 2 m of right-lateral fault slip that then tapers linearly to zero from
2 km to 4 km depth, and a linearly-varying amount of reverse slip, with a maximum of 0.25 m at the surface, linearly tapering
to 0 m at 2 km depth. The data dimension is one since the data vary linearly along a vertical line. The default slip time function
is a step-function, so we also must provide the time at which slip begins. The elastic solution is associated with advancing from
Figure 7.21: Color contours and vectors of displacement for the kinematic fault example using a mesh composed of linear
tetrahedral cells generated by LaGriT.
t = −d t to t = 0, so we set the slip initiation time for the step-function to 0 in dislocation_sliptime.spatialdb.

The files containing common information (tet4_1000m_binary.gmv, tet4_1000m_binary.pset, pylithapp.cfg,
mat_elastic.spatialdb, and mat_viscoelastic.spatialdb) along with the problem-specific files (step03.cfg,
finalslip.spatialdb, and sliptime.spatialdb) provide a complete description of the problem, and we can then
run this example by typing
Once the problem has run, eight files will be produced. The first file is named step03_t0000000.vtk. The t0000000
indicates that the output is for the first (and only) time step, corresponding to an elastic solution. This file contains mesh informa-
tion as well as displacement values at the mesh vertices. The second file is named step03-statevars-elastic_t0000000.vtk.
This file contains the state variables for each cell in the material group elastic. The default fields are the total strain and stress
fields. We have requested that the values be averaged over all quadrature points for each cell; however, since we only have a sin-
gle quadrature point for each linear tetrahedron, this will have no effect. The third file (step03-statevars-viscoelastic_info.vt
gives the material properties used for the viscoelastic material set. Since we have not specified which properties to write,
the default properties (mu, lambda, density) are written. There are two additional files containing the state variables for
each of the material sets. The file step03-groundsurf_t0000000.vtk is analogous to step03_t0000000.vtk,
but in this case the results are only given for a subset of the mesh corresponding to the ground surface. Also, the cells in this file
are one dimension lower than the cells described in step03_t0000000.vtk, so they are triangles rather than tetrahedra.
The file step03-fault_t0000000.vtk gives the specified fault slip for each vertex on the fault, along with the computed
traction change for the cohesive cell. The final file, step03-fault_info.vtk, provides information such as the normal
direction, final slip, and slip time for each vertex on the fault. All of the .vtk files may be used with a number of visualization
packages. If the problem ran correctly, you should be able to generate a figure such as Figure 7.21, which was generated using
ParaView.
7.7.5.1 Alternative Solver and Discretization Settings
As we did for the Shear Dislocation examples, in step04.cfg we switch to using the split fields and algebraic multigrid
preconditioner along with global uniform mesh refinement. Because PyLith implements fault slip using Lagrange multipliers,
we make a few small adjusments to the solver settings. As discussed in Section 4.1.5 on page 33, we use a custom preconditioner
for the Lagrange multiplier degrees of freedom when preconditioning with field splitting. Within step04.cfg we turn on
the use of the custom preconditioner for the Lagrange multiplier degrees of freedom and add the corresponding settings for the
fourth field for the algebraic multigrid algorithm,
split_fields = True
use_custom_constraint_pc = True
matrix_type = aij
[pylithapp.petsc]
fs_pc_type = fieldsplit
fs_pc_use_amat = true
fs_pc_fieldsplit_type = multiplicative
fs_fieldsplit_displacement_pc_type = ml
fs_fieldsplit_lagrange_multiplier_pc_type = jacobi
fs_fieldsplit_displacement_ksp_type = preonly
fs_fieldsplit_lagrange_multiplier_ksp_type = preonly
Table 7.1 on page 133 shows the improved efficiency of the solver using the split fields with the algebraic multigrid precondi-
tioner.
7.8 Examples Using Hexahedral Mesh Created by CUBIT/Trelis

PyLith features discussed in this set of examples:
• Static solution
• CUBIT/Trelis mesh format
• Trilinear hexahedral cells
• VTK output
• HDF5 output
• Dirichlet displacement and velocity boundary conditions
• Neumann traction boundary conditions and time-varying tractions
• Static fault rupture
• Multiple kinematic fault ruptures
• Nonlinear solver
• Generalized Maxwell linear viscoelastic material
• Power-law viscoelastic material
• Drucker-Prager elastoplastic material
• Adaptive time stepping
• Static fault friction
• Slip-weakening fault friction
• Rate-and-state fault friction
• Gravitational body forces
• Initial stresses
• Finite strain
7.8. EXAMPLES USING HEXAHEDRAL MESH CREATED BY CUBIT/TRELIS 137
All of the files necessary to run the examples are contained in the directory examples/3d/hex8.
7.8.1 Overview
This example is meant to demonstrate most of the important features of PyLith as a quasi-static finite-element code, using
a sequence of example problems. All problems use the same 3D hexahedral mesh generated using CUBIT/Trelis (CUBIT
is available to employees of the United States government through cubit.sandia.gov and Trelis licenses are available
through www.csimsoft.com/trelis). Each example builds on the previous examples, as we demonstrate new features.
As in the other examples, the files include extensive comments. We start with the generation of the mesh, which is composed of
144 hexahedra. Following the discussion of how to generate the mesh, we discuss the pylithapp.cfg file, which contains
information common to all the simulations. We group the examples into four sections, each pertaining to a particular set of
PyLith features. We suggest users go through each of these sections in order as the complexity increases at each step.
7.8.2 Mesh Generation and Description
The mesh for these examples is a simple rectangular solid (Figure 7.22 on the following page). Although it would be possible
to generate this mesh by hand, we use this example to illustrate the use of CUBIT/Trelis for mesh generation. We provide
documented journal files in examples/3d/hex8/mesh. Dissection of these journal files should provide some insight
into how to use CUBIT/Trelis with PyLith. For more detailed information on using CUBIT/Trelis, refer to the CUBIT/Trelis
documentation. If you have CUBIT/Trelis installed on your machine, you can use the journal files to create your own mesh.
Otherwise, you can use the mesh that has already been created.
If you are using CUBIT/Trelis to generate your own mesh, there are two ways to use the journal files. The simplest method
is to go to the Tools menu, select Play Journal File, and then select the file mesh_hex8_1000m.jou. This will run the
commands in that file as well as the commands in geometry.jou, which is referenced from mesh_hex8_1000m.jou.
Prior to doing this, you should set your directory to the one containing the journal files. This method will create the mesh,
but you will gain very little insight into what is being done. A more informative approach is to input each journal com-
mand into the CUBIT command window directly. That way, you will see what each command does. The first command in
mesh_hex8_1000m.jou is playback geometry.jou, so you should start with the commands in geometry.jou. The first
three commands, which define the block shape, are
reset
brick x 6000 y 6000 z 4000
volume 1 move x 0 y 0 z -2000
Continuing through the remainder of the commands in geometry.jou, and then using the additional commands in mesh_hex8_1000m.j
you will eventually end up with the file box_hex8_1000m.exo, which contains all of the mesh information. This infor-
mation is similar to that included in PyLith mesh ASCII format, but the information is contained in an Exodus file, which is a
specialized netCDF file. If you have the ncdump command available, you can see what is in the file by typing:
$$ ncdump box_hex8_1000m.exo
In addition to the mesh, the example problems share other information. As in previous examples, we place this information in
pylithapp.cfg. Since these examples use a mesh from CUBIT, in this file we set the importer to MeshIOCubit:
reader = pylith.meshio.MeshIOCubit
[pylithapp.mesh_generator.reader]
filename = mesh/box_hex8_1000m.exo
This example differs from some earlier examples, because we specify two material groups:
Figure 7.22: Mesh composed of trilinear hexahedral cells generated by CUBIT used for the suite of example problems. The
different colors represent the two different materials.
materials = [upper_crust, lower_crust]</h>
[pylithapp.timedependent.materials.upper_crust]
label = Upper crust material
id = 1
db.iohandler.filename = spatialdb/mat_elastic.spatialdb
[pylithapp.timedependent.materials.lower_crust]
label = Lower crust material
id = 2
db.iohandler.filename = spatialdb/mat\_elastic.spatialdb
The two material groups correspond to the two different colored regions in Figure 7.22. Using two material groups allows us
to specify different material types or material variations for the upper crust and lower crust, if desired. For now, we retain the
default ElasticIsotropic3D material type for both materials. This behavior will be overridden by example-specific.cfg files
in some of the examples. Although the material groups are specified in pylithapp.cfg, the physical properties for the
material models are given in spatialdb/ mat_elastic.spatialdb. This spatial database provides values at a single
point, resulting in uniform properties within the material.
7.8.4 Example Problems
The example problems are divided into categories that roughly correspond to simple static problems, quasi-static problems,
problems involving fault friction, and problems where gravity is used. For the most part, each successive example involves just
adding or changing a few parameters from the previous example. For this reason, it is advisable to go through each example in
order, starting with the simplest (static problems).
7.8.5 Static Examples

• Static solution
• VTK output
• Dirichlet displacement boundary conditions
• Neumann traction boundary conditions
7.8.5.1 Overview
This set of examples describe the simplest class of problems for PyLith. The problems are all purely elastic, and there is no time-
dependence. This set of elastostatic examples primarily demonstrates the application of different types of boundary conditions
in PyLith, as well as demonstrating the use of a kinematic fault for a static problem. All of the examples are contained in the
directory examples/3d/hex8, and the corresponding .cfg files are step01.cfg, step02.cfg, and step03.cfg.
Each example may be run as follows:
$$ pylith stepXX.cfg
This will cause PyLith to read the default parameters in pylithapp.cfg, and then override or augment them with the
additional parameters in the stepXX.cfg file. Each .cfg file is extensively documented to provide detailed information on
the various parameters.
7.8.5.2 Step01 - Pure Dirichlet Boundary Conditions
The step01.cfg file defines a problem with pure Dirichlet (displacement) boundary conditions corresponding to compres-
sion in the x-direction and shear in the y-direction. The bottom (minimum z) boundary is held fixed in the z-direction. On
the positive and negative x-faces, compressional displacements of 1 m are applied in the x-direction and shear displacements
yielding a left-lateral sense of shear are applied in the y-direction. In this example and in subsequent examples we would like
to output the displacement solution over a subset of the domain corresponding to the ground surface.
[pylithapp.timedependent.implicit]
# Set the output to an array of 2 output managers.
# We will output the solution over the domain and the ground surface.
output = [domain,subdomain]
# Set subdomain component to OutputSolnSubset (boundary of the domain).

output.subdomain = pylith.meshio.OutputSolnSubset
# Give basename for VTK domain output of solution over ground surface.
[pylithapp.problem.formulation.output.subdomain]
# Name of nodeset for ground surface.
label = face_zpos
writer.filename = output/step01-groundsurf.vtk
For the boundary conditions, we must describe which degrees of freedom are being constrained (bc_dof), we must provide
a the label associated with the CUBIT/Trelis nodeset associated with the BC, and we must specify the type of spatial database
is being used to describe the boundary conditions. For the x-faces, we use a SimpleDB to provide the displacements on the
x-faces:
# Boundary condition on +x face
bc_dof = [0, 1]
label = face_xpos
Figure 7.23: Displacement field for example step01 visualized using ParaView. The mesh has been distorted by the computed
displacements (magnified by 500), and the vectors show the computed displacements.
db_initial.label = Dirichlet BC on +x
db_initial.iohandler.filename = spatialdb/fixeddisp_axial_shear.spatialdb
# Boundary condition on -x face

[pylithapp.timedependent.bc.x_neg]
bc_dof = [0, 1]
label = face_xneg
db_initial.label = Dirichlet BC on -x
db_initial.iohandler.filename = spatialdb/fixeddisp_axial_shear.spatialdb
For a SimpleDB, we must provide a filename. The default spatial database for db_initial is ZeroDispBC, which auto-
matically applies zero displacements to all vertices in the nodeset, and no filename is required (or needed).
# Boundary condition on -z face
[pylithapp.timedependent.bc.z_neg]
bc_dof = [2]
label = face_zneg
db_initial.label = Dirichlet BC on -z
When we have run the simulation, the output VTK files will be contained in examples/3d/hex8/output (all with a prefix
of step01). Results using ParaView are shown in Figure 7.23.
7.8.5.3 Step02 - Dirichlet and Neumann Boundary Conditions
The step02.cfg file defines a problem with Dirichlet (displacement) boundary conditions corresponding to zero x and
y-displacements applied on the negative x-face and Neumann (traction) boundary conditions corresponding to normal com-
pression and horizontal shear applied on the positive x-face. The bottom (negative z) boundary is held fixed in the z-direction.
The problem is similar to example step01, except that 1 MPa of normal compression and 1 MPa of shear (in a left-lateral sense)
are applied on the positive x-face, and the negative x-face is pinned in both the x and y-directions.
For the boundary conditions, we must first change the boundary condition type for the positive x-face from the default
Dirichlet to Neumann:
# +x face -- first change bc type to Neumann
[pylithapp.timedependent.bc]
x_pos = pylith.bc.Neumann
We use a SimpleDB to describe the traction boundary conditions. When applying traction boundary conditions over a surface,
it is also necessary to specify integration information for the surface. Since this is a three-dimensional problem, the dimension
of the surface is 2. Since the cells being used are trilinear hexahedra, the cell type is FIATLagrange and we use an integration
order of 2. A lower integration order would not provide sufficient accuracy while a higher integration order would offer no
benefit (while requiring more computation time and storage):
label = face_xpos
db_initial.label = Neumann BC on +x
db_initial.iohandler.filename = spatialdb/tractions_axial_shear.spatialdb
# We must specify quadrature information for the cell faces.

quadrature.cell.quad_order = 2
The boundary conditions on the negative x-face are simpler than they were in example step01 (zero displacements in the x and
y-directions), so we can use the default ZeroDispBC:
bc_dof = [0, 1]
label = face_xneg
The boundary conditions on the negative z-face are supplied in the same manner as for example step01. When we have run the
simulation, the output VTK files will be contained in examples/3d/hex8/output (all with a prefix of step02). Results
using ParaView are shown in Figure 7.24.
7.8.5.4 Step03 - Dirichlet Boundary Conditions with Kinematic Fault Slip
The step03.cfg file describes a problem with Dirichlet (displacement) boundary conditions corresponding to zero x and
y-displacements applied on the negative and positive x-faces and a vertical fault with a combination of left-lateral and updip
motion. The left-lateral component of fault slip has a constant value of 2 m in the upper crust, and then decreases linearly to
zero at the base of the model. The reverse slip component has a value of 0.25 m at the surface, and then decreases linearly to
zero at 2 km depth.
Due to the simplicity of the boundary conditions, we are able to use the default ZeroDispBC for the positive and negative
x-faces, as well as the negative z-face. To use a fault, we must first define a fault interface. We do this by providing an array
containing a single interface. For this example we specify the fault slip, so we set the interface type to FaultCohesiveKin.
# Set interfaces to an array of 1 fault: ’fault’.
# Set the type of fault interface condition.

[pylithapp.timedependent.interfaces]
fault = pylith.faults.FaultCohesiveKin
[pylithapp.timedependent.interfaces.fault]
# The label corresponds to the name of the nodeset in CUBIT/Trelis.
label = fault
# We must define the quadrature information for fault cells.

# The fault cells are 2D (surface).
We retain the default StepSlipFn since we want static fault slip. Finally, we use one SimpleDB to define the spatial variation
of fault slip, and another SimpleDB to define the spatial variation in slip initiation times (the start time is 0.0 everywhere since
this is a static problem):
# The slip time and final slip are defined in spatial databases.
[pylithapp.timedependent.interfaces.fault.eq\_srcs.rupture.slip\_function]
slip.iohandler.filename = spatialdb/finalslip.spatialdb
slip.query_type = linear
slip_time.iohandler.filename = spatialdb/sliptime.spatialdb
# Fault output, give the basename for the VTK file.

[pylithapp.problem.interfaces.fault.output]
writer.filename = output/step03-fault.vtk
This will result in two extra files being produced. The first file (step03-fault_info.vtk) contains information such as
the normal directions to the fault surface, the applied fault slip, and the fault slip times. The second file (step03-fault_t0000000.vtk)
contains the cumulative fault slip for the time step and the change in tractions on the fault surface due to the slip. When we have
run the simulation, the output VTK files will be contained in examples/3d/hex8/output (all with a prefix of step03).
Results using ParaView are shown in Figure 7.25 on the facing page.
7.8.6 Quasi-Static Examples
• Formatting timestamps of VTK output files
• HDF5 output
• Output of velocity field
• Neumann traction boundary conditions and time-varying tractions
• CompositeDB spatial database
• Quasi-static fault rupture and fault creep
• Multiple kinematic fault ruptures

• Power-law viscoelastic material
• Drucker-Prager elastoplastic material
• Adaptive time stepping
7.8.6.1 Overview
This set of examples describes a set of quasi-static problems for PyLith. These quasi-static problems primarily demonstrate the
usage of time-dependent boundary conditions and fault slip, as well as different rheologies. Some of the examples also demon-
strate the usage of the nonlinear solver, which is required by the nonlinear rheologies (power-law viscoelastic and Drucker-
Prager elastoplastic). Some of the examples also demonstrate the usage of HDF5 output, which is an alternative to the default
VTK output. All of the examples are contained in the directory examples/3d/hex8, and the corresponding .cfg files are
step04.cfg, step05.cfg, step06.cfg, step07.cfg, step08.cfg, and step09.cfg. Each example may be
run as follows:
additional parameters in the stepXX.cfg file. Each .cfg file is extensively documented, to provide detailed information on
7.8.6.2 Step04 - Pure Dirichlet Velocity Boundary Conditions
The step04.cfg file defines a problem with x-displacements fixed at zero on the positive and negative x-faces while ve-
locity boundary conditions are applied in the y-directions on the same faces, yielding a left-lateral sense of movement. The
bottom (negative z) boundary is held fixed in the z-direction. We also use a Maxwell viscoelastic material for the lower crust,
and the simulation is run for 200 years using a constant time-step size of 20 years. The default time stepping behavior is
TimeStepUniform. We retain that behavior for this problem and provide the total simulation time and the time-step size:
# Change the total simulation time to 200 years, and use a constant time
# step size of 20 years.
[pylithapp.timedependent.implicit.time_step]<.h>
total_time = 200.0*year
dt = 20.0*year
We then change the material type of the lower crust, provide a spatial database from which to obtain the material properties
(using the default SimpleDB), and request additional output information for the material:
# Change material type of lower crust to Maxwell viscoelastic.
materials.lower_crust = pylith.materials.MaxwellIsotropic3D
# Provide a spatial database from which to obtain property values.

# Since there are additional properties and state variables for the Maxwell
# model, we explicitly request that they be output. Properties are named in
# cell_info_fields and state variables are named in cell_data_fields.
db_properties.iohandler.filename = spatialdb/mat_maxwell.spatialdb
output.cell_info_fields = [density, mu, lambda, maxwell_time]
output.cell_data_fields = [total_strain, stress, viscous_strain]
Note that the default output.cell_info_fields are those corresponding to an elastic material (density, mu, lambda),
and the default output.cell_data_fields are total_strain and stress. For materials other than elastic, there
are generally additional material properties and state variables, and the appropriate additional fields must be specifically re-
quested for each material type.
This example has no displacements in the elastic solution (t = 0), so we retain the default ZeroDispDB for all instances
of db_initial. To apply the velocity boundary conditions, we must specify db_rate, which is zero by default. We use a
UniformDB to assign the velocities:
bc_dof = [0, 1]
label = face_xpos
db_rate.label = Dirichlet rate BC on +x
db_rate.values = [displacement-rate-x, displacement-rate-y, rate-start-time]
db_rate.data = [0.0*cm/year, 1.0*cm/year, 0.0*year]

bc_dof = [0, 1]
label = face_xneg
db_rate.data = [0.0*cm/year, -1.0*cm/year, 0.0*year]
Note that db_rate requires a start time, which allows the condition to be applied at any time during the simulation. For this
example, we start the velocity boundary conditions at t = 0.
Finally, we must provide information on VTK output. This is slightly more complicated than the static case, because we
must decide the frequency with which output occurs for each output manager. We also assign a more user-friendly format to
the output file time stamp, and we request that the time stamp is in units of 1 year (rather than the default value of seconds):
# Give basename for VTK domain output of solution over domain.
[pylithapp.problem.formulation.output.domain]
# We specify that output occurs in terms of a given time frequency, and
# ask for output every 40 years. The time stamps of the output files are
# in years (rather than the default of seconds), and we give a format for
Figure 7.26: Displacement field for example step04 at t = 200 years visualized using ParaView. The mesh has been distorted
by the computed displacements (magnified by 500), and the vectors show the computed displacements.
# the time stamp.

time_step = 40.0*year
writer.filename = output/step04.vtk
writer.time_format = \%04.0f
writer.time_constant = 1.0*year
# Give basename for VTK domain output of solution over ground surface.
label = face_zpos ; Name of nodeset for ground surface
# We keep the default output frequency behavior (skip every n steps), and
# ask to skip 0 steps between output, so that we get output every time step.
skip = 0
writer.filename = output/step04-groundsurf.vtk
writer.time_format = %04.0f
writer.time_constant = 1.0*year
We provide similar output information for the two materials (upper_crust and lower_crust). Note that for the domain
output, we requested output in terms of a given time frequency, while for the subdomain we requested output in terms of number
of time steps. When we have run the simulation, the output VTK files will be contained in examples/3d/hex8/output
(all with a prefix of step04). Results using ParaView are shown in Figure 7.26.
7.8.6.3 Step05 - Time-Varying Dirichlet and Neumann Boundary Conditions
The step05.cfg file describes a problem with time-varying Dirichlet and Neumann boundary conditions. The example is
similar to example step04, with a few important differences:
• The Dirichlet boundary conditions on the negative x-face include an initial displacement (applied in the elastic solution),
as well as a constant velocity.
• Neumann (traction) boundary conditions are applied in the negative x-direction on the positive x-face, giving a compres-
sive stress. An initial traction is applied in the elastic solution, and then at t = 100 years it begins decreasing linearly until
it reaches zero at the end of the simulation (t = 200 years).
We again use a Maxwell viscoelastic material for the lower crust.

For the boundary conditions, we must first change the boundary condition type for the positive x-face from the default
Dirichlet to Neumann:
# +x face -- first change bc type to Neumann
x_pos = pylith.bc.Neumann
We provide quadrature information for this face as we did for example step02. We then use a UniformDB for both the initial
tractions as well as the traction rates. We provide a start time of 100 years for the traction rates, and use a rate of 0.01 MPa/year,
so that by the end of 200 years we have completely cancelled the initial traction of -1 MPa:
# First specify a UniformDB for the initial tractions, along with the values.
db_initial = spatialdata.spatialdb.UniformDB
db_initial.label = Neumann BC on +x
db_initial.values = [traction-shear-horiz, traction-shear-vert, traction-normal]
db_initial.data = [0.0*MPa, 0.0*MPa, -1.0*MPa]
# Provide information on traction rates.

db_rate.label = Neumann rate BC on +x
db_rate.values = [traction-rate-shear-horiz, traction-rate-shear-vert, traction-rate-normal,rate-start-t
db_rate.data = [0.0*MPa/year, 0.0*MPa/year, 0.01*MPa/year, 100.0*year]
The boundary conditions on the negative x-face are analogous, but we are instead using Dirichlet boundary conditions, and the
initial displacement is in the same direction as the applied velocities:
# -x face
bc_dof = [0, 1]
label = face_xneg
# Initial displacements.
db_initial.values = [displacement-x, displacement-y]
db_initial.data = [0.0*cm, -0.5*cm]
# Velocities.
db_rate.label = Dirichlet rate BC on -x
db_rate.values = [displacement-rate-x,displacement-rate-y,rate-start-time]
The boundary conditions on the negative z-face are supplied in the same manner as for example step04. When we have run the
simulation, the output VTK files will be contained in examples/3d/hex8/output (all with a prefix of step05). Results
using ParaView are shown in Figure 7.27 on the facing page.
7.8.6.4 Step06 - Dirichlet Boundary Conditions with Time-Dependent Kinematic Fault Slip
The step06.cfg file defines a problem with Dirichlet (displacement) boundary conditions corresponding to zero x- and
y-displacements applied on the negative and positive x-faces and a vertical fault that includes multiple earthquake ruptures as
well as steady fault creep. The upper (locked) portion of the fault has 4 m of left-lateral slip every 200 years, while the lower
(creeping) portion of the fault slips at a steady rate of 2 cm/year. The problem bears some similarity to the strike-slip fault
model of Savage and Prescott [Savage and Prescott, 1978], except that the fault creep extends through the viscoelastic portion
of the domain, and the far-field displacement boundary conditions are held fixed.
In this example and the remainder of the examples in this section, we change the time stepping behavior from the default
TimeStepUniform to TimeStepAdapt. For adaptive time stepping, we provide the maximum permissible time-step size,
along with a stability factor. The stability factor controls the time-step size relative to the stable time-step size provided by
the different materials in the model. A stability_factor of 1.0 means we should use the stable time-step size, while a
Figure 7.27: Displacement field for example step05 at t = 40 years visualized using ParaView. The mesh has been distorted by
the computed displacements (magnified by 500), and the vectors show the computed displacements.
stability_factor greater than 1.0 means we want to use a smaller time-step size. A stability_factor less than 1.0
allows time-step sizes greater than the stable time-step size, which may provide inaccurate results. The adaptive time stepping
information is provided as:
# Change time stepping algorithm from uniform time step, to adaptive
# time stepping.
time_step = pylith.problems.TimeStepAdapt
# Change the total simulation time to 700 years, and set the maximum time
# step size to 10 years.
[pylithapp.timedependent.implicit.time_step]
max_dt = 10.0*year
stability_factor = 1.0 ; use time step equal to stable value from materials
In this example and the remainder of the examples in this section, we also make use of HDF5 output rather than the default
VTK output. HDF5 output is a new feature beginning with PyLith version 1.6, and it is much more efficient with the additional
advantage that multiple time steps can be contained in a single file. PyLith also produces Xdmf files describing the contents of
the HDF5 files, which allows the files to be read easily by applications such as ParaView. Since VTK output is still the default,
we must change the value from the default. Also note that the filename suffix is .h5:
# Give basename for output of solution over domain.
# ask for output every 50 years.
# We are using HDF5 output so we must change the default writer.

writer = pylith.meshio.DataWriterHDF5
writer.filename = output/step06.h5
Note that we no longer need the writer.time_format or writer.time_constant properties, since all time steps are
contained in a single file. The HDF5 writer does not have these properties, so if we attempt to define them an error will result.
We also set the writer for other output as well, since it is not the default. For subdomain output we use:
# Give basename for output of solution over ground surface.
label = face_zpos
# We again switch the writer to produce HDF5 output.
skip = 0
writer.filename = output/step06-groundsurf.h5
# Fault output
[pylithapp.problem.interfaces.fault.output]
skip = 0
writer.filename = output/step06-fault.h5
Due to the simplicity of the boundary conditions, we are able to use the default ZeroDispBC for the positive and negative x-
faces, as well as the negative z-face. As for example step03, we define a fault interface, we identify the nodeset corresponding
to the fault, and we provide quadrature information for the fault. We then define an array of earthquake sources and provide an
origin time for each:
# Set earthquake sources to an array consisting of creep and 3 ruptures.
eq_srcs = [creep, one, two, three]
eq_srcs.creep.origin_time = 00.0*year
eq_srcs.one.origin_time = 200.0*year
eq_srcs.two.origin_time = 400.0*year
eq_srcs.three.origin_time = 600.0*year
Note that the creep begins at t = 0 years, while the ruptures (one, two, three) occur at regular intervals of 200 years. We
retain the default StepSlipFn for the ruptures. Each of the ruptures has the same amount of slip, and slip occurs simultaneously
for the entire rupture region, so we can use the same SimpleDB files providing slip and slip time for each rupture:
# Define slip and origin time for first rupture.
[pylithapp.timedependent.interfaces.fault.eq_srcs.one.slip_function]
slip.iohandler.filename = spatialdb/finalslip_rupture.spatialdb
# Define slip and origin time for second rupture.

[pylithapp.timedependent.interfaces.fault.eq_srcs.two.slip_function]
# Define slip and origin time for third rupture.

[pylithapp.timedependent.interfaces.fault.eq_srcs.three.slip_function]
For the creep source, we change the slip function to ConstRateSlipFn, and we use a SimpleDB for both the slip time and the
slip rate:
# Define slip rate and origin time for fault creep.
[pylithapp.timedependent.interfaces.fault.eq_srcs.creep]
slip_function = pylith.faults.ConstRateSlipFn
slip_function.slip_rate.iohandler.filename = spatialdb/sliprate_creep.spatialdb
slip_function.slip_time.iohandler.filename = spatialdb/sliptime.spatialdb
For all earthquake sources we provide both an origin_time and a slip_function.slip_time. The first provides the
starting time for the entire earthquake source, while the second provides any spatial variation in the slip time with respect to the
origin_time (if any). Since there are multiple earthquake sources of different types, there are a number of additional fault
information fields available for output. We add these additional fields’ output to the fault information file:
output.vertex_info_fields = [normal_dir, strike_dir, dip_dir, final_slip_creep, \
final_slip_one, final_slip_two, final_slip_three, slip_time_creep, slip_time_one, \
slip_time_two, slip_time_three]
This additional information will be contained in file step06-fault_info.h5. It will contain final slip information for each
earthquake source along with slip time information. When we have run the simulation, the output HDF5 and Xdmf files will be
contained in examples/3d/hex8/output (all with a prefix of step06). To open the files in ParaView, the Xdmf (.xmf)
files should be opened, as these files describe the HDF5 data structure. Results using ParaView are shown in Figure 7.28.
In step07 we add velocity boundary conditions in the positive and negative y-directions on the positive and negative x-faces, so
that the external boundaries keep pace with the average fault slip. This problem is nearly identical to the strike-slip fault model
of Savage and Prescott [Savage and Prescott, 1978], except that the fault creep extends through the viscoelastic portion of the
domain.
We use the default ZeroDispBC for the initial displacements on the positive and negative x-faces, as well as the negative
z-face. For the velocities on the positive and negative x-faces, we use a UniformDB:
bc_dof = [0, 1]
label = face_xpos
db_rate.data = [0.0*cm/year, 1.0*cm/year, 0.0*year]

bc_dof = [0, 1]
label = face_xneg
The fault definition information is identical to example step06. In previous examples, we have just used the default output
for the domain and subdomain (ground surface), which includes the displacements. In many cases, it is also useful to include
the velocities. PyLith provides this information, computing the velocities for the current time step as the difference between
the current displacements and the displacements from the previous time step, divided by the time-step size. This is more
accurate than computing the velocities from the displacement field output that has been decimated in time. We can obtain this
information by explicitly requesting it in vertex_data_fields:
# Give basename for output of solution over domain.
# ask for output every 50 years.
# We also request velocity output in addition to displacements.
vertex_data_fields = [displacement, velocity]
# We are using HDF5 output so we must change the default writer.

writer.filename = output/step07.h5
# Give basename for output of solution over ground surface.

label = face_zpos
# We also request velocity output in addition to displacements.

skip = 0

writer.filename = output/step07-groundsurf.h5
When we have run the simulation, the output HDF5 and Xdmf files will be contained in examples/3d/hex8/output (all
with a prefix of step07). As for example step06, make sure to open the .xmf files rather than the .h5 files. Results using
ParaView are shown in Figure 7.29 on the facing page.
7.8.6.6 Step08 - Dirichlet Velocity Boundary Conditions with Time-Dependent Kinematic Fault Slip and Power-Law
Rheology
The step08.cfg file defines a problem that is identical to example step07, except the the lower crust is composed of a
power-law viscoelastic material. Since the material behavior is now nonlinear, we must use the nonlinear solver:
# For this problem we must switch to a nonlinear solver.
implicit.solver = pylith.problems.SolverNonlinear
Although we have not discussed the PyLith PETSc settings previously, note that the use of the nonlinear solver may require
additional options if we wish to override the defaults. These settings are contained in pylithapp.cfg:
[pylithapp.petsc]
# Nonlinear solver monitoring options.
snes_rtol = 1.0e-8
Figure 7.29: Displacement field (color contours) and velocity field (vectors) for example step07 at t = 300 years visualized
using ParaView. The mesh has been distorted by the computed displacements (magnified by 500), and the vectors show the
computed velocities.
snes_atol = 1.0e-12
snes_max_it = 100
snes_monitor = true
snes_view = true
snes_converged_reason = true
These settings are ignored unless we are using the nonlinear solver.
When setting the physical properties for the power-law material in PyLith, the parameters (see Section 5.3.4.1 on page 73)
do not generally correspond to the values provided in laboratory results. PyLith includes a utility code, powerlaw_gendb.py,
to simplify the process of using laboratory results with PyLith. This utility code is installed in the same location as PyLith. An
example of how to use it is in examples/3d/hex8/spatialdb/powerlaw. The user must provide a spatial database
defining the spatial distribution of laboratory-derived parameters (contained in powerlaw_params.spatialdb), another
spatial database defining the temperature field in degrees K (contained in temperature.spatialdb), and a set of points for
which values are desired (powerlaw_points.txt). The parameters for the code are defined in powerlaw_gendb.cfg.
The properties expected by PyLith are reference_strain_rate, reference_stress, and power_law_exponent.
The user must specify either reference_strain_rate or reference_stress so that powerlaw_gendb.py can
compute the other property. Default values of 1.0e-6 1/s and 1 MPa are provided. In this example, the same database was used
for all parameters, and a separate database was used to define the temperature distribution. In practice, the user can provide any
desired thermal model to provide the spatial database for the temperature. In this example, a simple 1D (vertically-varying) dis-
tribution was used. The utility code can be used by simply executing it from the examples/3d/hex8/spatialdb/powerlaw
directory:
$$ powerlaw_gendb.py
This code will automatically read the parameters in powerlaw_gendb.cfg in creating the file examples/3d/hex8/spatialdb/mat
We first change the material type of the lower crust to PowerLaw3D:
# Change material type of lower crust to power-law viscoelastic.
materials.lower_crust = pylith.materials.PowerLaw3D
In many cases, it is useful to obtain the material properties from two different sources. For example, the elastic properties may
come from a seismic velocity model while the viscous properties may be derived from a thermal model. In such a case we can
use a CompositeDB, which allows a different spatial database to be used for a subset of the properties. We do this as follows:
Figure 7.30: The XY-component of strain (color contours) and displacement field (vectors) for example step08 at t =
150 years visualized using ParaView. For this visualization, we loaded both the step08-lower_crust.xmf and
step08-upper_crust.xmf files to contour the strain field, and superimposed on it the displacement field vectors from
step08.xmf.

# In this case, we prefer to obtain the power-law properties from one
# database and the elastic properties from another database, so we use
# a CompositeDB. Each part of the CompositeDB is a SimpleDB.
db_properties.db_A = spatialdata.spatialdb.SimpleDB
We must define the properties that come from each spatial database and then provide the database parameters:
# Provide the values to be obtained from each database and the database
# name.
[pylithapp.timedependent.materials.lower_crust.db_properties]
values_A = [density, vs, vp] ; Elastic properties.
db_A.label = Elastic properties
db_A.iohandler.filename = spatialdb/mat_elastic.spatialdb
values_B = [reference-stress, reference-strain-rate, power-law-exponent] ; Power-law properties.
db_B.label = Power-law properties
db_B.iohandler.filename = spatialdb/mat_powerlaw.spatialdb
The PowerLaw3D material has additional properties and state variables with respect to the default ElasticIsotropic3D mate-
rial, so we request that these properties be written to the lower_crust material files:
# Since there are additional properties and state variables for the
# power-law model, we explicitly request that they be output. Properties are
# named in cell_info_fields and state variables are named in
# cell_data_fields.
output.cell_info_fields = [density, mu, lambda, reference_strain_rate, reference_stress, power_law_expon
output.cell_data_fields = [total_strain, stress, viscous_strain]
with a prefix of step08). Results using ParaView are shown in Figure 7.30.
7.8.6.7 Step09 - Dirichlet Velocity Boundary Conditions with Time-Dependent Kinematic Fault Slip and Drucker-
Prager Elastoplastic Rheology
In this example we use a Drucker-Prager elastoplastic rheology in the lower crust. As in example step08, the material behavior
is nonlinear so we again use the nonlinear solver. The material is elastoplastic, there is no inherent time-dependent response
and the stable time-step size for the material depends on the loading conditions. To avoid this, we set the maximum time-step
size to 5 years rather than the value of 10 years used in example step08:
max_dt = 5.0*year
# For this problem we set adapt\_skip to zero so that the time step size is
# readjusted every time step.
adapt_skip = 0
# Change material type of lower crust to Drucker-Prager.

materials.lower_crust = pylith.materials.DruckerPrager3D

# In this case, we prefer to obtain the Drucker-Prager properties from one
# database and the elastic properties from another database, so we use
# a CompositeDB. Each part of the CompositeDB is a SimpleDB.
db_properties.db_A = spatialdata.spatialdb.SimpleDB
As for the step08 example, we first define the properties that come from each spatial database and then provide the database
filename:
# Provide the values to be obtained from each database and the database
# name.
[pylithapp.timedependent.materials.lower_crust.db_properties]
values_A = [density,vs,vp] ; Elastic properties.
db_A.label = Elastic properties
db_A.iohandler.filename = spatialdb/mat_elastic.spatialdb
values_B = [friction-angle, cohesion, dilatation-angle] ; Drucker-Prager properties.

db_B.label = Drucker-Prager properties
db_B.iohandler.filename = spatialdb/mat\_druckerprager.spatialdb
We also request output of the properties and state variables that are unique to the DruckerPrager3D material:
# Drucker-Prager model, we explicitly request that they be output.
# Properties are named in cell\_info\_fields and state variables are named in
# cell_data_fields.
output.cell_info_fields = [density, mu, lambda, alpha_yield, beta, alpha_flow]
output.cell_data_fields = [total_strain, stress, plastic_strain]
with a prefix of step09). Results using ParaView are shown in Figure 7.31 on the next page.
Figure 7.31: The XY-component of strain (color contours) and displacement field (vectors) for example step09 at t =
150 years visualized using ParaView. For this visualization, we loaded both the step09-lower_crust.xmf and
step09-upper_crust.xmf files to contour the strain field, and superimposed on it the displacement field vectors from
step09.xmf.
7.8.7 Fault Friction Examples
• Static fault friction

• Slip-weakening fault friction
• Rate-and-state fault friction
7.8.7.1 Overview
This set of examples provides an introduction to using fault friction in static and quasi-static problems with PyLith. Dynamic
problems with fault friction are discussed in Section 7.12 on page 177. The boundary conditions are all either static or quasi-
static Dirichlet conditions, and only elastic materials are used. In all the fault friction examples we apply axial (x) displacements
on both the positive and negative x-faces to maintain a compressive normal tractions on the fault. Otherwise, there would be
no frictional resistance. Fault friction generates nonlinear behavior, so we use the nonlinear solver. All of the examples
are contained in the directory examples/3d/hex8, and the corresponding .cfg files are step10.cfg, step11.cfg,
step12.cfg, step13.cfg, and step14.cfg. Each example may be run as follows:
7.8.7.2 Step10 - Static Friction (Stick) with Static Dirichlet Boundary Conditions
The step10.cfg file defines a problem that is identical to example step01, except for the presence of a vertical fault with
static friction. In this case, the applied displacements are insufficient to cause the fault to slip, so the solution is identical to that
in example step01. As in previous examples involving faults, we must first provide an array defining the fault interfaces:
# Set interfaces to an array of 1 fault: ’fault’.
# Fault friction models are nonlinear, so use nonlinear solver.

solver = pylith.problems.SolverNonlinear
We need to change the fault interface from the default (FaultCohesiveKin) to FaultCohesiveDyn and we set the friction
model to use:
[pylithapp.timedependent.interfaces]
fault = pylith.faults.FaultCohesiveDyn ; Change to dynamic fault interface.
friction = pylith.friction.StaticFriction ; Use static friction model.
The StaticFriction model requires values for the coefficient of friction and the cohesion (see Section 6.4.5.3 on page 101). We
provide both of these using a UniformDB:
# Set static friction model parameters using a uniform DB. Set the
# static coefficient of friction to 0.6 and cohesion to 0.0 Pa.
friction.db_properties = spatialdata.spatialdb.UniformDB
friction.db_properties.label = Static friction
friction.db_properties.values = [friction-coefficient, cohesion]
friction.db_properties.data = [0.6, 0.0*Pa]
# Fault friction models require additional PETSc settings:

[pylithapp.petsc]
# Friction sensitivity solve used to compute the increment in slip
# associated with changes in the Lagrange multiplier imposed by the
# fault constitutive model.
friction_sub_pc_factor_shift_type = nonzero
friction_ksp_max_it = 25
friction_ksp_gmres_restart = 30
# Uncomment to view details of friction sensitivity solve.

#friction_ksp_monitor = true
#friction_ksp_view = true
friction_ksp_converged_reason = true
of step10). Results using ParaView are shown in Figure 7.32 on the following page.
7.8.7.3 Step11 - Static Friction (Slip) with Static Dirichlet Boundary Conditions
In step11 we apply twice as much shear displacement as in step10, which is sufficient to induce slip on the fault. All other
settings are identical. To change the amount of shear displacement, we change the spatial database for the positive and negative
x-faces to a UniformDB, and apply the altered values within the .cfg file:
bc_dof = [0, 1]
label = face_xpos
db_initial.data = [-1.0*m, 2.0*m]
Figure 7.32: Magnitude of tractions on the fault for example step10 visualized using ParaView.

bc_dof = [0, 1]
label = face_xneg
db_initial.data = [1.0*m, -2.0*m]
of step11). Results using ParaView are shown in Figure 7.33 on the next page.
7.8.7.4 Step12 - Static Friction with Quasi-Static Dirichlet Boundary Conditions
The step12.cfg file describes a problem that is similar to examples step10 and step11, except that we apply velocity
boundary conditions and run the simulation for 200 years. Once fault friction is overcome, the fault slips at a steady rate. To
prevent convergence problems we set the time step size to a constant value of 5 years:
# Change the total simulation time to 200 years, and use a constant time
# step size of 5 years.
dt = 5.0*year
As in the other fault friction examples, we apply initial displacements along the x-axis (to maintain a compressive stress on the
fault), and we apply velocity boundary conditions that yield a left-lateral sense of motion:
# Boundary condition on +x face -- Dirichlet
bc_dof = [0,1]
label = face_xpos
db_initial.data = [-1.0*m, 0.0*m]
Figure 7.33: Magnitude of tractions on the fault for example step10 visualized using ParaView. Vectors of fault slip are also
plotted. Note that PyLith outputs slip in the fault coordinate system, so we transform them to the global coordinate system
using the Calculator in ParaView. A more general approach involves outputing the fault coordinate system information and
using these fields in the Calculator.

db_rate.data = [0.0*cm/year, 1.0*cm/year, 0.0*year] \\

bc_dof = [0, 1]
label = face_xneg
db_rate.label = Dirichlet rate BC on -x
For this example, we keep the same coefficient of friction as examples step10 and step11, but we include a cohesion of 2
MPa:
# Set static friction model parameters using a uniform DB. Set the
# static coefficient of friction to 0.6 and cohesion to 2.0 MPa.
friction.db_properties.label = Static friction
friction.db_properties.values = [friction-coefficient, cohesion]
friction.db_properties.data = [0.6, 2.0*MPa]
7.8.7.5 Step13 - Slip-Weakening Friction with Quasi-Static Dirichlet Boundary Conditions
In this example we replace the static friction fault constitutive model in step12 with a slip-weakening friction fault constitutive
model. Fault friction is overcome at about t = 80 years, the fault slips in each subsequent time step. We again use a constant
time step size of 5 years and apply the same intial displacement and velocity boundary conditions.
We first define the friction model for the simulation:
# Use the slip-weakening friction model.
friction = pylith.friction.SlipWeakening
# Set slip-weakening friction model parameters using a uniform DB. Set the
# parameters as follows:
# static coefficient of friction: 0.6
# dynamic coefficient of friction: 0.5
# slip-weakening parameter: 0.2 m
# cohesion: 0 Pa
friction.db_properties.label = Slip weakening
friction.db_properties.values = [static-coefficient,dynamic-coefficient, \
slip-weakening-parameter,cohesion]
friction.db_properties.data = [0.6,0.5,0.2{*}m,0.0{*}Pa]
7.8.7.6 Step14 - Rate-and-State Friction with Quasi-Static Dirichlet Boundary Conditions
In step14 we use a rate-and-state friction model with an ageing law instead of a slip-weakening friction model. Slip begins to
occur at about t = 45 years, and continues in each subsequent time step. We again use a constant time step size of 5 years and
apply the same intial displacement and velocity boundary conditions.
We first define the friction model for the simulation:
# Use the rate-and-state aging friction model.
friction = pylith.friction.RateStateAgeing
# Set rate-and-state parameters using a UniformDB. Set the parameters as
# follows:
# reference coefficient of friction: 0.6
# reference slip rate: 1.0e-06 m/s
# slip-weakening parameter: 0.037 m
# a: 0.0125
# b: 0.0172
# cohesion: 0 Pa
friction.db_properties.label = Rate State Ageing
friction.db_properties.values = [reference-friction-coefficient, reference-slip-rate, \
characteristic-slip-distance, constitutive-parameter-a, constitutive-parameter-b, cohesion]
friction.db_properties.data = [0.6, 1.0e-6*m/s, 0.0370*m, 0.0125, 0.0172, 0.0*Pa]
For this model, we also want to set the initial value of the state variable:
# Set spatial database for the initial value of the state variable.
friction.db_initial_state = spatialdata.spatialdb.UniformDB
friction.db_initial_state.label = Rate State Ageing State
friction.db_initial_state.values = [state-variable]
friction.db_initial_state.data = [92.7*s]
7.8.8 Gravitational Body Force Examples
• Gravitational body forces

• Finite strain
• Generalized Maxwell linear viscoelastic material
7.8.8.1 Overview
This set of examples describes a set of problems for PyLith involving gravitational body forces. All of the examples are
quasi-static and run for a time period of 200 years. These examples also demonstrate the use of a generalized Maxwell vis-
coelastic material, which is used for the lower crust in all examples. The final example (step17) demonstrates the usage of
a finite strain formulation, which automatically invokes the nonlinear solver. All of the examples are contained in the direc-
tory examples/3d/hex8, and the corresponding .cfg files are step15.cfg, step16.cfg, and step17.cfg. Each
example may be run as follows:
7.8.8.2 Step15 - Gravitational Body Forces
The step15.cfg file defines a problem with extremely simple Dirichlet boundary conditions. On the positive and negative
x-faces, the positive and negative y-faces, and the negative z-face, the displacements normal to the face are set to zero. Because
all of the materials in the example have the same density, the elastic solution for loading via gravitational body forces is
νρg h
σzz = ρg h; σxx = σ y y = . (7.1)
1−ν
We set the gravity field, which by default has values of 9.80655 m/s2 for acceleration and [0, 0, −1] for direction and time
stepping implementation:
gravity_field = spatialdata.spatialdb.GravityField ; Set gravity field
# Change time stepping algorithm from uniform time step, to adaptive
# time stepping.
time_step = pylith.problems.TimeStepAdapt
max_dt = 10.0*year
Figure 7.37: Displacement field for example step15 at t = 200 years visualized using ParaView. The z-component of the
displacement field is shown with the color contours, and the vectors show the computed displacements.
We use a generalized Maxwell model for the lower crust (see Section 5.3.3 on page 68), and use a SimpleDB to provide
the properties. We also request the relevant properties and state variables for output:
# Change material type of lower crust to generalized Maxwell viscoelastic.
materials.lower_crust = pylith.materials.GenMaxwellIsotropic3D
# generalized Maxwell model, we explicitly request that they be output.
# Properties are named in cell\_info\_fields and state variables are named in
# cell\_data\_fields.
db_properties.iohandler.filename = spatialdb/mat\_genmaxwell.spatialdb
output.cell_info_fields = [density, mu, lambda, shear_ratio, maxwell_time]
output.cell_data_fields = [total_strain, stress, viscous_strain_1, viscous_strain_2, \\
viscous_strain_3]
The boundary conditions for this example are trivial, so we are able to use the default ZeroDispDB for all faces. When we have
run the simulation, the output VTK files will be contained in examples/3d/hex8/output (all with a prefix of step15).
Results using ParaView are shown in Figure 7.37.
7.8.8.3 Step16 - Gravitational Body Forces with Initial Stresses
The step16.cfg file defines a problem that is identical to example step15, except that initial stresses are used to prevent the
initial large displacements due to ’turning on’ gravity. Since all normal stress components are given an initial stress of ρg h , the
initial stress state is lithostatic, which is an appropriate condition for many tectonic problems in the absence of tectonic stresses
(e.g., McGarr [McGarr, 1988]). When compared to example step15, this example should maintain a lithostatic state of stress
for the entire simulation, and displacements should remain essentially zero.
We set the gravity field, as in example step15, and we again use adaptive time stepping with a generalized Maxwell rheology
for the lower crust. We provide values for the initial stress for both the upper and lower crust. Since the materials have the same
density, we are able to use the same SimpleDB with a linear variation for both (see file examples/3d/hex8/spatialdb/initial_st
# We must specify initial stresses for each material.
# We provide a filename for the spatial database that gives the stresses,
# and we change the query_type from the default ’nearest’ to ’linear’.
[pylithapp.timedependent.materials.upper_crust]
Figure 7.38: Stress field (xx-component) for example step16 at t = 200 years visualized using ParaView. Note that for this
example, Stress_xx = Stress_yy = Stress_zz, and there is no vertical displacement throughout the simulation. Also note that the
stresses appear as four layers since we have used CellFilterAvg for material output.
db_initial_stress.iohandler.filename = spatialdb/initial_stress.spatialdb
db_initial_stress.query_type = linear
db_initial_stress.iohandler.filename = spatialdb/initial_stress.spatialdb
db_initial_stress.query_type = linear
Note that we use a linear query_type rather than the default type of nearest, so that a linear interpolation is performed
along the z-direction. When we have run the simulation, the output VTK files will be contained in examples/3d/hex8/output
(all with a prefix of step16). Results using ParaView are shown in Figure 7.38.
7.8.8.4 Step17 - Gravitational Body Forces with Small Strain
The step17.cfg file defines a problem that is identical to example step15, except that we now use a small strain formulation
(see Section 2.5 on page 14). All of the problems up to this point have assumed infinitesimal strain, meaning that the change
in shape of the domain during deformation is not taken into account. In many problems it is important to consider the change
in shape of the domain. This is particularly important in many problems involving gravitational body forces, since a change
in shape of the domain results in a different stress field. By examining the stress and deformation fields for this example in
comparison with those of example step15, we can see what effect the infinitesimal strain approximation has on our solution.
We set the gravity field, as in example step15 and again use adaptive time stepping withs a generalized Maxwell rheology
for the lower crust. The only change is that we change the problem formulation from the default Implicit to ImplicitLgDeform.
Since the large deformation formulation is nonlinear, PyLith automatically switches the solver from the default SolverLinear
to SolverNonlinear. It is thus only necessary to change the formulation:
# Set the formulation for finite strain. The default solver will
# automatically be switched to the nonlinear solver.
formulation = pylith.problems.ImplicitLgDeform
Figure 7.39: Displacement field for example step17 at t = 200 years visualized using ParaView. The z-component of the
displacement field is shown with the color contours, and the vectors show the computed displacements. Note the larger dis-
placements compared with example step15.
7.8.9 Surface Load Traction Examples
• Time-dependent Neumann (traction) boundary conditions

• Elastic material
• Output of solution at user-defined locations
7.8.9.1 Overview
This set of examples describes a set of problems for PyLith involving surface loading with a Neumann (traction) applied to
the ground surface. The first example demonstrates the use of a surface load in a static problem, and the second example
demonstates how to apply a cyclic load in a quasi-static problem. The second problem also includes output of the solution at
user-defined locations. All of the examples are contained in the directory examples/3d/hex8, and the corresponding .cfg
files are step18.cfg and step19.cfg. Each example may be run as follows:
7.8.9.2 Step18 - Static Surface Load
The step18.cfg file defines a problem with a spatially varying axial surface load applied to the top surface with Dirichlet
(roller) boundary conditions on the lateral and bottom surfaces. We first set the array of boundary conditions with one for each
surface of the domain. As in the other examples, we also setup output for the ground surface.
For the Dirichlet boundary conditions we fix the degree of freedom associated with motion normal to the boundary while
leaving the other degrees of freedom free. We do not explicitly specify the use of a Dirichlet boundary condition because it is
the default. Similarly, the ZeroDispDB is the default spatial database for the displacements in a Dirichlet boundary condition,
so all we need to specify is the degree of freedom that is constrained, the name of the nodeset from CUBIT, and a label used in
diagnostic output. For the Dirichlet boundary condition on the +x surface we have:
label = face_xpos
bc_dof = [0]
On the top surface we apply a Neumann boundary condition for the surface load, so we first set the boundary condition type
and then specify the nodeset in CUBIT associated with this surface. For the static surface load, we use a spatial database for
the initial value and linear interpolation. We integrate the surface tractions over the boundary, so we also specify the numerical
integration scheme to use. Finally, we specify a vector for the up direction because the tractions are applied to a horizontal
surface, resulting in ambiguous shear directions for our default orientation convention.
z_pos = pylith.bc.Neumann
[pylithapp.timedependent.bc.z_pos]
label = face_zpos
db_initial.label = Neumann BC on +z
db_initial.iohandler.filename = spatialdb/tractions\_axial\_pressure.spatialdb
db_initial.query_type = linear ; Use linear interpolation.
# Diagnostic output
output.cell_info_fields = [initial-value]
output.writer.filename = output/step18-traction.vtk
output.cell_filter = pylith.meshio.CellFilterAvg
# We must specify quadrature information for the cell faces.

quadrature.cell.quad_order = 2 \\
# Because normal for +z surface is {[}0,0,1{]}, the horizontal and

# vertical shear directions are ambiguous. We provide a ‘‘fake’’ up
# direction of [0,1,0] so that the horizontal shear direction (cross
# product of ‘‘up’’ and normal is [1,0,0] and the vertical shear
# direction (cross product of normal and horizontal) is [0,1,0].
up_dir = [0,1,0]
of step18). Results using ParaView are shown in Figure 7.40 on the facing page.
7.8.9.3 Step19 - Time-Dependent Surface Load
The step19.cfg file defines a problem that is identical to example step18, except that we vary the amplitude of the surface
load as a function of time. We use a temporal database (analogous to our spatial databases for specifying spatial variations)
to prescribe a piecewise linear variation of the amplitude with time as given in the file spatialdb/loadcycle.timedb.
The amplitude begins at zero, progresses to 1.0, then 1.5, before decreasing in a symmetric fashion. The temporal database can
use variable time steps to prescribe arbitrary time histories.
Rather than specify a spatial database for the initial value of the Neumann boundary condition corresponding to the surface
load, we specify a spatial database for the change in value and the temporal database:
[pylithapp.timedependent.bc.z_pos]
label = face_zpos
db_change = spatialdata.spatialdb.SimpleDB
Figure 7.40: Displacement field for example step18 visualized using ParaView. The vectors show the displacement field while
the colors in the wireframe correspond to the z-component of the displacement field.
db_change.label = Amplitude of Neumann BC on +z

db_change.iohandler.filename = spatialdb/tractions_axial_pressure.spatialdb
db_change.query_type = linear ; Use linear interpolation
th_change = spatialdata.spatialdb.TimeHistory
th_change.label = Time history for Neumann BC on +z
th_change.filename = spatialdb/loadcycle.timedb
of step19). Results using ParaView are shown in Figure 7.41 on the next page. We also output the solution at user-defined
locations, which are given in the file output_points.txt. See Section 4.7.2 on page 46 for a discussion of the output
parameters. This type of output is designed for comparison against observations and inversions and output via HDF5 files (see
Section 4.7.5 on page 47).
7.8.10 Dike Intrusion Example
• Fault opening via prescribed tractions to mimic a dike instrusion

• VTK output
7.8.10.1 Overview
This set of examples describes a problem where prescribed tensile tractions are imposed on a fault to mimic a dike intrusion.
The example is contained in the directory examples/3d/hex8, and the corresponding .cfg file is step20.cfg. The
example may be run as follows:
Figure 7.41: Stress field (zz-component) for example step19 at t = 200 years visualized using ParaView. The stresses appear as
four layers since we have used CellFilterAvg for material output.
additional parameters in the step20.cfg file. The .cfg file is extensively documented, to provide detailed information on
7.8.10.2 Step20 - Static Dike Intrusion
The step20.cfg file defines a problem with spatially varying tensile normal tractions on the fault surface associated with
a fluid intrusion. The lateral sides and bottom of the domain are fixed using Dirichlet (roller) boundary conditions. As in the
other examples, we also setup output for the ground surface.
We use the FaultCohesiveDyn object to impose tractions on the fault surface. We must include a fault constitutive model
so we choose static friction with a coefficient of friction of 0.1. The coefficient of friction is irrelevant for the center of the fault
where we impose uniform tensile tractions (10 MPa) and the fault opens, but it facilitates clamping the edges of the fault via
compressive normal tractions (-100 MPa). Note that we must set the property open_free_surface to False in order for
the tractions to be imposed when the fault is open; the default behavior for fault opening is a free surface (the two sides of the
fault are completely uncoupled). The most important fault parameters for prescribing the tensile fault tractions are
open_free_surface = False
traction_perturbation = pylith.faults.TractPerturbation
[pylithapp.timedependent.interfaces.fault.traction_perturbation]
db_initial.label = Initial fault tractions
db_initial.iohandler.filename = spatialdb/tractions_opening.spatialdb
db_initial.query_type = nearest
of step20). Results using ParaView are shown in Figure 7.42 on the facing page.
7.8.11 Green’s Functions Generation Example

Figure 7.42: Displacement magnitude for example step20 visualized using ParaView.
• Generation of Green’s functions from a fault

• Kinematic fault impulses
• Running a different problem type
• HDF5 output
• Interpolated point output
7.8.11.1 Overview
This example describes a problem where we generate a set of Green’s functions that could be used in an inversion. The example
is contained in the directory examples/3d/hex8, and the corresponding .cfg file is step21.cfg. The example may be
run as follows:
$$ pylith step21.cfg --problem=pylith.problems.GreensFns
This will cause PyLith to read the default parameters in pylithapp.cfg and greensfns.cfg, and then override or
augment them with the additional parameters in the step21.cfg file. The .cfg files are extensively documented, to provide
detailed information on the various parameters.
7.8.11.2 Step21 - Green’s Function Generation
This problem makes use of two .cfg files that are read by default – pylithapp.cfg and greensfns.cfg. The
greensfns.cfg file is read automatically because we have changed the problem type to GreensFns (as opposed to the
default TimeDependent problem type). The facility name then becomes greensfns, and PyLith will therefore search for a
.cfg file matching the name of the facility. The greensfns.cfg file contains settings that are specific to the GreensFns
problem type:
[greensfns]
fault_id = 10
[greensfns.interfaces]
fault = pylith.faults.FaultCohesiveImpulses
[greensfns.interfaces.fault]
impulse_dof = [0, 1]
db_impulse_amplitude.label = Amplitude of slip impulses

db_impulse_amplitude.iohandler.filename = spatialdb/impulse_amplitude.spatialdb
db_impulse_amplitude.query_type = nearest
We specify the fault_id, which is required by the GreensFns problem type (it is the same as the ID used when generating
the mesh). We also change the fault type to FaultCohesiveImpulses, which allows us to apply a single impulse of slip for each
impulse with a nonzero slip value in the corresponding spatial database file (spatialdb/impulse_amplitude.spatialdb).
We indicate that we would like to apply slip impulses in both the left-lateral (impulse_dof = 0) and updip (impulse_dof =
1) directions, and we use nearest-neighbor interpolation to determine the amount of applied slip. Note that in the spatialdb/impulse_am
file we specify negative slip, thus reversing the sense of applied slip for both slip directions. Note that we also put a margin of
zeros around the edge of the fault, which prevents impulses from being applied along this boundary.
The step21.cfg file defines the remainder of the parameters for this problem. The boundary conditions and fault
information are provided as for previous examples. Rather than computing the solution over the ground surface, we choose to
provide output at a set of points. PyLith provides the ability to interpolate displacements to a specified set of points, which
would generally be necessary when generating Green’s functions:
output = [domain, points]
output.points = pylith.meshio.OutputSolnPoints
[pylithapp.problem.formulation.output.points]
writer.filename = output/step21-points.h5
reader.filename = greensfns_points.txt
coordsys.units = m
We first define OutputSolnPoints as the output manager for points output. We use HDF5 output for all of the Green’s function
output, as it will generally be more efficient (faster I/O, smaller file sizes). We must provide a set of points for point output.
The file greensfns_points.txt contains a set of (x,y,z) coordinates. We must also provide the spatial dimension of the
coordinates as well as the units used. Note that we do not output any info or data fields for state variable output, as this would
otherwise create a large amount of output for each applied slip impulse. When we have run the simulation, the output HDF5
files will be contained in examples/3d/hex8/output (all with a prefix of step21). In Figure 7.43 on the next page
we show an impulse of left-lateral slip applied on the fault and the resulting response at the specified set of points. The time
corresponds to the impulse number in multiples of the specified time step size.
7.9 Example for Slip on a Subduction Zone

• Static solution
• CUBIT mesh generation
• Nonplanar geometry
• Variable mesh resolution
• APREPRO programming language
• HDF5 output
7.9. EXAMPLE FOR SLIP ON A SUBDUCTION ZONE 169
Figure 7.43: A slip impulse and the resulting point displacement responses visualized using ParaView.

• Multiple materials
• Plane Maxwell linear viscoelastic material
• Prescribed slip
• Multiple faults
• Spatially variable coseismic slip
• Spatially variable aseismic creep
• Afterslip via fault friction
• Static friction
All of the files necessary to run the examples are contained in the directory examples/2d/subduction.
7.9.1 Overview
This example examines quasi-static interseismic and coseismic deformation in 2D for a subduction zone (see Figure 7.44 on
the following page). It is based on the 2011 M9.0 Tohoku earthquake off the east coast of Japan. Figure 7.45 on the next
page shows the three steps of increasing complexity. Step 1 focuses on the coseismic slip, Step 2 focuses on interseismic
deformation, and Step 3 combines the two into a pseudo-earthquake cycle deformation simulation. Step 4 focuses on using the
change in tractions from Step 1 to construct a simulation with afterslip controlled by frictional sliding.
We construct the mesh in CUBIT by constructing the geometry, prescribing the discretization, running the mesher, and then
grouping cells and vertices for boundary conditions and materials. We use the APREPRO programming language within the
journal files to enable use of units and to set variables for values used many times. An appendix in the CUBIT documentation
discusses the features available with APREPRO in CUBIT. The CUBIT commands are in three separate journal files. The
main driver is in the journal file mesh_tri3.jou. It calls the journal file geometry.jou to construct the geometry and
Continental crust Oceanic crust
Mantle
Figure 7.44: Cartoon of subduction zone example.
Step 1 Step 2 Step 3

Earthquake Earthquake @ t=150 yrs
Steady aseismic creep
Figure 7.45: Diagram of fault slip and boundary conditions for each step in the subduction zone example.
createbc.jou to set up the groups associated with boundary conditions and materials. The journal files are documented
and describe the various steps outlined below.
1. Create the geometry defining the domain.

(a) Create points.
(b) Connect points into spline curves.
(c) Split curves to separate them into sections bounding surfaces.
(d) Connect curves into surfaces.
(e) Stitch surfaces together.
2. Define meshing scheme and cell size variation.
(a) Define cell size along curves near fault.
(b) Increase cell size away from fault at a geometric rate (bias).
3. Generate mesh.
4. Create blocks for materials and nodesets for boundary conditions.
5. Export mesh.
7.9.3 Common Information
As in the examples discussed in previous sections of these examples, we place parameters common to the three steps in the
pylithapp.cfg file so that we do not have to duplicate them for each step. The settings contained in pylithapp.cfg
for this problem consist of:
pylithapp.journal.info Settings that control the verbosity of the output written to stdout for the different components.
Figure 7.46: Variable resolution finite-element mesh with triangular cells. The nominal cell size increases at a geometric rate
of 1.2 away from the region of coseismic slip.
pylithapp.timedependent Settings that control the problem, such as the total time, time-step size, and spatial dimen-
sion.
associated with a particular material type, and give the name of the spatial database containing the physical
properties for the material. The quadrature information is also given.
pylithapp.problem.formulation.output Settings related output of the solution over the domain and subdomain
(ground surface).
pylithapp.timedependent.materials.MATERIAL.output Settings related to output of the state variables for
material MATERIAL.
The physical properties for each material are specified in spatial database files. For example, the elastic properties for the
continental crust are in mat_concrust.spatialdb. The provided spatial database files all use just a single point to
specify uniform physical properties within each material. A good exercise is to alter the spatial database files with the physical
properties to match PREM.
7.9.4 Step 1: Coseismic Slip Simulation
The first example problem is earthquake rupture involving coseismic slip along the interface between the subducting slab and
the continental crust and uppermost portion of the mantle below the continental crust. The spatial variation of slip comes
from a cross-section of Gavin Hayes’ finite-source model earthquake.usgs.gov/earthquakes/eqinthenews/
2011/usc0001xgp/finite_fault.php. On the lateral and bottom boundaries of the domain, we fix the degrees of
freedom perpendicular to the boundary as shown in Figure 7.45 on the facing page. Parameter settings that augment those in
pylithapp.cfg are contained in the file step01.cfg. These settings are:
pylithapp.timedependent.formulation.time_step Adjust the total simulation time to 0 years (static simula-
tion).
pylithapp.timedependent Specifies the array of boundary conditions.
pylithapp.timedependent.bc.BOUNDARY Defines the settings for boundary BOUNDARY, including which degrees
of freedom are being constrained (x or y), the label (defined in mesh_tri3.exo) corresponding to the
nodeset in CUBIT, and a label to the boundary condition used in any error messages.
pylithapp.timedependent.interfaces.fault Specify the coseismic slip along the interface between the oceanic
crust and continental crust with a small amount of slip penetrating into the upper mantle.
pylithapp.problem.formulation.output.domain Gives the base filenames for HDF5 output (for example, step01.h5).
We run this example by typing
The problem will produce twelve pairs of HDF5/Xdmf files. The HDF5 files contain the data and the Xdmf files contain the
metadata required by ParaView and Visit (and possibly other visualization tools that use Xdmf files) to access the mesh and
data sets in the HDF5 files. The files include the solution over the domain and ground surface (two pairs of files), physical
Figure 7.47: Solution for Step 1. The colors indicate the magnitude of the displacement, and the deformation is exaggerated by
a factor of 1000.
properties, stress, and strain within each material (eight pairs of files), and fault parameters, slip, and traction (two pairs of
files).
Figure 7.47, which was created using ParaView, displays the magnitude of the displacement field with the deformation
exaggerated by a factor of 1000.
7.9.5 Step 2: Interseismic Deformation Simulation
In this example we simulate the interseismic deformation associated with the oceanic crust subducting beneath the continental
crust and into the mantle. We prescribe steady aseismic slip of 8 cm/yr along the interfaces between the oceanic crust and
mantle with the interface between the oceanic crust and continental crust locked as shown in Figure 7.45 on page 170. We
adjust the Dirichlet boundary conditions on the lateral edges and bottom of the domain by pinning only the portions of the
boundaries in the mantle and continental crust (i.e., not part of the oceanic crust). Parameter settings that augment those in
pylithapp.cfg are contained in the file step02.cfg. These settings include:
pylithapp.timedependent.formulation.time_step Adjust the total simulation time to 100 years.
pylithapp.timedependent.interfaces Specify the steady aseismic slip as a constant slip rate on the fault surfaces.
pylithapp.problem.formulation.output.domain Gives the base filename for HDF5 output (for example, step02.h5).
The simulation will produce pairs of HDF5/Xdmf files with separate files for each material and fault interface. Figure 7.48
on the next page, which was created using ParaView, displays the magnitude of the displacement field with the deformation
exaggerated by a factor of 1000. Using the animation features within ParaView or Visit you can illustrate how the continental
crust near the trench subsides during the interseismic deformation.
7.9.6 Step 3: Pseudo-Earthquake Cycle Model
This simulation combines 300 years of interseismic deformation from Step 2 with the coseismic deformation from Step 1 ap-
plied at 150 years to create a simple model of the earthquake cycle. Parameter settings that augment those in pylithapp.cfg
are contained in the file step03.cfg. These settings include:
pylithapp.timedependent.formulation.time_step Adjust the total simulation time to 300 years.
pylithapp.timedependent.bc.BOUNDARY The Dirichlet boundary conditions match those in Step 2.
Figure 7.48: Solution for Step 2 at 100 years. The colors indicate the magnitude of the displacement, and the deformation is
Figure 7.49: Solution for Step 3 at 150 years (immediately following the earthquake rupture). The colors indicate the magnitude
of the displacement, and the deformation is exaggerated by a factor of 1000.
pylithapp.timedependent.interfaces On the interface between the subducting oceanic crust and the mantle, we
prescribe the same steady, aseismic slip as that in Step 2. On the interface along the top of the subducting
oceanic crust and the continental crust and mantle we create two earthquake ruptures, The first rupture
applies the coseismic slip form Step 1 at 150 years, while the second rupture prescribes the same steady,
aseismic slip as in Step 2.
pylithapp.problem.formulation.output.domain Gives the base filename for HDF5 output (for example, step03.h5).
The simulation will produce pairs of HDF5/Xdmf files with separate files for each material and fault interface. Figure 7.49,
which was created using ParaView, displays the magnitude of the displacement field with the deformation exaggerated by a
factor of 1000. Using the animation features within ParaView or Visit you can illustrate how the continental crust near the
trench rebounds during the earthquake after subsiding during the interseismic deformation.
7.9.7 Step 4: Frictional Afterslip Simulation
This simulation demonstrates how to combine the change in tractions associated with coseismic slip with a background stress
field to compute afterslip controlled by static friction. The Python script afterslip_tractions.py will create a spatial
database file with initial tractions based on the change in tractions from Step 1 and a background stress field. The background
stress field is simply normal tractions consistent with the overburden (lithostatic load) for a uniform half-space and shear
tractions consistent with a coefficient of friction of 0.6. The afterslip_tractions. spatialdb file is provided, so you do
not need to run the Python script afterslip_tractions.py; however, you can do so by typing
$$ python afterslip_tractions.py
We provide 2.0 MPa of strength excess associated with the background stress field by using a cohesion of 2.0 MPa in the static
friction model. Slip will occur in regions where the coseismic slip increased the shear tractions by more than 2.0 MPa. On
the lateral and bottom boundaries of the domain, we fix the degrees of freedom perpendicular to the boundary as shown in
Figure 7.50: Solution for Step 4. The colors indicate the magnitude of the displacement.
Figure 7.45 on page 170. Parameter settings that augment those in pylithapp.cfg are contained in the file step04.cfg.
These settings are:
pylithapp.timedependent.formulation.time_step Adjust the total simulation time to 0 years (static simula-
tion).
pylithapp.timedependent Selects the nonlinear solver and specifies the array of boundary conditions.
pylithapp.timedependent.interfaces.fault Specify a fault with a fault constitutive model (static friction) and
initial fault tractions.
pylithapp.problem.formulation.output.domain Gives the base filenames for HDF5 output (for example, step04.h5).
The problem will produce twelve pairs of HDF5/Xdmf files. The HDF5 files contain the data and the Xdmf files contain the
metadata required by ParaView and Visit (and possibly other visualization tools that use Xdmf files) to access the mesh and
data sets in the HDF5 files. The files include the solution over the domain and ground surface (two pairs of files), physical
properties, stress, and strain within each material (eight pairs of files), and fault parameters, slip, and traction (two pairs of
files).
Figure 7.50, which was created using ParaView, displays the magnitude of the displacement field with the original config-
uration. Slip occurs down-dip from the coseismic slip as well as in three areas with sharp gradients in slip, including the trench.
The location of the afterslip can be shifted by changing the spatial variation of the coseismic slip and background stress field.
7.9.8 Suggested Variations
The list below includes some suggested modifications to the problem that will allow you to become more familiar with PyLith
while examining some interesting physics.
• Change the resolution of the mesh by editing the mesh_tri3.jou journal file. Change the resolution and bias factor.
• Add depth dependent viscosity to the mantle and crust. This requires using the linear Maxwell plane strain bulk consti-
tutive model in the crust as well and creating spatial databases that include viscosity for the crust. Specifying a depth
dependent variation in the parameters will require adding points, updating num-locs accordingly, and changing data-dim
to 1.
• Modify the spatial database files for the material properties to use depth-dependent elastic properties based on PREM
(Dziewonski and Anderson, 1981, 10.1016/0031-9201(81)90046-7). See geophysics.ou.edu/solid_earth/
prem.html for a simple table of values. Add points, update num-locs accordingly, and change data-dim to 1.
• Modify the CUBIT journal files to use quad4 cells rather than tri3 cells. This requires using the pave mesh scheme.
• Create a simulation with multiple earthquake cycles by lengthening the duration of the simulation and adding additional
earthquake ruptures. See examples/3d/hex8/step06.cfg for an example with multiple earthquake ruptures.
7.10. SHEAR WAVE IN A BAR 175
Shear waves
Absorbing boundaries Fault

Figure 7.51: Domain for shear wave propagation in a 8.0 km bar with 400 m cross-section. We generate a shear wave via slip
on a fault located in the middle of the bar while limiting deformation to the transverse direction.
Examine spinup towards a steady-state solution.
7.10 Shear Wave in a Bar

This suite of examples focuses on the dynamics of a shear wave propagating down an 8 km-long bar with a 400 m-wide cross-
section. Motion is limited to shear deformation by fixing the longitudinal degree of freedom. For each cell type (tri3, quad4,
tet4, and hex8) we generate a shear wave using a kinematic fault rupture with simultaneous slip over the fault surface, which
we place at the center of the bar. The discretization size is 200 m in all cases. The slip-time histories follow the integral of
Brune’s far-field time function with slip initiating at 0.1 s, a left-lateral final slip of 1.0 m, and a rise time of 2.0 s. The shear
wave speed in the bar is 1.0 km/s, so the shear wave reaches each end of the bar at 4.1 s. Absorbing boundaries on the ends of
the bar prevent significant reflections. The bar comes to a rest with a static offset.
For the bar discretized with quad4 cells we also consider the fault subjected to frictional sliding controlled by static friction,
linear slip-weakening friction, and rate- and state-friction. We use initial tractions applied to the fault to drive the dislocation
and generate the shear wave. Because the fault tractions are constant in time, they continue to drive the motion even after the
shear wave reaches the absorbing boundary, leading to a steady state solution with uniform shear deformation in the bar and a
constant slip rate on the fault.
7.11 2D Bar Discretized with Triangles

• Dynamic solution
• CUBIT format
• Absorbing dampers boundary conditions
• VTK output
All of the files necessary to run the examples are contained in the directory examples/bar_shearwave/tri3.
7.11.1 Mesh Generation
The mesh is a simple rectangle 8 km by 400 m (Figure 7.59 on page 182). This mesh could be generated via a simple script, but it
is even easier to generate this mesh using CUBIT. We provide documented journal files in examples/bar_shearwave/tri3.
We first create the geometry, mesh the domain using triangular cells, and then create blocks and nodesets to associate the cells
Figure 7.52: Mesh composed of triangular cells generated by CUBIT used for the example problem.
and vertices with materials and boundary conditions. See Section 7.8 on page 136 for more information on using CUBIT to
generate meshes.
7.11.2 Simulation Parameters
All of the parameters are set in the pylithapp.cfg file. The structure of the file follows the same pattern as in all of the
other examples. We set the parameters for the journal information followed by the mesh reader, problem, materials, boundary
conditions, fault, and output. We change the time-stepping formulation from the default value of implicit time stepping to
explicit time stepping with a lumped Jacobian matrix by setting the formulation object via
formulation = pylith.problems.Explicit
Using the Explicit object automatically triggers lumping of the Jacobian cell matrices and assembly into a vector rather than
a sparse matrix. Lumping the Jacobian decouples the equations, so we can use a very simple direct solver. Use of this simple
solver is also triggered by the selection of any of the Explicit formulation objects.
For dynamic problems we use the NondimElasticDynamic object to nondimensionalize the equations. This object provides
scales associated with wave propagation for nondimensionalization, including the minimum wave period, the shear wave speed,
and mass density. In this example we use the default values of a minimum wave period of 1.0 s, a shear wave speed of 3 km/s,
and a mass density of 3000 kg/m3 . We simulate 12.0 s of motion with a time step of 1/30 s. This time step must follow the
Courant-Friedrichs-Lewy condition; that is, the time step must be smaller than the time it takes the P wave to propagate across
the shortest edge of a cell.
The boundary conditions include the absorbing dampers at the ends of the bar and a Dirichlet boundary condition to prevent
longitudinal motion. Because we cannot overlap the Dirichlet BC with the fault, we use the nodeset associated with all vertices
except the fault. For the output over the entire domain, we request both displacement and velocity fields:
[pylithapp.timedependent.output]
To run the problem, simply run PyLith without any command line arguments:
$$ pylith
The VTK files will be written to the output directory. The output includes the displacement and velocity fields over the entire
domain at every 3rd time step (0.10 s), the slip and change in traction vectors on the fault surface in along-strike and normal
directions at every 3rd time step (0.10 s), and the strain and stress tensors for each cell at every 30th time step (1.0 s). If the
problem ran correctly, you should be able to generate a figure such as Figure 7.53 on the next page, which was generated using
ParaView.
7.12. 3D BAR DISCRETIZED WITH QUADRILATERALS 177
Figure 7.53: Displacement field in the bar at 3.0 s. Deformation has been exaggerated by a factor of 800.
7.12 3D Bar Discretized with Quadrilaterals

• CUBIT mesh format
• Dynamic fault interface conditions
• VTK output
• Linear quadrilateral cells
All of the files necessary to run the examples are contained in the directory examples/bar_shearwave/quad4.
The mesh is a simple rectangular prism 8 km by 400 m by 400 m (Figure 7.54 on the following page). We provide doc-
umented CUBIT journal files in examples/bar_shearwave/quad4. We first create the geometry, mesh the domain
using quadrilateral cells, and then create blocks and nodesets associated with the materials and boundary conditions.
7.12.2 Kinematic Fault (Prescribed Slip)
The simulation parameters match those in the tri3, tet4, and hex8 examples. Using four-point quadrature permits use of a
time step of 1/20 s, which is slightly larger than the time step of 1/30 s used in the tri3 and tet4 simulations. In contrast
to the tri3, tet4, and hex8 shear wave examples which only contained a single simulation in a directory, in this example we
consider several different simulations. Consequently, we separate the parameters into multiple .cfg files. The common
parameters are placed in pylithapp.cfg with the parameters specific to the kinematic fault (prescribed rupture) example in
prescribedrup.cfg. To run the problem, simply run PyLith via:
$$ pylith prescribedrup.cfg
Figure 7.54: Mesh composed of hexahedral cells generated by CUBIT used for the example problem.
The VTK files will be written to the output directory with the prefix prescribedrup. The output includes the displace-
ment field over the entire domain at every other time step (0.10 s), the slip and traction vectors on the fault surface in along-strike
and normal directions at every other time step (0.10 s), and the strain and stress tensors for each cell at every 20th time step
(1.0 s). If the problem ran correctly, you should be able to generate a figure such as Figure 7.55, which was generated using
ParaView.
7.12.3 Dynamic Fault (Spontaneous Rupture)
In this set of examples we replace the kinematic fault interface with the dynamic fault interface, resulting in fault slip controlled
by a fault-constitutive model. See Section 6.4.5.3 on page 101 for detailed information about the fault constitutive models
available in PyLith. Because this is a dynamic simulation we want the generated shear wave to continue to be absorbed at the
ends of the bar, so we drive the fault by imposing initial tractions directly on the fault surface rather than through deformation
within the bar. We impose initial tractions (75 MPa of right-lateral shear and 120 MPa of compression) plus a temporal variation
(smoothly increasing from 0 to 25 MPa of right-lateral shear) similar to what would be used in a 2-D or 3-D version. While
the magnitude of these stresses is reasonable for tectonic problems, they give rise to very large slip rates in this 1-D bar. The
temporal variation, as specified via the traction_change.timedb file, has the functional form:
2
³ ´
exp t(t(t−t n)
(
−2t n ) , 0 < t ≤ tn
f (t ) = (7.2)
1, t > tn
7.12. 3D BAR DISCRETIZED WITH QUADRILATERALS 179
Figure 7.56: Velocity field in the bar at 3.0 s for the static friction fault constitutive model. Deformation has been exaggerated
by a factor of 20.
where t n = 1.0 s. We request that the fault output include the initial traction value and the slip, slip rate, and traction fields:
[pylithapp.timedependent.interfaces.fault.output]
vertex_info_fields = [traction_initial_value]
vertex_data_fields = [slip, slip_rate, traction]
The steady-state solution for this problem is constant velocity and slip rate with uniform strain within the bar. A Python script,
analytical_soln.py, is included for computing values related to the steady-state solution.
7.12.3.1 Dynamic Fault with Static Friction
The parameters specific to this example involve the static friction fault constitutive model. We set the fault constitutive model
via
friction = pylith.friction.StaticFriction
and use a UniformDB to set the static friction parameters. We use a coefficient of friction of 0.6 and no cohesion (0 MPa). The
parameters specific to this example are in spontaneousrup_staticfriction.cfg, so we run the problem via:
$$ pylith spontaneousrup.cfg spontaneousrup_staticfriction.cfg
The VTK files will be written to the output directory with the prefix staticfriction. The output includes the displace-
ment and velocity fields over the entire domain at every other time step (0.10 s), the slip, slip rate, and traction vectors on the
fault surface in along-strike and normal directions at every other time step (0.10 s), and the strain and stress tensors for each
cell at every 20th time step (1.0 s). If the problem ran correctly, you should be able to generate a figure such as Figure 7.56,
which was generated using ParaView. The steady-state solution is a constant slip rate of 22.4 m/s, a shear traction of 72.0 MPa
on the fault surface, a uniform shear strain of 5.6e-3 in the bar with uniform, and constant velocities in the y-direction of +11.2
m/s and -11.2 m/s on the -x and +x sides of the fault, respectively.
7.12.3.2 Dynamic Fault with Slip-Weakening Friction
The parameters specific to this example are related to the use of the slip-weakening friction fault constitutive model (see
Section 6.4.5.3 on page 101). We set the fault constitutive model via
Figure 7.57: Velocity field in the bar at 3.0 s for the slip-weakening friction fault constitutive model. Deformation has been
friction = pylith.friction.SlipWeakening
and use a UniformDB to set the slip-weakening friction parameters. We use a static coefficient of friction of 0.6, a dynamic
coefficient of friction of 0.5, a slip-weakening parameter of 0.2 m, and no cohesion (0 MPa). The fault constitutive model is
associated with the fault, so we can append the fault constitutive model parameters to the vertex information fields:
vertex_info_fields = [strike_dir, normal_dir, initial_traction, static_coefficient, dynamic_coefficient,
The parameters specific to this example are in spontaneousrup_slipweakening.cfg, so we run the problem via:
$$ pylith spontaneousrup.cfg spontaneousrup_slipweakening.cfg
The VTK files will be written to the output directory with the prefix slipweakening. If the problem ran correctly, you
should be able to generate a figure such as Figure 7.57, which was generated using ParaView. The steady-state solution is a
constant slip rate of 32.0 m/s and shear traction of 60.0 MPa on the fault surface, a uniform shear strain of 8.0e-3 in the bar
with uniform, constant velocities in the y-direction of +16.0 m/s and -46.0 m/s on the -x and +x sides of the fault, respectively.
7.12.3.3 Dynamic Fault with Rate-State Friction
The parameters specific to this example are related to the use of the rate- and state-friction fault constitutive model (see Sec-
tion 6.4.5.3 on page 101). The evolution of the state variable uses the ageing law. We set the fault constitutive model and add
the state variable to the output via
friction = pylith.friction.RateStateAgeing
vertex_data_fields = [slip, slip_rate, traction, state_variable]
and use a UniformDB to set the rate-state friction parameters. We use a reference coefficient of friction of 0.6, reference slip
rate of 1.0e-6 m/s, characteristic slip distance of 0.02 m, coefficients a and b of 0.008 and 0.012, and no cohesion (0 MPa). We
set the initial value of the state variable so that the fault is in equilibrium for the initial tractions. The parameters specific to this
example are in spontaneousrup_ratestateageing.cfg, so we run the problem via:
7.13. 3D BAR DISCRETIZED WITH TETRAHEDRA 181
Figure 7.58: Velocity field in the bar at 3.0 s for the rate- and state-friction fault constitutive model. Deformation has been
$$ pylith spontaneousrup.cfg spontaneousrup_ratestateageing.cfg
The VTK files will be written to the output directory with the prefix ratestateageing. If the problem ran correctly,
you should be able to generate a figure such as Figure 7.58, which was generated using ParaView. The steady-state solution is
a constant slip rate of 30.0 m/s and shear traction of 63.7 MPa on the fault surface, a uniform shear strain of 7.25e-3 in the bar
with uniform, constant velocities in the y-direction of +15.0 m/s and -15.0 m/s on the -x and +x sides of the fault, respectively.
7.13 3D Bar Discretized with Tetrahedra

• LaGriT mesh format
• Elastic isotropic linearly elastic material
• VTK output
All of the files necessary to run the examples are contained in the directory examples/bar_shearwave/tet4.
The mesh is a simple rectangular prism 8 km by 400 m by 400m (Figure 7.59 on the following page). This mesh could be
generated via a simple script, but it is even easier to generate this mesh using LaGriT. We provide documented LaGriT files in
examples/bar_shearwave/tet4. We first create the geometry and regions, mesh the domain using tetrahedral cells,
and then create point sets associated with boundary conditions.
Figure 7.59: Mesh composed of tetrahedral cells generated by LaGriT used for the example problem.
The simulation parameters match those in the tri3 example with the exception of using the LaGriT mesh reader and switching
from a two-dimensional problem to a three-dimensional problem. In addition to fixing the longitudinal degree of freedom, we
also fix the out-of-plane transverse degree of freedom. Because the fault separates two material regions in LaGriT, we use two
materials in PyLith. All of the parameters are set in the pylithapp.cfg file. To run the problem, simply run PyLith without
any command line arguments:
$$ pylith
domain at every 3rd time step (0.10 s), the slip and change in traction vectors on the fault surface in along-strike and normal
directions at every 3rd time step (0.10 s), and the strain and stress tensors for each cell at every 30th time step (1.0 s). If the
problem ran correctly, you should be able to generate a figure such as Figure 7.60, which was generated using ParaView.
7.14 3D Bar Discretized with Hexahedra

• CUBIT mesh format
7.15. EXAMPLE GENERATING AND USING GREEN’S FUNCTIONS IN TWO DIMENSIONS 183
Figure 7.61: Mesh composed of hexahedral cells generated by CUBIT used for the example problem.

• Elastic isotropic linearly elastic material
• VTK output
• Linear hexahedral cells
All of the files necessary to run the examples are contained in the directory examples/bar_shearwave/hex8.
The mesh is a simple rectangular prism 8 km by 400 m by 400 m (Figure 7.61). This mesh could be generated via a
simple script, but it is even easier to generate this mesh using CUBIT. We provide documented CUBIT journal files in
examples/bar_shearwave/hex8. We first create the geometry, mesh the domain using hexahedral cells, and then
create blocks and nodesets associated with the materials and boundary conditions.
The simulation parameters match those in the tri3 and tet4 examples. As in the tet4 example, we fix both the longitudinal degree
of freedom and the out-of-plane transverse degree of freedom. Using eight-point quadrature permits use of a time step of 1/20
s, which is slightly larger than the time step of 1/30 s used in the tri3 and tet4 simulations. All of the parameters are set in the
pylithapp.cfg file. To run the problem, simply run PyLith without any command line arguments:
$$ pylith
domain at every other time step (0.10 s), the slip and change in traction vectors on the fault surface in along-strike and normal
directions at every other time step (0.10 s), and the strain and stress tensors for each cell at every 20th time step (1.0 s). If the
problem ran correctly, you should be able to generate a figure such as Figure 7.62 on the next page, which was generated using
ParaView.
7.15 Example Generating and Using Green’s Functions in Two Dimensions

• Green’s functions
• HDF5 output
• HDF5 point output
• Reading HDF5 output using h5py
• Simple inversion procedure
• Plotting results using matplotlib
• Cubit mesh generation
• Variable mesh resolution
• APREPRO programming language
• Static solution
All of the files necessary to run the examples are contained under the directory examples/2d/greensfns.
7.15.1 Overview
This example examines the steps necessary to generate Green’s functions using PyLith and how they may be used in a linear
inversion. For simplicity we discuss strike-slip and reverse faulting examples in the context of 2D simulations. In each example,
we first compute surface displacement at a set of points, and these computed displacements provide the “data” for our inversion.
Second, we compute a set of Green’s functions using the same fault geometries, and output the results at the same set of
points. Third, we perform a simple linear inversion. An important aspect for both the forward problem and the Green’s
function problem is that the computed solution is output at a set of user-specified points (not necessarily coincident with mesh
vertices), rather than over a mesh or sub-mesh as for other types of output. To do this, PyLith internally performs the necessary
interpolation. There is a README file in the top-level directory that explains how to perform each step in the two problems.
We use linear triangular cells for the meshes in each of the two problems. We construct the mesh in CUBIT following the
same techniques used in the 2D subduction zone example. The main driver is in the journal file mesh_tri3.jou. It calls
the journal file geometry.jou to construct the geometry. It then calls the journal file gradient.jou to set the variable
Figure 7.63: Mesh used for both forward and Green’s function computations for the strike-slip problem. Computed y-
displacements for the forward problem are shown with the color scale.
discretization sizes used in this mesh. Finally, the createbc.jou file is called to set up the groups associated with boundary
conditions and materials. The mesh used for the strike-slip example is shown in Figure 7.63 The journal files are documented
and describe the various steps outlined below.

2. Create fault surface by splitting domain across the given locations.
3. Define meshing scheme and cell size variation.
4. Define cell size along curves near fault.
5. Increase cell size away from fault at a geometric rate (bias).
6. Generate mesh.
8. Export mesh.
As in the examples discussed in previous sections of these examples, we place parameters common to the forward model and
Green’s function computation in the pylithapp.cfg file so that we do not have to duplicate them for the two procedures.
The settings contained in pylithapp.cfg for this problem consist of:
pylithapp.problem Settings that control the problem, such as the total time, time-step size, and spatial dimension.
pylithapp.problem.materials Settings that control the material type, specify which material IDs are to be associated
with a particular material type, and give the name of the spatial database containing the physical properties
for the material. The quadrature information is also given.
pylithapp.problem.bc Settings that control the applied boundary conditions.
pylithapp.problem.interfaces Settings that control the specification of faults, including quadrature information.
pylithapp.problem.formulation.output Settings related to output of the solution over the domain and points
(surface observation locations).
One aspect that has not been covered previously is the specification of output at discrete points, rather than over a mesh or
sub-mesh. We do this using the OutputSolnPoints output type:
output = [domain, points]
output.points = pylith.meshio.OutputSolnPoints
[pylithapp.problem.formulation.output.points]
coordsys.units = km
reader.filename = output_points.txt
We provide the number of spatial dimensions and the units of the point coordinates, and then the coordinates are given in a
simple ASCII file (output_points.txt). These same points are used for both the forward model computation and the
generation of the Green’s functions.
7.15.4 Step 1: Solution of the Forward Problem
For both the strike-slip problem and the reverse fault problem, we first run a static simulation to generate our synthetic data.
Parameter settings that augment those in pylithapp.cfg are contained in the file eqsim.cfg. These settings are:
pylithapp.problem.interfaces Give the type of fault interface condition and provide the slip distribution to use.
Linear interpolation is used for the slip distribution.
pylithapp.problem.formulation.output Gives the output filenames for domain output, fault output, point output,
and material output. All output uses HDF5 format.
The applied fault slip is given in the file eqslip.spatialdb. For both the strike-slip and reverse problems, no fault opening
is given, so only the left-lateral component is nonzero. We run the forward models by typing (in the appropriate directory)
$$ pylith eqsim.cfg
Once the problem has run, four HDF5 files will be produced. The file named eqsim.h5 (and the associated XDMF file)
contains the solution for the entire domain. This corresponds to the solution shown in Figure 7.63 on the previous page. The
eqsim-fault.h5 file contains the applied fault slip and the change in fault tractions, while the eqsim-fault_info.h5
file contains the final slip, the fault normal, and the slip time. The final file (eqsim-points.h5) contains the solution
computed at the point locations provided in the output_points.txt file. These are the results that will be used as synthetic
data for our inversion. One the problem has run, the results may be viewed with a visualization package such as ParaView. In
Figure 7.64 on the facing page we show the applied fault slip (from eqsim-fault.h5) and the resulting x-displacements
(from eqsim-points.h5) for our strike-slip forward problem.
7.15.5 Step 2: Generation of Green’s Functions
The next step is to generate Green’s functions that may be used in an inversion. The procedure is similar to that for running the
forward problem; however, it is necessary to change the problem type from the default timedependent to greensfns.
This is accomplished by simply typing
pylith --problem=pylith.problems.GreensFns
This changes the problem type and it also causes PyLith to read the file greensfns.cfg by default, in addition to pylithapp.cfg.
These additional parameter settings provide the information necessary to generate the Green’s functions:
Figure 7.64: Applied fault slip for the strike-slip forward problem as well as computed x-displacements at a set of points.
[greensfns]
fault_id = 100
# Set the type of fault interface condition.

[greensfns.interfaces]
fault = pylith.faults.FaultCohesiveImpulses
# Set the parameters for the fault interface condition.

[greensfns.interfaces.fault]
# Generate impulses for lateral slip only, no fault opening.
# Fault DOF 0 corresponds to left-lateral slip.
impulse_dof = [0]
# Set the amplitude of the slip impulses (amplitude is nonzero on only

# a subset of the fault)
db_impulse_amplitude.label = Amplitude of slip impulses
db_impulse_amplitude.iohandler.filename = impulse_amplitude.spatialdb
db_impulse_amplitude.query_type = nearest
Note that the top-level identifier is now greensfns rather than pylithapp. We first set the fault interface condition type
to FaultCohesiveImpulses, and then specify the slip component to use. The amplitude of the fault slip and the fault vertices
to use are provided in the impulse_amplitude.spatialdb file. Fault vertices for which zero slip is specified will not
have associated Green’s functions generated. The remainder of the greensfns.cfg file provides output information, which
is exactly analogous to the settings in eqsim.cfg.
The generation of Green’s functions is somewhat similar to the solution of a time-dependent problem with multiple time
steps. In this case, each ‘time step’ corresponds to the solution computed for a slip impulse at a particular fault vertex. The
output files contain the solution for each separate impulse (slip on a single fault vertex). The greensfns-fault_info.h5
file simply contains the slip amplitude and fault normal. In Figure 7.65 on the next page we show the applied impulse (from file
greensfns-fault.h5) and associated point responses (from file greensfns-points.h5) for the seventh generated
Green’s function in the strike-slip example. In the next section we will show how to read these Green’s functions and use them
to perform a simple linear inversion.
7.15.6 Step 3: Simple Inversion Using PyLith-generated Green’s Functions
In the previous two steps we generated a set of synthetic data as well as a set of Green’s functions. Both are stored in HDF5
files. To make use of them, we provide a simple Python script that reads the HDF5 results using the h5py Python package.
Figure 7.65: Applied fault slip and computed responses (at points) for the seventh Green’s function generated for the strike-slip
fault example.
Once we have read the necessary information, we will perform a simple least-squares inversion using the penalty method. We
will be solving the equation:
G a m = da , (7.3)
where m are the model parameters (slip), G a is the augmented set of Green’s functions, and d a is the augmented data vector.
The Green’s functions are augmented by the addition of a penalty function:
· ¸
G
Ga = , (7.4)
λD
and the data vector is augmented by the addition of the a priori model parameter values:
· ¸
d
da = . (7.5)
m ap
The matrix D is the penalty function, and λ is the penalty parameter. The solution is obtained using the generalized inverse
(e.g., [Menke, 1984]):
¢−1 T
G −g = G aT G a
¡
Ga , (7.6)
and the estimated solution is then:
m est = G −g d a . (7.7)
The code to read the synthetic data and Green’s functions and to perform the inversion is contained in the file invert_slip.py,
which is contained in the top-level directory. For this simple example, we have simply used a diagonal matrix as the penalty
funtion, and the a priori parameter values are assumed to be zero. The solution is performed for a range of values of the penalty
parameter, which are contained in the file penalty_params.txt within each subdirectory. The inversion is performed by
running the script in the top-level directory from each subdirectory. To run an inversion, type:
$$ ../invert_slip.py --impulses=output/greensfns-fault.h5 \
--responses=output/greensfns-points.h5 --data=output/eqsim-points.h5 \
--penalty=penalty_params.txt --output=output/slip_inverted.txt \
This will produce an ASCII file (slip_inverted.txt), which will contain the estimated solution.
7.15.7 Step 4: Visualization of Estimated and True Solutions
Once we have computed the solution, we would then like to visualize the results. We do this using another Python script that re-
quires the matplotlib plotting package (this package is not included in the PyLith binary). We also use the h5py package again to
7.16. EXAMPLE USING GRAVITY AND FINITE STRAIN IN TWO DIMENSIONS 189
3.0 0
2.5
5
2.0
Right-Lateral Slip (m)
1.5
Depth (km)
10
1.0
15
0.5
0.0
20
0.530 20 10 0 10 20 30 0.5 0.0 0.5 1.0 1.5 2.0 2.5 3.0 3.5
Distance Along Strike (km) Reverse slip (m)
Figure 7.66: Inversion results from running Python plotting script.
read the applied slip for the forward problem. The Python code to plot the results is contained in the plot_invresults.py
file contained within each subdirectory. To plot the results, type:
$$ plot_invresults.py --solution=output/eqsim-fault.h5 --predicted=output/slip_inverted.txt
The script will produce an interactive matplotlib window that shows the estimated solution compared to the true solution
(Figure 7.66). As the penalty parameter is increased, the solution is progressively damped. In a real inversion we would also
include the effects of data uncertainties, and the penalty parameter would represent a factor controlling the tradeoff between
solution simplicity and fitting the noise in the data.
7.16 Example Using Gravity and Finite Strain in Two Dimensions

• Gravitational body forces (GravityField)

• Finite (or small) strain (ImplicitLgDeform)
• Direct solver in simulations without a fault
• Iterative solver with custom fault preconditioner for a fault
• Generating a spatial database using h5py from state variables output in HDF5 files
• Cubit mesh generation
• Linear quadrilateral cells
• Plane strain Maxwell viscoelastic material
All of the files necessary to run the examples are contained under the directory examples/2d/gravity. The directory
also contains a README file that describes the simulations and how to run them.
Figure 7.67: Mesh used for 2d gravity simulations with a 30 km thick elastic crust over a 70 km thick linear Maxwell viscoelastic
layer.
7.16.1 Overview
This example illustrates concepts related to using gravitational body forces and finite (or small) strain. We focus on setting up
initial conditions consistent with gravitational body forces and using them in a simulation of postseismic deformation with the
small strain formulation. We examine the differences between simulations with and without gravitational body forces and the
infinitesimal versus small strain formulation.
Steps 1-3 illustrate issues that arise when using gravitational body forces and how to achieve realistic stress states. Steps
4-8 illustrate the differences between infinitesimal and finite strain with and without gravitational body forces for postseismic
relaxation following an earthquake with reverse slip.
7.16.2 Problem Description
The geometry of the problem is a 200km-wide by 100km-deep domain with a flat ground surface. We use a 30km-thick elastic
layer over a linear Maxwell viscoelastic half-space to approximate the crust and mantle. A reverse fault dipping 45 degrees cuts
through the elastic layer and extends into the top portion of the viscoelastic layer. Gravitational body forces act in the vertical
direction. We apply roller Dirichlet boundary conditions to constrain the displacement normal to the boundary.
We discretize the domain using quadrilateral cells with a nominal cell size of 2.0 km. We construct the mesh in CUBIT
following the same techniques used in the 2D subduction zone example, except that this mesh is simpler. The main driver is in
the journal file mesh.jou. It calls the journal file geometry.jou to construct the geometry. The mesh shown in Figure 7.67
The journal files are documented and describe the various steps outlined below.

2. Set the meshing scheme and cell size.
3. Generate the mesh.

5. Export the mesh.
As in the examples discussed in previous sections of these examples, we place parameters common to all of the simulations in
the pylithapp.cfg file so that we do not have to duplicate them in each simulation parameter file. In some cases we do
override the values of parameters in simulation specific parameter files. The settings contained in pylithapp.cfg for this
problem consist of:
pylithapp.problem Settings that control the problem, such as the total time, time-step size, and spatial dimension. Note
that we turn off the elastic prestep here, since it is only used in the first simulation. We also turn on gravity
for the problem. The total_time of 2000.0*year is used for most of the simulations.
pylithapp.problem.materials Settings that control the material type, specify which material IDs are to be associated
with a particular material type, and give the name of the spatial database containing the physical properties
for the material. The quadrature information is also given.
pylithapp.problem.bc We apply Dirichlet roller boundary conditions (pin displacement perpendicular to the boundary)
on the lateral sides and bottom of the domain.
pylithapp.problem.formulation.output Settings related to output of the solution over the domain and subdo-
main. We specify both displacements and velocities for the output.
Since we do not desire an initial elastic solution prior to beginning our time stepping for the simulations, we turn off the elastic
prestep:
elastic_prestep = False
For two-dimensional problems involving gravity, we also need to change the default gravity_dir:
gravity_field.gravity_dir = [0.0, -1.0, 0.0]
7.16.4 Step 1: Gravitational Body Forces and Infinitesimal Strain
This simulation applies gravitational body forces to a domain without any initial conditions, so the gravitational body forces
cause the domain to compress in the vertical direction. The shear stresses in the mantle relax, so that the solution in the
mantle trends towards σxx = σ y y . The crust is elastic and compressible, so σxx 6= σyy . In the earth’s crust we gener-
ally observe σxx ≈ σyy , so this simulation does not yield a stress state consistent with that observed in nature. The file
gravity_infstrain.cfg contains the simulation specific parameter settings that augment those in pylithapp.cfg.
In addition to the filenames for the HDF5 ouput we also set the filename for the progress monitor. You can look at this file
during the simulation to monitor the progress and get an estimate of when the simulation will finish.
We run the simulation using:
$$ pylith gravity_infstrain.cfg
The simulation produces HDF5 (and corresponding XDMF) files with the output of the displacements on the ground surface
and the entire domain, and the state variables for the crust and mantle. Note that the output files contain both cauchy_stress
and stress fields. For problems using the infinitesimal strain formulation, these are identical. For the small strain formula-
tion, the stress field corresponds to the second Piola-Kirchoff stress tensor, which does not have the physical meaning as-
sociated with the Cauchy stress. Loading the axial stress fields for the crust and mantle into ParaView via the XDMF files
(output/gravity_infstrain-crust.xmf and output/gravity_infstrain-mantle.xmf) illustrates how
the axial stresses are not equal. We would like gravitational body forces to yield nearly axial stresses consistent with the
overburden pressure observed in nature.
Figure 7.68: Spatial variation in density in the finite element mesh. The mantle has a uniform density of 3400 kg/m3 and the
crust has a uniform density of 2500 kg/m3 except near the origin where we impose a low density semi-circular region.
7.16.5 Step 2: Gravitational Body Forces, Infinitesimal Strain, and Initial Stresses
This simulation uses depth-dependent initial stresses that satisfy the governing equations. As a result, there is zero deformation.
In practice, there would be no need to run such a simulation, because the initial stresses give us the stress state produced
in the simulation. In Steps 3-7, we use these initial stresses as initial conditions for postseismic deformation simulations.
Because we reuse the initial stress parameter settings in multiple simulations, we place them in their own parameter file,
gravity_initstress.cfg. As in Step 1, the simulation specific parameter file contains the filenames for the output.
$$ pylith gravity_initstress.cfg gravity_isostatic.cfg
7.16.6 Step 3: Infinitesimal Strain Simulation with Initial Stresses and a Local Density Variation
This simulation adds a local density variation in the elastic layer to the problem considered in Step 2. Near the origin, the density
is reduced in a semi-circular region with a radius of 5.0 km, roughly approximating a sedimentary basin. In this example, we
focus on the workflow and use a coarse mesh so we are not concerned with the fact that our mesh with a discretization size
of 2.0 km does a poor job of resolving this density variation; in a real research problem we would use a finer mesh in the low
density region. Figure 7.68shows the spatial variation in density, including the contrast in density between the mantle and crust
and the circular low density region around the origin.
We use the same initial stress state as for the previous two examples. The initial stress state is a close approximation to
the equilibrium state, so there is little deformation. The mantle relaxes corresponding to the viscous strains and shear stresses
approaching zero; shear stress associated with the lateral density variation becomes confined to the crust. In the region with the
lower density, the initial stresses do not satisfy the governing equation and the solution slowly evolves towards a steady state.
This slow asymptotic evolution presents some difficulties with using the output of this simulation (which has not reached the
equilibrium state) as a starting point in other simulations, as we will see in Step 8. Nevertheless, this simulation serves as an
example of how to use initial stresses from vertically layered material properties in computing an equilibrium or steady state
stress state associated with gravitational body forces and lateral density variations or topography.
$$ pylith gravity_initstress.cfg gravity_vardensity.cfg
Figure 7.69 on the next page shows the shear stress field at the end of the simulation.
Figure 7.69: Shear stress in the crust (linearly elastic) and mantle (linear Maxwell viscoelastic) associated gravitational body
forces and a low density region forces.
Figure 7.70: Vertical displacement at the end of the postseismic deformation simulation (t=4000 years).
7.16.7 Step 4: Postseismic Relaxation with Infinitesimal Strain
We impose slip on the reverse fault within the elastic layer and compute the postseismic deformation associated with relaxation
in the mantle. We do not include gravitational body forces. The earthquake slip is 2.0 m above a depth of 15 km and tapers
linearly to zero at a depth of 20 km. We impose the earthquake at time 0.0 years, but use a start time of -100 years so that
any pre-earthquake deformation trends are clear. We use one parameter file (nogravity.cfg) to turn off gravity (by setting
the gravitional acceleration to zero) and another parameter file (postseismic.cfg) for the earthquake related parameters.
Note that we change the preconditioner to the algebraic multigrid preconditioner for the elastic block and the custom fault
preconditioner for the Lagrange multipliers.
$$ pylith postseismic.cfg nogravity.cfg postseismic_infstrain_nograv.cfg
Figure 7.70 shows the vertical displacement field at the end of the simulation.
7.16.8 Step 5: Postseismic Relaxation with Finite Strain
This simulation is the same as Step 4, but we use the finite strain formulation.:
formulation = pylith.problems.ImplicitLgDeform
When we use the finite strain formulation, the solver is automatically switched to the nonlinear solver. We run the simulation
using:
Figure 7.71: Displacement field on the ground surface after 2550 years of postseismic deformation in Step 4 (Infinitesimal
strain without gravity), Step 5 (Finite strain without gravity), Step 6 (Infinitesimal strain with gravity), and 7 (Finite strain with
gravity). The displacement fields for Steps 4-6 are essentially identical.
$$ pylith postseismic.cfg nogravity.cfg postseismic_finstrain_nograv.cfg
The results are nearly identical to those with infinitesimal strain.
7.16.9 Step 6: Postseismic Relaxation with Infinitesimal Strain and Gravitational Body Forces
This simulation is the same as Step 4, but we include gravitational body forces. We use initial stresses that satisfy the governing
equations, so our initial conditions are axial stresses equal to the overburden pressure.
$$ pylith postseismic.cfg postseismic_infstrain.cfg
With the infinitesimal strain formulation and linearly material behavior, the initial stress state of equal axial stresses does not
alter the response. We obtain a displacement field and shear stresses identical to that in Step 4. The axial stresses are the
superposition of the initial stresses and those from the postseismic deformation.
7.16.10 Step 7: Postseismic Relaxation with Finite Strain and Gravitational Body Forces
This simulation is the same as Step 5, but we include gravitational body forces; this is also the same as Step 6, but with finite
strain.
$$ pylith postseismic.cfg postseismic\_finstrain.cfg
The finite strain formulation accounts for the redistribution of gravitational body forces as the domain deforms during the
postseismic response. As a result, the displacement field differs from that in Steps 4-6. To see this difference, we have created a
ParaView state file to view the ground surface deformation from the output of Steps 4-7. After running all four simulations, open
ParaView and load the state file postseismic.pvsm. If you start ParaView from the examples/2d/gravity directory
(PATH_TO_PARAVIEW/bin/paraview, File→Load State→postseismic.pvsm), you should not need to update
the locations of the filenames. If you start ParaView from a dock or other directory, you will need to set the relative or absolute
paths to the output files. Figure 7.71 shows the ground deformation 2550 years after the earthquake using the state file.
Figure 7.72: Cauchy shear stress at the end of the simulation of postseismic deformation with variable density in the crust. We
saturate the color scale at ±1 MPa to show the evidence of viscoelastic relaxation (near zero shear stress) in the mantle.
7.16.11 Step 8: Postseismic Relaxation with Finite Strain, Gravitational Body Forces, and Variable Density
We use the output of Step 3 to create realistic initial stresses for this simulation of postseismic deformation with variable density.
In Step 3 we average the stresses over the quadrature points within a cell using CellFilterAvg. For initial stresses consistent
with the state of the simulation at the end of Step 3, we want the stresses at each of the quadrature points. Note that Step 3 uses
the infintesimal strain formulation and for Step 8 we will use a finite strain formulation; any inconsistencies in using the output
from a simulation with one strain formulation as the input in a simulation for another strain formulation are very small given
that we start Step 8 from an undeformed state so that the Cauchy stresses are very close to the second Pioloa-Kirchoff stresses.
Our first step is to modify the pylithapp.cfg file by commenting out the lines with the CellFilterAvg settings:
# If rerunning Step 3 to get initial conditions for Step 8, comment out the next line as shown.
#cell_filter = pylith.meshio.CellFilterAvg
for both the crust and mantle. Next we rerun Step 3 using
$$ pylith gravity_initstress.cfg gravity_vardensity.cfg
This will change how the values appear in ParaView output. Because the output data fields contain the values at multiple points
within a cell, PyLith does not label them as tensor components; instead, it simply numbers the values 0..N. For the stress tensor
components, values 0, 1, and 2 are the σxx , σyy , and σxy values at the first quadrature point; values 3, 4, and 5 correspond to
the values at the second quadrature point, etc. We use the Python script generate_statedb.py to generate the spatial
databases with the initial stresses from the output of Step 3:
$$ ./generate_statedb.py
After generating the initial state variables, we uncomment the cell_filter lines in pylithapp.cfg to allow easier
visualization of Step 8 results. Finally, we run the simulation of the postseismic deformation using
$$ pylith postseismic.cfg gravity_initstress.cfg postseismic_vardensity.cfg
In the 100 years before the earthquake, it is clear that there is some ongoing deformation associated with the relaxation of the
mantle. Immediately following the earthquake the postseismic deformation signal is stronger at most locations, but as it decays
the ongoing deformation associated with the gravitational body forces and variable density become evident again. This ongoing
deformation is most obvious in the displacement and velocity fields. The postseismic deformation is much more dominant for
the stress field. This contamination by the initial conditions can be avoided with initial stress conditions at equilibrium as we
did in Step 7. However, this is much more difficult to obtain for complex lateral variations in density or topography. Figure 7.72
shows the ground deformation at time 2000 years into the simulation using the state file.
7.16.12 Exercises
The README file in examples/2d/gravity includes some suggetions of additional simulations to run to further explore
some of the issues discussed in this suite of examples.
7.17 Additional Examples
7.17.1 CUBIT Meshing Examples
The directory examples/meshing contains several examples of using CUBIT to construct finite-element meshes for com-
plex geometry. This includes features such as constructing nonplanar fault geometry from contours, constructing topography
from a DEM, and merging sheet bodies (surfaces). A separate examples discusses defining the discretization size using a vertex
field in an Exodus-II file. See the README files in the subdirectories for more detailed descriptions of these examples.
7.17.2 Debugging Examples
The directory examples/debugging contains a few examples to practice debugging a variety of user errors in param-
eters files and problem setup. The files with the errors corrected are in examples/debugging/correct. Step-by-
step corrections are discussed in the Debugging PyLith Simulations sessions of the 2014 and 2015 PyLith tutorials (wiki.
geodynamics.org/software:pylith:start).
7.17.3 Code Verification Benchmarks
The CIG GitHub software repository https://github.com/geodynamics/pylith_benchmarks contains input

files for a number of community benchmarks. The benchmarks do not include the mesh files because they are so large; instead
they include the CUBIT journal files that can be used to generate the meshes. Most, but not all, of the input files in the repository
are updated for PyLith v2.0.0, so you will need to modify them if you use another version of PyLith.
Chapter 8
Benchmarks
8.1 Overview
The Crustal Deformation Modeling and Earthquake Source Physics Focus Groups within the Southern California Earthquake
Center and the Short-Term Tectonics Working Group within CIG have developed a suite of benchmarks to test the accuracy
and performance of 3D numerical codes for quasi-static crustal deformation and earthquake rupture dynamics. The bench-
mark definitions for the quasi-static crustal deformation benchmarks are posted on the CIG website at Short-Term Tectonics
Benchmarks geodynamics.org/cig/workinggroups/short/workarea/benchmarks/ and the definitions for
the earthquake rupture benchmarks are posted on the SCEC website scecdata.usc.edu/cvws/cgi-bin/cvws.cgi.
This suite of benchmarks permits evaluating the relative performance of different types of basis functions, quadrature schemes,
and discretizations for geophysical applications. The files needed to run the 3D benchmarks are in the CIG GitHub Repository
https://github.com/geodynamics/pylith_benchmarks. In addition to evaluating the efficiency and accuracy
of numerical codes, the benchmarks also make good test problems, where users can perform simulations based on actual geo-
physical problems. The benchmarks are performed at various resolutions and using different element types. By comparing the
runtime and accuracy for different resolutions and element types, users can evaluate which combination will be best for their
problems of interest.
8.2 Strike-Slip Benchmark

This benchmark problem computes the viscoelastic (Maxwell) relaxation of stresses from a single, finite, strike-slip earthquake
in 3D without gravity. Dirichlet boundary conditions equal to the analytical elastic solution are imposed on the sides of a cube
with sides of length 24 km. Anti-plane strain boundary conditions are imposed at y = 0, so the solution is equivalent to that for a
domain with a 48 km length in the y direction. We can use the analytical solution of [Okada, 1992] both to apply the boundary
conditions and to compare against the numerically-computed elastic solution.
Figure 8.1 on the next page shows the geometry of the strike-slip fault (red surface) embedded in the cube consisting of an
elastic material (yellow block) over a Maxwell viscoelastic material (blue block).
Domain The domain spans the region
0 ≤ x ≤ 24 km,
0 ≤ y ≤ 24 km,
−24 km ≤ z ≤ 0.
197
198 CHAPTER 8. BENCHMARKS
The top (elastic) layer occupies the region −12 km ≤ z ≤ 0 and the bottom (viscoelastic) layer occupies the region
−24 km ≤ z ≤ −12 km .
Material properties The material is a Poisson solid with a shear modulus of 30 GPa. The domain is modeled using an elastic
isotropic material for the top layer and a Maxwell viscoelastic material for the bottom layer. The bottom layer has a
viscosity of 1.0e+18 Pa-s.
Fault The fault is a vertical, right-lateral strike-slip fault. The strike is parallel to the y-direction at the center of the model:
x = 12 km,
0 ≤ y ≤ 16 km,
−16 km ≤ z ≤ 0.
Uniform slip of 1 m is applied over the region 0 ≤ y ≤ 12 km and −12 km ≤ z ≤ 0 with a linear taper to 0 at y = 16 km
and z = -16 km. The tapered region is the light red portion of the fault surface in Figure 8.1. In the region where the two
tapers overlap, each slip value is the minimum of the two tapers (so that the taper remains linear).
Boundary conditions Bottom and side displacements are set to the elastic analytical solution, and the top of the model is
a free surface. There are two exceptions to these applied boundary conditions. The first is on the y=0 plane, where
y-displacements are left free to preserve symmetry, and the x- and z-displacements are set to zero. The second is along
the line segment between (12, 0, -24) and (12, 24, -24), where the analytical solution blows up in some cases. Along this
line segment, all three displacement components are left free.
Discretization The model is discretized with nominal spatial resolutions of 1000 m, 500 m, and 250 m.
Basis functions We use trilinear hexahedral cells and linear tetrahedral cells.
Solution We compute the error in the elastic solution and compare the solution over the domain after 0, 1, 5, and 10 years.
Figure 8.1: Geometry of strike-slip benchmark problem.

8.2. STRIKE-SLIP BENCHMARK 199
8.2.2 Running the Benchmark
Each benchmark uses three .cfg files in the parameters directory: pylithapp.cfg, a mesher related file (strikeslip_cubit.cfg
or strikeslip_lagrit.cfg), and a resolution and cell related file (e.g., strikeslip_hex8_1000m.cfg).
# Checkout the benchmark files from the CIG Git repository.
$ git clone https://github.com/geodynamics/pylith_benchmarks.git
# Change to the quasistatic/sceccrustdeform/strikeslip directory.
$ cd quasistatic/sceccrustdeform/strikeslip
# Decompress the gzipped files in the meshes and parameters
directories.
$ gunzip meshes/*.gz parameters/*.gz
# Change to the parameters directory.
$ cd parameters
# Examples of running static (elastic solution only) cases.
$ pylith strikeslip_cubit.cfg strikeslip_hex8_1000m.cfg
$ pylith strikeslip_cubit.cfg strikeslip_hex8_0500m.cfg
$ pylith strikeslip_cubit.cfg strikeslip_tet4_1000m.cfg
# Append timedep.cfg to run the time-dependent (viscoelastic cases).
$ pylith strikeslip_cubit.cfg strikeslip_hex8_1000m.cfg timedep.cfg
$ pylith strikeslip_cubit.cfg strikeslip_hex8_0500m.cfg timedep.cfg
$ pylith strikeslip_cubit.cfg strikeslip_tet4_1000m.cfg timedep.cfg
This will run the problem for 10 years, using a time-step size of 0.1 years, and results will be output for each year. The
benchmarks at resolutions of 1000 m, 500 m, and 250 m require approximately 150 MB, 960 MB, and 8 GB, respectively.
8.2.3 Benchmark Results
Figure 8.2 shows the displacement field from the simulation with hexahedral cells using trilinear basis functions at a resolution
of 1000 m. For each resolution and set of basis functions, we measure the accuracy by comparing the numerical solution against
the semi-analytical Okada solution [Okada, 1992]. We also compare the accuracy and runtime across resolutions and different
cell types. This provides practical information about what cell types and resolutions are required to achieve a given level of
accuracy with the shortest runtime.
Figure 8.2: Displacement field for strike-slip benchmark problem.

8.2.3.1 Solution Accuracy
We quantify the error in the finite-element solution by integrating the L2 norm of the difference between the finite-element
solution and the semi-analytical solution evaluated at the quadrature points. We define the local error (error for each finite-
element cell) to be v
1 u
Z ³
f em 2
´
²l ocal = u it − u i dV , (8.1)
u
t
Vcel l
cel l
f em
where u it is the ith component of the displacement field for the semi-analytical solution, and u i is the ith component of the
displacement field for the finite-element solution. Taking the square root of the L2 norm and normalizing by the volume of
the cell results in an error metric with dimensions of length. This roughly corresponds to the error in the magnitude of the
displacement field in the finite element solution. We define the global error in a similar fashion,
v
1
Z
f em 2
u ³ ´
²g l obal = u it − u i dV , (8.2)
u
t
Vd omai n
d omai n
where we sum the L2 norm computed for the local error over all of the cells before taking the square root and dividing by the
volume of the domain. CIG has developed a package called Cigma geodynamics.org/cig/software/packages/
cs/cigma that computes these local and global error metrics.
Figures 8.3 through 8.8 on page 203 show the local error for each of the three resolutions and two cell types. The error
decreases with decreasing cell size as expected for a converging solution. The largest errors, which approach 1 mm for 1 m
of slip for a discretization size of 250 m, occur where the gradient in slip is discontinuous at the boundary between the region
of uniform slip and linear taper in slip. The linear basis functions cannot match this higher order variation. The trilinear
basis functions in the hexahedral element provide more terms in the polynomial defining the variation in the displacement field
within each cell compared to the linear basis functions for the tetrahedral cell. Consequently, for this problem the error for the
hexahedral cells at a given resolution is smaller than that for the tetrahedral cells. Both sets of cell types and basis functions
provide the same rate of convergence as shown in Figure 8.9 on page 203.
Figure 8.3: Local error for strike-slip benchmark problem with tetrahedral cells and linear basis functions with a uniform
discretization size of 1000 m.
Figure 8.4: Local error for strike-slip benchmark problem with hexahedral cells and trilinear basis functions with a uniform
Figure 8.9: Convergence rate for the strike-slip benchmark problem with tetrahedral cells and linear basis functions and with
hexahedral cells with trilinear basis functions.
8.2.3.2 Performance
Figure 8.10 summarizes the overall performance of each of the six simulations. Although at a given resolution, the number of
degrees of freedom in the hexahedral and tetrahedral meshes are the same, the number of cells in the tetrahedral mesh is about
six times greater. However, we use only one integration point per tetrahedral cell compared to eight for the hexahedral cell.
This leads to approximately the same number of integration points for the two meshes, but the time required to unpack/pack
information for each cell from the finite-element data structure is greater than the time required to do the calculation for each
quadrature point (which can take advantage of the very fast, small memory cache in the processor). As a result, the runtime for
the simulations with hexahedral cells is significantly less than that for the tetrahedral cells at the same resolution.
6
# Vertices 7
# Cells Peak Memory Usage (MB)
10 10
4
10
6
10 3
10
5
10
5
10 10
2
4 4 1
10 10 10
1000m 500m 250m 1000m 500m 250m 1000m 500m 250m
Run Time (s) -2

Average Error (m)
10
3 Tet4
10
-3 Hex8
10
2
10 -4
10
1 -5
10 10
1000m 500m 250m 1000m 500m 250m
Figure 8.10: Summary of performance of PyLith for the six simulations of the strike-slip benchmark. For a given discretization
size, hexahedral cells with trilinear basis functions provide greater accuracy with a shorter runtime compared with tetrahedral
cells and linear basis functions.
Figure 8.11 on the facing page compares the runtime for the benchmark (elastic solution only) at 500 m resolution for 1
to 16 processors. The total runtime is the time required for the entire simulation, including initialization, distributing the mesh
over the processors, solving the problem in parallel, and writing the output to VTK files. Some initialization steps, writing
the output to VTK files, and distributing the mesh are essentially serial processes. For simulations with many time steps these
steps will generally occupy only a fraction of the runtime, and the runtime will be dominated by the solution of the equations.
Figure 8.11 on the next page also shows the total time required to form the Jacobian of the system, form the residual, and solve
the system. These steps provide a more accurate representation of the parallel-performance of the computational portion of the
code and show excellent performance as evident in the approximately linear slope of 0.7. S linear decrease with a slope of 1
would indicate strong scaling, which is rarely achieved in real applications.
8.3 Savage and Prescott Benchmark

This benchmark problem computes the viscoelastic (Maxwell) relaxation of stresses from repeated infinite, strike-slip earth-
quakes in 3D without gravity. The files needed to run the benchmark may be found at https://github.com/geodynamics/
pylith_benchmarks/tree/master/quasistatic/sceccrustdeform/savageprescott. An analytical so-
lution to this problem is described by Savage and Prescott [Savage and Prescott, 1978], which provides a simple way to check
our numerical solution. A python utility code is provided in the utils directory to compute the analytical solution. Although this
problem is actually 2.5D (infinite along-strike), we solve it using a 3D finite element model.
Figure 8.12 on page 206 shows the geometry of the problem, as described by [Savage and Prescott, 1978]. The analytical solu-
tion describes the surface deformation due to repeated earthquakes on an infinite strike-slip fault embedded in an elastic layer
8.3. SAVAGE AND PRESCOTT BENCHMARK 205
4
Runtime versus Number of Processors
10
Runtime (s)
St
ro
ng
Tet4 total sc
3 al
10 Tet4 compute in
g
Hex8 total
Hex8 compute
0 1
10 10
Number of Processors
Figure 8.11: Parallel performance of PyLith for the strike-slip benchmark problem with tetrahedral cells and linear basis
functions with a uniform discretization size of 500 m. The total runtime (total) and the runtime to compute the Jacobian and
residual and solve the system (compute) are shown. The compute runtime decreases with a slope of about 0.7; a linear decrease
with a slope of 1 would indicate strong scaling, which is rarely achieved in any real application.
overlying a Maxwell viscoelastic half-space. The upper portion of the fault (red in the figure) is locked between earthquakes,
while the lower portion (blue in the figure) creeps at plate velocity. At regular recurrence intervals, the upper portion of the
fault abruptly slips by an amount equal to the plate velocity multiplied by the recurrence interval, thus ’catching up’ with the
lower part of the fault.
There are some differences between the analytical solution and our numerical representation. First, the analytical solution
represents the earthquake cycle as the superposition of uniform fault creep and an elementary earthquake cycle. Uniform fault
creep is simply the uniform movement of the two plates past each other at plate velocity. For the elementary earthquake cycle,
no slip occurs below the locked portion of the fault (blue portion in the figure). On the locked (red) portion of the fault, backslip
equal to plate velocity occurs until the earthquake recurrence interval, at which point abrupt forward slip occurs. In the finite
element solution, we perform the simulation as described in the figure. Velocity boundary conditions are applied at the extreme
edges of the model to simulate block motion, steady creep is applied along the blue portion of the fault, and regular earthquakes
are applied along the upper portion of the fault. It takes several earthquake cycles for the velocity boundary conditions to
approximate the steady flow due to steady block motion, so we would not expect the analytical and numerical solutions to
match until several earthquakes have occurred. Another difference lies in the dimensions of the domain. The analytical solution
assumes an infinite strike-slip fault in an elastic layer overlying a Maxwell viscoelastic half-space. In our finite element model
we are restricted to finite dimensions. We therefore extend the outer boundaries far enough from the region of interest to
approximate boundaries at infinity.
Due to the difficulties in representing solutions in an infinite domain, there are several meshes that have been tested for
this problem. The simplest meshes have uniform resolution (all cells have equal dimensions); however, such meshes typically
do not provide accurate solutions since the resolution is too coarse in the region of interest. For that reason, we also tested
meshes where the mesh resolution decreases away from the center. In the problem description that follows, we will focus on
the hexahedral mesh with finer discretization near the fault (meshes/hex8_6.7km.exo.gz), which provides a good match
with the analytical solution. It will first be necessary to gunzip this mesh so that it may be used by PyLith.
Domain The domain for this mesh spans the region
−1000 ≤ x ≤ 1000 km,

−500 ≤ y ≤ 500 km,
−400 km ≤ z ≤ 0.
The top (elastic) layer occupies the region −40 km ≤ z ≤ 0 and the bottom (viscoelastic) layer occupies the region
−400 km ≤ z ≤ −40 km .
Material properties The material is a Poisson solid with a shear modulus (µ) of 30 GPa. The domain is modeled using an
elastic isotropic material for the top layer and a Maxwell viscoelastic material for the bottom layer. The bottom layer has
a viscosity (η) of 2.36682e+19 Pa-s, yielding a relaxation time (2η/µ) of 50 years.
Fault The fault is a vertical, left-lateral strike-slip fault. The strike is parallel to the y-direction at the center of the model:
x = 0 km,
−500 ≤ y ≤ 500 km,
−40 km ≤ z ≤ 0.
The locked portion of the fault (red section in Figure 8.12) extends from −20 km ≤ z ≤ 0, while the creeping section
(blue) extends from −40 km ≤ z ≤ 0. Along the line where the two sections coincide (z = −20 km ), half of the coseismic
displacement and half of the steady creep is applied (see finalslip.spatialdb and creeprate.spatialdb).
Boundary conditions On the bottom boundary, vertical displacements are set to zero, while on the y-boundaries the x-
displacements are set to zero. On the x-boundaries, the x-displacements are set to zero, while constant velocities of
+/- 1 cm/yr are applied in the y-direction, giving a relative plate motion of 2 cm/year.
Discretization For the nonuniform hexahedral mesh, the resolution at the outer boundaries is 20 km. An inner region is then
put through one level of refinement, so that near the center of the mesh the resolution is 6.7 km. All meshes were
generated with CUBIT.
Basis functions We use trilinear hexahedral cells.
Solution We compute the surface displacements and compare these to the analytical solution in Figure 8.13 on the facing page.
Figure 8.12: Problem description for the Savage and Prescott strike-slip benchmark problem.
8.3.2 Running the Benchmark
There are a number of .cfg files corresponding to the different meshes, as well as a pylithapp.cfg file defining parameters
common to all problems. Each problem uses four .cfg files: pylithapp.cfg, fieldsplit.cfg (algrebraic multigrid
preconditioner), a cell-specific file (e.g., hex8.cfg), and a resolution specific file (e.g., hex8_6.7km.cfg).
# If you have not do so already, checkout the benchmarks from the CIG Git repository.
$ git clone https://github.com/geodynamics/pylith_benchmarks.git
# Change to the quasistatic/sceccrustdeform/savageprescott directory.
$ cd quasistatic/sceccrustdeform/savageprescott
# Decompress the gzipped files in the meshes directory.
$ gunzip meshes/*.gz
# Run one of the simulations.
$ pylith hex8.cfg hex8_6.7km.cfg fieldsplit.cfg
Each simulation uses 10 earthquake cycles of 200 years each, using a time-step size of 10 years, for a total simulation time
of 2000 years. Ground surface output occurs every 10 years, while all other outputs occur every 50 years.
8.4. SCEC DYNAMIC RUPTURE BENCHMARKS 207
Once the problem has run, results will be placed in the output directory. These results may be viewed directly using
3-D visualization software such as ParaView; however, to compare results to the analytical solution, some postprocessing is
required. First, generate the analytical results by running the calc_analytic.py script. This will produce files with
displacements and velocities (analytic_disp.txt and analytic_vel.txt) in the output directory that are easy to
use with a plotting package, such as matplotlib or Matlab.
8.3.3 Benchmark Results
Figure 8.13 shows the computed surface displacements for the 10th earthquake cycle compared with the analytical solution.
The profile results were obtained as described above, and then all results (analytical and numerical) were referenced to the
displacements immediately following the last earthquake. We find very good agreement between the analytical and numerical
solutions, even for meshes with uniform refinement. We have not yet explored quantitative fits as a function of mesh resolution.
For this benchmark, it is also important to consider the distance of the boundary from the region of interest. Also note that the
agreement between analytical and numerical solutions is poor for early earthquake cycles, due to the differences in simulating
the problem, as noted above.
Analytic
Hex8 20km
Tet4 20km
Hex8 6.7km
Tet4 6.7km
Earthquake Cycle 2
0.5
(a)
Disp. / Coseismic Disp.
0.4
0.3
0.2
0.1
0.0
Earthquake Cycle 10
0.5 t=0.95
(b)
Disp. / Coseismic Disp.
0.4 t=0.75
0.3 t=0.50
0.2
t=0.25
0.1
t=0.05
0.0 -1
10 100
101
Dist. from Fault / Elastic thickness
Figure 8.13: Displacement profiles perpendicular to the fault for a PyLith simulation with hex8 cells and the analytical solution
for earthquake cycle 10.
8.4 SCEC Dynamic Rupture Benchmarks

The SCEC website scecdata.usc.edu/cvws/cgi-bin/cvws.cgi includes a graphical user interface for examining
the benchmark results. Benchmark results for PyLith are available for TPV205-2D (horizontal slice through a vertical strike-
slip fault), TPV205 (vertical strike-slip fault with high and low stress asperities), TPV210-2D (vertical slice through a 60-
degree dipping normal fault), TPV210 (60-degree dipping normal fault), TPV11, TPV12, TPV13, TPV14-2D and TPV15-2D
(horizontal slice through a verticel strike-slip fault with a branch), TPV14, TPV15, TPV 24, TPV25 (vertical strike-slip fault
with a branch), TPV 16 and 17 (vertical strike-slip fault with spatially heterogeneous initial tractions), TPV 22 and 23 (vertical
strike-slip fault with a stepover), TPV102 (vertical strike-slip fault with rate-state friction).
The benchmark results indicate that triangular and tetrahedral cells generate less numerical noise than quadrilateral or
hexahedral cells. The input files in the repository are updated for PyLith v2.0.0, so you will need to modify them if you use
another version of PyLith.
Chapter 9
Extending PyLith
One of the powerful features of using the Pyre framework in PyLith is the ability to extend the functionality of the software
without altering any of the PyLith code. Any of the components can be replaced with other compatible components. You are
already familiar with this feature from running the examples; when you set the spatial database to UniformDB, SimpleDB,
or SCECCVMH you are switching between different compatible components for a spatial database facility. Modifying the
governing equations to include other physical processes requires changing the data structures associated with the solution and
altering the PyLith code.
In this section we provide examples of how to extend PyLith for components that users will most likely want to replace
with their own custom versions. You will need a familiarity with Python, Makefiles, and C++ to write your own components.
The primary steps in constructing a component to extend PyLith’s functionality include:
1. Setting up the source files for the component or set of components based on the templates.
2. Edit the Python source file (.py) for the component.
(a) Define the user-specified properties and facilities.

(b) Transfer the user-specified data from the Python object to the corresponding C++ object via calls to the SWIG
interface object.
3. Edit the C++ header (.hh) and implementation files (.cc) for the component.
(a) Implement the methods required to satisfy the interface definition of the component.
(b) Implement the desired functionality of the component in C++.
4. Edit the SWIG interface files (.i) that provide the glue between Python and C++.
5. Edit the Python source file that tests the functionality of the component.
6. Run configure, build, install, and run the tests of the component.
9.1 Spatial Databases

PyLith provides several types of spatial databases that can be used for specification of parameters associated with boundary
conditions, earthquake ruptures, and physical properties. In this example we demonstrate how to provide a spatial database,
UniformVelModel, for specifying elastic properties. The source files are included in the source for the spatialdata package
in the templates/spatialdb directory. The README file in templates/spatialdb provides detailed instructions
for the various steps involved, and the source files contain numerous comments to help guide you through the customization
process.
209
210 CHAPTER 9. EXTENDING PYLITH
The UniformVelModel component provides uniform physical properties: P-wave speed, S-wave speed, and density. Al-
though this is a rather trivial specification of physical properties that could be easily done using a UniformDB, this example
demonstrates how to create a user-defined component that matches the requirements of a spatial database for elastic physical
properties. Adding additional physical properties is simply a matter of including some additional values in the spatial database.
Furthermore, in cases where we are constructing a spatial database for a seismic velocity model, the data points are georef-
erenced. With our uniform physical properties we do not need to worry about any differences in coordinate systems between
our seismic velocity model and points at which the model is queried. However, in many cases we do, so we illustrate this
functionality by using a geographic projection as the coordinate system in our example.
Using a top-down approach, the first step is to determine what information the user will need to supply to the component.
Is the data for the spatial database in a file or a series of files? If so, file names and possible paths to a directory containing
files with known names might be necessary. Are there other parameters that control the behavior of the component, such as a
minimum shear wave speed? In our example the user supplies values for the P-wave speed, S-wave speed, and density. The
user-supplied parameters become Pyre properties and facilities in the Python source file. Because our user supplied parameters
are floating point values with dimensions, we create dimensional properties vs, vp, and density. In addition to defining the
properties of the component, we also need to transfer these properties to the C++ object that does the real work. This is done
by calling the C++ vs(), vp(), and density() accessor functions that are accessible via the Python module created by
SWIG.
In the C++ object we must implement the functions that are required by the spatial database interface. These functions are
listed near the beginning of the UniformVelModel class definition at the top of the C++ header file, UniformVelModel.hh.
The C++ object also includes the accessor functions that allow us to set the P-wave speed, S-wave speed, and density values to
the user-specified values in the Python object. Additional information, such as a file name, parameters defined as data structures,
etc., would be set via similar accessor functions. You can also add additional functions and data structures to the C++ class to
provide the necessary operations and functionality of the spatial database.
In SimpleDB we use a separate class to read in the spatial database and yet another class to perform the actual query. In our
example, the C++ object also creates and stores the UTM zone 10 geographic projection for the seismic velocity model. When
the spatial database gets a query for physical properties, we transform the coordinates of the query point from its coordinate
system to the coordinate system of our seismic velocity model.
In order to use SWIG to create the Python module that allows us to call C++ from Python, we use a “main” SWIG interface
file (spatialdbcontrib.i in this case) and then one for each object (UniformVelModel.i in this case). This greatly
simplifies keeping the Python module synchronized with the C++ and Python code. The UniformVelModel.i SWIG file
is nearly identical to the corresponding C++ header file. There are a few differences, as noted in the comments within the
file. Copying and pasting the C++ header file and then doing a little cleanup is a very quick and easy way to construct a
SWIG interface file for a C++ object. Because very little changes from SWIG module to SWIG module, it is usually easiest to
construct the “main” SWIG interface by copying and customizing an existing one.
Once the Python, C++, and SWIG interface files are complete, we are ready to build the module. The Makefile.am file
defines how to compile and link the C++ library and generate the Python module via SWIG. The configure.ac file contains
the information used to build a configure script. The configure script checks to make sure it can find all of the tools needed
to build the component (C++ compiler, Python, installed spatial database package, etc.). See the README file for detailed
instructions on how to generate the configure script, and build and install the component.
We recommend constructing tests of the component to insure that it is functioning properly before attempting to use it in an
application. The tests directory within templates/spatialdb contains a Python script, testcontrib.py, that runs
the tests of the UniformVelModel component defined in TestUniformVelModel.py. Normally, one would want to test
each function individually to isolate errors and create C++ tests as well as the Python tests included here. In our rather simple
example, we simply test the overall functionality of the component. For examples of thorough testing, see the spatialdata and
PyLith source code.
Once you have built, installed, and tested the UniformVelModel, it is time to use it in a simple example. Because the
seismic velocity model uses georeferenced coordinates, our example must also use georeferenced coordinates. The dislocation
example in the PyLith examples/twocells/twotet4-geoproj directory uses UTM zone 11 coordinates. The spatial
database package will transform the coordinates between the two projections as defined in the UniformVelModel query()
function. The dislocation example uses the SCEC CVM-H seismic velocity model. In order to replace the SCEC CVM-H
9.2. BULK CONSTITUTIVE MODELS 211
seismic velocity with our uniform velocity model, in pylithapp.cfg
# Replace these two lines
db_properties = spatialdata.spatialdb.SCECCVMH
db_properties.data_dir = /home/john/data/sceccvm-h/vx53/bin
# with
db_properties = spatialdata.spatialdb.contrib.UniformVelModel
When you run the dislocation example, the dislocation-statevars_info.vtk file should reflect the use of physical
properties from the uniform seismic velocity with µ = 1.69 × 1010 Pa, λ = 1.6825 × 1010 Pa, and ρ = 2500kg/m3 .
9.2 Bulk Constitutive Models

PyLith includes several linearly elastic and inelastic bulk constitutive models for 2D and 3D problems. In this example, we
demonstrate how to extend PyLith by adding your own bulk constitutive model. We reimplement the 2D plane strain constitutive
model while adding the current strain and stress tensors as state variables. This constitutive model, PlaneStrainState, is
not particularly useful, but it illustrates the basic steps involved in creating a bulk constitutive model with state variables.
The source files are included with the main PyLith source code in the templates/materials directory. The README
file in templates/materials provides detailed instructions for the various steps, and the source files contain numerous
comments to guide you through the customization process.
In contrast to our previous example of creating a customized spatial database, which involved gathering user-specified
parameters via the Pyre framework, there are no user-defined parameters for bulk constitutive models. The specification of the
physical properties and state variables associated with the constitutive model is handled directly in the C++ code. As a result,
the Python object for the constitutive model component is very simple, and customization is limited to simply changing the
names of objects and labels.
The properties and state variables used in the bulk constitutive model are set using arguments to the constructor of the
C++ ElasticMaterial object. We define a number of constants at the top of the C++ file and use the Metadata object to define
the properties and state variables. The C++ object for the bulk constitutive component includes a number of functions that
implement elasticity behavior of a bulk material as well as several utility routines:
_dbToProperties() Computes the physical properties used in the constitutive model equations from the physical proper-
ties supplied in spatial databases.
_nondimProperties() Nondimensionalizes the physical properties used in the constitutive model equations.
_dimProperties() Dimensionalizes the physical properties used in the constitutive model equations.
_stableTimeStepImplicit() Computes the stable time step for implicit time stepping in quasi-static simulations given
the current state (strain, stress, and state variables).
_calcDensity() Computes the density given the physical properties and state variables. In most cases density is a physical
property used in the constitutive equations, so this is a trivial function in those cases.
_calcStress() Computes the stress tensor given the physical properties, state variables, total strain, initial stress, and
initial strain.
_calcElasticConsts() Computes the elastic constants given the physical properties, state variables, total strain, initial
stress, and initial strain.
_updateStateVars() Updates the state variables given the physical properties, total strain, initial stress, and initial strain.
If a constitutive model does not use state variables, then this routine is omitted.
Because it is sometimes convenient to supply physical properties for a bulk constitutive model that are equivalent but different
from the ones that appear in the constitutive equations (e.g., P-wave speed, S-wave speed, and density rather then Lame’s
constants µ, λ, and density), each bulk constitutive model component has routines to convert the physical property parameters
and state variables a user specifies via spatial databases to the physical property properties and state variables used in the
constitutive model equations. In quasi-static problems, PyLith computes an elastic solution for the first time step (−∆t to t ).
This means that for inelastic materials, we supply two sets of functions for the constitutive behavior: one set for the initial
elastic step and one set for the remainder of the simulation. See the source code for the inelastic materials in PyLith for an
illustration of an efficient mechanism for doing this.
The SWIG interface files for a bulk constitutive component are set up in the same manner as in the previous example of
creating a customized spatial database component. The “main” SWIG interface file (materialscontrib.i in this case)
sets up the Python module, and the SWIG interface file for the component (PlaneStrainState.i in this case) defines the
functions that should be included in the Python module. Note that because the C++ ElasticMaterial object defines a number
of pure virtual methods (which merely specify the interface for the functions and do not implement default behavior), we must
include many protected functions in the SWIG interface file. If these are omitted, SWIG will give a warning indicating that
some of the functions remain abstract (i.e., some pure virtual functions defined in the parent class ElasticMaterial were not
implemented in the child class PlaneStrainState), and no constructor is created. When this happens, you cannot create a
PlaneStrainState Python object.
Once the Python, C++, and SWIG interface files are complete, you are ready to configure and build the C++ library
and Python module for the component. Edit the Makefile.am file as necessary, then generate the configure script, run
configure, and then build and install the library and module (see the README file for detailed instructions).
Because most functionality of the bulk constitutive model component is at the C++ level, properly constructed unit tests
for the component should include tests for both the C++ code and Python code. The C++ unit tests can be quite complex, and
it is best to examine those used for the bulk constitutive models included with PyLith. In this example we create the Python unit
tests to verify that we can create a PlaneStrainState Python object and call some of the simple underlying C++ functions. The
source files are in the templates/materials/tests directory. The testcontrib.py Python script runs the tests
defined in TestPlaneStrainState.py.
Once you have built, installed, and tested the PlaneStrainState component, it is time to use it in a simple example. You
can try using it in any of the 2D examples. For the examples in examples/twocells/twoquad4, in pylithapp.cfg
# Replace
material = pylith.materials.ElasticPlaneStrain
# with
material = pylith.materials.contrib.PlaneStrainState
or simply add the command line argument --timedependent.homogeneous.material=pylith.materials.contrib.Plan

when running any of the 2D examples. The output should remain identical, but you should see the PlaneStrainState object
listed in the information written to stdout.
9.3 Fault Constitutive Models

PyLith includes two of the most widely used fault constitutive models, but there are a wide range of models that have been
proposed to explain earthquake source processes. In this example, we demonstrate how to extend PyLith by adding your own
fault constitutive model. We implement a linear viscous fault constitutive model wherein the perturbation in the coefficient
of friction is linearly proportional to the slip rate. This constitutive model, ViscousFriction, is not particularly useful, but it
illustrates the basic steps involved in creating a fault constitutive model. The source files are included with the main PyLith
source code in the templates/friction directory. The README file in templates/friction provides detailed
instructions for the various steps, and the source files contain numerous comments to guide you through the customization
process.
Similar to our previous example of creating a customized bulk constitutive model, the parameters are defined in the C++
code, not in the Pyre framework. As a result, the Python object for the fault constitutive model component is very simple and
customization is limited to simply changing the names of objects and labels.
The properties and state variables used in the fault constitutive model are set using arguments to the constructor of the C++
FrictionModel object, analogous to the ElasticMaterial object for bulk constitutive models. In fact, both types of constitutive
9.3. FAULT CONSTITUTIVE MODELS 213
models used the same underlying C++ object (Metadata::ParamDescription) to store the description of the parameters and
state variables. We define a number of constants at the top of the C++ file and use the Metadata object to define the properties
and state variables. The C++ object for the fault constitutive component includes a number of functions that implement friction
as well as several utility routines:
_dbToProperties() Computes the physical properties used in the constitutive model equations from the physical proper-
ties supplied in spatial databases.
_nondimProperties() Nondimensionalizes the physical properties used in the constitutive model equations.
_dimProperties() Dimensionalizes the physical properties used in the constitutive model equations.
_dbToStateVars() Computes the initial state variables used in the constitutive model equations from the initial values
supplied in spatial databases.
_nondimStateVars() Nondimensionalizes the state variables used in the constitutive model equations.
_dimStateVars() Dimensionalizes the state variables used in the constitutive model equations.
_calcFriction() Computes the friction stress given the physical properties, state variables, slip, slip rate, and normal
traction.
_updateStateVars() Updates the state variables given the physical properties, slip, slip rate, and normal traction.
If a constitutive model does not use state variables, then the state variable routines are omitted.
Because it is sometimes convenient to supply physical properties for a fault constitutive model that are equivalent but
different from the ones that appear in the constitutive equations, each fault constitutive model component has routines to convert
the physical property parameters and state variables a user specifies via spatial databases to the physical property properties and
state variables used in the constitutive model equations.
The SWIG interface files for a fault constitutive component are set up in the same manner as in the previous exam-
ples of creating a bulk constitutive model or a customized spatial database component. The “main” SWIG interface file
(frictioncontrib.i in this case) sets up the Python module, and the SWIG interface file for the component (ViscousFriction.i
in this case) defines the functions that should be included in the Python module. Note that because the C++ FrictionModel
object defines a number of pure virtual methods (which merely specify the interface for the functions and do not implement
default behavior), we must include many protected functions in the SWIG interface file. If these are omitted, SWIG will give
a warning indicating that some of the functions remain abstract (i.e., some pure virtual functions defined in the parent class
FrictionModel were not implemented in the child class ViscousFriction), and no constructor is created. When this happens,
you cannot create a ViscousFriction Python object.
Once the Python, C++, and SWIG interface files are complete, you are ready to configure and build the C++ library
and Python module for the component. Edit the Makefile.am file as necessary, then generate the configure script, run
configure, and then build and install the library and module (see the README file for detailed instructions).
Because most functionality of the fault constitutive model component is at the C++ level, properly constructed unit tests
for the component should include tests for both the C++ code and Python code. The C++ unit tests can be quite complex, and
it is best to examine those used for the fault constitutive models included with PyLith. In this example we create the Python
unit tests to verify that we can create a ViscousFriction Python object and call some of the simple underlying C++ functions.
The source files are in the templates/friction/tests directory. The testcontrib.py Python script runs the tests
defined in TestViscousFriction.py.
Once you have built, installed, and tested the ViscousFriction component, it is time to use it in a simple example.
You can try using it in any of the 2D or 3D examples. For the examples in examples/bar_shearwave/quad4, in
shearwave_staticfriction.cfg
# Replace
friction = pylith.friction.StaticFriction
# with
friction = pylith.friction.contrib.ViscousFriction
or simply add the command line argument --timedependent.interfaces.fault.friction=pylith.friction.contrib.
when running any of the friction examples. You will also need to supply a corresponding spatial database with the physical
properties for the viscous friction constitutive model.
Appendix A
Glossary
A.1 Pyre
component Basic building block of a Pyre application. A component may be built-up from smaller building blocks, where
simple data types are called properties and data structures and objects are called facilities. In general a component is
a specific implementation of the functionality of a facility. For example, SimpleDB is a specific implementation of the
spatial database facility. A component is generally composed of a Python object and a C++ object, although either one
may be missing. We nearly always use the naming convention such that for an object called Foo the Python object is in
file Foo.py, the C++ class definition is in Foo.hh, inline C++ functions are in foo.icc, the C++ class implementation is in
Foo.cc, and the SWIG interface file that glues the C++ and Python code together is in Foo.i.
facility Complex data type (object or data structure) building block of a component. See component.
property Simple data type (string, integer, real number, or boolean value) parameter for a component.
A.2 DMPlex
The plex construction is a representation of the topology of the finite element mesh based upon a covering relation. For
example, segments are covered by their endpoints, faces by their bounding edges, etc. Geometry is absent from the plex, and
is represented instead by a field with the coordinates of the vertices. Meshes can also be understood as directed acyclic graphs,
where we call the constituents points and arrows.
mesh A finite element mesh, used to partition space and provide support for the basis functions.
cell The highest dimensional elements of a mesh, or mesh entities of codimension zero.
vertex The zero dimensional mesh elements.
face Mesh elements that separate cells, or mesh entities of codimension one.
field A parallel section which can be completed, or made consistent, across process boundaries. These are used to represent
continuum fields.
section These objects associate values in vectors to points (vertices, edges, faces, and cells) in a mesh. The section describes
the offset into the vector along with the number of values associated with each point.
dimension The topological dimension of the mesh, meaning the cell dimension. It can also mean the dimension of the space
in which the mesh is embedded, but this is properly the embedding dimension.
215
216 APPENDIX A. GLOSSARY
fiber dimension Dimension of the space associated with the field. For example, the scalar field has a fiber dimension of 1 and
a vector field has a fiber displacement equal to the dimension of the mesh.
cohesive cell A zero volume cell inserted between any two cells which shared a fault face. They are prisms with a fault face as
the base.
cone The set of entities which cover any entity in a mesh. For example, the cone of a triangle is its three edges.
support The set of mesh entities which are covered by any entity in a mesh. For example, the support of a triangle is the two
tetrahedra it separates.
Appendix B
PyLith and Spatialdata Components
The name of the component is followed by the full path name and description. The full path name is used when setting a
component to a facility in a .cfg file or with command line arguments.
B.1 Application components

PyLithApp pylith.apps.PyLithApp
PyLith application.
B.1.1 Problem Components
TimeDependent pylith.problems.TimeDependent
Time-dependent problem.
GreensFns pylith.problems.GreensFns
Static Green’s function problem with slip impulses.
Implicit pylith.problems.Implicit
Implicit time stepping for static and quasi-static simulations with infinitesimal strains.
ImplicitLgDeform pylith.problems.ImplicitLgDeform
Implicit time stepping for static and quasi-static simulations including the effects of rigid body motion and small strains.
Explicit pylith.problems.Explicit
Explicit time stepping for dynamic simulations with a lumped system Jacobian matrix.
ExplicitLgDeform pylith.problems.ExplicitLgDeform
Explicit time stepping for dynamic simulations including the effects of rigid body motion and small strains with a lumped
system Jacobian matrix.
ExplicitTri3 pylith.problems.ExplicitTri3
Optimized elasticity formulation for linear triangular cells and one quadrature point for explicit time stepping in dynamic
simulations.
ExplicitTet4 pylith.problems.ExplicitTet4
Optimized elasticity formulation for linear tetrahedral cells and one quadrature point for explicit time stepping in dynamic
simulations.
SolverLinear pylith.problems.SolverLinear
Linear PETSc solver (KSP).
217
218 APPENDIX B. PYLITH AND SPATIALDATA COMPONENTS
SolverNonlinear pylith.problems.SolverNonlinear
Nonlinear PETSc solver (SNES).
SolverLumped pylith.problems.SolverLumped
Built-in simple, optimized solver for solving systems with a lumped Jacobian.
TimeStepUniform pylith.problems.TimeStepUniform
Uniform time stepping.
TimeStepAdapt pylith.problems.TimeStepAdapt
Adaptive time stepping (time step selected based on estimated stable time step).
TimeStepUser pylith.problems.TimeStepUser
User defined time stepping (variable time step set by user).
B.1.2 Utility Components
NullComponent pylith.utils.NullComponent
Null component used to set a facility to an empty value.
EventLogger pylith.utils.EventLogger
PETSc event logger.
VTKDataReader pylith.utils.VTKDataReader
Data reader for VTK files, requires TVTK Enthought package available from https://github.com/enthought/
mayavi.
B.1.3 Topology Components
Distributor pylith.topology.Distributor
Distributor of mesh among processors in parallel simulations.
JacobianViewer pylith.topology.JacobianViewer
Viewer for writing Jacobian sparse matrix to file.
MeshGenerator pylith.topology.MeshGenerator
Mesh generator/importer.
MeshImporter pylith.topology.MeshImporter
Mesh importer/reader.
MeshRefiner pylith.topology.MeshRefiner
Default (null) mesh refinement object that does not refine the mesh.
RefineUniform pylith.topology.RefineUniform
Uniform global mesh refinement.
ReverseCuthillMcKee pylith.topology.ReverseCuthillMcKee
Object used to manage reordering cells and vertices using the reverse Cuthill-McKee algorithm.
B.1.4 Material Components
ElasticPlaneStrain pylith.materials.ElasticPlaneStrain
Linearly elastic 2D bulk constitutive model with plane strain (²zz = 0).
ElasticPlaneStress pylith.materials.ElasticPlaneStress
Linearly elastic 2D bulk constitutive model with plane stress (σzz = 0).
B.1. APPLICATION COMPONENTS 219
ElasticIsotropic3D pylith.materials.ElasticIsotropic3D
Linearly elastic 3D bulk constitutive model.
MaxwellIsotropic3D pylith.materials.MaxwellIsotropic3D
Linear Maxwell viscoelastic bulk constitutive model.
MaxwellPlaneStrain pylith.materials.MaxwellPlaneStrain
Linear Maxwell viscoelastic bulk constitutive model for plane strain problems.
GenMaxwellIsotropic3D pylith.materials.GenMaxwellIsotropic3D
Generalized Maxwell viscoelastic bulk constitutive model.
GenMaxwellPlaneStrain pylith.materials.GenMaxwellPlaneStrain
Generalized Maxwell viscoelastic bulk constitutive model for plane strain problems.
PowerLaw3D pylith.materials.PowerLaw3D
Power-law viscoelastic bulk constitutive model.
PowerLawPlaneStrain pylith.materials.PowerLawPlaneStrain
Power-law viscoelastic bulk constitutive model for plane strain problems.
DruckerPrage3D pylith.materials.DruckerPrager3D
Drucker-Prager elastoplastic bulk constitutive model.
DruckerPragePlaneStrain pylith.materials.DruckerPragerPlaneStrain
Drucker-Prager elastoplastic bulk constitutive model for plane strain problems.
Homogeneous pylith.materials.Homogeneous
Container with a single bulk material.
B.1.5 Boundary Condition Components
AbsorbingDampers pylith.bc.AbsorbingDampers
Absorbing boundary condition using simple dashpots.
DirichletBC pylith.bc.DirichletBC
Dirichlet (prescribed displacements) boundary condition for a set of points.
DirichletBoundary pylith.bc.DirichletBoundary
Dirichlet (prescribed displacements) boundary condition for a set of points associated with a boundary surface.
Neumann pylith.bc.Neumann
Neumann (traction) boundary conditions applied to a boundary surface.
PointForce pylith.bc.PointForce
Point forces applied to a set of vertices.
ZeroDispDB pylith.bc.ZeroDispDB
Specialized UniformDB with uniform zero displacements at all degrees of freedom.
B.1.6 Fault Components
FaultCohesiveKin pylith.faults.FaultCohesiveKin
Fault surface with kinematic (prescribed) slip implemented using cohesive elements.
FaultCohesiveDyn pylith.faults.FaultCohesiveDyn
Fault surface with dynamic (friction) slip implemented using cohesive elements.
FaultCohesiveImpulses pylith.faults.FaultCohesiveImpulses
Fault surface with Green’s functions slip impulses implemented using cohesive elements.
EqKinSrc pylith.faults.EqKinSrc
Kinematic (prescribed) slip earthquake rupture.
SingleRupture pylith.faults.SingleRupture
Container with one kinematic earthquake rupture.
StepSlipFn pylith.faults.StepSlipFn
Step function slip-time function.
ConstRateSlipFn pylith.faults.ConstRateSlipFn
Constant slip rate slip-time function.
BruneSlipFn pylith.faults.BruneSlipFn
Slip-time function where slip rate is equal to Brune’s far-field slip function.
LiuCosSlipFn pylith.faults.LiuCosSlipFn
Slip-time function composed of three sine/cosine functions. Similar to Brune’s far-field time function but with more
abrupt termination of slip.
TimeHistorySlipFn pylith.faults.TimeHistorySlipFn
Slip-time function with a user-defined slip time function.
TractPerturbation pylith.faults.TractPerturbation
Prescribed traction perturbation applied to fault with constitituve model in additional to tractions from deformation (gen-
erally used to nucleate a rupture).
B.1.7 Friction Components
StaticFriction pylith.friction.StaticFriction
Static friction fault constitutive model.
SlipWeakening pylith.friction.SlipWeakening
Linear slip-weakening friction fault constitutive model.
RateStateAgeing pylith.friction.RateStateAgeing
Dieterich-Ruina rate and state friction with ageing law state variable evolution.
TimeWeakening pylith.friction.TimeWeakening
Linear time-weakening friction fault constitutive model.
B.1.8 Discretization Components
FIATLagrange pylith.feassemble.FIATLagrange
Finite-element basis functions and quadrature rules for a Lagrange reference finite-element cell (point, line, quadrilateral,
or hexahedron) using FIAT. The basis functions are constructed from the tensor produce of 1D Lagrange reference cells.
FIATSimplex pylith.feassemble.FIATSimplex
Finite-element basis functions and quadrature rules for a simplex finite-element cell (point, line, triangle, or tetrahedron)
using FIAT.
B.1. APPLICATION COMPONENTS 221
B.1.9 Output Components
MeshIOAscii pylith.meshio.MeshIOAscii
Reader for simple mesh ASCII files.
MeshIOCubit pylith.meshio.MeshIOCubit
Reader for CUBIT Exodus files.
MeshIOLagrit pylith.meshio.MeshIOLagrit
Reader for LaGriT GMV/Pset files.
OutputManager pylith.meshio.OutputManager
General output manager for mesh information and data.
OutputSoln pylith.meshio.OutputSoln
Output manager for solution data.
OutputSolnSubset pylith.meshio.OutputSolnSubset
Output manager for solution data over a submesh.
OutputSolnPoints pylith.meshio.OutputSolnPoints
Output manager for solution data at arbitrary points in the domain.
OutputDirichlet pylith.meshio.OutputDirichlet
Output manager for Dirichlet boundary condition information over a submesh.
OutputNeumann pylith.meshio.OutputNeumann
Output manager for Neumann boundary condition information over a submesh.
OutputFaultKin pylith.meshio.OutputFaultKin
Output manager for fault with kinematic (prescribed) earthquake ruptures.
OutputFaultDyn pylith.meshio.OutputFaultDyn
Output manager for fault with dynamic (friction) earthquake ruptures.
OutputFaultImpulses pylith.meshio.OutputFaultImpulses
Output manager for fault with static slip impulses.
OutputMatElastic pylith.meshio.OutputMatElastic
Output manager for bulk constitutive models for elasticity.
SingleOutput pylith.meshio.SingleOutput
Container with single output manger.
PointsList pylith.meshio.PointsList
Manager for text file container points for OutputSolnPoints.
DataWriterVTK pylith.meshio.DataWriterVTK
Writer for output to VTK files.
DataWriterHDF5 pylith.meshio.DataWriterHDF5
Writer for output to HDF5 files.
DataWriterHDF5Ext pylith.meshio.DataWriterHDF5Ext
Writer for output to HDF5 files with datasets written to external raw binary files.
CellFilterAvg pylith.meshio.CellFilterAvg
Filter that averages information over quadrature points of cells.
VertexFilterVecNorm pylith.meshio.VertexFilterVecNorm
Filter that computes magnitude of vectors for vertex fields.
B.2 Spatialdata Components
B.2.1 Coordinate System Components
CSCart spatialdata.geocoords.CSCart
Cartesian coordinate system (1D, 2D, or 3D).
CSGeo spatialdata.geocoords.CSGeo
Geographic coordinate system.
CSGeoProj spatialdata.geocoords.CSGeoProj
Coordinate system associated with a geographic projection.
CSGeoLocalCart spatialdata.geocoords.CSGeoLocalCart
Local, georeferenced Cartesian coordinate system.
Projector spatialdata.geocoords.Projector
Geographic projection.
Converter spatialdata.geocoords.Converter
Converter for transforming coordinates of points from one coordinate system to another.
B.2.2 Spatial database Components
UniformDB spatialdata.spatialdb.UniformDB
Spatial database with uniform values.
SimpleDB spatialdata.spatialdb.SimpleDB
Simple spatial database that defines fields using a point cloud. Values are determined using a nearest neighbor search or
linear interpolation in 0D, 1D, 2D, or 3D.
SimpleIOAscii spatialdata.spatialdb.SimpleIOAscii
Reader/writer for simple spatial database files.
SCECCVMH spatialdata.spatialdb.SCECCVMH
Spatial database interface to the SCEC CVM-H (seismic velocity model).
CompositeDB spatialdata.spatialdb.CompositeDB
Spatial database composed from multiple other spatial databases.
TimeHistory spatialdata.spatialdb.TimeHistory
Time history for temporal variations of a parameter.
GravityField spatialdata.spatialdb.GravityField
Spatial database providing vector for body forces associated with gravity.
B.2.3 Nondimensionalization components
Nondimensional spatialdata.units.Nondimensional
Nondimensionalization of length, time, and pressure scales.
NondimensionalElasticDynamic spatialdata.units.NondimensionalElasticDynamic
Nondimensionalization of scales for dynamic problems.
NondimensionalElasticQuasistatic spatialdata.units.NondimensionalElasticQuasistatic
Nondimensionalization of scales for quasi-static problems.
Appendix C
File Formats
C.1 PyLith Mesh ASCII Files

PyLith mesh ASCII files allow quick specification of the mesh information for very small, simple meshes that are most easily
written by hand. We do not recommend using this format for anything other than these very small, simple meshes.
1 3 5
0 2 4
Figure C.1: Diagram of mesh specified in the MeshIOAscii file.
// This mesh file defines a finite-element mesh composed of two

// square cells of edge length 2.
//
// Comments can appear almost anywhere in these files and are
// delimited with two slashes (//) just like in C++. All text and
// whitespace after the delimiter on a given line is ignored.
mesh = { // begin specification of the mesh

dimension = 2 // spatial dimension of the mesh
// Begin vertex and cell labels with 0. This is the default so

// this next line is optional
use-index-zero = true
vertices = { // vertices or nodes of the finite-element cells

dimension = 2 // spatial dimension of the vertex coordinates
count = 6 // number of vertices in the mesh
coordinates = { // list of vertex index and coordinates
// the coordinates must coincide with the coordinate
// system specified in the Mesh object
// exactly one vertex must appear on each line
// (excluding whitespace)
0 -2.0 -1.0
223
224 APPENDIX C. FILE FORMATS
1 -2.0 +1.0
2 0.0 -1.0
3 0.0 +1.0
4 +2.0 -1.0
5 +2.0 +1.0
} // end of coordinates list
} // end of vertices
cells = { // finite-element cells

count = 2 // number of cells in the mesh
num-corners = 4 // number of vertices defining the cell
simplices = { // list of vertices in each cell
// see Section 4.2 for diagrams giving the order for each
// type of cell supported in PyLith
// index of cell precedes the list of vertices for the cell
// exactly one cell must appear on each line
// (excluding whitespace)
0 0 2 3 1
1 4 5 3 2
} // end of simplices list
material-ids = { // associated each cell with a material model

// the material id is specified using the index of the cell
// and then the corresponding material id
0 0 // cell 0 has a material id of 0
1 2 // cell 1 has a material id of 2
} // end of material-ids list
} // end of cells
// This next section lists groups of vertices that can be used

// in applying boundary conditions to portions of the domain
group = { // start of a group
// the name can have whitespace, so no comments are allowed
// after the name
name = face +y
// Either groups of vertices or groups of cells can be

// specified, but currently PyLith only makes use of groups
// of vertices
type = vertices // ’vertices’ or ’cells’
count = 2 // number of vertices in the group
indices = { // list of vertex indices in the group
// multiple vertices may appear on a line
0 4 // this group contains vertices 0 and 4
} // end of list of vertices
} // end of group
// additional groups can be listed here
C.2 SimpleDB Spatial Database Files

SimpleDB spatial database files contain a header describing the set of points and then the data with each line listing the
coordinates of a point followed by the values of the fields for that point.
// This spatial database specifies the distribution of slip on the
// fault surface. In this case we prescribe a piecewise linear,
// depth dependent distribution of slip. The slip is 2.0 m
// right-lateral with 0.25 m of reverse slip at the surface with
// a linear taper from 2.0 m to 0.0 m from -2 km to -4 km.
//
C.2. SIMPLEDB SPATIAL DATABASE FILES 225
//
// The next line is the magic header for spatial database files
// in ASCII format.
#SPATIAL.ascii 1
SimpleDB { // start specifying the database parameters
num-values = 3 // number of values in the database
// Specify the names and the order of the values as they appear
// in the data. The names of the values must correspond to the
// names PyLith requests in querying the database.
value-names = left-lateral-slip reverse-slip fault-opening
// Specify the units of the values in Python syntax (e.g., kg/m**3).

value-units = m m m
num-locs = 3 // Number of locations where values are given
data-dim = 1 // Locations of data points form a line
space-dim = 3 // Spatial dimension in which data resides
// Specify the coordinate system associated with the

// coordinates of the locations where data is given
cs-data = cartesian { // Use a Cartesian coordinate system
to-meters = 1.0e+3 // Coordinates are in km
// Specify the spatial dimension of the coordinate system

// This value must match the one associated with the database
space-dim = 3
} // cs-data // end of coordinate system specification
} // end of SimpleDB parameters

// The locations and values are listed after the parameters.
// Columns are coordinates of the points (1 column for each
// spatial dimension) followed by the data values in the order
// specified by the value-names field.
0.0 0.0 0.0 -2.00 0.25 0.00
0.0 0.0 -2.0 -2.00 0.00 0.00
0.0 0.0 -4.0 0.00 0.00 0.00
C.2.1 Spatial Database Coordinate Systems
The spatial database files support four different types of coordinate systems. Conversions among the three geographic co-
ordinate systems are supported in 3D. Conversions among the geographic and geographic projected coordinate systems are
supported in 2D. In using the coordinate systems, we assume that you have installed the proj program in addition to the Proj.4
libraries, so that you can obtain a list of support projections, datums, and ellipsoids. Alternatively, refer to the documentation
for the Proj.4 Cartographic Projections library trac.osgeo.org/proj.
C.2.1.1 Cartesian
This is a conventional Cartesian coordinate system. Conversions to other Cartesian coordinate systems are possible.
cs-data = cartesian {
to-meters = 1.0e+3 // Locations in km
space-dim = 2 // 1, 2, or 3 dimensions
}
C.2.1.2 Geographic
This coordinate system is for geographic coordinates, such as longitude and latitude. Specification of the location in three-
dimensions is supported. The vertical datum can be either the reference ellipsoid or mean sea level. The vertical coordinate is
positive upwards.
cs-data = geographic {
// Conversion factor to get to meters (only applies to vertical
// coordinate unless you are using a geocentric coordinate system).
to-meters = 1.0e+3
space-dim = 2 // 2 or 3 dimensions
// Run ‘‘proj -le’’ to see a list of available reference ellipsoids.

// Comments are not allowed at the end of the next line.
ellipsoid = WGS84
// Run ‘‘proj -ld’’ to see a list of available datums.

datum-horiz = WGS84
// ‘‘ellipsoid’’ or ‘‘mean sea level’’

datum-vert = ellipsoid
// Use a geocentric coordinate system?

is-geocentric = false // true or false
}
C.2.1.3 Geographic Projection
This coordinate system applies to geographic projections. As in the geographic coordinate system, the vertical coordinate (if
used) can be specified with respect to either the reference ellipsoid or mean sea level. The coordinate system can use a local
origin and be rotated about the vertical direction.
cs-data = geo-projected {
to-meters = 1.0e+3 // Conversion factor to get to meters.

ellipsoid = WGS84

datum-horiz = WGS84

// Longitude of local origin in WGS84.

origin-lon = -120.0
// Latitude of local origin in WGS84.

origin-lat = 37.0
// Rotation angle in degrees (CCW) or local x-axis from east.

rotation-angle = 23.0
// Run ‘‘proj -lp’’ to see a list of available geographic

// projections.
projector = projection {
C.3. SIMPLEGRIDDB SPATIAL DATABASE FILES 227
// Name of the projection. run ‘‘proj -lp’’ to see a list of
// supported projections. Use the Universal Transverse Mercator
// projection.
projection = utm
units = m // Units in the projection.
// Provide a list of projection options; these are the command

// line arguments you would use with the proj program. Refer to
// the Proj.4 library documentation for complete details.
}
C.2.1.4 Geographic Local Cartesian
This coordinate system is a geographically referenced, local 3D Cartesian coordinate system. This allows use of a conventional
Cartesian coordinate system with accurate georeferencing. For example, one can construct a finite-element model in this
coordinate system and use spatial databases in geographic coordinates. This coordinate system provides an alternative to using
a geographic projection as the Cartesian grip. The advantage of this coordinate system is that it retains the curvature of the
Earth, while a geographic projection does not.
cs-data = geo-local-cartesian {
// Conversion factor to get to meters (only applies to vertical
// coordinate unless you are using a geocentric coordinate system).
to-meters = 1.0 // use meters

ellipsoid = WGS84

datum-horiz = WGS84

// Origin of the local Cartesian coordinate system. To avoid

// round-off errors it is best to pick a location near the center of
// the region of interest. An elevation on the surface of the Earth
// in the middle of the region also works well (and makes the
// vertical coordinate easy to interpret).
origin-lon = -116.7094 // Longitude of the origin in decimal degrees
// (west is negative).
origin-lat = 36.3874 // Latitude of the origin in decimal degrees

// (north is positive).
// Elevation with respect to the vertical datum. Units are the

// same as the Cartesian coordinate system (in this case meters).
origin-elev = 3.5
}
C.3 SimpleGridDB Spatial Database Files

SimpleGridDB spatial database files contain a header describing the grid of points and then the data with each line listing the
coordinates of a point followed by the values of the fields for that point. The coordinates for each dimension of the grid do not
need to be uniformly spaced. The coordinate systems are specified the same way as they are in SimpleDB spatial database files
as described in Section C.2 on page 224.
// This spatial database specifies the elastic properties on a
// 2-D grid in 3-D space.
//
// in ASCII format.
#SPATIAL_GRID.ascii 1
SimpleGridDB { // start specifying the database parameters
num-values = 3 // number of values in the database
// Specify the names and the order of the values as they appear
// in the data. The names of the values must correspond to the
// names PyLith requests in querying the database.
value-names = Vp Vs Density
// Specify the units of the values in Python syntax.

value-units = km/s km/s kg/m{*}{*}3
num-x = 3 // Number of locations along x coordinate direction
num-y = 1 // Number of locations along y coordinate direction
num-z = 2 // Number of locations along z coordinate direction
space-dim = 3 // Spatial dimension in which data resides
// Specify the coordinate system associated with the

// coordinates of the locations where data is given
cs-data = cartesian \{ // Use a Cartesian coordinate system
to-meters = 1.0e+3 // Coordinates are in km
// Specify the spatial dimension of the coordinate system

// This value must match the one associated with the database
space-dim = 3
} // cs-data // end of coordinate system specification
} // end of SimpleGridDB specification
// x coordinates
-3.0 1.0 2.0
// y coordinates
8.0
// z coordinates
2.0 4.0
// The locations and values are listed after the parameters.

// Columns are coordinates of the points (1 column for each
// spatial dimension) followed by the data values in the order
// specified by the value-names field. The points can be in any order.
-3.0 8.0 2.0 6.0 4.0 2500.0
1.0 8.0 2.0 6.2 4.1 2600.0
2.0 8.0 2.0 5.8 3.9 2400.0
-3.0 8.0 4.0 6.1 4.1 2500.0
1.0 8.0 4.0 5.9 3.8 2450.0
2.0 8.0 4.0 5.7 3.7 2400.0
C.4 TimeHistory Database Files

TimeHistory database files contain a header describing the number of points in the time history and the units for the time stamps
followed by a list with pairs of time stamps and amplitude values. The amplitude at an arbitrary point in time is computed via
C.5. USER-SPECIFIED TIME-STEP FILE 229
interpolation of the values in the database. This means that the time history database must span the range of time values of
interest. The points in the time history must also be ordered in time.
// This time history database specifies temporal variation in
// amplitude. In this case we prescribe a triangular slip time
// history.
//
//
// in ASCII format.
#TIME HISTORY ascii
TimeHistory { // start specifying the database parameters
num-points = 5 // number of points in time history
// Specify the units used in the time stamps.

time-units = year
} // end of TimeHistory header
// The time history values are listed after the parameters.
// Columns time and amplitude where the amplitude values are unitless.
0.0 0.00
2.0 1.00
6.0 4.00
10.0 2.00
11.0 0.00
C.5 User-Specified Time-Step File

This file lists the time-step sizes for nonuniform, user-specified time steps associated with the TimeStepUser object. The file’s
format is an ASCII file that includes the units for the time-step sizes and then a list of the time steps.
// This time step file specifies five time steps with the units in years.
//
// Units for the time steps
units = year
1.0 // Comment
2.0
3.0
2.5
3.0
C.6 PointsList File

This file lists the coordinates of the locations where output is requested for the OutputSolnPoints component. The
coordinate system is specified in the OutputSolnPoints component.
# Comments are limited to complete lines. The default delimiter for comments
# is ’#’, which can be changed via parameters. Additionally, the delimiter
# separating values can also be customized (default is whitespace).
#
# The first column is the station name. The coordinates of the points are given
# in the subsequent columns.
P0 1.0 -2.0 0.0
P1 2.0 -4.0 -0.1
P2 0.0 +2.0 0.0
P3 2.5 -0.2 -0.2
P4 0.0 2.0 +0.2
Appendix D
Alternative Material Model Formulations
D.1 Viscoelastic Formulations

The viscoelastic formulations presently used in PyLith are described in Section 5.3 on page 66. In some cases there are
alternative formulations that may be used in future versions of PyLith, and those are described here.
D.1.1 Effective Stress Formulation for a Linear Maxwell Viscoelastic Material
An alternative technique for solving the equations for a Maxwell viscoelastic material is based on the effective stress formulation
described in Section 5.3.4 on page 72. A linear Maxwell viscoelastic material may be characterized by the same elastic
parameters as an isotropic elastic material (E and ν), as well as the viscosity, η. The creep strain increment is
∆t τ S
∆e C = . (D.1)
2η
Therefore,
q
∆t τ J 20 ∆t τ σ 1
∆e C = p = , and τ γ = . (D.2)
3η 3η 2η
Substituting Equations 5.48 on page 72, D.1, and D.2 into 5.45 on page 72, we obtain
∆t £
½ ¾
t +∆t 1 t +∆t 0
(1 − α)t S + αt +∆t S + S I .
¤
S= e − (D.3)
aE 2η
Solving for t +∆t S ,
∆t 1+ν I
· ¸
t +∆t 1 t +∆t 0
S= e − (1 − α)t S + S . (D.4)
a E + α∆t
2η
2η E
In this case it is possible to solve directly for the deviatoric stresses, and the effective stress function approach is not needed.
To obtain the total stress, we simply use
t +∆t 1 ¡ t +∆t
σi j = t +∆t S i j + θ − θ I δi j + P I δi j .
¢
(D.5)
am
To compute the viscoelastic tangent material matrix relating stress and strain, we need to compute the first term in Equa-
tion 5.55 on page 73. From Equation D.4, we have
∂t +∆t S i δi k
= . (D.6)
∂t +∆t e k0 a E + α∆t
2η
231
232 APPENDIX D. ALTERNATIVE MATERIAL MODEL FORMULATIONS
Using this, along with Equations 5.55 on page 73, 5.56 on page 73, and 5.57 on page 73, the final material matrix relating stress
and tensor strain is
   
1 1 1 0 0 0 2 −1 −1 0 0 0

 1 1 1 0 0 0 


 −1 2 −1 0 0 0 

1  1 1 1 0 0 0
 1 
−1 −1 2 0 0 0

C iVj E = + ³ . (D.7)
   
0 0 0 0 0 0 0 0 0 3 0 0
´
 3 a + α∆t 

3a m  
  E 2η  
 0 0 0 0 0 0   0 0 0 0 3 0 
0 0 0 0 0 0 0 0 0 0 0 3
Note that the coefficient of the second matrix approaches E /3(1+ν) = 1/3aE as η goes to infinity. To check the results we make
sure that the regular elastic constitutive matrix is obtained for selected terms in the case where η goes to infinity.
E E (1 − ν)
C 11 =
(1 + ν)(1 − 2ν)
E Eν
C 12 = . (D.8)
(1 + ν)(1 − 2ν)
E E
C 44 =
1+ν
This is consistent with the regular elasticity matrix, and Equation D.7 should thus be used when forming the stiffness matrix.
We do not presently use this formulation, but it may be included in future versions.
Appendix E
Analytical Solutions
E.1 Traction Problems

Computation of analytical solutions for elastostatic problems over regular domains is a relatively straightforward procedure.
These problems are typically formulated in terms of a combination of displacement and traction boundary conditions, and such
problems provide a good test of the code accuracy, as well as specifically testing the implementation of traction boundary
conditions. We present here two simple problems for this purpose.
E.1.1 Solutions Using Polynomial Stress Functions
Our derivation follows the procedures outlined in Timoshenko and Goodier [Timoshenko and Goodier, 1987], and we restrict
ourselves to two-dimensional problems. Any problem in elastostatics must satisfy the equilibrium equations
∂σxx ∂σx y
+ +X =0 (E.1)
∂x ∂y
∂σ y y ∂σx y
+ + Y = 0,
∂y ∂x
where X and Y are the body force components in the x and y directions, respectively, and the stress components are given by σ.
In the problems considered here, we neglect body forces, so X and Y disappear from the equilibrium equations. The solution
must also satisfy the boundary conditions, given as surface tractions over the surface of the body. Finally, the solution must
satisfy the conditions of compatibility, which may be expressed as:
∂2 ∂2 ¡
µ ¶
σxx + σ y y = 0.
¢
+ (E.2)
∂x 2 ∂y 2
To compute the displacement field, it is also necessary to specify displacement boundary conditions.
Equations E.1 may be satisfied by taking any function φ of x and y, and letting the stress components be given by the
following expressions:
∂2 φ ∂2 φ ∂2 φ
σxx = , σ y y = , σ x y = − . (E.3)
∂y 2 ∂x 2 ∂x∂y
The solution must also satisfy the compatibility equations. Substituting Equations E.3 into Equation E.2, we find that the stress
function φ must satisfy
∂4 φ ∂4 φ ∂4 φ
+ 2 + = 0. (E.4)
∂x 4 ∂x 2 ∂y 2 ∂y 4
A relatively easy way to solve a number of problems is to select expressions for φ consisting of polynomial functions of x and
y of second degree or higher. Any polynomial of second or third degree will satisfy Equation E.4. For polynomials of higher
233
234 APPENDIX E. ANALYTICAL SOLUTIONS
degree, they must be substituted into Equation E.4 on the previous page to determine what restrictions must be placed on the
solution.
E.1.2 Constant Traction Applied to a Rectangular Region

→
−
For this problem, a constant normal traction, N , is applied along the positive x-edge of the rectangular region (x = x 0 ), and
roller boundary conditions are applied along the left and bottom boundaries ( E.1). Since the tractions are constant, we assume
a second degree polynomial for the stress function:
a2 2 c2
φ2 = x + b2 x y + y 2 . (E.5)
2 2
This yields the following expressions for the stresses:
∂2 φ2
σxx = = c 2 = N , σ y y = a 2 = 0, σx y = −b 2 = 0. (E.6)
∂y 2
From Hooke’s law, we have:
∂u 1 − ν2 N ∂v −ν (1 + ν) N 1 ∂v ∂u
¡ ¢ µ ¶
²xx = = , ²y y = = , ²x y = + = 0. (E.7)
∂x E ∂y E 2 ∂x ∂y
The strain components are thus easily obtained from the stress components.
To obtain the displacements, we must integrate Equation E.7 and make use of the displacement boundary conditions.
Integrating the first two of these, we obtain
1 − ν2 N x −ν (1 + ν) N y
¡ ¢
¡ ¢
u= +f y , v= + f (x) . (E.8)
E E
Substituting these into the third expression, we obtain
∂ f (x) ∂f y
¡ ¢
=− , (E.9)
∂x ∂y
¡ ¢
which means that both f (x) and f y must be constant. We solve for these constants using the displacement boundary condi-
tions along x = x 0 and y = y 0 . Doing this, we obtain the following expressions for the displacement components:
1 − ν2 N ν (1 + ν) N ¡
¡ ¢
¢
u= (x − x 0 ) , v = y0 − y . (E.10)
E E
Figure E.1: Problem with constant traction boundary conditions applied along right edge.
(x1 , y1 )
(x0 , y0 )
E.1. TRACTION PROBLEMS 235
236 APPENDIX E. ANALYTICAL SOLUTIONS
Appendix F
PyLith Software License
Copyright (C) 2010-2017 University of California, Davis

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation
files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify,
merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED “AS IS,” WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, IN-
CLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LI-
ABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
DEALINGS IN THE SOFTWARE.
237
238 APPENDIX F. PYLITH SOFTWARE LICENSE
Bibliography
[Aagaard et al., 2001a] Aagaard, B.T., J.F. Hall, and T.H. Heaton (2001), Characterization of near-source ground motions with
earthquake simulations, Earthquake Spectra, 17(2), 177-207.
[Aagaard et al., 2001b] Aagaard, B.T., T.H. Heaton, and J.F. Hall (2001), Dynamic earthquake ruptures in the presence of
lithostatic normal stresses: Implications for friction models and heat production, Bulletin of the Seismological
Society of America, 91(6), 1765-1796.
[Aagaard et al., 2007] Aagaard, B., C. Williams, and M. Knepley (2007), PyLith: A finite-element code for modeling quasi-
static and dynamic crustal deformation, Eos Trans. AGU, 88(52), Fall Meet. Suppl., Abstract T21B-0592.
[Aagaard et al., 2008] Aagaard, B., C. Williams, and M. Knepley (2008), PyLith: A finite-element code for modeling quasi-
static and dynamic crustal deformation, Eos Trans. AGU, 89(53), Fall Meet. Suppl., Abstract T41A-1925.
[Bathe, 1995] Bathe, K.-J. (1995), Finite-Element Procedures, Prentice Hall, Upper Saddle River, New Jersey, 1037 pp.
[Ben-Zion and Rice, 1997] Ben-Zion, Y. and J.R. Rice (1997), Dynamic simulations of slip on a smooth fault in an elastic
solid, Journal of Geophysical Research, 102, 17,771–17,784.
[Brune, 1970] Brune, J.N. (1970), Tectonic stress and spectra of seismic shear waves from earthquakes, Journal of Geophysi-
cal Research, 75, 4997-5009.
[Courant et al., 1967] Courant, R., K. Friedrichs and H. Lewy (1967), On the Partial Differential Equations of Mathematical
Physics, IBM Journal of Research and Development, 11(2), 215–234.
[Day and Ely, 2002] Day, S.M. and G.P. Ely (2002), Effct of a shallow weak zone on fault rupture: Numerical simulation of
scale-model experiments, Bull. Seismol. Soc. Am., 92(8), 3022-3041, doi: 10.1785/0120010273.
[Drucker and Prager, 1952] Drucker, D. C. and Prager, W. (1952). Soil mechanics and plastic analysis for limit design, Quar-
terly of Applied Mathematics, 10, 157–165.
[Liu et al., 2006] Liu, P., R.J. Archuleta, S.H. Hartzell (2006), Prediction of broadband ground-motion time histories: Hybrid
low/high-frequency method with correlated random source parameters, Bull. Seismol. Soc. Am., 96, 2118-2130.
[Kaneko et al., 2008] Kaneko, Y., N. Lapusta, and J.-P. Ampuero (2008), Spectral element modeling of spontaneous earth-
quake rupture on rate and state faults: Effect of velocity-strengthening friction at shallow depths, Journal of
Geophysical Research, 113, B09317, doi:10.1029/2007JB005553.
[Kaus et al., 2010] Kaus, B. J. P., H. Muhlhaus, and D. A. May (2010), A stabilization algorithm for geodynamic
numerical simulations with a free surface, Physics of the Earth and Planetary Interiors, 181, 12-20,
doi:10.1016/j.pepi.2010.04.007.
[Kirby and Kronenberg, 1987] Kirby, S. H. and A. K. Kronenberg (1987), Rheology of the lithosphere: Selected topics, Re-
views of Geophysics, 25, 1219-1244.
[Knopoff and Ni, 2001] Knopoff, L. and X.X. Ni (2001), Numerical instability at the edge of a dynamic fracture, Geophysical
Journal International, 147(3), 1-6, doi: 10.1046/j.1365-246x.2001.01567.x.
239
240 BIBLIOGRAPHY
[Kojic and Bathe, 1987] Kojic, M. and K.-J. Bathe (1987), The ‘Effective Stress-Function’ Algorithm for Thermo-Elasto-
Plasticity and Creep, Int. J. Num. Meth. Eng., 24, 1509-1532.
[McGarr, 1988] McGarr, A. (1988), On the state of lithospheric stress in the absence of applied tectonic forces, Journal of
Geophysical Research, 93, 13,609-13,617.
[Menke, 1984] Menke, W. (1984), Geophysical Data Analysis: Discrete Inverse Theory, Academic Press, Inc., Orlando, 260
pp.
[Okada, 1992] Okada, Y., Internal deformation due to shear and tensile faults in a half-space (1992), Bull. Seismol. Soc. Am.,
83, 1018-1040.
[Paterson, 1994] Paterson, W. S. B. (1994), The Physics of Glaciers, Third Edition, Elsevier Science Ltd., Oxford, 480 pp.
[Prentice, 1968] Prentice, J. H, (1968), Dimensional problem of the power law in rheology, Nature, 217, 157.
[Savage and Prescott, 1978] Savage, J. C. and W. H. Prescott (1978), Asthenosphere readjustment and the earthquake cycle,
Journal of Geophysical Research, 83, 3369-3376.
[Taylor, 2003] Taylor, R.L. (2003), ‘FEAP–A Finite Element Analysis Program’, Version 7.5 Theory Manual, 154 pp.
[Timoshenko and Goodier, 1987] Timoshenko, S.P. and J.N. Goodier (1987), Theory of Elasticity, Third Edition, McGraw-Hill,
New York, 567 pp.
[Williams et al., 2005] Williams, C.A., B. Aagaard, and M.G. Knepley (2005), Development of software for studying earth-
quakes across multiple spatial and temporal scales by coupling quasi-static and dynamic simulations, Eos Trans.
AGU, 86(52), Fall Meet. Suppl., Abstract S53A-1072.
[Williams, 2006] Williams, C.A. (2006), Development of a package for modeling stress in the lithosphere, Eos Trans. AGU,
87(36), Jt. Assem. Suppl., Abstract T24A-01 Invited.
[Zienkiewicz and Taylor, 2000] Zienkiewicz, O.C. and R.L. Taylor (2000), The Finite Element Method, Fifth Edition, Volume
2: Solid Mechanics, Butterworth-Heinemann, Oxford, 459 pp.125

Pylith-2.2.0 Manual

Uploaded by

Copyright:

Available Formats

Pylith-2.2.0 Manual

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Pylith-2.2.0 Manual

Uploaded by

Copyright:

Available Formats

COMPUTATIONAL INFRASTRUCTURE FOR GEODYNAMICS (CIG)

©University of California, Davis

March 31, 2017

3 Installation and Getting Help 17

6 Boundary and Interface Conditions 83

9 Extending PyLith 209

B PyLith and Spatialdata Components 217

C File Formats 223

D Alternative Material Model Formulations 231

E Analytical Solutions 233

F PyLith Software License 237

1.1 Workflow involved in going from geologic structure to problem analysis. . . . . . . . . . . . . . . . . . . . . . . . 2

8.1 Geometry of strike-slip benchmark problem. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198

2.1 Mathematical notation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

4.1 Pyre supported units. Aliases are in parentheses. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

6.1 Fields available in output of DirichletBoundary boundary condition information. . . . . . . . . . . . . . . . . . . 85

0.1 About This Document

0.2 Who Will Use This Documentation

0.3.1 Command Line Arguments

Exmaple of a command line argument: --help.

Example of filenames and directories: pylith, /usr/local.

0.3.3 Unix Shell Commands

0.3.4 Excerpts of cfg Files

Example of an excerpt from a .cfg file:

To cite the software and manual, use:

0.7 Request for Comments

1.2 New in PyLith Version 2.2.0

1.4 PyLith Workflow

Gocad CUBIT PyLith ParaView

Earth Vision LaGriT Relax Visit

TetGen GeoFEST Matlab

Gmsh Abaqus Matplotlib

Open Source Commercial Planned

PETSc spatialdata FIAT

NetCDF HDF5 Proj.4 Pyre numpy

Table 2.1: Mathematical notation

2.1 Derivation of Elasticity Equation

2.1.1 Index Notation

The traction vector field is related to the stress tensor through

where n j is the vector normal to S . Substituting into equation 2.1 yields

2.1.2 Vector Notation

The traction vector field is related to the stress tensor through

Applying the divergence theorem, Z Z

2.2 Finite-Element Formulation of Elasticity Equation

2.2.1 Index Notation

We start with the wave equation (strong form),

Expanding the left-hand side yields

Substituting into the weak form gives

and recognize that

We want to solve this equation for the unknown coefficients a im subject to

2.2.2 Vector Notation

We start with the wave equation (strong form),

We separate the integration over S into integration over S T and S u ,

and recognize that

so that the equation reduces to

r in = − σi j (x q , t + ∆t )N,nj (x q ) w q |J cel l (x q )| + f i (x q , t + ∆t )N n (x q ) w q |J cel l (x q )|

Isolating the term associated with the increment in stresses yields

Now, d σi j φi , j is a scalar, so it is symmetric,

2.4 Solution Method for Dynamic Problems