root/trunk/MACOSX-INSTALLATION.txt

============================
Simple Mac OS X Installation
============================

.. contents::
   :local:
   :depth: 2

We present two comparatively simple routes to installing |FiPy| on `Mac OS
X`_. The `Fink Installation`_ procedure is appropriate if you are already
familiar with the Fink_ package manager. The `Binary Installation`_
procedure is the most expedient if you have never heard of Fink_ or if
you are not comfortable with it. Please see the more general
|INSTALLATION-txt| for detailed installation instructions. These
instructions are not the only ways to set up |FiPy| on `Mac OS X`_ but
represent the most expedient ways, from our experience, to have a usable
installation up and running.

.. attention::

   You must have an administrator account to install most of the following 
   packages.

.. include:: utils/include.txt

.. |INSTALLATION-txt| replace:: |htmlINSTALL| |latexINSTALL|
.. _Mac OS X: http://www.nist.gov/cgi-bin/exit_nist.cgi?url=http://www.apple.com/macosx/
.. _Fink: http://www.nist.gov/cgi-bin/exit_nist.cgi?url=http://fink.sourceforge.net

Binary Installation
===================

.. attention::

   Choose this method if you have never heard of Fink_ or if you are not
   comfortable with it for any reason. Binary installation is the fastest 
   way to get |FiPy| up and running, but may offer less flexibility in the 
   long run.
   
   .. note:: 
   
      If you wish to view 3D models, the MayaVi_ viewer is required, which
      is best installed via Fink_, so you should follow the `Fink
      Installation`_ instructions.

Pre-built binaries for many of the required packages are available at 
http://pythonmac.org/packages/py24-fat/.

.. _pythonmac: http://www.nist.gov/cgi-bin/exit_nist.cgi?url=http://pythonmac.org/packages/py24-fat/

Python
------

Python is pre-installed on `Mac OS X`_, but installation of other packages
is much easier if you upgrade to the latest version of
``python-2.4.X-XXXX-XX-XX.dmg`` from pythonmac_ (or possibly some variant on 
``Universal-MacPython-2.4.X-XXXX-XX-XX.dmg``). Your existing
installation will not be harmed.

.. note::

   Any command-line instructions that start with ``python`` will either 
   need to be explicitly typed as ``/usr/local/bin/python`` or you will 
   need to adjust your ``$path`` variable so that this version of 
   ``python`` is found before the pre-installed version.

.. note::

   Another option is ActivePython_, which probably is the most heavily 
   supported installation on the Mac, but seems to lack `readline` support, 
   but these instructions

       http://www.friday.com/bbum/2006/03/06/python-mac-os-x-and-readline/

   worked for us.

.. _ActivePython: http://www.nist.gov/cgi-bin/exit_nist.cgi?url=http://www.activestate.com/Products/ActivePython/

NumPy
-----

Download and install the latest version of 
``numpy-X.XX-py2.4-macosx10.4.mpkg.zip`` from pythonmac_.



matplotlib
----------

In order to see simulation results, you will need a viewer. We recommend
you download and install the latest version of
``matplotlib-X.XX.X-py2.4-macosx10.4.mpkg.zip`` from pythonmac_.


matplotlib requires:

wxPython
~~~~~~~~

Download and install the latest version of
``wxPythonX.X-osx-unicode-X.X.X.X-universal10.4-py2.4.dmg`` from
pythonmac_.


PySparse
--------

http://sourceforge.net/project/showfiles.php?group_id=101403

Download and install the latest version of
``pysparse-X.XX.XXX.macosx-10.4-py24.dmg``

|FiPy|
------

http://www.ctcms.nist.gov/fipy/

Download and unpack the source archive (``FiPy-x.y.tar.gz``).     

From within the |FiPy| directory, execute the command-line instruction::

    $ python setup.py build
    $ sudo python setup.py install

.. note::

   You may now choose to install `Optional Packages`_ or you may choose 
   proceed directly to `Using FiPy on Mac OS X`_.



Fink Installation
=================
   
.. attention::

   Choose this method if you are already familiar with Fink_ or with Linux_
   package managers in general (such as Debian_ packages or RPMs). Fink_ 
   installation takes considerably longer than `Binary Installation`_, but 
   offers a wealth of other programs that can make it worthwhile.

The Fink_ package manager automatically handles the many intricate
dependencies involved in building open source software. Fink_ is based on
the Debian_ tools and the package manager model will be familiar to Linux_
users.

.. _Debian: http://www.nist.gov/cgi-bin/exit_nist.cgi?url=http://www.debian.org
.. _Linux: http://www.nist.gov/cgi-bin/exit_nist.cgi?url=http://www.linux.org


Xcode Development Tools
-----------------------

http://developer.apple.com/tools/xcode

Some required packages are not available from Fink_ as binaries, so you 
will need to have the developer tools for `Mac OS X`_. They may already 
be installed in the ``/Developer/`` directory, but a different version may 
be required by Fink_; see the recommendations at http://fink.sourceforge.net/download

.. note::

   Free registration with the `Apple Developer Connection`_ is required.
   
.. _Apple Developer Connection: 

X11
---

Open the X11 application.

Set your ``$DISPLAY`` environment variable to ``:0.0``.

.. note:: 

   If the X11 application is not already present in the
   ``/Applications/Utilities/`` directory, it should be available as an
   optional package on the OS installation media that came with your
   computer.


Fink
----

http://fink.sourceforge.net/download

Ensure that Fink_ is installed and up to date for your OS.

.. note::

   The following steps have been tested with Fink_ 0.8.1 on `Mac OS X`_
   10.4 "Tiger". Variations may be necessary for other OS versions.

unstable tree
~~~~~~~~~~~~~

Follow the directions at http://www.finkproject.org/faq/usage-fink.php#unstable

.. note::

   We recommend that you accept all defaults presented by 
   ``fink selfupdate``.

.. note:: 

   "unstable" is not as scary as it sounds. The Fink_ administrators tend 
   to be very conservative about what packages are designated "stable".

Remaining Fink packages
~~~~~~~~~~~~~~~~~~~~~~~

Execute the following commands from Terminal application (you can use 
``xterm`` or any other terminal application of your choosing)::

    $ fink --use-binary-dist install python

Take note of the version of Python that gets installed (`python
--version`). Many other packages, indicated by a "`-pyXX`" suffix, require
you substitute the Python version. E.g., Python 2.4 takes "`-py24`", Python
2.5 takes "`-py25`", and so on.

    $ fink --use-binary-dist install matplotlib-pyXX

.. attention::

   The matplotlib_ installation will automatically download and build a 
   number of other packages. This process can take quite awhile. We 
   recommend that you accept all defaults offered at the beginning of this 
   process.
   
.. note::

   If the installation of matplotlib-pyXX fails for some reason, we 
   recommend you execute the ``install`` command again.
      
A few changes are needed to allow matplotlib_ to run::

    $ mkdir ~/.matplotlib
    $ curl http://matplotlib.sourceforge.net/matplotlibrc \
      > ~/.matplotlib/matplotlibrc

You may now choose to either edit the "backend" configuration in
``~/.matplotlib/matplotlibrc`` to read::

    backend      : TkAgg
    
or you can install wxPython with::

    $ fink --use-binary-dist install wxpython-pyXX
    
(the second choice takes awhile, as it needs to build things).

PySparse installation
---------------------

http://sourceforge.net/project/showfiles.php?group_id=101403

Download and unpack the latest version of
``pysparse-X.XX.XXX.tar.gz``

From within the PySparse directory, execute::

    $ python setup.py build
    $ sudo python setup.py install

|FiPy| installation
-------------------

Install |FiPy|_ packages as explained above.

.. note::

   You may now choose to install `Optional Packages`_ or you may choose 
   proceed directly to `Using FiPy on Mac OS X`_.

..

Optional Packages
=================

ipython
-------

http://ipython.scipy.org/moin/Download

This interactive Python shell is nicer to use than the default, and 
integrates nicely with matplotlib_. Download the source and follow the 
building and installation instructions for `Mac OS X`_.

Gmsh
----

http://www.geuz.org/gmsh

If you wish to run examples that have unstructured meshes, it is
necessary to install Gmsh. Download and unpack the latest version of
Gmsh for `Mac OS X`. Create a link on your ``$path`` or a shell alias that 
points to ``<Gmsh path>/Gmsh.app/Contents/MacOS/Gmsh``.

.. note::

   This is a required package for superfill examples.

MayaVi
------

`MayaVi 1`_ is a requirement if you wish to view 3D problems or improve the
viewing capabilities of the superfill examples. This is one package that is
probably much easier to install via Fink_ than by hand. You might attempt
to follow the instructions at
http://mayavi.sourceforge.net/mwiki/BuildingVTKOnOSX but they are quite out
of date and did not work for us.

If you have already followed the `Fink Installation`_ instructions, then 
you can go to the command line and type::

    $ sudo apt-get install mayavi-pyXX
    
.. note::

   `MayaVi 1`_ is outdated and we hope to have compatilibiltiy with
   `MayaVi 2`_ as soon as possible.

.. _MayaVi 1: http://www.nist.gov/cgi-bin/exit_nist.cgi?url=http://mayavi.sourceforge.net
.. _MayaVi 2: http://www.nist.gov/cgi-bin/exit_nist.cgi?url=http://code.enthought.com/projects/mayavi

SciPy
-----

http://www.scipy.org/

This is a very powerful set of tools that augments the capabilities of 
|FiPy|. Although not required for using |FiPy|, some tests will fail if it 
is not present:

    * If you followed the `Binary Installation`_ procedure, there are a few 
      different choices for obtaining prebuilt binaries of SciPy, each with 
      their own issues: 

          - We presently recommend obtaining SciPy from the ScipySuperpack_

            .. warning:: 

               We do *not* recommend installing the other components from the
               ScipySuperpack_. In particular, matplotlib_ was not usable
               when we tried it.

          - pythonmac_ includes a build of SciPy, but the latest version we
            tried from pythonmac_, ``scipy-0.5.1-py2.4-macosx10.4.mpkg.zip
            (MD5: 15daecd1b5709f04a41154102269359f)``, was apparently not
            linked correctly and does not work properly, c.f.

                http://projects.scipy.org/pipermail/scipy-user/2007-January/010820.html

          - We *may* provide builds of SciPy from `our own site`_ if we 
            conclude that we can better serve |FiPy| users that way.

    * If you followed the `Fink Installation`_ procedure, then you should be
      able to type::

          $ sudo apt-get install scipy-pyXX


.. _ScipySuperpack: http://www.nist.gov/cgi-bin/exit_nist.cgi?url=http://trichech.us/?page_id=4

.. _our own site: http://www.ctcms.nist.gov/fipy/download/

.. note::

   You are now ready to proceed to `Using FiPy on Mac OS X`_.
      
   
   
Using |FiPy| on Mac OS X
========================

We do a substantial amount of our |FiPy| development on `Mac OS X`_, so you
can assume that it is well-tested on this platform. We exlusively use the
unix command line to interact with |FiPy|. The commands in |examples/| are
written with the assumption that they will be executed from the command
line. For instance, from within the main |FiPy| directory, you can type::

    $ python examples/diffusion/mesh1D.py

A matplotlib_ viewer should appear and you should be prompted 
through a series of examples. 

.. note::

   We strongly recommend you proceed through |examples/|, but at 
   the very least work through |examples/diffusion/mesh1D-py| to understand 
   the notation and basic concepts of |FiPy|.


IDLE Environment
----------------

For those that are averse to the command line, the IDLE_ environment is
installed by the pythonmac_ Python_ installer and will appear in the
MacPython 2.4 folder of the Applications folder.

.. note:: We are not aware of a Fink_ package for IDLE_.

.. attention:: 

   We have no experience with using the IDLE_ environment on `Mac OS X`_, 
   but the following steps do work.

You can use the IDLE_ file browser to open the examples and run the
module.

    - Open the IDLE_ application, located in ``/Applications/MacPython 2.4/``
    - Select the Python Shell window. 
      You can close the Console window if it appears.
    - Choose File > Open
    - Select ``/Path/To/Base/FiPy/Directory/examples/diffusion/mesh1D.py`` 
      and click the Open button

The script will open in an editor window.

    - Choose Run > Run Module
    
A matplotlib_ viewer should appear and the Python Shell should prompt you 
through a series of examples.

Another way to use |FiPy| examples is to import the example file and then
run any functionality it may have. For example, execute the following
commands in the Python Shell:

    >>> import sys
    >>> sys.path.append('\Path\To\Base\FiPy\Directory')
    >>> from examples.levelSet.electroChem.inputGold import runGold
    >>> runGold(numberOfSteps = 100)

If you have installed the optional packages, a viewer should
appear with a trench filling simulation.

.. _IDLE: http://www.nist.gov/cgi-bin/exit_nist.cgi?url=http://www.python.org/idle/
.. |FiPy| replace:: |htmlFiPy| |latexFiPy| 
.. |examples/| replace:: |htmlExamples/| |latexExamples/|

.. |latexMesh1D-py| raw:: latex

   Section~\ref{sec:Examples:diffusion:mesh1D} ``\titleref{sec:Examples:diffusion:mesh1D}''

.. |htmlMesh1D-py| raw:: html

   Example 7.1: "Module <code>examples.diffusion.mesh1D</code>" of the <a href="download/fipy.pdf">Manual</a>

.. |examples/diffusion/mesh1D-py| replace:: |htmlMesh1D-py| |latexMesh1D-py|