README

Thanks for downloading MeshPy!

WHAT IS THIS?
-------------

MeshPy enables you to generate quality triangular and tetrahedral meshes for
arbitrary geometric regions, all from within Python. Meshes of this type are
chiefly used in finite-element simulation codes, but also have many other 
applications ranging from computer graphics to robotics.

In order to generate these 2D and 3D meshes, MeshPy provides Python interfaces 
to two well-regarded mesh generators, Triangle [1] by J. Shewchuk and TetGen [2]
by Hang Si.

[1] http://www.cs.cmu.edu/~quake/triangle.html
[2] http://tetgen.berlios.de/

MeshPy is based on TetGen 1.4.2 and Triangle 1.6.

GETTING STARTED
---------------

To get started, you need the Boost.Python [1] wrapper generator library 
installed. See below for installation instructions.

After you have installed MeshPy, take a look at the examples in the test/
subdirectory to see what you can do with MeshPy and how. There is no user
documentation currently, but if you would like to contribute some, 
please feel free. In general, you might want to study how Triangle's and
TetGen's C interfaces work--then MeshPy's interface should not be a 
surprise. MeshPy makes an attempt to make the two meshing interfaces even
more similar than they already are, by renaming fields called "triangle..." 
and "tetrahedron..." into "element...".

I hope you enjoy using MeshPy. If you use it for your work, I'd be delighted
to hear from you.

Andreas Kloeckner <kloeckner@dam.brown.edu>

[1] http://www.boost.org/libs/python/doc/

INSTALLING BOOST.PYTHON
-----------------------

(You may skip all this if your distribution ships Boost.Python, which is the case
for Debian and Ubuntu. For the latter two, you just need to install the package
libboost-python-dev, it will pull in all the other dependencies.)

If you figure you need to build manually, proceed as follows:

* Download a Boost release from http://www.boost.org/.

* Download and install Boost.Jam, a build tool, from

* Build Boost, such as by typing

    bjam -sPYTHON_ROOT=/usr -sPYTHON_VERSION=2.4 \
      -sBUILD="release <runtime-link>dynamic <threading>multi"

  (You may have to adapt PYTHON_ROOT and PYTHON_VERSION depending on your system.)

* Check the directory 

    boost/bin/boost/libs/python/build/libboost_python.so...
      .../gcc/release/shared-linkable-true/threading-multi

  and find libboost_python*.so. (Don't copy the dots from the command
  line--they are only there to make the line fit on this page.) Copy these
  files to somewhere on your dynamic linker path, for example:
  
  - /usr/lib
  - a directory on LD_LIBRARY_PATH
  - or something mentioned in /etc/ld.so.conf.

  You should also create a symbolic link called libboost_python.so
  to the main .so file.

* Run ldconfig.
  
INSTALLING MESHPY
-----------------

Simply run

    su -c "python setup.py install"

To cut down on compile time in this step, you may edit the variable OPT in the file

    /usr/lib/python2.N/config/Makefile

and remove the "-g" flag from it. This will cut compile time and memory requirements
for the compile in about half.