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