Preface
About This Document
Who Will Use This Documentation
Conventions
Command Line Arguments
Filenames and Directories
Unix Shell Commands
Excerpts of cfg Files
Citation
Support
Acknowledgments
Request for Comments
Introduction
Overview
New in PyLith Version 2.2.1
History
PyLith Workflow
PyLith Design
Pyre
PETSc
Governing Equations
Derivation of Elasticity Equation
Index Notation
Vector Notation
Finite-Element Formulation of Elasticity Equation
Index Notation
Vector Notation
Solution Method for Quasi-Static Problems
Solution Method for Dynamic Problems
Small (Finite) Strain Formulation
Quasi-static Problems
Dynamic Problems
Installation and Getting Help
Installation of Binary Executable
Linux and Mac OS X (Darwin)
Windows 10
Extending PyLith and/or Integrating Other Software Into PyLith
Installation of PyLith Docker Container
Setup (first time only)
Run Unix shell within Docker to use PyLith.
Using Docker containers
Copy data to/from persistent storage volume.
Docker Quick Reference
Installation from Source
Verifying PyLith is Installed Correctly
Configuration on a Cluster
Launchers and Schedulers
Running without a Batch System
Using a Batch System
LSF Batch System
PBS Batch System
Getting Help and Reporting Bugs
Running PyLith
Defining the Simulation
Setting PyLith Parameters
Units
Using the Command Line
Using a .cfg File
Using a .pml File
Specification and Placement of Configuration Files
List of PyLith Parameters (pylithinfo)
Mesh Information (mesher)
Mesh Importer
MeshIOAscii
MeshIOCubit
MeshIOLagrit
Distributor
Refiner
Problem Specification (blueproblem)
Nondimensionalization (bluenormalizer)
Finite-Element Integration Settings
PETSc Settings (bluepetsc)
Model Verification with PETSc Direct Solvers
Time-Dependent Problem (formulation)
Time-Stepping Formulation
Numerical Damping in Explicit Time Stepping
Solvers
Time Stepping
Uniform, User-Specified Time Step (TimeStepUniform)
Nonuniform, User-Specified Time Step (TimeStepUser)
Nonuniform, Automatic Time Step (TimeStepAdapt)
Green's Functions Problem (GreensFns)
Progress Monitors
ProgressMonitorTime
ProgressMonitorStep
Databases for Boundaries, Interfaces, and Material Properties
SimpleDB Spatial Database
UniformDB Spatial Database
ZeroDispDB
SimpleGridDB Spatial Database
SCEC CVM-H Spatial Database (SCECCVMH)
CompositeDB Spatial Database
TimeHistory Database
Labels and Identifiers for Materials, Boundary Conditions, and Faults
PyLith Output
Output Manager
Output Over Subdomain
Output at Arbitrary Points
PointsList Reader
Output Field Filters
Vertex Field Filters
Cell Field Filters
VTK Output (DataWriterVTK)
HDF5/Xdmf Output (DataWriterHDF5, DataWriterHDF5Ext)
Parameters
HDF5 Utilities
Tips and Hints
Tips and Hints For Running PyLith
Troubleshooting
Import Error and Missing Library
Unrecognized Property 'p4wd'
Detected zero pivor in LU factorization
Bus Error
Segmentation Fault
Post-Processing Utilities
pylith_eqinfo
pylith_genxdmf
PyLith Parameter Viewer
Installation
Running the Parameter Viewer
Generate the parameter JSON file
Start the web server
Using the Parameter Viewer
Version Information
Parameter Information
Material Models
Specifying Material Properties
Setting the Material Identifier
Material Property Groups
Material Parameters
Initial State Variables
Specification of Initial State Variables
Cauchy Stress Tensor and Second Piola-Kirchoff Stress Tensor
Stable time step
Elastic Material Models
2D Elastic Material Models
Elastic Plane Strain
Elastic Plane Stress
3D Elastic Material Models
Isotropic
Viscoelastic Materials
Definitions
Linear Viscoelastic Models
Formulation for Generalized Maxwell Models
Effective Stress Formulations for Viscoelastic Materials
Power-Law Maxwell Viscoelastic Material
Elastoplastic Materials
General Elastoplasticity Formulation
Drucker-Prager Elastoplastic Material
Drucker-Prager Elastoplastic With No Hardening (Perfectly Plastic)
Boundary and Interface Conditions
Assigning Boundary Conditions
Creating Sets of Vertices
Arrays of Boundary Condition Components
Time-Dependent Boundary Conditions
Dirichlet Boundary Conditions
Dirichlet Boundary Condition Spatial Database Files
Neumann Boundary Conditions
Neumann Boundary Condition Spatial Database Files
Point Force Boundary Conditions
Point Force Parameters
Point Force Spatial Database Files
Absorbing Boundary Conditions
Finite-Element Implementation of Absorbing Boundary
Fault Interface Conditions
Conventions
Fault Implementation
Fault Parameters
Kinematic Earthquake Rupture
Governing Equations
Arrays of Kinematic Rupture Components
Kinematic Rupture Parameters
Slip Time Function
Dynamic Earthquake Rupture
Governing Equations
Dynamic Rupture Parameters
Fault Constitutive Models
Slip Impulses for Green's Functions
Gravitational Body Forces
Examples
Overview
Prerequisites
Input Files
ParaView Python Scripts
Overriding Default Parameters
Examples Using Two Triangles
Overview
Mesh Description
Additional Common Information
Axial Displacement Example
Shear Displacement Example
Kinematic Fault Slip Example
Example Using Two Quadrilaterals
Overview
Mesh Description
Additional Common Information
Axial Displacement Example
Shear Displacement Example
Kinematic Fault Slip Example
Axial Traction Example
Example Using Two Tetrahedra
Overview
Mesh Description
Additional Common Information
Axial Displacement Example
Kinematic Fault Slip Example
Example Using Two Hexahedra
Overview
Mesh Description
Additional Common Information
Axial Displacement Example
Shear Displacement Example
Kinematic Fault Slip Example
Example Using Two Tetrahedra with Georeferenced Coordinate System Mesh
Overview
Mesh Description
Additional Common Information
Kinematic Fault Slip Example
Example Using Tetrahedral Mesh Created by LaGriT
Overview
Mesh Generation and Description
Additional Common Information
Shear Displacement Example
Alternative Solver and Discretization Settings
Kinematic Fault Slip Example
Alternative Solver and Discretization Settings
Examples Using Hexahedral Mesh Created by CUBIT/Trelis
Overview
Mesh Generation and Description
Additional Common Information
Example Problems
Static Examples
Overview
Step01 - Pure Dirichlet Boundary Conditions
Step02 - Dirichlet and Neumann Boundary Conditions
Step03 - Dirichlet Boundary Conditions with Kinematic Fault Slip
Quasi-Static Examples
Overview
Step04 - Pure Dirichlet Velocity Boundary Conditions
Step05 - Time-Varying Dirichlet and Neumann Boundary Conditions
Step06 - Dirichlet Boundary Conditions with Time-Dependent Kinematic Fault Slip
Step07 - Dirichlet Velocity Boundary Conditions with Time-Dependent Kinematic Fault Slip
Step08 - Dirichlet Velocity Boundary Conditions with Time-Dependent Kinematic Fault Slip and Power-Law Rheology
Step09 - Dirichlet Velocity Boundary Conditions with Time-Dependent Kinematic Fault Slip and Drucker-Prager Elastoplastic Rheology
Fault Friction Examples
Overview
Step10 - Static Friction (Stick) with Static Dirichlet Boundary Conditions
Step11 - Static Friction (Slip) with Static Dirichlet Boundary Conditions
Step12 - Static Friction with Quasi-Static Dirichlet Boundary Conditions
Step13 - Slip-Weakening Friction with Quasi-Static Dirichlet Boundary Conditions
Step14 - Rate-and-State Friction with Quasi-Static Dirichlet Boundary Conditions
Gravitational Body Force Examples
Overview
Step15 - Gravitational Body Forces
Step16 - Gravitational Body Forces with Initial Stresses
Step17 - Gravitational Body Forces with Small Strain
Surface Load Traction Examples
Overview
Step18 - Static Surface Load
Step19 - Time-Dependent Surface Load
Dike Intrusion Example
Overview
Step20 - Static Dike Intrusion
Green's Functions Generation Example
Overview
Step21 - Green's Function Generation
Example for Slip on a 2D Subduction Zone
Overview
Mesh Description
Common Information
Step 1: Coseismic Slip Simulation
Step 2: Interseismic Deformation Simulation
Step 3: Pseudo-Earthquake Cycle Model
Step 4: Frictional Afterslip Simulation
Step 5: Spontaneous Earthquakes With Slip-Weakening Friction
Step 6: Spontaneous Earthquakes With Rate-State Friction
Exercises
Shear Wave in a Bar
2D Bar Discretized with Triangles
Mesh Generation
Simulation Parameters
3D Bar Discretized with Quadrilaterals
Mesh Generation
Kinematic Fault (Prescribed Slip)
Dynamic Fault (Spontaneous Rupture)
Dynamic Fault with Static Friction
Dynamic Fault with Slip-Weakening Friction
Dynamic Fault with Rate-State Friction
3D Bar Discretized with Tetrahedra
Mesh Generation
Simulation Parameters
3D Bar Discretized with Hexahedra
Mesh Generation
Simulation Parameters
Example Generating and Using Green's Functions in Two Dimensions
Overview
Mesh Description
Additional Common Information
Step 1: Solution of the Forward Problem
Step 2: Generation of Green's Functions
Step 3: Simple Inversion Using PyLith-generated Green's Functions
Step 4: Visualization of Estimated and True Solutions
Example Using Gravity and Finite Strain in Two Dimensions
Overview
Problem Description
Additional Common Information
Step 1: Gravitational Body Forces and Infinitesimal Strain
Step 2: Gravitational Body Forces, Infinitesimal Strain, and Initial Stresses
Step 3: Infinitesimal Strain Simulation with Initial Stresses and a Local Density Variation
Step 4: Postseismic Relaxation with Infinitesimal Strain
Step 5: Postseismic Relaxation with Finite Strain
Step 6: Postseismic Relaxation with Infinitesimal Strain and Gravitational Body Forces
Step 7: Postseismic Relaxation with Finite Strain and Gravitational Body Forces
Step 8: Postseismic Relaxation with Finite Strain, Gravitational Body Forces, and Variable Density
Exercises
Examples for a 3D Subduction Zone
Overview
Features Illustrated
Generating the Finite-Element Mesh
Visualizing the Mesh
Organization of Simulation Parameters
Coordinate system
Materials
Boundary Conditions
Solver Parameters
Step 1: Axial Compression
Exercises
Step 2: Prescribed Coseismic Slip and Postseismic Relaxation
Exercises
Step 3: Prescribed Aseismic Creep and Interseismic Deformation
Exercises
Step 4: Prescribed Earthquake Cycle
Exercises
Step 5: Spontaneous Rupture Driven by Subducting Slab
Step 6: Prescribed Slow-Slip Event
Exercises
Step 7: Inversion of Slow-Slip Event using 3-D Green's Functions
Exercises
Step 8: Stress Field Due to Gravitational Body Forces
Step 08a
Step 8b
Step 8c
Exercises
Additional Examples
CUBIT Meshing Examples
Debugging Examples
Code Verification Benchmarks
Benchmarks
Overview
Strike-Slip Benchmark
Problem Description
Running the Benchmark
Benchmark Results
Solution Accuracy
Performance
Savage and Prescott Benchmark
Problem Description
Running the Benchmark
Benchmark Results
SCEC Dynamic Rupture Benchmarks
Extending PyLith
Spatial Databases
Bulk Constitutive Models
Fault Constitutive Models
Glossary
Pyre
DMPlex
PyLith and Spatialdata Components
Application components
Problem Components
Utility Components
Topology Components
Material Components
Boundary Condition Components
Fault Components
Friction Components
Discretization Components
Output Components
Spatialdata Components
Coordinate System Components
Spatial database Components
Nondimensionalization components
File Formats
PyLith Mesh ASCII Files
SimpleDB Spatial Database Files
Spatial Database Coordinate Systems
Cartesian
Geographic
Geographic Projection
Geographic Local Cartesian
SimpleGridDB Spatial Database Files
TimeHistory Database Files
User-Specified Time-Step File
PointsList File
Alternative Material Model Formulations
Viscoelastic Formulations
Effective Stress Formulation for a Linear Maxwell Viscoelastic Material
Analytical Solutions
Traction Problems
Solutions Using Polynomial Stress Functions
Constant Traction Applied to a Rectangular Region
PyLith Software License