[cig-commits] r16819 - short/3D/PyLith/trunk/doc/userguide/extending

[brad at geodynamics.org]

Author: brad
Date: 2010-05-27 21:03:08 -0700 (Thu, 27 May 2010)
New Revision: 16819

Modified:
   short/3D/PyLith/trunk/doc/userguide/extending/extending.lyx
Log:
Added section on how to add a fault constitutive model.

Modified: short/3D/PyLith/trunk/doc/userguide/extending/extending.lyx
===================================================================
--- short/3D/PyLith/trunk/doc/userguide/extending/extending.lyx	2010-05-28 03:55:12 UTC (rev 16818)
+++ short/3D/PyLith/trunk/doc/userguide/extending/extending.lyx	2010-05-28 04:03:08 UTC (rev 16819)
@@ -1,4 +1,4 @@
-#LyX 1.6.2 created this file. For more info see http://www.lyx.org/
+#LyX 1.6.5 created this file. For more info see http://www.lyx.org/
 \lyxformat 345
 \begin_document
 \begin_header
@@ -718,7 +718,7 @@
 \begin_layout LyX-Code
 
 \family typewriter
---material.problem.homogeneous.material=pylith.materials.contrib.PlaneStrainState
+--timedependent.homogeneous.material=pylith.materials.contrib.PlaneStrainState
 \end_layout
 
 \begin_layout Standard
@@ -734,5 +734,296 @@
 .
 \end_layout
 
+\begin_layout Section
+\begin_inset CommandInset label
+LatexCommand label
+name "sec:Extending:FaultConstitutiveModels"
+
+\end_inset
+
+Fault Constitutive Models
+\end_layout
+
+\begin_layout Standard
+PyLith includes a 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 coeficient of friction is linearly proportional to the slip rate.
+ This constitutive model, 
+\family typewriter
+ViscousFriction
+\family default
+, is not particularly useful, but it illustrates the basic steps involved
+ in creating a fault constitutive model.
+ The sources files are included with the main PyLith source code in the
+ 
+\family typewriter
+templates/friction
+\family default
+ directory.
+ The 
+\family typewriter
+README
+\family default
+ file in 
+\family typewriter
+templates/friction
+\family default
+ provides detailed instructions for the various steps, and the source files
+ contain numerous comments to guide you through the customization process.
+\end_layout
+
+\begin_layout Standard
+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.
+\end_layout
+
+\begin_layout Standard
+The properties and state variables used in the fault constitutive model
+ are set using arguments to the constuctor of the C++ 
+\family typewriter
+FrictionModel
+\family default
+ object, analogous to the 
+\family typewriter
+ElasticMaterial
+\family default
+ object for bulk constitutive models.
+ In fact, both types of constitutive models used the same underlying C++
+ object (
+\family typewriter
+Metadata::ParamDescription
+\family default
+) 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
+ 
+\family typewriter
+Metadata
+\family default
+ 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:
+\end_layout
+
+\begin_layout Description
+
+\family typewriter
+_dbToProperties()
+\family default
+ Computes the physical properties used in the constitutive model equations
+ from the physical properties supplied in spatial databases.
+\end_layout
+
+\begin_layout Description
+
+\family typewriter
+_nondimProperties()
+\family default
+ Nondimensionalizes the physical properties used in the constitutive model
+ equations.
+\end_layout
+
+\begin_layout Description
+
+\family typewriter
+_dimProperties()
+\family default
+ Dimensionalizes the physical properties used in the constitutive model
+ equations.
+\end_layout
+
+\begin_layout Description
+
+\family typewriter
+_dbToStateVars()
+\family default
+ Computes the initial state variables used in the constitutive model equations
+ from the initial values supplied in spatial databases.
+\end_layout
+
+\begin_layout Description
+
+\family typewriter
+_nondimStateVars()
+\family default
+ Nondimensionalizes the state variables used in the constitutive model equations.
+\end_layout
+
+\begin_layout Description
+
+\family typewriter
+_dimStateVars()
+\family default
+ Dimensionalizes the state variables used in the constitutive model equations.
+\end_layout
+
+\begin_layout Description
+
+\family typewriter
+_calcFriction()
+\family default
+ Computes the friction stress given the physical properties, state variables,
+ slip, slip rate, and normal traction.
+\end_layout
+
+\begin_layout Description
+
+\family typewriter
+_updateStateVars()
+\family default
+ Updates the state variables given the physical properties, slip, slip rate,
+ and normal traction.
+\end_layout
+
+\begin_layout Standard
+If a constitutive model does not use state variables, then the state variable
+ routines are omitted.
+ 
+\end_layout
+
+\begin_layout Standard
+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.
+ 
+\end_layout
+
+\begin_layout Standard
+The SWIG interface files for a fault constitutive component are setup in
+ the same manner as in the previous examples of creating a bulk constitutive
+ model or a customized spatial database component.
+ The ``main'' SWIG interface file (
+\family typewriter
+frictioncontrib.i
+\family default
+ in this case) sets up the Python module, and the SWIG interface file for
+ the component (
+\family typewriter
+ViscousFriction.i
+\family default
+ in this case) defines the functions that should be included in the Python
+ module.
+ Note that because the C++ 
+\family typewriter
+FrictionModel
+\family default
+ 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 
+\family typewriter
+FrictionModel
+\family default
+ were not implemented in the child class 
+\family typewriter
+ViscousFriction
+\family default
+), and no constructor is created.
+ When this happens, you cannot create a 
+\family typewriter
+ViscousFriction
+\family default
+ Python object.
+\end_layout
+
+\begin_layout Standard
+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 
+\family typewriter
+Makefile.am
+\family default
+ file as necessary, then generate the configure script, run configure, and
+ then build and install the library and module (see the 
+\family typewriter
+README
+\family default
+ file for detailed instructions).
+\end_layout
+
+\begin_layout Standard
+Because most functionality of the fault constitutive model component is
+ at the C++ level, properly constructed unit tests for the 
+\family typewriter
+component
+\family default
+ 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 
+\family typewriter
+ViscousFriction
+\family default
+ Python object and call some of the simple underlying C++ functions.
+ The source files are in the 
+\family typewriter
+templates/friction/tests
+\family default
+ directory.
+ The 
+\family typewriter
+testcontrib.py
+\family default
+ Python script runs the tests defined in 
+\family typewriter
+TestViscousFriction.py
+\family default
+.
+\end_layout
+
+\begin_layout Standard
+Once you have built, installed, and tested the 
+\family typewriter
+ViscousFriction
+\family default
+ 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 
+\family typewriter
+examples/bar_shearwave/quad4, in shearwave_staticfriction.cfg
+\family default
+ replace the line
+\end_layout
+
+\begin_layout LyX-Code
+friction = pylith.friction.StaticFriction
+\end_layout
+
+\begin_layout Standard
+with the line
+\end_layout
+
+\begin_layout LyX-Code
+friction = pylith.friction.contrib.ViscousFriction
+\end_layout
+
+\begin_layout Standard
+or simply add the command line argument
+\end_layout
+
+\begin_layout LyX-Code
+
+\family typewriter
+--timedependent.interfaces.fault.friction=pylith.friction.contrib.ViscousFriction
+\end_layout
+
+\begin_layout Standard
+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.
+\end_layout
+
 \end_body
 \end_document