The examples in this directory illustrate the use of gravitational
body forces and the small strain formulation.

The main features of these examples are:
  * gravitational body forces in 2-D
  * initial stresses and state variables
  * small strain formulation (large rigid body motions and small strains)
  * viscoelastic relaxation with a linear Maxwell model
  * direct solver in simulations without a fault
  * iterative solver with custom preconditioner for a fault
  * spatial database with irregular distribution of points in 2-D

Problem Setup

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.0km. The general parameters are included in the
pylithapp.cfg file, which will be read by default.


Mesh generation (optional)

  NOTE: The result of this step will overwrite the included file
        mesh.exo. You may want to copy/rename this file so that
        you have a backup copy in case you have difficulty running
        CUBIT/Trelis.

  Start CUBIT and play the journal file "mesh.jou". We highly
  recommend that you study the contents of the journal files to
  understand the mesh generation process.

Steps 1-3 illustrate issues that arise when using gravitational body
forces and setting up initial conditions for simulations for such
cases.

Steps 4-8 illustrate the differences between infinitesimal and finite
strain and with and without gravitational body forces for postseismic
relaxation following an earthquake with reverse slip.


Step 1. Gravitational body forces and infinitesimal strain

  This simulation does not use initial stresses, 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 stress_xx == stress_yy. The
  crust is elastic, so stress_xx is not close to stress_yy;
  consequently, this does not yield a realistic stress state.

  Run the simulation via the following command:
    pylith gravity_infstrain.cfg


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 to give us
  equilibrium or near-equilibrium conditions at the beginning of a
  simulation.

  Run the simulation via the following command:
    pylith gravity_initstress.cfg gravity_isostatic.cfg


Step 3. Gravitational body forces, infinitesimal strain, initial stresses,
  and 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, roughly approximating a
  sedimentary basin. In this region, the initial stresses do not
  satisfy the governing equation and the solution evolves to a steady
  state.

  Run the simulation via the following command:
    pylith gravity_initstress.cfg gravity_vardensity.cfg


Step 4. Postseismic relaxation with infinitesimal strain and without
  gravitational body forces.

  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 is imposed at 50 years into the simulation so that any
  pre-earthquake deformation trends are clear.

  Run the simulation via the following command:
    pylith postseismic.cfg nogravity.cfg postseismic_infstrain_nograv.cfg


Step 5. Postseismic relaxation with finite strain and without
  gravitational body forces.

  Same as Step 4 but with finite strain.

  Run the simulation via the following command:
    pylith postseismic.cfg nogravity.cfg postseismic_finstrain_nograv.cfg


Step 6. Postseismic relaxation with infinitesimal strain and
  gravitational body forces.

  Same as Step 4 but with gravitational body forces.

  Run the simulation via the following command:
    pylith postseismic.cfg gravity_initstress.cfg postseismic_infstrain.cfg


Step 7. Postseismic relaxation with finite strain and gravitational
  body forces.

  Same as Step 5 but with gravitational body forces; same as Step 6
  but with finite strain.

  Run the simulation via the following command:
    pylith postseismic.cfg gravity_initstress.cfg postseismic_finstrain.cfg


Step 8. Postseismic relaxation with finite strain, gravitational
  body forces, and variable density.

  Same as Step 7 but with the spatial variation in density in Step
  3. We use the output from Step 3 to generate near-equilibrium
  initial conditions. We want to impose the initial stresses at each
  quadrature point, so we rerun Step 3 and turn off the averaging of
  values over the quadrature points in the cell data output.

  i. Edit pyithapp.cfg and comment out the CellFilterAvg lines.

  ii. Rerun Step 3:
    pylith gravity_initstress.cfg gravity_vardensity.cfg

  iii. Generate the spatial databases for the initial stresses and strains:
    generate_statedb.py

  iv. Edit pylithapp.cfg again, and uncomment the CellFilterAvg lines.

  v. Run the simulation via the following command:
    pylith postseismic.cfg gravity_initstress.cfg postseismic_vardensity.cfg


Suggested variations

  The list below includes some suggested modifications to the suite of
  examples that will allow you to become more familiar with some of
  the subtle issues that arise when dealing with gravitational body
  forces and finite strain.

  * Change the cells from quadrilaterals to triangles. How does this
    affect the solution? Can you identify any differences in the
    numerical accuracy?

  * Extend the earthquake slip into the viscoelastic layer.
    How does this affect the postseismic deformation?

  * In Step 3, add topography or increase the size/amplitude of the
    local density perturbation to the elastic layer. How does this
    solution affect the results and postseismic deformation in Step 8?

  * For Step 8, we used an infinitesimal strain formulation to generate
    state variables for a finite strain problem, which may influence our
    results. What happens when we use a finite strain formulation to
    generate our initial state variables?
