Installation

The FiPy finite volume PDE solver relies on several third-party packages. It is best to obtain and install those first before attempting to install FiPy. This document explains how to install FiPy, not how to use it. See Using FiPy for details on how to use FiPy.

Note

It may be useful to set up a Development Environment before beginning the installation process.

Note

By selecting the links on this page, you will be leaving NIST webspace. We have provided these links to other web sites because they may have information that would be of interest to you. No inferences should be drawn on account of other sites being referenced, or not, from this page. There may be other web sites that are more appropriate for your purpose. NIST does not necessarily endorse the views expressed, or concur with the facts presented on these sites. Further, NIST does not endorse any commercial products that may be mentioned on these sites. Please address comments about this page to fipy@nist.gov.

Installing Python Packages

In general, it is best to use the following order of precedence when installing packages:

• Use the operating system package manager, if possible.

• Use the pip installs python (pip) tool to obtain software from the Python Package Index (PyPI) repository:

  $ pip install package

  Warning

  pip takes care of dependencies that are themselves Python packages. It does not deal with non-Python dependencies.

• Download the packages manually, unpack and run:

  $ python setup.py install

  Further information about each setup.py script is available by typing:

  $ python setup.py --help

Many of the packages listed below have prebuilt installers for different platforms (particularly for Windows). These installers can save considerable time and effort compared to configuring and building from source, although they frequently comprise somewhat older versions of the respective code. Whether building from source or using a prebuilt installer, please read and follow explicitly any instructions given in the respective packages’ README and INSTALLATION files.

Obtaining FiPy

FiPy is freely available for download via Git or as a compressed archive from <http://www.ctcms.nist.gov/fipy/download>. Please see Git usage for instructions on obtaining FiPy with Git.

Warning

Keep in mind that if you choose to download the compressed archive you will then need to preserve your changes when upgrades to FiPy become available (upgrades via Git will handle this issue automatically).

Installing FiPy

Details of the Required Packages and links are given below and in platform-specific instructions, but for the courageous and the impatient, FiPy can be up and running quickly by simply installing the following prerequisite packages on your system:

• Python
• NumPy
• At least one of the Solvers
• At least one of the Viewers (FiPy‘s tests will run without a viewer, but you’ll want one for any practical work)

Other Optional Packages add greatly to FiPy‘s capabilities, but are not necessary for an initial installation or to simply run the test suite.

It is not necessary to formally install FiPy, but if you wish to do so and you are confident that all of the requisite packages have been installed properly, you can install it by typing:

$ pip install fipy

or by unpacking the archive and typing:

$ python setup.py install

at the command line in the base FiPy directory. You can also install FiPy in “development mode” by typing:

$ python setup.py develop

which allows the source code to be altered in place and executed without issuing further installation commands.

Alternatively, you may choose not to formally install FiPy and to simply work within the base directory instead. In this case or if you are making a non-standard install (without admin privileges), read about setting up your Development Environment before beginning the installation process.

Required Packages

Python

http://www.python.org/

FiPy is written in the Python language and requires a Python installation to run. Python comes pre-installed on many operating systems, which you can check by opening a terminal and typing python, e.g.:

$ python
Python 2.3 (#1, Sep 13 2003, 00:49:11)
...
Type "help", "copyright", "credits" or "license" for more information.
>>>

If necessary, you can download and install it for your platform <http://www.python.org/download>.

Note

FiPy requires at least version 2.4.x of Python. See the specialized instructions if you wish to RunUnderPython3.

Python along with many of FiPy‘s required and optional packages is available with one of the following distributions.

Enthought Python Distribution

http://www.enthought.com/epd

This installer provides a very large number of useful scientific packages for Python, including NumPy, SciPy, Matplotlib, Mayavi, and IPython, as well as a Python interpreter. Installers are available for Windows, Mac OS X and RedHat Linux, Solaris, Ubuntu Linux, and OpenSuSE Linux.

Attention

PySparse and FiPy are not presently included in EPD, so you will need to separately install them manually.

Python(x,y)

http://www.pythonxy.com/

Another comprehensive Python package installer for scientific applications, presently only available for Windows.

Attention

PySparse and FiPy are not presently included in python(x,y), so you will need to separately install them manually.

NumPy

http://numpy.scipy.org

Obtain and install the NumPy package. FiPy requires at least version 1.0 of NumPy.

Optional Packages

Gmsh

http://www.geuz.org/gmsh/

Gmsh is an application that allows the creation of irregular meshes.

SciPy

http://www.scipy.org/

SciPy provides a large collection of functions and tools that can be useful for running and analyzing FiPy simulations. Significantly improved performance has been achieved with the judicious use of C language inlining (see the Command-line Flags and Environment Variables section for more details), via the scipy.weave module.

Level Set Packages

To use the level set components of FiPy one of the following is required.

Scikit-fmm

http://packages.python.org/scikit-fmm/

Scikit-fmm is a python extension module which implements the fast marching method.

LSMLIB

http://ktchu.serendipityresearch.org/software/lsmlib/index.html

The Level Set Method Library (LSMLIB) provides support for the serial and parallel simulation of implicit surface and curve dynamics in two- and three-dimensions.

Install LSMLIB as per the instructions on the website. Additionally PyLSMLIB is required. To install, follow the instructions on the website, https://github.com/ktchu/LSMLIB/tree/master/pylsmlib#pylsmlib.

Platform-Specific Instructions

FiPy is tested regularly on Mac OS X, Debian Linux, Ubuntu Linux, and Windows XP. We welcome reports of compatibility with other systems, particularly if any additional steps are necessary to install (see Miscellaneous Build Recipes for user contributed installation tips).

The only elements of FiPy that are likely to be platform-dependent are the Viewers but at least one viewer should work on each platform. All other aspects should function on any platform that has a recent Python installation.

Mac OS X Installation

There is no official package manager for Mac OS X, but there are several third-party package managers that provide many, but not all of FiPy‘s Required Packages and Optional Packages. Options include

Fink

is based on the Debian package management system. It installs all of its dependencies into /sw.

MacPorts

is a package manager originally part of OpenDarwin. It installs all of its dependencies into /opt.

Homebrew

is a recent, lightweight package manager based on Ruby scripts. It installs all of its dependencies into /usr/local (although it can be directed not to).

In addition, there is an Enthought Python Distribution installer for Mac OS X.

Attention

PySparse and FiPy are not presently included in any of these package managers or installers, so you will need to separately install them manually.

We presently find that the combination of Homebrew and pip is a pretty straightforward way to get most of FiPy‘s prerequesites. See the Miscellaneous Build Recipes for up-to-date directions.

Windows Installation

There is no official package manager for Windows, but the Enthought Python Distribution and Python(x,y) installers provide most of FiPy‘s prerequisites.

Attention

PySparse and FiPy are not presently included in EPD or python(x,y), so you will need to separately install them manually.

Ubuntu/Debian Installation

FiPy now has a .deb for Ubuntu/Debian systems that can be downloaded from <http://www.ctcms.nist.gov/fipy/download>. Simply run:

$ dpkg -i python-fipy_x.y.z-1_all.deb

to install. The .deb includes dependencies for all of the Required Packages and Optional Packages.

Miscellaneous Build Recipes

We often post miscellaneous installation instructions on the FiPy blog and wiki pages. The most useful of these include:

• Installing FiPy on Mac OS X using Homebrew
• Building a 64-bit scientific python environment for FiPy from source
• Installing FiPy with pip

Note

We encourange you to contribute your own build recipes on the wiki if they are significantly different.

Development Environment

It is often preferable to not formally install packages in the system directories. The reasons for this include:

• developing or altering the package source code,
• trying out a new package along with its dependencies without violating a working system,
• dealing with conflicting packages and dependencies,
• or not having admin privileges.

The simplest way to use a Python package without installing it is to work in the base directory of the unpacked package and set the PYTHONPATH environment variable to “.”. In order to work in an directory other than the package’s base directory, the PYTHONPATH environment variable must be set to “~/path/to/package”. This method of working is adequate for one package, but quickly becomes unmanageable with multiple Python packages. In order to manage multiple packages, it is better to choose a standard location other than the default installation path.

If you do not have administrative privileges on your computer, or if for any reason you don’t want to tamper with your existing Python installation, most packages (including FiPy) will allow you to install to an alternative location. Instead of installing these packages with python setup.py install, you would use python setup.py install --home=dir, where dir is the desired installation directory (usually “~” to indicate your home directory). You will then need to append dir/lib/python to your PYTHONPATH environment variable. See the Alternate Installation section of the Python document “Installing Python Modules” [InstallingPythonModules] for more information, such as circumstances in which you should use --prefix instead of --home.

An alternative to setting the PYTHONPATH is to employ one of the utilities that manage packages and their dependencies independently of the system package manager and the system directories. These utilities include Stow, Virtualenv and zc.buildout, amongst others. Here we’ll describe the use of Virtualenv, which we highly recommend.

Virtualenv

http://pypi.python.org/pypi/virtualenv

Virtualenv enables the installation of packages in multiple isolated environments. It organizes the installation of Python packages especially well and also provides a handy location for installing non-Python packages. In addition Virtualenv works seamlessly with the PyPI package manager (pip).

The utility of Virtualenv is significantly augmented with Virtualenvwrapper.

In general, the initial installation of Virtualenv and Virtualenvwrapper requires admin privileges, but thereafter, creating new virtual environments and installing packages into them does not require admin privileges.

Git usage

All stages of FiPy development are archived in a Git repository at MatForge. You can browse through the code at http://matforge.org/fipy/browser/fipy and, using a Git client, you can download various tagged revisions of FiPy depending on your needs.

Attention

Be sure to follow Installation to obtain all the prerequisites for FiPy.

Git client

A git client application is needed in order to fetch files from our repository. This is provided on many operating systems (try executing which git) but needs to be installed on many others. The sources to build Git, as well as links to various pre-built binaries for different platforms, can be obtained from http://git-scm.com/.

Git branches

In general, most users will not want to download the very latest state of FiPy, as these files are subject to active development and may not behave as desired. Most users will not be interested in particular version numbers either, but instead with the degree of code stability. Different branches are used to indicate different stages of FiPy development. For the most part, we follow a successful Git branching model. You will need to decide on your own risk tolerance when deciding which stage of development to track.

A fresh copy of the FiPy source code can be obtained with:

$ git clone git://code.matforge.org/nist/fipy.git

An existing Git checkout of FiPy can be shifted to a different <branch> of development by issuing the command:

$ git checkout <branch>

in the base directory of the working copy. The main branches for FiPy are:

master

designates the (ready to) release state of FiPy. This code is stable and should pass all of the tests (or should be documented that it does not).

develop

designates the latest state of code destined for the next release. This code should be stable and pass all tests, but may be awaiting new features or bug fixes before merging to master and formal release.

Past releases of FiPy are tagged as

version-x_y_z

which designates a released version x.y.z. Any released version of FiPy will be designated with a fixed tag: The current version of FiPy is 3.0.1-dev139-ge5d2233.

Tagged releases can be found with:

$ git tag --list

Any other branches will not generally be of interest to most users.

Note

For some time now, we have done all significant development work on branches, only merged back to develop when the tests pass successfully. Although we cannot guarantee that develop will never be broken, you can always check our build status page

http://build.cmi.kent.edu:8010

to find the most recent revision that it is running acceptably.

For those who are interested in learning more about Git, a wide variety of online sources are available, starting with the official Git website. The Pro Git book [ProGit] is particularly instructive.