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.
Shortcuts
Detailed prerequisites and links are given below and in platform-specific instructions, but for the courageous and the impatient, FiPy can be up and running quickly with one of the following methods.
EasyInstall
http://peak.telecommunity.com/DevCenter/EasyInstall
If Python and setuptools are already available, a minimally functional installation of FiPy can be obtained by issuing the commands:
$ easy_install numpy $ easy_install matplotlib $ easy_install pysparse $ easy_install fipy
Some of the Optional Packages may also be available via easy_install, but not all are.
Enthought Python Edition
This installer provides a very large number of useful scientific packages for Python, including Python, NumPy, SciPy, Matplotlib, and IPython. Installers are available for Windows, Mac OS X and RedHat Linux.
Attention!
PySparse and FiPy are not presently included in EPD, so you will need to separately install them, either manually or via EasyInstall.
Python(x,y)
Another comprehensive Python package installer for scientific applications, presently only available for Windows. See the Windows Installation Guide for more information.
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 is tested regularly on Mac OS X 10.4 "Tiger" and 10.5 "Leopard", Debian Linux 4.0 "etch", Ubuntu Linux 10.10, and Windows XP. We welcome reports of compatibility with other systems, particularly if any additional steps are 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
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. FiPy has not yet
- been tested (and will almost certainly not work) with Python 3.0.
NumPy
http://sourceforge.net/projects/numpy/
Obtain and install the NumPy package. FiPy requires at least version 1.0 of NumPy.
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
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.
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 2.0.2 and HEAD). If you prefer, you can download FiPy version 2.0.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}
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 .
Note
We strongly recommend you proceed through the Examples portion of the Manual , but at
the very least work through Example 7.1: "Module examples.diffusion.mesh1D
" of the Manual to understand
the notation and basic concepts of FiPy .
We exlusively use either the unix command line or IPython to interact with FiPy . The commands in the Examples portion of the Manual 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 viewer should appear and you should be prompted through a series of examples.
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 .
As you gain experience, you will want to see FAQ 6.6: "How do I change FiPy's default behavior?" of the Manual to learn about the flags and environment variables that modify FiPy 's default behavior.
Optional Packages
Note
The following packages are not required to run FiPy , but they can be helpful.
SciPy
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
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.
IPython
This interactive Python shell is nicer to use than the default, and integrates nicely with matplotlib. Depending on platform, you may be able to download a binary or build from source.
Trilinos
Trilinos provides solvers and preconditioners, and can be used instead of PySparse. Trilinos preconditioning allows for iterative solutions to some difficult problems that PySparse cannot solve.
Attention!
Trilinos is a large software suite with its own set of prerequisites, and can be difficult to set up. It is not necessary for most problems, and is NOT recommended in a basic install of FiPy .
Trilinos is built using the standard configure, make and make install method. The best approach that we have found is as follows:
$ cd trilinos-X.Y/ $ mkdir BUILD_DIR $ cd BUILD_DIR $ ../configure CXXFLAGS="-O3" CFLAGS="-O3" FFLAGS="-O5 -funroll-all-loops \ > -malign-double" --enable-epetra --enable-aztecoo --enable-pytrilinos \ > --enable-ml --enable-ifpack --enable-amesos --with-gnumake --enable-galeri $ make $ make install
Depending on your platform, other options may be helpful or necessary; see ../configure --help, the Trilinos user guide available from http://trilinos.sandia.gov/documentation.html, or
http://trilinos.sandia.gov/packages/pytrilinos/faq.html for more in-depth documentation.
Note
Trilinos can be installed in a non-standard location by adding the --prefix=$LOCAL_INSTALLATION_DIR flag to the configure step. If Trilinos is installed in a nonstandard location, the path to the PyTrilinos site-packages directory should be added to the PYTHONPATH environment variable; this should be of the form $INSTALL_DIR/lib/$PYTHON_VERSION/site-packages/. Also, the path to the Trilinos lib directory should be added to the LD_LIBRARY_PATH (on Linux) or DYLD_LIBRARY_PATH (on Mac OS X) environment variable; this should be of the form $INSTALL_DIR/lib.
Note
If swig is in a non-standard place use the --with-swig=$PATH_TO_SWIG_EXECUTABLE flag with the configure step.
Trilinos solvers can be used to replace PySparse solvers. If both PySparse and Trilinos are present, useage can be controlled by setting the FIPY_SOLVERS environment variable to Trilinos or Pysparse, or by passing a --Trilinos or --Pysparse flag to the FiPy script, overriding the environment. In the absence of these indicators, FiPy will default to using PySparse if it is present.
Note
Trilinos solvers frequently give intermediate output that FiPy cannot suppress. The most commonly encountered messages are:
- Gen_Prolongator warning : Max eigen <= 0.0:
- which is not significant to FiPy .
- Aztec status AZ_loss: loss of precision:
- which indicates that there was some difficulty in solving the problem to the requested tolerance due to precision limitations, but usually does not prevent the solver from finding an adequate solution.
- Aztec status AZ_ill_cond: GMRES hessenberg ill-conditioned:
- which indicates that GMRES is having trouble with the problem, and may indicate that trying a different solver or preconditioner may give more accurate results if GMRES fails.
- Aztec status AZ_breakdown: numerical breakdown
- which usually indicates serious problems solving the equation which forced the solver to stop before reaching an adequate solution. Different solvers, different preconditioners, or a less restrictive tolerance may help.