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

[brad at geodynamics.org]

Author: brad
Date: 2009-06-16 12:10:37 -0700 (Tue, 16 Jun 2009)
New Revision: 15302

Modified:
   short/3D/PyLith/trunk/doc/userguide/extending/extending.lyx
Log:
Finished extending section in manual.

Modified: short/3D/PyLith/trunk/doc/userguide/extending/extending.lyx
===================================================================
--- short/3D/PyLith/trunk/doc/userguide/extending/extending.lyx	2009-06-16 17:44:41 UTC (rev 15301)
+++ short/3D/PyLith/trunk/doc/userguide/extending/extending.lyx	2009-06-16 19:10:37 UTC (rev 15302)
@@ -420,26 +420,310 @@
  bulk constitutive model.
  We reimplement the 2-D 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.
+ This constitutive model, 
+\family typewriter
+PlaneStrainState
+\family default
+ is not particularly useful, but it illustrates the basic steps involved
+ in creating a bulk constitutive model with state variables.
  The sources 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 custcomization process.
+ 
+\family typewriter
+templates/materials
+\family default
+ directory.
+ The 
+\family typewriter
+README
+\family default
+ file in 
+\family typewriter
+templates/materials
+\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
-In contrast to our previous example of customization of a spatial database
+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.
+ objects and labels.
 \end_layout
 
+\begin_layout Standard
+The properties and state variables used in the bulk constitutive model are
+ set using arguments to the constuctor of the C++ 
+\family typewriter
+ElasticMaterial
+\family default
+ object.
+ 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 bulk constitutive component includes a number of
+ functions that implement elasticity behavior of a bulk material 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
+ Nondimensionalize the physical properties used in the constitutive model
+ equations.
+\end_layout
+
+\begin_layout Description
+
+\family typewriter
+_dimProperties()
+\family default
+ Dimensionalize the physical properties used in the constitutive model equations.
+\end_layout
+
+\begin_layout Description
+
+\family typewriter
+_stableTimeStepImplicit()
+\family default
+ Computes the stable time step for implicit time stepping in quasi-static
+ simulations given the current state (strain, stress, and state variables).
+\end_layout
+
+\begin_layout Description
+
+\family typewriter
+_calcDensity()
+\family default
+ Compute 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.
+\end_layout
+
+\begin_layout Description
+
+\family typewriter
+_calcStress()
+\family default
+ Compute the stress tensor given the physical properties, state variables,
+ total strain, initial stress, and initial strain.
+\end_layout
+
+\begin_layout Description
+
+\family typewriter
+_calcElasticConsts()
+\family default
+ Compute the elastic constants given the physical properties, state variables,
+ total strain, initial stress, and initial strain.
+\end_layout
+
+\begin_layout Description
+
+\family typewriter
+_updateStateVars()
+\family default
+ Update 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.
+\end_layout
+
+\begin_layout Standard
+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 
+\begin_inset Formula $\mu,$
+\end_inset
+
+
+\begin_inset Formula $\lambda,$
+\end_inset
+
+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 (
+\begin_inset Formula $-\Delta t$
+\end_inset
+
+ to 
+\begin_inset Formula $t$
+\end_inset
+
+).
+ 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.
+\end_layout
+
+\begin_layout Standard
+The SWIG interface files for a bulk constitutive component are setup in
+ the same manner as in the previous example of creating a customized spatial
+ database component.
+ The 
+\begin_inset Quotes eld
+\end_inset
+
+main
+\begin_inset Quotes erd
+\end_inset
+
+ SWIG interface file (
+\family typewriter
+materialscontrib.i
+\family default
+ in this case) sets up the Python module, and the SWIG interface file for
+ the component (
+\family typewriter
+PlaneStrainState.i
+\family default
+ in this case) defines the functions that should be included in the Python
+ module.
+ Note that because the C++ 
+\family typewriter
+ElasticMaterial
+\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 functions
+ remain abstract (i.e., some pure virtual functions defined in the parent
+ class 
+\family typewriter
+ElasticMaterial
+\family default
+ were not implemented in the child class 
+\family typewriter
+PlaneStrainState
+\family default
+) and no constructor is created.
+ When this happens, you cannot create a 
+\family typewriter
+PlaneStrainState
+\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 bulk 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 bulk constitutive models included with PyLith.
+ In this example we create the Python unit tests to verify that we can create
+ a 
+\family typewriter
+PlaneStrainState
+\family default
+ Python object and call some of the simple underlying C++ functions.
+ The source files are in the 
+\family typewriter
+templates/materials/tests
+\family default
+ directory.
+ The 
+\family typewriter
+testcontrib.py
+\family default
+ Python script runs the tests defined in 
+\family typewriter
+TestPlaneStrainState.py
+\family default
+.
+\end_layout
+
+\begin_layout Standard
+Once you have built, installed, and tested the 
+\family typewriter
+PlaneStrainState
+\family default
+ component, it is time to use it in a simple example.
+ You can try using it in any of the 2-D examples.
+ For the examples in 
+\family typewriter
+examples/twocells/twoquad4
+\family default
+, in 
+\family typewriter
+pylithapp.cfg
+\family default
+ replace the line
+\end_layout
+
+\begin_layout LyX-Code
+material = pylith.materials.ElasticPlaneStrain
+\end_layout
+
+\begin_layout Standard
+with the line
+\end_layout
+
+\begin_layout LyX-Code
+material = pylith.materials.contrib.PlaneStrainState
+\end_layout
+
+\begin_layout Standard
+or simply add the command line argument
+\begin_inset Newline newline
+\end_inset
+
+
+\family typewriter
+--material.problem.materials.material=pylith.materials.contrib.PlaneStrainState
+\family default
+ when running any of the 2-D examples.
+ The output should remain identical, but you should see the 
+\family typewriter
+PlaneStrainState
+\family default
+ object listed in the information written to 
+\family typewriter
+stdout
+\family default
+.
+\end_layout
+
 \end_body
 \end_document