[MOAB-dev] r2929 - MOAB/trunk/tools/iMesh/python/doc

[jvporter at wisc.edu]

Author: jvporter
Date: 2009-06-04 00:46:41 -0500 (Thu, 04 Jun 2009)
New Revision: 2929

Modified:
   MOAB/trunk/tools/iMesh/python/doc/build.rst
   MOAB/trunk/tools/iMesh/python/doc/intro.rst
Log:
Added more documentation for Python bindings


Modified: MOAB/trunk/tools/iMesh/python/doc/build.rst
===================================================================
--- MOAB/trunk/tools/iMesh/python/doc/build.rst	2009-06-03 20:55:17 UTC (rev 2928)
+++ MOAB/trunk/tools/iMesh/python/doc/build.rst	2009-06-04 05:46:41 UTC (rev 2929)
@@ -7,6 +7,21 @@
 directory for PyTAPS. However, certain iMesh interfaces may require some
 additional setup.
 
+Requirements
+============
+
+In order to build PyTAPS, several external libraries are required:
+
+* Python 2.5+
+* `Numpy <http://numpy.scipy.org/>`_ 1.3.0+
+* An iMesh implementation (currently only `MOAB
+  <http://trac.mcs.anl.gov/projects/ITAPS/wiki/MOAB>`_ is supported)
+
+To run the performance tests or tools, `Matplotlib
+<http://matplotlib.sourceforge.net/>`_ is also required. Finally, to build the
+documentation (you're reading it!), `Sphinx <http://sphinx.pocoo.org/>`_ is
+required.
+
 With MOAB
 =========
 
@@ -21,4 +36,4 @@
 directories. One solution to this is to include the appropriate directories in
 the environment variables ``CPATH`` and ``PYTHONPATH``. Another, more flexible
 method is to use the ``setup.cfg`` file. Information on how to use this file can
-be found in the official Python `documentation <http://docs.python.org/install/index.html#distutils-configuration-files>`_.
\ No newline at end of file
+be found in the official Python `documentation <http://docs.python.org/install/index.html#distutils-configuration-files>`_.

Modified: MOAB/trunk/tools/iMesh/python/doc/intro.rst
===================================================================
--- MOAB/trunk/tools/iMesh/python/doc/intro.rst	2009-06-03 20:55:17 UTC (rev 2928)
+++ MOAB/trunk/tools/iMesh/python/doc/intro.rst	2009-06-04 05:46:41 UTC (rev 2929)
@@ -2,6 +2,53 @@
  Introduction
 ==============
 
+From C
+======
+
+Compared to the C interface for ITAPS, PyTAPS has some important differences
+designed to take advantage of Python language features. Users familiar with the
+C interface should review the changes below.
+
+Return Values
+-------------
+
+Instead of relying on out-values to return data from interface functions, PyTAPS
+uses the simpler method of merely returning the data. In cases where multiple
+return values are needed, PyTAPS returns a tuple of the values. As a notable
+exception to this, return values from adjacency queries are wrapped into helper
+classes: :mod:`itaps.helpers`.
+
+Error Handling
+--------------
+
+All instances of the out-value ``int *err`` in functions have been replaced with
+Python ``RuntimeError``\ s that are raised if an error of some kind occurs.
+
+Arrays
+------
+
+In the C interface, arrays are passed as pairs of parameters when used as input
+(``type *data, int size``) and as triples of parameters when used as output
+(``type **data, int *alloc, int *size``). The PyTAPS interface uses `Numpy
+<http://numpy.scipy.org/>`_ for all array data, and so the size is passed
+implicitly along with the array. Since Python programs (generally) do not
+manually manage their own memory, the ``alloc`` parameter is similarly
+eliminated.
+
+Overloads
+---------
+
+To reduce the number of methods that must be memorized when using these
+interfaces, PyTAPS coalesces all entity, entity array, and entity set functions
+into a single function where appropriate. For instance, the iMesh functions
+``iMesh_addEntToSet``, ``iMesh_addEntArrToSet``, and ``iMesh_addEntSet`` are all
+called by :meth:`itaps.iMesh.EntitySet.add`. Which C API function is ultimately
+called is determined by the type of the argument passed to ``add``.
+
+One notable exception to this rule is :meth:`itaps.iMesh.createEnt` and
+:meth:`itaps.iMesh.createEntArr`, which have the same signatures and so cannot
+be overloaded based on the types of the arguments.
+
 An Example
 ==========
 
@@ -11,4 +58,4 @@
 of the volumes of each region and graphs them (or optionally prints the raw data
 to the console).
 
-.. literalinclude :: ../tools/volume.py
\ No newline at end of file
+.. literalinclude :: ../tools/volume.py