.. _MACOSX-INSTALLATION:

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

We present four comparatively simple routes to installing :term:`FiPy` on `Mac OS
X`_. The `Fink Installation`_ procedure is appropriate if you are already
familiar with the Fink_ package manager. 
`Enthought Python Distribution`_ will get :term:`FiPy` running in a minumum number of
steps. The `Binary Installation`_ procedure is the next most expedient if
you have never heard of Fink_ or if you are not comfortable with it. Please
see the more general :ref:`INSTALLATION` for detailed installation
instructions. These instructions are not the only ways to set up :term:`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.

.. _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

Enthought Python Distribution
=============================

http://www.enthought.com/epd

This installer provides a very large number of useful scientific packages
for Python, including Python_, NumPy_, SciPy_, Matplotlib_, and IPython_.

.. attention::

   PySparse_ and :term:`FiPy` are not presently included in EPD, so you will need
   to separately install them manually.

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 :term:`FiPy` up and running, but may offer less flexibility in the 
   long run.
   
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
:file:`python-2.{4.X-XXXX-XX-XX}.dmg`` from pythonmac_ (or possibly some variant on 
:file:`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 
:file:`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
:file:`wxPython{X.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
:file:`pysparse-{X.XX.XXX}.macosx-10.4-py24.dmg`

FiPy
----

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

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

From within the :term:`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 :envvar:`DISPLAY` environment variable to ``:0.0``.

.. note:: 

   If the X11 application is not already present in the
   :file:`/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 ":samp:`-py{XX}`" suffix, require
you substitute the Python version. E.g., Python 2.4 takes ":samp:`-py24`", Python
2.5 takes ":samp:`-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 :samp:`matplotlib-py{XX}` 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
:file:`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/

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
------

http://code.enthought.com/projects/mayavi/

`Mayavi 2`_ is a requirement if you wish to view 3D problems or improve the
viewing capabilities of the superfill examples. The standard instructions
for either installing with `Enthought Python Distribution`_ or installing
manually work fine.

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

    $ sudo apt-get install mayavi2-pyXX
    
.. _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 
:term:`FiPy`. Although not required for using :term:`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 :term:`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 :term:`FiPy` development on `Mac OS X`_, so you
can assume that it is well-tested on this platform. See :ref:`sec:UsingFiPy` 
for more information.

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.

.. _IDLE: http://www.nist.gov/cgi-bin/exit_nist.cgi?url=http://www.python.org/idle/




