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.
It may be useful to set up a Development Environment before beginning the installation process.
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@example.com.
Pre-Installed on Binder¶
A full FiPy installation is available for basic exploration on Binder. The default notebook gives a rudimentary introduction to FiPy syntax and, like any Jupyter Notebook interface, tab completion will help you explore the package interactively.
There are many ways to obtain the software packages necessary to run FiPy, but the most expedient way is with the conda package manager. In addition to the scientific Python stack, conda also provides virtual environment management. Keeping separate installations is useful e.g. for comparing Python 2 and Python 3 software stacks, or when the user does not have sufficient privileges to install software system-wide.
In addition to the default packages, many other developers provide “channels” to distribute their own builds of a variety of software. These days, the most useful channel is conda-forge, which provides everything necessary to install FiPy.
install Miniconda on your computer
$ conda create --name <MYFIPYENV> --channel conda-forge python=<PYTHONVERSION> fipy
Windows x86_64 is fully supported, but this does not work on Windows x86_32, as conda-forge no longer supports that platform. For Python 2.7.x, you should be able to do:
conda create --name <MYFIPYENV> --channel conda-forge python=2.7 numpy scipy matplotlib pysparse mayavi weave
and for Python 3.x, you should be able to do:
conda create --name <MYFIPYENV> --channel conda-forge python=3.6 numpy scipy matplotlib pysparse
followed, for either, by:
activate <MYFIPYENV> pip install fipy
enable this new environment with:
$ source activate <MYFIPYENV>
$ activate <MYFIPYENV>on Windows
move on to Using FiPy.
On Linux and Mac OS X, you should have a pretty complete system to run and visualize FiPy simulations. On Windows, there are fewer packages available via conda, particularly amongst the sparse matrix Solvers, but the system still should be functional. Significantly, you will need to download and install Gmsh manually when using Python 2.7.
Details of the Required Packages and links are given below, but for the courageous and the impatient, FiPy can be up and running quickly by simply installing the following prerequisite packages on your system:
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
$ 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.
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
$ python Python 2.7.15 | ... ... Type "help", "copyright", "credits" or "license" for more information. >>>
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
Level Set Packages¶
Scikit-fmm is a python extension module which implements the fast marching method.
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.
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.
To avoid tampering with the system Python installation, you can employ one of the utilities that manage packages and their dependencies independently of the system package manager and the system directories. These utilities include conda, Nix, Stow, Virtualenv and Buildout, amongst others. Conda and Nix are only ones of these we have the resources to support.
Our preferred development environment is set up with:
$ conda create --name <MYFIPYENV> --channel conda-forge python=<PYTHONVERSION> fipy $ source activate <MYFIPYENV> $ pip install scikit-fmm $ conda remove --channel conda-forge --force fipy $ git clone https://github.com/usnistgov/fipy.git $ cd fipy $ python setup.py develop
All stages of FiPy development are archived in a Git repository at GitHub. You can browse through the code at https://github.com/usnistgov/fipy and, using a Git client, you can download various tagged revisions of FiPy depending on your needs.
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/.
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 https://github.com/usnistgov/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:
- 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).
Past releases of FiPy are tagged as
- Any released version of FiPy will be designated with a fixed tag: The
current version of FiPy is 3.4. (Legacy
version-x_y_ztags are retained for historical purposes, but won’t be added to.)
Tagged releases can be found with:
$ git tag --list
Any other branches will not generally be of interest to most users.
For some time now, we have done all significant development work on
branches, only merged back to
master when the tests pass
successfully. Although we cannot guarantee that
master will never
be broken, you can always check our Continuous Integration status
to find the most recent revision that it is running acceptably.
Historically, we merged to
develop before merging to
no longer do this, although for time being,
develop is kept
master. In a future release, we will remove the
develop branch altogether.
FiPy now has a Nix expression for installing FiPy using Nix. Nix is a powerful package manager for Linux and other Unix systems that makes package management reliable and reproducible. The recipe works on both Linux and Mac OS X.
Getting Started with Nix¶
There are a number of tutorials on getting started with Nix. The page that I used when getting started is on the Blog of the HPC team of GRICAD,
I also made my own notes,
which are a succinct steps that I use when setting up a new system with Nix.
Once you have a working Nix installation use:
$ nix-shell --pure
in the base FiPy directory to install FiPy with Python
3 by default. Modify the shell.nix file to use another version of
nix-shell drops the user into a shell with a working
version of FiPy. To test your installation use:
$ nix-shell --pure --command "python setup.py test"
To install additional packages available from Nixpkgs include them in the nativeBuildInputs list in shell.nix.
Packages unavailable from Nix can be installed using Pip. In
this case, the installation has been set up so that the Nix shell
knows about a
.local directory in the base FiPy directory
used by Pip for installation. So, for example, to install the
toolz package from within the Nix shell use:
$ pip install --user toolz
.local directory will persist after the Nix shell has been