Overview

  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.

  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.