FiPy: A Finite Volume PDE Solver Using Python

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 .

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.

Note

Most of the installation steps will involve a variant on the command:

$ python setup.py ...

In addition to the specific commands given here, further information about each setup.py script is available by typing:

$ python setup.py --help

For each package, please follow any instructions given in its README or INSTALLATION files.

Privileges

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 alternate 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" for more information, such as circumstances in which you should use --prefix instead of --home.

Prerequisites

Operating System

FiPy has been developed and tested on the following operating systems, Mac OS X 10.3 "Panther" & 10.4 "Tiger", Debian Linux 3.1 "Sarge", Windows XP and Windows 2000. We welcome reports of compatibility with other systems, along with any steps necessary to install.

Note

Simple instructions for Mac OS X users are in the Mac OS X Installation Guide . Simple instructions for Windows users are in the Windows Installation Guide .

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.

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.

Required Packages

Warning

FiPy will not run if the following items are not installed.

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 .

Note

FiPy requires at least version 2.3 of Python and has not yet
been tested with version 2.5.
NumPy

http://sourceforge.net/projects/numpy/

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

Attention!

FiPy no longer uses the older Numeric or numarray packages.

PySparse

http://pysparse.sourceforge.net

FiPy requires Roman Geus' PySparse package.

You can download the PySparse archive or check it out via anonymous CVS download:

$ cvs -d:pserver:anonymous@pysparse.cvs.sourceforge.net:/cvsroot/pysparse login

and press enter at the password prompt, then:

$ cvs -z3 -d:pserver:anonymous@pysparse.cvs.sourceforge.net:/cvsroot/pysparse \
>     checkout pysparse

From within the pysparse base directory, follow its included instructions for building PySparse for your platform. PySparse Windows installers are available.

Note

Windows users who choose to build from source should pay particular attention to the instructions in the INSTALL file in the base PySparse directory.

Warning

If pysparse is installed in a local directory a further path may have to be added to the PYTHONPATH environment variable. For example, if

$ python setup.py install --home=/some/directory/some/where

then both /some/directory/some/where and /some/directory/some/where/lib/python are required to be added to the PYTHONPATH. e.g.

$ set PYTHONPATH=/some/directory/some/where:/some/directory/some/where/lib/python

Warning

FiPy requires version 1.0 or higher of PySparse.

Viewers

FiPy will work perfectly well without them, but at least one of the following packages will be required to view the results of FiPy calculations. FiPy will select the first viewer that is available from the list below. If more than one is installed, specify a viewer by setting the FIPY_VIEWER environment variable to either "gist", "gnuplot" or "matplotlib".

Matplotlib

http://matplotlib.sourceforge.net

Matplotlib is a Python package that displays publication quality results. It displays both 1D X-Y type plots and 2D contour plots for structured data. It does not display unstructured 2D data or 3D data. It works on all common platforms and produces publication quality hard copies. Version 0.72.1 or higher is required. Matplotlib installers for specific platforms are available .

Note

Matplotlib is noticeably slower than Pygist or Gnuplot.py, but has superior image rendering and plotting functionality.

Gnuplot-py

http://gnuplot-py.sourceforge.net

Gnuplot.py is a Python package that interfaces to gnuplot, the popular open-source plotting program. It displays both 1D X-Y type plots and 2D contour plots for structured data but not for unstructured data or 3D data. It works on all common platforms and produces hard copies, however, it sometimes breaks on Windows. As a general remark, the viewing quality using either Pygist or Matplotlib is preferable.

Pygist

http://hifweb.lbl.gov/public/software/gist/

The Pygist package can be used to display simulation results. It displays both 1D X-Y type plots and 2D contour plots for both structured and unstructured data. It does not display 3D data. Although stated as working on Windows, it does not seem to do a good job of rendering on this platform. Pygist works fine on other common platforms. Pygist no longer seems to be under development, but is still recommended as a fast light weight alternative to Matplotlib.

Attention!

Pygist requires the old Numeric module to be installed.

Warning

The facility to produce hard copies in Pygist does not work very well and may crash the FiPy run. ".eps" and ".cgm" export seem to work.

Note

If you experience difficulty building the native Pygist viewer on Mac OS X, you may wish to build the package with the --x11 option described in its documentation.

Note

Pygist can have problems finding color pallets, such as "heat.gp" and "work.gs", when installed locally. You may need to set the GISTPATH environment variable to point to the directory containing these files (you may find it as "g/" within the directory you specified for --home).

MayaVi

http://mayavi.sourceforge.net

The MayaVi 1 Data Visualizer is a free, easy to use scientific data visualizer. It displays 1D, 2D and 3D data. It is the only FiPy viewer available for 3D data. Other viewers are probably better for 1D or 2D viewing.

Warning

FiPy can only use MayaVi 1 to display 3D meshes consisting entirely of tetrahedrons or wedge elements. The ordering of vertices for other mesh types may not work.

Note

Is is also necessary to install the PyVTK package to use the FiPy MayaVi viewers.

Note

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

Optional Packages

Note

The following packages are not required to run FiPy , but they can be helpful.

SciPy

http://www.scipy.org/

Significantly improved performance has been achieved with the judicious use of C language inlining, via the weave module of the SciPy package. SciPy download instructions are available. We recommend version 0.5.2 or greater.

Note

A handful of test cases use functions from the SciPy library and will throw errors if it is missing.

gmsh

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

It is possible to create irregular meshes with this package.

Note

The Mac OS X distribution of gmsh provides a nice graphical tool, but is structured a bit differently than on other platforms. To access the underlying shell tool, create a shell alias called gmsh that corresponds to <Gmsh path>/Gmsh.app/Contents/MacOS/Gmsh.

Obtaining FiPy

FiPy is freely available for download via Subversion or as a compressed archive . To obtain FiPy via anonymous Subversion, issue the following command:

$ svn checkout http://matforge.org/svn/fipy/tags/CURRENT

This will download a fairly stable version of FiPy (somewhere between version 1.2.2 and HEAD). If you prefer, you can download FiPy version 1.2.2 (recommended) with:

$ svn checkout http://matforge.org/svn/fipy/tags/STABLE

Further information about Subversion can be found in SVN tags and in the online Subversion Red Bean book .

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 Subversion will handle this issue automatically).

Manual

You can download the latest manual . Alternatively, it may be possible to build a fresh copy by issuing the following command in the base directory:

$ python setup.py build_docs --latex --manual

Note

This mechanism is intended primarily for the developers. A command-line pdfTeX installation and several LaTeX packages are required; particularly memoir.cls. You will also need to add ~/path/to/fipy/utils to your PYTHONPATH environment variable.

Testing FiPy

From the base directory, you can verify that FiPy works properly by executing:

$ python setup.py test

Depending on the packages you chose to install in Optional Packages, be sure to set the appropriate environment variables. You can expect a few errors if you did not install all of the recommended packages.

If you chose to install the weave package, you should rerun the tests with:

$ python setup.py test --inline

A few tests will fail the first time as a result of the messages output in the course of caching the compiled inline code, but a repeat test should have no failures (although see "repairing catalog by removing key" in Chapter 6: "Frequently Asked Questions" of the Manual ).

Note

In order for Python to find the FiPy modules, you will need to ensure that the base directory is added to your PYTHONPATH environment variable, e.g.:

$ setenv PYTHONPATH .:${PYTHONPATH}

or:

$ export PYTHONPATH=.:${PYTHONPATH}

Attention!

Depending on your operating system and version of gmsh you may get failures in examples.levelSet.electroChem.inputGold and examples.levelSet.electroChem.inputLeveler. These are caused by the test being overly strict and are not cause for concern. The models are solved accurately.

Installing FiPy

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 and FiPy passes its tests, you can install it by typing:

$ python setup.py install

at the command line. Alternatively, you may choose not to formally install FiPy and to simply work within the base directory instead.

If you choose to install, Python will find your FiPy modules automatically. If you choose not to install, then you will need to ensure that the FiPy distribution directory is appended to your PYTHONPATH environment variable (either "." if you are working within the FiPy directory, or "~/path/to/fipy" if you are working in your own directory).

Using FiPy

To see examples of problems that FiPy is capable of solving, you can run any of the scripts in the Examples portion of the Manual . You can type, e.g.:

$ python examples/diffusion/steadyState/mesh1D/input.py

at the command line, which should produce a graphical display of the solution.

With judicious use of the weave package, we have been able to obtain significantly improved performance for some problems, while keeping the code as clear as possible. You can invoke this faster code by passing the --inline option at the command line, i.e.:

$ python examples/diffusion/steadyState/mesh1D/input.py --inline

Some modest speed efficiency gains can be made with the use of the --cache flag. This flag instructs FiPy to trade memory for speed. This flag can be invoked with, e.g.:

$ python examples/diffusion/steadyState/mesh1D/input.py --inline --cache

In order to customize the examples, or to develop your own scripts, some knowledge of Python syntax is required. We recommend you familiarize yourself with the excellent Python tutorial or with Dive Into Python .

Cahn Hilliard

Cahn Hilliard

Dendrite

Phase Field

Superfill

Level Set