The :term:`FiPy` finite volume PDE solver relies on several third-party packages. It is best to obtain and install those first before attempting to install :term:`FiPy`. This document explains how to install :term:`FiPy`, not how to use it. See :ref:`USAGE` for details on how to use :term:`FiPy`.
Note
It may be useful to set up a :ref:`ENVIRONMENT` before beginning the installation process.
.. only:: html
.. 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 [email protected].
A full :term:`FiPy` installation is available for basic exploration on
Attention!
There are many ways (described further down) to obtain the software packages necessary to run :term:`FiPy`, but the most expedient way is with the conda package manager.
install Miniconda on your computer
run:
$ conda create --name <MYFIPYENV> --channel guyer --channel conda-forge fipy nomkl
Note
This command creates a self-contained conda environment and then downloads and populates the environment with the prerequisites for :term:`FiPy` from the channels guyer and conda-forge at https://anaconda.org.
Attention!
Note, this does not work on Windows. On that platform, you should be able to do:
conda create --name <MYFIPYENV> --channel guyer --channel conda-forge python numpy scipy matplotlib mayavi activate <MYFIPYENV> pip install fipy
There are presently no conda packages of any solver suite but scipy available for Windows.
enable this new environment with:
$ source activate <MYFIPYENV>
Note
$ activate <MYFIPYENV>on Windowsmove on to :ref:`USAGE`.
Note
On Linux and Mac OS X, you should have a pretty complete system to run and visualize :term:`FiPy` simulations. On Windows, there are fewer packages available via conda, particularly amongst the sparse matrix :ref:`SOLVERS`, but the system still should be functional.
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 conda package management system, which handles both :term:`Python` and non-:term:`Python` packages and provides facilities for self-contained environments with different combinations of :term:`Python` packages, libraries, and applications.
Use the pip installs python (:term:`pip`) tool to obtain software from the Python Package Index (:term:`PyPI`) repository:
$ pip install packageWarning
:term:`pip` takes care of dependencies that are themselves :term:`Python` packages. It does not deal with non-:term:`Python` dependencies.
Download the packages manually, unpack and run:
$ python setup.py installFurther information about each
setup.pyscript 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' :file:`README` and :file:`INSTALLATION` files.
:term:`FiPy` is freely available for download via Git or as a compressed archive from <http://www.ctcms.nist.gov/fipy/download>. Please see :ref:`documentation:GIT` for instructions on obtaining :term:`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 :term:`FiPy` become available (upgrades via Git will handle this issue automatically).
Details of the Required Packages and links are given below and in platform-specific instructions, but for the courageous and the impatient, :term:`FiPy` can be up and running quickly by simply installing the following prerequisite packages on your system:
- Python
- NumPy
- At least one of the :ref:`SOLVERS`
- At least one of the :ref:`VIEWERS` (:term:`FiPy`'s tests will run without a viewer, but you'll want one for any practical work)
Other :ref:`OPTIONALPACKAGES` add greatly to :term:`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 :term:`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 :term:`FiPy` directory. You can also install :term:`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 :term:`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 :ref:`ENVIRONMENT` before beginning the installation process.
:term:`FiPy` is written in the :term:`Python` language and requires a
:term:`Python` installation to run. :term:`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
:term:`FiPy` requires at least version 2.4.x of :term:`Python`. See the specialized instructions if you plan on :ref:`RunningUnderPython3`.
:term:`Python` along with many of :term:`FiPy`'s required and optional packages is available with one of the following distributions.
This package manager provides a wide array of both :term:`Python`-based and general scientific packages. In addition to the default packages, many other developers (including us) provide "channels" to distribute their own builds of a variety of software.
In a given conda environment, you can install :term:`FiPy` with:
$ conda install --channel guyer --channel conda-forge fipy
:term:`FiPy` depends on or benefits from the so-called scientific Python stack, which includes :term:`IPython`, :term:`Matplotlib`, :term:`NumPy`, :term:`pandas`, and :term:`SciPy`. These packages provide Python with advanced numerical and graphical capabilities, important for the analysis and visual representation of scientific data. The following :term:`Python` distributions provide the :term:`Python` interpreter, scientific Python stacks, and searchable package management for all three major operating systems: Linux, Mac OS X, and Windows.
Attention!
:term:`Python` distributions include cryptographic software packages, and may be subject to export control laws.
If you have the reference :term:`Python` distribution installed, :term:`pip` provides a straightforward way to install and manage the scientific :term:`Python` stack. :term:`pip` interfaces with :term:`PyPI`, searchable on the Web or through the command line by opening a terminal and typing:
$ pip search <package name>
:term:`PyPI` packages are maintained by the individual authors, so installations using :term:`pip` run a somewhat elevated risk of unmet dependencies as the independent codes evolve. Stable releases of :term:`FiPy` are packaged for distribution through :term:`PyPI`.
In addition to the scientific :term:`Python` stack, the Anaconda package manager also provides virtual environment management. Keeping separate installations is useful e.g. for comparing :term:`Python` 2 and :term:`Python` 3 software stacks, or when the user does not have sufficient provileges to install software system-wide.
Attention!
:term:`PySparse` and :term:`FiPy` are not presently included in Anaconda, so you will need to separately install them manually.
http://www.enthought.com/products/canopy
In addition to the core scientific :term:`Python` stack, Canopy includes packages for a very large number of software projects. Canopy supports the venv virtual environment manager.
Attention!
:term:`PySparse` and :term:`FiPy` are not presently included in Canopy, so you will need to separately install them manually.
A non-commercial scientific :term:`Python` distribution developed specifically for Windows.
Attention!
:term:`PySparse` and :term:`FiPy` are not presently included in Python(x,y), so you will need to separately install them manually.
Obtain and install the :term:`NumPy` package. :term:`FiPy` requires at least version 1.0 of NumPy.
:term:`Gmsh` is an application that allows the creation of irregular meshes.
:term:`SciPy` provides a large collection of functions and tools that can be useful for running and analyzing :term:`FiPy` simulations. Significantly improved performance has been achieved with the judicious use of C language inlining (see the :ref:`FlagsAndEnvironmentVariables` section for more details), via the :mod:`scipy.weave` module.
To use the level set components of :ref:`FiPy` one of the following is required.
http://packages.python.org/scikit-fmm/
Scikit-fmm is a python extension module which implements the fast marching method.
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.
:term:`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 :term:`FiPy` that are likely to be platform-dependent are the :ref:`VIEWERS` but at least one viewer should work on each platform. All other aspects should function on any platform that has a recent :term:`Python` 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 :term:`FiPy`'s :ref:`REQUIREDPACKAGES` and :ref:`OPTIONALPACKAGES`. Options include
- Fink
- is based on the Debian package management system. It installs all of its dependencies into :file:`/sw`.
- MacPorts
- is a package manager originally part of OpenDarwin. It installs all of its dependencies into :file:`/opt`.
- Homebrew
- is a recent, lightweight package manager based on Ruby scripts. It installs all of its dependencies into :file:`/usr/local` (although it can be directed not to).
In addition, there is an :ref:`ECP` installer for Mac OS X.
Attention!
:term:`PySparse` and :term:`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 :term:`pip` is a pretty straightforward way to get most of :term:`FiPy`'s prerequesites. See the Miscellaneous Build Recipes for up-to-date directions.
There is no official package manager for Windows, but the :ref:`ECP` and :ref:`PYTHONXY` installers provide most of :term:`FiPy`'s prerequisites.
Attention!
:term:`PySparse` and :term:`FiPy` are not presently included in Canopy or Python(x,y), so you will need to separately install them manually.
:term:`FiPy` now has a .deb for Ubuntu/Debian systems that can be downloaded from <http://www.ctcms.nist.gov/fipy/download>. Simply run:
$ VERSION=x.y-z # choose the version you want
$ apt-get install gmsh libsuperlu3 python-central python-sparse
$ curl -O http://www.ctcms.nist.gov/fipy/download/python-fipy_${VERSION}_all.deb
$ dpkg -i python-fipy_${VERSION}_all.deb
to install. The .deb includes dependencies for all of the :ref:`REQUIREDPACKAGES` and :ref:`OPTIONALPACKAGES`.
We often post miscellaneous installation instructions on the :term:`FiPy` blog and wiki pages. The most useful of these include:
Note
We encourange you to contribute your own build recipes on the wiki if they are significantly different.
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 :term:`Python` package without installing it
is to work in the base directory of the unpacked package and set
the :envvar:`PYTHONPATH` environment variable to ".". In order to work in an
directory other than the package's base directory, the :envvar:`PYTHONPATH`
environment variable must be set to ":file:`~/path/to/package`". This
method of working is adequate for one package, but quickly becomes
unmanageable with multiple :term:`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
:term:`Python` installation, most packages (including :term:`FiPy`)
will allow you to install to an alternative location. Instead of
installing these packages with python setup.py install, you would
use :samp:`python setup.py install --home={dir}`, where :samp:`{dir}`
is the desired installation directory (usually "~" to indicate
your home directory). You will then need to append
:file:`{dir}/lib/python` to your :envvar:`PYTHONPATH` environment
variable. See the Alternate Installation section of the
:term:`Python` document "Installing Python Modules"
:cite:`InstallingPythonModules` for more information, such as circumstances
in which you should use :option:`--prefix` instead of
:option:`--home`.
An alternative to setting the :envvar:`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.