[cig-commits] r15342 - in cs/spatialdata-0.1/trunk/templates: . spatialdb
brad at geodynamics.org
brad at geodynamics.org
Thu Jun 18 21:29:08 PDT 2009
Author: brad
Date: 2009-06-18 21:29:08 -0700 (Thu, 18 Jun 2009)
New Revision: 15342
Modified:
cs/spatialdata-0.1/trunk/templates/Makefile.am
cs/spatialdata-0.1/trunk/templates/spatialdb/Makefile.am
cs/spatialdata-0.1/trunk/templates/spatialdb/README
cs/spatialdata-0.1/trunk/templates/spatialdb/UniformVelModel.cc
cs/spatialdata-0.1/trunk/templates/spatialdb/UniformVelModel.hh
cs/spatialdata-0.1/trunk/templates/spatialdb/UniformVelModel.py
Log:
Added description and instructions to the README and added more documentation to the source code.
Modified: cs/spatialdata-0.1/trunk/templates/Makefile.am
===================================================================
--- cs/spatialdata-0.1/trunk/templates/Makefile.am 2009-06-19 00:42:11 UTC (rev 15341)
+++ cs/spatialdata-0.1/trunk/templates/Makefile.am 2009-06-19 04:29:08 UTC (rev 15342)
@@ -10,6 +10,7 @@
# ----------------------------------------------------------------------
#
+# Include files in templates in spatialdata source distribution.
EXTRA_DIST = \
Makefile.am \
README \
Modified: cs/spatialdata-0.1/trunk/templates/spatialdb/Makefile.am
===================================================================
--- cs/spatialdata-0.1/trunk/templates/spatialdb/Makefile.am 2009-06-19 00:42:11 UTC (rev 15341)
+++ cs/spatialdata-0.1/trunk/templates/spatialdb/Makefile.am 2009-06-19 04:29:08 UTC (rev 15342)
@@ -10,70 +10,91 @@
# ----------------------------------------------------------------------
#
+# This files uses autoconf patterns in variables names so that the GNU
+# build system can automatically construct the dependencies and build
+# the library using the appropriate flags.
+
+# m4 macros for GNU build system
ACLOCAL_AMFLAGS = -I ./m4
SUBDIRS = tests
+# Define path where python and module will be installed
subpkgpythondir = $(pythondir)/spatialdata/spatialdb/contrib
subpkgpyexecdir = $(pyexecdir)/spatialdata/spatialdb/contrib
-# LIBRARY --------------------------------------------------------------
+# C++ LIBRARY ----------------------------------------------------------
+# The resulting library will be libspatialcontrib.MACHINE_DEPENDENT_SUFFIX
lib_LTLIBRARIES = libspatialdbcontrib.la
+# Source files for library
libspatialdbcontrib_la_SOURCES = \
UniformVelModel.cc
+# C++ Header files
noinst_HEADERS = \
UniformVelModel.hh
+# Set link flags to automake link flags
libspatialdbcontrib_la_LDFLAGS = $(AM_LDFLAGS)
+# Link to spatialdata and proj libraries
libspatialdbcontrib_la_LIBADD = \
-lspatialdata \
-lproj
if NO_UNDEFINED
+# Add linking to Python libraries if linker doesn't allow undefined symbols
libspatialdbcontrib_la_LIBADD += \
$(PYTHON_BLDLIBRARY) $(PYTHON_LIBS) $(PYTHON_SYSLIBS)
endif
+# Preprocessor flags
AM_CPPFLAGS = $(PYTHON_EGG_CPPFLAGS) -I$(PYTHON_INCDIR)
INCLUDES =
-# MODULE ---------------------------------------------------------------
-
+# SWIG PYTHON MODULE ---------------------------------------------------
+# The name of the module will be _spatialdbcontribmodule.MACHINE_DEPENDENT_SUFFIX
subpkgpyexec_LTLIBRARIES = _spatialdbcontribmodule.la
+# SWIG generated Python file and user-generated module initialization file.
subpkgpyexec_PYTHON = \
spatialdbcontrib.py \
__init__.py
+# SWIG source files
swig_sources = \
spatialdbcontrib.i \
UniformVelModel.i
+# SWIG generated files
swig_generated = \
spatialdbcontrib_wrap.cxx \
spatialdbcontrib.py
+# Special link lags for creating Python module
_spatialdbcontribmodule_la_LDFLAGS = -module -avoid-version \
$(AM_LDFLAGS) $(PYTHON_LA_LDFLAGS)
+# Module sources
dist__spatialdbcontribmodule_la_SOURCES = $(swig_sources) $(swig_generated)
+# Link module w/spatialdbcontrib library
_spatialdbcontribmodule_la_LIBADD = libspatialdbcontrib.la
if NO_UNDEFINED
_spatialdbcontribmodule_la_LIBADD += \
$(PYTHON_BLDLIBRARY) $(PYTHON_LIBS) $(PYTHON_SYSLIBS)
endif
+# Module uses numpy and Python header files
INCLUDES += -I$(NUMPY_INCDIR) -I$(PYTHON_INCDIR)
+# Command to invoke SWIG
$(srcdir)/spatialdbcontrib_wrap.cxx $(srcdir)/spatialdbcontrib.py: $(swig_sources)
$(SWIG) -Wall -c++ -python $(SWIG_FLAGS) $<
-
+# Remove SWIG generated files for make clean-maintainer.
MAINTAINERCLEANFILES = $(swig_generated)
Modified: cs/spatialdata-0.1/trunk/templates/spatialdb/README
===================================================================
--- cs/spatialdata-0.1/trunk/templates/spatialdb/README 2009-06-19 00:42:11 UTC (rev 15341)
+++ cs/spatialdata-0.1/trunk/templates/spatialdb/README 2009-06-19 04:29:08 UTC (rev 15342)
@@ -0,0 +1,101 @@
+Overview
+
+ This directory contains source files for building a user defined
+ spatial database component consisting of C++ code, a Python module,
+ and Python code. The example implementation provides a uniform
+ seismic velocity model than can be used to provide elastic physical
+ properties in PyLith simulations using a georeferenced coordinate
+ system.
+
+ The suggested path to customizing this component is to build and
+ install the provided UniformVelModel component and then rename/copy
+ the files and gradually adopt it to your specific needs.
+
+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
+ README - this file
+ UniformVelModel.cc - C++ source file implementing UniformVelModel object functions
+ UniformVelModel.hh - C++ header file with class definition for UniformVelModel
+ UniformVelModel.i - SWIG interface file for the C++ UniformVelModel object
+ __init__.py - Python source file for module initialization
+ configure.ac - autoconf parameters for construction a configure script
+ m4 - directory containing autoconf macros
+ spatialdbcontrib.i - SWIG interface file defining the spatialdbcontrib Python module
+ tests - directory containing tests of the UniformVelModel object
+
+How to build/install the UniformVelModel component
+
+ 1. Run "autoreconf -if" in this directory (templates/spatialdb).
+
+ 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/spatialdb-contrib run
+ $HOME/src/spatialdata/templates/spatialdb/configure --prefix=$HOME/cig.
+
+ Configure will check for a number of files including the location of
+ spatialdata 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/spatialdata/templates/spatialdb/configure --config-cache \
+ --prefix=${HOME}/tools/cig/gcc-4.0 \
+ 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" \
+ SPATIALDATA_SWIG_DIR="${CIG_DIR}/share/spatialdata/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 UniformVelModel 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
+ UniformVelModel component. The UniformVelModel Python object simply
+ acquires user input using Pyre properties (and could use facilities
+ as well) and in _configure() transfers that information to the
+ UniformVelModel C++ object via the SWIG module in. The
+ UniformVelModel C++ object does the grunt work of managing which
+ values will be returned in a query and performing the query
+ itself. In this case, the query is trivial (it simply returns the
+ same value independent of the location where the physical properties
+ are desired). In a real UniformVelModel component, the query
+ function can be quite complex and will usually involve interpolation
+ of values to the location specified in the arguments of the query()
+ function (the query location).
+
+ We recommend that you start by changing the default values assigned
+ to the UniformVelModel, followed by changing the user controlled
+ parameters (Pyre properties). When you change the Pyre properties
+ (vp, vs, density) you should change the corresponding names of the
+ C++ accessor functions (vp, vs, density).
Modified: cs/spatialdata-0.1/trunk/templates/spatialdb/UniformVelModel.cc
===================================================================
--- cs/spatialdata-0.1/trunk/templates/spatialdb/UniformVelModel.cc 2009-06-19 00:42:11 UTC (rev 15341)
+++ cs/spatialdata-0.1/trunk/templates/spatialdb/UniformVelModel.cc 2009-06-19 04:29:08 UTC (rev 15342)
@@ -10,6 +10,9 @@
// ======================================================================
//
+// See UniformVelModel.hh for a description of each C++ function and
+// its arguments.
+
#include <portinfo> // machine specific info generated by configure
#include "UniformVelModel.hh" // Implementation of class methods
Modified: cs/spatialdata-0.1/trunk/templates/spatialdb/UniformVelModel.hh
===================================================================
--- cs/spatialdata-0.1/trunk/templates/spatialdb/UniformVelModel.hh 2009-06-19 00:42:11 UTC (rev 15341)
+++ cs/spatialdata-0.1/trunk/templates/spatialdb/UniformVelModel.hh 2009-06-19 04:29:08 UTC (rev 15342)
@@ -20,6 +20,8 @@
#include "spatialdata/spatialdb/SpatialDB.hh" // ISA SpatialDB
+// Forward declaration of the C++ UniformVelModel object in the
+// contrib/spatialdb namespace.
namespace contrib {
namespace spatialdb {
class UniformVelModel;
@@ -27,9 +29,11 @@
} // contrib
class contrib::spatialdb::UniformVelModel :
- public spatialdata::spatialdb::SpatialDB
+ public spatialdata::spatialdb::SpatialDB // inheritance from SpatialDB
{ // UniformVelModel
- friend class TestUniformVelModel; // unit testing
+ // Allow the unit testing TestUniformVelModel object access to
+ // private class methods and members.
+ friend class TestUniformVelModel;
// PUBLIC METHODS ///////////////////////////////////////////////////////
public :
Modified: cs/spatialdata-0.1/trunk/templates/spatialdb/UniformVelModel.py
===================================================================
--- cs/spatialdata-0.1/trunk/templates/spatialdb/UniformVelModel.py 2009-06-19 00:42:11 UTC (rev 15341)
+++ cs/spatialdata-0.1/trunk/templates/spatialdb/UniformVelModel.py 2009-06-19 04:29:08 UTC (rev 15342)
@@ -22,8 +22,11 @@
class UniformVelModel(SpatialDBObj, ModuleUniformVelModel):
"""
Python object associated with the C++ UniformVelModel object. This
- objects provides a Pyre interface to the C++ object. Python manager
- for spatial database to a new velocity model.
+ objects provides a Pyre interface to the C++ object. It inherits
+ from the generic SpatialDBObj and the UniformVelModel SWIG module
+ object. This insures that this object has all of the SpatialDBObj
+ Pyre properties and facilities and functions and calls to the
+ underlying C++ code are passed onto the SWIG Python module.
Factory: spatial_database
"""
@@ -32,12 +35,8 @@
class Inventory(SpatialDBObj.Inventory):
"""
- Python object for managing UniformVelModel facilities and properties.
- """
+ Python object for managing UniformVelModel Pyre facilities and properties.
- ## @class Inventory
- ## Python object for managing UniformVelModel facilities and properties.
- ##
## \b Properties
## @li \b vs S wave speed.
## @li \b vp P wave speed.
@@ -45,19 +44,45 @@
##
## \b Facilities
## @li none
+ """
import pyre.inventory
+ # Units used in properties
from pyre.units.time import s
from pyre.units.length import km,m
from pyre.units.mass import kg
+ # Pyre properties have the form
+ #
+ # VARIABLE = pyre.inventory.TYPE("CFG_NAME", default=DEFAULT_VALUE)
+ # VARIABLE.meta['tip'] = "HELP STRING"
+ #
+ # where VARIABLE is a variable used to refer to the Pyre property,
+ # TYPE of the type of property (dimensional, str, float, int,
+ # etc), CFG_NAME is the name used in the Pyre .cfg files and the
+ # command line, and DEFAULT_VALUE is the default value.
+ #
+ # When a Pyre property is a dimensional scalar quantity, use the
+ # dimensional type for properties and Pyre will automatically
+ # check to make sure user-specified quantities have compatible
+ # units and convert the value to SI units.
+ #
+ # The help string will be printed when the user uses the command
+ # line arugments --FULL_COMPONENT_NAME.help-properties or
+ # --FULL_COMPONENT.help-components. See the PyLith manual chapter
+ # "Running PyLith" for more information regarding getting help
+ # using command line arguments.
+ #
+ # Create a Pyre property named vs with a default value of 2.6 km/s.
vs = pyre.inventory.dimensional("vs", default=2.6*km/s)
vs.meta['tip'] = "S wave speed."
+ # Create a Pyre property named vp with a default value of 4.5 km/s.
vp = pyre.inventory.dimensional("vp", default=4.5*km/s)
vp.meta['tip'] = "P wave speed."
+ # Create a Pyre property named density with a default value of 2500 kg/m**3.
density = pyre.inventory.dimensional("density", default=2.5e+3*kg/m**3)
density.meta['tip'] = "Density."
@@ -66,7 +91,8 @@
def __init__(self, name="uniformvelmodel"):
"""
- Constructor.
+ Constructor. This function is called automatically when the Python
+ UniformVelModel object is created.
"""
SpatialDBObj.__init__(self, name)
return
@@ -76,7 +102,8 @@
def _configure(self):
"""
- Set members based on inventory.
+ Set members based on inventory. This function is called
+ automatically when the component is setup.
"""
SpatialDBObj._configure(self) # Call parent function.
@@ -89,8 +116,11 @@
def _createModuleObj(self):
"""
- Create handle to C++ object.
+ Create handle to C++ object. This function is called by the
+ generic SpatialDBObj constructor. The name cannot be changed and
+ no arguments can be added.
"""
+ # Create the SWIG module object to provide access to the C++ object.
ModuleUniformVelModel.__init__(self)
return
More information about the CIG-COMMITS
mailing list