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. This document explains how to install FiPy, not how to use it. See Using FiPy for details on how to use FiPy.

Note

It may be useful to set up a Development Environment before beginning the installation process.

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@list.nist.gov.

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.

Recommended Method

Attention

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 conda

Install conda or install micromamba on your computer.

Create a conda environment

Use one of the following methods to create a self-contained conda environment and then download and populate the environment with the prerequisites for FiPy from the conda-forge channel at https://anaconda.org. See this discussion of the merits of and relationship between the different methods.

• Conda environment files

  This option is the most upgradable in the future and probably the best for development.

  $ conda env create --name <MYFIPYENV> \
      --file environments/<SOLVER>-environment.yml
  

  Note

  You can try to include multiple solver suites using conda env update, but be aware that different suites may have incompatible requirements, or may restrict installation to obsolete versions of Python. Given that FiPy can only use one solver suite during a run, installing more than one solver in an environment isn’t necessary.

  Attention

  Successively updating an environment can be unpredictable, as later packages may conflict with earlier ones. Unfortunately, conda env create does not support multiple environment files.

  Alternatively, combine the different environments/<SOLVER>-environment.yml files you wish to use, along with environment.yml files for any other packages you are interested in (conda-merge may prove useful). Then execute:

  $ conda env create --name <MYFIPYENV> --file <MYMERGEDENVIRONMENT>.yml
  

• conda-lock lockfiles

  This option will pin all the packages, so is the most reproducible, but not particularly upgradable. For most, this is the safest way to generate a FiPy environment that consistently works.

  $ conda-lock install --name <MYFIPYENV> \
      environments/locks/conda-<SOLVER>-lock.yml
  

  or, to be really explicit (and obviating the need for conda-lock):

  $ conda create --name <MYFIPYENV> \
      --file environments/locks/conda-<SOLVER>-<PLATFORM>.lock
  

• Directly from conda-forge, picking and choosing desired packages

  This option is the most flexible, but has the highest risk of missing or incompatible packages.

  e.g.:

  $ conda create --name <MYFIPYENV> --channel conda-forge \
      python=3 numpy scipy matplotlib-base future packaging mpich \
      mpi4py petsc4py mayavi "gmsh <4.0|>=4.5.2"
  

  or:

  $ conda create --name <MYFIPYENV> --channel conda-forge \
      python=2.7 numpy scipy matplotlib-base future packaging \
      pysparse mayavi "traitsui<7.0.0" "gmsh<4.0"
  

  Attention

  Bit rot has started to set in for Python 2.7. One consequence is that VTKViewers can raise errors (probably other uses of Mayavi, too). Hence, the constraint of “traitsui<7.0.0”.

Install FiPy

$ conda install --name <MYFIPYENV> --channel conda-forge fipy

Note

The fipy conda-forge package used to be “batteries included”, but we found this to be too fragile. It now only includes the bare minimum for FiPy to function.

Enable conda environment

Enable your new environment with:

$ conda activate <MYFIPYENV>

or:

$ source activate <MYFIPYENV>

or, on Windows:

$ activate <MYFIPYENV>

You’re now ready to move on to Using FiPy.

Note

conda can be quite slow to resolve all dependencies when performing an installation. You may wish to consider using the alternative mamba installation manager to speed things up.

Note

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.

Attention

When installed via conda or pip, FiPy will not include its examples. These can be obtained by cloning the repository or downloading a compressed archive.

Obtaining FiPy

FiPy is freely available for download via Git or as a compressed archive. Please see Git usage for instructions on obtaining 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 FiPy become available (upgrades via Git will handle this issue automatically).

Installing FiPy

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:

• Python

• NumPy

• At least one of the Solvers

• At least one of the Viewers (FiPy’s tests will run without a viewer, but you’ll want one for any practical work)

Other Optional Packages add greatly to 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 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:

$ python -m pip install fipy

or by unpacking the archive and typing:

$ python setup.py install

at the command line in the base FiPy directory. You can also install 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 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.

Required Packages

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

FiPy requires at least version 2.7.x of Python.

Python along with many of FiPy’s required and optional packages is available with one of the following distributions.

NumPy

http://numpy.scipy.org

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

Optional Packages

Gmsh

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

Gmsh is an application that allows the creation of irregular meshes. When running in parallel, FiPy requires a version of Gmsh >= 2.5 and < 4.0 or >= 4.5.2.

SciPy

http://www.scipy.org/

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

Level Set Packages

To use the level set ([8]) components of FiPy one of the following is required.

Scikit-fmm

http://packages.python.org/scikit-fmm/

Scikit-fmm is a python extension module which implements the fast marching method.

LSMLIB

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.

Development Environment

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.

Create a conda environment for development, followed by:

$ source activate <MYFIPYENV>
$ python -m pip install scikit-fmm
$ git clone https://github.com/usnistgov/fipy.git
$ cd fipy
$ python setup.py develop

Git usage

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.

Attention

Be sure to follow Installation to obtain all the prerequisites for FiPy.

Git client

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

Git branches

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:

master

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

x.y.z

Any released version of FiPy will be designated with a fixed tag: The current version of FiPy is 3.4.5+308.gbf598029e. (Legacy version-x_y_z tags 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.

Note

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 master. We no longer do this, although for time being, develop is kept synchronized with master. In a future release, we will remove the develop branch altogether.

For those who are interested in learning more about Git, a wide variety of online sources are available, starting with the official Git website. The Pro Git book [9] is particularly instructive.

Nix

Nix Installation

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. Go to nix.dev to get started with Nix.

Installing

Once you have a working Nix installation use:

$ nix develop

in the base FiPy directory to install FiPy with Python 3 by default. nix develop drops the user into a shell with a working version of FiPy. To test your installation use:

$ nix develop --command bash -c "python setup.py test"

Note

The SciPy solvers are the only available solvers currently.

Last updated on Feb 06, 2025. Created using Sphinx 7.1.2.