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