Merge pull request #486 from geodynamics/baagaard/update-examples-3ds…

…ubduction Update examples/subduction-3d (steps 1-4) for v3.0
geodynamics · Jun 19, 2022 · 56a0c33 · 56a0c33
2 parents 37a2ac7 + ee40272
commit 56a0c33
Show file tree

Hide file tree

Showing 134 changed files with 7,151 additions and 1,112 deletions.
diff --git a/.gitignore b/.gitignore
@@ -25,12 +25,11 @@ autom4te.cache
 /build
 /dist
 output/
-examples/3d/subduction/mesh/geometry_surfs.jou
-examples/3d/subduction/mesh/*.exo
-examples/3d/subduction/mesh/*.sat
-examples/3d/subduction/spatialdb/fault_slabtop_slowslip.spatialdb
-examples/3d/subduction/spatialdb/fault_slabtop_slowslip.timedb
-examples/3d/subduction/spatialdb/mat_initial_stress_grav-*.spatialdb
+examples/subduction-3d/scratch/*.spatialdb
+examples/subduction-3d/scratch/*.sat
+examples/subduction-3d/scratch/*.txt
+examples/subduction-3d/scratch/*.jou
+examples/subduction-3d/input/*.exo
 /docs/_build/
 /doc-latex/userguide/userguide.pdf
 /doc-latex/userguide/userguide.aux

diff --git a/README.md b/README.md
@@ -8,7 +8,7 @@
 ## Description
 
 PyLith is an open-source finite-element code for dynamic and
-quasistatic simulations of crustal deformation, primarily earthquakes
+quasi-static simulations of crustal deformation, primarily earthquakes
 and volcanoes.
 
 * Main page: [https://geodynamics.org/resources/pylith](https://geodynamics.org/resources/pylith)

diff --git a/docs/Makefile.am b/docs/Makefile.am
@@ -392,6 +392,34 @@ dist_noinst_DATA = \
     user/examples/subduction-2d/figs/step03-diagram.svg \
     user/examples/subduction-2d/figs/step03-solution.jpg \
     user/examples/subduction-3d/index.md \
+    user/examples/subduction-3d/common-information.md \
+    user/examples/subduction-3d/exercises.md \
+    user/examples/subduction-3d/meshing-cubit.md \
+    user/examples/subduction-3d/step01-axialdisp.md \
+    user/examples/subduction-3d/step02-coseismic.md \
+    user/examples/subduction-3d/step03-interseismic.md \
+    user/examples/subduction-3d/step04-eqcycle.md \
+    user/examples/subduction-3d/figs/cascadia.png \
+    user/examples/subduction-3d/figs/conceptualmodel.png \
+    user/examples/subduction-3d/figs/cubit-geometry-patch.png \
+    user/examples/subduction-3d/figs/cubit-geometry.png \
+    user/examples/subduction-3d/figs/cubit-mesh.jpg \
+    user/examples/subduction-3d/figs/diagrams.tex \
+    user/examples/subduction-3d/figs/generate.sh \
+    user/examples/subduction-3d/figs/step01-diagram.pdf \
+    user/examples/subduction-3d/figs/step01-diagram.svg \
+    user/examples/subduction-3d/figs/step01-solution.jpg \
+    user/examples/subduction-3d/figs/step02-diagram.pdf \
+    user/examples/subduction-3d/figs/step02-diagram.svg \
+    user/examples/subduction-3d/figs/step02-solution.jpg \
+    user/examples/subduction-3d/figs/step03-diagram.pdf \
+    user/examples/subduction-3d/figs/step03-diagram.svg \
+    user/examples/subduction-3d/figs/step03-solution.jpg \
+    user/examples/subduction-3d/figs/step04-diagram.pdf \
+    user/examples/subduction-3d/figs/step04-diagram.svg \
+    user/examples/subduction-3d/figs/step04-solution.jpg \
+    user/examples/subduction-3d/figs/step06-diagram.pdf \
+    user/examples/subduction-3d/figs/step06-diagram.svg \
     user/examples/examples-other.md \
     user/examples/index.md \
     user/examples/paraview-python.md \

diff --git a/docs/intro/development-plan.md b/docs/intro/development-plan.md
@@ -2,7 +2,7 @@
 
 Future implementation of features is guided by several target applications, including
 
-* Earthquake cycle modeling with quasistatic simulation of interseismic deformation and dynamic simulation of coseismic deformation.
+* Earthquake cycle modeling with quasi-static simulation of interseismic deformation and dynamic simulation of coseismic deformation.
 * Inversion of geodetic data for slow slip events, fault creep, and long-term fault slip rates.
 * Quasistatic and dynamic modeling of fluids and faulting.
 

diff --git a/docs/user/examples/box-2d/step01_axialdisp-synopsis.md b/docs/user/examples/box-2d/step01_axialdisp-synopsis.md
@@ -9,6 +9,6 @@
 * spatialdata.spatialdb.UniformDB
 * pylith.meshio.DataWriterHDF5
 * Static simulation
-* ILU preconditioner
+* LU preconditioner
 * pylith.bc.DirichletTimeDependent
 * spatialdata.spatialdb.ZeroDB
diff --git a/docs/user/examples/box-2d/step02_sheardisp-synopsis.md b/docs/user/examples/box-2d/step02_sheardisp-synopsis.md
@@ -9,6 +9,6 @@
 * spatialdata.spatialdb.UniformDB
 * pylith.meshio.DataWriterHDF5
 * Static simulation
-* ILU preconditioner
+* LU preconditioner
 * pylith.bc.DirichletTimeDependent
 * spatialdata.spatialdb.SimpleDB
diff --git a/docs/user/examples/box-2d/step03_sheardisptract-synopsis.md b/docs/user/examples/box-2d/step03_sheardisptract-synopsis.md
@@ -9,7 +9,7 @@
 * spatialdata.spatialdb.UniformDB
 * pylith.meshio.DataWriterHDF5
 * Static simulation
-* ILU preconditioner
+* LU preconditioner
 * pylith.bc.DirichletTimeDependent
 * pylith.bc.NeumannTimeDependent
 * spatialdata.spatialdb.SimpleDB
diff --git a/docs/user/examples/box-2d/step04_sheardispic-synopsis.md b/docs/user/examples/box-2d/step04_sheardispic-synopsis.md
@@ -9,7 +9,7 @@
 * spatialdata.spatialdb.UniformDB
 * pylith.meshio.DataWriterHDF5
 * Static simulation
-* ILU preconditioner
+* LU preconditioner
 * pylith.problems.InitialConditionDomain
 * pylith.bc.DirichletTimeDependent
 * spatialdata.spatialdb.SimpleDB

diff --git a/docs/user/examples/box-2d/step05_sheardisptractrate-synopsis.md b/docs/user/examples/box-2d/step05_sheardisptractrate-synopsis.md
@@ -8,9 +8,9 @@
 * pylith.materials.IsotropicLinearElasticity
 * spatialdata.spatialdb.UniformDB
 * pylith.meshio.DataWriterHDF5
-* Quasistatic simulation
+* Quasi-static simulation
 * backward Euler time stepping
-* ILU preconditioner
+* LU preconditioner
 * pylith.bc.DirichletTimeDependent
 * pylith.bc.NeumannTimeDependent
 * spatialdata.spatialdb.SimpleDB
diff --git a/docs/user/examples/box-3d/step01_axialdisp-synopsis.md b/docs/user/examples/box-3d/step01_axialdisp-synopsis.md
@@ -10,6 +10,6 @@
 * pylith.meshio.OutputSolnBoundary
 * pylith.meshio.DataWriterHDF5
 * Static simulation
-* ILU preconditioner
+* LU preconditioner
 * pylith.bc.DirichletTimeDependent
 * spatialdata.spatialdb.ZeroDB
diff --git a/docs/user/examples/box-3d/step02_sheardisp-synopsis.md b/docs/user/examples/box-3d/step02_sheardisp-synopsis.md
@@ -10,7 +10,7 @@
 * pylith.meshio.OutputSolnBoundary
 * pylith.meshio.DataWriterHDF5
 * Static simulation
-* ILU preconditioner
+* LU preconditioner
 * pylith.bc.DirichletTimeDependent
 * spatialdata.spatialdb.SimpleDB
 * spatialdata.spatialdb.ZeroDB
diff --git a/docs/user/examples/box-3d/step03_sheardisptract-synopsis.md b/docs/user/examples/box-3d/step03_sheardisptract-synopsis.md
@@ -10,7 +10,7 @@
 * pylith.meshio.OutputSolnBoundary
 * pylith.meshio.DataWriterHDF5
 * Static simulation
-* ILU preconditioner
+* LU preconditioner
 * pylith.bc.DirichletTimeDependent
 * pylith.bc.NeumannTimeDependent
 * spatialdata.spatialdb.SimpleDB

diff --git a/docs/user/examples/box-3d/step04_sheardispic-synopsis.md b/docs/user/examples/box-3d/step04_sheardispic-synopsis.md
@@ -10,7 +10,7 @@
 * pylith.meshio.OutputSolnBoundary
 * pylith.meshio.DataWriterHDF5
 * Static simulation
-* ILU preconditioner
+* LU preconditioner
 * pylith.problems.InitialConditionDomain
 * pylith.bc.DirichletTimeDependent
 * spatialdata.spatialdb.SimpleDB

diff --git a/docs/user/examples/box-3d/step05_sheardisptractrate-synopsis.md b/docs/user/examples/box-3d/step05_sheardisptractrate-synopsis.md
@@ -9,9 +9,9 @@
 * spatialdata.spatialdb.UniformDB
 * pylith.meshio.OutputSolnBoundary
 * pylith.meshio.DataWriterHDF5
-* Quasistatic simulation
+* Quasi-static simulation
 * backward Euler time stepping
-* ILU preconditioner
+* LU preconditioner
 * pylith.bc.DirichletTimeDependent
 * pylith.bc.NeumannTimeDependent
 * spatialdata.spatialdb.SimpleDB

diff --git a/docs/user/examples/index.md b/docs/user/examples/index.md
@@ -13,7 +13,7 @@ In some cases, a later step may make use of output from an earlier step; these c
 
 | **Example Suite**                         | **Difficulty** | **Description** |
 |:------------------------------------------|:------------:|:---------------------------------------------------------------------------------------------|
-| [`box-2d`](box-2d/index.md)               | novice       | Simple axial and shear deformation in static and quasistatic simulations in 2D box with a mesh in an ASCII text file.
+| [`box-2d`](box-2d/index.md)               | novice       | Simple axial and shear deformation in static and quasi-static simulations in 2D box with a mesh in an ASCII text file.
 | [`box-3d`](box-3d/index.md)               | novice       | Same as `2d/box` but with a 3D box and a mesh from Gmsh or Cubit.
 | [`strikeslip-2d`](strikeslip-2d/index.md) | beginner     | Prescribed coseismic slip and multiple earthquake ruptures in 2D with a mesh from Gmsh or Cubit.
 | [`reverse-2d`](reverse-2d/index.md)       | beginner     | Gravity, surface loads, and prescribed coseismic slip on multiple reverse faults in 2D with a mesh from Gmsh or Cubit.

diff --git a/docs/user/examples/magma-2d/common-information.md b/docs/user/examples/magma-2d/common-information.md
@@ -12,7 +12,7 @@ The settings contained in `pylithapp.cfg` for this problem consist of:
 * `pylithapp.problem` Parameters that define the boundary value problem and it solution, such as the type of solver, solution fields.
 * `pylithapp.problem.materials` Paramters that specify the governing equation and bulk rheologies.
 
-These quasistatic simulations solve the poroelasticity equation, so we have a solution field with  displacement, pressure, and volumetric strain subfields.
+These quasi-static simulations solve the poroelasticity equation, so we have a solution field with  displacement, pressure, and volumetric strain subfields.
 We specify a basis order of 2 for the displacement subfield, and 1 for each of the remaining subfields.
 
 We use the material properties in all of the simulations in this directory, so we specify them in `pylithapp.cfg` to avoid repeating the information in the file with parameters for each simulation.
diff --git a/docs/user/examples/magma-2d/step01-inflation.md b/docs/user/examples/magma-2d/step01-inflation.md
@@ -119,7 +119,7 @@ At the beginning of the output written to the terminal, we see that PyLith is re
 The scales for nondimensionalization .
 PyLith detects the use of poroelasticity without a fault and selects appropriate preconditioning options as discussed in {ref}`sec-user-run-pylith-petsc-options`.
 
-At the end of the output written to the termial, we see that the solver advanced the solution 51 time steps.
+At the end of the output written to the terminal, we see that the solver advanced the solution 51 time steps.
 At each time step, the linear converges in 1 iteration and the norm of the residual met the absolute convergence tolerance (`ksp_atol`) .
 The nonlinear solve converged in 1 iteration, which we expect because this is a linear problem, and the residual met the absolute convergence tolerance (`snes_atol`).
 

diff --git a/docs/user/examples/paraview-python.md b/docs/user/examples/paraview-python.md
@@ -11,7 +11,7 @@ The primary advantage of the ParaView Python scripts is that they make it easy t
 
 There are several different ways to run the ParaView Python scripts:
 
-* Within the ParaView GUI, select `View`&#8594;`Python Shell`.
+* Within the ParaView GUI, select `View`$\rightarrow$`Python Shell`.
 Override the default parameters as desired (which we will discuss later in this section).
 Click on the `Run Script` button, and navigate to the select the script you want to run.
 * From a shell (terminal window) start ParaView from the command line with the `--script=FILENAME` where `FILENAME` is the relative or absolute path to the ParaView Python script.

diff --git a/docs/user/examples/reverse-2d/common-information.md b/docs/user/examples/reverse-2d/common-information.md
@@ -12,7 +12,7 @@ The settings contained in `pylithapp.cfg` for this problem consist of:
 * `pylithapp.problem.materials` Paramters that specify the governing equation and bulk rheologies.
 * `pylithapp.problem.bc` Boundary condition parameters common aomong the simulations in this directory.
 
-These static and quasistatic simulations solve the elasticity equation.
+These static and quasi-static simulations solve the elasticity equation.
 We use the default solution field (displacement); we will override this for the simulations with a fault.
 
 We use the same material properties for several simulations in this directory, so we specify them in `pylithapp.cfg` to avoid repeating the information in the file with parameters for each simulation.

diff --git a/docs/user/examples/reverse-2d/step01-gravity.md b/docs/user/examples/reverse-2d/step01-gravity.md
@@ -110,7 +110,7 @@ At the beginning of the output written to the terminal, we see that PyLith is re
 The output also shows the scales for nondimensionalization and the PETSc options selected by PyLith.
 This simulation did not use a fault, so PyLith used the LU preconditioner.
 
-At the end of the output written to the termial, we see that the solver advanced the solution one time step (static simulation).
+At the end of the output written to the terminal, we see that the solver advanced the solution one time step (static simulation).
 The linear solve converged after 1 iterations and the norm of the residual met the relative convergence tolerance (`ksp_rtol`) .
 The nonlinear solve converged in 1 iteration, which we expect because this is a linear problem, and the residual met the absolute convergence tolerance (`snes_atol`).
 

diff --git a/docs/user/examples/reverse-2d/step07_twofaults_maxwell-synopsis.md b/docs/user/examples/reverse-2d/step07_twofaults_maxwell-synopsis.md
@@ -9,7 +9,7 @@
 * spatialdata.spatialdb.ZeroDB
 * pylith.meshio.OutputSolnBoundary
 * pylith.meshio.DataWriterHDF5
-* Quasistatic simulation
+* Quasi-static simulation
 * pylith.materials.Elasticity
 * pylith.materials.IsotropicLinearMaxwell
 * pylith.faults.FaultCohesiveKin

diff --git a/docs/user/examples/reverse-2d/step08_twofaults_powerlaw-synopsis.md b/docs/user/examples/reverse-2d/step08_twofaults_powerlaw-synopsis.md
@@ -9,7 +9,7 @@
 * spatialdata.spatialdb.ZeroDB
 * pylith.meshio.OutputSolnBoundary
 * pylith.meshio.DataWriterHDF5
-* Quasistatic simulation
+* Quasi-static simulation
 * pylith.materials.Elasticity
 * pylith.materials.IsotropicPowerLaw
 * pylith.faults.FaultCohesiveKin

diff --git a/docs/user/examples/strikeslip-2d/step01-slip.md b/docs/user/examples/strikeslip-2d/step01-slip.md
@@ -121,7 +121,7 @@ At the beginning of the output written to the terminal, we see that PyLith is re
 The scales for nondimensionalization remain the default values for a quasistatic problem.
 PyLith detects the presence of a fault based on the Lagrange multiplier for the fault in the solution field and selects appropriate preconditioning options as discussed in {ref}`sec-user-run-pylith-petsc-options`.
 
-At the end of the output written to the termial, we see that the solver advanced the solution one time step (static simulation).
+At the end of the output written to the terminal, we see that the solver advanced the solution one time step (static simulation).
 The linear solve converged after 35 iterations and the norm of the residual met the absolute convergence tolerance (`ksp_atol`) .
 The nonlinear solve converged in 1 iteration, which we expect because this is a linear problem, and the residual met the absolute convergence tolerance (`snes_atol`).
 

diff --git a/docs/user/examples/strikeslip-2d/step02_slip_velbc-synopsis.md b/docs/user/examples/strikeslip-2d/step02_slip_velbc-synopsis.md
@@ -14,5 +14,5 @@
 * spatialdata.spatialdb.UniformDB
 * pylith.meshio.OutputSolnBoundary
 * pylith.meshio.DataWriterHDF5
-* Quasistatic simulation
+* Quasi-static simulation
 * spatialdata.spatialdb.SimpleDB
diff --git a/docs/user/examples/strikeslip-2d/step03_multislip_velbc-synopsis.md b/docs/user/examples/strikeslip-2d/step03_multislip_velbc-synopsis.md
@@ -14,5 +14,5 @@
 * spatialdata.spatialdb.UniformDB
 * pylith.meshio.OutputSolnBoundary
 * pylith.meshio.DataWriterHDF5
-* Quasistatic simulation
+* Quasi-static simulation
 * spatialdata.spatialdb.SimpleDB
diff --git a/docs/user/examples/strikeslip-2d/step04-varslip.md b/docs/user/examples/strikeslip-2d/step04-varslip.md
@@ -82,7 +82,7 @@ $ pylith step04_varslip.cfg
 ```
 
 The beginning of the output written to the terminal matches that in our previous simulations.
-At the end of the output written to the termial, we see that the solver advanced the solution one time step (static simulation).
+At the end of the output written to the terminal, we see that the solver advanced the solution one time step (static simulation).
 The linear solve converged after 73 iterations and the norm of the residual met the absolute convergence tolerance (`ksp_atol`).
 The nonlinear solve converged in 1 iteration, which we expect because this is a linear problem, and the residual met the absolute convergence tolerance (`snes_atol`).
 

diff --git a/docs/user/examples/subduction-2d/common-information.md b/docs/user/examples/subduction-2d/common-information.md
@@ -9,7 +9,7 @@ The settings contained in `pylithapp.cfg` for this problem consist of:
 * `pylithapp.journal.info` Parameters that control the verbosity of the output written to stdout for the different components.
 * `pylithapp.mesh_generator` Parameters for importing the finite-element mesh.
 * `pylithapp.problem` Parameters that define the boundary value problem and it solution, such as the type of solver, solution fields.
-* `pylithapp.problem.materials` Paramters that specify the governing equation and bulk rheologies.
+* `pylithapp.problem.materials` Parameters that specify the governing equation and bulk rheologies.
 
 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`.

diff --git a/docs/user/examples/subduction-2d/step01-coseismic.md b/docs/user/examples/subduction-2d/step01-coseismic.md
@@ -108,7 +108,7 @@ ts_type = beuler
 At the beginning of the output written to the terminal, we see that PyLith is reading the mesh using the `MeshIOPetsc` reader and that it found the domain to extend from -600 km to +600 km in the x direction and from -600 km to 0 in the y direction.
 The output also includes the scales used for nondimensionalization and the default PETSc options.
 
-At the end of the output written to the termial, we see that the solver advanced the solution one time step (static simulation).
+At the end of the output written to the terminal, we see that the solver advanced the solution one time step (static simulation).
 The linear solve converged after 85 iterations and the norm of the residual met the absolute convergence tolerance (`ksp_atol`) .
 The nonlinear solve converged in 1 iteration, which we expect because this is a linear problem, and the residual met the absolute convergence tolerance (`snes_atol`).
 

diff --git a/docs/user/examples/subduction-3d/common-information.md b/docs/user/examples/subduction-3d/common-information.md
@@ -0,0 +1,20 @@
+# Common Information
+
+In addition to the finite-element mesh, PyLith requires files to specify the simulation parameters.
+We specify parameters common to all simulations in a directory in `pylithapp.cfg`, which contains numerous comments, so we only summarize the parameters here.
+
+The settings contained in `pylithapp.cfg` for this problem consist of:
+
+* `pylithapp.metadata` Metadata common to all of the simulations in the directory.
+* `pylithapp.journal.info` Parameters that control the verbosity of the output written to stdout for the different components.
+* `pylithapp.mesh_generator` Parameters for importing the finite-element mesh.
+* `pylithapp.problem` Parameters that define the boundary value problem and it solution, such as the type of solver, solution fields, and output over the domain.
+* `pylithapp.problem.materials` Parameters that specify the governing equation and bulk rheologies.
+* `pylithapp.problem.bc` Parameters that specify the boundary conditions.
+
+To make it easier to switch between elastic and viscoelastic bulk rheologies for different simulations, we separate the material parameters relevant to the bulk rheologies into two parameter files: `mat_elastic.cfg` and `mat_viscoelastic.cfg`.
+We use `mat_elastic.cfg` when we want all materials to use elastic bulk rheologies.
+We use `mat_viscoelastic.cfg` when we want the mantle and bottom of the slab to use viscoelastic bulk rheologies.
+The physical properties for each material are specified in spatial database files.
+For example, the elastic properties for the crust are in `mat_crust_elastic.spatialdb`.
+The spatial database files for elastic properties all use just a single point to specify uniform physical properties within each material.
diff --git a/docs/user/examples/subduction-3d/exercises.md b/docs/user/examples/subduction-3d/exercises.md
@@ -0,0 +1,7 @@
+# Suggested Exercises
+
+1. Change the elastic bulk rheology properties to be depth dependent.
+2. Add spatial variation to the slip distribution in Step 2.
+3. Change the distribution of aseismic slip (creep) in Steps 3 and 4.
+4. Change the distribution of slow slip in Step 6 and the GPS stations used in Steps 6 and 7.
+5. Optimize the depth variation of the initial stresses in Step 8a to minimize the deformation.
diff --git a/docs/user/examples/subduction-3d/figs/cascadia.png b/docs/user/examples/subduction-3d/figs/cascadia.png
diff --git a/docs/user/examples/subduction-3d/figs/conceptualmodel.png b/docs/user/examples/subduction-3d/figs/conceptualmodel.png
diff --git a/docs/user/examples/subduction-3d/figs/cubit-geometry-patch.png b/docs/user/examples/subduction-3d/figs/cubit-geometry-patch.png
diff --git a/docs/user/examples/subduction-3d/figs/cubit-geometry.png b/docs/user/examples/subduction-3d/figs/cubit-geometry.png
diff --git a/docs/user/examples/subduction-3d/figs/cubit-mesh.jpg b/docs/user/examples/subduction-3d/figs/cubit-mesh.jpg