[cig-commits] r15344 - in short/3D/PyLith/trunk: . templates templates/materials
brad at geodynamics.org
brad at geodynamics.org
Thu Jun 18 21:59:01 PDT 2009
Author: brad
Date: 2009-06-18 21:58:59 -0700 (Thu, 18 Jun 2009)
New Revision: 15344
Modified:
short/3D/PyLith/trunk/TODO
short/3D/PyLith/trunk/templates/Makefile.am
short/3D/PyLith/trunk/templates/materials/PlaneStrainState.cc
short/3D/PyLith/trunk/templates/materials/PlaneStrainState.py
short/3D/PyLith/trunk/templates/materials/README
Log:
Added meat to the templates/materials/README file and more documentation to the template source files.
Modified: short/3D/PyLith/trunk/TODO
===================================================================
--- short/3D/PyLith/trunk/TODO 2009-06-19 04:30:50 UTC (rev 15343)
+++ short/3D/PyLith/trunk/TODO 2009-06-19 04:58:59 UTC (rev 15344)
@@ -27,8 +27,6 @@
BONUS
- Add more to READMEs for extensions.
-
pylithinfo (Python application, send extra args to PyLith)
Memory model
Modified: short/3D/PyLith/trunk/templates/Makefile.am
===================================================================
--- short/3D/PyLith/trunk/templates/Makefile.am 2009-06-19 04:30:50 UTC (rev 15343)
+++ short/3D/PyLith/trunk/templates/Makefile.am 2009-06-19 04:58:59 UTC (rev 15344)
@@ -14,12 +14,8 @@
Makefile.am \
README \
materials/README \
- materials/configure \
materials/configure.ac \
materials/Makefile.am \
- materials/aclocal.m4 \
- materials/Makefile.in \
- materials/portinfo.in \
materials/PlaneStrainState.hh \
materials/PlaneStrainState.cc \
materials/PlaneStrainState.i \
@@ -27,7 +23,6 @@
materials/__init__.py \
materials/PlaneStrainState.py \
materials/tests/Makefile.am \
- materials/tests/Makefile.in \
materials/tests/testcontrib.py \
materials/tests/TestPlaneStrainState.py
Modified: short/3D/PyLith/trunk/templates/materials/PlaneStrainState.cc
===================================================================
--- short/3D/PyLith/trunk/templates/materials/PlaneStrainState.cc 2009-06-19 04:30:50 UTC (rev 15343)
+++ short/3D/PyLith/trunk/templates/materials/PlaneStrainState.cc 2009-06-19 04:58:59 UTC (rev 15344)
@@ -10,8 +10,11 @@
// ----------------------------------------------------------------------
//
-#include <portinfo>
+// See PlaneStrainState.hh for a description of each C++ function and
+// its arguments.
+#include <portinfo> // machine specificinfo generated by configure
+
#include "PlaneStrainState.hh" // implementation of object methods
#include "pylith/materials/Metadata.hh" // USES Metadata
@@ -21,8 +24,6 @@
#include "spatialdata/units/Nondimensional.hh" // USES Nondimensional
-//#include "petsc.h" // USES PetscLogFlops
-
#include <cassert> // USES assert()
#include <sstream> // USES std::ostringstream
#include <stdexcept> // USES std::runtime_error
@@ -185,8 +186,6 @@
propValues[p_density] = density;
propValues[p_mu] = mu;
propValues[p_lambda] = lambda;
-
- // PetscLogFlops(6); // Add to logging of number of floating point operations
} // _dbToProperties
// ----------------------------------------------------------------------
@@ -213,8 +212,6 @@
_normalizer->nondimensionalize(values[p_mu], pressureScale);
values[p_lambda] =
_normalizer->nondimensionalize(values[p_lambda], pressureScale);
-
- // PetscLogFlops(3); // Add to logging of number of floating point operations
} // _nondimProperties
// ----------------------------------------------------------------------
@@ -241,8 +238,6 @@
_normalizer->dimensionalize(values[p_mu], pressureScale);
values[p_lambda] =
_normalizer->dimensionalize(values[p_lambda], pressureScale);
-
- // PetscLogFlops(3); // Add to logging of number of floating point operations
} // _dimProperties
// ----------------------------------------------------------------------
@@ -317,8 +312,6 @@
stress[0] = s12 + mu2*e11 + initialStress[0];
stress[1] = s12 + mu2*e22 + initialStress[1];
stress[2] = mu2 * e12 + initialStress[2];
-
- // PetscLogFlops(14); // Add to logging of number of floating point operations
} // _calcStress
// ----------------------------------------------------------------------
@@ -369,8 +362,6 @@
elasticConsts[3] = lambda2mu; // C2222
elasticConsts[4] = 0; // C2212
elasticConsts[5] = mu2; // C1212
-
- // PetscLogFlops(2); // Add to logging of number of floating point operations
} // calcElasticConsts
// ----------------------------------------------------------------------
Modified: short/3D/PyLith/trunk/templates/materials/PlaneStrainState.py
===================================================================
--- short/3D/PyLith/trunk/templates/materials/PlaneStrainState.py 2009-06-19 04:30:50 UTC (rev 15343)
+++ short/3D/PyLith/trunk/templates/materials/PlaneStrainState.py 2009-06-19 04:58:59 UTC (rev 15344)
@@ -47,6 +47,9 @@
#
# There are no vertex fields because the constitutive model
# operations on quantities evaluated at the quadrature points.
+ #
+ # Do not change the name of this variable. The output manager will
+ # request this variable by name.
self.availableFields = \
{'vertex': \
{'info': [],
@@ -62,7 +65,9 @@
def _createModuleObj(self):
"""
- Call constructor for module object for access to C++ object.
+ Call constructor for module object for access to C++ object. This
+ function is called automatically by the generic Python Material
+ object. It must have this name and self as the only argument.
"""
ModulePlaneStrainState.__init__(self)
return
@@ -70,7 +75,10 @@
# FACTORIES ////////////////////////////////////////////////////////////
-def material(): # The name of this function MUST be 'material'.
+# This is the function that is called when you invoke
+# material_one = pylith.materials.contrib.PlaneStrainState
+# The name of this function MUST be 'material'.
+def material():
"""
Factory associated with PlaneStrainState.
"""
Modified: short/3D/PyLith/trunk/templates/materials/README
===================================================================
--- short/3D/PyLith/trunk/templates/materials/README 2009-06-19 04:30:50 UTC (rev 15343)
+++ short/3D/PyLith/trunk/templates/materials/README 2009-06-19 04:58:59 UTC (rev 15344)
@@ -1,12 +1,123 @@
-PyLith interface files are installed to $PREFIX/shared/pylith/swig.
+Overview
-Functions in bulk material routines are called for every quadrature
-point of every cell of the material, so efficient code is essential.
+ This directory contains source files for building a user defined
+ bulk constitutive model component consisting of C++ code, a Python
+ module, and Python code. The example implementation provides
+ isotropic, elastic plane strain behavior. State variables are used
+ to hold the stress and strain tensors. Note that state variables are
+ not needed for a purely elastic material because the stress and
+ strain can be computed from the deformation field and the elastic
+ constants; we use them in this example to illustrate how to use
+ state variables in a bulk material.
-The consistency checks of user input should throw exceptions with a
-meaningful error message so that the user can fix the
-mistake. Consistency checks in the other routines should use the
-assert() macro so that they can be removed during compilation. To
-remove the assert() calls during compilation configure with -DNDEBUG
-added to the CFLAGS and CXXFLAGS environment variables.
+ PyLith already contains a ElasticPlaneStrain component that does not
+ use state variables.
+ The suggested path to customizing this component is to build and
+ install the provided PlaneStrainState component and then rename/copy
+ the files and gradually adopt it to your specific needs. For more
+ complex bulk rheologies, you may want to use the MaxwellIsotropic3D,
+ GenMaxwellIsotropic3D, or PowerLaw3D components provided with PyLith
+ as templates.
+
+
+
+Requirements
+
+ In order to build the component and interface it with PyLith, you will need
+ * C++ compiler
+ * SWIG (version 1.3.33 or later)
+ * Python with header files (version 2.3 or later)
+ * autoconf tools
+
+ The C++ compiler must be compatible with the installed Python and
+ both must be compatible with the C++ compiler and Python used to
+ build PyLith. The safest way to insure compatibility is to use the
+ C++ compiler and Python provided with your operating system and
+ build PyLith from source. However, on many systems it should be
+ possible to build the component and have it work with PyLith
+ installed from a binary package.
+
+Files
+
+ Makefile.am - automake parameters for constructing a Makefile
+ PlaneStrainState.cc - C++ source file implementing PlaneStrainState object functions
+ PlaneStrainState.hh - C++ header file with class definition for PlaneStrainState
+ PlaneStrainState.i - SWIG interface file for the C++ PlaneStrainState object
+ README - this file
+ __init__.py - Python source file for module initialization
+ configure.ac - autoconf parameters for construction a configure script
+ m4 - directory containing autoconf macros
+ materialscontrib.i - SWIG interface file defining the materialscontrib Python module
+ tests - directory containing tests of the PlaneStrainState object
+
+How to build/install the PlaneStrainState component
+
+ 1. Run "autoreconf -if" in this directory (templates/materials).
+
+ 2. Run configure either from this directory or a scratch build
+ directory. Use the --prefix=DIRECTORY to indicate where the files
+ should be installed. We strongly recommend that you install the
+ component to the same location as where PyLith is installed. For
+ example, if PyLith is installed in $HOME/cig then use the
+ --prefix=$HOME/cig command line argument to configure. To build in a
+ separate directory simply invoke the configure script from the other
+ directory. For example, from $HOME/build/pylith-contrib run
+ $HOME/src/pylith/templates/materials/configure --prefix=$HOME/cig.
+
+ Configure will check for a number of files including the location of
+ PyLith C++ header files, library, and SWIG interface files. You
+ may need to define some additional command line arguments to
+ configure and/or environment variables to help configure find the
+ required files.
+
+ We run configure using on a MacBook Pro using MacPorts where we have
+ defined a number of environment variables in .bashrc for installed
+ tools.
+
+ ${HOME}/src/cig/pylith/templates/materials/configure \
+ --prefix=${CIG_DIR} \
+ CPPFLAGS="-I${PROJ4_INCDIR} -I${PORTS_INCDIR} -I${CIG_INCDIR}" \
+ LDFLAGS="-L${PROJ4_LIBDIR} -L${PORTS_LIBDIR} -L${CIG_LIBDIR} -F${PORTS_DIR}/Library/Frameworks" \
+ PYLITH_SWIG_DIR="${CIG_DIR}/share/pylith/swig" CC=gcc CXX=g++
+
+
+ 3. Run "make", "make install", and "make check" from the top-level
+ build directory. This will first build the C++ library and module,
+ then install the files to the location specified by the --prefix
+ command line argument to configure, and finally run some Python
+ tests to verify that the PlaneStrainState component was installed
+ correctly.
+
+Customization
+
+ This is where the fun begins. Read over the Python and C++ source
+ code to become familiar with the features implemented with the
+ PlaneStrainState component. The PlaneStrainState Python object
+ simply defines what fields are available for output (properties in
+ the info files and state variables stress and strain in data files
+ at a given time in a simulation. The PlaneStrainState C++ object
+ does the grunt work of computing the various quantities required for
+ solving the elasticity equations. The interface for the bulk
+ constitutive models has been designed to be simple and use arrays
+ rather than complex C++ data structures. This reduces speed slightly
+ but makes it much easier to implement new constitutive models.
+
+ We recommend that you start by changing the constitutive equations,
+ followed by changing the properties and state variables (e.g., store
+ the deviatoric stress and strain as state variables).
+
+Hints
+
+ Functions in bulk material routines are called for every quadrature
+ point of every cell of the material, so efficient code is
+ essential. Having said that, get the implementation correct first
+ and then worry about speed.
+
+ The consistency checks of user input should throw exceptions with a
+ meaningful error message so that the user can fix the
+ mistake. Consistency checks in the other routines should use the
+ assert() macro so that they can be removed during compilation. To
+ remove the assert() calls during compilation configure with -DNDEBUG
+ added to the CFLAGS and CXXFLAGS environment variables.
+
More information about the CIG-COMMITS
mailing list